@WRITE (format 1) - Write file

The @WRITE statement (format 1) creates a new file and writes the content of the current work file to the new file, overwrites an existing file with the content of the current work file or writes the content of the current work file back to a file opened using @OPEN (format 1). An open file remains open when @WRITE is issued. If existing files are overwritten then the old file content is completely replaced. The work file is retained in all cases.

Whenever this section refers to a “file”, this can be a SAM file, an ISAM file, a library element or a POSIX file.

Operation	Operands	F mode, L mode
@WRITE	[ {  LIBRARY=path1 ( [ELEMENT=] elname [(vers)] [,eltype] )      ELEMENT=elname [(vers)] [,eltype]      FILE={ path2 | *linkname } [,TYPE={ ISAM |  SAM  } ] [,KEY={LINENUMBER |  DATA } ]      POSIX-FILE=xpath } ]     [,MODE={  ANY  |  UPDATE |  NEW |  REPLACE } ] [,CODE={ name |  *FILE |  *EDT } ]

LIBRARY=...	A library element is to be overwritten. This is defined by explicitly specifying the library name and the element designation.
path1 elname vers	Name of the library. Name of the element. Version of the required element (see the LMS User Guide [14]). If vers is not specified or if *STD is specified then the highest available version of the element is selected.
eltype	Type of element. Permitted type specifications are S,M, P, J, D, X, *STD as well as freely selectable type names having one of these types as basic type. If eltype is not specified then the default type specified with @PAR ELEMENT-TYPE is used. The permitted element types and their meanings are described in chapter “File processing”.
ELEMENT=...	A library element is to be written. This is defined by means of the element designation without any library name specification. The default library set with @PAR LIBRARY is used implicitly (if @PAR LIBRARY has been specified, otherwise the error message EDT5181 is issued). The operands elname, vers and eltype have the same meaning as when a library is specified explicitly (see above).
FILE= path2	A BS2000 file is to be written. Name of the BS2000 file (fully qualified file name) that is to be written.
*linkname	File link name of the BS2000 file that is to be written. The file name and the file attributes are stored in the Task File Table. In this way, it is possible to create files with nonstandard names. The file link name must not be specified as the special file name *BY-PROGRAM. This results in the error EDT4923. If no file link name is defined then the statement is rejected with the message EDT5480. If the file link name is declared as the special file name *DUMMY then it is treated as an non-existent file. However, no file is created.
TYPE=	Specifies the access method when creating a new file. In the case of existing files, this operand is ignored.
SAM ISAM KEY=	A SAM file is created and written. This is the default value. An ISAM file is created and written. In the case of ISAM files, specifies how the ISAM key is to be formed. In the case of other file types, this operand is ignored. If the operand is not specified then the ISAM key is formed from the line number when a new file is written or when an existing file is overwritten. When data is written back to an open file, the ISAM key is formed from the line number if KEY=LINENUMBER or KEY=IGNORE was specified when the file was opened. If KEY=DATA was specified when the file was opened then the ISAM key is taken over from the data area.
LINENUMBER
	The ISAM key is formed from the line number. If the position of the key differs from the default value or if the key is too long, the message EDT5465 is output and the file is not written. If the key is too short, the line number is truncated from the left.
DATA	The ISAM key is a component of the data range in the work file. In this case, the user must make sure that the sequence of work file records corresponds to the sequence of ISAM keys as otherwise the write operation will be rejected with the message EDT4208 (DMS error code 0AAB).
POSIX-FILE=	A POSIX file is to be written.
xpath	Path name of the POSIX file that is to be written. The xpath operand can also be specified as a string variable. It must be specified as a string variable if the path name contains characters which have a special meaning in EDT syntax (e.g. blanks, semicolons in F mode or commas).
MODE=	Specifies whether the file should already be present. If an open file is to be written back, this operand is ignored.
ANY	If the file already exists then it is overwritten. Otherwise, it is created and written. This is the default value.
UPDATE	The file that is to written must already be present as otherwise the message EDT5281, EDT5270 or EDT5310 is output depending on the file type. The old content is completely overwritten.
NEW	The file is created and written. It must not already be present as otherwise the message EDT5258, EDT5273 or EDT5311 is output depending on the file type.
REPLACE	Has the same meaning as ANY. If the file already exists then it is overwritten. Otherwise, it is created and written.
CODE=	The operand controls the character set in which the work file is to be written. If this operand is not specified then the character set defined with @PAR CODE is used for POSIX files and the work file's character set is used for other files. If in the case of SAM files, ISAM files or library elements, the character set of an existing file differs from that of the work file then the message EDT5457 is output in batch mode and no write operation is performed. In interactive mode, the following query is output: % EDT0915 CONVERT TO FILE CCS (&00)? REPLY (Y=YES; N=NO)? If the user responds Y then a conversion to the file's character set is performed before the write operation. If the user responds N then the work file's character set is used.
name	Character set that is to be used for writing. The name of a valid character set must be specified for name (see section “Character sets”).
*FILE	Before the write operation, the work file is converted into the character set of the existing SAM file, ISAM file or library element or into the character set used when opening a POSIX file. If this character set was *NONE then EDF03IRV is used. If the file does not yet exist or if an existing POSIX file is to be overwritten then the message EDT1181 is output and the CODE operand is ignored. System behavior is then the same as when the CODE operand is omitted.
*EDT	The work file's character set is used for writing irrespective of whether any file that may exist has a different character set.

When new files are written or when existing files are overwritten, it is always necessary to specify a file name operand. When files opened with @OPEN are written back, the file name operand can be omitted. If the file name operand is omitted even though no file is open then the statement is rejected with the message EDT5122. If all the statement's operands are omitted and no file is open then the statement is interpreted as @WRITE (format 2) and a @FILE entry is searched for (see @WRITE format 2).

If the specified file cannot be accessed as required then the statement is rejected with a corresponding error message.

After the write operation, the employed character set is entered in the catalog for SAM files, ISAM files and library elements. If this character set is EDF03IRV and the file that is to be written already exists with the character set *NONE in the catalog then this value is retained.

If the work file is converted before writing and if it contains characters which are invalid in the character set used by 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 error message EDT5453 is output. The user can then define a substitute character or modify the character set for writing and run @WRITE again.

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, during the processing of an opened ISAM file, the character set is changed either from or to UTF16 or if this occurs implicitly due to a corresponding specification in the CODE operand a file opened with @OPEN cannot be written back since this would modify the length of the key field. In this case, the @WRITE statement is rejected with the error message EDT5468.

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.

Caution

Since the default setting is MODE=ANY, existing files are overwritten without any warning being issued.

Example

@WRITE LIBRARY=PROGLIB(ELEMENT=SYNT)

The current work file is written to the element SYNT in the library PROGLIB. In this case, the highest possible version and the default type specified with @PAR ELEMENT-TYPE are used.

@PAR LIBRARY=LIB1
@SET #S02='PROC.PR'
@WRITE ELEMENT=.#S02 (V01),J

The current work file is written to the element with the name PROC.PR, the version V01 and the element type J in the library LIB1.

@WRITE FILE=FILE2,MODE=NEW,CODE=*EDT

The SAM file FILE2 is created and the current work file is written to the new file. The work file's character set is used.

@OPEN POSIX-FILE=/home/user1/test/data,CODE=UTF8

@WRITE ,MODE=ANY

The current work file is written back to the open POSIX file data in the directory /home/user1/test.