OPEN—Connect program and data (BDAM, BISAM interface to VSAM, BPAM, BSAM, QISAM interface to VSAM, and QSAM)

The OPEN macro completes the specified data control blocks and prepares for processing the data sets identified in the data control blocks. Input labels are analyzed and output labels are created. Control is given to exit routines as specified in the data control block exit list. The processing method (option 1) provides volume positioning for the data set and define the processing mode (INPUT, OUTPUT, and so forth) for the data sets. Final volume positioning (when volume switching occurs) can be specified (option 2) to override the positioning implied by the DD statement DISP parameter. Option 2 applies only to volumes in a multivolume tape data set other than the last volume. Any number of data control block addresses and associated options can be specified in the OPEN macro.

You must supply a DD statement or the dynamic allocation equivalent. The amount of information in the DD statement is up to you, but you must specify the device allocation and a DDNAME that corresponds to the DDNAME keyword of the associated data control block.

All DCBs must reside below the 16 MB line. The real address can be below or above the 16 MB line or above the 2 GB bar.

The OPEN macro does not support more than a total of 255 spooled, SUBSYS or compressed format data sets for one invocation.

The following DCB access methods support the NOCAPTURE option of dynamic allocation: BPAM, BSAM, and QSAM. The following DCB access method does not support the NOCAPTURE option of dynamic allocation: BDAM.

If associated data sets for a 3525 card punch are being opened, all associated data sets must be open before an I/O operation is initiated for any of the data sets.

Note: You can put more than one ACB/DCB in an OPEN/CLOSE macro or you can include BOTH ACBs and DCBs.

HFS data sets: Open and end-of-volume processing do not support HFS data sets. If an application attempts to open a DCB for an HFS data set, the system issues an information message and the current task abends. If an application encounters an end-of-volume condition which causes positioning to an HFS data set, the system issues an information message and the task abends.

HFS and UNIX files: The OPEN macro supports UNIX files. One type of UNIX file is HFS file. OPEN allows you to specify PATH= on a DD statement for a DCB with DSORG=PS and a BSAM or QSAM MACRF. See z/OS DFSMS Using Data Sets for more information on this type of access.

Large Format Data Sets: On systems at z/OS® V1R7 and above, if you code BLOCKTOKENSIZE=LARGE on the DCBE macro it indicates that your program supports large format data sets. OPEN will also allow you to open large format data sets for input without the BLOCKTOKENSIZE=LARGE if the data contains no more than 65535 tracks. This allows for programs which have not been modified to support large format data sets to be compatible as long as the data sets are not too large.

The standard form of the OPEN macro is as follows (the list and execute forms are shown following the description of the standard form):

[label]

OPEN

(dcb address[, [(options)][,...]])
[,TYPE=J]
[,MODE=24|31]

dcb address—A-type address or (2-12)

specifies the address of the data control blocks for the data sets to be prepared for processing.

If the register format is specified, then the register must be enclosed within parentheses. For example, OPEN ((2),INPUT).

options

The option values shown in the following table indicate the volume positioning available based on the device type and access method being used.

Access Method	Device Type
	Magnetic Tape		Direct Access Storage Device or TSO terminal		Other Types

	Option 1	Option 2	Option 1	Option 2	Option 1	Option 2
QSAM	[INPUT] [EXTEND] [OUTPUT] [RDBACK]	[,REREAD] [,LEAVE] [,DISP]	[INPUT] [EXTEND] [OUTPUT] [UPDAT]	[,REREAD] [,LEAVE] [,DISP]	[INPUT] [EXTEND] [OUTPUT]	—
BSAM	[INPUT] [EXTEND] [OUTINX] [OUTPUT] [INOUT] [OUTIN] [RDBACK]	[,REREAD] [,LEAVE] [,DISP]	[INPUT] [EXTEND] [OUTINX] [OUTPUT] [INOUT] [OUTIN] [UPDAT]	[,REREAD] [,LEAVE] [,DISP]	[INPUT] [OUTPUT]	—
QISAM Load Mode	—	—	[OUTPUT] [EXTEND]	—	—	—
BPAM, BDAM	—	—	[INPUT] [OUTPUT] [UPDAT]	—	—	—

If option 1 is omitted, INPUT is assumed. If option 2 is omitted, DISP is assumed. You must code option 1 if also coding option 2. Option 2 has an effect only for multivolume tape data sets. Options 1 and 2 are ignored for BISAM interface to VSAM and QISAM interface to VSAM (in the scan mode), and the data control block indicates the operation. You must specify OUTPUT, OUTIN, OUTINX (DASD), or EXTEND (on DASD) when creating a data set.

Restrictions are as follows:

The EXTEND, INOUT, OUTIN, and OUTINX options are not allowed for ISO/ANSI Version 3 tape processing. This restriction does not apply to ISO/ANSI Version 4 IBM® formatted tapes.
The UPDAT option is not allowed for compressed format data sets.
TSO terminals support only QSAM and BSAM

The following describes the options shown in the preceding illustration. All option parameters are coded as shown.

