|
- Keyword
- Description
- SOC-FUNCTION
- A 16-byte character field containing GETADDRINFO. The field is
left-justified and padded on the right with blanks.
- NODE
- An input parameter. Storage up to
255 bytes long that contains the host name being queried. If the
AI-NUMERICHOST flag is specified in the storage pointed to by the
HINTS field, then NODE should contain the queried host's IP address
in presentation form. This is an optional field but if specified
you must also code NODELEN. The NODE name being queried will consist
of up to NODELEN or up to the first binary 0.
You can append scope
information to the host name, using the format node%scope
information. The combined information must be 255 bytes or less.
For more information, see z/OS Communications Server: IPv6 Network and
Application Design Guide.
- NODELEN
- An input parameter. A fullword binary field set to the length
of the host name specified in the NODE field and should not include
extraneous blanks. This is an optional field but if specified you
must also code NODE.
- SERVICE
- An input parameter. Storage up to
32 bytes long that contains the service name being queried. If the
AI-NUMERICSERV flag is specified in the storage pointed to by the
HINTS field, then SERVICE should contain the queried port number in
presentation form. This is an optional field but if specified you
must also code SERVLEN. The SERVICE name being queried will consist
of up to SERVLEN or up to the first binary 0.
- SERVLEN
- An input parameter. A fullword binary
field set to the length of the service name specified in the SERVICE
field and should not include extraneous blanks. This is an optional
field but if specified you must also code SERVICE.
- HINTS
- An input parameter. If the HINTS
argument is specified, it contains the address of an addrinfo structure
containing input values that may direct the operation by providing
options and limiting the returned information to a specific socket
type, address family, or protocol. If the HINTS argument is not specified,
then the information returned will be as if it referred to a structure
containing the value 0 for the FLAGS, SOCTYPE and PROTO fields, and
AF_UNSPEC for the AF field. Include the EZBREHST resolver macro so
that your assembler program will contain the assembler mappings for
the ADDR_INFO structure. The EZBREHST assembler macro is stored in
the SYS1.MACLIB library. The macro defines the resolver hostent (host
entry), address information (addrinfo) mappings, and services return
codes. Copy definitions from the EZACOBOL sample module to your COBOL
program for mapping the ADDRINFO structure. The EZACOBOL sample module
is stored in the hlq.SEZAINST library.
Copy definitions from the CBLOCK sample module to your PL/I program
for mapping the ADDRINFO structure. The CBLOCK sample module is stored
in hlq.SEZAINST library.
This is an optional
field.
The address information structure has the following
fields: - Field
- Description
- FLAGS
- A fullword binary field. Must have the value of 0 or the bitwise
OR of one or more of the following values:
- AI-PASSIVE (X'00000001') or the decimal value 1.
-
- Specifies how to specify the NAME pointed to
by the returned RES.
- If this flag is specified, then the returned address information
will be suitable for use in binding a socket for accepting incoming
connections for the specified service (for example, the BIND call).
In this case, if the NODE argument is not
specified, then the IP address portion of the socket address structure
pointed to by the returned RES will be set
to INADDR_ANY for an IPv4 address or to the IPv6 unspecified address
(in6addr_any) for an IPv6 address.
- If this flag is not set, the returned address information will
be suitable for the CONNECT call (for a connection-mode protocol)
or for a CONNECT, SENDTO, or SENDMSG call (for a connectionless protocol).
In this case, if the NODE argument is not
specified, then the IP address portion of the socket address structure
pointed to by the returned RES will be set
to the default loopback address for an IPv4 address (127.0.0.0) or
the default loopback address for an IPv6 address (::1).
- This flag is ignored if the NODE argument
is specified.
- AI-CANONNAMEOK (X'00000002') or the decimal value 2.
-
- If this flag is specified and the NODE argument is specified, then the GETADDRINFO call attempts to determine
the canonical name corresponding to the NODE argument.
- AI-NUMERICHOST (X'00000004') or the decimal value 4.
-
- If this flag is specified then the NODE argument must be a numeric host address in presentation form. Otherwise,
an error of host not found [EAI_NONAME] is returned.
- AI-NUMERICSERV (X'00000008') or the decimal value 8.
-
- If this flag is specified, the SERVICE argument must be a numeric port in presentation form. Otherwise,
an error [EAI_NONAME] is returned.
- AI-V4MAPPED (X'00000010') or the decimal value 16.
-
- If this flag is specified along with the AF field with the value
of AF_INET6 or a value of AF_UNSPEC when IPv6 is supported, the caller
will accept IPv4-mapped IPv6 addresses. When the AI-ALL flag is not
also specified, if no IPv6 addresses are found, a query is made for
IPv4 addresses. If IPv4 addresses are found, they are returned as
IPv4-mapped IPv6 addresses.
- If the AF field does not have the value of AF_INET6 or the AF
field contains AF_UNSPEC but IPv6 is not supported on the system,
this flag is ignored.
- AI-ALL (X'00000020') or the decimal value 32.
-
- When the AF field has a value of AF_INET6 and AI-ALL is set, the
AI-V4MAPPED flag must also be set to indicate that the caller will
accept all addresses (IPv6 and IPv4-mapped IPv6 addresses). When
the AF field has a value of AF_UNSPEC when the system supports IPv6
and AI-ALL is set, the caller accepts IPv6 addresses and either IPv4
address (if AI-V4MAPPED is not set), or IPv4-mapped IPv6 addresses
(if AI-V4MAPPED is set). A query is first made for IPv6 addresses
and if successful, the IPv6 addresses are returned. Another query
is then made for IPv4 addresses, and any IPv4 addresses found are
returned as either IPv4-mapped IPv6 addresses (if AI-V4MAPPED is also
specified), or as IPv4 addresses (if AI-V4MAPPED is not specified).
- If the AF field does not have the value of AF_INET6 or does not
have the value of AF_UNSPEC when the system supports IPv6, this flag
is ignored.
- AI-ADDRCONFIG (X'00000040') or the decimal value 64.
- If this flag is specified, then a query on the name in NODE will
occur if the Resolver determines whether either of the following conditions
is true:
- If the system is IPv6 enabled and has at least one IPv6 interface,
then the Resolver will make a query for IPv6 (AAAA or A6 DNS) records.
- If the system is IPv4 enabled and has at least one IPv4 interface,
then the Resolver will make a query for IPv4 (A DNS) records.
The loopback address is not considered in this case as a
valid interface.
- AI-EXTFLAGS (X'00000080') or the decimal value 128.
- Specifies this flag to request the extended form of the getaddrinfo
function. The extended form allows additional hints to be passed to
the resolver for determining the order of destination addresses that
are returned. If this flag is specified, the EFLAGS field is required.
Tip: To perform the binary OR'ing of
the flags above in a COBOL program, simply add the necessary COBOL
statements as in the example below. Note that the value of the FLAGS
field after the COBOL ADD is a decimal 80 or a X'00000050', which is the sum of OR'ing AI_V4MAPPED and AI_ADDRCONFIG or X'00000010' and X'00000040': 01 AI-V4MAPPED PIC 9(8) BINARY VALUE 16.
01 AI-ADDRCONFIG PIC 9(8) BINARY VALUE 64.
ADD AI-V4MAPPED TO FLAGS.
ADD AI-ADDRCONFG TO FLAGS.
- AF
- A fullword binary field. Used to limit the returned information
to a specific address family. The value of AF_UNSPEC means that the
caller will accept any protocol family. The value of a decimal 0
indicates AF_UNSPEC. The value of a decimal 2 indicates AF_INET,
and the value of a decimal 19 indicates AF_INET6.
- SOCTYPE
-
A fullword binary field. Used to limit the returned information
to a specific socket type. A value of 0 means that the caller will
accept any socket type. If a specific socket type is not given (for
example, a value of 0) then information on all supported socket types
will be returned.
The following table shows the acceptable
socket types:
Type name |
Decimal value |
Description |
---|
SOCK_STREAM |
1 |
for stream socket |
SOCK_DGRAM |
2 |
for datagram socket |
SOCK_RAW |
3 |
for raw-protocol interface |
Anything else will fail with return code EAI_SOCTYPE.
Note that although SOCK_RAW will be accepted, it will be valid only
when SERVICE is numeric (for example, SERVICE=23). A lookup for a
SERVICE name will never occur in the appropriate services file (for
example, hlq.ETC.SERVICES) using any protocol value other than
SOCK_STREAM or SOCK_DGRAM.
If PROTO is not 0 and SOCTYPE is
0, then the only acceptable input values for PROTO are IPPROTO_TCP
and IPPROTO_UDP. Otherwise, the GETADDRINFO call will be failed with
return code of EAI_BADFLAGS.
If SOCTYPE and PROTO are both
specified as 0, then GETADDRINFO will proceed as follows: - If SERVICE is null, or if SERVICE is numeric, then any returned
addrinfos will default to a specification of SOCTYPE as SOCK_STREAM.
- If SERVICE is specified as a service name (for example, SERVICE=FTP),
the GETADDRINFO call will search the appropriate services file (for
example, hlq.ETC.SERVICES) twice. The first search will use
SOCK_STREAM as the protocol, and the second search will use SOCK_DGRAM
as the protocol. No default socket type is provided in this case.
If both SOCTYPE and PROTO are specified as nonzero, then
they should be compatible, regardless of the value specified by SERVICE.
In this context, compatible can have one of the following meanings: - SOCTYPE=SOCK_STREAM and PROTO=IPPROTO_TCP
- SOCTYPE=SOCK_DGRAM and PROTO=IPPROTO_UDP
- SOCTYPE is specified as SOCK_RAW, in which case PROTO can be anything
- PROTO
- A fullword binary field. Used to limit the returned information
to a specific protocol. A value of 0 means that the caller will accept
any protocol.
The following table shows the acceptable protocols:
Protocol name |
Decimal value |
Description |
---|
IPPROTO_TCP |
6 |
TCP |
IPPROTO_UDP |
17 |
user datagram |
If SOCTYPE is 0 and PROTO is nonzero, the only acceptable
input values for PROTO are IPPROTO_TCP and IPPROTO_UDP. Otherwise,
the GETADDRINFO call will be failed with return code of EAI_BADFLAGS.
If PROTO and SOCTYPE are both specified as 0, then GETADDRINFO
will proceed as follows: - If SERVICE is null, or if SERVICE is numeric, then any returned
addrinfos will default to a specification of SOCTYPE as SOCK_STREAM.
- If SERVICE is specified as a service name (for example, SERVICE=FTP),
the GETADDRINFO will search the appropriate services file (for example, hlq.ETC.SERVICE) twice. The first search will use SOCK_STREAM
as the protocol, and the second search will use SOCK_DGRAM as the
protocol. No default socket type is provided in
this case.
If both PROTO and SOCTYPE are specified as nonzero, they
should be compatible, regardless of the value specified by SERVICE.
In this context, compatible can have one of the following meanings: - SOCTYPE=SOCK_STREAM and PROTO=IPPROTO_TCP
- SOCTYPE=SOCK_DGRAM and PROTO=IPPROTO_UDP
- SOCTYPE=SOCK_RAW, in which case PROTO can be anything
If the lookup for the value specified in SERVICE fails
[for example, the service name does not appear in an appropriate service
file (such as, hlq.ETC.SERVICES) using the input protocol],
then the GETADDRINFO call will be failed with return code of EAI_SERVICE.
- NAMELEN
- A fullword binary field followed by 8 padding bytes. On input,
this field must be 0.
- CANONNAME
- A fullword binary field followed by 4 padding bytes. On input,
this field must be 0.
- NAME
- A fullword binary field followed by 4 padding bytes. On input,
this field must be 0.
- NEXT
- A fullword binary field. On input, this field must be 0.
- EFLAGS
- A fullword binary field that specifies the source IPv6 address
selection preferences. This field is required if the value AI_EXTFLAGS
is specified in the FLAGS field.
This field must contain the value
0 or the bitwise OR of one or more of the following values: - IPV6_PREFER_SRC_HOME (X'00000001') or the decimal value
1
- Indicates that home source IPv6 addresses are preferred over care-of
source IPv6 addresses.
- IPV6_PREFER_SRC_COA (X'00000002') or the decimal value
2
- Indicates that care-of source IPv6 addresses are preferred over
home source IPv6 addresses.
- IPV6_PREFER_SRC_TMP (X'00000004') or the decimal value
4
- Indicates that temporary source IPv6 addresses are preferred over
public source IPv6 addresses.
- IPV6_PREFER_SRC_PUBLIC (X'00000008') or the decimal value
8
- Indicates that public source IPv6 addresses are preferred over
temporary source IPv6 addresses.
- IPV6_PREFER_SRC_CGA (X'00000010') or the decimal value
16
- Indicates that cryptographically generated source IPv6 addresses
are preferred over non-cryptographically generated source IPv6 addresses.
- IPV6_PREFER_SRC_NONCGA (X'00000020') or the decimal value
32
- Indicates that non-cryptographically generated source IPv6 addresses
are preferred over cryptographically generated source IPv6 addresses.
Guidelines: - If contradictory EFLAGS (for example, IPV6_PREFER_SRC_TMP and
IPV6_PREFER_SRC_PUBLIC) or invalid EFLAGS (for example, X'00000040' or the decimal value 64) are specified, then the GETADDRINFO call
fails with RETCODE -1 and ERRNO EAI_BADEXTFLAGS (decimal value 11).
- The COBOL constants for EFLAGS use hyphens instead of underscores.
- RES
-
Initially a fullword binary field. On a successful return,
this field contains a pointer to a chain of one or more address information
structures. The structures are allocated in the key of the calling
application. The structures that are returned on a GETADDRINFO call
are serially reusable storage for the z/OS® UNIX process. They
can be used or referenced between process threads, but should not
be used or referenced between processes. When you finish using the
structures, explicitly release their storage by specifying the returned
pointer on a FREEADDRINFO call. Include the EZBREHST resolver macro
so that your assembler program contains the assembler mappings for
the ADDR_INFO structure. The EZBREHST assembler macro is stored in
the SYS1.MACLIB library. Copy definitions from the EZACOBOL sample
module to your COBOL program for mapping the ADDRINFO structure.
The EZACOBOL sample module is stored in the hlq.SEZAINST library. Copy definitions from the CBLOCK sample module
to your PL/I program for mapping the ADDRINFO structure. The CBLOCK
sample module is stored in the hlq.SEZAINST
library.
The address information structure contains the following
fields:
- Field
- Description
- FLAGS
- A fullword binary field that is not used as output.
- AF
- A fullword binary field. The value returned in this field may
be used as the AF argument on the SOCKET call to create a socket suitable
for use with the returned address NAME.
- SOCTYPE
- A fullword binary field. The value returned in this field may
be used as the SOCTYPE argument on the SOCKET call to create a socket
suitable for use with the returned address NAME.
- PROTO
- A fullword binary field. The value returned in this field may
be used as the PROTO argument on the SOCKET call to create a socket
suitable for use with the returned address ADDR.
- NAMELEN
- A fullword binary field followed by 8 padding bytes. The length
of the NAME socket address structure.
- CANONNAME
- A fullword binary field followed by 4 padding bytes. The canonical
name for the value specified by NODE. If the NODE argument is specified,
and if the AI-CANONNAMEOK flag was specified by the HINTS argument,
then the CANONNAME field in the first returned address information
structure will contain the address of storage containing the canonical
name corresponding to the input NODE argument. If the canonical name
is not available, then the CANONNAME field will refer to the NODE
argument or a string with the same contents. The CANNLEN field contains
the length of the returned canonical name.
- NAME
- A fullword binary field followed by 4 padding bytes. The address
of the returned socket address structure. The value returned in this
field can be used as the arguments for the CONNECT, BIND, or BIND2ADDRSEL
call with such a socket, according to the AI-PASSIVE flag.
- NEXT
- A fullword binary field. Contains the address of the next address
information structure on the list, or 0's if it is the last structure
on the list.
- EFLAGS
- A fullword binary field that is not used as output.
- CANNLEN
- Initially an input parameter. A fullword binary field used to
contain the length of the canonical name returned by the RES CANONNAME
field. This is an optional field.
- 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.
The ADDRINFO structure uses indirect addressing to return
a variable number of NAMES. If you are coding in PL/I or assembler
language, this structure can be processed in a relatively straight-forward
manner. If you are coding in COBOL, this structure may be difficult
to interpret. You can use the subroutine EZACIC09 to simplify interpretation
of the information returned by the GETADDRINFO calls.
|