MC_CONFIRM
The MC_CONFIRM verb sends the contents of the local LU's send buffer and a confirmation request to the partner TP.
For the Microsoft® Windows® version 3.x system, it is recommended that you use WinAsyncAPPC rather than the blocking version of this call.
The following structure describes the verb control block used by the MC_CONFIRM verb.
struct mc_confirm {
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 char rts_rcvd;
};
Members
-
opcode
-
Supplied parameter. Specifies the verb operation code, AP_M_CONFIRM.
-
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 was returned by TP_STARTED.
-
conv_id
-
Returned parameter. Identifies the conversation established between the two TPs.
-
rts_rcvd
-
Returned parameter. Indicates whether the partner TP issued MC_REQUEST_TO_SEND, which requests the local TP to change the conversation to RECEIVE state.
To change to RECEIVE state operating on Microsoft® Windows NT® or Windows 95, the local TP can use MC_PREPARE_TO_RECEIVE, MC_RECEIVE_AND_WAIT, or MC_RECEIVE_AND_POST.
To change to RECEIVE state operating on Windows 3.x, the local TP can use MC_PREPARE_TO_RECEIVE or MC_RECEIVE_AND_WAIT.
To change to RECEIVE state operating on OS/2, the local TP can use MC_RECEIVE_AND_POST.
Return Codes
-
ap_ok
-
Primary return code; the verb executed successfully.
-
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_confirm_on_sync_level_none
-
Secondary return code; the local TP attempted to use MC_CONFIRM in a conversation with a synchronization level of AP_NONE. The synchronization level, established by MC_ALLOCATE, must be AP_CONFIRM_SYNC_LEVEL.
-
ap_state_check
-
Primary return code; the verb did not execute because it was issued in an invalid state.
-
ap_confirm_bad_state
-
Secondary return code; the conversation was not in SEND state.
-
ap_confirm_not_ll_bdy
-
Secondary return code; the conversation for the local TP was in SEND state, and the local TP did not finish sending a logical record.
-
ap_allocation_error
-
Primary return code; APPC has failed to allocate a conversation. The conversation state is set to RESET.
This code can 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, AP_CONFIRM_SYNC_LEVEL, or AP_SYNCPT) 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 node used by this conversation encountered an ABEND.
-
The connection between the TP and the PU 2.1 node has been broken (a LAN error).
-
The SnaBase at the TP's computer has encountered an ABEND.
The system administrator should examine the error log to determine the reason for the ABEND.
-
ap_comm_subsystem_not_loaded
-
Primary return code; a required component could not be loaded or terminated while processing the verb. Thus, communication could not take place. Contact the system administrator for corrective action.
When this return code is used with MC_ALLOCATE, it can indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there is no node available that can satisfy the MC_ALLOCATE request.
When MC_ALLOCATE produces this return code for a Microsoft® SNA Server system configured with multiple nodes, there are two secondary return codes as follows:
-
0xF0000001
-
Secondary return code; no nodes have been started.
-
0xf0000002
-
Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:
· The node with the local LU is not started. |
· The local LU is not configured. |
-
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_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:
-
The partner TP issued MC_DEALLOCATE with dealloc_type set to AP_ABEND.
-
The partner TP encountered an ABEND, causing the partner LU to send an MC_DEALLOCATE request.
Remarks
In response to MC_CONFIRM, the partner TP normally issues MC_CONFIRMED to confirm that it has received the data without error. (If the partner TP encounters an error, it issues MC_SEND_ERROR or abnormally deallocates the conversation.)
The TP can issue MC_CONFIRM only if the conversation's synchronization level, established by MC_ALLOCATE, is AP_CONFIRM_SYNC_LEVEL.
The conversation must be in SEND state when the TP issues this verb. State changes, summarized in the following table, are based on the value of the primary_rc.
primary_rc |
New state |
ap_ok |
No change |
ap_allocation_error |
RESET |
ap_comm_subsystem_abended
ap_comm_subsystem_not_loaded |
RESET
RESET |
ap_conv_failure_retry
ap_conv_failure_no_retry |
RESET
RESET |
ap_dealloc_abend
ap_dealloc_abend_prog
ap_dealloc_abend_svc
ap_dealloc_abend_timer |
RESET
RESET
RESET
RESET |
ap_prog_error_purging
ap_svc_error_purging |
RECEIVE
RECEIVE |
MC_CONFIRM waits for a response from the partner TP. A response is generated by one of the following verbs in the partner TP:
By issuing MC_CONFIRM after MC_ALLOCATE, the invoking TP can immediately determine whether the allocation was successful (if synclevel is set to AP_CONFIRM_SYNC_LEVEL).
Normally, the value of the MC_ALLOCATE verb's mode_name parameter must match the name of a mode configured for the invoked TP's node and associated during configuration with the partner LU.
If one of the modes associated with the partner LU on the invoked TP's node is an implicit mode, the session established between the two LUs will be of the implicit mode when no mode name associated with the partner LU matches the value of mode_name. For more information, see the Microsoft SNA Server Administration Guide.
Several parameters of MC_ALLOCATE are EBCDIC or ASCII strings. A TP can use the CSV CONVERT to translate a string from one character set to the other.
To send the MC_ALLOCATE request immediately, the invoking TP can issue MC_FLUSH or MC_CONFIRM immediately after MC_ALLOCATE. Otherwise, the MC_ALLOCATE request accumulates with other data in the local LU's send buffer until the buffer is full.