OPENSEQ Statement

Opens a host file or a Reality item for sequential access, and locks it to prevent access by other users.

Syntax

OPENSEQ {EXISTING} {APPENDING} path{,,record.size} TO seqfile-var {SETTING setting-var} {ON ERROR statement(s)} {LOCKED statement(s)} [ THEN statement(s) | ELSE statement(s) ]

OPENSEQ {EXISTING} {APPENDING} file-specifier,item-id{,record.size} TO seqfile-var {SETTING setting-var} {ON ERROR statement(s)} {LOCKED statement(s)} [ THEN statement(s) | ELSE statement(s) ]

Syntax Elements

EXISTING Inhibits the automatic creation of the file or item if it does not exist.

APPENDING Sets the current file position to the end of the file or item.

path Specifies the host file to be opened.

file-specifier Specifies the Reality file containing the item to be opened.

See General Conventions for the full syntax of file-specifier.

item-id Specifies the Reality item to be opened.

record.size If defined specifies that all data written via the WRITESEQ or WRITEBLK statements will be padded out, if required, such that the length of the data written will always be a multiple of this size.

seqfile-var Is the name of a variable to which a reference to the opened file or item is assigned for use with other sequential access statements. Note that a file reference is assigned even if the file or item does not exist.

setting-var The name of a variable to which the return status is assigned. See Operation for details of the possible values for this variable.

statement(s) A sequence of one or more valid DataBasic statements, either separated by semicolons, or contained on separate lines and followed by an END statement.

Restrictions

OPENSEQ must not be used to open directory views or special files.

Operation

The following details circumstances under which the different clauses are executed and the values returned in setting-var:

Clause Executed	Reason	`setting-var`	STATUS() Value
THEN	File or item opened successfully	File or item size	0
ELSE	File or item does not exist - created automatically	0	2
LOCKED	File or item already locked	Lock owner's port number	Lock owner's port number
ON ERROR	Invalid path, file-specifier or item-id	2416	204
	Invalid record size	2417	205
	The file or item does not exist (EXISTING keyword used)	2420	206
	General file error	Error number	Error number

Notes:

If an error occurs but there is no ON ERROR clause, the DataBasic Debugger will be entered with error B53 as well as the setting-var value.
The final column gives the values returned by the STATUS function if this is used instead of a SETTING clause.

Comments

If you do not include the EXISTING keyword, the specified host file or Reality item will be created immediately if it does not already exist. With the EXISTING keyword, the file will not be created until you write to it.

Note: If you include the EXISTING keyword and the file does not exist, the ON ERROR clause, if any, is executed. If there is no ON ERROR clause, the DataBasic Debugger will be entered.

If the file or item is already locked, the LOCKED clause is executed if present. Otherwise, the OPENSEQ statement is suspended until the file or item becomes unlocked.

The file or item is locked even if it does not exist. Thus, when building a new host file or Reality item, it can be locked first before it is ever written away.

Examples

OPENSEQ "/usr/pauls/qa4" TO SF1 THEN NULL

LOOP WHILE READSEQ LINE FROM SF1 DO
    PRINT LINE
REPEAT

CLOSESEQ SF1

This program opens the host file /usr/pauls/qa4 and saves a reference to the open file in variable SF1. The program then loops, reading lines from the file and displaying them, until the end of the file is reached. Finally, the file is closed.

OPENSEQ APPENDING "/usr/pauls/qa4" TO SF1 THEN NULL

WRITEBLK DATA TO SF1 THEN NULL

CLOSESEQ SF1

This program opens the host file /usr/pauls/qa4 for appending and saves a reference to the open file in variable SF1. The program then writes the contents of the variable DATA to the file and closes it.