Receiving a message, blocking and non-blocking receive

The UTM service transfers its results in the form of a message or several message segments to the client. This can also be an empty message. Moreover, the UTM application either transfers permission to send to the client or terminates the conversation. The message from the UTM service is received by UPIC and stored locally in a receive buffer. The client can pick up the message from the receive buffer as required using one of the following Receive calls:

Receive
Receive_Mapped_Data

Every message segment from the UTM service (MPUT NT/NE) must be received with its own Receive call. If the status_received field is set to CM_SEND_RECEIVED for the Receive call, the client receives permission to send.

When the UTM service terminates (PEND FI), the conversation is terminated by the server. In the Receive, the return code CM_DEALLOCATE_NORMAL is returned to the client and the conversation switches to the “Reset” state.

A CPI-C program must always issue at least one Receive call, i.e.Send calls without a following Receive call are not permitted.

The following diagram shows how messages are received in the client program.

Figure 8: Client receives a message from server, conversation is shut down

Explanation of the diagram

1. With the Set_Receive_Type call you can specify whether the data is to be received with or without blocking.
   Whether a Receive call is processed with blocking or without depends on the value of the conversation characteristic receive_type. After initialization of the conversation characteristics with the Initialize_Conversation call, a blocking Receive is set for the conversation. You can change this default setting using the Set_Receive_Type call.

   With a blocking Receive call (receive_type=CM_RECEIVE_AND_WAIT) the client program waits in the Receive or Receive_Mapped_Data until data from the server arrives for the conversation or the call is interrupted by a timer. Only then is control returned to the client program and the program run can be resumed.

   If you are working with the blocking receive, you should make sure that the program does not wait “for ever” by setting appropriate timers in the UTM server application (see the openUTM manual “Administering Applications” and the openUTM manual “Generating Applications”). On the client side, a timeout timer can be set for the blocking Receive with Set_Receive_Timer.

   In the case of a non-blocking Receive call (receive_type=CM_RECEIVE_IMMEDIATE), control is returned to the program immediately. If data from the service is present at the time of the call, it is transferred to the program. If there is no data present at the time of the call, the call returns the return code CM_UNSUCCESSFUL.

   The receive_type characteristic can be changed as often as you like within the conversation. For each Receive, the setting defined by the last Set_Receive_Type call before the Receive applies.

   Upic local:
   Local connection via UPIC local does not support the non-blocking Receive or the Set_Receive_Type call.

2. With the Receive or Receive_Mapped_Data call, the client reads the data from the receive buffer. If data is present, the Receive call passes the data directly to the client program. The remaining course of the client program depends on the result of the Receive call (fields data_received, status_received, return_code). The following situations can occur:

   • The Receive-call is issued and the UTM service has not terminated the conversation (return_code=CM_OK) and
     • the message segment could not be read completely (data_received=CM_INCOMPLETE_DATA_RECEIVED), because it is longer than the buffer provided.
       --> More parts of this message part must be read with a Receive- e.g. Receive_Mapped_Data-call.
     • the message segment could be read completely (data_received=CM_COMPLETE_DATA_RECEIVED), the client has not received the permission to send (status_received=CM_NO_STATUS_RECEIVED).
       --> More message parts must be read with a Receive- e.g. Receive_Mapped_Data-call.
     • the message segment could be read completely (data_received=CM_COMPLETE_DATA_RECEIVED), it was the last (or only) message part of the UTM program unit run, and the client has received the permission to send (status_received=CM_SEND_RECEIVED).
       --> The conversation must be continued by the client with at least one Send- e.g. Send_Mapped_Data-call and repeated Receive- e.g. Receive_Mapped_Data-calls. In this case this is a multi-step service (the service has terminated with PEND RE, PEND KP, PGWT KP or PGWT CM).

   • The Receive-call is issued and the UTM service has terminated the conversation (return_code=CM_DEALLOCATE_NORMAL - the service has terminated with PEND FI).
     --> The program switches to the "Reset" state. It can now establish a new conversation or sign off from UPIC with Disable_UTM_UPIC().

3. Once the last conversation has terminated, the client program calls Disable_UTM_UPIC in order to sign off from UPIC.