PING table function

Edit online

The PING table function tests connectivity to a remote system.

This function is similar to the PING or Verify TCP/IP Connection (VFYTCPCNN) CL command.

Authorization: See Note below.

The schema is SYSTOOLS.

remote-system

A character string containing the name of the remote system with which the ping operation takes place. Can contain the following special value:

*INTNETADR: The remote-ip-address parameter identifies the remote system.

If this parameter is omitted, the default value is *INTNETADR and a value for remote-ip-address must be specified.

remote-ip-address

A character string that specifies the remote internet address. Either a valid IP Version 4 or IP Version 6 address is accepted.

If remote-system contains a value other than *INTNETADR, this parameter is ignored.

address-version-format

A character string that specifies how the host name specified for remote-system is to be resolved. It is also the address format to be used if remote-ip-address is specified.

*CALC: The host name resolution method will be determined based on the host name entered for remote-system. This is the default.
*IP4: Use the IP Version 4 host name resolution method.
*IP6: Use the IP Version 6 host name resolution method.

number-packets-to-send

An integer value that specifies the number of packets that are sent to the remote system. Valid values are 1 to 999. The default is 5.

packet-length-to-send

An integer value that specifies the packet length (in bytes) to be sent to the remote system. Valid values are 8 to 65500. The default is 256.

wait-time

An integer value that specifies the number of seconds to wait for the return (echo) packet before declaring a packet transfer a failure. Valid values are 1 to 120. The default is 1.

local-ip-address

A character string that specifies the local internet address of the interface that the outbound packets are to use. Either a valid IP Version 4 or IP Version 6 address is accepted. *ANY indicates that any interface's local internet address can be used. The default is *ANY.

The result of the function is a table containing one row with the format shown in the following table. All the columns are null capable.

Table 1. PING table function
Column Name	Data Type	Description
RESULT	VARCHAR(7)	The result of the ping request. FAILURE At least one packet did not respond or an error occurred with the command. SUCCESS All packets responded.
PERCENT_SUCCESSFUL	INTEGER	The percent of successful packet responses.
PACKETS_SENT	INTEGER	The total number of packets that were sent.
RESPONSES_RETURNED	INTEGER	The total number of responses received for the packets that were sent.
ROUND_TRIP_AVG	INTEGER	The average time, in milliseconds, for a response.
ROUND_TRIP_MIN	INTEGER	The shortest time, in milliseconds, for a response.
ROUND_TRIP_MAX	INTEGER	The longest time, in milliseconds, for a response.
REMOTE_HOST_NAME	VARCHAR(255)	The name of the host that was the target of the ping request.
REMOTE_IP_ADDRESS	VARCHAR(45)	The IP address for REMOTE_HOST_NAME.

Note

This function is provided in the SYSTOOLS schema as an example of how messages in a job log can be examined to gather status information. Similar to other Db2® for i provided tools within SYSTOOLS, the SQL source can be extracted and used as a model for building similar helper functions, or to create a customized version within a user-specified schema.

Services provided in SYSTOOLS have authorization requirements that are determined by the interfaces used to implement the service. To understand the authority requirements, extract the SQL for the service and examine the implementation.

Example

Verify connectivity to a remote system by name.

SELECT * FROM TABLE(SYSTOOLS.PING('REMOTESYS'));

Verify connectivity to a remote system by IP address.

SELECT * FROM TABLE(SYSTOOLS.PING(REMOTE_IP_ADDRESS => '9.1.2.3'));