CICS management client interface

The CICS® management client interface (CMCI) is a system management application programming interface, designed using Representational State Transfer (RESTful) principles, for use by HTTP client applications including IBM® CICS Explorer. You can use this interface to develop HTTP client applications that manage installed and definitional CICS and CICSPlex® SM resources on CICS regions being managed by CICSPlex SM or CICS resources on stand-alone CICS regions.

The client initiates an HTTP request to the CICS management client interface. If the interface determines that the request is valid, it constructs a CICSPlex SM API command or, in the case of a stand-alone CICS region, a CICS system command. After running the command the CMCI creates an HTTP response. If the request is successful, this takes the form of an HTTP 200 (OK) response and an XML feed containing a result set, which it passes back to the client. If the request is not successful, the response consists of a non-OK HTTP response code with details of the failure.

The format for CICS management client interface HTTP requests and responses is based on the HTTP/1.1 protocol. See The HTTP protocol for more information about this protocol.

A CICS management client interface request takes the form of an HTTP header followed by a URI (Universal Resource Identifier) and, where appropriate, an XML body containing details of any changes to be made to CICS or CICSPlex SM resources.

The header incorporates one of the following HTTP methods:
Removes resources from the CICSPlex SM data repository, removes resources from the CSD, or discards installed resources.
Retrieves information about resources on the CICSPlex SM data repository, retrieves information about resources on the CSD, or retrieves information about installed resources.
Creates resources on the CICSPlex SM data repository or resources in the CSD.
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.

The URI includes the name of a CICS or CICSPlex SM resource, and specifies a series of parameters that refine the scope and nature of the query to identify one or more instances of the specified resource. In a GET request, the URI also specifies whether the API retains or discards a set of results. If the API retains the results, a new request can act on the retained results without having to repeat the retrieval operation. You can also use subsequent requests to page through the retained results selecting one or more records at a time. See Using retained result sets to improve the performance of GET requests for more information about retaining result sets.

POST and PUT requests include an XML body. In a PUT request the body contains either details of the changes to be made to resource attributes, or the action to be performed on the targeted resources. In a POST request, the body incorporates the attribute values you wish to give to the new resource instance.

GET and DELETE requests do not require an XML body. If additional parameters are required for a DELETE request, those parameters must be included in the URI and can optionally be added to the XML body. For example; if you are deleting a CSD resource definition you must include PARAMETER=CSDGROUP(csdgrp) in the URI, and you can optionally add <parameter name="CSD"/> to the XML body.

You can use CMCI either in a CICSPlex SM environment or in a stand-alone CICS region (SMSS).

If you use CMCI with CICSPlex SM, you can manage definitional, operational, and CSD resources in all of the regions managed by CICSPlex SM.

If you use CMCI in a stand-alone CICS region, you can manage only the operational and CSD resources associated with that region. If you use CMCI in a stand-alone CICS region, the context is specified as the application ID of that CICS region.