LISTEN

Only servers use the LISTEN macro. The LISTEN macro:

Completes the bind, if BIND has not already been called for the socket. If the BIND has already been called for in the socket, the LISTEN macro uses what was specified in the BIND call.
Creates a connection-request queue of a specified number of entries for incoming connection requests.

The LISTEN macro is typically used by a concurrent server to receive connection requests from clients. When a connection request is received, a new socket is created by a later ACCEPT macro. The original socket continues to listen for additional connection requests.

Note: Concurrent servers and iterative servers use this macro. An iterative server handles one client at a time. A concurrent server receives connection requests from multiple clients and creates subtasks that process the client requests. When a subtask is created, the concurrent server gets a new socket, passes the new socket to the subtask, and dissociates itself from the connection. The TCP⁄IP Listener program is an example of a concurrent server.

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=LISTEN--,S--=--+-number---+--------------------->
                               +-address--+   
                               +-*indaddr-+   
                               '-(reg)----'   

>--,BACKLOG--=--+-'number'-+--,ERRNO--=--+-address--+----------->
                +-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.

BACKLOG

Input parameter. A value (enclosed in single quotation marks) or the address of a fullword binary number specifying the number of messages that can be backlogged.

Rule: The BACKLOG value specified on the LISTEN macro is limited to 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. You might need to update SOMAXCONN if a larger backlog is desired. See the SOMAXCONN information in the z/OS Communications Server: IP Configuration Reference for details.

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.