File I/O
This page describes using sequential files in InterSystems IRIS® data platform.
In most cases, you may be able to use the API provided by the %Library.FileOpens in a new tab class instead of needing the detailed information on this page. See Using %Library.File.
Introduction
All operating systems consider disk I/O files as sequential files. Windows systems consider printers as sequential file I/O devices (unless the printer is connected through a serial communications port). UNIX® systems consider printers as terminal I/O devices. For further details on printers, see Printers.
This section discusses how InterSystems IRIS processes sequential files. It provides an introduction to sequential file I/O and descriptions of the relevant commands.
-
To gain access to a sequential file, you must first open the file using the OPEN command, supplying the name of the file as an argument. You also, optionally, specify OPEN mode parameters. If the OPEN specifies a file that does not exist, a mode parameter specifies whether or not to create a new file. You can open multiple files concurrently.
-
After opening a sequential file, you must specify a USE command to access the file, supplying the name of the file as an argument. The USE command makes the specified file the current device; therefore you can only use one file at a time. The USE command can also specify mode parameters.
-
You then can issue multiple READ or WRITE commands against the file. Each READ or WRITE command delivers one record to or from the file. You cannot write to the file unless it has been opened with the “W” mode parameter. Attempting to read past the end of the file causes an <ENDOFFILE> error.
-
You can use the $ZSEEK function to set the file position, specified by character count offset from the beginning, current position, or end of the sequential file. The $ZPOS special variable contains the current character count position from the beginning of the current sequential file.
-
Once you have completed file I/O, you issue a CLOSE command to close the sequential file.
These operations can also be performed using the methods of the %Library.FileOpens in a new tab class.
The %Library.File.Exists()Opens in a new tab method tells you whether a sequential file with the specified name already exists.
The %Library.File.SizeOpens in a new tab property returns the number of characters currently in the sequential file.
The %Library.File.DateModifiedOpens in a new tab property is updated with the current local date and time when a file is opened, and —if it has been modified—when it is closed.
The %Library.File.IsOpenOpens in a new tab property only returns 1 if the file has been opened by the %Library.File.Open()Opens in a new tab method; the OPEN command does not set this boolean property.
Specifying a File
A sequential file can be specified by a canonical (full) pathname or a relative (partial) pathname that the system expands to a full pathname. A pathname can be canonical (c:\InterSystems\IRIS\mgr\user\myfiles\testfile.txt) or relative to the current directory (testfile.txt). A leading period (.) specifies the current directory. A leading double period (..) specifies the parent of the current directory. If the OPEN command creates a new file, the specified directory must already exist.
A file access error returned by the operating system, such as The system cannot find the file specified is returned by the %SYSTEM.Process.OSError() method. This method returns the operating system error number enclosed in angle brackets, followed by the error text. This is shown in the following Windows example:
USER>OPEN "C:\InterSystems\IRIS\mgr\nodir\testfile.txt":("WNS"):5
USER>w $SYSTEM.Process.OSError()
<3> The system cannot find the path specified.
USER>w ##class(%File).TempFilename("txt","C:\InterSystems\IRIS\mgr\nodir\testfile",.oserrnum)
USER>w $SYSTEM.Process.OSError()
<3> The system cannot find the path specified.
The following Windows examples all create a file in the current namespace (USER) directory:
-
full pathname: OPEN "C:\InterSystems\IRIS\mgr\user\testfile1.txt":("WNS"):10
-
filename expansion: OPEN "testfile2.txt":("WNS"):10
-
current directory expansion: OPEN ".\testfile3.txt":("WNS"):10
The following Windows example creates a file in an existing child directory of the current namespace (USER) directory:
-
child of current directory: OPEN "mytemp\testfile4.txt":("WNS"):10
The following Windows examples create a file using parent directory (..) syntax:
-
parent directory (C:\InterSystems\IRIS\mgr\): OPEN "..\testfile5.txt":("WNS"):10
-
current directory (child of parent directory) C:\InterSystems\IRIS\mgr\user\: OPEN "..\user\testfile6.txt":("WNS"):10.
-
another child of parent directory C:\InterSystems\IRIS\mgr\temp\: OPEN "..\temp\testfile7.txt":("WNS"):10.
-
parent of parent directory C:\InterSystems\IRIS\: OPEN "..\..\testfile8.txt":("WNS"):10.
Windows pathnames use a \ (backslash) directory separator; UNIX pathnames use a / (slash) directory separator. Valid characters may be 8-bit ASCII, or ISO Latin-1 Unicode.
A Windows file pathname specification has the following format:
device:\directory\file.type
For example, C:\InterSystems\IRIS\mgr\user\myfiles\testfile.txt. The type suffix is optional.
A UNIX® file pathname specification has the following format:
../directory/name
A file pathname must not exceed 256 characters when fully expanded. If the pathname length of all directories exceeds 256, a <DIRECTORY> error is generated. If the pathname length exceeds 256 because of the length of the filename, a <NAMEADD> error is generated.
A UNIX® file pathname can include up to 255 characters of any type. While the characters period (“.”) and underscore (“_”) can appear anywhere in the filename, you typically use them to divide the name into meaningful parts. For example, you can define a filename pat_rec.dat, using .dat as the file type.
When accessing files in the current UNIX® default directory, you usually need to specify only the name. The system fills in default values for the directory.
A DLL name can be specified as a full pathname, or a partial pathname. If you specify a partial pathname, InterSystems IRIS expands it to the current directory. Generally, DLLs are stored in the binary directory ("bin"). To locate the binary directory, call the BinaryDirectory()Opens in a new tab method of the %SYSTEM.UtilOpens in a new tab class.
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, InterSystems IRIS expands to the current user's full directory pathname and appends ~guest/myfile.txt as a literal: /Users/techwriter/iris/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/iris/mgr/user/~myfile.txt and /Users/techwriter/iris/mgr/user/~123.txt, respectively.
OPEN Command
OPEN opens a sequential file. Remember that you cannot use the OPEN command to open an InterSystems IRIS 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.
InterSystems IRIS 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 InterSystems IRIS 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 Syntax
OPEN filename{{:({parameters{:reclength{:terminators}}})}{:timeout}}
where
Any valid file specification, enclosed in quotation marks. This file pathname must not exceed 255 characters. Valid characters may be 8-bit ASCII, or ISO Latin-1 Unicode. In UNIX pathnames, you can use tilde (~) expansion to indicate the current user’s home directory. For example: ~myfile or ~/myfile.
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 OpenModeOpens in a new tab property of the Config.MiscellaneousOpens in a new tab 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.
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.
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.
Optional — Number of seconds during which InterSystems IRIS 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.
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 InterSystems IRIS 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 InterSystems IRIS 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
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 (or the “T” 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()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class. The system-wide default behavior can be established by setting the FileModeOpens in a new tab property of the Config.MiscellaneousOpens in a new tab 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()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class, or the FileModeOpens in a new tab property of the Config.MiscellaneousOpens in a new tab class is enabled. |
T | /TRUNCATE | Truncate File: If the file exists and is writable it will be truncated and its attributes left unchanged. If the specified file does not exist, the system creates a new file, just as if the “N” mode was specified. “WT” and “WNT” are functionally identical. |
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: InterSystems IRIS 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 OpenModeOpens in a new tab property of the Config.MiscellaneousOpens in a new tab class. |
W |
/WRITE or /WRI |
Write: InterSystems IRIS 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 OpenModeOpens in a new tab property of the Config.MiscellaneousOpens in a new tab class. Can be used with /OBUFSIZE. |
L | Locked Exclusive: Use the “L” 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. 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. InterSystems IRIS 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, see 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). | |
/COMPRESS=str |
Specifies the stream data compression type as one of these values:
To disable compression, specify /COMPRESS="". To compress a string, use %SYSTEM.Util.Compress()Opens in a new tab. |
OPEN Argument Keywords
The following table describes the OPEN command argument keywords for sequential files:
Keyword | Default | Description |
---|---|---|
/PARAMS=str or /PAR=str |
No default | Corresponds to the parameters positional parameter. (It provides a way to specify a parameter letter code string in a position-independent way). |
/RECORDSIZE=int or /REC=int |
No default | Corresponds to the reclen positional parameter, which establishes a record size for fixed-length records. (Currently only implemented for READ operations.) |
/TERMINATOR=str or /TER=str |
No default | Corresponds to the terminators positional parameter, which establishes user-defined terminators. str is 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. |
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.
W | RW | RL | WL | RWL | R | |
---|---|---|---|---|---|---|
W | 1 | 1 | 1 | 0 | 0 | 1 |
RW | 1 | 1 | 1 | 0 | 0 | 1 |
RL | 1 | 1 | 1 | 0 | 0 | 1 |
WL | 0 | 0 | 0 | 0 | 0 | 0 |
RWL | 0 | 0 | 0 | 0 | 0 | 0 |
R | 1 | 1 | 1 | 0 | 0 | 1 |
For Windows systems, the interactions in this table apply equally to concurrent opens from the same InterSystems IRIS instance, concurrent opens from two different InterSystems IRIS instances, or concurrent opens by InterSystems IRIS and a non-InterSystems IRIS application (with restrictions on non-InterSystems IRIS applications, as described below).
W | RW | RL | WL | RWL | R | |
---|---|---|---|---|---|---|
W | 1 | 1 | 1 | 1 | 1 | 1 |
RW | 1 | 1 | 1 | 1 | 1 | 1 |
RL | 1 | 1 | 1 | 0 | 0 | 1 |
WL | 1 | 1 | 0 | 0 | 0 | 1 |
RWL | 1 | 1 | 0 | 0 | 0 | 1 |
R | 1 | 1 | 1 | 1 | 1 | 1 |
For UNIX® systems, the interactions in this table only to concurrent opens from the same InterSystems IRIS instance. They do not govern concurrent opens from two different InterSystems IRIS instances, or concurrent opens by InterSystems IRIS and a non-InterSystems IRIS application.
Interactions with Non-InterSystems IRIS Software
On Windows systems, opening a sequential file in InterSystems IRIS for “WL” write access generally prevents a non-InterSystems IRIS application from opening the sequential file for write access. Similarly, a non-InterSystems IRIS application opening a sequential file for write access generally prevents an InterSystems IRIS process from concurrent “WL” write access.
However, certain non-InterSystems IRIS 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 an InterSystems IRIS process could still open the file in “WL” mode. An error would occur when one of these non-InterSystems IRIS 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-InterSystems IRIS applications opens a file, then InterSystems IRIS opens, modifies, and closes the file, then the non-InterSystems IRIS 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 InterSystems IRIS for “WL” write access generally has no effect on the behavior of non-InterSystems IRIS applications. You must use locks to reliably restrict write access from non-InterSystems IRIS applications.
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))
USE Command
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.
Syntax
USE file:position
where
Any valid file specification, enclosed in quotation marks. The specified file must already have been opened. In UNIX pathnames, you can use tilde (~) expansion to indicate the current user’s home directory. For example: ~myfile or ~/myfile.
Optional — The position of the next READ or WRITE within the file. The position value is a numerical expression whose meaning depends on the record format of the file. For fixed-length records, position is the absolute record number, relative to zero, where each record contains the number of characters specified in the previous OPEN command. For stream or variable-length records, position is the absolute byte position relative to zero. The default is to read or write records sequentially from the beginning of the file.
You can use the $ZSEEK function to set the file position, specified by character count offset from the beginning, current position, or end of the sequential file. The $ZPOS special variable contains the current character count position from the beginning of the sequential file.
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:
Keyword | Default | Description |
---|---|---|
/POSITION=n | Current file position. (The file pointer position is at the beginning of a file when it is first opened, unless the file was opened in append mode. In that case, the file pointer position is at the end of the file.) | Corresponds to the positional parameter, which sets the position of the next READ or WRITE within a file. |
READ Command
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.
Syntax
READ x#n:timeout
where
The variable that will hold the record read from the file.
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.
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\IRIS\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
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)
WRITE Command
After a positioned READ or WRITE, subsequent READ or WRITE operations proceed sequentially until the next USE command with a position parameter.
The WRITE command writes data, one record at a time, to the sequential file that is the current device.
Syntax
WRITE x
where
The data in variable x is written as one record in the sequential file.
CLOSE Command
The CLOSE command relinquishes ownership of a sequential file.
If the specified file is not open or does not exist, InterSystems IRIS ignores CLOSE and returns without issuing an error.
Syntax
CLOSE file
CLOSE file:"D"
CLOSE file:("R":newname)
where:
Any valid file specification, enclosed in quotation marks. The specified file must already have been opened. In UNIX pathnames, you can use tilde (~) expansion to indicate the current user’s home directory. For example: ~myfile or ~/myfile.
Closes and deletes the file with the name specified in the argument.
Closes the file with the name specified in the argument and renames it newname.
CLOSE-Only Command Keywords
The following table describes the keywords for controlling sequential files with only the CLOSE command.
Keyword | Default | Description |
---|---|---|
/DELETE[=n] or /DEL[=n] |
0, unless the file was marked for delete when it was opened. | Corresponds to the D parameter code, which specifies that the file should be deleted. /DELETE or /DELETE=n for nonzero values of n enable the parameter code and /DELETE=n for a zero value of n disables the parameter code. |
/RENAME=name or /REN=name |
Do not rename the file. | Corresponds to the R parameter code and the file name positional parameter. The R parameter code specifies that the file should be renamed and the file name positional parameter gives the new name of the file. |