VSAM File Access for PL/1

I had already been working my way through a PL/1 textbook for a while when I decided to write my VSAMIO routine to allow programs compiled with the MVT COBOL compiler to access VSAM datasets.  It was a natural progression to want to have access to VSAM datasets from PL/1 programs as well.  I wanted to be able to use the same program, but there was a problem to overcome.  PL/1 passes character and structure variables by constructing a descriptor block for the variable; then the address of that descriptor block is passed to the called program instead of the address of the actual variable.  This PL/1 compiler is so antiquated that it doesn't recognize any options that would override this behavior so that the called program would receive the raw variable address.

I decided that the simplest solution was to write an intermediary program that would extract the addresses of the actual variables needed by VSAMIO, call VSAMIO using those addresses as parameters, and then return control to the PL/1 caller.  The instructions on this page are for installing the intermediary program, the PL/1 "copybooks", and the sample PL/1 programs.  You will need to have already installed the VSAMIO program as a prerequisite.  If you haven't already install the base VSAMIO, here is what you will need to do to accomplish that:

• Download the archive:  vsioinst.tgz [MD5: 1BD056C2F271168123BE553A805D333B]

• Uncompress the single jobstream in the archive - tar xvzf vsioinst.tgz - or - WinZip on Windows/??

• Edit the jobstream from the archive - VSIOINST.JCL - to customize DASD volume serial and unit types for your system

• Submit the jobstream - VSIOINST.JCL - to install the routine

I have not repeated all the development background here that is included on the page: VSAM File Access for COBOL, but if you follow the four steps above, you may continue following the instructions below and you will have everything you need to use the routine with PL/1 programs.

Your PL/1 program calls the intermediary program, VSAMIOP.  There are three variables passed by address - two structures containing control variables and an Input/Output buffer.  VSAMIOP extracts the addresses of the actual variables from the descriptor blocks that PL/1 constructs and calls VSAMIO using these addresses.  VSAMIO does all the processing on the VSAM dataset and control is returned, first to VSAMIOP and then to the calling PL/1 program.  The intermediary program, VSAMIOP, is only used to facilitate communication with VSAMIO.  So, the remainder of the documentation on this page will refer to VSAMIO, even though the PL/1 CALL is in fact to VSAMIOP.

The single routine, VSAMIO, will handle all access to one or more VSAM datasets for the calling 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 is assembled during installation into a library and will only need to be linked to the PL/1 object module during linkage editing.  It is not necessary to reassemble the routine each time a PL/1 calling program is compiled.  

Parameter Interface Blocks

Communication between the PL/1 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 PL/1 copybook VSAMIO:

/********************************************************************** VV VV SSSSS A M M IIII OOOOO VV VV SS SS AAA MM MM II OO OO VV VV SS AA AA MMM MMM II OO OO VV VV SSSSS AA AA MMMMMMM II OO OO VV VV SS AA AA MM M MM II OO OO VV VV SS SS AAAAAAA MM MM II OO OO VVV SS SS AA AA MM MM II OO OO V SSSSS AA AA MM MM IIII OOOOO ********************************************************************** THESE PARAMETERS ARE USED TO INTERFACE WITH THE VSAM DATASET ACCESS ROUTINE. THE VSIO_PARAMETER_VALUES SUPPLY THE VALUES USED TO MOVE INTO PARAMETER ENTRIES TO TAILOR THE ROUTINE TO A SPECIFIC DATASET AND TO PROVIDE COMMANDS TO DRIVE THE ROUTINE. *********************************************************************/ DECLARE 1 VSIO_PARAMETER_VALUES STATIC, 2 VSIO_OPEN CHAR(8) INIT('OPEN '), 2 VSIO_CLOSE CHAR(8) INIT('CLOSE '), 2 VSIO_READ CHAR(8) INIT('READ '), 2 VSIO_WRITE CHAR(8) INIT('WRITE '), 2 VSIO_REWRITE CHAR(8) INIT('REWRITE '), 2 VSIO_DELETE CHAR(8) INIT('DELETE '), 2 VSIO_START_EQUAL CHAR(8) INIT('STARTEQ '), 2 VSIO_START_NOTLESS CHAR(8) INIT('STARTGE '), 2 VSIO_KSDS CHAR(4) INIT('KSDS'), 2 VSIO_ESDS CHAR(4) INIT('ESDS'), 2 VSIO_RRDS CHAR(4) INIT('RRDS'), 2 VSIO_SEQUENTIAL CHAR(10) INIT('SEQUENTIAL'), 2 VSIO_DIRECT CHAR(10) INIT('DIRECT '), 2 VSIO_DYNAMIC CHAR(10) INIT('DYNAMIC '), 2 VSIO_INPUT CHAR(6) INIT('INPUT '), 2 VSIO_OUTPUT CHAR(6) INIT('OUTPUT'), 2 VSIO_INPUT_OUTPUT CHAR(6) INIT('UPDATE'), 2 (VSIO_RC_SUCCESS INIT(0), VSIO_RC_LOGIC_ERROR INIT(8), VSIO_RC_END_OF_FILE INIT(9999), VSIO_RC_UNKNOWN_COMMAND INIT(20), VSIO_RC_DATASET_ALREADY_OPEN INIT(21), VSIO_RC_DATASET_NOT_OPEN INIT(22), VSIO_RC_ORGANIZATION_UNKNOWN INIT(23), VSIO_RC_ACCESS_UNKNOWN INIT(24), VSIO_RC_ORG_ACCESS_MISMATCH INIT(25), VSIO_RC_MODE_UNKNOWN INIT(26), VSIO_RC_MODE_UNSUPPORTED INIT(27), VSIO_RC_DDNAME_BLANK INIT(28)) FIXED BINARY(15,0), 2 (VSIO_FB_DUPLICATE_RECORD INIT(8), VSIO_FB_KEY_SEQUENCE INIT(12), VSIO_FB_RECORD_NOT_FOUND INIT(16), VSIO_FB_NO_MORE_SPACE INIT(28), VSIO_FB_READ_WITHOUT_START INIT(88)) FIXED BINARY(15,0), /********************************************************************** THE VSIO_PARAMETER_BLOCK IS THE COMMUNICATION INTERFACE TO THE THE ROUTINE. *********************************************************************/ 1 VSIO_PARAMETER_BLOCK STATIC, 2 VSIO_COMMAND CHAR(8) INIT(' '), 2 (VSIO_RETURN_CODE, VSIO_VSAM_RC, VSIO_VSAM_FUNCTION, VSIO_VSAM_FEEDBACK) FIXED BINARY(15,0) INIT(0); /********************************************************************** END OF VSAMIO COPY BOOK *********************************************************************/

