Set_Allocate_Timer - Setting timer for the allocate call

The Set_Allocate_Timer call (CMSAT) sets the timeout for an Allocate call.

When this timer is set, the Allocate call is broken off after the time defined in the allocate_timer array.

The Set_Allocate_Timer call is only permitted in the “Initialize” state.

This function is one of the additional functions of the UPIC carrier system; it is not a component of the CPI-C specification.

UPIC-Local on Unix, Linux and Windows systems: Connection via UPIC-Local does not support the Set_Allocate_Timer call.

Syntax

CMSAT (conversation_ID, allocate_timer, return_code)

Parameters

--> conversation_ID	Conversation identifier
--> allocate_timer	Time in milliseconds after which an Allocate call is broken off. The Allocate timer is reset if you set allocate_timer to 0. The waiting time of the Allocate call is then no longer monitored. The value specified for allocate_timer is rounded up to the next whole second.
<-- return_code	Result of the function call.

Result (return_code)

CM_OK

The call is OK.

CM_CALL_NOT_SUPPORTED

This return code only applies to Unix, Linux and Windows systems.
The function is not supported. This return code only occurs for UPIC-L.

CM_PROGRAM_STATE_CHECK

The conversation is not in the “Initialize” state.

CM_PROGRAM_PARAMETER_CHECK

The value of conversation_ID is invalid, or a value < 0 was specified in allocate_timer.

CM_PRODUCT_SPECIFIC_ERROR

The UPIC intance could not be found.

State change

If there are no errors the function returns CM_OK. The call does not change the state of the conversation.

Note

The Set_Allocate_Timer only makes sense in conjunction with the Allocate call. Set_Allocate_Timer can be called as often as desired between an Initialize_Conversation call and an Allocate call. The value which applies is always the one to have been set when Set_Allocate_Timer was last called prior to an allocate call.

Behavior in the event of errors

CM_CALL_NOT_SUPPORTED

This return code only applies to Unix, Linux and Windows systems.
This is not necessarily an error: If the application is intended for both UPIC-L and UPIC-R this return code just means that the application is linked to a UPIC-L library. If this is the case, timer functions are not possible. The program can take note of this return code and avoid making further calls relating to the timer.

CM_PROGRAM_STATE_CHECK

Modify program.

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 requirements of your program are excessive and if necessary reboot your system.

Function declaration: Set_Allocate_Timer

CM_ENTRY Set_Allocate_Timer ( unsigned char CM_PTR  conversation_ID,
                             CM_TIMEOUT     CM_PTR  allocate_timer,
                             CM_RETURN_CODE CM_PTR  return_code )