OPEN
The OPEN statement logically and physically opens a specified file immediately. Normally, files are not opened until an I/O operation is performed on the file, such as a READ or a WRITE, and are handled by APPX automatically. However, OPEN statements may be necessary to switch between disk and cache versions of a file. Also, OPEN statements may be desirable for performance reasons, for example, by checking certain conditions before requiring a file to be opened.
OPEN
SHARE? FAIL CACHE?
(1)
(2) (3) (4) (5) (6)
|
(2) Application ID |
|
(3) File name |
|
(4) Share the file? (Y/N) |
|
(5) Fail action (0=nothing, 1=warning, 2=error, 3=cancel) |
|
(6) Cache? (Y=cache version, N=disk version) |
The next true/false status indicator is set to T if the file exists and was successfully opened, and to F if it cannot be opened. If the process cannot be invoked successfully, the FAIL parameter determines what additional action to take. In addition, on a false condition, the predefined field STATUS CODE returns a token indicating the reason for an I/O command failure. This token can be used as a key to read the system message file to obtain a descriptive I/O error message (see STATUS CODE for details).
A file is physically opened only once for each user, but may be logically opened in several different processes for each user. For example, if a user is entering sales orders, the customer file may be logically opened both for the process that enters the order itself and the related child process that enters the sales line items. Additionally, the OPEN statement allows you to open either the cached version of a file or the disk version of a file.
The SHARE? parameter determines whether other users should be permitted to update the file while it is open. If some other user has opened the file already in a restrictive sharing mode, the current user is presented with an In Use display, unless a TIMEOUT statement with a nonblank label was executed before the OPEN statement. In this case, processing control transfers to the label specified.
The application ID and file name for the file to open are specified in the statement. Additional information that can affect the location of the file may be contained in the predefined fields DATABASE and NEXT DATABASE.
The file name references a file that is defined in the data dictionary of the application ID. You can set the NEXT DATABASE predefined field to the database ID of the database containing the file that you want opened.
If NEXT DATABASE is blank, the DATABASE predefined field is used. Note that the NEXT DATABASE field is modifiable, whereas the DATABASE field is not.
The NEXT DATABASE field is set to blank by the OPEN statement, regardless of whether or not the file is successfully opened.
If NEXT DATABASE is specified in conjunction with a cache file, then NEXT DATABASE is cleared and ignored. Like memory files there is only one instance of a cached file, not one for each database.
Serious problems encountered while trying to open a file, such as a file structure/data dictionary mismatch, cause a non-recoverable runtime error to occur, regardless of the FAIL parameter.
If CACHE? has been set to Y and a cached version of the file does not exist, then the OPEN statement will fail. Therefore, a CREATE statement must be used to create the cached version of a file before the OPEN statement can be used to open it.
BEG READ, CLOSE, CREATE, END READ, READ, READNEXT, SCRATCH, TIMEOUT, WRITE
The following example opens the Customer file in the database labeled ARC. Other users are allowed access to the file. If the OPEN fails, a warning message is generated.
SET ---
NEXT DATABASE = ARC
OPEN TAR
CUSTOMER SHARE? Y FAIL 1 CACHE? N