OPEN - Open file

Macro type: type R

Every file has to be opened with the OPEN macro before it can be processed. The default value for the OPEN macro is defined in the OPEN operand of the FCB or FILE macro (via the TFT); if no OPEN mode is specified in these macros, the default value is OPEN=INPUT.

Format

Operation	Operands
OPEN	fcbadr / (1) ,mode / (0) [,PARMOD = 24 / 31]

Operand descriptions

fcbaddr

Address of the FCB for the file to be opened.

(1)
The address of the FCB is stored in register 1.

mode

OPEN processing mode (see first column of table below).

(0)
The OPEN mode is stored in coded form in the least significant byte of register 0. The following table shows the various OPEN modes and the associated codes.

OPEN mode	Code	Meaning
not specified	X'00'	The OPEN mode specified in the TU FCB has priority. If this is also X'00' , an error message is displayed.
INPUT	X'01'	The file is opened as an input file and only read operations are permitted; the file is read “forwards” (from beginning of file -> end of file).
REVERSE	X'02'	The file is opened as an input file and only read operations are permitted; the file is read “backwards” (from end of file -> beginning of file).
OUTPUT	X'04'	The file is opened as an output file and, if it already exists, overwritten from the beginning; only sequential write operations are permitted.
EXTEND	X'08'	The file is opened as an output file for sequential extension; starting at a defined point in the file, only sequential write operations are permitted. In the case of an empty file, OPEN EXTEND is mapped onto OPEN OUTPUT.
UPDATE	X'10'	The file is to be updated; both read and write operations are permitted.
INOUT	X'20'	The file is to be updated; both read and write operations are permitted.
OUTIN	X'40'	The file is first to be created (or overwritten); after this, both read and write operations are permitted.

PARMOD

Specifies the generation mode for the macro.

Default value:

the value preset for the generation mode by means of the GPARMOD macro or by the assembler.

= 24
The macro is expanded in accordance with the format for the 24-bit interface. The object code is thus executable only in 24-bit addressing mode.

= 31
The macro is generated as addressing mode-independent.

Programming notes

1. The OPEN macro overwrites the registers 0, 1, 14 and 15.

2. If, during program execution, an FCB address is specified for a file in an OPEN macro, and that address has been used in a previous OPEN, the program is terminated abnormally and error code DMS0D9F returned.

Notes on programming and on large files

The OPEN macro and the access methods are only affected by the introduction of large files, not by the introduction of large volumes.

The OPEN interface checks whether files are permitted to extend beyond 32 GB and whether the creation of files >= 32 GB and access to such files are permitted.

There are two aspects associated with this:

1. Rejection of access to or the creation of large files for access methods that do not allow processing of large files.

2. Indication that a program can create or open files >= 32 GB.

Incompatible interface variants

Interfaces where 3-byte block numbers are used are never able to work with files >= 32 GB. This affects the following cases:

• All files in key format (BLKCTRL=PAMKEY):
  The logical block numbers in the PAMKEY are only 3 bytes wide.

• 24-bit interface of UPAM
  The field for logical block numbers in the UPAM parameter lists and in the TU FCB is only 3 bytes wide.

• 24-bit interface of SAM
  The logical block numbers are affected as part of the retrieval address. 

In all the cases described above, the following applies:

• Access to files >= 32 GB is rejected with the return code X'0000D9D' or X'00000D00', depending on the size of the storage space allocated to the file (FILE_SIZE).

• Exceeding a file size of 32 GB as a result of secondary allocation is prohibited (LARGE_FILE).

Semantic incompatibilities

It is possible that applications use interfaces that employ 4-byte fields for the data fields described above, but that these 4-byte fields are implicitly or explicitly subject to the former limitation to values less than X'00FFFFFF'.
Please notice, that for the modifications in Assembler code for files >= 32 GB in addition to the conversion to 4-byte block numbers and counters, it is necessary to check whether the program logic implicitly assumes that files may not be larger than 32 GB.

The following lists a number of examples of potential problems.

• The highest 3-byte block number X'FFFFFF' has a special meaning.

• “Block numbers” greater than X'00FFFFFF' represent objects other than blocks.

• For calculations with block numbers or counters greater than X'00FFFFFF', overflow can occur.

• The number of digits in input or output fields is not sufficient for displaying such large block numbers or counters.

• When converting hexadecimal numbers to decimal numbers, the field length is too small for the decimal number.

• It is assumed that data structures whose size depends on a file size always find space in virtual memory. This assumption can apply to files less than 32 GB, but not if this size is exceeded.

It is not possible to give a complete list of problem cases. However, one possible source of problems could be coding based on block numbers, file sizes and derived or dependent structures.

The following return codes display information about execution of the macro with regard to large files:

X'cc'	X'bb'	X'aaaa'	Explanation
X'00'	X'00'	X'0D9D'	Error when opening a disk file
X'00'	X'00'	X'0D00'	System error when opening a file