The interaction between the program units and openUTM is implemented using KDCS calls. With these calls you inform openUTM which functions are to be executed. You pass the address of the KDCS parameter area in every KDCS call, and in some calls you pass the address of a message area.
The call parameters are passed to openUTM in the KDCS parameter area. You are provided with predefined language-specific data structures for the KDCS parameter area, in COBOL these are located in the KCPAC COPY element and in C/C++ in the kcpa.h include file. For a language-independent description of the value to be entered in this area for the individual KDCS calls refer to chapter "KDCS calls".
openUTM passes return information after every KDCS call (except for PEND) in the KB return area. The evaluation of the return codes tells you if the execution was successful or unsuccessful and can be used to take the appropriate control measures in the program (see also section "Programming error routines").
You will also find the current information on users, services, program units and communication partners after every KDCS call in the KB header.
The KB header and the KB return area are part of the communication area (KB), see "Communication area (KB)". openUTM provides a program unit with the address of the KB in a call parameter when the program unit is called.
You are provided with predefined language-specific data structures - for COBOL in the COPY element KCKBC and for C/C++ in the kcca.h include file - for the structure of the KB header and KB return area.
The first UTM call in a program unit run is the INIT call. This call initiates the interoperation of a program unit and openUTM. Other program code may precede the INIT call. After the INIT call, openUTM provides current, runtime-specific information in the KB header and in the message area.
The final call in a program unit run is the PEND call. This call terminates the program unit; control is not returned to the program unit once this call has been issued.
The different variants of the PEND call are used to control execution of a UTM service. You have the following options:
PEND PR | continues the processing step continues in another program unit without carrying out a message exchange with the partner. |
PEND PA | same as PEND PR. |
PEND PS | specially for the sign-on service, similar to PEND PR. |
PEND KP | terminates the processing step but not the transaction. |
PEND SP | terminates the transaction but not the processing step. |
PEND RE | simultaneously terminates the processing step and the transaction. |
PEND FI | terminates dialog step, transaction and service. |
PEND FC | terminates transaction and service and continues the dialog step in another service. |
PEND RS | aborts the processing step and rolls back the transaction to the last synchronization point. |
PEND ER | aborts the processing step, rolls back the transaction, terminates the service and generates a UTM dump. On BS2000 systems the application program is loaded dynamically; on Unix, Linux and Windows systems it is restarted. |
PEND FR | same effect as PEND ER but without dynamic loading or restarting of the application program. |
Note that many actions, such as the sending of an output message to the communication partner of a UTM service, are not executed by openUTM until the PEND call is issued, i.e. they are not executed during the program unit run. The source of this behavior is the transaction-oriented manner in which openUTM functions; you can decide if the action executed in this transaction by the program unit is to be committed or rolled back up until the end of the transaction.
If a serious error occurs in a UTM transaction, then openUTM independently rolls back the entire transaction to the most recent synchronization point and terminates the service (see also the openUTM manual “Concepts and Functions”).