z/OS DFSMS Managing Catalogs
Previous topic | Next topic | Contents | Contact z/OS | Library | PDF


MODIFY CATALOG Command Syntax

z/OS DFSMS Managing Catalogs
SC23-6853-00

This section contains an explanation of the syntax and parameters of the MODIFY CATALOG command. Use this command to communicate with the catalog address space, in order to display information or request services.

When a system console operator issues any MODIFY CATALOG command except for MODIFY CATALOG,RESTART, messages return to that system console exclusively. If the system console operator issues the MODIFY CATALOG,RESTART, command, messages are returned to the master console and the console issuing the MODIFY CATALOG,RESTART. For information on system messages and abend codes, refer to z/OS MVS System Messages, Vol 1 (ABA-AOM) through z/OS MVS System Messages, Vol 10 (IXC-IZP), and z/OS MVS System Codes.

where:

ABEND(task)[,FORCE]
specifies a CAS task to be abnormally ended with abend code C1A (for the SYSPCMD and SYSPQUI tasks) or abend code 91A (for all other tasks). Any catalog request in process at the time of the abnormal ending is redriven one time. The task identifier can be specified as:
id
To abnormally end the task with this unique CAS identifier. If id is specified, the optional FORCE parameter may also be specified:
FORCE
To abnormally end an active service task, even if the service task is in recall.
Restriction: Do not use FORCE unless the address space or task that the service task is operating on behalf of has ended abnormally.
hextaskaddr
To abnormally end the task whose CAS service task has this four byte hexadecimal address.
ALLOCATE
To terminate the CAS allocation task (IGG0CLGE) and attach a new CAS allocation task.
ANALYSIS
To terminate the CAS analysis task (IGG0CLGG) and attach a new CAS analysis task.
ASYNC
To terminate the CAS asynchronous event task (IGG0CLSA) and attach a new CAS asynchronous event task.
MODIFY
To terminate the CAS modify task (IGG0CLGA) and attach a new CAS modify task.
SYSPCMD
To terminate the Sysplex command task with a C1A ABEND; a new sysplex command task will be attached.
SYSPQUI
To terminate the Sysplex quiesce task with a C1A ABEND; a new sysplex quiesce task will be attached.
ALIASLEVEL(n)
specifies the number of data set name qualifiers to be used in the multilevel alias facility catalog search. The alias level is initially set at IPL with the value specified in the SYSCATxx member of SYS1.NUCLEUS. The value n can be an integer between 1 and 4, inclusive.
ALLOCATE(catname)[,{NOISC|NOVLF}]
specifies that the catalog is to be allocated to CAS. The catalog must be specified in catname. The optional parameters are:
NOISC
specifies that the in-storage catalog is to be deactivated for the catalog.
NOVLF
specifies that the catalog data space cache is to be deactivated for the catalog.
ALLOCATED[(volser)]
specifies that the name, volume serial number, current allocation count, and status flags for every catalog currently allocated on the system be displayed. This information is listed in message IEC348I.

If you specify a volume serial number (volser), only open catalogs that reside on the specified volume are listed.

CATMAX(nnnn)
specifies the maximum number of catalogs that can be opened concurrently in CAS. When the limit is exceeded, the least recently accessed catalog is closed, freeing the CAS storage it had occupied. Closed catalogs are not unallocated. They remain allocated, but in restart status with no CAS storage. If the new limit is less than the previous limit, all currently open catalogs are closed.

The minimum value is 1 and the maximum value is 9999.

The number specified for nnnn is in decimal.

