Skip to main content

By clicking Submit, you agree to the developerWorks terms of use.

The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

All information submitted is secure.

  • Close [x]

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerworks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

By clicking Submit, you agree to the developerWorks terms of use.

All information submitted is secure.

  • Close [x]

developerWorks Community:

  • Close [x]

Build a RESTful service on CICS with PHP

Robin Fernandes (, Software Developer, IBM
Photo of Robin Fernandes
Robin Fernandes joined IBM's Java Technology Centre in Hursley, United Kingdom as Software Developer after graduating from Imperial College in 2003. His current focus is a Java-based runtime for PHP, which is used in the CA1S SupportPac and WebSphere sMash. He also regularly contributes test cases and patches to and enjoys experimenting with audio software in his spare time.
Jonathan Lawrence (, Software Developer, IBM
Photo of Jonathan Lawrence
Jonathan Lawrence joined IBM's Java Technology Centre in Hursley, United Kingdom as a Software Developer in 2006, after 4 years in Hursley's Software Services department where he was a CICS and Cross-platform Integration Specialist. He designed the CICS integration aspects of the CA1S SupportPac.

Summary:  CICS® Transaction Server® (TS) is a powerful transaction manager designed for rapid, high-volume processing. SupportPac CA1S uses technology from IBM WebSphere® sMash to enhance CICS TS with PHP scripting capabilities and Representational state transfer (REST)-related features. This tutorial shows how you can use PHP to quickly and easily work with CICS programs and expose them on the Web. If you are a PHP developer, find out how you can use your skills to interact with enterprise assets in CICS; if you are a CICS developer, see how PHP provides a simple and agile way to manipulate your existing resources.

Date:  21 Apr 2009
Level:  Intermediate PDF:  A4 and Letter (409 KB | 37 pages)Get Adobe® Reader®

Activity:  12723 views

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.

Steps to set up the Library application

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.

Creating and defining the VSAM file

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:

  1. Submit the LIBFILE JCL as modified above, and check for successful execution.
  2. 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
    DSName <As specified in LIBFILE JCL>
    ADD Yes
    BROWSE Yes
    DELETE Yes
    READ Yes
    UPDATE Yes

  3. Install the LIBFILE definition and check for success.
  4. Optionally, using CEMT or otherwise, open LIBFILE and check that it opens successfully:

    This step is suggested to check that the file has been created and defined correctly, because limited verification of the setup is possible.

Compiling and defining the COBOL program

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

//        LNGPRFX=PP.COBOL390.V340,
//          'CICS(''COBOL2,SP'')'),       TRANSLATOR OPTIONS
//        INDEX=CTS320.CICS650,
//        LIBPRFX=PP.ADLE370.ZOS190,
//        DISP=SHR

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:

  1. Submit the LIBCOBOL JCL as modified above, and check for successful execution.
  2. 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
    Language COBOL

  3. Install the LIBRARY program definition and check for success.
  4. Optionally, using CEMT or otherwise, NEWCOPY the LIBRARY program, and check that it loads:

    This step is suggested to check that the program has been compiled and defined correctly, because limited verification of the setup is possible.

How to use the COBOL Library application

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.

Library COMMAREA format

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.

Library program use

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
LIB-REQUEST-TYPE Library operation
LIST Return a list of all books in the library in the array LIB-BOOK-ITEM.
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 LIB-ITEM-COUNT.
QUERY Return details of specified book in the first element, LIB-BOOK-ITEM(1).
The index (reference) for the requested book is input in BOOK-ITEM-REF(1).
ADD Add a new book to the library; details supplied in LIB-BOOK-ITEM(1). Provided there is space in the library (max books = 24), the index for the new book is returned in BOOK-ITEM-REF(1).
DELETE Delete the book identified by BOOK-ITEM-REF(1) from the library, if it exists.
BORROW Mark the book specified by BOOK-ITEM-REF(1) as being borrowed, and add the supplied borrower name (BOOK-BORROWER(1)) to the book record.
RETURN Mark the specified book as not borrowed and delete the borrower name from the book record. The book to be returned is identified by BOOK-ITEM-REF(1).

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
Field name Value Operation(s) Condition
LIBRARY-OK 0 All Successful completion.
LIBRARY-NOTFOUND 1 All except LIST, ADD Specified book not found in library.
LIBRARY-ONLOAN 2 BORROW Book is already out on loan.
LIBRARY-DUPLICATE 3 Not used Should not occur.
LIBRARY-INVREQ 4 All Invalid user request.
LIBRARY-FULL 5 ADD Library is full (maximum 24 books!).
LIBRARY-ERROR 99 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.

2 of 9 | Previous | Next


Zone=Web development, Open source
TutorialTitle=Build a RESTful service on CICS with PHP