CICS management client interface GET request URI

The following diagram illustrates the URI syntax for a GET request.

URI syntax

|--/--CICSSystemManagement--/--+-| resource parameters |-+------>
                               '-| cache parameters |----'   

>--+--------------+--+------------+--+-------------+------------|
   '-NODISCARD--&-'  '-ORDERBY--&-'  '-SUMMONLY--&-'   

Resource parameters:

|--resource_name--/--context--/--+-------+--+-----------+--?---->
                                 '-scope-'  '-//--count-'      

>--+---------------------------------------+-------------------->
   '-CRITERIA=--escaped_criteria_string--&-'   

>--+--------------------------------------+---------------------|
   '-PARAMETER=--escaped_parameter_string-'   

Cache parameters:

|--CICSResultCache--/--cache_token--/--+-/--------+--+----------+--?--|
                                       '-index--/-'  '-count--/-'      

Options

/CICSSystemManagement

Indicates that the request is accessing the CICS management client interface. CICSSystemManagement is case-sensitive.

resource_name

Specifies the external resource name that is associated with the CICS or CICSPlex SM resource that is being queried. For example, specifying the resource name CICSRegion associates the request with the CICSPlex SM CICSRGN resource, and CICSResourceAssignmentDefinition associates the request with the RASGNDEF resource. See CICS management client interface resource names for a complete list of external resource names in CICS management client interface requests.

The HTTP GET method is not valid for all resources. To determine whether this HTTP method is valid for a particular resource, see the description of the resource in CICSPlex SM resource tables.

Resource names are not case-sensitive. If the client specifies an incorrect resource name, an HTTP 404 (Not Found) response is returned.

context

If CMCI is installed in a CICSPlex SM environment, context is the name of the CICSplex or CMAS associated with the request; for example, PLEX1. See the relevant resource table in CICSPlex SM resource tables to determine whether to specify a CICSplex or CMAS.

If CMCI is installed as a single server, context is the application ID of the CICS region associated with the request.

The value of context must not contain spaces. Context is not case-sensitive.

scope

Specifies the name of a CICSplex, CICS group, CICS region, or logical scope associated with the query. Scope is a subset of context, and limits the request to particular CICS systems or resources. Scope is not mandatory. If scope is absent, the request is limited by the value of the context alone. The value of scope must not contain spaces. Scope is not case-sensitive.

CICSResultCache/cache_token

Identifies a results cache containing a retained set of results. Specifying a cache token restricts the request to records retained from a previous GET request. At the end of every CMCI request CMCI checks the status of retained result sets. Any result set that has been unused for 15 minutes or more is discarded together with its cache_token.

index

Identifies a record in the retained results specified by the cache token parameter. Records are identified by the position they hold in the set of retained results. index must be an integer in the range 1 - 2 147 483 647 inclusive. A value of zero is not permitted. If you do not specify index, you must insert a forward slash in this position.

Specifying the index option does not alter the number of records requested and does not affect the warning count mechanism.

count

Identifies a subset of records in a results cache starting from the first record in the results cache or from the record specified by the index parameter. A negative number indicates a count back from the last record; for example, -1 means the last record, -2 the last record but one, and so on. count must be an integer in the range -2 147 483 647 through 2 147 483 647 inclusive. A value of zero is not permitted. In the case of resource parameters, you must precede count with two forward slashes.

Specifying the count option can limit the number of records displayed for a request, it does not alter the number of records requested and does not affect the warning count mechanism.

Query parameters

Refine the scope and nature of the request. The constituent parts of the query section can occur in any order, but each can occur only once in a URI. Query parameters are separated with an ampersand (&). Although query parameter values are not case-sensitive, certain attribute values must have the correct capitalization because some attributes such as TRANID and DESC can hold mixed-case values. The query parameters are as follows:

CRITERIA=escaped_criteria_string

A string of logical expressions that filters the data returned on the request. The string that makes up the value of the CRITERIA parameter follows the same rules as the filter expressions in the CICSPlex SM application programming interface. For more guidance about specifying filter expressions using the CICSPlex SM API, see How to build a filter expresion.

You must replace certain restricted characters with escape sequences to ensure that they can be interpreted correctly by the server. See CICS management client interface escape sequences for guidance about using escape sequences in CICS management client interface URIs.

PARAMETER=escaped_parameter_string

A string of one or more parameters and values of the form parameter_name(data_value) that refines the request. The rules for specifying these parameters are the same as in the CICSPlex SM application programming interface. For more guidance about specifying parameter expressions using the CICSPlex SM API, see Performing an action against a resource.

You must encode certain characters with escape characters. See CICS management client interface escape sequences for guidance about using escape sequences in CICS management client interface URIs.

NODISCARD

Indicates that the result set is retained following the request. This attribute is specified without a value. If you do not specify NODISCARD, the result set is discarded. You can use NODISCARD for requests operating on a resource name or a retained cache. At the end of each request CMCI checks the status of retained result sets and discards any that have been unused for 15 minutes or more.

ORDERBY

Indicates that the result set is sorted by the specified fields. This attribute is specified by a string of logical expressions; the string that makes up the value of the ORDERBY parameter follows the same rules as the in the CICSPlex SM application programming interface. For EYUDA and CVDA values, the field is sorted on the numeric value rather than the character value displayed. For more guidance about sorting records using the CICSPlex SM API, see Sorting the records in a result set.

You must encode certain characters with escape characters. See CICS management client interface escape sequences for guidance about using escape sequences in CICS management client interface URIs.

Each request that uses this option requires an L8 TCB from the pool of L8 and L9 mode open TCBs, which is managed automatically by CICS.

SUMMONLY

Indicates that only a result summary is returned by the request. No detailed records are included in the response.

Although specifying the SUMMONLY option prevents records being displayed for a request, it does not alter the number of records requested and does not affect the warning count mechanism. A request that includes SUMMONLY fails if the number of records requested exceeds the warning count value.