CLOSE(catname)
specifies that the catalog named in catname is to be closed. All CAS storage for the catalog is released. The catalog is not permanently closed. The next job that requires the catalog opens it.
CONTENTION
displays the Catalog resources for which contention detection is available (ALLOCLCK, SYSIGGV2, SYSZTIOT, and SYSZVVDS), along with the current wait time and associated actions for each.
CONTENTION(resource,wait_time,action-flags)
specifies a new wait time or action (or both) for one of the Catalog resources for which contention detection is available. See Detecting Catalog Resource Contention for complete information.
resource
resource can be any of:
ALLOCLCK
ALLOCLCK is an internal CAS lock that serializes access to CAS allocation task responsible for most catalog allocation events.
SYSIGGV2
The SYSIGGV2 reserve is used to serialize access to associated Catalog records.
SYSZTIOT
The SYSZTIOT resource is used to control access to task input/output table resources.
SYSZVVDS
The SYSZVVDS reserve is used to serialize access to associated VVDS records. The SYSZVVDS reserve, along with the SYSIGGV2 reserve, provide a mechanism to facilitate cross system sharing of catalogs.
The value of resource is case insensitive.
wait_time
Specifies a new wait time, in minutes, that the system lets CAS tasks wait on the resource resource before taking the action specified by action-flags.

The default wait_time is 10 minutes.

The minimum wait_time value is 5 minutes. The maximum value is 9999 minutes.

Specifying a wait_time value of zero disables the resource contention checking for the specified resource.

action-flags
Specifies an action that the system is to take when a catalog service task with an active resource in contention detection is detected past the wait threshold specified for the resource. action-flags can be one of:
N
Notification action only is specified. The notification action generates a contention summary message to the operator the first time a catalog service task with an active resource in contention detection is detected past the wait threshold specified for the resource. Additionally, when a service task initially passes the wait threshold a LOGREC message specific to the task and contention event is created.
Note: Notification cannot be turned off for a resource for which contention detection is active.
NR
Notification and re-drive. In addition to the notification action, the re-drive action is specified. When re-drive is active, the first time a service task with an active resource passes the contention threshold, the service task is abended and the request is resubmitted to catalog for processing. The abend is a 91A, which will produce a dump, unless suppressed, and a LOGREC with error code 246 is generated out of module IGG0CLA9 for the service task. When the service task is abended, all resources it currently holds are freed, and the contention caused due to this request is removed.

NR can also be specified as R or RN.

The default action-flags is "N".

If resource, wait_time, and action-flags are all omitted, the MODIFY CONTENTION command displays the Catalog resources for which contention detection is available (ALLOCLCK, SYSIGGV2, SYSZTIOT, and SYSZVVDS), along with the current wait time and associated actions for each.

DISABLE(feature)
disables a particular optional feature, where feature can be any one of the following:
AUTOTUNING
indicates that the Catalog Address Space should not attempt to improve performance of any catalog on this system by modifying the number of data and index buffers and VSAM strings on the current system.
BCSCHECK
disables verification of the BCS record structure before the record is written to ensure valid records are written to the catalog. An RC14 RSN46 dump will be taken and the operation failed if an invalid BCS record is detected.
DELFORCEWNG
disables the warning message IDC1997I or IDC1998I when attempting to use the DELETE VVDS RECOVERY or DELETE USERCATALOG FORCE command.
DELRECOVWNG
specifies that message IDC1999I should not be issued if a DELETE UCAT RECOVERY command is attempted.

DELRECOVWNG is disabled, by default.

DSNCHECK
disables syntax checking on names being added to a catalog.
ENQCHECK
disables the search for outstanding SYSIGGV2 enqueues at the end of a CAS service task request.
EXTENDEDALIAS
disables the ability to create extension records for user catalog aliases on the current system.

EXTENDEDALIAS is disabled, by default.

SYMREC
specifies that SYMREC records are not created. Use this option to temporarily disable the creation of SYMREC records. For example, if a problem is causing repeated creation of SYMREC records and this is disrupting how well you are able to manage of the SYMREC target data set, you can disable the SYMREC records.
UPDTFAIL
disables the message IEC390I when a VSAM update request against a catalog has been abnormally terminated. This message is intended to alert the installation that potential catalog damage may have resulted from the incomplete request. The default for this option is enabled.
VVRCHECK
disables enhanced VVR checking on VVDS I/O.

VVRCHECK is disabled, by default.

{DUMPON|DUMPOFF}
specifies whether or not CAS dynamic dumping is to occur. Dynamic dumping by CAS does not occur unless you specify DUMPON. You can use these DUMPON commands for problem solving: 
              MODIFY CATALOG,DUMPON
              MODIFY CATALOG,DUMPON(rc,rsn,mm)
              MODIFY CATALOG,DUMPON(rc,rsn,mm,cnt)
