Governance and troubleshooting
This chapter provides a method to gauge the effect that changes to an application might have on the events in a CICS system. It also describes best practices for performance considerations and event processing monitoring and statistics. The problem determination section shows a procedure to determine why expected events are not captured, and gives guidance to ascertain why too many events are captured and why, after data has been captured, it might not be as expected.
This chapter includes the following topics:
8.1 Impact of application changes on events
To assess the effect changes to applications might have on events in a CICS system, a clear understanding is needed of the resources that are named in event bindings that are currently installed in the system. Equally as important is identifying resources named in event bindings that are currently defined in the CICS Explorer workspace and might be installed in a CICS system. A new search function that is specifically designed for event processing artifacts can help with this process.
8.1.1 Event processing search
The event processing search function, which is initiated from the CICS Explorer Resource perspective, allows for the analysis of installed and offline resources that are used in the capture and emission of events. To start a search, select the Search function from the menu bar, as shown in Figure 8-1.
Figure 8-1 Selecting the event processing search function in CICS Explorer
An offline search can be initiated against different resource types and information sources within the event bindings in the CICS Explorer workspace by specifying a search string and selecting or clearing the Case sensitive option.
The search can be limited by selecting the options in the EP Search panel, to search for a specific resource type that can appear in the context data or the event options of an event binding, for example.
In the Shopping example that was used in earlier chapters of this book, a search can be run to find a resource type of PROGRAM in context data. Selecting the box labeled Ignore predicates with operator “All” limits the search results that are returned to only those options that contain other operators, as shown in Figure 8-2 on page 173.
Figure 8-2 Search the current workspace for a PROGRAM resource called UPDSTOCK
The search results return all exact and potential hits. For example, if an event binding included a current Program with a name of PROG in the context data and the operator used is “Does not start with”, this event binding is included in search results for a program name of UPDSTOCK. Ensuring that the Ignore predicates with operator “All” is selected limits the number of potential search results. This configuration might risk missing potential effects. For example, if an event specification captures WRITE FILE requests to a file CUST from programs with any name, the event specification uses the All operator for the current program and a search for program UPDSTOCK only finds such an event specification if the Ignore predicates with operator All is not selected. In this situation, a search for file CUST might be a more appropriate way to find the impact of changes.
In this instance, the search results that are only limited to the workspace include the Capture fulfill capture specification in the ShoppingEventBinding file. Switch to the Search Results view in CICS Explorer, which is displayed when the search is started. Click Expand All to see the results of the search, as shown in Figure 8-3 on page 174.
Figure 8-3 Workspace search results for the UPDSTOCK program resource
Double-click the word Context in the search results view to open the ShoppingEventBinding in the Event Binding Editor. The capture specification filtering page is displayed, where the program name UPDSTOCK can be found in the Context section.
To search all installed event bindings, use CICS Explorer to set a System Management Host connection to a CICSplex (see 5.1.2, “CICS Explorer connectivity” on page 83). Change the scope in the EP Search panel to CICS resources installed in. Select the CICSplex from the available list, as shown in Figure 8-4.
Figure 8-4 Search a CICSplex for a program resource called UPDSTOCK
Switch to the Search Results view in CICS Explorer and expand the output. The results are returned for each CICS region in the CICSplex, as shown in Figure 8-5.
Figure 8-5 Search results for installed event bindings in a CICSplex
Double-click Application Context or right-click Application Context and select Open to view the Capture Specification for the ShoppingEventBinding event binding. The value UPDSTOCK can be seen in the current program (Currpgm) field, as shown in Figure 8-6.
Figure 8-6 Capture specification details for an event binding installed in a CICSplex
8.2 Best practices for performance
From a performance perspective, CICS event processing consists of the following main steps:
•Capturing an event
•Dispatching the EP adapter
•Emitting the event through the EP adapter
8.2.1 Capturing an event
Filtering of the predicates that are specified for each event occurs during the capture stage. The capture point specifies the API call or system occurrence for which an event is to be captured. The filter is made up of predicates that identify the circumstances in which instances of the API call or system occurrence relate to the event. So, when event processing is started and no event bindings are installed, processor usage is negligible. Processor usage is also negligible when event bindings are installed, but there is no capture specification that matches the capture points that are started in the system.
The primary predicate is the primary value that is specified in the API command or on the system occurrence. For example, for a PUT CONTAINER command, the container name is a primary predicate. On a READ FILE and on a FILE ENABLESTATUS or OPENSTATUS capture point, the file name is a primary predicate. On a Filter, performance is optimized by the use of primary predicate filters that use the Equals operator. If there is a match on the primary predicate, use of Equals can result in improved performance when compared to other operator values.
Reduce the number of filters, where possible, by not including unnecessary filters. For example, if only one program writes to file XYZ, it is necessary to filter only on the file name and not also the program name.
Another way to help with performance is to organize the filter predicates to put those that filter out the largest number of unwanted events before the filter predicates that exclude fewer unwanted events in the capture specification.
Do not use filter predicates on zoned decimal or packed decimal data fields that might contain unusable data. Ensure you have sufficient filter predicates before making a packed decimal or zoned decimal check to ensure that the data area that is checked always contains valid packed decimal or zoned decimal data.
If you capture payload data that is associated with the event (information sources in the CICS Explorer event binding editor), keeping the number of data items captured to a minimum aids performance. For example, it is more efficient to define a single data capture element to capture bytes 0 - 35 than it is to define five data capture elements capturing bytes 0 - 5, 10 - 15, 20 - 25 and 30 - 35. It is recommended that containers do not contain a mix of data types. If the event is emitted to another platform, it is important that character data is translated to the correct code page.
8.2.2 Dispatching the EP adapter
In the dispatching stage, event processing runs multiple event dispatcher tasks on L8 TCBs to emit events. The maximum number of L8 TCBs is fixed at two times the value of MXT, plus 32. As of CICS TS V5.1, the maximum number for event processing dispatchers is limited to one third of this value to prevent event processing from monopolizing the L8 TCBs. Use the data in the “Peak event capture queue” and “Peak dispatcher tasks” entries in the EVENTPROCESS global statistics to ensure that the max tasks value is not set too low.
Specifying a user ID or transaction ID in the advanced options of the EP adapter causes the EP adapter to be attached as a separate task. However, performance is improved if no user ID or transaction ID is specified in the EP adapter because the EP adapter is then linked to the dispatcher task.
8.2.3 Emitting an event through the EP adapter
During the EP adapter stage, the cost of running the EP adapters depends on which EP adapter is used. The TSQ EP adapter imposes the least cost in terms of CPU usage.
An MQPUT1 call is generated for each event that is emitted to the WebSphere MQ EP adapter, which has some overhead. In addition, if event emission is assured (synchronous emission option), the cost of this call transfers from an asynchronous event processing task to the application thread, which can increase application response time.
The transaction start EP adapter starts a new CICS task. Therefore, processor usage increases because of starting the transaction that is driven as a result of the CICS event. Also, as each data capture field is made available to a started transaction in a separate container, a large number of data capture fields can impose a significant increase in processor usage on the EP adapter.
The HTTP EP adapter issues a WEB OPEN, WEB CONVERSE, and WEB CLOSE call for each event and by default closes the client HTTP connection after the event is emitted. Processor overhead for reopening the connection can be saved by keeping the connection open after event emission. You can achieve this by specifying the SOCKETCLOSE attribute in the URIMAP resource that the HTTP EP adapter names. A CEPH task is attached for each event that is emitted by using the HTTP EP adapter, which has a default timeout value (RTIMEOUT) of 5 seconds. By taking a copy of the profile for this transaction (DFHECEPH) and the CEPH transaction, the timeout value can be changed to match your environment. For example, if the event emission rate is high when compared to the response rate of your network or HTTP 1.1 compliant server, the number of CEPH tasks that are generated can cause the MXT limit to be reached on your system. To avoid this, assign a copy of the CEPH transaction to a transaction class that has a MAXACTIVE value low enough to avoid reaching the MXT limit.
For the same number of event emissions, the use of an EP adapter set, separate EP adapters, or EP adapter that is defined as part of an event binding all have similar performance characteristics.
8.2.4 Assured events
The following scenarios cause an increase in CPU usage:
•When a WebSphere MQ EP adapter is used, synchronous processing causes a WebSphere MQ Commit call at user task sync point time.
•When WebSphere MQ persistent queues are used, an MQPUT1 call results in more processing.
•When the user task is running on the QR TCB and events are emitted synchronously to a WebSphere MQ EP adapter, more TCB switches occur.
However, all these CPU overheads are relatively low.
8.3 Monitoring and statistics
CICS monitoring collects data about the performance of all user and CICS transactions during online processing for later offline analysis. The CICS Explorer (with the CICS Performance Analyzer plug-in) can be used to view the event processing monitor data.
CICS gathers statistics data about the system resource usage and the performance of the CICS system during online processing. Reports can be generated by using the sample statistics utility program (DFH0STAT) for the event processing, event binding, capture specification and EP adapter global and resource statistics.
8.4 Problem determination
There can be times when events that are expected to be received are not captured or when you capture more events than intended. The following tools can be used to determine why the expected number of events is different from the actual number captured:
•CICS Explorer
•CICS auxiliary trace
•Statistics utility program DFH0STAT
•CICS memory dump
•INQUIRE SPI
•CICSPlex SM WUI
In this section, it is demonstrated how to use some of these tools when expected events are not captured by event processing. It is explained why unexpected events are captured and how to determine why captured data is missing, incorrect, or contains only asterisks.
Information also is provided on which steps to take to find the cause of missing events that were captured but have not arrived at their destination and if the events are to be emitted through an HTTP EP adapter to IBM Operational Decision Manager or IBM Business Monitor.
In addition to the tools listed in this section, you can use the TSQ EP adapter and the sample custom EP adapter during problem determination to check the number of events and the data that is captured. The TSQ EP adapter can be configured to write CICS event objects to a TS queue in CICS flattened event format or XML format. The sample custom EP adapter writes them to a TS queue in a simplified flattened event format.
8.4.1 Events not captured
This section gives some examples of rudimentary checks to be performed on a CICS system to determine why expected events were not captured. In addition, this section describes techniques that can be used to determine why expected events are not captured when an order process is completed in the shopping sample application.
The first check to make is that CICS can capture events. Use the CICS Explorer Event Processing view to check the EVENTPROCESS status is set to STARTED. If EVENTPROCESS is STOPPED, no events are captured. In this case, EVENTPROCESS is started.
Next, check that the event binding is installed and enabled. This can be done by using the CICS Explorer. For more information, see 5.3, “Creating and installing a bundle definition” on page 88.
The master terminal commands CEMT INQUIRE EVENTPROCESS, CEMT INQUIRE EVENTBINDING, and CEMT INQUIRE BUNDLE also can be used to gather this information.
If these techniques return no information for the bundle (for example, zero records returned in the Bundles view in CICS Explorer) check that the bundle was successfully deployed to the zFS. When querying bundles and event bindings, remember items stored in the zFS can have case-sensitive names.
Check that the permissions are set on the zFS directory to which the bundle is deployed to allow the files to be added or updated.
See 5.5, “Security considerations for CICS events” on page 100, to determine the security controls that might be in place for the event binding resource because these govern who has the ability to inquire on and to update the event bindings.
Check if the event binding is replaced. It is possible to replace an installed event binding by deploying a second bundle with a different name that contains an event binding with the same name as the event binding that is already installed. The consequence of this might be that expected events are not captured. For more information, see 5.4.1, “Replacing a deployed bundle” on page 99. The techniques that are described in the following section also can be used to determine if the correct event binding is currently installed on the CICS system.
Use the Bundle Definitions view in the CICS Explorer to ensure that the bundle definition contains a valid zFS directory where the bundle is stored and then initiate the install of the bundle. For more information, see 2.5, “Deploying a CICS bundle to zFS” on page 46.
If the event binding specifies a predefined EP adapter or an EP adapter set, ensure that the EP adapters or EP adapter set are installed and enabled; otherwise, events are not emitted as expected. Use the EP adapters and EP adapter Sets views in the CICS Explorer to verify that the resources are installed and in the enabled state.
For synchronous application events, check that the emission and transaction modes are applicable for the EP adapter type that was specified in the event binding because not all EP adapters can support synchronous emission with all combinations of transaction mode. Synchronous emission is not supported for system events.
There are some circumstances under which transaction abends are handled by CICS, so if the events that are missing are for unhandled transaction abend system events, check if this is the case. For example, abends issued during CICS initialization and shutdown Program List Table (PLT) programs are handled by CICS. Abends issued by a CICS web support transaction are caught and handled by the CICS web support alias program DHWBA. In addition, abends issued by CECI commands are handled by an EXEC CICS HANDLE ABEND issued by the CECI transaction.
The event binding that is used in this section (ShoppingEventBinding) contains five event specifications and each has one capture specification, as described in 4.4, “The events emitted from the sample application” on page 76.
To generate events, run the sample application to order an item, fulfill the order, and ship the order. One event is expected to be captured for each of these tasks and one SIGNAL EVENT API call to be captured, for a total of four events.
The event binding is created to emit events to the TSQ EP adapter. In this scenario, when the sample application is run, it is found that no events are captured.
After making the initial checks that were described earlier in this section and after the Event Bindings and Bundles views in CICS Explorer are refreshed, it can be seen that the event binding is not installed and that the bundle is installed but has a status of disabled. This is an indication that something might be wrong with the event binding. There is a group of messages written to the CICS message log each time a BUNDLE resource is installed.
The first message to search for is DFHRL0107, which indicates that the CICS resource lifecycle manager started to create the BUNDLE resource. If the BUNDLE resource failed to be created, or if an event binding failed to be installed successfully, there are more messages that indicate the cause of the failure.
For example, in this instance message, DFHPI1007 is seen in the CICS message log that indicates a problem with the XML data in the event binding, as shown in Example 8-1.
Example 8-1 Message DFHRL0107 followed by DFHPI1007, problem with event binding
DFHRL0107 I 11/27/2012 12:13:26 EPRED5 CICSUSER The CICS resource
life-cycle manager has started to create the BUNDLE resource
SHOPPING.
DFHPI1007 11/27/2012 12:13:26 EPRED5 00075 XML to data
transformation failed because of incorrect input
(XML_FORMAT_ERROR Content data found outside root element) for
EVENTBINDING ShoppingEventBinding.
The next message to look for in the CICS message log is a message with the DFHEC prefix. In this example, DFHEC1003 appears, as shown in Example 8-2. This message is issued for several different reasons, as indicated in the reason at the end of the message. In this instance, the reason indicates BAD XML DATA. Message DFHRL0102 confirms that the event binding resource was not created.
Example 8-2 Messages showing an event binding was not created in CICS
DFHEC1003 11/27/2012 12:13:26 EPRED5 The CICS event capture component failed to create the EVENTBINDING resource ShoppingEventBinding in BUNDLE SHOPPING because XML data in the event binding could not be parsed.
DFHRL0102 E 11/27/2012 12:13:26 EPRED5 CEDA The CICS resource lifecycle manager failed to create the resource ShoppingEventBinding and returned with reason CALL_BACK_ERROR.
Examine the event binding to establish the cause of the bad XML. One cause of bad XML data is if the event binding is manually transferred from the CICS Explorer workspace on the local workstation to the zFS by using file transfer protocol (FTP) without specifying binary transfer.
Browse the event binding file in the zFS and check that the file is in ASCII format. If not, FTP the file again from the workstation specifying binary transfer or deploy the bundle from the CICS Explorer by right-clicking the bundle in the Project Explorer view and selecting Export Bundle Project to z/OS UNIX File System. In this instance, the bundle was installed as disabled because one part (the event binding) was not installed, so it is necessary to DISABLE the bundle again to ensure that all parts are disabled and DISCARD the bundle resource before you attempt to re-install the updated file.
When an event binding is successfully installed, the DFHRL0107 message is followed by DFHEC1001, as shown in Example 8-3, which confirms the event binding was created successfully. A separate EP adapter is created in CICS when Use an adapter defined here is selected on the adapter page in the event binding editor in CICS Explorer. This adapter has the same name as its associated event binding, so message DFHEP1001 also indicates the EP adapter was successfully installed.
Example 8-3 Showing a bundle, event binding and adapter installed successfully in CICS
DFHRL0107 I 11/14/2012 13:27:31 EPRED5 CICSUSER The CICS resource lifecycle manager has started to create the BUNDLE resource SHOPPING.
DFHRL0125 I 11/14/2012 13:27:31 EPRED5 CICSUSER BUNDLE resource SHOPPING is being created with BUNDLEID Shopping_Bundle and version 1.0.0.
DFHEP1001 11/14/2012 13:27:31 EPRED5 EPADAPTER ShoppingEventBinding from BUNDLE SHOPPING installed successfully.
DFHEC1001 11/14/2012 13:27:31 EPRED5 EVENTBINDING ShoppingEventBinding from BUNDLE SHOPPING installed successfully.
DFHRL0109 I 11/14/2012 13:27:31 EPRED5 CEDA The CICS resource lifecycle manager has created the BUNDLE resource SHOPPING and the BUNDLE is in the enabled state.
In CICS Explorer, the status of the bundle, event binding, and EP adapter can be seen in the Bundles, Event Bindings, and EP adapters views.
After the event binding and EP adapter are installed and enabled, run the shopping sample application again to order an item, fulfill the order, and ship the order. As before, four events are expected to be captured. However, only three events appear on the TS queue. Therefore, this section contains a sequence of steps to take to determine why the correct number of events are not received.
The event processing global statistics reports can provide more details about the number of events being generated. In Example 8-4, “Put events” shows the total number of captured events passed to the EP adapter through the dispatcher. “Normal events” shows the total number of normal priority events generated, as shown in Example 8-4.
Example 8-4 Extract from event processing global statistics
Put Events. . . . . . . . . . . . . : 3
Normal events . . . . . . . . . . . : 3
The event binding was configured with a TSQ EP adapter, so the line from the event processing global statistics is also relevant, as shown in Example 8-5.
Example 8-5 TSQ EP adapter data in event processing global statistics
Events to Tsqueue EP adapter. . . . : 3
However, because four events were expected but only three are shown in the statistics reports, it must be determined why one event was not generated.
In the first instance, view the event binding in the CICS Explorer event binding editor to determine if there is an obvious reason why the expected number of events are not captured by a particular capture specification. Check the filter predicates for errors that might lead to events not being captured. If the cause of the missing events cannot be determined from the event binding, generate the CAPTURESPEC resource statistics report by using the DFH0STAT sample statistics application.
CAPTURESPEC resource statistics lists details about each capture specification. Example 8-6 shows that events were received for the Order, Ship, and SendOrder events, but not for the Fulfill event (a QueryStock event is not expected because this part of the shopping sample application was not used).
Example 8-6 Capture specification resource statistics
CAPTURESPECs
EVENTBINDING Name . . . . . . . . . : ShoppingEventBinding
EPADAPTER Name. . . . . . . . . . . : ShoppingEventBinding
Enable Status . . . . . . . . . . . : Enabled
Events Capture
Capturespec name Capture point Captured Failures Event Name ________________________________________________________________________
Capturefulfill POST:PUT_CONTAINER 0 0 Fulfil
Current Program . .: UPDSTOCK Current Program Op . .:Equals
Current Transaction: Current Transaction Op:All
Current Userid . .: Current Userid Op . .:All
CaptureOrder POST:LINK_PROGRAM 1 0 Order
Current Program . .: Current Program Op . .:All
Current Transaction: Current Transaction Op:All
Current Userid . .: Current Userid Op . .:All
CaptureQueryEvent PROGRAM_INITIATION 0 0 QueryStock
Current Program . .: Current Program Op . .:All
Current Transaction: Current Transaction Op:All
Current Userid . .: Current Userid Op . .:All
CaptureShip POST:REWRITE 1 0 Ship
Current Program . .: SHIP Current Program Op . .:Equals
Current Transaction: Current Transaction Op:All
Current Userid . .: Current Userid Op . .:All
CaptureSendOrder POST:SIGNAL_EVENT 1 0 SendOrder
Current Program . .: Current Program Op . .:All
Current Transaction: Current Transaction Op:All
Current Userid . .: Current Userid Op . .:All
The capture specification for the Fulfill event is called Capturefulfill, and is designed to capture an event on a PUT CONTAINER API call in the program called UPDSTOCK when the container name equals OUTPUT and the stock level falls to less than 50.
So, generate and format a level 1 and 2 CICS auxiliary trace for the EC component to determine why the Fulfill event was not captured.
Within the trace, search for the group of ECEC entries that might relate to the following PUT CONTAINER API command:
EXEC CICS PUT CONTAINER(‘OUTPUT’)
FROM(UPDATE-OUT)
END-EXEC.
Find the entries that show the event for the PUT_CONTAINER predicate and the container name is OUTPUT, as shown in Example 8-7. “POST-CMD” indicates the event is captured after the command completes.
Example 8-7 CICS trace entry showing the PUT_CONTAINER predicate
AP 3530 ECEC ENTRY - FUNCTION(EVENT_CAPTURE) PARM_LIST(27049BD8) EVP_ADDRESS(260CFE31)
:POST-CMD(PUT_CONTAINER)
AB000000 00000000 01000100 27049BD8 *.......,.......................Q*
*................ *
00000000 000DD7E4 E36DC3D6 D5E3C1C9 *......................PUT_CONTAI*
09C3D6D5 E3C1C9D5 C5D90000 00 *NER..............CONTAINER... *
DD 0301 DDLO ENTRY - FUNCTION(LOCATE) DIRECTORY_TOKEN(26E1CF20) ENTRY_NAME(26E2F197)
LOCKING_MODE(CALLER) DIRECTORY_NAME(ECCS) NAME(....OUTPUT...........)
Continuing to search through the trace, it can be seen that the next ECEC trace entry confirms that the primary predicate matched. The container name is OUTPUT, as shown in Example 8-8 on page 186.
Example 8-8 CICS trace entry showing the primary predicate is matched
AP 353C ECEC EVENT - PRIMARY_PREDICATE MATCHED
40404040 00000000 00000000 00000000 *....OUTPUT ............*
The next ECEC trace entry, shown in Example 8-9, shows that the capture specification called Capturefulfill is being processed.
Example 8-9 CICS trace entry for the Capturefulfill capture specification
AP 353B ECEC EVENT - FILTERING CAPTURESPEC(Capturefulfill) EVENTBINDING(ShoppingEventBinding)
C38197A3 A4998586 A4938689 93934040 40404040 40404040 *Capturefulfill
E2889697 97899587 C5A58595 A3C28995 84899587 40404040 *ShoppingEventBinding
In this trace entry, the current program name is equal to UPDSTOCK, as was selected in the event binding (see Example 8-10).
Example 8-10 CICS trace entry showing the CURRENT_PGM predicate is true
AP 3534 ECEC EVENT - PREDICATE_TRUE - TESTING CURRENT-PROGRAM EQUAL
27289350 00040000 00000000 00000000 *..>DFHECFP ..l&............*
C5D5E36D D7C7D440 *............CURRENT_PGM *
*UPDSTOCK *
*UPDSTOCK
However, the following ECEC trace entry (see Example 8-11) gives an indication as to why the event is not captured. The test comparing the new level of stock (in the OUTPUT container) and the predicate of the filter value is found to be false. The values in this trace entry show that the current level of stock is 45, whereas the predicate specified in the event binding is less than 5.
Example 8-11 CICS trace entry showing the LESS_THAN predicate is false
AP 3539 ECEC EVENT - PREDICATE_FALSE - TESTING ZONED IN PARAMETER(FROM) LESS_THAN
00000000 001E0802 40050080 10021005 *..>DFHECFP ........ .......*
40404040 40404040 *............FROM *
*00045 *
*00005
The final trace entry confirms that this event was not captured, as shown in Example 8-12.
Example 8-12 CICS trace entry showing this event has not been captured
AP 3531 ECEC EXIT - FUNCTION(EVENT_CAPTURE) RESPONSE(OK) EVENTS(0)
To further confirm the findings within the trace, generate a CICS system memory dump by using the CEMT PER SNAP command. Format the memory dump by using Interactive Problem Control Facility (IPCS) on z/OS, with the VERBX CICS680 ‘EC=3’ command.
Search in the formatted memory dump for the sub-title Event Binding Summary. The Event Binding Summary section lists details about each event binding that is installed in the CICS system, along with all of the capture specifications, filter predicates, and the number of events that are captured for each event binding.
The important pieces in the summary for the event binding in this scenario can be seen in the following examples (Example 8-13, Example 8-14, and Example 8-15). The first line in the ECEVB control block contains the event binding name, its enable status, and the name of the EP adapter that is associated with the event binding, as shown in Example 8-13.
Example 8-13 The start of the ECEVB control block
ECEVB: ShoppingEventBinding UserTag=V001 EPAdapter=ShoppingEventBinding Enabled=Y
The ECCS: Entry shows this is the capture specification called Capturefulfill, along with the primary predicate of PUT_CONTAINER, for the container named OUTPUT, as shown in Example 8-14.
Example 8-14 Capture specification information in the ECEVB control block
ECCS: Capturefulfill PUT_CONTAINER(postcmd) group/func=3416 Events=0000000000000000 Failed=00000000 Specific Primary_Predicate: CONTAINER='OUTPUT '
The ECFP: Entries contain the filter predicates; CURRENT_PGM equals UPDSTOCK and data item at offset 13 (x’D’) in the OUTPUT container to be less than 00005, a shown in Example 8-15.
Example 8-15 Filter predicate information in the ECEVB control block
Filter type Keyword Op Offset Length …KB KM MN Value(up to 32chars)
ECFP: program CURRENT_PGM EQ 00000000 00000008 …00 00 00 'UPDSTOCK'
ECFP: fulldata_zoned FROM LT 0000000D 00000005 …05 00 10 '00005'
So, it was thought that the capture specification was designed to check for a stock level of less than 50, but the trace entries and the event binding summary in the formatted memory dump show that what was actually specified is a predicate of “stock level of less than 5” in the event binding. This is corrected by changing the application data predicate in the filtering view for the event binding in the CICS Explorer event binding editor and saving the event binding. Re-deploy the amended event binding to the zFS and re-install the bundle into CICS, to pick up the changes made to the event binding.
8.4.2 Unexpected events captured
To determine why more events are being captured than expected, start by identifying which capture specification is capturing the unexpected events by using the statistics utility program DFH0STAT. Install the group DFH$STAT and run the STAT transaction. Press PF4 Reports and scroll to the page that contains the CAPTURESPECs report, select it, and press Enter to generate the report.
The CAPTURESPECs report (as shown in Example 8-16) lists the capture specifications for the event bindings and the number of events that are captured for each capture specification. So, if there are more than an expected number of events generated, the capture specification that is generating the extra events can be quickly identified.
Example 8-16 The CAPTURESPECs statistics report
CAPTURESPECs
EVENTBINDING Name . . . . . . . . . : ShoppingEventBinding
EPADAPTER Name. . . . . . . . . . . : ShoppingEventBinding
Enable Status . . . . . . . . . . . : Enabled
Events Capture
Capturespec name Capture point Captured Failures Event Name
Capturefulfill POST:PUT_CONTAINER 1 0 Fulfil
Current Program . .: UPDSTOCK Current Program Op . .:Equals
Current Transaction: Current Transaction Op:All
Current Userid . .: Current Userid Op . .:All
CaptureOrder POST:LINK_PROGRAM 1 0 Order
Current Program . .: Current Program Op . .:All
Current Transaction: Current Transaction Op:All
Current Userid . .: Current Userid Op . .:All
CaptureQueryEvent PROGRAM_INITIATION 0 0 QueryStock
Current Program . .: Current Program Op . .:All
Current Transaction: Current Transaction Op:All
Current Userid . .: Current Userid Op . .:All
CaptureShip POST:REWRITE 1 0 Ship
Current Program . .: SHIP Current Program Op . .:Equals
Current Transaction: Current Transaction Op:All
Current Userid . .: Current Userid Op . .:All
CaptureSendOrder POST:SIGNAL_EVENT 1 0 SendOrder
Current Program . .: Current Program Op . .:All
Current Transaction: Current Transaction Op:All
Current Userid . .: Current Userid Op . .:All
For this example, use the capture specification called Capturefulfill. To check why the event was generated for the Capturefulfill capture specification, generate and format a CICS auxiliary trace that contains level 1 and 2 trace entries for the EC component. By using the information from the CAPTURESPEC statistics, search for the ECEC trace entries that relate to the capture specification named Capturefulfill, as shown in Example 8-17.
Example 8-17 CICS trace entry showing the capture specification name
AP 353B ECEC EVENT - FILTERING CAPTURESPEC(Capturefulfill) EVENTBINDING(ShoppingEventBinding)
C38197A3 A4998586 A4938689 93934040 40404040 40404040 *Capturefulfill
E2889697 97899587 C5A58595 A3C28995 84899587 40404040 *ShoppingEventBinding
Before this entry in the trace, find the ECEC EVENT entry with PREDICATE_TRUE, as shown in Example 8-18. The predicate of “Less than 50” for the new stock level is found to be true, as the actual stock level is 45, so the event is captured.
Example 8-18 CICS trace entry showing the LESS_THAN predicate is true
AP 3534 ECEC EVENT - PREDICATE_TRUE - TESTING ZONED IN PARAMETER(FROM)LESS_THAN
00000000 001E0802 40050080 10021005 *..>DFHECFP ........ .......*
40404040 40404040 *............FROM *
*00045 *
*00050
The two previous examples (Example 8-17 and Example 8-18) show why the event was captured for this capture specification. The use of this technique can help to determine why unexpected events are captured. In the examples that are used here, the events were expected.
If too many events are being emitted to an EP adapter, use the EVENTPROCESS global statistics to identify the number of events that are destined for each EP adapter type, as shown in Example 8-19 on page 190.
Example 8-19 Extract from Event Processing Global Statistics showing the number of events emitted
Events to WebSphere MQ EP adapter . : 0
Events to Transaction EP adapter. . : 0
Events to Tsqueue EP adapter. . . . : 3
Events to Custom EP adapter . . . . : 0
Events to HTTP EP adapter . . . . . : 0
8.4.3 Capture data is not as expected
The payload captured along with an event can include application context data, command options, and items of application data. If the data that is captured is not the data that was expected, here are some approaches that can be used to identify the cause.
If some or all of the application data is missing from the expected payload, this might be because of an optional parameter, channel, or container not being present on the API command at the time the event is captured. It also might be because of a container, data area, or COMMAREA that was provided that is too short to hold the data item.
If all of the expected data is missing, gather a CICS auxiliary trace with level 1 and 2 data for the EC component. Format the trace and search for the phrase “UNAVAILABLE_DATA” within an ECEC trace record. The trace record contains the source of the data and ECEC trace records before this identifies the capture specification for this event. With this information, check the circumstances under which data is expected to be captured. For example, there might be occasions when the data is genuinely not available. In this instance, adjust the predicate information in the event binding to allow for this.
If data was captured with the event but it is not the correct data, this might be caused by incorrect capture information in the capture specification. This can be verified by viewing the information sources for the event binding in the CICS Explorer event binding editor. Check that the correct data types, lengths, offsets, and sources were used for the emitted business information. For example, the data might include fields of different formats, so check that all the data formats were specified correctly in the capture specification. A CICS auxiliary trace with level 1 and 2 entries for the EC component can help identify these fields.
Capturing data from the wrong parameter or container or specifying the wrong offset, length, or both in the capture specification might also lead to incorrect data being seen in the event. In this instance, a CICS dump formatted for the EC component is useful. Capture and format the memory dump as described in 8.4.1, “Events not captured” on page 180.
Search the Event Binding Summary in the dump and find the event binding and capture specification that is generating the incorrect data.
The ECCD: Entry (or entries, if there is more than one item of data being captured) for this capture specification contains the data that is being captured, its length, and where it is being captured from. Use this to identify any incorrect information in the capture specification of the event binding.
Alternatively, use the INQUIRE SPI commands CAPOPTPRED, CAPDATAPRED, and CAPINFOSRCE to browse the option and data filter values and the information sources that are contained in the capture specifications of the event bindings that are installed in your CICS region.
If the captured data is numeric and is too large for the formatted field length, the entire field is replaced with asterisks. Check the length that is specified in the capture specification and adjust as necessary. The event data also contains asterisks if the data that is requested to be captured is missing entirely.
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.