Previous Topic Next topic Print topic


WRITE

Purpose

Adds a record to a STREAM OUTPUT, RECORD OUTPUT, or RECORD UPDATE file.

Syntax

WRITE FILE(f)FROM(v)[KEYFROM(k)];

Parameters

f
A reference to the file to which the record will be written.
v
A reference to the variable that contains data for the output record.
k
An expression that specifies a key position.

The FILE, FROM, and KEYFROM specifiers may be written in any order.

Description

The WRITE statement adds a record to a file, either at the end of the file having the SEQUENTIAL and OUTPUT attributes, or into a file having the KEYED and OUTPUT attributes or the KEYED and UPDATE attributes.

The variable that contains data for the output record cannot be an unaligned bit string, a structure consisting entirely of unaligned bit strings, or a structure with the UNION attribute.

If the file associated with f has been opened with the KEYED and SEQUENTIAL attributes, the KEYFROM option may be specified. If the KEYFROM option is specified, the value of the expression k serves as the key value of the new record. If a record with this key value already exists, the KEY condition is signaled.

For indexed (VSAM) files, the key value must be of type Character, Widechar, or Graphic; otherwise, it is converted to Character. If specified, the KEYFROM option must be of Character type; if not, it is converted to Character type. Its maximum length is implementation-defined.

For non-VSAM files, if the file associated with f has been opened with the KEYED and DIRECT attributes, the KEYFROM option must be specified. The value of the expression k serves as the record number of the new record. If a record with this record number already exists, the KEY condition is signaled.

If a KEYFROM option is given, the file must have been previously opened with the KEYED attribute. The presence of the KEYFROM option does not supply the KEYED attribute in an implicit file opening.

The FILE option must contain a reference f that produces a file value. The file associated with f must either have been previously opened with RECORD OUTPUT, or it must be closed. If closed, it is opened by the WRITE statement and given the OUTPUT RECORD SEQUENTIAL attributes.

Open PL/I allows the use of WRITE with a stream file, as long as the WRITE statement specifies a scalar character varying string variable in its FROM option. The WRITE statement does an implicit SKIP and then writes a line consisting of the current value of the varying string specified by the FROM option followed by a new-line character.

Example

WRITE FILE(F) FROM(CUSTOMER) KEYFROM(N+1); 
DECLARE 1 CUSTOMER,
      2 NAME CHAR(20) VARYING,
      2 ADDRESS
            3 NUMBER FIXED BINARY(15), 
            3 STREET CHAR(12) VARYING, 
            3 CITY CHAR(20) VARYING;
DECLARE F FILE;
   .
   .
   .

Restrictions

For DIRECT and KEYED SEQUENTIAL files the first WRITE that is performed on the file sets the default record size. This means that if a small record is the first record written to a file, subsequent WRITEs of large records could cause errors to occur. For example:

DECLARE F1 FILE,
      RECORD_ONE CHAR(5),
      RECORD_TWO CHAR(6);

OPEN FILE(F1) RECORD DIRECT OUTPUT;
WRITE FILE(F1) FROM(RECORD_ONE) KEYFROM(1);
WRITE FILE(F1) FROM(RECORD_TWO) KEYFROM(2);

In the previous program the first WRITE will cause the default record size to be set to 5. Since the second WRITE is of a value greater than 5, an ERROR will be signaled. This restriction does not apply if the file is opened with the -DAM switch in the TITLE option to specify the record size in the file. For example, the program fragment in the above example would have worked correctly if the OPEN statement had read:

OPEN FILE(F1) TITLE('TESTFILE -DAM 10') RECORD DIRECT OUTPUT;

This would have set the default record size to 10 and the WRITE of both the CHAR (5) and CHAR ( 6 ) would have worked correctly.

Previous Topic Next topic Print topic