Command RESTORE | Xbase++ | Alaska Software

Reads memory variables from an XPF file.

RESTORE FROM <cVarFile> [ADDITIVE]

<cVarFile> specifies the name of the memory variable file from which data is read. The name must include the drive and path. The file name can be specified either as a literal file name or as a character expression in parentheses. When the file name is specified without a file extension, ".XPF" is used by default.

ADDITIVE

The option ADDITIVE adds the variables read to the variables already available. If variables of the same names as those in the file already exist, the values from the file are assigned to the existing variables.

The command RESTORE FROM is identical in its functionality to the command with the same name in dBASE or Clipper. It does not, however, support the file format of MEM files. In Xbase++, memory variables are not saved in MEM files but in XPF files. This file format allows saving objects, arrays and code blocks on the hard disk as well as the conventional data types character, date, numeric and logical.

The command RESTORE copies into memory PRIVATE or PUBLIC variables which were previously written into an XPF file using the command SAVE. It also assigns the saved values. When the option ADDITIVE is not included, all PRIVATE and PUBLIC variables are first deleted. If ADDITIVE is used, the values from the file are assigned to variables of the same name if they exist at the time RESTORE is executed.

When no variable exists matching the variable name in the file when RESTORE is called, a PRIVATE variable of the same name is created. This variable has the same lifetime as the function or procedure within which the command RESTORE is executed. If a PUBLIC variable of the same name exists, it is assigned the value from the file. This variable, like all PUBLIC variables, remains after termination of the function or procedure which called the command RESTORE.

References to LOCAL and STATIC variables are resolved at compile time and are not affected by the command RESTORE. These variables cannot be saved with SAVE or read using RESTORE.

Restoring objects

If objects are stored in a file, the method :notifyLoaded() is executed automatically after RESTORE. This method is called only if it is implemented in a user defined class (see the second example).

Restoring dynamic memory variables


// In the example, an array is assigned to a PRIVATE 
// variable. The variable is saved using SAVE, released 
// with RELEASE and read in again using RESTORE. 


PROCEDURE Main 
   MEMVAR aArray 

   PRIVATE aArray := { "Xbase++", ; 
                       123.456  , ; 
                       .T.      , ; 
                       Date()   , ; 
                       {|| QOut("Hello World")} ; 
                     } 

   SAVE TO Temp 

   ? Type("aArray")                  // result: A 

   RELEASE aArray 

   ? Type("aArray")                  // result: U 

   RESTORE FROM Temp 

   ? aArray[2]                       // result: 123.456 
   Eval(aArray[5])                   // result: Hello World 

   ERASE Temp.XPF 
RETURN

Loading persistent objects


// The example demonstrates how objects are notified when loaded from 
// an XPF file. The method :notifyLoaded() is implemented in the 
// class MyClass and executed after RESTORE. 

#include "Common.ch" 

PROCEDURE MAIN 
   MEMVAR obj1, obj2 

   LOCAL cString := "Object 1" 
   LOCAL aArray  := {"Hello", "World"} 

   PRIVATE obj1 := MyClass():new( cString ) 
   PRIVATE obj2 := MyClass():new( aArray ) 

   ? "Objects are created" 

   obj1:show() 
   obj2:show() 

   WAIT "Objects are going to be saved. Press a key." 

   SAVE ALL LIKE obj* TO Temp 
   RELEASE ALL 

   WAIT "Objects are going to be loaded again. Press a key." 

   RESTORE FROM Temp 

   WAIT 
RETURN 


************* 
CLASS MyClass 
   EXPORTED: 
   VAR iVar 
 
   INLINE METHOD init( xValue ) 
      DEFAULT xValue TO ::className() 
      ::iVar := xValue 
   RETURN self 

   INLINE METHOD notifyLoaded 
      ? "I am restored:", ::iVar 
   RETURN self 

   INLINE METHOD show 
      ? ::iVar 
   RETURN self 
ENDCLASS

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Command RESTORE Foundation