VSAM File Access for COBOL

 

The MVT COBOL compiler, that is.  Anyone who really wants to do anything worthwhile with COBOL, even if it is just a beginner learning to write some COBOL, cannot be pleased that the COBOL compiler we have available to us (the one bundled in with MVT), cannot handle VSAM files directly.  The only option up until now (at least to the best of my knowledge) has been to write the COBOL code as though it was manipulating ISAM files and point the DD for the ISAM file to a VSAM dataset, which invokes the ISAM Interface Program under the covers.  This is only marginally acceptable, and I know because I maintained applications for commercial banks doing this in the late 1970's.  I decided to try and find a better solution.

So I sat down with a matrix of organization, access type, and mode that is available with a modern COBOL compiler and did some research to see how I could provide most of this functionality to the ancient compiler we had available.  The result is a single Assembler routine which is called from COBOL to access any VSAM dataset in any valid combination of dataset organization, access, and mode.  I know that calling an external routine still isn't the same as using native COBOL files and file access verbs, but it is closer than we have with the ISAM Interface Program.  Here is a matrix indicating what I implemented in my routine:

Organization

Access

Sequential

Direct

Dynamic

Input

Output

Input/Output

Input

Output

Input/Output

Input

Output

Input/Output

KSDS

yes

yes

yes

yes

no

yes

yes

no

yes

RRDS

yes

yes

yes

yes

yes

yes

yes

no

yes

ESDS

yes

yes

yes

no

no

no

no

no

no

Shortly after I began designing the routine, someone I was corresponding with passed along a web link they found while looking for a solution for me.  It was not an acceptable solution to me, as their Assembler routine required modification and reassembly for each dataset to be accessed.  That would also require a more detailed knowledge of both Assembler and VSAM access control block macros, not to mention that it would result in having a lot of customized Assembler modules to keep track of.  As I began coding the Assembler, I hit a rough spot and went searching the web myself, just to see if any other solution had been overlooked.  The only additional solution I found was written for DOS/VSE and utilized hard-coded, self-modifying code.  I couldn't even determine the version of VSAM it was written for.  So, I rolled up my sleeves and finished my solution, becoming a pioneer, once again.  Oh well, at least I know a lot more about VSAM control block macros now.

My single routine, VSAMIO, will handle all access to one or more VSAM datasets for the calling COBOL program.  Prior to calling the routine to open each VSAM dataset to be processed, a parameter block is populated to customize the characteristics of the dataset and the manner in which it will be accessed.  Therefore, it is not necessary to know Assembler or how to use the Assembler VSAM control block macros.  In fact, the routine can be assembled once into an object module library and will only need to be linked to the COBOL object module during linkage editing.  It is not necessary to reassemble the routine each time a COBOL calling program is compiled.  

Note about Version 2

If you visited my site when I first announced that I had written this routine, you probably remember that the version of my routine available at that time only handled a single VSAM dataset.  In order to handle more than one dataset, it was necessary to "clone" the routine.  I was urged to begin work on an updated version that would handle multiple datasets, and that is the version that is available and described here.  

Parameter Interface Blocks

Communication between the COBOL calling program and VSAMIO is accomplished by the use of two parameter blocks.  The first block contains only the command to process against a particular dataset and return code information regarding the outcome of processing that command.  The second block contains Information regarding the VSAM dataset against which the command is to be processed.  The first parameter block is contained in the COBOL copybook VSAMIO:

