BIND

Use the BIND command to bind a local NAME string to a socket descriptor.

The format of the NAME string depends on the addressing family of the socket. An application can use the BIND command to specify the network interface from which the socket can receive TCP connection requests or UDP packets. A socket bound to a specific local-IP address receives only packets that are targeted to that address. Outgoing packets have as their source address the address that is used to bind the socket. The BIND command supports both stream or datagram sockets, and it can be issued by both clients or servers.

Guidelines:
  • Do not bind a socket to a specific interface address. Binding a socket to a specific interface address limits network access to the application and might result in unexpected outages. To enable TCP connections to be accepted and UDP datagrams to be received over any interface, specify INADDR_ANY or IN6ADDR_ANY in the ipaddress field of the NAME parameter.
  • A server (an application that calls the LISTEN command) should always bind to the same well-known port. When the socket is bound and the LISTEN command is issued, the bound socket is marked as being passive. Passive sockets cannot be used to send or receive data. They are used to receive new connection requests from remote clients using the ACCEPT command.
  • The 48 EADDRINUSE error message indicates that a previous application is using the port. This error also can be received when a listening server is restarted. The TCP/IP stack maintains state information from the previous instance of the server for a fixed time before it releases a port and address for reuse. To avoid this situation, use the SETSOCKOPT command to set the SO_REUSEADDR socket option on the listening socket.

Format

Read syntax diagramSkip visual syntax diagramSOCKET("BIND" ,socketid,name )

Parameters

socketid
The socket descriptor.
name
The socket address to which the socket is to be bound.
The format for the name parameter depends on the socket type:
AF_INET sockets (IPv4)
name = "domain portid ipaddress"
AF_INET6 sockets (IPv6)
name = "domain portid flowinfo ipaddress scopeid"
where:
  • The domain value is the decimal number 2 for AF_INET and the decimal number 19 for AF_INET6.
  • The portid value is 0 or the local port to which the socket will bind. When the portid field is set to 0, the stack selects the local port.
  • The ipaddress value is the IP address to which the socket binds and the source address of outgoing packets. Other valid values are INADDR_ANY, IN6ADDR_ANY, INADDR_BROADCAST, BROADCAST, and LOOPBACK. When the ipaddress field is set to INADDR_ANY or IN6ADDR_ANY, the stack passes to the application any TCP connection requests or UDP datagrams that are received for the socket on any local interface. For outgoing packets, the stack selects the source address.
    Tip: System administrators can override the INADDR_ANY or IN6ADDR_ANY value by specifying the BIND option on the PORT reservation statement in the TCPIP.PROFILE file. This is equivalent to coding the IP address on the name parameter. For more information, see z/OS Communications Server: IP Configuration Reference.
  • The flowinfo value must be 0.
  • The scopeid value identifies the interfaces that are applicable for the scope of the address that is specified in the ipaddress field. For a link-local IP address, the scopeid field can specify a link index, which identifies a set of interfaces. For all other scopes, the scopeid field must be set to 0. Setting the scopeid field to 0 indicates that any address type and scope can be specified.

Returned value

The return code can be 0, a REXX socket API error number, or the REXX TCP/IP error number that is set by the socket command. The return code 0 indicates that the requested socket command was completed successfully.

See Socket call error return codes for additional information about the numeric error codes that are returned by this command.

The following REXX TCP/IP error numbers can be returned:
  • 1 EPERM
  • 9 EBADF
  • 22 EINVAL
  • 47 EAFNOSUPPORT
  • 48 EADDRINUSE
  • 49 EADDRNOTAVAIL
The following REXX socket API error numbers can be returned:
  • 2001 EINVALIDRXSOCKETCALL
  • 2009 ESOCKETNOTDEFINED

LE C/C++ equivalent

int bind(int socket, struct sockaddr *address, int *address_len);

Returned value

See the ACCEPT command for an example of using the BIND command.