Extract_Client_Context - Querying the client context

The Extract_Client_Context call provides the program with the client-specific context last sent by openUTM.

The context, transferred to openUTM with Set_Client_Context() is saved until the end of the conversation unless it is overwritten with a new context. If the client requests a restart, the context is transferred back to the client together with the last dialog message, which openUTM has currently saved for this conversation.

The client context is not saved by openUTM unless the client is signed on with a UTM user ID with restart functionality. This is a requirement for service restart.

The Extract_Client_Context call is permitted in the "Send" and "Receive" state and in the "Reset" state directly after a Receive/Receive_Mapped_Data call.

Extract_Client_Context is not part of the CPI-C specification but is an additional function of the UPIC carrier system.

Syntax

CMECC (conversation_ID, buffer, requested_length, data_received, received_length, return_code)

Parameters

--> conversation_ID	Identifier of the conversation already initialized (is supplied by the Initialize call).
<-- buffer	Buffer in which the data is received. If the return value of data_received is CM_NO_DATA_RECEIVED or the return value of received_length = 0, the content of buffer is undefined.
--> requested_length	Maximum length of the data that can be received.
<-- data_received	Specifies whether the program has received the client context in full. If the result (return_code) is not CM_OK, the value of data_received is undefined. The data_received variable can have one of the following values: CM_COMPLETE_DATA_RECEIVED The client context was received in full. CM_INCOMPLETE_DATA_RECEIVED The client context was not received in full by the program. CM_NO_DATA_RECEIVED No data was received.
<-- received_length	Length of the received data. If the value of received_length = 0, no client context has been received. The value of received_length is undefined if the result (return_code) is not CM_OK.
<-- return_code	Result of the function call.

Result ( return_code )

CM_OK

The call is OK

CM_PROGRAM_PARAMETER_CHECK

The value in conversation_ID is invalid or the value for requested_length is more than 32767 or less than 1.

The value in conversation_ID is invalid because the function was called more than once after the end of the conversation or because no conversation existed (the Enable_UTM_UPIC call has not yet been followed by an Initialize_Conversation call).

CM_PRODUCT_SPECIFIC_ERROR

The UPIC instance could not be found.

CM_PROGRAM_STATE_CHECK

The conversation is not in the "Reset", "Send" or "Receive" state.

Notes

• If a message segment was received with one or more Receive/Receive_Mapped_Data calls (data_received has the value CM_COMPLETE_DATA_RECEIVED), the client_context and client_context_length parameters are reset in a subsequent Receive/Receive_Mapped_Data call.

• The value in conversation_ID remains valid for this function call after the end of a conversation until an Initialize_Conversation or an Extract_Client_Context call has been made.

• The internal buffer size is currently limited to 8 bytes.

• openUTM currently always returns a client context with a length of 8 bytes. Consequently, if a valid client context has been received from UPIC, the received_length is 8. If a client context with a length of less than 8 bytes was sent to openUTM, the client context of openUTM is padded with binary zeros to a length of 8 bytes.

• If the value for

  requested_length is less than the length of the internally buffered client_context, the buffer made available by the application program is completely filled and data_received is set to CM_INCOMPLETE_DATA_RECEIVED. If another CMECC call is then immediately made with a sufficiently large value for requested_length (i.e. >= 8), the buffer is read in full by such a call.

Behavior in the event of errors

CM_PROGRAM_STATE_CHECK

Modify program.

CM_PROGRAM_PARAMETER_CHECK

Modify program.

CM_PRODUCT_SPECIFIC_ERROR

The operating system cannot provide sufficient memory for internal buffers. Check whether the memory requirement of your program is too high and if necessary reboot your system.

Function declaration: Extract_Client_Context

CM_ENTRY Extract_Client_Context (
                           unsigned char         CM_PTR   conversation_ID, 
                           unsigned char         CM_PTR   buffer,
                           CM_INT32              CM_PTR   requested_length, 
                           CM_DATA_RECEIVED_TYPE CM_PTR   data_received, 
                           CM_INT32              CM_PTR   received_length, 
                           CM_RETURN_CODE        CM_PTR   return_code )