Special considerations for generating EGL or REST services for z/OS® CICS®

Generating an EGL or REST service to a z/OS® CICS® environment involves the following requirements:

• Generation of services requires access to Hierarchical File System (HFS) on z/OS®:
  • The destDirectory build descriptor option will indicate the base directory on the HFS to use for deployment of a CICS® web service and of requesters.
  • For web service deployment, a subdirectory will be added to the directory named in the destDirectory build descriptor option; this subdirectory will be labeled as "RestProvider", and a .wsbind will be uploaded to the RestProvider subdirectory at preparation time. CICS® must have read and write access to this directory.
    Note:

    To reflect in the RBD Code on the endPointURL, we must provide the port 9090 (for example) to the RESTTCPIP under symbolic parameters in the build descriptor and using in JSON Schema file.

    WSBIND File location in HFS Path: /u/rbdtest/services/RestProvider/xxx.wsbind

• The default transaction provided for CICS web services is CPIH, which uses a Transaction Work Area (TWA) of 0 bytes. EGL applications require a minimum TWA size of 1024 bytes. To deploy your EGL-created applications, you must copy your CPIH transaction and modify the TWA size to 1024 bytes. Then the new copied transaction must be specified in the Transaction attribute of the protocol used for communication on CICS.

• PIPELINE , WEBSERVICE , URIMAP & TCPIPSERVICE resources to support REST services in CICS.
  • A PIPELINE resource definition is required for every REST service. It provides information about the message handler programs that act on a service request and on the response.

    The configuration of a pipeline used to handle a web service request is specified in an XML document, known as a pipeline configuration file.

    The pipeline configuration file is stored in the z/OS® UNIX System Services file system and the name is specified in the CONFIGFILE attribute of a PIPELINE resource definition.

    Pipeline configuration file is defined on the Unix shell path: /u/<uid>/services/basicRESTprovider.xml

    This is a simple example of a configuration file for a service provider pipeline that uses the <cics_json_handler_java> element:

    <?xml version="1.0" encoding="EBCDIC-CP-US"?>
    <provider_pipeline xmlns="http://www.ibm.com/software/htp/cics/pipeline"> 
      <service>
        <terminal_handler>
          <cics_json_handler_java>
            <jvmserver>DFHAXIS</jvmserver>
            <repository>/hcl/tcics55/usr/lpp/cicsts/cicsts55/lib/pipeline/repository</repository>
          </cics_json_handler_java> 
        </terminal_handler>
      </service>
      <apphandler class>com.ibm.cicsts.axis2.CICSAxis2ApplicationHandler</apphandler_class>
    </provider_pipeline>

    This is an example of installed REST service pipeline configuration. RESTPROV is the pipeline name of the components.

    Pipeline(RESTPROV)
    Enablestatus( Enabled )
    Mode(Provider)
    Mtomst(Nomtom)
    Sendmtomst(Nosendmtom)
    Mtomnoxopst(Nomtomnoxop)
    Xopsupportst(Noxopsupport)
    Xopdirectst(Noxopdirect)
    Soaplevel(NOTSOAP)
    Respwait(     )
    Configfile(/u/rbdtest/services/basicRESTprovider.xml)
    Shelf(/u/rbdtest/services/RESTprovider/shelf/) 
    Wsdir(/u/rbdtest/services/RESTprovider/) 
    Ciddomain(cicsts) 
    Installtime(01/10/22 09:02:25) 
    Installusrid(RBDTEST) 
    Installagent(Grplist) 
    Definesource(ELAGRP)

  • The pipeline should be scanned whenever interfaces code changes and generates the deployment descriptor. When we scan the pipeline, CICS will automatically create the Webservice and URIMAP definition for the corresponding program in the CICS region.

    CEMT PERFORM PIPELINE(REST_pipeline_name) SCAN

  • A WEBSERVICE resource definition is required only when the mapping between application data structure and messages has been generated using the CICS web services assistant.
    To check the installed webservice through pipeline scan, provide the below command.

    CEMT S WEBSERVICE (*)

    Example:

    Webs (PostRest. Postservice              )  Pip(RESTPROV)
           Ins CCS (00037) Uri($153550 ) Pro(POSTSERW) Cha Xopsup Xopdir

  • A URIMAP definition is also required if you use HTTP basic authentication. The URIMAP resource definition specifies that the service requester user ID information is passed in an HTTP authorization header to the service provider.
    URI Representation to access EGL CICS REST Service:

    http://localhost:port/Postservice/putEmployee/

    To check the installed URIMAP through pipeline scan, provide the below command.

    CEMT S URIMAP (*)

    Example:

    Uri($153550 ) Pip Ena  Http
       Hos(*                     ) Path(/PostService/*       )

    Here, /PostService denotes the <REST Service> and /* denotes the function-annotation in the Uri Template.
  • A TCPIPSERVICE definition is required in a service provider that uses HTTP transport. It contains information about the port on which inbound requests are received.

    To check the TCP IP service, provide the below command.

    CEMT S TCPIPS ALL

    Example:

    Tcpips(RBDREST ) Ope Por(09090) Http Nos Tra(CWXN)
       con(00009) Bac( 01024 ) Max( 000032 ) Urm( DFHWBAAX )

  • To use CICS as a service provider for JSON requests or the linkable interface to transform JSON, define and install a JVMSERVER resource with a JVM profile and specify the value JAVA_PIPELINE=YES.

    An example of JVMSERVER resource definition called DFHAXIS is provided in group DFH$AXIS.

    CEDA INST JVMS(DFHAXIS) GROUP(DFH$AXIS)