CICS management client interface GET requests

The CICS management client interface uses the HTTP GET method to retrieve resources from CICS or CICSPlex SM.

The client forms a GET request from the following parts:
  • The HTTP method, in this case GET
  • The URI that identifies the resources to be retrieved and indicates whether the results are stored for later use or discarded
  • The HTTP version
  • Authorization credentials if required
For example, to retrieve all CICS local files in the CICSplex PLEX1, the client might construct the following request:
GET /CICSSystemManagement/CICSLocalFile/PLEX1/ HTTP/1.1 
Host: example.com:22958
Authorization: Basic RlJFRDpQQVNTVzBSRA==
The initial request line of the HTTP header has three parts, each separated by spaces and ended by a carriage return, followed by a line-feed:
  • 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 determine which instances of that resource are to be retrieved.

    A GET request can either operate directly on CICS or CICSplex SM resources or on results retained from a previous GET request. Normally results are discarded at the end of each request but you can retain a set of results by specifying the NODISCARD option on the GET request URI. When you use this option CMCI checks the status of all result sets and discards only those that have been unused for 15 minutes or more.

    If the request is operating directly on a resource, specify a resource name, which can be of an operational or a definitional resource, add the context and optionally the scope, and then further refine, sort, and filter the results by including one or more query parameters. Specify the ORDERBY parameter on the GET request URI to sort the results by one or more attributes.

    If the request operates on a set of retained results, you identify the results by replacing the resource name with CICSResultCache and specifying a cache token.You can narrow down the request to one or more records in the retained results by adding values for the index and count options. See Using retained result sets to improve the performance of GET requests for more information about retaining result sets.

    See CICS management client interface GET request URI for a detailed description of the GET 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.

Response to a GET request

On the completion of a GET request, the client receives a response from the CICS management client interface made up of an HTTP header, an XML feed containing a result summary, and details of the retrieved resources. However, if the URI 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 GET request:
HTTP/1.1 200 OK
Cache-Control: no-store
Date: Wed, 06 Aug 2008 08:32:00 GMT
Server: IBM_CICS_Transaction_Server/4.1.0(zOS)
Content-Type: application/xml; charset=UTF-8
Transfer-Encoding: chunked

See CICS management client interface error messages for a description of other 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 retrieved resources. 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 GET request.

Parent topic: CICS management client interface requests

clientapi_get.html | Timestamp icon Last updated: Thursday, 27 June 2019