In a server program, the BIND macro normally follows a
SOCKET macro to complete the new socket creation process.
The BIND macro can specify the port or let the system
choose the port. A listener program should always bind to the same
well-known port so that clients know the socket address to use when
issuing a CONNECT, SENDTO, or SENDMSG request.
In addition to the port, the application also specifies
an IP address on the BIND macro. Most applications typically specify
a value of 0 for the IP address, which allows these applications to
accept new TCP connections or receive UDP datagrams that arrive over
any of the network interfaces of the local host. This enables client
applications to contact the application using any of the IP addresses
associated with the local host.
Alternatively, an application can indicate that it is
interested in receiving new TCP connections or UDP datagrams that
are targeted towards only a specific IP address associated with the
local host. This can be accomplished by specifying the IP address
in the appropriate field of the socket address structure passed on
the NAME parameter.
Tip: Even if an application specifies the value
0 for the IP address on the BIND, the system administrator can override
that value by specifying the BIND parameter on the PORT reservation
statement in the TCP/IP profile. The effect of this override is similar
to the effect of the application specifying an explicit IP address
on the BIND macro. For more information, see
z/OS Communications Server: IP Configuration
Reference.
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.
|
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=BIND--,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 specifying the socket descriptor.
- NAME
-
Input parameter. The IPv4 or IPv6 application provides
a pointer to an IPv4 or IPv6 socket address structure. This structure
specifies the port number and an IPv4 or IPv6 IP address from which
the application can accept connections. Include the SYS1.MACLIB(BPXYSOCK)
macro to get the assembler mappings for the socket address structure.
The socket address structure mappings begin at the SOCKADDR label.
The AF_INET socket address structure fields start at the SOCK_SIN
label. The AF_INET6 socket address structure fields start at the SOCK_SIN6
label.
See Designing an iterative server program for more information.
The IPv4 socket structure must specify the following fields:
- Field
- Description
- FAMILY
- A halfword binary field specifying the IPv4 addressing family.
For IPv4 the value is a decimal 2, indicating AF_INET.
- PORT
- A halfword binary field set to the port number that binds to the
socket. The application can call the GETSOCKNAME macro after the BIND
macro to discover the assigned port number.
- IPv4-ADDRESS
- A fullword binary field that is set to the 32-bit IPv4 Internet
address, in network byte order, of the host machine.
- RESERVED
- Specifies eight bytes of binary zeros. This field is required,
but not used.
The IPv6 socket structure must specify the following
fields:
- Field
- Description
- NAMELEN
- A 1-byte binary field specifying the length of this IPv6 socket
address structure. Any value specified by the use of this field is
ignored when processed as input and the field is set to 0 when processed
as output.
- FAMILY
- A 1-byte binary field specifying the IPv6 addressing family. For
IPv6 the value is a decimal 19, indicating AF_INET6.
- PORT
- A halfword binary field set to the port number that binds to the
socket. The application can call the GETSOCKNAME macro after the BIND
macro to discover the assigned port number.
- FLOW-INFO
- A fullword binary field specifying the traffic class and flow
label. This field must be set to 0.
- IPv6-ADDRESS
- A 16-byte binary field that is set to the 128-bit IPv6 Internet
address, in network byte order, of the host machine.
- SCOPE-ID
- A fullword binary field which identifies a set of interfaces as
appropriate for the scope of the address carried in the IPv6-ADDRESS field. A value of 0 indicates that the SCOPE-ID field does not identify the set of interfaces
to be used, and can be specified for any address types and scopes.
For a link scope IPv6-ADDRESS, SCOPE-ID can specify a link index which identifies
a set of interfaces. For all other address scopes, SCOPE-ID must be set to 0.
- ERRNO
- Output parameter. A fullword binary
field. If RETCODE is negative, ERRNO 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 are
using APITYPE=3. It points to a 104-byte field containing:
- For ECB
- A 4-byte ECB 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 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.