Previous Topic: &SOCKET OPEN

Next Topic: &SOCKET RECEIVE

Verbs and Built-in Functions › &SOCKET PING

&SOCKET PING

Tests connectivity with a specified host.

&SOCKET PING
      { ADDRESS=ip_address | HOSTNAME=host_name }
      [ PACKETSIZE=nn ]
      [ COUNT=nn ]
      [ MDO=mdo_name ]
      [ GETNAME={ YES | NO } ]
      [ WAIT=time ]
      [ TYPE={ SYNC | ASYNC }]

PING is used to send an echo request to a host specified either by the ADDRESS or HOSTNAME parameter, and waits a specified period of time for a response from the host.

Operands:

ADDRESS=ip_address

Specifies the IP address of the host.

HOSTNAME=host_name

Specifies the name of the host.

PACKETSIZE=nn

Specifies the length of the packets to send to the host. This value must be in the range of 16 to 2048 bytes. The default value is 64.

COUNT=nn

Specifies the number of times to execute the ping. This value must be in the range of 1 to 999. The default value is 1.

MDO=mdo_name

Specifies the name of the Mapped Data Object (MDO) to receive the statistical information collected by this verb. The MDO is mapped by the $NMTCPPG map.

GETNAME={ YES | NO }

If the default value YES is used the name of the destination host is resolved.

WAIT=time

Specifies the time (in seconds) to wait for the host to respond. The default value is 30 seconds.

TYPE={SYNC | ASYNC}

Indicates whether this is a synchronous (SYNC) or asynchronous (ASYNC) socket request.

If TYPE=ASYNC is specified, WAIT cannot be specified.

If TYPE=ASYNC is specified, the verb returns control immediately, and a notification message is queued to the dependent environment when each PING completes:

N00101 NOTIFY: TCP/IP EVENT: PING RESOURCE: RC=rc RSN=rsn ERR=errno VERRIN=vendor_info RESULT=**result_type**  **addr/name**

where:

**result_type** is PARTIAL (intermediate result) or FINAL (final result)

**addr/name** is set to the destination specified on the PING request (that is, either ADDRESS=ip_address or HOSTNAME=host_name)

The return MDO is available in $INT.USERMDO after &INTREAD receives the message.

Examples: &SOCKET PING

&SOCKET PING HOSTNAME=TESTMVS1 MDO=MDO1 COUNT=&COUNT WAIT=30

Return Codes:

0

Ping successful

4

Ping timed out

8

Ping failed; see &ZFDBK for reason code, &ZSOCERRN and &ZSOCVERR for further error information.

Notes:

The information returned is set into the following NCL variables:

Some interfaces may not support &SOCKET PING. In this case, &ZFDBK is set to 36 and &ZSOCERRN to 7 (EUNSUPP). The &ZTCPSUPP function is used to test if &SOCKET PING is supported.