where:
rc
Specifies the catalog return code in decimal format (one to three characters from 0 to 255), or * for wild card searches.
rsn
Specifies the catalog reason code in decimal format (one to three characters from 0 to 255), or * for wild card searches.
mm
Specifies the catalog module identifier in CAS, or ** for wild card searches.
cnt
Specifies to capture a dump on the nth occurrence of the condition (one to three characters from 1 to 999). The default value is '1' to cause a dump to be captured on the first occurrence of the condition.
For example:

MODIFY CATALOG,DUMPON(8,42,**) creates a dump for any return code 8, reason code 42, and for any module that detected the error.

You can use the options in parentheses that follow the DUMPON parameter to create a dump whenever a given return code, reason code, and module identifier occur. The dump can prove valuable to service personnel for solving problems. Typically, the return code, reason code, and module identifier are available on return from CAS, and printed by IDCAMS. The module identifier corresponds to the last two characters in the catalog module name. For example, the module identifier is A3 for IGG0CLA3.

You can specify the return code, reason code, and module identifiers as a string of asterisks to indicate that any value encountered will match the value of that field. This is referred to as a generic match. All three fields cannot be specified simultaneously using asterisks. Whenever you specify a generic match for a field, it is assumed that field always matches the value that is returned by catalog for a catalog request. As an example: 
   MODIFY CATALOG,DUMPON(008,042,**)
creates a dump for return code 8, and reason code 42, regardless of the module that detects the error.

An option has been provided for a match count to obtain the nth occurrence of a return code, reason code, and module identifier. The match count is decremented by one each time a return code, reason code, and module identifier is set in the catalog address space. If this option is not specified or is set to 000, then the first occurrence causes a dump.

You can set only one set of return codes, reason codes, and module identifiers at a time. Each entry overwrites the previous information. After a match occurs, the information is cleared, and the original DUMPON status is maintained. If you enter DUMPON without the additional options, certain conditions produce dumps automatically. If you create a DUMPON with options, a match causes a dump and the return code, reason code, and module identifier are cleared. The DUMPON status remains on.

You can use MODIFY CATALOG,REPORT,DUMP to view the settings.

The header for the catalog dynamic dump contains the return code and reason code in hex. For example:

  CAS DYNAMIC DUMP-IGG0CLA9 RCX'F6' RSNX'00'
Note: The DUMPON parameter will only work if the module detecting the return and reason codes are not in LPA.
ECSHR(value)
Specifies changes for enhanced catalog sharing (ECS) mode, where value may be one of the following:
AUTOADD
AUTOADD indicates whether ECS-eligible catalogs should be automatically added to the ECS structure. AUTOADD re-enables and causes ECS-eligible catalogs to be automatically added to the ECS structure on the next reference to the catalog. See the ENABLE parameter description above for the conditions that make a catalog eligible. AUTOADD is a sysplex-wide function.
CONNECT
CONNECT causes the system to connect to the ECS structure. The catalog address space issues an IXLCONN request to allocate and connect to the ECS structure or to connect to the already allocated structure.
DISCONNECT
DISCONNECT causes the system to disconnect from the ECS structure. The catalog address space issues an IXLDISC request. Any ECS catalogs in the structure are removed, and will subsequently be shared via the VVDS sharing mode.
ENABLE,catname
ENABLE causes the named catalog (catname) that is temporarily ineligible to be enabled to the ECS structure if all the following conditions are true:
  • The catalog has the ECSHARING attribute
  • The catalog has shareoptions(3 4)
  • The catalog resides on a volume that is defined as shared
  • The system is connected to the ECS structure
If any of the above conditions are not true, the request is rejected. The issuer of this command should ensure that all current or potential sharers of the catalog are capable of ECS. Otherwise, manual intervention might be required to return to the VVDS sharing protocol.
ENABLEALL
ENABLEALL causes all temporarily ineligible catalogs known to CAS to be enabled for ECS.
REMOVE,catname
REMOVE causes the named catalog (catname) to be removed from the ECS structure, thereby affecting all systems sharing this catalog. The sharing protocol then reverts to the VVDS method. The catalog will not automatically be added to the ECS structure (even if AUTOADD is currently enabled) until the catalog is re-enabled for ECS activity by one of the following:
  • The MODIFY CATALOG,ECSHR(ENABLE) command is issued for the catalog
  • The MODIFY CATALOG,ECSHR(ENABLEALL) command is issued
  • The MODIFY CATALOG,ECSHR(AUTOADD) command is reissued.
STATUS
STATUS causes the status of each catalog that has been referenced since the last IPL to be displayed in message IEC380I. The message includes the status of the CF connection as well as the ECS status of each catalog.
STATUS,catname
STATUS causes the status for the named catalog (catname) to be displayed in message IEC380I. The message includes the status of the CF connection as well as the ECS status of the named catalog.
ENABLE(feature)
enables a particular optional feature, where feature can be any one of the following:
AUTOTUNING
Indicates that the Catalog Address Space should automatically attempt to improve performance of catalogs by modifying the number of data and index buffers and VSAM strings on the current system. This is the default value.
BCSCHECK
Enables verification of the BCS record structure before the record is written to ensure valid records are written to the catalog. An RC14 RSN46 dump will be taken and the operation failed if an invalid BCS record is detected.
DELFORCEWNG
enables issuance of messages IDC1997I and IDC1998I when a DELETE VVDS RECOVERY or DELETE USERCATALOG FORCE are performed.
DELRECOVWNG
specifies that message IDC1999I be issued if a DELETE UCAT RECOVERY command is attempted.
DSNCHECK
enables syntax checking of data set names being added to a catalog.

DSNCHECK is enabled by default.

ENQCHECK
enables the search for outstanding SYSIGGV2 enqueues at the end of a CAS service task request. Enabling this check will cause increased CPU time and degraded performance and is not recommended for general use. This request will cause CAS to set a DUMPON for an RC246 RSN244 error and will take a dump when it finds an outstanding SYSIGGV2 resource is owned by the finished request. Please send the dump to the IBM® Service Center.
EXTENDEDALIAS
enables the ability to create extension records for user catalog aliases on the current system. Note that you should only enable this feature when all systems in the sysplex are V1R13 or greater.
SYMREC
specifies that SYMREC records are to be created. Use this option to reset the default value if you have disabled the creation of SYMREC records using the MODIFY CATALOG, DISABLE(SYMREC) command.

SYMREC is enabled by default.

UPDTFAIL
enables the message IEC390I to notify the operator when a VSAM request to update a catalog fails abnormally. This notification is designed to alert the installation that a catalog may be damaged by an incomplete update request against a catalog. The default is that this feature is enabled.

UPDTFAIL is enabled by default.

VVRCHECK
enables enhanced VVDS record validation during VVDS I/O.
END(id)[,{REDRIVE|NOREDRIVE}][,FORCE]
specifies that the task identified by id is to be ended. This is the preferred method of ending a CAS task. The subparameters are:
id
specifies the unique task identification.
REDRIVE
specifies that any catalog request that is in process at the time of the abnormal ending is to be redriven. The CAS task is abnormally ended with abend code 91A. The MODIFY CATALOG,END(xx),REDRIVE command may be entered as many times as necessary for a given catalog request.
NOREDRIVE
specifies that any catalog request that is in process at the time of the abnormal ending fails with catalog return code 246. The CAS task is abnormally ended with abend code 71A. NOREDRIVE is the default.
FORCE
specifies the abnormal ending of an active service task, even if it is in recall.
Restriction: Do not use FORCE unless the address space or task that the service task is operating on behalf of has ended abnormally.
ENTRY[(csectname)]
specifies that the starting addresses, the FMIDs, and the PTF/APAR levels of all the modules in the catalog load modules IGG0CLX0 (resident in CAS) and IGG0CLHA (resident in the link pack area) are to be displayed. The information is displayed in message IEC349I.

You can specify an individual CSECT in csectname, or you can have information for all entry points displayed by omitting a CSECT name.

The output of this command is probably best viewed on the system log due to its size, if all entry points are requested.

