RECEIVE_AND_POST
The RECEIVE_AND_POST verb receives application data and status information asynchronously. This allows the local TP to proceed with processing while data is still arriving at the local LU.
RECEIVE_AND_POST is only supported under the Microsoft® Windows NT®, Microsoft® Windows® 95, and OS/2 operating systems. For similar functionality under the Windows version 3.x graphical environment, use RECEIVE_AND_WAIT in conjunction with WinAsyncAPPC. Specifically, while an asynchronous RECEIVE_AND_POST is outstanding, the following verbs can be issued on the same conversation:
DEALLOCATE (AP_ABEND_PROG, AP_ABEND_SVC, or AP_ABEND_TIMER)
GET_ATTRIBUTES
GET_TYPE
REQUEST_TO_SEND
SEND_ERROR
TEST_RTS
TP_ENDED
This allows an application to use an asynchronous RECEIVE_AND_POST to receive data. While the RECEIVE_AND_POST is outstanding, it can still use SEND_ERROR and REQUEST_TO_SEND. It is recommended that you use this feature for full asynchronous support. For information on how a TP receives data and how to use this verb, see Remarks in this topic.
The following structure describes the verb control block used by the RECEIVE_AND_POST verb.
struct receive_and_post {
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 short what_rcvd;
unsigned char rtn_status;
unsigned char fill;
unsigned char rts_rcvd;
unsigned char reserv4;
unsigned short max_len;
unsigned short dlen;
unsigned char FAR * dptr;
unsigned char FAR * sema;
unsigned char reserv5;
};
Members
-
opcode
-
Supplied parameter. Specifies the verb operation code, AP_B_RECEIVE_AND_POST.
-
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.
-
what_rcvd
-
Returned parameter. Indicates whether data or conversation status was received.
-
ap_confirm_deallocate indicates that the partner TP issued DEALLOCATE with dealloc_type set to AP_SYNC_LEVEL. The conversation's synchronization level, established by ALLOCATE, is AP_CONFIRM_SYNC_LEVEL. Upon receiving this value, the local TP normally issues CONFIRMED.
-
ap_confirm_send indicates that the partner TP issued PREPARE_TO_RECEIVE with ptr_type set to AP_SYNC_LEVEL. The conversation's synchronization level, established by ALLOCATE, is AP_CONFIRM_SYNC_LEVEL. Upon receiving this value, the local TP normally issues CONFIRMED, and begins to send data.
-
ap_confirm_what_received indicates that the partner TP issued CONFIRM. Upon receiving this value, the local TP normally issues CONFIRMED.
-
ap_data indicates that this value can be returned by RECEIVE_AND_POST if fill is set to AP_BUFFER. The local TP received data until max_len or the end of the data was reached. For more information, see Remarks in this topic.
-
ap_data_complete indicates, for RECEIVE_AND_POST, that the local TP has received a complete data record or the last part of a data record.
For RECEIVE_AND_POST with fill set to AP_LL, this value indicates that the local TP has received a complete logical record or the end of a logical record.
Upon receiving this value, the local TP normally reissues RECEIVE_AND_POST or issues another receive verb. If the partner TP has sent more data, the local TP begins to receive a new unit of data.
Otherwise, the local TP examines status information.
If primary_rc contains ap_ok and what_rcvd contains AP_SEND, AP_CONFIRM_SEND, AP_CONFIRM_DEALLOCATE, or AP_CONFIRM_WHAT_RECEIVED, see the description of the value (in this section) for the next action the local TP normally takes.
If primary_rc contains AP_DEALLOC_NORMAL, the conversation has been deallocated in response to the DEALLOCATE issued by the partner TP.
-
ap_data_incomplete indicates, for RECEIVE_AND_POST, that the local TP has received an incomplete data record. The max_len parameter specified a value less than the length of the data record (or less than the remainder of the data record if this is not the first receive verb to read the record).
For RECEIVE_AND_POST with fill set to AP_LL, this value indicates that the local TP has received an incomplete logical record.
Upon receiving this value, the local TP normally reissues RECEIVE_AND_POST (or issues another receive verb) to receive the next part of the record.
-
ap_none indicates that the TP did not receive data or conversation status indicators.
-
ap_send indicates, for the partner TP, that the conversation has entered RECEIVE state. For the local TP, the conversation is now in SEND state. Upon receiving this value, the local TP normally uses SEND_DATA to begin sending data.
-
rtn_status
-
Supplied parameter. Indicates whether both data and conversation status indicators should be returned within one API call.
-
AP_NO specifies that indicators should be returned individually on separate invocations of the verb.
-
AP_YES specifies that indicators should be returned together, provided both are available. Both can be returned when:
The receive buffer is large enough to hold all of the data that precedes the status indicator.
The fill parameter specifies BUFFER or LL, and the data is the last logical record before the status indicator.
-
fill
-
Supplied parameter. Specifies how the local TP receives data.
Use AP_BUFFER to indicate that the local TP receives data until the number of bytes specified by max_len is reached or until end of data. Data is received without regard for the logical-record format.
Use AP_LL to indicate that data is received in logical-record format. The data received can be:
-
A complete logical record.
-
A max_len byte portion of a logical record.
-
The end of a logical record.
-
rts_rcvd
-
Returned parameter. Indicates whether the partner TP issued REQUEST_TO_SEND. Possible values are:
-
ap_yes indicates that the partner TP issued REQUEST_TO_SEND, which requests that the local TP change the conversation to RECEIVE state.
-
ap_no indicates that the partner TP has not issued REQUEST_TO_SEND.
-
max_len
-
Supplied parameter. Specifies the maximum number of bytes of data the local TP can receive. The range is from 0 through 65535.
The value must not exceed the length of the buffer to contain the received data. The offset of dptr plus the value of max_len must not exceed the size of the data segment.
-
dlen
-
Returned parameter. Specifies the number of bytes of data received. Data is stored in the buffer specified by dptr. A length of zero indicates that no data was received.
-
dptr
-
Supplied parameter. Provides the address of the buffer to contain the data received by the local LU.
For the Windows NT and Windows 95 operating systems, 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 the OS/2 operating system, the data buffer must reside on an unnamed, shared segment, which is allocated by the DosAllocSeg function with Flags equal to 1. The data buffer must fit entirely on the data segment.
-
sema
-
Supplied parameter. Provides the address of the semaphore that APPC is to clear when the asynchronous receiving operation is finished. On OS/2, the sema parameter is either a RAM or system semaphore. On Windows NT and Windows 95, the sema parameter is an event handle obtained by calling either the CreateEvent or OpenEvent Win32® function.
Return Codes
-
ap_ok
-
Primary return code; the verb executed successfully.
When rtn_status is ap_yes, the preceding return code or one of the following return codes can be returned.
-
ap_data_complete_send
-
Primary return code; this is a combination of ap_data_complete and ap_send.
-
ap_data_complete_confirm_send
-
Primary return code; this is a combination of ap_data_complete and ap_confirm_send.
-
ap_data_complete_confirm
-
Primary return code; this is a combination of ap_data_complete and ap_confirm_what_received.
-
ap_data_complete_confirm_deall
-
Primary return code; this is a combination of ap_data_complete and ap_confirm_deallocate.
-
AP_DATA_SEND
-
Primary return code; this is a combination of ap_data and ap_send.
-
AP_DATA_CONFIRM_SEND
-
Primary return code; this is a combination of ap_data and ap_confirm_send.
-
AP_DATA_CONFIRM
-
Primary return code; this is a combination of ap_data and ap_confirm.
-
AP_DATA_CONFIRM_DEALLOCATE
-
Primary return code; this is a combination of ap_data and ap_confirm_deallocate.
-
ap_dealloc_normal
-
Primary return code; the partner TP issued DEALLOCATE with dealloc_type set to AP_FLUSH or AP_SYNC_LEVEL with the synchronization level of the conversation specified as AP_NONE.
If rtn_status is AP_YES, examine what_rcvd also.
-
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_tp_id
-
Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.
-
ap_bad_return_status_with_data
-
Secondary return code; the specified rtn_status value was not recognized 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_invalid_semaphore_handle
-
Secondary return code; the address of the RAM semaphore or system semaphore handle was invalid.
Note APPC cannot trap all invalid semaphore handles. If the TP passes a bad RAM semaphore handle, a protection violation results.
-
ap_rcv_and_post_bad_fill
-
Secondary return code; the fill parameter was set to an invalid value.
-
ap_state_check
-
Primary return code; the verb did not execute because it was issued in an invalid state.
-
ap_rcv_and_post_bad_state
-
Secondary return code; the conversation was not in RECEIVE or SEND state when the TP issued this verb.
-
ap_rcv_and_post_not_ll_bdy
-
Secondary return code; the conversation was in SEND state; the TP began but did not finish sending a logical record.
-
ap_canceled
-
Primary return code; the local TP issued one of the following verbs, which canceled RECEIVE_AND_POST:
DEALLOCATE with dealloc_type set to AP_ABEND_PROG, AP_ABEND_SVC, or AP_ABEND_TIMER
SEND_ERROR
TP_ENDED
Issuing one of these verbs causes the semaphore to be cleared.
-
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 node used by this conversation encountered an ABEND.
-
The connection between the TP and the PU 2.1 node has been broken (a LAN error).
-
The SnaBase at the TP's computer encountered an ABEND.
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 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 can 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 a Microsoft® 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_no_trunc
-
Primary return code; the partner TP issued SEND_ERROR with err_type set to AP_PROG while the conversation was in SEND state. Data was not truncated.
-
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_prog_error_trunc
-
Primary return code; in SEND state, after sending an incomplete logical record, the partner TP issued SEND_ERROR with err_type set to AP_PROG. The local TP may have received the first part of the logical record through a receive verb.
-
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_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:
-
The partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_PROG.
-
The partner TP has encountered an ABEND, causing the partner LU to send a DEALLOCATE request.
-
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_NO_TRUNC
-
Primary return code; while in SEND state, the partner TP (or partner LU) issued SEND_ERROR with err_type set to AP_SVC. Data was not truncated.
-
AP_SVC_ERROR_PURGING
-
Primary return code; the partner TP (or partner LU) issued SEND_ERROR 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.
-
AP_SVC_ERROR_TRUNC
-
Primary return code; in SEND state, after sending an incomplete logical record, the partner TP (or partner LU) issued SEND_ERROR. The local TP may have received the first part of the logical record.
Remarks
The local TP receives data through the following process:
-
The local TP issues a receive verb until it finishes receiving a complete unit of data. The data received can be:
-
One logical record.
-
A buffer of data received independent of its logical-record format.
The local TP may need to issue the receive verb several times in order to receive a complete unit of data. After a complete unit of data has been received, the local TP can manipulate it. The receive verbs are RECEIVE_AND_POST (Windows NT, Windows 95, and OS/2), RECEIVE_AND_WAIT, and RECEIVE_IMMEDIATE.
-
The local TP issues the receive verb again. This has one of the following effects:
-
If the partner TP has sent more data, the local TP begins to receive a new unit of data.
-
If the partner TP has finished sending data or is waiting for confirmation, status information (available through what_rcvd) indicates the next action the local TP normally takes.
The following procedure shows tasks performed by the local TP in using RECEIVE_AND_POST.
To use RECEIVE_AND_POST
-
For the Windows NT and Windows 95 operating systems, the TP retrieves the WinAsyncAPPC message number by calling the RegisterWindowMessage API or allocating a semaphore. The sema field should be set to NULL if the application expects to be notified through the Windows message mechanism.
APPC sends the Windows message or clears the semaphore when the local TP finishes receiving data.
For the OS/2 operating system, the TP uses the DosSemSet function to set the semaphore pointed to by sema.
The semaphore will remain set while the local TP receives data asynchronously. APPC will clear the semaphore when the local TP finishes receiving data.
-
The TP issues RECEIVE_AND_POST.
-
The TP checks the value of primary_rc.
If primary_rc is ap_ok, the receive buffer (pointed to by dptr) is asynchronously receiving data from the partner TP. While receiving data asynchronously, the local TP can:
If, however, primary_rc is not ap_ok, RECEIVE_AND_POST has failed. In this case, the local TP does not perform the next two tasks.
-
For the Windows NT and Windows 95 operating systems, when the TP finishes receiving data asynchronously, APPC issues the WinAsyncAPPC Windows message or clears the semaphore.
For the OS/2 operating system, the TP uses the DosSemWait function to wait for APPC to clear the semaphore pointed to by sema. When the TP finishes receiving data asynchronously, APPC clears the semaphore. To prevent the local TP from waiting, have it test the semaphore (invoking DosSemWait with Timeout set to zero) until APPC clears the semaphore.
-
The TP checks the new value of primary_rc.
If primary_rc is ap_ok, the local TP can examine the other returned parameters and manipulate the asynchronously received data.
If primary_rc is not ap_ok, only secondary_rc and rts_rcvd (request-to-send received) are meaningful.
Conversation State Effects
The conversation must be in RECEIVE or SEND state when the TP issues this verb.
Issuing RECEIVE_AND_POST while the conversation is in SEND state has the following effects:
-
The local LU sends the information in its send buffer and a SEND indicator to the partner TP.
-
The conversation changes to PENDING_POST state; the local TP is ready to receive information from the partner TP asynchronously.
The conversation changes states twice:
The following table shows the new state associated with each value of what_rcvd when primary_rc is AP_OK.
what_rcvd |
New state |
AP_CONFIRM_DEALLOCATE |
CONFIRM_DEALLOCATE |
AP_DATA_COMPLETE_CONFIRM_DEALL |
CONFIRM_DEALLOCATE |
AP_DATA_CONFIRM_DEALLOCATE |
CONFIRM_DEALLOCATE |
AP_CONFIRM_SEND |
CONFIRM_SEND |
AP_DATA_COMPLETE_CONFIRM_SEND |
CONFIRM_SEND |
AP_DATA_CONFIRM_SEND |
CONFIRM_SEND |
AP_CONFIRM_WHAT_RECEIVED |
CONFIRM |
AP_DATA_COMPLETE_CONFIRM |
CONFIRM |
AP_DATA_CONFIRM |
CONFIRM |
AP_DATA |
RECEIVE |
AP_DATA_COMPLETE |
RECEIVE |
AP_DATA_INCOMPLETE |
RECEIVE |
AP_SEND |
SEND |
AP_DATA_COMPLETE_SEND |
SEND_PENDING |
The following table shows the new state associated with each value of primary_rc other than AP_OK.
primary_rc |
New state |
ap_canceled |
No change |
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_DEALLOC_NORMAL |
RESET |
ap_prog_error_purging |
RECEIVE |
ap_prog_error_no_trunc |
RECEIVE |
ap_svc_error_purging |
RECEIVE |
ap_svc_error_no_trunc |
RECEIVE |
ap_prog_error_trunc |
RECEIVE |
ap_svc_error_trunc |
RECEIVE |
End of Data for a Basic Conversation
If the local TP issues RECEIVE_AND_POST and sets fill to AP_BUFFER, the receipt of data ends when max_len or the end of the data is reached. The end of the data is indicated by either primary_rc with a value other than ap_ok (for example, ap_dealloc_normal), or by what_rcvd with one of the following values:
AP_SEND
AP_CONFIRM_SEND
AP_CONFIRM_DEALLOCATE
AP_CONFIRM_WHAT_RECEIVED
AP_DATA_CONFIRM_SEND
AP_DATA_CONFIRM_DEALLOCATE
AP_DATA_CONFIRM
To determine if the end of the data has been reached, the local TP reissues RECEIVE_AND_POST. If the new primary_rc contains ap_ok and what_rcvd contains AP_DATA, the end of the data has not been reached. If, however, the end of the data has been reached, primary_rc or what_rcvd will indicate the cause of the end of the data.
Troubleshooting
The local TP can wait indefinitely if one of the following situations occurs:
-
For the Windows NT and Windows 95 operating systems, the local TP issues a RECEIVE_AND_POST request, but either the partner TP has not sent data or the initial primary_rc is not ap_ok.
-
For the OS/2 operating system, the local TP issues a DosSemWait function call, but either the partner TP has not sent data or the initial primary_rc is not ap_ok.
This is because APPC will not issue the Windows message or clear the semaphore.
When a condition resulting in one of the following primary_rc parameters occurs, APPC does not clear the semaphore:
AP_INVALID_SEMAPHORE_HANDLE
AP_INVALID_VERB_SEGMENT
AP_STACK_TOO_SMALL
To test what_rcvd, issue RECEIVE_AND_POST with max_len set to zero, so that the local TP can determine whether the partner TP has data to send, seeks confirmation, or has changed the conversation state.