GETADDRINFO

The GETADDRINFO call returns the 32-bit internet address for the current host from the GETADDRINFO command that is issued by z/OS Communications Server to resolve host or service name information. This command translates the name of a service location (host name) or a service name.

Example of GETADDRINFO call

SOC_FUNCTION DC   CL16'GETADDRINFO'
NAME         DS   CL255
NAMELEN      DS   F
SERVICE      DS   CL32
SERVICELEN   DS   F

HINTS        DS   A
RESULTS      DS   A
CANONICALLEN DS   F
ERRNO        DS   F
RETCODE      DS   F
 
             CALL DFHSOKET,(SOC_FUNCTION,NAME,NAMELEN,SERVICE,SERVICELEN,HINTS,
RESULTS,CANONICALLEN,ERRNO,RETCODE)

Input parameters

SOC_FUNCTION
A 16-byte character field containing GETADDRINFO. The field is left-justified and padded on the right with blanks.
NAME
NAME is returned as one of the following strings:
  • An EBCDIC character string, up to 255 characters long, set to the node name (host name) that is being queried.
  • An EBCDIC character string set to the IP address of the node (host) where the service resides.
NAMELEN
The name of a fullword that contains the length of the NAME parameter.
SERVICE
SERVICE is returned as one of the following strings:
  • An EBCDIC character string, up to 32 characters long, set to the service name that is being queried.
  • An EBCDIC character string set to the port number of the required service.
SERVICELEN
The name of a fullword that contains the length of the SERVICE parameter.
HINTS
The name of a field that contains a pointer to a z/OS Communications Server input Addr_Info structure. The following fields can be specified in the Addr_Info structure:
  • A set of flags (ai_flags) for interpreting the request. Here are the flags:
    • AI_PASSIVE
    • AI_CANONNAMEOK
    • AI_NUMERICHOST
    • AI_NUMERICSERV
    • AI_V4MAPPED
    • AI_ALL
    • AI_ADDRCONFIG
    For more information about ai_flags, see the Parameters topic in the z/OS Communications Server IP CICS Sockets Guide.
  • The address family (ai_family) that the caller expects to be returned by the resolver. Here are the address families:
    • AF_UNSPEC
    • AF_INET
    • AF_INET6
  • The socket type (ai_socktype) that the caller can accept as a response.
  • The protocol (ai_protocol) that the caller can accept as a response.

All other fields in the Addr_Info structure must be set to zero.

If the HINTS parameter is not specified; that is, HINT is set to zero, the following settings are used:
  • All flags are set to off.
  • Address family is set to AF_UNSPEC.
  • Socket type is set to 0.
  • Protocol is set to 0.

Output parameters

RESULTS
The name of a field that contains a pointer to an output Addr_Info structure. If more than one address is returned, this field contains a linked list of output Addr_Info structures. Each output Addr_Info structure contains the following information about the information returned in the Addr_Info structure:
  • A set of flags (ai_flags) for interpreting the address.
  • The address family (ai_family) for the address.
  • The socket type (ai_socktype) for the address.
  • The protocol (ai_protocol) for the address.
  • The length (ai_addrlen) of the sock_inet_sockaddr or sock_inet6_sockaddr structure returned in the ai_addr field.
  • The canonical name (ai_canonname) associated with the NAME input parameter, if NAME was requested using the input AI_CANONNAMEOK flag. If more than one Addr_Info structure is returned, the canonical name is supplied in the first Addr_Info structure only.
CANONICALLEN
The name of a fullword binary field that contains the length of the canonical name that was returned in the first Addr_Info structure pointed to by the RESULTS parameter.
ERRNO
A fullword binary field. If RETCODE is negative, ERRNO contains an error number. For a list of return code values for GETADDRINFO, see z/OS Communications Server: IP and SNA Codes.
RETCODE
A fullword binary field that returns one of the following values:
Value
Description
0
Successful call
-1
An error occurred.


dfhtn0_getaddr.html | Timestamp icon Last updated: Monday, 5 June 2017