ISAM / VSAM Interface

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.

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.

Implementing the ISAM Interface

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 you 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 hte processing program can issue (STRNO)

• the name of an ISAM user exit routine to analyze physical and logical errors (SYNAD).

AMP Subparameter Definition

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 ofr 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=IL

Indicates 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=VB

Identifies 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.

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: