[MC_]PREPARE_TO_RECEIVE

The PREPARE_TO_RECEIVE verb changes the state of the conversation for the local transaction program from SEND or SEND_PENDING to RECEIVE.

Before changing the conversation state, this verb performs the equivalent of one of the following verbs:
  • The FLUSH verb, which sends the contents of the local LU's send buffer to the partner LU (and transaction program).
  • The CONFIRM verb, which send the contents of the local LU's send buffer and a confirmation request to the partner transaction program.

After this verb has successfully executed, the local transaction program can receive data.

VCB Structure

typedef struct prepare_to_receive
{
 unsigned short    opcode;               /* verb operation code      */
 unsigned char     opext;                /* verb extension code      */
 unsigned char     format;               /* format                   */
 unsigned short    primary_rc;           /* primary return code      */
 unsigned long     secondary_rc;         /* secondary return code    */
 unsigned char     tp_id[8];             /* TP identifier            */
 unsigned long     conv_id;              /* conversation identifier  */
 unsigned char     ptr_type;             /* prepare to receive type  */
 unsigned char     locks;                /* prepare to receive locks */
} PREPARE_TO_RECEIVE;
typedef struct mc_prepare_to_receive
{
 unsigned short     opcode;              /* verb operation code      */
 unsigned char      opext;               /* verb extension code      */
 unsigned char      format;              /* format                   */
 unsigned short     primary_rc;          /* primary return code      */
 unsigned long      secondary_rc;        /* secondary return code    */
 unsigned char      tp_id[8];            /* TP identifier            */
 unsigned long      conv_id;             /* conversation identifier  */
 unsigned char      ptr_type;            /* prepare to receive type  */
 unsigned char      locks;               /* prepare to receive locks */
} MC_PREPARE_TO_RECEIVE;

Supplied Parameters

The transaction program supplies the following parameters to Personal Communications:
opcode
AP_B_PREPARE_TO_RECEIVE
Displays a basic verb icon.
AP_M_PREPARE_TO_RECEIVE
Displays a mapped verb icon.
opext
AP_BASIC_CONVERSATION or AP_MAPPED_CONVERSATION. For nonblocking operation, this flag can be ORed together with AP_NON_BLOCKING.
format
Identifies the format of the VCB. Set this field to zero to specify the version of the VCB listed above.
tp_id
Identifier for the local transaction program. The value of this parameter was returned by the TP_STARTED verb in the invoking transaction program or by RECEIVE_ALLOCATE in the invoked transaction program.
conv_id
Conversation identifier.

The value of this parameter was returned by the ALLOCATE verb in the invoking transaction program or by RECEIVE_ALLOCATE in the invoked transaction program.

ptr_type
Specifies how to perform the state change.

AP_FLUSH
AP_SYNC_LEVEL
AP_P_TO_R_CONFIRM

locks
Specifies when Personal Communications is to return control to the local transaction processor.
  • AP_LONG
  • AP_SHORT

Returned Parameters

If the verb executes successfully, Personal Communications returns the following parameter:
primary_rc
AP_OK
If the verb is nonblocking and has not completed, Personal Communications returns the following parameters;
primary_rc
AP_OPERATION_INCOMPLETE
opext
AP_OPERATION_INCOMPLETE_FLAG
If the verb does not execute because of a parameter error, Personal Communications returns the following parameters:
primary_rc
AP_PARAMETER_CHECK
secondary_rc
AP_BAD_CONV_ID

AP_BAD_TP_ID
AP_P_TO_R_INVALID_FOR_FDX
AP_P_TO_R_INVALID_TYPE

If the conversation is in the wrong state when the transaction processor issues this verb, Personal Communications returns the following parameters:
primary_rc
AP_STATE_CHECK
secondary_rc
AP_TO_R_NOT_LL_BDY
Displays a basic verb icon.

AP_P_TO_R_NOT_SEND_STATE

The conditions generating the following possible primary return codes (primary_rc) and indented secondary return codes (secondary_rc) are described in APPC Common Return Codes.

AP_ALLOCATION_ERROR

  • AP_SECURITY_NOT_VALID
  • AP_TRANS_PGM_NOT_AVAIL_RETRY
  • AP_TRANS_PGM_NOT_AVAIL_NO_RTRY
  • AP_TP_NAME_NOT_RECOGNIZED
  • AP_PIP_NOT_ALLOWED
  • AP_PIP_NOT_SPECIFIED_CORRECTLY
  • AP_CONVERSATION_TYPE_MISMATCH
  • AP_SYNC_LEVEL_NOT_SUPPORTED
  • AP_CONV_FAILURE_NO_RETRY
  • AP_CONV_FAILURE_RETRY
  • AP_DEALLOC_ABEND
    Displays a mapped verb icon.
  • AP_DEALLOC_ABEND_PROG
    Displays a basic verb icon.
  • AP_DEALLOC_ABEND_SVC
    Displays a basic verb icon.
  • AP_DEALLOC_ABEND_TIMER
    Displays a basic verb icon.
  • AP_PROG_ERROR_PURGING
    Displays a basic verb icon.
  • AP_SVC_ERROR_PURGING
    Displays a basic verb icon.
  • AP_TP_BUSY
  • AP_CONVERSATION_TYPE_MIXED
  • AP_UNEXPECTED_SYSTEM_ERROR
  • AP_CANCELLED
Note:
For performance reasons, the SNA API client can return a successful return code on the [MC_]SEND_DATA verb without forwarding it to the server. When a subsequent [MC_]PREPARE_TO_RECEIVE verb is issued, the [MC_]SEND_DATA is forwarded to the server for processing. If there is a [MC_]SEND_DATA error return code, it is returned on the [MC_]PREPARE_TO_RECEIVE verb. See [MC_]SEND_DATA for a list of error return codes.