For users new to z/OS, understanding how to accomplish even simple tasks can be a challenge. Creating and copying files, defining z/OS-unique items such as Generation Data Groups (GDGs) and VSAM datasets, and just getting dataset information in z/OS systems is different. Fortunately, there’s a ‘Swiss-Army knife’ that can perform all these tasks and much more. IDCAMS, the Access Method Services utility, is one of the most important and widely used applications in any z/OS system. IDCAMS is used by both applications and systems programmers to perform tasks ranging from file creation and reporting to managing catalogs and tape libraries. IDCAMS amazingly wide range of function means there’s almost nothing you can’t do with it – let’s take a look at how it works and some of the more common tasks we can perform.
JCL and Control Statements
The Job Control Language (JCL) required to execute IDCAMS is remarkably simple. Besides the EXEC PGM=IDCAMS statement, all that’s usually required is a SYSPRINT dataset for the output and a SYSIN dataset for the control statements. Most other datasets, if they are needed, can be referenced in the control statements or dynamically allocated. About thirty different control statements allow the user to perform almost any dataset or catalog-related z/OS function. The ‘modal’ commands (IF-THEN, DO-END, SET, etc.,) control the flow of operations if more than one function is to be performed, but it’s the ‘functional’ commands (DEFINE, ALTER, LISTCAT, and so on), that do the work.
Common Tasks – Creating VSAM Clusters and More
The DEFINE command, used to create datasets or catalog entries, is the most commonly used of the functional commands. DEFINE has a number of variations, depending upon whether one is creating a VSAM cluster (i.e., a VSAM dataset, probably the most common use) or something else, such as an alias, usercatalog, GDG, or non-VSAM catalog entry. Numerous parameters on the DEFINE command specify all of the many detailed characteristics of the cluster or other entity that’s being defined. For a complex dataset such as a VSAM key-sequenced cluster with alternate indexes and pathnames, additional commands (DEFINE AIX, DEFINE PATH) follow the DEFINE CLUSTER command used to create the base VSAM dataset and are used to create the additional components of the cluster, such as indexes and pathnames. Ultimately, for most VSAM DEFINEs as well as many other functions, such as LISTCAT, IDCAMS invokes SVC 26 to do the actual work required.
In addition to VSAM clusters, the DEFINE command can be used to create many other items, using variations such as DEFINE GDG (to create generation datasets), DEFINE ALIAS (to create alternate names for datasets or qualifiers), and DEFINE USERCATALOG (to create catalogs). DEFINE NONVSAM can be used to create non-VSAM catalog entries, but the creation of actual non-VSAM datasets (as opposed to just catalog entries) is accomplished with the ALLOCATE command, which functions in the same way as the identical TSO command.
After Creation – Loading, Altering, Copying
Once a dataset or a catalog entry (such as a GDG base) is defined, the ALTER command allows IDCAMS to change almost any attribute of the entity if needed. A dataset, of course, is only useful if it actually contains data – the IDCAMS REPRO command is therefore used to load VSAM clusters from sequential datasets (or other VSAM clusters). REPRO is also generally to copy data from one dataset to another. Parameters on the REPRO command specify if records should be skipped, encrypted/decrypted, and whether existing files or records can be overlaid with new data (REPLACE and REUSE). REPRO is also used by system programmers for such tasks as merging user catalogs. Figure 1 shows a typical IDCAMS job that might be used to create a keyed VSAM cluster, load it with data via REPRO, and update the alternate index via the BLDINDEX command.
Removing Data
Datasets usually ‘live’ on disk for only so long before storage management utilities such as DFSMShsm or FDRABR automatically delete them. The IDCAMS DELETE command, however, can be used to deliberately remove just about any type of dataset or catalog entry. Operands such as PURGE and FORCE can be used to delete unexpired datasets or non-empty GDGs. The MASK operand, which allows mass deletion of large numbers of like-named datasets, can be particularly useful. Figure 2 shows two uses of DELETE – removing and erasing all datasets with a specified naming convention, and removing an ‘orphan’ VVR for a VSAM cluster which happens to be incorrectly uncatalogued.
Displaying Catalog Entries
By far the oldest, most common, and essential use of IDCAMS is the LISTCAT command. LISTCAT is used to display the contents of catalog entries based on their name, and perhaps type, such as CLUSTER, NONVSAM, or USERCATALOG. Unlike the DELETE command, there is no MASK option. Catalog entities to be listed are specified by the ENTRIES or LEVEL parameters, which allow for a certain limited amount of masking via the ‘*’ or ‘%’ characters. The format of the LISTCAT output is fixed, and varies depending upon the type of entries being listed. If the LISTCAT command happens to select entries from multiple catalogs, they appear in catalog order rather than in alphabetical order. Because LISTCAT’s selection filtering is limited and the output cannot be changed (and often includes more information than might be necessary), it’s common to use the OUTFILE parameter to direct the output from LISTCAT to a DD statement. From there, the fixed-format output can then be parsed and processed by a more flexible REXX exec. Figure 3 shows the use of LISTCAT to display a subset of the tape volume entries for a particular tape library, with the output directed to a dataset.
MANUALIDFSMS Access Method Services Commands
The z/OS DFSMS Access Method Services Commands manual (SC23-6846) describes each of the IDCAMS commands in detail, along with JCL examples, sample output, and a description of the interface that can be used to invoke IDCAMS from a program.
Still More IDCAMS Functions
There are many more IDCAMS functions besides those listed above. Particularly useful commands for debugging are PRINT, which displays the contents of VSAM or non-VSAM datasets or catalogs, and the EXAMINE and VERIFY commands. EXAMINE can be used to find problems with the structure of complex multi-component key-sequenced or relative record VSAM datasets (KSDS or VRRDS). VERIFY is run to detect and fix VSAM end-of-file errors which can arise if errors occur when a VSAM dataset is closed.
There is also a plethora of specialized IDCAMS functions used mostly by storage administrators and system programmers. These include operations such as IMPORT, EXPORT, and RECOVER commands for managing catalogs, and commands related to VSAM record-level sharing (RLS), such as SETCACHE and LISTDATA. One IDCAMS command that deserves special mention is DCOLLECT, which produces system-level, dataset-level and volume level records that can be processed to produce detailed reports on the DFSMS storage environment.
Conclusion
To describe everything that can be done with IDCAMS would require an entire book. Fortunately, there is such a book. The z/OS DFSMS Access Method Services Commands manual (SC23-6846) describes each of the IDCAMS commands in detail, along with JCL examples, sample output, and a description of the interface that can be used to invoke IDCAMS from a program. The manual, a must-have in every z/OS programmer’s toolkit, can be found at here.
IDCAMS is available in every z/OS installation as it is part of DFSMS, the storage management component of the operating system. It is an essential tool for both application and system programmers and whether they are new to z/OS or grizzled veterans.
