WRITE (Create New Records)

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 (identified by an F in position 22 of the file description specification), 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 EXTNAME(...:*OUTPUT) or LIKEREC(...:*OUTPUT). 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 a DISK file, you must specify an A in position 20 of the file description specifications. (See Position 20 (File Addition).)
• 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.

*...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