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.File class contains numerous methods that provide file system services. These include:

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

• NormalizeFilenameWithSpaces(), 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() method of the %Library.File 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

Argument	Description
filename	Any valid file specification, enclosed in quotation marks. Valid characters may be 8-bit ASCII, or ISO Latin-1 Unicode.
parameters	Optional — A string of one-letter codes, enclosed in quotation marks, that define the file format and types of operations you can perform. (You may also specify parameters using keywords that begin with the slash (/) character.) See the table “OPEN Mode Parameters,” for definitions of these codes. If the parameters do not include R or W, then R is the default. This system-wide default open mode can be configured by setting the OpenMode property of the Config.Miscellaneous class. To open a new file, you must specify the parameter N for new. Otherwise, the OPEN will hang or return unsuccessfully from a timeout. If the parameters do not include S, V, F, or U, then the default for a new Windows or UNIX® file is S, and the default for an existing file is the mode specified when the file was created. If A is not specified, WRITE operations will overwrite the previous contents of the file. Parameters are applied in left-to-right order.
reclen	Optional — For Windows and UNIX systems, specifies the maximum record length for (S) and (U) records, or the absolute record length for fixed-length (F) records. Ignored for variable-length (V) records. Default value is 32767.
terminators	Optional — A string of user-defined record terminators that apply to stream mode only. They let you override the default terminators: carriage return, line feed, and form feed. User-defined terminators only apply to input, they do not affect how data is written to the file (terminators are written to a file as special characters). If there's more than one user-defined terminator, it is treated as a list of terminators, not a multi-character sequence to be used as a single terminator.
timeout	Optional — Number of seconds during which Caché attempts to open the file. If it does not succeed within this interval, it sets $TEST to 0 and returns control to the process. If it succeeds, it sets $TEST to 1.

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.

Copy link to this sectionOPEN 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

Copy code to clipboard