{ISC|NOISC}(catname)
specifies whether the indicated catalog's records are to be held in the in-storage catalog (ISC). The catalog must already be allocated to use this command. ISC specifies the catalog is to use ISC; NOISC specifies the catalog is not to use ISC.

The objective of in-storage cache is to cache only those records that are read directly. Records will not be cached for other types of requests, and therefore in-storage cache is not then in effect. The ISC flag will be turned on the first time a direct read is done. This flag will remain on until that record is no longer in cache. At that point, it will remain off until the next direct read to the catalog.

LIST[(task)]
specifies that currently active CAS service tasks, their related job names, elapsed times, and unique identifications, are to be listed. The information is listed in message IEC347I. The identifiers listed can then be used in other MODIFY CATALOG commands that require a CAS task ID.
All current tasks are listed unless task is specified. The task can be specified as:
id
To list information about the task with this unique identification.
hextaskaddr
To list information about the task whose task control block (TCB) address is this four byte hexadecimal address.
jobname
To list information about all service tasks currently active for this job.
LISTJ(jobname)[,DETAIL]
Specifies that information should be displayed about the status of the catalog service task that is processing the catalog request for the specified jobname. If specified without the DISPLAY keyword, the output for LISTJ(jobname) is similar to that produced by LIST(jobname).
DETAIL
Requests additional optional information. This optional information is primarily internal information about the catalog request. However, some of the information can be useful for diagnosing real-time problems involving the catalog address space. For example, an entry could show that the request has been waiting for a long time for completion of an ENQ. Then the ENQ resource name shown in the detail information could be used with a D GRS,C to find out what task in the system might be causing the wait condition.
MLA(value)
allows the operator to selectively enable, disable, or rebuild the multi-level alias facility control blocks. This may be necessary if the MLA has disabled itself, which is usually indicated by one of the messages IEC369I, IEC370I, IEC374I, or IEC375I. value may be specified as:
DISABLE
to disable MLA processing. When the MLA is disabled, generic searches will fail with return code 194 and reason code 8.
ENABLE
to re-enable and rebuild the MLA control blocks. This may be used to counteract a previous DISABLE command or to activate the MLA after a previous failure during its initialization.
REFRESH
forces a complete rebuild of the MLA control blocks. This can be used when an error is suspected in the MLA structure, but the MLA logic detects no condition that it considers a trigger for a rebuild.
NOTIFYEXTENT(percent)
specifies the percentage of the maximum extents possible for a catalog that is currently allocated. percent is a percentage number from 0-99. (You can omit leading zeros.) A percentage value of zero indicates that normal monitoring is suppressed. The default is 80. The setting specified is retained across catalog restarts, but not IPLs. If the allocated extent threshold exceeds the given threshold for any catalog, the system will issue message IEC361I for that catalog. If a catalog exceeds 90% utilization of the maximum extents, the system will issue message IEC361I even if the threshold has been set to zero (that is, no normal monitoring).
Start of change[RECOVER,{LOCK | UNLOCK | SUSPEND | RESUME}(ucat)] End of change
Start of change specifies a dynamic reset of the catalogs LOCK/UNLOCK or SUSPEND/RESUME VVR setting.

These commands are sysplex in scope and so should only be issued from one system in the sysplex. Each command must either fully complete or time out before another command can take effect. If you issue multiple commands simultaneously from multiple systems, the commands execute on a first come first serve basis with a sysplex scope.

To issue these commands, you must have read access to the IGG.CATLOCK profile, and ALTER authority to the catalog. If the IGG.CATLOCK profile is not defined or the FACILITY class is not active, you cannot use this command.

LOCK
specifies that the system issue a serialized LOCK and CLOSE of the catalog. The LOCK attribute is an existing, permanent attribute of a catalog. Use LOCK to lock a catalog that is being reorganized or recovered. Unauthorized LOCK requests fail with return code 186.

For more information about LOCK, see the IDCAMS DEFINE USERCATALOG LOCK and ALTER ucatname LOCK in z/OS DFSMS Access Method Services Commands.

