Working with result sets

CICSPlex® SM places the resource table records that you select in a result set. A result set is a logical group of resource table records that can be accessed, reviewed, and manipulated by an API program.

A result set can be created in one of two ways:

The resource table records in a result set must all represent one type of managed object. That is, a result set that contains PROGRAM resource table records cannot also contain LOCTRAN resource table records. The resource table records must also be collected from the same CICSPlex SM context. So a result set that contains records from one CICSplex cannot be used to hold records from any other CICSplex. Once a result set is created, its resource type and context are fixed. The only way to change the type or context of a result set is to completely replace the contents of the result set with new resource table records.

Keep in mind that a resource table record in a result set is not the actual managed object; it is a report of the managed object's attributes at the point in time when data was collected. This is an important distinction because the actual managed object may have changed or may no longer exist by the time the resource table record is returned to your program. The number of records returned may vary as managed objects come and go, but the structure of the records in a result set remains constant.

A simple API program might deal with only one result set at a time. Each new request for data could create a result set that replaces the previous one. A more complex program might maintain several result sets concurrently and control the retention of those result sets more directly.

An overview of result set commands

You can use the following commands to create result sets and manage the resources that they represent:

GET
Returns a result set containing selected resource table records that represent instances of a managed resource.
PERFORM
Performs an action on one or more managed resources. PERFORM SET acts upon the resource table records in an existing result set. PERFORM OBJECT does not require a result set to exist; it creates one implicitly.
REFRESH
Refreshes the data for some or all of the managed resources as represented by resource table records in a result set.
SET
Modifies the attributes of one or more managed resources as represented by resource table records in a result set.

These commands affect not only the resource table records in a result set, but also the managed resources that those records represent. Figure 4 illustrates the relationship of these commands to the API environment.

Figure 4. API commands that manipulate managed resources
 This figure illustrates the use of the GET, PERFORM, REFRESH and SET commands to create results sets in CICSPlex SM, and to manage the CICS resources they represent.

Once a result set is created, you can perform various operations on the records it contains. You can sort, mark, copy, delete, and summarize the records in a result set. Most importantly, perhaps, you can retrieve records from a result set into local storage where they can be processed by your program.

You can use the following commands to manipulate one or more records in a result set:

COPY
Copies some or all of the resource table records in one result set to another result set.
DELETE
Deletes one or more resource table records from a result set.
FETCH
Retrieves data and status information for one or more resource table records in a result set.
GROUP
Returns a summarized result set by grouping some or all of the resource table records in a result set.
LOCATE
Positions the record pointer within a result set.
MARK
Marks selected resource table records in a result set.
ORDER
Sorts the resource table records in a result set.
UNMARK
Removes the marks placed on resource table records by a previous MARK command.

These commands affect only the current contents of a result set; they have no impact on the managed resources that the result set represents. Figure 5 illustrates the relationship of these commands to the API environment.

Figure 5. API commands that manipulate result set records
 This figure illustrates the use of the COPY, DELETE, FETCH, GROUP, LOCATE, MARK, ORDER and UNMARK commands to manipulate records in a result set in CICSplex SM.

CICSPlex SM also provides tools for managing result sets as a whole: filters and views for controlling the contents of a result set and commands for reviewing and discarding result sets.

You can use the following commands to manage result sets and their contents:

DISCARD
Discards a result set.
QUERY
Retrieves information about a result set and the resource table records it contains.
SPECIFY FILTER
Defines an attribute or value filter that can be used to control the contents of a result set.
SPECIFY VIEW
Builds a customized view of a resource table that can be used to control the contents of a result set

These commands affect only an existing or newly created result set; they have no impact on the managed resources that the result set represents. Figure 6 illustrates the relationship of these commands to the API environment.

Figure 6. API commands that manipulate result sets
 This figure illustrates the use of the DISCARD, QUERY, SPECIFY FILTER and SPECIFY VIEW commands to manipulate a result set in CICSplex SM without affecting the managed resources.

Retrieving records from a result set

Once you have created a result set (using the GET command), you can transfer some or all of the records it contains to local storage for processing. You can use the FETCH command to retrieve a single resource table record, multiple selected records, or the entire result set at one time.

Each resource table record that you retrieve contains current data about the managed resource that it represents. Each record also contains certain status information that is maintained by CICSPlex SM.

This status information is presented as a resource table called OBJSTAT. The contents of the OBJSTAT resource table are described below:

OBJSTAT

The OBJSTAT resource table provides status information for a specific record in a result set.

Name
Description
RECORDNUM
The number of the record within the result set.
CONTEXT
The context in effect when the data for the record was collected.
CICSNAME
The name of the CICS® system from which the data was collected.
CICSREL
The release level of the CICS system from which the data was collected.
OBJECT
The name of the managed object to which the data refers.
OBJTYPE
The data type of the managed object:
1
CPSM resource
2
Logical view
RECTYPE
The type of record data:
1
Detail data
2
Summary data
LASTOPER
The last operation performed against the object:
1
COPY operation
2
DELETE operation
3
GET operation
4
MARK operation
5
REFRESH operation
6
PERFORM OBJECT operation
7
PERFORM SET operation
8
SET operation
9
UNMARK operation
STATUS
The current record status:
1... ....    X'80'      The record is MARKED
.... ...1    X'01'      Operation error
The attribute is not valid in the version of CICS if the bit is set on.
CNTRECORDS
The record count. For RECTYPE=1 the record count is zero. For RECTYPE=2 the record count will reflect the number of detail records.
KEYLEN
The length of the key data.
KEYDATA
The native key data
RESERVE1
Reserved area for future use.

In effect, each record in a result set contains a pair of resource tables: an instance of the OBJSTAT resource table followed by an instance of the resource table that was requested. The managed resource data and the OBJSTAT status information can be retrieved either as a pair or separately, depending on the option you specify with the FETCH command:

DATA
Retrieves only the specified resource table data.
STATUS
Retrieves only the OBJSTAT status information.
BOTH
Retrieves both the resource table data and the OBJSTAT status information.

Figure 7 illustrates the information available in result set records and the FETCH commands you can use to retrieve that information.

Figure 7. Using FETCH to retrieve result set records
 This figure illustrates the use of the FETCH STATUS, FETCH DATA and FETCH BOTH commands to retrieve LOCKTRAN (MAS, Tranid, Program, Status, UseCount, and so on) and OBJSTAT (Num, Context, MAS, Object, CntRecords, and so on) data from the result set referenced by TOKENA.

The result set referenced by TOKENA was created by issuing a GET command for LOCTRAN records. Each record in the result set consists of LOCTRAN data and OBJSTAT data.

You can use the FETCH commands shown in Figure 7 to selectively retrieve some or all of the data. For example, Figure 8 shows the output of a FETCH DATA command.

Figure 8. Sample FETCH DATA output
 This figure illustrates sample data from the command FETCH DATA ALL RESULT(TOKENA) INTO (AREA1)...

Positioning the record pointer in a result set

CICSPlex SM maintains a current record pointer in each result set. When you first create a result set (with a GET command, for example), the pointer is positioned at the top of the result set. The first command that you issue against the result set affects the first record.

In most cases, when you issue FETCH commands to retrieve records from the result set, the record pointer is positioned to the next record in the result set (that is, the record following the last record that was fetched). However, certain API commands always act upon the last record that was fetched. When you issue any of these commands after a FETCH command, the record pointer is not advanced to the next record:

The record pointer in a result set may actually move either forward or backward, depending on the direction in which you are retrieving records. If you issue a FETCH command and no records are found that match the specified criteria, no records are retrieved. In that case, the pointer is positioned to the top or bottom of the result set, depending on the direction the pointer was moving.

If you issue a FETCH command and there is insufficient storage to retrieve all of the records, the pointer is positioned at the last record that would have been retrieved if there had been enough space. The pointer is not positioned at the last record that was actually retrieved. To be certain of the pointer's location, you should use the LOCATE command to explicitly position it within the result set.

The GET and FETCH commands leave the record pointer in specific, predefined positions, but other API commands do not. Many API commands manipulate records or update the data in a result set. The position of the record pointer after one of these commands depends on a combination of factors, including the options that you specified on the command. The pointer may have moved forward or backward one or more records, or it may be positioned to the top or bottom of the result set. If you specified the CURRENT option, the record pointer does not move; it remains positioned on the current record after the command is complete.

For this reason, CICSPlex SM provides the LOCATE command, which lets you explicitly position the record pointer within a result set. If you want to use the record pointer after issuing any of these commands, first use the LOCATE command to reposition it:

Processing selected records in a result set

If you want to process a subset of the resource table records in a result set, you can identify the records you are interested in by:

Using MARK and UNMARK

The MARK command enables you to mark some or all of the resource table records in a result set for future reference. The UNMARK command removes existing marks from selected records. Once you have marked records in a result set, you can refer to the records that are either marked or not marked in subsequent commands. The following API commands support the MARKED and NOTMARKED options:

For example, Figure 9 shows a result set in which selected resource table records have been marked. The MARKED option is then used with the FETCH command to retrieve only those records that are marked.

Figure 9. Marking and retrieving records in a result set
 This figure illustrates a result set with three records marked using the command MARK PARM('3,4,6.')RESULT(TOKENA).... The marked records are retrieved using the command FETCH BOTH MARKED RESULT(TOKENA) INTO(AREA2)...

Identifying the records to be marked

By default, when you issue a MARK or UNMARK command, only the current resource table record is marked or unmarked. But there are a variety of ways that you can identify the records to be marked:

In addition to these options, you can use the PARM option to identify a list of records to be marked. To use the PARM option, you specify a character string of record numbers in a parameter expression. The parameter expression can contain:

The whole parameter expression must end with a period.

For example, to mark records 1, 3, 6 through 9, and 24 in a result set, you would specify:

  PARM(‘1,3,6:9,24.’)

When you use the PARM option, you must also use the PARMLEN option to specify the length of the buffer that contains the parameter expression.

Notes:
  1. Negative values and 0 are not valid record numbers. If you specify an invalid record number, the MARK (or UNMARK) command returns RESPONSE and REASON values of INVALIDPARM PARM.
  2. If you mistakenly specify the higher value in a range first (such as 9:6), CICSPlex SM reverses the values to produce a valid range.
  3. If you mistakenly specify a single value preceded or followed by a colon (such as 6:), the colon is ignored. CICSPlex SM marks only the specified record.

Identifying records that could not be marked

When you are marking or unmarking records, it might be useful to know if all the records you identified were successfully processed. For example, you might mistakenly ask CICSPlex SM to mark or unmark a record that was previously deleted from the result set. Or you might identify a record number that is out of range for the result set.

You can use the COUNT option on a MARK or UNMARK command to determine the number of records that could not be marked or unmarked. You can also use the INTO and LENGTH options to identify a buffer to receive a list of records that could not be marked. When deciding on the length of the INTO buffer, keep in mind that it must be long enough to hold the maximum number of record numbers that could result from your MARK request (in the event that none of them can be marked). Furthermore, all record numbers are listed individually (not by range) in the INTO buffer and are separated by commas. So if you specified the PARM option like this:

  PARM(‘1,3:6,12,15.’)

the INTO buffer would have to be long enough to hold the following character string:

  1,3,4,5,6,12,15

If the INTO buffer you specify is not long enough to hold a complete list of records that could not be marked, you receive a RESPONSE value of WARNING AREATOOSMALL. In that case, the INTO buffer returns a partial list of records and the LENGTH value is set to the buffer length that would be required for a complete list. You could then resubmit the MARK command with the appropriate LENGTH value to determine which records could not be marked.

How to remove the marks in a result set

You can use the UNMARK command to remove some or all of the marks placed on resource table records by a previous MARK command. However, if you want to mark other records at the same time, you can save a step by using the RESET option of the MARK command.

By default, the records you specify on a MARK command are marked in addition to any records that are already marked in the result set. That is, any resource table records that were marked previously remain marked unless you use the RESET option. RESET wipes the result set clean of any previous marks. So the records identified on the current MARK command are the only records marked when processing is complete. Using the RESET option on a MARK command is an alternative to using the UNMARK command before the MARK command.

Note:
Any marks that you placed on resource table records are also removed when you use the COPY command to copy those records from one result set to another.

Summarizing the records in a result set

If you want to analyze or modify a large number of records in a result set, you might find it useful to summarize those records. The GROUP command lets you summarize the records in a result set based upon the value of some resource table attribute.

When you issue a GROUP command, CICSPlex SM summarizes the records in one result set to create a new, summarized result set. A summarized result set is a special type of result set. It contains summary resource table records that correspond to one or more records in the source result set.

For example, you could use the GROUP command to summarize a result set that contains LOCTRAN resource table records. If you want to group the records according to the value of the STATUS attribute, the summarized result set would contain, at most, two records: one representing those records with a STATUS value of ENABLED, and one representing those with a STATUS of DISABLED. Figure 10 illustrates this use of the GROUP command.

Figure 10. Using GROUP to summarize result set records
 This figure illustrates the use of the command GROUP BY(STATUS) FROM (TOKENA) TO(TOKENB).. to summarize result set records for OBJSTAT and LOCKTRAN data.

In general, you can work with a summarized result set in the same ways that you do a regular result set. You can use the FETCH command to retrieve records from a summarized result set. You can also retrieve the individual records of the source result set on which the summary is based. The DETAIL option of the FETCH command lets you retrieve that subset of records in the source result set that correspond to a particular summary record.

Figure 11 shows an example of fetching the detail records associated with a summary record. In this case, the summary record was a LOCTRAN record that represented all enabled transactions.

Figure 11. Sample FETCH DETAIL output
 This figure illustrates the use of the command FETCH DETAIL RESULT(TOKENB) INTO(AREA3)... to retrieve detail records.

You can modify the records in a summarized result set using the PERFORM or SET commands. This is equivalent to modifying all the records in the source result set that are represented by a given summary record. However, since each record in a summarized result set has a single OBJSTAT record associated with it (rather than one for each of the source records being modified), you may want to use the FETCH DETAIL command to determine the results of a summary action.

The OBJSTAT records in a source result set are not summarized when you issue a GROUP command. So the OBJSTAT records in a summarized result set do not represent the OBJSTAT information for all of the source records. However, the OBJSTAT records in a summarized result set do include a summary count, which indicates how many source records were combined to produce each summary record.

A summarized result set and its source result set should be thought of as a pair to be used together. They share certain attributes and the summarized result set has certain dependencies on the source result set:

Specifying summary expressions

The attributes of a summary record are set according to a summary option that is appropriate for the attribute's data type. For each resource table attribute, CICSPlex SM defines a default summary option. CICSPlex SM uses these defaults when summarizing records unless you explicitly override them.

You tell CICSPlex SM how to summarize the attributes in a record by specifying a summary expression on the SUMOPT option of the GROUP command. A summary expression is a character string that consists of one or more summary options and the resource table attributes to which they apply.

The syntax of a summary expression is:

Read syntax diagramSkip visual syntax diagramSummary Expression
 
   .---------------------.
   |          .-,----.   |
   V          V      |   |
>>---sumopt-(---attr-+-)-+-.-----------------------------------><
 

where:

sumopt
Is the summary option to be used for the specified resource table attributes:
AVG
Provides the average attribute value. Valid for numeric fields only.
DIF
Provides those characters that are common to all underlying records and displays an asterisk (*) for those not common. Valid for character fields only.
LIKE
Provides the CVDA or EYUDA value, if all records contain a common value. Otherwise, displays N/A. Valid for CVDA and EYUDA fields only.
MAX
Provides the maximum attribute value.
MIN
Provides the minimum attribute value.
SUM
Provides the sum of the attribute values. Valid for numeric fields only.
You can specify the same summary option more than once in a summary expression.
attr
Is the name of an attribute in the resource table.

You can specify as many attribute names for each summary option as you like.

Note:
A summary expression must be followed by either blank spaces or null characters to the end of the specified buffer. That is, the buffer length you specify (using the LENGTH option) should not include any data other than a summary expression.

For example, you could use a summary expression like this when grouping LOCTRAN records:

  SUM(USECOUNT) MAX(PRIORITY,TWASIZE).

By default, the values for these attributes would be averaged. But this summary expression specifies that each summary record should include the sum of all USECOUNT values and the maximum PRIORITY and TWASIZE values.

Table 7 shows the valid summary options for the various datatypes.

Table 7. Valid summary options by attribute data type
AVG DIF LIKE MAX MIN SUM
ADDRESS X X
AVG X X X X
AVG3 X X X X
BIN X X X X
BIT X X
CHAR X X X
CODEBIN X X X X
COMPID X X
CVDAS X X X
CVDAT X X X
DATE X X
DATETIME X X
DEC X X
DECSTP X X
EYUDA X X X
HCHAR X X X
HEX X X X
HHMM X X
INTVMSEC X X X X
INTVSEC X X X X
INTVSTCK X X X X
INTVUSEC X X X X
INTV16US X X X X
PCT X X X X
PCT3 X X X X
RATE X X X X
RATE3 X X X X
RATIO X X X X
RESTYPE X X
SCLOCK X X X X
SUM X X X X
SUM3 X X X X
TEXT X X X
TIMESTP X X

Sorting the records in a result set

The records in a result set are normally sorted by the key attributes for that resource table. In the case of CICS Resource and CICS Monitored tables, records are sorted by the CICS system from which they were collected. In working with result sets, you may find it easier to process the records if they are in some logical order of your own choosing. The ORDER command lets you sort the records in a result set according to the values of a particular resource table attribute.

You tell CICSPlex SM how to sort the records by specifying an order expression on the BY option of the ORDER command. An order expression is a character string that consists of one or more attribute names to be used in sorting the resource table records.

The syntax of an order expression for sorting records is:

Read syntax diagramSkip visual syntax diagramOrder Expression - Sorting Records
 
   .-,-----------.
   V             |
>>---attr-+----+-+-.-------------------------------------------><
          '-/D-'
 

where:

attr
Is the name of an attribute in the resource table.

You can specify as many attribute names as you like, but the total length of an order expression, including commas and blank spaces, must not exceed 255 characters.

Note:
You cannot specify the EYU_CICSNAME or EYU_CICSREL attributes in an order expression.
/D
Indicates the attribute values should be sorted in descending order. By default, the values are sorted in ascending order.
Note:
An order expression must be followed by either blank spaces or null characters to the end of the specified buffer. That is, the buffer length you specify (using the LENGTH option) should not include any data other than an order expression.

For example, to sort a result set of LOCTRAN records by transaction ID and enabled status, you could specify:

  TRANID,STATUS.

In this example, transaction ID is the primary sort key and enabled status is the secondary sort key.

To sort records in descending order of use count, add /D to the end of the attribute name, like this:

  USECOUNT/D
[[ Contents Previous Page | Next Page Index ]]