Selecting managed objects

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:

Setting the context and scope

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:

CONTEXT
For most operations in a CICSplex, the context is the name of the CICSplex. For operations related to CMAS configuration (such as defining CICSplexes or CMAS communication links), the context must be a CMAS name and for applications executing in a CICS local MAS the CMAS name must be the local CMAS name.
SCOPE
When the context is a CICSplex, the scope can be: When the context is a CMAS, the scope value is ignored. Start of changeThere are also a number of resources for which the scope value is ignored. These are identified in the description of resource tables in CICSPlex System Manager Resource Tables Reference by the SCOPE applies field.End of change

You can set a default context and scope for your program by using one of these commands:

CONNECT
Defines a default context and scope when the API processing thread is established.
QUALIFY
Changes the default context and scope for subsequent commands issued on the thread.

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.

Using filter expressions

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.

How you can use filter expressions

You can use filter expressions in one of two ways:

How to build a filter expression

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:

Read syntax diagramSkip visual syntax diagramFilter Expression
 
>>-| logic_expr |-.--------------------------------------------><
 
logic_expr:
 
   .-AND/OR-------------------------.
   V                                |
|----+-----+-+-| attr_expr |------+-+---------------------------|
     '-NOT-' '-(-| logic_expr |-)-'
 
attr_expr:
 
|--attropervalue------------------------------------------------|
 

where:

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

You can name the same attribute more than once in a filter expression.

Note:
Start of change
In a filter expression you cannot specify the EYU_CICSNAME or EYU_CICSREL attributes, or attributes with a maximum length over 256 bytes.
End of change
oper
Is one of the following comparison operators:
<
Less than
<=
Less than or equal to
=
Equal to
>=
Greater than or equal to
>
Greater than
¬=
Not equal to
Note:
Start of change
Use less than (<) or greater than (>) operators in your CRITERIA expression instead of equal (=), when you are working with store clock based fields. If you are directly using the CICSPlex SM API, or the CMCI and require to select records that are based on a specific store clock value, a compound CRITERIA expression can be used. For example, "RESPTIME>='0000:00:00.008351' AND RESPTIME<'0000:00:00.008352'.".
End of change
value
Is the value for which the attribute is being tested. The value must be a valid one for the resource table attribute.
Generic values
If the attribute accepts character data, this value can be a generic. Generic values can contain:
  • An asterisk (*), to represent any number of characters, including zero. The asterisk must be the last or only character in the specified value. For example:
      TRANID=PAY*.
  • A plus sign (+), to represent a single character. A + can appear in one or more positions in the specified value. For example:
      TRANID=P++9.
Notes:
  1. Generic value checking is applied only to the filter value. For example, a filter value of USERID=S* returns resource table records that have a user ID starting with S. However, a filter value of USERID=SMITH does not return resource table records that appear to contain generic characters, for example, those with a user ID of S*.
  2. For hexadecimal data types, the data must be converted to hexadecimal prior to appending the asterisk (*) for the generic search. The plus sign (+) is not supported for hexadecimal data types.
  3. The Web User Interface does not support the use of generic characters in attribute filters in WLM active views such as EYUSTARTWLMATAFF.
Imbedded blanks or special characters

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’.
Note:
Be sure to consider the quoting conventions of your programming language when using single quotes in a CICSPlex SM value string.
Hexadecimal data
If the attribute has a datatype of HEX the value must be in hexadecimal notation.

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.
AND/OR
Combines attribute expressions into compound logic expressions using the logical operators AND and OR, like this:
  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.
NOT
Negates one or more attribute expressions.

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.

Note:
A filter 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 filter expression.

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.

Start of change

Parameter expressions

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).')
End of change [[ Contents Previous Page | Next Page Index ]]