Using retained result sets to improve the performance of GET requests

You can improve the performance of HTTP GET requests by using the NODISCARD option to instruct the server to retain a set of results in memory after an initial request has completed. Instead of querying the CMAS, subsequent requests can then operate on the retained result set, which reduces the load on the server.

About this task

Normally CMCI garbage collection discards the result set after each GET request. If you use the NODISCARD option, however, the result set is retained. At the end of each request, CMCI checks the status of all result sets and discards only those that have been unused for 15 minutes or more.

The use of retained result sets permits the client to request the results of a query in several small XML response documents instead of one large one. Operating on smaller XML documents reduces the load on the server, network, and client by avoiding the need to render, transmit, and parse a large number of results. For example, by operating on retained results a client can display queried resources in pages, with each page displaying only twenty or so results from an original result set containing thousands of records. However, the snapshot nature of retained result sets makes them unsuitable for querying data that is changing rapidly or when the client needs to obtain the most up-to-date status possible.

If security is enabled on the server, you have access only to those retained result sets that you have created. An attempt to access a retained result set created by a different user results in an HTTP 403 error.

To work with a retained result set:

Procedure

  1. Issue an initial HTTP GET request specifying the optional NODISCARD and SUMMONLY options in the request URI.

    See CICS management client interface GET request URI for a detailed description of the GET request URI.

    Assuming that the request is successful, the CICS management client interface stores the results of the query in the GCDSA dynamic storage area and returns a token to the client that can be used on subsequent requests to access the retained result set. The token is returned as the value of the cachetoken attribute in the <resultsummary> element of the GET request response. Specifying SUMMONLY prevents the server from returning any records in the body of the response.
  2. Issue a second GET request specifying CICSResultCache in place of the external resource name, followed by the value of the cachetoken attribute from the response to the initial request.

    If you specify a cache token that is not recognized or has been deleted, it is treated as a resource not found condition and the server returns an HTTP 404 error.

    You can further refine the request by specifying index, count, and orderby options. index identifies one record from the result set by its position in the set of retained results. count identifies a subset of the records in the retained results, either from the first record in the set or from the position of the record identified by index.orderby identifies which field, or fields, the result set is sorted by. The maximum number of fields that can be specified in the orderby option is 32.

    You can continue to make the result set available following this request, by specifying the NODISCARD option on subsequent requests. If you do not specify NODISCARD, the server deletes the result set at the end of the request.

    The client can also issue multiple concurrent requests to the server against a single cache token. For example, multithreaded client applications can get information for records 1 - 10, 11 -20, and 21 - 30 simultaneously. However, failing to specify the NODISCARD option on one or more of the concurrent requests leads to results that are unpredictable.

Example

A GET request to view all the installed programs in a system can result in thousands of records being returned to the client, but you can use retained result sets to permit faster paging through the results.

The following request identifies all the PROGRAM resources installed in the system, but the SUMMONLY option indicates that no records are returned, only a summary of the identified resources. The NODISCARD option returns a cache token to identify this result set.
http://hostname.example.com:12345/CICSSystemManagement/CICSProgram/CICSPLEX?NODISCARD&SUMMONLY
The server returns the following response:
<?xml version="1.0" encoding="UTF-8"?>
<response xmlns="https://www.ibm.com/xmlns/prod/CICS/smw2int" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
connect_version="0410" version="1.0" xsi:schemaLocation="https://www.ibm.com/xmlns/prod/CICS/smw2int 
http://hostname.mycompany.com:12345/CICSSystemManagement/schema/CICSSystemManagement.xsd">
<resultsummary api_response1="1024" api_response1_alt="OK" api_response2="0" 
api_response2_alt="" cachetoken="C3D526A2F224FFE1" recordcount="1662"/>
</response>
You can verify that the query is successful by ensuring that the api_response1 and api_response2 attributes are 1024 and 0 respectively.

The <resultsummary> element identifies the result set with the cachetoken value C3D526A2F224FFE1. The recordcount attribute indicates that a total of 1662 records are in the result set.

To examine the first ten records in this retained result set, you can issue the following request:
 http://hostname.example.com:12345/CICSSystemManagement/CICSResultCache/C3D526A2F224FFE1/1/10?NODISCARD
The server returns the following response:
<?xml version="1.0" encoding="UTF-8"?>
<response xmlns="https://www.ibm.com/xmlns/prod/CICS/smw2int" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
connect_version="0410" version="1.0" xsi:schemaLocation="https://www.ibm.com/xmlns/prod/CICS/smw2int 
http://hostname.mycompany.com:12345/CICSSystemManagement/schema/CICSSystemManagement.xsd">
<resultsummary api_response1="1024" api_response1_alt="OK" api_response2="0" api_response2_alt=""
cachetoken="C3D526A2F224FFE1" displayed_recordcount="10" recordcount="1662"/>
<records>
  <cicsprogram _keydata="C3C5C5C3C2D3C4E8" aloadtime="00:00:00.000" ... usecount="0" usefetch="0.000" />
  <cicsprogram _keydata="C3C5C5C3C3C9C3E2" aloadtime="00:00:00.000" ... usecount="0" usefetch="0.000" />
  <cicsprogram _keydata="C3C5C5C3D4C94040" aloadtime="00:00:00.000" ... usecount="0" usefetch="0.000" />
         ...
</records>
</response>
The displayed_recordcount attribute indicates that the <records> element contains ten <cicsprogram> child elements. The cachetoken attribute confirms that the result set has been retained in the server for future use.
The client can then retrieve the next ten records starting at record 11, by issuing the following request:
http://hostname.example.com:12345/CICSSystemManagement/CICSResultCache/C3D526A2F224FFE1/11/10?NODISCARD
When you have finished examining the retained result set, you inform the server by accessing the result set without specifying the NODISCARD option. The following request again uses the SUMMONLY parameter to prevent the server from returning any records on this request.
  http://hostname.example.com:12345/CICSSystemManagement/CICSResultCache/C3D526A2F224FFE1?SUMMONLY
The server returns the following response:
<?xml version="1.0" encoding="UTF-8"?> 
<response xmlns="https://www.ibm.com/xmlns/prod/CICS/smw2int" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
connect_version="0410" version="1.0" xsi:schemaLocation="https://www.ibm.com/xmlns/prod/CICS/smw2int 
http://hostname.mycompany.com:12345/CICSSystemManagement/schema/CICSSystemManagement.xsd"> 
<resultsummary api_response1="1024" api_response1_alt="OK" api_response2="0" 
api_response2_alt="" recordcount="1662"/> 
</response>
The absence of the cachetoken attribute in the <resultsummary> element indicates that the result set is no longer stored in the server. If you try to issue further requests to use the retained result set, the server returns an HTTP 404 Not Found error.