4. IDCAMS COMMANDS

You can write IDCAMS utility program

1. To create VSAM dataset

2. To list, examine, print, tune, backup, and export/import VSAM datasets.

The IDCAMS utility can be invoked in batch mode with JCL or interactively with TSO commands. With JCL you can print/display datasets and system messages and return codes. Multiple commands can be coded per job. You can use IF-THEN-ELSE statement to execute command/s selectively based on condition codes returned by previous commands.
Listed below are the IDCAMS commands to be discussed in this course

• DEFINE
• MODAL COMMANDS
 IF
 SET
 PARM
• BUILDINDEX
• REPRO
• PRINT
• DELETE
• VERIFY
• IMPORT/EXPORT
• ALTER
• LISTCAT

The example 4.1 shown below is a skeleton JCL for executing IDCAMS commands. The PGM parameter specifies that the program to be executed is IDCAMS utility program . The statements that follow SYSIN DD * are IDCAMS commands. The end of data is specified by /*.

Optionally JOBCAT and STEPCAT statements may be coded to indicate catalog names for a job/step, in which concerned dataset may be cataloged


// jobname JOB (parameters)
// stepname EXEC PGM=IDCAMS
// SYSPRINT DD SYSOUT = *
[// ddname DD DSN=datasetname,
DISP= SHR/ OLD
]
//SYSIN DD *
IDCAMS command/s coded freely between 2 to 72 cols.
/*
//
Optionally:
// JOBCAT DD DSN = catalogname, DISP= SHR
// STEPCAT DD DSN = catalogname, DISP = SHR




Example 4.1 JCL for executing IDCAMS commands

Format of IDCAMS command

verb object (parameters)

Every IDCAMS command starts with a verb followed by object which takes some parameters. In the code listing 4.2 DEFINE is the verb CLUSTER is the object which takes a dataset DA0001T.LIB.KSDS.CLUSTER as parameter

DEFINE CLUSTER -
NAME(DA0001T.LIB.KSDS.CLUSTER) -
CYLINDERS(5, 1) -
VOLUMES (BS3013) -
INDEXED -
)


Example 4.2 Creating a cluster

Comments:
Comments in IDCAMS can be specified in the following manner

/* comment */
or
/* -----
*/

IDCAMS return codes

The IDCAMS Commands return certain codes which have the following interpretation

Condition code:

0 : command executed with no errors
4 : warning - execution may go successful
8 : serious error - execution may fail
12 : serious error - execution impossible
16 : fatal error - job step terminates

The condition codes are stored in LASTCC/MAXCC. LASTCC stores the condition code for the previous command and MAXCC stores the maximum code returned by all previous commands. Both LASTCC and MAXCC contain zero by default at the start of IDCAMS execution. You can check the condition code of the previous command and direct the flow of execution or terminate the JCL.

Syntax of IF statement

IF LASTCC/MAXCC
comparand VALUE -
THEN -
command
ELSE
Command

Comparand(s) are : EQ/NE/GT/LT/GE/LE

Hyphen is required after then to indicate the continuation of the command on the next line . Comment is assumed as null command . ELSE is optional. LASTCC and MAXCC values can be changed using the SET command.

Note : LASTCC and MAXCC can also be set to any value between 0-16

e.g.

SET LASTCC = 4

Setting MAXCC has no effect on LASTCC. Setting LASTCC changes the value of MAXCC, if LASTCC is set to a value larger than MAXCC. Setting MAXCC = 16 terminates the job


.........
REPRO INFILE (INDD) -
OUTFILE (OUTDD)
................
IF LASTCC EQ 0 -
THEN -
PRINT OUTFILE (INDD)
ELSE
PRINT INFILE (OUTDD)
IF MAXCC LT 4 -
THEN -
DO
/* COMMENT */
Command
Command
END
ELSE
Command

Example 4.3a JCL using MAXCC and LASTCC



DEFINE CLUSTER
….
IF LASTCC > 0 THEN
SET MAXCC = 16
ELSE
REPRO
……


Example 4.3b JCL using MAXCC and LASTCC



Defining an ESDS Cluster

DEFINE CLUSTER

Clusters are created and named with the DEFINE CLUSTER command.
The NAME parameter
This is a required positional parameter.

Format : NAME(Cluster-Name)
Cluster name :- The name to be assigned to the cluster

