VSAM - Access Method Services

Non-VSAM data management required many utility programs for file processing operations.

• IEBGENER to copy the contents of sequential datasets

• IEHMOVE and IEBCOPY to copy, move, reorganize, expand, backup and restore the contents of partitioned dataset

• IEBISAM to load, backup, restore, and reorganize the contents of ISAM datasets

However, There is only a single utility for managing all of the file processing operation for VSAM - JCL IDCAMS Utility.

IDCAMS is also known by the functionality it provides - Access Method Services - or, simply, AMS

AMS has a utility program called IDCAMS that can be invoked through a standard JCL and will perform the various functions of the AMS through its commands.

The most commonly used AMS commands are:

• DEFINE USERCATALOG/MASTERCATALOG

  This command is used by system programmers to define a VSAM catalog. A user catalog has to be allocated and cataloged in a master catalog prior to defining VSAM data sets in it.

• DEFINE SPACE

  This command allocates VSAM space on a particular disk pack. This space is subsequently used to define sub-allocated VSAM data sets within it.

• DEFINE CLUSTER

  This command allocates and catalogs a VSAM data set. For a KSDS, it allocates both the data and index components.

• REPRO - This command is used to load records into a VSAM data set. It is similar in some respects to the IEBGENER utility.

• DEFINE ALTERNATE INDEX

  This command is used to define an alternate index for a KSDS or an ESDS. This command only allocates the space for the alternate index and the records can be loaded into only by using the BLDINDEX command. The base cluster has to be defined to prior to defining the alternate index.

• BLDINDEX

  As mentioned before, the alternate key-pointer pair records are loaded into the alternate index cluster by this command. Therefore, the base cluster has to be defined and loaded and the alternate index defined before using this command.

• PRINT

  This command can be used to print a VSAM data set. It can also be used to print physical sequential, partitioned data set members, etc.

• VERIFY

  During abnormal terminations of the system, VSAM files open at that time will be left open. This command closes the files, brings the index component in sync with the data components and updates the catalog.

• DELETE

  As the name of the command implies, this command can be used to delete a VSAM cluster. It can also be used to delete non-VSAM files. VSAM files cannot be deleted with the DELETE option of the DISPOSITION parameter of JCL.

• ALTER

  This command can be used to alter certain parameters used while creating a VSAM cluster without actually delete-defining the data set.

• DEFINE GDG

  You can define* Generation Data Group (GDG) index using this command. A GDG is a logical grouping of sequential files under the GDG index. For example, the monthly payroll file for each month can be defined as a GDG index racfid.GDG.TEST. Then you can use the following references in a JCL:

  • racfid.GDG.TEST(O)

    would refer to the latest generation of this Generation Data Group

  • racfid.GDG.TEST(-1)

    would refer to the previous generation of this Generation Data Group

  • racfid.GDG.TEST(+1)

    will allocate a new generation for the next month

• LISTCAT

  This command lists the different attributes of a VSAM data set.

We have seperate chaper to discuss each commands.

Example:

The basic JCL to run the utility is.

//JOBNAME1 JOB 'IBMMAINFRAMER',CLASS=C,MSGLEVEL=(1,1),MSGCLASS=C
//IDCAMS   EXEC PGM=IDCAMS,REGION=0K
//SYSPRINT DD SYSOUT=C
//SYSIN    DD *
/* UTILITY COMMAND STATEMENTS */
/*

Some of the functions require additional DD statements when they are referenced by the AMS command statements, but SYSPRINT and SYSIN are the only absolute requirements.

Rules for Command Statements:

• The default statement margins are positions 2 through 72.

• Any command statement may be continued from one line to the next by following the last parameter in a line with a hyphen (-).

• A value may be continued by immediately following it with a plus sign (+).

• A comment may be embedded in the command statements by enclosing the comment characters with /* and */.

• Blank lines may be included at any point before, interspersed with, or following AMS commands.

• Positional parameters are not optional and must precede all keyword parameters.

• Keyword parameters can stand alone or they may have an associated set of values or a subparameter list enclosed in parentheses.

• Parameters, subparamenters, and values are separated from one another by spaces, commas, or comment blocks.

Modal Commands

It is possible to include AMS commands to perform more than one function in a single execution of the IDCAMS utility. Therefore, AMS sets a return code following the execution of each command, and also maintains a maximum return code value for each execution.

AMS commands are provided to interrogate these return codes and conditionally execute command statements based on the return code set during the execution of prior commands.

The return codes set by AMS can be interpreted as.

• 0 - Normal Completion - the functional command completed its processing successfully.

• 4 - Minor Error - processing is able to continue, but a minor error occurred, causing a warming message to be issued.

• 8 - Major Error - processing is able to continue, but a more severe error occurred, causing major command specifications to be bypassed.

• 12 - Logical Error - generally, inconsistent parameters are specified, causing the entire command to be bypassed.

• 16 - Severe Error - an error of such severity occurred that not only can the command causing the error not be completed, the entire AMS command stream is flushed.

IF - THEN - ELSE Structure

The statement structure used to conditionally execute commands based upon the return code values is an IF - THEN - ELSE structure.

IF {LASTCC | MAXCC} {operator} {numeric value}
    THEN {command} |
        DO {command set}
        END
[ELSE {command} |
        DO
          {command set}
        END]

In the IF statement, the return code to be tested is specified as one of LASTCC or MAXCC, where LASTCC specifies the return code set during the execution of the command just prior to the IF structure and MAXCC specifies the largest return code value set during this execution if IDCAMS.

The {operator} is specified as one of the following comparison operators.

Following the THEN keyword or the optional ELSE keyword, either a single AMS command or a block of AMS commands enclosed in a DO/END pair may be coded.

Null Commands

If a THEN keyword or ELSE keyword in an IF-THEN-ELSE structure is not followed by an AMS functional command, or does not include a continuation character indicating that a functional command follows on the next line, then a null THEN or ELSE clause is assumed.

SET Command

The SET command may be used to set either the LASTCC value or the MAXCC value to a specific value. Frequently the SET command is used to reset the return code(s) to a value of 0 following an expected warning level error condition.

Example:

Let us see an example how to delete and define VSAM dataset in single JCL step using IF statement.

//JOBNAME1 JOB 'IBMMAINFRAMER',CLASS=A,MSGLEVEL=(1,1),MSGCLASS=A
//*
//IDCAMS EXEC PGM=IDCAMS,REGION=4096K
//SYSPRINT DD SYSOUT=A
//SYSIN DD *
/* DELETE KSDS CLUSTER, IF IT EXISTS */
    DELETE racfid.EMPLOYEE.FILE CLUSTER PURGE
/* DEFINE KSDS CLUSTER */
IF LASTCC = 0 THEN -
    DEFINE CLUSTER ( -
      NAME(racfid.EMPLOYEE.FILE) -
      VOLUMES(IBM01) -
      RECORDSIZE(80 80) -
      RECORDS(50 10) -
      KEYS(10 0) -
      INDEXED ) -
    DATA ( -
      NAME(racfid.EMPLOYEE.FILE.DATA) ) -
    INDEX ( -
      NAME(racfid.EMPLOYEE.FILE.INDEX) )
END
/*

Explanation:

if delete command completed successfully(i.e. LASTCC=0), then the define cluster command will be executed.

If you have any doubts or queries related to this chapter, get them clarified from our Mainframe experts on ibmmainframer Community!