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} TOseqfile-var {SETTING setting-var} {ON ERROR statement(s)} {LOCKED statement(s)} [ THEN statement(s) | ELSE statement(s) ]

or

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

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

pathSpecifies the host file to be opened.

file-specifierSpecifies the Reality file containing the item to be opened.

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

item-idSpecifies the Reality item to be opened.

record.sizeIf 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-varIs 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-varThe 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

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.

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.

See also

CLOSESEQ statement, READSEQ statement, READBLK statement, WRITESEQ statement, WRITEBLK statement, SEEK statement, DELETESEQ statement, WEOFSEQ statement.