The DCB extension (DCBE) provides functions that augment those provided by the DCB. A DCBE is optional. The DCBE must reside in storage that you can access and modify. This storage may be located above or below the 16 MB line independently of whether your program is executing in 31-bit addressing mode. The DCBE is specified using the DCBE parameter of the DCB macro.

The DCBE must not be shared by multiple DCBs that are open. After the DCB is successfully closed, the user may open a different DCB pointing to the same DCBE. Your program may refer to DCBE fields symbolically by using the IHADCBE mapping macro and the DCBDCBE address in the DCB (using the DCBD mapping macro).

OPEN will set a flag (DCBEMD31) in the DCBE if 31-bit SAM is supported. You may test the DCBEMD31 flag during the DCB OPEN exit routine or any time until CLOSE. In a concatenation, if you turned on the DCB unlike attributes bit before using OPEN, then OPEN will set DCBEMD31 on if the current access supports data above the line. If you did not turn on the DCB unlike attributes bit, then OPEN will set DCBEMD31 on if all the data sets in the concatenation support data above the line. Otherwise, OPEN will set DCBEMD31 off.

The purpose of this test is to allow you to determine that the SAM 31-bit interfaces will not work for the data set being opened. DCBEMD31 also will remain off on a DFP level that supports none of the SAM 31-bit interfaces.

The value of DCBEMD31 does not specify whether an OPEN or CLOSE issuer or parameter list may be the 31-bit type.

Each DCBE parameter description contains a heading, "Source." The information under this heading describes when you may set the parameter.

The format of the DCBE macro is:

BLKSIZE=n 

requests the large block interface (LBI) even if you code 0. If the value is nonzero, this parameter specifies the maximum block length in bytes. For fixed-length, unblocked records, a non-zero value specifies the record length. The actual value that you can specify in BLKSIZE depends on the device type and the record format being used. Most of the LBI information is described in this book. For further information, refer to z/OS DFSMS Using Data Sets.

In order to process a large (greater than 32760) block size tape with BSAM or QSAM, your program must provide a DCBE along with the DCB for the data set. The DCBE must indicate that the application is capable of processing large block sizes by specifying the BLKSIZE parameter. If you specify BLKSIZE=0 on the DCBE macro, the open function sets the DCBE block size field from the first non-zero value from one of the following:

• The JCL parameters DCB=BLKSIZE or BLKSIZE.
• The data set label on tape or disk.
• Determined by the system when the following conditions are met:
  • The OPEN option is OUTPUT or OUTINX
  • The record format is fixed or variable
  • The maximum logical record length is available
  The upper limit to the block size that is determined by OPEN is the BLKSZLIM value on the DD statement or a limit that is set in the data class or in SYS1.PARMLIB by a system programmer. Seez/OS DFSMS Using Data Sets for a description of the system-determined block size function.

If you code a value for DCBE BLKSIZE, even 0, and the large block interface is used, the system uses the DCB BLKSIZE field for scratch purposes.

If you do not code a value for DCBE BLKSIZE but there is a DCB BLKSIZE value specified, the DCB BLKSIZE will apply.

BLOCKTOKENSIZE={LARGE|SMALL}

This option allows you to specify whether your application program is capable of handling the interface for large format data sets. The default is SMALL.

The IGDSMSxx member of the SYS1.PARMLIB system data set has an option that affects whether your program can open large format data sets. Only a system programmer can change the IGDSMSxx member.

You can ask your system programmer which of the following two values of the option are in effect:

• BLOCKTOKENSIZE(REQUIRE):

  It means that all programs that open any large format data set must have BLOCKTOKENSIZE=LARGE on the DCBE macro unless the OPEN option is INPUT and the data set contains no more than 65535 tracks on the volume. Otherwise OPEN will issue an ABEND macro.

• BLOCKTOKENSIZE(NOREQUIRE):
  This is the default when IBM® supplies the operating system. This means that when programs open a large format data set, they do not need to code BLOCKTOKENSIZE=LARGE on the DCBE unless one of these is true:

  • The DCB signifies BSAM with the NOTE or POINT macro. This means that the DCB has a MACRF value of RP or WP or both.
  • The DCB signifies EXCP (MACRF=E).

When you code BLOCKTOKENSIZE=LARGE on the DCBE macro, it will have the following effects:

• The DCBELARGE bit in DCBEFLAG3 of the DCBE will be set to 1.
• Your program can use this DCBE option so as to open large format data sets without regard to the value of the BLOCKTOKENSIZE option in the IGDSMSxx member of the SYS1.PARMLIB system data set. It means that your program is aware of the differences in the DSCB (DS1TTTHI), DEB (DEBTTTHI), and TTR conversion routines. These topics are described in z/OS DFSMSdfp Advanced Services.
• If you use BSAM with the NOTE and POINT macros, then the OPEN macro will allow the opening of large format data sets. You also can use BPAM with large block tokens. Your program is signifying that the NOTE and POINT macros will use four-byte block tokens (or addresses) instead of three-byte block tokens. When using BPAM with a PDS, this will not effect the TTR values used for BLDL and FIND. For more details see the descriptions of the NOTE and POINT macros. Also, with BPAM the content of DCBRELAD and DCBERELA, which identify the location of the beginning of the member, are unaffected.
  Note: If you pass to POINT a TTR returned from BLDL, you must right align the three bytes returned into the four byte field that you pass.
• If the DCB macro signifies EXCP, then the OPEN macro will allow the opening of large format data sets.

CAPACITYMODE=XCAP 

This option specifies that you want to use extended capacity with the NOTE and POINT macros if the device is capable of it. This affects the NOTE and POINT macros when TYPE=ABS is coded, but when TYPE=REL is coded or defaulted. It also allows more blocks on the tape with BSAM, QSAM and EXCP.

This option will have an effect only if the device is an IBM 3590 that is emulating an IBM 3490, and has the right level of maintenance. You might want to request the extended capacity mode for the following reasons:

• It allows BSAM, QSAM or EXCP programs to read or write longer tapes.
• The BSAM or EXCP program can issue the NOTE and POINT macros with extended capacity mode.

In order to help your program adapt to various devices and levels of the system, the DCBE has a bit named DCBE_32BIT_INUSE. See the DCBE field descriptions in Data control block extension (DCBE). After a successful OPEN macro, your code can test this bit. If it is 1, your program knows that one of the following conditions is true:

• The current volume is on a device that supports extended capacity all the time. This bit will be on even if you do not code CAPACITYMODE.
• The current volume is on a drive, such as the IBM 3590, that is emulating a lower capacity device, but it is operating in high-capacity mode. The bit will be on only if you specify CAPACITYMODE=XCAP.

If you request CAPACITYMODE=XCAP, but your program finds that the DCBE_32BIT_INUSE bit is off, one of the following conditions is true:

• The operating system is down-level and does not support CAPACITYMODE=XCAP.
• The operating system is up-level, but the device does not support extended capacity.

Each volume in a data set and each data set in a sequential concatenation might have differing values for this bit.

A QSAM program will automatically be able to read a long tape without requesting extended capacity. A BSAM or EXCP reading program will not be able to read a long tape without requesting CAPACITYMODE=XCAP. This is because the NOTE macro with TYPE=ABS returns a larger value than would be returned from lower capacity models such as the 3480 and 3490.

After the drive is switched to high-capacity mode, it remains in that mode as long as the tape is mounted, even if your program closes the data set and opens the same or a different data set on the tape and does not code CAPACITYMODE.

EADSCB=OK|NOTOK

Specify the support level for extended attribute DSCBs.

EADSCB=OK allows you to specify that your application program supports the following:

• Opening a VTOC that might have format 8 DSCBs. These calls must provide a DCBE macro with the EADSCB=OK keyword to indicate that the caller supports extended attribute data provided in DSCBs and track addresses with cylinder 65520 or larger. If you do not code this option, the OPEN function will issue ABEND 113-48 and message IEC142I. Code this option when your application program supports Format 8 and 9 DSCBs.
• Opening a data set that has a format 8 DSCB for EXCP access or for BDAM access with OPTCD=A. These calls must provide a DCBE macro with the EADSCB=OK keyword to indicate that the caller supports extended attribute data provided in DSCBs and track addresses with cylinder 65520 or larger. If you do not code this option, the OPEN function will issue ABEND 113-44 and message IEC142I. Code this option when your application program supports Format 8 and 9 DSCBs and such track addresses.

EADSCB=NOTOK indicates a calling program does not support extended attribute DSCBs. The specification of this will resolve to the DCBEEADSCBOK indicator in the DCBE to be set off. This is the default.

EODAD=relexp

specifies the address of an end-of-data routine given control when the end of an input data set is reached. The entry point may be above the line or below the line. If the EODAD routine resides above the line, you must issue all CHECKs or GETs in 31-bit addressing mode.

An EODAD address in the DCBE will take precedence over an EODAD address in the DCB. The EODAD routine (whether it is specified in the DCBE or DCB) will get control in the addressing mode in which the CHECK or GET is issued.

If the record format is RECFM=FS or FBS, the end-of-data condition is detected when a file mark is read or when more data is requested after reading a truncated block.

If the end of data block is reached but no EODAD address was supplied in either the DCBE or DCB, or if a GET macro is issued after an end-of-data exit is taken, the task is abnormally terminated. For additional information on the EODAD routine, see z/OS DFSMS Using Data Sets. You may also refer to the EODAD parameter in the appropriate DCB macro.

Source: EODAD can be supplied in the DCBE macro or by the problem program before the end of the data set has been reached.

FIXED=USER

With this DCBE option, you assert that the data areas will remain fixed from the time the READ or WRITE macro instruction is issued through the completion of the CHECK or WAIT macro instruction. Failure to keep the data areas fixed results in a system integrity exposure as the channel program uses the real addresses associated with the data areas.

The purpose of this option is to improve performance by using less processor time.

Your program can ensure that the data areas are fixed by doing one of the following:

• Issuing the PGSER FIX macro
• Using the GETMAIN or STORAGE macro for a page fixed subpool
• Issuing the IARV64 macro with REQUEST=GETSTOR and TYPE=DREF
• Issuing the IARV64 macro with REQUEST=PAGEFIX
• Issuing the IARST64 macro with REQUEST=GET and TYPE=DREF or TYPE=FIXED
• Issuing the IARCP64 macro with REQUEST=BUILD and TYPE=DREF or TYPE=FIXED.

All of these methods of fixing pages require that your program have a form of authorization, such as APF authorization or running in either supervisor state or system protection key. Other restrictions may apply. The FIXED=USER option also requires one of these forms of authorization.

This parameter has an effect only for these types of DASD data sets:

• Basic or large format
• Extended format but not compressed format
• Partitioned but not PDSE.

If the data set is not one of those types, the system will take care of any page fixing that is needed.

The following is not intended programming interface information: After completion of the OPEN macro, your program can test a bit to determine whether FIXED=USER has an effect. The bit is DEB2XUPF in the DEB2XFG3 byte and is mapped by the IEZDEB macro in DEB2X.

GETSIZE={YES|NO}

specifies that OPEN is to calculate the number of blocks in the data set and store this number in the DCBE (DCBESIZE). In most cases this is an estimate. With concatenated data sets the number is for only the current data set. As you read through the data sets, the system changes this number.

DCBESIZE is valid after OPEN and on entry to the user's DCB OPEN exit routine. However, for compressed format data sets, DCBESIZE will not be valid until after OPEN.

For a compressed format data set, the number of physical blocks in the data set will differ from the number of user blocks found in the data set. DCBESIZE will refer to the number of user blocks found in the data set.

This parameter is ignored if the data set is not extended format data sets or UNIX files.

For UNIX files,

• If GETSIZE=YES is specified, DCBEXSIZ (an 8-byte value) is set to the approximate number of blocks in the file based on DCBRECFM and DCBBLKSI.

  GETSIZE is not supported for FIFO or character special files. DCBEXSIZ is set to 0.

Source: You may set this parameter in the DCBE macro.

LOC={ANY|BELOW}

Specify this option before issuing the OPEN or RDJFCB macro. If you specify LOC=BELOW or do not code LOC=, you signify that the program does not support the XTIOT, UCB NOCAPTURE, or DSAB-above-the-line options of dynamic allocation. These are the S99TIOEX, S99ACUCB, and S99DSABA options. By setting LOC=ANY you signify that the program is either not affected by or that is allows for any of the following possibilities:

• the DCBTIOT field (offset in TIOT to an entry) might contain zeroes or contain a TIOT offset,
• the DEBXDSAB field (address of DSAB) might point above the line,
• the DSABTIOT field might point to an XTIOT or to a TIOT entry,
• the UCB address field in the DEB might be four bytes or three bytes (test the DEB31UCB bit),
• the TIOEFSRT field might contain zeroes instead of a UCB address.

For more information on the XTIOT and other dynamic allocation options, see z/OS DFSMS Using Data Sets and z/OS MVS Programming: Authorized Assembler Services Guide.

IBM recommends that, regardless of dynamic allocation and the NON_VSAM_XTIOT setting, you always specified DCBE LOC=ANY when either your program does not reference TIOT, UCB, and DSAB, or that it is correctly modified to support the XTIOT, UCB NOCAPTURE, or DSAB-above-the-line options.

Table 1. LOC=ANY for BSAM, QSAM, and BPAM

NON_VSAM_XTIOT=	DCBE LOC=	Result
NO or not coded	BELOW or not coded	OPEN return code 8, Message IEC133I, DCBOFOPN bit is off.
NO or not coded	ANY	ABEND 113–4C, messages IEC133I and IEC142I.
YES	BELOW or not coded	OPEN return code 8, Message IEC133I, DCBOFOPN bit is off.
YES	ANY	Successful OPEN.

If the application program specifies LOC=ANY for a data set dynamically allocated with the options XTIOT, UCB NOCAPTURE, and/or DSAB-above-the-line, and the NON_VSAM_XTIOT=YES option in PARMLIB is in effect, then OPEN will set the two-byte DCBTIOT field to zero instead of setting it to an offset in the TIOT, and the data set will be opened successfully. On the other hand, if the application program sets the DCBE option LOC=ANY before OPEN, but the NON_VSAM_XTIOT=YES option in PARMLIB is not in effect and any of the three dynamic allocation options is in effect, then OPEN will issue an ABEND 113–4C and message IEC142I. A summary of the expected results with BSAM, QSAM, and BPAM is in Table 1.

Table 2. LOC=ANY for EXCP

NON_VSAM_XTIOT=	DCBE LOC=	Result
NO or not coded	BELOW or not coded	OPEN will capture the UCB if needed and CLOSE will uncapture it.
NO or not coded	ANY	OPEN will capture the UCB if needed and CLOSE will uncapture it. OPEN will issue message IEC136I ddname, DCBE LOC=ANY NOT HONORED DUE TO PARMLIB OPTION.
YES	BELOW or not coded	OPEN will capture the UCB if needed and CLOSE will uncapture it.
YES	ANY	Successful OPEN and UCB is not captured.

The LOC=ANY option for an EXCP DCB for DASD or tape means that the application program accepts:

• OPEN not capturing the UCB,
• the TIOT DD entry being an XTIOT, and
• the DSAB being above the line.

The result will depend on the NON_VSAM_XTIOT option of the DEVSUPxx member of PARMLIB as described in Table 2. An EXCP DCB for a device other than DASD or tape will continue to get the existing failures.

MULTACC=n

allows the system to process BSAM I/O requests more efficiently by not starting I/O until a number of buffers have been presented to BSAM.

A non-zero value indicates to OPEN that BSAM can do a more efficient type of queuing of (accumulation) of READ or WRITE requests. If you code a non-zero value, your program must not issue a WAIT or EVENTS macro against a DECB unless you preceded it with issuance of a TRUNC macro. If you code a nonzero value but your program issues a WAIT or EVENTS macro against a DECB for the DCB and the program has not issued a TRUNC after the previous READ or WRITE, the program may go into an unending wait.

If your program follows the rules for MULTACC use but the data set type does not support it, the program will still run correctly.

If you code a nonzero value, OPEN calculates a default number of READ or WRITE requests that you are suggesting the system queue more efficiently. First OPEN calculates the number of BLKSIZE-length blocks that can fit on a track. OPEN then multiplies this value by the MULTACC value and, for an extended format data set, by the number of stripes. The system will try to defer starting I/O requests until you have issued this many READ or WRITE requests for the DCB. BSAM will never queue (defer) more READ or WRITE requests than the NCP value set in OPEN.

MULTACC has an effect only for BSAM DASD non-spooled, and non-PDSE data sets. In the current release it has no effect for other types of data sets or UNIX files.

MULTACC has no effect for compressed format data sets. The user may issue WAITs in this case.

Recommendation: IBM recommends that users not take advantage of this characteristic of compressed format data sets (that WAIT may be issued although MULTACC is specified) because it will not work reliably for other types of data sets and, in future levels of the system, it may not work with compressed format data sets.

Source: You may set MULTACC in the DCBE macro or in the DCB OPEN exit routine. This parameter should not be changed while the DCB is open except when the DCB OPEN exit is reentered for each data set in a concatenation where you have set on the DCB unlike attributes bit.

MULTSDN=n

requests a system-defaulted NCP.

If nonzero and DCBNCP is zero and the data set block size is available, the system will calculate an appropriate initial NCP value. The system will then multiply this value by the number specified in MULTSDN and store this value in DCBNCP. DCBNCP will be set before the DCB OPEN exit routine is given control. This allows you to give the system indicators without being dependent on device information such as blocks per track or number of stripes. If DCBNCP is zero after returning from the OPEN exit, the SDN will be derived or re-derived after the OPEN exit and stored in DCBNCP.

If you are using large block interface (LBI) tape, DCBNCP is set to MULTSDN with the value being a minimum of 2 and a maximum of 16. For non-LBI tape, the default DCBNCP is 5.

For DASD data sets which are not extended format data sets, the initial NCP value will be the number of DCBBLKSI-length blocks that can fit on a track.

For extended format data sets (not in the compressed format), the initial NCP value will be the number of DCBBLKSI-length blocks (plus the suffix) that can fit on a track times the number of stripes. For compressed format data sets, the initial NCP value is 1 because 1 is the most efficient value.

For UNIX files, if MULTSDN is specified (and DCBNCP is not specified), DCBNCP is set to the value specified by MULTSDN. Currently, the initial NCP value is set to 5.

Restriction: This parameter will be ignored if BLKSIZE is not available from any source.

The NCP limit is 255.

Source: You may set MULTSDN in the DCBE macro or in the DCB OPEN exit routine. This parameter should not be changed while the DCB is open except when the DCB OPEN exit is reentered for each data set in a concatenation where you have set on the DCB unlike attributes bit.

NOVER={YES|NO}

specifies that OPEN should bypass any verification to determine whether the size of the stripes of an extended format data set are consistent. The default is NO.

Inconsistent stripes could be caused by inadvertently restoring one or more stripes of an extended format data set without restoring all stripes.

In general, OPEN will use the longest stripe to be the end of the file if you specify NOVER=YES. However, if the longest stripe fills a track and a later stripe ends in the middle of that same relative track, OPEN will assume the shorter stripe to be the true data set end.

This parameter is ignored if th e data set is not an extended format data set.

Source: You may set this parameter in the DCBE macro or in the DCB OPEN exit routine. It should not be changed while the DCB is open.

