OPEN
Synopsis
OPEN [SECTION,] mvfile [TO filevar] [SETTING var] [ON ERROR statements] [THEN statements] [ELSE statements]
Arguments
| SECTION | Optional — An expression evaluating to “DICT”, “DATA”, or “”. Unless SECTION is “DICT”, the section opened by OPEN is determined by the mvfile argument. |
|
DATA DICT |
Optional — A keyword specifying whether to access the MultiValue data file or the dictionary file. The default is to access the data file. Note the required comma following this keyword. |
| mvfile | An expression evaluating to a filename defined in the VOC, or an mv filename path. See the Description below. |
| filevar | Optional — A local variable name assigned to the MultiValue file. If omitted, the file is opened into the special variable @STDFIL. |
| SETTING var | Optional — When an error occurs, sets the local variable var to the operating system's error return code. Successful completion returns 0; error return codes are platform-specific. The SETTING clause is executed before the ON ERROR, THEN, or ELSE clause. Provided for jBASE compatibility. |
Description
The OPEN statement is used to open the mvfile MultiValue file. This must either be an existing file defined as a file in the VOC, or the VOC itself. You can create a MultiValue file by using the CREATE.FILE verb.
You can specify mvfile in any of the following ways:
"filename" "filename," "filename,datasection" "account,," "account,filename," "account,filename,datasection"
The following four OPEN statements all do the same thing:
OPEN “DATA”,”filename” OPEN “DATA filename” OPEN “filename” OPEN “filename,filename”
The following two OPEN statements both do the same thing:
OPEN “DICT”,”filename” OPEN “DICT filename”
Note the trailing comma(s) in several of these formats. "filename" and "filename," are functionally identical. If you specify "account,," the VOC for the specified account is opened. If mvfile is an empty string, OPEN executes its ELSE clause.
The OPEN statement assigns a filevar variable to the specified MultiValue file. filevar is a local variable specific to the current process. You use this filevar variable to refer to the MultiValue file in subsequent READ, WRITE, and other file statements. Issuing a CLOSE statement deletes the filevar value.
A process can successfully issue multiple concurrent OPEN statements against the same MultiValue file. Multiple processes can issue concurrent OPEN statements against the same MultiValue file.
You can optionally specify an ON ERROR clause, which is executed if an argument is invalid.
You can optionally specify a THEN clause, an ELSE clause, or both a THEN and an ELSE clause. If the file open is successful (the specified file exists), the THEN clause is executed. If file open fails (the specified file does not exist), the ELSE clause is executed. Commonly, a STOP is issued as part of an ELSE clause.
You can use the STATUS function to determine the status of the file open operation, as follows: 0=success; -1=file does not exist.
After opening a file, you can use the STATUS statement to obtain file status information. You can use the FILEINFO function to get information about an open file.
OPEN is used to open a MultiValue file for READ and WRITE access. Use OPENSEQ to open a sequential file.
The following example uses OPEN to open the VOC file:
OPEN 'VOC' TO MyVoc
IF 0=STATUS() THEN PRINT 'Opened file' ELSE STOP 201,'VOC'
CLOSE MyVoc
IF 0=STATUS() THEN PRINT 'Closed file' ELSE PRINT 'Close error'
Directory Direct Reference
You can use the double slash (//) prefix to directly reference a directory pathname from the OPEN command. For example:
OPEN "//C:/temp" TO DSCB
WRITE results ON DSCB,"results.txt"
This program opens the Windows directory C:/temp and creates the file C:/temp/results.txt.
The directory pathname must be preceded by //, and must not already exist in the VOC.
The DICT and DATA keywords are not meaningful in this context. Either may be specified or omitted without affecting the directory reference.
Emulation
You may specify the keyword SYSTEM before the account portion of mvfile. For example: "SYSTEM,account,filename". In Caché MVBasic this keyword is a no-op, it is provided for compatibility with other MultiValue implementations.
In D3 emulation mode, you can specify MDS, rather than SYSTEM, as this no-op keyword prefix.
