Synergy stream files are used to access records sequentially or by relative record number.
Stream file structure
A stream file consists of a byte stream where the end of each record is defined by the location of the record terminator. On UNIX, the default record terminator is a single LF (line feed) byte. On Windows and OpenVMS, the default record terminator is a LF CR (line feed and carriage return) byte pair, but the record terminator can also be a single LF (line feed) byte. On all systems, a record terminator can also be a VT (vertical tab) byte or a FF (form feed) byte.
Random record positioning is accomplished by multiplying the record number minus one by the sum of the record size and the number of bytes in the default record terminator to determine the byte offset from the beginning of the file.
Stream file types
On Windows and UNIX, there is only one file type: a byte stream, where the records are defined by the placement of the record terminator.
To create a stream file, specify the mode as O or A without a submode on the OPEN statement. On OpenVMS, the OPTIONS=“/STREAM” qualifier must also be present or the file must have been compiled with the /STREAM switch to create a stream file. To open an existing stream file, specify the mode as I, U, or A without a submode on the OPEN statement.
Record access
Records are accessed randomly by specifying the record number as a numeric field in the key field of a READ, FIND, or WRITE statement, or sequentially using the READS or WRITES statements.
Stream record input and output statements
This section lists the primary input and output statements and describes how their use affects stream files. System-specific differences are also listed. See the Synergy DBL Statements for more information about other statement qualifiers that are not specific to stream file access.
READ statement
read(channel, record, record_number)
You can use the READ statement to retrieve a record from the file by specifying the relative record number. To specify the first or last record in the file, replace the record number with ^FIRST or ^LAST, respectively. The POSITION qualifier can replace ^FIRST or ^LAST. READ returns the data from the new file position to the next record terminator.
FIND statement
find(channel, record, record_number)
The FIND statement positions to the record specified by record_number. To specify the first or last record in the file, replace the record number with ^FIRST or ^LAST, respectively. To specify the beginning (before the first record) or end of the file (after the last record, replace the record number with ^BOF or ^EOF, respectively. The POSITION qualifier can replace ^FIRST, ^LAST, ^BOF, or ^EOF.
WRITE statement
write(channel, record, record_number)
You can use the WRITE statement to replace a record in the file or add a record at the end of the file. You can extend a stream file opened in update mode by specifying the record at the current end-of-file position. The WRITE statement writes the contents of the record plus the default record terminator.
READS statement
reads(channel, record, eof_label)
The READS statement retrieves the next sequential record in the file. It returns the data from the current file position to the next record terminator.
WRITES statement
writes(channel, record)
The WRITES statement replaces the next sequential record in the file or adds a record at the end of the file. You can extend a stream file opened in update mode by writing the record when positioned at the current end-of-file position. The WRITES statement writes the contents of the record plus the record terminators.
GET statement
get(channel, record, record_number)
The GET statement retrieves a record from the file by specifying the relative record number. It returns the contents of the file from the new file position for the length of the record, regardless of any record terminators.
GETS statement
gets(channel, record, eof_label)
The GETS statement retrieves the next sequential record in the file. It returns the contents of the file from the current file position for the length of the record, regardless of any record terminators.
PUT statement
put(channel, record, record_number)
The PUT statement replaces a record in the file or adds a record at the end of the file. You can extend a stream file opened in update mode by specifying the record at the current end-of-file position. The PUT statement writes only the contents of the record; the default record terminator is not written.
PUTS statement
puts(channel, record, eof_label)
The PUTS statement replaces the next sequential record in the file or adds a record at the end of the file. You can extend a stream file opened in update mode by writing the record at the current end-of-file position. The PUTS statement writes only the contents of the record; the default record terminator is not written.
UNLOCK statement
unlock(channel)
The UNLOCK statement unlocks any records with automatic locks. On OpenVMS, the blocks encompassing the locked record are unlocked.
%RSIZE function
size = %rsize
The %RSIZE (or %RDLEN) function retrieves the size of the last record read but does not include the record terminator. The returned value is for the last operation, regardless of the channel used.
%RTERM function
value = %rterm
For READ and READS operations, %RTERM (or %RDTRM) returns the record terminator of the last operation, regardless of the channel used.
%RECNUM function
number = %recnum(channel)
The %RECNUM function returns the relative record number of the last accessed record.
Record locking
On Windows and UNIX, the bytes encompassing the record plus the record terminator are locked when the READ or READS statement is used. When the GET or GETS statement is used, only the bytes in the file for the length of the specified record are locked.
On OpenVMS, the blocks encompassing the record plus the record terminator are locked when the READ or READS statement is used. When a GET or GETS statement is used, the blocks encompassing the bytes in the file for the length of the specified record are locked. If the BUFSIZ qualifier is specified in the OPEN statement, the number of locked blocks may be greater.
