Enhanced Catalog Sharing and Management - IBM Redbooks

Enhanced Catalog Sharing and Management 

Jon Tate, Frank Byrne, Klaus Stanislawiak, Wolfgang Wettig 

International Technical Support Organization 

www.redbooks.ibm.com 

SG24-5594-00

International Technical Support Organization 


July 1999 

SG24-5594-00

Take Note! 

Before using this information and the product it supports, be sure to read the general information in 

Appendix C, “Special Notices” on page 117. 

First Edition (July 1999) 

This edition applies to Version 1, Release 5 of DFSMS/MVS, Program Number 

5695-DF1 for use with the OS/390 Operating System. 

Comments may be addressed to: 

IBM Corporation, International Technical Support Organization 

Dept. 471F Building 80-E2 

650 Harry Road 

San Jose, California 95120-6099 

When you send information to IBM, you grant IBM a non-exclusive right to use or 

distribute the information in any way it believes appropriate without incurring any 

obligation to you. 

© Copyright International Business Machines Corporation 1999. All rights reserved. 

Note to U.S Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions 

set forth in GSA ADP Schedule Contract with IBM Corp.

Contents 

Figures ......................................................vii 

Tables .......................................................ix 

Preface ......................................................xi 

The Team That Wrote This Redbook . ...................................xi 

CommentsWelcome ............................................... xii 

Chapter 1. Introduction. .........................................1 

1.1 ICFCatalogStructureandEvolution..............................1 

1.1.1 CatalogStructure ........................................2 

1.1.2 WhereaDataSetisDescribed..............................2 

1.1.3 AccessingCatalogs.......................................4 

1.1.4 CatalogAddressSpace....................................5 

1.2 TapeVolumeCatalogs........................................7 

1.3 AReviewoftheSHAREOPTIONSParameter.......................7 

1.3.1 DefiningtheLevelofSharingwithinaSystem...................8 

1.3.2 DefiningtheLevelofSharingAcrossSystems ..................8 

1.4 CatalogEvolution............................................8 

1.5 ParallelSysplexPerformanceConsiderationsandSolutions............9 

1.5.1 Non-CatalogSolution ....................................10 

1.5.2 Enhanced Catalog Sharing ................................10 

1.5.3 Coupling Facility Structure Terminology and Connectivity .........12 

1.6 DataSetNaminginaParallelSysplex ...........................13 

Chapter 2. Planning ...........................................15 

2.1 Planning for the New Functions of DFSMS/MVS 1.5 .................15 

2.2 Planning for ECS Implementation . . . ............................16 

2.2.1 DeterminingWhichCatalogsUtilizeECS .....................16 

2.2.2 DeterminingtheNumberofCatalogs.........................16 

2.2.3 CacheStructureDescription...............................16 

2.2.4 SecurityConsiderations ..................................17 

2.2.5 CacheStructureSizing...................................17 

2.2.6 ActivatingECS .........................................18 

2.2.7 LossofECSMode ......................................18 

2.2.8 Operational Issues ......................................19 

2.3 Extended Alias Support. ......................................20 

Chapter 3. Implementation ......................................23 

3.1 Implementing Enhanced Catalog Sharing . . . ......................23 

3.1.1 Understanding the ITSO Environment Setup . . .................23 

3.1.2 DefiningtheCFRMPolicy.................................24 

3.1.3 ActivatingtheCFRMPolicy................................25 

3.1.4 Connecting to the CF Structure . ............................26 

3.1.5 SettingtheECSHRAttributeforSelectedCatalogs..............28 

3.1.6 IssuingtheAutomaticAddCommand........................29 

3.2 Implementing Extended Alias Support. ...........................30 

3.2.1 SettingtheSystemSymbols...............................30 

3.2.2 Defining an Extended Alias ................................32 

3.2.3 Referring to an Extended Alias . ............................33 

3.2.4 Extended Alias Support for Catalogs . . . ......................34 

© Copyright IBM Corp. 1999 iii

iv Enhanced Catalog Sharing and Management 

Chapter 4. Operations .........................................35 

4.1 UsingtheModifyCatalogCommand............................ 35 

4.1.1 SettingtheInitialCASOptionsandParameters................ 35 

4.1.2 AllocatingCatalogstotheCAS ............................ 36 

4.1.3 ControllingtheCASEnvironment........................... 36 

4.1.4 ControllingtheStatusofCatalogsintheCAS ................. 37 

4.1.5 ControllingOptionsandSettingsintheCAS .................. 41 

4.1.6 ControllingtheStatusofServiceTasksinCAS................44 

4.1.7 Controlling Enhanced Catalog Sharing in CAS. . . .............. 44 

4.1.8 RestartingCAS........................................ 45 

4.1.9 SysplexConsiderations.................................. 45 

4.2 Operational Procedures . . .................................... 46 

4.2.1 MonitoringtheSharingStatusforCatalogs................... 46 

4.2.2 Monitoring the CF Connection Status for ECS . . . .............. 46 

4.2.3 MonitoringthePerformanceParametersforCAS............... 47 

4.2.4 PerformanceStatistics................................... 47 

4.2.5 ReplacingAMSLISTCATwiththeCatalogSearchInterface...... 52 

Chapter 5. Backup and Recovery ................................ 53 

5.1 Backup .................................................. 53 

5.1.1 Backup Frequency . . .................................... 53 

5.1.2 Backup Techniques . .................................... 53 

5.1.3 DecidingontheBackupTechnique......................... 54 

5.1.4 Backup Utilities ........................................ 54 

5.1.5 ConsiderationsforDevelopingtheBackupProcess............. 57 

5.1.6 Considerations for Developing the Backup Procedures . . ........58 

5.2 TapeVolumeCatalogs ......................................59 

5.2.1 UsingDFSMSdss....................................... 60 

5.2.2 UsingAMSExport...................................... 60 

5.3 Recovery................................................. 61 

5.3.1 DeterminingWhentoRecoveraCatalog..................... 61 

5.3.2 Recovery Techniques and Utility Actions . . ................... 61 

5.3.3 ConsiderationsforDevelopingtheRecoveryProcess........... 61 

5.3.4 Considerations for Developing Recovery Procedures. ........... 63 

5.4 Post-Recovery Updates . . .................................... 64 

5.4.1 Manually Checking for Missing Updates. . . ................... 64 

5.4.2 UsingDFSORTintheCheckingProcess..................... 65 

5.5 Integrated Catalog Forward Recovery Utility . . . ................... 66 

Chapter 6. Analyzing Structural Integrity. ......................... 69 

6.1 StructuralIntegrity.......................................... 69 

6.1.1 WhentoChecktheStructuralIntegrity....................... 69 

6.1.2 HowtoChecktheStructuralIntegrity........................ 69 

6.1.3 The Consequences of Neglecting Structural Integrity. ........... 70 

6.2 SynchronizationErrors ......................................70 

6.2.1 WhatCausesSynchronizationErrors........................ 72 

6.2.2 DetectingSynchronizationErrors........................... 72 

6.2.3 Repairing Synchronization Errors. . ......................... 74 

6.2.4 Utilities and Tools Available for Diagnosis . ................... 76 

6.2.5 VSAM Knowledge Database .............................. 77 

6.3 CatalogSharingProblems....................................77 

6.3.1 ErrorSymptomsDuetoSharingProblems.................... 77 

6.3.2 DeterminingIfaCatalogisActuallyShared...................78

6.4 CASProblemsDuetoCatalogStructuralorSynchronizationErrors.....79 

6.4.1 CAS ABEND or Error Messages ............................79 

6.4.2 CASHangorLockoutSituations............................79 

Appendix A. Catalog Search Interface ..............................83 

A.1 CSISetup....................................................83 

A.2 CSIProgrammingConsiderations..................................84 

A.3 IBM Supplied Sample Programs . ..................................85 

A.4 RealWorldExampleofCSIImplementation..........................87 

Appendix B. What’s Changed and What’s New ......................101 

B.1 MODIFYCATALOGCommandSyntax.............................101 

B.2 New and Changed Messages . . . .................................108 

Appendix C. Special Notices .....................................117 

Appendix D. Related Publications .................................119 

D.1 International Technical Support Organization Publications. .............119 

D.2 Redbooks on CD-ROMs . .......................................119 

D.3 OtherPublications.............................................119 

How to Get ITSO Redbooks. ....................................121 

IBM Redbook Fax Order Form .......................................122 

List of Abbreviations ..........................................123 

Index .......................................................125 

ITSO Redbook Evaluation ......................................133 

v

vi Enhanced Catalog Sharing and Management

Figures 

1. UserAddressSpaceActivityRelatedtoDataSetOpen..................5 

2. CASUsageforDataSetReference..................................6 

3. CASUsageofIntegrityVVRs ......................................9 

4. Integrity VVR Coupling Facility Utilization . ...........................11 

5. StructureDiagramoftheITSOParallelSysplex .......................24 

6. Running the Administrative Data Utility (IXCMIAPU) ....................25 

7. HowtoStartUsingtheCFRMPolicy................................26 

8. CAS ECS Status Display After Connecting to the Coupling Facility ........26 

9. CASConnectFailuretoECSStructureatIPLandStatusDisplay .........27 

10. XCF Structure Display for SYSIGGCAS_ECS. ........................28 

11. AlteringtheECSHRAttribute......................................28 

12. DefiningaUserCatalogwiththeECSHRAttribute.....................29 

13. Enabling the Automatic Add Function and Status Display . . ..............29 

14. Sample Symbol Definitions Parmlib Member (IEASYMxx) . ..............31 

15. DataSetNameResolutionforaSymbolicAliasonDifferentSystems......32 

16. DefininganExtendedAliasUsingaSystemSymbol....................32 

17. Extended Alias Name Resolution without the System Symbol Set . ........33 

18. Extended Alias Name Resolution with the System Symbol Set. ...........33 

19. Using an Extended Alias in JCL. . ..................................34 

20. AllocatedCatalogsStatusDisplay..................................38 

21. CatalogCacheStatisticsReport ...................................38 

22. ECSStatusDisplayWithCatalogsNotUsingECS.....................40 

23. Sample Catalog Report Output . . ..................................41 

24. Sample Catalog Dynamic Dump Report . . ...........................42 

25. SampleCatalogModuleEntryDisplay...............................42 

26. Sample Catalog Performance Report ...............................43 

27. SampleCatalogServiceTasksDisplay..............................44 

28. SampleCatalogTaskDetailDisplay................................44 

29. Performance Report after LISTCAT in ECS Mode. .....................48 

30. Performance Report after LISTCAT in VVDS Sharing Mode. .............49 

31. Performance Report after Allocating 300 Data Sets ECS Active . . . ........50 

32. Performance Report after Allocating 300 Data Sets in VVDS Sharing Mode . 51 

33. IDCAMS EXPORT joblog Sample ..................................55 

34. DFSMSdss Logical Dump joblog Sample . ...........................56 

35. DFSMSdssFullVolumeDumpjoblogSample.........................57 

36. SampleJCLforDFSMSdssVOLCATBackup.........................59 

37. Sample JCL to Create a GDG Base Entry for SMS-Managed GDSs .......60 

38. Sample JCL to Create a GDG Base Entry for a non SMS-Managed volume . 60 

39. SampleJCLtoLockaCatalogbyIDCAMSALTERLOCKCommand......64 

40. Sample JCL to Restore the Most Recent Catalog Backup Copy from a GDS . 64 

41. DFSORTControlStatementstoCollectSMFRecordtype61.............65 

42. ICFRUSimplifiedDataFlow ......................................67 

43. ICF-Catalog BCS, VVDS Dependencies . . ...........................70 

44. SampletoDIAGNOSEaBCSandComparetoTwoVVDSs .............73 

45. SampleJCLtoDIAGNOSEaVVDSandComparetoaBCS.............73 

46. Sample JCL for DFSMSdss to Detect Duplicate or Orphan VVRs . ........74 

47. SampleJCLtoPrintaVVDSbyDFSMSdss..........................76 

48. Sample Output of the DS QT,0CC2,1,UCB Command.. .................79 

49. CatalogStatusDisplayforOpenCatalogs............................80 

50. CatalogTaskandStatusDisplay...................................80 

© Copyright IBM Corp. 1999 vii

viii Enhanced Catalog Sharing and Management 

51. MODIFYCATALOGCommandSyntax .............................101

Tables 

1. LocationofDataSetInformation....................................4 

2. SampleTimingsUsedbyAMSLISTCATandIGGCSILC................11 

3. Sample ECS Structure Sizes for a Currently Supported Coupling Facility . . . 18 

4. MODIFYCATALOGParametersbyResourceType....................37 

5. BackupandRecoveryUtilitiesRelationship..........................61 

6. OverviewofRepairActionsPerformedbyIDCAMS ....................75 

7. SampleTimingsUsedbyIDCAMSLISTCATandIGGCSILC.............86 

© Copyright IBM Corp. 1999 ix

x Enhanced Catalog Sharing and Management

Preface 

This redbook will help you implement, tailor and configure Enhanced Catalog 

Sharing (ECS), which was introduced with DFSMS/MVS 1.5. It uses a concise 

step-by-step approach, taking you through the considerations and sequence of 

tasks necessary to perform a successful implementation of ECS in your Parallel 

Sysplex. 

This redbook gives you a broad understanding of the Integrated Catalog Facility 

(ICF) with respect to its design, structure and evolution. The manner in which 

ECS exploits the Parallel Sysplex architecture is explained, along with the 

performance and recovery benefits that this allows you to enjoy. The changed 

commands and operational considerations for ECS are introduced to allow you to 

take advantage of the new functionality immediately. Additionally, this redbook 

shows how symbolic substitution and Extended Alias Support is implemented, 

and how to realize performance gains by using the Catalog Search Interface 

(CSI) in place of the LISTCAT command. 

This redbook is intended for experienced storage administrators familiar with both 

DFSMSdfp and ICF. New users of DFSMSdfp and ICF may like to read 

DFSMS/MVS V1R5 DFSMSdfp Storage Administration Reference, SC26-4920, 

and also Managing Catalogs, SC26-4914 before reading this redbook, to 

familiarize themselves with the concepts and commands that are covered here. 

This redbook is not intended to give an in-depth understanding of Parallel 

Sysplex. 

First, we introduce the ICF and its evolution, and explain the business problem 

that ECS solves. We show the considerations that installations must take into 

account when planning to implement the ECS solution, and the commands, JCL, 

and operational considerations necessary. We cover backup and recovery 

considerations applicable to ECS and the ICF, and the structural integrity of the 

ECS and the ICF, with preventative and reactive measures that can be taken by 

the user. 

The Team That Wrote This Redbook 

This redbook was produced by a team of specialists from around the world 

working at the International Technical Support Organization, San Jose Center. 

Jon Tate is a project leader for Storage Solutions at the International Technical 

Support Organization, San Jose Center. Before joining the ITSO in 1999, he 

worked in the IBM Technical Support Center, providing level 2 support for IBM 

storage products. Jon has 13 years of experience in storage software and 

management, services and support. 

Frank Byrne is an Advisory Specialist working for the IBM Technical Support 

Center in the UK. He has 30 years of experience in support of OS/390 and its 

predecessors. His areas of expertise include the implementation of Parallel 

Sysplex. 

© Copyright IBM Corp. 1999 xi

Comments Welcome 

xii Enhanced Catalog Sharing and Management 

Klaus Stanislawiak is a systems engineer at Software AG in Darmstadt, 

Germany. He has 18 years of experience working with customers in the areas of 

MVS and OS/390. His areas of expertise include implementation support for 

OS/390, systems and network management, and cross-platform application 

development. 

Wolfgang Wettig is a Senior Advisory Specialist working in IBM Global Services 

PSS Software Support Center in Mainz, Germany for OS/390. He joined IBM in 

1970, and for the first 13 years, worked as a Customer Engineer in the Large 

Systems environment. Since 1983, he has worked in software service and 

support. His areas of expertise include DFSMS/MVS storage management 

software, and he has supported SMS installations since the availability of SMS. 

He has contributed to several other ITSO redbooks. 

Thanks to the following people for their invaluable contributions to this project: 

From the Storage Systems Division - San Jose: 

Charlie Burger 

Pat Choi 

Mike Nelsen 

Mark Thomen 

From the International Technical Support Organization: 

Rich Conway 

Bob Haimowitz 

Mary Lovelace 

From the International Technical Support Organization Publishing Team: 

Joan Bow 

Emma Jacobs 

Yvonne Lyon 

Deanna Polm 

Your comments are important to us! 

We want our redbooks to be as helpful as possible. Please send us your 

comments about this or other redbooks in one of the following ways: 

Fax the evaluation form found in “ITSO Redbook Evaluation” on page 133 to 

the fax number shown on the form. 

Use the on-line evaluation form found at http://www.redbooks.ibm.com/ 

Send your comments in an internet note to redbook@us.ibm.com

Chapter 1. Introduction 

As the number of systems grows over time, and with it the number of catalogs 

increases, this brings with it problems related to the sharing of catalogs across 

these additional systems. Maintaining catalog integrity and the speed with which 

data is retrieved, while sharing the catalog between systems, is a business 

problem for which there have been various attempts at a solution. 

As the technology that surrounds operating systems has evolved over time, a 

solution to this problem has been provided by using the Parallel Sysplex coupling 

facility. This solution is presented here as Enhanced Catalog Sharing (ECS). By 

taking advantage of this solution, you will be able to decrease both CPU (central 

processor usage) and job elapsed time, while maintaining the structural integrity 

of your catalog. 

In this introductory chapter, we describe: 

The ICF structure and evolution 

Tape volume catalogs 

A review of sharing options 

Catalog evolution 

Parallel Sysplex performance considerations and solutions 

Data set naming in a Parallel Sysplex 

After reading this chapter, you will see how the ICF catalog has evolved, why 

ECS is an attractive proposition, how ECS operates in the OS/390 environment, 

and how to take advantage of the solutions offered by the changes introduced by 

DFSMS/MVS Version 1 Release 5. 

Throughout this redbook, the term catalog is defined as the Integrated Catalog 

Facility (ICF) catalog. From January 1, 2000, the two older types of catalog, 

VSAM and CVOL, will no longer function or be supported. Additionally, as ECS 

requires the use of a coupling facility, the term sysplex will be used to indicate a 

Parallel Sysplex. 

Appendix A, “Catalog Search Interface” on page 83 shows samples of the CSI 

and the performance benefits of using CSI versus the LISTCAT command. 

Appendix B, “What’s Changed and What’s New” on page 101 shows the changed 

command syntax and messages introduced with ECS. 

1.1 ICF Catalog Structure and Evolution 

In order to introduce the concepts associated with ECS, we will revisit some of 

the terminology associated with data set access and give a high-level overview of 

the catalog structure associated with the ICF design. 

Catalog structure—where data sets are described, how catalogs are managed, 

catalog evolution, and the catalog performance and flexibility needed in a 

sysplex—are covered in the topics that follow. 

© Copyright IBM Corp. 1999 1

1.1.1 Catalog Structure 

2 Enhanced Catalog Sharing and Management 

The ICF catalog records are stored in two components, the basic catalog 

structure (BCS) and the VSAM volume data set (VVDS). The BCS can be 

considered the catalog, whereas the VVDS can be considered an extension of 

the VTOC. 

The relationship between the BCS and the VVDS is one-to-many. That is, a BCS 

can point to multiple VVDSs and a VVDS can point to multiple BCSs. 

The BCS is a VSAM KSDS, and its primary function is to point to the volumes on 

which a data set is located. The BCS is created when either a user or master 

catalog is defined using Access Method Services (AMS). A BCS does not have to 

be on the same volume as the data set it references, and there can be more than 

one BCS on a volume. 

The VVDS is a VSAM ESDS that contains the information required to process 

VSAM data sets and, in a Storage Management Subsystem (SMS) environment, 

it contains the volume related information for non-VSAM SMS-managed data 

sets. There is one VVDS on each DASD volume that contains a VSAM or 

SMS-managed data set cataloged in an ICF catalog. The VVDS is always on the 

same volume as the data set it references. For this reason, any volume 

containing a BCS will also contain a VVDS, because the BCS is itself a VSAM 

data set. 

The records in both the VVDS and BCS are made up of variable length cells and 

subcells. The two cell types that are often referred to are the VSAM volume 

record (VVR) and the non-VSAM volume record (NVR), which are both held in the 

VVDS. The VVR contains information relating to VSAM data sets and the NVR 

contains information relating to non-VSAM SMS-managed data sets. 

1.1.2 Where a Data Set is Described 

The BCS, VVDS, and VTOC each supply a portion of the information required to 

process a data set. 

For VSAM data sets: 

The BCS contains the following information: 

Volume - the volumes with which the data set is associated 

Ownership - creation and expiration dates 

Association - information related to paths, alternate indexes and aliases for 

catalogs 

SMS class information 

The VVDS contains the following information: 

Data set characteristics 

Extent description - allows for more than 16 extents 

Catalog name - where this data set is cataloged 

General information - such as the type of data set 

SMS class information

The VTOC contains the following information: 

Extent description 

For non-VSAM SMS managed data sets: 



Ownership - creation and expiration dates 

Association - describes alias entries 


GDS information in a GDG 

The VVDS contains the following information: 


Catalog name - where this data set is cataloged 





For cataloged non-VSAM, non-SMS: 



Ownership 

Association - alias information 

The VVDS contains no information 




For uncataloged non-VSAM, non-SMS: 

The BCS contains no information 

The VVDS contains no information 



Introduction 3



See also Table 1 for a summary of the locations of data set information. 

Most data sets will only have entries in one VVDS. The exception is the 

multi-volume data set, which will have entries in the VVDS of each volume it is 

allocated to. 

Table 1. Location of Data Set Information 

Information VSAM data set SMS-managed 

non-VSAM 

data set 

Non-SMS 

non-VSAM 

data set 

Volume BCS BCS BCS n/a 

Data Set Type BCS BCS BCS n/a 

Association BCS BCS BCS n/a 

Ownership BCS BCS BCS n/a 

SMS Class Info BCS & VVDS BCS & VVDS n/a n/a 

Uncataloged 

non-VSAM 

dataset 

Data Set Attributes VVDS VVDS & VTOC VTOC VTOC 

Extent Description VVDS & VTOC VTOC VTOC VTOC 

Catalog Name VVDS VVDS n/a n/a 

Because the data set, VTOC, and VVDS are on the same volume, backups of the 

volume contain all of the information necessary to recover the data in the event of 

a volume failure. We discuss the importance associated with this in “BCS and 

VVDS” on page 57. 

1.1.3 Accessing Catalogs 

The original method of accessing a catalog was that it was opened for each user 

in their own address space. This gave rise to the situation we have illustrated in 

Figure 1.

User A Address Space User B Address Space 

Referenced Data Set 

| 

Open Catalog 

| 

Create Control Blocks 

and Buffers 

| 

Close Catalog 

| 

Delete Control Blocks 


Figure 1. User Address Space Activity Related to Data Set Open 

Referenced Data Set 

| 

Open Catalog 

| 

Create Control Blocks 


| 

Close Catalog 

| 

Delete Control Blocks 


Each user has the overhead of allocating, opening and closing each catalog 

referenced. Clearly, there were performance gains to be made if catalog access 

could be performed by a central function and this led to the introduction of the 

Catalog Address Space (CAS). 

1.1.4 Catalog Address Space 

With the introduction of the CAS, the request for a catalog function, which is 

normally through a supervisor call (SVC), is passed to the CAS using OS/390 

cross memory services. In Figure 2, we show how the functionality of CAS is 

utilized upon data set reference, as it is performed today: 

Introduction 5

User A Address Space 

Reference 

Data Set 

Call CAS 

Wait 

Continue 


Figure 2. CAS Usage for Data Set Reference 

Catalog Address Space 

Process 

Request 

Control Blocks 


User B Address Space 

Reference 

Data Set 

Call CAS 

Wait 

Continue 

This shows how the functions are now performed in the CAS. Because most of 

the catalog modules and control blocks are located in the CAS above the 16MB 

line, this also reduces the virtual storage, in a user’s private area, needed to 

perform catalog functions. 

The CAS will process requests concurrently up to a user-selected value. Refer to 

OS/390 V2R7.0 MVS Initialization and Tuning Reference, SC28-1752, for more 

information on the TASKMAX value. Once this threshold is reached, the caller has 

to wait for another task to complete. 

In this scenario, the catalog is opened at the first reference and remains open 

unless one of the following occurs: 

The operator issues a command to close the catalog. 

The CAS address space terminates or is restarted by the operator. 

The maximum number of catalogs allowed to be open is reached. 

To further improve performance, two types of cache were introduced: 

In-storage catalog cache (ISC) 

Catalog data space cache (CDSC) 

ISC is the default and caches within the CAS address space, whereas, CDSC 

caches in a data space associated with the CAS using the virtual look-aside 

facility (VLF). 

With shared catalogs, each CAS has its own cache, which creates a potential for 

integrity exposures. The solutions to these possible exposures are discussed in 

later topics.

1.2 Tape Volume Catalogs 

The internal structure of a tape volume catalog (VOLCAT) is the same as all other 

ICF user catalogs. It is a key sequenced data set (KSDS). Its only relationship to 

a VVDS is that its self-describing VVRs are in the VVDS of the volume the 

VOLCAT resides on. 

All rules for sharing and protecting a catalog apply for a VOLCAT, as they do for 

any other user catalog. 

The difference between a VOLCAT and other user catalogs is the content. A 

VOLCAT contains only library records for SMS-managed tape libraries, or volume 

records for SMS managed tape volumes. For both record types there is no 

relationship to any VVDS. 

There are two varieties of tape volume catalogs available. They are: 

The general VOLCAT 

The specific VOLCAT 

The general VOLCAT contains library records and may contain tape volume 

records. A specific VOLCAT contains only tape volume records. In a system 

managed tape environment, you are required to have at least one general 

VOLCAT, and you can have multiple, specific VOLCATs. When a VOLCAT is 

defined, a catalog connector record is created in the system’s master catalog. In 

a shared environment where the master catalog is not shared, an Access Method 

Services (AMS) IMPORT CONNECT is needed on all sharing systems to create a 

connector record in their master catalog. You do not need to define an alias 

pointing to a VOLCAT. 

The fixed naming conventions for VOLCATs are: 

hlq.VOLCAT.VGENERAL 

hlq.VOLCAT.V* 

All have three qualifiers, the system default for the high level qualifier (hlq) is 

SYS1. If any hlq other than SYS1 is specified, it needs to be reflected in the 

LOADxx member in SYS1.PARMLIB as well as in the SYSCATLG member in 

SYS1.NUCLEUS, if this is used in your environment. 

The ’*’ in the third qualifier of any specific VOLCAT needs to be replaced by the 

first digit of the volume serial number range you would like to catalog them in. 

Volume records for tape volumes that do have a first digit in volser, for which 

there is no specific VOLCAT defined, are stored into the general VOLCAT. 

1.3 A Review of the SHAREOPTIONS Parameter 

The AMS DEFINE parameter SHAREOPTIONS indicates the level of sharing within 

a system and across systems. For a catalog, there are only two allowable 

specifications of SHAREOPTIONS, either (3,3) or (3,4) with the default being 

(3,4). 

Introduction 7

1.3.1 Defining the Level of Sharing within a System 


The first parameter defines the level of sharing within an OS/390 image. The 

value 3 indicates that any number of users can have the catalog open for both 

read and write, but it is the user’s responsibility to provide protection against 

multiple updating. This is not a problem for CAS, as all of its updates take place 

from within a single address space. VSAM will prevent other programs from 

opening catalogs for any type of output operation. However user programs could 

cause damage to catalogs. 

1.3.2 Defining the Level of Sharing Across Systems 

The second parameter specifies the level of sharing across systems. The value 3 

indicates that there is no sharing and the value 4, indicating sharing. 

1.4 Catalog Evolution 

With parameter value 3, all previously read buffers are considered to be valid and 

do not need to be refreshed from the physical catalog records. This gives good 

performance but, if the catalog was actually being shared, corruption or the use 

of records that were no longer valid could occur. 

Specifying a value of 4 does not, in itself, make a catalog shared, it must also 

reside on a DASD volume which was defined as shared. For more information as 

to the type of messages that are issued when there are sharing problems, or how 

to determine whether a catalog is truly shared, refer to “Catalog Sharing 

Problems” on page 77. 

If both conditions are met, CAS ensures that each system uses an up-to-date, 

valid copy of the catalog at all times, by reading the physical catalog records for 

each request. 

Ensuring integrity meant that the advantages of the ISC and CDSC were lost and 

additional overhead was introduced because the read of the catalog records had 

to be protected by issuing a RESERVE request. This was a special form of 

enqueue (ENQ) and resulted in the DASD volume that the catalog resided on, 

being temporarily unavailable to other systems. This was a problem for catalogs 

with little update activity, particularly master catalogs, as the previously read 

entries were generally still valid. 

All ENQs are processed by Global Resource Serialization (GRS), or an 

equivalent product, and a RESERVE can be processed either as a physical or a 

logical operation. Physically, the reserve is passed to Input-Output Supervisor 

(IOS), which issues a reserve Channel Command Word (CCW). Logically, it is 

converted to a SYSTEMS ENQ and passed to the other systems known to GRS. 

Both of these have performance implications. The reserve lacks granularity, as it 

will prevent all other systems from accessing any data on the volume reserved, 

and conversion will delay the read of the catalog records until all systems have 

acknowledged the request. 

To improve performance, a solution was designed that took advantage of the fact 

that the catalog is a VSAM data set and, therefore, has cells in the VVDS 

describing it.

A VVR was introduced that allows sharing systems to detect changes that had 

been made to catalog records. Any system that changes catalog records stores 

the Time Of Day (TOD) clock in this VVR, updates a counter, and identifies the 

change. Because of the TOD clock value, this VVR is generally referred to as the 

timestamp VVR, but would be better described as an integrity record or integrity 

VVR. 

In Figure 3 we show how the CAS utilizes integrity VVRs: 

System A 

Catalog 

Address 

Space 

Figure 3. CAS Usage of Integrity VVRs 

VVDS 

(Integrity VVR 

for BCS) 

Catalog BCS 

When CAS opens a catalog, the integrity VVR is read, and the TOD and counter 

values are stored in internal control blocks. Each time that access to the catalog 

is required, the VVR is read and, by comparing the previously read information 

with the latest contents of the record, the CAS is able to determine the validity of 

its cached records. 

It is necessary to protect the VVR from being updated by another system while 

the catalogs records are being processed. To do this, a RESERVE is issued 

against the volume containing the VVDS. Although this has the disadvantages 

discussed earlier, it does reduce the overall number of I/O requests and means 

that many of the cached records can be reused. 

1.5 Parallel Sysplex Performance Considerations and Solutions 

Reserve 

Reserve 

System B 


Address 

Space 

The implementation of Parallel Sysplex has brought with it an increase in the 

number of sharing systems. This means that the delays inherent in both reserving 

the volume, or converting the request are proportionally increased. Either more 

systems are prevented from accessing the volume containing the VVDS, or the 

Introduction 9


elapsed time required for the sharing systems to acknowledge the request 

increases. In the topics that follow, we show a non-catalog solution and introduce 

the concept of Enhanced Catalog Sharing. 

1.5.1 Non-Catalog Solution 

The performance of GRS can be improved by implementing star mode, which 

uses a Coupling Facility structure. This produces significant improvements to 

GRS performance but is only a partial solution for catalog sharing because it 

does not remove the requirement for reading the VVR. We recommend this for its 

general improvement to sysplex performance and particularly in those 

environments where the catalog solution, discussed in the next section, is not an 

option. 

1.5.2 Enhanced Catalog Sharing 

The solution offered by DFSMS/MVS 1.5, Enhanced Catalog Sharing (ECS), 

takes advantage of the strength and reliability of the existing design, and exploits 

the well-established architecture of the Coupling Facility structure. 

This design uses a Coupling Facility cache structure to contain the integrity VVR 

of each active shared catalog. A new option, ECSHARING has been introduced 

for use when defining or altering a catalog, see DFSMS/MVS V1R5 Access 

Method Services for the Integrated Catalog Facility, SC26-4906, to indicate that it 

is available for ECS. A catalog is eligible for ECS when all of the following 

requirements are met: 

It has been defined as or altered to ECSHARING 

It has been defined as or altered to SHAREOPTIONS(3,4) 

It is on a device which is defined as SHARED 

When CAS opens an eligible catalog and the system is in catalog sharing mode, 

as described in “Activating ECS” on page 18, the integrity VVR is copied into the 

Coupling Facility structure. Once this occurs, the systems that share the catalog 

do not have to read the VVR to detect change, as they will receive notification 

from the Coupling Facility. Also, the requirement to ENQ on the resource is 

removed because the Coupling Facility architecture incorporates the necessary 

locking. In Figure 4, we show how the integrity VVR utilizes the Coupling Facility:

System A 


Address 

Space 

Coupling 

Facility 

Integrity VVR 

in ECS Cache 

Structure 

VVDS 

(Integrity VVR 

for BCS) 

Catalog BCS 

Figure 4. Integrity VVR Coupling Facility Utilization 

This is an elegant solution to the performance issues. The elapsed time is 

reduced because GRS is no longer used, and the number of I/Os is reduced 

because the VVR does not have to be read. Also, the new function fits smoothly 

alongside the existing reliable and robust code, which will still be used for 

non-ECS catalogs. Non-ECS catalogs are now described as being in VVDS 

mode, which indicates that the VVR is being read from the VVDS. 

In the rare circumstance of a connectivity or Coupling Facility structure failure, 

the ECS catalogs will revert to VVDS mode, allowing the integrity of the catalogs 

to be maintained across such a failure. 

It was not our objective to measure performance; however, as part of the 

comparisons between AMS and CSI, we did observe a significant reduction in 

elapsed time when we were in ECS mode. These figures are reflected in Table 2: 

Table 2. Sample Timings Used by AMS LISTCAT and IGGCSILC 

System B 


Address 

Space 

Timings AMS w/ ECS CSI w/ ECS AMS wo/ ECS CSI wo/ ECS 

Elapsed Time 11 sec 1 sec 24 sec 1 sec 

TCB Time 3.07 sec 0.04 sec 3.14 sec 0.04 sec 

SRB Time 0.06 sec 0.01 sec 0.06 sec 0.01 sec 

ENQ’s/RESERVEs 9010 18 13515 27 

DEQ’s 13515 18 18020 27 

We discuss the benefits of using CSI in Appendix A, “Catalog Search Interface” 

on page 83. 

Introduction 11


DB2 initialization showed gains in three areas: 

Reduction in elapsed time (primarily in allocation and catalog updates) 

Reduction in catalog ASID CPU time 

Reduction in GRS ASID CPU time 

In “Performance Statistics” on page 47, we also show other areas in which we 

were able to observe significant performance benefits. 

1.5.3 Coupling Facility Structure Terminology and Connectivity 

This section is intended to give readers, who are not familiar with Coupling 

Facility structures, an overview of the terminology used later in this book. The 

terms are: 

Coupling facility resource management (CFRM) policy 

Connection 

Disconnection 

Persistence 

1.5.3.1 CFRM Policy 

The CFRM policy is the description of structures which allows them to be defined 

when the policy is activated. For each structure, it specifies the size, the 

preferred Coupling Facility and structures which should not be placed in the same 

coupling facility. It does not define the structure type. The structure type is set by 

the application when it connects. 

1.5.3.2 Connection 

The term connection is used in both a physical and a logical context. The physical 

connection refers to the data path between the S/390 processor and the Coupling 

Facility that is used by all structure users. The logical connection refers to the 

relationship between an application and a structure. 

Physical connection is established automatically by OS/390 as part of the IPL 

process. Under normal operation this link will not be broken. 

Logical connection is made by OS/390 services when an application issues the 

IXLCONN macro. 

1.5.3.3 Disconnection 

Disconnection can occur if an application issues the IXLDISC macro, or if there is 

a failure of the physical link. 

1.5.3.4 Persistence 

When the last user disconnects from a structure, it can be kept or deleted from 

the Coupling Facility. If it is kept it is described as persistent. The structure used 

by ECS is not persistent and the operational implications of this are discussed in 

“Loss of ECS Mode” on page 18. 

The macros mentioned are documented in the OS/390 V2R7.0 MVS 

Programming: Sysplex Services Reference, GC28-1772.

1.6 Data Set Naming in a Parallel Sysplex 

In a sysplex, with all of the DASD shared, there is no requirement for each 

system to have its own master catalog. This has the advantage of reducing 

maintenance activities such as defining aliases in multiple master catalogs, but it 

also means that the introduction of new releases of products, such as language 

compilers, which can require multiple versions of execution procedures. 

This requirement has been addressed by Extended Alias Support by using 

system symbols, which can be system unique, to resolve data set references to 

different physical data sets on individual systems. This is implemented by a new 

AMS DEFINE ALIAS parameter SYMBOLICRELATE, and can be used for defining 

aliases of user catalogs or non-VSAM (non-GDS) data sets. 

The implementation of Extended Alias Support is discussed in “Implementing 

Extended Alias Support” on page 30. 

Introduction 13

14 Enhanced Catalog Sharing and Management

Chapter 2. Planning 

This chapter will discuss the general concepts and considerations of a shared 

catalog environment, and the planning required to implement ECS and Extended 

Alias Support. You will learn how to determine which parameters are required for 

input to the implementation steps that are discussed in Chapter 3, 

“Implementation” on page 23. 

In the following sections we will describe: 

Planning for the new functions of DFSMS/MVS 1.5 

Planning for ECS implementation 

Extended Alias Support 

2.1 Planning for the New Functions of DFSMS/MVS 1.5 

We recommend that ECS and Extended Alias Support not be implemented until 

all of the sharing systems are at a DFSMS/MVS 1.5 level that includes the 

Program Temporary Fix (PTF) for OW39071. The reasons for waiting until all 

systems are at this level are: 

Lower level systems will be unable to resolve extended alias names. 

If catalogs are in ECS mode, they are not available to lower level systems. 

OW39071 introduces code to increase the operational capability of ECS. 

This redbook is written, based on our system with the code for OW39071 

installed, and the information in this redbook will not apply to any system that 

does not have this fix applied. 

As with all new releases of software where there will be coexistence between old 

and new levels, it is imperative to read the DFSMS/MVS V1R5 Planning for 

Installation, SC26-4919 and to obtain the Preventive Service Planning (PSP) 

information from your local IBM Support Center. This is particularly important if 

ECS is to be exploited, because the indication that a catalog is in ECS mode is 

achieved by the use of a new ENQ, which has to be recognized by lower level 

systems to be effective. 

As part of the planning for the new release, this may also be an appropriate time 

to review the general catalog structure and parameters before considering ECS. 

Some areas for consideration are suggested below. 

ECS is designed to reduce the overhead associated with ensuring the integrity of 

shared catalogs. There have been no changes in the general performance 

provided by ISC and CDSC, however other changes to the environment, such as 

new processors with more real storage, might make it appropriate to increase the 

size of the CDSC. 

Some of the recommendations for DASD performance might no longer be valid. 

For example: 

The use of IMBED is ignored for new data sets in DFSMS/MVS 1.5. 

The use of REPLICATE is ignored for new data sets in DFSMS/MVS 1.5. 



Positioning of the catalog next to the VTOC. 

All of these techniques were based on the characteristics of DASD where the 

data was physically contiguous. However modern DASD is generally designed to 

have data dispersed across several internal disks and there is no longer any 

performance advantage in attempting to position the data. 

2.2 Planning for ECS Implementation 

This section will discuss the criteria for catalogs to be in ECS, and the sizing of 

the cache structure required to support them. In the topics that follow we cover: 

Determining which catalogs utilize ECS 

Determining the number of catalogs 

Cache structure description 

Security considerations 

Cache structure sizing 

CAS and the structure 

Operational issues 

2.2.1 Determining Which Catalogs Utilize ECS 

All currently shared user catalogs should be altered to ECSHARING, unless they 

are shared by systems that do not have ECS capability. This means they are 

either not at DFSMS/MVS 1.5 plus OW39071, or not in the same sysplex. It may 

be possible to split catalogs that fall into this category, and create an ECS and 

non-ECS catalog. 

Master catalogs that are shared, but defined with SHAREOPTIONS(3,3), should 

be altered to SHAREOPTIONS(3,4) and ECSHARING. This will maintain the 

integrity without an impact to performance. 

Any catalog that is currently not shared, because of the GRS/RESERVE 

overhead, should be altered to use ECS. 

2.2.2 Determining the Number of Catalogs 

The DFSMS/MVS 1.5 implementation of ECS allows a maximum of 1024 catalogs 

in ECS mode on each system. However, the total number of ECS catalogs in the 

sysplex can be greater than 1024, as each catalog does not have to be open on 

all systems. The theoretical limit, if every catalog is only in use by one system, is 

1024 multiplied by the number of systems in the sysplex. 

2.2.3 Cache Structure Description 

A practical limitation is set by the CATMAX parameter which restricts the number 

of open catalogs to 255 per system. Beyond this number, a catalog has to be 

closed by the CAS to open a new one. For a more detailed explanation of 

CATMAX refer to OS/390 V2R7.0 MVS System Commands, GC28-1781. 

The structure name must be SYSIGGCAS_ECS.

The structure has a disposition of delete, meaning that when the last system 

disconnects from it, it is deleted from the Coupling Facility. This has implications 

for operations and is described in 3.1, “Implementing Enhanced Catalog Sharing” 

on page 23. 

2.2.4 Security Considerations 

When the CAS attempts to connect to the cache structure, a check is made to 

determine whether it has the authority to do so. The resource is in the Resource 

Access Control Facility (RACF) Facility class and is called IXLSTR.SYSIGGCAS_ECS. 

Because the CAS is a started task, this may not be an issue but should be 

checked with the installation security administrator. 

2.2.5 Cache Structure Sizing 

The storage allocated to the structure has three elements: 

Fixed controls 

Data 

Directory 

The storage used for the fixed controls is required by the Coupling Facility 

microcode in order to maintain and process the structure contents. The data 

portion contains the integrity VVRs, one per ECS catalog, and the directory 

allows the VVRs to be located. 

In order to accurately calculate the storage required, the values in Managing 

Catalogs, SC26-4914 must be applied to the formula in the S/390 PR/SM 

Planning Guide, GA22-7236. This calculation is, in the context of the ECS cache, 

more precise than necessary, for reasons that are discussed below. 

The structure size is specified in 1KB blocks but will be allocated in multiples of 

256KB because of the architecture of the Coupling Facility. 

If the cache structure becomes full, no more catalogs will be eligible for sharing 

unless the structure is made larger. This means disconnecting all systems from 

the structure, reverting to VVDS mode and redefining the structure. We therefore 

recommend that either a size 25% larger than the size calculated be specified, or 

that the structure is defined with the INITSIZE and SIZE parameters specified. The 

INITSIZE parameter specifies the initial storage allocation, and SIZE is a value to 

which the structure will be increased dynamically. Refer to OS/390 V2R7.0 MVS 

Setting Up a Sysplex, GC28-1779 for more information about these parameters. 

At the present time, the value of the fixed controls varies from approximately 

40KB to 70KB, and the value of each directory element varies from 188 to 208 

bytes. Each catalog in ECS mode requires one data element of 4KB to contain 

the VVR, and one directory entry. This permits a simple rule of thumb calculation. 

The fixed controls and approximately 40 VVRs can be contained in the first 

Planning 17


256KB, and each further allocation of 256KB will hold approximately 60 VVRs. 

Table 3 shows examples of the calculations. 

Table 3. Sample ECS Structure Sizes for a Currently Supported Coupling Facility 

Expected ECS-Active 

Catalogs 

Plus 25% for Expansion ECS Structure Size 

31 39 256 KB 

80 100 512 KB 

128 160 768 KB 

176 220 1 MB 

371 464 2 MB 

760 950 4 MB 

1100 1375 6 MB 

1536 1920 8 MB 

1920 2400 10 MB 

Although the storage allocations might appear to be large values, in the context 

of a cache structure 10MB which would support over two thousand catalogs, this 

would be considered comparatively small. 

2.2.6 Activating ECS 

In addition to the catalog eligibility requirements we discussed in “Enhanced 

Catalog Sharing” on page 10, there are four requirements that must be met 

before any catalog can be used in ECS mode: 

All sharing systems are at Version DFSMS/MVS 1.5, with OW39071 PTF 

applied. 

The structure has been defined and the CFRM policy activated. 

At least one catalog has been defined with ECSHARING. 

The AUTOADD command has been issued. 

The CFRM policy can be activated before or after the implementation of 

DFSMS/MVS 1.5. If it is before implementation, the CAS will connect to the 

structure when the new system is IPLed. If it is after implementation, the CAS exit 

routines will receive notification when the structure is activated and will connect 

at that time. 

The AUTOADD command and the ECSHARING parameter cannot be used until 

DFSMS/MVS 1.5 is implemented. 

The AUTOADD command can be issued on any system in the sysplex after which the 

structure has been connected. The AUTOADD status is communicated to the other 

systems by updating a control record in the structure. The next reference to any 

catalog with ECSHARING set will cause ECS mode to be entered for that catalog. 

2.2.7 Loss of ECS Mode 

There are situations that, in order to maintain the integrity of shared catalogs, will 

cause ECS to be turned off across the sysplex and VVDS mode to be used.

These situations are in two categories; those where failures have occurred and 

the loss is predictable, and those during apparently normal operation. 

The predictable loss of ECS mode could happen for any of the following reasons: 

DISCONNECT command is issued 

Coupling Facility failure 

Coupling Facility connectivity failure 

The first two cases are essentially the same. The DISCONNECT command is 

intended for use when a Coupling Facility is required for scheduled maintenance 

and allows a controlled exit from ECS mode. 

In the third case, the system that loses connectivity is still active and handling 

catalog requests, and therefore, to maintain integrity, all systems must use VVDS 

mode until the connectivity is restored. 

There is no automatic rebuild of the structure in another Coupling Facility. The 

planner will need to establish procedures that either allow the system to run in 

VVDS mode or have the structure defined elsewhere, and a new CFRM policy be 

activated. 

When the situations described previously have been corrected and all systems 

have connectivity to the structure, the AUTOADD command will need to be issued for 

the sysplex to return to ECS mode. 

The unexpected loss of ECS mode could happen during the following situations: 

IPL 

CAS restart 

To plan for these circumstances, it is necessary to understand three elements of 

the relationship between CAS and the cache structure: 

When does connection occur 

When does disconnection occur 

When the structure is deleted 

The CAS connects to the structure when it receives its first catalog request. The 

CAS will disconnect during restart processing. During the IPL process, you may 

notice the CAS issue two connects. This is normal operation and can be 

discounted. If an error occurs in the CAS, or if the operator issues the RESTART 

command, a disconnect will also take place. 

It is, therefore, possible for all systems to have an active CAS but for there to be 

no connections to the structure. Because the structure is not persistent, it will 

automatically be deleted in this situation and VVDS mode is entered. 

2.2.8 Operational Issues 

Because the MODIFY CATALOG command has new parameters, operations personnel 

will require education on the ECS function and the effects of these new 

parameters. We discuss these parameters in detail in Chapter 4, “Operations” on 

page 35. 

Planning 19

2.3 Extended Alias Support 


If there will be a period of time when the sysplex will be a mix of ECS and 

non-ECS capable systems, it may not be possible to activate sharing. 

The interaction between ECS and non-ECS systems is dependent on them being 

part of the same GRS configuration. Any combination of systems which are not in 

such a configuration is not supported and will cause catalog corruption. 

Recovery scenarios for connectivity and Coupling Facility failures will need to be 

reviewed and amended to allow for the new structure. 

Automation procedures should be implemented to check for the presence of the 

AUTOADD status. 

This support provides the capability for systems in a sysplex, which are sharing 

catalogs, to have references to either data set names or catalogs be translated to 

a different name for accessing the physical data. 

The following is an example of the AMS statements required for an extended 

alias: 

DEFINE ALIAS (NAME(CEE.SCEELINK) - 

SYMBOLICRELATE('CEE.&LELEVEL..SCEELINK')) 

These statements mean that references to a data set called CEE.SCEELINK will 

be modified depending on the value of the symbol &LELEVEL. This symbol must be 

defined in SYS1.PARMLIB member IEASYMxx, and can be defined either as a 

global value which applies to every system in the sysplex, or as a local value 

which applies to an individual system. If a symbol is defined as both a global and 

a local, the local value will be used on the system to which it applies. 

The following shows an extract from an IEASYMxx member. For a full description, 

refer to OS/390 V2R7.0 MVS Initialization and Tuning Reference, SC28-1752: 

SYSDEF SYSCLONE(&SYSNAME(3:2)) 

SYMDEF(&SYSR2='&SYSR1(1:5).2') 

