Contents

restore()

Usage:

restore(FileName [ ,delete:F, list:T, history:F, options:F,\
  foreignok:T])

Keywords: files, general

restore(FileName) restores the workspace or variables previously put in
file FileName by save() or asciisave(), where FileName is a quoted
string or CHARACTER variable.  Unless option 'restoredel' has been set
to False (see subtopic 'options:"restoredel"'), all current variables
are deleted before restoration.  If a history of commands was saved by
using history:T on save() or asciisave(), it replaces the corrent
history of recent commands.

In a version with windows (Macintosh, Windows, Motif), if FileName is ""
you will be prompted for the name of the file.  Restore Workspace on the
File menu in versions with windows is equivalent to 'restore("")'.

Restoring a workspace may destroy any existing locked variables.  See
topic 'variables:"locked_variables"'.

Although variables HOME, DATAFILE, DATAPATHS, and MACROFILES are saved
by save() and asciisave(), they are not restored unless they do not
currently exist.  Any of them that are not restored become components of
structure variable SAVEDNAMES with components HOME, DATAFILE, DATAPATHS
and/or MACROFILES.  If you want to restore DATAPATHS, say, you must
follow restore() by

  Cmd> DATAPATHS <- SAVEDNAMES$DATAPATHS

These variables are automatically used to find files containing macros
and data.  See topics adddatapath(), addmacrofile(), getdata(),
getmacros(), 'macros' and 'DATAPATHS'.

In addition, variable VERSION is not restored.  Whether or not VERSION
exists before restore() is run, restore() sets it to a value appropriate
to the MacAnova version being run.

These steps help ensure that the values of these variables pertains to
the computer and version you are actually using rather than to
the computer and version used to create the workspace file.  See topics
'files', 'launching'.

restore(FileName, delete:F) does not delete existing variables before
restoring.  However, a variable or macro with the same name as a
variable or macro in the file is replaced by the one in the file.  If
option 'restoredel' has been set to False, it may be overridden by
delete:T.

restore(FileName, history:F) suppresses restoring of any history of
recent commands that may have been saved.  Use this if you want to
preserve the history of commands immediately preceding the restore()
command.  This is not available in versions that do not save such a
history.  See sethistory() and gethistory().  Note: a command history is
not saved on a save of selected variables.

restore(FileName, options:F) suppresses restoring the values of options
in effect when the workspace file was created.  Use this if you want to
preserve options currently in effect.  See topics 'options',
setoptions() and getoptions().

Note: option values are not saved on a save of selected variables.

restore(FileName [,delete:F], list:T) lists information on variables as
they are restored.

It is normally an error when the file is a binary workspace file from an
incompatible computer, for example, restoring a Macintosh save file on
Windows.

restore(FileName, foreignok:T ...) makes it permissible to try to
restore a binary workspace file from an incompatible computer.  When
necessary and possible, bytes in the internal representation of numbers
are permuted so as to give them correct values.  This is impossible if
either the number of bytes in either a double precision number or a long
integer differ between the machines.

If you are planning to use a save workspace on a different type of
computer, it is safer to save it using asciisave().

Unless 'graphwind:F' was used when the workspace file was created,
special structure GRAPHWINDOWS is restored.  In windowed versions the
windows corresponding to its components are redrawn (see topic
'GRAPHWINDOWS').  If the number of components saved is greater than the
number allowed in the version you are using, extra components are
ignored.  If the number is fewer, missing components are assumed to be
NULL.

Unless options:F is an argument to restore() or was an argument to
save() or asciisave() when the workspace file was created, values for
options such as 'nsig', 'format', and 'seeds' will be restored to the
previous values at the time the save was done (see 'options').

There are a couple of exceptions.
  'prompt' is not restored when input is from a 'batch' file; see
  batch()
  'matchdelay' is not restored when restoring a workspace saved on an
  incompatible system.

If all:T was used when the file was created, then private information
related to the most recent GLM command will be restored.  Without this
information certain commands such as secoefs() do not work until a GLM
command has been executed.  See topic 'glm'.

Workspace files created by earlier versions of MacAnova for the same
computer can normally be restored correctly except that binary files
created by MacAnova2.4x on a Macintosh cannot be restored.

See also topics asciisave(), save(), 'options', 'files'.