|
|
|
|
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.
SNAP-IX 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.
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 */
} APING;
The application supplies the following parameters:
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 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.
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.
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.
Name of the invoked TP (generally set to APINGD). This is a 64-byte string, padded on the right with spaces.
Specifies whether conversation security information is required to start the TP. Possible values are:
No security information is required.
Security information may be verified by the TP that invoked this TP on behalf of a third TP.
A user ID and password are required to start the TP.
A password and user ID are required to start the TP, but the password must not be sent in clear text. If password substitution is not supported on the session, the aping fails. Otherwise, the password is sent encrypted.
Password required to access the partner TP; this parameter is required
only if the security parameter is set to
User ID required to access the partner TP; this parameter is required
only if the security parameter is set to
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.)
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.
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.
Specifies whether the APING TP requests data from the partner LU after sending data to it. Possible values are:
After sending the specified number of data strings, APING waits to receive data from the partner LU.
After sending the specified number of data strings, APING requests confirmation from the partner LU, but does not receive data.
Number of times that the APING TP should perform the sequence of sending data to the partner LU and requesting either data or confirmation.
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.
If the verb executes successfully, APING returns the following parameters:
AP_OK
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).
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.
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.
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.
Length of verification string returned by the partner TP.
In addition to these returned parameters, the verification string returned by the partner TP is appended to the end of the APING VCB. The length of this string is given by partner_ver_len. If partner_ver_len is zero, then this string is not returned.
If the verb does not execute because of a parameter error, SNAP-IX returns the following parameters:
AP_PARAMETER_CHECK
Possible values are:
The lu_alias parameter did not match any defined LU alias.
The lu_name parameter did not match any defined LU name.
The security parameter was not set to a valid value.
The value specified for plu_alias, fqplu_name, or mode_name did not match any defined partner LU or mode.
The value specified for plu_alias did not match any defined partner LU.
Common Return Codes lists further secondary return codes associated with AP_PARAMETER_CHECK, which are common to all NOF verbs.
If the verb does not execute because SNAP-IX cannot allocate the APPC conversation, SNAP-IX returns the following parameters:
AP_ALLOCATION_ERROR
Possible values are:
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.
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.
The user ID or password specified was not accepted by the partner LU.
The partner LU does not recognize the specified TP name.
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.
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.
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.
If the verb does not execute because the APPC conversation with the partner TP failed, SNAP-IX returns the following parameters:
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.
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.
The partner TP deallocated the conversation because of an error condition. The reason for the error may be logged on the remote node.
Common Return Codes lists further combinations of primary and secondary return codes that are common to all NOF verbs.
|
|
|
 |
|