Appendix A: Common Return Codes

This appendix describes the primary return codes (and, if applicable, secondary return codes) that are common to several APPC verbs.

Verb-specific return codes are described in the documentation for the individual verbs.

Common return codes are described in the following sections.

A.1 AP_ALLOCATION_ERROR

The primary and secondary return codes are:

primary_rc

AP_ALLOCATION_ERROR: 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.

secondary_rc

Possible values are:

AP_ALLOCATION_FAILURE_NO_RETRY: 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 attempt to retry the allocation until the error has been corrected.
AP_ALLOCATION_FAILURE_RETRY: 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, preferably after a timeout to allow the condition to clear.
AP_CONVERSATION_TYPE_MISMATCH: The partner LU or TP does not support the conversation type (basic or mapped) specified in the allocation request.
AP_PIP_NOT_ALLOWED: The allocation request specified PIP data, but the partner TP did not accept it. This may be because the partner TP does not require this data, because it is using an APPC implementation which does not support receiving PIP data, or because the partner is a CPI-C application (CPI-C does not support PIP data).
AP_PIP_NOT_SPECIFIED_CORRECTLY: 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: The user ID or password specified in the allocation request was not accepted by the partner LU.
AP_SYNC_LEVEL_NOT_SUPPORTED: 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: The partner LU does not recognize the TP name specified in the allocation request.
AP_TRANS_PGM_NOT_AVAIL_NO_RETRY: 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 cause of the error has been corrected.
AP_TRANS_PGM_NOT_AVAIL_RETRY: 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 timeout. The reason for the error may be logged on the remote node. Retry the allocation, preferably after a timeout to allow the condition to clear.
AP_SEC_BAD_PROTOCOL_VIOLATION: The remote LU rejected the allocation request due to a protocol violation.
AP_SEC_BAD_PASSWORD_EXPIRED: The remote LU rejected the allocation request because the password provided is no longer valid.
AP_SEC_BAD_PASSWORD_INVALID: The remote LU rejected the allocation request because the password is not valid.
AP_SEC_BAD_USERID_REVOKED: The remote LU rejected the allocation request because the user ID is no longer valid.
AP_SEC_BAD_USERID_INVALID: The remote LU rejected the allocation request because the user ID is not valid.
AP_SEC_BAD_USERID_MISSING: The remote LU rejected the allocation request because a user ID was not specified but is required.
AP_SEC_BAD_PASSWORD_MISSING: The remote LU rejected the allocation request because a password was not specified but is required.
AP_SEC_BAD_GROUP_INVALID: The remote LU rejected the allocation request because the group is not valid.
AP_SEC_BAD_UID_REVOKED_IN_GRP: The remote LU rejected the allocation request because the user ID is no longer in the group.
AP_SEC_BAD_UID_NOT_DEFD_TO_GRP: The remote LU rejected the allocation request because the user ID is not in the group.
AP_SEC_BAD_UNAUTHRZD_AT_RLU: The remote LU rejected the allocation request because the user ID is not authorized to start this TP at the remote LU.
AP_SEC_BAD_UNAUTHRZD_FROM_LLU: The remote LU rejected the allocation request because the user ID is not authorized to start this TP from the local LU.
AP_SEC_BAD_UNAUTHRZD_TO_TP: The remote LU rejected the allocation request because the user ID is not authorized to start this TP.
AP_SEC_BAD_INSTALL_EXIT_FAILED: The remote LU rejected the allocation request because it failed to install a required exit.
AP_SEC_BAD_PROCESSING_FAILURE: The remote LU rejected the allocation request because of a processing failure at the remote LU.

Because providing detailed information about security failures is a potential security flaw, it is possible to turn off support for these AP_SEC_BAD_* return codes. If this is done, all of these errors are reported to the application as AP_SECURITY_NOT_VALID. See the define_defaults command in the SNAP-IX Administration Command Reference and DEFINE_DEFAULTS NOF verb in the SNAP-IX NOF Programmer's Guide for details.