%SS_GETHOSTBYNAME

Get the IPv4 address corresponding to a host name

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
status = %SS_GETHOSTBYNAME(h_name, in_addr[, pos])

Return value

status

If successful, returns SS_SUCCESS (0). If unsuccessful, returns SS_ENULL (2). See the Socket Errors table for additional information about this error.  (n)

Arguments

h_name

Specifies the host name. (a)

in_addr

Returned with the IPv4 address(es). ([*]i4)

pos

(optional) The position of a specific host address to be returned. Default is 1 (the primary address). (n)

Discussion

Note

We recommend using %SS_GETADDRINFO rather than %SS_GETHOSTBYNAME, because the latter is based on a deprecated Winsock function.

%SS_GETHOSTBYNAME retrieves an IPv4 address using the host name in h_name as a search parameter. When in_addr is an array, the array is filled with all of the IP addresses associated with the host name up to the number of elements in the array. Any array element beyond the number needed for the available IP addresses is filled with a zero value.

A position, pos, can be specified to retrieve an address other than the primary address. If pos is specified and in_addr is an array, only the address specified by pos is returned. If pos is greater than the number of addresses present, SS_ENULL is returned. Using pos, you can call %SS_GETHOSTBYNAME in a loop, incrementing pos until it returns SS_ENULL. However, since many hosts use round‑robin rotation for Internet addresses, calling this function in a loop often returns inconsistent results.

If SS_ENULL is returned, the system error code can be returned by immediately calling %SYSERR.

Note

Do not use %SS_GETHOSTBYNAME to resolve dotted IP address strings—it should be used only when the known value is the host name. To resolve an IP address string, use %SS_INET_ADDR to convert the string to a numeric IP address. If you want to get the host name, you can then use %SS_GETHOSTBYADDR.

Examples

status = %ss_gethostbyname("www.google.com", in_addr)
status = %ss_gethostbyname("www.google.com", in_addr_array)
status = %ss_gethostbyname("www.google.com", in_addr, 2)