 |
» |
|
|
|
The aping command is the APPN version of the “ping” utility
and 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, aping returns information about the time taken to allocate
a conversation to the partner LU and to send and receive data. This command 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 command must be issued to a running node. Supplied Parameters | |
Parameter name Type Length Default
[aping]
lu_name character 8 (null string)
lu_alias character 8 (null string)
plu_alias character 8 (null string)
mode_name character 8
tp_name character 64 APINGD
security constant NONE
pwd character 10 (null string)
user_id character 10 (null string)
dlen decimal 0
consec decimal 1
fqplu_name character 17 (null string)
echo constant NO
iterations decimal 0
partner_ver_le decimal 0
|
Supplied parameters are: - lu_name
LU name of the local LU. This name is a type-A character
string. To indicate that the LU is identified by its LU alias instead
of its LU name, do not specify this parameter. - lu_alias
LU alias of the local LU. This parameter is used
only if lu_name is not specified. If lu_name and lu_alias are not specified, the command is forwarded to the
LU associated with the CP (the default LU). - plu_alias
Partner LU alias. This parameter should be the alias
of an LU on a remote node; using aping with a partner LU on the local node is not recommended. To indicate that the LU is identified by its fully qualified
name instead of its alias, do not specify this parameter, but specify
the LU name in the fqplu_name parameter. - mode_name
Name of the mode used by the LU pair. This name
is a type-A character string starting with a letter. - tp_name
Name of the invoked TP. This parameter is generally set
to “APINGD.” - security
Specifies whether conversation security information
is required to start the TP. Possible values are: - NONE
No security information is required. - SAME
Security information can be verified by the TP that invoked
this TP on behalf of a third TP. - PGM
A password and user ID are required to start the
TP. The password is sent unencrypted if password substitution is
not supported on the session. If password substitution is supported
on the session, the password is sent encrypted. - 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 PGM or PGM_STRONG.
This password is a type-AE character string. - user_id
User ID required to access the partner TP. This parameter
is required only if the security parameter is set to SAME, PGM or PGM_STRONG.
This ID is a type-AE character string. - 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.)
Specify a value in the range 0-65,535. - consec
Number of consecutive data strings sent to the partner LU
before a response is required. The APING TP sends this number of
data strings, with each string containing the number of bytes specified
by the dlen parameter. The APING TP then requests either data or a
confirmation message from the partner TP, depending on the setting
of the echo parameter. Specify a value in the range 1-65,535. - fqplu_name
Fully qualified name of the partner LU. Specify
3-17 type-A characters that consist of a 1-8 character network
name, followed by a period, followed by a 1-8 character
partner LU name. This name should be the name of an LU on a remote node; using aping with a partner LU on the local node is not recommended. This parameter is used only if the plu_alias parameter is not specified; it is ignored if plu_alias is specified. - echo
Specifies whether the APING TP receives data or requests
confirmation from the partner LU after sending data to it. Possible
values are: - YES
After sending the specified number of data strings,
the APING TP receives data from the partner LU. - NO
After sending the specified number of data strings,
the APING TP requests confirmation from the partner LU, but does
not receive data.
- iterations
Number of times that the APING TP performs the sequence
of sending data to the partner LU and requesting either data or
confirmation. Specify a value in the range 0-65,535. - partner_ver_len
Maximum length of the partner TP verification data string
to return. Specify a value in the range 0-3000.
Returned Parameters | |
Parameter name Type Length
alloc_time decimal
min_time decimal
avg_time decimal
max_time decimal
partner_ver_len decimal
partner_ver_data hex array (max_length as
specified on
command)
|
If the command executes successfully, SNAplus2 returns the
following parameters: - 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 0 (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 0 (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 0 (zero), this
parameter is not used. - partner_ver_len
Actual length of the verification string returned
by the partner TP. - partner_ver_data
Verification string returned by the partner TP.
If partner_ver_len is 0 (zero), then this string is
not returned.
Error Return Codes | |
If the command cannot be executed, SNAplus2 returns a primary
return code to indicate the type of error and a secondary return
code to provide specific details about the reason for unsuccessful
execution. If the command does not execute because of a parameter error,
SNAplus2 returns the following parameters: - primary_rc
PARAMETER_CHECK - secondary_rc
Possible values are: - INVALID_LU_ALIAS
The lu_alias parameter value did not match any defined LU alias. - INVALID_LU_NAME
The lu_name parameter value did not match any defined LU name. - BAD_PARTNER_LU_ALIAS
The value specified for plu_alias did not match any defined partner LU.
If the command does not execute because other conditions exist, SNAplus2
returns the following parameters: - primary_rc
- ALLOCATION_ERROR
SNAplus2 could not allocate the APPC conversation with
the remote TP.
- secondary_rc
Possible values are: - ALLOCATION_FAILURE_NO_RETRY
The conversation could not 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 command until the error has been corrected. - 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 command, preferably after a timeout to allow the condition
to clear. - SECURITY_NOT_VALID
The user ID or password specified was not accepted
by the partner LU. - TP_NAME_NOT_RECOGNIZED
The partner LU does not recognize the specified
TP name. - 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 command until the cause of the error has been corrected. - 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 command, preferably after a timeout to allow the condition
to clear.
- sense_data
If the secondary_rc parameter is ALLOCATION_FAILURE_NO_RETRY,
this parameter contains the SNA sense data associated with the error. For
all other secondary_rc values, this parameter is not returned. - primary_rc
- CONV_FAILURE_NO_RETRY
The APPC conversation with the partner TP 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 command until the error has been corrected.
- primary_rc
- CONV_FAILURE_RETRY
The APPC conversation with the partner TP was terminated
because of a temporary error. Retry the aping command. If the problem occurs again, check the error
log file to determine the cause of the error.
- primary_rc
- DEALLOC_ABEND
The partner TP deallocated the APPC conversation because
of an error condition. The reason for the error may be logged on
the remote node.
Appendix A “Common Return Codes from snapadmin Commands” lists combinations
of primary and secondary return codes that are common to all commands. |
Printable version
