Restore File - Revision history

John at 15:50, 12 April 2018

2018-04-12T15:50:17Z

← Older revision		Revision as of 15:50, 12 April 2018
Line 1:		Line 1:
	The '''Restore File''' [[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.		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.

	# 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.		# 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.

Laura: /* Syntax */

2016-06-16T20:22:27Z

Syntax

← Older revision		Revision as of 20:22, 16 June 2016
Line 33:		Line 33:

	===Syntax===		===Syntax===
	RESTORE #<[[file number]]> {[, [[KEY]] {=\|>=} <[[string expression]]>]\|[, [[Index_Facility#Finding_records_with_the_KEY_and_SEARCH_parameters\|SEARCH]]{=\|>=} <[[string expression]]>]\|[, [[REC=]]<[[numeric expression]]>]\|[, [[Pos Parameter\|POS]]=<[[numeric expression]]>]} [, <[[positional parameter]]>] [, {[[RESERVE]]\|[[RELEASE]]}] : [<[[error condition]]> <[[line ref]]>][,...]		RESTORE #<[[file number]]> {[, [[KEY]] {=\|>=} <[[string expression]]>]\|[, [[Index_Facility#Finding_records_with_the_KEY_and_SEARCH_parameters\|SEARCH]] {=\|>=} <[[string expression]]>]\|[, [[REC=]]<[[numeric expression]]>]\|[, [[Pos Parameter\|POS]]=<[[numeric expression]]>]} [, <[[positional parameter]]>] [, {[[RESERVE]]\|[[RELEASE]]}] : [<[[error condition]]> <[[line ref]]>][,...]
	[[Image:Restorefile.png\|850px]]		[[Image:Restorefile.png\|850px]]

Laura: /* Syntax */

2016-06-16T20:22:11Z

Syntax

← Older revision		Revision as of 20:22, 16 June 2016
Line 33:		Line 33:

	===Syntax===		===Syntax===
	RESTORE #<[[file number]]> {[, [[KEY]] {=\|>=} <[[string expression]]>]\|[, [[Index_Facility#Finding_records_with_the_KEY_and_SEARCH_parameters\|SEARCH]]]\|[, [[REC=]]<[[numeric expression]]>]\|[, [[Pos Parameter\|POS]]=<[[numeric expression]]>]} [, <[[positional parameter]]>] [, {[[RESERVE]]\|[[RELEASE]]}] : [<[[error condition]]> <[[line ref]]>][,...]		RESTORE #<[[file number]]> {[, [[KEY]] {=\|>=} <[[string expression]]>]\|[, [[Index_Facility#Finding_records_with_the_KEY_and_SEARCH_parameters\|SEARCH]]{=\|>=} <[[string expression]]>]\|[, [[REC=]]<[[numeric expression]]>]\|[, [[Pos Parameter\|POS]]=<[[numeric expression]]>]} [, <[[positional parameter]]>] [, {[[RESERVE]]\|[[RELEASE]]}] : [<[[error condition]]> <[[line ref]]>][,...]
	[[Image:Restorefile.png\|850px]]		[[Image:Restorefile.png\|850px]]

John at 20:38, 2 June 2016

2016-06-02T20:38:56Z

← Older revision		Revision as of 20:38, 2 June 2016
Line 50:		Line 50:
	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.		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 ~~the~~ Index Facility ~~chapter~~.		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]]		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]]

Laura: /* Syntax */

2014-05-05T17:29:30Z

Syntax

← Older revision		Revision as of 17:29, 5 May 2014
Line 33:		Line 33:

	===Syntax===		===Syntax===
	RESTORE #<file number> {[, KEY {=\|>=} <string expression>]\|[, SEARCH]\|[, REC=<numeric expression>]\|[, POS=<numeric expression>]} [, <positional parameter>] [, {RESERVE\|RELEASE}] : [<error condition> <line ref>][,...]		RESTORE #<[[file number]]> {[, [[KEY]] {=\|>=} <[[string expression]]>]\|[, [[Index_Facility#Finding_records_with_the_KEY_and_SEARCH_parameters\|SEARCH]]]\|[, [[REC=]]<[[numeric expression]]>]\|[, [[Pos Parameter\|POS]]=<[[numeric expression]]>]} [, <[[positional parameter]]>] [, {[[RESERVE]]\|[[RELEASE]]}] : [<[[error condition]]> <[[line ref]]>][,...]
	[[Image:Restorefile.png\|850px]]		[[Image:Restorefile.png\|850px]]

Laura: /* Syntax */

2014-04-29T14:21:01Z

Syntax

← Older revision		Revision as of 14:21, 29 April 2014
Line 33:		Line 33:

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

Laura: /* Syntax */

2013-02-01T03:13:24Z

Syntax

← Older revision		Revision as of 03:13, 1 February 2013
Line 33:		Line 33:

	===Syntax===		===Syntax===
	[[Image:Restorefile.png]]		[[Image:Restorefile.png\|850px]]

	===Defaults===		===Defaults===

Laura at 03:00, 1 February 2013

2013-02-01T03:00:24Z

← Older revision		Revision as of 03:00, 1 February 2013
Line 1:		Line 1:
	The '''Restore File''' [[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.		The '''Restore File''' [[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.

	# 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"~~Read File statement discussion for details.		# 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.
	# 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.		# 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.

Line 7:		Line 7:

	===Comments and Examples===		===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.		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.		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.		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.
Line 47:		Line 47:
	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 "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		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.

	SEARCH		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 the Index Facility chapter.
	~~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 the Index Facility chapter~~.		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 "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.
Line 58:		Line 58:
	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 "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 ~~the~~ Error Conditions ~~chapter~~ for more information.		The RESTORE file statement allows error handling with the "error-cond line-ref" parameter. See [[Error Conditions]] for more information.

	===Technical Considerations===		===Technical Considerations===
	# Relevant error conditions are ERROR, ~~Exit~~, IOERR, NOREC, and NOKEY.		# Relevant error conditions are [[ERROR]], [[EXIT]], [[IOERR]], [[NOREC]], and [[NOKEY]].
	# Although RESTORE #1: is often used to release the record(s) locked by a workstation, REREAD #1: RELEASE is faster.		# Although RESTORE #1: is often used to release the record(s) locked by a workstation, REREAD #1: RELEASE is faster.
	# 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.		# 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.

Laura: Created page with "The '''Restore File''' 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 speci..."

2013-02-01T02:39:42Z

Created page with "The '''Restore File''' 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 speci..."

New page

The '''Restore File''' [[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.

# 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"Read File statement discussion for details.
# 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===
[[Image:Restorefile.png]]

===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

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 the Index Facility chapter.

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 the Error Conditions chapter for more information.

===Technical Considerations===
# Relevant error conditions are ERROR, Exit, IOERR, NOREC, and NOKEY.
# Although RESTORE #1: is often used to release the record(s) locked by a workstation, REREAD #1: RELEASE is faster.
# 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.
# 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.

<noinclude>
[[Category:External File Processing Statements]]
[[Category:Internal File Processing Statements]]
[[Category:Statements]]
</noinclude>