POST_ON_RECEIPT

The POST_ON_RECEIPT verb allows the application to register to receive a notification when data or status arrives at the local LU without actually receiving it at the same time. This verb can only be issued while in RECEIVE state and it never causes a change in conversation state. This verb is only supported on Microsoft® Windows NT® and Microsoft® Windows® 95 by Microsoft® SNA Server version 3.0 with Service Pack 1 or later and by SNA Server version 4.0.

When the TP issues this verb, APPC returns control to the TP immediately. When the specified conditions are satisfied the Win32® event specified by the sema parameter is signalled and the verb completes. Then the TP looks at the return code in the verb control block to determine whether or not any data or status notification has arrived at the local LU and issues a RECEIVE_IMMEDIATE or RECEIVE_AND_WAIT verb to actually receive the data or status notification.

The POST_ON_RECEIPT verb implements both the POST_ON_RECEIPT and TEST verbs as described in the IBM Transaction Programmer's manual for LU Type 6.2.

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

struct post_on_receipt {
    unsigned short   opcode;
    unsigned char    opext;
    unsigned char    reserv1;
    unsigned char    primary_rc;
    unsigned long    secondary_rc;
    unsigned char    tp_id[8];
    unsigned long    conv_id;
    unsigned short   reserv2;
    unsigned char    fill;
    unsigned char    reserv4;
    unsigned short   max_len;
    unsigned short   reserv5;
    unsigned char *  reserv6;
    unsigned char    reserv7[5];
    unsigned long    sema;
};

Members

opcode

Supplied parameter. Specifies the verb operation code, AP_B_POST_ON_RECEIPT.

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.

fill

Supplied parameter. Specifies how the local TP receives data. The following values are allowed:

AP_BUFFER: Specifies that APPC should post a notification when the number of data bytes specified by max_len have arrived at the local LU, the end of the data has been reached, or information other than data is received.(such as a conversation status, a confirmation, or a syncpoint request).
AP_LL: Specifies that APPC should post a notification when a complete or truncated logical record is received, when a portion of a logical record is received which is at least equal in length to the length specified by max_len, or when information other than data is received.

max_len

Supplied parameter. Specifies the length of data that triggers APPC to post a notification to the TP.

sema

Supplied parameter. Specifies the handle of a Win32 event. The event should have been created by the TP and the TP is responsible for ensuring that it is reset before a call is made and after the verb completes.

Return Codes

ap_ok

Primary return code; the verb executed successfully.

ap_data: Secondary return code; data is available for the program to receive.
ap_not_data: Secondary return code; information other than data is available for the program to receive.

ap_cancelled

Primary return code; the verb was canceled.

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_invalid_semaphore_handle: Secondary return code; the sema parameter was not set to a valid value.

ap_state_check

Primary return code; the verb did not execute because it was issued in an invalid state.

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.

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_dealloc_normal

Primary return code; the partner TP has deallocated the conversation without requesting confirmation and issued DEALLOCATE with dealloc_type set to one of the following:

AP_CONFIRM_SYNC_LEVEL
AP_FLUSH
AP_SYNC_LEVEL with the synchronization level of the conversation specified as AP_NONE

ap_prog_error_no_trunc

Primary return code; the partner TP has issued SEND_ERROR 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. Data sent but not yet received is purged.

ap_prog_error_trunc

Primary return code; the partner TP has issued SEND_ERROR while the conversation was in SEND state. Data was truncated.

ap_svc_error_no_trunc

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 was not truncated.

ap_svc_error_purging

ap_svc_error_trunc

Remarks

While a POST_ON_RECEIPT verb is outstanding, the following verbs can be issued on the same conversation:

RECEIVE_IMMEDIATE

Issuing any of the following verbs prior to completion of the asynchronous POST_ON_RECEIPT verb causes the POST_ON_RECEIPT verb to be canceled (the Win32 event is signaled and the primary return code in the verb control block is set to AP_CANCELLED).

DEALLOCATE

RECEIVE_AND_WAIT

RECEIVE_IMMEDIATE

SEND_ERROR

TP_ENDED