TEXT

Define System TEXT File

This directive is used to create a new, character-oriented, flat file that is structurally compatible with system text files. There is no record concept and, therefore, no ability to EXTRACT a record. Access may still be controlled by using the LOCK directive on the entire file. Access to the file is based on starting byte (specified by IND= I/O option) and length. IND= is zero-based and has a maximum value of 8388605, limiting the maximum addressable starting byte of a Thoroughbred TEXT file READ or WRITE to 8388605.

Syntax

TEXT file-name [,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.
disk-num: specifies the logical disk directory that contains this file. Valid values are 0 through 35. If omitted, 0 is used.
sector-num: is 0 or any positive integer. This field is ignored.
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

This directive is generally available starting with release level 8.1.

This directive creates an empty file. The file does not contain any information about how it was created, how it may be used, record size limitations, or file growth limitations.

When a TEXT file is OPENed, there is no header information to tell Thoroughbred Basic about the file. This file type is treated as a SYSTEM file with a blocking factor (ISZ=) of 512. An additional I/O option has been added to the OPEN directive to avoid the possibility of raw data in the file being interpreted as a Thoroughbred Basic file header. This I/O option is “OPT=”. If the OPEN directive contains the I/O option OPT=“TEXT”, then Thoroughbred Basic treats this file as a TEXT file type.

When READing a TEXT file, the IND= I/O option specifies the starting byte in the file for the read (zero-based) and the SIZ= I/O option specifies the number of bytes to READ. The actual READ is terminated by an End of File (ERR=02), the first occurrence of the SIZ= I/O option value, a Thoroughbred Basic field separator character ($8A$), a line feed character ($0A$), a carriage return character ($0D$), the combination of one line feed and one carriage return ($0A0D$), or the combination of one carriage return and one line feed ($0D0A$). The returned data does not contain any Thoroughbred Basic field separator characters ($8A$), line feed characters ($0A$), or carriage return characters ($0D$). A READ that is terminated by an end of file (ERR=02) returns no data. If the SIZ=I/O option is omitted, the maximum string size is assumed: under Thoroughbred Basic 8.3.0, the maximum string size is 32600; for Thoroughbred Basic 8.3.1, the maximum string size is 65000.

A READ RECORD directive is terminated only by an end of file (ERR=02) or when the SIZ= I/O option value is reached. Any Thoroughbred Basic field separator characters ($8A$), line feed characters ($0A$), or carriage return characters ($0D$) appears in the data that is READ. A READ RECORD that is terminated by an end of file (ERR=02) returns no data.

When WRITEing a TEXT file, the physical length of the data specifies the length of the written string, and the IND= I/O option specifies the starting byte of the file for the write (zero-based). The actual written string contains a line terminator (e.g., $0A$ in UNIX,
$0D0A$ in Microsoft Windows) after each named variable or string constant in the WRITE directive (including the last named variable or string constant).

A WRITE RECORD directive simply writes the named variable or string constant to the file starting at the current position or the position specified by the IND= I/O option for the number of bytes contained in the resultant string.

Since there are no records in a TEXT file, the [P]EXTRACT [RECORD] directive does not prohibit access to any data in the file. Instead, it performs as if it was a [P]READ [RECORD] directive, and generates no error when EXTRACTing from a TEXT file. The LOCK directive does, however, prohibit access to the entire file in the same fashion as all other Thoroughbred Basic files.

The FID function for a TEXT file returns the file name and a file type of $03$. All other fields in the returned string from the FID function are unused.

The INITFILE directive does not support TEXT files.

The FILE directive supports TEXT files, but requires that the XFD function string be used (not the FID function).

Examples

TEXT "TEST",0,0

creates an empty file named TEST on logical disk directory number 0 starting at a sector allocated by the operating system. Note that no file size is specified since the only limiting factor is the operating system and/or physical disk space.

TEXT

Syntax

Remarks

Examples

See also