@WRITE (format 2) - Write SAM file

The @WRITE statement (format 2) fully or partially writes the content of the current work file to disk or tape as a SAM file.

Operation	Operands	F mode, L mode
@WRITE	[file] [(ver)] [,] [lines[,...]] [:cols[,...]:] [KEY] [ { UPDATE | OVERWRITE } ]

file	Name of the SAM file that is to be written. The name must correspond to the SDF data type <filename 1..54> or must consist of the special specification '/'. If the file file does not yet exist then it is created prior to the write operation. If the file operand is not specified then the explicit local @FILE entry is used as the file name if present. If not, the global @FILE entry (from the @FILE statement) is used and, failing this, the implicit local @FILE entry (e.g. from the @READ statement). If there is no @FILE entry then @WRITE is rejected with the message EDT5484. If the specified file cannot be accessed as required then the statement is rejected with a corresponding error message. If the file link name EDTSAM is assigned to a file then the user simply needs to specify '/' in order to write this file (see chapter “File processing”).
ver	Version number of the file that is to be overwritten. If an incorrect version number is specified for an existing file then the statement is rejected with EDT4985. If the file does not yet exist then this specification is ignored and version 001 of the file is written.
lines	One or more line ranges that are to be written to the SAM file. If lines are specified more than once then they are also written more than once. If lines is not specified, then the entire file is written.
cols	One or more column ranges which define the section to be written for each record. The ranges may repeat and overlap. The column specifications refer to the characters in the current work file. If column values which exceed the work file record length are specified then blanks are written to the file in their place. If no column range is specified then the lines are written in full.
KEY	When the SAM file is written, every line is prefixed with an 8-character long key which is derived from the associated line number. As a result, the file can subsequently be read in using exactly the same line numbers (see @READ with the KEY operand).
UPDATE	Specifying UPDATE causes the lines that are to be saved to be appended at the end of the existing SAM file. This operand is ignored if no SAM file with the specified name exists.
OVERWRITE	An existing file of the same name is overwritten without any request for confirmation. If the specified file does not yet exist, OVERWRITE has no effect.

If neither UPDATE nor OVERWRITE is specified and if a file with the same name already exists then, in interactive mode, EDT issues the query:

% %	EDT0903 FILE 'file' IS IN THE CATALOG, FCBTYPE = fcbtyp EDT0296 OVERWRITE FILE? REPLY (Y=YES; N=NO)?

If the user answers the message with Y then the existing file is overwritten as a SAM file with the content of the current work file. In contrast, if the user answers N then the file is not written and the message EDT0293 is output.
In batch mode, the file is always overwritten.

If an existing file is overwritten by @WRITE without the UPDATE operand then the file type and/or file attributes may change. The file is written as a SAM file with default attributes (e.g. variable record length) unless a corresponding /SET-FILE-LINK command with the file link name EDTSAM has already been specified with the divergent attributes (see section “File processing”). Files of the type PAM or BTAM cannot be overwritten.

The file is only opened temporarily during the write operation.

The character set used for the write operation depends on whether the file is overwritten, created or extended (see the UPDATE operand.

If the file is overwritten or created then the data is written in the work file's character set and this character set is entered for the file in the catalog.

If the file is extended then the data is converted from the work file's character set into the character set specified in the file's catalog entry. If the value *NONE is entered for the file in the catalog then EDF03IRV is used (see also section “Character sets”).

If the work file contains characters which are invalid in the character set of the file that is to be written then these characters are replaced by a substitute character provided that such a character has been specified (see @PAR SUBSTITUTION-CHARACTER); otherwise, the file is not written and the error message EDT5453 is output. This does not apply to invalid characters outside of the line or column range that is to be written. These characters are ignored.

If the work file contains lines that are too long for the file that is to be written (e.g. if the file has a fixed record length) or if the conversion operation creates any such records (possible in the case of Unicode character sets), then the write operation is aborted with the message EDT5444.

If the statement is interrupted with [K2] and the EDT session is continued with /INFORM-PROGRAM then the processing of the statement is aborted and message EDT5501 is output.

If all the statement's operands are omitted and no file is open in the current work file then the statement is interpreted as @WRITE (format 1) and no @FILE entry is searched for (see @WRITE format 1).

Caution

If the @FILE statement has been used to prefix a file name then the statement sequence

@READ 'filename'

@WRITE

does not cause the read file to be written. Instead, the file from the @FILE entry is written.

Example

1.     A VERY SHORT FILE --------------------------------------------- (1)
2.     @WRITE 'TEST.@WRITE.1' ---------------------------------------- (2)
2.     @FILE 'TEST.@WRITE.1' ----------------------------------------- (3)
2.     @WRITE UPDATE ------------------------------------------------- (4)
2.     @DELETE ------------------------------------------------------- (5)
1.     @READ --------------------------------------------------------- (6)
3.     @PRINT
1.0000 A VERY SHORT FILE
2.0000 A VERY SHORT FILE --------------------------------------------- (7)
3.

(1)	A line is written to the work file.
(2)	This line is written to disk as the file TEST.@WRITE.1.
(3)	The file name TEST.@WRITE.1 is declared via @FILE.
(4)	@WRITE refers to the file name declared in (3). UPDATE causes the content of the work file – i.e. still the line created in (1) – to be appended at the end of the file TEST.@WRITE.1.
(5)	The content of the work file is deleted.
(6)	The file TEST.@WRITE.1 is moved into the work file (here again, there is no need to specify a file name.)
(7)	It can be seen that the line was appended at the end of the file in (4).