300
SERIAL Directive
Create a Sequential File
Format
SERIAL filename$[,max_recs[,rec_size]][,ERR=stmtref]
Where:
filename$
String variable that defines the name of the serial (sequential) file to create.
rec_size
Maximum size of the data portion of the record. (Optional on most
operating systems.) Numeric expression.
max_recs
Estimated number of records the file is to contain. The default is no initial
allocation of file space, with no limit as to final size. (Not used in most
operating system implementations.) Numeric expression.
stmtref
Program line number or label to transfer control to.
Description
When you use the SERIAL directive to create a serial (sequential or flat) file, ProvideX
creates a standard text data file in a format the operating system can access directly. The
record size is "for documentation purposes only" on most operating systems. If you do
specify the size, make it large enough to hold all the data fields written to the file for each
record. If a file of the name you use already exists, ProvideX returns an Error #12:
File does not exist (or already exists).
Record Access Mode and Binary Access Mode
In record access mode, a serial file is read a line or record at a time. Each line is
determined by the presence of end-of-line-character(s) which are different based on
the OS. On UNIX (or similar OS's) the end-of-line character is the line feed ($0A$),
on Microsoft Windows it is a carriage return followed by a line feed ($0D0A$).
Each READ or READ RECORD will only read 1 line. When using a standard READ
directive READ each line will be parsed by any field SEP's that exist within the line
and the corresponding variables within the READ will be set. If you use a READ
RECORD then the field SEP's will not be parsed and the variable on the directive will
receive the complete lines data.
When you OPEN a serial file in record access mode, there are 2 logical file pointers in
the file. The read pointer starts at the top of the file, and the write pointer starts at
the bottom; therefore, reads return the data starting from the first record whereas
writes automatically append to the end of the file.
You can move both file pointers by issuing a READ or WRITE and supplying an
IND= clause (IND=0 is the first record, IND=1 is second, etc.)
When a file is opened in binary access mode, you can read and write byte by byte
with no regard for the data contents. The data on the file is logically parsed into
records each of whose size is based on the ISZ= in an OPEN clause. For example,
OPEN(chan,ISZ=1) sets binary access mode with the contents of the file being
considered a series of 1-byte records. An OPEN(chan,ISZ=512) sets binary mode
with a series of 512-byte records.