Option 1: Meaning
EXTEND: The data set is treated as an OUTPUT data set, except that records are added to the end of the data set regardless of what was specified on the DISP parameter of the DD statement.
INPUT: Input data set.
INOUT: The data set is first used for input and, without reopening, is used as an output data set. The data set is processed as INPUT if it is a SYSIN data set, or a PDSE, or LABEL=(,,,IN) is specified in the DD statement.
OUTPUT: Output data set (for BDAM, OUTPUT is equivalent to UPDAT).
OUTIN: The data set is first used for output and, without reopening, is used as an input data set. The data set is processed as OUTPUT if it is a SYSOUT data set, or a PDSE, or LABEL=(,,,OUT) is specified in the DD statement.
OUTINX: The data set is treated as an OUTIN data set, except that records are added to the end of the data set regardless of what was specified on the DISP parameter of the DD statement. For PDSEs, OUTINX is equivalent to OUTPUT.
RDBACK: Input data set, positioned to read backward.
Restriction: Variable-length records cannot be read backward. The RDBACK option is not allowed for DASD data sets.
UPDAT: Data set to be updated in place or, for BDAM, blocks are to be updated or added. If you specify UPDAT using QSAM, you must use locate mode.
Restriction: The UPDAT option is not allowed for compressed format data sets, or UNIX files, or for magnetic tapes, or with large block interface.

Option 2: Meaning
LEAVE: Positions the current tape volume to the logical end of the data set when volume switching occurs. If processing was forward, the volume is positioned to the end of the data set. If processing was backward (RDBACK), the volume is positioned to the beginning of the data set.
REREAD: Positions the current tape volume to reprocess the data set when volume switching occurs. If processing was forward, the volume is positioned to the beginning of the data set. If processing was backward (RDBACK), the volume is positioned to the end of the data set.
DISP: Specifies that a tape volume is disposed of in the manner implied by the DD statement associated with the data set. Direct access volume positioning and disposition are not affected by this parameter of the OPEN macro. There are several dispositions that you can specify in the DISP parameter of the DD statement. DISP can be PASS, DELETE, KEEP, CATLG, or UNCATLG. This option has significance at the time an end-of-volume condition is found only when DISP is PASS. The end-of-volume condition might result from issuing an FEOV macro or might be the result of reaching the end of a volume.
If DISP is PASS in the DD statement, the tape is spaced forward to the end of the data set on the current volume.

If any DISP option is coded in the DD statement (except when DISP is PASS), the resultant action when an end-of-volume condition arises depends on (1) how many tape units are allocated to the data set and (2) how many volumes are specified for the data set in the DD statement. This is determined by the UNIT and VOLUME parameters of the DD statement associated with the data set. If the number of volumes is greater than the number of units allocated, the current volume is rewound and unloaded. If the number of volumes is less than or equal to the number of units, the current volume is merely rewound.
Note: When the DELETE option is specified, the system waits for the completion of the rewind operation before it continues processing subsequent reels of tape.
If you code DISP and issue a CLOSE TYPE=T, LEAVE processing is performed. Any other options specified for CLOSE TYPE=T besides LEAVE and REREAD are treated as LEAVE during execution.

TYPE=J

You can code OPEN TYPE=J to specify that, for each data control block referred to, you have supplied a job file control block (JFCB) for use during initialization. A JFCB is an internal representation of information in a DD statement or dynamic allocation. This option, because it may be used with modifying a JFCB, should be used only by the system programmer or only under the system programmer's supervision. MODE=31 is not allowed when TYPE=J is specified. For more detailed information on using TYPE=J, see z/OS DFSMSdfp Advanced Services.

UNIX files: When you specify TYPE=J, you cannot add or change the value of PATH=. Only changes to LRECL, BLKSIZE, RECFM, BUFNO, and NCP have an effect.

MODE=24|31

You can code OPEN MODE=31 to specify a long form parameter list that can contain 31-bit addresses. Your program does not need to be executing in 31-bit addressing mode to use MODE=31 in the OPEN macro. This parameter specifies the form of the parameter list, not the addressing mode of the program. The default, MODE=24, specifies a short form parameter list with 24-bit addresses. MODE=31 is not permitted if TYPE=J is specified. If TYPE=J is specified, you must use the short form parameter list.

The caller of the standard form of the macro with the short form of the parameter list must reside below the 16 MB line, but the caller can be executing in 31-bit mode. If you code the short form, all ACBs and DCBs must reside below the 16MB line.

The long form parameter list can reside above or below the 16MB line. Although the ACB or DCB address is contained in a 4-byte field, the DCB must be below the 16MB line. Except for VSAM or VTAM® ACBs, all ACBs must also be below the 16MB line. Therefore, the leading byte of the ACB or DCB address must contain zeros. If the byte contains something other than zeros, an IEC190I message is issued and the data set is not opened. The program is not abnormally terminated unless an attempt is made to read to or write from the data set.

The following errors in opening a DCB cause the results indicated:

Attempting to open a data control block that is already open: No action
Attempting to open a data control block when the DCB address does not specify the address of a data control block.: Unpredictable
Attempting to open a data control block when a corresponding DD statement has not been provided.: A "DD STATEMENT MISSING" message is issued. An attempt to use the data set causes unpredictable results (see note 1).

Notes:

You can test bit 3 of the DCBOFLGS field in the data control block. Bit 3 is set to 1 if the data control block opened successfully, but is set to 0 if an error occurs, and can be tested by the sequence:
```
TM DCBOFLGS,DCBOFOPN
BZ ERRORRTN       (Branch to your error routine)
```
If OPEN gives return code 0, then bit 3 for each DCB is 1.

Executing the two instructions shown above requires writing a DCBD macro in the program, and a base register must be defined with a USING statement before the instructions are executed.
Other errors detected by OPEN result in an abend with a system completion code in the form x13, where x is a hex digit from 0 to F. See z/OS MVS System Codes for the abend codes.