gethostbyname (BPX1GHN, BPX4GHN) Get IP information for specified host domain names

Function

The gethostbyname callable service returns the alias names and the internet addresses of a host whose domain name is specified as input. The TCP/IP Services resolver tries to resolve the name through a name server, if one is present. If a name server is not present, the resolver searches for the HOSTS.SITEINFO data set (or /etc hosts data set) until a matching host name is found, or until an EOF marker is reached.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1GHN):	31-bit
AMODE (BPX4GHN):	64-bit
ASC mode:	Primary mode
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1GHN,(Name,
              Name_length,
              Hostent_ptr,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4GHN with the same parameters. Hostent_ptr is a doubleword pointer field.

Parameters

Name

Supplied parameter

Type:: Character
Length:: Length specified by Name_length

A string, up to 255 characters long, set to the host name that is being queried.

Name_length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length of the Name parameter.

Hostent_ptr

Returned parameter

Type:: Pointer
Length:: Fullword (doubleword)

The name of a field that contains a pointer to the Hostent structure. The Hostent structure contains the following fields:

h_name: The address of the host name returned by the service. The host name is a variable-length field that is ended by X'00'.
h_aliases: The address of a list of addresses that point to the alias names returned by the service. The list is ended by the pointer X'00000000'. Each alias name is a variable-length field that is ended by X'00'.
h_addrtype: The value 2, which signifies AF_INET.
h_length: The length of the host internet addresses pointed to by h_addr_list.
h_addr_list: The address of a list of addresses that point to the host internet addresses returned by this service. This list is ended by the pointer X'00000000'.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the gethostbyname service returns one of the following:

0, if the request is successful.
-1, if the request is not successful.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the gethostbyname service stores the return code. The gethostbyname service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The gethostbyname service can return one of the following values in the Return_code parameter:

Return_code	Explanation
HOST_NOT_FOUND	The host name specified by the Name parameter was not found.
TRY_AGAIN	The host name specified by the Name parameter could not be resolved within the configured time interval. The request can be retried later.
NO_RECOVERY	An unrecoverable error occurred.
NO_DATA	The requested Name parameter is valid, but it does not have a record at the name server.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the gethostbyname service stores the reason code. The gethostbyname service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value.

Reason codes lower than decimal 4096 are z/OS UNIX System Services return codes, and are documented in z/OS UNIX System Services Messages and Codes. Reason codes greater than decimal 4096 are returned by the resolver, and are described in z/OS V2R1.0 Communications Server: IP and SNA Codes.

An assembler macro (EZBREHST) that contains the hostent structure, gethostbyxxxx return codes, and reason codes is shipped in the installation's MACLIB SMP/E DDEF location.

Related services

gethostbyaddr (BPX1GHA, BPX4GHA) Get the IP address and alias of a host name for the specified IP address

Characteristics and restrictions

The gethostbyname service does not support a fully reentrant environment. The Hostent structure that is returned is allocated at a task level, and is reused on subsequent gethostbyname calls. Therefore, at any time only one call can be occurring within a task. For example, if the mainline task has issued a gethostbyname call that has not completed, a signal handler that interrupts that thread's processing should not invoke the gethostbyname service.

The Hostent structure is freed when the task is terminated.

Examples

For an example using this callable service, see BPX1GHN (gethostbyname) example.