SYMDEF(&LELEVEL='R170’) 

SYSDEF HWNAME(SCZP601) 

LPARNAME(A10) 

SYSNAME(SC65) 

SYMDEF(&LELEVEL=’R180’) 

The first SYSDEF statement defines defaults for any system not specifically 

referenced. The SYMDEF parameter sets &LELEVEL to R170. The second SYSDEF 

statement defines values for a system with a system name of SC65 and for this 

system &LELEVEL will have a value of R180. The result of this, on a nine-way 

sysplex, would be that eight of the systems would change the data set 

CEE.SCEELINK references to CEE.R170.SCEELINK and system SC65 would 

change it to CEE.R180.SCEELINK. 

It is especially important to ensure that the job runs on the required system. In the 

example above, a job requiring CEE.R180.SCEELINK must be run on SC65. If it

is run on any other system it may appear to have been successful but the results 

could be incorrect. 

We detail the steps needed to implement Extended Alias Support in 

“Implementing Extended Alias Support” on page 30. 

Tip 

An alias becomes active as soon as it is defined, but system symbols require 

an IPL to become active. If a symbol is not defined on a particular system, the 

alias can not be resolved and the user will see an allocation error, stating data 

set not found. There is no indication given that a symbol was not resolved. 

Applying Alias Name to Catalogs: 

The option to apply an extended alias to the name of a user catalog should be 

treated with caution. It is intended to allow system builders to clone systems and, 

if used in a production environment, requires careful planning and control to 

ensure that jobs and TSO logons were on the correct system. 

Planning 21


Chapter 3. Implementation 

In this chapter we discuss the steps required to implement two of the new 

functions that were introduced with DFSMS/MVS Version 1 Release 5, Enhanced 

Catalog Sharing and Extended Alias Support. You can use this information to 

successfully implement ECS in your environment. In the following sections we will 

cover: 

Implementing Enhanced Catalog Sharing 

Implementing Extended Alias Support 

The information presented will allow you to quickly implement ECS with minimal 

modification of our examples. 

3.1 Implementing Enhanced Catalog Sharing 

In this section we detail the steps required to enable the CAS in order to use 

ECS. In summary, these steps are: 

Define the CFRM policy 

Activate the CFRM policy 

Verify connection to the CF structure 

Identify catalogs for ECS 

Issue the AUTOADD command 

Some of these steps must be performed manually, while others occur 

automatically after certain criteria is met. For each step of the process, we 

provide example definitions, control statements and commands. Additionally, we 

included the system messages and status displays related to ECS for the CAS. 

3.1.1 Understanding the ITSO Environment Setup 

In our ITSO test environment, the sysplex consisted of three OS/390 V2R7 

systems with DFSMS/MVS V1R5 with OW39071 applied. The system ids were 

SC63, SC64 and SC65. We also had two Coupling Facilities, CF03 and CF04. 

The structure of our sysplex is shown in Figure 5. All three systems share a 

master catalog and a user catalog, which reside on volume SBOX01. 


SC63 

OS/390 

V2R7 

3.1.2 Defining the CFRM Policy 


CF03 

Coupling 

Facilities CF04 

SC64 

OS/390 

V2R7 

SBOX01 

MCAT 

VVDS 

Figure 5. Structure Diagram of the ITSO Parallel Sysplex 

Shared 

Master 


SC65 

OS/390 

V2R7 

We used the parameters provided in Managing Catalogs, SC26-4914, and the 

algorithms from the S/390 PR/SM Planning Guide, GA22-7236 to determine that 

a CF structure size of 10 MB would be more than adequate for our requirements. 

A structure of this size is large enough for 1920 ECS-active catalogs plus the 

recommended buffer of 25 percent. Figure 6 shows a sample job to update an 

existing CFRM policy. In most cases, you will want to give the structure name and 

size to your systems programmer, who will add this definition to your existing 

structures. If this is not done and only this definition is included, all others will be 

lost once this new policy is activated.

DEFCFRMP JOB (999,POK),'CFRM',CLASS=A,REGION=4096K, 

// MSGCLASS=X,TIME=10,MSGLEVEL=(1,1),NOTIFY=&SYSUID 

//STEP1 EXEC PGM=IXCMIAPU 

//SYSPRINT DD SYSOUT=* 

//SYSABEND DD SYSOUT=* 

//SYSIN DD * 

DATA TYPE(CFRM) REPORT(YES) 

DEFINE POLICY NAME(CFRM01) REPLACE(YES) 

/* 

CF NAME(CF03) DUMPSPACE(2048) PARTITION(F) CPCID(00) 

TYPE(009672) MFG(IBM) PLANT(02) SEQUENCE(000000049305) 

CF NAME(CF04) DUMPSPACE(2048) PARTITION(D) CPCID(00) 

TYPE(009672) MFG(IBM) PLANT(02) SEQUENCE(000000049305) 

(include existing structure definitions) 

STRUCTURE NAME(SYSIGGCAS_ECS) 

INITSIZE(5120) 

SIZE(10240) 

PREFLIST(CF03,CF04) 

Figure 6. Running the Administrative Data Utility (IXCMIAPU) 

The relevant parameters in the definition for the ECS structure are: 

NAME(SYSIGGCAS_ECS) specifies the name of the structure used by CAS for ECS. 

INITSIZE(5120) specifies the initial size to be allocated for the structure in the 

coupling facility. 

SIZE(10240) specifies the maximum size (in kilobytes) to be allocated for the 

structure in the coupling facility. 

PREFLIST(CF03,CF04) specifies an ordered list of CF names from which the 

system is to select one for allocation of the structure. 

See OS/390 V2R7.0 MVS Setting Up a Sysplex, GC28-1779, for a complete 

description of all parameters for the Administrative Data Utility, IXCMIAPU. 

3.1.3 Activating the CFRM Policy 

After defining the cache structure for SYSIGGCAS_ECS in the CFRM policy, we 

activated that policy by issuing the SETXCF START,POLICY command. This can be 

issued from any system within the sysplex. Figure 7 shows the command and the 

system messages that indicate successful activation. Your systems programmer 

or systems operator may have to activate the updated CFRM policy for you, if you 

do not have the required authority. 

Implementation 25

Figure 7. How to Start Using the CFRM Policy 

3.1.4 Connecting to the CF Structure 


SETXCF START,POLICY,POLNAME=CFRM01,TYPE=CFRM 

IXC511I START ADMINISTRATIVE POLICY CFRM01 FOR CFRM ACCEPTED 

IXC513I COMPLETED POLICY CHANGE FOR CFRM. 919 

CFRM01 POLICY IS ACTIVE. 

IEC377I ENHANCED CATALOG SHARING: CONNECT COMPLETE 

IEC377I ENHANCED CATALOG SHARING: AUTOADD IS NOT CURRENTLY ENABLED 

IXL014I IXLCONN REQUEST FOR STRUCTURE SYSIGGCAS_ECS 920 

WAS SUCCESSFUL. JOBNAME: CATALOG ASID: 002A 

CONNECTOR NAME: IXCLO00D0001 CFNAME: CF04 

IXL015I STRUCTURE ALLOCATION INFORMATION FOR 921 

STRUCTURE SYSIGGCAS_ECS, CONNECTOR NAME IXCLO00D0001 

CFNAME ALLOCATION STATUS/FAILURE REASON 

-------- --------------------------------- 

CF04 STRUCTURE ALLOCATED 

CF03 NO CONNECTIVITY 

As you can see from the IEC377I message in Figure 7, CAS automatically 

connected to the ECS structure as soon as it became available. All active 

systems in a sysplex are notified by the Coupling Facility about the altered 

structure and any other system’s CAS will connect to the structure at the same 

time. We recommend that you then issue a MODIFY CATALOG,ECSHR(STATUS) 

command to verify the status of the Coupling Facility connection. From the 

corresponding status display shown in Figure 8, we could see that none of the 

catalogs currently open were eligible for ECS. 

F CATALOG,ECSHR(STATUS) 

IEC351I CATALOG ADDRESS SPACE MODIFY COMMAND ACTIVE 

IEC380I ENHANCED CATALOG SHARING 071 

*CAS************************************************************** 

* CF Connection: Connected * 

* ------------------CATALOG------------------- -----STATUS------ * 

* UCAT.OS3R7V01.VO37CAT Inact(NotElig) * 

* UCAT.VSBOX09 Inact(NotElig) * 


* CATALOG.SHRICF1.VIODFPK Inact(NotElig) * 

* MCAT.SANDBOX.VSBOX01 Inact(NotElig) * 

*CAS************************************************************** 

IEC352I CATALOG ADDRESS SPACE MODIFY COMMAND COMPLETED 

Figure 8. CAS ECS Status Display After Connecting to the Coupling Facility 

During initial program load (IPL), the CAS attempts to connect to the ECS 

structure in the Coupling Facility. For reference, we included the results that 

occur when an ECS structure has not been defined. Figure 9 shows the 

corresponding system error messages and the output from a CAS ECS status 

display. We will discuss the new MODIFY CATALOG commands in more detail in 

Chapter 4.1, “Using the Modify Catalog Command” on page 35. It is worth noting 

that for a Connect Failure status, the CAS gives the return and reason codes from 

the failing IXLCONN request. These codes are documented in OS/390 V2R7.0 MVS 

Programming: Sysplex Services Reference, GC28-1772. In this case, the

explanation is "The active CFRM policy for the installation does not specify the 

structure" for reason code xxxx0C05. 

IXL013I IXLCONN REQUEST FOR STRUCTURE SYSIGGCAS_ECS FAILED. 696 

JOBNAME: CATALOG ASID: 002A CONNECTOR NAME: N/A 

IXLCONN RETURN CODE: 0000000C, REASON CODE: 02010C05 

IEC377I ENHANCED CATALOG SHARING: NOT CONNECTED: 

228-003(000C-0C05),SI 

IEC350I CATALOG ADDRESS SPACE MODIFY COMMAND AVAILABLE 

IEC368I - CATALOG INITIALIZATION 699 

THE MULTILEVEL ALIAS FACILITY HAS BEEN INITIALIZED 

THE NUMBER OF LEVELS OF QUALIFICATION IS 1 




*CAS************************************************************** 

* CF Connection: Connect Failure RC: 0000000C RSN: 02010C05 * 


* UCAT.VSBOX09 Inact(Unknown) * 

* UCAT.VSBOX01 Inact(Unknown) * 

* CATALOG.SHRICF1.VIODFPK Inact(Unknown) * 

* MCAT.SANDBOX.VSBOX01 Inact(Unknown) * 

*CAS************************************************************** 

Figure 9. CAS Connect Failure to ECS Structure at IPL and Status Display 

It is also possible to verify the status of the ECS structure in the Coupling Facility 

by issuing the DISPLAY XCF,STRUCTURE command for SYSIGGCAS_ECS. Figure 10 

shows the command and the responses we received. From this display you can 

also see which other systems are connected to the structure. Note that the ECS 

structure is allocated with a disposition of DELETE, which will take effect when 

the last system in a sysplex disconnects from the structure. 

Implementation 27


D XCF,STR,STRNAME=SYSIGGCAS_ECS 

IXC360I 09.41.42 DISPLAY XCF 930 

STRNAME: SYSIGGCAS_ECS 

STATUS: ALLOCATED 

POLICY SIZE : 10240 K 

POLICY INITSIZE: 5120 K 

REBUILD PERCENT: N/A 

DUPLEX : DISABLED 

PREFERENCE LIST: CF03 CF04 

EXCLUSION LIST IS EMPTY 

ACTIVE STRUCTURE 

---------------- 

ALLOCATION TIME: 04/07/1999 09:41:07 

CFNAME : CF04 

COUPLING FACILITY: 009672.IBM.02.000000049305 

PARTITION: D CPCID: 00 

ACTUAL SIZE : 5120 K 

STORAGE INCREMENT SIZE: 256 K 

VERSION : B20F9A13 A12AC040 

DISPOSITION : DELETE 

ACCESS TIME : NOLIMIT 

MAX CONNECTIONS: 32 

# CONNECTIONS : 2 

CONNECTION NAME ID VERSION SYSNAME JOBNAME ASID STATE 

---------------- -- -------- -------- -------- ---- --------------- 

IXCLO00D0001 01 00010001 SC63 CATALOG 002A ACTIVE 

IXCLO00D0002 02 00020001 SC64 CATALOG 002A ACTIVE 

Figure 10. XCF Structure Display for SYSIGGCAS_ECS 

3.1.5 Setting the ECSHR Attribute for Selected Catalogs 

For the catalogs that we selected to take advantage of this sharing protocol, we 

have to identify them as being ECS-eligible. This is accomplished by means of 

the ECSHARING attribute. On our systems, we chose to make the master catalog 

and one user catalog eligible for ECS. Figure 11 shows a sample job using the 

AMS ALTER command to alter the ECSHARING attribute for a user catalog. This job 

can run on any system sharing this catalog. Other catalogs kept their default 

attribute of NOECSHARING and are displayed by the CAS as Inact(NotElig). 

//ALTERCAT JOB (999,POK),'TATERS2',CLASS=A,REGION=4096K, 


//STEP1 EXEC PGM=IDCAMS 


//CATVOL DD DISP=OLD,VOL=SER=SBOX01,UNIT=3390 

//SYSIN DD * 

ALTER - 

UCAT.VSBOX01 - 

ECSHR - 

FILE(CATVOL) 

/* 

Figure 11. Altering the ECSHR Attribute

For test purposes, we defined another user catalog, using the AMS DEFINE job 

shown in Figure 12: 

//DEFUCAT JOB (999,POK),'TATERS2',CLASS=A,REGION=4096K, 




//SYSIN DD * 

DEFINE USERCATALOG - 

(NAME(UCAT.VSTEST1) - 

CYL(2 1) - 

VOL(SBOX02) - 

ECSHARING - 

ICFCATALOG ) 

/* 

Figure 12. Defining a User Catalog with the ECSHR Attribute 

3.1.6 Issuing the Automatic Add Command 

Finally, we issued a MODIFY CATALOG,ECSHR(AUTOADD) command to signal to the CAS 

to automatically add ECS-eligible catalogs to the ECS structure. This will happen 

for any ECS-eligible catalog the next time it is referenced. In our case, this 

occurred when we issued the MODIFY CATALOG,ECSHR(STATUS) command which 

counts as a reference to the catalogs. Figure 13 shows both these commands 

and the corresponding system messages that are returned. Notice that the 

Coupling Facility connection status changed to AutoAdd, and the altered catalogs’ 

status to Active. 

F CATALOG,ECSHR(AUTOADD) 


IEC377I ENHANCED CATALOG SHARING: AUTOADD ENABLED 

IEC377I ENHANCED CATALOG SHARING: ALL ELIGIBLE CATALOGS ENABLED 





*CAS************************************************************** 

* CF Connection: AutoAdd * 


* UCAT.OS3R7V01.VO37CAT Inact(NotElig) * 


* UCAT.VSBOX01 Active * 


* MCAT.SANDBOX.VSBOX01 Active * 

*CAS************************************************************** 


Figure 13. Enabling the Automatic Add Function and Status Display 

Once the MODIFY CATALOG,ECSHR(AUTOADD) command has been issued on one 

system, all the CAS in the sysplex recognize this and start using this function. 

Implementation 29


Additionally, when the ECSHR attribute is now set for a shared catalog, it will 

automatically be added to the ECS structure. 

All information about the Coupling Facility connections and the catalogs using 

ECS is kept in the ECS structure. This information will be lost when the last 

system in a sysplex disconnects from the structure. In this case, you will have to 

issue the MODIFY CATALOG,ECSHR(AUTOADD) command again to restart that function. 

3.2 Implementing Extended Alias Support 

In this section we discuss how to implement and begin using Extended Alias 

Support to access different non-VSAM data sets on different systems, using the 

same data set name. In this topic we describe: 

How to set the system symbols 

How to define an extended alias 

How to refer to an extended alias 

In the examples that follow we used load libraries for different releases of the 

Language Environment for OS/390. For all the steps involved we provide 

examples of definition and control statements, as well as related LISTCAT 

command and job output. 

3.2.1 Setting the System Symbols 

System symbols are variables that are used to make system definitions more 

flexible in a shared system environment. However, introducing this flexibility can 

increase the potential for pointing users to libraries or data sets that they did not 

want to access. For this reason, we recommend that you carefully consider the 

system symbols that you use and the effect that they may have in your 

environment. 

System symbols are set using PARMLIB member IEASYMxx. For a 

comprehensive description of statements and parameters, please refer to the 

OS/390 V2R7.0 MVS Initialization and Tuning Reference, SC28-1752. When 

specified in other PARMLIB members or in JCL, system symbols will be 

substituted by their current values on each system. Because an IPL is required to 

set the symbols on each system, you should give careful consideration to the 

names you are going to use before applying them to your environment. 

With DFSMS/MVS 1.4, you could use system symbols, for example &SYSR1, to 

specify VOLUMES for non-VSAM, non-SMS data sets. This is known as Indirect 

Volume Serial Support. With DFSMS/MVS 1.5, it is also possible to use system 

symbols in extended alias definitions for data set names. These can then be 

related to different real data set names on different systems. This can be useful 

when migrating from one software release to the next. The advantage of this 

function is that your JCL does not have to be modified with respect to the data set 

names that you wish to use. What you must consider is the system on which you 

run the job. Selecting the system on which you run the job can be accomplished 

by setting up job classes that run exclusively on selected systems. 

Figure 14 shows sample definitions for system symbols in our Sysplex:

SYSDEF SYSCLONE(&SYSNAME(3:2)) 

SYMDEF(&SRES2='&SYSR1(1:5).2') 



SYMDEF(&ALLCLST1='CANCEL') 

SYMDEF(&CMDLIST1='&SYSCLONE.,00') 

SYMDEF(&LPALIST1='00') 

SYMDEF(&MLPALST1='OE') 

SYMDEF(&LELEVEL='R170') 

... 

(more global symbol definitions included) 

... 


LPARNAME(A8) 

SYSPARM(R3) 

SYSNAME(SC63) 

SYMDEF(&OMVSPARM='7A') 


LPARNAME(A9) 

SYSPARM(R3) 

SYSNAME(SC64) 

SYMDEF(&OMVSPARM='7A') 


LPARNAME(A3) 

SYSPARM(GR,R3) 

SYSNAME(SC65) 

SYMDEF(&OMVSPARM='5E') 

SYMDEF(&LELEVEL='R180') 

Figure 14. Sample Symbol Definitions Parmlib Member (IEASYMxx) 

For all the systems in our sysplex we set the global symbol &LELEVEL to ’R170’, 

and we used a local symbol definition to set a value of ’R180’ for system SC65. We 

use &LELEVEL in an extended alias definition for the data set name 

CEE.SCEELKED that will relate to different real data set names on different 

systems. Figure 15 shows our intention, with respect to the resolution of the alias 

name CEE.SCEELKED, to point to different real data set names on systems 

SC63, SC64 and SC65. 

Implementation 31

SC63 

CEE.SCEELKED 


SC64 

CEE.SCEELKED 

SB0X01 SB0X02 

CEE.R170.SCEELKED CEE.R180.SCEELKED 

Figure 15. Data Set Name Resolution for a Symbolic Alias on Different Systems 

At this stage we have not performed an IPL, so these system symbols will not 

take effect until an IPL has taken place on all systems. 

3.2.2 Defining an Extended Alias 

ThenextstepistousetheAMSDEFINE command to define an extended alias for 

CEE.SCEELKED. A new keyword, SYMBOLICRELATE, has been introduced to 

allow you to define an alias using a system symbol. If a period is to follow the 

system symbol, you must code two consecutive periods (..). There is no 

restriction defining the extended alias even though an IPL has not been carried 

out to activate the system symbol &LELEVEL. The job to define the extended 

alias can run on any system sharing the catalog in which the alias is defined. 

Figure 16 shows the job that we submitted: 

//DEFALIAS JOB (999,POK),'TATERS2',CLASS=A,REGION=4096K, 




//SYSIN DD * 

DEFINE ALIAS - 

(NAME(CEE.SCEELKED) - 

SYMBOLICRELATE(CEE.&LELEVEL..SCEELKED)) - 

CATALOG(MCAT.SANDBOX.VSBOX01) 

/* 

Figure 16. Defining an Extended Alias Using a System Symbol 

SC65 

CEE.SCEELKED

3.2.3 Referring to an Extended Alias 

As we stated earlier, an IPL is needed to set the system symbol used in an 

extended alias definition. Until that time, references to that alias will not be 

resolved. In our case, allocation requests to CEE.SCEELKED would have failed 

and a LISTCAT command issued for this entry would show the name of the system 

symbol in its associations group as shown in Figure 17: 

ALIAS --------- CEE.SCEELKED 

IN-CAT --- MCAT.SANDBOX.VSBOX01 

HISTORY 

RELEASE----------------2 

ASSOCIATIONS 

NONVSAM--CEE.&LELEVEL..SCEELKED 

Figure 17. Extended Alias Name Resolution without the System Symbol Set 

After the next IPL, the system symbols defined in IEASYMxx have been set, and 

references to CEE.SCEELKED will result in &LELEVEL being resolved to its 

intended value in each respective system. In Figure 18, you can see the output of 

the LISTCAT command on system SC63, and you can see that resolution has taken 

place as we intended: 

ALIAS --------- CEE.SCEELKED 

IN-CAT --- MCAT.SANDBOX.VSBOX01 

HISTORY 

RELEASE----------------2 

ASSOCIATIONS 

NONVSAM--CEE.R170.SCEELKED 

Figure 18. Extended Alias Name Resolution with the System Symbol Set 

When used in JCL, the resolution of a symbolic alias is transparent to the 

end-user. As you can see from our sample JCL in Figure 19, which was run on 

systems SC63 and SC65, the alias name CEE.SCEELKED specified in the 

SYSLIB DD statement will also be used in the disposition message IEF285I. Itis 

only when the different target data sets reside on different volumes that you will 

see a difference from the device numbers in allocation message IEF237I and the 

volume serial numbers in message IEF285I. 

Note 

Because the system symbol is not resolved at the time of definition for a 

symbolic alias, there is no backward association from the related-to non-VSAM 

data set to its symbolic alias. As a consequence, symbolic aliases will not be 

deleted when deleting the non-VSAM data set to which they relate. 

Implementation 33

Figure 19. Using an Extended Alias in JCL 

3.2.4 Extended Alias Support for Catalogs 


... 

//LKED EXEC PGM=HEWL,COND=(8,LT,COBOL),REGION=1024K 

//SYSLIB DD DSNAME=CEE.SCEELKED, 

// DISP=SHR 


//SYSLIN DD DSNAME=&&LOADSET,DISP=(OLD,DELETE) 

// DD DDNAME=SYSIN 

//SYSLMOD DD DSNAME=&&GOSET(&GOPGM),SPACE=(TRK,(10,10,1)), 

// UNIT=SYSDA,DISP=(MOD,PASS) 

//SYSUT1 DD UNIT=SYSDA,SPACE=(TRK,(10,10)) 

... 

... 

IEF236I ALLOC. FOR TATERS2I LKED RUNIVP 

IEF237I 0CC1 ALLOCATED TO SYSLIB 

IEF237I JES2 ALLOCATED TO SYSPRINT 

IEF237I 2518 ALLOCATED TO SYSLIN 

IEF237I DMY ALLOCATED TO 

IGD100I 2518 ALLOCATED TO DDNAME SYSLMOD DATACLAS ( ) 

IGD100I 2518 ALLOCATED TO DDNAME SYSUT1 DATACLAS ( ) 

IEF142I TATERS2I LKED IGYWCLG - STEP WAS EXECUTED - COND CODE 0000 

IEF285I CEE.SCEELKED KEPT 

IEF285I VOL SER NOS= SBOX01. 

IEF285I TATERS2.TATERS2I.JOB03676.D0000102.? SYSOUT 

... 

... 

IEF236I ALLOC. FOR TATERS2I LKED RUNIVP 

IEF237I 0CC2 ALLOCATED TO SYSLIB 

IEF237I JES2 ALLOCATED TO SYSPRINT 

IEF237I 2518 ALLOCATED TO SYSLIN 

IEF237I DMY ALLOCATED TO 

IGD100I 2518 ALLOCATED TO DDNAME SYSLMOD DATACLAS ( ) 

IGD100I 2518 ALLOCATED TO DDNAME SYSUT1 DATACLAS ( ) 

IEF142I TATERS2I LKED IGYWCLG - STEP WAS EXECUTED - COND CODE 0000 

IEF285I CEE.SCEELKED KEPT 

IEF285I VOL SER NOS= SBOX02. 

IEF285I TATERS2.TATERS2I.JOB03677.D0000102.? SYSOUT 

... 

Extended Alias Support for catalogs uses the same principles as those 

associated with data sets. However, in the case of a catalog, the resolution of the 

symbolic string is done at CAS initialization or when the multi-level alias table is 

refreshed. As stated before, particular care and testing should be employed when 

using Extended Alias Support for catalogs to avoid unpredictable results.

Chapter 4. Operations 

In this chapter we discuss the system definitions and commands that can be used 

to control the way in which the catalog address space operates. We also 

recommend some checks that you can implement to monitor the health of your 

ECS environment. 

In the following sections we describe: 

How to use the Modify command 

Operational procedure suggestions 

4.1 Using the Modify Catalog Command 

In this section, we discuss the definitions and parameters that the CAS will use 

during IPL or CAS restart to set its operational characteristics. These can be 

displayed or changed once the CAS is active by using the MODIFY CATALOG 

command. We will explain its parameters and their usage as it relates to the ECS 

environment and our test systems. Refer to Managing Catalogs, SC26-4914 for a 

complete description of CAS functions and OS/390 V2R7.0 MVS System 

Commands, GC28-1781 for a complete command reference. We have included 

the current MODIFY CATALOG command syntax in Appendix B, “What’s Changed and 

What’s New” on page 101. 

4.1.1 Setting the Initial CAS Options and Parameters 

When CAS is first started as part of the IPL process, the following system 

definitions will determine its operational characteristics: 

The SYSCAT statement in PARMLIB member LOADxx or the SYSCATxx 

member in SYS1.NUCLEUS 

An (optional) CLASS statement for NAME(IGGCAS) in PARMLIB member 

COFVLFxx 

An (optional) structure with the name SYSIGGCAS_ECS in an active CFRM 

policy 

The SYSCAT statement in LOADxx identifies: 

The master catalog 

The volume the master catalog resides on 

The initial state of SYS% to SYS1 conversion 

The initial alias name level 

The initial service task lower limit 

The high level qualifier of the tape volume catalog 

Other limits and functions are set to their initial default values. For example, the 

maximum number of open catalogs is set to 200, the dynamic dump function is 

set off, and the DELETE UCAT/VVDS WARNING is set on. 

Using a CLASS statement for NAME(IGGCAS) in COFVLFxx allows you to 

specify the names of user catalogs that are eligible for the catalog data space 

cache (CDSC). Since the CDSC is maintained by the virtual lookaside facility 



(VLF), the CAS can start using it as soon as VLF has initialized. For a complete 

description of both the COFVLFxx and LOADxx parmlib members, see OS/390 

V2R7.0 MVS Initialization and Tuning Reference, SC28-1752. 

If there is a structure with the name SYSIGGCAS_ECS defined in an active CFRM 

policy, CAS will connect to it and use it for ECS. This is discussed in greater 

detail in Chapter 3.1, “Implementing Enhanced Catalog Sharing” on page 23. 

4.1.2 Allocating Catalogs to the CAS 

During IPL, the first catalog request from the master address space causes the 

CAS to open the master catalog. Once the CAS is in full-function mode, CAS 

builds internal tables of user catalog names, their aliases and volume serial 

numbers from the entries in the master catalog. The CAS also attempts to 

connect to the ECS structure in an active CFRM policy. 

When a catalog function is requested for a data set whose high-level qualifier 

relates to a user catalog, that catalog will be opened by the CAS. Records read 

from a catalog can be kept in a cache that can be either an in-storage cache 

(ISC) within the CAS, or a catalog data space cache (CDSC) maintained by VLF. 

For a shared catalog that is eligible for ECS, its VVR is maintained in the ECS 


Catalogs will remain open to the CAS until either the maximum number of open 

catalogs (CATMAX) is reached, or a catalog is explicitly closed using the MODIFY 

CATALOG,CLOSE command. 

4.1.3 Controlling the CAS Environment 

You can use the MODIFY CATALOG command to: 

Obtain information about the current CAS environment including: 

The status of allocated catalogs 

The current setting of options and parameters 

The service level of specific catalog modules 

Make temporary changes to the CAS environment including: 

Closing or unallocating catalogs 

Changing the current setting of options and parameters 

Fix temporary catalog problems by: 

Rebuilding control blocks after closing or unallocating catalogs 

Terminating service tasks that will not complete 

Simplify system maintenance procedures by: 

Unallocating catalogs and VVDS’s to allow a volume recovery 

Restarting the CAS with a new service level in IGG0CLX0 only

Various parameters can be used to control the status of catalogs, VVDS’s, 

service tasks and other items in the CAS. Table 4 shows a summary of 

parameters for the MODIFY CATALOG command by resource type. 

Table 4. MODIFY CATALOG Parameters by Resource Type 

Resource Type Use to Display Use to Modify 

CAS modules REPORT 

ENTRY 

CAS options REPORT 

REPORT,DUMP 

CAS performance REPORT,CACHE 

REPORT,PERFORMANCE 

CAS service task LIST 

LISTJ(jobname) 

REPORT 

catalog BCS ALLOCATED 

ECSHR(STATUS,catname) 

REPORT,CACHE 

REPORT,CACHE 

RESTART 

ABEND(ALLOCATE|ANALYSIS| 

MODIFY) 

ALIASLEVEL(n) 

CATMAX(xx) 

DUMPON|DUMPOFF 

ROTATE|NOROTATE 

SYS%ON|SYS%OFF 

TASKMAX(xx) 

WARNING|NOWARNING 

ISC|NOISC, VLF|NOVLF 

ECSHR, 

CATMAX(xx), TASKMAX(xx) a 

ABEND(id|taskaddr) 

END(id) 

TASKMAX(xx) 

ALLOCATE 

CLOSE 

ECSHR(ENABLE|REMOVE) 

ISC|NOISC 

UNALLOCATE 

VLF|NOVLF 

ECS ECSHR(STATUS) ECSHR(AUTOADD|CONNECT| 

DISCONNECT|ENABLEALL) 

volume ALLOCATED(volser) UNALLOCATE 

VUNALLOCATE|NOVUNALLOCATE 

VVDS 

REPORT 

VCLOSE 


a. These parameters all have an influence on CAS performance. However, they cannot be used 

to set catalog performance directly. 

4.1.4 Controlling the Status of Catalogs in the CAS 

To obtain a status summary of all catalogs currently allocated to the CAS, we 

recommend that you issue the MODIFY CATALOG,ALLOCATED command. It reflects the 

status of any catalog currently allocated to the CAS. If you want to restrict the 

status display to catalogs residing on a specific volume, you can specify that 

volume with the command. Figure 20 shows a sample response to a MODIFY 

CATALOG,ALLOCATED command, which provides information about: 

The allocation status of catalogs 

The caching status of catalogs 

The sharing status of catalogs 

Operations 37

Figure 20. Allocated Catalogs Status Display 


F CATALOG,ALLOCATED 


IEC348I ALLOCATED CATALOGS 219 

*CAS*************************************************************** 

* FLAGS -VOLSER-USER-CATALOG NAME * 

* Y-I-R- SBOX09 0001 UCAT.VSBOX09 * 

* Y-I-E- SBOX01 0001 UCAT.VSBOX01 * 

* Y-I-R- IODFPK 0001 CATALOG.SHRICF1.VIODFPK * 

* Y-I-E- SBOX01 0001 MCAT.SANDBOX.VSBOX01 * 

******************************************************************* 

* Y/N-ALLOCATED TO CAS, S-SMS, V-VLF, I-ISC, C-CLOSED, D-DELETED, * 

* R-SHARED, A-ATL, E-ECS SHARED, K-LOCKED * 

*CAS*************************************************************** 


The multi-line message IEC348I describes the meaning of the status flags after 

the last catalog is displayed. 

Controlling the Caching Status of Catalogs 

If the status flags for a catalog indicate that it is cached in ISC (--I---) or VLF 

(--V---), or that it uses ECS (----E-), you can obtain more detailed information by 

using the REPORT,CACHE or the ECSHR(STATUS) parameters of the MODIFY 

CATALOG command. If you are interested in information relating to a specific 

catalog, you can specify its name with the command to restrict the output to that 

catalog. Figure 21 shows a sample catalog cache report. 

F CATALOG,REPORT,CACHE 


IEC359I CATALOG CACHE REPORT 014 

*CAS****************************************************************** 

* HIT% -RECORDS- -SEARCHES --FOUND-- -DELETES- -SHR UPD- --PURGE-- * 

* * 

* UCAT.VSBOX09 (ISC) * 

* 66% 8 24 16 0 0 1 * 

* UCAT.VSBOX01 (ISC) * 

* 55% 12 47 26 3 0 10 * 

* MCAT.SANDBOX.VSBOX01 (ISC) * 

* 70% 271 1,450 1,018 0 0 4 * 

* * 

*CAS****************************************************************** 


Figure 21. Catalog Cache Statistics Report 

Two kinds of cache can be used to keep catalog records in the CAS or in a data 

space maintained by VLF. The in-storage catalog cache (ISC) is the default cache 

for all catalogs and should always be used for the master catalog. Alternatively, 

user catalog records can be cached in the catalog data space cache (CDSC) 

using VLF. See Managing Catalogs, SC26-4914 for a complete description of 

both caching methods. 

To limit the amount of storage used in CAS, or to overcome the fixed limit for each 

user catalog in the ISC, you may want to prevent a catalog from using the ISC

and start using the CDSC for it. To do this, you can use the ISC/NOISC and the 

VLF/NOVLF parameters of the MODIFY CATALOG command. However, you may have 

to update the CLASS definitions for NAME(IGGCAS) in PARMLIB member 

COFVLFxx and restart VLF before you can use the CDSC for a catalog. 

Controlling the Sharing Status of Catalogs 

From the flags in the allocated catalogs status display (Figure 20), it is possible to 

tell if a catalog is being shared using VVDS mode (R) orusingECS(E). If the flags 

do not show an ’R’ oran’E’ in the 5th position, the catalog is not shared, and also 

indicates that it does not reside on a shared volume, or is not defined with 

SHAREOPTIONS(3,4). For more information about catalog sharing problems, 

refer to 6.3, “Catalog Sharing Problems” on page 77. 

This display shows only the known sharing status on the issuing system. To 

determine whether a catalog is being shared correctly in a sysplex, you must 

verify that all systems show ’R’ or’E’. 

If the allocated catalogs status display shows that catalogs are not using ECS, 

although you have defined them as eligible for ECSHARING, we recommend that 

you issue the MODIFY CATALOG,ECSHR(STATUS) command to determine why ECS is 

not being used for those catalogs. The message IEC380I that is issued in 

response shows information only for catalogs that are open to the CAS on this 

system. ECS can be used for other catalogs on other systems in the sysplex. 

Refer to Figure 22 for a sample ECS status display, which shows various reasons 

for ECS not being used: 

Inact(NotElig) for two user catalogs, UCAT.VSBOX09 and 

CATALOG.SHRICF.VIODFPK, which have not been defined for ECSHARING. 

Inact(NonECSAcc) for a user catalog, UCAT.VSTEST1, which is temporarily 

ineligible for ECS, because it has been accessed by a non-ECS system (using 

VVDS mode sharing) or explicitly been removed from the ECS structure. 

Inact(CFFail) for the master catalog, MCAT.SANDBOX.VSBOX01, and a user 

catalog, UCAT.VSBOX01, which are not using ECS because of a connection 

failure to the ECS structure in the coupling facility. 

As you can see from the CF Connection: Connected status in Figure 22, the 

connection failure to the Coupling Facility has occurred on another system in the 

sysplex. In this example, the connection failure caused the AUTOADD function to 

quiesce on the systems that are still connected. In this case, you will have to use 

the ECSHR(AUTOADD) parameter of the MODIFY CATALOG command to reactivate 

the AUTOADD function. Also, you may have to re-enable catalogs that have been 

marked temporarily ineligible by using the ECSHR(ENABLE) or 

ECSHR(ENABLEALL) parameters. 

For a complete description of the Coupling Facility connection and catalog ECS 

status values, see OS/390 V2R7.0 MVS System Messages, Vol 4 (IEC-IFD), 

GC28-1787. The current status descriptions are also included in Appendix B.2, 

“New and Changed Messages” on page 108. 

Operations 39





*CAS*************************************************************** 

* CF Connection: Connected * 


* UCAT.VSTEST1 Inact(NonECSAcc) * 


* UCAT.VSBOX01 Inact(CFFail) * 


* MCAT.SANDBOX.VSBOX01 Inact(CFFail) * 

*CAS*************************************************************** 


Figure 22. ECS Status Display With Catalogs Not Using ECS 

If you want a catalog to use ECS that has not been defined for ECSHARING, you 

can change the attribute for that catalog using the AMS ALTER command. Refer to 

3.1.5, “Setting the ECSHR Attribute for Selected Catalogs” on page 28 for more 

details. As long as the ECS requirements are met, and if the AUTOADD function 

is enabled, the catalog will start using ECS on the next reference to that catalog. 

In the same way, the sharing mode for a catalog will revert from ECS to VVDS 

sharing, if its attribute is changed back to NOECSHR by the AMS ALTER 

command. 

Changing other attributes for a catalog, however, does not have an immediate 

effect. For example, if you change the SHAREOPTIONS for a catalog to indicate 

that it can now be shared amongst systems, you will have to close the catalog in 

the CAS using the CLOSE parameter of the MODIFY CATALOG command. The CAS 

will then open it again on the next reference to the catalog, and honor its changed 

attributes. 

When a catalog is closed, all associated private storage will be freed in the CAS, 

and allocated cache space will be released. Also, if the catalog was using VLF for 

caching, the space used for it in the CDSC will become available for use by other 

catalogs. 

Likewise, the VCLOSE parameter of the MODIFY CATALOG command is used to 

close the VVDS on a specific volume. The private storage used in CAS for the 

VVDS will be freed. The VVDS will be reopened on the next catalog request that 

needs information for data sets on this volume. 

Controlling the Allocation Status of Catalogs 

To get a catalog unallocated from CAS, you can use the MODIFY CATALOG command 

with the UNALLOCATE parameter. This might become necessary when you want 

to vary the device offline on which the catalog resides. 

To have CAS unallocate a VVDS, you can use the VUNALLOCATE parameter of 

the MODIFY CATALOG command. The default setting for VUNALLOCATE is on, which 

indicates that a VVDS is to be unallocated on completion of a request. However, 

it may have been turned off using the NOVUNALLOCATE parameter, which can 

improve performance by eliminating repeated dynamic allocation and 

unallocation requests for the VVDS’s.

4.1.5 Controlling Options and Settings in the CAS 

To review the current settings of the CAS options and parameters, issue the 

MODIFY CATALOG,REPORT command. Figure 23 shows the sample output from this 

command. Note that all numerical data, including the numbers and limits of 

service tasks and open catalogs, is displayed in hexadecimal. Additional 

information, such as the catalog component level (FMID), the address space 

number of the CAS, and its TCB addresses, will be helpful for diagnostic 

purposes. 

F CATALOG,REPORT 


IEC359I CATALOG REPORT OUTPUT 232 

*CAS************************************** 

* CATALOG COMPONENT LEVEL = HDZ11E0 * 

* CATALOG ADDRESS SPACE ASN = 002A * 

* SERVICE TASK UPPER LIMIT = 000000B4 * 

* HIGHEST # SERVICE TASKS = 0006 * 

* CURRENT # SERVICE TASKS = 0006 * 

* MAXIMUM # OPEN CATALOGS = 000000C8 * 

* ALIAS TABLE AVAILABLE = YES * 

* ALIAS LEVELS SPECIFIED = 1 * 

* CRT TABLE SLOT ROTATION = OFF * 

* SYS% TO SYS1 CONVERSION = OFF * 

* CAS MOTHER TASK = 00896A70 * 

* CAS MODIFY TASK = 008968D8 * 

* CAS ANALYSIS TASK = 00896178 * 

* CAS ALLOCATION TASK = 008963A8 * 

* VOLCAT HI-LEVEL QUALIFIER = SYS1 * 

* VUNALLOCATE = ON * 

* DELETE UCAT/VVDS WARNING = ON * 

*CAS************************************** 


Figure 23. Sample Catalog Report Output 

Modifying Current CAS Options 

You can set the maximum number of open catalogs and the service task upper 

limit using the CATMAX and TASKMAX parameters of the MODIFY CATALOG 

command. These settings will have an effect on catalog performance. Refer to 

“Monitoring the Performance Parameters for CAS” on page 47, for more 

information on catalog performance indicators. 

If you plan to change the search level for the multi-level alias facility, you can use 

the MODIFY CATALOG command with the ALIASLEVEL parameter to temporarily set 

the search level for testing purposes. When you have tested an alias level 

successfully, you should set the initial alias search level in the SYSCAT 

statement in parmlib member LOADxx or the SYSCATxx member in 

SYS1.NUCLEUS. 

The current setting of the DELETE command using the UCAT/VVDS WARNING 

option determines if WTOR messages IDC1997I or IDC1998I should be issued 

when an AMS DELETE USERCATALOG FORCE command or a DELETE RECOVERY for a 

VVDS is about to be executed. These messages have to be replied to with ’Y’ to 

confirm the deletion of the catalog or VVDS. If you do not want the CAS to issue 

these messages, you can use the NOWARNING parameter of the MODIFY CATALOG 

command to turn off this option. 

Operations 41


Determining the Current Dynamic Dump Status 

To check the dynamic dump status of the CAS, you can use the REPORT,DUMP 

parameter of the MODIFY CATALOG command. Figure 24 shows a sample dump 

report output. Initially, the dynamic dump status will be OFF, but you may be 

asked by support personnel of the IBM Support Center to turn it ON for diagnostic 

purposes. This can be done by using the DUMPON parameter of the MODIFY 

CATALOG command, and optionally, specifying catalog return and reason codes and 

a module ID for which dumps are to be taken. 

F CATALOG,REPORT,DUMP 


IEC359I CATALOG REPORT DUMP OUTPUT 021 

*CAS*************************************************************** 

* STATUS RETURN CODE REASON CODE MODULE ID COUNT * 

* ON 194 008 ** 001 * 

*CAS*************************************************************** 


Figure 24. Sample Catalog Dynamic Dump Report 

Determining the Service Level of Catalog Modules 

To determine the starting address and the service level of the catalog modules 

currently in use, issue the MODIFY CATALOG command with the ENTRY parameter 

and, optionally, a module name. See Figure 25 for the sample command and its 

related output. This kind of information can be helpful for diagnostic purposes. 

F CATALOG,ENTRY(IGG0CLSH) 


IEC349I DISPLAY ENTRY POINT(S) 089 

*CAS**************************************** 

* NAME - ADDRESS - FMID/LEVEL * 

* IGG0CLSH 00008948 HDZ11E0/OW39071 * 

*CAS**************************************** 


Figure 25. Sample Catalog Module Entry Display 

In the example above, the service level of module IGG0CLSH is OW39071. If the 

entry name IGG0CLSH is omitted, all CAS modules and their service levels are 

displayed. 

Obtaining CAS Performance Statistics 

To obtain performance statistics about the frequency and timings for system 

functions requested by CAS, you can issue the MODIFY CATALOG command with the 

REPORT,PERFORMANCE parameter. Figure 26 shows a sample catalog 

performance report. This information can be helpful when you need to identify 

performance problems. If you want to monitor the system events for a specific 

time period, you can reset the statistic values using the RESET subparameter. 

The types of events that you will want to look at depend on the type of 

performance problem that you experience on your systems. As far as ECS is 

concerned, you will notice differences in the numbers of VVDS RESERVEs, 

VVDS DEQs and VVDS I/Os, compared to VVDS mode sharing. Refer to 4.2.4, 

“Performance Statistics” on page 47 for more details.

F CATALOG,REPORT,PERFORMANCE 


IEC359I CATALOG PERFORMANCE REPORT 398 

*CAS*************************************************** 

* -----CATALOG EVENT---- --COUNT-- ---AVERAGE--- * 

* Entries to Catalog 50,420 9.651 MSEC * 

* BCS ENQ Shr Sys 50,567 0.613 MSEC * 

* BCS ENQ Excl Sys 33 0.472 MSEC * 

* BCS DEQ 99,904 0.452 MSEC * 

* VVDS RESERVE CI 45 0.396 MSEC * 

* VVDS DEQ CI 43 0.218 MSEC * 

* VVDS RESERVE Shr 12,641 1.140 MSEC * 

* VVDS RESERVE Excl 1,142 5.637 MSEC * 

* VVDS DEQ 13,619 0.506 MSEC * 

* SPHERE ENQ Excl Sys 6 0.485 MSEC * 

* SPHERE DEQ 6 0.263 MSEC * 

* CAXWA ENQ Shr 3 0.013 MSEC * 

* CAXWA DEQ 3 0.011 MSEC * 

* VDSPM ENQ 50,610 0.974 MSEC * 

* VDSPM DEQ 50,610 0.112 MSEC * 

* RPL ENQ 7,108 0.455 MSEC * 

* RPL DEQ 7,108 0.119 MSEC * 

* BCS Get 55,117 1.346 MSEC * 

* BCS Put 4 2.067 MSEC * 

* BCS Erase 1 1.575 MSEC * 

* VVDS I/O 11,565 2.877 MSEC * 

* VLF Define Major 3 0.045 MSEC * 

* VLF Identify 10,207 0.000 MSEC * 

* RMM Exit 1 0.002 MSEC * 

* Tape Exit 1 0.001 MSEC * 

* BCS Allocate 4 0.382 MSEC * 

* SMF Write 18 0.089 MSEC * 

* ENQ SYSZCATS Shr 4 0.381 MSEC * 

* DEQ SYSZCATS 2 0.134 MSEC * 

* IXLCONN 2 1.510 SEC * 

* IXLCACHE Read 33,220 0.208 MSEC * 

* IXLCACHE Write 13 0.172 MSEC * 

* IXLVECTR 57,461 0.009 MSEC * 

* Resolve Symbolic 24 0.570 MSEC * 

* MVS Allocate 4 255.055 MSEC * 

* ENQ SYSZCATS LCB 2 0.366 MSEC * 

* DEQ SYSZCATS LCB 2 0.214 MSEC * 

* Lookup/Pin UCB 4 0.032 MSEC * 

* Unpin UCB 4 0.014 MSEC * 

* Capture UCB 5 0.021 MSEC * 

* Uncapture UCB 1,148 0.030 MSEC * 

* RACROUTE Auth 49,455 0.660 MSEC * 

* RACROUTE Define 4 0.446 MSEC * 

*CAS*************************************************** 


Figure 26. Sample Catalog Performance Report 

Operations 43

4.1.6 Controlling the Status of Service Tasks in CAS 


To obtain a summary display of currently active service tasks in the CAS, use the 

LIST or the LISTJ parameter of the MODIFY CATALOG command. Figure 27 shows a 

sample service tasks display output which includes the job and step names of the 

requestor and the associated service task ID. This task ID can be used to end a 

request that does not complete, for example in case of an enqueue lockout. You 

can use the MODIFY CATALOG command with the END parameter to end a catalog 

request. If the service task still does not end, you can attempt to end the request 

abnormally by using the ABEND parameter and either the service task ID or the 

TASK ADDRESS specified. 

F CATALOG,LIST 


IEC347I LIST CATALOG TASK(S) 561 

*CAS**************************************************************** 

* FLAGS - TASK ADDRESS - JOBNAME / STEPNAME - ELAPSED TIME - ID * 

* -W--R- 00891B40 TATERS2L / STEP1 00.00.01 01 * 

* -W--R- 00893E88 TATERS2K / STEP1 00.00.01 02 * 

* -W-E-- 00893470 TATERS2N / STEP1 00.00.01 05 * 

* WAITING FOR VVDS I/O FROM 000597AA FOR 00.00.01 * 

******************************************************************** 

* O-OLDEST, W-WAIT, A-ABEND, E-ENQ, R-RECALL, L-RLS * 

*CAS**************************************************************** 


Figure 27. Sample Catalog Service Tasks Display 

If you need more detailed information about the status of a service task, use 

LISTJ with the DETAIL parameter. Figure 28 shows the sample output from this 

command. This information can be helpful in determining why a request will not 

complete. 

F CATALOG,LISTJ(TATERS2L),DETAIL 



*CAS****************************************************************** 

* JOB/STEP Name: TATERS2L/STEP1 ASN: 001E TCB: 008E12D0 * 

* CAS TCB: 00891B40 Task Number: 01 TCB Comp Code: 00000000 * 

* CCX: 08290000 CCA: 7F754000 CCAPROB: 00000000 * 

* CTGPL: 04118102 7F5E4CDC 7F5E4CD8 7F5E4E30 * 

* 2100FF07 00000000 00000000 * 

* Request Type: Listcat * 

* CTGENT: SYS1.V2R5M0.SIATLIB * 

* CCASRCH: SYS1.V2R5M0.SIATLIB * 

* Oriented to: MCAT.SANDBOX.VSBOX01 * 

* Waiting for: VVDS I/O at 000596A2 for 00.00.01 * 

* VDSPM ENQ: EXCL * 

* MCAT.SANDBOX.VSBOX01 * 

*CAS****************************************************************** 


Figure 28. Sample Catalog Task Detail Display 

4.1.7 Controlling Enhanced Catalog Sharing in CAS 

We have already discussed using the ECSHR(STATUS) parameter of the MODIFY 

CATALOG command to determine the status of enhanced catalog sharing in

“Connecting to the CF Structure” on page 26, “Issuing the Automatic Add 

Command” on page 29, and “Controlling the Status of Catalogs in the CAS” on 

page 37. We have seen that the CAS will use ECS if it can connect to the ECS 

structure in the Coupling Facility, and the automatic add function is enabled. 

Under normal conditions, no further operator intervention is required to maintain 

ECS. In some special situations, however, you may need to use the following 

subparameters of ECSHR: 

DISCONNECT will disconnect the current system from the ECS structure in 

the Coupling Facility. All open catalogs will revert their sharing protocol from 

ECS to VVDS mode, and the automatic add function will be disabled. This will 

become necessary when you want to change the size of the ECS structure in 

the CFRM policy, or when service has to be applied to the Coupling Facility. 

CONNECT will connect the current system to the ECS structure in the 

Coupling Facility. Normally, the CAS will automatically connect to the Coupling 

Facility as soon as a CFRM policy with an ECS structure is activated. You 

might want to use the CONNECT subparameter if CAS does not connect 

automatically, and you want to determine the reason for the non-connectivity 

from the resultant output. 

AUTOADD will cause ECS-eligible catalogs to be added to the ECS structure 

in the Coupling Facility on the next reference to the catalog. You will need this 

subparameter to re-enable automatic add function after losing the ECS 

structure by a sysplex-wide IPL, a sysplex-wide CAS restart, a Coupling 

Facility connection failure, or after an explicit DISCONNECT request has been 

issued. 

ENABLEALL will enable all currently open catalogs for ECS that have been 

marked temporarily ineligible. You may want to use the ENABLEALL 

subparameter when catalogs have been explicitly REMOVEd from the ECS 

structure, or have been accessed by another system using VVDS mode 

sharing. 

4.1.8 Restarting CAS 

To activate maintenance that has been applied to the catalog load module 

IGG0CLX0 only, you must restart CAS by issuing the MODIFY CATALOG command 

with the RESTART parameter. Be sure to have LLA refreshed before restarting 

the CAS. Service applied to modules other than those in IGG0CLX0 will affect the 

MVS link pack area (LPA). In this case, you must update LPA by either performing 

an IPL with the CLPA option, or use the MLPA function. Take care that you do not 

have different levels of service active in the IGG0CLX0 load module and in LPA. 

You may want to restart the CAS in other rare circumstances, such as when 

problems cannot be resolved by terminating service tasks, or closing or 

unallocating catalogs. You should, however, always try to solve a problem on a 

task or catalog basis first. Refer to “CAS Hang or Lockout Situations” on page 79, 

for a discussion of how to attempt resolution of problems in the CAS and the 

diagnostic information that you should gather before you attempt resolution. 

4.1.9 Sysplex Considerations 

Most of the parameters for the MODIFY CATALOG command affect only the CAS of 

the system on which the command is issued. With ECS, commands that affect the 

Operations 45

4.2 Operational Procedures 


ECS structure in the coupling facility will have a sysplex-wide scope. The ECSHR 

subparameters that will have an effect on other systems are: 

AUTOADD will enable the automatic add function for all systems connected to 

the ECS structure in the Coupling Facility. 

ENABLE | ENABLEALL will re-enable a specific catalog or all catalogs open to 

the CAS for ECS on all systems connected to the ECS structure in the 

Coupling Facility. Note that this may also re-enable catalogs for ECS that have 

been explicitly REMOVEd from another system. 

REMOVE will remove the specified catalog from the ECS structure in the 

Coupling Facility and revert its sharing protocol from ECS to VVDS mode on 

all connected systems. 

DISCONNECT will disable the automatic add function for all other systems 

connected to the ECS structure, and revert the sharing protocol for all 

catalogs open to the CAS from ECS to VVDS mode sharing. 

In this section we discuss some operational procedures that you may want to 

install in order to maintain your catalogs’ integrity and your CAS’ performance. 

4.2.1 Monitoring the Sharing Status for Catalogs 

You may want to install automated procedures to check regularly that catalogs 

which should be shared are actually being shared. The conditions for sharing 

may be lost, for example, by inadvertently altering the sharing attributes of a 

catalog, or by changing the definition for the device on which a catalog resides. 

This would result in an integrity exposure that might not be detected for a long 

period of time. 

To monitor the sharing status of catalogs, we recommend that you issue the 

MODIFY CATALOG,ALLOCATED command from an automated procedure. The procedure 

could then parse the text from the responding message IEC348I (see Figure 20 on 

page 38), and check the 5th position of the flags for an ’R’ (VVDS mode sharing) 

or an ’E’ (ECS). 

4.2.2 Monitoring the CF Connection Status for ECS 

You might also consider checking the Coupling Facility connection status for ECS 

at regular intervals. Although catalog integrity will be maintained when their 

sharing protocol is reverted from ECS to VVDS mode, performance will be 

degraded. 

We recommend using the MODIFY CATALOG,ECSHR(STATUS) from an automated 

procedure to monitor the status of the Coupling Facility connection. The third line 

of the responding message IEC380I (see Figure 22 on page 40) can be parsed to 

determine the connection status. The ECS status for all open catalogs will be 

displayed in the subsequent lines of this multi-line message. 

Additionally, you may want to include messages IEC377I, IEC378I and IEC381I in a 

NetView automation table. These messages report updates for the Coupling 

Facility connection status, the ECS status for a single catalog, or a connection 

failure to the Coupling Facility on another system.

4.2.3 Monitoring the Performance Parameters for CAS 

As we have mentioned before in “Controlling Options and Settings in the CAS” on 

page 41, you can issue the MODIFY CATALOG command with the 

REPORT,PERFORMANCE parameter to obtain a list of statistics for system 

functions requested by the CAS. In most cases, you will only want to take a closer 

look at these statistics when you suspect a performance problem with your CAS. 

As these performance statistics are very much dependent on the type of workload 

in your environment, there are no general guidelines as to what the figures should 

look like. You might consider obtaining the performance statistics for your 

environment on a regular basis, and then reset them to zero using the RESET 

subparameter. This enables you to compare your current values with those of the 

previous time period and detect potential performance problems if some of the 

figures differ significantly. 

In addition to the checks mentioned earlier in this section, you may consider 

checking the following settings that have an influence on CAS performance: 

ISC|NOISC, VLF|NOVLF. The response to a MODIFY CATALOG,ALLOCATED 

command (see Figure 20 on page 38) will display in the third position of the 

flags field, to show how (’I’ for ISC and ’V’ for VLF) a catalog is cached. 

VUNALLOCATE|NOVUNALLOCATE. The response to a MODIFY CATALOG,REPORT 

command (see Figure 23 on page 41) will tell you whether dynamically 

allocated VVDSs will be unallocated on completion of a request. Performance 

can be improved by specifying NOVUNALLOCATE which eliminates repeated 

dynamic allocations of a VVDS. 

CATMAX. The response to a MODIFY CATALOG,REPORT command will also tell you 

(in hexadecimal) the current maximum number of open catalogs. When this 

limit is reached, the least recently used catalog is closed. It will be opened 

again on the next request for this catalog. The results of the MODIFY 

CATALOG,ALLOCATED, discussed in “Controlling the Status of Catalogs in the 

CAS” on page 37, displays all allocated catalogs. The CATMAX value should 

be set larger than this number for the best performance. Setting CATMAX too 

low can cause serious performance problems. 

TASKMAX. The current maximum number of CAS service tasks will also be 

displayed (in hexadecimal) in the response to a MODIFY CATALOG,REPORT 

command. Once this limit is reached, additional requests to the CAS will be 

delayed until an active request is completed. 

Note that most of these settings that could improve performance, could also 

increase the amount of storage needed in the CAS for related control blocks. If 

you experience storage shortages in your CAS (indicated by system 878 

abends), you will have to balance the benefits gained from higher limits against 

the drawbacks of increased storage requirements. 

4.2.4 Performance Statistics 

Although it was not within our scope to present real-world performance figures 

here, due to the workload on the system, we will show some figures gathered by 

the F CATALOG,REPORT,PERFORMANCE command. These figures will show the 

difference between ECS and VVDS sharing and the benefits that we were able to 

gain. 

Operations 47


Even though this information was gathered in a test environment and not a 

production environment, the statistics provided by the catalog performance report 

can be used to show differences between ECS and VVDS sharing mode. 

LISTCAT 

With the first test, the ECS is active and the master catalog in ECS mode, we 

issued the: 

F CATALOG,REPORT,PERFORMANCE(RESET) 

command to reset all performance reporting information to zero. 

Next, we submitted an AMS LISTCAT ALL job against our shared master catalog 

which contained a total of 4,554 entries. The total elapsed time for that AMS 

LISTCAT job was 18 seconds. A performance report was taken after the AMS 

LISTCAT job by the command: 


This report is shown in Figure 29. 




*CAS*************************************************** 




* BCS DEQ 9,131 0.227 MSEC * 

* VVDS RESERVE Shr 344 0.461 MSEC * 

* VVDS RESERVE Excl 102 0.468 MSEC * 

* VVDS DEQ 446 0.282 MSEC * 

* VDSPM ENQ 4,566 0.021 MSEC * 

* VDSPM DEQ 4,566 0.016 MSEC * 

* BCS Get 4,794 0.123 MSEC * 

* VVDS I/O 242 1.939 MSEC * 

* IXLVECTR 9,134 0.006 MSEC * 


* Uncapture UCB 102 0.022 MSEC * 


*CAS*************************************************** 


Figure 29. Performance Report after LISTCAT in ECS Mode 

We then submitted the same AMS LISTCAT ALL job but in VVDS sharing mode. 

Figure 30 shows the performance report taken after the AMS LISTCAT job in 

VVDS sharing mode. The total elapsed time for the AMS LISCAT job in VVDS 

sharing mode was 30 seconds. The statistics that show the tremendous 

performance improvements are shown in bold.




*CAS*************************************************** 




* BCS DEQ 9,131 0.249 MSEC * 


* VVDS RESERVE Excl 102 0.500 MSEC * 

* VVDS DEQ 5,012 0.239 MSEC * 

* VDSPM ENQ 4,566 0.022 MSEC * 

* VDSPM DEQ 4,566 0.021 MSEC * 

* BCS Get 4,794 0.100 MSEC * 

* VVDS I/O 4,808 1.906 MSEC * 



* Uncapture UCB 102 0.021 MSEC * 


*CAS*************************************************** 


Figure 30. Performance Report after LISTCAT in VVDS Sharing Mode 

Comparison of these reports shows significant reductions in: 

The job elapsed time reduced from 30 seconds to 18 seconds. 

The average time to process an entry from catalog reduced from 6.023 MSEC 

in VVDS sharing mode to 3.238 MSEC in ECS mode. 

The number of VVDS RESERVE Shr dropped from 4,910 in VVDS sharing 

mode to 344 in ECS mode. 

The number of VVDS I/Os dropped from 4,808 in VVDS sharing mode to 242 

in ECS mode. 

ALLOCATE 

We then decided to use IBM utility IEFBR14 to allocate 300 non-VSAM, non-SMS 

managed data sets. Using an alias, all data sets were cataloged into the user 

catalog UCAT.VSBOX01. Both the master catalog and the user catalog were in 

ECS mode. We issued the command: 

F CATALOG,REPORT,PERFORMANCE(RESET) 

This resets all performance reporting information to zero. 

Then we submitted an IEFBR14 job containing 300 DD statements, all with 

DISP=(NEW,CATLG), to create and catalog 300 non-SMS managed data sets. 

The elapsed time for this job was 12 seconds. 

After the job successfully ended, we again issued the command: 


The output is shown in Figure 31. 

Operations 49


Next, we changed the master catalog, as well as the user catalog from ECS to 

VVDS sharing mode and, again, allocated 300 non-VSAM, non-SMS managed 

data sets after the performance reporting statistics were reset to zero again. The 

elapsed time for this IEFBR14 job was 18 seconds. Figure 32 on page 51 shows 

the performance report that was taken after the job had run. 




*CAS*************************************************** 


* Entries to Catalog 600 6.316 MSEC * 



* BCS DEQ 1,500 0.247 MSEC * 



* VDSPM ENQ 2,100 0.022 MSEC * 

* VDSPM DEQ 2,100 0.022 MSEC * 

* BCS Get 601 0.045 MSEC * 

* BCS Put 300 2.929 MSEC * 


* IXLCACHE Write 600 0.227 MSEC * 




* RACROUTE Auth 600 0.523 MSEC * 


*CAS*************************************************** 


Figure 31. Performance Report after Allocating 300 Data Sets ECS Active




*CAS*************************************************** 


* Entries to Catalog 600 16.932 MSEC * 



* BCS DEQ 1,500 0.253 MSEC * 

* VVDS RESERVE CI 600 0.424 MSEC * 

* VVDS DEQ CI 600 0.219 MSEC * 


* VVDS DEQ 2,100 0.256 MSEC * 



* VDSPM ENQ 2,100 0.021 MSEC * 

* VDSPM DEQ 2,100 0.020 MSEC * 

* BCS Get 601 0.051 MSEC * 

* BCS Put 300 2.457 MSEC * 

* VVDS I/O 2,700 1.795 MSEC * 





* RACROUTE Auth 600 0.554 MSEC * 


*CAS*************************************************** 


Figure 32. Performance Report after Allocating 300 Data Sets in VVDS Sharing Mode 

Comparison of these reports shows the following significant reductions: 

In ECS mode, the average time to process a catalog entry is reduced from 

16.932 MSEC to 6.316 MSEC. 

In VVDS sharing mode, you will find 2,700 VVDS I/Os and 2,100 VVDS 

RESERVE Shr, which reflect the read of the integrity VVRs, and 600 VVDS 

RESERVE CI, which reflects the time stamp update activity in the catalogs 

integrity VVR. 

In ECS mode, there is no VVDS activity at all. Instead, we see 600 IXLCACHE 

writes, which reflect the time stamp update activity in the catalog’s integrity 

VVR held in the Coupling Facility. 

There is no reason why the performance benefits we have experienced would not 

apply to your environment. Performing similar comparisons to those that we run 

will give a good indication as to what you may expect to achieve. 

Operations 51

4.2.5 Replacing AMS LISTCAT with the Catalog Search Interface 

If you are running AMS LISTCAT jobs on a regular basis, for example, to check 

the consistency of catalogs, you may want to consider replacing these jobs by 

implementing the Catalog Search Interface (CSI). Since the CAS can process 

multiple entries for one CSI request, this will result in performance improvements 

when compared with LISTCAT. Please see Appendix A, “Catalog Search 

Interface” on page 83, and Managing Catalogs, SC26-4914, for more information 

on the Catalog Search Interface. 


Chapter 5. Backup and Recovery 

5.1 Backup 

In this chapter we will discuss the importance of an effective backup and recovery 

strategy for catalogs in a Parallel Sysplex environment. We also discuss the 

techniques and utilities that are available for performing backup and recovery. 

Throughout this book, the backup of a catalog is taken to mean that a backup 

copy of the BCS component of the catalog is created. 

In the following sections we discuss: 

Backup 

Tape Volume Catalogs 

Recovery 

Post-recovery updates 

The Integrated Catalog Forward Recovery Utility 

Catalogs are essential system data sets, and in today’s Sysplex environment, it 

becomes more important to ensure backup copies are available. In a shared 

environment, a broken catalog has a tremendous impact to all systems sharing 

the catalog. In a Sysplex environment where the master catalog is shared, a 

broken master catalog may mean an outage of the entire Sysplex. In the topics 

that follow, we discuss the techniques and utilities you can apply to ensure you 

can maintain the integrity of your system after a disaster has struck. 

5.1.1 Backup Frequency 

The most important consideration for the backup frequency should be the time 

needed to recover a broken catalog. The time taken to recover a catalog can be 

decreased depending on how recently the backup copy has been made. 

Conversely, the time taken to recover a catalog without a recent backup copy and 

high catalog update activity may take significantly longer. For some catalogs, a 

daily backup may be sufficient. However, for important applications that result in 

high catalog update activity, you may wish to increase the frequency with which 

you make catalog backups. 

5.1.2 Backup Techniques 

There are a number of different techniques that exist to perform backup and 

recovery for catalogs. These techniques can, in turn, be used by different utilities. 

To simplify your backup procedures, it is possible to utilize the functionality built 

into the Storage Management Subsystem. If the catalog resides on an 

SMS-managed volume, the management class is used to control the backup 

frequency and the number of backup copies. This allows you to define specific 

management classes to achieve your needs for the backup frequency, and the 

number of backups you would like to maintain for different catalogs. SMS will 

invoke the DFSMShsm utility, which will in turn use the AMS EXPORT command to 

perform backup of a catalog. 



The following sections discuss the various backup utilities and techniques that 

you can employ in your environment, along with considerations that are unique to 

these techniques. 

5.1.3 Deciding on the Backup Technique 

Normally, the storage administrator decides which backup technique is 

appropriate. This can be based on speed, utilities available or a number of other 

business reasons. It may even be a combination of different utilities. 

The most important consideration, when deciding upon a backup technique, is 

that you perform some form of checking to ensure that the backup of the catalog 

or catalogs has been successful. We recommend that you test your backup and 

recovery procedures and processes to be sure that the backup copy you have 

created is usable in the event of a disaster. 

You may also want to try out different utilities to see which one best suits your 

environment, and the ease with which post-recovery updates can take place. 

5.1.4 Backup Utilities 

A backup copy of a catalog can be created by one of the following IBM utilities: 

Access method services EXPORT command 

DFSMSdss logical dump 

DFSMSdss full volume dump 

DFSMShsm Availability Management 

To verify that the backup of your catalog has been successful, and the backup 

copy you created is usable, following are sample control statements for the 

different utilities, and the messages that we recommend you check. 

In later topics, we discuss the advantages and disadvantages of these utilities as 

input to your backup and recovery process, and procedure development. 

5.1.4.1 Access Method Services Export command 

For the AMS EXPORT command, see Figure 33, and check that the following 

message is issued for each catalog you backed up: 

IDC0594I PORTABLE DATA SET CREATED SUCCESSFULLY

IDCAMS SYSTEM SERVICES TIME: 17:03:58 

EXPORT - 

UCAT.VSBOX01 - 

OUTFILE(RECEIVE) - 

TEMPORARY 

IDC0005I NUMBER OF RECORDS PROCESSED WAS 506 

IDC0594I PORTABLE DATA SET CREATED SUCCESSFULLY ON 05/14/99 AT 17:03:59 

IDC1147I IT IS RECOMMENDED THAT DIAGNOSE AND EXAMINE BE RUN BEFORE 

IDC1147I IMPORT OF CATALOG 

IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 

IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 

Figure 33. IDCAMS EXPORT joblog Sample 

5.1.4.2 DFSMSdss Logical Dump 

For the DFSMSdss logical dump statements, see Figure 34. Check that the 

following message is issued and shows each catalog you specified in the 

INCLUDE statement: 

ADR454I (001)-DTDSC(01), THE FOLLOWING DATA SETS WERE 

SUCCESSFULLY PROCESSED 

Backup and Recovery 55


Figure 34. DFSMSdss Logical Dump joblog Sample 

5.1.4.3 DFSMSdss Full Volume Dump 

The DFSMSdss control statements for a full volume dump are shown in Figure 

35. Check that the following message is issued to indicate successful completion: 

ADR013I (001)-CLTSK(01), 1999.137 18:30:47 TASK COMPLETED WITH 

RETURN CODE 0000 

. 

PAGE 0001 5695-DF175 DFSMSDSS V1R5.0 DATA SET SERVICES 1999.137 

14:51 

DUMP - 00002002 

DATASET(INCLUDE(UCAT.VSBOX09 - 00003002 

UCAT.VSBOX01 - 00003102 

MCAT.SANDBOX.VSBOX01)) - 00003202 

OUTDDNAME(OUTDD) 00005002 

ADR101I (R/I)-RI01 (01), TASKID 001 HAS BEEN ASSIGNED TO COMMAND 'DUMP ' 

ADR109I (R/I)-RI01 (01), 1999.137 14:51:18 INITIAL SCAN OF USER CONTROL 

STATEMEN 

ADR016I (001)-PRIME(01), RACF LOGGING OPTION IN EFFECT FOR THIS TASK 

ADR006I (001)-STEND(01), 1999.137 14:51:18 EXECUTION BEGINS 

ADR801I (001)-DTDSC(01), DATA SET FILTERING IS COMPLETE. 3 OF 3 DATA SETS 

ADR454I (001)-DTDSC(01), THE FOLLOWING DATA SETS WERE SUCCESSFULLY PROCESSED 

CLUSTER NAME UCAT.VSBOX09 

CATALOG NAME MCAT.SANDBOX.VSBOX01 

COMPONENT NAME UCAT.VSBOX09 

COMPONENT NAME UCAT.VSBOX09.CATINDEX 

CLUSTER NAME UCAT.VSBOX01 


COMPONENT NAME UCAT.VSBOX01 

COMPONENT NAME UCAT.VSBOX01.CATINDEX 

CLUSTER NAME MCAT.SANDBOX.VSBOX01 


COMPONENT NAME MCAT.SANDBOX.VSBOX01 

COMPONENT NAME MCAT.SANDBOX.VSBOX01.CATINDEX 

ADR006I (001)-STEND(02), 1999.137 14:51:19 EXECUTION ENDS 

ADR013I (001)-CLTSK(01), 1999.137 14:51:19 TASK COMPLETED WITH RETURN CODE 

0000

PAGE 0001 5695-DF175 DFSMSDSS V1R5.0 DATA SET SERVICES 1999.137 

18:30 

DUMP FULL - 00009001 

INDDNAME(INDD) - 00009101 

OUTDDNAME(OUTDD) 00009201 

ADR101I (R/I)-RI01 (01), TASKID 001 HAS BEEN ASSIGNED TO COMMAND 'DUMP ' 

ADR109I (R/I)-RI01 (01), 1999.137 18:30:12 INITIAL SCAN OF USER CONTROL 

STATEMEN 

ADR016I (001)-PRIME(01), RACF LOGGING OPTION IN EFFECT FOR THIS TASK 

ADR006I (001)-STEND(01), 1999.137 18:30:12 EXECUTION BEGINS 

ADR006I (001)-STEND(02), 1999.137 18:30:47 EXECUTION ENDS 

ADR013I (001)-CLTSK(01), 1999.137 18:30:47 TASK COMPLETED WITH RETURN CODE 

0000 

ADR012I (SCH)-DSSU (01), 1999.137 18:30:47 DFSMSDSS PROCESSING COMPLETE. 

HIGHEST 

Figure 35. DFSMSdss Full Volume Dump joblog Sample 

5.1.4.4 DFSMShsm 

When utilizing DFSMShsm Availability Management or DFSMShsm command 

backup, you must check the DFSMShsm activity logs for error messages related 

to your catalogs. 

5.1.5 Considerations for Developing the Backup Process 

It is important to understand the requirements that relate to your environment, 

and choose the backup method that satisfies those requirements. There are a 

number of items that we feel it is important for you to consider. They are worthy of 

special attention because they are sometimes overlooked and only become 

apparent during the recovery phase. The items that you should consider are: 

5.1.5.1 BCS and VVDS 

Before you decide which backup technique and utility to use, it is important to 

understand that a backup copy of your catalog only contains data from the BCS 

component of a catalog. To recover a VVDS, you need to restore all data sets 

residing on that volume. 

5.1.5.2 Aliases 

To preserve aliases use the AMS EXPORT command, DFSMSdss logical dump or 

DFSMShsm BACKDS command to backup catalogs. The aliases will be saved in the 

catalog backup copy that is created. 

5.1.5.3 Backup Copy Storage Media 

The media in which the backup copies are stored can be either tape or DASD. 

5.1.5.4 Tape Volume Catalog 

Ensure that backup copies of Tape Volume Catalogs (VOLCAT) are not stored on 

a virtual tape residing in a 3494 Virtual Tape Server (VTS). Additionally, never 

store a backup copy of a VOLCAT to a physical cartridge if you do not have read 

compatible tape drives outside a 3494 or 3495 Automated Tape Library (ATL). 

The reason for this is that you will not be able to access an SMS-managed tape 

volume if the VOLCAT is broken and needs to be recovered. 



5.1.5.5 Integrated Catalog Forward Recovery Utility 

If your environment utilizes, or is considering utilizing, the Integrated Catalog 

Forward Recovery Utility (ICFRU) 1 , remember that ICFRU requires a portable 

copy of the BCS created by an AMS EXPORT command as an input data set. If you 

decide to use a DFSMSdss logical dump or the DFSMShsm BACKDS command to 

create your catalog backup copies, additional steps are needed to create a 

portable backup copy that ICFRU can use. The additional steps for DFSMSdss 

and DFSMShsm are: 

DFSMSdss 

1. Run logical RESTORE for the catalog. 

2. Run AMS EXPORT. 

DFSMShsm 

1. Run RECOVER dsname for the catalog. 

2. Run AMS EXPORT. 

5.1.5.6 DFSMSdss Restore 

Backup copies of catalogs created by DFSMSdss can only be restored to a 

volume with the same volume serial number (VOLSER) as the source volume. 

This means that DFSMSdss logical dump and restore cannot be used to move a 

catalog to a different volume with a different VOLSER. For more information 

about DFSMSdss, refer to DFSMS/MVS V1R5 DFSMSdss Storage 

Administration Guide, SC26-4930. 

To move a catalog to another volume, you need to use DFSMSdss COPY command 

or use AMS EXPORT/IMPORT commands. 

5.1.6 Considerations for Developing the Backup Procedures 

Following the previous topic which deals with product, structural and architectural 

considerations is the philosophy that you employ regarding the backup of your 

catalogs. 

5.1.6.1 Master Catalog Availability 

We recommend that a procedure be implemented to ensure an alternate master 

catalog is always made available. For information on defining and using an 

alternate master catalog, refer to Managing Catalogs, SC26-4914 "Creating and 

Using an Alternate Mastercatalog". 

5.1.6.2 Creating Master Catalog Copies 

Backup copies of the master catalog should be created by an AMS EXPORT job. 

Additionally, periodic full volume dumps of the master catalog’s volume will 

provide the ability to perform a restore by using the stand-alone version of 

DFSMSdss. This is especially useful if the volume cannot be accessed by 

another system. 

5.1.6.3 Creating User Catalog Copies 

For user catalogs, we recommend that you define them on SMS-managed 

volumes. This allows you to control the backup frequency and the number of 

backup copies kept by assigning them to a specific management class which 

matches the requirements of the catalog. 

1 ICFRU is Program Offering, the Program number is 5798-DXQ.

5.2 Tape Volume Catalogs 

We recommend DFSMShsm as the product to create backup copies of your user 

catalogs. As DFSMShsm invokes AMS EXPORT to backup catalogs, the 

DFSMShsm RECOVER dsname command can be used to recover a catalog to a 

volume other than the source. 

As DFSMShsm backups are directed to tape, there are special considerations 

that must be taken for Tape Volume Catalogs. We recommend that the most 

recent backup copy of each VOLCAT should reside on DASD. One of the ways in 

which you can achieve this is to use DFSMSdss logical dump to perform a 

backup of all VOLCATs in one step and direct the DFSMSdss output to a 

generation data set (GDS) on DASD. This means that the latest copies are 

available on DASD. Refer to Figure 36, for sample JCL and DFSMSdss logical 

dump control statements. To create backup copies for catalogs, the catalog 

names must be fully qualified. 

//VOLCATB JOB (ACC3),'WETT3-SAVE',MSGCLASS=K,CLASS=A, 

// MSGLEVEL=(1,1),NOTIFY=&SYSUID 

//DUMP EXEC PGM=ADRDSSU,REGION=6000K 


//OUTDD DD DSN=hlq.VOLCAT.GDG1(+1), 

// UNIT=3390, 

// VOL=SER=volser, 

// SPACE=(CYL,(10,5),RLSE), 

// DISP=(NEW,CATLG,DELETE) 

//SYSIN DD * 

DUMP - 

OUTDDNAME(OUTDD) - 

DATASET(INCLUDE(hlq.VOLCAT.VGENERAL - 

hlq.VOLCAT.VA - 

hlq.VOLCAT.VB - 

hlq.VOLCAT.VC)) 

/* 

Figure 36. Sample JCL for DFSMSdss VOLCAT Backup 

The limit count you specified in the generation data group (GDG) definition will 

control the number of VOLCAT backup copies you would like to maintain on 

DASD. 

Figure 37 shows how to define a GDG in an SMS environment. In this sample up 

to five backup copies can be maintained on DASD. 


5.2.1 Using DFSMSdss 


//DEFGDG1 JOB (7904,NCS),WETT3,MSGLEVEL=(1,1),MSGCLASS=K, 

// &SYSUID,CLASS=A 

//GDGBASE EXEC PGM=IDCAMS 


//SYSIN DD * 

DEFINE - 

GENERATIONDATAGROUP - 

(NAME(hlq.VOLCAT.GDG1) - 

SCRATCH - 

LIMIT(5)) 

/* 

Figure 37. Sample JCL to Create a GDG Base Entry for SMS-Managed GDSs 

Figure 38 shows how to define a non SMS-managed GDG. 

//DEFGDG2 JOB (7904,NCS),WETT3,MSGLEVEL=(1,1),MSGCLASS=K, 

// &SYSUID,CLASS=A 

//GDGBASE EXEC PGM=IDCAMS 

//GDGMOD DD DSN=hlq.VOLCAT.GDG1, 

// DISP=(NEW,KEEP), 

// UNIT=3390, 

// VOL=SER=volser, 

// SPACE=(CYL,(0)), 

// DCB=(DSORG=PS,BLKSIZE=0) 


//SYSIN DD * 

DEFINE - 

GENERATIONDATAGROUP - 

(NAME(hlq.VOLCAT.GDG1) - 

SCRATCH - 

LIMIT(5)) 

/* 

Figure 38. Sample JCL to Create a GDG Base Entry for a non SMS-Managed volume 

The advantage of using DFSMSdss to perform the backups of your VOLCATs is 

that it will backup all VOLCATs in one job step and require one output GDS 

regardless of the number of VOLCATs you have. 

The disadvantage is that you can only recover a catalog with DFSMSdss logical 

restore to a volume with a volser that matches the source. 

5.2.2 Using AMS Export 

IfyoudecidetousetheAMSEXPORT command to backup your VOLCATs, you 

need to define a GDG for each VOLCAT. Only one catalog can be exported by 

one AMS EXPORT command. 

The advantage is that you can AMS IMPORT the catalog to a different volume with 

a different volser.

5.3 Recovery 

If a catalog is broken due to a structural error, or if it is not accessible because of 

a hardware or media problem, it is likely that the catalog needs to be recovered. 

To reduce the outage and its subsequent impact, it is essential to implement a 

recovery methodology that reduces any outage to a minimum. To help you make 

that decision, the following sections describe the considerations that relate to the 

process, procedures, techniques and utilities. 

5.3.1 Determining When to Recover a Catalog 

If a catalog is not accessible, or if a catalog structural error cannot be repaired by 

recovering the damaged record using AMS DELETE and DEFINE commands, it is 

likely that a full recovery of the BCS will be necessary. The outage time can be 

usually reduced the more quickly you can begin your recovery process, and 

procedures are brought in to action. 

5.3.2 Recovery Techniques and Utility Actions 

The technique used to recover a catalog depends on the technique and utility 

used for backup. The relationship between backup and recovery utilities is shown 

in Table 5. 

Table 5. Backup and Recovery Utilities Relationship 

Backup Utility Recover Utility Alias Handling 

AMS EXPORT command AMS IMPORT command Aliases are defined if ALIAS 

is specified with IMPORT 

DFSMSdss logical dump DFSMSdss logical restore Aliases are defined 

DFSMSdss full volume 

dump 

DFSMSdss full volume or 

physical data set restore 

DFSMShsm BACKDS DFSMShsm RECOVER 

dsname 

Regardless of the technique and utility used for backup and recovery, you need to 

manually check for recent changes to the BCS that are not reflected in the 

recovered copy. If you are utilizing ICFRU to create a new portable backup copy, 

this will be done as part of the ICFRU process. 

We strongly recommend that access to the catalog is restricted during any 

maintenance or recovery action, by using the AMS LOCK and UNLOCK commands. 

For more information about catalog recovery and locking refer to Managing 

Catalogs, SC26-4914. 

5.3.3 Considerations for Developing the Recovery Process 

No alias handling 

Aliases are defined 

There are certain elements of any catalog recovery process that must be 

included. In the following topics we discuss those elements that you should 

include when developing your process. 

5.3.3.1 Master Catalog Recovery 

Recovery of a master catalog must be performed from a different system. During 

the time that the catalog is being used as a master catalog, no recovery can be 

performed. For this reason, recovery of a master catalog always results in a 



system outage. If the master catalog is shared in a Sysplex, this means an 

outage for the whole Sysplex. If there is no other system available to perform the 

recovery of the master catalog, a DFSMSdss Stand-Alone restore of the volume 

containing the master catalog may be the only way to recover. 

As long as a catalog is used as a master catalog it cannot be locked. While a 

catalog is locked, any unauthorized requests to access the catalog will fail. Only 

users who have READ access authority to RACF profile IGG.CATLOCK can 

access a locked catalog. 

When there is an alternate master catalog available, an IPL can be performed 

using the alternate master catalog. 

5.3.3.2 Imbed and Replicate 

As explained in “Planning for the New Functions of DFSMS/MVS 1.5” on page 15, 

the use of IMBED and REPLICATE is no longer valid and these keywords will be 

ignored if specified when defining a new catalog. For compatibility reasons, 

IMBED and REPLICATE are still supported for IMPORT and DFSMSdss 

RESTORE. However, we suggest that a catalog be preallocated that has no 

imbedded indexes to simplify any recovery action. This will mean that you need to 

specify the INTOEMPTY keyword for an AMS IMPORT process, or the REPLACE 

keyword for a DFSMSdss logical restore. 

5.3.3.3 Alias Handling and DFSMSdss Restore 

DFSMSdss logical restore handles aliases differently depending on whether the 

catalog is pre-allocated or not. If the catalog to be restored is preallocated but not 

empty, aliases are not restored. (Note: An empty catalog means that the catalog 

contains nothing other than its self describing record.) 

5.3.3.4 Source Volume not Available 

If you must restore the catalog because the source volume is not available, you 

need to use the utility ICKDSF to initialize a different volume with the VOLSER of 

the source volume. 

5.3.3.5 Fully Qualified Name 

With DFSMSdss RESTORE you must specify the fully qualified name to restore a 

catalog. 

5.3.3.6 Catalog Reorganization 

DFSMSdss does not reorganize a catalog during logical restore. 

5.3.3.7 Determining the Most Recent Version 

If your backup and recovery strategy is DFSMShsm, generation numbers are 

available to keep track of the most recent backup version. A catalog cannot be 

recovered with a new name. 

IfyouareusingAMSEXPORT/IMPORT commands, you can use SMF type 36 records 

to determine your most recent backup version. For each successful export of a 

catalog, an SMF type 36 record is created.

5.3.4 Considerations for Developing Recovery Procedures 

In the following topics we discuss the considerations that apply to the recovery of 

catalogs, and the manner in which you can simplify the procedures that are put in 

place. 

5.3.4.1 Master Catalogs 

To recover a broken master catalog, you need to submit an AMS IMPORT job from a 

different system to recover the master catalog from the portable backup copy. 

If you do not have a usable portable backup copy of your master catalog 

available, you must either perform a full volume recovery from a full volume 

backup of the master catalogs volume, or you can perform a physical restore of 

the tracks containing the master catalog. You need to check for recent changes 

which are not reflected in the backup copy that has just been restored. 

Recommendation 

To minimize update activity to the master catalog, and to reduce the exposure 

to breakage, we strongly recommend that only SYS1 data sets, user catalog 

connector records, and the aliases pointing to those connectors should be in 

the master catalog. 

5.3.4.2 User Catalogs 

We recommend using the DFSMShsm RECOVER command in preference to other 

utilities to recover user catalogs. Using DFSMShsm, you do not need to delete 

the broken catalog, because during the recover process, the catalog is deleted 

and redefined using the attributes of the backup copy. If you wish to change the 

size or characteristics of the catalog, you will need to preallocate the catalog. In 

both cases, aliases for that catalog in the systems master catalog will not be 

deleted. Aliases preserved in the backup copy will be defined if they do not 

already exist. 

5.3.4.3 Moving Catalogs to Other Volumes 

The DFSMShsm RECOVER command can also be used to move a catalog to a 

different volume with a different volume serial number. The TOVOLUME keyword 

is available to specify the target non-SMS managed volume. For SMS-managed 

catalogs, the TOVOLUME keyword is only honored if a storage class with the 

GUARANTEED SPACE attribute is assigned. Please refer to the DFSMS/MVS 

V1R5 DFSMShsm Storage Administration Reference, SH21-1075, and 

DFSMS/MVS V1R5 DFSMShsm Storage Administration Guide, SH21-1076, for 

more detailed information. 

5.3.4.4 DFSMSdss User Catalog and VOLCAT Restore 

To recover VOLCATs or user catalogs using DFSMSdss logical restore, you must 

specify the fully qualified name of each catalog you need to restore. 

5.3.4.5 Preventing Catalog Activity during Restore 

Before you run the restore for the catalog, you should restrict access to the 

broken catalog, or define a new catalog by an AMS ALTER command, with the 

LOCK parameter or specify the LOCK parameter when the catalog is initially 

defined. See Figure 39 for a sample job to lock an existing catalog. We have 

already stated that to use the LOCK and UNLOCK parameters for catalogs, you 


5.4 Post-Recovery Updates 


need to have RACF profile IGG.CATLOCK defined. Additionally, you must have 

READ authority to profile IGG.CATLOCK and ALTER authority to the catalog. 

//ALTERL JOB (999,POK),MSGLEVEL=1,NOTIFY=&SYSUID 

//ALTER EXEC PGM=IDCAMS 

//UCAT DD VOL=SER=volser,UNIT=3390,DISP=SHR 


//SYSIN DD * 

ALTER - 

SYS1.VOLCAT.VGENERAL - 

LOCK - 

FILE(UCAT) 

/* 

Figure39. SampleJCLtoLockaCatalogbyIDCAMSALTERLOCKCommand 

Depending on whether the catalog to be restored is preallocated or still exists, 

you must specify the REPLACE keyword on the DFSMSdss RESTORE job. 

Figure 40 shows sample JCL to restore the most recent backup copy of a 

VOLCAT: 

//VOLCATR JOB (ACCT#),'WETT3-RES',MSGCLASS=K,CLASS=S, 

// MSGLEVEL=(1,1),NOTIFY=&SYSUID 

//RESTORE EXEC PGM=ADRDSSU,REGION=6000K 


//INDD DD DSN=hlq.VOLCAT.GDG1(+0), 

//OUTDD DD UNIT=3390,VOL=SER=volser,DISP=SHR 

//SYSIN DD * 

RESTORE - 

DATASET(INCLUDE(hlq.VOLCAT.VGENERAL)) - 

INDDNAME(INDDD) - 


REPLACE 

/* 

Figure 40. Sample JCL to Restore the Most Recent Catalog Backup Copy from a GDS 

The version of your catalog that you have just recovered reflects the status of the 

catalog at the time the backup copy was taken. If you are not using ICFRU or 

other vendor utilities, for example, Catalog Solution (a trademark of 

SOFTWORKS), you must manually check for changes to the catalog which are 

not reflected in the recovered copy. 

5.4.1 Manually Checking for Missing Updates 

To check for changes which are not reflected, you can use the AMS DIAGNOSE 

command to compare the VVDSs to the BCS. You need to list VVDSs connected 

to the catalog to find out which VVDSs you need to compare against the BCS. 

This only will work for VSAM and SMS-managed data sets because non-SMS 

managed and tape data sets are not reflected in a VVDS. Issuing the LISTCAT 

NONVSAM command before and after the recovery may help to find changes for 

non-SMS managed and tape data sets.

A more efficient way to check for changes since the last backup was taken is to 

collect and check SMF records generated by the ICF. You must make sure that 

you are not suppressing SMF record types 61, 65, and 66 in member SMFPRMxx 

in SYS1.PARMLIB for all jobs including subsystems and system tasks. 

The record types that are created and need to be analyzed are: 

RECORD TYPE 61 (3D) 

Created by ICF DEFINE ACTIVITY: 

IDCAMS DEFINE 

IEHPROGM CATLG 

RECORD TYPE 65 (41) 

Created by ICF DELETE ACTIVITY: 

IDCAMS DELETE 

IEHPROGM UNCATLG 

RECORD TYPE 66 (42) 

Created by ICF ALTER ACTIVITY: 

IDCAMS ALTER 

5.4.2 Using DFSORT in the Checking Process 

The IBM product DFSORT can be used to filter out the SMF records for a specific 

catalog corresponding to the time frame since the last backup copy was made. 

Figure 41 shows sample DFSORT control statements to collect catalog related 

record types: 

//SYSIN DD * 

OPTION VLSHRT 

RECORD TYPE=V 

INCLUDE COND=((6,1,BI,EQ,X'3D'),AND, 

(11,4,BI,GT,X'0099115F'),AND, 

(76,20,CH,EQ,C'MCAT.SANDBOX.VSBOX01')) 

SORT FIELDS=(11,4,BI,A) 

/* 

Figure 41. DFSORT Control Statements to Collect SMF Record type 61 

In the sample in Figure 41: 

The first comparison checks for SMF record type 61 (3D). 

The second comparison checks records created after day 99115. 

The third comparison checks for a 20-character catalog name 

MCAT.SANDBOX.VSBOX01. 

The SORT FIELDS Statement sorts the records by date in ascending order. 

For more information with respect to the format and contents of the SMF records 

see OS/390 V2R7.0 MVS System Management Facilities (SMF), GC28-1783. 


5.5 Integrated Catalog Forward Recovery Utility 


Integrated Catalog Forward Recovery Utility (ICFRU) is a powerful utility that will 

help you to reduce any outage to a minimum where forward recovery of a catalog 

is required. 

ICFRU Requirements: 

ICFRU needs a backup copy of the BCS, created by an AMS EXPORT command, 

known as the portable backup copy as its foundation. If this portable copy is not 

available, then ICFRU cannot be used. 

Additionally, SMF record types 61, 65, and 66 created by ICF activity will be 

needed from all systems sharing the catalog to be recovered. These SMF records 

can be handled as a log file for catalog changes. The SMF records contain the 

complete sphere of each catalog record added, deleted or altered. These catalog 

records can be combined with the catalog records from the portable backup copy 

to create a new portable backup copy of the catalog to be recovered. This new 

updated portable copy can be used as an input data set for the AMS IMPORT 


ICFRU actually uses two programs. First, the Integrated Catalog Forward 

Recovery Record Selection and Validation (ICFRRSV) program performs the 

extract of the appropriate SMF records. These records are then sorted by calling 

DFSORT, and are processed together with records from the EXPORT copy by the 

Integrated Catalog Forward Recovery Record Analysis and Processing 

(ICFRRAP) program to create the new portable data set. 

See Figure 42 for a simplified data flow of ICFRU. For more detailed information, 

refer to Integrated Catalog Forward Recovery Utility Program 

Description/Operations, SH20-6952.

Actual SMF records 

SYS1.SC63.MANx SYS1.SC64.MANx 

portable 

backup copy 

created by 

export 

Figure 42. ICFRU Simplified Data Flow 

ICFRU Accumulated SMF records 

SYS1.SC65.MANx 

selected 

and sorted 

SMF recors 

ICFRU 

newportable 

backup copy 

IDCAMS 

IMPORT 

RECOVERED 

CATALOG 

ICFRU Reports 

If you do not have a portable backup copy of the catalog you wish to recover, for 

example, because you use DFSMShsm or DFSMSdss to create your catalog 

backups, you will need to recover the catalog according to the backup utility you 

are using. 

Once this copy is created, you can issue an AMS EXPORT command to create a 

portable copy of the catalog to be recovered and use this as input to ICFRU. 



Chapter 6. Analyzing Structural Integrity 

6.1 Structural Integrity 

In the sections that follow, we describe why it is necessary to analyze the 

structural integrity of your catalogs, and how to ascertain if the data set 

information in the BCS, VVDS and VTOC is in synchronization. We will show 

what utilities are available and how to recover from structural errors. 

In the following sections we cover: 

Structural integrity considerations 

Synchronization errors and correction 

Failures associated with catalog sharing 

Failures affecting the CAS 

Structural errors in your catalog environment may result in lack of access to data 

sets defined in the failing catalog, as well as an impact on the CAS for all systems 

sharing the catalog that has been structurally compromised. This may result in an 

abend or hang situations for the CAS. In a sysplex environment it is important to 

keep vital system address spaces like the CAS running. 

6.1.1 When to Check the Structural Integrity 

You should suspect the structural integrity of a catalog if non-zero return codes 

are issued during your daily catalog backup. The same is true if you receive any 

error messages or non-zero return codes accessing a catalog. These should 

send a clear signal that you should check the structural integrity and take the 

appropriate repair action. We suggest that you regularly run jobs to check the 

structural integrity of your catalogs. This will create additional sysplex resource 

overhead, but it may decrease the chance of suffering an outage of the sysplex if 

a structural error is not fixed before it becomes more serious. Like a computer 

virus, a structural error may exist and do no harm until a certain condition occurs. 

An example of this could be a control interval (CI) or control area (CA) split 

failure, which may have the end result that your catalog is no longer accessible, 

and abends in the CAS may be seen. 

6.1.2 How to Check the Structural Integrity 

We recommend that the internal VSAM structure of catalogs should be checked 

using the AMS EXAMINE command, which analyzes and reports on the structural 

integrity of the index and data components of the catalog. We recommend that 

INDEXTEST as well as DATATEST should be performed. 

If EXAMINE detects an error related to a certain entry, you can try to use the AMS 

DELETE command to delete this entry. However, it is important that, before any 

recovery action or delete is attempted, that you try to take a backup of the data 

set or the entry. If a partial cluster entry is detected, an AMS DELETE command 

using the TRUENAME parameter can correct the situation. 

If deletion of the failing entry is possible, you will then need to re-run EXAMINE. If 

there are no further errors detected, you can redefine and recover the failing 

entry. 



In most cases a catalog structural error means that you will need to recover the 

BCS from the most recent backup copy. 

6.1.3 The Consequences of Neglecting Structural Integrity 

Backup utilities may fail if they detect a structural error and leave you without a 

backup copy of the catalog. This may require some explaining in a recovery 

situation! There is also the chance that backup utilities will not detect a structural 

error in your catalog, which may mean that the backup copies taken are 

unusable. This will result in an additional, unnecessary outage if you need to 

recover the catalog. You will need to find the last usable backup copy and then 

carry out the post-recovery actions described in 5.4, “Post-Recovery Updates” on 

page 64. This has the result of extending the time period that you must look for 

updates to the catalog. 

6.2 Synchronization Errors 

In addition to the internal structure of catalogs, you should also check for 

synchronization errors. Synchronization errors may be the result of AMS DEFINE, 

DELETE or ALTER jobs that were canceled by force, or due to system errors not 

allowing a job to complete successfully. In this case the necessary cleanup 

actions may not be done. Differences between BCS, VVDS and VTOC may make 

a data set inaccessible or otherwise unusable and may also lead to CAS 

problems. 

The dependencies between BCS and VVDS for SMS-managed volumes, as well 

as for non-SMS managed volumes, are shown in Figure 43. 

SBOX02 

SMS 

VTOC 

VTOCIX 

VVDS 

UCAT.SBOX02 

VSAM UCAT.SBOX02 

VTOC 

VTOCIX 

VVDS 

SBOX01 

NON-SMS 

MCAT.SBOX01 

MCAT.SBOX01 

nonVSAM MCAT.SBOX01 

Figure 43. ICF-Catalog BCS, VVDS Dependencies 

VTOC 

VTOCIX 

VVDS 

SBOX03 

SMS 

SMS 

nonVSAM MCAT.SBOX01 

VSAM UCAT.SBOX02

Volume SBOX01 is non-SMS-managed and contains a master catalog as well as 

one non-SMS-managed, non-VSAM data set cataloged in the master catalog 

MCAT.SBOX01. 

Volume SBOX02 contains a user catalog, UCAT.SBOX02; and one VSAM KSDS 

cluster cataloged in UCAT.SBOX02. 

Volume SBOX03 contains one SMS-managed, non-VSAM data set cataloged in 

the master catalog; and one SMS-managed VSAM KSDS cluster cataloged in 

user catalog UCAT.SBOX02. 

The contents of the BCS, VVDS and VTOC for all volumes are as follows: 

SBOX01 non-SMS managed volume 

BCS MCAT.SBOX01 

UCAT connector record for UCAT.SBOX02 

Entry for SYS1.VVDS.VSBOX01 

Entry for SYS1.VVDS.VSBOX02 

Entry for non-VSAM non-SMS managed data set on SBOX01 

Entry for non-VSAM SMS-managed data set on SBOX03 

VVDS 

VVR VVDS self-describing 

VVR for MCAT index component 

VVR for MCAT data component 

VTOC 

F4DSCB 

F1DSCB for VTOCIX 

F1DSCB for VVDS 

F1DSCB for MCAT index component 

F1DSCB for MCAT data component 

F1DSCB for non-VSAM data set 

SBOX02 SMS-managed volume 

BCS 

Entry for SYS1.VVDS.SBOX02 

Entry for VSAM KSDS on volume SBOX02 

Entry for VSAM KSDS on volume SBOX03 

VVDS 


VVR for UCAT.SBOX02 index component 

VVR for UCAT.SBOX02 data component 

VVR for VSAM KSDS index component 

VVR for VSAM KSDS data component 

VTOC 

Analyzing Structural Integrity 71


F4DSCB 



F1DSCB for UCAT.SBOX02 index component 

F1DSCB for UCAT.SBOX02 data component 

F1DSCB for VSAM KSDS index component 

F1DSCB for VSAM KSDS data component 

SBOX03 SMS-managed volume 

VVDS 


VVR for KSDS index component 

VVR for KSDS data component 

NVR for non-VSAM SMS managed data set 

VTOC 

F4DSCB 



F1DSCB for KSDS index component 

F1DSCB for KSDS data component 

F1DSCB for non-VSAM 

6.2.1 What Causes Synchronization Errors 

Common synchronization errors can be caused by: 

BCS entry missing 

VVDS entry missing 

Duplicate VVRs or NVRs 

Orphan VVRs or NVRs 

Uncataloged VSAM or SMS-managed non-VSAM data sets 

VTOC entry missing 

6.2.2 Detecting Synchronization Errors 

Using the AMS DIAGNOSE command, you can analyze and check the dependent 

content and validity of catalog and VVDS records. To check the dependent 

content of catalog records, you need to specify the COMPAREDD or the 

COMPAREDS keywords with the DIAGNOSE command. 

To compare a BCS against the VVDS, you must specify: 

DIAGNOSE ICFCATLOG COMPAREDD(diag01) 

To compare a VVDS against a BCS, you must specify: 

DIAGNOSE VVDS COMPAREDD(diag01)

If you are comparing: 

A BCS: the VVDS is checked for dependency. 

A VVDS: the BCS and the VTOC are checked for dependency. 

To make sure that all possible errors will be detected, both checks must be 

performed. 

SeeFigure44forsampleJCLtoDIAGNOSE BCS records and check the dependent 

records of the VVDS on volumes SBOX01 and SBOX02. 

//TATERS3 JOB (999,POK),MSGLEVEL=1,NOTIFY=&SYSUID 

//DIAGN EXEC PGM=IDCAMS 

//DIAG01 DD VOL=SER=SBOX01,UNIT=3390,DISP=SHR, 

// DSN=SYS1.VVDS.VSBOX01,AMP='AMORG' 

//DIAG02 DD VOL=SER=SBOX02,UNIT=3390,DISP=SHR, 


//DIAGDD DD DSN=MCAT.SANDBOX.VSBOX01,DISP=SHR 


//SYSIN DD * 

DIAGNOSE - 

ICFCATALOG - 

INFILE(DIAGDD) - 

COMPAREDD(DIAG01 DIAG02) 

/* 

Figure 44. Sample to DIAGNOSE a BCS and Compare to Two VVDSs 

Figure 45 shows sample JCL to run DIAGNOSE for the VVDS of volume SBOX01: A 

compare is performed against the BCS records of catalog 

MCAT.SANDBOX.VSBOX01 and dependency to the VTOC of volume SBOX01 is 

checked. 


//DIAGN EXEC PGM=IDCAMS 

//DIAGDD DD VOL=SER=SBOX01,UNIT=3390,DISP=SHR, 


//CAT01 DD DSN=MCAT.SANDBOX.VSBOX01,DISP=SHR 


//SYSIN DD * 

DIAGNOSE - 

ICFCATALOG - 

INFILE(DIAGDD) - 

COMPAREDD(CAT01) 

/* 

Figure45. SampleJCLtoDIAGNOSEaVVDSandComparetoaBCS 

To determine which VVDSs are connected to a BCS, you can use LISTCAT 

LEVEL(SYS1.VVDS). The BCS name needs to be specified in the CATALOG 

parameter. Care should be taken because this LISTCAT will show only the volumes 

for which a SYS1.VVDS.Vvolser entry exits. There may also be catalog records in 

the BCS for data sets which reside on volumes for which no SYS1.VVDS.Vvolser 

entry exists in the BCS. 



Another fast and easy way to detect duplicate VVRs, orphan VVRs or 

uncataloged data sets is to run DFSMSdss logical dump specifying 

PARM='TYPRUN=NORUN' on the EXEC statement. This means all filtering for the logical 

dump is performed but no data set is processed or moved. 

Figure 46 shows sample DFSMSdss logical dump JCL and control statements. 


//DUMP02 EXEC PGM=ADRDSSU,REGION=6000K,PARM='TYPRUN=NORUN' 


//OUTDD DD DUMMY 

//SYSIN DD * 

DUMP - 

DATASET(INCLUDE(**)) - 

LOGINDY(SBOX02) - 


TOL(ENQF) 

/* 

Figure 46. Sample JCL for DFSMSdss to Detect Duplicate or Orphan VVRs 

6.2.3 Repairing Synchronization Errors 

Different errors may force you to take different repair actions. Table 6 shows 

which AMS commands need to be performed for different error situations and 

data set types; and which functional components (BCS,VVDS,VTOC) are 

changed by what actions. Some of these actions can also be done by ISPF/PDF 

catalog or uncatalog. For example, delete of a catalog record for a non-VSAM 

data set can be done by an ISPF/PDF UNCATALOG command. 

Uncataloged VSAM and non-VSAM SMS-managed data sets can also be 

detected by ISMF and can be deleted by the ISMF DELETE line command. Under 

the covers, an ISMF DELETE line command issues an AMS DELETE VVR or NVR.

Table 6. Overview of Repair Actions Performed by IDCAMS 

Error Situation Data Set Type Action needed BCS VVDS VTOC 

VTOC entry 

missing 

VTOC entry 

missing 

VTOC entry 

missing 

VVDS entry 

missing 

Catalog (BCS) 

entry missing 


entry missing 


entry missing 

Orphan VVR 

or NVR 

Duplicate VVR 

or NVR 

SMS managed 

NON-VSAM 

Non-SMS 

managed 

NON-VSAM 

DELETE NOSCRATCH a 

DELETE NVR b 

Recoverorre-allocate 

DELETE NOSCRATCH X 

VSAM DELETE CLUSTER 

NOSCRATCH 

DELETE VVR b,d 

DEFINE CLUSTER and 

recover 

VSAM and 

SMS managed 

NON-VSAM 

SMS managed 

NON-VSAM 

NON-SMS- 

NON-VSAM 

VSAM SMS or 

NON-SMS 

VSAM or SMS 

NON-VSAM 

VSAM or SMS 

NON-VSAM 

DELETE NOSCRATCH 

DELETE VVR/NVR c,d 

Recoverorre-allocate 

DEFINE NONVSAM 

RECATALOG b,e 

DEFINE NONVSAM X 

DEFINE CLUSTER 

RECATALOG b,e 

DELETE VVR f 

DELETE NVR f 

RENAME or DELETE the 

data set. 

DELETE VVR/NVR b,d,f 

RENAME Or DEFINE 

to old name 

a. Removal of BCS is entry is required to do DELETE VVR/NVR. 

b. Requires that the catalog pointed to in VVR/NVR is available. 

c. This deletes also the VTOC entries. 

d. For VSAM this needs to be done for each component by component name. 

e. DEFINE RECATLOG can only be done into the catalog pointed to by the VVR/NVR. In 

case this is not the right catalog, you can use IDCAMS REPRO MERGECAT afterwards to 

move the catalog entry. 

f. Print of VVDS will be needed to get the component name. 

Duplicate or orphan VVRs or NVRs will be detected by the AMS DIAGNOSE 

command. In some cases you may need to print the VVDS to check for duplicate 

or orphan entries. You can use either the AMS or DFSMSdss PRINT command to 

print a VVDS. 

Figure 47 shows sample JCL to print a VVDS using the DFSMSdss PRINT 


X 

X 

X 

X 

X 

X X 

X 

X 

X 

X 

X 

X X 

X 

X X 

X 

X 

X 

X 

Analyzing Structural Integrity 75 

X 

X 

X X



//DFDSS EXEC PGM=ADRDSSU 



//DD1 DD UNIT=3390,DISP=SHR,VOL=SER=SBOX02 

//SYSIN DD * 

PRINT INDDNAME(DD1) - 

DATASET(SYS1.VVDS.VSBOX02) - 

TOL(ENQF) 

/* 

Figure47. SampleJCLtoPrintaVVDSbyDFSMSdss 

VSAM data sets and non-VSAM SMS-managed data sets with a HLQ of SYS1 

can be cataloged in more than one BCS. This can be done by AMS DEFINE 

RECATALOG. In this case the VVR/NVR still points to the original catalog. This is 

a situation which might be detected by DIAGNOSE but this is not considered a 

structural or synchronization error. 

6.2.4 Utilities and Tools Available for Diagnosis 

A variety of different utilities and tools are available to diagnose the different 

components and their relationship to each other. We list some of those utilities 

below: 


IDCAMS 

LISTCAT 

EXAMINE 

DIAGNOSE 

PRINT 

DFSMSdss 

PRINT 

Catalog Solution 

VVDS 

IDCAMS 

LISTCAT 

DIAGNOSE 

PRINT 

DFSMSdss 

PRINT 

Catalog Solution 

VTOC 

IEHLIST 

LISTVTOC DUMP|FORMAT

DFSMSdss 

PRINT 

DEFRAG specify PARM=’TYPRUN=NORUN,TRACE=YES’ 

ICKDSF 

BUILDIX 

6.2.5 VSAM Knowledge Database 

You may also like to visit the VSAM Knowledge Base, which is an interactive 

diagnostic tool. It is a question-and-answer driven knowledge data base that 

resides on the DFSMS/MVS Technical Support Website under "Technical 

Database" at the following URL: 

http://knowledge.storage.ibm.com/ 

6.3 Catalog Sharing Problems 

Catalog structural and synchronization errors may also occur due to failures in 

establishing the proper catalog sharing environment. 

6.3.1 Error Symptoms Due to Sharing Problems 

A typical symptom for a catalog sharing problem is that catalog entries created on 

one system cannot be found on another system sharing the same catalog. A 

no-record-found condition will be indicated by either of the following messages: 

or 

IDC3009I ** VSAM CATALOG RETURN CODE IS 8 - REASON CODE IS IGG0CLEG-42 

IDC3012I ENTRY entname NOT FOUND 

There are two conditions that must both be met to establish the proper catalog 

sharing environment: 

The catalog must be defined using SHAREOPTIONS(3,4), which is the default 

for catalogs. 

The catalog must reside on a DASD volume that is defined with the 

FEATURE=SHARED option using hardware configuration definition (HCD) on 

all sharing systems. 

Also, we suggest that you revisit 1.3, “A Review of the SHAREOPTIONS 

Parameter” on page 7. 

A common user error related to this is that a catalog resides on a DASD volume 

that is defined as shared in HCD on one system, but not on the sharing system. 

This situation can be temporarily resolved by issuing the command: 

F CATALOG,CLOSE(catalogname) 

or, it may be resolved by restarting CAS using the command on the failing 

system: 

F CATALOG,RESTART 



However, extreme care should be taken if this situation occurs. If the system 

which has seen the no-record-found condition is going to update the catalog, 

updates done by the other system may be lost. The result is a corrupted catalog. 

6.3.2 Determining If a Catalog is Actually Shared 

There is a very convenient way to verify that a catalog is shared: You can issue 

the following command on all sharing systems: 

F CATALOG,OPEN 

The status display, as shown in Figure 49 on page 80, will show you if a catalog is 

considered as shared. You need to check the CAS FLAGS for either ’E’, to 

indicate ECS mode, or ’R’ to indicate VVDS mode sharing. If neither of the sharing 

flags is shown, you can be certain that the two conditions for sharing a catalog 

are not met. It may be that on one of the sharing systems the DASD volume is not 

defined as shared in HCD. In this case you will see the ’R’ flag on the systems that 

meet the conditions, but not on the systems that do not. 

The ’E’ flag will only be seen if ECS is active for that catalog, and this means that 

the conditions for shared catalogs are met on all systems in the sysplex. 

Additionally, if you do not see the ’R’ flag on one of the sharing systems, you can 

use the DEVSERV QUERY DASD system command to check the reserve release (RR) 

bit in the UCB of this volume. Issue the following command: 

DS QD,devnumber,1,UCB 

See Figure 48 for sample output from the DEVSERV QUERY DASD command. You need 

to check for the RR bit in UCB common segment at offset x’11’ bit 2=ON(..1. ....).

IEE459I 14.19.16 DEVSERV QDASD 093 

UNIT VOLSER SCUTYPE DEVTYPE CYL SSID SCU-SERIAL DEV-SERIAL EF-CHK 

0CC2 SBOX02 3990006 3390A28 2226 000A 0113-90802 0113-T0177 **OK** 

UCB AT V00F1B350 

008AFF8C0CC20000 0000000000C3C3F2 3030200F00F1B328 41280100E2C2D6E7 

F0F2040800000011 ^ 

UCB PREFIX AT V024E94C8 

000C804000000000 000000000001038C 289C009BE00080F8 082088A4F5FFFFFF 

0108000000000001 

UCB COMMON EXTENSION AT V00F1B328 

0000094020AA0000 024E94C800000031 0000000000FCAF54 00F1B2F000000000 

**** 1 DEVICE(S) MET THE SELECTION CRITERIA 

**** 0 DEVICE(S) FAILED EXTENDED FUNCTION CHECKING 

Figure 48. Sample Output of the DS QT,0CC2,1,UCB Command. 

6.4 CAS Problems Due to Catalog Structural or Synchronization Errors 

As we stated earlier, broken catalogs can influence the CAS, and abends or hang 

situations may be seen in the CAS. User jobs might also be affected, and may 

see abends or catalog error messages of the format IDCxxxxx issued. 

6.4.1 CAS ABEND or Error Messages 

The most important catalog management message to observe is: 

IDC3009I VSAM CATALOG RETURN CODE IS rtn - REASON CODE IS IGGOCLaa - rsn 

Using the command MODIFY CATALOG,DUMPON(retcode,rsncode,modid), you can force 

the CAS to create a dump whenever a given return code, reason code, and 

module identifier are provided in the IDC3009I message. 

For unexpected abends in the CAS, a dump is always created. There are certain 

forced (expected) abends in CAS, for example, abend81A during CAS restart, for 

which there is no dump created. Using the command F CATALOG,DUMPON with no 

additional options specified will create a dump for expected abends. 

6.4.2 CAS Hang or Lockout Situations 

If a user address space is waiting for the CAS, and CAS does not respond due to 

a hang or lockout situation, you can try different MODIFY CATALOG commands to 

attempt to alleviate the situation. 

First issue the command F CATALOG,OPEN which will provide a list of open catalogs 

and the volser of the allocated DASD as well as information about caching and 

sharing. Figure 49 shows the sample output from this command. 



F CATALOG,OPEN 


IEC348I ALLOCATED CATALOGS 687 

*CAS*************************************************************** 

* FLAGS -VOLSER-USER-CATALOG NAME * 

* Y-I-R- SBOX09 0001 UCAT.VSBOX09 * 

* Y-I-E- SBOX01 0001 UCAT.VSBOX01 * 

* Y-I-E- SBOX01 0001 MCAT.SANDBOX.VSBOX01 * 

******************************************************************* 

* Y/N-ALLOCATED TO CAS, S-SMS, V-VLF, I-ISC, C-CLOSED, D-DELETED, * 

* R-SHARED, A-ATL, E-ECS SHARED, K-LOCKED * 

*CAS*************************************************************** 


Figure 49. Catalog Status Display for Open Catalogs 

If you suspect that a certain catalog is causing the error, you can issue the 

command F CATALOG,CLOSE(catname) to close the suspected catalog. It will 

automatically be reopened at the next request for that catalog. 

ThenextstepistoissuethecommandF CATALOG,LIST. A list of catalog tasks and 

their status is provided. Each task has a unique ID. 

Figure 50 shows sample output from this command. 

F CATALOG,LIST 



*CAS**************************************************************** 

* FLAGS - TASK ADDRESS - JOBNAME / STEPNAME - ELAPSED TIME - ID * 

* -W-E-- 00886108 TATERS3L / IDCAMS 00.00.01 01 * 

******************************************************************** 

* O-OLDEST, W-WAIT, A-ABEND, E-ENQ, R-RECALL, L-RLS * 

*CAS**************************************************************** 


Figure 50. Catalog Task and Status Display 

With the information from the CAS task and status display, you might consider 

cancelling the job which is holding the E-ENQ. To clear this condition, issue the 

command F CATALOG,END(id), where id is the id of the O-OLDEST task. In most 

cases this will solve the hang or lockout situation. In some cases the sequence of 

F CATALOG,LIST and F CATALOG,END,(id) commands needs to be repeated until the 

situation is resolved. 

For diagnostic purposes, and certainly before you are going to cancel jobs or 

issue commands to manipulate the CAS, you should take a CAS dump using the 

following system commands and dump options: 

DUMP COMM=(title) 

Rid,JOBNAME=(CATALOG),SDATA=(CSA,LPA,LSQA,SQA,RGN,GRSQ,SWA,TRT,SUM) 

Keep in mind that the command F CATALOG,RESTART is considered as the last resort 

before an IPL. The reason for this is that all current catalog requests need to be 

ended and will have to be resumed after the CAS restart. If a CAS request cannot

e ended because of an outstanding I/O operation, the CAS restart will fail. This 

will finally result in an IPL needing to be performed. 

For further information, see Managing Catalogs, SC26-4914. For a complete and 

up to date corrected description of the MODIFY CATALOG commands refer to 

Appendix B.1, “MODIFY CATALOG Command Syntax” on page 101. 



Appendix A. Catalog Search Interface 

A.1 CSI Setup 

The Catalog Search Interface (CSI) is shipped as a component of base 

DFSMS/MVS 1.5. As its use is not widespread, we will take this opportunity to 

remind you of its availability and to point out its advantages over other methods of 

obtaining catalog information. The following sections describe: 

CSI setup 

CSI programming considerations 

The IBM supplied sample programs 

Real world example of CSI usage with sample code 

The CSI is a general-use programming interface for obtaining information from 

ICF catalogs. It provides great flexibility in specifying the selection criteria for the 

data that is to be returned. The CSI may be invoked by assembler programs, 

high-level language programs and REXX execs. See Managing Catalogs, 

SC26-4914 for a complete description of the interface. 

Much of the information you can obtain from the CSI you could also obtain using 

an AMS LISTCAT command. However, there are some advantages that you may 

want to consider when accessing catalog information: 

Using a Generic Filter Key. When requesting information from the CSI for 

specific catalog entries, you may specify a generic filter key. This key can 

contain the following symbols used to filter the entry names: 

* A single asterisk to represent one or more characters within a qualifier 

** A double asterisk to represent zero or more qualifiers 

% A percent sign to represent one alphanumeric or national character 

%%... Up to eight characters can be specified in one qualifier 

Using the AMS LISTCAT command, you can request either information for 

specific ENTRIES or a LEVEL (entries beginning with the specified name), 

where generic names may contain one asterisk to represent one qualifier. For 

example, if you wanted to retrieve information about Language Environment 

target libraries, you could call the CSI and specify a generic filter key of 

CEE.**.SCEE*. Using the LISTCAT command you could only request 

information for LEVEL(CEE) and then scan AMS’s output matching your 

requirements. 

Using Selection Criteria Fields. When requesting information from the CSI 

for specific catalog fields, you may specify a list of field names. For example, if 

you were only interested in the volume and the file sequence number for 

specific data sets, you could specify the catalog field names VOLSER and 

FILESEQ in the field name list when calling the CSI. Obtaining this information 

from AMS would require you to use the AMS LISTCAT ALL command and to 

scan the output to retrieve the desired information. 

Performance Benefits. Using the CSI generally results in significantly better 

performance compared to using AMS LISTCAT, which does a catalog call for 

each entry processed. The flexibility in requesting only the information that 


A.2 CSI Programming Considerations 


you are interested in from the CSI results in additional performance 

improvements, since you eliminate the retrieval of information that you will 

discard later. 

The CSI is distributed as load module IGGCSI00 in SYS1.LINKLIB. It is reentrant 

and reusable, can be invoked in 24-bit or 31-bit addressing mode, in any 

protection key, and in either problem or supervisor state. 

CSI requires three parameters to process your request: 

A 4-byte reason area used to return error or status information 

A variable length selection criteria list 

A work area used to return the requested catalog data 

Reason area: This 4-byte area provides additional information when a CSI 

request fails with return code 4 or 8. The reason area contains a 2-byte module 

ID, followed by a catalog reason and return code. 

Selection criteria list: This list is used to specify the generic filter key for the 

entries to be obtained, an optional catalog name, a list of requested entry types, 

and a variable length table of requested catalog field names. Copy code member 

IGGCSINA in SYS1.MACLIB provides a mapping for the selection criteria list. 

Work Area: This area contains the requested information from the catalog. It can 

reside anywhere, and can have a size between 1 KB and 1 MB. Generally a size 

of 64 KB is recommended. The information returned will be in the following 

sequence: 

Work area information. This contains the total length of the work area, the 

minimum length required for one catalog entry and one data entry, the length 

of the returned catalog data, and the number of field names. 

Catalog information. This contains the catalog name, and a return and 

reason code in case of an error processing this catalog. The following 

information will be for entries defined in this catalog. If multiple catalogs have 

been processed, this will then be followed by the next catalog’s information. 

Entry information. This contains the entry type, the entry name, a return and 

reason code in case of an error processing this entry, and the length of field 

data returned for this entry. The following field information will apply to this 

entry, which will then be followed by the next entry information. Entry 

information will be provided in alphabetical order. 

Field name information. This consists of the total length field, an array of 

individual field lengths, and the field data itself. All length fields are 2-byte 

unsigned numbers. Depending on the fields requested, the returned data may 

be of fixed length (such as the expiration date DSEXDT2), of variable length 

(such as the SMS storage class STORCLAS), or may be an array of fields 

(such as the volume serial number VOLSER). Field information is provided in 

the sequence of the field name list specified in the selection criteria. 

To retrieve the information from the work area you will probably need to code a 

nested loop processing the data first by catalog level, next by entry level, and 

finally by field level. Depending on the number of entries matching your search

A.3 IBM Supplied Sample Programs 

criteria, the results may not fit into the work area. In this case, CSI will set fields in 

the selection criteria list, CSIRESUM and CSIRESNM, that allow you to resume 

the information retrieval with subsequent calls to CSI. 

IBM provides three sample assembler programs and one REXX exec in 

SYS1.SAMPLIB. Here we provide a short summary of their functions. Refer to 

Managing Catalogs, SC26-4914 for a complete description of these sample 

programs. 

IGGCSILK produces output similar to that of an AMS LISTCAT CAT(catname) 

command. The input to this program is the catalog name specified left-justified 

on an 80-byte SYSIN record. 

IGGCSIVG identifies unused space at the end of VSAM data sets defined in a 

given catalog. This is calculated as the difference of the high-allocated and the 

high-used relative byte address (HARBA-HURBA). Again, the catalog name is 

specified left-justified on an 80-byte SYSIN record. 

IGGCSIVS produces a list of data set names defined in a given catalog that 

reside on a specific volume. Such a list might be helpful in a recovery situation 

affecting that volume. The volume serial number is specified in columns 1 to 6 

of an 80-byte SYSIN record, and the catalog name is specified starting in 

column 7. 

IGGCSIRX is a REXX exec that produces a list of data set names matching a 

generic filter key. When you call it from a TSO/E session, it will prompt you for 

the filter key, and return matching data set names, their type, and volume 

definition. 

To get an idea of the performance benefits of using CSI, we assembled 

IGGCSILK and ran it in comparison with an AMS LISTCAT to list all entry names in 

our sandbox master catalog. Table 7 shows the times used to list the 4505 entries 

in the catalog. 

Being curious about the reasons for the differences, we then ran Generalized 

Trace Facility (GTF) traces to count the number of ENQ’s/RESERVE’s and DEQ’s 

for AMS and CSI. From these figures, also included in Table 7, we can see that 

the numbers of ENQs/RESERVEs and DEQs for AMS are multiples of the number 

of entries in the catalog. In the case of CSI, the numbers are multiples of the 

number of calls that have to be made (including resume calls). 

To determine the effect of ECS on these performance figures, we finally removed 

our catalog from ECS and ran the jobs again. The results show that the numbers 

of ENQs/RESERVEs and DEQs are reduced by 29% (AMS) and 33% (CSI) when 

using ECS compared to VVDS mode sharing. 

As these figures cannot be representative or guaranteed, we suggest that you 

compare these jobs on your system, if you run LISTCATs on a regular basis. 

CatalogSearchInterface 85


Table 7. Sample Timings Used by IDCAMS LISTCAT and IGGCSILC 

Timings AMS w/ ECS CSI w/ ECS AMS wo/ ECS CSI wo/ ECS 

Elapsed Time 11 sec 1 sec 24 sec 1 sec 

TCB Time 3.07 sec 0.04 sec 3.14 sec 0.04 sec 

SRB Time 0.06 sec 0.01 sec 0.06 sec 0.01 sec 

ENQ’s/RESERVEs 9010 18 13515 27 

DEQ’s 13515 18 18020 27

A.4 Real World Example of CSI Implementation 

The following example of using CSI is a module from Software AG’s product 

Entire System Server. This product is designed to make information from the 

operating system environment available to Natural programs in the same way 

that data is retrieved from Adabas or other databases. Unlike normal database 

requests that will select rows from tables, information requested from Entire 

System Server is obtained at execution time and returned to the calling program. 

You can request information from Entire System Server by specifying field names 

from views in a Natural FIND or PROCESS statement. Views have been 

predefined for various types of objects, one of which is the CATALOG view, and 

the requested information will be provided by the CATALOG view processor. 

In earlier releases, two methods have been used to retrieve selected catalog 

information: 

Invoking Access Method Services (AMS) 

Using the TSO/E Catalog Information Routine (IKJEHCIR) 

When CSI became available with DFSMS/MVS 1.4, the CATALOG view 

processor was rewritten to utilize some of the advantages of CSI compared to the 

previously used methods. These enhancements include: 

Using a Generic Filter Key. This provides more flexibility than requesting 

data for ENTRIES or LEVEL from IDCAMS, or using entry codes X’04’ 

(volume information for DSN) or X’06’ (volume information for DSN’s with 

same high level qualifier) with IKJEHCIR. 

Requesting Only Specific Fields. This is far more efficient than requesting 

all information from IDCAMS and then parsing the output for the information 

needed. 

Variety of Field Names Available. More fields may be easily included in the 

information request. IKJEHCIR retrieves only volume information; additional 

data has to be obtained using additional macros. 

No Limits on the Number of Entries. Due to the resume function available 

with the CSI, the information returned is not limited by the size of the work 

area. With IKJEHCIR the data returned is restricted by the maximum size of 

64 KB for the user work area. Even AMS LISTCAT has a restriction on the 

number of entries due to the amount of available storage below the line (24-bit 

addressing). 

Work Area Above 16 MB. This may relieve some storage constraints on a 

heavily used system. The user work area passed to IKJEHCIR has to be 

below 16 MB. 

Improved Performance. Retrieving catalog information from CSI is 

significantly faster than from AMS or IKJEHCIR. 

Additional considerations have to be taken when requesting volume information 

for data sets from the catalog(s). When non-VSAM data sets are defined using 

indirect volume serial forms, CSI (as well as AMS) will return the unresolved 

definition value, that is, either a system symbol or ’******’ for the system 

residence volume. In these cases, also, the device type returned will be zero. 



In this sample program, the system symbol is resolved to the real volume serial 

number (see the call to ASASYMBM on page 93), and a UCB copy is obtained to 

get its device type (UCBSCAN COPY macro on page 93). Later, the device type 

is translated into a unit name (EDTINFO macro on page 96) that will be more 

meaningful to the user. 

*********************************************************************** 

* * 

* MAINTENANCE: * 

* * 

* Date UID Description * 

* ------------------------------------------------------------------- * 

* 06.11.1998 STL Rewritten to use Catalog Search Interface * 

* -------------> npr 221 release End of filter field 

MVI WKTRTAB,C’-’ Initialize function ... 

MVC WKTRTAB+1(255),WKTRTAB ... bytes table for TRT 

XC WKTRTAB+240(10),WKTRTAB+240 Clear 0 - 9 

MVC WKTRTAB+C’A’(9),WKTRTAB+240 Clear A - I 

MVC WKTRTAB+C’J’(9),WKTRTAB+240 Clear J - R 

MVC WKTRTAB+C’S’(8),WKTRTAB+240 Clear S - Z 

MVI WKTRTAB+C’.’,0 Clear period 

MVC WKTRTAB+C’$’(2),WKTRTAB+240 Clear $ - * 

MVI WKTRTAB+C’-’,0 Clear hyphen 

MVI WKTRTAB+C’%’,0 Clear percent

MVC WKTRTAB+C’#’(2),WKTRTAB+240 Clear # - @ 

C_SPACE EQU *+1,1,C’C’ 

MVI WKTRTAB+C’ ’,C’ ’ Set space 

C_USCORE EQU *+1,1,C’C’ 

MVI WKTRTAB+C’_’,C’_’ Set underscore 

TRTDSN DS 0H 

TRT DSNAME,WKTRTAB Check for valid characters 

BZ DSNOK No strange characters 

CLM R2,1,C_SPACE Space found ? 

BE DSNOK OK as well 

CLM R2,1,C_USCORE Underscore found ? 

BNE INVDSN No - some strange character 

MVI 0(R1),C’%’ Yes - replace by percent 

B TRTDSN Repeat 

SPACE 

DSNOK DS 0H 

CLC PREFIX(2),C_NO PREFIX=NO specified ? 

BE PREFIXOK Yes - go to process 

LA R0,DSNAME+44-4 R0 -> end of DSNAME - 4 

CR R1,R0 How much space for asterisks ? 

*.STL01. BL TRISTARS Enough for ’.*.**’ 

NOP TRISTARS Enough for ’.*.**’ .STL01. 

*.STL01. BE TWOSTARS Enough for ’.**’ 

NOP TWOSTARS Enough for ’.**’ .STL01. 

LA R0,DSNAME+44-2 R0 -> end of DSNAME - 2 

CR R1,R0 How much space for asterisks ? 

BL TWOSTARS Enough for ’.**’ 

*.STL01. BH PREFIXOK Not enough space for any *’s 

B PREFIXOK Not enough space for any.STL01. 

MVC 0(2,R1),C_SUFFIX Just enough space for ’.*’ 

B PREFIXOK Continue 

TWOSTARS DS 0H 

MVC 0(3,R1),C_SUFFIX+2 Enough space for ’.**’ 

B PREFIXOK Continue 

TRISTARS DS 0H 

BCTR R1,0 R1 -> last character of DSNAME 

CLI 0(R1),C’*’ is there an asterisk already ? 

LA R1,1(,R1) . (restore suffix position) 

BE TWOSTARS yes - suffix with only ’.**’ 

MVC 0(5,R1),C_SUFFIX Enough space for ’.*.**’ 

SPACE 

PREFIXOK DS 0H 

MVI WKS1CAT,C’ ’ Set default search all cat’s 

CLC OPTION,C_LONG OPTION=LONG specified ? 

BE OPTIONOK Yes - continue 

CLI OPTION,0 OPTION not specified ? 

BE OPTIONOK Yes - continue 

CLC OPTION,C_UCAT OPTION=USERCAT specified ? 

BNE INVOPT No - invalid specification 

MVI WKS1CAT,C’Y’ Indicate search this cat only 

SPACE 

OPTIONOK DS 0H 

CLI USERCAT,0 USERCAT not specified ? 

BE NOUCAT Yes - set field to blanks 

MVI WKTRTAB+C’*’,C’-’ Asterisk invalid in catalogname 

MVI WKTRTAB+C’%’,C’-’ Percent invalid in catalogname 

MVI WKTRTAB+C’_’,C’-’ Uscore invalid in catalogname 

TRT USERCAT,WKTRTAB Check for valid characters 



BZ INVUCAT No strange characters 

CLM R2,1,C_SPACE Space found ? 

BNE INVUCAT No - some strange character 

SPACE 

NOUCAT DS 0H 

MVI USERCAT,C’ ’ Set USERCAT field ... 

MVC USERCAT+1(43),USERCAT ... to blanks 

SPACE 

UCATOK DS 0H 

*********************************************************************** 

* * 

* 2. getmain buffer for CSI work area * 

* use SUBPOOL 8 for view 8 * 

* build selection criteria for CSI * 

* * 

*********************************************************************** 

LA R15,WKCSIRSN R15 -> CSI reason area 

ST R15,WKCSIPR1 set as 1st parameter address 

MVC CSIFILTK,DSNAME set generic filter key 

MVC CSICATNM,USERCAT set catalog name 

MVI CSIRESNM,C’ ’ clear resume name ... 

MVC CSIRESNM+1(44+16+1),CSIRESNM ... and types & options 

MVC CSIS1CAT,WKS1CAT set catalog search option 

MVC CSIFLDNM,=CL8’DEVTYP’ set 1st field name 

MVC CSIFLDN2,=CL8’VOLSER’ set 2nd field name 

MVC CSIFLDN3,=CL8’FILESEQ’ set 3rd field name 

LA R0,3 R0 := number of field names 

STH R0,CSINUMEN set number of field entries 

LA R15,WKCSISEL R15 -> CSI selection criteria 

ST R15,WKCSIPR2 set as 1st parameter address 

STORAGE OBTAIN,LENGTH=32760, Obtain storage for CSI ... * 

SP=8,LOC=ANY,COND=YES ... work area 

LTR R15,R15 Request successful ? 

BNZ STGERR No - return error code 

SPACE 

LR R11,R1 Yes - load into R11 

ST R0,0(,R11) set work area length 

ST R11,WKCSIPR3 set as 3rd parameter address 

OI WKCSIPR3,128 indicate last parameter 

ST R11,WKCURPOS+4 save address in position 

SPACE 

*********************************************************************** 

* * 

* 3. call catalog search interface (available since DFSMS/MVS V1R4) * 

* (see DFSMS/MVS Managing Catalogs, Appendix D, CSI User’s Guide) * 

* * 

*********************************************************************** 

CALLCSI DS 0H 

LA R1,WKCSIPR1 R1 -> parameter address list 

*** L R15,=V(IGGCSI00) R15 -> Catalog search interface 

*** BALR R14,R15 call CSI 

LINK EP=IGGCSI00 call catalog search interface 

LTR R15,R15 Catalog search successful ? 

BNZ CSIERR No - return error code 

SPACE 

USING CSIRWORK,R11 

L R9,CSIUSDLN R9 := used work area length 

ALR R9,R11 R9 -> end of used work area

LA R10,WORKEND R10 -> 1st entry 

USING CSIENTRY,R10 

MVC USERCAT,CSICNAME move (user) catalog name 

ST R10,WKCURPOS save current (initial) position 

TM CSICFLG,CSINOENT any entries found ? 

BO CATENTRY no - go to get next entry 

SPACE 3 

GETIT DS 0H + 

CLI OPENOK,1 + Did S1/S4 preceed ? 

BNE INVFUNC + No, invalid function sequence 

ICM R15,3,WKERR + Any previous error ? 

BNZ HANDERR + Yes, handle error 

SPACE 

GETNEXT DS 0H 

LM R10,R11,WKCURPOS restore current position 

L R9,CSIUSDLN R9 := used work area length 

ALR R9,R11 R9 -> end of used work area 

CR R10,R9 current entry within workarea ? 

BL TESTTYPE yes - continue 

CLI CSIRESUM,C’Y’ more catalog entries ? 

BE CALLCSI Yes - call CSI with resume 

B EODAD No - signal end of data 

SPACE 

TESTTYPE DS 0H 

CLI CSIETYPE,C’0’ Is entry for a catalog ? 

BE CATENTRY Yes - go to process 

MVC DSNAME,CSIENAME No - copy entry name 

LA R15,ENTYPTAB R15 -> entry type table 

LA R0,ENTYPLEN R0 := size of one entry 

LA R1,ENTYPEND-1 R1 -> end of table 

*********************************************************************** 

* * 

* 4. copy retrieved information into dynamic work area * 

* * 

*********************************************************************** 

FINDTYPE DS 0H 

CLC CSIETYPE,0(R15) entry type found ? 

BE COPYTYPE yes - go to copy type 

BXLE R15,R0,FINDTYPE no - repeat for next entry 

MVC TYPE,=C’-N/A-( )’ end of table, type not found 

MVC TYPE+6(1),CSIETYPE set entry type from CSI 

B TYPEDONE continue 

COPYTYPE DS 0H 

MVC TYPE,1(R15) copy type from table entry 

SPACE 

TYPEDONE DS 0H 

TM CSIEFLAG,CSIENTER Error indication set ? 

BZ COPYINFO No - go to copy info fields 

MVI DSNAME+34,C’-’ Yes - insert hyphen into DSN 

MVC DSNAME+35(2),CSIERETM insert module ID 

MVI DSNAME+37,C’-’ insert hyphen 

MVC WKDOUB+6(1),CSIERETR prepare reason code for unpack 

MVI WKDOUB+7,6 append packed hyphen 

UNPK DSNAME+38(3),WKDOUB unpack reason code 

TR DSNAME+38(2),HEXTRTAB translate hex digits 

MVC WKDOUB+6(1),CSIERETC prepare return code for unpack 

UNPK DSNAME+41(3),WKDOUB unpack reason code 

TR DSNAME+41(2),HEXTRTAB translate hex digits 



LA R10,CSIEDATA R10 -> next entry 

B INFODONE continue 

SPACE 

COPYINFO DS 0H 

LA R7,CSILENFD R7 -> 1st length field 

LH R8,CSINUMFD R8 := number of field names+1 

BCTR R8,0 R8 := number of field names 

SLL R8,1 R8 := length of field names 

LA R8,0(R8,R7) R8 -> 1st field data 

ICM R15,3,0(R7) any data for devtype ? 

BZ NODEVTYP no - continue 

MVC DEVTYPE,0(R8) copy devtype 

B COPYVOLS continue 

NODEVTYP DS 0H 

XC DEVTYPE,DEVTYPE clear devtype field 

SPACE 

COPYVOLS DS 0H 

AH R8,0(,R7) R8 -> 2nd field data 

LA R7,2(,R7) R7 -> 2nd field length 

LH R15,0(,R7) R15 := volser field length 

SLR R14,R14 clear R14 

LA R1,6 R1 := one volser’s length 

DR R14,R1 R15 := number of volumes 

CVD R15,WKDOUB convert to decimal 

ZAP NUMVOLS,WKDOUB set number of volumes 

ICM R15,7,WKCURVOL+4+1 multi-volume dataset ? 

BNZ CONTVOLS yes - continue to move volser 

LH R15,0(,R7) R15 := volser field length 

LR R14,R8 R14 -> source field for MVCL 

B MVCLVOLS continue 

CONTVOLS DS 0H 

L R14,WKCURVOL R14 -> source data for MVCL 

MVCLVOLS DS 0H 

ICM R15,8,C_SPACE insert padding byte for MVCL 

LA R0,VOLSER R0 -> destination field 

STM R14,R15,WKLSTVOL save this volume(s) position 

MVCL R0,R14 move one volume serial number 

STM R14,R15,WKCURVOL save next volume(s) position 

SPACE 

CLC VOLSER,C_SYSRES SYSRES volume ? 

BNE TESTSYMB no - continue 

L R15,CVTPTR R15 -> CVT 

L R15,CVTSYSAD-CVT(,R15) R15 -> SYSRES UCB 

MVC VOLSER,UCBVOLI-UCBCMSEG(R15) move real volser 

MVC DEVTYPE,UCBTYP-UCBCMSEG(R15) move device type 

SPACE 

*********************************************************************** 

* * 

* 5. eventually substitute system symbol with real volser * 

* * 

*********************************************************************** 

TESTSYMB DS 0H 

CLI VOLSER,C’&&’ system symbol in volser ? 

BNE COPYFSEQ no - continue 

LA R15,WKSYMTBL R15 -> internal symbol table 

LA R0,WKSYMTBN R0 := number of entries 

COMPSYMB DS 0H 

CLC VOLSER,0(R15) symbol found ?

BE COPYSYMB yes - go to copy substitution 

LA R15,16(,R15) R15 -> next table entry 

BCT R0,COMPSYMB repeat for next entry 

SPACE 

MVC WKPATTRN,VOLSER yes - move pattern for ASASYMBM 

XC WKSYMBP,WKSYMBP clear ASASYMBM parameter area 

USING SYMBP,WKSYMBP 

LA R15,WKPATTRN R15 -> pattern for ASASYMBM 

ST R15,SYMBPPATTERN@ Save in SYMBP area 

LA R15,6 R15 := length of pattern 

ST R15,SYMBPPATTERNLENGTH Save in SYMBP area 

ST R15,WKTARGLN set target length 

LA R15,WKTARGET R15 -> target for ASASYMBM 

ST R15,SYMBPTARGET@ Save in SYMBP area 

LA R15,WKTARGLN R15 -> target length field 

ST R15,SYMBPTARGETLENGTH@ Save in SYMBP area 

LA R15,WKSYMBRC R15 -> return code field 

ST R15,SYMBPRETURNCODE@ Save in SYMBP area 

LINK EP=ASASYMBM,MF=(E,WKSYMBP) call symbol substitution 

ICM R15,15,WKSYMBRC ASASYMBM request successful ? 

BNZ SYMBERR no - return error code 

SPACE 

MVC VOLSER,WKTARGET move substituted volser 

SPACE 

UCBSCAN COPY,WORKAREA=WKUCBSWA, get a copy of the UCB ... * 

UCBAREA=WKUCBCPY,VOLSER=VOLSER, ... for this volser * 

MF=(E,WKUCBSCN,COMPLETE) 

LTR R15,R15 UCBSCAN successful ? 

BNZ UCBSERR no - return error code 

SPACE 

MVC DEVTYPE,UCBTYP-UCBCMSEG+WKUCBCPY move device type 

SPACE 

LA R15,WKSYMTBL R15 -> internal symbol table 

LA R0,WKSYMTBN R0 := number of entries 

TESTISTE DS 0H 

CLI 0(R15),C’&&’ entry already filled ? 

BNE INSRTSYM no - go to insert symbol 

LA R15,16(,R15) R15 -> next table entry 

BCT R0,TESTISTE repeat for next entry 

B COPYFSEQ table full - forget about it 

SPACE 

INSRTSYM DS 0H 

MVC 0(6,R15),WKPATTRN insert symbol into table 

MVC 6(6,R15),WKTARGET insert substitution into table 

MVC 12(4,R15),UCBTYP-UCBCMSEG+WKUCBCPY move device type 

SPACE 

COPYSYMB DS 0H 

MVC VOLSER,6(R15) move substituted volser 

MVC DEVTYPE,12(R15) move corresponding device type 

SPACE 

COPYFSEQ DS 0H 

AH R8,0(,R7) R8 -> 3rd field data 

LA R7,2(,R7) R7 -> 3rd field length 

ICM R0,3,0(R7) any data for fileseq ? 

BZ NOFILSEQ no - continue 

LH R0,0(,R8) R0 := file sequence number 

CVD R0,WKDOUB convert to decimal 

ZAP VOLSEQ,WKDOUB set volume sequence number 



B COPYDONE continue 

NOFILSEQ DS 0H 

ZAP VOLSEQ,=P’0’ set volume sequence number zero 

SPACE 

COPYDONE DS 0H 

ICM R15,7,WKCURVOL+4+1 more volumes left to be moved ? 

BNZ INFODONE yes - process same entry next 

SPACE 

ST R10,WKLSTPOS save this entry’s position 

LH R15,CSITOTLN R15 := total length of data 

LA R10,CSIEDATA(R15) R10 -> next entry 

SPACE 

INFODONE DS 0H 

ST R10,WKCURPOS save current position 

SPACE 

*********************************************************************** 

* * 

* 6. call search-buffer analyze routine * 

* * 

*********************************************************************** 

- - - - - - - - - - - - - - - - 8 Line(s) not Displayed 

* COMPARISONS SUCCEEDED 

*********************************************************************** 

* * 

* 7. call record-buffer build routine * 

* * 

*********************************************************************** 

CATFLDS DS 0H + 


MVC WKCURPOS,WKLSTPOS restore current position 

MVC WKCURVOL,WKLSTVOL restore current volume 


CATENTRY DS 0H 

MVC USERCAT,CSIENAME move (user) catalog name 

LA R10,CSILENFD R10 -> next entry 

ST R10,WKCURPOS save current position 

B GETNEXT go to get next (non-cat) entry 

* 

EJECT 

* 

CLOSE DS 0H + TERMINATE FUNCTION 

ICM R11,15,WKCURPOS+4 R11 -> CSI work area (if obt’d) 

BZ FREEWA no - free dynamic work area 

STORAGE RELEASE,LENGTH=32760, Release storage for CSI ... * 

ADDR=(R11),SP=8 - COND=YES ... work area 

LTR R15,R15 Request successful ? 

BNZ STGERR - S378 - No - return error code 

B FREEWA go to free dynamic work area 


SPACE 3 

NOTFOUND DS 0H 

MVC WKERRT,ERRNTFT move not found error text 

LA R15,ERRNTF R15 := not found error code 

B HANDERR go to handle error 

SPACE 3 

INVDSN DS 0H 

MVC WKERRT,ERRDSNT move DSN error text 

LA R15,ERRDSN R15 := DSN error code


SPACE 3 

INVOPT DS 0H 

MVC WKERRT,ERROPTT move option error text 

LA R15,ERROPT R15 := option error code 


SPACE 3 

INVUCAT DS 0H 

MVC WKERRT,ERRUCAT move catalog error text 

LA R15,ERRUCA R15 := UCAT error code 


SPACE 3 

STGERR DS 0H 

MVC WKERRT,ERRSTGT move storage error text 

LA R15,ERRSTG R15 := Stg Err return code 


SPACE 3 

CSIERR DS 0H 

CLI WKCSIRSN+3,122 RC 122 (’invalid filter key’) ? 

BE INVDSN yes - return syntax error 

MVC WKERRT,ERRCSIT move CSI error text 

MVC WKERRT+27(2),WKCSIRSN insert module ID 

MVC WKDOUB+6(1),WKCSIRSN+2 prepare reason code for UNPK 

MVI WKDOUB+7,167 append packed colon 

UNPK WKERRT+38(3),WKDOUB unpack CSI reason code 

TR WKERRT+38(2),HEXTRTAB translate hex digits 

MVC WKDOUB+6(1),WKCSIRSN+3 prepare return code for UNPK 


UNPK WKERRT+45(3),WKDOUB unpack CSI return code 


LA R15,ERRCSI R15 := CSI fail return code 


SPACE 3 

SYMBERR DS 0H 

MVC WKERRT,ERRSYMT move symbol subst. error text 

MVC WKERRT+28(6),WKPATTRN insert symbol 

MVC WKDOUB+6(1),WKSYMBRC+3 prepare return code for UNPK 


UNPK WKERRT+39(3),WKDOUB unpack SYMB return code 


LA R15,ERRSYM R15 := SYMB fail return code 


SPACE 3 

UCBSERR DS 0H 

MVC WKERRT,ERRUCBT move UCBSCAN error text 

MVC WKERRT+27(6),WKTARGET insert volume 

STC R15,WKDOUB+6 prepare return code for UNPK 


UNPK WKERRT+38(3),WKDOUB unpack SYMB return code 


LA R15,ERRUCB R15 := UCBSCAN fail return code 


SPACE 3 

HANDERR DS 0H + HANDLE ERROR CONDITION 


**** FIELD ROUTINES FOR VIEW 08 ******* 


* 



VIEW08A1 DS 0H + DSNAME 

LA R1,DSNAME + POINT TO DSNAME 

BR R14 + RETURN 

* 

VIEW08A2 DS 0H + DEVICE-CODE 

LA R1,DEVTYPE + POINT TO DEVICE TYPE 


* 

VIEW08A3 DS 0H + VOLSER 

LA R1,VOLSER + POINT TO VOLSER 


* 

VIEW08A4 DS 0H + VOLUME SEQUENCE 

LA R1,VOLSEQ + GET VOL SEQUENCE 


* 

VIEW08A5 DS 0H + NUMBER-OF-VOLUMES 

LA R1,NUMVOLS + POINT TO VOL COUNT 


* 

VIEW08A6 DS 0H + SERIES 

EDTINFO RTNUNIT,DEVTYPE=DEVTYPE, return unitname for ... * 

OUTUNIT=UNITNAME,MF=(E,WKEDTINF) ... this device type 

LA R1,UNITNAME + POINT TO UNITNAME 


* 

VIEW08A7 DS 0H + CLASS 

TM DEVTYPE+2,X’20’ direct access device ? 

BZ NOTDASD no - try next class 

MVC DEVCLASS,=C’DASD’ yes - set class DASD 

B CLASDONE continue 

NOTDASD DS 0H 

TM DEVTYPE+2,X’80’ tape device ? 

BZ NOTTAPE no - try next class 

MVC DEVCLASS,=C’TAPE’ yes - set class TAPE 

B CLASDONE continue 

NOTTAPE DS 0H 

MVC DEVCLASS,=C’-NA-’ hardly believable 

CLASDONE DS 0H 

LA R1,DEVCLASS + POINT TO DEVICE CLASS 


* 

VIEW08A8 DS 0H + TYPE 

LA R1,TYPE + POINT TO FILE TYPE 


* 

VIEW08AB DS 0H + PREFIX 

LA R1,PREFIX + POINT TO YES³NO 


* 

VIEW08AC DS 0H + USER-CATALOG 

LA R1,USERCAT + POINT TO CATALOG NAME 


* 

VIEW08AD DS 0H + OPTION 

LA R1,OPTION + POINT TO OPTION 


- - - - - - - - - - - - - - - - 40 Line(s) not Displayed

SPACE 3 

ENTYPTAB DC C’A’,CL8’NONVSAM ’ Table of entry types 

ENTYPLEN EQU *-ENTYPTAB size of one entry 

DC C’B’,CL8’GDG ’ . 

DC C’C’,CL8’CLUSTER ’ . 

DC C’D’,CL8’DATA ’ . 

DC C’G’,CL8’AIX ’ . 

DC C’H’,CL8’GDS ’ . 

DC C’I’,CL8’INDEX ’ . 

DC C’R’,CL8’PATH ’ . 

DC C’U’,CL8’USERCAT ’ . 

DC C’X’,CL8’ALIAS ’ . 

ENTYPEND EQU * end of table 

HEXTRTAB EQU *-240 Translate table for hex digits 

C_029 DC C’0123456789’ Digits 0 to 9 

C_A2I DC C’ABCDEFGHI’ Char’s A to I 

C_J2R DC C’JKLMNOPQR’ Char’s J to R 

C_NO EQU C_J2R+4,2,C’C’ C’NO’ 

C_S2Z DC C’STUVWXYZ’ Char’s S to Z 

C_SUFFIX DC C’.*.**’ Suffix for DSNAME 

DC C’****’ more asterisks 

C_SYSRES EQU *-6,6,C’C’ SYSRES volume 

C_LONG DC CL8’LONG ’ Keyword OPTION value 

C_UCAT DC CL8’USERCAT ’ Keyword OPTION value 

C_SPACES DC CL8’ ’ Spaces 

* * * ----+----1----+----2----+----3----+----4----+----5 

ERRNTF EQU 562 

ERRNTFT DC CL50’Catalog entry not found. ’ 

ERRDSN EQU 565 

ERRDSNT DC CL50’Syntax error in data set name. ’ 

ERRUCA EQU 566 

ERRUCAT DC CL50’Syntax error in catalog name. ’ 

ERROPT EQU 567 

ERROPTT DC CL50’Invalid OPTION, specify LONG or USERCAT. ’ 

ERRCSI EQU 787 

ERRCSIT DC CL50’CSI request failed, Module:..:,Reason:..:,RC:..: ’ 

ERRSTG EQU 786 

ERRSTGT DC CL50’Unable to obtain/release storage for CSI work area’ 

ERRSYM EQU 788 

ERRSYMT DC CL50’Unable to substitute symbol:......:,RC:..: ’ 

ERRUCB EQU 789 

ERRUCBT DC CL50’Unable to get UCB copy for:......:,RC:..: ’ 

LTORG 

EJECT 

COPY VIEWWK WORK AREA 

************ WORK FIELDS FOR THIS VIEW PROCESSOR ***************** 

************ here starts area of output fields ******************* 

V8OUTPF DS 0H Output fields 

* DSNAME . . defined in common workarea 

DEVTYPE DS BL4 Device type 

* VOLSER . . defined in common workarea 

VOLSEQ DS PL2 Volume sequence number 

NUMVOLS DS PL2 Volume Count 

UNITNAME DS CL8 Unit name (SERIES) 

DEVCLASS DS CL4 Device class (DASD, TAPE, ...) 

TYPE DS CL8 Entry type 

USERCAT DS CL44 Usercatalog name 

OPTION DS CL8 Option (LONG / USERCAT) 



PREFIX DS CL3 Prefix (YES / NO) 

V8OUTPL EQU *-V8OUTPF Output fields length 

************ here ends area of output fields ******************* 

SPACE 

WKS1CAT DS CL1 Catalog search option (Y / b) 

WKCSIPR1 DS A 1st parameter address for CSI 

WKCSIPR2 DS A 2nd parameter address for CSI 

WKCSIPR3 DS A 3rd parameter address for CSI 

WKCSIRSN DS XL4 CSI reason area 

WKCSISEL DS 0F CSI selection criteria 

*/* ---- COPY IGGCSINA --------------- copied to (w/o DSECT): ----- */ 

CSIFILTK DS CL44 FILTER KEY 

CSICATNM DS CL44 CATALOG NAME OR BLANKS 

CSIRESNM DS CL44 RESUME NAME OR BLANKS 

CSIDTYPD DS 0CL16 ENTRY TYPES 

CSIDTYPS DS 16CL1 ENTRY TYPES 

CSIOPTS DS 0CL4 CSI OPTIONS 

CSICLDI DS CL1 RETURN D&I IF C A MATCH Y OR BLNK 

CSIRESUM DS CL1 RESUME FLAG Y OR BLANK 

CSIS1CAT DS CL1 SEARCH CATALOG Y OR BLANK 

CSIRESRV DS XL1 RESERVED 

CSINUMEN DS H NUMBER OF ENTRIES FOLLOWING 

CSIENTS DS 0CL8 VARIABLE NUMBER OF ENTRIES FOLLOW 

CSIFLDNM DS CL8 FIELD NAME 

*/* ---- COPY IGGCSINA --------------- end of copy book ----------- */ 

CSIFLDN2 DS CL8 2nd field name (VOLSER) 

CSIFLDN3 DS CL8 3rd field name (FILESEQ) 

SPACE 

WKCURPOS DS 2F saved curr. position (R10,R11) 

WKCURVOL DS 2F saved current volser (R14,R15) 

WKLSTPOS DS 2F saved last position (R10,R11) 

WKLSTVOL DS 2F saved last volser (R14,R15) 

SPACE 

EDTINFO MF=(L,WKEDTINF) Parameter List for EDTINFO 

SPACE 

UCBSCAN MF=(L,WKUCBSCN) Parameter List for UCBSCAN 

WKUCBSWA DS CL100 UCBSCAN work area 

WKUCBCPY DS CL48 UCB copy area 

SPACE 

WKSYMBP DS CL(SYMBP_LEN) Parameter List for ASASYMBM 

WKSYMBRC DS F ASASYMBM return code 

WKPATTRN DS CL6 pattern for symbol substitution 

WKTARGET DS CL6 target for symbol substitution 

WKTARGLN DS F target length 

WKSYMTBL DS CL6,CL6,BL4 symbol, substitution, devtype 

DS CL6,CL6,BL4 2nd entry 

DS CL6,CL6,BL4 3rd entry 

WKSYMTBN EQU 3 number of table entries 

SPACE 

WKTRTAB DS CL256 Area used for TR, TRT 

WALEN EQU *-WADS Length of work area 

SPACE 3 

CSIRWORK DSECT CSI RETURN WORK AREA 

CSIUSRLN DS F TOTAL LENGTH OF WORK AREA 

CSIREQLN DS F MINIMUM REQUIRED WORK AREA 

CSIUSDLN DS F TOTAL LENGTH OF WORK AREA USED 

CSINUMFD DS H NUMBER OF FIELD NAMES PLUS ONE 

SPACE

CSICFLG DS BL1 CATALOG FLAG INFORMATION 

CSINTICF EQU X’80’ NON-ICF CATALOG, NOT SUPPORTED 

CSINOENT EQU X’40’ NO ENTRY FOUND FOR THIS CATALOG 

CSINTCMP EQU X’20’ DATA ... NOT COMPLETE 

CSICERR EQU X’10’ CATALOG NOT PROCESSED 

CSICERRP EQU X’08’ CATALOG PARTIALLY PROCESSED 

CSICTYPE DS CL1 CATALOG TYPE (HEX ’F0’) 

CSICNAME DS CL44 CATALOG NAME 

CSICRETN DS 0CL4 RETURN INFORMATION FOR CATALOG 

CSICRETM DS CL2 CATALOG RETURN MODULE ID 

CSICRETR DS XL1 CATALOG RETURN REASON CODE 

CSICRETC DS XL1 CATALOG RETURN CODE 

WORKEND DS 0F 

SPACE 

CSIENTRY DS 0H 

CSIEFLAG DS XL1 ENTRY FLAG INFORMATION 

CSIPMENT EQU X’80’ PRIMARY ENTRY 

CSIENTER EQU X’40’ ERROR INDICATION IS SET 

CSIEDATR EQU X’20’ DATA IS RETURNED FOR THIS ENTRY 

CSIETYPE DS XL1 ENTRY TYPE 

CSIENAME DS CL44 ENTRY NAME 

CSIERETN DS 0XL4 RETURN INFORMATION FOR ENTRY 

CSIERETM DS CL2 ENTRY RETURN MODULE ID 

CSIERETR DS XL1 ENTRY RETURN REASON CODE 

CSIERETC DS XL1 ENTRY RETURN CODE 

ORG CSIERETN 

CSIEDATA DS 0H 

CSITOTLN DS XL2 TOTAL LENGTH OF RETURNED DATA 

DS XL2 RESERVED 

CSILENFD DS 0H 

CSILENF1 DS XL2 LENGTH OF FIELD(S) 

SPACE 3 

PRINT NOGEN 

ASASYMBP , ASASYMBM Parameter List 

SPACE 3 

CVT DSECT=YES CVT DSECT 

SPACE 3 

IEFUCBOB DEVCLAS=DA UCB MAPPING MACRO 


END , 



Appendix B. What’s Changed and What’s New 

In this appendix we show the complete command syntax for the MODIFY CATALOG 

command and the new and changed messages that ECS utilizes. 

B.1 MODIFY CATALOG Command Syntax 

The MODIFY CATALOG command and its parameters are shown in Figure 51. 

{MODIFY|F} CATALOG, {ABEND({id|taskaddr|ALLOCATE|ANALYSIS|MODIFY})} 

{ALIASLEVEL(n)} 

{ALLOCATE(catname)[,{NOISC|NOVLF}]} 

{ALLOCATED[(volser)]} 

{CATMAX(xx)} 

{CLOSE(catname)} 

{{DUMPON[(retcode,rsncode,modid[,count])]|DUMPOFF}} 

{ECSHR(AUTOADD|CONNECT|DISCONNECT| 

ENABLE,catname|ENABLEALL|REMOVE,catname| 

STATUS[,catname])} 

{END(id)[,{REDRIVE|NOREDRIVE}]} 

{ENTRY[(csectname)]} 

{{ISC|NOISC}(catname)} 

{LIST[{(id)|(taskaddr)}]} 

{LISTJ(jobname)[,DETAIL]} 

{REPORT[,{CACHE[(catname)]|DUMP| 

PERFORMANCE[(RESET)]}]} 

{RESTART} 

{ROTATE|NOROTATE} 

{{SYS%ON|SYS%OFF}} 

{TASKMAX(xx)} 

{UNALLOCATE[(catname)]} 

{VCLOSE(volser)} 

{{VLF|NOVLF}(catname)} 

{{VUNALLOCATE|NOVUNALLOCATE}} 

{{WARNING|NOWARNING}} 

Figure 51. MODIFY CATALOG Command Syntax 

The parameters are: 

ABEND 

Terminates a CAS task with abend code 91A. Any catalog request in process 

at the time of the abend is redriven once. The task can be specified as: 

(id) 

The service task with the specified CAS task id is terminated. 

(taskaddr) 

The CAS service task with the specified four byte hexadecimal TCB 

address is terminated. 

(ALLOCATE) 

The CAS allocation task (IGG0CLGE) is terminated and a new CAS 

allocation task is attached. 



(ANALYSIS) 

The CAS analysis task (IGG0CLGG) is terminated and a new CAS analysis 

task is attached. 

(MODIFY) 

The CAS modify task (IGG0CLGA) is terminated and a new CAS modify 

task is attached. 

ALIASLEVEL(n) 

Sets the number of data set name qualifiers to be used in the multilevel alias 

facility catalog search. The value of n can be an integer from 1 through 4. The 

alias level is initially set at IPL with the value specified in the SYSCAT 

statement of parmlib member LOADxx or in the SYSCATxx member of 

SYS1.NUCLEUS. 

ALLOCATE(catname)[,{NOISC|NOVLF}] 

Allocates the catalog specified as catname to the CAS. The optional 

parameters are: 

NOISC Deactivates the in-storage catalog cache (ISC) for the catalog. 

NOVLF Deactivates the catalog data space cache (CDSC) for the catalog. 

ALLOCATED[(volser)] 

Lists the name, volume serial number, current allocation count, and status 

flags for every catalog currently allocated to the CAS. The information is listed 

in message IEC348I. 

If a volume serial number is specified (volser), only information for catalogs 

residing on that volume is listed. 

CATMAX(xx) 

Closes all open user catalogs, and sets the maximum number of catalogs that 

can be open concurrently in CAS. The limit is specified as a hexadecimal 

value xx from 01 through FF. 

When the limit is reached, the least recently accessed catalog is closed, 

freeing the CAS storage it has occupied. Closed catalogs remain allocated. 

They remain allocated, but in restart status with no storage in the CAS. 

CLOSE(catname) 

Closes the catalog specified as catname. All CAS storage for the catalog is 

released. The catalog remains allocated to the CAS and will be reopened the 

next time a request is processed for that catalog. 

DUMPON[(retcode,rsncode,modid[,count])]|DUMPOFF 

Activates or deactivates dynamic dumping by the CAS. The default, 

DUMPOFF is set at IPL. The optional parameters for DUMPON are: 

retcode The catalog return code in decimal (000-255), or *** 

rsncode The catalog reason code in decimal (000-255), or *** 

modid The catalog module identifier in CAS, or ** 

count The limit number in decimal (000-999)

Options in parentheses that follow the DUMPON parameter can be used to 

create a dump whenever a given return code, reason code, and module 

identifier occur. This dump can prove valuable to service personnel in solving 

problems. Normally, the return code, reason code, and module identifier are 

available on return from CAS and are printed by AMS. The module identifier 

corresponds to the last two characters in the catalog module name. For 

example, the module identifier is A3 for IGG0CLA3. 

The return code, reason code, and module identifiers can be specified 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 

simultaneously specified as asterisks. Whenever a generic match is specified 

for a particular field, it will be assumed that field always matches the value 

being returned by catalog for a catalog request; for example: 

MODIFY CATALOG,DUMPON(008,042,**) 

This will create a dump for any return code 8, reason code 42, regardless of 

the module that detected 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. 

Only one set of return codes, reason codes and module identifiers can be set 

at a time. Each entry overwrites the previous information. Once a match 

occurs, the information is cleared and the original DUMPON status is 

maintained. If DUMPON is entered without the additional options, certain 

conditions will produce dumps automatically. Then, if a DUMPON with options 

is entered, a match will cause a dump, and the return code, reason code, and 

module identifier will be cleared. The DUMPON status will remain on. 

MODIFY CATALOG,REPORT,DUMP can be used to view the settings. 

The header for the catalog dynamic dump will contain the return code and 

reason code in hexadecimal. For example: 

CAS DYNAMIC DUMP-IGG0CLA9 RCX'F6' RSNX'00' 

ECSHR(AUTOADD|CONNECT|DISCONNECT|ENABLE,catname|ENABLEALL| 

REMOVE,catname|STATUS[,catname]) 

Enables the AutoAdd function for ECS, enables an individual catalog or all 

catalogs for ECS, or displays ECS status information for the entire ECS 

structure on an individual catalog. 

AUTOADD 

Enables the AutoAdd function for ECS. This requires CAS to be connected 

to the ECS structure in an active CFRM policy. The function is enabled for 

all systems in a Parallel Sysplex. AutoAdd causes ECS-eligible catalogs to 

be automatically added to the ECS structure on the next reference to the 

catalog. Catalogs are considered ECS-eligible if all of 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. 

What’s Changed and What’s New 103


Note that catalogs which have been removed from ECS will also be 

re-enabled by the MODIFY CATALOG command with the ECSHR(AUTOADD) 

parameter. 

CONNECT 

Connects the system to the ECS structure in the coupling facility. The CAS 

issues an IXLCONN request to allocate and connect to the ECS structure 

or to connect to the already allocated structure. 

DISCONNECT 

Disconnects the system from the ECS structure in the coupling facility. The 

CAS issues an IXLDISC request. Any ECS catalogs in the structure are 

removed and will subsequently be shared using the VVDS sharing mode. 

ENABLE,catname 

Enables the specified catalog catname for ECS if it has been marked 

temporarily ineligible. It will be added to the ECS structure on the next 

reference to the catalog. 

ENABLEALL 

Enables all currently known catalogs for ECS that have been marked 

temporarily ineligible. They will be added to the ECS structure on the next 

reference to the catalog. 

REMOVE,catname 

Removes the specified catalog catname from the ECS structure, thereby 

affecting all sharing systems. The catalog will then be marked temporarily 

ineligible for ECS, and the sharing protocol reverts to the VVDS method. 

The MODIFY CATALOG command with the ECSHR(ENABLE,...) or the 

ENABLEALL parameter must be used to enable the catalog again for ECS. 

To permanently remove a catalog from ECS use, turn off the ECSHARING 

attribute using the AMS ALTER command. 

Note that a removed catalog can also be re-enabled by a MODIFY CATALOG 

command with the ECSHR(ENABLE,...) or ECSHR(ENABLEALL) 

parameter issued from another system. 

STATUS[,catname] 

Displays the status of the coupling facility connection and the ECS status of 

the open catalogs. The information is displayed in message IEC380I. 

If a catalog is specified (catname), only the ECS status for this catalog is 

displayed. 

END(id)[,{REDRIVE|NOREDRIVE}] 

Ends the service task with the specified CAS task id. This is the preferred 

method of ending a CAS task. The subparameters are: 

REDRIVE 

Specifies that any catalog request in process at that time will continue to be 

processed by a different task. REDRIVE will free up an ENQ lockout. The 

CAS task is abended with abend code 91A. 

NOREDRIVE 

Specifies that any catalog request in process at that time will fail with a 

catalog return code of 246. The CAS task is abended with abend code 71A.

ENTRY[(csectname)] 

Displays the names, the entry points, the FMIDs, and the maintenance level of 

all CSECTS in the catalog load modules IGG0CLX0 (resident in CAS) and 

IGG0CLHA (resident in the link pack area). The information is displayed in 

message IEC349I. 

If a CSECT name is specified (csectname), only the information for this 

individual CSECT is displayed. 

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) 

Activates (ISC) or deactivates (NOISC) the in-storage catalog cache (ISC) for 

the catalog specified as catname. The catalog must already be allocated to 

use this command. 

The objective of in-storage cache is to cache only those records which 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[{(id)|(taskaddr)}] 

Lists currently active CAS service tasks, their related jobnames, elapsed 

times, and unique identifiers. The information is displayed 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 an individual task is specified. The task can 

be specified as: 

(id) 

To list information for the service task with this unique identifier. 

(taskaddr) 

To list information for the service task with the specified four byte 

hexadecimal TCB address. 

LISTJ(jobname)[,DETAIL] 

Displays information about an active CAS service task for the job specified as 

jobname. The DETAIL keyword can be used to request 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. 

REPORT[,{CACHE[(catname)]|DUMP|PERFORMANCE[(RESET)]}] 

Displays basic information about the CAS status, about the cache 

performance, the current CAS dump status, or CAS performance statistics. 



The information is displayed in message IEC359I. If no additional keywords 

are specified, current limits and installation-specified defaults are provided. 

The optional parameters are: 

CACHE[(catname)] 

Displays general information on catalog cache status. The report 

generated shows information useful in evaluating the catalog cache 

performance for the specified catalogs. If you do not specify a catalog 

name (catname), performance information for all catalogs currently active 

