A true restart is only possible with the CPI-C interface from UPIC, because only this interface can communicate in multi-step UTM services. However, the last output message can also be read with the XATMI interface; see section “Restart” - XATMI. The following description therefore only refers to CPI-C client programs.
A service context is linked with the UTM user ID. Amongst other things, the service context contains the last output message and service data such as KB and LSSBs, etc. The client can also send a client context to the UTM application, see Restart with Client Context.
Restart capability depends on how a UTM user ID is configured:
If a UTM user ID is configured as USER ...,RESTART=YES (default value), openUTM performs a service restart after system failure or after loss of the connection to the client. In other words, openUTM reactivates the service context and, where appropriate, the client context for the user ID.
If a UTM user ID is configured as RESTART=NO, openUTM does not implement any service restarts, even if the LTERM partner used by the client is configured with LTERM ...,RESTART=YES.
A service restart means that after the client signs on again, processing continues at the last synchronization point of a service which is still open. openUTM retransmits the last message of the open service and, where appropriate, the client context to the client. The client can then continue the service.
If an open service exists for the client under the user ID, this service must be continued immediately after the next sign-on, as otherwise openUTM terminates the open service abnormally.
The client program must initiate the restart by first of all establishing a new conversation and transferring the KDCDISP transaction code in the Set_TP_Name call. The example below illustrates this type of “restart program” for CPI-C.
Initialize_Conversation (...)
Set_Conversation_Security_Type (...,CM_SECURITY_PROGRAM,..) // 1.
Set_Conversation_Security_User_ID (...,"UTMUSER1",..) // 1.
Set_Conversation_Security-Password (...,"SECRET",..) // 1.
Set_TP_Name (...,"KDCDISP",...) // 2.
Allocate (...)
Send_Data (...) // 3.
/* blank message */
Receive (...)
return_code=CM_OK
/* service open, send authorization transferred to client */
/* continue communication in UTM service */
status_received=CM_SEND_RECEIVED // 4.
/* or */
return_code=CM_DEALLOCATED_NORMAL // 5.
/* end of service, restart terminated */
/* or */
return_code=CM_TP_NOT_AVAILABLE_NO_RETRY // 6.
/* restart not possible */
The program uses the system access control functions of openUTM and explicitly sets the UTM user ID and password.
The program must set the TP_name to KDCDISP for the restart.
No data can be sent with Send_Data, i.e. send_length must be set to 0 (“blank message”).
Processing and communication with the UTM service can be continued.
The program has already received the last output message; there are no more open services on the UTM side.
A restart is not possible, due to UTM reconfiguration.
The client always receives the last output message of openUTM with Receive as the result of this type of restart program.
A user can sign on to a UTM server under a particular user ID in one of several ways:
from a terminal
via a transport system application
via a client program with various carrier systems
A restart by a client program is only possible if the user ID was also last used by a client program with the same carrier system. If this is not the case, openUTM rejects the client programs’ attempt to sign on (CM_SECURITY_NOT_VALID) because the open service must first be terminated by the partner that started it.
If no open service exists when the conversation is established with KDCDISP, openUTM terminates the conversation after sending the last output message of the previous service. If the last service was started by a different partner, openUTM does not transfer any messages (return code CM_TP_NOT_AVAILABLE_NO_RETRY).
If no application context exists following a re-configuraton of the UTM application, the program receives the return code CM_TP_NOT_AVAILABLE_NO_RETRY. openUTM then terminates the conversation.
The UTM utility KDCUPD transfers services of a client with restart capability.
Restart with client context
With each user message the client can send what is known as a client context to the UTM application. A client context consists of a string up to 8 bytes long. The string may contain, for example, the time or a message ID.
If the user ID is configured with RESTART=YES, the client context is buffered by openUTM until the end of the conversation unless it is overwritten with a new context.
If the client requests a restart, openUTM transfers the client context to the client together with the last dialog message. By referring to the client context the program is able to uniquely identify at which point in the dialog a restart must be made and how the program must respond; for example, by outputting a specific form. The following UPIC calls are available to set and read the client context:
Set_Client_Context: set client context
Extract_Client_Context: output the last client context sent by openUTM