Selecting a target region from a set of target regions

As distributed, EYU9WRAM uses SM_SCOPE and SM_BALANCE to select a target region from the list of target regions defined for a transaction. The options that you set affect the way that the target region is chosen.

  • SM_SCOPE returns a list of target regions for the current transaction occurrence. The target regions are those that are explicitly or implicitly associated with the requesting region by a workload specification.
  • SM_BALANCE selects a target region from the list of candidate target regions returned by SM_SCOPE.

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.

Actions during route selection

A dynamic route selection occurs when a transaction or program is scheduled for routing.

  • When SM_SCOPE is issued, the EYURWCOM communication area Scope Vector pointer is updated with the address of the target region scope list description area, SCOP_VECT. Also, the element count field is updated to contain the count of elements in the scope vector. Each element in the scope vector identifies a candidate target region and indicates its current status.

    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.

  • When no affinity is associated with the current transaction occurrence, an SM_SCOPE call sorts the SCOP_VECT elements so that the target region that is the best candidate is placed first in the list.
    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 that is not marked to be ignored will be selected.
    Note:
    1. If the transaction identifier and the ids of the terminal and user associated with that transaction match a transaction group to which an affinity is defined, the affinity is made active during SM_BALANCE processing.
    2. With DPL, you can update the transaction id before the SM_SCOPE call.
  • When an affinity is associated with the current transaction occurrence, an SM_SCOPE call normally causes only the target region with which the affinity exists to be identified in SCOP_VECT. An SM_BALANCE call then selects that target region. If the target region is not available for routing, the SM_BALANCE function will set a warning indicator. It will not attempt to select another target region.
  • If the transaction is defined as a DTRTRAN, the EYURWCOM communication area will contain indicators denoting that the transaction is a DTRTRAN and that it will not be rejected by the Workload Manager. Processing is generally identical to the normal, non-DTRTRAN, case. Issuing SM_SCOPE returns a SCOP_VECT. Issuing SM_BALANCE selects a target region.

    The EYU9WRAM module might opt to reject the transaction before issuing the SM_SCOPE call. In this case, the Workload Manager returns to CICS® 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.

Actions during notification

Notification occurs when a static transaction or ATI transaction is being scheduled for routing.

  • For statically routable transactions, ATI transactions, and BTS static routing requests, issuing SM_SCOPE causes the scope vector to contain a single target region. This is the target region associated with the transaction.

Actions during routing attempt complete

None, but you can tidy up and release any resources at this stage.

Actions during route selection error

A route selection error call occurs if the CICS link between the requesting region and target region is not available or is not defined.

  • When no affinity is active: issue SM_SCOPE again. The candidate target regions identified by the SCOP_VECT it returns will not include the target region that caused the error. You can then use SM_BALANCE to select a new target region.
  • When affinity became active as a result of the previous route selection:
    • If the lifetime associated with the affinity is PERMANENT, SYSTEM, ACTIVITY, or PROCESS, the target region causing the error will be included in scope list returned by SM_SCOPE. SM_BALANCE is required by affinity rules to select that target region. It also returns a warning to EYU9WRAM. EYU9WRAM should then notify the user that an error has occurred.
    • If the lifetime associated with the affinity is SIGNON, LOGON, DELIMIT, or PCONV, the active affinity status is removed before control returns to EYU9WRAM. When you reissue SM_SCOPE, the target region causing the error will not be included in the scope list. If the workload specification is defined with Create Affinity YES for the transaction group, EYU9WRAM is notified that an affinity is defined and will be activated when you issue SM_BALANCE.
  • When affinity was activated by a previous transaction instance, and you issue SM_SCOPE again, the scope list returned contains the previously selected target region. Since SM_BALANCE is required by affinity rules to select that target region, a warning is returned to EYU9WRAM. EYU9WRAM should then notify the user that an error has occurred.

Actions during transaction termination

Transaction termination occurs when a transaction has terminated normally.

  • EYU9WRAM should release any resources it may have acquired.
  • Issuing SM_SCOPE or SM_BALANCE or SM_ROUTE causes an exception response to be returned.

Actions during transaction abend

Transaction abend occurs when a transaction has terminated abnormally.

  • EYU9WRAM should release any resources it may have acquired.
  • Issuing SM_SCOPE or SM_BALANCE or SM_ROUTE causes an exception response to be returned.

Actions during transaction initiation

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.