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.
You can use the following commands to create result sets and manage the resources that they represent:
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.
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:
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.
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:
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.
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:
The OBJSTAT resource table provides status information for a specific record in a result set.
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.
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:
Figure 7 illustrates the information available in result set records and the FETCH commands you can use to retrieve that information.
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.
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:
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:
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.
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.
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.
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.
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.
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.
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:
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:
Summary Expression .---------------------. | .-,----. | V V | | >>---sumopt-(---attr-+-)-+-.-----------------------------------><
where:
You can specify as many attribute names for each summary option as you like.
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.
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 |
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:
Order Expression - Sorting Records .-,-----------. V | >>---attr-+----+-+-.------------------------------------------->< '-/D-'
where:
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.
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 ]]