Setting up CICS for events
This chapter describes how to set up CICS for events. It shows how to configure CICS TS for event processing and use the CICS Explorer to control event processing. The CICS Explorer provides the development tooling environment that is needed to create an event binding.
This chapter assumes that you already have a CICS bundle deployed on zFS that contains an event binding. You are shown how to deploy, install, and manage bundles in CICS. For more information about how to create bundles and event bindings, see Chapter 6, “Capturing application events” on page 107.
This chapter also provides information about the various CICS security options that relate to CICS event processing. An example of how to protect access to bundles and event bindings also is provided. The External Security Manager (ESM) that is used in this case is IBM Resource Access Control Facility (RACF®).
This chapter includes the following topics:
5.1 CICS Explorer setup
This section describes how to obtain the CICS Explorer and connect it by using the CICS management client interface (CMCI) to the IBM CICSPlex SM web User Interface (WUI).
For more information about the use of and connecting the CICS Explorer to CICS, see the CICS Information Center at this website:
5.1.1 Obtaining the CICS Explorer
This section shows you how to install and configure CICS for event processing by using the CICS Explorer. This chapter uses CICS Explorer V5.1, which can be used to manage CICS TS V5.1 and V4. The CICS Explorer can be downloaded from this website:
After you install the CICS Explorer, use the EPREDW section to connect it to our CICSPlex SM WUI.
5.1.2 CICS Explorer connectivity
Complete the following steps to connect to our CICSPlex SM WUI server:
1. In the CICS Explorer Host Connections view, highlight CICS System Management and click Add. Select CMCI from the menu, as shown in Figure 5-1.
Figure 5-1 CICS Explorer Host Connections view: Adding a CMCI connection
 
Important: We use the connection type CICS Management Interface to enable update capability. The default connection type CICSPlex SM Data Interface allows read-only capability.
Our WUI server (Hostname: wtsc66.itso.ibm.com) has port 1491. The CMCIPORT system initialization parameter for our WUI is set as CMCIPORT=1491, as shown in Figure 5-2 on page 84.
Figure 5-2 Add CMCI Connection dialog
For more information about how to set up the CMCI in CICS, see this website:
2. Click Save and Connect. You are prompted to enter your user name and password, if required.
The CICS Explorer is now connected to your CICSPlex via a CMCI Connection.
5.1.3 The CICS event binding editor
The CICS event binding editor is supplied as part of the CICS Explorer, which was downloaded in 5.1.1, “Obtaining the CICS Explorer” on page 82. Chapter 6, “Capturing application events” on page 107shows how this is used to create event bindings.
5.2 CICS System setup
This section reviews the CICS system setup that is required to implement events in CICS.
5.2.1 Adding TCP/IP support to use the HTTP EP adapter
The shopping application uses the HTTP EP adapter to format and process events. To use the HTTP EP adapter, CICS must be enabled for TCP/IP.
In the CICS SIT, set TCPIP=YES, as shown in Example 5-1.
Example 5-1 CICS SIT showing TCP/IP
APPLID=EPREDA01
SYSIDNT=RED7
START=INITIAL
GRPLIST=(DFHLIST,EPREDA01)
TCPIP=YES
5.2.2 Enabling CICS event processing
Event processing is enabled by default when a START=INITIAL or START=COLD parameter is used during the startup of your CICS TS systems.
When a START=WARM or START=EMERGENCY parameter is used, the settings from the previous run of CICS are used. So, unless the setting changed, event processing should be enabled. You can inquire on EVENTPROCESS to check this; for example, by using the CICS Explorer.
You can stop and start event processing from the IBM CICS Explorer, the CICSPlex SM WUI, or the CICS SPI or API commands. For example, you might want to stop event processing during an upgrade or system maintenance and then restart event processing.
CICS event processing can be set by using three possible states: START, DRAIN, or STOP.
DRAIN causes event capture to stop but allows events that were captured to be processed through the system and emitted. Transactional events are not emitted if the unit of work had not reached sync point at the time the DRAIN request is received. STOPPED causes event processing to stop immediately, with no further events captured or emitted.
5.2.3 Stopping CICS event processing
Complete the following steps to stop event processing in the CICS region:
1. By using the CICSplex Explorer view, select the CICSplex or CICS region for which you want to stop event processing.
2. By using the IBM CICS Explorer toolbar, click Operations → Event Processing → Event Processing to open the Event Processing view, as shown in Figure 5-3. The current status of event processing is shown.
Figure 5-3 Opening the Event Processing view in the CICS Explorer
3. Right-click the region where you want to stop event processing and click Stop, as shown in Figure 5-4 on page 87.
Figure 5-4 Stopping Event Processing in the CICS Explorer
4. A window opens in which you can confirm the action that you are about to perform, as shown in Figure 5-5. Click OK to continue.
Figure 5-5 Perform action confirmation
The STOPPED status displays, which indicates that event processing is stopped, as shown in Figure 5-6.
Figure 5-6 Event Processing Stopped
5. To restart event processing, right-click the region where you want to start event processing and click Start. Click OK.
5.3 Creating and installing a bundle definition
This IBM Redbooks publication uses the CICS Explorer to define and install bundle resources. Other mechanisms (such as CEDA) also can be used.
The following tasks are performed by using CICS Explorer:
•Create a bundle resource definition (BUNDDEF resource).
•Install a bundle resource into CICS.
Bundles and event bindings
A bundle resource is a type of resource that was introduced in CICS TS V4.1. A bundle resource defines a bundle, which is a unit of deployment for an application. A bundle is a collection of CICS resources, artifacts, references, and a manifest that you can deploy into a CICS region to represent an application. CICS bundles can describe various CICS resources types, one of which is an event binding.
A bundle is deployed to z/OS UNIX file system (or zFS) and is a directory structure that contains artifacts. The bundle resource defines where the bundle is deployed on z/OS UNIX and its status.
To deploy your event binding file to a CICS system, you must first export the bundle that contains it to zFS. You then install the bundle resource that points to the bundle on the zFS. This can be done by using IBM CICS Explorer, the CICSPlex WUI, the RDO CEDA transaction, or the DFHCSDUP utility.
5.3.1 Creating a new CICS bundle definition
This section describes how to define a bundle resource that is named SHOPEVE, which references the sample bundle that is called ShoppingEventBundle_1.0.0, as described in Appendix B, “Additional material” on page 243. You should extract the bundle to an zFS directory, as shown in Example 5-2.
Example 5-2 Sample event binding in sample bundle
/u/cicsrs2/bundles/ShoppingEventBundle_1.0.0/
Type Filename
_ Dir .
_ Dir ..
_ Dir META-INF
_ File ShoppingEventBinding.evbind
Creating and deploying bundles: When you create and deploy your bundles to zFS by using the CICS Explorer, you should ensure proper management of the bundle source code. The bundle cannot be reconstructed from the exported data in zFS, and a failure of your workstation can cause the data to be lost. You can use the Export function of CICS Explorer to export the bundle and check it in to a source code management system.
Use the New Wizard in CICS Explorer to create a bundle resource definition that can then be installed in one or more active CICS systems, as shown in Figure 5-7 on page 90. For the purposes of this example, you should use CICS TS V4.2 or higher. This is because the sample bundle contains features (such as a separate EP adapter) that were introduced in V4.2.
Figure 5-7 Opening New Wizard
You enter the basic details that are needed to create the resource by using the New Wizard and add information by using the editor. You must be connected to a CICS version V4.1 (or above) system to create resource definitions.
Complete the following steps to create a resource:
1. Open the New Wizard by completing the following steps:
a. Click Explorer → New Wizards → Other.
b. Select Bundle Definition and click Next, as shown in Figure 5-8.
Figure 5-8 Creating a BUNDDEF
2. The New Bundle Definition window opens, as shown in Figure 5-9.
Figure 5-9 Specifying bundle definition options
3. If you selected a CICSplex before you opened the wizard, the CICSplex field contains the name of the CICSplex. You can type over the name or, if the field is empty, enter a new name. The light bulb symbol next to the text field shows that content assist is available. When you press Ctrl+space, content assist displays a list of the possible choices for the field. You can double-click a name in the list to select the CICSplex.
4. If you selected a resource group before you opened the wizard, the Resource Group field contains the name of the resource group, and the CICSplex field contains the name of the CICSplex. You can type over the name or, if the field is empty, enter a new name. In this case, the Resource Group field is left blank so as not to create a resource group.
 
5. Complete the remaining fields in the wizard. This example specifies a Bundle Directory value of /u/cicsrs2/bundles/ShoppingEventBundle_1.0.0/, because that was the zFS directory where the bundle was previously exported.
6. If you want to save the new resource and immediately open it in the editor, ensure that the Open editor option is selected.
7. Click Finish and your bundle definition is created. In this case, the new definition is saved onto the CPSM repository.
 
New definition: When you are creating a definition with the CICS Explorer, the definition panel that opens for your specified new resource prompts you to supply the required parameters to complete the definition. Field help is available by pressing the PF1 key on any of the parameter fields. If you want to define further options for your definition, select the open editor and click Finish. The editor opens and you can specify other attributes for your definition
5.3.2 Installing a bundle definition into CICS
When a bundle is installed into CICS, the various resources that it contains are each installed as a result. This allows the resources in the bundle to be managed as a group. To install an event binding into CICS, install the bundle in which it is included.
When an event binding is installed, the capture specifications that are associated with the events in the binding are deployed into CICS and the run time starts to capture events where they match the filtering that is specified in the capture specifications.
An event binding is installed by installing the bundle resource for the bundle that contains it. If the bundle resource specifies enabled as its initial state, this also enables the event binding if the install action succeeds.
Complete the following steps to install the bundle by using the IBM CICS Explorer:
1. From the IBM CICS Explorer toolbar, click Definitions → Bundle Definitions to view the list of bundle resource definitions, as shown in Figure 5-10 on page 94.
Figure 5-10 Bundle definitions to view the list of BUNDDEF resource definitions
2. Right-click the event binding bundle definition name in the Bundle Definitions view and click Install, as shown in Figure 5-11. On the Install action panel, select the appropriate target CICS system or system group option where you want to install your event binding bundle and click OK.
Figure 5-11 Install bundle definitions
The message CNX0551I Install of BUNDDEF definitions into EPREDA01 successful displays. The bundle that contains the event binding installs in the specified CICS region. CICS also dynamically creates any other resources that are defined in the bundle.
What to do next
After the resource definition installs successfully, you can view the status of installed event bindings or bundles. To do this, open the various resource views from the Operations menu on the CICS Explorer toolbar. Figure 5-12 shows the various views that are available.
Figure 5-12 Operational views for Bundles and Event Processing resources
5.4 Enabling and disabling and discarding events
This section shows how to enable, disable, and discard event bindings or bundles by using the CICS Explorer.
If you disable an event binding resource, CICS also disables the bundle resource that contains it. However, any other resources that are part of the bundle remain in an enabled state in the CICS region. If you re-enable the event binding successfully, the bundle resource also changes to the enabled state.
 
