OPEN

OPEN

Top  Previous  Next

 

The OPEN statement opens a directory file or dynamic file, associating it with a file variable.

 

 

Format

 

OPEN {dict.expr,} filename.expr {options} TO file.var

{ON ERROR statement(s)}

{THEN statement(s)}

{ELSE statement(s)}

 

where

 

dict.exprevaluates to DICT (case insensitive) to open the dictionary portion of the file or to a null string to open the data portion. If omitted or any other value, the data portion is opened. If given as a literal value, it must be enclosed in quotes. The dict.expr is followed by a comma.

 

filename.exprevaluates to the VOC name of the file to be opened. If given as a literal value, it must be enclosed in quotes.

 

optionscontrol the manner in which the file is opened and may be any combination of:
ENCODING nameSpecifies the default encoding mode for directory files. Ignored for other file types.
NON.TRANSACTIONALIgnore transaction boundaries
NO.MAPSuppress id character translations in directory files
READONLYDisable file updates
SYNCForce write all file updates

 

file.varis the name of the variable to hold the file reference for use in later operations on this file.

 

statement(s)are statements to be executed depending on the outcome of the OPEN operation.

 

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

 

 

A file opened by the OPEN statement may be referenced using the file variable in subsequent statements that operate on the file. The file remains open so long as the file variable remains intact. Overwriting this variable or discard of the variable on return from a subroutine will implicitly close the file. QM has limited support for the concept of a default file variable as found in some other multivalue products.

 

The ENCODING option, applicable only to directory files, sets the default character encoding to be used and overrides any encoding set in the VOC F-type record. 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, falling back on use of any encoding specified in the VOC. To disable an encoding set via the VOC record, the encoding name should be specified as "NULL".

 

The optional NON.TRANSACTIONAL clause indicates that updates to the file are not to be treated as part of any transaction within which they occur.

 

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

 

The optional READONLY clause opens the file for read only access. Any attempt to write will fail.

 

The SYNC option causes updates to the file to be flushed to disk after every write. This will have a severe impact on performance if the file is updated frequently. See synchronous (forced write) mode in the section that discusses dynamic files for more details.

 

 

If the file is opened successfully, the THEN clause is executed.

 

If the open fails the ELSE clause is executed and the STATUS() function may be used to determine the cause of the failure. The default action is to set the file variable as unassigned. Use of the OPEN.FAIL.ZERO.FVAR setting of the $MODE compiler directive changes this to set the file variable to zero.

 

The ON ERROR clause is taken only in the case of serious errors such as damage to the file's internal control structures. The STATUS() function will contain an error number. If no ON ERROR clause is present, a fatal error results in an abort.

 

QM allows more files to be open than the underlying operating system limit. This is achieved by automatically closing files at the operating system level if the  limit is reached, retaining information to reopen them automatically when the next access to the file occurs. This process allows greater freedom of application design but has a performance penalty if a large number of files are used frequently.

 

For dynamic files, the INMAT() function used immediately after the OPEN returns the modulus of the file.

 

 

Example

 

OPEN "STOCK.FILE" TO STOCK ELSE ABORT "Cannot open file"

 

This statement opens a file with VOC name STOCK.FILE. If the open fails, the program aborts with an error message.

 

 

See also:

OPENPATH, OPENSEQ, OPENTEMP