z390 VSAM Compatible
 Assembler Support

As of z390 release v1.4.01, VSAM ESDS, RRDS, and KSDS sequential and random access are supported.  ESDS, RRDS, and KSDS  sequential and random updates with insert are supported.  All VSAM file types can be defined in VCDT VSAM catalog definition tables.  The VCDT catalogs can contain any number of base cluster, alternate index, and path definitions with default local path or explicit overrides defining user specified path and name for data and index files.  The DDNAME on ACB at open must point to the VCDT loadable catalog table file containing the desired base cluster or path to be opened.  The DDNAME file specification can contain optional dot suffix with the name of the base cluster or path to  be opened.  If an explicit entry is not specified, the name of the ACB will be used to find entry in the specified catalog.  The current plan for additional VSAM support is as follows:

1. KSDS alternate index read only plus BUILDINDEX utility

2. ENQ/DEQ record locking for VSAM (currently there is no locking)

3. KSDS ENDREQ and ERASE macro support

4. LDS linear support with user specified CONTROLINTERVALSIZE on DEFINE CLUSTER macro.  (Note the current default support for ESDS, RRDS/VRRDS, and KSDS does not use CI/CA structures and all inserts are added at the end of base cluster VES data file.  The planned initial LDS support will insert dead space in CI’s as required to insure no records are split across CI’s.

See the following VSAM User Guide for more information on the current support: 

1. z390 VSAM User Guide (PDF)

z390 VSAM support consists of the following components:

• VCDT - VSAM Catalog Definition Table is assembled from multiple DEFINE macros used to define VSAM base clusters, alternate index, and paths.  The VCDT is assembled and linked into loadable table which is referened by ACB DDNAME at open time.  The following DCB physical files are dynamically allocated at ACB open time:
  • VES DCB base data file with fixed or variable length records.  Variable records are prefixed with 4 byte length which is not included in logical record length.  For ESDS the keyword INDEX=NONINDEXED is required on the DEFINE CLUSTER macro.  For RRDS the keyword INDEX=NUMBERED is required on DEFINE CLUSTER macro. The default is KSDS which also requires keyword KEYS=(length, offset) defining primary unique key field.
  • VX0 DCB primary VRRDS or KSDS index file containing 8 byte XRBA's to each record in VES DCB.  For KSDS the VX0 file include XRBA and primary key field in key sequence.
  • VXN DCB alternate index file for KSDS optional alternate index files containing 8 byte RBA plus alternate key field alternate key sequence.  The VXN XRBA points to record entry in the VX0 index file.  The keyword RELATE= specifies name of base cluster, and the keyword UPGRADE=NOGRADE can be specified to turn off updating of alternate index.
  • The DEFINE macro parameters for creating VCDT catalog are as follows:
    • CATALOG
      • ,NAME=  define catalog name which appears in dump
    • CLUSTER,
      • NAME=, base cluster name (default file names will be NAME.VES and NAME.VX0)
      • RECORDSIZE=,  required fixed length or average and maximum variable record length up to 2 GB.
      • INDEX=INDEXED, optional cluster type INDEXED (KSDS default), NUMBERED (RRDS), NONINDEXED (ESDS), or LINEAR (LDS) type VSAM cluster.
      • KEYS=(64,0), KSDS primary unique key field (length,offset)
      • REUSE=REUSE, optional parameter to request empty file at each open
      • VESDSN, optional user specified path and file name for base cluster data
      • VX0DSN, optional user specified override path and name for base cluster index
    • ALTERNATEINDEX,
      • NAME=,  alternate index name (default file name will be NAME.VXN)
      • KEYS=(64,0), alternate key length and offset in base cluster records
      • RELATE=, name of base cluster
      • UPGRADE=NOUPGRADE, request no updating of alternate index
      • REUSE=REUSE, optional paramter to request empty file at each open
    • PATH,
      • NAME=, name of path to alternate index or alias base cluster
      • ENTRY=, name of alternate index or base cluster
      • UPDATE=NOUPDATE request no updating of any alternate indexes
• ACB, ACBD, CLOSE, ENDREQ, ERASE, GENCB, GET, OPEN, MODCB, POINT, PUT, RPL, RPLD, SHOWCB, TESTCB, and VCDTD - VSAM application macros for VSAM access/
• REPRO - utility to load or unload fixed or variable length VSAM file from/to QSAM file.  For VSAM files with variable length records over 32760, an application program must be used to load, unload or copy to another VSAM file.
• Demo programs in vsam\demo:
  • DEMOS.BAT - assemble, link, and execute all VSAM demo programs
  • ESF1DEMO.BAT - assemble, link, and execute ESF1SP.MLC to copy fixed length QSAM file to VSAM ESDS file and then run ESF1SG.MLC to copy ESDS file back to fixed length QSAM file and verify QSAM files match.
  • ESV1DEMO.BAT - assemble, link, and execute ESV1SP.MLC to copy variable length QSAM file to ESDS and execute ESV1SG.MLC to copy ESDS file back to variable length QSAM file and verify QSAM files match.
  • KSF1RPO1.BAT - load and unload KSDS fixed length file from/to text file with 6 test names and addresses.
  • KSF1DEMO.BAT - randomly read the 6 records randomly by name key and display records.
  • KSF1SKP1.BAT - point to first record with name >= "MQ" and read and display sequentially.
  • RRF1DEMO.BAT - create RRDS file with 3 fixed length records and read records back by relative record number to verify content.
  • RRV1DEMO.BAT - create RRDS file with 3 variable length records and read records back by relative record number to verify length and content.
• Regression test programs and files (vsam\test):
  • ESF1TEST.BAT - test fixed length ESDS sequential, RBA, and XRBA access
  • ESF1SKP1.BAT - test fixed length ESDS skip sequential forward/backward from XRBA start
  • ESF2TEST.BAT - test fixed length ESDS sequential and random update in place
  • ESF3TEST.BAT - test fixed length ESDS read backwards
  • ESF3GEN1.BAT - test fixed length ESDS read backwards using GENCB for ACB and RPL
  • ESV1TEST.BAT - test variable length ESDS sequential, RBA, and XRBA random access
  • ESV1SKP1.BAT - test variable length ESDS skip sequential forward/backward from XRBA start
  • ESV2TEST.BAT - test variable length ESDS with records up to 100,000 bytes
  • ESV3TEST.BAT - test variable length ESDS sequential and random update in place
  • ESV4TEST.BAT - test variable length ESDS read backwards
  • RRF1TEST.BAT - test fixed length RRDS random read and write
  • RRV1TEST.BAT - test variable length VRRDS random read and write and update different length
  • KSF1TEST.BAT - test KSDS fixed length record query by key and sequentail forward/backword
  • KSF2TST1.BAT - test KSDS insert of 1 record and retrieval by key
  • KSF2TST2.BAT - test KSDS insert of 3 records and retrieval by key
  • KSF2TST3.BAT - test KSDS retrieval of existing and inserted records by key and seq. fwd/bwd
  • KSF2TST4.BAT - test KSDS AVL balanced tree insert support by inserting 1000 records in pseudo random sequence and then retrieving them sequentially by key.  See AVL statistics on the STATS optional STA statistics file showing max tree depth of 10 for 1000 records (2**10=1024).
• REPRO load and unload tests
  • ESF1RPO1.BAT - test load and unload of fixed length ESDS from/to QSAM EF format
  • ESF4RPO1.BAT - load and unload ESDS fixed file from/to QSAM EF format
  • ESV1RPO1.BAT - load and unload of variable length ESDS from/to QSAM EV format
  • ESV5RPO1.BAT - load and unload ESDS variable file from/to QSAM EV format
  • RRF1RPO1.BAT - load and unload RRDS fixed file from/to QSAM RF format
  • RRF2RPO1.BAT - load and unload RRDS fixed file from/to QSAM RF format
  • RRV1RPO1.BAT - load and unload RRDS variable file from/to QSAM RV format
  • ESF1RPQ1.BAT - test load and unload of fixed length ESDS from/to QSAM E format
  • ESF4RPQ1.BAT - load and unload ESDS fixed file from/to QSAM FT format
  • ESV1RPQ1.BAT - load and unload of variable length ESDS from/to QSAM V format
  • ESV5RPQ1.BAT - load and unload ESDS variable file from/to QSAM VT format
  • RRF2RPQ1.BAT - load and unload RRDS fixed file from/to QSAM F format
  • RRV1RPQ1.BAT - load and unload RRDS variable file from/to QSAM V format
• See online document with VSAM regression tests by RPL option and macro type

IBM VSAM Related References:

1. VSAM Demystified (Redbook)
2. VSAM Data Set Overview and Design Parameters
3. z/OS DFSMS AMS for Catalogs
   1. DEFINE CLUSTER to define base cluster
   2. DEFINE ALTERNATEINDEX to define an alternate index
   3. DEFINE PATH to define path for accessing base via an alternate index
4. z/OS DFSMS Macro Instructions for Data Sets
   1. ACB macro to access VSAM cluster
      1. OPEN - open one or more ACB's
      2. CLOSE - close one or more ACB's
   2. GENCB - dynamically generate ACB
   3. GENCB - dynamically generate exit list
   4. GENCB - dynamically generated RPL
   5. MODCB - modify ACB
   6. MODCB - modify exit list
   7. MODCB - modify RPL
   8. RPL macro to request specific VSAM record access
      1. ENDREQ - end request to release update locking
      2. ERASE - delete record previously retrieved via GET
      3. GET macro to read record
      4. POINT - set current position to specified key, record, or RBA address
      5. PUT macro to write record
   9. SHOWCB - show contents of ACB
   10. SHOWCB - show contents of exit list
   11. SHOWCB - show contents of RPL
   12. TESTCB - test content of ACB field
   13. TESTCB - test content of exit list field
   14. TESTCB - test content of RPL field
   15. VSAM macro return and reason codes
5. z/OS DFSMS Using Data Sets
   1. Loading a VSAM Data Set
   2. RDF record definition fields at end of control interval (not used)

Other Useful VSAM References:

• AVL Balanced Tree Algorithm
• Neon VSAM Function description
• SAS VSAM
• VSAM Record Level Sharing