TCPPing

Command group Flag affected Reversible Execute on client Platform(s)
External commands YES NO NO All

Syntax

TCPPing (hostname[,size,timeout]) Returns milliseconds

Description

Note: The flag is set according to whether Omnis was able to make a call to this external command.

This Web command is multi-threaded, allowing another thread to execute in the multi-threaded server while it runs. Note that the same socket cannot safely be used concurrently by more than one thread.

TCPPing sends an ICMP request packet to a specified IP address or named host. It returns the round-trip packet time in milliseconds. If the host is unreachable or not available, the command will return a negative error code.

Hostname is an Omnis Character field containing the IP address or hostname of the host to ping.

Size is an optional parameter. It is an Omnis Long Integer field containing the size, in bytes, of the packet to ping the specified host. Typical values are from 512 to 2,048 bytes. The command makes sure the size is between 1 and 16k bytes, and will force sizes outside this range to the minimum or maximum, appropriately. If omitted, Size defaults to 256.

Timeout is an optional parameter. It is an Omnis Long Integer field containing the number of milliseconds to use as a timeout value for the ping request. If the host is unavailable or does not respond in the specified number of milliseconds, the TCPPing function cancels the ping request and returns -1. If omitted, Timeout defaults to 3000.

Milliseconds is an Omnis Long Integer field. When no error occurs, TCPPing returns the number of milliseconds that it took to receive the ping response from the host. On very fast LANs, it is possible that the ping can complete so quickly that the value may be 0 (zero). A value of -1 (minus one) is returned if the ping times out. All other negative values are error codes.

Example

; Ping iHostName to see if it is available
Calculate iHostName as '0.0.0.0'
TCPPing (iHostName) Returns iMilliseconds
If iMilliseconds<0
  If iMilliseconds=-1
    OK message {Timeout}
  Else
    OK message {Error [iMilliseconds]}
  End If
End If