Synergy relative files are used to access records by relative record number. The physical file format varies slightly on each operating system.
On Windows and UNIX, Synergy DBMS accesses records in relative files. Binary data can be in the records because all records are assumed to be of the same length followed by the record terminator, so the data is not scanned for the end of the record. If the record terminator is not found in the correct location, an “Invalid relative record” error ($ERR_RELREC) is generated. The record size can be specified either by the destination size on the first I/O statement or by the RECSIZ qualifier on the OPEN statement.
On OpenVMS, the RMS file system is used for native compatibility. Binary data can be in the records because RMS knows the length of each record and does not depend on the record terminator to separate each record. When the file is opened, the record length is automatically retrieved. If the RECSIZ is specified, the value is compared against the actual record size and the error generated is IRCSIZ if they do not match.
To support terabyte relative files, both the operating system and file system must be 64 bit.
Relative file structure
On Windows and UNIX, a relative file consists of a byte stream where the records all contain the same number of bytes followed by the record terminator. On Windows, the record terminator is a CR-LF (carriage return and line feed) byte pair. On UNIX, the record terminator is a single LF (line 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 record terminator to determine the byte offset from the beginning of the file.
On OpenVMS, a relative file is a specific RMS file type. Each record consists of only the data without record terminators. Each record is accessed by a record number index that ranges from 1 through 2147483647.
Relative file types
On Windows and UNIX, there is only one file type where all of the records are the same length.
On OpenVMS, relative files can either contain fixed-length records or variable-length records depending on how the record format for the file was specified when it was created. The maximum size for fixed-length records in a relative file is 32,255 bytes. The maximum size for variable-length records is 32,253 bytes. For VFC (variable-length with fixed-length control field) records, the maximum size is 32,253 bytes minus the size of the fixed-length control field, which may be up to 255 bytes long. The RECTYPE qualifier of the OPEN statement is used to specify the record format.
To create a relative file, specify the mode as O:R or A:R in the OPEN statement. To open an existing relative file, specify the mode as I:R, U:R, or A:R in the OPEN statement. The record size can be specified in the OPEN statement using the RECSIZ qualifier. On OpenVMS, the record size is stored in the file header, so if RECSIZ is specified, the record size is compared against the RECSIZ value. If the RECSIZ qualifier is not specified on Windows or UNIX, the record size is determined by the size of the destination area on the first I/O operation. If the RECSIZ qualifier is specified as -1 on Windows or UNIX, the record size is determined by the size of the first record in the file.
Record access
Records are accessed randomly by specifying the record number as a numeric field in the key field of READ, FIND, and WRITE statements, or sequentially using the READS or WRITES statements.
Relative record input and output statements
This section lists the primary input and output statements and describes how their use affects relative files. System-specific differences are also listed. See Synergy DBL Statements for more information about other statement qualifiers that are not specific to relative 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 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.
On Windows or UNIX, a READ of an unwritten record returns data of indeterminate contents. If the record terminator is not found in the file at the end of the fixed number of bytes, an “Invalid relative record” error ($ERR_RELREC) is generated.
On OpenVMS, a READ of an unwritten record results in a “Record not found” error ($ERR_RNF).
FIND statement
find(channel, record, record_number)
The FIND statement positions to the record specified by record_number. To specify positioning to the first or last record in the file, replace the record number with ^FIRST or ^LAST, respectively. To specify positioning to the beginning of the file (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.
On Windows or UNIX, a FIND to an unwritten record proceeds without error, as positioning in the file is all that occurs.
On OpenVMS, a FIND to an unwritten record results in a “Record not found” error ($ERR_RNF).
WRITE statement
write(channel, record, record_number)
The WRITE statement updates a record in the file or adds the specified record to the file. 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.
On Windows or UNIX, if a WRITE statement specifies a record number beyond the last record written to the file when it was opened in append or output mode, the file is extended by the size required to include the unwritten records. The contents of these unwritten records are undefined.
On OpenVMS, if a WRITE statement specifies a record number beyond the last record written to the file when it was opened in append or output mode, the specified record is written to the file, and the unwritten records between the previous last record and the record just written are left as “holes” in the file.
READS statement
reads(channel, record, eof_label [, DIRECTION=Q_REVERSE])
The READS statement retrieves the record that is sequentially next in the file. When DIRECTION=Q_REVERSE is specified, the previous sequential record is retrieved.
On Windows or UNIX, a READS of an unwritten record returns data of indeterminate contents. If the record terminator is not found in the file at the end of the fixed number of bytes, an “Invalid relative record” error ($ERR_RELREC) is generated.
On OpenVMS, a READS statement skips unwritten records and retrieves the next record in the file without error.
WRITES statement
writes(channel, record)
The WRITES statement updates the record that is sequentially next in the file. If the file is opened in append or output mode, the operation adds the next sequential record to the file.
DELETE statement
delete(channel)
The DELETE statement is only available for use on relative files on OpenVMS, because RMS allows “holes” of unwritten records to exist in relative files.
UNLOCK statement
unlock channel[, RFA:match_rfa]
The UNLOCK statement unlocks any records that have automatic locks. If RFA:match_rfa is specified, the specified record with the manual lock is the only record unlocked. The RFA:match_rfa qualifier is ignored on Windows and UNIX.
%RSIZE function
size = %rsize
The %RSIZE (or %RDLEN) function returns the size of the last record read, excluding 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
When a relative file is opened in update or output mode, record locking is in effect by default unless the LOCK:Q_NO_LOCK option is specified on the OPEN statement. The FIND, READ, and READS statements unlock any previously locked record. READ and READS also lock the specified record.
