You add capture specifications to an event
specification to create capture points in CICS®.
About this task
The 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 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
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.
- 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:
- 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.
- 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:
- 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.
- 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*.
- 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.
- Double-click an information source, or select it and
click Edit.
The Event
Information Source window is displayed.
- 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.