Letter Code	Keyword	Description
N	/NEW	New file. If the specified file does not exist, the system creates the file. If the specified file already exists as a ReadOnly file, the system deletes the old file and replaces it with a new one with the same name (permissions permitting). Note that file locking should be used to prevent concurrent processes using this parameter overwriting the same file. If the “N” mode is not specified and the file specified in OPEN does not exist, the Windows and UNIX® default is to not create a new file. This behavior is configurable using the FileMode() method of the %SYSTEM.Process class. The system-wide default behavior can be established by setting the FileMode property of the Config.Miscellaneous class.
E	/CREATE or /CRE	Create a file if it does not exist. Does not delete and recreate an existing file, as the “N” mode does. The default is to not create a new file. This default is overridden if the FileMode() method of the %SYSTEM.Process class, or the FileMode property of the Config.Miscellaneous class is enabled.
D	/DELETE[=n] or /DEL[=n]	Delete File: Specifies that the file should be automatically deleted when it is closed. /DELETE or /DELETE=n for nonzero values of n enable the parameter code. /DELETE=n for a zero value of n disables the parameter code. The default is to not delete a file.
R	/READ	Read: Caché permits READ access the file. Other processes may also access this file (however, see “L” parameter). If you attempt to open a nonexistent file in “R” mode, the process hangs. To prevent this situation, use a timeout. “R” is the default for all platforms. The system-wide default open mode can be configured by setting the OpenMode property of the Config.Miscellaneous class.
W	/WRITE or /WRI	Write: Caché permits WRITE access to the file. In Windows and UNIX®, “W” gives the process shared write access to the file, with exclusive write access to the record. Use “WL” to specify exclusive write access to the file. If you attempt to open a nonexistent file in “W” mode, the process hangs until the file is created or the process is resolved by a timeout, a Process Terminate, or RESJOB. “R” is the default for all platforms. The system-wide default open mode can be configured by setting the OpenMode property of the Config.Miscellaneous class. Can be used with /OBUFSIZE.
L		Locked Exclusive: Use this mode with the “W” (Write) mode to specify exclusive write access to a file. “WL” or “WRL” specifies that the current process has exclusive write access to the file. A file opened with “RL” may still have shared read access. The effects of the “L” mode on concurrent opens are different in Windows and UNIX®. Refer to the “OPEN Mode Locking” section, below, for further details. On UNIX® systems if one process specifies “WL” (or “WRL”) access to a file, other processes requesting read access to that file must specify “RL” so that UNIX® can coordinate file locking.
A	/APPEND or /APP	Append: WRITE operations append data to the end of an existing file. The default is to overwrite existing data, rather than append.
S	/STREAM	Stream format with carriage return, line feed, or form feed as default terminators. Jobbed processes that inherit TCP devices are automatically set to “S” format. You can reset the format with the USE command. S, V, F, and U modes are mutually exclusive. Stream record format is the default.
V	/VARIABLE	Variable length: Each WRITE creates one record. For Windows and UNIX®, a variable record can be of any length; the reclen argument is ignored. Do not attempt to insert records at any point other than the end of a variable-length sequential file; a WRITE will render inaccessible all data in the file from the point after the WRITE on. S, V, F, and U modes are mutually exclusive. Stream record (S) format is the default. A variable-length record written using a translation table, such as Unicode data using UTF8 translation, can result in a stored record with a different string length than the input data. Caché uses the original input string length when reading this record.
F	/FIXED or /FIX	Fixed length: Each record is the length specified in the reclen argument. For example: OPEN "myfile":("RF":4) USE "myfile":0 READ x:5This example reads the first 4–character record into the variable x. This works only for READ operations (not WRITE operations). S, V, F, and U modes are mutually exclusive.
U	/UNDEFINED	Undefined length: Specifies that file records have an undefined length and therefore READ operations must specify the number of characters to read. The maximum record length is specified in the reclen argument. No translation on output. Default value is the maximum string length. S, V, F, and U modes are mutually exclusive.
K\name\ or Knum	/TRANSLATE[=n]: /IOTABLE[=name] or /TRA[=n]: /IOT[=name]	I/O Translation Mode: When you use the “K” parameter for a device, I/O translation will occur for that device if translation has been enabled system-wide. You identify the previously defined table on which the translation is based by specifying the table's name. When using keywords you specify /TRANSLATE to enable I/O translation (n=1 to enable; n=0 to disable), and /IOTABLE=name to specify the translation table to use. For a list of available translation tables, refer to “Encoded Translation” in the $ZCONVERT function documentation. The + and - options for turning protocols on and off are not available with the K protocol. (The older form Knum, where “num” represents the number of the slot the table is loaded in, is being phased out but is still supported. The system manager can display slot numbers in the %NLS utility in the selection window for each table type.) This parameter may be used with either the OPEN command or the USE command.
Y\name\ or Ynum	/XYTABLE[=name] or /XYT[=name]	$X/$Y Action Mode: When you use the “Y” parameter for a device, the system uses the named $X/$Y Action Table. You identify the previously defined $X/$Y Action Table on which translation is based by specifying the table's name. $X/$Y action is always enabled. If “Y” is not specified and a system default $X/$Y is not defined, a built in $X/$Y action table is used. The + and - options for turning protocols on and off are not available with the Y protocol. (The older form Ynum, where “num” represents the number of the slot the table is loaded in, is being phased out but is still supported. The system manager can display slot numbers in the NLS utility in the selection window for each table type.) This parameter may be used with either the OPEN command or the USE command.
	/NOXY [=n]	No $X and $Y processing: /NOXY or /NOXY=n (for nonzero values of n) disables $X and $Y processing. This can substantially improve performance of READ and WRITE operations. The values of the $X and $Y variables are indeterminate, and margin processing (which depends on $X) is disabled. /NOXY=0 enables $X and $Y processing; this is the default. This parameter may be used with either the OPEN command or the USE command.
	/OBUFSIZE=int	Output Buffering: Creates an output WRITE buffer. The int variable is an integer that specifies the size of the buffer in bytes. May only be used when the file is open for write only (“W”, not “R” or “RW”). May provide significant performance improvement when performing multiple small writes, especially over a WAN. However, data in buffer may be lost if a system crash occurs. Data in buffer is flushed to disk upon CLOSE, or WRITE *-1 or WRITE *-3.
	/GZIP [=n]	GZIP Compression: Specifies GZIP-compatible stream data compression. /GZIP or /GZIP=n (for nonzero values of n) enables compression on WRITE and decompression on READ. /GZIP=0 disables compression and decompression. Before issuing /GZIP=0 to disable compression and decompression, check the $ZEOS special variable to make sure that a stream data read is not in progress. /GZIP compression has no effect on I/O translation, such as translation established using /IOTABLE. This is because compression is applied after all other translation (except encryption) and decompression is applied before all other translation (except encryption).

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"

Copy code to clipboard

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"

Copy code to clipboard

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)

Copy code to clipboard

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

Copy code to clipboard

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

Copy code to clipboard

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)

Copy code to clipboard

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.