PASTEOD={YES|NO}

specifies that the end-of-data marker of the extended format data set, which is saved when the data set is open for INPUT, UPDATE, OUTIN, or INOUT is to be ignored. The default is NO.

This parameter is ignored if the data set is not an extended format data set. This parameter is ignored if the data set is open for other than INPUT, INOUT, UPDAT, or OUTIN.

For extended format data sets, the system saves the end-of-data marker of the data set when the data set is opened for input or update. If the data set is opened for output while it is still open for input (without specifying PASTEOD=YES), the input DCB will not see any of the records which may have been written past the end-of-data marker by the output DCB. PASTEOD=YES allows the input DCB to read past the end-of-data marker of the data set which was saved when the data set was opened. This allows the input DCB to read records which may have been written past the end-of-data marker by another DCB.

Source: You may set this parameter in the DCBE macro or in the DCB OPEN exit routine. It should not be changed while the DCB is open.

RMODE31={BUFF|NONE}

specifies whether you request that OPEN get QSAM buffers above the 16 MB line (RMODE31=BUFF) or not (RMODE31=NONE) when acquiring buffers automatically. The default is NONE. If BFTEK=A is specified in the DCB, OPEN also gets the QSAM logical record interface (LRI) area above the 16MB line. CLOSE will free these buffers and the LRI area, if it exists.

In releases prior to DFSMS/MVS 1.1, FREEPOOL is typically issued after CLOSE since CLOSE does not free the QSAM 24-bit buffers. However, if OPEN honors your request for buffers above the 16 MB line, you should either avoid the FREEPOOL macro, or reassemble the program with the FREEPOOL macro. At DFSMS/MVS 1.1, the FREEPOOL expansion tests whether the buffer pool exists before attempting to free it.

The RMODE31=BUFF parameter has no effect if any of the following are true:

• BUFCB is specified on the DCB macro.
• Buffer pool is built by a GETPOOL, BUILD, or BUILDRCD macro or a previous OPEN.
• Access method is BSAM or BPAM.
• OPEN leaves DCBEMD31 as zero.

Source: You may set this parameter in the DCBE macro or in the DCB OPEN exit routine. It should not be changed while the DCB is open except when the DCB OPEN exit is reentered for each data set in a concatenation where you have set on the DCB unlike attributes bit.

SYNAD=relexp

specifies the address of an error analysis (SYNAD) routine given control when an uncorrectable input/output error occurs. The entry point may be above the line or below the line. If the SYNAD routine resides above the line, you must issue all CHECKs, GETs, or PUTs in 31-bit addressing mode.

A SYNAD address in the DCBE will take precedence over a SYNAD address in the DCB. The SYNAD routine (whether it is specified in the DCBE or DCB) will get control in the addressing mode in which the CHECK, GET, or PUT is issued.

If an uncorrectable input/output error is encountered but no SYNAD routine was supplied in either the DCBE or DCB, the task is abnormally terminated. See z/OS DFSMS Using Data Sets for additional information on the SYNAD routine. You may also refer to the SYNAD parameter in the appropriate DCB macro.

Source: SYNAD can be supplied in the DCBE macro or by the problem program. The problem program can also change the error routine address at any time.

SYNC={SYSTEM|NONE}

This parameter is intended for use with magnetic tapes. Two options are available: SYSTEM and NONE. The default is SYSTEM.

When your program is in write mode, the system will try to ensure that your data is safe on the medium in each of the following circumstances:

• The program switches to another volume to continue writing.
• The data set is closed.

If the system's volume-switching function or close function detects a data loss, it issues an ABEND.

Issuing a BSAM CHECK macro or EXCP WAIT macro ensures that the data has been sent to the device. Whether it is safe on the medium depends on the type of device and data set, and on the guaranteed synchronous write option in the storage class. This storage class option affects only PDSEs. You can use the SYNCDEV macro to ensure synchronization, but the performance might not be up to your installation's standards.