in the catalog address space is listed. 

DUMP 

Displays the current dump status of the CAS. The dump status can be 

enabled or disabled using the DUMPON and DUMPOFF parameters of the 

MODIFY CATALOG command. 

PERFORMANCE 

Lists information about events in CAS that invoke functions outside of the 

catalog component. It shows the number of entries to the catalog, the 

number of occurrences for a list of internal events, and the average time 

spent completing that event. 

PERFORMANCE(RESET) 

The RESET parameter is used to reset the performance reporting 

information to zero. 

RESTART 

Restarts the CAS 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. 

Before you use this command we recommend that you carry out the actions 

described in 6.4.2, “CAS Hang or Lockout Situations” on page 79, to make 

sure that a dump is available. 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. 

ROTATE|NOROTATE 

Activates or deactivates rotation through the catalog resource table (CRT) 

when control blocks are assigned to process catalog requests. Rotation 

delays the reuse of CAS control blocks as long as possible, increasing their 

availability for examination in diagnostic situations. 

SYS%ON|SYS%OFF 

Activates or deactivates the conversion of SYS% to SYS1. The default setting 

for SYS% conversion is set during system initialization. 

TASKMAX(xx) 

Sets the maximum number of CAS service tasks that are attached to process 

catalog requests. Once this limit has been reached, further requests for CAS 