Tip: Because a bundle is the unit of deployment for an application, it is recommended that you enable, disable, and discard the bundle resource only. However, it can still be useful to disable individual event bindings to effectively turn off the emission of particular events.
Complete the following steps to disable and discard an event binding:
1. Select Operations → Event Processing → Event bindings or Operations → Bundles to open the Event Bindings or Bundles views, as shown in Figure 5-13 on page 96.
Figure 5-13 Working with event bindings
2. You can disable event bindings or bundles right-click in these views. Click to select your event binding, then right-click to disable, as shown in Figure 5-14.
Figure 5-14 Disabling the ShoppingEventBinding event binding
3. Click OK, as shown in Figure 5-15.
Figure 5-15 Confirmation panel for disable
The event binding is disabled, as shown in Figure 5-16.
Figure 5-16 Disabled ShoppingEventBinding event binding
4. In the Bundles view, you can now right-click and discard SHOPEVE bundle, as shown in Figure 5-17 on page 98.
Figure 5-17 Discarding a disabled bundle
5. Click OK and the bundle resource is discarded, as shown in Figure 5-18. The event binding also is discarded.
Figure 5-18 Confirm discard request
 
Important: When you disable an event binding, the bundle state changes to disabled. If you try to discard a disabled bundle resource when enabled resources that belong to the bundle are in the CICS region, CICS issues a message and the discard fails, as show in Figure 5-19. You must disable each of the enabled resources before the bundle resource is discarded. You can right-click Disable a bundle to disable all of its associated resources.
Figure 5-19 Discard of bundle fails
5.4.1 Replacing a deployed bundle
The following methods can be used to replace a deployed bundle after it is installed:
•Disable, discard, and then install the changed version of a bundle with the same name. No events are emitted from the moment the bundle is disabled until the moment the install completes successfully.
•You can replace a bundle without disabling the event binding by creating a new bundle, which must have a different name from the original bundle and contains the event binding with the same name. Events continue to be emitted until the bundle install completes successfully, at which point the new binding replaces the previous version.
5.5 Security considerations for CICS events
New security-related resources were added to support event processing in CICS TS. This section describes these new resources and shows how to set up CICS and the External Security Manager (ESM), in this case RACF, to protect event processing resources from unauthorized access.
5.5.1 Changes to security
Resource and command security apply to all event processing resources when these functions are enabled for the CICS region.
New category 1 transactions
The following transactions are category 1:
•CEPD: The event dispatcher, which is implemented by DFHEPDS.
•CEPM: The event queue manager, which is implemented by DFHEPSY.
•CEPF: The deferred filtering task for system events, which is implemented by DFHECDF.
•CRLR: The bundle resource resolver, which is implemented by DFHRLR.
These transactions are defined internally.
Resource security
Resource security for event processing resources uses resource profiles in the RCICSRES class, the WCICSRES grouping class, or equivalent customer-defined classes that are specified in the XRES system initialization parameter.
You must supply the following prefixes:
•EVENTBINDING to the name of the EVENTBINDING resource definition.
•EPADAPTER to the name of the EPADAPTER resource definition.
•EPADAPTERSET to the name of the EPADAPTERSET resource definition.
•CAPDATAPRED to the name of the CAPDATAPRED resource definition.
•CAPINFOSRCE to the name of the CAPINFOSRCE resource definition.
•CAPOPTPRED to the name of the CAPOPTPRED resource definition.
•CAPTURESPEC to the name of the CAPTURESPEC resource definition.
An example of this is shown in Example 5-4 on page 102.
Command security
Command security for event processing resources uses the following resources in the CCICSCMD class or the VCICSCMD grouping class:
•EVENTPROCESS
•EVENTBINDING
•EPADAPTER
•EPADAPTERSET
•CAPDATAPRED
•CAPINFOSRCE
•CAPOPTPRED
Security that uses the XRES resource security parameter
The XRES system initialization parameter is used to security check CICS resources.
CICS profiles are passed to the security manager for checking. For more information, see CICS Information Center at this website:
5.5.2 Setting up CICS security for event bindings
This section shows how to use an ESM (in this case, RACF) to protect access to the eventbinding resource.
The CMAS in this example has simulated CICS Resource Security enabled.
In the SIT for CICS EPREDA01, the security options are set as shown in Example 5-3. The XRES option is the specific option that is needed to enable resource checking.
Example 5-3 CICS SIT security options
SEC=YES
XAPPC=NO
XCMD=NO
XDB2=NO
XDCT=NO
XEJB=NO
XFCT=NO
XJCT=NO
XPCT=NO
XPPT=NO
XPSB=NO
XRES=YES
XTRAN=NO
XTST=NO
RACF definitions
This example shows how to protect the BUNDLE, which is named SHOPEVE. This bundle contains an EVENTBINDING called ShoppingEventBinding.
From the TSO command prompt, run the commands that are shown in Example 5-4to define profiles in RACF for the BUNDLE and EVENTBINDING in the RCICSRES class. This permits the user ID CICSRS7 to use these profiles.
Example 5-4 RACF Permissions for BUNDLE and EVENTBINDING
RDEFINE RCICSRES BUNDLE.SHOPEVE UACC(NONE))
PERMIT BUNDLE.SHOPEVE CLASS(RCICSRES) ID(CICSRS7) ACCESS(ALTER)
RDEFINE RCICSRES EVENTBINDING.ShoppingEventBinding UACC(NONE)
PERMIT EVENTBINDING.ShoppingEventBinding CLASS(RCICSRES) ID(CICSRS7) ACCESS(ALTER)
 
