Revised May, 2020: Following the revision of my MVS 3.8j installation instructions/tutorial, I received some feedback that the instructions for installing the VSAM file access routines for COBOL and PL/1 were hard to follow and/or there were portions that simply did not work as described. When I created the SYSCPK volume, containing the various language compilers and other tools, I included the VSAM I/O routines, both COBOL and PL/1, in SYSC.LINKLIB, as well as the source code in their own libraries. Therefore, following these instructions became redundant. All that is required is that you download the SYSCPK volume and integrate it into your MVS 3.8j installation. If you have followed my MVS 3.8j installation instructions (revision done in April, 2020), SYSCPK is already integrated into your system. You may run the test/example programs from the datasets on SYSCPK: SYSC.VSAMIO.SOURCE and SYSC.VSAMIOP.SOURCE. To compile programs you write using the VSAM I/O routines, include SYSC.VSAMIO.SOURCE in the SYSLIB DD for MVT COBOL compiles or SYSC.VSAMIOP.MACLIB in the SYSLIB DD for MVT PL/1 compiles, and include SYSC.LINKLIB concatenated to the SYSLIB DD for the Link Editor. I have modified these instructions to remove steps referencing installation of the VSAM I/O routines themselves, as they are already installed on SYSCPK. I have also added output listings for the various test/example programs below.
Revised 7 July 2020: John James wrote to inform me he had found an error that has been in the VSAMIOFB definition since 2001 when this was originally coded. In the area immediately following the fields that define the characteristics of the VSAM object, there is a FILLER. In this area the VSAMIO assembler code builds the access control blocks required to manipulate the object (open, close, read, start, write, rewrite). As originally distributed, I had defined this FILLER as 153 bytes, but the area used by the access control blocks is actually 161 bytes. As long as the programs written using the VSAMIO routine were coded exactly as I have them coded there was no problem, but if you moved the placement of the block of storage around, as JJ did, you can encounter S0C1 and/or S0C4 abends. I have corrected the copy members and reassembled the program, although it was not actually necessary to reassemble VSAMIO as the fault was in the copy libraries used in COBOL programs calling VSAMIO.
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.
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.
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:
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:
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.
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:
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:
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.
VSIO-VSAM-RETURN-CODE
VSIO-VSAM-FUNCTION-CODE
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:
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.
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.
Everything required to use the VSAM I/O routine with MVT COBOL programs is already installed on the SYSCPK volume.
The dataset SYSC.VSAMIO.SOURCE contains:
the assembler source for the routine,
the JCL to assemble the source - which is not required to be run as the routine is already assembled into SYSC.LINKLIB,
2 COBOL copybooks for the interface blocks that are used to facilitate communication between MVT COBOL programs and the assembler routine,
17 test/example COBOL programs,
22 jobstreams of JCL to execute the test/example programs, as well as create and delete the test data,
6 jobstreams that use IDCAMS to display information about or print the test datasets.
The VSAM I/O routine - VSAMIO - is already assembled and linked into SYSC.LINKLIB.
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.
The source for these COBOL programs, as well as the jobstreams to create test datasets, execute the COBOL example programs, and delete the test datasets, are installed in SYSC.VSAMIO.SOURCE. 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.
Here is a cross-reference of the jobstreams, the COBOL test program they execute, the function of the jobstream and/or program, and, for the actual COBOL programs, a PDF of the expected output:
Jobstream
COBOL Program
Function
View Expected Output
VSTEST01.JCL n/a Creates a sequential dataset of 100 instream card images used in subsequent jobstreams. DSN=PUB001.VSAMTEST.DATA, UNIT=SYSDA, VOL=SER=PUB001 vstest01.pdf VSTESTE1.JCL n/a Uses IDCAMS to delete and then define an empty Entry Sequenced cluster. DSN=PUB001.VSTESTES.CLUSTER, VOL=SER=PUB001, suballocated out of existing space vsteste1.pdf VSTESTE2.JCL ESDSLOAD Reads card images from non-VSAM dataset and writes them into VSAM Entry Sequenced cluster. vsteste2.pdf VSTESTE3.JCL ESDSREAD Reads records sequentially from VSAM Entry Sequenced cluster and displays them on SYSOUT. vsteste3.pdf VSTESTE4.JCL ESDSUPDT Reads records sequentially from VSAM Entry Sequenced cluster and selectively updates records. vsteste4.pdf VSTESTE5.JCL ESDSADDT Reads card images from SYSIN and appends to VSAM Entry Sequenced cluster. vsteste5.pdf VSTESTR1.JCL n/a Uses IDCAMS to delete and then define an empty Numbered cluster. DSN=PUB001.VSTESTRR.CLUSTER, VOL=SER=PUB001, suballocated out of existing space vstestr1.pdf 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. vstestr2.pdf VSTESTR3.JCL RRDSREAD Reads images from VSAM Numbered cluster and displays them on SYSOUT. vstestr3.pdf 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 must rerun VSTESTR1.JCL prior to this job if you have already run VSTESTR2.JCL.) Run VSTESTR3 again to see that slots have been left empty. vstestr1.pdf VSTESTR5.JCL RRDSUPDT Reads images sequentially from VSAM Numbered cluster and selectively updates and deletes records. vstestr5.pdf VSTESTR6.JCL RRDSRAND Randomly updates VSAM Numbered cluster - adds, updates, and deletes images, using data from SYSIN. vstestr6.pdf 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. vstestr7.pdf VSTESTK1.JCL n/a Uses IDCAMS to delete and then define an empty Indexed cluster. DSN=PUB001.VSTESTKS.CLUSTER, VOL=SER=PUB001, suballocated out of existing space vstestk1.pdf VSTESTK2.JCL KSDSLOAD Reads card images from non-VSAM dataset and writes them into VSAM Indexed cluster. vstestk2.pdf VSTESTK3.JCL KSDSREAD Reads records from VSAM Indexed cluster and displays them on SYSOUT. vstestk3.pdf VSTESTK4.JCL KSDSUPDT Reads records sequentially from VSAM Indexed cluster and selectively updates and deletes records. vstestk4.pdf VSTESTK5.JCL KSDSRAND Randomly updates records from a VSAM Indexed cluster - adds, updates, and deletes images, using data from SYSIN. vstestk5.pdf 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. vstestk6.pdf 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: PUB001.VSTESTK1.CLUSTER. This dataset is required by KSDSMULT described below. vstest02.pdf VSTEST03.JCL KSDSMULT Sequentially reads a variable length, indexed cluster - PUB001.VSTESTK1.CLUSTER - and randomly reads corresponding records from three fixed length indexed clusters - PUB001.VSTESTK2.CLUSTER, PUB001.VSTESTK3.CLUSTER, PUB001.VSTESTK4.CLUSTER - to produce a report. vstest03.pdf VSTEST99.JCL n/a Uses IDCAMS to delete all test datasets (Non-VSAM and VSAM) created in this test suite. vstest99.pdf
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. The test/example programs, with the exception of KSDSMULT, do the bare minimum of producing output. Following any of the jobs that update/modify the VSAM datasets, you can always run the jobstream that sequentially reads/displays the records from the VSAM dataset you are updating/modifying.
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.