Restore File

The Restore File (rest) statement positions the file pointer at the start of the file for display, internal or external files; it also positions the file pointer to a specified byte for external files, or to a specified record for internal or external files. The RESTORE file statement can also be used to drop all data from any type of files opened OUTPUT SEQUENTIAL.

1. The positional parameters FIRST, LAST, PRIOR, NEXT, and SAME can now be used with the RESTORE statement, as well as with READ, DELETE and REWRITE. See the Read File statement discussion for details.
2. In linked files, the RESTORE file statement plays two important roles. First, it can be used with the REC= parameter to reposition the file pointer to any specified record number. The number of the anchor record of a desired link list would typically be stored in the associated master record.

If REC= specifies an anchor record KREC is set accordingly. Otherwise KREC is set to zero. The second role of RESTORE is that it can be used without parameters (or REC=0) to create a new anchor point for a linked list that you wish to add or insert. The current position of the file pointer makes no difference when RESTORE is used in this manner.

Comments and Examples

A file must already be opened and assigned a file number before RESTORE can be used. With a display file, RESTORE moves the pointer to the beginning of the file. When used with internal or external files, RESTORE can have three functions.

First, it can move the file pointer to the start of the file when used with the SEQUENTIAL, RELATIVE, or KEYED access methods.

Second, it can move the pointer to a specified relative record number when the file is opened for RELATIVE processing and the REC= clause is specified.

Third, it can position the index file pointer to a record with a specified key field when that file is opened for KEYED processing and a "KEY=" clause is specified.

A fourth function, available only with external files opened for RELATIVE processing, is to position the file pointer to a specified byte number.

Lines 300, 310, 320 and 330 illustrate these four functions, respectively.

00300 RESTORE #1:
00310 RESTORE #2,REC=25: NOREC 920
00320 RESTORE #3,KEY=CUSTNUM$: NOKEY 930
00330 RESTORE #4,POS=25*RLN(4)+1: NOREC 920

Line 300 moves the pointer to the beginning of the file for any type of file (display, internal or external) opened for INPUT. For an internal or external file opened for RELATIVE processing, line 310 moves the pointer to record number 25; the program's next sequential READ (without a REC= clause) would read record 25. If record 25 does not exist, the NOREC clause on line 310 would transfer control to line 920.

For file #3 opened for internal KEYED processing, line 320 moves the pointer in file #3 to the first record with a key field equal to the current value of CUSTNUM$. The next sequential READ (without a KEY= clause) would read this record. If there is no match for this key value, the NOKEY clause on line 320 transfers control to line 930.

File #4 must be opened for external RELATIVE processing to use a POS= clause. Line 330 moves invokes the RLN function to obtain the record length when file #4 was opened; it then computes 25 times this record length and adds one; finally it moves the pointer to the calculated byte number. If this byte is past the end of the file, the NOREC clause will transfer control to line 920.

There are potential problems in using a RESTORE statement to move the pointer to the beginning of the file whenever the file is opened for OUTPUT. All data will be dropped when RESTORE is executed on files opened DISPLAY OUTPUT, or INTERNAL OUTPUT SEQUENTIAL or EXTERNAL OUTPUT SEQUENTIAL; this may not be desirable. An error will result for files opened EXTERNAL OUTPUT RELATIVE, INTERNAL OUTPUT RELATIVE or OUTPUT KEYED whenever an attempt is made to execute a RESTORE.

Syntax

RESTORE #<file number> {[, KEY {=|>=} <string expression>]|[, SEARCH {=|>=} <string expression>]|[, REC=<numeric expression>]|[, POS=<numeric expression>]} [, <positional parameter>] [, {RESERVE|RELEASE}] : [<error condition> <line ref>][,...]

Defaults

1.) Move the pointer to the start of the file. In addition, drop the contents of the file if access is INTERNAL, OUTPUT, SEQUENTIAL, or EXTERNAL, OUTPUT, SEQUENTIAL, or DISPLAY, OUTPUT.

2.) Release current lock and all previous locks.

3.) Interrupt the program if an error occurs and "ON error" is not active.

Parameters

The "#file-num" parameter is a numeric expression that references the file to be acted on. It must evaluate to a number from 0 to 127 or to 255.

The optional "REC = num-expr" clause is used with internal or external files opened for RELATIVE processing; its purpose is to position to a specified record number. After the numeric expression is evaluated and rounded to an integer, the pointer is moved to the start of that record number. If "REC = num-expr" or "POS = num- expr" is not specified, the pointer will be moved to the start of the file (as if RESTORE #n, REC = 1 had been executed).

The optional "POS = num-expr" clause is used only with external files opened for RELATIVE processing; its purpose is to position the file pointer to a specified byte. The numeric expression (usually a simple numeric variable or constant) is evaluated and rounded to an integer before positioning.

The optional "KEY" and "SEARCH" parameters are used with internal files opened for KEYED processing; after the string expression is evaluated, the system reads the first record that matches the key field. If a KEY or if the SEARCH clause is not specified; the system inputs the next record in key sequence.

For complete information about the KEY and SEARCH parameters and the "=" and ">=" operators (used for full and partial matches either exactly equal or "next greater"), see Index Facility.

The positional parameters that can be used with the RESTORE statementare : FIRST, LAST, PRIOR, NEXT, and SAME. Additionally the following are available for System/36 compatibility: RESTORE, DELETE, REWRITE These may be used with Business Rules! internal files which have been opened for either RELATIVE or KEYED access, and with external files. The files must be opened for either INPUT or OUTIN. See Read file for more information.

The "string-expr" parameter is the string that is to be matched to the key field. This specification usually takes the form of a simple string variable or constant.

The "RESERVE" and "RELEASE" parameters specify record locking rules for multi-user systems. "RESERVE" instructs the system to hold all previous locks. "RELEASE" releases all previous locks.

The RESTORE file statement allows error handling with the "error-cond line-ref" parameter. See Error Conditions for more information.

Technical Considerations

1. Relevant error conditions are ERROR, EXIT, IOERR, NOREC, and NOKEY.
2. Although RESTORE #1: is often used to release the record(s) locked by a workstation, REREAD #1: RELEASE is faster.
3. When a file is opened INTERNAL OUTPUT SEQUENTIAL, EXTERNAL OUTPUT SEQUENTIAL, or DISPLAY OUTPUT, the pointer is initially positioned at the end of the file; all new records are added to the end. A RESTORE statement can override this and move the pointer to the beginning of the file. However, all the existing data is dropped (as with the DROP command) and new records are written at the beginning.
4. If an internal file is opened OUTPUT RELATIVE or OUTPUT KEYED, the RESTORE statement cannot be used. If an external file is opened OUTPUT RELATIVE, the RESTORE statement cannot be used without a POS= clause.