Example: NAME(DA0004T.LIB.KSDS.CLUSTER)
The cluster Name becomes the dataset name in any JCL that invokes this cluster either as an input or output

//INPUT DD DSN=DA0004T.LIB.KSDS.CLUSTER,DISP=SHR

The high-level qualifier is important because in most installations this technique ensures that VSAM datasets are cataloged in the appropriate user catalog.

Rules for Naming Cluster

Can have 1 to 44 alphanumeric characters

Can include the national characters #, @, $

Segmented into level of eight or fewer characters, separated by periods

The first character must be either alphabetic or national character

The SPACE Allocation parameter

The space allocation parameter specifies space allocation values in the units shown below:
Format :
CYLINDERS(Pri Sec)
TRACKS(Pri Sec)
RECORDS(Pri Sec)
KILOBYTES(Pri Sec)
MEGABYTES(Pri Sec)

Primary : Number of units of primary space to allocate. This amount is allocated once when the dataset is created

Secondary : Number of units of secondary space to allocate. This amount is allocated a maximum of 122 times as needed during the life of the dataset. VSAM calculates the control area size for you. A control area size of one cylinder usually yields best performance. To ensure control area size of one cylinder you must allocate space in CYLINDERS.

Allocating space ine RECORDS must be avoided as this might result in an inefficient Control Area size.
The VOLUMES parameter

This VOLUMES parameter assigns one or more storage volumes to your dataset. Multiple volumes must be of the same device type.
Format :
VOLUMES(volser) or VOLUMES(volser ........ volser)

volser : The 6 digit volume serial number of a volume.
Example :
VOLUMES(BS3011)
VOLUMES(BS3011 BS3040 BS3042)

You can store the data and index (in case of KSDS clusters) on separate volumes as this may provide a performance advantage for large dataset
The Recordsize parameter

This parameter tells VSAM what size records to expect. The avg and max are average and maximum values for variable length record. If records are of fixed length, avg and max should be the same.
Format :

RECORDSIZE(avg max)

avg : Average length of records
max : Maximum length of records
e.g. :
RECORDSIZE(80 80) [Fixed Length records]
RECORDSIZE(80 120) [Variable Length records]
RECORDSIZE can be assigned at the cluster or data
level
Note :

This is an optional parameter, if omitted default is RECORDSIZE(4086 4086)
The SPANNED parameter

This parameter allows large record to span more than one control interval. However records cannot span Control Areas. The resulting free space in the spanned control interval is unusable by other records, even if they fit logically in the unused bytes. [NONSPANNED is the default] & it means that records cannot span control intervals
The DATASET-TYPE parameter

This parameter specifies whether the dataset is INDEXED(KSDS),
NONINDEXED(ESDS), or NUMBERED(RRDS).

Format : INDEXED NONINDEXED NUMBERED

INDEXED :- Specifies a KSDS and is the default
NONINDEXED :- Specifies an ESDS. No index is created and records are accessed sequentially or by relative byte address
NUMBERED :- Specifies an RRDS
LINEAR :- Specifies a LINEAR dataset

The default dataset Type is INDEXED.


//DA0001TA JOB LA2719, PCS,MSGLEVEL=(1,1),
// MGCLASS=A,NOTIFY=DA0001T
// * Delete/Define Cluster for ESDS VSAM Dataset
//STEP1 EXEC PGM=IDCAMS
// SYSPRINT DD SYSOUT = *
// SYSIN DD *
DELETE DA0001T.LIB.ESDS.CLUSTER


DEFINE CLUSTER -
(NAME(DA0001T.LIB.ESDS.CLUSTER) -
NONINDEXED -
RECORDSIZE(125 125) -
RECORDS(100 10) -
NONSPANNED -
VOLUMES (BS3013) -
REUSE - ) -
DATA(NAME(DA0001T.LIB.ESDS.DATA))

Example 4.4 JCL for Defining an ESDS Cluster

Defining KSDS Cluster
While defining a KSDS Cluster it is essential to code the DATA, INDEX and KEYS parameter
The DATA parameter

The DATA parameter tells IDCAMS that you are going to create a separate data component. This parameter is optional for ESDS and RRDS datasets. You should code the NAME parameter of DATA for KSDS datasets, in order to operate on the data component by itself.

Format : DATA(NAME(dataname) Parameters)

dataname :- The name you choose to name the data component

