Setting up the Library application in CICS
This section outlines the administrative tasks required to install the sample LIBRARY application in CICS, and describes the use of the COMMAREA interface to the program from a client. This interface is needed to write a PHP script that accesses the program.
The Library application requires a VSAM file to be created and populated, and a COBOL program to be compiled. CICS resource definitions for the file and program are also required. These steps are outlined in more detail below. Some knowledge of CICS configuration procedures is assumed.
No mechanism is provided to invoke the LIBRARY program except through PHP as
described later in this article, although one could be developed.
Therefore, there is limited opportunity to verify the correct installation
of the File and Program, and for this reason, the setup instructions suggest
that the file be opened and the program loaded manually using
CEMT in order
to check these definitions.
The example library program requires a VSAM KSDS to hold the contents of the library catalog. The library/jcl/LIBFILE file in the supplied code archive contains sample JCL to delete and recreate the required dataset, and populate it with suitable initial data. This JCL needs to be transferred to a suitable location in your z/OS® system, and modified as follows:
- Replace the JOB card with one suitable for your environment.
- Replace all instances of the dataset name (P8BUILD.CICS650.LIBRARY.LIBFILE) with a suitable dataset name for your system. The chosen name is required later for the CICS FILE definition.
- Optionally, edit the initial data for the library, taking care to preserve consistency and integrity (see note below).
The following steps complete the creation and definition of the VSAM file:
- Submit the LIBFILE JCL as modified above, and check for successful execution.
- Log into CICS and create a CICS FILE definition using CEDA (or other
mechanism) with the following attributes:
Table 1. Attributes to use when creating the VSAM FILE definition
Attribute Value FILE LIBFILE GROUP LIBRARY DSName <As specified in LIBFILE JCL> RECORD FORMAT F ADD Yes BROWSE Yes DELETE Yes READ Yes UPDATE Yes
- Install the LIBFILE definition and check for success.
- Optionally, using
CEMTor otherwise, open LIBFILE and check that it opens successfully:
CEMT SET FILE(LIBFILE) OPEN
This step is suggested to check that the file has been created and defined correctly, because limited verification of the setup is possible.
The source code for the LIBRARY application is in the file library/cobol/LIBRARY, and the sample JCL to compile it is in the file library/jcl/LIBCOBOL, both in the sample code archive file provided with this article. These files should be transferred to suitable locations in your z/OS system, and the LIBCOBOL JCL should be modified as described below. The supplied version is as follows:
Listing 1. The JCL to compile the LIBRARY program
//LIBCOBOL JOB USER=P8BUILD,CLASS=A,MSGCLASS=A,NOTIFY=&SYSUID // JCLLIB ORDER=CTS320.CICS650.SDFHPROC //COMPCOB EXEC DFHZITCL, // PROGLIB=P8BUILD.CICS650.LOAD, // LNGPRFX=PP.COBOL390.V340, // CBLPARM=('NODYNAM,LIB,ADATA,RENT', COMPILER OPTIONS // 'CICS(''COBOL2,SP'')'), TRANSLATOR OPTIONS // INDEX=CTS320.CICS650, // LIBPRFX=PP.ADLE370.ZOS190, // DSCTLIB=P8BUILD.CICS650.COPY //COBOL.SYSIN DD DSN=P8BUILD.CICS650.COBOL(LIBRARY),DISP=SHR //COBOL.SYSADATA DD DSN=P8BUILD.CICS650.COBADATA(LIBRARY), // DISP=SHR //LKED.SYSIN DD * NAME LIBRARY(R) /*
The required changes are as follows:
- Provide a suitable JOB card.
- Change all dataset names and prefixes as appropriate for your z/OS and CICS installation.
- Ensure that the COBOL.SYSADATA DD definition points to a member of a PDS with variable length records, which is suitable to contain the ADATA output. Refer to the COBOL compiler documentation for more details.
The following steps complete the compilation and installation of the LIBRARY program:
- Submit the LIBCOBOL JCL as modified above, and check for successful execution.
- Log into CICS and create a CICS PROGRAM definition using CEDA (or
other mechanism) with the following attributes:
Table 2. CICS PROGRAM attributes
Attribute Value PROGRAM LIBRARY GROUP LIBRARY Language COBOL
- Install the LIBRARY program definition and check for success.
- Optionally, using
NEWCOPYthe LIBRARY program, and check that it loads:
CEMT SET PROGRAM(LIBRARY) NEWCOPY
This step is suggested to check that the program has been compiled and defined correctly, because limited verification of the setup is possible.
The convention for a CICS COMMAREA program is that when it is invoked, an area of storage is passed to the program containing input data, sometimes including an indication of the operation that is to be performed. On completion of processing, the storage area is overwritten with output data and response codes from the operation. The format of the COMMAREA storage area is often defined in a COBOL copybook, which is included in the target program and its callers.
To use such a CICS program, you need to know not only the format of the COMMAREA expected by the program for input and output, but also the supported operations and the expected input and output data and response codes. In CA1S, the task of building and interpreting the data structure of the COMMAREA is performed by the JZOS-generated record classes. However, the PHP programmer is responsible for setting the required fields on input and extracting the appropriate data on output, using the JZOS-generated APIs.
The supplied example Library application follows this standard pattern, and therefore, the PHP programmer needs details of the use of the COMMAREA interface in addition to the generated JZOS record classes, in order to invoke the Library program correctly from a PHP script.
The COMMAREA format used by the library program is defined by the following COBOL data definition:
Listing 2. The library program's COBOL data definition
01 DFHCOMMAREA. * LIBRARY COMMAREA structure 03 LIB-REQUEST-TYPE PIC X(6). 03 LIB-RETURN-CODE PIC 9(2). 03 LIB-ITEM-COUNT PIC 9(4). 03 LIB-BOOK-ITEM OCCURS 24 TIMES. 05 BOOK-ITEM-REF PIC 9(4). 05 BOOK-TITLE PIC X(20). 05 BOOK-AUTHOR PIC X(20). 05 BOOK-LOAN-STATUS PIC 9(2). 88 BOOK-ONLOAN VALUE 1. 88 BOOK-UNLENT VALUE 0. 05 BOOK-BORROWER PIC X(20). 05 FILLER PIC X(14).
The JZOS record generator tool, described later, converts the definition shown in Listing 2 into APIs that can be used from PHP to get and set fields in the COMMAREA. There is an intuitive mapping between the field names used in the COBOL and the PHP methods so that these can be related to each other.
Knowledge of the COMMAREA format expected by the target CICS program alone is insufficient to allow the program to be invoked correctly. It is also necessary to have usage information for the program, such as what operations are supported by the program, how this is specified in the COMMAREA, and the other inputs and outputs for each operation, together with possible outcomes and responses. This usage information for the library program is given in Table 3 for reference.
Because sample PHP scripts to invoke the library application are provided with this article, you do not need to use this information for the initial setup, but you do need it to understand, modify, or re-implement the scripts.
LIB-REQUEST-TYPE is a 6-character text field
that determines the operation to be performed by the Library program, and
must be set to one of the following values before calling the program:
Table 3. The library program's LIB-REQUEST-TYPE field
|| Return a list of all books in the library
in the array |
This may contain up to 24 elements, which is the maximum capacity of the library. Each item contains full details of the associated book. The number of books present is returned in
|| Return details of specified book in the
first element, |
The index (reference) for the requested book is input in
|| Add a new book to the library; details
supplied in |
|| Delete the book identified by |
|| Mark the book specified by |
|| Mark the specified book as not borrowed and
delete the borrower name from the book record. The book to be
returned is identified by |
On return, the Library program sets
LIB-RETURN-CODE to a two-digit numeric value depending on the
outcome of the requested operation:
Table 4. The library program's return codes
|| All except ||Specified book not found in library.|
||Book is already out on loan.|
||Not used||Should not occur.|
||All||Invalid user request.|
||Library is full (maximum 24 books!).|
||All||Unexpected processing error.|
The available request types and return codes are defined in a level-01 data section (LIBRARY-CONSTANTS) in the library program, which means that they can be made available to a PHP script using the JZOS record generator in a similar way to the COMMAREA data section.
In general, the PHP programmer will need information equivalent to the information in Table 4 for each CICS program to be called from PHP, and this will typically be provided in a suitable form by the CICS programmer responsible for maintaining the program.