CMCI PUT requests

The CICS® management client interface (CMCI) uses the HTTP PUT method to change the attributes of CICS or CICSPlex® SM resources or to perform actions, including INSTALL, on those resources.

The client forms a PUT request from the following components:
  • The HTTP method, in this case PUT
  • The URI that identifies the resources to be changed
  • The HTTP version
  • Authorization credentials if required.
  • The HTTP body that specifies in XML the changes to be made, or the action to be performed
For example, to update attributes of transaction definitions in CICSplex PLEX1 that have a name beginning with TR and a program beginning with P, the client constructs the following request:
PUT /CICSSystemManagement/CICSDefinitionTransaction/PLEX1?CRITERIA=NAME%3DTR%2A%20
AND%20PROGRAM%3DP%2A 
HTTP/1.1
Host: example.com:23792
Authorization: Basic RlJFRDpQQVNTVzBSRA==

<request>
   <update>
      <attributes STATUS="ENABLED" />
   </update>
</request>
The initial line has three parts, separated by spaces:
  • The method name
  • The request URI, which is specified as an absolute path that begins /CICSSystemManagement/ immediately followed by the external name that identifies resource together with the parameters and filters that determine which instances of that resource type are to be selected. To make the URI suitable for processing by the CICS management client interface, the client replaces certain restricted characters such as spaces and asterisks with escape sequences. See CMCI PUT request URI for a detailed description of the PUT request URI.
  • The HTTP version, which, when connecting to the CICS management client interface, is always HTTP/1.1

The second line identifies the host name and port number of the target system separated by a colon as specified in the URI. This line ends with a carriage return, followed by a line-feed.

The optional third line contains authorization credentials. If your system is running with the CICS system initialization parameter SEC as YES, you must supply a user ID and password in base-64 in a basic authentication header. In this example the user ID is FRED and the password is PASSWORD.

The HTTP header is then finalized by a final carriage return and line-feed on a separate line.

The remainder of the request is the XML body specifying the change to be made to the identified resource instances. In this case the request changes the STATUS attribute of the selected transaction definitions to ENABLED. The body consists of a the XML <request> element containing either one <attributes> element or one <action> element. See <request> element for more information about the XML elements in the body of a PUT request.

A PUT request can operate on either installed resources or on definitional CICS or CICSplex SM resources. A single PUT request can either specify attribute changes or perform an action. You cannot combine attribute changes and an action in a single request.

The PUT method does not support all actions. The following actions are supported by the POST method:
  • CREATE for definitional resources.
  • ADD for SYSDUMP and TRANDUMP resource types.
The following actions are supported by the DELETE method:
  • DISCARD for operational resources.
  • REMOVE for definition resources.

Response to a PUT request

On completion of a PUT request, the client receives a response from the CICS management client interface made up of an HTTP header, and an XML feed containing a result summary, and if the request is successful, details of the changed resources.

The header consists of an HTTP response, the date and time, and details of the server and content type; for example:
HTTP/1.1 200 OK
Cache-Control: no-store
Date: Wed, 10 Aug 2008 12:56:00 GMT
Server: IBM_CICS_Transaction_Server (zOS)
Content-Type: application/xml; charset=UTF-8
Transfer-Encoding: chunked
If the PUT request fails, the server issues an HTTP non-OK response. For example if the body of the request is not valid, the header includes the following 400 response:
400 Bad request. The body of the request is invalid.
This response can occur if the client sends multiple tags on a PUT request, or the body of the request contains an unknown tag, or the tag name does not match the model name in the URI. See CICS management client interface error messages for a complete list of HTTP response codes.

The body of the response consists of a <response> root element containing a <resultsummary> element displaying summarized information about the request, and typically a <records> element containing details of the selected resources. However, you can suppress the <records> element of the response by specifying the SUMMONLY parameter in the URI. If the request completed with errors, diagnostic information is provided in an <errors> element.

See <response> element for more information about the XML elements in the response to a PUT request.

Security considerations

When you are using HTTP methods, be aware that some firewalls do not allow HTTP PUT or DELETE traffic through the firewall because of security considerations. To accommodate this restriction, you can use a CMCI POST request to tunnel a PUT request through a POST request.