SEND_DATA

The SEND_DATA verb places data in the local LU's send buffer for transmission to the partner TP.

For the Microsoft® Windows® version 3.x system, it is recommended that you use WinAsyncAPPC rather than the blocking version of this call.

The following structure describes the verb control block used by the SEND_DATA verb.

struct send_data {
    unsigned short      opcode;
    unsigned char       opext;
    unsigned char       reserv2;
    unsigned short      primary_rc;
    unsigned long       secondary_rc;
    unsigned char       tp_id[8];
    unsigned long       conv_id;
    unsigned char       rts_rcvd;
    unsigned char       data_type;
    unsigned short int  dlen;
    unsigned char FAR * dptr ;
    unsigned char       type;
    unsigned char       reserv4;
};

Members

opcode
Supplied parameter. Specifies the verb operation code, AP_B_SEND_DATA.
opext
Supplied parameter. Specifies the verb operation extension, AP_BASIC_CONVERSATION.
primary_rc
Returned parameter. Specifies the primary return code set by APPC at the completion of the verb. The valid return codes vary depending on the APPC verb issued. See Return Codes for valid error codes for this verb.
secondary_rc
Returned parameter. Specifies the secondary return code set by APPC at the completion of the verb. The valid return codes vary depending on the APPC verb issued. See Return Codes for valid error codes for this verb.
tp_id
Supplied parameter. Identifies the local TP.

The value of this parameter is returned by TP_STARTED in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.

conv_id
Supplied parameter. Provides the conversation identifier.

The value of this parameter is returned by ALLOCATE in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.

rts_rcvd
Returned parameter. Provides the request-to-send-received indicator.
data_type
Supplied parameter. Specifies the type of data to be sent if Sync Point is supported. Valid parameters are:

AP_APPLICATION

AP_USER_CONTROL_DATA

AP_PS_HEADER

dlen
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 65535.
dptr
Supplied parameter. Specifies the address of the buffer containing the data to be put in the local LU's send buffer.

For the Microsoft® Windows NT® and Windows 95 operating systems and the Windows graphical environment, the data buffer can reside in a static data area or in a globally allocated area. The data buffer must fit entirely within this area.

For OS/2, the data buffer must reside on an unnamed, shared segment, which is allocated by the function DosAllocSeg with Flags equal to 1. The data buffer must fit entirely on the data segment.

type
Supplied parameter. Allows a TP to send data and perform other functions within one API call. For example, you can combine SEND_DATA with type set to CONFIRM to accomplish the same objective as issuing SEND_DATA followed by CONFIRM.

Return Codes

ap_ok
Primary return code; the verb executed successfully.
ap_parameter_check
Primary return code; the verb did not execute because of a parameter error.
ap_bad_conv_id
Secondary return code; the value of conv_id did not match a conversation identifier assigned by APPC.
ap_bad_ll
Secondary return code; the logical record length field of a logical record contained an invalid value—0x0000, 0x0001, 0x8000, or 0x8001. See About Transaction Programs for information on logical records.
ap_bad_tp_id
Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.
ap_invalid_data_segment
Secondary return code; the length specified for the data buffer was longer than the segment allocated to contain the buffer.
ap_send_data_invalid_type
Secondary return code; the specified type was not recognized by APPC.
ap_send_data_confirm_sync_none
Secondary return code; the type CONFIRM is not permitted for a conversation that was allocated with a sync_level of NONE.
ap_state_check
Primary return code; the verb did not execute because it was issued in an invalid state.
ap_send_data_not_send_state
Secondary return code; the local TP issued SEND_DATA, but the conversation was not in SEND state.
ap_send_data_not_ll_bdy
Secondary return code; the TP started but did not finish sending a logical record. This occurs only when the type parameter is one of the following:

AP_SEND_DATA_CONFIRM

AP_SEND_DATA_DEALLOC_FLUSH

AP_SEND_DATA_DEALLOC_SYNC_LEVEL

AP_SEND_DATA_P_TO_R_FLUSH

AP_SEND_DATA_P_TO_R_SYNC_LEVEL

ap_allocation_error
Primary return code; APPC has failed to allocate a conversation. The conversation state is set to RESET.

This code can be returned through a verb issued after ALLOCATE.

