Request_To_Send

The Request_To_Send call (function name cmrts) notifies the partner program that the local program wants to send data.

CM_ENTRY Request_To_Send(
  unsigned char FAR *conversation_ID,  
  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 or Accept_Conversation.
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_operation_not_accepted: Primary return code; a previous operation on this conversation is incomplete.
cm_operation_incomplete: Primary return code; the operation has not completed (processing mode is nonblocking only) and is still in progress. The program can issue Wait_For_Conversation to await the completion of the operation, or Cancel_Conversation to cancel the operation and conversation. If Specify_Windows_Handle has been called, the application should wait for notification by a Windows message and not call Wait_For_Conversation.
cm_program_parameter_check: Primary return code; the value specified by conversation_ID is invalid.
cm_program_state_check: Primary return code; the conversation is not in the RECEIVE, SEND, SEND_PENDING, CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state.
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 can be in any of the following states: RECEIVE, SEND, SEND_PENDING, CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE.

There is no state change.

In response to this request, the partner program can change the conversation to RECEIVE state by issuing one of the following calls:

Receive with receive type set to CM_RECEIVE_AND_WAIT
Prepare_To_Receive
Send_Data with send type set to CM_SEND_AND_PREP_TO_RECEIVE

The partner program can also ignore the request to send.

The conversation state changes to SEND for the local program when the local program receives one of the following values through the status_received parameter of a subsequent Receive call:

CM_SEND_RECEIVED
CM_CONFIRM_SEND_RECEIVED and the local program replies with a Confirmed call

Remarks

The request-to-send notification is received by the partner program through the request_to_send_received parameter of the following calls:

Test_Request_To_Send_Received

Request-to-send notification is sent to the partner program immediately; CPI-C does not wait until the send buffer fills up or is flushed. Consequently, the request-to-send notification can arrive out of sequence. For example, if the local program is in SEND state and issues the Prepare_To_Receive call followed by the Request_To_Send call, the partner program, in RECEIVE state, can receive the request-to-send notification before it receives the send notification. For this reason, request_to_send can be reported to a program through the Receive call.

Upon receiving a request-to-send notification, the partner LU retains the notification until the partner issues a call that returns request_to_send_received. The LU keeps only one request-to-send notification per conversation. Thus the local program can issue more Request_To_Send calls than are explicitly handled by the partner TP.