WRITE

Write Data to I/O Channel

This directive is used to output data from the specified variables to a terminal, printer, or file, but its primary use is for files.

Syntax

WRITE [(channel [,I/O-opts] [,OPT="LOCK"])] [,variable-list [:mask]]
[,IOL=line-ref]

WRITE RECORD [(channel [,I/O-opts] [,OPT="LOCK"])] string-variable

channel: is an integer in the range of 0 to 32764 indicating the channel of an OPEN file or device. If omitted, 0 is the default.
I/O-opts: is one or more of the following specifiers:
Branching: ERR=line-ref DOM=line-ref END=line-ref
Record: IND=numeric-value KEY=string-value
Miscellaneous: TBL=line-ref ERC=error-code
variable-list: is a list of numeric or string variables that contain values to be output.
:mask: is any string containing a mask to format numeric values for output. Please refer to the Data Representation chapter in Volume I for a detailed discussion of all the masking characters. All numeric data must be masked before output; string data format is the only valid format for output. If not specified, the default mask is 0.
line-ref: (IOL) specifies a program line number or label containing an IOLIST that defines a variable list to be output. If both variable-list and IOL=line-ref are used, the variable-list is output first, followed by the variables named in the IOLIST directive at line-ref.
string-variable: is any string variable name whose full contents are output.

Remarks

Starting with release level 8.2, a format may be specified to be the source of data for the directive.

The default for the channel is 0, the terminal.

The attempt to reference a format name that the data dictionary or the current program does not recognize results in an ERR=161.

I/O options include:

ERR=: specifies the program line number or label to branch to if an error is produced by this directive.
DOM=: specifies the program line number or label to branch to if an attempt is made to output a record using KEY= and an ERR=11 results.
END=: specifies the program line number or label to branch to if this WRITE senses the end of the file (ERR=2) when attempting to output to a fixed length file. END= takes precedence over ERR= in the same WRITE directive.
TBL=: specifies the program line number or label of a TABLE directive to use for code conversion for outgoing data (see TABLE directive).
IND=: specifies the index number of the record to receive this output (IND= is zero-based).
KEY=: specifies the key value of the record to receive this output (ignored for WRITE to MSORT and TISAM files)
ERC=: specifies a programmer-defined error code, which enables programmers to define and manage errors without branching. ERC= provides a structured programming alternative to ERR=.

The IND= and KEY= options are mutually exclusive in the same WRITE directive.

Values from the variable list or IOLIST are output to the file or device in sequential order. The first data variable appears first in the output record.

The RECORD modifier is used to allow an entire record, including delimiting characters, to be output as data from a single variable.

If a file is specified as the output form, the records are accessed in sequential order by key value for DIRECT and SORT files or index value for INDEXED files unless the IND or KEY options are used. After this directive is executed, the record pointer is advanced to indicate the next sequential record.

A WRITE to a SORT file only establishes the key value of the record and advances the pointer to the next sequential record.

If a mask is used to format a numeric variable, that variable is written to the file (or device) in string form. In a subsequent READ of the record containing that variable, a string variable must be used to receive the formatted data.

You can write to a DIRECT or INDEXED file without specifying the key or index values by extracting the record first. (An EXTRACT/ WRITE sequence processes the file in sequential order without the necessity of specifying Key or Index values. The WRITE updates the record pointer.)

If the DOM=branch parameter is specified, an attempt to WRITE a record to a file whose primary key or Unique-mode secondary key is not unique results in an ERR=11 (Duplicate Key).

Starting with release 8.3.0, an attempt to reference a format or data name in the I/O list of a channel that was OPENed with OPT=“LINK” results in an ERR=172.

Starting with release 8.3.1, the OPT=“LOCK” option enables you to leave a record extracted after it is updated. Previously, you had to write a directive sequence such as WRITE(channel,KEY=K$) REC$; EXTRACT(channel, KEY=K$). Now you can use a directive such as WRITE(channel, KEY=K$, OPT=“LOCK”).

For information on how to use the WRITE RECORD directive to provide information to a DDE server or execute a command on a DDE server when you use the Thoroughbred Environment under Microsoft Windows, please refer to the description of the OPEN directive.

Examples

WRITE (1) A$, A

accesses the current record in the file OPEN on channel 1 and transfers data from the first variable A$ into the first field of the record and from the variable A into the second field. The record pointer is updated to the next sequential record.

WRITE RECORD (1) B$

has the same effect as the first example, but transfers all of the data in the variable, including delimiting characters, into the current record of the file.

WRITE RECORD (1, IND = X, ERR = 7999) B$

If X = 56, has the same effect as the previous example, but accesses the record having the index number 56 and branches to statement 7999 if the directive produces an error.

WRITE (1, KEY = I$, END = 7500) IOL = 5000

If I$ = “ASD#123” and statement 5000 is IOLIST A$, A, this statement accesses the record with the key value “ ASD#123 “ and branches to statement 7500 if the end of the file is reached.

WRITE (1,KEY=K$)#DNFFMT

writes a record out of the contents of the data area of the format name “DNFFMT” into an OPENed file.

WRITE

Syntax

Remarks

Examples

See also