000100* ************************************************************** *
000200*                                                                *
000300*        VV   VV  SSSSS     A    M     M  IIII    OOOOO          *
000400*        VV   VV SS   SS   AAA   MM   MM   II    OO   OO         *
000500*        VV   VV SS       AA AA  MMM MMM   II    OO   OO         *
000600*        VV   VV  SSSSS  AA   AA MMMMMMM   II    OO   OO         *
000700*        VV   VV      SS AA   AA MM M MM   II    OO   OO         *
000800*         VV VV  SS   SS AAAAAAA MM   MM   II    OO   OO         *
000900*          VVV   SS   SS AA   AA MM   MM   II    OO   OO         *
001000*           V     SSSSS  AA   AA MM   MM  IIII    OOOOO          *
001100*                                                                *
001200* ************************************************************** *
001300*                                                                *
001400* THESE PARAMETERS ARE USED TO INTERFACE WITH THE VSAM DATASET   *
001500* ACCESS ROUTINE.                                                *
001600*                                                                *
001700* THE VSIO-PARAMETER-VALUES SUPPLY THE VALUES USED TO MOVE INTO  *
001800* PARAMETER ENTRIES TO TAILOR THE ROUTINE TO A SPECIFIC DATASET  *
001900* AND TO PROVIDE COMMANDS TO DRIVE THE ROUTINE.                  *
002000* ************************************************************** *
002100 01  VSIO-PARAMETER-VALUES.
002200     02  VSIO-OPEN               PIC  X(08)  VALUE 'OPEN    '.
002300     02  VSIO-CLOSE              PIC  X(08)  VALUE 'CLOSE   '.
002400     02  VSIO-READ               PIC  X(08)  VALUE 'READ    '.
002500     02  VSIO-WRITE              PIC  X(08)  VALUE 'WRITE   '.
002600     02  VSIO-REWRITE            PIC  X(08)  VALUE 'REWRITE '.
002700     02  VSIO-DELETE             PIC  X(08)  VALUE 'DELETE  '.
002800     02  VSIO-START-KEY-EQUAL    PIC  X(08)  VALUE 'STARTEQ '.
002900     02  VSIO-START-KEY-NOTLESS  PIC  X(08)  VALUE 'STARTGE '.
003000     02  VSIO-KSDS               PIC  X(04)  VALUE 'KSDS'.
003100     02  VSIO-ESDS               PIC  X(04)  VALUE 'ESDS'.
003200     02  VSIO-RRDS               PIC  X(04)  VALUE 'RRDS'.
003300     02  VSIO-SEQUENTIAL         PIC  X(10)  VALUE 'SEQUENTIAL'.
003400     02  VSIO-DIRECT             PIC  X(10)  VALUE 'DIRECT    '.
003500     02  VSIO-DYNAMIC            PIC  X(10)  VALUE 'DYNAMIC   '.
003600     02  VSIO-INPUT              PIC  X(06)  VALUE 'INPUT '.
003700     02  VSIO-OUTPUT             PIC  X(06)  VALUE 'OUTPUT'.
003800     02  VSIO-INPUT-OUTPUT       PIC  X(06)  VALUE 'UPDATE'.
003900
004000* ************************************************************** *
004100* THE VSIO-PARAMETER-BLOCK IS THE COMMUNICATION INTERFACE TO     *
004200* THE ROUTINE.                                                   *
004300* ************************************************************** *
004400 01  VSIO-PARAMETER-BLOCK.
004500     02  VSIO-COMMAND            PIC  X(08).
004600     02  VSIO-RETURN-CODE        PIC S9(04)  COMP.
004700         88  VSIO-SUCCESS                    VALUE +0.
004800         88  VSIO-LOGIC-ERROR                VALUE +8.
004900         88  VSIO-END-OF-FILE                VALUE +9999.
005000         88  VSIO-PARAMETER-ERROR            VALUE +20 THRU +28.
005100         88  VSIO-COMMAND-UNKNOWN            VALUE +20.
005200         88  VSIO-DATASET-ALREADY-OPEN       VALUE +21.
005300         88  VSIO-DATASET-NOT-OPEN           VALUE +22.
005400         88  VSIO-ORGANIZATION-KEYWORD       VALUE +23.
005500         88  VSIO-ACCESS-KEYWORD             VALUE +24.
005600         88  VSIO-ACCESS-UNSUPPORTED         VALUE +25.
005700         88  VSIO-MODE-KEYWORD               VALUE +26.
005800         88  VSIO-MODE-UNSUPPORTED           VALUE +27.
005900         88  VSIO-DDNAME-BLANK               VALUE +28.
006000     02  VSIO-VSAM-RETURN-CODE   PIC S9(04)  COMP.
006100     02  VSIO-VSAM-FUNCTION-CODE PIC S9(04)  COMP.
006200     02  VSIO-VSAM-FEEDBACK-CODE PIC S9(04)  COMP.
006300         88  VSIO-DUPLICATE-RECORD           VALUE +8.
006400         88  VSIO-SEQUENCE-ERROR             VALUE +12.
006500         88  VSIO-RECORD-NOT-FOUND           VALUE +16.
006600         88  VSIO-NO-MORE-SPACE              VALUE +28.
006700         88  VSIO-READ-WITHOUT-START         VALUE +88.
006800* ************************************************************** *
006900*                    END OF VSAMIO COPY BOOK                     *
007000* ************************************************************** *

