Welcome back, after The CMCI RESTful API: Part 1 – Talk to CICS using the Browser this will now be part II. In the last version we have focused on GET, which was useful to retrieve information. This article will examine POST, PUT and DELETE.

The CMCI request structure requires

  • an HTTP header with method
  • followed by a URI (Universal Resource Identifier
  • plus optional <request> XML body containing details of any changes to be made to CICS or CICSPlex SM resources

For CICS resources this means:

  • GET: Retrieves information about resources on the CICSPlex SM data repository, retrieves information about resources on the CSD, or retrieves information about installed resources,
    no body required
  • DELETE: Removes resources from the CICSPlex SM data repository, removes resources from the CSD, or discards installed resources,
    optional body with one <delete> element
  • POST: Creates resources on the CICSPlex SM data repository or resources in the CSD,
    body required with one <create> element
  • PUT: Updates existing resources in the CICSPlex SM data repository, updates existing resources in the CSD , or sets attributes and performs actions on installed resources. Also performs actions on CICSPlex SM and CSD resources,
    body required with one <update> or one <action> element

This time a browser will not be sufficient as we need to specify the HTTP method and send request data. I will use Poster for Firefox, a free developer tool for interacting with web services and other web resources that lets you make HTTP requests, set the entity body, and content type.

poster

We will define a transaction, modify, install, disable, discard and delete it. I will use a CICS Region with CSD in a CICSPlex (CICACB01 in CICSPLX1), therefore my URIs will be in the form of
yourHostName:yourCMCIPort/CICSSystemManagement/CICSDefinitionTransaction/yourCICSPlexName/yourCICSRegionName
For the screenshots you will see
ibmzos:3050/CICSSystemManagement/CICSDefinitionTransaction/CICSPLX1/CICACB01
If you run a single CICS Region without a CICSPlex, simply use
yourHostName:yourSingleCICSRegionCMCI{codePort/CICSSystemManagement/CICSDefinitionTransaction/yourSingleCICSRegionName

We will work with CICSLocalTransaction (LOCTRAN) and CICSDefinitionTransaction (TRANDEF) as described in the CICS management client interface resource names.

Define a transaction – POST

A CMCI POST request requires a <request> body with a <create> element consisting of

  • <parameter> – parameters associated with action
  • <attributes> – list of required attributes as specified by CPSM resource tables
  • To create a transaction named HELO in the CSD of our region you will need to send a POST request to
    http://yourHostName:yourCMCIPort/CICSSystemManagement/CICSDefinitionTransaction/yourCICSPlexName/yourCICSRegionName

    with the following body:

    <request>
      <create>
        <parameter name="CSD"/>
        <attributes name="HELO" PROGRAM="HELLOWCI" LOCALQ="N_A" csdgroup="ARNOLD" />
      </create>
    </request> 
    

    POST TranDef
    which should return the created transaction definition
    POST TranDef Response

    If you want you can send a GET request to
    http://yourHostName:yourCMCIPort/CICSSystemManagement/CICSDefinitionTransaction/yourCICSPlexName/yourCICSRegionName?CRITERIA=(NAME=HELO)&PARAMETER=CSDGROUP(ARNOLD)
    to verify that your definition is there. Refer to Part I of this article for instructions on filter criteria for the URI.

    Update your transaction definition – PUT update

    So what happens, if you forgot to add a description to your transaction definition? In this case you will need to send a PUT request with an <update> element against http://yourHostName:yourCMCIPort/CICSSystemManagement/CICSDefinitionTransaction/yourCICSPlexName/yourCICSRegionName?CRITERIA=(NAME=HELO)&PARAMETER=CSDGROUP(ARNOLD)
    which could contain

    <request>
      <update>
        <parameter name="CSD"/>
        <attributes description="forgot description" />
      </update>
    </request> 
    

    PUT TranDef description

    Install your transaction – PUT action

    This time you will send an <action> element containing the action to be performed. To install from the CSD, specify

    <request> 
      <action name="CSDINSTALL"/> 
    </request> 
    

    To check whether your transaction was successfully installed, issue a GET request against
    http://yourHostName:yourCMCIPort/CICSSystemManagement/CICSLocalTransaction/yourCICSPlexName/yourCICSRegionName?CRITERIA=(TRANID=HELO)
    GET Tran after install

    Disable your transaction – PUT action

    Before you discard a resource, you may want to disable it. Therefore send a PUT request with a DISABLE <action> to your transaction http://yourHostName:yourCMCIPort/CICSSystemManagement/CICSLocalTransaction/yourCICSPlexName/yourCICSRegionName?CRITERIA=(TRANID=HELO)

    <request>
      <action name="DISABLE"/>
    </request>
    

    Discard your transaction and delete the definition – DELETE

    To discard the installed transaction, simply send a DELETE request without any body against the transaction’s URI.
    DISCARD
    The same works for the transaction definition.
    DELETE

    Summary

    Congratulations! You’ve just went through a full transaction lifecycle completely based on HTTP requests. There may be more convenient methods but at least HTTP can be used by many applications or clients.

    1 comment on"The CMCI RESTful API: Part 2 – define, install, update and delete CICS resources with HTTP"

    1. Name *Kathy Bazinet May 10, 2016

      Nicely written Isabel and very timely and helpful.

    Join The Discussion

    Your email address will not be published. Required fields are marked *