MC_RECEIVE_AND_WAIT

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

For the Microsoft® Windows® version 3.x system, it is recommended that you use WinAsyncAPPC rather than the blocking version of this call. To allow full use to be made of the asynchronous support, asynchronously issued MC_RECEIVE_AND_WAIT verbs have been altered to act like MC_RECEIVE_AND_POST verbs. Specifically, while an asynchronous MC_RECEIVE_AND_WAIT is outstanding, the following verbs can be issued on the same conversation:

GET_TYPE

MC_GET_ATTRIBUTES

MC_REQUEST_TO_SEND

MC_SEND_ERROR

MC_TEST_RTS

TP_ENDED

This allows an application, and in particular, a 5250 emulator, to use an asynchronous MC_RECEIVE_AND_WAIT to receive data. While the MC_RECEIVE_AND_WAIT is outstanding, it can still use MC_SEND_ERROR and MC_REQUEST_TO_SEND. It is recommended that you use this feature for full asynchronous support.

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

struct mc_receive_and_wait {
    unsigned short      opcode;
    unsigned char       opext;
    unsigned char       reserv2;
    unsigned short      primary_rc;
    unsigned long       secondary_rc;
    unsigned char       tp_id[8];
    unsigned long       conv_id;
    unsigned short      what_rcvd;
    unsigned char       rtn_status;
    unsigned char       reserv4;
    unsigned char       rts_rcvd;
    unsigned char       reserv5;
    unsigned short      max_len;
    unsigned short      dlen;
    unsigned char FAR * dptr;
    unsigned char       reserv6[5];
}; 
 

Members

opcode
Supplied parameter. Specifies the verb operation code, AP_M_RECEIVE_AND_WAIT.
opext
Supplied parameter. Specifies the verb operation extension, AP_MAPPED_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. Specifies the conversation identifier.

The value of this parameter is returned by MC_ALLOCATE in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.

what_rcvd
Returned parameter. Indicates whether data or conversation status was received.
rtn_status
Supplied parameter. Indicates whether both data and conversation status indicators should be returned within one API call.
rts_rcvd
Returned parameter. Contains the request-to-send indicator.
max_len
Supplied parameter. Indicates the maximum number of bytes of data the local TP can receive. The range is from 0 through 65535.

For the Windows NT and Windows 95 operating systems and the Windows graphical environment, this value must not exceed the length of the buffer to contain the received data.

For the OS/2 operating system, the offset of dptr plus the value of max_len must not exceed the size of the data segment.

By issuing MC_RECEIVE_AND_WAIT with max_len set to zero, the local TP can determine whether the partner TP has data to send, seeks confirmation, or has changed the conversation state.

dlen
Returned parameter. Indicates the number of bytes of data received. Data is stored in the buffer specified by dptr. A length of zero indicates that no data was received.
dptr
Supplied parameter. Provides the address of the buffer to contain the data received by the local TP.

For the Windows NT and Windows 95 operating systems and the Windows graphical environment, the data buffer can reside in a static data area or in a globally allocated area. The data buffer must fit entirely within this area.

For the OS/2 operating system, the data buffer must reside on an unnamed, shared segment, which is allocated by the DosAllocSeg function with Flags equal to 1. The data buffer must fit entirely on the data segment.

For the Windows environment, the data buffer can reside in a static data area or in a globally allocated area. The data buffer must fit entirely within this area.

Return Codes

ap_ok
Primary return code; the verb executed successfully.

When rtn_status is ap_yes, the preceding return code or one of the following return codes can be returned.

AP_DATA_COMPLETE_SEND
Primary return code; this is a combination of ap_data_complete and ap_send.
AP_DATA_COMPLETE_CONFIRM_SEND
Primary return code; this is a combination of ap_data_complete and ap_confirm_send.
AP_DATA_COMPLETE_CONFIRM
Primary return code; this is a combination of ap_data_complete and ap_confirm_what_received.
AP_DATA_COMPLETE_CONFIRM_DEALL
Primary return code; this is a combination of ap_data_complete and ap_confirm_deallocate.
ap_dealloc_normal
Primary return code; the partner TP has deallocated the conversation without requesting confirmation and issued MC_DEALLOCATE with dealloc_type set to one of the following:

If rtn_status is AP_YES, examine what_rcvd also.

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_bad_return_status_with_data
Secondary return code; the specified rtn_status value was not recognized by APPC.
ap_invalid_data_segment
Secondary return code; the length specified for the data buffer was longer than the segment allocated to contain the buffer.
ap_state_check
Primary return code; the verb did not execute because it was issued in an invalid state.
ap_rcv_and_wait_bad_state
Secondary return code; the conversation was not in RECEIVE or SEND state when the TP issued this verb.
ap_allocation_error
Primary return code; APPC has failed to allocate a conversation. The conversation state is set to RESET.

This code may be returned through a verb issued after MC_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 system administrator should examine the error log to determine the reason for the ABEND.

ap_conv_failure_no_retry
Primary return code; the conversation was terminated because of a permanent condition, such as a session protocol error. The system administrator should examine the system error log to determine the cause of the error. Do not retry the conversation until the error has been corrected.
ap_conv_failure_retry
Primary return code; the conversation was terminated because of a temporary error. Restart the TP to see if the problem occurs again. If it does, the system administrator should examine the error log to determine the cause of the error.
ap_conversation_type_mixed
Primary return code; the TP has issued both basic and mapped conversation verbs. Only one type can be issued in a single conversation.
ap_invalid_verb_segment
Primary return code; the VCB extended beyond the end of the data segment.
ap_prog_error_no_trunc
Primary return code; the partner TP has issued MC_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 MC_SEND_ERROR. Data sent but not yet received is purged.
ap_stack_too_small
Primary return code; the stack size of the application is too small to execute the verb. Increase the stack size of your application.
ap_conv_busy
Primary return code; there can only be one outstanding conversation verb at a time on any conversation. This can occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same conv_id.
ap_thread_blocking
Primary return code; the calling thread is already in a blocking call.
ap_unexpected_dos_error
Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.
ap_dealloc_abend
Primary return code; the conversation has been deallocated for one of the following reasons:

Remarks

The local TP receives data through the following process:

  1. The local TP issues a receive verb until it finishes receiving a complete unit of data. The data received is one data record.

    The local TP may need to issue the receive verb several times in order to receive a complete unit of data. After a complete unit of data has been received, the local TP can manipulate it.

    The receive verbs are MC_RECEIVE_AND_POST (Windows NT, Windows 95, and OS/2 operating systems), MC_RECEIVE_AND_WAIT, and MC_RECEIVE_IMMEDIATE.

  2. The local TP issues the receive verb again. This has one of the following effects:

The conversation must be in RECEIVE or SEND state when the TP issues this verb.

Issuing the Verb in SEND State

Issuing MC_RECEIVE_AND_WAIT while the conversation is in SEND state has the following effects:

State Change

The new conversation state is determined by the following factors:

Verb Issued in SEND State

The following table details the state changes when MC_RECEIVE_AND_WAIT is issued in SEND state and primary_rc is ap_ok.

what_rcvd New state
AP_CONFIRM_DEALLOCATE confirm_deallocate
AP_DATA_COMPLETE_CONFIRM_DEALL confirm_deallocate
AP_DATA_CONFIRM_DEALLOCATE confirm_deallocate
AP_CONFIRM_SEND confirm_send
AP_DATA_COMPLETE_CONFIRM_SEND confirm_send
AP_DATA_CONFIRM_SEND confirm_send
AP_CONFIRM_WHAT_RECEIVED confirm
AP_DATA_COMPLETE_CONFIRM confirm
AP_DATA_CONFIRM confirm
AP_DATA receive
AP_DATA_COMPLETE receive
AP_DATA_INCOMPLETE receive
AP_SEND No change
AP_DATA_COMPLETE_SEND send_pending

The following table details the state changes when MC_RECEIVE_AND_WAIT is issued in SEND state and primary_rc is not ap_ok.

primary_rc New state
ap_allocation_error reset
ap_conv_failure_retry reset
ap_conv_failure_no_retry reset
ap_dealloc_abend reset
ap_dealloc_abend_prog reset
ap_dealloc_abend_svc reset
ap_dealloc_abend_timer reset
ap_dealloc_normal RESET
ap_prog_error_purging receive
ap_prog_error_no_trunc receive
ap_svc_error_purging receive
ap_svc_error_no_trunc receive

Verb Issued in RECEIVE State

The following table details the state changes when MC_RECEIVE_AND_WAIT is issued in RECEIVE state and primary_rc is ap_ok.

what_rcvd New state
ap_confirm_deallocate confirm_deallocate
ap_data_complete_confirm_deall confirm_deallocate
ap_data_confirm_deallocate confirm_deallocate
ap_confirm_send confirm_send
ap_data_complete_confirm_send confirm_send
ap_data_confirm_send confirm_send
ap_confirm_what_received confirm
ap_data_complete_confirm confirm
ap_data_confirm confirm
ap_data No change
ap_data_complete No change
ap_data_incomplete No change
ap_send send
ap_data_complete_send send_pending

The following table details the state changes when MC_RECEIVE_AND_WAIT is issued in RECEIVE state and primary_rc is not ap_ok.

primary_rc New state
ap_allocation_error reset
ap_conv_failure_retry reset
ap_conv_failure_no_retry reset
ap_dealloc_abend reset
ap_dealloc_abend_prog reset
ap_dealloc_abend_svc reset
ap_dealloc_abend_timer reset
ap_dealloc_normal reset
ap_prog_error_purging No change
ap_prog_error_no_trunc No change
ap_svc_error_purging No change
ap_svc_error_no_trunc No change
ap_prog_error_trunc No change
ap_svc_error_trunc No change