Fields, Records, and I/O Lists

Regardless of the type of file or device, the PRO/5 concepts of fields, records, and I/O lists apply uniformly.

Fields

A field is a string of bytes ending with a field terminator. The recognized field terminators are: $00$ (null), $0A$ (linefeed), $0D$ (carriage return), $1C$, $1D$, $1E$, and $1F$ (these terminators may be modified using the STBL() command). A field may be returned to either a string variable or numeric variable (numeric fields are written in ASCII). When reading fields from a record-oriented file, fields are scanned until the end of the record is reached. If the desired fields are all scanned before the end of the record, then the remainder of the record is ignored. When reading fields from a byte-oriented file, characters coming in from the file are scanned only until the desired fields have been read. The SIZ= option in a READ may be used to specify the maximum length of a field. If this maximum length is read before a terminator is encountered, the field up to that point is returned. The next field begins with the next character. A LEN= option (as in READ (1,LEN=10)) may be used and works like SIZ= except that the next field will begin following the next terminator. In effect, LEN= will discard excess bytes in fields where SIZ= does not.

When writing fields, PRO/5 automatically supplies a linefeed ($0A$) as a field terminator.

Records

A record is a block of bytes with a known length. Records are read/written using the RECORD option on READ/WRITE verbs: READ RECORD or WRITE RECORD. PRO/5 will transfer the record to and from a string variable with no concern as to the content of the record. With record-oriented files PRO/5 will automatically know the length of the record. With byte-oriented files the programmer must specify the length during a READ RECORD by using the SIZ= option.

I/O Lists

An I/O list determines what data is to be written to a file or what variables are to receive data when reading from a file. A string template (see the String Templates section) would normally be used in conjunction with a READ RECORD.

When writing to a fixed length record file, the I/O list cannot specify more data than can fit in a record, otherwise an !ERROR=1 (End-of-record) error occurs. If less data is written than will fit in a record, the remainder of the record will be padded with nulls ($00$).

When writing to a variable length record file or a byte file, only the specified data is written with no padding. An end-of-record error will occur if writing more than 32767 bytes to any record-oriented file. See WRITE in the Commands Manual for more information.

When reading a record file, a single record is retrieved and the data in that record is assigned to variables in the I/O list. If the I/O list requests more data than the record provides, an end-of-record error occurs. When reading a byte file, data is read until the I/O list is satisfied. An !ERROR=2 (end-of-file) error may occur if the end of the file has been reached. See READ in the Commands Manual for more information.