Set_Return_Control

The Set_Return_Control call (function name cmsrc) is issued by the invoking program to specify when the local LU, acting on the session request from the local program's Allocate call, should return control to the local program.

CM_ENTRY Set_Return_Control(
  unsigned char FAR *conversation_ID,  
  CM_INT32 FAR *return_control,        
  CM_INT32 FAR *return_code            
);
 

Parameters

conversation_ID

Supplied parameter. Specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation.

return_control

Supplied parameter. Specifies when the local LU, acting on the Allocate call, should return control to the local program. The following are allowed values:

CM_IMMEDIATE

The LU allocates a contention-winner session, if one is immediately available, and returns control to the program.

CM_WHEN_SESSION_ALLOCATED

The LU does not return control to the program until it allocates a session or encounters errors. If a session is not available, the program waits for one. (If the session limit is zero, the LU returns control immediately.)

return_code

The code returned from this call. The valid return codes are listed below.

Return Codes

cm_ok

Primary return code; the call executed successfully.

cm_program_state_check

Primary return code; the conversation is not in INITIALIZE state.

cm_program_parameter_check

Primary return code; the value specified by conversation_ID or return_control is invalid.

cm_product_specific_error

Primary return code; a product-specific error occurred and has been logged in the product's error log.

State Changes

The conversation must be in INITIALIZE state.

There is no state change.

Remarks

This call overrides the default return control established by Initialize_Conversation. By default, control is returned when the session is allocated. This call cannot be issued after the Allocate call has been issued.

For further information about sessions, see Writing CPI-C Applications.

If the LU is unable to allocate a session, the notification is returned on the Allocate call.