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

http://yourHostName:yourCMCIPort/CICSSystemManagement/CICSLocalFile/yourCICSPlexName/yourCICSRegionName//10

if you don't have a CICSPlex set up and connect CICS Explorer to a single CICS region

http://yourHostName:yourCMCIPort/CICSSystemManagement/CICSLocalFile/yourCICSRegionName//10

You will be asked for your Host Credentials
image

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.
image
 

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.

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
CICSRemoteTransaction REMTRAN Remote transaction
CICSDefinitionTransaction TRANDEF Transaction definition
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

http://yourHostName:yourCMCIPort/CICSSystemManagement/CICSLocalFile/yourCICSPlexName//10

http://yourHostName:yourCMCIPort/CICSSystemManagement/CICSLocalFile/yourCICSPlexName/yourSYSGROUPName//10

http://yourHostName:yourCMCIPort/CICSSystemManagement/CICSLocalFile/yourCICSPlexName/yourCICSRegionName//10

http://yourHostName:yourSingleCICSRegionCMCIPort/CICSSystemManagement/CICSLocalFile/yourSingleCICSRegionName//10

"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 …)

In the following example I requested all enabled files starting with D. Note that compared to the previous example there are now only 4 records returned. image
 

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.
image

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.
image

 

The following example filters for FILEA in group DFH$FILA
image

 

cache parameters

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

http://yourHostName:yourCMCIPort/CICSSystemManagement/CICSLocalFile/yourCICSPlexName/yourCICSRegionName//10?NODISCARD&SUMMONLY

image

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.

http://yourHostName:yourCMCIPort/CICSSystemManagement/CICSResultCache/yourCacheToken/yourNumberToStartFrom/yourAmountToReturn?NODISCARD

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.

image

 

Summary

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! In Part 2 we will look at POST (create resources), PUT (installs & change resources) and DELETE. Happy Browsing!

Join The Discussion

Your email address will not be published. Required fields are marked *