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