Sequential File I/O

File Pathname Tools

If the current device is a sequential file, $ZIO contains the full pathname of that file.

You can use $ZSEARCH to return the full file specification (pathname and filename) of a specified file or directory. The filename may contain wild cards that $ZSEARCH uses to return a series of fully qualified pathnames that satisfy the wild carding.

The %Library.FileOpens in a new tab class contains numerous methods that provide file system services. These include:

• NormalizeDirectory()Opens in a new tab, which returns the full pathname of a specified file or directory.

• NormalizeFilenameWithSpaces()Opens in a new tab, which handles spaces in pathnames as appropriate for the host platform. If a pathname contains a space character, pathname handling is platform-dependent. Windows and UNIX® permit space characters in pathnames, but the entire pathname containing spaces must be enclosed in an additional set of double quote (") characters. This is in accordance with the Windows cmd /c statement. For further details, specify cmd /? at the Windows command prompt.

Tilde (~) Expansion

In Windows pathnames, a tilde (~) indicates 8.3 compression of long names. For example: c:\PROGRA~1\. To convert compressed directory names, use the NormalizeDirectory()Opens in a new tab method of the %Library.FileOpens in a new tab class.

In UNIX® pathnames, you can use tilde (~) expansion to indicate the current user’s home directory or the home directory of a specified user:

• ~ and ~/myfile.txt are expanded to the current user's home directory: /Users/techwriter/ and /Users/techwriter/myfile.txt, respectively.

• ~guest/myfile.txt is expanded to the home directory of user “guest”: /Users/guest/myfile.txt. However, if user “guest” does not exist, Caché expands to the current user's full directory pathname and appends ~guest/myfile.txt as a literal: /Users/techwriter/Cache/mgr/user/~guest/myfile.txt.

• ~myfile.txt and ~123.txt are appended to the current user's full directory pathname as a literal: /Users/techwriter/Cache/mgr/user/~myfile.txt and /Users/techwriter/Cache/mgr/user/~123.txt, respectively.

OPEN Syntax

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.

OPEN Mode Parameters

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

• A letter code string, such as “VRWN”, enclosed in quote characters. Each letter specifies a parameter. Letter codes may be specified in any order; because Caché executes them in left-to-right order, interactions between letter codes may dictate a preferred order in some cases.

• A series of /keyword parameters, not quoted. These parameters are separated by colons. Keyword parameters may be specified in any order; because Caché executes them in left-to-right order, interactions between parameters may dictate a preferred order in some cases.

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

OPEN Argument Keywords

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

OPEN Mode Locking

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.

Examples

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))

Syntax

USE file:position

USE-Only Command Keywords

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

READ Command

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

Syntax

READ x#n:timeout

where

Argument	Description
x	The variable that will hold the record read from the file.
n	Optional — For a variable-length read, the number of characters to read, specified as an integer. For a fixed-length read, this argument is ignored.
timeout	Optional — The number of seconds to wait for the read operation to complete before timing out. Either an integer value or a variable that resolves to an integer.

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

WRITE Command

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

WRITE x

Example

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)

Syntax

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

CLOSE-Only Command Keywords

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