Important: RACF profile definitions and security checking are case-sensitive.
Run the RACF SETROPTS command to refresh the RCICSRES class. Specify ALTER access above as this is needed to allow the user ID CICSRS7 to DISCARD an event binding or bundle.
With these options set, the CICS user ID CICSRS7 can see bundle SHOPBUN and event binding ShoppingEventBinding by using the CICS Explorer. This user ID also can INSTALL a bundle definition and DISABLE or DISCARD this event binding and bundle.
A user ID other than CICSRS7 cannot see the event bindings or bundles that are installed in the CICS region. An attempt to access these resources does not generate a security error message in the CICS Explorer. This is a feature of how CICS works. To help explain this feature, compare the behavior for an unauthorized user of the CICS Explorer with the way in which CEMT INQUIRE EVENTBINDING works.
For example, by using CEMT INQUIRE EVENTBINDING(*) with generic target generates a NOTFOUND response, even when the user ID that is running the command is not authorized to the EVENTBINDING profile, as shown in Example 5-5 on page 103.
Example 5-5 CEMT INQUIRE EVENTBINDING: Generic
I EVENTBINDING(*)
STATUS: RESULTS - OVERTYPE TO MODIFY
Eventb(* ) NOT FOUND
 
SYSID=RED7 APPLID=EPREDA01
RESPONSE: 1 ERROR TIME: 06.30.15 DATE: 07/14/09
Whereas, a CEMT INQUIRE EVENTBINDING that specifies the event binding name receives a NOT AUTHORIZED response, as shown in Example 5-6.
Example 5-6 CEMT INQ EVENTBINDING - specific
I EVENTB(SHOPPINGEVENTBINDING)
STATUS: RESULTS - OVERTYPE TO MODIFY
Eventb(SHOPPINGEVENTBINDING ) NOT AUTHORIZED
 
SYSID=RED7 APPLID=EPREDA01
RESPONSE: 1 ERROR TIME: 09.35.53 DATE: 07/10/09
PF 1 HELP 3 END 5 VAR 7 SBH 8 SFH 9 MSG 10 SB 11 SF
In the CICS job log, we see the security violation message that shows that the CICS default user CICSUSER is not authorized, as shown in Example 5-7.
Example 5-7 CICS job log showing security violation
DFHXS1111 07/14/2009 09:35:53 EPREDA01 CEMT Security violation by user CICSUSER for resource EVENTBINDING.SHOPPINGEVENTBINDING in class RCICSRES. SAF codes are (X'00000008',X'00000000'). ESM codes are (X'00000008',X'00000000').
Because the CICS Explorer obtains all of the attributes for all event bindings and then applies a filter to the results, it does not generate a security violation.
For example, if a user that is signed on to the CICS Explorer attempts to see event bindings for which they are not authorized, the event bindings are not displayed.
Details of the CICS Explorer signed-on user ID and password are entered in the CICS Explorer connection panel.
 
