[MC_]RECEIVE_IMMEDIATE

The [MC_]RECEIVE_IMMEDIATE verb receives any data or status information that is currently available from the partner transaction program. If none is currently available, the local transaction program returns immediately and does not wait.

VCB Structure

typedef struct receive_immediate
{
 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 short      what_rcvd;         /* what received              */
 unsigned char       rtn_status;        /* return status with data    */
 unsigned char       fill;              /* data fill                  */
 unsigned char       rts_rcvd;          /* request to send received   */
 unsigned char       expd_data_rcvd;    /* expedited data received    */
 unsigned short      max_len;           /* maximum length of received */
                                        /* data                       */
 unsigned short      dlen;              /* actual length of received  */
                                        /* data                       */
 unsigned char      *dptr;              /* pointer to data buffer     */
 unsigned char       reserv5[5];        /* reserved                   */
} RECEIVE_IMMEDIATE;
typedef struct mc_receive_immediate
{
 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 short    what_rcvd;           /* what received              */
 unsigned char     rtn_status;          /* return status with data    */
 unsigned char     reserv4;             /* reserved                   */
 unsigned char     rts_rcvd;            /* request to send received   */
 unsigned char     expd_data_rcvd;      /* expedited data received    */
 unsigned short    max_len;             /* maximum length of received */
                                        /* data                       */
 unsigned short    dlen;                /* actual length of received  */
                                        /* data                       */
 unsigned char    *dptr;                /* pointer to data buffer     */
 unsigned char     reserv6[5];          /* reserved                   */
} MC_RECEIVE_IMMEDIATE;

Supplied Parameters

The transaction program supplies the following parameters to Personal Communications:
opcode
AP_B_RECEIVE_IMMEDIATE
Displays a basic verb icon.
AP_M_RECEIVE_IMMEDIATE
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.

On full-duplex conversations, this flag must be ORed together with AP_FULL_DUPLEX_CONVERSATION.

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 [MC_]ALLOCATE verb in the invoking transaction program or by RECEIVE_ALLOCATE in the invoked transaction program.

rtn_status
Indicates whether status information and data can be returned on the same verb.
  • AP_YES
  • AP_NO
fill
Displays a basic verb icon.

 

Indicates the manner in which the local transaction program receives data.

  • AP_BUFFER
  • AP_LL
max_len
Maximum number of bytes of data the local transaction program can receive.

Range: 0–65535

This value must not exceed the length of the buffer to contain the received data.

dptr
Address of the buffer to contain the data received by the local LU. The application can append data to the end of the VCB, in which case dptr must be set to NULL.

Returned Parameters

If the verb executes successfully, Personal Communications returns the following parameters:
primary_rc
AP_OK

AP_DEALLOC_NORMAL

what_rcvd
Status information received with the incoming data. If rtn_status is set to AP_NO, this field always contains a value from the following list:
  • AP_NONE
  • AP_CONFIRM_DEALLOCATE
  • AP_CONFIRM_SEND
  • AP_CONFIRM_WHAT_RECEIVED
  • AP_DATA
  • AP_DATA_COMPLETE
  • AP_DATA_INCOMPLETE
  • AP_SEND
    Displays a basic verb icon.
  • AP_USER_CONTROL_DATA_COMPLETE
    Displays a mapped verb icon.
  • AP_USER_CONTROL_DATA_INCMP
    Displays a mapped verb icon.
  • AP_PS_HEADER_COMPLETE
    Displays a mapped verb icon.
  • AP_PS_HEADER_INCOMPLETE
    Displays a mapped verb icon.
  • AP_DATA_CONFIRM
    Displays a basic verb icon.
  • AP_DATA_COMPLETE_CONFIRM
  • AP_DATA_CONFIRM_DEALLOCATE
  • AP_DATA_COMPLETE_CONFIRM_DEALL
  • AP_DATA_CONFIRM_SEND
  • AP_DATA_COMPLETE_CONFIRM_SEND
  • AP_DATA_SEND
    Displays a basic verb icon.

If rtn_status is set to AP_YES, this field can contain any value from either the previous list or the following list.

The following parameters apply to mapped only:
Displays a mapped verb icon.
  • AP_DATA_COMPLETE_SEND
  • AP_UC_DATA_COMPLETE_CONFIRM
  • AP_UC_DATA_COMPLETE_CNFM_DEALL
  • AP_UC_DATA_COMPLETE_CNFM_SEND
  • AP_UC_DATA_COMPLETE_SEND
  • AP_PS_HDR_COMPLETE_CONFIRM
  • AP_PS_HDR_COMPLETE_CNFM_DEALL
  • AP_PS_HDR_COMPLETE_CNFM_SEND
  • AP_PS_HDR_COMPLETE_SEND
expd_data_rcvd
Expedited-data-received indicator.
  • AP_YES
  • AP_NO
rts_rcvd
Request-to-send-received indicator.
  • AP_YES
  • AP_NO
dlen
This parameter is only used if the what_rcvd parameter indicates that data was received. Number of bytes of data received (the data is stored in the buffer specified by the dptr parameter). A length of zero indicates that no data was received.
If the verb is nonblocking and has not completed, Personal Communications returns the following parameter.
primary_rc
AP_OPERATION_INCOMPLETE
opext
AP_BASIC_CONVERSION or AP_MAPPED_CONVERSATION ORed together with

AP_NON_BLOCKING ORed together with
AP_OPERATION_INCOMPLETE_FLAG

If no data is immediately available from the partner transaction program, Personal Communications returns the following parameter.
primary_rc
AP_UNSUCCESSFUL
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_RETURN_STATUS_WITH_DATA
  • AP_BAD_TP_ID
  • AP_RCV_IMMD_BAD_FILL
    Displays a basic verb icon.
If the conversation is in the wrong state when the transaction program issues this verb, Personal Communications returns the following parameters:
primary_rc
AP_STATE_CHECK
secondary_rc
AP_RCV_IMMD_BAD_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
AP_DEALLOC_ABEND_SVC
AP_DEALLOC_ABEND_SVC
AP_DEALLOC_ABEND_SVC
AP_DEALLOC_ABEND_SVC
AP_DEALLOC_ABEND_SVC
AP_DEALLOC_ABEND_TIMER
AP_DEALLOC_NORMAL
AP_PROG_ERROR_NO_TRUNC
AP_PROG_ERROR_PURGING

AP_PROG_ERROR_TRUNC
Displays a basic verb icon.
AP_SVC_ERROR_NO_TRUNC
Displays a basic verb icon.
AP_SVC_ERROR_PURGING
Displays a basic verb icon.
AP_SVC_ERROR_TRUNC
Displays a basic verb icon.

AP_TP_BUSY
AP_CONVERSATION_TYPE_MIXED
AP_UNEXPECTED_SYSTEM_ERROR
AP_DUPLEX_TYPE_MIXED
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_]RECEIVE_IMMEDIATE 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_]RECEIVE_IMMEDIATE verb. See [MC_]SEND_DATA for a list of error return codes.