@OPEN (format 1) - Open and read a file

@OPEN (format 1) is used to open an existing file and read it into the current work file or to create a file and open it for processing.

The work file must be empty and a SAM file, ISAM file or library element must not already be open in another work file. The file remains open until it is closed with @CLOSE.

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
@OPEN	{ LIBRARY=path1([ELEMENT=] elname [(vers)] [,eltype]) |   ELEMENT=elname [(vers)] [,eltype] |   FILE={path2 | *linkname}[,TYPE={ISAM | SAM | CATA-}] [,KEY={ LINENUMBER | DATA | IGNORE}] |   POSIX-FILE=xpath [,CODE=name]} [,MODE={ ANY | UPDATE | NEW | REPLACE}]

LIBRARY=	A library element is to be opened and 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 opened and 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 opened and read in. Name of the BS2000 file (fully qualified file name) that is to be opened.
*linkname	File link name of the BS2000 file that is to be opened and read in. The file 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 a nonexistent file. However, no file is created.
TYPE= SAM	Specifies the access method for the BS2000 file. If the file does not yet exist then a SAM file is created, otherwise the specification is ignored. This is the default value when a new file is created.
ISAM	If the file does not yet exist then an ISAM file is created, otherwise the specification is ignored.
CATALOG	If the file already exists then the attributes are taken over from the category entry, otherwise the message EDT5281 is output. The access method is determined on the basis of the FCBTYPE attribute in the catalog entry. This is the default value for existing files.
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. This is the default value. 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 opened.
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. 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 opened.
xpath	Path name of the POSIX file that is to be opened. 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.
MODE= ANY	Specifies whether the file should already be present. If the file already exists then it is opened for processing and read in. Otherwise, it is created and opened for processing. This is the default value.
UPDATE	The file that is to be opened and read in for processing must already exist or must be linked to *DUMMY via the file link name. Otherwise, the message EDT5281, EDT5284 or EDT5310 is output depending on the file type.
NEW	The file is created and opened for processing. It must not already be present as otherwise the message EDT5258, EDT5273 or EDT5311 is output depending on the file type.
REPLACE	If the file already exists then it is opened for processing. However, its previous content is deleted and is not read into the work file. Otherwise, it is created and opened for processing.

If the current work file is not empty or a file is already open in it then the statement is rejected with the message EDT5191 or EDT5180.

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

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 “insert between two lines” (see section “Line number assignment”).

If the empty work file has the character set *NONE when an existing file is read in then the work file 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 EDF003IRV.

If the empty work file already has a character set when an existing file is opened (e.g. due to a preceding @CODENAME statement) 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 characters are replaced by a substitute character provided that 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

@OPEN LIBRARY=PROGLIB(ELEMENT=TEST)

The element TEST in the library PROGLIB is opened and read into the current work file. In this case, the highest available version and the default type specified with @PAR ELEMENT-TYPE are used. The work file must first be empty.

@PAR LIBRARY=LIB1
@SET #S01='PROC.EX'
@OPEN ELEMENT=.#S01(V01),J

The element with the name PROC.EX, the version V01 and the element type J (procedure) from the library LIB1 is opened and read into the current work file.

@OPEN FILE=FILE1,TYPE=ISAM,MODE=NEW

The ISAM file FILE1 is created and opened. The line numbers in the work file represent the ISAM key.

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

The POSIX file data in the directory /home/user1/test with the character set UTF8 is opened and read into the current work file.