[z/OS]

Formatting page sets (FORMAT) on z/OS®

You can use the CSQUTIL program to format page sets.

Use the FORMAT function to format page sets on all data sets specified by DDnames CSQP0000 through CSQP0099. In this way, you can format up to 100 page sets in a single invocation of the utility program. Use the FORCE keyword to reuse existing data sets.

You can also use the FORMAT function to change the recovery processing that is performed against page sets when the queue manager starts, using the TYPE keyword. This can assist in changing or recovering page sets, or reintroducing page sets that have been offline or suspended.

In summary, to:
  • Reinstate a page set with no data, use FORMAT with the TYPE(NEW) option
  • Reinstate a page set with old data, use FORMAT with the TYPE(REPLACE) option
  • Reinstate a page set with old data made up-to-date, do not use FORMAT but start the queue manager with a backed-up copy of the page set
  • [MQ 9.2.0 Jul 2020]Reintroduce a page set that was offline when the queue manager was backwards migrated using the START QMGR BACKMIG command, use FORMAT with the TYPE(REINTRODUCE) option.

Page sets have identifiers (PSIDs, in the range 00 through 99) which are established by the DDnames used for the data sets in the queue manager started task procedure; DDname CSQP00nn specifies the page set with identifier nn. The DDnames you use for the FORMAT function do not have to correspond to those used in the queue manager started task procedure, and do not therefore have any significance regarding page set identifiers.

Page set management (FORMAT)

Read syntax diagramSkip visual syntax diagram FORMAT FORCE PAGES(1)PAGES(nnn)TYPE(RECOVER)TYPE(NEW)TYPE(REPLACE)TYPE(REINTRODUCE)TARGVER(target-vrm)

Keywords and parameters

FORCE
Specifies that existing data sets are to be reused without having to delete and redefine them first. You must define any page sets you want to reuse with the REUSE attribute in the AMS DEFINE CLUSTER statement.

See the Optional Parameters section of the DEFINE CLUSTER command for more information on REUSE.

The following code is an example on how you set REUSE:
//IDCAMS EXEC PGM=IDCAMS,REGION=0M
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
ALTER VICY.MQOM.PSID04 REUSE
/*

To undo the REUSE option, use the ALTER attribute to change the REUSE parameter to NOREUSE.

The FORCE keyword is not valid if TYPE(REPLACE) is specified.

PAGES (nnn)
Specifies the minimum number of pages to format in each page set. This enables a data set that spans more than one volume to be formatted.

Formatting of the data set is always done in whole space allocations, as specified as primary or secondary quantities when the data set is defined. The number of space allocations formatted is the minimum necessary to provide the requested number of pages; if there is insufficient data set space available, as many extents as can be obtained are formatted. If an existing page set is being reused (with the FORCE keyword), the whole page set is formatted, if that is larger.

The number of pages must be in the range 1 through 16 777 213 (because the maximum page set size is 64 GB (gigabytes)). The default is 1.

The PAGES keyword is not valid if TYPE(REPLACE) is specified.

TYPE
Specifies the type of recovery processing that is performed against queue manager page sets. Values are:
RECOVER

Use RECOVER for a data set that is to be a new page set for a queue manager (that is, to have a PSID which was never been used before).

This is the default.

The data set is formatted, and any messages or other data are erased. If a DDname is added to the queue manager's started task procedure for the new PSID that specifies this data set, it will be recognized as a new page set when the queue manager is restarted.

If such a data set was used as a page set with a PSID that has been used before, on restart the queue manager attempts to recover all queues and their messages that use storage classes that reference the page set from the time the page set was first used. This may make restart a lengthy process, and is unlikely to be what is wanted.

NEW

Use NEW for a data set that is to be a page set with a PSID that has been used before for a queue manager and with data that can be discarded, to restart a failed queue manager quickly or to reintroduce the page set after it has been offline or suspended.

The data set is formatted, and any messages or other data are erased. When the queue manager is restarted, with a DDname for the old PSID that specifies this data set, it does not recover the page set but treats it as if it has been newly added to the queue manager, and any historical information about it is discarded. All queues that use storage classes referencing this page set are cleared of all messages, in a similar fashion to the way that nonpersistent messages are cleared during restart processing. This means that there will be no effect on restart time.

REPLACE

Use REPLACE for a data set with a PSID that has been used before for a queue manager and with data that is known to be consistent and up to date, to reintroduce the page set after being offline or suspended.

The data set is not formatted, and any messages or other data are preserved. When the queue manager is restarted with a DDname for the PSID that specifies this data set, it does not recover the page set but treats it as if it has never been offline, or suspended, and any historical information about it is retained. All queues that use storage classes that reference the page set keep their messages. This means that there will be no effect on restart time.

This option will only be successful if the page set is in a consistent state; that is, on its last use the queue manager was terminated normally by a STOP QMGR MODE(FORCE) or MODE(QUIESCE) command.

[MQ 9.2.0 Jul 2020]REINTRODUCE
Use REINTRODUCE for a data set that was offline when the queue manager was backward migrated using the START QMGR BACKMIG command, and you want to reintroduce the page set with old data made up-to-date, or if you want to reintroduce the data set with old data.
If you want to reintroduce the data set with old data, you also need to subsequently run FORMAT TYPE(REPLACE) CSQUTIL against the data set.
The data set is migrated to the version specified by the TARGVER keyword, and the data is not changed.
TYPE(REINTRODUCE) is not valid for page set zero.
The version of CSQUTIL must match the version of queue manager that last used the IBM MQ page set when TYPE(REINTRODUCE) is used. The command fails if migration is not allowed to the version specified by the TARGVER keyword.
You can also use TYPE(NEW) or TYPE(RECOVER) with CSQUTIL, at the migration target version to reintroduce the page set at that version.
[MQ 9.2.0 Jul 2020]TARGVER
Specifies the target version for the formatted page set
target-vrm
The version, release and modification number for the target version for TYPE(REINTRODUCE), for example 910.
This must be an LTS release, otherwise a CSQU104E message is output, and the utility exits with a return code of 12.
Attention: TARGVER is not valid if you do not also specify TYPE(REINTRODUCE).

Example

Figure 1 illustrates how the FORMAT command is invoked from CSQUTIL. In this example, two page sets, referenced by CSQP0000 and CSQP0003, are formatted by CSQUTIL.
Figure 1. Sample JCL for the FORMAT function of CSQUTIL

//FORMAT   EXEC PGM=CSQUTIL
//STEPLIB  DD   DISP=SHR,DSN=thlqual.SCSQANLE
//         DD   DISP=SHR,DSN=thlqual.SCSQAUTH
//CSQP0000 DD   DISP=OLD,DSN=pageset.dsname0
//CSQP0003 DD   DISP=OLD,DSN=pageset.dsname3
//SYSPRINT DD   SYSOUT=*
//SYSIN    DD   *
FORMAT
/*
Figure 2 illustrates how the FORMAT command with the TYPE option is invoked from CSQUTIL. In this example, the page set referenced by CSQP0003 is formatted by CSQUTIL.
Figure 2. Sample JCL for the FORMAT function of CSQUTIL with the TYPE option

//FORMAT   EXEC PGM=CSQUTIL 
//STEPLIB  DD   DISP=SHR,DSN=thlqual.SCSQANLE
//         DD   DISP=SHR,DSN=thlqual.SCSQAUTH
//CSQP0003 DD   DISP=OLD,DSN=page set.dsname3
//SYSPRINT DD   SYSOUT=*
//SYSIN    DD   *
FORMAT TYPE(RECOVER)  
/*

Usage notes

  1. You cannot format page sets that belong to a queue manager that is still running.
  2. When you use FORMAT, it is not necessary to specify a queue manager name.
  3. If you use TYPE(REPLACE), recovery logs starting from when the page set was first used with the queue manager, or from when the page set was last formatted, must be available.
  4. If you use data set names in which the queue manager name is a high-level qualifier, you can more easily identify which page sets are used by which queue manager, if more than one queue manager is defined.
  5. Any update to a resource due to the resolution of an incomplete unit of work, where the update relates to a page on a page set that has been formatted with TYPE(REPLACE) or TYPE(NEW), is not honored. The update to the resource is lost.
  6. If there is an error when formatting a page set, it does not prevent other page sets from being formatted, although the FORMAT function is considered to have failed.
  7. Failure of this function does not prevent other CSQUTIL functions being attempted.