Step-by-step: define a VSAM KSDS

Defining a KSDS is one of the first “I am a real mainframer” tasks you will own end to end. It is also easy to do dangerously fast: a copied DEFINE from the internet, a rushed KEYS clause, and suddenly a catalog entry exists that training LPARs tolerate but production RACF never allows. This page is a twelve-step recipe that forces sequencing: understand the record, choose space, write DEFINE with explicit component names for clarity, review with a human, submit IDCAMS, LISTCAT verify, wire security, optionally REPRO load, smoke test, document, and hand off. Adapt numbers to your standards; do not adapt the ordering if you are still learning.

Step table at a glance

Worked example skeleton (test LPAR only)

Replace every name, volume, and size with values your storage team approved. KEYS(10 0) means length ten starting at displacement zero in the logical record per IBM convention—confirm against your layout; many production keys are not at zero.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
//DEFKSDS EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DEFINE CLUSTER (NAME(DEPT.TRAIN.CUST.KSDS) -
    INDEXED -
    KEYS(10 0) -
    RECORDSIZE(80 80) -
    CYLINDERS(2 1) -
    FREESPACE(10 5) -
    SHAREOPTIONS(2 3) -
    VOLUMES(SCR001)) -
  DATA (NAME(DEPT.TRAIN.CUST.KSDS.DATA)) -
  INDEX (NAME(DEPT.TRAIN.CUST.KSDS.INDEX))
/*
//CHKLIST  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  LISTCAT ENTRIES(DEPT.TRAIN.CUST.KSDS) ALL
/*

Deep dives on the fragile lines

RECORDSIZE(min,max)

Minimum and maximum logical lengths must bracket every record you will store. Variable-length KSDS records use a four-byte RDW-style length prefix in many language mappings; beginners miscount that prefix and set maximum too small. Walk the layout with hex documentation if needed.

SHAREOPTIONS(cross-system,cross-region)

The pair expresses how VSAM allows sharing across systems and regions. Wrong values cause intermittent locking failures or, worse, unsafe sharing. CICS and batch combinations have opinions; copy from a known-good pattern at your shop instead of inventing numbers.

CATALOG placement

If your enterprise uses user catalogs, the CATALOG operand or alias strategy determines where the entry lands. Wrong catalog placement makes LISTCAT searches feel “flaky” because you are looking in the master while the object lives elsewhere.

After define: do not skip LISTCAT

LISTCAT ALL is your photograph of reality. Compare KEYS, RECORDSIZE, volumes, and free space to the design document. If anything drifted because SMS ignored a mistyped DATACLAS, you want that discovery before REPRO loads ten million rows.

Optional REPRO load hook

If you will populate immediately, queue the SORT job before REPRO as described on the initial load page. Keep define and load in separate steps during learning so you can separate catalog mistakes from data mistakes when SYSPRINT complains.

Handoff package contents

• DSN list: cluster, data, index, and any PATH names if AIX arrives later.
• DISP guidance: SHR versus OLD expectations per environment.
• FILE STATUS expectations: normal versus exceptional codes for service programs.
• Reorg owner: who runs IDCAMS reorganization utilities or vendor equivalents on what schedule.

Practice exercises

1. Define a tiny training KSDS on scratch volumes and LISTCAT the full entry set.
2. Deliberately use a wrong KEYS offset in test (with mentor supervision) and capture the DEFINE error text.
3. Write a peer-review checklist of five questions to ask before submitting any DEFINE in production.
4. Pair-read DEFINE CLUSTER syntax and mark three clauses your shop always omits versus IBM examples.

Explain like I'm five

Building a KSDS is like building a labeled drawer cabinet before you put toys inside. You measure toys first, print labels the same size as the measuring tape says, screw the cabinet to the wall where parents allow, then take a photo for the grown-ups’ binder—that is LISTCAT. Only after the cabinet is solid do you sort toys by label and put them in—that is REPRO. If you skip measuring, the dinosaur tail sticks out and the drawer jams forever.

Test your knowledge