IDCAMS: define, load, inspect

IDCAMS is the utility for everything VSAM. Three commands cover most of what you will do: DEFINE creates a cluster, REPRO copies data in or out, and LISTCAT tells you what state it is in.

Defining a KSDS

A realistic DEFINE CLUSTER

//DEFSTEP  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DEFINE CLUSTER ( -
     NAME(PROD.PAY.ACCOUNT) -
     INDEXED -                        KSDS
     KEYS(10 0) -                    10-byte key at offset 0
     RECORDSIZE(200 200) -           average, maximum
     FREESPACE(20 20) -              % free in CI, % free CIs in CA
     SHAREOPTIONS(2 3) -
     CYLINDERS(50 10) -
     VOLUMES(DASD01) ) -
   DATA  ( NAME(PROD.PAY.ACCOUNT.DATA) ) -
   INDEX ( NAME(PROD.PAY.ACCOUNT.INDEX) )
/*

Parameter	Means
INDEXED / NONINDEXED / NUMBERED / LINEAR	KSDS / ESDS / RRDS / LDS
KEYS(length offset)	Where the key is in the record
RECORDSIZE(avg max)	Equal values mean fixed-length records
FREESPACE(ci% ca%)	Room left for inserts — higher for files that grow
SHAREOPTIONS(x y)	Who may open it at once, within and across systems
REUSE	Allows the file to be reset and reloaded as if new

Loading and unloading with REPRO

REPRO both ways

* load a sequential file into the VSAM cluster
  REPRO INFILE(SEQIN) OUTFILE(VSAMOUT)

* unload VSAM to sequential, for a backup or a test extract
  REPRO INFILE(VSAMIN) OUTFILE(SEQOUT)

* copy just part of it, by key range
  REPRO INFILE(VSAMIN) OUTFILE(SEQOUT) -
        FROMKEY('0010000000') TOKEY('0019999999')

* take the first 1000 records for a test file
  REPRO INFILE(VSAMIN) OUTFILE(SEQOUT) COUNT(1000)

LISTCAT: reading the health of a file

LISTCAT ENT('PROD.PAY.ACCOUNT') ALL prints a long report. Four numbers in it are worth finding every time:

Field	Tells you
REC-TOTAL	How many records are in the file
REC-DELETED	How many were deleted — high values mean wasted space
SPLITS-CI / SPLITS-CA	How often inserts have forced restructuring. Rising CA splits mean a REORG is due
EXTENTS	How many pieces the file is in. Approaching the limit means it will soon fail to extend
HI-USED-RBA vs HI-ALLOC-RBA	How full the allocated space is

Alternate indexes

Defining and building an alternate index

  DEFINE ALTERNATEINDEX ( -
     NAME(PROD.PAY.ACCOUNT.AIX1) -
     RELATE(PROD.PAY.ACCOUNT) -
     KEYS(20 30) -                    surname, at offset 30
     NONUNIQUEKEY -                 several accounts per surname
     RECORDSIZE(100 500) -
     CYLINDERS(10 2) )

  DEFINE PATH ( -
     NAME(PROD.PAY.ACCOUNT.PATH1) -
     PATHENTRY(PROD.PAY.ACCOUNT.AIX1) )

  BLDINDEX INDATASET(PROD.PAY.ACCOUNT) -
           OUTDATASET(PROD.PAY.ACCOUNT.AIX1)

DEFINE CLUSTER, line by line

IDCAMSWhat it means

DEFINE CLUSTER (NAME(PROD.ACCT.KSDS) -

The cluster name. The hyphen continues the command on the next line.

INDEXED -

A key-sequenced dataset (KSDS).

KEYS(8 0) -

The key is 8 bytes long, starting at offset 0.

RECORDSIZE(200 200) -

Average and maximum record length.

FREESPACE(20 10) -

Leave 20% of each control interval and 10% of the CIs in each control area free for inserts.

CYLINDERS(50 10))

Primary and secondary space.

Try it yourself

TRY IT YOURSELF

Write the KEYS parameter for a 12-byte key that starts at offset 4.

Show a hint

Length first, then offset.

Show the solution

KEYS(12 4)