CheckHost Method (RUNTIME)

10.1A

The CheckHost method checks to see if a specific internet host address exists. The method uses the following format:

Where:

label

Optional. A Program Execution Label.

object

Required. A RUNTIME object.

return

Optional. A Numeric Variable that returns the pass\failure values for the execution of the method.

hostname

Required. A previously defined Character String Variable or literal that contains the host name or IP address that is being checked.

port

Optional. A Numeric Variable or decimal number that identifies the port to be tested.

timeout

Optional. A Numeric Variable or decimal number that identifies the number of seconds to wait.

options

Required. A Numeric Variable or decimal number that specifies a bit mask value that controls the behaviors of this method.

Flags Affected: OVER, ZERO

Note the following:

1. The ZERO flag is always set when the {return} value is zero which indicates that the method execution was successful. The ZERO flag is cleared if the {return} value is not zero which indicates that the method execution failed.

2. The OVER flag is set if the hostname was not found and FALSE if the hostname was found.

3. If the optional port parameter is given, the CheckHost method attempts to connect to the host using that port number.

 

Warning: When using the {port} number of '80' to make a connection, the 'CheckHost' method performs a special 'ping' test to verify that the 'URL' is valid before doing the connection check. If this special 'ping' check fails, the {result} is returned with a value of '100 + N' where the 'N' value is the 'ping' error value. This special 'ping' check is required to insure expected pass/fail results.

4. If the optional port parameter is not given, the CheckHost method uses the Internet Control Message Protocol (ICMP) to 'ping' the host name. This is be tried four (4) times before an error is given.

5. The timeout parameter specifies the number of seconds to wait checking. If no value is given or the value iszero, one hundred (100) milliseconds is used.

6. If the {return} value is non-zero indicating a failure the following failure results can be expected:

 

Failure Value	Description (Using PING mode without {port})
1	Unable to create/setup socket.
2	Unable to resolve {hostname} ip.
3	Send error.
4	Select error.
5	Timeout occurred.
6	Receive error.
7	Unable to set file descriptor (Linux Only).

 

Failure Value	Description (Using CONNECT mode with {port})
1	Unable to make socket connection.
3	Unable to resolve {hostname} ip.
9	Unable to set file descriptor (Linux Only).
10	Unable to create socket.
11	Connect socket error.
12	Select socket error.
13	Select timeout.
14	Select file descriptor error.
100 + N	Special 'port' 80 type errors. The 'N' values in this case are the same as described for the PING mode error values. See the Note (3.) for more details when the {port} value of '80' is being used.

 

7. The options parameter is reserved for future use.

8. When executing the 'CheckHost' method on a Linux\Linux system, the end-user must insure that the 'PL/B' runtime has sufficient privileges to execute using the 'Ping' mode. Otherwise, the 'CheckHost' method 'Ping' mode will always fail.

See Also: RUNTIME, RUNTIME Methods, Method Syntax