CMCI POST requests

The CICS® management client interface (CMCI) uses the HTTP POST method to create resources in CICS or CICSPlex® SM.

The client forms a POST request from the following parts:
  • The HTTP method, in this case POST
  • The URI that identifies the resources to be retrieved and indicates whether the results are cached for later use or discarded
  • The HTTP version
  • Authorization credentials if required
  • The XML body containing details of the resource to be created.
For example, 
POST /CICSSystemManagement/CICSLocalFile/PLEX1/ HTTP/1.1 
Host: example.com:22958
Authorization: Basic RlJFRDpQQVNTVzBSRA==

<request>
<create>
<parameter name="RESGROUP" value="BASIC" />
<attributes name="FILE1" defver="1" />
</create>
</request>
The initial line has three parts, which are separated by spaces:
  • The HTTP method name
  • The request URI, which is specified as an absolute path that begins /CICSSystemManagement/ immediately followed by the external name that identifies the resource, and the parameters and filters that identify the instance of the resource that is to be created. See CMCI POST request URI for a detailed description of the POST request URI.
  • The HTTP version, which, when connecting to the CICS system management client API, 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 attributes of the new resource. The body consists of the XML <request> element containing one <attributes> child element. For more information about the XML elements in the body of a POST request, see <request> element.

Response to a POST request

On the completion of a POST request, the client receives a response from the client API made up of an HTTP header, an XML feed containing a result summary, and details of the resources created. However, if the request included the SUMMONLY parameter, the response consists only of the HTTP header and the result summary.

The header consists of an HTTP response, the date and time, and details of the server and content type. The following example shows the header for a successful request:
HTTP/1.1 200 OK
Cache-Control: no-store
Date: Wed, 06 Aug 2008 08:32:00 GMT
Server: IBM_CICS_Transaction_Server (zOS)
Content-Type: application/xml; charset=UTF-8
Transfer-Encoding: chunked

See CICS management client interface error messages for a description of the 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 new resource. 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.

For more information about the XML elements in the response to a POST request, see <response> element.

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 the X-HTTP-Method-Override HTTP header field to tunnel a PUT or DELETE request through a POST request. For example:
X-HTTP-Method-Override:	PUT