Parameter values set by the application

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.