Reading and Modifying a Job File Control Block (RDJFCB Macro)

To accomplish the functions that are performed as a result of an OPEN macro instruction, the open routine requires access to information that you have supplied in a data definition (DD) statement. This information is stored by the system in a job file control block (JFCB). Some information is placed into the JFCB when the data set is allocated, while other information is placed there only when the data set is opened. Which fields are updated and when they are updated will vary depending upon factors such as what is specified in the JCL DD statement, what the application does, whether the data set is SMS managed or not, and so on. Fields that have not been updated yet will contain binary zeroes.

In certain applications, you might find it necessary to modify the contents of a JFCB (previously specified in the allocation parameters) before issuing an OPEN macro instruction against a data set. For example, lets suppose that you are adding records to the end of a sequential data set. You might want to add a secondary allocation quantity to allow the existing data set to be extended when the space currently allocated is exhausted. To assist you, the system provides the RDJFCB macro instruction. This macro instruction causes a JFCB to be moved to an area specified in an exit list. Use of the RDJFCB macro instruction with an exit list is shown under Example. When you subsequently issue the OPEN macro instruction, you can specify the TYPE=J operand to open the data set using the JFCB in the area you specified.

You can use RDJFCB and a DCB to learn the data set name, AMP parameters and volume serials of a VSAM data set. You can use any valid combination of MACRF and DSORG in the DCB. The simplest would be DSORG=PS,MACRF=R. You cannot use the JFCB with OPEN TYPE=J to open a VSAM data set.

If you specify the XTIOT, UCB NOCAPTURE or DSAB-above-the-line options of dynamic allocation, then the system creates an XTIOT. With these options, if the access method is not EXCP and the data set is not VSAM, then RDJFCB requires that you code the LOC=ANY option on the DCBE macro, and the NON_VSAM_XTIOT=YES option in the DEVSUPxx member of SYS1.PARMLIB is in effect.

The RDJFCB macro also allows you to retrieve allocation information for the data sets in a concatenation. You can either select data sets or, by default, retrieve the information for all data sets in the concatenation.

You can retrieve the following items:

All JFCBs
All volume serial numbers
Block size limit
The path name (PATH=) associated with any DD. In these cases the data set name in the JFCB is a dummy value.

Type 07 JFCB Exit List Entry describes how you can use RDJFCB to retrieve this information.

Tip: If you set the bit JFCNWRIT in the JFCBTSDM field to 1 before you issue the OPEN macro instruction, the JFCB is not written back at the conclusion of open processing. OPEN TYPE=J normally moves your program's modified copy of the JFCB, to replace the system copy. To ensure that this move is done, your program must set bit zero of the JFCBMASK+4 field to 1. IBM® recommends not setting on JFCNWRIT. If the user JFCB (which the system used to open the data set) is not written back, errors can occur during termination processing for EOV, CLOSE, or the job/step because OPEN might have updated information in the user JFCB which will not be reflected in the system copy of the JFCB. For example, when a nonspecific tape data set is opened, OPEN will update the user supplied JFCB with the volume serial number of the tape selected. However, the system copy of the JFCB will not reflect this volume serial number. This could cause errors during termination processing for EOV, CLOSE, or the job/step (for example, the data set might not be cataloged even though the job requested it).

Start of change Your program can also use the SWAREQ macro to access JFCBs and JFCBXs. It requires your program to access the DSAB or DSABs and the TIOT or XTIOTs. You can use the GETDSAB macro for this and you will need several mapping macros. SWAREQ and GETDSAB are documented in z/OS MVS Programming: Authorized Assembler Services Guide. The RDJFCB macro is designed to be simpler to use and does not require examining system control blocks. End of change

Some of the modifications that can be made to the JFCB include:

