Extract_Secondary_Information - Querying secondary information

The Extract_Secondary_Information (CMESI) call provides the program with expanded information (secondary information) relating to the return code of the most recent CPI-C call.

Syntax

CMESI (conversation_ID, call_ID, buffer, requested_length, data_received, received_length, return_code)

Parameters

--> conversation_ID	Identifier for the started conversation (supplied by the Initialize call).
--> call_ID	Specifies the function on which secondary information is required.
<-- buffer	Buffer which receives the data. 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 data that can be received
<-- data_received	Specifies whether the program has completely received the secondary information. If the result (return_code) is not CM_OK, the value of data_received is undefined. data_received can have one of the following values: CM_COMPLETE_DATA_RECEIVED The secondary information was received completely. CM_INCOMPLETE_DATA_RECEIVED The secondary information was incompletely received by the program. CM_NO_DATA_RECEIVED No data was received.
<-- received_length	Length of received data. The value of received_length is undefined as long as the result (return_code) does not have the value CM_OK.
<-- return_code	Result of the function call.

Result (return_code)

CM_OK

The call is OK

CM_NO_SECONDARY_INFORMATION

There is no secondary information available for the call of the specified conversation.

CM_PROGRAM_PARAMETER_CHECK

The value of conversation_ID is invalid, the call_ID specifies CMESI or an invalid value, or the value of requested_length is greater than 32767 or less than 1.

CM_PRODUCT_SPECIFIC_ERROR

The UPIC instance could not be found.

Notes

• The program should make this call immediately after receiving a return_code. Subsequent CPI-C calls can overwrite the secondary information. If there is no conversation, for example, if the library is in the “Reset” state, then conversation_ID is ignored.

• When the Extract_Secondary_Information call is successfully terminated, the returned secondary information does not remain saved. The same information will no longer be available in a subsequent Extract_Secondary_Information call.

• The program cannot use the call to extract secondary information from a previous Extract_Secondary_Information call.

• The full complexity of this function is not implemented as laid down in the CPI-C specification. The simplifications in comparison with CPI-C are as follows:

- The internal buffer is limited to a size of 1024 bytes.

- If the value of requested_length is less than the length of the secondary information saved internally, the buffer made available by the application program is filled completely and data_received is set to CM_INCOMPLETE_DATA_RECEIVED. It is not possible to obtain the remaining data using further CMESI calls.

Behavior in the event of errors

CM_PROGRAM_PARAMETER_CHECK

Modify program.

CM_PRODUCT_SPECIFIC_ERROR

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

Function declaration: Extract_Secondary_Information

CM_ENTRY Extract_Secondary_Information (
                              unsigned char CM_PTR  conversation_ID,
                      CM_INT32              CM_PTR  call_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 )