GETHOSTBYADDR

The GETHOSTBYADDR macro returns domain and alias names of the host whose IPv4 Internet address is specified by the macro. A TCP⁄IP host can have multiple alias names and host IPv4 Internet addresses.

The following requirements apply to this call:

Authorization:

Supervisor state or problem state. The PSW key must match the key in which the MVS™ application task was attached.

Dispatchable unit mode:

Task.

Cross memory mode:

PASN = HASN.

Amode:

31-bit or 24-bit.

Note: See "Addressability mode (Amode) considerations" under CALL instruction API environmental restrictions and programming requirements.

ASC mode:

Primary address space control (ASC) mode.

Interrupt status:

Enabled for interrupts.

Locks:

Unlocked.

Control parameters:

All parameters must be addressable by the caller and in the primary address space.


>>-EZASMI--TYPE=GETHOSTBYADDR--,HOSTADR--=--+-number---+-------->
                                            +-address--+   
                                            +-*indaddr-+   
                                            '-(reg)----'   

>--,HOSTENT--=--+-address--+--,RETCODE--=--+-address--+--------->
                +-*indaddr-+               +-*indaddr-+   
                '-(reg)----'               '-(reg)----'   

>--+-------------------------+--+------------------------+-----><
   '-,ERROR--=--+-address--+-'  '-,TASK--=--+-address--+-'   
                +-*indaddr-+                +-*indaddr-+     
                '-(reg)----'                '-(reg)----'

Note: The storage for the HOSTENT structure returned by this call is released during TERMAPI processing; therefore, the application program must not use the HOSTENT storage after the TERMAPI.

Keyword

Description

HOSTADR

Input parameter. A fullword unsigned binary field set to the Internet address of the host whose name you want to find.

HOSTENT

Input parameter. A fullword containing the address of the HOSTENT structure returned by the macro. For information about the HOSTENT structure, see Figure 1.

RETCODE

Output parameter. A fullword binary field that returns one of the following values:

Value: Description
>0: Successful call.
-1: An error occurred.

ERROR

Input parameter. The location in your program to receive control when the application programming interface (API) processing module cannot be loaded.

TASK

Input parameter. The location of the task storage area in your program.

Figure 1. HOSTENT structure returned by the GETHOSTBYADDR macro

Hostent returned by the GETHOSTBYADDR macro consists of the addresses of host name, alias list, family, host address length, and host address list.

GETHOSTBYADDR returns the HOSTENT structure shown in Figure 1. The HOSTENT structure is a tasks's serially reusable storage area. It should not be used or referenced between MVS tasks. The storage is freed when the task terminates. The assembler mapping of the structure is defined in macro EZBREHST, which is installed in the data set specified on your SMP/E DDDEF for MACLIB. This structure contains:

The address of the host name returned by the macro. The name length is variable and is ended by X'00'.
The address of a list of addresses that point to the alias names returned by the GETHOSTBYADDR. This list is ended by the pointer X'00000000'. Each alias name is a variable length field ended by X'00'.
The value returned in the FAMILY field is always 2 to signify AF_INET.
The length of the host Internet address returned in the HOSTADDR_LEN field is always 4 to signify AF_INET.
The address of a list of addresses that point to the host Internet addresses returned by the macro. The list is ended by the pointer X'00000000'.

The HOSTENT structure uses indirect addressing to return a variable number of alias names and Internet addresses.