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.
Format
>>-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;