[MC]RECEIVE_AND_WAIT

The RECEIVE_AND_WAIT verb receives any data that is currently available from the partner transaction program. If no data is currently available, the local transaction program waits for data to arrive.

For half-duplex conversations:
The program can issue this verb when the conversation is in send state. In this case, the LU flushes its send buffer, sending all buffered information and the SEND indication to the remote program. This changes the conversation to receive state. The LU then waits for information to arrive. The remote program can send data to the local program after it receives the SEND indication.
For full-duplex conversations:
If the send buffer contains the conversation allocation request, it will be flushed; otherwise, this verb will not cause the LU to flush its send buffer. If it is important that the data remaining in the send buffer be transmitted before receiving data, the local program should issue a FLUSH before issuing this verb.

VCB Structure

typedef struct receive_and_wait
{
 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_AND_WAIT;
typedef struct mc_receive_and_wait
{
 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_AND_WAIT;

Supplied Parameters

The transaction program supplies the following parameters to Personal Communications:
opcode
AP_B_RECEIVE_AND_WAIT
Displays a basic verb icon.

AP_M_RECEIVE_AND_WAIT

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 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
    Displays a basic verb icon.
  • AP_DATA_COMPLETE
  • AP_DATA_INCOMPLETE
  • AP_SEND
  • 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
    Displays a basic verb icon.
  • AP_DATA_COMPLETE_CONFIRM_DEALL
  • AP_DATA_CONFIRM_SEND
    Displays a basic verb icon.
  • AP_DATA_COMPLETE_CONFIRM_SEND
  • AP_DATA_SEND
    Displays a basic verb icon.
  • AP_DATA_COMPLETE_SEND

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_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
rts_rcvd
Request-to-send-received indicator.
  • AP_YES
  • AP_NO

This format of the following verb is the format 1 version of the VCB. See Full-Duplex VCBs for more details on accessing format 1 VCBs.

expd_data_rcvd
Expedited-data-received indicator. This indication continues to be set to AP_YES until a RECEIVE_EXPEDITED_DATA is issued.
  • 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 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_RETURN_STATUS_WITH_DATA
  • AP_BAD_TP_ID
  • AP_RCV_AND_WAIT_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_AND_WAIT_BAD_STATE

AP_RCV_AND_WAIT_NOT_LL_BDY

Displays a basic verb icon.

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_NORMAL
  • AP_PROG_ERROR_NO_TRUNC
  • AP_PROG_ERROR_PURGING
  • AP_TP_BUSY
  • AP_CONVERSATION_TYPE_MIXED
  • AP_DUPLEX_TYPE_MIXED
  • AP_UNEXPECTED_SYSTEM_ERROR
  • AP_CANCELLED
The following parameters apply to basic only:
Displays a basic verb icon.

AP_DEALLOC_ABEND_PROG
AP_DEALLOC_ABEND_SVC
AP_DEALLOC_ABEND_TIMER
AP_PROG_ERROR_TRUNCL
AP_SVC_ERROR_NO_TRUNC
AP_SVC_ERROR_PURGING
AP_SVC_ERROR_TRUNC

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_AND_WAIT 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_AND_WAIT verb. See [MC_]SEND_DATA for a list of error return codes.
Parent topic: APPC Verbs