UNLOCK
specifies that a locked catalog be unlocked for a catalog that was locked in one of the following ways:
  • F CATALOG,RECOVER,LOCK command
  • IDCAMS command DEFINE USERCATALOG
  • IDCAMS command ALTER ucatname LOCK.
See z/OS DFSMS Access Method Services Commands for IDCAMS commands.
SUSPEND
specifies that the system:
  1. Perform a serialized close of the catalog for RLS or non-RLS access across the sysplex.
  2. Obtain serialization to suspend new (unauthorized) catalog requests.
  3. Set the catalog SUSPEND attribute. The SUSPEND attribute is a new catalog state that you can set using one of the following:
    • This command, F CATALOG,RECOVER,SUSPEND
    • IDCAMS command DEFINE USERCATALOG
    • IDCAMS command ALTER ucatname SUSPEND.
RESUME
specifies that catalogs suspended either by the F CATALOG or IDCAMS commands resume processing. This command also resets the SUSPEND attribute.
ucat
Specifies the catalog name or names for the RECOVER command. You can specify multiple catalogs to recover in one command using wildcards.

The user performing the forward recovery must be authorized as follows: If you have READ access to the IGG.CATLOCK profile and ALTER authority to the catalog, you can lock, unlock, suspend, or resume a catalog. If you have READ access to the IGG.CATLOCK profile, you can access and repair a locked or suspended catalog. If the IGG.CATLOCK profile is not defined, or the FACILITY class is not active, you cannot lock, unlock, suspend, or resume a catalog. The new commands may time out after x minutes and will result in a reversal of the command. Issuing the LOCK or SUSPEND command cannot cancel (reverse) a executing UNLOCK or RESUME command or vice versa. Each command must fully complete or time out, before another command will take effect. Multiple commands may be simultaneously issued from multiple systems, however, the commands will execute on a first come first serve basis.

End of change
REPORT
provides basic information about some of the current limits and installation-specified defaults that are selected for the catalog address space.
REPORT,CACHE[(catname)]
causes general information on catalog cache status for all catalogs currently active in the catalog address space to be listed. The report generated shows information useful in evaluating the catalog cache performance for the listed catalogs. If you specify a catalog name (catname), performance information will be listed only for that catalog.
REPORT,CATSTATS[(catname)]
lists the I/O statistics and BUFNI, BUFND, and STRNO for all catalogs currently active in the catalog address space. If you specify a catalog name (catname), statistics will be listed for only that catalog.
Start of change REPORT,CATSTATX[({catname | catprefix*})] End of change
Start of change lists the same I/O statistics and settings produced by CATSTATS, and additionally provides CA-Reclaim and CA-Reuse statistics. Output is in the form of a table for each selected catalog. The catname or catprefix* must be specified. If catprefix* is used, all currently open catalogs which match the prefix will be reported on. Caution should be used with the catprefix* option as it can generate a significant amount of WTO output. End of change
REPORT,DUMP
The DUMP option is used to display the current dump status of catalog address space. This dump status can be enabled or disabled by DUMPON and DUMPOFF forms of the MODIFY command.
REPORT,PERFORMANCE
PERFORMANCE lists information about events in CAS that invoke code outside of the catalog component. It shows the total number of occurrences of each event and the average time spent completing that event.
REPORT,PERFORMANCE(RESET)
Use the RESET keyword to reset all performance statistics being accumulated. This allows you to periodically reset the statistical information and gather data to create a profile of the performance of the Catalog Address Space in your environment. The RESET keyword is also helpful in problem determination by allowing you to set the current statistics to zero during a period when performance might be a problem, and gather data specifically for that period.
RESET,CACHE[(catname)]
resets the cache statistics for all catalogs currently active in the Catalog address space. If you specify a catalog name (catname), statistics will be reset only for that catalog.

You can use this command to reset the cache statistics and determine how | much activity the specified catalog gets during a given time period. To see the current cache statistics report, use the F CATALOG,REPORT,CACHE option.

RESET,CATSTATS[(catname)]
resets the I/O statistics for all catalogs currently active in the Catalog address space. If you specify a catalog name (catname), statistics will be reset only for that catalog.

