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:

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.

You can define three types of predicates:
Application Context
Every capture point has context items for which you can specify predicates. An example is the transaction ID. All the available application context predicates are shown in the Filtering tab. Application context predicates are optional; however, you typically specify the transaction ID or current program to emit events from a particular application.
Application Command Options
Each EXEC CICS command that you can specify for a capture point can have application command options for which you can specify predicates. Some commands have no application command options. Application command options correspond with the options for a particular EXEC CICS command. An example for the SEND MAP command is the MAP name. All the available fixed data values for the EXEC CICS command for that capture point are shown in the Filtering tab.

The format of application command options is known to CICS.

Application Data
Each EXEC CICS command that you can specify for a capture point 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. For example, the first predicate is processed, then the second, and so on.

Application data is used for storage areas such as a COMMAREA or container that are passed as options on CICS commands. The format of these areas is unknown to CICS, but is known by your application program. You probably have a source language description that you can import to describe the format.

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 panel a table of the information it needs to meet the business specification. The table is partially filled as a result of the event specifications entered earlier by the business manager. The table has empty spaces that must be filled so that CICS knows the location of the data it must capture.

Procedure

  1. In the Specification tab, click an event specification. The right pane shows the details of the highlighted event specification.
  2. Click Add a capture specification. The Add Capture Specification window is displayed.
  3. 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".
  4. Optional: Enter a Description for your new capture specification.
  5. 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.
  6. 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.
  7. 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 the 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 Command Options for your capture specification. The application command options available for your chosen capture point are displayed. Select the Operator and provide a Value to specify the predicates. An operator of All specifies that there is no filtering on the associated predicate.

      Application command options that can be primary predicates and are marked with an asterisk (*). Start of changeYou must select the Equals 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 command option CONTAINER*.End of change

    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 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 an available 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.

  8. 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 an available 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.