%SS2_GETHOSTBYNAME

Get the IP 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 = %SS2_GETHOSTBYNAME(h_name, in_addr6[, 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_addr6

Returned with the IP address(es). ([#][#]byte)

pos

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

Discussion

Note

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

%SS2_GETHOSTBYNAME retrieves an IP address using the host name in h_name as a search parameter. Since the in_addr6 argument is a dynamic array (of a dynamic array of bytes), it will create as many arrays as needed and fill them with all of the IP addresses associated with the host name.

This function supports both IPv4 and IPv6 formatted IP addresses. When retrieving addresses from the byte array, you can tell whether they are IPv4 format or IPv6 format by the length: IPv4 will be i4 and IPv6 will be i16. The %SS2_GETADDRINFO Examples demonstrate how you can retrieve this information.

A position, pos, can be specified to retrieve a specific address other than the primary address. If pos is specified, only the address specified by pos is returned. If pos is greater than the number of addresses present, SS_ENULL is returned. Since many hosts use round‑robin rotation for Internet addresses, calling %SS2_GETHOSTBYNAME multiple times and specifying the same pos may return inconsistent results.

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

Note

Do not use %SS2_GETHOSTBYNAME to resolve IP address strings—it should be used only when the known value is the host name. To resolve an IP address string, use %SS2_INET_NTOP (or %SS_INET_NTOP for IPv4) to convert the string to a numeric IP address. If you want to get the host name, you can then use %SS2_GETHOSTBYADDR (or %SS_GETHOSTBYADDR, though the SS2_ version handles both IPv4 and IPv6) to retrieve that value.