Stata 15 help for restore

[P] preserve -- Preserve and restore data

Syntax

Preserve data

preserve [, changed]

Restore data

restore [, not preserve]

Description

preserve preserves the data, guaranteeing that data will be restored after program termination.

restore forces a restore of the data now.

Options

changed instructs preserve to preserve only the flag indicating that the data have changed since the last save. Use of this option is strongly discouraged; see the technical note.

not instructs restore to cancel the previous preserve.

preserve instructs restore to restore the data now, but not to cancel the restoration of the data again at program conclusion. If preserve is not specified, the scheduled restoration at program conclusion is canceled.

Remarks

preserve and restore deal with the programming problem where the user's data must be changed to achieve the desired result but, when the program concludes, the programmer wishes to undo the damage done to the data. When preserve is issued, the user's data are preserved. The data in memory remain unchanged. When the program or do-file concludes, the user's data are automatically restored.

After a preserve, the programmer can also instruct Stata to restore the data now with the restore command. This is useful when the programmer needs the original data back and knows that no more damage will be done to the data. restore, preserve can be used when the programmer needs the data back but plans further damage. restore, not can be used when the programmer wishes to cancel the previous preserve and to have the data currently in memory returned to the user.

Technical note

preserve, changed is best avoided, although it is very fast. preserve, changed does not preserve the data; it merely records whether the data have changed since the data were last saved (as mentioned by describe and as checked by exit and use when the user does not also say clear) and restores the flag at the conclusion of the program. The programmer must ensure that the data really have not changed.

As long as your programs use temporary variables, as created by tempvar (see [P] macro), the changed-since-last-saved flag would not be changed anyway -- Stata can track such temporary changes to the data that it will, itself, be able to undo. In fact, we cannot think of one use for preserve, changed, and included it only to preserve the happiness of our more imaginative users.


© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index