The INET6_IS_SRCADDR macro indicates whether an input IPV6 socket address matches an address that is defined to the stack, which conforms to one or more input IPV6_ADDR_PREFERENCES flags.

A client or server program can use the INET6_IS_SRCADDR macro when it strictly requires the IP addresses that it uses to have one or more specific attributes before allowing network activity. Such an application would perform the following tasks:

1. (Optional) Issue the SETSOCKOPT macro with the IPV6_ADDR_PREFERENCES option to set the selection preferences of the source IP address for the socket.
2. Issue the BIND2ADDRSEL macro to bind a socket to a local IP address. The BIND2ADDRSEL macro attempts to assign a local IP address that matches the IPV6_ADDR_PREFERENCES flags that are specified with the SETSOCKOPT macro, but does not guarantee that the local IP address that it selects satisfies all preferences.
3. Issue the GETSOCKNAME macro to obtain the local IP address bound to the socket.
4. Issue the INET6_IS_SRCADDR macro to verify whether the local IP address has the correct attributes.

The macro returns true (value 1) when the IPv6 address corresponds to a valid address in the node, and satisfies the given IPV6_ADDR_PREFERENCES flag or flags. If the IPv6 address input value does not correspond to any address in the node, or if the flags are not valid preference flags, the macro returns a failure (value -1). If the input address is a valid address on the node, but does not satisfy the preference flags indicated, the function returns false (value 0).

You can specify more than one IPV6_ADDR_PREFERENCES flag on this macro. All flags must be satisfied for the result to be true. Some IPV6_ADDR_PREFERENCES flags are contradictory. If you combine contradictory flags on a single macro invocation, the result will be false.

Keyword

Descriptions

NAME

An input parameter. An IPv6 socket address structure describing the interface address to be tested. Include the SYS1.MACLIB(BPXYSOCK) macro in your program to get the assembler mappings for the socket address structure. The socket address structure mappings begin at the SOCKADDR label. The AF_INET6 socket address structure fields start at the SOCK_SIN6 label.

The IPv6 socket address structure specifies the following fields:

FAMILY

A halfword binary field that specifies the IPv6 addressing family. This value must be set to AF_INET6.

Tip: You can specify an IPv4-mapped IPv6 address.

PORT

This field is ignored by the TYPE=INET6_IS_SRCADDR macro.

FLOWINFO

This field is ignored by the TYPE=INET6_IS_SRCADDR macro.

IP-ADDRESS

A 16-byte binary field that specifies the 128-bit IPv6 Internet address, in network byte order.

SCOPE-ID

A fullword binary field that specifies the scope for an IPv6 address as an interface index. This field must be nonzero if the address specified in the IPv6-ADDRESS field is a link-local address and must be 0 for any other scope.

FLAGS

An input parameter. The FLAGS argument can be a literal value or a fullword binary field. The following flags can be specified individually or in combination.

Flag name	Binary value	Description
IPV6_PREFER_SRC_HOME	X'00000001'	Test whether the input IP address is a home address.1
IPV6_PREFER_SRC_COA	X'00000002'	Test whether the input IP address is a care-of address.2
IPV6_PREFER_SRC_TMP	X'00000004'	Test whether the input IP address is a temporary address.
IPV6_PREFER_SRC_PUBLIC	X'00000008'	Test whether the input IP address is a public address.
IPV6_PREFER_SRC_CGA	X'00000010'	Test whether the input IP address is cryptographically generated.2
IPV6_PREFER_SRC_NONCGA	X'00000020'	Test whether the input IP address is not cryptographically generated.1
Notes: Any valid IP address that is known to the stack satisfies this flag. z/OS® Communications Server does not support this type of address. The macro always returns FALSE if this flag is specified with a valid IP address that is known to the stack.

Requirement: You must pass a binary number to the macro to specify more than one preference flags. Include the BPXYSOCK macro in your program to get the binary values for the flags.

Tip: Some of these flags are contradictory, for example:

• The flag IPV6_PREFER_SRC_HOME contradicts the flag IPV6_PREFER_SRC_COA.
• The flag IPV6_PREFER_SRC_CGA contradicts the flag IPV6_PREFER_SRC_NONCGA.
• The flag IPV6_PREFER_SRC_TMP contradicts the flags IPV6_PREFER_SRC_PUBLIC.

Result: If you specify contradictory flags on the macro, the result is FALSE.

Example:

MYFLAGS  DC  A(IPV6_PREFER_SRC_HOME+IPV6_PREFER_SRC_NONCGA)  one way to combine flags
EZASMI    TYPE=INET6_IS_SRCADDR,
            NAME=name,
            FLAGS=MYFLAGS

ERRNO

Output parameter. A fullword binary field. If the RETCODE value is negative, the ERRNO field contains a valid error number; otherwise, ignore ERRNO.

See Socket call error return codes for information about ERRNO return codes.

ECB or REQAREA

Input parameter. This parameter is required if you use APITYPE=3. This parameter points to a 104-byte field that contains one of the following values:

For ECB

A 4-byte ECB that is posted by TCP/IP when the macro completes.

For REQAREA

A 4-byte user token (set by you) that is presented to your exit when the response to this function request is complete.

For both ECB and REQAREA

The last 100 bytes is a storage field that is used by the interface to save the state information.

Requirement: This storage must not be modified until the macro function has completed and the ECB has been posted, or the asynchronous exit has been driven.

RETCODE

Output parameter. A fullword binary field that returns one of the following values:

Value

Description

0

False. The IPv6 address corresponds to a valid address in the node, but does not satisfy one or more of the input IPV6_ADDR_PREFERENCES flags.

1

True. The IPv6 address corresponds to a valid address in the node and satisfies the given IPV6_ADDR_PREFERENCES flag or flags.

Tip: Any valid IPv6 address on a z/OS V1R12 node satisfies the following preference flags:

• IPV6_PREFER_SRC_HOME
• IPV6_PREFER_SRC_NONCGA

-1

The input IPV6 address does not correspond to an address on the node or the input flags are not valid IPV6_PREFER_SRC_ADDR flags. Check the ERRNO value for an error code.

ERROR

Input parameter. The location in your program to receive control when the application programming interface (API) processing module cannot be loaded.

TASK

Input parameter. The location of the task storage area in your program.