services are delayed until a task control block becomes available. 

The limit is specified as a hexadecimal value xx from 18 (decimal 24) to B4 

(decimal 180). The value must also be at least as high as the current number

of tasks active in CAS. This value is displayed using the REPORT parameter. 

The default, set at IPL, is 3C (decimal 60). 

If the value xx is less than the current number of service tasks, the value for 

the maximum number of service tasks is set to the larger of B4 or the current 

number of service tasks. 

UNALLOCATE[(catname)] 

Unallocates the catalog specified as catname from CAS. The CAS storage 

used by the catalog is freed, and if this is the only catalog that resides on the 

device, the device on which the catalog resides is unallocated from CAS. 

If you do not specify a catalog, all catalogs allocated to CAS are unallocated. 

VCLOSE(volser) 

Closes the VVDS which resides on the volume with the volume serial number 

volser. 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. 

{VLF|NOVLF}(catname) 

Activates (VLF) or deactivates (NOVLF) the catalog data space cache (CDSC) 

for the catalog named catname. To activate the 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. 


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. 

WARNING|NOWARNING 

Specifies if the system is to issue message IDC1997I or IDC1998I before 

initiating an AMS DELETE UCAT FORCE, or DELETE VVDS RECOVERY. The 

messages require an operator response to complete the commands. 

At IPL time, this option is set to WARNING. The current setting of this option 

can be displayed using the REPORT parameter of the MODIFY CATALOG 

command. For information about this type of AMS DELETE, refer to: 

DFSMS/MVS V1R5 Access Method Services for the Integrated Catalog 

Facility, SC26-4906. 

If you do not want the system to issue the messages, use NOWARNING. 


B.2 New and Changed Messages 


IDC3009I VSAM CATALOG RETURN CODE IS rtn - REASON CODE IS 

IGG0CLaa - rsn 

Explanation: Catalog management returned this return code and reason code as 

a result of a catalog error or exceptional condition. 

Return code 228 has been changed to describe ECS errors. (Return code 228, 

reason code 0 was used to report a hardware error when reading the time-of-day 

clock.) 

Return code 228 

Explanation: An error occurred while processing an Enhanced Catalog Sharing 

request. The following reasons may be corrected by the installation; codes not 

shown indicate an internal system error. 

Reason Code Description 

3 Coupling facility connection error. If received with message 

IEC377I, fields aaaa and bbbb in that message contain the 

return and reason codes from IXLCONN. 

4 An ECS request was made but the system is not ECS-active. 

9 Coupling facility disconnection error. If received with message 

IEC377I, fields aaaa and bbbb in that message contain the 

return and reason codes from IXLDISC. 

13 An ECS activation request was issued for a catalog with the 

NOECSHARING attribute. 

26 Returned when the system determines that the catalog it wants to 

access is currently being shared by other systems using ECS, 

and the current system is not able to use, or is currently not using 

ECS. 

28 Catalog is temporarily in use by another system using VVDS 

sharing mode. 

29 ECS-activation of a catalog is requested, but the catalog does not 

have cross-system share options or is not on a shared volume.

IEC348I ALLOCATED CATALOGS 

Explanation: FLAGS VOLSER USER CATALOG NAME 

abcdef volser count cname 

Y/N-ALLOCATED TO CAS 

S-SMS 

V-VLF 

I-ISC 

C-CLOSED 

D-DELETED 

R-SHARED 

A-ATL 

E-ECS SHARED 

K-LOCKED 

The MODIFY command was issued for CAS, requesting a list of allocated 

catalogs. Information about each catalog includes the following: 

volser The volume serial number. 

count The hexadecimal use count. 

cname The catalog's name (this name may contain up to 44 characters). 

a Allocation status: 

If a is Y, the catalog is allocated to CAS. 

If a is N, the catalog is not allocated to CAS. 

b SMS status: 

If b is S, the catalog is SMS managed. 

c Condition: 

If c is V, the VLF (Data Space Cache) is active for this catalog. 

If c is I, the ISC (IN-STORAGE CATALOG) is active for this catalog. 

If c is C, the catalog is closed to free record management storage. The 

catalog might have been closed by the F CATALOG, CLOSE(nnnnn...) 

command, or by CAS recovery functions that caused control block 

rebuild and/or freed CAS resources. At the next access, the catalog 

will be opened with a new set of record management control blocks. 

This new set of control blocks will not affect catalog allocation, 

CAXWA, ACB, or RPL storage in CSA. 

If c is D, the catalog has been deleted. 

d Tape-volume indicator: 

If d is A, the catalog is a tape volume catalog. 

e Sharing status: 

If e is R, the catalog is using cross-system sharing in VVDS mode. 

If e is E, the catalog is shared and is using the Enhanced Catalog 

Sharing facility. 

f If f is K, the catalog is locked. 

Source: DFSMSdfp 

Module: IGG0CLGB 

System Action: The system issues a multi-line message with the volume serial 

number, the hexadecimal use count and the name of each catalog. 



IEC359I CATALOG {REPORT OUTPUT | CACHE REPORT | REPORT DUMP 

OUTPUT | PERFORMANCE OUTPUT} 

CATALOG REPORT OUTPUT 

CATALOG COMPONENT LEVEL = complvl 

CATALOG ADDRESS SPACE ASN = asn 

SERVICE TASK UPPER LIMIT = uppr 

HIGHEST # SERVICE TASKS = hnum 

CURRENT # SERVICE TASKS = cnum 

MAXIMUM # OPEN CATALOGS = maxo 

ALIAS TABLE AVAILABLE = {YES|NO} 

ALIAS LEVELS SPECIFIED = n 

CRT TABLE SLOT ROTATION = {ON|OFF} 

SYS% TO SYS1 CONVERSION = {ON|OFF} 

CAS MOTHER TASK = address 

CAS MODIFY TASK = address 

CAS ANALYSIS TASK = address 

CAS ALLOCATION TASK = address 

VOLCAT HI-LEVEL QUALIFIER = volcathlq 

VUNALLOCATE = {ON|OFF} 

DELETE UCAT/VVDS WARNING = {ON|OFF} 

CATALOG CACHE REPORT 

HIT% RECORDS SEARCHES FOUND DELETES SHR UPD PURGE 

catalog name (ISC|VLF) 

hit% records searches found deletes sharing purge 

CATALOG REPORT DUMP OUTPUT 

STATUS RETURN CODE REASON CODE MODULE ID COUNT 

{ON|OFF} retcode rsncode modid count 

CATALOG PERFORMANCE REPORT 

-----CATALOG EVENT---- --COUNT-- ---AVERAGE--event 

count avgtime 

Explanation: This message is issued in response to one of the following 

commands: 

MODIFY CATALOG,REPORT 

MODIFY CATALOG,REPORT,CACHE 

MODIFY CATALOG,REPORT,DUMP 

MODIFY CATALOG,REPORT,PERFORMANCE 

The message display contains the following information: 

For a CATALOG REPORT OUTPUT: 

complvl The FMID value. 

asn The current ASID for CAS. 

uppr The service task upper limit. The default for uppr is X'00C8', but can 

be set to another value by using the TASKMAX command format of 

MODIFY CATALOG. uppr can never be less than the service task high 

water mark, hnum.

hnum The service task high water mark. This value can never be less than 

the number of service tasks currently attached, cnum. 

cnum The number of service tasks currently attached. This number may be 

less than the service task lower limit, lowr, if: 

CAS has not yet processed the number of requests represented 

by lowr. 

or 

Tasks have abended. 

As requests are processed, CAS creates new tasks to maintain lower 

limit, and cnum increases. 

maxo The maximum number of ICF catalogs that can be open concurrently 

in CAS (or NOLIMIT). This number can be set using the CATMAX 

command format of MODIFY CATALOG. 

n The number of alias level qualifiers currently being used by catalog 

search logic (MLA). Valid values for n are1,2,3,or4. 

address The hexadecimal TCB address of various CAS tasks. 

volcathlq The high level qualifier used for the tape volume catalogs of this 

system. 

For a CATALOG CACHE REPORT: 

catname The name of the catalog to which the following information applies. 

hit% The relative number of times a search of the cache found the 

requested record, expressed as a percentage. 

records The number of records added to the cache. 

searches The number of times the cache was searched. 

found The number of times a record was found in the cache. 

deletes The number of records deleted from the cache. 

sharing The number of times the sharing protocol was effective in 

communicating changes made by sharing systems at the granularity of 

a catalog record. 

purge The number of times the entire cache for this catalog had to be 

invalidated (VLF cache only). 

For a CATALOG REPORT DUMP OUTPUT: 

retcode The catalog return code (0 to 255, or ’***’), for which dynamic dumping 

is to occur. 

rsncode The catalog reason code (0 to 255, or ’***’), for which dynamic 

dumping is to occur. 

modid The catalog module identifier, or ’**’, for which dynamic dumping is to 

occur. 

count The match count (0 to 999) for dynamic dumping. 

This number decrements each time an error that matches the return 

code, reason code, and module identifier is detected within the catalog 

address space. When the count becomes zero, a dump will be taken 

for that occurrence of the error. 



For a CATALOG PERFORMANCE REPORT: 

event The name of an internal event that requests a system function outside 

CAS. 

count The count of occurrences for this event. 

avgtime The average time for each of those events. 

The time may appear in one of three forms: 

xxx.xxx MSEC-milliseconds, used for times up to 999.999 

milliseconds. 

xxx.xxx SEC-second, used for times from 1.000 seconds up to 

999.999 seconds. 

hh:mm:ss-hours, minutes, and seconds, used for times greater than 

999.999 seconds. 


System Action: The system issues a multi-line message with the appropriate 

general information about CAS status. 

IEC377I ENHANCED CATALOG SHARING: 

{CONNECT COMPLETE | 

DISCONNECT COMPLETE | 

NOT CONNECTED: rc-rsn(sfi),mm | 

ERROR: rc-rsn(sfi),mm | 

ENABLED catname | 

REMOVED catname | 

AUTOADD ENABLED | 

AUTOADD IS NOT CURRENTLY ENABLED | 

ALL ELIGIBLE CATALOGS ENABLED} 

Explanation: This is the general status message for ECS. 

CONNECT COMPLETE 

Issued to acknowledge the successful connection of Enhanced Catalog 

Sharing (ECS) to the ECS structure in the coupling facility. This message is 

issued either during IPL, during a CAS restart, or when requested by a 

MODIFY CATALOG command with the ECSHR(CONNECT) parameter. 

DISCONNECT COMPLETE 

Issued to acknowledge a successful disconnection of ECS from the ECS 

structure in the coupling facility. This message is issued either during a 

CAS restart or when requested via a MODIFY CATALOG command with the 

ECSHR(DISCONNECT) parameter. 

NOT CONNECTED: rc-rsn(sfi),mm 

Issued during IPL or CAS restart when the system automatically tries but 

cannot connect to the ECS structure. The parameters rc, rsn and mm are 

the return code, reason code, and module ID of the detecting catalog 

module; see message IDC3009I for a description of these codes. If the

problem was detected by another service, sfi displays subfunction 

information related to the error. 

ERROR: rc-rsn(sfi),mm 

A situation has occurred which caused the sharing of catalogs using ECS 

to fail or to be terminated. This message is also issued for an unsuccessful 

CONNECT, DISCONNECT, or AUTOADD request by a MODIFY 

CATALOG(ECSHR) command. The parameters rc, rsn, and mm are the return 

code, reason code, and module ID of the detecting catalog module; see 

message IDC3009I for a description of these codes. If the problem was 

detected by another service, sfi displays subfunction information related to 

the error. 

ENABLED catname 

Issued to acknowledge an ECSHR(ENABLE,catname) request that was 

successful. 

REMOVED catname 

Issued to acknowledge an ECSHR(REMOVE,catname) request that was 

successful. 

AUTOADD ENABLED 

Issued to acknowledge an ECSHR(AUTOADD) request that was 

successful, or to report the status of the AUTOADD function after 

connecting to the ECS structure in the coupling facility. 

AUTOADD IS NOT CURRENTLY ENABLED 

Issued to report the status of the AUTOADD function after connecting to 

the ECS structure in the coupling facility. 

ALL ELIGIBLE CATALOGS ENABLED 

Issued to acknowledge an ECSHR(ENABLEALL) request that was 

successful. 


Module: IGG0CLSH/IGG0CLSI 

System Action: In the case of termination of ECS at the system level, CAS 

disconnects from the coupling facility, and sharing for all sharers using the ECS 

method is therefore terminated. The sharing of catalogs reverts to the non-ECS 

method. 

In the case where the system lost its CF connection, all catalogs are removed 

from the ECS structure and the AUTOADD function is disabled. 

In the case of an ECS failure for an individual catalog, ECS is not activated for 

this catalog. The sharing method for this catalog remains the non-ECS method. 

Operator Response: Correct the situation which caused the error/failure and 

retry the request. 

In the case of a lost CF connection, once the connection has been restored, issue 

the MODIFY CATALOG command with the ECSHR(AUTOADD) parameter to 

re-enable automatic activation. 



IEC378I catname IS NOT USING ENHANCED CATALOG SHARING. 

Explanation: This message is issued when the system is processing a shared 

catalog request and discovers for the very first time, or the first time since the last 

time the catalog was ECS-active, that the desired sharing method as defined for 

the named catalog is ECS, but either (1) another system is accessing the catalog 

in VVDS sharing mode, (2) another system has explicitly stopped ECS for this 

catalog using the MODIFY CATALOG command with the ECSHR(REMOVE) 

parameter, or (3) either of the above conditions existed when the system went 

down. 

In the text of the message above, catname indicates the catalog the system is 

accessing. 


Module: IGG0CLSJ 

System Action: Sharing will continue with the non-enhanced method of catalog 

sharing. This may result in decreased performance for this catalog. 

Operator Response: Verify if ECS is desired for this catalog. If so, then issue the 

MODIFY CATALOG command with the ECSHR(ENABLE,...) parameter to start ECS 

for this catalog. For more information, see the manual Managing Catalogs, 

SC26-4914. 

IEC380I ENHANCED CATALOG SHARING 

Explanation: This message is issued in response to a MODIFY CATALOG command 

with the ECSHR(STATUS) parameter. It displays the status of the CF connection 

as well as the ECS status of each open catalog. 

The possible values for the ECS system status are: 

AutoAdd 

The system is connected to the ECS structure and the automatic add 

function is enabled. 

Connected 

The system is connected to the ECS structure in the coupling facility; 

AUTOADD is disabled. 

Connect Failure 

While attempting to connect to the ECS structure, an error was returned 

from IXLCONN. The return and reason codes from IXLCONN are also 

displayed. 

Inact(CFFail) 

The system has disconnected because a coupling facility failure was 

detected. 

Inact(Disconnect)

ECS is disconnected from the ECS structure in the coupling facility due to a 

MODIFY CATALOG command with the ECSHR(DISCONNECT) parameter. 

Inact(Restart) 

The system disconnected while processing a CAS restart. 

Quiescing 

ECS is currently active but is in the process of quiescing. 

Unknown 

The system status of ECS is unknown. 

The possible values for a catalog's status are: 

Active 

ECS is active for the catalog. 

Inact(AddFailed) 

Activation of a catalog failed due to an internal system error. 

Inact(CFFail) 

The catalog is inactive because the coupling facility failed. 

Inact(CFFull) 

An attempt was made to activate the catalog but the ECS structure in the 

coupling facility is full. 

Inact(Disconnect) 

The catalog is inactive because the system disconnected from the ECS 

structure. 

Inact(MaxCats) 

An attempt was made to activate the catalog, but the maximum number of 

catalogs allowed to be active on a single system has been reached. 

Inact(NeverConn) 

The catalog is inactive because the system is not connected to the ECS 


Inact(NonECSAcc) 

The catalog is inactive because the last access to the catalog was from a 

system using VVDS sharing mode. 

Inact(NotElig) 

The catalog is inactive because it does not have the ECSHARING attribute. 

Inact(NotShrable) 

The catalog is inactive because it cannot be cross-system shared, because 

it either does not have SHAREOPTIONS(3 4) or the volume is not marked 

as shared. 

Inact(Removed) 

The catalog is inactive due to a MODIFY CATALOG command with the 

ECSHR(REMOVE,...) parameter. 

Inact(Unknown) 



The ECS status of this catalog has never been set or is otherwise 

unknown. 

Unavailable 

The ECS status of the catalog cannot be determined. 


Module: IGG0CLGB 

System Action: System operation continues normally. 

Operator Response: None. For additional information on the interpretation of the 

output from this command, see Managing Catalogs, SC26-4914. 

IEC381I ENHANCED CATALOG SHARING HAS BEEN QUIESCED DUE TO A 

COUPLING FACILITY FAILURE ON ANOTHER SYSTEM. 

Explanation: This message is issued on an ECS-active system when another 

system in the sysplex that was also ECS-active, lost its connection to the ECS 

coupling facility structure. 


Module: IGG0CLSI 

System Action: All ECS-active catalogs are deactivated and the AUTOADD 

function is disabled. However, the system remains connected to the ECS 

structure. 

Operator Response: Once the connection problem is resolved, issue the MODIFY 

CATALOG command with the ECSHR(AUTOADD) parameter to re-enable automatic 

activation. Catalogs not referenced by the system that lost the connection can be 

explicitly activated using the MODIFY CATALOG command with the 

ECSHR(ENABLE,...) parameter.

Appendix C. Special Notices 

This publication is intended to help experienced storage administrators 

implement Enhanced Catalog Sharing. The information in this publication is not 

intended as the specification of any programming interfaces that are provided by 

DFSMS/MVS 1.5. See the PUBLICATIONS section of the IBM Programming 

Announcement for DFSMS/MVS 1.5 for more information about what publications 

are considered to be product documentation. 

References in this publication to IBM products, programs or services do not imply 

that IBM intends to make these available in all countries in which IBM operates. 

Any reference to an IBM product, program, or service is not intended to state or 

imply that only IBM's product, program, or service may be used. Any functionally 

equivalent program that does not infringe any of IBM's intellectual property rights 

may be used instead of the IBM product, program or service. 

Information in this book was developed in conjunction with use of the equipment 

specified, and is limited in application to those specific hardware and software 

products and levels. 

IBM may have patents or pending patent applications covering subject matter in 

this document. The furnishing of this document does not give you any license to 

these patents. You can send license inquiries, in writing, to the IBM Director of 

Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785. 

Licensees of this program who wish to have information about it for the purpose 

of enabling: (i) the exchange of information between independently created 

programs and other programs (including this one) and (ii) the mutual use of the 

information which has been exchanged, should contact IBM Corporation, Dept. 

600A, Mail Drop 1329, Somers, NY 10589 USA. 

Such information may be available, subject to appropriate terms and conditions, 

including in some cases, payment of a fee. 

The information contained in this document has not been submitted to any formal 

IBM test and is distributed AS IS. The use of this information or the 

implementation of any of these techniques is a customer responsibility and 

depends on the customer's ability to evaluate and integrate them into the 

customer's operational environment. While each item may have been reviewed 

by IBM for accuracy in a specific situation, there is no guarantee that the same or 

similar results will be obtained elsewhere. Customers attempting to adapt these 

techniques to their own environments do so at their own risk. 

Any pointers in this publication to external Web sites are provided for 

convenience only and do not in any manner serve as an endorsement of these 

Web sites. 

Reference to PTF numbers that have not been released through the normal 

distribution process does not imply general availability. The purpose of including 

these reference numbers is to alert IBM customers to specific information relative 

to the implementation of the PTF when it becomes available to each customer 

according to the normal IBM PTF distribution process. 



The following terms are trademarks of the International Business Machines 

Corporation in the United States and/or other countries: 

AIX DFSMSdss 

DFSMS/MVS DFSMS 

IBM Language Environment 

NetView PR/SM 

OS/390 RACF 

The following terms are trademarks of other companies: 

C-bus is a trademark of Corollary, Inc. in the United States and/or other countries. 

Java and all Java-based trademarks and logos are trademarks or registered 

trademarks of Sun Microsystems, Inc. in the United States and/or other countries. 

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of 

Microsoft Corporation in the United States and/or other countries. 

PC Direct is a trademark of Ziff Communications Company in the United States 

and/or other countries and is used by IBM Corporation under license. 

ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel 

Corporation in the United States and/or other countries. 

UNIX is a registered trademark in the United States and/or other countries 

licensed exclusively through X/Open Company Limited. 

SET and the SET logo are trademarks owned by SET Secure Electronic 

Transaction LLC. 

Other company, product, and service names may be trademarks or service marks 

of others.

Appendix D. Related Publications 

The publications listed in this section are considered particularly suitable for a 

more detailed discussion of the topics covered in this redbook. 

D.1 International Technical Support Organization Publications 

D.2 Redbooks on CD-ROMs 

D.3 Other Publications 

For information on ordering these ITSO publications see “How to Get ITSO 

Redbooks” on page 121. 

DFSMShsm Primer, SG24-5272 

DFSMS Optimizer: The New HSM Monitor/Tuner, SG24-5248 

Redbooks are also available on the following CD-ROMs. Click the CD-ROMs 

button at http://www.redbooks.ibm.com/ for information about all the CD-ROMs 

offered, updates and formats. 

CD-ROM Title Collection Kit 

Number 

System/390 Redbooks Collection SK2T-2177 

Networking and Systems Management Redbooks Collection SK2T-6022 

Transaction Processing and Data Management Redbooks Collection SK2T-8038 

Lotus Redbooks Collection SK2T-8039 

Tivoli Redbooks Collection SK2T-8044 

AS/400 Redbooks Collection SK2T-2849 

Netfinity Hardware and Software Redbooks Collection SK2T-8046 

RS/6000 Redbooks Collection (BkMgr Format) SK2T-8040 

RS/6000 Redbooks Collection (PDF Format) SK2T-8043 

Application Development Redbooks Collection SK2T-8037 

These publications are also relevant as further information sources: 

DFSMS/MVS V1R5 Access Method Services for the Integrated Catalog 

Facility, SC26-4906 

DFSMS/MVS V1R5 DFSMSdfp Advanced Services, SC26-4921 

DFSMS/MVS V1R5 DFSMSdfp Storage Administration Reference, SC26-4920 

DFSMS/MVS V1R5 General Information, GC26-4900 

DFSMS/MVS V1R5 DFSMSdss Storage Administration Guide, SC26-4930 

DFSMS/MVS V1R5 DFSMSdss Storage Administration Reference, 

SC26-4929 

DFSMS/MVS V1R5 DFSMShsm Implementing and Customizing, SH21-1078 

DFSMS/MVS V1R5 DFSMShsm Managing Your Own Data, SH21-1077 

DFSMS/MVS V1R5 DFSMShsm Storage Administration Guide, SH21-1076 

DFSMS/MVS V1R5 DFSMShsm Storage Administration Reference, 

SH21-1075 

DFSMS/MVS V1R5 Installation Exits, SC26-4908 



DFSMS/MVS V1R5 Implementing System-Managed Storage, SC26-3123 

DFSMS/MVS V1R5 Managing Catalogs, SC26-4914 

DFSMS/MVS V1R5 Macro Instructions for Data Sets, SC26-4913 

DFSMS/MVS V1R5 Using Data Sets, SC26-4922 

DFSMS/MVS V1R5 Planning for Installation, SC26-4919 

Integrated Catalog Forward Recovery Utility Program Description/Operations, 

SH20-6952 

OS/390 V2R7.0 MVS Initialization and Tuning Guide, SC28-1751 

OS/390 V2R7.0 MVS Initialization and Tuning Reference, SC28-1752 

OS/390 V2R7.0 MVS Setting Up a Sysplex, GC28-1779 

OS/390 V2R7.0 MVS Programming: Sysplex Services Reference, GC28-1772 

OS/390 V2R7.0 MVS System Commands, GC28-1781 

OS/390 V2R7.0 MVS System Management Facilities (SMF), GC28-1783 

OS/390 V2R7.0 MVS System Messages, Vol 1 (ABA-ASA), GC28-1784 

OS/390 V2R7.0 MVS System Messages, Vol 2 (ASB-EZM), GC28-1785 

OS/390 V2R7.0 MVS System Messages, Vol 3 (GDE-IEB), GC28-1786 

OS/390 V2R7.0 MVS System Messages, Vol 4 (IEC-IFD), GC28-1787 

OS/390 V2R7.0 MVS System Messages, Vol 5 (IGD-IZP), GC28-1788 

OS/390 Parallel Sysplex Recovery, GA22-7286 

Removing an MVS System from a Sysplex, GA22-7407 

S/390 PR/SM Planning Guide, GA22-7236

How to Get ITSO Redbooks 

This section explains how both customers and IBM employees can find out about ITSO redbooks, redpieces, and 

CD-ROMs. A form for ordering books and CD-ROMs by fax or e-mail is also provided. 

Redbooks Web Site http://www.redbooks.ibm.com/ 

Search for, view, download, or order hardcopy/CD-ROM redbooks from the redbooks Web site. Also read 

redpieces and download additional materials (code samples or diskette/CD-ROM images) from this redbooks 

site. 

Redpieces are redbooks in progress; not all redbooks become redpieces and sometimes just a few chapters will 

be published this way. The intent is to get the information out much quicker than the formal publishing process 

allows. 

E-mail Orders 

Send orders by e-mail including information from the redbooks fax order form to: 

In United States 

Outside North America 

Telephone Orders 

United States (toll free) 

Canada (toll free) 


Fax Orders 

United States (toll free) 

Canada 


e-mail address 

usib6fpl@ibmmail.com 

Contact information is in the “How to Order” section at this site: 

http://www.elink.ibmlink.ibm.com/pbl/pbl/ 

1-800-879-2755 

1-800-IBM-4YOU 

Country coordinator phone number is in the “How to Order” section at 

this site: 


This information was current at the time of publication, but is continually subject to change. The latest information 

may be found at the redbooks Web site. 

IBM Intranet for Employees 

1-800-445-9269 

1-403-267-4455 

Fax phone number is in the “How to Order” section at this site: 


IBM employees may register for information on workshops, residencies, and redbooks by accessing the IBM 

Intranet Web site at http://w3.itso.ibm.com/ and clicking the ITSO Mailing List button. Look in the Materials 

repository for workshops, presentations, papers, and Web pages developed and written by the ITSO technical 

professionals; click the Additional Materials button. Employees may access MyNews at http://w3.ibm.com/ for 

redbook, residency, and workshop announcements. 


IBM Redbook Fax Order Form 

Please send me the following: 

Title Order Number Quantity 

First name Last name 

Company 

Address 

City Postal code 

Telephone number Telefax number VAT number 

Invoice to customer number 

Credit card number 

We accept American Express, Diners, Eurocard, Master Card, and Visa. Payment by credit card not 

available in all countries. Signature mandatory for credit card payment. 


Country 

Credit card expiration date Card issued to 

Signature

List of Abbreviations 

AMS Access method services 

BCS Basic catalog structure 

CAS Catalog address space 

CCW Channel command word 

CDSC Catalog data space cache 

CF Coupling facility 

CFRM Coupling facility resource management 

CPU Central processing unit 

CSI Catalog search interface 

DASD Direct access storage device 

ECS Enhanced catalog sharing 

GDG Generation data group 

GDS Generation data set 

GRS Global resource serialization 

GTF Generalized trace facility 

IBM International Business Machines Corporation 

ICF Integrated catalog facility 

IOS Input-output supervisor 

IPL Initial program load 

ISC In-storage cache 

ITSO International Technical Support Organization 

KSDS Key-sequenced data set 

LLA Library lookaside 

LPA Link pack area 

NVR Non-VSAM volume record 

PR/SM Processor Resource/Systems Manager 

SMF System management facilities 

SMS Storage Management Subsystem 

SVC Supervisor call 

VLF Virtual lookaside facility 

VSAM Virtual Storage Access Method 

VTOC Volume table of contents 

VVDS VSAM volume data set 

VVR VSAM volume record 



Index 

Symbols 

&LELEVEL 20, 33 

A 

alias 

DFSMSdss restore 62 

ALIASLEVEL 41 

Allocating Catalogs to the CAS 36 

ALTER 63, 70 

AMS 

ALTER 28, 40, 63 

DEFINE 29, 32 

DELETE TRUENAME 69 

DIAGNOSE 64, 72 

EXAMINE 69 

EXPORT 59, 66 

IMPORT 63, 66 

LOCK 61, 63 

UNLOCK 61 

assembler programs 83 

AUTOADD 29, 45 

restart 30 

system recognition of 29 

AutoAdd 39 

Automatic Add 29 

B 

backup 

aliases 57 

backup copy storage media 57 

BCS 57 

Integrated Catalog Forward Recovery Utility 58 

tape volume catalog 57 

VVDS 57 

backup copy numbers 58 

backup copy of catalog 54 

backup frequency 53, 58 

backup technique 54 

BCS 2 

checking for missing updates 64 

comparing 72 

creation 2 

function 2 

portable copy used by ICFRU 58 

synchronization 70 

VSAM information 2 

C 

Cache Structure Description 16 

CAS connection 19 

CAS disconnection 19 

full 17 

integrity VVR 17 

storage required 17 

Cache Structure Sizing 17 


catalog 

Access Method Services Export 54 

accessing 4 

altering to ECSHARING 40 

backup creation 54 

DFSMSdss full volume dump 56 

DFSMSdss logical dump 55 

DFSMShsm 57 

error symptoms 77 

monitoring sharing status 46 

moving to another volume 58 

recovery of broken 61 

recovery techniques 61 

reorganization 62 

RESERVE 8 

sharing problems 77 

structural error 61 

structural integrity 69 

utility actions 61 

when to recover 61 

Catalog Address Space 5 

abends 79 

activating maintenance 45 

automatic add 29 

control block location 6 

controlling 36 

enhanced catalog sharing 44 

controlling caching status 38 

controlling current settings 41 

controlling service tasks 44 

controlling the allocation status 40 

controlling the sharing status 39 

definitions 35 

determining service level of modules 42 

FMID 41 

function 6 

hang 79 


modifying current CAS options 41 

monitoring performance 47 

performance statistics 42 

restarting 45 

status 37 

status messages 39 

supervisor call 5 

user waiting for 79 

virtual storage 6 

Catalog data space cache 6 

Catalog Search Interface 52 

implementation 87 

catalog structure 2 

BCS 2 

VVDS 2 

CATMAX 36, 41 

CDSC 6, 35, 38 

CF Connection Status for ECS 46 

CF structure connection 26 

CFRM Policy 24 

activating 25 

recommended buffer 24 


size 24 

Channel Command Word 8 

CLPA 45 

COFVLFxx 35 

COMPAREDD 72 

COMPAREDS 72 

Connect Failure status 26 

coupling facility 10 

Coupling Facility Structure 12 

CFRM policy 12 

connection 12 

Disconnection 12 

persistence 12 

CSI 52, 83 

performance benefits 85 

CVOL 1 

D 

Data 17 

data set 2 

BCS information 2 

VTOC information 3 

VVDS information 2 

DATATEST 69 

DEFINE 70 

defining aliases 13 

DELETE 70 

DELETE RECOVERY 41 

DELETE TRUENAME 69 

DELETE UCAT/VVDS WARNING 41 

DELETE USERCATALOG FORCE 41 

DEVSERV 78 

DFSMSdss 55, 56, 58, 74 

fully qualified name 62 

DFSMShsm 57, 58, 59 

DFSORT 65 

DIAGNOSE 64, 72 

diagnosis tools 76 

Directory 17 

DUMP 80 

SDATA options 80 

E 

ECS 10 

ECS and non-ECS interaction 20 

ECS eligible 10 

ECSHARING 10 

ECSHR attribute 28 

eligible for ECS 26 

ENABLEALL 45 

Enhanced Catalog Sharing 10 

controlling status 44 

determining catalogs 16 

failure 11 

integrity 11 


limitation 16 

lower level systems 15 

maximum catalogs 16 

127

performance 11 

performance statistics 42 

PTF 15 

statistics 47 

SYSIGGCAS_ECS 16 

sysplex considerations 45 

verifying the status 27 

VVDS mode 11 

EXAMINE 69 

EXPORT 58, 59, 66 

extended alias reference 33 

Extended Alias Support 13 

catalog resolution 34 

catalogs 20 

data set names 20 

name resolution 15 

system symbols 30 

F 

Fixed controls 17 

G 

GDG 59 

GDS 59 

generalized trace facility 85 

generation data group 59 

generation data set 59 

generation numbers 62 

global symbol 31 

GRS 10 

star mode 10 

H 

hardware configuration definition 77 

HCD 77, 78 

I 

ICFRRAP 66 

ICFRRSV 66 

ICFRU 58, 66 

IEASYMxx 20, 30, 33 

IEC377I 26 

IEFBR14 49 

IGG.CATLOCK 62, 64 

IGGCSI00 84 

IGGCSILK 85 

IGGCSIRX 85 

IGGCSIVG 85 

IGGCSIVS 85 

IMBED 15, 62 

IMPORT 63, 66 

INDEXTEST 69 

Indirect Volume Serial Support 30 

In-storage catalog cache 6 

Integrated Catalog Forward Recovery Utility 66 

integrity exposures 6 


ISC 6, 38 


IXLCACHE 51 

IXLCONN 26 

IXLSTR.SYSIGGCAS_ECS 17 

L 

link pack area 45 

LISTCAT 64 

NONVSAM 64 

LLA refresh 45 

LOADxx 35 

local symbol 31 

LOCK 61 

logical dump 55 

M 

master address space 36 

master catalog availability 58 

master catalog copies 58 

master catalog opening 36 

master catalog recovery 61 

messages 108 

MLPA 45 

MODIFY CATALOG 

complete parameter list 101 

N 

Non-ECS catalog 11 

non-VSAM 

BCS information 3 

non-SMS BCS information 3 

non-SMS VTOC information 3 

non-SMS VVDS information 3 

VTOC information 3 

VVDS information 3 

number of backup copies 58 

NVR 2 

O 

Operational Issues 19 

P 

Parallel Sysplex 9 

performance figures 47 

portable backup copy 61, 63, 66 

Program Temporary Fix 15 

R 

recovery 61 

master catalogs 63 

missing updates 64 

moving catalogs to other volumes 63 

post recovery updates 64 

preventing catalog activity 63 

user catalogs 63 

ReferringtoanExtendedAlias 33 

REPLICATE 15, 62 

129

Resource Access Control Facility 17 

facility class 17 

REXX 83 

S 

SDATA 80 

Security Considerations 17 

SETXCF 25 

shared DASD 77 

SHAREOPTION 77 

SHAREOPTIONS 7 

default 7 

system 7 

systems 7 

user programs 8 

SMF 65, 66 

TYPE 61 65 

TYPE 65 65 

TYPE 66 65 

SMF type 36 62 

SMFPRMxx 65 

stand-alone restore 62 

SYMBOLICRELATE 13, 32 

SYMDEF 20 

synchronization error repairing 74 

synchronization errors 70, 72 

SYS1.LINKLIB 84 

SYS1.PARMLIB 20, 65 

SYSCAT 35 

SYSDEF 20 

SYSIGGCAS_ECS 16, 25, 27, 35 

sysplex considerations 45 

system symbol variables 30 

T 

tape volume catalog 7 

backup 57 

storing backup copy 57 

tape volume catalogs 

backup considerations 59 

TASKMAX 41 

TOD clock 9 

U 

UCB 78 

UCB common segment 78 

unexpected 19 

UNLOCK 61 

user catalog copies 58 

V 

virtual lookaside facility 35 

VLF 36, 38 

VOLCAT 7 

content 7 

General 7 

naming conventions 7 

sharing and protecting 7 


Specific 7 

structure 7 

VTOC 



VVDS 

backup 57 

checking for missing updates 64 

comparing 72 

description 2 

function 2 



VVDS DEQs 42 

VVDS I/O 42, 49 

VVDS mode 11, 39, 42, 46, 48, 50, 78 

VVDS RESERVE Shr 49, 51 

VVDS RESERVEs 42 

VVR 2 

131


ITSO Redbook Evaluation 


SG24-5594-00 

Your feedback is very important to help us maintain the quality of ITSO redbooks. Please complete this 

questionnaire and return it using one of the following methods: 

Use the online evaluation form found at http://www.redbooks.ibm.com 

Fax this form to: USA International Access Code + 1 914 432 8264 

Send your comments in an Internet note to redbook@us.ibm.com 

Which of the following best describes you? 

_ Customer _ Business Partner _ Solution Developer _ IBM employee 

_ None of the above 

Please rate your overall satisfaction with this book using the scale: 

(1 = very good, 2 = good, 3 = average, 4 = poor, 5 = very poor) 

Overall Satisfaction __________ 

Please answer the following questions: 

Was this redbook published in time for your needs? Yes___ No___ 

If no, please explain: 

What other redbooks would you like to see published? 

Comments/Suggestions: (THANK YOU FOR YOUR FEEDBACK!) 


SG24-5594-00 

Printed in the U.S.A. 

Enhanced Catalog Sharing and Management SG24-5594-00

Enhanced Catalog Sharing and Management - IBM Redbooks

Create successful ePaper yourself

Delete template?

Save as template?