Post_on_Receipt

Requests to be notified when data or status is ready to be received for a specified conversation. Specifically, Post_on_Receipt notifies the caller (through an ECB the caller specifies) for the following situations:

A complete logical record is available to be received from a partner program
Conversation status (control information) is available
A non-zero return code is available to be received because of an action taken by the partner program (such as deallocating the conversation).

When Post_on_Receipt posts the specified ECB, the caller can determine which of the preceding information is available by calling the Receive_and_Wait or Receive_Immediate service and checking the returned parameters.

You can call the Post_on_Receipt service in Receive state only, and it does not alter the conversation state. This function only applies to basic conversations.

Asynchronous Processing

To be notified asynchronously when data or status is ready for you to receive on a conversation, you can use the Post_on_Receipt service. APPC/MVS posts the ECB specified by the ECB_address parameter when data or status, or both, is available to be received. The caller is free to call other conversation services (such as Request_to_Send) while APPC/MVS processes the Post_on_Receipt request asynchronously.

Your call to Post_on_Receipt remains in effect until the specified ECB is posted, or the call is cancelled. Thereafter, to obtain subsequent notification of data or status to be received, issue a new call to the Post_on_Receipt service.

APPC/MVS cancels an active Post_on_Receipt request if the caller issues any of the following services on the same conversation:

Receive_Immediate
Receive_and_Wait
Deallocate (with the deallocate_type parameter set to deallocate_abend)
Send_Error.

You can call the Post_on_Receipt service any number of times on a given conversation. However, if you call the Post_on_Receipt service multiple times before the specified ECB is posted, only one post can occur. In this situation, APPC/MVS posts the ECB that was specified on the most recent call to the Post_on_Receipt service.

Receiving Asynchronous Notification

When asynchronous processing is complete, the POST completion code in the ECB is the return code for the service. Post_on_Receipt posts the ECB with a completion code of 0 when information is available. You can then determine what this information is by calling either the Receive_and_Wait or Receive_Immediate services. These services return the following information about the specified conversation:

There is a complete logical record is available to be received from the partner program (see the Data_received parameter returned by Receive_and_Wait or Receive_Immediate).
There is a change in conversation status, to one of the following (as shown in the Status_received parameter returned by Receive_and_Wait or Receive_Immediate):
- Send_received
- Confirm_received
- Confirm_send_received
- Confirm_deallocate_received.
Note that Post_on_Receipt does not notify the caller for a Request_To_Send Received condition.
A previous call by the partner program on this conversation caused one of the following non-zero return codes (indicated in the Return_code parameter of Receive_and_Wait or Receive_Immediate):
- 3 - Conversation_type_mismatch
- 5 - Pip_not_specified_correctly
- 6 - Security_not_valid
- 8 - Sync_lvl_not_supported_pgm
- 9 - TPN_not_recognized
- 10 - TP_not_available_no_retry
- 11 - TP_not_available_retry
- 17 - Deallocated_abend
- 18 - Deallocated_normal
- 21 - Program_error_no_trunc
- 22 - Program_error_purging
- 23 - Program_error_trunc
- 26 - Resource_failure_no_retry
- 27 - Resource_failure_retry
- 30 - Deallocated_abend_SVC
- 31 - Deallocated_abend_timer
- 32 - SVC_error_no_trunc
- 33 - SVC_error_purging
- 34 - SVC_error_trunc

Post_on_Receipt posts the caller's ECB with a non-zero POST return code if the service ends unsuccessfully. For example, if the APPC address space is cancelled before information for the conversation becomes available, Post_on_Receipt posts the caller's ECB with a return code of product_specific_error.

Requirements

Authorization:

Supervisor state or problem state, any PSW key

Dispatchable unit mode:

Task or SRB

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31-bit

ASC mode:

Primary or access register (AR)

Interrupt status:

Enabled for I/O and external interrupts

Locks:

Unlocked

Control parameters:

All parameters must be addressable by the caller in the primary address space.

Format

Figure 1. ATBPOR2 - Post_on_Receipt

CALL ATBPOR2(
        Conversation_id,
        ECB_address,
        Return_code
       );

Parameters

Conversation_id

Supplied parameter

Type: Character string
Char Set: No restriction
Length: 8 bytes

Conversation_id, sometimes called the resource identifier, identifies a conversation to the system.

ECB_address

Supplied parameter

Type: Address
Char Set: N/A
Length: 32 bits

ECB_address specifies the address of a fullword that specifies the address of the ECB to be posted. The ECB must reside in the caller's home address space.

Return_code

Returned parameter

Type: Integer
Char Set: N/A
Length: 32 bits

Return_code specifies the result of the call. See the next section for descriptions of return codes that can be returned to a caller of Post_On_Receipt.

Return Codes

Valid return code values for the Return_code parameter are:

Table 1. Return Codes for the Post_on_Receipt Service
Return Code	Value, Meaning, and Action
0	Value: OK Meaning: The call completed successfully. System Action: The system continues processing. Application Programmer Response: None required.
20	Value: Product_specific_error Meaning: The system found a product-specific error. System Action: The system might write symptom records, which describe the error, to the logrec data set. Application Programmer Response: See Diagnosing Problems with APPC/MVS TPs for methods to use to diagnose the return code. See Error_Extract for the Error_Extract calling format. If necessary, see Diagnosing Product-Specific Errors for more information about product-specific errors.
24	Value: Program_parameter_check Meaning: The system detected a program parameter check. System Action: The system returns this return code to the caller of the APPC service in error. Application Programmer Response: See Diagnosing Problems with APPC/MVS TPs for methods to use to diagnose the return code. See Error_Extract for the Error_Extract calling format.
25	Value: Program_state_check Meaning: The local TP called a service while running in a state in which the call is not valid. The TP should not examine any other returned variables associated with the call because nothing is placed in those variables. System Action: The state of the conversation remains unchanged. For a list of states that are valid for each call, see APPC/MVS Conversation State Table. Application Programmer Response: See Diagnosing Problems with APPC/MVS TPs for methods to use to diagnose the return code. See Error_Extract for the Error_Extract calling format.

Restrictions

When using this service, observe the following restrictions:

Call Post_on_Receipt only for basic conversations; do not call the service for mapped conversations. If you call the service for a mapped conversation, the service returns a return code of program_parameter_check.
If running in task mode, do not have any enabled unlocked task (EUT) functional recovery routines (FRRs) established. For more information about EUT FRRs, see the section on providing recovery in z/OS MVS Programming: Authorized Assembler Services Guide.
Call Post_on_Receipt in receive state only. If you call the service in a state other than Receive state, the service returns a return code of program_state_check.
Do not call the Post_on_Receipt service when another callable service is outstanding on the specified conversation. If you call the service while another service is in effect, Post_on_Receipt returns a return code of product_specific_error.