The INDEX parameter
The INDEX parameter creates a separate index component
Format :
INDEX(NAME(indexname) Parameters)
indexname : The name you choose to name the index component

INDEX(NAME(DA0004T.LIB.KSDS.INDEX))

When you code the DATA and INDEX parameters, you usually coda a NAME parameter for them. If you omit the NAME parameter for DATA and INDEX , VSAM appends .DATA or .INDEX as the low-level qualifier.
The KEYS parameter

This parameter defines the length and offset of the primary key in a KSDS record.
The offset is the primary key’s displacement (in bytes) from the beginning of the record.

Format :
KEYS(length offset)

length : length in bytes of the primary key
offset : Offset in bytes of the primary key with records (0 to n)
Example :
KEYS(8 0)
VSAM records begin in position zero

Note :
Default is KEYS(64 1) [Key is in bytes 2 thru 65]



//DA0001TA JOB LA2719, PCS,MSGLEVEL=(1,1),
// MGCLASS=A,NOTIFY=DA0001T
// * Delete/Define Cluster for KSDS VSAM Dataset
//*
//STEP1 EXEC PGM=IDCAMS
// SYSPRINT DD SYSOUT=*
// SYSIN DD *
DELETEDA0001T.LIB.KSDS.CLUSTER
DEFINE CLUSTER(
NAME(DA0001T.LIB.KSDS.CLUSTER) -
INDEXED -
KEYS(4 0) -
FSPC(10 20) -
RECORDSIZE(125 125) -
RECORDS(100 10) -
NONSPANNED -
VOLUMES (BS3013) -
NOREUSE - )-DATA(NAME(DA0001T.LIB.KSDS.DATA)) INDEX(NAME(DA0001T.LIB.KSDS.INDEX))
/*
//


Example 4.5 JCL for Defining a KSDS Cluster
The FREESPACE parameter

This FREESPACE parameter, which applies to the KSDS, allocates some percentage of control interval and control area for planned free space. This free space can be used for adding new records or for expanding existing variable records. FREESPACE applies only to the data component

Format :
FREESPACE(%CI %CA)

%CI :- Percentage of control interval to leave free for expansion
%CA :- Percentage of control area to leave free for expansion
Example : FREESPACE(20 10)
Too much free space results in more i/o, especially when doing sequential processing. Too little results in excessive control interval and control area split

Note :
Default is FREESPACE(0 0)
The REUSE parameter

The REUSE parameter specifies that the cluster can be opened a second time as a reusable cluster. NOREUSE is the default, and specifies the cluster as non-reusable.

Format :

REUSENOREUSE

Some application call for temporary dataset or workfile that must be created, used and deleted each time the application runs. To simplify these applications, VSAM lets you create reusable files. The reusable file is a standard VSAM KSDS, ESDS or RRDS. The only difference is that, if you open an existing reusable file for output processing, VSAM treats the file as if were empty. Any records already present in the file are ignored.
The CONTROL INTERVAL SIZE parameter

This parameter specifies the Control Interval size. It is usually abbreviated CISZ.
Format :
CISZ(bytes)
Example :
CISZ(4096)

Note : If omitted VSAM calculates CISZ based on record size.

Remark : Control Interval is VSAM’s equivalent of a block and it is the unit of data that is actually transmitted when records are read or written.
Guidelines for determining the CISZ

ESDS is processed sequentially, so the CISZ should be relatively large, depending on the size of the record. For sequential processing with larger records you may choose a CISZ of 8k

For datasets processed randomly as well as sequentially (for backup at night) choose a CISZ for random processing and then allocate extra buffers for sequential processing with the AMP JCL parameter.

RRDS is usually processed randomly, so the CISZ should be relatively small, depending on the size of the record.
SHAREOPTIONS
This parameter tells VSAM whether you want to let two or more jobs to process your file at the same time. It specifies how a VSAM dataset can be shared
Format :

SHARE OPTIONS(cr value cs value)

cr value : Specifies the value for cross region sharing. Cross region sharing is defined as different jobs running on the same system using Global Resource Serialization(GRS), a resource control facility available only under MVS/XA and ESA
cs value : Specifies the value for cross system sharing means different jobs running on different system in a NONGRS environment

Values :-
• multiple read OR single write
• multiple read AND single write
• multiple read AND multiple write

Default :- SHAREOPTIONS(1 3)

Back to VSAM index