Send_Data
The Send_Data call (function name cmsend) puts data in the local LU's send buffer for transmission to the partner program.
CM_ENTRY Send_Data(
unsigned char FAR *conversation_ID,
unsigned char FAR *buffer,
CM_INT32 FAR *send_length,
CM_INT32 FAR *request_to_send_received,
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.
-
buffer
-
Supplied parameter. Specifies the address of the buffer containing the data to be put in the local LU's send buffer.
-
send_length
-
Supplied parameter. Specifies the number of bytes of data to be put in the local LU's send buffer. The range is from 0 through 32767.
For a mapped conversation, if send_length is set to zero, a null data record is sent to the partner program.
For a basic conversation, if send_length is set to zero, no data is sent. The buffer parameter is not relevant. However, the other parameters are processed.
-
request_to_send_received
-
Returned parameter. Is the request-to-send-received indicator. Possible values are:
-
CM_REQ_TO_SEND_RECEIVED
-
The partner program issued the Request_To_Send call, which requests the local program to change the conversation to RECEIVE state.
-
CM_REQ_TO_SEND_NOT_RECEIVED
-
The partner program did not issue the Request_To_Send call. This value is not relevant if return_code is set to CM_PROGRAM_PARAMETER_CHECK or CM_PROGRAM_STATE_CHECK.
-
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; one of the following occurred:
-
The value specified by conversation_ID is invalid.
-
The value specified by send_length is out of range (greater than 32767).
-
This is a basic conversation and the first two bytes of buffer contain an invalid logical record length (0x0000, 0x0001, 0x8000, or 0x8001).
-
cm_program_state_check
-
Primary return code; one of the following occurred:
-
The conversation state is not SEND or SEND_PENDING.
-
The basic conversation is in SEND state and send_type is set to CM_SEND_AND_CONFIRM, CM_SEND_AND_DEALLOCATE, or CM_SEND_AND_PREP_TO_RECEIVE. However, the data does not end on a logical record boundary. This condition is allowed only when deallocate_type is set to CM_DEALLOCATE_ABEND and the send_type is set to CM_SEND_AND_DEALLOCATE.
-
cm_product_specific_error
-
Primary return code; a product-specific error occurred and has been logged in the product's error log.
-
cm_conversation_type_mismatch
-
Primary return code; the partner LU or program does not support the conversation type (basic or mapped) specified in the allocation request.
-
cm_pip_not_specified_correctly
-
Primary return code; the allocation request was rejected by a non-CPI-C LU 6.2 TP. The partner program requires one or more PIP data variables, which are not supported by CPI-C.
-
cm_security_not_valid
-
Primary return code; the user identifier or password specified in the allocation request was not accepted by the partner LU.
-
cm_sync_level_not_supported_pgm
-
Primary return code; the partner program does not support the synchronization level specified in the allocation request.
-
cm_tpn_not_recognized
-
Primary return code; the partner LU does not recognize the program name specified in the allocation request.
-
cm_tp_not_available_no_retry
-
Primary return code; the partner LU cannot start the program specified in the allocation request because of a permanent condition. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.
-
cm_tp_not_available_retry
-
Primary return code; the partner LU cannot start the program specified in the allocation request because of a temporary condition. The reason for the error may be logged on the remote node. Retry the allocation.
-
cm_program_error_purging
-
Primary return code; one of the following occurred:
-
While in RECEIVE or CONFIRM state, the partner program issued Send_Error. Data sent but not yet received is purged.
-
While in SEND_PENDING state with the error direction set to CM_RECEIVE_ERROR, the partner program issued Send_Error. Data was not purged.
-
cm_resource_failure_no_retry
-
Primary return code; one of the following occurred:
-
The conversation was terminated prematurely because of a permanent condition. Do not retry until the error has been corrected.
-
The partner program did not deallocate the conversation before terminating normally.
-
cm_resource_failure_retry
-
Primary return code; the conversation was terminated prematurely because of a temporary condition, such as modem failure. Retry the conversation.
-
cm_deallocated_abend
-
Primary return code; the conversation has been deallocated for one of the following reasons:
-
The remote program issued Deallocate with the type parameter set to CM_DEALLOCATE_ABEND, or the remote LU did so because of a remote program abnormal-ending condition. If the conversation for the remote program was in RECEIVE state when the call was issued, information sent by the local program and not yet received by the remote program is purged.
-
The remote TP terminated normally but did not deallocate the conversation before terminating. Node services at the remote LU deallocated the conversation on behalf of the remote TP.
-
cm_deallocated_abend_svc
-
Primary return code; the conversation has been deallocated for one of the following reasons:
-
The partner program issued Deallocate with the type parameter set to ABEND_SVC.
-
The partner program did not deallocate the conversation before terminating.
If the conversation is in RECEIVE state for the partner program when this call is issued by the local program, data sent by the local program and not yet received by the partner program is purged.
-
cm_deallocated_abend_timer
-
Primary return code; the conversation has been deallocated because the partner program issued Deallocate with the type parameter set to ABEND_TIMER. If the conversation is in RECEIVE state for the partner program when this call is issued by the local program, data sent by the local program and not yet received by the partner program is purged.
-
cm_svc_error_purging
-
Primary return code; while in SEND state, the partner program or partner LU issued Send_Error with the type parameter set to SVC. Data sent to the partner program may have been purged.
State Changes
The conversation must be in SEND or SEND_PENDING state when the program issues this call.
The following tables summarize state changes that are possible when return_code is set to cm_ok.
send_type |
Old state |
New state |
CM_BUFFER_DATA |
SEND |
No change |
|
SEND_PENDING |
SEND |
CM_SEND_AND_FLUSH |
SEND |
No change |
|
SEND_PENDING |
SEND |
CM_SEND_AND_CONFIRM |
SEND |
No change |
|
SEND_PENDING |
SEND |
CM_SEND_AND_PREP_TO_
RECEIVE |
|
RECEIVE |
CM_SEND_AND_DEALLOCATE |
|
RESET |
For a return_code value of cm_program_error_purging or cm_svc_error_purging, the conversation changes to RECEIVE state. For other non-Cm_ok values, the conversation changes to RESET state.
Remarks
The data collected in the local LU's send buffer is transmitted to the partner LU and partner program when one of the following occurs:
-
The send buffer fills up.
-
The local program issues a Flush, Confirm, or Deallocate call or other call that flushes the LU's send buffer. (Some send types, set by Set_Send_Type, include flush functionality.)
The data to be sent can be either:
-
A complete data record on a mapped conversation. A complete data record is a string of the length specified by the send_length parameter.
-
A complete logical record or portion thereof on a basic conversation. A complete logical record is determined by the LL value. (One logical record can end and a new one begin in the middle of the string of data to be sent.)
The LU does not automatically perform any conversion between ASCII and EBCDIC on the string of data to be sent. If necessary, the program can use the CSV CONVERT to translate a string from one character set to the other.