The level 02 data names under VSIO-PARAMETER-VALUES are constants that may be moved into the parameter fields to customize how the routine handles a particular dataset.  By defining the constants here in the copybook, I reduce the possibility of introducing errors that hand coding literals might cause.

The level 02 data names under the second 01 group, VSIO-PARAMETER-BLOCK, are the actual fields passed to the Assembler routine. 

For each VSAM dataset to be processed by the VSAMIO routine, a second parameter block must be defined.  The second parameter block is contained in the COBOL copybook VSAMIOFB:

000100* ************************************************************** *
000200*                                                                *
000300*  VV   VV  SSSSS     A    M     M IIII  OOOOO  FFFFFFF BBBBBB   *
000400*  VV   VV SS   SS   AAA   MM   MM  II  OO   OO FF      BB   BB  *
000500*  VV   VV SS       AA AA  MMM MMM  II  OO   OO FF      BB   BB  *
000600*  VV   VV  SSSSS  AA   AA MMMMMMM  II  OO   OO FFFFF   BBBBBB   *
000700*  VV   VV      SS AA   AA MM M MM  II  OO   OO FF      BB   BB  *
000800*   VV VV  SS   SS AAAAAAA MM   MM  II  OO   OO FF      BB   BB  *
000900*    VVV   SS   SS AA   AA MM   MM  II  OO   OO FF      BB   BB  *
001000*     V     SSSSS  AA   AA MM   MM IIII  OOOOO  FF      BBBBBB   *
001100*                                                                *
001200* ************************************************************** *
001300* THESE PARAMETERS ARE USED TO INTERFACE WITH THE VSAM DATASET   *
001400* ACCESS ROUTINE, AND ARE USED TO COMMUNICATE CHARACTERISTICS    *
001500* FOR A SINGLE VSAM DATASET.                                     *
001600*                                                                *
001700* WITH THE 2 EXCEPTIONS FOR RECORD LENGTH (TO ACCOMODATE         *
001800* VARIABLE LENGTH RECORDS) AND RELATIVE RECORD (TO ACCOMODATE    *
001900* RELATIVE RECORD DATASETS) THESE DATA NAMES MUST BE POPULATED   *
002000* PRIOR TO CALLING THE ROUTINE TO OPEN THE DATASET AND MUST NOT  *
002100* THEN BE CHANGED UNTIL THE DATASET HAS BEEN CLOSED.             *
002200* ************************************************************** *
002300 01  VSIO-FILE-BLOCK.
002400     02  VSIO-DDNAME             PIC  X(08)  VALUE SPACES.
002500     02  VSIO-ORGANIZATION       PIC  X(04)  VALUE SPACES.
002600     02  VSIO-ACCESS             PIC  X(10)  VALUE SPACES.
002700     02  VSIO-MODE               PIC  X(06)  VALUE SPACES.
002800     02  VSIO-RECORD-LENGTH      PIC S9(04)  COMP VALUE +0.
002900     02  VSIO-KEY-ARGUMENT.
003000         03  VSIO-KEY-POSITION   PIC S9(04)  COMP VALUE +0.
003100         03  VSIO-KEY-LENGTH     PIC S9(04)  COMP VALUE +0.
003200     02  VSIO-RELATIVE-RECORD    REDEFINES VSIO-KEY-ARGUMENT
003300                                 PIC S9(08)  COMP.
003400     02  FILLER                  PIC  X(01)  VALUE 'C'.
003500         88  VSIO-FILE-OPEN                  VALUE 'O'.
003600         88  VSIO-FILE-CLOSED                VALUE 'C'.
003700     02  FILLER                  PIC  X(153).
003800* ************************************************************** *
003900*                   END OF VSAMIOFB COPY BOOK                    *
004000* ************************************************************** *

As the comment above the VSIO-FILE-BLOCK group states, with the exception of VSIO-RELATIVE-RECORD, only when processing a relative record dataset, and VSIO-RECORD-LENGTH, only when processing a variable length dataset, these data items must be populated prior to the call to VSAMIO to open the dataset.  They must not be modified while the dataset is open.

This copybook can be copied into the calling COBOL program multiple times, once for each VSAM dataset to be accessed.  In addition to communicating dataset characteristics with VSAMIO, it provides storage for VSAMIO to build and maintain the VSAM Access Control Blocks used to manipulate the dataset while it is open.

The record input/output area(s) for each dataset is coded as separate 01 group item(s) elsewhere in Working-Storage of the calling COBOL program.

Calling the Routine

To illustrate how to use the routine, the COBOL fragments below are taken from the one of the suite of test programs I used as I developed the routine (all of which may be downloaded from this page).  The goal of this particular program is to sequentially load a Key Sequenced dataset.

First, the command and dataset parameter blocks must be initialized and a call made to open the dataset:

005300     MOVE 'KSDSF01' TO VSIO-DDNAME.
005400     MOVE VSIO-KSDS TO VSIO-ORGANIZATION.
005500     MOVE VSIO-SEQUENTIAL TO VSIO-ACCESS.
005600     MOVE VSIO-OUTPUT TO VSIO-MODE.
005700     MOVE +80 TO VSIO-RECORD-LENGTH.
005800     MOVE +0 TO VSIO-KEY-POSITION.
005900     MOVE +10 TO VSIO-KEY-LENGTH.
006000     MOVE VSIO-OPEN TO VSIO-COMMAND.
006100     CALL 'VSAMIO' USING VSIO-PARAMETER-BLOCK, KSDSF01,
006200                         KSDS-RECORD.
006300*    END-CALL.
006400     IF NOT VSIO-SUCCESS
006500         DISPLAY 'VSAMIO ERROR OCCURRED DURING '
006600                 VSIO-COMMAND
006700         EXHIBIT NAMED VSIO-RETURN-CODE,
006800         EXHIBIT NAMED VSIO-VSAM-RETURN-CODE,
006900                       VSIO-VSAM-FUNCTION-CODE,
007000                       VSIO-VSAM-FEEDBACK-CODE
007100         STOP RUN.
007200*    END-IF.

If there are multiple instances of the copybook VSAMIOFB, you will have to qualify references to the dataset parameter fields.  See the sample program KSDSMULT in the source dataset to see how this is handled.

The literal value, KSDSF01, moved into VSIO-DDNAME identifies the name that will be used on the DD statement for the dataset.  

The organization is set to KSDS, the access method is set to SEQUENTIAL, and the access mode is set to OUTPUT, which are requirements for an initial load of an indexed VSAM dataset.

The record length is set to 80.  

The key position is the offset, relative to zero, of the key from the beginning of the data record.  When set to 0, as in this case, the key begins in the first position of the record.  The length of the key field is 10 characters.

