Parameter values set by the application

Keyword
Description
SOC-FUNCTION
A 16-byte character field containing GETNAMEINFO. The field is left-aligned and padded on the right with blanks.
NAME

An input parameter. A socket address structure to be translated which has the following fields:

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.
IP-ADDRESS
A fullword binary number specifying the 32-bit IPv4 IP 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
FAMILY
A halfword binary field specifying the IPv6 addressing family. For TCP/IP the value is a decimal 19, indicating AF_INET6.
PORT
A halfword binary number specifying the port number.
FLOWINFO
A fullword binary field specifying the traffic class and flow label. This value of this field is undefined.
IP-ADDRESS
A 16-byte binary field specifying the 128-bit IPv6 IP address, in network byte order.
SCOPE-ID
A fullword binary field that identifies a set of interfaces as appropriate for the scope of the address carried in the IPv6-ADDRESS field. For a link-local scope IPv6-ADDRESS, SCOPE-ID contains the interface index for the IPv6-ADDRESS. For all other address scopes, SCOPE-ID is undefined and is ignored by the resolver.
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 will return the host name up to the storage specified and truncation might occur. If the host name cannot be located, the numeric form of the host address is returned instead of its name. However, if the NI_NAMEREQD option is specified and no host name is located then an error is returned. HOST is an optional field, but if you specify it, you also must code HOSTLEN. 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.

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 in the format host%scope information. The scope information can be either the numeric form of the SCOPE-ID interface index or the interface name associated with the SCOPE-ID interface index. Use the NI_NUMERICSCOPE option to select which form should be returned. The combined host name and scope information will still be at most 255 bytes long. For more information about scope information and GETNAMEINFO processing, see z/OS Communications Server: IPv6 Network and Application Design Guide.

HOSTLEN
An output parameter. A fullword binary field that contains the length of the host storage used to contain the returned resolved host name. The HOSTLEN value must be equal to or greater than the length of the longest host name, or host name and scope information combination, to be returned. The GETNAMEINFO call returns the host name, or host name and scope information combination, up to the length specified by the HOSTLEN value. On output, the HOSTLEN value contains the length of the returned resolved host name or host name and scope information combination. If HOSTLEN is 0 on input, then the resolved host name is not returned. HOSTLEN is an optional field but if specified you must also 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 will return 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 numeric form of the service address is returned instead of its name. SERVICE is an optional field, but if you specify it, you also must code the SERVLEN 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.
SERVLEN
An output parameter. A fullword binary field. The length of the SERVICE storage used to contain the returned resolved service name. SERVLEN must be equal to or greater than the length of the longest service name to be returned. GETNAMEINFO will return the service name up to the length specified by SERVLEN. On output, SERVLEN will contain the length of the returned resolved service name. If SERVLEN is 0 on input, then the service name information will not be returned. SERVLEN is an optional field, but if you specify it, you also must code the SERVICE 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.
FLAGS
An input parameter. A fullword binary field. FLAGS is an optional field. The FLAGS field must contain either a binary value or decimal value, depending on the programming language used:
Flag name 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 Return only 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 Return only 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 Return only the numeric form of the scope information, when applicable
ERRNO
Output parameter. A fullword binary field. If RETCODE is negative, ERRNO contains a valid error number. Otherwise, ignore the ERRNO field.

See 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.