APING

APING is the APPN version of the “ping” utility; it allows a management application to check the communications path from a local LU to a remote LU in the network.

SNAplus2 APING is implemented using an internally-defined APPC TP. This TP sends data to the partner LU, and optionally receives data from the partner LU. If the TP completes successfully, the APING verb returns information about the time taken to allocate a conversation to the partner LU and to send and receive data.

The application must supply a VCB that is large enough to include a partner TP verification string of the requested size as well as the basic APING VCB structure; the returned data includes this string appended to the end of the basic structure.

This verb is intended for checking the path to an LU on a remote node. Using APING to check communications with a partner LU on the local node will impact the performance of other programs on the local computer, and is not recommended.

This verb must be issued to a running node.

VCB Structure

typedef struct aping
{
     AP_UINT16         opcode;            /* verb operation code             */
     unsigned char     reserv2;           /* reserved                        */
     unsigned char     format;            /* reserved                        */
     AP_UINT16         primary_rc;        /* primary return code             */
     AP_UINT32         secondary_rc;      /* secondary return code           */
     unsigned char     lu_name[8];        /* local LU name                   */
     unsigned char     lu_alias[8];       /* local LU alias                  */
     AP_UINT32         sense_data;        /* sense data                      */
     unsigned char     plu_alias[8];      /* partner LU alias                */
     unsigned char     mode_name[8];      /* mode name                       */
     unsigned char     tp_name[64];       /* destination TP name             */
     unsigned char     security;          /* security level                  */
     unsigned char     reserv3a[3];       /* reserved                        */
     unsigned char     pwd[10];           /* password                        */
     unsigned char     user_id[10];       /* user ID                         */
     AP_UINT16         dlen;              /* length of data to send          */
     AP_UINT16         consec;            /* number of consecutive sends     */
     unsigned char     fqplu_name[17];    /* fully qualified partner LU name */
     unsigned char     echo;              /* data echo flag                  */
     AP_UINT16         iterations         /* number of iterations            */
     AP_UINT32         alloc_time;        /* time taken for ALLOCATE         */
     AP_UINT32         min_time;          /* minimum send/receive time       */
     AP_UINT32         avg_time;          /* average send/receive time       */
     AP_UINT32         max_time;          /* maximum send/receive time       */
     AP_UINT16         partner_ver_len;   /* size of string to receive       */
     PARTNER_VER_DATA  partner_ver_data;
} APING;
 
typedef struct partner_ver_data
{
     AP_UINT16         partner_ver_len;   /* size of string to receive      */
}
PARTNER_VER_DATA;

Supplied Parameters

The application supplies the following parameters:

opcode

AP_APING

lu_name

LU name of the local LU. This is an 8-byte type-A EBCDIC string, padded on the right with spaces if the name is shorter than 8 characters. To indicate that the LU is identified by its LU alias instead of its LU name, set this parameter to 8 binary zeros and specify the LU alias in the following parameter.

lu_alias

LU alias of the local LU. This parameter is used only if the lu_name field is set to 8 binary zeros, and is ignored otherwise. The alias is an 8-byte ASCII string, padded on the right with spaces if the name is shorter than 8 bytes. To use the default LU (the LU associated with the CP), set both the lu_name and lu_alias parameters to 8 binary zeros.

plu_alias

Partner LU alias. This should be the alias of an LU on a remote node; you are not recommended to use APING with a partner LU on the local node.

The alias is an 8-byte ASCII string, padded on the right with spaces if the name is shorter than 8 bytes. To indicate that the LU is identified by its fully qualified name instead of its alias, set this parameter to 8 binary zeros and specify the LU name in the fqplu_name parameter.

mode_name

Name of the mode used by the LU pair. This is an 8-byte type-A EBCDIC string (starting with a letter), padded on the right with spaces if the name is shorter than 8 characters.

tp_name

Name of the invoked TP (generally set to APINGD). This is a 64-byte string, padded on the right with spaces.

security

Specifies whether conversation security information is required to start the TP. Possible values are:

AP_NONE: No security information is required.
AP_SAME: Security information may be verified by the TP that invoked this TP on behalf of a third TP.
AP_PGM: A user ID and password are required to start the TP.
AP_PGM_STRONG: A password and user ID are required to start the TP. If password substitution is not supported on the session, the aping fails. Otherwise, the password is sent encrypted.

pwd

Password required to access the partner TP; this parameter is required only if the security parameter is set to AP_PGM. This is a 10-byte type-AE EBCDIC character string, padded on the right with EBCDIC spaces if the password is shorter than 10 bytes.

user_id

User ID required to access the partner TP; this parameter is required only if the security parameter is set to AP_SAME or AP_PGM. This is a 10-byte type-AE EBCDIC character string, padded on the right with EBCDIC spaces if the user ID is shorter than 10 bytes.

dlen

Length of the data string to be sent to the partner LU. (The NOF API application does not need to provide a data string; the APING TP simply sends a string of zeros of the specified length.)

consec

