GETNAMEINFO

Use the GETNAMEINFO command to translate a socket address to a node name and service location.

This command can be used for both IPv4 or IPv6 socket addresses.

Tip: You can use a resolver trace to determine why a resolver command failed. See z/OS Communications Server: IP Diagnosis Guide.

Format

Read syntax diagramSkip visual syntax diagram
>>-SOCKET--(--"GETNAMEINFO"--,--name--+------------------+--)--><
                                      |    .-----------. |      
                                      |    V           | |      
                                      '-,------flags---+-'      

Parameters

name
An IPv4 or IPv6 NAME string. If the NAME string is an IPv4-mapped IPv6 address, then the embedded IPv4 address is extracted; then, the lookup is performed on the IPv4 address. If the NAME string is an IPv6 unspecified address, the lookup is not performed and the 1 EAI_NONAME error code is returned.
The format for the name parameter depends on the socket type:
AF_INET sockets (IPv4)
name = "domain portid ipaddress"
AF_INET6 sockets (IPv6)
name = "domain portid flowinfo ipaddress scopeid"
where
  • The domain value is the decimal number 2 for AF_INET and the decimal number 19 for AF_INET6.
  • The portid value is the port number.
  • The ipaddress value is the IP address of the remote host. It must be an IPv4 address for AF_INET and an IPv6 address for AF_INET6.
  • The flowinfo value must be 0.
  • The scopeid value identifies the interfaces that are applicable for the scope of the address that is specified in the ipaddress field. For a link-local IP address, the scopeid field can specify a link index, which identifies a set of interfaces. For all other scopes, the scopeid field must be set to 0. Setting the scopeid field to 0 indicates that any address type and scope can be specified.
If the scopeid field is specified and the destination is not a link-local address, the resolver ignores the scopeid field.
flags
An optional parameter that specifies the type of information that is returned. Separate multiple flags with spaces. If no flag is issued, the fully qualified host name is returned. The following flags are supported:
NI_NOFQDN
Returns the host name of the fully qualified domain name.
NI_NUMERICHOST
Returns only the numeric form of the host address.
NI_NAMEREQD
Returns an error if the host name cannot be found.
NI_NUMERICSERV
Returns the numeric form of the service.
NI_DGRAM
Indicates that the service query is for a datagram socket. If this flag is not issued, the GETNAMEINFO command assumes that the query is for a stream socket.
NI_NUMERICSCOPE
Returns only the numeric form of the scopeid interface index.

Do not specify both the NI_NUMERICHOST and the NI_NAMEREQD flags; otherwise, you get the EAI_FAIL (3) error. See GETNAMEINFO flags and returned information examples for examples of returned information when various combinations of flags are used.

Returned value

This command returns a string that contains the return code, the host name, and the service. The return code can be 0, a REXX socket API error number, or the REXX TCP/IP error number that is set by the socket command. The return code 0 indicates that the requested socket command was completed successfully.

If a link-local IPv6 address is passed as input and the value of the scopeid parameter is not 0, then scope information is appended to the host name, using the format host name%scope information. For more information about scope information and the GETNAMEINFO command, see z/OS Communications Server: IPv6 Network and Application Design Guide.

The following string is an example of what is returned by the GETNAMEINFO command: 
0 BOB01.THEWORLD.COM%23 echo
In the example, 0 is the return code, BOB01.THEWORLD.COM is the host name, 23 is the scope ID, and echo denotes the service. The numeric scope information is returned only if the NI_NUMERICSCOPE flag is issued.

For information about the format of the NAME string, see How structures are represented. See Socket call error return codes for additional information about the numeric error codes that are returned by this command.

The following REXX TCP/IP error numbers can be returned:
  • 1 EAI_NONAME
  • EAI_FAIL
  • 5 EAI_FAMILY
  • 7 EAI_BADFLAGS
The following REXX socket API error numbers can be returned:
  • 2001 EINVALIDRXSOCKETCALL
  • 2005 ESUBTASKNOTACTIVE

LE C/C++ equivalent

int getnameinfo(cons struct sockaddr *sa, socklen_t salen, 
         char *host, socklen_t hostlen, char *serv, socklen_t servlen, 
         int flags);

Code example

Figure 1. GETNAMEINFO command example
/* REXX EZARXR13 */
/*
 * This sample demonstrates the use of the GETNAMEINFO
 * socket command.
 */
src = socket("INITIALIZE","MYSET01");
if perror(src,"INITIALIZE") = 0 then
   Say socket("GETNAMEINFO", "AF_INET6 21 0 2000:197:11:103::1 0");
src = socket("TERMINATE","MYSET01");
src = perror(src,"TERMINATE");
exit 0;

/* This routine returns -1 if the first word if arg 1 is not zero */
perror: if word(arg(1),1) = 0 then return 0; else
    Say arg(2) "Error : "arg(1);
    return -1;