Sending a message and starting a UTM service

The following diagram illustrates the sequence in the client program via which the client starts the service in the UTM server application and transfers a message to the service.

Figure 7: Client starts service in a UTM partner application

Explanation of the diagram

1. Following the Allocate call, the conversation is “established” and a connection to the UTM application has been set up. The UTM service, however, is not yet started. UPIC now manages an internal buffer to which the data from the conversation is written.

2. Following the Allocate call, the client is in the “Send” state; it has permission to send data to the conversation and must now transfer a message for the addressed service (TP_Name) to UPIC. The message must contain the input data to be processed by the service. The following Send calls are available to the client for this:

   Send_Data
   Send_Mapped_Data

   After the Allocate call you may still modify the conversation characteristic receive_type and the values for the receive timer and the function key using Set_... calls.

   Send_Mapped_Data differs from the Send_Data call in that, as well as the message, format names are also sent to the server. In the same way, the client can receive data together with the format names from the service with Receive_Mapped_Data. See section“Sending and receiving formats”.

   The Send call writes the data from UPIC into a local send buffer which is uniquely assigned to the UTM service on the local system.
   The client can issue several Send calls for transferring the message.

   If the UTM service does not need any data for processing the request, the client must send an empty message to the server.

3. Once the client has transferred the message completely to UPIC, it must pass on send authorization to the server by changing to the “Receive” state. The following CPI-C calls are available for this:

   Receive
   Receive_Mapped_Data
   Prepare_To_Receive

   Only now does UPIC transfer the last section of the send buffer to the UTM service together with permission to send. The corresponding program unit of the UTM server application is started.

   If you use a Receive call to transfer permission to send to the UTM application, the client transfers permission to send and then waits in the Receive for the response from the service (blocking receive; see section “Receiving a message, blocking and non-blocking receive”).

   The Prepare_To_Receive call causes the local UPIC send buffer to be transferred immediately to the server together with permission to send. The client switches to the “Receive” state but does not receive any data yet. When the response is received from the UTM service, the client must call Receive or Receive_Mapped_Data. Before this Receive call, however, the client cannot execute further (local) processing steps which do not use the CPI-C interface. Because the conversation is in the “Receive” state, only the CPI-C calls Set_Receive_Type, Set_Receive_Timer and Set_Function_Key are allowed between Prepare_To_Receive and the Receive or Receive_Mapped_Data call. Prepare_To_Receive is useful if you are starting a “long-running” service which will not necessarily produce a reply, e.g. services with several database accesses or with distributed transaction processing between the UTM partner application and other server applications. The client program and the process are then not blocked for the entire processing time.