This section discusses how Caché processes sequential files. It provides an introduction to sequential file I/O and descriptions of the relevant commands.

OPEN opens a Caché sequential file. Remember that you cannot use the OPEN command to open a Caché database file.

The OPEN command by itself does not prevent another process from opening the same sequential file. You can govern concurrent sequential file access by using the OPEN command “L” mode parameter and/or the ObjectScript LOCK command. File locking support is provided by the file access rules of the underlying operating system.

Caché allocates each process' open file quota between database files and files opened with the ObjectScript OPEN command. When an OPEN command causes too many files to be allocated to OPEN commands, a <TOOMANYFILES> error occurs. The Caché maximum number of open files for a process is 1,024. The actual maximum number of open files for each process is a platform-specific setting. For example, Windows defaults to a maximum of 998 open files per process. Consult the operating system documentation for your system.

OPEN filename{{:({parameters{:reclength{:terminators}}})}{:timeout}}

where

The timeout argument, though optional, is strongly recommended because the success or failure of OPEN is indicated by the value of the $TEST special variable, and $TEST is only set if timeout is specified. $TEST is set to 1 if the open attempt succeeds before the timeout expires; if the timeout expires, $TEST is set to 0.

You can specify the OPEN mode parameters in either of two ways:

When specifying a combination of letter code parameters and keyword parameters, specify the letter code string first, followed by the keyword parameter(s), separated with colons. The following example specifies three letter code parameters, followed by two keyword parameters, followed by the reclen and timeout arguments.

  OPEN "mytest":("WNS":/OBUFSIZE=65536:/GZIP=0:32767):10

The following table describes the OPEN command argument keywords for sequential files:

When two processes attempt to open the same sequential file, the second OPEN succeeds or fails based on the mode used by the first OPEN. The following tables show the interactions between two opens using exclusive (“L”) and non-exclusive read and write modes. Note that the interpretation of these interactions is platform-dependent. Tables are provided for Windows operating systems and UNIX® operating systems.

In the following tables, the horizontal axes indicates the open mode of the first OPEN and the vertical axis indicates the open mode of the second OPEN. A 1 indicates that the second OPEN succeeds; a 0 indicates that the second OPEN fails.

For Windows systems, the interactions in this table apply equally to concurrent opens from the same Caché instance, concurrent opens from two different Caché instances, or concurrent opens by Caché and a non-Caché application (with restrictions on non-Caché applications, as described below).

For UNIX® systems, the interactions in this table only to concurrent opens from the same Caché instance. They do not govern concurrent opens from two different Caché instances, or concurrent opens by Caché and a non-Caché application.

On Windows systems, opening a sequential file in Caché for “WL” write access generally prevents a non-Caché application from opening the sequential file for write access. Similarly, a non-Caché application opening a sequential file for write access generally prevents a Caché process from concurrent “WL” write access.

However, certain non-Caché applications, including the Notepad and WordPad applications, open a file, make a copy of the file in shared mode, and then immediately close it. Thus a Caché process could still open the file in “WL” mode. An error would occur when one of these non-Caché applications then either attempts to save changes from their copy to the original, or attempts to reopen the original file. A more serious situation can occur as follows: If one of these non-Caché applications opens a file, then Caché opens, modifies, and closes the file, then the non-Caché application saves changes to the file, the changes made by both processes are saved, and the integrity of the file data could be compromised.

On UNIX® systems, opening a sequential file in Caché for “WL” write access generally has no effect on the behavior of non-Caché applications. You must use locks to reliably restrict write access from non-Caché applications.

The following example opens the file “LUDWIG.B” in the current directory. Because it specifies no mode parameters, it opens the file with read access and in stream mode by default:

  OPEN "LUDWIG.B"

The following example opens a new file “LIST.FILE” in the current directory, with write access, in stream format. Notice that you do not need parentheses when you include only the first of the arguments they would normally enclose.

  OPEN "LIST.FILE":"WNS"

The following example opens a file “CARDS” in the current directory, with read and write access, and 80-character fixed-length records.

  OPEN "CARDS":("FRW":80)

The following example opens the stream-format file “STRNG” in the directory c:\usr\dir, with non-default terminators.

  OPEN "c:\usr\dir\STRNG":("S"::$CHAR(0)_$CHAR(255))

The USE command makes an opened sequential file the current device. You can have many open sequential files, but you can use only one sequential file at a time.

USE file:position

where

In addition to the command keywords that it shares with OPEN, listed above, the USE command has its own set of keywords:

After a positioned READ or WRITE, subsequent READ or WRITE operations proceed sequentially until the next USE command with a position parameter.

The READ command reads data from the current device, one record at a time. Reading past the end of file causes an <ENDOFFILE> error.

READ x#n:timeout

where

The timeout argument, though optional, is strongly recommended because the success or failure of the READ is indicated by the value of the $TEST special variable if timeout is specified. $TEST is set to 1 if the read attempt succeeds before the timeout expires; if the timeout expires, $TEST is set to 0.

The following example shows a READ operation reading fixed-length records from a Windows sequential file. It creates a sequential file, writes data into it, then closes the file. It then opens this file for fixed-length reads of 4 characters ("RF":4). It sets the USE position argument to the first record (record 0); each read operation advances this position. A FOR loop reads each four-character record into a subscripted variable. The ZWRITE command then displays all of these subscripted local variables and their values.

  SET myf="C:\InterSystems\Cache\mgr\temp\myfixedlengthfile"
  OPEN myf:("NW") USE myf WRITE "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
  CLOSE myf
  OPEN myf:("RF":4) USE myf:0 FOR i=1:1:7 {READ x(i):5}
  CLOSE myf
  ZWRITE

The WRITE command writes data, one record at a time, to the sequential file that is the current device.

WRITE x

where

The following example reads the third, fourth, and fifth records of a fixed-length file:

   SET myfile="FIXED.LEN"
   OPEN myfile:("FR":100)
   USE myfile:2 
   READ var1(3),var1(4),var1(5)

The CLOSE command relinquishes ownership of a sequential file.

CLOSE file
CLOSE file:"D"
CLOSE file:("R":newname)

The following table describes the keywords for controlling sequential files with only the CLOSE command.