OPENSEQ Statement

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

This version of the OPENSEQ statement is provided for compatibility with mvEnterprise. It is only available in MVENTERPRISE mode (set with the $OPTIONS statement). In this mode, Reality items cannot be opened for sequential access.

Syntax

OPENSEQ {EXISTING} {APPENDING} path,filename{,record.size} TOseqfile-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 host file if it does not exist.

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

path,filename The path and filename of the host file to open.

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-var Is the name of a variable to which a reference to the opened file is assigned for use with other sequential access statements. Note that a file reference is assigned even if the file 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.

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 opened successfully	File size	0
ELSE	File does not exist - created automatically	0	2
LOCKED	File already locked	Lock owner's port number	Lock owner's port number
ON ERROR	Invalid path or file-specifier	2416	204
	Invalid record size	2417	205
	The file does not exist (EXISTING keyword used)	2420	206
	General file error	Error number	Error number

Note

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 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 or create it with the CREATE statement.

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 is already locked, the LOCKED clause is executed if present. Otherwise, the OPENSEQ statement is suspended until the file becomes unlocked.

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

Example

$OPTIONS MVENTERPRISE
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. Finally, the file is closed.

$OPTIONS MVENTERPRISE
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.