The data control block for a basic partitioned access method (BPAM) data set is constructed during assembly of the problem program. You must code the DSORG and MACRF parameters in the DCB macro, but the other DCB parameters can be supplied from other sources. Each of the BPAM DCB parameter descriptions contains a heading, "Source". The information under this heading describes the sources that can supply the parameter to the data control block. Each reference to a DCB OPEN exit routine applies also to a JFCBE exit routine. The DCB fields that you can test or set are described in Non-VSAM control blocks.
You can assemble the DCB macro into a program that resides above the 16 MB line, but the program must move it below the line before using it. Except for the DCBE, all areas that the DCB refers to, such as EXLST and EODAD, must be below the 16 MB line.
The format of the DCB macro for BPAM is:
[label] |
DCB |
[BFALN={F|D}] |
---|
If the BUILD macro is used to construct the buffer pool or if the problem program controls all buffering, the problem program must provide an area for the buffers and control buffer alignment.
Source: BFALN can be supplied in the DCB macro, in the DCB subparameter of a DD statement, or by the problem program before completion of the data control block exit routine.
You can request to use the BLKSIZE keyword on a DCBE macro. This is the large block interface (LBI). If the system allows the LBI, the system modifies the BLKSIZE field in the DCB and your program should not use it.
The actual block size you can specify depends on the record format and type of direct access storage devices being used. The block size can be up to 32760 but you will get more data on each track if you write shorter blocks. Device capacity for direct access storage devices is described in Selecting logical record lengths and block sizes for specific devices. For additional information about space allocation, see z/OS DFSMS Using Data Sets.
For fixed-length records, the value specified in BLKSIZE should be a multiple of the value specified for the logical record length (LRECL).
For fixed-length unblocked records, LRECL must equal BLKSIZE (if LRECL is specified).
For variable-length records, the value specified in BLKSIZE must include the maximum logical record length (up to 32756 bytes) plus 4 bytes for the block descriptor word (BDW).
For undefined-length records, the value specified for BLKSIZE can be altered by the problem program when the actual length becomes known to the problem program. The value can be inserted into the DCBBLKSI field of the data control block, or DCBEBLKSI field of the DCBE, or specified in the length parameter of a READ or WRITE macro.
Processing PDSEs: The system reblocks PDSE records into its own internal format when the data set is written, and reconstructs the blocks using the block size from the DCB when the data set is read. For fixed-length blocked records, the value specified in BLKSIZE must be a multiple of the value in LRECL (if LRECL is specified). The LRECL value must be available to OPEN when the PDSE is open for output.
When reading a PDSE directory using fixed-length blocked records, you can specify a BLKSIZE of 256 or greater (the LRECL is ignored).
System-Determined Block Size: IBM® recommends that you not specify block size unless the record format is U. This makes your program less dependent on the physical characteristics of the device although a PDSE block size has little to do with device characteristics. If the block size is not specified when the data set is allocated, and the LRECL and RECFM are known, the system derives an optimum block size for the data set. This system-determined block size is retained in the data set label. When the data set is opened for output, OPEN checks the block size in the data set label. If it is a system-determined block size, and the LRECL or RECFM have changed from those specified in the data set label, OPEN redetermines an optimum block size for the data set.
Source: BLKSIZE can be supplied in the DCB or DCBE macro, in the DCB subparameter of a DD statement, by the problem program before completion of the data control block exit routine, by the data set label of an existing data set, or by the system determining a value for a new data set. The system does not copy BLKSIZE when you code the JCL keyword LIKE. It derives the BLKSIZE from RECFM and LRECL which can be copied. For more information on LIKE, see z/OS MVS JCL Reference and z/OS MVS JCL User's Guide. .
If the buffer pool is constructed automatically or by a GETPOOL macro, you can omit the BUFCB parameter because the system places the address of the buffer pool control block into the data control block. Also, if the problem program is to control all buffering, omit the BUFCB parameter. A buffer pool control block resides below the 16MB line.
Source: BUFCB can be supplied in the DCB macro or by the problem program before issuing a GETBUF macro.
If the problem program controls all buffering, BUFL is not required.
Source: BUFL can be supplied in the DCB macro, in the DCB subparameter of a DD statement, or by the problem program before completion of the data control block exit routine.
If the problem program controls all buffering or if the buffer pool is constructed by a GETPOOL macro, omit BUFNO.
The default value is zero. If the blocksize is less than 32768 and BUFNO is either specified as zero to allowed to default to zero the system does not acquire buffers automatically. If the blocksize is 32768 or greater and BUFNO is either specified as zero or allowed to default to zero then the system will acquire two buffers or the number of buffers specified by MULTSDN, whichever is greater. If the system acquires buffers for BPAM, they reside below the 16MB line. You may obtain each buffer by issuing a GETBUF macro.
Source: BUFNO can be supplied in the DCB macro, in the DCB subparameter of a DD statement, or by the problem program before completion of the data control block exit routine.
If the DCBE is specified, it must be specified before issuing the OPEN macro. Like the DCB, the DCBE must exist until the data set is closed. Otherwise, there may be unpredictable results.
Only one open DCB at a time can refer to a particular DCBE. After a DCB is successfully closed, you can open a different DCB that refers to the DCBE.
The DCBE is not required with BPAM unless the data set requires a DCBE option or if you choose to use DCBE options.
If a DCB points to a DCBE, the flags DCBH0 and DCBH1 are both set on. The pointer to the DCBE is stored at offset +0 in the DCB (and replaces the field DCBRELAD). If a DCBE exists, data that would be stored at DCBRELAD is stored in the DCBE (DCBERELA). If a DCBE does not exist, DCBRELAD continues to be located at offset +0 in the DCB.
Source: You can supply the DCBE address in the DCB macro or before issuing an OPEN macro to open the data set.
Source: DDNAME can be supplied in the DCB macro or by the problem program before an OPEN macro is issued to open the data set.
If BSAM or QSAM is used to add or retrieve a single member of a partitioned data set, specify DSORG=PS or DSORG=PSU in the BSAM or QSAM DCB. To retrieve a single member of a PDSE, specify DSORG=PS in the BSAM or QSAM DCB. The name of the member being processed in this manner is supplied in the DD statement.
Restrictions are as follows:
Source: DSORG parameter must be specified in the DCB macro.
Source: EODAD can be supplied in the DCB macro or by the problem program before the end of the member is reached.
The exit list must reside below the line. For the functions, format, and requirements of exit list processing, see z/OS DFSMS Using Data Sets. Exit routines can reside above the 16 MB line if you use the technique described in Figure 1.
Source: EXLST can be supplied in the DCB macro or by the problem program before the relevant function is needed.
A nonzero key length is allowed for input from a PDSE, but is not allowed for output to a PDSE. You can use keys for reading PDSE members, but not for writing PDSE members.
Source: KEYLEN can be supplied in the DCB macro, in the DCB subparameter of a DD statement, by the problem program before the completion of the data control block exit routine, or by the data set label of an existing data set. If KEYLEN=0 is specified in the DCB macro, a special indicator is set in RECFM so that KEYLEN cannot be supplied from the DCB subparameter of a DD statement or data set label of an existing data set. KEYLEN=0 can be coded only in the DCB macro and is ignored if specified in the DD statement.
Key length can be derived from the data class associated with the data set. Key length can also be derived from the JCL keyword LIKE. However, if KEYLEN is specified in the DCB macro, it overrides the value derived from data class or LIKE. For more information, see z/OS MVS JCL Reference.
For PDSEs containing fixed-length blocked records, you must specify LRECL when opened for output. For other types of data sets, you can omit LRECL for BSAM; the system uses the value specified in BLKSIZE. If you want the system to determine the optimum block size for the data set, you must code LRECL. If the LRECL value is coded, it is coded as follows:
Unblocked fixed-length records: the value specified in LRECL must be equal to the value specified in BLKSIZE.
Blocked fixed-length records: the value specified in LRECL must be evenly divisible into the value specified in BLKSIZE. However, except for PDSEs, the LRECL parameter is not checked for validity.
Variable-length records: the value specified in LRECL must include the maximum data length (up to 32752 bytes) plus 4 bytes for the record-descriptor word (RDW).
Undefined-length records: omit LRECL; the actual length is supplied dynamically in a READ/WRITE macro. When an undefined-length record is read, the actual length of the record is returned by the system in the DCBLRECL field of the data control block if your program is not using the large block interface (LBI).
Source: LRECL can be supplied in the DCB macro, in the DCB subparameter of a DD statement, by the problem program before completion of the data control block exit routine, or by the data set label of an existing data set.
Record length can be derived from the data class associated with the data set. Record length can also be derived from the JCL keyword LIKE. For undefined-length records, if LRECL is specified in the DCB macro, it overrides the value derived from data class or LIKE. For more information, see z/OS MVS JCL Reference.
All BPAM READ and WRITE macros issued must be tested for completion using a CHECK macro. MACRF does not require any coding to specify that a CHECK macro is to be used.
Source: MACRF must be specified in the DCB macro.
To request the system to default a value for NCP other than 1, you must supply a DCBE and set MULTSDN to nonzero. The system will update DCBNCP with the system-defaulted NCP (SDN) before the DCB OPEN exit is given control. This allows you to give the system indicators without being dependent on device information such as blocks per track. If you change parameters in the OPEN exit which would cause recalculation of system-determined block size, or you change block size, the SDN will be re-derived after the OPEN exit and stored in the DCBNCP.
Source: NCP can be supplied in the DCB macro, in the DCB subparameter of a DD statement, or by the problem program before completion of the data control block open exit routine.
OPTCD=W is ignored for PDSEs.
Source: OPTCD can be supplied in the DCB macro, in the DCB subparameter of a DD statement, or by the problem program before an OPEN macro is issued to open the data set. However, all optional services must be requested from the same source.
Source: RECFM can be supplied in the DCB macro, in the DCB subparameter of a DD statement, by the problem program before completion of the data control block exit routine, or by the data set label of an existing data set.
Record format can be derived from the data class associated with the data set. Record format can also be derived from the JCL keyword LIKE. However, if RECFM is specified in the DCB macro, it overrides the value derived from data class or LIKE. For more information, see z/OS MVS JCL Reference.
The system detects I/O errors asynchronously. It calls your SYNAD routine synchronously (hence the name SYNAD) when you issue a CHECK macro for the failed block. If SYNAD is omitted in the DCB and DCBE, the task is abnormally terminated when you issue a CHECK and an uncorrectable input/output error occurred.
The error analysis routine must not use the save area pointed to by register 13. The system does not restore registers when it regains control from the error analysis routine. The error analysis routine can issue a RETURN macro that uses the address in register 14 to return control to the system. If control is returned in this manner, the system returns control to the problem program and proceeds as though no error had been found.
SYNAD receives control in the addressing mode in which the CHECK macro was issued. On return from a SYNADAF or SYNADRLS macro issued in the SYNAD routine, the high order byte of register 15 will be unpredictable. Therefore, callers of SYNADAF or SYNADRLS in 31-bit addressing mode must either not use register 15 as a base register or restore the high order bytes on return from SYNADAF or SYNADRLS.
Source: SYNAD can be supplied in the DCB macro or by the problem program. The problem program can also change the error routine address at any time.