The level 2 data items 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 2 data items under the second structure, 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 PL/1 copybook VSAMIOFB:

/********************************************************************** VV VV SSSSS A M M IIII OOOOO FFFFFFF BBBBBB VV VV SS SS AAA MM MM II OO OO FF BB BB VV VV SS AA AA MMM MMM II OO OO FF BB BB VV VV SSSSS AA AA MMMMMMM II OO OO FFFFF BBBBBB VV VV SS AA AA MM M MM II OO OO FF BB BB VV VV SS SS AAAAAAA MM MM II OO OO FF BB BB VVV SS SS AA AA MM MM II OO OO FF BB BB V SSSSS AA AA MM MM IIII OOOOO FF BBBBBB ********************************************************************** THESE PARAMETERS ARE USED TO INTERFACE WITH THE VSAM DATASET ACCESS ROUTINE, AND ARE USED TO COMMUNICATE CHARACTERISTICS FOR A SINGLE VSAM DATASET. WITH THE 2 EXCEPTIONS FOR RECORD LENGTH (TO ACCOMODATE VARIABLE LENGTH RECORDS) AND KEY LENGTH (TO ACCOMODATE RELATIVE RECORD DATASETS), THESE DATA NAMES MUST BE POPULATED PRIOR TO CALLING THE ROUTINE TO OPEN THE DATASET AND MUST NOT THEN BE CHANGED UNTIL THE DATASET HAS BEEN CLOSED. *********************************************************************/ DECLARE 1 VSIO_FILE_BLOCK STATIC, 2 VSFB_DDNAME CHAR(8) INIT(' '), 2 VSFB_ORGANIZATION CHAR(4) INIT(' '), 2 VSFB_ACCESS CHAR(10) INIT(' '), 2 VSFB_MODE CHAR(6) INIT(' '), 2 (VSFB_RECORD_LENGTH, VSFB_KEY_POSITION, VSFB_KEY_LENGTH) FIXED BINARY(15,0) INIT(0), 2 VSFB_FILE_STATUS CHAR(1) INIT('C'), 2 VSFB_RESERVED CHAR(153); /********************************************************************** END OF VSAMIOFB COPY BOOK *********************************************************************/

As the comment above the VSIO_FILE_BLOCK group states, with the exception of VSFB_KEY_LENGTH, only when processing a relative record dataset, and VSFB_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.

Note:  Utilizing VSFB_KEY_LENGTH for relative record number is actually a compromise to get around the apparent limitations of the MVT PL/1 compiler.  The VSAMIO routine actually utilizes the entire fullword encompassed by VSFB_KEY_POSITION and VSFB_KEY_LENGTH when processing a relative record dataset, but I have been unable to find a method under this PL/1 compiler to redefine these two halfword variables with a single fullword variable.  This imposes a limit of 65,535 on the relative record number.

A unique copy of this file block must be provided for each VSAM dataset to be processed simultaneously.  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 structure or CHAR scalar item elsewhere in the calling PL/1 program.

Calling the Routine