You can use this command to reset the I/O statistics and determine how much activity the specified catalog gets during a given time period. To see the current I/O statistics report, use the F CATALOG,REPORT,CATSTATS option.

RESTART
specifies that CAS is to be restarted in a new address space. The CAS mother task is ended with abend code 81A, and any catalog requests in process at the time are redriven. The RESTART command should only be used when the only other option is an IPL. You should try other versions of the MODIFY command first before you use RESTART to solve catalog or VVDS problems.
Start of changeRLSENABLE | RLSQUIESCE {(ucat) | ,SYSTEM} End of change
Start of change specifies that the specified catalog or catalogs be enabled or quiesced for VSAM record-level sharing (RLS).

These commands are sysplex in scope and result in a sysplex wide enable or quiesce of the catalogs, and so should only be issued from one system in the sysplex. Issuing the RLSENABLE command cannot cancel or reverse a executing RLSQUIESCE command or vice versa. Each command must either fully complete or time out before another command can take effect. If you issue multiple commands simultaneously from multiple systems, the commands execute on a first come first serve basis with a sysplex scope.

Catalog requests will be suspended during the process of enabling or quiescing RLS access for catalogs. No catalog requests will fail as a result of the enable or quiesce.

ucat
Specifies the catalog name or names for the RLSENABLE | RLSQUIESCE command. ucat can be specified as:
  • ucat, specifying an individual catalog using a fully qualified catalog name. The catalog name specified must be connected to active master catalog.
  • ucat*, specifying a list of catalogs using a partially qualified catalog name. The system resolves the list of catalogs from the master catalog that's active on the system where you issue the command.
SYSTEM
Specifies that RLSENABLE or RLSQUIESCE impact all catalogs across the sysplex opened for the system the command is issued from.
  • RLSENABLE,SYSTEM closes all non-RLS catalogs across the sysplex opened on the system the command is issued from. Once the non-RLS catalogs are closed, the RLS QUIESCE attribute is set to NO in the catalogs’ VVR entry. The next reference will access the catalogs for RLS.
  • RLSQUIESCE,SYSTEM closes all RLS catalogs across the sysplex opened for the system the command is issued from. Once the RLS catalogs are closed, the RLS QUIESCE attribute is set to YES in the catalogs’ VVR entry. The next reference will access the catalogs for non RLS.
End of change
{SYS%ON|SYS%OFF}
specifies that SYS% conversion to SYS1 either is (SYS%ON) or is not (SYS%OFF) to occur. The default setting for SYS% conversion is set during system initialization.
TAKEDUMP
causes the Catalog Address Space to issue an SVCDUMP using the proper dump options to ensure all of the data needed to diagnose catalog problems is available. This eliminates the need for a user to issue an MVS™ DUMP command and potentially omit vital dump parameters needed for the problem.
TAKEDUMP(SYSPLEX)
causes the issuance of sysplex-wide dumps. The dump of each system includes the Catalog, Master, and SMSVSAM address spaces and the SMSVSAM data spaces. Because these dumps will be large, you should ensure the dump data sets are large enough to handle this much data.
TASKMAX(nnn)
Start of change specifies the maximum number of CAS service tasks that are attached to process (non-CAS) catalog requests. Once this limit has been reached, further requests for CAS services are delayed until a task control block becomes available.

The value nnn must be in the range 24-360.

The number specified for nnn is in decimal.

End of change
UNALLOCATE[(catname)]
specifies that all catalogs allocated to CAS are to be removed from CAS. The CAS storage used by the catalogs is freed and the devices on which these catalogs reside are also unallocated from CAS.

If you specify a catalog (catname), only the specified catalog is unallocated. If this is the only catalog that resides on the device, the device on which the catalog resides is unallocated from CAS.

VCLOSE(volser)
specifies that the VVDS that resides on the volume with the volume serial number volser is to be closed. The VVDS is reopened by the next request for the VVDS, and new control blocks are built.

Do not use VCLOSE to unallocate a VVDS to vary a volume offline. Use VUNALLOCATE.

