LISTEN call

The LISTEN call:

Completes the bind, if BIND has not already been called for the socket.
Creates a connection-request queue of a specified length for incoming connection requests.

Note: The LISTEN call is not supported for datagram sockets or raw sockets.

The LISTEN call is typically used by a server to receive connection requests from clients. When a connection request is received, a new socket is created by a subsequent ACCEPT call, and the original socket continues to listen for additional connection requests. The LISTEN call converts an active socket to a passive socket and conditions it to accept connection requests from clients. After a socket becomes passive, it cannot initiate connection requests.

Note: The BACKLOG value specified on the LISTEN command cannot be greater than the value configured by the SOMAXCONN statement in the stack's TCPIP PROFILE (default=10); no error is returned if a larger backlog is requested. If you want a larger backlog, update the SOMAXCONN statement. See the z/OS Communications Server: IP Configuration Reference for details.

The following requirements apply to this call:

Requirement	Description
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

Figure 1 shows an example of LISTEN call instructions.

Figure 1. LISTEN call instruction example

    WORKING-STORAGE SECTION.
        01  SOC-FUNCTION    PIC X(16)  VALUE IS 'LISTEN'.
        01  S               PIC 9(4) BINARY.
        01  BACKLOG         PIC 9(8) BINARY.
        01  ERRNO           PIC 9(8) BINARY.
        01  RETCODE         PIC S9(8) BINARY.
 
    PROCEDURE DIVISION.
        CALL 'EZASOKET' USING SOC-FUNCTION S BACKLOG ERRNO RETCODE.

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