Number of consecutive data strings sent to the partner LU during each iteration. The APING TP sends this number of data strings, each containing the number of bytes specified by the dlen parameter. It then requests either data or a confirmation message from the partner TP, depending on the setting of the echo parameter.

fqplu_name

Fully qualified network name for the partner LU. This parameter is used only if the plu_alias field is set to 8 binary zeros, and is ignored otherwise. This should be the name of an LU on a remote node; you are not recommended to use APING with a partner LU on the local node.

The name is a 17-byte EBCDIC string, right-padded with EBCDIC spaces. It consists of a network ID of up to 8 A-string characters, an EBCDIC dot (period) character, and a network name of up to 8 A-string characters.

echo

Specifies whether the APING TP requests data from the partner LU after sending data to it. Possible values are:

AP_YES: After sending the specified number of data strings, APING waits to receive data from the partner LU.
AP_NO: After sending the specified number of data strings, APING requests confirmation from the partner LU, but does not receive data.

iterations

Number of times that the APING TP should perform the sequence of sending data to the partner LU and requesting either data or confirmation.

partner_ver_len

Maximum length of the partner TP verification data string which can be received by the NOF API application. The application must supply a VCB large enough to include this string as well as the basic APING VCB structure, because the string will be appended to the returned VCB.

partner_ver_data

When the verb is returned, data up to the length defined by the partner_ver_len parameter is appended to the verb.

Returned Parameters: Successful Execution

If the verb executes successfully, APING returns the following parameters:

primary_rc: AP_OK
alloc_time: The time in milliseconds to allocate a conversation to the partner (the time taken for the MC_ALLOCATE verb issued by the APING TP to complete).
min_time: The minimum time in milliseconds required for a data-sending iteration (the shortest measured time for a single iteration of sending data and receiving either data or confirmation). If iterations was set to zero, this parameter is not used.
avg_time: The average time in milliseconds required for a data-sending iteration (the average time for a single iteration of sending data and receiving either data or confirmation). If iterations was set to zero, this parameter is not used.
max_time: The maximum time in milliseconds required for a data-sending iteration (the longest measured time for a single iteration of sending data and receiving either data or confirmation). If iterations was set to zero, this parameter is not used.
partner_ver_len: Length of verification string returned by the partner TP. The string itself is appended to the end of the VCB.
partner_ver_data: Verification string returned by the partner TP. If partner_ver_len is zero, then this string is not returned.

Returned Parameters: Parameter Check

If the verb does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

AP_PARAMETER_CHECK

secondary_rc

Possible values are:

AP_INVALID_LU_ALIAS: The lu_alias parameter did not match any defined LU alias.
AP_INVALID_LU_NAME: The lu_name parameter did not match any defined LU name.
AP_BAD_SECURITY: The security parameter was not set to a valid value.
AP_UNKNOWN_PARTNER_MODE: The value specified for plu_alias, fqplu_name, or mode_name did not match any defined partner LU or mode.
AP_BAD_PARTNER_LU_ALIAS: The value specified for plu_alias did not match any defined partner LU.

Appendix A “Common Return Codes” lists further secondary return codes associated with AP_PARAMETER_CHECK, which are common to all NOF verbs.

Returned Parameters: Allocation Failure

If the verb does not execute because SNAplus2 cannot allocate the APPC conversation, SNAplus2 returns the following parameters:

primary_rc

AP_ALLOCATION_ERROR

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. Check the sense_data parameter and the error log file for more information. Do not attempt to retry the APING verb 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. Check the error log file for more information. Retry the APING verb, preferably after a timeout to allow the condition to clear.
AP_SECURITY_NOT_VALID: The user ID or password specified was not accepted by the partner LU.
AP_TP_NAME_NOT_RECOGNIZED: The partner LU does not recognize the specified TP name.
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 APING verb 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 APING verb, preferably after a timeout to allow the condition to clear.

sense_data

If the secondary_rc parameter is AP_ALLOCATION_FAILURE_NO_RETRY, this parameter contains the SNA sense data associated with the error. For all other secondary_rc values, this parameter is reserved.

Returned Parameters: Conversation Failure

If the verb does not execute because the APPC conversation with the partner TP failed, SNAplus2 returns the following parameters:

primary_rc

AP_CONV_FAILURE_NO_RETRY: The conversation was terminated because of a permanent condition, such as a session protocol error. Check the error log file to determine the cause of the error. Do not retry the APING verb until the error has been corrected.

primary_rc

AP_CONV_FAILURE_RETRY: The conversation was terminated because of a temporary error. Retry the APING verb. If the problem occurs again, check the error log file to determine the cause of the error.

primary_rc

AP_DEALLOC_ABEND: The partner TP deallocated the conversation because of an error condition. The reason for the error may be logged on the remote node.

Returned Parameters: Other Conditions

Appendix A “Common Return Codes” lists further combinations of primary and secondary return codes that are common to all NOF verbs.

APING

Technical documentation

» Table of Contents

» Index

VCB Structure

Supplied Parameters

Returned Parameters: Successful Execution

Returned Parameters: Parameter Check

Returned Parameters: Allocation Failure

Returned Parameters: Conversation Failure

Returned Parameters: Other Conditions