Adding a capture specification

You add capture specifications to an event specification to create capture points in CICS®.

About this task

The CICS event binding editor guides you through creation of one or more capture specifications. These specifications identify the following items:

Any point in a program that is considered an event
The conditions under which the event is considered valid
How data to be captured at a capture point is to be mapped into the event output data structure

For example, you can specify that any READQ TS (temporary storage READ) command is a potential event. You then qualify the conditions under which the event is raised by adding predicates of the types available for the command that you want to intercept. All predicates must be true for the event to be raised.

You can define three types of predicates:

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.

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.

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.

The basic event binding information, entered by the business manager during the high-level definition of the event binding, includes an event specification. This event binding information identified data that was known to be required for further processing, but gave no details of its location. You specify information sources to provide these details.

The CICS event binding editor helps by presenting in the Information Sources tab a table of the information it needs to meet the business specification. The table shows business information from the event specification. For each item in the table you must define the source of information for this capture specification.

Procedure

In the Specification tab, click an event specification. The right pane shows the details of the highlighted event specification.
Click Add a capture specification. The Add Capture Specification window is displayed.
Enter a name for your new capture specification. The acceptable characters are A-Z, a-z, 0-9, and _. Leading and embedded blank characters are not permitted. The string must not start with 0-9, _, or the string "xml", regardless of whether it is lowercase, uppercase, or mixed case; for example, "Xml" or "xMl".
Optional: Enter a description for your new capture specification.
Click OK. A new capture specification is created. Three tabs open in the right editor pane: Capture Point, Filtering, and Information Sources. Use each tab to provide information describing the new capture specification.
Click the Capture Point tab. Perform the following steps to add capture point information:
1. Select the EXEC CICS command for which you want to add a capture point, or Program initiation from the Capture Point list. Program initiation is a capture point associated with the start of a CICS program.
2. Click Capture before or Capture after. You can specify the capture point to be before or after some EXEC CICS commands. This option is disabled for a subset of these EXEC CICS commands.
Click the Filtering tab. Perform the following steps if you want to add capture predicate information:
1. Optional: Define the application context for your capture specification. The application context predicates available for your chosen capture point are displayed. Select an option for Operator and provide a value to specify the predicates. An operator of All specifies there is no filtering on the associated predicate. You enter values for Transaction ID, Current Program, and User ID in uppercase.
2. Optional: Define application options for your capture specification. The application options that are available for your chosen capture point are displayed. Select an option for Operator and provide a value to specify the predicates. An operator of All specifies that there is no filtering on the associated predicate.
  Application options that can be primary predicates are marked with an asterisk (*). You must select Equals as the Operator and specify a value for the primary predicate to maintain CICS performance. For example, for a PUT CONTAINER capture point, you specify a value for the available application option CONTAINER*.
3. Optional: Define application data for your capture specification. To add an application data predicate, click Add. The Application Data Predicate window is displayed.
  Select an option for Operator and enter a value for your predicate. An operator of All specifies that there is no filtering on the associated predicate.
  
  Define the variable that you want to test with the predicate. You can either click Select from imported language structure and follow the instructions in Selecting variables from imported source code, or select options for Location and Type and further define your variable, using the active fields in the panel. Only those fields that are required for the type that you select will be active. For example, if you select the Character type, only the Offset, Length, and Codepage fields are active.
Click the Information Sources tab. Perform the following steps on each of the information sources in the table to map the information source to an available data item. The table might contain no information sources if no business data is to be captured on the event.
You do not have to capture data if it is not required.
1. Double-click an information source, or select it and click Edit. The Event Information Source window is displayed.
2. Select an available data item from Context, Data Values, or Variable Length Data. If you select a variable length data item, you can either click Select from imported language structure and follow the instructions in Selecting variables from imported source code, or select options for Location and Type and further define your variable, using the active fields in the panel. Only those fields that are required for the type that you select will be active. For example, if you select the Character type, only the Offset, Length, and Codepage fields are active.
  The information source does not have to be the same length as the emitted business information item. CICS pads or truncates the value as necessary.

Results

You have created a capture specification. You can also remove capture specifications by clicking Remove Capture Specification in the Capture Point tab, and clicking Yes to confirm.