OPENSEQ

Opens a file for sequential access.

Synopsis

OPENSEQ filename TO filevar [LOCKED statements] 
[ON ERROR statements] [THEN statements] [ELSE statements]

Arguments

filename	The file to be opened. A fully-qualified Windows or UNIX® file pathname, specified as a quoted string. For two-part versions of this argument, see the Emulation section below.
TO filevar	A file variable name used to refer to the file in Caché MVBasic. filevar can be a simple variable, or can be a single dynamic array reference (A<i>), a single substring reference (A[s,l]), or a substring reference nested inside a dynamic array reference (A<i>[s,l]).

Description

The OPENSEQ statement is used to open a file for sequential access. This can be an existing file or a new file. It assigns the file to filevar.

You can optionally specify a LOCKED clause, which is executed if OPENSEQ could not open the specified file due to lock contention. The LOCKED clause is optional, but strongly recommended; if no LOCKED clause is specified, program execution waits indefinitely for the conflicting lock to be released.

You can optionally specify an ON ERROR clause, which is executed if the file could not be opened. If no ON ERROR clause is present, the ELSE clause is taken for this type of error condition.

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.

You can use the STATUS function to determine the status of the sequential file open operation, as follows: 0=success; -1=file does not exist.

To create a file, you must first issue an OPENSEQ statement, giving the fully-qualified pathname for the file you wish to create. Because the file does not yet exist, the OPENSEQ appears to fail, taking its ELSE clause and setting the value returned by the STATUS function to -1. However, the OPENSEQ sets its filevar to an identifier for the specified file. You then supply this filevar to CREATE to create the new file.

The filename must be a fully-qualified pathname. The directories specified in filename must exist for a file create to be successful. Pathnames are not case-sensitive; however, case is preserved when you specify a filename to create a sequential file.

After opening a file, you can use the STATUS statement to obtain file status information. You can use READBLK, READSEQ, WRITEBLK, and WRITESEQ to perform sequential read and write operations. You can use CLOSESEQ to release an open file, making it available to other processes.

File Locking

Issuing OPENSEQ gives the process exclusive access to the specified file. An OPENSEQ locks the file against an OPENSEQ issued by any other process. This lock persists until the process that opened the file releases the lock, by issuing a CLOSE, a CLOSESEQ, or a RELEASE statement.

Issuing an OPENSEQ for a non-existent file also performs an exclusive file lock, so that your process can issue a CREATE to create this file. A CLOSE or CLOSESEQ releases this file lock, whether or not the file has been successfully created.

If an OPENSEQ without a LOCKED clause attempts to open a file already opened by another process, the OPENSEQ waits until the first process closes (or releases) the desired file. If an OPENSEQ with a LOCKED clause attempts to open a file already opened by another process, the OPENSEQ concludes by executing the LOCKED clause statements. The ELSE clause is not invoked because of lock contention.

FILEINFO and @FILENAME

You can use the FILEINFO function to return sequential file information, including whether a specified filevar has been defined (key=0) and the filename specified in OPENSEQ for that filevar (key=2). The @FILENAME system variable also contains the filename specified in the most recent OPENSEQ.

In both cases, the file does not have to exist; if OPENSEQ specifies a non-existent file, both FILEINFO and @FILENAME return the specified pathname as a directory path. Subsequently creating this file does not change the FILEINFO and @FILENAME pathname values. If the file does not exist, the FILEINFO file type (key=3) is 0. Creating the file changes this FILEINFO file type to 5.

Sequential File I/O Buffering

By default, sequential file I/O is performed using I/O buffering. This buffer is automatically assigned as part of the OPENSEQ operation. I/O buffering significantly improves overall performance, but means that write operations are not immediately applied to the sequential file.

Caché MVBasic provides two statements that override I/O buffering. The FLUSH statement immediately writes the current contents of the I/O buffer to the sequential file. The NOBUF statement disables the I/O buffer for the duration of the sequential file open. That is, all subsequent I/O write operations are immediately executed on the sequential file.

Emulation

For jBASE emulation, the filename argument can be specified with a two-part path,filename syntax. When executed, the two parts are concatenated together, with a delimiter added to the end of path, when necessary. For example, OPENSEQ 'c:\temp\','mytest.txt' TO FD or OPENSEQ 'c:\temp','mytest.txt' TO FD.

For other emulation modes, the filename argument can be specified with a two-part file,itemID syntax. The file part is a dir-type file defined in the VOC master dictionary, and the itemID part is an operating system file within that directory.

Examples

The following example opens a sequential file on a Windows system and writes a line to it. If the file does not exist, it creates the file:

filename='c:\myfiles\test1'
OPENSEQ filename TO mytest ELSE STOP 201,filename
   IF STATUS()=0 
   THEN
     WRITESEQ "John Doe" TO mytest
     CLOSESEQ mytest
   END
   ELSE
     CREATE mytest
     IF STATUS()=0
       THEN
         WRITESEQ "John Doe" TO mytest
         CLOSESEQ mytest
       END
       ELSE
         PRINT "File create failed"
       END
   END