SERIAL

Define SERIAL File

This directive is used to create a new, variable record length, sequential access file in a logical disk directory.

Syntax

SERIAL file-name, num-records, record-size, disk-num, sector-num
[,ERR=line-ref|,ERC=error-code]

file-name: is any string of 8 characters or fewer used to name this file.
num-records: is an integer in the range of 1 to 16,777,215 indicating the maximum number of records to be contained in this file.
record-size: is an integer in the range of 0 to 32767 indicating the average number of bytes in each record in this file.
disk-num: specifies the logical disk directory that contains this file. Valid values are 0 through 35.
sector-num: is the number 0 (zero). Each operating system allocates where the file is stored. Refer to your documentation for additional options.
line-ref: is the program line number or label to branch to if this directive produces an error.
error-code: is a programmer-defined error code. Valid values are positive or negative whole numbers.

Remarks

If an integer range is exceeded, an ERR=41 results.

If a file-name of more than eight characters (operating system-dependent) is specified, an ERR=10 results.

All valid values for sector-num are treated as 0, but syntax requires sector-num to be specified.

File-name must be unique in the execution environment. An attempt to define a file using the same name as another file that is already defined on an available logical disk directory results in an ERR=12.

File-name may contain any ASCII characters, unprintable as well as printable. Avoid using characters which have special meaning in different operating system environments (e.g. “*” in UNIX and Microsoft Windows, “/” in UNIX, “#” and “\” in Microsoft Windows, and so on).

To avoid confusion do not use device or task names as file names. For example, do not use T0 - T9, TA - TZ, Ta - Tz, D0 - Dz, LP, P0 - Pz, G0 - Gz, Co - Cz. In general, most device and task names use two-character names. The simplest approach is to not use two-character file-names.

A SERIAL file must be LOCKed in order to write to it.

All records written to a SERIAL file are appended at the end of the file unless the file is ERASEd or cleared with an INITFILE directive first.

SERIAL files contain variable-length records that can only be accessed sequentially or with the use of the IND= I/O option on READ.

SERIAL files are typically used for spooling operations.

If the IND= I/O option is used in a WRITE to a SERIAL file, Thoroughbred Basic ignores it.

Examples

SERIAL "LIBR", 100, 50, 4, 0

creates a SERIAL file with slightly more than 5000 bytes of storage space (100 records averaging 50 bytes each) on logical disk directory number 4 starting at a sector number to be assigned by the operating system.

SERIAL "ACCTFILE", 4, 4, 2, 0, ERR=7999

creates a SERIAL file on logical disk directory number 2 at a location allocated by the system and, if an error occurs, branches to statement number 7999.

SERIAL

Syntax

Remarks

Examples

See also