{VDUMPON|VDUMPOFF}
specifies whether or not user-initiated VSAM dynamic dumping is to occur. You can use the VDUMPON parameter to create a dump whenever a given combination of PDF code, error code, component code, or return code is encountered. You would usually request such a dump in response to the codes returned in the request parameter list (RPL) feedback area. (See "Return Codes from the Record-Management (Request) MacrosReturn Codes from the Record-Management (Request) Macros" in z/OS DFSMSdfp Diagnosis.) The dump can provide valuable information to IBM service personnel for solving problems.
The VDUMPON command is specified with the following format: 
MODIFY CATALOG,VDUMPON(pdf,rc,compid,error)
where:
pdf
Specifies the VSAM Problem Determination Function code (one to three characters from 0 to 255), or * (asterisk).
rc
Specifies the VSAM return code in decimal format (one to three characters from 0 to 255), or * (asterisk).
compid
Specifies the component code (0 - 5), or * (asterisk).
error
Specifies the VSAM error code in decimal format (one to three characters from 0 to 255), or * (asterisk).
Note:
  1. Specifying an asterisk (*) for any parameter indicates that a wild card search is to be done for that value. Up to three asterisks (without intervening spaces) may be specified where a single asterisk is allowed, but the extra asterisks have no effect on the command's output.
  2. If a parameter is to be omitted, it must be specified as an asterisk (*). For example, VDUMPON(*,*,*,2) is syntactically valid, while VDUMPON(2), VDUMPON( , , ,2), and VDUMPON(2, ,2) are all invalid.
  3. At least one of the parameters must be specified with a value other than asterisks. For example, VDUMPON(*,*,*,*) is not allowed.
  4. User-initiated VSAM dynamic dumping does not occur unless you specify VDUMPON.
  5. You can set only one VDUMPON at a time. Each entry overwrites the previous information. After a match occurs, the information is cleared and no further user-initiated dumps will be taken.
For example: 
MODIFY CATALOG,VDUMPON(*,8,*,20)
requests a dump for any return code 8, error code 20 (exclusive control conflict), with any PDF code and any component code.
z/OS® acknowledges the command with the following messages: 
IEC351I CATALOG ADDRESS SPACE MODIFY COMMAND ACTIVE
IEC359I CATALOG REPORT VDUMP OUTPUT 503
*CAS*************************************************************
*    STATUS  FUNC CODE  RETURN CODE  COMPONENT  ERROR CODE      *
*       ON      ***         008         ***        020          *
*CAS*************************************************************
IEC352I CATALOG ADDRESS SPACE MODIFY COMMAND COMPLETED

Issuing MODIFY CATALOG,VDUMPOFF will clear the VDUMP options.

{VLF|NOVLF}(catname)
specifies that the catalog data space cache is to be activated (VLF) or deactivated (NOVLF) for the catalog named catname. To activate the catalog data space cache (CDSC) for a catalog, the catalog must already be defined as eligible for CDSC. To deactivate CDSC, the catalog must already be allocated to CDSC.
VUNALLOCATE|NOVUNALLOCATE
specifies that all dynamically allocated VVDSs are to be unallocated from CAS (VUNALLOCATE) when a request is completed, or left allocated to CAS (NOVUNALLOCATE) after a request has completed. By default, VVDSs are unallocated after processing a request. Performance can be improved if you specify NOVUNALLOCATE, because repeated requests for a volume do not result in repeated dynamic allocations for the VVDS.

If you specify NOVUNALLOCATE, VVDSs remain allocated until VUNALLOCATE is issued, CAS is restarted, or the system is IPLed.

VUNALLOCATE can be used to unallocate a VVDS from CAS to allow a volume to be varied offline.

VVDSSPACE(primary,secondary)
Indicates that the Catalog Address Space should use the values specified as the primary and secondary allocation amount in tracks for an implicitly defined VVDS. The default value is ten tracks for both the primary and secondary values. The specified values are preserved across a Catalog Address Space restart, but are not preserved across an IPL.
Parent topic: Working with the Catalog Address Space

Go to the previous page Go to the next page

Notices | Terms of use | Support | Contact z/OS | zFavorites



Copyright IBM Corporation 1990, 2014