BIND2ADDRSEL

The BIND2ADDRSEL macro binds a socket to the local IP address that would be selected by the stack to communicate with the input destination IP address.

Use the BIND2ADDRSEL macro when the application must verify that the local IP address assigned by the stack meets its address selection criteria as specified by the IPV6_ADDR_PREFERENCES socket option before the stack sends any packets to the remote host. In a TCP or UDP application, the BIND2ADDRSEL macro usually follows the SETSOCKOPT macro with option IPV6_ADDR_PREFERENCES and precedes any communication with a remote host.

Result: The stack attempts to select a local IP address according to your application preferences. However, a successful BIND2ADDRSEL macro does not guarantee that all of your selection preferences of source IP address were met.

Guidelines:

Use the SETSOCKOPT macro to set the IPV6_ADDR_PREFERENCES option to indicate your selection preferences of source IP address before binding the socket and before allowing an implicit bind of the socket to occur.
Result: If a socket has not been explicitly bound to a local IP address with a BIND or BIND2ADDRSEL macro when a CONNECT, SENDTO, or SENDMSG macro is issued, an implicit bind occurs. The stack chooses the local IP address used for outbound packets.

Requirement: When your application is using stream sockets, and must prevent the stack from sending any packets whatsoever (such as SYN) to the remote host before it can verify that the local IP address meets the values specified for the IPV6_ADDR_PREFERENCES option, do not allow the CONNECT macro to implicitly bind the socket to a local IP address. Instead, bind the socket with the BIND2ADDRSEL macro and test the local IP address assigned with the INET6_IS_SRCADDR macro. If the assigned local IP address is satisfactory, you can then use the CONNECT macro to establish communication with the remote host.
After you successfully issue the BIND2ADDRSEL macro, use the GETSOCKNAME macro to obtain the local IP address that is bound to the socket. When the local IP address is obtained, use the INET6_IS_SRCADDR macro to verify that the local IP address meets your address selection criteria.

The following requirements apply to this call:

Authorization:

Supervisor state or problem state, any PSW key.

Dispatchable unit mode:

Task.

Cross memory mode:

PASN = HASN.

Amode:

31-bit or 24-bit.

Note: See "Addressability mode (Amode) considerations" under CALL instruction API environmental restrictions and programming requirements.

ASC mode:

Primary address space control (ASC) mode.

Interrupt status:

Enabled for interrupts.

Locks:

Unlocked.

Control parameters:

All parameters must be addressable by the caller and in the primary address space.


>>-EZASMI--TYPE=BIND2ADDRSEL--,S--=--+-number---+--------------->
                                     +-address--+   
                                     +-*indaddr-+   
                                     '-(reg)----'   

>--,NAME--=--+-address--+--,ERRNO--=--+-address--+-------------->
             +-*indaddr-+             +-*indaddr-+   
             '-(reg)----'             '-(reg)----'   

>--,RETCODE--=--+-address--+--+---------------------------+----->
                +-*indaddr-+  +-,ECB--=--+-address--+-----+   
                '-(reg)----'  |          +-*indaddr-+     |   
                              |          '-(reg)----'     |   
                              '-,REQAREA--=--+-address--+-'   
                                             +-*indaddr-+     
                                             '-(reg)----'     

>--+-------------------------+--+------------------------+-----><
   '-,ERROR--=--+-address--+-'  '-,TASK--=--+-address--+-'   
                +-*indaddr-+                +-*indaddr-+     
                '-(reg)----'                '-(reg)----'

Keyword

Description

S

Input parameter. A value or the address of a halfword binary number that specifies the socket descriptor.

Requirements: The socket must be an AF_INET6 socket. The type can be SOCK_STREAM or SOCK_DGRAM.

NAME

Input parameter. The application provides a pointer to an AF_INET6 socket address structure. You can specify an IPv4 address by using its IPv4-mapped IPv6 format.

Guidelines:

Include the SYS1.MACLIB(BPXYSOCK) macro to get the assembler mappings for the socket address structure.
Begin the socket address structure mappings at the SOCKADDR label.
Begin the AF_INET6 socket address structure fields at the SOCK_SIN6 label.

The IPv6 socket structure must specify the following fields:

Field: Description
FAMILY: A halfword binary field that specifies the IPv6 addressing family. For IPv6 the value is the decimal value 19, indicating AF_INET6.
PORT: A halfword binary field. This field is ignored by BIND2ADDRSEL processing.
Guideline: The application can call the GETSOCKNAME macro after the BIND2ADDRSEL macro to discover the assigned port number.
FLOW-INFO: A fullword binary field that specifies the traffic class and flow label. This field is ignored by BIND2ADDRSEL processing.
IPv6-ADDRESS: A 16-byte binary field that is set to the 128-bit IPv6 Internet address, in network byte order, of the remote host machine that the application communicates with.
Rule: Specify an IPv4 address by using its IPv4-mapped IPv6 format.
SCOPE-ID: A fullword binary field that identifies a set of interfaces as appropriate for the scope of the address that is specified in the IPv6-ADDRESS field. The value 0 indicates that the SCOPE-ID field does not identify the set of interfaces to be used.
Requirement: The SCOPE-ID field must be nonzero if the address is a link-local address. For all other address scopes, the SCOPE-ID value must be set to 0.

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.

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.

ECB or REQAREA

Input parameter. This parameter is required if you use APITYPE=3. This parameter points to a 104-byte field containing 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 ECB/REQAREA: The last 100 bytes is a storage field that is used by the interface to save the state information.

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

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.