Any given API program is likely to be interested in only a subset of the CICSPlex® SM managed objects. You can identify the managed objects you want to work with by:
The set of managed objects that your API program can work with is determined primarily by the context and scope associated with the processing thread. As with all CICSPlex SM operations, the context and scope of an API program identify the CICS® systems on which the program can act.
In general, you can set the context and scope values as follows:
You can set a default context and scope for your program by using one of these commands:
The values you set on either of these commands are in effect for all API commands that use context and scope.
Alternatively, you can specify context and scope values for individual API commands. The following commands support one or both of the CONTEXT and SCOPE options:
The context and scope values you set on any of these commands are in effect for that command alone. If you specified a default context and scope for the thread, the values on any of these commands temporarily override the default values. If you did not specify a default context and scope and you issue a command that expects these values (such as GET), you must specify a context and scope on the command.
A request for CICSPlex SM managed object data can produce a large number of resource table records. The default is to return all the resource table records that exist for a given object within the current context and scope. For example, if you ask for PROGRAM object data, you receive a resource table record for every program in every CICS system in the current context and scope. However, if you are only interested in certain programs, you can use a filter expression to limit the number of records returned based on the current values of certain PROGRAM attributes.
You can use filter expressions in one of two ways:
Once a filter is defined, you can use it with these commands to limit the resource table records being processed:
A filter expression that you define with the SPECIFY FILTER command is available to your program until you either discard it (with the DISCARD command) or terminate the processing thread.
A filter expression is a character string that defines logical expressions to be used in filtering resource table records. A filter expression can be made up of one or more attribute expressions in the form:
Filter Expression >>-| logic_expr |-.-------------------------------------------->< logic_expr: .-AND/OR-------------------------. V | |----+-----+-+-| attr_expr |------+-+---------------------------| '-NOT-' '-(-| logic_expr |-)-' attr_expr: |--attropervalue------------------------------------------------|
where:
You can name the same attribute more than once in a filter expression.
TRANID=PAY*.
TRANID=P++9.
If the value contains imbedded blanks or special characters (such as periods, commas, or equal signs), the entire value string must be enclosed in single quotes. For example:
TERMID=‘Z AB’.
To include a single quote or apostrophe in a value, you must repeat the character, like this:
DESCRIPTION=‘October’’s Payroll’.
For example, the NAME attribute of the REQID resource table is a HEX datatype. To specify a name equal to 01234567 the value, using hexadecimal notation, would be
NAME=F0F1F2F3F4F5F6F7.
attr_expr AND attr_expr.
Filter expressions are evaluated from left to right. You can use parentheses to vary the meaning of a filter expression. For example, this expression:
attr_expr AND (attr_expr OR attr_expr).
has a different meaning than this one:
(attr_expr AND attr_expr) OR attr_expr.
You can negate a single attribute expression, like this:
NOT attr_expr.
You can also negate multiple attribute expressions or even a whole filter expression, like this:
NOT (attr_expr OR attr_expr).
Note that you must place parentheses around the attribute expressions (or the filter expression) to be negated.
For example, the following is a simple filter expression that you could use to select LOCTRAN objects representing local transactions that are enabled and have a storage violation count greater than zero:
STATUS=ENABLED AND STGVCNT>0.
You can build more complex filter expressions to select objects with a very specific combination of attributes. For example, to select LOCTRAN objects that:
you could specify a filter expression like this:
(TRANID=P* AND PROGRAM=PAY* AND STATUS=ENABLED) AND
((USECOUNT>0 AND STGVCNT>0) OR NOT RESTARTCNT=0).
Note that the RESTARTCNT attribute in this example could also have been specified with the greater than operator instead of the NOT operator.
Some objects support additional capabilities (in addition to facilities provided by filters) in order to reduce the number of records in a result set. If this is the case, parameters will be documented in the CICSPlex System Manager Resource Tables Reference describing parameters for GET.
The syntax to be used for these parameters is the same as that described in Modifying managed resources. For example, to build a result set containing completed task history (HTASK) records that finished between 05:00pm and 05:05pm on the 17th of July 2006, use the following parameter expression:
PARM('STARTDATE(07/17/2006) STARTTIME(17:00)
INTERVAL(300).')