Before explaining the rules which a service must respect in a distributed transaction, it is first necessary to explain certain terms.
Explanation of terms
Data transfer phase
A service is in the data transfer phase until it has either been requested to end the transaction or has requested its job receivers to end the transaction.
Send authorization
During the data transfer phase, a send authorization exists for each dialog. This is assigned to one or other of the communication partners at any given time.
The service which has send authorization in a dialog may use MPUT to send a message to the partner service. When the message is sent, the send authorization passes to the communication partner unless the partner has explicitly prohibited this with a CTRL call (CTRL PR or PE and KCNORPLY=Y).
In a processing step, a service can pass the send authorization for the dialog with the job submitter or pass one or more send authorizations for dialogs with job receivers.
End-of-transaction send authorization
The end-of-transaction send authorization controls which of the communication partners owns the send authorization after the current transaction is finished.
Usually the job-submitting service owns the end-of-transaction send authorization. However, the job-submitting service can use an MPUT message followed by PEND RE to pass this send authorization to the job-receiving service.
Here you have to remember that a service can only pass on send authorization for a maximum of one dialog at the end of the transaction.
End of transaction
A service may request end of transaction if it has been requested to do so by its job-submitting service, and it does not possess end-of-transaction send authorization for more than one dialog.
End of service
A service may request end of service if it has been requested to do so by its job-submitting service, and the service has not sent a message to a job receiver in the current processing step.
Other programming rules
In the data transfer phase, the local service possesses the send authorization for all dialogs during a program unit run.
In a processing step, a service cannot simultaneously send messages to its job submitter and to job receivers.
If the transaction remains open at the end of the processing step, then the local service may send messages to multiple job receivers simultaneously in this processing step.
A service may pass the end-of-transaction send authorization to no more than one partner. The consequences of this rule are:
In a processing step which is terminated by a request to end a transaction, a message may be sent to only one partner.
An intermediate node may only transfer the end-of-transaction send authorization in a dialog with a job receiver if it possesses the end-of-transaction send authorization in the dialog with the job submitter.
A job receiver may only request end of transaction if it has been requested to do so by its job submitter.
Rules for using the different PEND variants
You can use PEND KP if, in the processing step, messages are only sent to partners which have not yet requested end of transaction.
You can use PEND RE if, in the processing step,
messages have been sent to no more than one partner.
no request for end of transaction or dialog has simultaneously been sent to this partner.
the local service has already received a request for end of transaction or the local service itself is the root in the transaction tree.
You can use PEND SP if, in the processing step,
the local service has already received a request for end of transaction or the local service itself is the root in the transaction tree and
the local service possesses the end-of-transaction send authorization for the dialog with the job submitter and
no message has been sent to a job receiver and
no message has been sent to the client.
You can use PEND FI if, in the processing step,
the local service has already received a request for end of dialog or the local service itself is the root of the transaction tree and
no job receiver has received a request (using CTRL PR) for end of transaction, but not for end of service.
no message has been sent to a job receiver.
Rules for using PGWT variants
A PGWT KP is possible if PEND KP is allowed.
A PGWT CM is possible
with output of a dialog message if PEND RE is allowed.
without output of a dialog message if PEND SP is allowed.
PGWT RB must be used if a transaction in which the last synchronization point was set with PGWT CM is to be rolled back without terminating the OSI TP dialog.
Programming recommendations
In distributed transaction processing via OSI TP protocol, you should preferably terminate the distributed transaction in the following way:
If the uppermost job submitter in the transaction tree wants to terminate the distributed transaction, it issues a CTRL PR and an MPUT call to each of its job receivers and subsequently uses PEND/PGWT KP to terminate the processing step. The uppermost job submitter terminates the transaction after the responses from its job receivers have been received.
If an intermediate node in the transaction tree receives a request to end the transaction, it issues a CTRL PR and an MPUT call to each of its job receivers and subsequently uses PEND/PGWT KP to terminate the processing step. After the responses from its job receivers have been received, the intermediate node sends a response to its job submitter and terminates the dialog step and the transaction.
If the lowest job receiver in the transaction tree receives a request to end the transaction, it sends a response to its job submitter and terminates the dialog step and the transaction.
If you follow this rule, the next transaction starts at the uppermost job-submitting service in a program unit run.