Saving and Restoring Sessions

The SAVE and RESTORE procedures are used together to save the state of user-generated variables, system variables, and compiled procedures and functions. The saved session can then be restored at a later time. This ability to “checkpoint” a session and then recover it later can be very convenient. Save files can be used for many purposes:

Save files can be used to recover variables that are used from session to session. A startup file can be used to execute the RESTORE command every time PV‑WAVE is started. See Modifying Your Environment in the PV‑WAVE Programmer’s Guide for more details.

The state of a session can be saved, then quickly restored to the same point, allowing you to stop working, and then later resume at a convenient time.

Saved files relieve you of the need to remember the dimensions of arrays and other details. It is very convenient to store images this way. For example, if the three variables R, G, and B hold the colortable vectors, and the variable Image holds the image data, the statement:

saves everything required to display the image properly, in a file named image.dat. At a later time, the command:

will restore the four variables from the file.

Long iterative jobs can save partial results in Save/Restore format to guard against losing data if some unexpected event such as a machine crash were to occur.

When used with the Wavepoint keyword, SAVE saves PV‑WAVE variables so that they can be read into PV‑WAVE Point & Click and PV‑WAVE Personal Edition.

You can save user-generated variables, system variables, compiled procedures, and compiled functions for future sessions.

The SAVE procedure saves variables, system variables, and compiled user-written procedures and functions in a file, using an efficient binary format, for later recovery by RESTORE. It has the form:

where varn are the named variables to be saved. In addition, you can use keywords with SAVE. For a description of these keywords, see Chapter 2, Function and Procedure Reference in the PV‑WAVE Reference.

note	Under UNIX, creating a new save file causes any existing file with the same name to be lost. Use the Filename keyword with SAVE to avoid destroying desired files. For more information, see the PV‑WAVE Reference.

The RESTORE procedure restores the objects previously saved in a save file by the SAVE procedure.

where filename is the name of the save file. If filename is not supplied, wavesave.dat is used. In addition, you can use keywords with RESTORE. For a description of these keywords, see the PV‑WAVE Reference.

When restoring a structure variable, the structure of the saved variable must either not exist, or must agree with the existing structure definition. If the structure is already defined and does not match, RESTORE issues an error message, skips the variable in question, and continues with the next variable in the file. This also applies to system variables.

note	Rogue Wave Software, Inc., reserves the right to change the structure of system variables, although such changes are not anticipated. Generally, there is little need to save system variables, so this restriction is not a problem.

Read-only system variables are not restored. RESTORE quietly skips over such variables in the file unless the Verbose keyword is present. In this case an informative message is issued as the variable is skipped.