|
Caché I/O Device Guide
Sequential File I/O
|
|
This chapter describes using sequential files in Caché. 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, refer to the
Printers chapter of this manual.
This section discusses how Caché 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.
-
Once you have completed file I/O, you issue a
CLOSE command to close the sequential file.
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 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.
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 Mode Parameters
| 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, the system creates a new one with the same name. The status of the old file depends on which operating system you are using. On UNIX® and Windows, Caché deletes the old file. (Note that file locking should be used to prevent two concurrent processes using this parameter from overwriting the same file.) |
| E |
/CREATE /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 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 /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. In Windows, 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 /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 /FIX |
Fixed length: Each record is the length specified in the reclen argument. For example: OPEN "myfile":("RF":4)
USE "myfile":0
READ x:5 This 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\ Knum |
/TRANSLATE[= n]: /IOTABLE[= 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\ Ynum |
|
$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 |
Windows only — 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 Keyword Arguments for Sequential Files
| Keyword |
Default |
Description |
|---|
| |
No default |
Corresponds to the parameters positional parameter. (It provides a way to specify a parameter letter code string in a position-independent way). |
| |
No default |
Corresponds to the reclen positional parameter, which establishes a record size for fixed-length records. (Currently only implemented for READ operations.) |
| |
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.
Windows OPEN Mode Interactions
| |
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 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).
UNIX® OPEN Mode Interactions
| |
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 Caché instance. They do not govern concurrent opens from two different Caché instances, or concurrent opens by Caché and a non-Caché application.
Interactions with Non-Caché Software
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.
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))
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
where
USE Command Parameters
| Argument |
Description |
|---|
| file |
Any valid file specification, enclosed in quotation marks. The specified file must already have been opened. |
| position |
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. |
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:
USE-Only Command Keywords for Sequential Files
| 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. |
After a positioned
READ or
WRITE, subsequent
READ or
WRITE operations proceed sequentially until the next
USE command with a position parameter.
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
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
WRITE Command
The
WRITE command writes data, one record at a time, to the sequential file that is the current device.
Syntax
where
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)
The
CLOSE command relinquishes ownership of a sequential file.
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.
CLOSE-Only Command Keywords for Sequential Files
| Keyword |
Default |
Description |
|---|
| |
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. |
| |
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. |