To illustrate how to use the routine, the PL/1 fragments below are taken from the one of the suite of sample programs (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 is made to open the dataset:

/********************************************************************** ESTABLISH PARAMETERS FOR VSAM DATASET AND CALL ROUTINE TO OPEN *********************************************************************/ VSFB_DDNAME = 'KSDSF01'; VSFB_ORGANIZATION = VSIO_KSDS; VSFB_ACCESS = VSIO_SEQUENTIAL; VSFB_MODE = VSIO_OUTPUT; VSFB_RECORD_LENGTH = 80; VSFB_KEY_POSITION = 0; VSFB_KEY_LENGTH = 10; VSIO_COMMAND = VSIO_OPEN; CALL VSAMIOP (VSIO_PARAMETER_BLOCK, VSIO_FILE_BLOCK, RECORD_IMAGE); IF (VSIO_RETURN_CODE ^= VSIO_RC_SUCCESS) THEN DO; CALL VSIO_ERROR; RETURN; END;

The literal value, KSDSF01, assigned to 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_RC

3. VSIO_VSAM_FUNCTION

4. VSIO_VSAM_FEEDBACK will contain the most useful information in the case of an error.  I have supplied some constant values in VSIO_PARAMETER_VALUES which may be useful in interpreting VSAMIO's return code and VSAM feedback codes.

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

/********************************************************************** CALL ROUTINE TO WRITE RECORD INTO VSAM DATASET *********************************************************************/ VSIO_COMMAND = VSIO_WRITE; CALL VSAMIOP (VSIO_PARAMETER_BLOCK, VSIO_FILE_BLOCK, RECORD_IMAGE); IF (VSIO_RETURN_CODE ^= VSIO_RC_SUCCESS) THEN CALL VSIO_ERROR; ELSE RECORD_COUNTER = RECORD_COUNTER + 1;

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.

/********************************************************************** CALL ROUTINE TO CLOSE VSAM DATASET *********************************************************************/ VSIO_COMMAND = VSIO_CLOSE; CALL VSAMIOP (VSIO_PARAMETER_BLOCK, VSIO_FILE_BLOCK, RECORD_IMAGE); IF (VSIO_RETURN_CODE ^= VSIO_RC_SUCCESS) THEN CALL VSIO_ERROR;

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:  vsiopinst.tgz  [MD5: 2F87A24C16B7873BF18B3B546D10E28F] which contains a single MVS jobstream in the file VSIOINST.JCL.  Download and uncompress this archive with the command:

tar xvzf vsiopinst.tgz 

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

The VSIOINST.JCL jobstream consists of five steps - 

• the first step uses IDCAMS to delete the three target Partitioned Datasets which will be created during the remainder of the jobstream

• the second step uses IEBUPDTE to place the Assembler source for VSAMIOP and the PL/1 source for the test/demonstration programs into a source Partitioned Dataset

• the third step uses IEBUPDTE to place the PL/1 copy books for the command and dataset parameter interface blocks into a library Partitioned Dataset

• the fourth step uses the Assembler to assemble VSAMIOP into a temporary object dataset, which is passed to the fifth step

• the fifth step uses the Linkage Editor to link both VSAMIO and VSAMIOP into a Partitioned Dataset from which they may be linked with your PL/1 programs

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

SYS2.VSAMIOP.SOURCE
SYS2.VSAMIOP.MACLIB
SYS2.VSAMIOP.LOADLIB

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 some error messages from the first step, since the datasets being deleted should not exist on your system.  However, I use the SET AMS command to set the return code to zero following the deletes.  You must receive zero return codes from the second, third, and fourth steps.  The fifth step, the link edit, will receive a return code of 0008.  This is because VSAMIOP calls VSAMIO and that produces an unresolved reference until both routines are link edited with a calling PL/1 program.

VSAMIO and VSAMIOP are not reentrant.  Since the MVT PL/1 compiler cannot compile dynamic calls, the routines must be statically linked into every load module.  Therefore, I did not make the effort to make it reentrant.

Component Cross Reference

With the addition of VSAMIOP and a second set of example programs, it can be confusing about what dataset contains what component and where it came from.  So, the table below lists all of the datasets created by my installation jobstreams and their contents:

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 PL/1 programs.  The test programs are very simple, as my knowledge of PL/1 is pretty basic at this time.  Mostly I was interested in the functionality of the Assembler routine.  The suite of COBOL programs includes a test of a variable length dataset and accessing multiple datasets simultaneously.  I will try to add PL/1 versions of these programs shortly.

During the installation process described above, the source for these PL/1 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:  vsioptest.tgz [MD5: AD0F2B0EC3ADEBED7B3CE2C0D5563CB5].  Download and uncompress this archive with the command:

tar xvzf vsioptest.tgz 

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

Here is a cross-reference of the jobstreams contained in that archive, the PL/1 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 prints them.
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 prints them.
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 prints them.
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.
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 PL/1 programs invoke a compile, link-edit, and execute, so the PL/1 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.

And, if you figure out how to get the MVT PL/1 compiler to redefine those two halfword scalar items with a single fullword item, I would certainly appreciate knowing how you did it.