Formatting page sets (FORMAT) on z/OS®

We 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, we can format up to 100 page sets in a single invocation of the utility program. Use the FORCE keyword to reuse existing data sets.

We 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
  • to reinstate a page set with old data, use FORMAT with the TYPE(REPLACE) option
  • to 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

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 we 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)

FORMAT FORCE PAGES(1)PAGES(nnn)TYPE(RECOVER)TYPE(NEW)TYPE(REPLACE)


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. For more information about DEFINE CLUSTER, see the DFSMS/MVS™ Access Method Services for VSAM or the DFSMS/MVS Access Method Services for the Integrated Catalog Facility manual.

    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.


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. We cannot format page sets that belong to a queue manager that is still running.
  2. When we use FORMAT, it is not necessary to specify a queue manager name.
  3. If we 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 we use data set names in which the queue manager name is a high-level qualifier, we 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.