 |
- Keyword
- Description
- SOC-FUNCTION
- A 16-byte character field containing GETNAMEINFO. The field is
left-justified 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 may 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 may 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 then an error is returned. This 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 using 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. This 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 may 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 may 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. This 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.
This 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. This 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 |
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 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 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.
|
z/OS Communications Server: IP Sockets Application Programming Interface Guide and Reference
Copyright IBM Corporation 1990, 2014