The GETNAMEINFO macro returns the node name and service location of a socket address that is specified in the macro. On successful completion, GETNAMEINFO returns the node and service named, if requested, in the buffers provided.

Keyword

Description

NAME

An input parameter. An IPv4 or IPv6 socket address structure to be translated. Include the SYS1.MACLIB(BPXYSOCK) macro to get the assembler mappings for the socket address structure. The socket address structure mappings begin at the SOCKADDR label. The AF_INET socket address structure fields start at the SOCK_SIN label. The AF_INET6 socket address structure fields start at the SOCK_SIN6 label.

The IPv4 socket address structure must specify the following fields:

Field

Description

FAMILY

A halfword binary number specifying the IPv4 addressing family. For TCP/IP the value is a decimal 2, indicating AF_INET.

PORT

A halfword binary number specifying the port number.

IPv4–ADDRESS

A fullword binary number specifying the 32-bit IPv4 Internet address.

RESERVED

An 8-byte reserved field. This field is required, but is not used.

The IPv6 socket address structure specifies the following fields:

Field

Description

NAMELEN

A 1-byte binary field that specifies the length of the IPv6 socket address structure. Any value specified by the use of this field is ignored when processed as input. The field is set to 0 when processed as output.

FAMILY

A 1-byte binary field that specifies the IPv6 addressing family. For TCP/IP the value is a decimal 19, indicating AF_INET6.

PORT

A halfword binary number that specifies the port number.

FLOW-INFO

This field is ignored by the TYPE=GETNAMEINFO macro.

IPv6–ADDRESS

A 16-byte binary field that specifies the 128-bit IPv6 Internet address, in network byte order.

SCOPE-ID

A fullword binary field that specifies the scope for an IPv6 address as an interface index. The resolver ignores the SCOPE_ID field, unless the address in IPv6-ADDRESS is a link-local address and the HOST parameter also is specified.

NAMELEN

An input parameter. A fullword binary field. The length of the socket address structure pointed to by the NAME argument.

HOST

On input, storage capable of holding the returned resolved host name, which can be up to 255 bytes long, for the input socket address. If inadequate storage is specified to contain the resolved host name, then the resolver returns the host name up to the storage specified and truncation might occur. If the host's name cannot be located, the numeric form of the host's address is returned instead of its name. However, if the NI_NAMEREQD option is specified and no host name is located, an error is returned. One or both of the following groups of parameters are required:

• The HOST and HOSTLEN parameters
• The SERVICE and SERVLEN parameters

Otherwise, an error occurs. The HOST name being queried consists of up to HOSTLEN or up to the first binary 0.

If the IPv6-ADDRESS value is a link-local address, and the SCOPE_ID interface index is nonzero, scope information is appended to the resolved host name using the format host%scope information. The scope information can be the numeric form of the SCOPE_ID interface index or the interface name that is associated with the SCOPE_ID interface index. Use the NI_NUMERICSCOPE option to select which form is returned. The combined host name and scope information is 255 bytes or less. For more information about scope information and TYPE=GETNAMEINFO processing, see z/OS Communications Server: IPv6 Network and Application Design Guide.

HOSTLEN

Initially an input parameter. A fullword binary field that contains the length of the host storage that is used to contain the returned resolved host name. If HOSTLEN is 0 on input, then the resolved host name is not returned. The HOSTLEN value must be equal to or greater than the length of the longest host name, or hostname and scope information combination, to be returned. The TYPE=GETNAMEINFO returns the host name, or host name and scope information combination, up to the length specified by the HOSTLEN value. On output, HOSTLEN contains the length of the returned resolved host name, or host name and scope information combination. This is an optional field, but if you specify this field, you also must code the HOST value. One or both of the following groups of parameters are required:

• The HOST and HOSTLEN parameters
• The SERVICE and SERVLEN parameters

Otherwise, an error occurs.

SERVICE

On input, storage capable of holding the returned resolved service name, which can be up to 32 bytes long, for the input socket address. If inadequate storage is specified to contain the resolved service name, then the resolver returns the service name up to the storage specified and truncation might occur. If the service name cannot be located, or if NI_NUMERICSERV was specified in the FLAGS operand, then the presentation form of the service address is returned instead of its name. This is an optional field, but if you specify this field, you also must code the SERVLEN parameter. The SERVICE name being queried consists of up to SERVLEN or up to the first binary zero. One or both of the following groups of parameters are required:

• The HOST and HOSTLEN parameters
• The SERVICE and SERVLEN parameters

Otherwise, an error occurs.

SERVLEN

Initially an input parameter. A fullword binary field that contains the length of the SERVICE storage used to contain the returned resolved service name. If SERVLEN is 0 on input, then the service name information is not returned. SERVLEN must be equal to or greater than the length of the longest service name to be returned. The TYPE=GETNAMEINFO returns the service name up to the length specified by SERVLEN. On output, SERVLEN contains the length of the returned resolved service name. This is an optional field, but if you specify it, you also must code the SERVICE parameter. One or both of the following groups of parameters are required:

• The HOST and HOSTLEN parameters
• The SERVICE and SERVLEN parameters

Otherwise, an error occurs.

FLAGS

An input parameter. A fullword binary field. This is an optional field. A resultant binary value can represent multiple flags. If this parameter is not specified, the fully qualified host name is returned. The FLAGS argument can be a literal value or a fullword binary field:

Literal Value	Binary Value	Decimal Value	Description
'NI_NOFQDN'	X'00000001'	1	Return the NAME portion of the fully qualified domain name.
'NI_NUMERICHOST'	X'00000002'	2	Only return the numeric form of host's address.
'NI_NAMEREQD'	X'00000004'	4	Return an error if the host's name cannot be located.
'NI_NUMERICSERV'	X'00000008'	8	Only return the numeric form of the service address.
'NI_DGRAM'	X'00000010'	16	Indicates that the service is a datagram service. The default behavior is to assume that the service is a stream service.
'NI_NUMERICSCOPE'	X'00000020'	32	Only return the numeric form of the SCOPE-ID interface index, if applicable.

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.

ERRNO

Output parameter. A fullword binary field. If RETCODE is negative, ERRNO contains a valid error number. Otherwise, ignore the ERRNO field.

See Socket call error return codes for information about ERRNO return codes.

RETCODE

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

Value

Description

0

Successful call.

-1

Check ERRNO for an error code.

ERROR

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