BIND

In a typical server program, the BIND call follows a SOCKET call and completes the process of creating a new socket.

The BIND socket command 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 socket command. 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.

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.

Figure 1 shows an example of BIND call instructions.

Figure 1. BIND call instruction example

    WORKING-STORAGE SECTION.
        01  SOC-FUNCTION    PIC X(16)  VALUE IS 'BIND'.
        01  S               PIC 9(4) BINARY.

     * IPv4 socket address structure.
        01  NAME.
            03  FAMILY      PIC 9(4) BINARY.
            03  PORT        PIC 9(4) BINARY.
            03  IP-ADDRESS  PIC 9(8) BINARY.
            03  RESERVED    PIC X(8).

     * IPv6 socket address structure.
        01  NAME.
            03  FAMILY      PIC 9(4) BINARY.
            03  PORT        PIC 9(4) BINARY.
            03  FLOWINFO    PIC 9(8) BINARY.
            03  IP-ADDRESS.
                10 FILLER   PIC 9(16) BINARY.
                10 FILLER   PIC 9(16) BINARY.
            03  SCOPE-ID    PIC 9(8) BINARY.

        01  ERRNO           PIC 9(8) BINARY.
        01  RETCODE         PIC S9(8) BINARY.
 
    PROCEDURE DIVISION.
         CALL 'EZASOKET' USING SOC-FUNCTION S NAME ERRNO RETCODE.

For equivalent PL/I and assembler language declarations, see Converting parameter descriptions.