Following any call to the routine, the return code fields should be tested to determine the success or failure of the processing of the dataset.  There are four fields used to return information:

  1. VSIO-RETURN-CODE will contain 0 if no error occurred.  If any action performed on a VSAM dataset results in an error, a value - usually 8 - is returned, and will be placed in this field.  Values in the range of 20 through 28, and 9999 are special values indicating conditions signaled by my routine.  The values from 20 through 28 indicate inconsistency or error in the parameters.  The value 9999 is set to indicate end of file was reached performing a sequential read.  If VSIO-RETURN-CODE doesn't contain 0, a value in the range of 20 through 28, or 9999, the following three fields will contain additional information about the error and originates from VSAM.

  2. VSIO-VSAM-RETURN-CODE

  3. VSIO-VSAM-FUNCTION-CODE

  4. VSIO-VSAM-FEEDBACK-CODE will contain the most useful information in the case of an error.  I have supplied some condition names in the copy book for frequently expected code values.

To write a record into the dataset, the record is populated with data and a call is made to the routine with the WRITE command:

012100     MOVE VSIO-WRITE TO VSIO-COMMAND.
012200     CALL 'VSAMIO' USING VSIO-PARAMETER-BLOCK, KSDSF01,
012300                         KSDS-RECORD.
012400*    END-CALL.
012500
012600     IF VSIO-SUCCESS
012700         ADD +1 TO RECORD-COUNTER
012800         GO TO 129-EXIT.
012900*    END-IF.
013000
013100     IF VSIO-LOGIC-ERROR
013200     AND VSIO-NO-MORE-SPACE
013300         DISPLAY 'INSUFFICIENT SPACE DEFINED IN '
013400                 'CLUSTER TO CONTAIN ALL RECORDS - '
013500                 'LOADING TERMINATED'
013600         GO TO 129-EXIT.
013700*    END-IF.
013800
013900     IF VSIO-LOGIC-ERROR
014000     AND VSIO-SEQUENCE-ERROR
014100         DISPLAY 'KEY SEQUENCE ERROR DURING LOAD'
014200         DISPLAY 'RECORD BYPASSED: ' RECORD-IMAGE
014300         MOVE +0 TO VSIO-RETURN-CODE
014400         GO TO 129-EXIT.
014500*    END-IF.
014600
014700     DISPLAY 'VSAMIO ERROR OCCURRED DURING '
014800             VSIO-COMMAND.
014900     EXHIBIT NAMED VSIO-RETURN-CODE.
015000     EXHIBIT NAMED VSIO-VSAM-RETURN-CODE,
015100                   VSIO-VSAM-FUNCTION-CODE,
015200                   VSIO-VSAM-FEEDBACK-CODE.
015300*    END-IF.

As with the OPEN, following the call to write the record, the condition names associated with the return fields are used to handle error conditions that might arise from the WRITE.

008600     MOVE VSIO-CLOSE TO VSIO-COMMAND.
008700     CALL 'VSAMIO' USING VSIO-PARAMETER-BLOCK, KSDSF01,
008800                         KSDS-RECORD.
008900*    END-CALL.
009000     IF NOT VSIO-SUCCESS
009100         DISPLAY 'VSAMIO ERROR OCCURRED DURING '
009200                 VSIO-COMMAND
009300         EXHIBIT NAMED VSIO-RETURN-CODE,
009400         EXHIBIT NAMED VSIO-VSAM-RETURN-CODE,
009500                       VSIO-VSAM-FUNCTION-CODE,
009600                       VSIO-VSAM-FEEDBACK-CODE.
009700*    END-IF.

After processing of the dataset is concluded, the dataset must be closed by calling the routine with the CLOSE command.  And, as with other calls, the return information should be checked to verify a successful close has occurred.  If you fail to close a VSAM dataset prior to the end of the program, you will receive an error on any future access of the dataset until you use the IDCAMS VERIFY function to reset error flags in the catalog entry for the dataset.

Installing the Routine

Everything you need to install the routine is in the archive:  vsioinst.tgz  [MD5: 1BD056C2F271168123BE553A805D333B] which contains a single MVS jobstream in the file VSIOINST.JCL.  Download and uncompress this archive with the command:

tar xvzf vsioinst.tgz 

(on Linux) or use WinZip or ZipNAll on Windows/??.