Moving the creation and expiration date fields of the DSCB into the JFCB
Modifying the number-of-volumes field in the JFCB
The number-of-volumes field can be modified only to be a value not greater than the total number of volume serial numbers available in the JFCB and any JFCBXs (extensions). The JFCB can have five volume serial numbers. Each JFCBX can have 15 volume serial numbers. Whether or not a JFCBX is required and how many JFCBXs are required is determined during data set allocation. A JFCBX cannot be dynamically created after allocation. Therefore, the maximum value of the number-of- volumes field is based on the JFCB and how many JFCBXs exist. Setting the number-of-volumes field to a value greater than that maximum will not cause a JFCBX to be dynamically created.
Moving the DCB fields from the DSCB into the JFCB
Adding volume serial numbers to the JFCB (see RDJFCB Security)
Volume serial numbers in excess of five are written to the JFCBX (extension). The JFCBX cannot be modified by user programs.
Modifying the sequence number field of the volume in the JFCB. For DISP=NEW the modified volume sequence will be honored during OPEN TYPE=J only for tape and only when the file sequence number in the JFCB is also modified.
Modifying the sequence number field of the data set in the JFCB. This specifies the file for a subsequent OPEN TYPE=J to process. You can use this technique to write many data sets on a tape volume or set of volumes. Use RDJFCB and increase the sequence number of the data set by 1 before each OPEN TYPE=J. If the device supports buffered tape marks, you can obtain significantly better performance by requesting the SYNC=NONE option on the DCBE macro. It allows the device to enter "streaming mode" and to write tape marks much faster. A side effect is that any I/O error can be reflected at an unpredictable time. This can result in an ABEND in OPEN or CLOSE for a user data block. It also means that if a device malfunction occurs, it might result in the loss of more than one data set that the application had closed previously. To position rapidly to a tape data set other than the next data set, you can use the technique described in High-Speed Cartridge Tape Positioning.
Changing the data set name field or member field in the JFCB. See RDJFCB Security and RDJFCB Use by Authorized Programs. You can open a VTOC by reading the JFCB, changing the data set name to 44 bytes of X'04' and then issuing the OPEN macro with TYPE=J. Use BSAM or EXCP. If you use BSAM, also code RECFM=F, KEYLEN=44 and BLKSIZE=96 on the DCB macro. For an extended address volume the DCB macro must point to a DCBE where the EADSCB=OK keyword is specified. You'll find examples of opening an EXCP DCB for a VTOC in Example of Using the CVAFFILT Macro and Example of using the CVAFSEQ macro to process a volume in physical sequential order.
Setting bit JFCDQDSP in field JFCBFLG3 to invoke the tape volume DEQ at demount facility (see DEQ at Demount Facility for Tape Volumes)
Modifying the JFCRBIDO field in the JFCB to cause high-speed positioning to a specific data block on a tape volume on a device that supports cartridge tapes (see High-Speed Cartridge Tape Positioning)
Setting bit JFCNDSCB to prevent OPEN from merging fields from the data set label to the JFCB. This means that you must supply the information from other sources, such as the JFCB or the DCB. A data set label is a DSCB or standard tape label. This bit does not control all fields. For example it does not control the creation and expiration dates. Note that if you set this bit on, it can cause incorrect positioning in the data set after an automatic step restart when using DISP=MOD or the OPEN macro with the EXTEND option. Setting this bit on can interfere with the system correcting JFCBDSCB (TTR of DSCB on first volume). Setting this bit on is not a good programming practice because it depends on internal system logic.
Setting bit JFCNDCB to prevent OPEN from merging fields from the DCB to the JFCB. This interferes with correct information being set in the data set label and it interferes with OPEN doing certain checks. Setting this bit on is not a good programming practice because it depends on internal system logic.
Setting bit JFCBLKSZ to indicate that the JFCB block size field has been set to zero by the application and that OPEN needs to set the block size value in the SIOT extension, if applicable, to zero as well. OPEN will also reset JFCBLKSZ off.

The secondary allocation quantity will be moved from the DSCB into the JFCB unless prevented by the setting of JFCNWRIT or JFCNDSCB.