Many of us have used CICS Explorer to manage CICS. But did you know that you can use the underlying CICS Management Client Interface (CMCI) from your browser (or any other HTTP client)? The CMCI request structure consists of
- an HTTP header with a method (GET, PUT, POST, DELETE)
- followed by a URI (Universal Resource Identifier) and
- an optional XML body containing details of any changes to be made to CICS or CICSPlex SM resources
To try out the examples you need to know the hostname (called yourHostName in this article) and the CMCI port (called yourCMCIPort) that you use to connect CICS Explorer to your system.
In this part you will only use your browser to send GET requests - we will cover PUT, POST and DELETE in another article.
Send your first Request
As a first example, try the following URL from your browser to return all installed Files in a specific CICS region:
If you connect CICS Explorer to a CICSPlex
if you don't have a CICSPlex set up and connect CICS Explorer to a single CICS region
Congratulations! You just performed your first HTTP GET request.
You will see all your local Files currently installed in that region. In my example there are 19 Files in that region (the recordcount is 19) from which 10 are displayed (displayed_recordcount).
I strongly recommend you always limit the number of results when you try out the following examples.
How to construct the GET URI
So how do you construct this URI to retrieve different resources?
The URI includes
- the External Resource Name of a CICS resource
and specifies a series of parameters to
- refine the scope and nature of the query
- identify one or more instances of the specified resource by name or other filter criteria
This is the URI syntax for a GET request
|--/--CICSSystemManagement--/--+-| resource parameters |-+------> '-| cache parameters |----' >--+--------------+--+------------+--+-------------+------------| '-NODISCARD--&-' '-ORDERBY--&-' '-SUMMONLY--&-'
We will first look at the resource parameters.
Your URI contains the following resource parameters.
|--resource_name--/--context--/--+-------+--+-----------+--?----> '-scope-' '-//--count-' >--+---------------------------------------+--------------------> '-CRITERIA=--escaped_criteria_string--&-' >--+--------------------------------------+---------------------| '-PARAMETER=--escaped_parameter_string-'
I already introduced you to the count parameter when you issued your very first request and limited the results to 10. Let's have a look at the other parameters.
Select the resource type
In the previous example you requested a CICSLocalFile.
The CICSPlex SM resource table architecture has been extended to allow it to work with the CMCI’s RESTful approach:
There is a new external resource name section for each resource type (V5.1 | V4.2) for example
|External resource name||CICSPlex SM resource name||Description|
|CICSLocalTransaction||LOCTRAN||CICS local transaction|
|CICSLocalFile||LOCFILE||CICS local file|
Set the context and scope
If you use CMCI in a CICSPlex SM environment, the context is the name of the CICSplex or CMAS associated with the request, in my example HEROPLEX.
If CMCI is installed as a single server, context is the application ID of the CICS region associated with the request.
With the scope you can further refine your request, for example to focus on a specific CICS region or SYSGROUP in your CICSPlex.
The values of scope and context must not contain spaces and are not case-sensitive. So to retrieve your list of Files you could use
"But where do I specify my CSD?" you might ask. We will cover this later when we look at parameter strings. For now, let's look at installed resources only.
Define filter criteria strings
You already know where to find the resource name, let's have a look at the CRITERIA you can use to filter. They are attached to your URI in the following way
http://yourHostName:yourCMCIPort/CICSSystemManagement/CICSLocalFile/yourCICSPlexName/yourCICSRegionName//10?CRITERIA=(yourAttribute1=yourValue1 AND|OR yourAttribute2=yourValue2 ...)
Use parameter strings to specify a CSD
So what to use parameters for? If you look at the resource table for local Files you will notice that for a GET request no parameters are available.
Now is a good time to look at resource definitions because we need parameters there to specify the CSD. If you look at the file definition resource table you will see parameters that can be specified.
During your requests you probably returned large amounts of data. Therefore you are probably interested in how you can limit the number of results and cache the rest to retrieve them in chunks. The URI syntax for a GET request contains more options that will help you:
|--/--CICSSystemManagement--/--+-| resource parameters |-+------> '-| cache parameters |----' >--+--------------+--+------------+--+-------------+------------| '-NODISCARD--&-' '-ORDERBY--&-' '-SUMMONLY--&-' Cache parameters: |--CICSResultCache--/--cache_token--/--+-/--------+--+----------+--?--| '-index--/-' '-count--/-'
Go back to your very first example that queries all local Files and add ?NODISCARD&SUMMONLY, for example
Note that the limitation to 10 is ignored. SUMMONLY will return the number of records matching your request and together with NODISCARD give you a cachetoken representing your request. You can now use the returned cachetoken to step through your results.
My following example returns the 9th until the 13th element of my result set. Always specify NODISCARD to ensure your results will not be deleted by CICS.
Congratulation! You used your browser to query installed resources from CICS as well as resource definitions from the CSD. And using the caching mechanism you can even break down the results into chunks.
And this was only what the GET method offers you! Next time we will look at POST (create resources), PUT (installs & change resources) and DELETE. Happy Browsing!