ap_allocation_failure_no_retry
Secondary return code; the conversation cannot be allocated because of a permanent condition, such as a configuration error or session protocol error. To determine the error, the system administrator should examine the error log file. Do not retry the allocation until the error has been corrected.
ap_allocation_failure_retry
Secondary return code; the conversation could not be allocated because of a temporary condition, such as a link failure. The reason for the failure is logged in the system error log. Retry the allocation.
ap_conversation_type_mismatch
Secondary return code; the partner LU or TP does not support the conversation type (basic or mapped) specified in the allocation request.
ap_pip_not_allowed
Secondary return code; the allocation request specified PIP data, but either the partner TP does not require this data, or the partner LU does not support it.
ap_pip_not_specified_correctly
Secondary return code; the partner TP requires PIP data, but the allocation request specified either no PIP data or an incorrect number of parameters.
ap_security_not_valid
Secondary return code; the user identifier or password specified in the allocation request was not accepted by the partner LU.
ap_sync_level_not_supported
Secondary return code; the partner TP does not support the sync_level (AP_NONE or AP_CONFIRM_SYNC_LEVEL) specified in the allocation request, or the sync_level was not recognized.
ap_tp_name_not_recognized
Secondary return code; the partner LU does not recognize the TP name specified in the allocation request.
ap_trans_pgm_not_avail_no_retry
Secondary return code; the remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition is permanent. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.
ap_trans_pgm_not_avail_retry
Secondary return code; the remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition may be temporary, such as a time-out. The reason for the error may be logged on the remote node. Retry the allocation.
ap_comm_subsystem_abended
Primary return code; indicates one of the following conditions:

The system administrator should examine the error log to determine the reason for the ABEND.

ap_comm_subsystem_not_loaded
Primary return code; a required component could not be loaded or has terminated while processing the verb. Thus, communication could not take place. Contact the system administrator for corrective action.

When this return code is used with ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there is no node available that can satisfy the ALLOCATE request.

When ALLOCATE produces this return code for an SNA Server Client system configured with multiple nodes, there are two secondary return codes as follows:

0xf0000001
Secondary return code; no nodes have been started.
0xf0000002
Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:
·    The node with the local LU is not started.
·    The local LU is not configured.

ap_conv_failure_no_retry
Primary return code; the conversation was terminated because of a permanent condition, such as a session protocol error. The system administrator should examine the system error log to determine the cause of the error. Do not retry the conversation until the error has been corrected.
ap_conv_failure_retry
Primary return code; the conversation was terminated because of a temporary error. Restart the TP to see if the problem occurs again. If it does, the system administrator should examine the error log to determine the cause of the error.
ap_conversation_type_mixed
Primary return code; the TP has issued both basic and mapped conversation verbs. Only one type can be issued in a single conversation.
ap_invalid_verb_segment
Primary return code; the VCB extended beyond the end of the data segment.
ap_prog_error_purging
Primary return code; while in RECEIVE, PENDING, PENDING_POST (Windows NT, Windows 95, and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state, the partner TP issued SEND_ERROR with err_type set to AP_PROG. Data sent but not yet received is purged.
ap_stack_too_small
Primary return code; the stack size of the application is too small to execute the verb. Increase the stack size of your application.
ap_conv_busy
Primary return code; there can only be one outstanding conversation verb at a time on any conversation. This can occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same conv_id.
ap_thread_blocking
Primary return code; the calling thread is already in a blocking call.
ap_unexpected_dos_error
Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.
ap_dealloc_abend_prog
Primary return code; the conversation has been deallocated for one of the following reasons:
ap_dealloc_abend_svc
Primary return code; the conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_SVC.
ap_dealloc_abend_timer
Primary return code; the conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_TIMER.
ap_svc_error_purging
Primary return code; the partner TP (or partner LU) issued a SEND_ERROR verb with err_type set to AP_SVC while in RECEIVE, PENDING_POST (Windows NT, Windows 95, and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state. Data sent to the partner TP may have been purged.

Remarks

The conversation must be in SEND state when the TP issues this verb. State changes, based on primary_rc, are summarized in the following table.

primary_rc New state
AP_OK No change
AP_ALLOCATION_ERROR RESET
AP_CONV_FAILURE_RETRY RESET
AP_CONV_FAILURE_NO_RETRY RESET
AP_DEALLOC_ABEND RESET
AP_DEALLOC_ABEND_PROG RESET
AP_DEALLOC_ABEND_SVC RESET
AP_DEALLOC_ABEND_TIMER RESET
AP_PROG_ERROR_PURGING RECEIVE
AP_SVC_ERROR_PURGING RECEIVE

SEND_DATA may wait indefinitely because the partner TP has not issued a receive verb. If this occurs, the send buffer may fill up.

The data collected in the local LU's send buffer is transmitted to the partner LU (and partner TP) when one of the following occurs: