You can customize normal CICSPlex® SM workload management processing by modifying the module EYU9WRAM.
EYU9WRAM uses the CICSPlex SM dynamic routing application programming interface (API), which is a special-purpose, call-level interface that provides the mechanism needed to request workload management actions. All calls are constructed using standard CALL statements. The CALL statement generates the linkage between the EYU9WRAM module and the CICSPlex SM Workload Manager component. The format of the CALL statement is shown here:
CALL WAPIENPT(DA_TOKEN,function)
where:
You can use SM_SCOPE and SM_BALANCE together to obtain a list of target regions and then select the target region to which a transaction is to be routed.
If you know that a transaction is always to be directed to a specific target region, you can use just SM_ROUTE.
As distributed, EYU9WRAM issues SM_SCOPE and SM_BALANCE calls. It does not include any SM_ROUTE calls. It includes unexecuted calls to SM_CREAFF and SM_DELAFF. You can modify the program to issue these calls as desired.
Although all of the examples in this chapter use the assembler language form of the dynamic routing API verbs, you can also use these verbs in programs written in C, COBOL 2, and PL/I. Sample programs distributed with CICSPlex SM contain examples of the CALL statements for each of these languages.
As distributed, EYU9WRAM handles the workload balancing and separation established via the workload management definitions by using the API verbs. Any changes you make to EYU9WRAM, therefore, may adversely impact the CICSPlex SM workload management facilities. For example, if you do not use SM_SCOPE, SM_BALANCE, or SM_ROUTE, each transaction occurrence is routed to the default target region identified when the transaction was defined to CICS®. Thus, all CICSPlex SM workload management definitions are bypassed.
For CICS/ESA 4.1 and later, you do not need to include any calls through the API if a transaction is statically routed or is started by ATI. In these cases, the target region may not be changed. The routing function in those cases will be route notify. The route notify function is intended to notify the EYU9WRAM program that such a transaction is being routed.
If you do include any of these functions, the following occurs:
When EYU9WRAM is called for:
When routing a transaction associated with either a CICS BTS activity or a non-terminal-related EXEC CICS START comand, the routing program, identified in the DSRTPGM SIT parameter, is invoked for both static and dynamic routing. In the case of statically routed transactions, the EYU9WRAM program cannot alter the target region; see Nondynamic transaction considerations. In the case of dynamically routed transactions, the EYU9WRAM program may alter the target region; see Selecting a target region from a set of target regions. However, in both cases, the EYU9WRAM program is invoked only for:
For details of the function of route initiation, see CICS Intercommunication Guide.
When routing a transaction associated with an enterprise bean invocation, the routing program, identified in the DSRTPGM SIT parameter, is invoked for both static and dynamic routing. In the case of statically routed transactions, the EYU9WRAM program cannot alter the target region; see Nondynamic transaction considerations. In the case of dynamically routed transactions, the EYU9WRAM program may alter the target region; see Selecting a target region from a set of target regions. However, in both cases, the EYU9WRAM program is invoked only for:
In the target region:
For details of the function of route initiation, see CICS Intercommunication Guide.
As distributed, EYU9WRAM uses SM_SCOPE and SM_BALANCE to select a target region from the list of target regions defined for a transaction. Specifically, issuing:
After an SM_SCOPE or SM_BALANCE call, the result of the operation is indicated in the response and reason fields of the EYURWCOM communication area.
A dynamic route selection occurs when a transaction or program is scheduled for routing.
During SM_BALANCE processing, the target region appearing first in the ordered list is selected for routing, unless the scope vector element EYURWSVE is marked ignore.
During SM_BALANCE processing, the APPLID and SYSID of the most suitable target region are placed in the fields WCOM_SEL_AOR and WCOM_SEL_SYSID, respectively. Typically, this will be the first target region represented in the scope vector. However, if the EYU9WRAM program has marked the WSVE-IGNORE field on some of the SCOP_VECT elements to denote that the target region is to be ignored, the first target region in the scope vector which is not marked to be ignored will be selected.
The EYU9WRAM module may opt to reject the transaction prior to issuing the SM_SCOPE call. In this case, the Workload Manager returns to CICS/ESA with the reject indicator set to Y in the DFHDYPDS communication area. The sample EYU9WRAM program causes a DTRTRAN transaction to be rejected only if the transaction identifier is all blanks.
Notification occurs when a static transaction or ATI transaction is being scheduled for routing.
None, but you can tidy up and release any resources at this stage.
A route selection error call occurs if the CICS link between the requesting region and target region is not available or is not defined.
Transaction termination occurs when a transaction has terminated normally.
Transaction abend occurs when a transaction has terminated abnormally.
Transaction initiation occurs when a CICS BTS-related transaction, or an enterprise bean-related transaction, has been routed to the target region. No specific action is taken. The call is issued for information purposes only.
SM_ROUTE requests that a specific target region be selected for routing. Use SM_ROUTE when you have application- or data-dependent requirements for explicit routing. For example, you might want to route a transaction associated with a specific user ID to a specific target region.
After an SM_ROUTE call, the result of the operation is stored in the response and reason fields of the EYURWCOM communication area.
A sample SM_ROUTE call is show here:
CALL WAPIENPT(DA_TOKEN,SM_ROUTE)
DA_TOKEN identifies the dynamic routing API token supplied via the EYURWCOM communication area. This token is used by EYU9WAPI and must not be altered.
The actions during route selection are:
If there are multiple connections between a requesting region and the target region, supply both the SYSID and the APPLID, as described previously, to ensure that the correct target region is selected. Note that when both the SYSID and APPLID are supplied, they are not validated.
The target region need not be defined to CICSPlex SM. The affinity status is not checked. Thus, no affinity is established as a result of this call and, if an affinity was in effect, it is ignored.
None, but you can tidy up and release any resources at this stage.
The EYU9WRAM program may issue a message and terminate. You may then issue SM_ROUTE again specifying a different target region, or issue SM_SCOPE and SM_BALANCE.
At transaction initiation:
You can use SM_CREAFF to create an affinity if one does not already exist in the transaction group established for the transaction. The transaction group must be defined with an affinity type and lifetime. The affinity created will have the same affinity type and lifetime as defined in the transaction group.
You should review Affinity considerations before using SM_CREAFF.
Prior to calling SM_CREAFF, you must first call SM_SCOPE to obtain a scope list. SM_CREAFF will not create an affinity to an target region that is not in the scope list. In addition, you should set the EYUWRCOM communication area fields WCOM_SEL_AOR and WCOM_SEL_SYSID to the APPLID and SYSID, respectively, of the target region for which you want the affinity created.
EYU9WRAM contains a fragment of unexecuted code that you can use as a template for implementing the SM_CREAFF function.
The SM_CREAFF function cannot be called during:
You can use SM_DELAFF to delete an active affinity.
You should review Affinity considerations before using SM_DELAFF.
Prior to calling SM_DELAFF, you must first call SM_SCOPE to obtain a scope list. The WCOM_AFF_STAT field in the EYURWCOM communication area contains a value indicating whether an affinity is active or committed. An active affinity can be deleted using SM_DELAFF. A committed affinity has a lifetime of SYSTEM or PERMANENT and cannot be deleted using SM_DELAFF.
EYU9WRAM contains a fragment of unexecuted code that you can use as a template for implementing the SM_DELAFF API function.
The SM_DELAFF function cannot be called during:
Once created, an affinity normally exists until the lifetime of the affinity has expired. The expiration for each lifetime is as follows:
CICS does not support pseudoconversations for APPC (LUTYPE6.2) devices.
There are circumstances when SM_SCOPE generates a scope list containing a single affinity target region, but the target region is not available for routing. This happens when:
In these cases, the EYU9WRAM default processing issues a terminal message indicating that the affinity target region is not available and causes the transaction to terminate. If the affinity lifetime is PCONV (pseudoconversation), CICSPlex SM automatically deletes the affinity because it has expired (there is no NEXTTRANSID). However, the default EYU9WRAM processing does not delete any other affinities because the characteristics of the actual affinity to the target region are unknown. For example, a LOGON affinity may involve the use of the TCTUA to pass information to the target region. If the affinity is deleted when the target region is not available, the next transaction for the transaction group would cause a new target region to be selected. The transaction might fail upon using the TCTUA contents when routed to the new target region.
The sample EYU9WRAM program, which implements the default processing, contains a subroutine that checks on affinity status after a call to SM_SCOPE. When an affinity is active to an target region, but not committed, and the affinity target region status is not OK, the subroutine sends a message to the terminal user and then exits so that the EYU9WRAM program terminates. The subroutine contains an unexecuted code fragment that can be used to delete the affinity using the SM_DELAFF call. Prior to the unexecuted code fragment is a series of tests for the affinity lifetime of the active affinity. One or more of the branches can be changed to jump to the code fragment. The code fragment itself deletes the affinity, issues a message, and then returns so that the EYU9WRAM program exits, thereby causing the transaction to terminate. This processing can be modified so that the affinity is deleted, no message is issued, and the subroutine exits causing the mainline process to reexecute the SM_SCOPE call. In that case, a new set of target regions is received for use by SM_BALANCE.
The same subroutine also contains an unexecuted code fragment that can be enabled to create an affinity. In this case, the subroutine has determined that an affinity is defined but not active. It then checks the WCOM_AFF_AUTO indicator to determine whether CICSPlex SM should automatically create affinities during SM_BALANCE. The subroutine exits normally no matter what the answer is. You can enable the SM_CREAFF fragment in order to cause an affinity to be created. The SM_CREAFF call may be used regardless of whether WCOM_AFF_AUTO does or does not indicate the automatic creation of affinities during SM_BALANCE. The SM_CREAFF call can therefore be used to:
The SM_CREAFF code fragment creates an affinity to the target region that appears first in the scope list returned by SM_SCOPE.
The following fields in the EYURWCOM communication area provide information regarding CICSPlex SM affinity processing.
These fields are described in EYURWCOM.