The following sections explain the rules which have to be observed when using distributed dialogs via LU6.1. If you follow the suggested "programming recommendations" in the final section the presented rules are automatically observed.
Effect of PEND calls and rules for usage
The PEND calls in job-submitting and job-receiving services control the distributed transaction, i.e. they decide when the common synchronization point of the two transactions is to be set.
Which PEND calls a service may use and their effect depends on the service and transaction status of the partner service.
The following table describes the effect of the PEND calls in the job-receiving and job-submitting services and the rules for how to use them:
Variant | Effect / rule of usage |
|---|---|
PEND KP | No synchronization point is requested and no synchronization point is set. The service remains in transaction status "0" and in service status "0". An open DB transaction remains open. The follow-up program unit specified in KCRN is started in the job-submitting service as soon as all results from the job-receiving services have been received. This is permissible if the program unit sends a message to the terminal or the client (LTERM partner) or if the message is addressed to a partner service and this does not have transaction status "P". |
PEND RE | End of transaction (synchronization point) is requested. End of transaction (synchronization point) is requested. If all partner services already have transaction status "P" (i.e. they have already requested end of transaction), then the end of transaction is executed by all participating services, i.e. a common synchronization point is set. If a partner service is not in transaction status "P", the local service passes to transaction status "P" and waits for the partner service to request end of transaction, too. The follow-up program unit specified in KCRN is started in the job-submitting service as soon as all results have been received from the job-receiving services. Permissible in the two cases below:
If multiple partner services with open transactions exist then PEND RE is forbidden. |
PEND FI | The effect is the same as with PEND RE, except that end of service is requested simultaneously. The service is terminated at the next synchronization point. This is permissible if no job-receiving services are open any longer, i.e. all job receivers must have issued PEND FI before the job submitter is permitted to issue PEND FI. |
PEND FC | The effect is the same as with PEND FI, except that after end of service, the chained follow-up service is started immediately. This is permissible in job-submitting services only (never permitted in job receivers), and only if no further job-receiving services are open, i.e. all job receivers must have issued PEND FI before the job submitter is permitted to issue PEND FC. |
PEND PR | No effect on the transaction. |
PEND SP | The transaction is closed, i.e. a synchronization point is set and the dialog step is continued. Not allowed if there are partner services with open transactions. |
PEND RS | With PEND RS all the services participating in the distributed transaction are rolled back to the last synchronization point. All services created in the distributed transaction are terminated by the rollback. Services which have reached at least one synchronization point remain open. |
Programming rules
A set of rules has to be adhered to when programming distributed transactions. Violation of these rules leads to abortion of the service with (internal) PEND ER and KCRCCC=87Z.
These rules determine:
how transactions and services have to be terminated when using distributed processing and
where the output message may be sent.
Program unit runs, transactions and services are terminated as usual via the various PEND variants; of particular importance here are the PEND variants KP, RE, SP, FI and FC, and for error handling RS, ER and FR.
Using the variants KP, RE and SP you have to specify the follow-up program unit in KCRN, which is used to continue the service. You start this follow-up program unit with PEND KP/RE after all results from the job receivers have been received, or, if the message was addressed to the job submitter, after the next message is received from the job submitter. If you use PEND SP the follow-up program unit is started immediately.
The PGWT KP call may be used whenever a PEND KP is allowed.
The following rules hold for correct programming of a distributed transaction:
Service rule:
a job-submitting service may only be terminated once all the associated job-receiving services have been terminated (with PEND FI). PEND FC is prohibited in job-receiving services.
After the PEND FI of the job-receiving service, the job-submitting service can terminate the subsequent dialog step with PEND KP, RE, SP, FI or FC. It may not send any more messages to this job-receiver service.
Transaction rule (single-level):
a job-submitting or job-receiving service can terminate a dialog step either with or without end of transaction subject to the following restrictions:a job-submitting service may not request end of transaction if the transaction is open in the job-receiving service, and the output message is directed to the client
a service must request end of transaction if the output message is directed to a partner service which has requested end of transaction.
With multi-level distributed transactions, i.e. when a job-receiving service is itself a job-submitting service or when a job-submitting service addresses several job-receiving services in one transaction, then the transaction rule is generalized as follows:
Transaction rule (multi-level):
a service can terminate a processing step either with or without end of transaction subject to the following restrictions:a service may not request end of transaction if there is a partner service with an open transaction and the output message is not directed to this partner service. If multiple partner services with open transactions exist, it is never permitted to request end of transaction.
a service must request end of transaction if the output message is directed to a partner service which has requested end of transaction
If a service has multiple partner services with open transactions, PEND RE, PEND FI and PEND SP are never permitted.
The tables "Effect of PEND calls and rules for usage", "PEND variants in the job submitter" and "PEND variants in job-receiving service" illustrate the situations when you can use the PEND call.
If you follow the "bottom-up strategy" described below, then the programming rules are adhered to automatically.
Programming recommendation: Bottom-up strategy
The bottom-up strategy is such that distributed transactions are always terminated from the bottom up, i.e.
a job-receiving service always requests end of transaction before its job-submitting service and sends its output message to its job-submitting service, and
a job-submitting service only requests end of transaction once all its job-receiving services have requested end of transaction. The output message then goes to its own job submitter.
PEND variants depending on the partner status
When using the PEND call must always consider the service status and transaction status of the partner service. Following MGET, openUTM returns the status information in the KCVGST/kcpcv_state and KCTAST/kcpta_state fields.
The cases illustrated in the following tables contain no new rules. They illustrate the rules described in the preceding sections.
PEND variants in the job submitter
The calls PEND PA and PEND PR are not included because they have no special features for distributed processing.
Partner status | PEND variants in the job-submitting service | ||
|---|---|---|---|
KCVGST/kcpcv_state | KCTAST/kcpta_state | permitted variants and their effect and limitations | |
"O" | "O" | KP: | transactions in the job-receiving and job-submitting services remain open - default. |
RE: | requests end of transaction. Only permitted if the output message is addressed to this job receiver and no further partner with open transactions exist. | ||
RS: | rolls back the job-submitting and job-receiving transaction to the last synchronization point. Services in this transaction are terminated. | ||
ER/FR: | rolls back the distributed transaction; the job-receiving service is terminated. | ||
"O" | "P" | KP: | only permitted if the output message is addressed to another partner service or another client; the transactions remain open (not recommended because of PTC state) |
RE: | terminates the distributed transaction. | ||
SP: | terminates the distributed transaction. | ||
RS: | rolls back the job submitter and job receiver transaction to the last synchronization point. Services in this transaction are terminated. | ||
ER/FR: | rolls back the distributed transaction; the job-receiving and job-submitting service are terminated | ||
"O" | "C" | KP: | transaction in job-submitting service remains open. |
RE: | transaction in job-submitting service is terminated if the output message is addressed to the client, otherwise the service passes to transaction status "P". | ||
SP: | terminates the job submitter transaction. | ||
RS: | rolls back the transaction in the job-submitting service to the last synchronization point; services which started in this transaction are terminated. | ||
ER/FR: | terminates job-submitting and job-receiving service and rolls back the local transaction. | ||
"C" | "P" | The output message must be addressed to another partner or the client or (with PEND SP/FC) to a follow-up program unit! | |
KP: | not recommended, since the job-receiving service waits in state PTC. | ||
RE: | terminates the distributed transaction and the job-receiving service. | ||
SP: | as RE | ||
FI: | terminates the distributed transaction as well as the job-receiving service and job-submitting service. | ||
FC: | as FI | ||
RS | rolls back job-submitting and job-receiving service to the last synchronization point. Services which started in this transaction are terminated. | ||
ER/FR: | terminates job-submitting and job-receiving service and rolls back the distributed transaction. | ||
"C" | "C" | the output message must be addressed to another partner or to the client or (with PEND SP/FC) to the follow-up program unit! | |
KP: | keep transaction in job submitter open. | ||
RE: | terminates the transaction in the job submitter. | ||
SP: | terminates the transaction in the job submitter. | ||
FI: | terminates transaction and job-submitting service. | ||
FC: | terminates transaction and job-submitting service. | ||
RS: | rolls back the job submitter transaction to the last synchronization point. | ||
ER/FR: | rolls back the transaction in the job-submitting service and terminates the job-submitting service. the job-receiving service is already terminated. | ||
The combinations "KCVGST=O, KCTAST=C" and "KCVGST=C, KCTAST=C" cannot occur if you follow the "bottom-up strategy".
PEND variants in job-receiving service
The calls PEND PA and PEND PR are not included because they have no special features for distributed processing. The variant PEND FC is not permitted in job-receiving services.
Partner status | PEND variants in job-receiving service | ||
|---|---|---|---|
KCVGST/kcpcv_state | KCTAST/kcpta_state | permitted variants and their effects and limitations | |
"O" | "O" | KP: | transactions in the job-receiving and job-submitting services remain open. |
RE: | job-receiving services passes to transaction status P. | ||
FI: | the job-receiving service changes to transaction status P. The service is terminated at the next synchronization point (=end of the distributed transaction). | ||
RS: | rolls back the distributed transaction to the last synchronization point. Services in this transaction are terminated. | ||
ER/FR: | rolls back the distributed transaction; the job-receiving service is terminated. | ||
"O" | "P" | RE: | terminates the distributed transaction. |
SP: | terminates the distributed transaction. | ||
FI: | terminates the distributed transaction and the job-receiving service. | ||
RS: | rolls back the distributed transaction to the last synchronization point. Services in this transaction are terminated. | ||
ER/FR: | rolls back the distributed transaction; the job-receiving service is terminated. | ||
"O" | "C" | KP: | permitted |
RE: | job-receiving service passes to transaction status P. | ||
SP: | job-receiving service passes to transaction status P. | ||
FI: | The service is terminated at the next synchronization point (= end of the distributed transaction). | ||
RS: | rolls back the distributed transaction to the last synchronization point. | ||
ER/FR: | rolls back the distributed transaction; the job-receiving service is terminated. | ||
If the bottom-up strategy is adhered to, only the combination "O"/"O" can occur, see "bottom-up strategy".
Prior to a PEND RS in a follow-up transaction, you have to send a rollback message with MPUT RM, otherwise openUTM aborts the job-receiving service with 83Z.