Important: To install a bundle resource (BUNDDEF) from the CICS Explorer that is connected to CICSPlex SM WUI and uses CICSPlex simulated resource security (as in this case), a CICSPlex APAR PK91529 is required.
5.5.3 The user ID in EP adapters
EP adapters can emit events by using the user ID from the security context at the time of event capture or you can specify an ID in the adapter that is used for event emission. It is useful to specify an ID when you do not want to grant permission to the application’s task ID to use the event emission transport but you still want to emit events.
When you install a BUNDLE resource that includes an EP adapter for which you specified a user ID, CICS checks that the user ID that is performing the install operation is authorized as a surrogate user of the specified user ID. This check also applies to the CICS region user ID during group list install on a CICS cold or initial start.
This example specifies a user ID CICSRS9 in the EP adapter, as shown in Figure 5-20 on page 105. It also shows how to set up the security authorization that is required to install the bundle that contains this EP adapter during an initial start of CICS with an RDO definition that is added to the CICS group list.
Figure 5-20 Adapter with user ID specified
With user ID CICSRS9 set in the EP adapter, you can attempt to INITIAL start CICS and install the bundle SHOPEVE through an RDO group SHOPBUND that is included in the CICS group list. The install of the event binding ShoppingEventBinding now fails with a security violation as expected, as shown in Example 5-8 on page 106.
Example 5-8 Security violation
DFHRL0107 I 07/15/2009 12:48:38 EPREDA01 CICSRS7 The CICS resource life-cycle manager has started to create the BUNDLE resource SHOPEVE.
DFHXS1111 07/15/2009 12:48:38 EPREDA01 CSSY Security violation by user CICSRS7 for resource CICSRS9.DFHINSTL in class SURROGAT. SAF codes are (X'00000004',X'00000000'). ESM codes are (X'00000004',X'00000000').
DFHEC1010 07/15/2009 12:48:38 EPREDA01 Userid CICSRS7 is not authorized to create EVENTBINDING  ShoppingEventBinding  with  an  EP  adapter  userid  of  CICSRS9.
DFHRL0102 E 07/15/2009 12:48:38 EPREDA01 CSSY The CICS resource life-cycle manager failed to create the resource ShoppingEventBinding
and returned with reason CALL_BACK_ERROR.
DFHAM4893 I 07/15/2009 12:48:38 EPREDA01 Install for group SHOPBUND has completed successfully.
Now issue the RACF commands in TSO to allow the install to work, as shown in Example 5-9.
Example 5-9 RACF command
RDEFINE SURROGAT CICSRS9.DFHINSTL UACC(NONE) OWNER(CICSRS9)
PERMIT CICSRS9.DFHINSTL CLASS(SURROGAT) ID(CICSRS7) ACCESS(READ)
Issue RACF SETROPTS to refresh the SURROGAT class profile and then try to INITIAL start CICS. This time it is successful, as shown in Example 5-10.
Example 5-10 Initial start of CICS
DFHRL0107 I 07/15/2009 12:58:14 EPREDA01 CICSRS7 The CICS resource life-cycle manager has started to create the BUNDLE resource
SHOPEVE.
DFHEC1001 07/15/2009 12:58:14 EPREDA01 Event binding ShoppingEventBinding installed successfully.
DFHRL0109 I 07/15/2009 12:58:14 EPREDA01 CSSY The CICS resource life-cycle manager has created the BUNDLE resource SHOPEVE and the
BUNDLE is in the enabled state.
DFHAM4893 I 07/15/2009 12:58:14 EPREDA01 Install for group SHOPBUND has completed successfully.
 
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset