WRITE (Create New Records)

Free-Form Syntax WRITE{(E)} name {data-structure}
Code Factor 1 Factor 2 Result Field Indicators
WRITE (E)   name (file or record format) data-structure _ ER EOF

The WRITE operation writes a new record to a file.

The name operand must be the name of a program-described file or a record format from an externally-described file.

If the data-structure operand is specified, the record is written directly from the data structure to the file. If name refers to a program described file, the data structure is required and can be any data structure of the same length as the file's declared record length. If name refers to a record format from an externally described file, the data structure must be a data structure defined with type EXTNAME(...:*OUTPUT or *ALL) or LIKEREC(...:*OUTPUT or *ALL). For a DISK file, if the data structure is defined with LIKEREC and the type of fields is not specified, the data structure can be used for a WRITE operation if the output buffer layout exactly matches the input buffer layout. See Figure 2 for an example. See File Operations for information on how to define the data structure and how data is transferred between the file and the data structure.

To handle WRITE exceptions (file status codes greater than 1000), either the operation code extender 'E' or an error indicator ER can be specified, but not both. An error occurs if overflow is reached to an externally described print file and no overflow indicator has been specified on the File description specification. For more information on error handling, see File Exception/Errors.

You can specify an indicator in positions 75-76 to signal whether an end of file occurred (subfile is filled) on the WRITE operation. The indicator is set on (an EOF condition) or off every time the WRITE operation is performed. This information can also be obtained from the %EOF built-in function, which returns '1' if an EOF condition occurs and '0' otherwise.

When using the WRITE operation remember:
  • When name is a record format name, the current values in the program for all the fields in the record definition are used to construct the record.
  • When records that use relative record numbers are written to a file, you must update the field name specified on the RECNO File specification keyword (relative record number), so it contains the relative record number of the record to be written.
  • When you use the WRITE operation to add records to an input-capable or update-capable DISK file (see the USAGE keyword for a free-form file definition or position 17 for a fixed-form file definition), you must also define the file so that it is output-capable (specify *OUTPUT for the USAGE keyword of a free-form definition or specify an A in position 20 of the file description specifications.
  • Device dependent functions are limited. For example, if a "WRITE" is issued to a "PRINTER" device, the space after will be set to 1 if the keyword PRTCTL is not specified on the file specification (normally spacing or skipping information are specified in columns 41 through 51 of the output specifications). If the file is externally described, these functions are part of the external description.
  • For a multiple device file, data is written to the program device named in the field name specified with the DEVID keyword on the file description specifications. (See DEVID(fieldname).) If the DEVID keyword is not specified, data is written to the program device for which the last successful input operation was processed.

See Database Null Value Support for information on adding records with null-capable fields containing null values.

For more information, see File Operations.

Figure 1. WRITE Operation with a Program Described File
*...1....+....2....+....3....+....4....+....5....+....6....+....7...+....
CL0N01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq....
 *
 *  The WRITE operation writes the fields in the data structure
 *  DS1 to the file, FILE1.
 *
C                   WRITE     FILE1         DS1
Figure 2. WRITE Operation for a DISK file with LIKEREC Data Structures

    dcl-f FILE1 DISK USAGE(*OUTPUT);

    dcl-ds likerec_default LIKEREC(FMT1);
    dcl-ds likerec_output LIKEREC(FMT1 : *OUTPUT);
    dcl-ds likerec_all LIKEREC(FMT1 : *ALL);

    WRITE FMT1 likerec_default;
    WRITE FMT1 likerec_output;
    WRITE FMT1 likerec_all;