The BSDS conversion utility (CSQJUCNV) on z/OS

We can use the CSQJUCNV BSDS conversion utility to convert a version 1 bootstrap data set (BSDS) to version 2. CSQJUCNV runs as a batch job.

A version 1 BSDS supports 6 byte log RBA (Relative Byte Address) values. A version 2 BSDS can be used by queue managers running IBM MQ Version 8.0.0, or later, and supports 8 byte log RBA values. For more information about the change from 6 byte to 8 byte log RBA, see Larger log Relative Byte Address.

Using a version 2 BSDS has implications for coexistence in a queue sharing group. In order to use a version 2 BSDS in a queue sharing group, all queue managers in the queue sharing group must be at one of the following levels:

At Version 9.0.n CD, Version 9.1.0 LTS, or later
At Version 9.0.0 and have been started with OPMODE=(NEWFUNC,800), or OPMODE=(NEWFUNC,900)

before the BSDS can be converted to version 2.

If the queue manager is not in a queue sharing group and you convert the queue manager to use a version 2 BSDS at Version 9.1.0 or later, and subsequently migrate back to Version 9.0.0, ensure that we are using OPMODE=NEWFUNC, 900, otherwise the queue manager will not start.

If the parameters provided specify that the queue manager is in a queue sharing group, the utility checks that the queue managers are at the correct level, before allowing the conversion of the BSDS to proceed.

The converted BSDSs are written to new data sets. These new data sets must be allocated with similar attributes to the current BSDS before the utility is run, and must be empty. A version 2 BSDS contains more data than a version 1 BSDS, therefore, we must ensure that the new data sets are allocated with sufficient available space. The sample JCL in thlqual.SCSQPROC(CSQ4BSDS) contains the recommended values when defining a new BSDS.

The current BSDSs are not modified and can be used to start the queue manager, should the attempt to convert the BSDSs and restart the queue manager with the new BSDS be unsuccessful.

Important:

Only run this utility when the queue manager that owns the BSDS is stopped.
Do not attempt to start the queue manager with the new BSDS until the utility has completed successfully. If a queue manager is started with a BSDS that is the output of an unsuccessful or incomplete conversion, it terminates with reason code 00D10121.
To use this utility, your user ID of the job must have read and write access to both the old and new BSDSs.

Invoking the CSQJUCNV utility
Syntax, keywords, and parameters
Data definition (DD) statements

Invoking the CSQJUCNV utility

The utility runs as a z/OS batch program. Figure 1 shows an example of the JCL used to invoke the CSQJUCNV utility for a queue manager that is a member of a queue sharing group.

Figure 1. Sample JCL to invoke the CSQJUCNV utility

//CONVERT EXEC PGM=CSQJUCNV,REGION=32M,
//             PARM=('INQSG,qsgname,dsgname,db2ssid')
//STEPLIB  DD DSN=thlqual.SCSQAUTH,DISP=SHR
//         DD DSN=thlqual.SCSQANLE,DISP=SHR
//         DD DSN=db2qual.SDSNLOAD,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSUT1   DD DSN=hlq.BSDS01,DISP=SHR
//SYSUT2   DD DSN=hlq.BSDS02,DISP=SHR
//SYSUT3   DD DSN=newhlq.BSDS01,DISP=OLD
//SYSUT4   DD DSN=newhlq.BSDS02,DISP=OLD

Sample JCL to run the utility is also provided in thlqual.SCSQPROC(CSQ4BCNV).

Syntax, keywords, and parameters

BSDS conversion utility

PARM

This field must contain one of the following parameters to indicate whether the queue manager is a member of a queue sharing group or not, followed by any function-specific parameters described in the following text:

INQSG

The queue manager that owns the BSDS is a member of a queue sharing group. Specifying this parameter causes the utility to verify that all members of the queue sharing group meet the requirements for enabling 8 byte log RBA.

See Implement the larger log Relative Byte Address for details on how you perform this task.

The utility terminates with a nonzero reason code, without writing anything to the output BSDS, if this condition is not met.

qsgname: The queue sharing group name
dsgname: The Db2 data sharing group name
db2ssid: The Db2 subsystem ID

NOQSG

The queue manager that owns the BSDS is not a member of a queue sharing group. Attention: Do not specify this parameter for a queue manager that is a member of a queue sharing group. If you do, the BSDS is converted, regardless of whether all members of the queue sharing group meet the requirements for enabling 8 byte log RBA.

Data definition (DD) statements

CSQJUCNV recognizes DD statements with the following DD names:

SYSUT1: Specifies the old BSDS that is to be converted. This statement is required.
SYSUT2: Specifies the second copy of the old BSDS that is to be converted. If we are using dual BSDS, we should specify this.
SYSUT3: Specifies the new, converted BSDS. This statement is required.
SYSUT4: Specifies the second copy of the converted BSDS. This statement is required if the installation uses dual BSDSs; otherwise, it is optional.
SYSPRINT: Contains the output messages from the conversion utility. This statement is required.

Parent topic: Use the IBM MQ utilities on z/OS