OPENSEQ

OPENSEQ

Top  Previous  Next

 

The OPENSEQ statement opens a record of a directory file, a device or a pipe for sequential access.

 

 

Format

 

OPENSEQ file.name, id {options} TO file.var

{ON ERROR statement(s)}

{LOCKED statement(s)}

{THEN statement(s)}

{ELSE statement(s)}

or

OPENSEQ pathname {options} TO file.var

{ON ERROR statement(s)}

{LOCKED statement(s)}

{THEN statement(s)}

{ELSE statement(s)}

 

where

 

file.nameevaluates to the VOC name of the directory file holding the record to be opened.

 

idevaluates to the name of the record to be opened.

 

pathnameevaluates to the operating system pathname of the record to be opened. This may be a file, a device or a pipe.

 

optionsare chosen from the following, each of which is described in detail below:

ENCODING name

APPEND

CREATING

NOBUF

NO.MAP

OVERWRITE

READONLY

SHARED

 

file.varis the name of a variable to be used in later statements accessing this record.

 

statement(s)are statement(s) to be executed depending on the outcome of the OPENSEQ statement.

 

At least one of the THEN and ELSE clauses must be present.

 

 

The named record is opened and associated with file.var for later operations.

 

The optional ENCODING clause sets the default character encoding to be used and overrides any encoding set in the VOC F-type record for the first form of OPENSEQ. Because the second form of this statement does not reference the VOC, any encoding to be applied must be specified using the ENCODING option. The name may be a quoted literal string or an expression that evaluates to the encoding name. A null string as the encoding name is equivalent to not having the ENCODING clause at all. To disable the default encoding, the encoding name should be specified as "NULL".

 

Use of the APPEND option causes the OPENSEQ statement to position at the end of any existing data in the record such that subsequent write operations will append new data. Use of OVERWRITE truncates the record to remove any existing data. These two options may not be used together.

 

The NOBUF option causes the file, device or pipe opened by OPENSEQ to be accessed in an unbuffered mode. This is likely to degrade performance compared to use of the default buffered mode but allows, for example, two processes to read from the same pipe.

 

The NO.MAP option suppresses the normal translation of restricted characters in record ids. See directory files for more information.

 

The READONLY option opens the item for read only access. Any attempt to write will fail.

 

The SHARED option allows multiple QM processes to open the same record such that use of WRITEBLK, WRITECSV, WRITESEQ or WRITESEQF will append to the record, allowing easy construction of audit trail logs or other similar items. Use of this option implies APPEND and NOBUF. Also, the record will be created by OPENSEQ if it does not already exist.

 

 

If the record already exists, the THEN clause is executed. Except when using the SHARED option, an update lock will be set on this record unless the record is read-only in which case a shared read lock is set.

 

If the record does not already exist, the action depends on whether the CREATING option has been used. If this option is present, the record is created and the THEN clause is executed. Otherwise the ELSE clause is executed and the STATUS() function returns zero. The record will have been locked and use of WRITESEQ, WRITESEQF, WRITEBLK, WEOFSEQ or CREATE with the returned file.var will create the record. Alternatively, the lock can be released using RELEASE or closing the file.var

 

The ELSE clause is also executed if the specified item cannot be opened due to an error. The STATUS() function will contain the error code.

 

The LOCKED clause is executed if the record is already locked by another process.

 

The ON ERROR clause is executed if a fatal error occurs when opening the record. The STATUS() function will return an error code relating to the problem.

 

 

A record open for sequential access may be read and written using READSEQ and WRITESEQ respectively. The WRITESEQF statement provides a forced write and WEOFSEQ sets an end of file marker. The record should be closed using CLOSESEQ though it will be closed automatically when the program in which the file variable lies terminates.

 

The second form of OPENSEQ may be used to open a serial port by using the device name as pathname. On Windows, this name is COM1, COM2, etc followed by a colon. On other platforms, it is the device driver name.

 

To open a floppy disk drive (e.g. a Pick style account save) specify the pathname as "A:" on Windows or use the device driver name (probably /dev/fd0) on Linux.

 

 

Examples

 

OPENSEQ "STOCKS", "STOCK.LIST" TO STOCK.LIST ELSE

  IF STATUS() THEN ABORT "Cannot open stocks list"

END

 

This program fragment opens the record STOCK.LIST of directory file STOCKS. If it fails to either open an existing record or to create a new record, the program aborts.

 

 

OPENSEQ "C:\TEMP\IMPORT.DATA" TO DAT.F ELSE

  IF STATUS() THEN ABORT "Cannot open import data file"

END

 

This program fragment opens the operating system file in C:\TEMP\IMPORT.DATA for sequential processing.

 

 

See also:

CLOSESEQ, CREATE, NOBUF, READBLK, READCSV, READSEQ, SEEK, WEOFSEQ, WRITEBLK, WRITECSV, WRITESEQ, WRITESEQF