The advent of getting MVS 3.8 installed and usable under Hercules has a good news/bad news aspect if you want to write some useful application programs using key-sequenced datasets in anything other than Assembler. The good news is that VSAM (Virtual Storage Access Method) is present and fully functional in the base system. The bad news is that the compilers that we have available for the higher level languages (specifically COBOL, PL/1, and RPG), don't know anything about describing and using VSAM files. However, the ISAM interface is also present and functional on MVS 3.8 and that is how we can overcome this limitation, albeit with some minor limitations.
Subsequent to producing this page on my site, I wrote the VSAM Interface routines for the MVT COBOL and PL/I compilers. So I am adding this note here to make sure that those who are contemplating using the ISAM/VSAM interface will be aware of another option. You can read about, and download, the routines from VSAM File Access for COBOL and VSAM File Access for PL/I.
Update 12/23/2021: I have added another page that demonstrates using COBOL programs (that may be compiled with the MVT COBOL compiler) to load, update, and access indexed datasets: 1) maintained in a native ISAM dataset, 2) maintained in VSAM cluster via the ISAM/VSAM Interface Program, 3) maintained in VSAM, using my VSAMIO subprogram. That page is located at COBOL Programs with ISAM and VSAM Datasets.
The ISAM interface allows a properly written and debugged program that processes an indexed sequential data set to process a key-sequenced VSAM dataset (KSDS) transparently. The KSDS can have been converted from an indexed-sequential or a sequential dataset (or another KSDS) or can be loaded by one of your own programs. The loading program can be coded with VSAM macros, ISAM macros, PL/1 statements, COBOL statements, or RPG statements. That is, you can load records into a newly defined key-sequenced data set with a program that was coded to load records into an indexed sequential dataset.
When a processing program that uses ISAM (assembler-language macros, PL/1, COBOL, or RPG) issues an OPEN to open a key-sequenced data set, the ISAM interface is given control to:
construct control blocks that are required by VSAM
load the appropriate ISAM interface routines into virtual storage
initialize the ISAM DCB to enable the interface to intercept ISAM requests
take the DCB user exit requested by the processing program.
The ISAM interface intercepts each subsequent ISAM request, analyzes it to determine the equivalent keyed VSAM request, defines the keyed VSAM request in a request parameter list, and initiates the request.
The ISAM interface receives return codes and exception codes for logical and physical errors from VSAM, translates them to ISAM codes and routes them to the processing program or error-analysis (SYNAD) routine through the ISAM DCB or DECB.
To execute your ISAM processing program to process a key-sequenced dataset, replace the ISAM DD card with a VSAM DD card using the ddname that was used for the ISAM dataset. The VSAM DD card names the key-sequenced dataset and gives any necessary VSAM parameters (through the AMP parameter). Specify DISP=MOD for resume loading and DISP=OLD or SHR for all other processing (be wary of SHR as there are significant limitations on the protections against simultaneous updates of VSAM data accessed through the ISAM interface).
You do not have to specify anything about the ISAM interface itself. The interface is automatically brought into action when your processing program opens a DCB whose associated DD statement describes a key-sequenced dataset (instead of an indexed sequential dataset). If you have defined your VSAM dataset in a user catalog, specify the user catalog in a JOBCAT or STEPCAT DD statement.
The DCB parameter in the DD statement that identifies a VSAM dataset is invalid and must be removed. If the DCB parameter is not removed, unpredictable results can occur. Certain DCB-type information can be safely specified in the AMP parameter.
When an ISAM processing program is run with the ISAM interface, the AMP parameter allows you to specify:
that a VSAM dataset is to be processed (AMORG)
the need for additional data buffers to improve sequential performance (BUFND)
the need for extra index buffers for simulating the residency of the highest level(s) of an index in virtual storage (BUFNI)
whether to remove records flagged (OPTCD)
what record format (RECFM) is used by the processing program
the number of concurrent BISAM and QISAM (basic and queued indexed-sequential access methods) requests that the processing program can issue (STRNO)
the name of an ISAM user exit routine to analyze physical and logical errors (SYNAD).
AMORG (required)
Indicates that the DD statement defines a VSAM dataset and is required for the following reasons:
When dataset access is through the ISAM interface program and the DD statement contains VOLUME and UNIT parameters or contains a DUMMY parameter.
To open an ACB for a VSAM dataset, if the dataset is not fully defined at the beginning of the job step
BUFND=number
Specifies the number of I/O buffers that VSAM is to use for data records. The minimum is 1 plus the STRNO subparameter number. This value overrides the BUFND value specified in the ACB or GENCB macro, or provides a value if one is not specified. If you omit STRNO, BUFND must be at least 2.
If you omit BUFND from AMP and from the ACB macro instruction, the system uses the STRNO number plus 1.
BUFNI=number
Specifies the number of I/O buffers that VSAM is to use for index records. This value overrides the BUFNI value specified in the ACB or GENCB macro, or provides a value if one is not specified. If you omit BUFNI from AMP and from the ACB macro instruction, VSAM uses as many index buffers as the STRNO subparameter number. If you omit both BUFNI and STRNO, VSAM uses 1 index buffer.
If data access is through the ISAM interface program, specify for the BUFNI number 1 more than the STRNO number, or specify 2 if you omit STRNO, to simulate having the highest level of an ISAM index resident. Specify a BUFNI number 2 or more greater than the STRNO number to simulate having intermediate levels of the index resident.
BUFSP=number
Specifies the maximum number of bytes for the data and index buffers in the user area. This value overrides the BUFSP value specified in the ACB or GENCB macro, or provides a value if one is not specified.
If BUFSP specifies fewer bytes than the BUFFERSPACE parameter of the access method services DEFINE command, the BUFFERSPACE number overrides the BUFSP number.
OPTCD=I
OPTCD=L
OPTCD=ILIndicates how the ISAM interface program is to process records that the step's processing program flags for deletion.
I requests, when the data control block (DCB) contains OPTCD=L, that the ISAM interface program is not to write into the dataset records marked for deletion by the processing program.
If AMP=('OPTCD=I') is specified without OPTCD=L in the DCB, the system ignores deletion flags on records.
L requests that the ISAM interface program is to keep in the dataset records marked for deletion by the processing program.
If records marked for deletion are to be kept but OPTCD=L is not in the DCB, AMP=('OPTCD=L') is required.
Note: This parameter has the same meaning and restrictions for the ISAM interface as it has for ISAM. While it was not requred in the ISAM job control language, you should code it in the AMP parameter.
IL requests that the ISAM interface program is not to write into the dataset records marked for deletion by the processing progarm. If the processing program had read the record for update, the ISAM interface program deletes the record from the dataset.
AMP=('OPTCD=IL') has the same effect as AMP=('OPTCD=I') coded with the OPTCD=L in the DCB.
RECFM=F
RECFM=FB
RECFM=V
RECFM=VBIdentifies the ISAM record format used by the processing program. You must code this RECFM subparameter when the record format is not specified in the DCB.
Note: This parameter has the same meaning and restrictions for the ISAM interface as it has for ISAM. While it was not required in the ISAM job control language, you should code it in the AMP parameter.
All VSAM requests are for unblocked records. If the processing program requests blocked records, the ISAM interface program sets the overflow-record indicator for each record to indicate that each is being passed to the program unblocked.
F indicates fixed-length records.
FB indicates blocked fixed-length records.
V indicates variable-length records.
VB indicates blocked variable-length records.If no RECFM is specified in the AMP parameter or in the DCB, V is the default.
STRNO=number
Indicates the number of request parameter lists the processing program uses concurrently. The number must at least equal the number of BISAM and QISAM requests that the program can issue concurrently. If the program creates subtasks, add together the number of requests for each subtask plus 1 for each subtask that sequentially processes the dataset. This value overrides the STRNO value specified in the ACB or GENCB macro, or provides a value if one is not specified.
SYNAD=module
Names a SYNAD exit routine. The ISAM interface program is to load and exit to this routine if a physical or logical error occurs when the processing program is gaining access to the dataset.
The SYNAD parameter overrides a SYNAD exit routine specified in the EXLST or GENCB macro instruction that generates the exit list. The address of the intended exit list is specified in the access method control block that links this DD statement to the processing program. If no SYNAD exit is specified, the system ignores the AMP SYNAD parameter.
Update 31 December 2020: I had not made changes to this page for almost two decades, but recent discussions on the Hercules MVS forum about ISAM and MVS 3.8j came to my attention and I realized I should probably put a simple example here to illustrate what I had written (above) a long time ago.
The COBOL programs, jobstreams (JCL), and a Hercules Emulated Tape image with the sample dataset are available for download from my website at iipdemo.tar.gz [5 kB, MD5: 0e95a26fe80de7dbb690cd048a78e47a].
The sample dataset is fifty records containing data for hypothetical students. The dataset on the tape has been sorted to be in ascending sequence on the student identification field. Data to be loaded into an ISAM or VSAM keyed dataset must be in ascending sequence on the key field or an error will be reported and the out-of-sequence record will not be written.
There are two simple COBOL programs. The first program simply copies the fields from the record read from the input tape record to the ISAM data record and writes the record. There should be no output from this program, because there are no errors expected. The second program reads the records sequentially from the loaded dataset and displays four fields from each record on SYSOUT.
There are three jobstreams.
The defclusk.jcl jobstream defines the VSAM cluster that will hold the records loaded. The high level qualifier of the dataset will need to be changed for your system, and perhaps the DASD volume on which to create the cluster if you do not have a PUB000 volume on your system. The cluster is defined UNIQUE, so it will be allocated out of non-VSAM space on the volume. The program PRIMEVS is used to initialize the cluster and is located in SYSC.LINKLIB on the SYSCPK volume. The output from this job may be viewed at defclusk.pdf.
The cobclg jobstream compiles, link-edits, and executes the first COBOL program to load the sample data from the tape. The output from this job may be viewed at cobclg.pdf. The JCL listed in this output differs slightly from the cobclg jobstream, as I have inserted the COBOL source inline to simplify sharing the supplied job/program.
The cobclg2 jobstream compiles, link-edits, and executes the second COBOL program to list four fields from each record in the dataset loaded by the first program and also uses IDCAMS to dump the first ten records from the dataset. The output from this job may be viewed at cobclg2.pdf. The JCL listed in this output differs slightly from the cobclg jobstream, as I have inserted the COBOL source inline to simplify sharing the supplied job/program.
This is an extremely simplified example, but illustrates most of the concepts necessary to utilize the ISAM Interface Program.
The ISAM/VSAM Interface will work with PL/I programs, and RPG programs as well; it should even work with Assembler programs. The ISAM Interface Program is managed by MVS 'under the covers' and is invoked when a DD statement is processed linking a DCB that defines the dataset to be accessed as ISAM (on the application program side) to a VSAM cluster. There is nothing special to be done in the application program code, simply code as you would for ISAM and when the OPEN code is executed the ISAM Interface Program will be loaded to handle all subsequent requests to/from the dataset (which is a VSAM dataset).
To provide an example of an RPG program, I grabbed a program from my RPG Tutorial pages and modified it to print fields from the dataset loaded by the COBOL program above. The output from the job may be viewed at rpgisam.pdf.
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: