CTRL Control OSI TP Dialog

The CTRL (control) function call is used for distributed processing via the OSI TP protocol. It allows you to explicitly control a dialog with an OSI TP partner.

The CTRL PR and CTRL PE calls may only be addressed to job-receiving services for which the "Commit" functional unit was selected.

There are a number of variants of the CTRL call:

• CTRL PR (Prepare to Commit)
  CTRL PR requests the job-receiving service to initiate the end of transaction. If the local service also sends data to the partner with an MPUT call, then it can use the CTRL call to specify whether or not the remote service is still permitted to send data.

• CTRL PE (Prepare End Dialogue)
  CTRL PE requests the job-receiving service to initiate the end of dialog. If the local service also sends data to the partner with an MPUT call, then it can use the CTRL call to specify whether or not the remote service is still permitted to send data.

• CTRL AB (Abort Dialogue)
  CTRL AB initiates an abnormal termination of the current dialog with the job-receiving service. MPUT calls to this job receiver are deleted and not sent. If the Commit functionality is selected for the dialog, openUTM ensures that the distributed transaction is rolled back to the last consistency point before the dialog is terminated. A separate CTRL call must be issued for each dialog which is to be terminated abnormally.

Setting the 1st parameter

The table below shows the various options and associated specifications in the KDCS parameter area.

Function of the call	Entries in the KDCS parameter area
	KCOM	KCLA	KCLM	KCRN	KCMF/kcfn	KCNORPLY
Prepare to Commit	"PR"	0	0	service ID	blanks	"Y"/0
Prepare End Dialogue	"PE"	0	0	service ID	blanks	"Y"/0
Abort Dialogue	"AB"	0	0	service ID	blanks	0

Setting the 2nd parameter

Here you have to specify the address of the message area. The message area is not used in this version of openUTM. It is intended for future extensions.

Setting the parameters
Field name in the KDCS parameter area	Contents
KCOP	"CTRL"
KCOM	"PR"/"PE"/"AB"
KCLA	0
KCLM	0
KCRN	Service ID
KCMF/kcfn	Blanks
KCNORPLY	"Y"/0

KDCS call
1st parameter	2nd parameter
KDCS parameter area	Message area

C/C++ macro calls
Macro names	Parameter
KDCS_CTRLPR/KDCS_CTRLPE/KDCS_CTRLAB	(kcrn)

openUTM return information
Field name in KB return area	Contents
KCRCCC	Return code
KCRCDC	Internal return code

For the CTRL call the following entries are required in the KDCS parameter area:

KCOP

In the KCOP field, you must enter the CTRL operation code.

KCOM

The KCOM field must contain one of the following operation modifiers:

• PR (PRepare to commit)
  This variant requests the job-receiving service to initiate the end of transaction. The following also applies:

  • If the local service also sends data to the job-receiving service with an MPUT call, then it can use the KCNORPLY field to specify whether or not the job-receiving service is still permitted to send data in the current transaction. The local service is then only continued after completion of the processing step if the remote service has initiated an end-of-transaction.

  • If the local service does not send any data to the job-receiving service then the job-receiving service may also not send any more data in this transaction. The local service then does not wait for the job-receiving service to initiate an endof-transaction following completion of the processing step.

• PE (Prepare End dialogue)
  This variant requests the job-receiving service to initiate the end of dialog. The following also applies:

  • If the local service also sends data to the job-receiving service with an MPUT call, then it can use the KCNORPLY field to specify whether or not the job-receiving service is still permitted to send data in the current dialog. The local service is then only continued after completion of the processing step if the remote service has initiated an end-of-dialog.

  • If the local service does not send any data to the job-receiving service then the job-receiving service may also not send any more data in this dialog. The local service then does not wait for the job-receiving service to initiate an end-ofdialog following completion of the processing step.

• AB (ABort dialogue)
  This variant initiates an abnormal termination for the current dialog with a job-receiving service. If the Commit functionality is selected for the dialog, openUTM ensures that the distributed transaction is rolled back to the last synchronization point using an appropriate PEND call before the dialog is terminated. A separate CTRL call must be issued for each dialog which is to be terminated abnormally. With CTRL AB, messages sent to the partner using MPUT are deleted.

KCLA

The KCLA field must be set to zero.

KCLM

The KCLM field must be set to zero.

KCRN

In the KCRN field, specify the service ID (VGID) of the partner service to which the CTRL call refers.

KCMF / kcfn

In the KCMF/kcfn field, enter blanks.

KCNORPLY

If KCOM=PR/PE, the value Y can be entered in the KCNORPLY field. This value informs the job-receiving service that it cannot send any more data in this transaction or this dialog, even if the local service continues to send data to the job-receiving service with MPUT.

You must specify binary zero for all unused fields.

For the KDCS call you enter:

1st parameter

The address of the KDCS parameter area.

2nd parameter

As 2nd parameter: the address of the message area. This address must be specified for all CTRL calls even though CTRL calls do not currently use the message area.

Macro names

The use of C/C++ calls is described in detail in section "C/C++ macro interface".

openUTM returns:

KCRCCC

in the KCRCCC field: the KDCS return code.

KCRCDC

in the KCRCDC field: the internal return code of openUTM (see the openUTM manual ”Messages, Debugging and Diagnostics”).

KDCS return codes in the KCRCCC field for the CTRL call

The following codes can be analyzed in the program:

000	Function carried out successfully.
40Z	The application was generated without distributed processing.
41Z	CTRL call is impermissible at this point. Possible reasons are: The call was issued for an asynchronous service, i.e. the specified service ID was defined using an APRO AM call. The call is addressed to a partner to which an MPUT HM has already been sent. A CTRL PE or PR is addressed to a partner for which FU commit has not been selected. A CTRL PE or PR is addressed to a partner to which no MPUT has as yet been sent following an APRO.
42Z	The function variant in KCOM is invalid.
43Z	The value specified in KCLA or KCLM is invalid.
44Z	The service ID specified in KCRN is invalid or no service ID has been specified.
45Z	The KCMF/kcfn field is not filled with blanks.
49Z	The content of unused fields in the KDCS parameter area is not equal to binary zero.
54Z	The KCNORPLY field in CTRL PR or PE has a value other than Y or binary 0.

Additional error codes can be found in the dump:

71Z	No INIT call has been issued in the program unit run.
77Z	Invalid area address.

Features of the CTRL calls

• No end of transaction may be requested at the end of a processing step in which a CTRL PR or PE call and an MPUT call have been addressed to the same partner.

• You may address the CTRL PR / PE / AB call only to those job-receiving services which are currently involved in a distributed dialog, i.e. which were addressed with an APRO DM.

• You may address CTRL PR and CTRL PE calls only to those job-receiving services for which the Commit functional unit has been selected and for which an MPUT has already been issued after APRO.

• You can issue CTRL calls for multiple partners in a single processing step or program unit run.

• Only those PEND calls with the operation modifiers RS, FR and ER are allowed after a CTRL AB call for a dialog with an AN service in which the commit functionality has been selected.