help preserve, help restore
-------------------------------------------------------------------------------
Title
[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.
Also see
Manual: [P] preserve
Help: [P] nopreserve, [D] snapshot; [P] macro (tempfile)
