Filtering tab

Use the Filtering tab in the CICS® event binding editor to define criteria, called predicates, for capturing events. If you provide no predicates, events are emitted every time the capture point you choose runs in the target CICS system.

Each predicate consists of information identifying the predicate, an operator, and a value. You can specify as many predicates as you want to identify the situation in which you want this capture point to emit an event. The three types of predicates that you can specify are Context, Event Options, and Application Data.

Some capture points have a primary predicate. A primary predicate is a predicate for which you select Equals as the Operator setting and provide a value to avoid a performance impact as you add more capture specifications at a capture point.

Note: The CICS module names can change; therefore, do not include filters that contain DFH* module names in your capture specifications. The CICS event binding editor validates the users input when coding the names of most DFH* modules on the current program filter. Users can only code DFH£*, DFH0*, DFHW2FI, DFHW2TS, DFHMQBP0, DFHMQBP3, or DFHECID. In addition DFHMIRR and DFHMIRS can be coded for LINK PROGRAM application event.
An image of the filtering tab.

Context

The predicates in the capture specification are used for filtering on the context of the capture point.

Every capture point has context items for which you can specify predicates. An example is the transaction ID. All of the available context predicates are shown in the Filtering tab. Context predicates are optional; however, you typically specify the transaction ID or current program to emit events from a particular application.

The Context area is used to set filtering options for events. Based on other information that you supply in the CICS event binding editor, not all fields apply; the context predicates available depend on the capture point. The predicates that you might want to specify are: transaction ID, current program, and user ID.

Transaction ID
Operator choices for all capture points:
  • All
  • Equals
  • Does Not Equal
  • Does Not Start With
  • Starts With
Additional choices for application capture points:
  • Less Than
  • Not Less Than
  • Greater Than
  • Not Greater Than
Current Program
Operator choices for all capture points:
  • All
  • Equals
  • Does Not Equal
  • Does Not Start With
  • Starts With
  • Less Than
  • Not Less Than
  • Greater Than
  • Not Greater Than
User ID
Operator choices for all capture points:
  • All
  • Equals
  • Does Not Equal
  • Does Not Start With
  • Starts With
Additional choices for application capture points:
  • Less Than
  • Not Less Than
  • Greater Than
  • Not Greater Than
Response Code
Operator choices:
  • All
  • Equals
Values for the Equals operator include:
  • Ok
  • Not Ok

Event Options

The predicates in the capture specification are used for filtering on the values of event options for a CICS command or system event.

Each capture point can have event options for which you can specify predicates. Some commands have no event options. Event options correspond with the options for a particular EXEC CICS command or system event. An example for the SEND MAP command is the MAP name. An example for the DB2 connection status event is the FROM_CONNECTST status. All the available fixed data values for the capture point are shown in the Filtering tab. The format of event options is known to CICS.

Name
The name of the capture specification.
Operator
Operator choices for all capture points:
  • All
  • Equals
  • Does Not Equal
  • Does Not Start With
  • Starts With
Additional choices for application capture points:
  • All
  • Equals
  • Does Not Equal
  • Does Not Start With
  • Starts with
Additional choices for system capture points:
  • Goes Higher Than
  • Goes Lower Than
Value
The value that you specify for the predicate.
The application command option predicate limits vary depending on the CICS API. For example, TRANSID is 4 characters; CHANNEL is 16 characters. The CICS event binding editor adjusts dynamically for each type and displays a message if the predicate value is too long or too short.

For more information about event options for CICS API calls, see Application events in the CICS TS V5.2 product information.

For more information about event options for system events, see System events in the CICS TS V5.2 product information and Information Sources tab in the CICS TS V5.2 product information.

Application Data

The predicates in the capture specification are used for filtering on application data that is specified in a CICS command.

Note: You cannot add application data when a capture point of DELETEQ TD or DELETEQ TS is defined for a capture specification.

Application capture points can have variable length data values for which you can specify predicates. The application data corresponds with the options for a particular EXEC CICS command. An example for the SEND MAP command is the FROM field. All the available variable data values for the EXEC CICS command for that capture point are shown in the Filtering tab.

Application data predicates are processed by CICS in the order specified; that is, the first predicate is processed, followed by the second predicate, and so on.

Application data is used for storage areas such as COMMAREAs or containers that are passed as options on CICS commands. The format of these areas is not known to CICS, but is known by your application program. You probably have a source language description that you can import to describe the format.
Note: System events do not use application data.
Location
The value of the Location field depends on the CICS API call.
Examples:
  • For the command EXEC CICS WRITE FILE(EXMPCAT), the choices for the Location field are FROM and RIDFLD.
  • For the command EXEC CICS INVOKE SERVICE(name), the choices for the Location field are CHANNEL and SCOPE.
Container
Specifies a CICS channel container. The container field can be selected only when the application data has a channel specified. In all other situations the field is disabled.
Offset
Specifies the distance from the beginning, where the data starts. Offset 0 is the start of the field.
Length
The length of the field in bytes. A length of 0 means filter on the whole data area or container. This is useful when filtering on, for example, the contents of a container regardless of its length.
Operator
Operator choices:
  • All
  • Exists
  • Equals
  • Does Not Equal
  • Does Not Exist
  • Starts With
  • Does Not Start With
  • Less Than
  • Not Less Than
  • Greater Than
  • Not Greater Than
Value
The value that you specify for the predicate.
The length depends on the data type; for example, the maximum length for type character is 255 characters, while the maximum length for type unsigned halfword is 5 characters with a value in the range of 0 to 65535.
Parent topic: Capture specification