The VSIOINST.JCL jobstream consists of three steps - 

  • the first step uses IDCAMS to delete the two target Partitioned Datasets which will be created during the final two steps

  • the second step uses IEBUPDTE to place the Assembler source for VSAMIO, the COBOL copy books for the command and dataset parameter interface blocks, and the COBOL source for the test/demonstration programs into a source Partitioned Dataset

  • the third step uses the Assembler to assemble VSAMIO into an object Partitioned Dataset, from which it can then be link-edited with any COBOL programs from which it is called.

The names of the two Partitioned Datasets which will be created and catalogued are currently set in the jobstream as:

SYS2.VSAMIO.SOURCE
SYS2.VSAMIO.OBJECT

You may change these names as you prefer.  You most definitely will need to change the VOL=SER and probably the UNIT= for the two datasets.  They are currently set to UNIT=3380 and VOL=SER=MVS801.

Submit the jobstream to MVS.  You should expect a non-zero return code from the first step, since the datasets being deleted should not exist on your system.  You must receive zero return codes from the second and third steps.  If you do, installation is complete.

If you want to take a look at the assembled VSIOF001 from my system, here is a link to it:  VSAMIO Assembly.

VSAMIO is not reentrant.  Since the MVT COBOL compiler cannot compile dynamic calls, the routine must be statically linked into every load module.  Therefore, I did not make the effort to make it reentrant.

Executing the Test/Example Programs

I have attempted to test the functions in the routine using all possible combinations of organization, access method, and access mode with a series of COBOL programs.  The test programs are very simple, using only DISPLAY statements to convey information about the program execution, as I was mostly interested in the functionality of the Assembler routine.  Along with the creation of version two, I added a couple of more complex COBOL programs, the first to load a variable length indexed dataset and the second which processes four indexed datasets simultaneously.

During the installation process described above, the source for these COBOL programs are added into the source Partitioned Dataset.  You may use them as examples to see how to set up the parameter block for the various combinations of organization, access, and open mode.

If you want to execute the suite of test programs I used, there is an additional archive containing the jobstreams and test data available:  vsiotest.tgz [MD5: B0B7E7BE2DE7DF99DC7EE7091593BA24].  Download and uncompress this archive with the command:

tar xvzf vsiotest.tgz 

(on Linux) or use WinZip or ZipNAll on Windows/??.

Here is a cross-reference of the jobstreams contained in that archive, the COBOL test program they use, and function of the jobstream and/or program:

Jobstream

COBOL Program

Function

