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 list of return code values, see Return codes (errnos) in 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 that are less than decimal 4096 are z/OS UNIX System Services return codes. See Reason codes in z/OS UNIX System Services Messages and Codes. Reason codes that are greater than decimal 4096 are returned by the resolver, and are described in Resolver reason codes in z/OS 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
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.