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 be in the same storage key as the corresponding DCB. If they are not in the same storage key, the DCBE invocation will fail with message IEC190I.
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:
[label] |
DCBE |
[,BLKSIZE=n] |
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.
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.
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.
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.
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=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.
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.
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:
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.
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.
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.
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.
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.
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. |
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. |
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.
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.
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.
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.
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.
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.
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.
This parameter is intended for use with magnetic tapes. These options are available: SYSTEM, NONE and (NUMFILES,nnn). The default is SYSTEM.
You can use the NUMFILES keyword to specify the number of files that a job can submit sequentially before they are written to tape (synchronized). For example, if you specify a value of NUMFILES(100), then up to 100 files can be written specifying PASS RETAIN or CLOSE LEAVE before the files are explicitly written to the tape medium.
If you specify SYSTEM (the default value), then 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:
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.