December, 2021
Recently I have been fielding some questions on using COBOL programs to create and access ISAM datasets, so I put together this page to give some examples. As I reviewed my site to determine where I would link this page in, I saw that I have covered some of this material before, but everything I have done below is new work, so even if it seems similar to other content on my site, it is all new material, written in December, 2021.
Both the text, and example programs, are organized into three task groups:
The goal in the first task group is to load, update, access, and reorganize a dataset that is native ISAM.
The goal in the second task group is to move the actual dataset storage into VSAM and utilize the same compiled programs from the first group to load, update, access, and reorganize the dataset using the ISAM Interface Program.
The goal in the third task group is to modify (upgrade perhaps is a better word to use here) the design of the COBOL programs to utilize my VSAM for COBOL subroutine to load, update, access, and reorganize a VSAM cluster. The basic function of the COBOL programs are not changed, the only changes made are those required to implement I/O through the VSAMIO routine rather than using the MVT COBOL ISAM access.
The COBOL source, jobstreams, and test data are available for download from my site at: isam_vsam_cobol.tar.gz (160 kB MD5: 9a3675c87d93f3a972478d3181b4ff5a). This archive contains a jobstream that will use PDSLOAD to create and load a partitioned dataset with the COBOL source programs and jobstreams to compile and execute the programs. The archive also contains a tape image with required test data. You will probably need to edit the PDSLOAD jobstream, as well as the jobstreams that will be reloaded, to customize DASD volume serial numbers and dataset names to conform to your system. The list of members loaded to the partitioned dataset is:
$INDEX - This member ISLOAD - COBOL source to load native ISAM dataset ISREPT1 - COBOL source to read ISAM dataset (primary key) and report ISREPT2 - COBOL source to read ISAM dataset (primary key) and report ISUPDT - COBOL source to process random updates to ISAM dataset JCOBUCL1 - JCL to compile ISLOAD+SORTNAME into ISLOAD load module JCOBUCL2 - JCL to compile ISREPT1 into ISREPT1 load module JCOBUCL3 - JCL to compile ISREPT2 into ISREPT2 load module JCOBUCL4 - JCL to compile ISUPDT+SORTNAME+Y2KGTOA into ISUPDT load module JCOBUCL5 - JCL to compile VSLOAD+SORTNAME+VSAMIO into VSLOAD load module JCOBUCL6 - JCL to compile VSREPT+VSAMIO into VSREPT load module JCOBUCL7 - JCL to compile VSUPDT+SORTNAME+Y2KGTOA+VSAMIO into VSUPDT load module JIEBISL - JCL to reload ISAM dataset from backup, purging deleted recs JIEBISL2 - JCL to reload ISAM dataset from backup, purging deleted recs (IVI) JIEBISU - JCL to unload ISAM dataset to a sequential backup dataset JIEBISU2 - JCL to unload ISAM dataset to a sequential backup dataset (IVI) JISLOAD1 - JCL to execute ISLOAD to load native ISAM dataset JISLOAD2 - JCL to execute ISLOAD to load ISAM dataset (IVI) JISREPT1 - JCL to execute ISREPT1 to print primary key report (native) JISREPT2 - JCL to execute ISREPT2 to print alternate key report (native) JISREPT3 - JCL to execute ISREPT1 to print primary key report (IVI) JISREPT4 - JCL to execute ISREPT2 to print alternate key report (IVI) JISUPDT1 - JCL to execute ISUPDT to update ISAM dataset (native) JISUPDT2 - JCL to execute ISUPDT to update ISAM dataset (IVI) JVSLOAD - JCL to execute VSLOAD to load VSAM dataset JVSRELOD - JCL to delete and redefine VSAM dataset, then rebuild contents from sequential dataset backup JVSREPT1 - JCL to execute VSREPT to print primary key report JVSREPT2 - JCL to execute VSREPT to print alternate key report JVSUNLOD - JCL to copy VSAM dataset to backup sequential dataset JVSUPDT - JCL to execute VSUPDT to update VSAM dataset SORTNAME - COBOL source for subroutine to create sort name field VSLOAD - COBOL source to load VSAM dataset VSREPT - COBOL source to read VSAM dataset and report VSUPDT - COBOL source to process random updates to VSAM dataset
It will be necessary to have my VSAMIO and Y2K (date) routines available to compile the programs that call these routines. If you have SYSCPK installed in your system, those are already in place and ready to use.
The goals for each task group are identical:
Load data records from a sequential dataset (supplied on a Hercules emulated tape [HET] image) into an indexed dataset; the key is a unique numeric identification field contained in each sequential record.
Retrieve data records from the indexed dataset in primary key order and produce a simple report. Since the goal of these tasks is not the report, minimal effort is placed into report design.
Retrieve data records from the indexed dataset in a secondary key order and produce a simple report.
Retrieve data records from the indexed dataset randomly and apply updates (additions, changes, deletions) using updates read from an instream card image dataset.
Unload data records from the indexed dataset, then delete and reload the indexed dataset removing any records flagged for deletion (x'255' in position 1 of the record).
Load data records from the sequential dataset into an indexed dataset
The COBOL source program ISLOAD was written to read a sequential dataset on tape and load the records into an ISAM dataset. A secondary COBOL source program, SORTNAME, is called for each data record to build a field which can be considered an alternate key, which consists of the last name, first name, and middle initial from each data record. The JCL to compile these programs is JCOBUCL1 and the output listing from the job may be viewed at jcobucl1.pdf. The JCL to execute the program and load the indexed dataset is JISLOAD1 and the output listing from the job may be viewed at jloadis1.pdf.
Retrieve data records from the indexed dataset and produce a report in primary key sequence
The COBOL source program ISREPT1 was written to read the data records from the ISAM dataset sequentially, in primary key order, and produce a simple report of each record's contents. The JCL to compile this program is JCOBUCL2 and the output listing from the job may be viewed at jcobucl2.pdf. The JCL to execute the program and print the report is JISREPT1 and the output listing from the job may be viewed at jrepis1.pdf.
Retrieve data records from the indexed dataset and produce a report in an alternate sequence
There is no direct method to retrieve records from an ISAM dataset in an alternate order, but to have comparable capability with the VSAM dataset in Task Group #3, I wrote this COBOL program that produces a similar report using the MVT Sort/Merge program called from within COBOL. The COBOL source program is ISREPT2. The JCL to compile this program is JCOBUCL3 and the output listing from the job may be viewed at jcobucl3.pdf. The JCL to execute the program and print the report is JISREPT2 and the output listing from the job may be viewed at jrepis2.pdf.
Retrieve data records from the indexed dataset randomly and apply updates
The COBOL source program ISUPDT was written to process an update dataset sequentially, retrieve affected records from the ISAM dataset randomly, update the records, and rewrite them. The JCL to compile this program is JCOBUCL4 and the output listing from the job may be viewed at jcobucl4.pdf. The JCL to execute the program is JISUPDT1 and the output listing from the job may be viewed at jupdtis1.pdf. It is possible to relist all of the data records from the ISAM dataset following the update using either of the previous two jobstreams (JISREPT1 and JISREPT2).
Unload data records from the indexed dataset, then delete and reload the indexed dataset removing records flagged for deletion
The IBM utility program IEBISAM is used to unload and reload ISAM datasets. Records flagged for deletion - x'255' in the first byte of the data record - will not be processed by IEBISAM. In fact, once you have rewritten a record in an ISAM dataset with x'255' in the first character, it will not be read back in when the ISAM dataset is being processed sequentially. The JCL to execute IEBISAM to unload the dataset, creating a sequential backup copy of the records is JIEBISU and the output listing from the job may be viewed at jiebisamu.pdf. The JCL to delete the ISAM dataset and reload it from the sequential backup dataset is JIEBISL and the output listing from the job may be viewed at jiebisaml.pdf.
Load data records from the sequential dataset into an indexed dataset
The same COBOL source program ISLOAD, from task group #1, will be used. It is not necessary to recompile or relink the program. A VSAM Key-Sequenced Cluster will be defined to hold the dataset. The JCL to define the VSAM Cluster, then execute the program and load the indexed dataset is JISLOAD2 and the output listing from the job may be viewed at jloadis2.pdf.
Retrieve data records from the indexed dataset and produce a report in primary key sequence
The same COBOL source program ISREPT1, from task group #1, will be used. It is not necessary to recompile or relink the program. The JCL to execute the program and print the report is JISREPT3 and the output listing from the job may be viewed at jrepis3.pdf.
Retrieve data records from the indexed dataset and produce a report in an alternate sequence
Since we are still accessing the VSAM Cluster through ISAM logic, there is still no direct method to retrieve records from an ISAM dataset in an alternate order, but the same COBOL source program ISREPT2, from task group #1, will be used to produce a report in the alternate key sequence. It is not necessary to recompile or relink the program. The JCL to execute the program and print the report is JISREPT4 and the output listing from the job may be viewed at jrepis4.pdf.
Unload data records from the indexed dataset, then delete and reload the indexed dataset removing records flagged for deletion
The IBM utility program IEBISAM is used to unload and reload ISAM datasets, even if they are defined in VSAM and accessed via the ISAM Interface Program. Records flagged for deletion - x'255' in the first byte of the data record - will not be processed by IEBISAM. In fact, once you have rewritten a record in an ISAM dataset with x'255' in the first character, it will not be read back in when the ISAM dataset is being processed sequentially. The JCL to execute IEBISAM to unload the dataset, creating a sequential backup copy of the records is JIEBISU2 and the output listing from the job may be viewed at iebismu2.pdf. The JCL to delete and redefine the VSAM Cluster that will hold the dataset, and then reload it from the sequential backup dataset is JIEBISL2 and the output listing from the job may be viewed at iebisml2.pdf.
Load data records from the sequential dataset into an indexed dataset
The COBOL source program VSLOAD was written to read a sequential dataset on tape and load the records into a VSAM dataset. Since the MVT COBOL compiler lacks the capability to access VSAM datasets, my VSAMIO subroutine is used to provide that functionality. A secondary COBOL source program, SORTNAME, is called for each data record to build a field which can be considered an alternate key, which consists of the last name, first name, and middle initial from each data record. The JCL to compile these programs is JCOBUCL5 and the output listing from the job may be viewed at jcobucl5.pdf. The JCL to define the VSAM KSDS Cluster, execute the program and load the indexed dataset, and then build an Alternate Index set for the KSDS Cluster is JVSLOAD and the output listing from the job may be viewed at jloadvs.pdf.
Retrieve data records from the indexed dataset and produce a report in primary key sequence
The COBOL source program VSREPT was written to read the data records from the VSAM dataset sequentially and produce a simple report of each record's contents. Since the MVT COBOL compiler lacks the capability to access VSAM datasets, my VSAMIO subroutine is used to provide that functionality. The JCL to compile this program is JCOBUCL6 and the output listing from the job may be viewed at jcobucl6.pdf. The JCL to execute the program and print the report is JVSREPT1 and the output listing from the job may be viewed at jrepvs1.pdf.
Retrieve data records from the indexed dataset and produce a report in an alternate sequence
This is the first major divergence in the capabilities of VSAM over ISAM. Where ISAM has no direct means to maintain an alternate key for an indexed dataset, VSAM can have any number of alternate indexes for any VSAM dataset. Where in the ISAM solution it was necessary to write a second program to utilize the Sort/Merge utility to produce a report in alternate key sequence, in VSAM the same report program is utilized and it is simply a matter of using the DD for the Alternate Index Path to access the data records in the alternate sequence. The JCL to execute the program and print the report is JVSREPT2 and the output listing from the job may be viewed at jrepvs2.pdf.
Retrieve data records from the indexed dataset randomly and apply updates
The COBOL source program VSUPDT was written to process an update dataset sequentially, retrieve affected records from the VSAM dataset randomly, update the records, and rewrite them. Since the MVT COBOL compiler lacks the capability to access VSAM datasets, my VSAMIO subroutine is used to provide that functionality. The JCL to compile this program is JCOBUCL7 and the output listing from the job may be viewed at jcobucl7.pdf. The JCL to execute the program is JVSUPDT and the output listing from the job may be viewed at jupdtvs.pdf. It is possible to relist all of the data records from the VSAM dataset following the update using either of the previous two jobstreams (JVSREPT1 and JVSREPT2). Again here, you should note that where with an ISAM dataset records to be deleted are flagged as deleted in the dataset by writing x'255' in the first byte, but with a VSAM dataset, deleted records are physically removed from the dataset.
Unload data records from the indexed dataset, then delete and reload the indexed dataset
The final major difference between ISAM datasets and VSAM datasets is both the necessity and means of reorganizing the datasets. ISAM datasets require more frequent reorganization if there is heavy maintenance on the dataset that involves the addition of records or flagging records for deletion. In ISAM, when records are added, some records are moved into an overflow area to make room for additions. As more records are pushed into the overflow, access time increases. With VSAM there is also some splitting of physical blocks of records, but the impact on application programs accessing the dataset is less severe than with ISAM. And of course, deletions in a VSAM file take place immediately, completely removing the deleted records from the dataset. The IBM VSAM utility program IDCAMS is used to both unload the records from the VSAM dataset, creating a portable backup sequential dataset; and then is used again to delete, redefine the empty KSDS Cluster, reload the data from the sequential backup, and finally to rebuild the Alternate Index and Path. The JCL to execute IDCAMS to unload the dataset, creating a sequential backup copy of the records is JVSUNLOD and the output listing from the job may be viewed at jvsunlod.pdf. The JCL to delete the VSAM KSDS Cluster, reload it from the sequential backup dataset, and rebuild the Alternate Index is JVSRELOD and the output listing from the job may be viewed at jvsrelod.pdf.
September, 2022 For an example of how to build Alternate Indexes for an ESDS Cluster and then access them with VSAMIO, see: Alternate Indexes over ESDS Clusters
I hope that you have found my instructions useful. If you have questions that I can answer to help expand upon my explanations and examples shown here, please don't hesitate to send them to me: