CMCI GET request URI
The URI of a GET request identifies the instances of the resources to be retrieved by the operation.
The following diagram illustrates the URI syntax for a GET request.
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 CMCI 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 expression.
You must replace certain restricted characters with escape sequences to ensure that they can be interpreted correctly by the server. See CMCI 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 CMCI 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 CMCI 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.
- OVERRIDEWARNINGCOUNT
- Bypasses the warning count limit mechanism and allows the request to execute as if the default warning count limits were not specified. This option is effective only when the CICSPlex SM Web User Interface server initialization parameter RESOURCELIMIT is set to WARNING.
- 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.