@COPY (format 1) - Read in a file

@COPY (format 1) is used to read an existing file in full into the current work file. The work file does not have to be empty when this is done. It is possible to specify the position in the work file at which the file is to be inserted. After being read in, the file is closed again.

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
@COPY	{  L IBRARY = path1 ([  E LEMENT = ] elname [(vers)] [,eltype])  |  E LEMENT = elname [(vers)] [,eltype]  |  F ILE = {path2 | *linkname} [, K EY = {  L INENUMBER |  D ATA |  IGNORE  } ]  |  P OSIX-FILE = xpath [, C ODE = name] } [ [,] { BEFORE |  AFTER } line ]

LIBRARY=	A library element is to be read in. 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 read in. 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 read in. Name of the BS2000 file (fully qualified file name) that is to be read in.
*linkname	File link name of the BS2000 file that is to be read in. The file name and the file attributes are stored in the Task File Table. 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 existing empty file.
KEY=	In the case of ISAM files, specifies the location at which the ISAM key is stored in the work file. In the case of other file types, this operand is ignored.
LINENUMBER
	The ISAM key is stored as a line number in the work file. Any existing lines with the same line numbers are overwritten. The operands BEFORE and AFTER may not be specified. If the ISAM key cannot be interpreted as a line number because the position of the key differs from the default value, the key is too long or the keys are not numerical then the message EDT5459 is output and the file is not read in.
DATA IGNORE	The ISAM key becomes a component of the data range in the work file. The ISAM key is not stored in the work file. This is the default value. If the position of the key differs from the default value, the message EDT5466 is output and the file is not read in.
POSIX-FILE=	A POSIX file is to be read in.
xpath	Path name of the POSIX file that is to be read into the current work file. 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).
CODE=	Defines the character set that is to be assumed for the POSIX file. Since it is not possible to assign character sets to POSIX files in the POSIX file system, a user specification is required here. If CODE is not specified then the character set defined in @PAR CODE is assumed.
name	Character set of the POSIX file that is to be read in. The name of a valid character set must be specified for name (see section “Character sets”).
EBCDIC	The keyword EBCDIC is now only supported for reasons of compatibility and is a synonym for the character set EDF041.
ISO	The keyword ISO is now only supported for reasons of compatibility and is a synonym for the character set ISO88591.
BEFORE	The file is inserted in front of the specified line in the work file. This operand may not be specified if KEY=LINENUMBER is defined.
AFTER	The file is inserted after the specified line in the work file. This operand may not be specified if KEY=LINENUMBER is defined.
line	Line number before or after which the file is inserted.

If the specified file does not exist or cannot be accessed as required or if the file cannot be read in successfully then the statement is rejected with a corresponding error message.

In neither BEFORE nor AFTER is specified and if the KEY operand is not equal to LINENUMBER then the file is inserted after the last line of the current work file.

When ISAM files are read with the operand KEY=LINENUMBER, the line numbers in the work file are derived from the file's ISAM key. In all other cases, they are formed using the procedure “Insertion between two lines” (see section “Line number assignment”).

If the current work file is empty and has the character set *NONE then it is assigned the character set of the file that is to be read in. If this character set is *NONE then the work file is assigned the character set EDF03IRV.

If the work file already has a character set then the records that are to be read in are converted from the file's character set into the work file's character set. If the file that is to be read in contains characters which cannot be displayed in the work file's character set then these are replaced by a substitute character if such a character has been specified.(see @PAR SUBSTITUTION-CHARACTER), otherwise the file is not read in and the error message EDT5453 is output.

If the file is present in a Unicode character set and contains an illegal byte sequence, e.g. surrogate characters, then it will be impossible to read it even if SUBSTITUTION-CHARACTERS is specified. In this case, the read operation is rejected with the message EDT5454.

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.

Example

@COPY LIBRARY=MACLIB(ELEMENT=XYZ,M) AFTER 12.3

The element with the name XYZ, the highest existing version and the element type M (macro) from the library MACLIB is inserted in full after line 0012.3000 in the current work file.

@PAR LIBRARY=DATA

@COPY ELEMENT=PERSONAL(@),D

The element with the name PERSONAL, the highest existing version and the element type D (text data) from the library DATA is inserted after the last line in the current work file.

@COPY FILE=FILE.ISAM,KEY=LINENUMBER

The ISAM file FILE.ISAM is read into the work file. The line numbers in the work file are formed from the ISAM key. Any existing lines are overwritten.

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

The POSIX file data in the directory /home/user1/test with the character set UTF8 is inserted after the end of the current work file. When this is done, the file is converted into the work file's character set.