VSTEST01.JCL n/a Creates a sequential dataset of 100 instream card images used in subsequent jobstreams.  DSN=SYS2.VSAMTEST.DATA, UNIT=3350, VOL=SER=PUB001
VSTESTE1.JCL n/a Uses IDCAMS to delete and then define an empty Entry Sequenced cluster.  DSN=VSTESTES.CLUSTER, VOL=SER=MVS803, suballocated out of existing space
VSTESTE2.JCL ESDSLOAD Reads images from non-VSAM dataset and writes them into VSAM Entry Sequenced cluster.
VSTESTE3.JCL ESDSREAD Reads images from VSAM Entry Sequenced cluster and displays them on SYSOUT.
VSTESTE4.JCL ESDSUPDT Reads images sequentially from VSAM Entry Sequenced cluster and selectively updates records.
VSTESTE5.JCL ESDSADDT Reads images from SYSIN and appends to VSAM Entry Sequenced cluster.
VSTESTR1.JCL n/a Uses IDCAMS to delete and then define an empty Numbered cluster.  DSN=VSTESTRR.CLUSTER, VOL=SER=MVS803, suballocated out of existing space
VSTESTR2.JCL RRDSLODS Reads images from non-VSAM dataset and writes them into VSAM Numbered cluster, generating sequential relative record numbers ranging from 1 through 100.
VSTESTR3.JCL RRDSREAD Reads images from VSAM Numbered cluster and displays them on SYSOUT.
VSTESTR4.JCL RRDSLODR Reads images from non-VSAM dataset and writes them into VSAM Numbered cluster, deriving relative record number from portion of data record, leaving embedded empty record slots.  (Note, you will need to rerun VSTESTR1.JCL prior to this job if you have already run VSTESTR2.JCL.)
VSTESTR5.JCL RRDSUPDT Reads images sequentially from VSAM Numbered cluster and selectively updates and deletes records.
VSTESTR6.JCL RRDSRAND Randomly updates VSAM Numbered cluster - adds, updates, and deletes images, using data from SYSIN.
VSTESTR7.JCL RRDSSSEQ Issues START against VSAM Numbered cluster, using both Key Equal and Key Greater Than or Equal options, then reads sequentially forward from started position.
VSTESTK1.JCL n/a Uses IDCAMS to delete and then define an empty Indexed cluster.  DSN=VSTESTKS.CLUSTER, VOL=SER=MVS803, suballocated out of existing space
VSTESTK2.JCL KSDSLOAD Reads images from non-VSAM dataset and writes them into VSAM Indexed cluster.
VSTESTK3.JCL KSDSREAD Reads images from VSAM Indexed cluster and displays them on SYSOUT.
VSTESTK4.JCL KSDSUPDT Reads images sequentially from VSAM Indexed cluster and selectively updates and deletes records.
VSTESTK5.JCL KSDSRAND Randomly updates VSAM Indexed cluster - adds, updates, and deletes images, using data from SYSIN.
VSTESTK6.JCL KSDSSSEQ Issues START against VSAM Indexed cluster, using both Key Equal and Key Greater Than or Equal options, then reads sequentially forward from started position.
LISTCATE.JCL n/a Uses IDCAMS to list catalog entry for Entry Sequenced cluster: VSTESTES.CLUSTER.
LISTCATR.JCL n/a Uses IDCAMS to list catalog entry for Numbered cluster: VSTESTRR.CLUSTER.
LISTCATK.JCL n/a Uses IDCAMS to list catalog entry for Indexed cluster: VSTESTKS.CLUSTER.
PRINTE.JCL n/a Uses IDCAMS to print contents for Entry Sequenced cluster:  VSTESTES.CLUSTER.
PRINTR.JCL n/a Uses IDCAMS to print contents for Numbered cluster:  VSTESTRR.CLUSTER.
PRINTK.JCL n/a Uses IDCAMS to print contents for Indexed cluster:  VSTESTKS.CLUSTER.
VSTEST02.JCL KSDSLVAR Reads card images from SYSIN and loads a variable length, indexed cluster: VSTESTK1.CLUSTER.  This dataset is required by KSDSMULT described below.
VSTEST03.JCL KSDSMULT Sequentially reads a variable length, indexed cluster - VSTESTK1.CLUSTER - and randomly reads corresponding records from three fixed length indexed clusters - VSTESTK2.CLUSTER, VSTESTK3.CLUSTER, VSTESTK4.CLUSTER - to produce a report.
VSTEST99.JCL n/a Uses IDCAMS to delete all test datasets (Non-VSAM and VSAM) created in this test suite.

Prior to executing the jobstreams, verify that the UNIT= and VOL=SER= entries will match DASD allocations in your MVS 3.8j environment.  The jobstreams executing COBOL programs use a compile, link-edit, and execute procedure, so the COBOL compiler must be installed on your system.

A Note About Reading Variable Length Datasets

Prior to issuing a READ command against a variable length dataset, the record length - VSIO-RECORD-LENGTH - should be set to the length of the largest possible record and the record area provided should be large enough to accommodate a record of this size.  After the read, VSIO-RECORD-LENGTH will contain the length of the record read into the record area.


If you need to open an newly defined (empty) cluster as Input-Output and then add (Write) records to it, you will need to prime the cluster first.  Look at Prime VSAM Cluster on my miscellaneous programs page.


If you are interested in writing COBOL programs that utilize VSAM datasets, I hope this documentation has provided you with the information you need to install my routine and get started writing programs on your own.  If I can answer any questions about installing and/or using the routine, or if you find errors in these instructions, please don't hesitate to send them to me:



This page was last updated on November 12, 2010.