Listening for client connection requests in an iterative server program

After the bind is issued, the server has been specified a particular IP address and port. It now must notify the TCP/IP address space that it intends to listen for connections on this socket. The listen() function puts the socket into passive open mode and allocates a backlog queue for pending connections. In passive open mode, the socket is open to client contact. For example:

listen(s, backlog_number);

The server gives to the socket on which it will be listening the number of requests that can be queued (the backlog_number). If a connection request arrives before the server can process it, the request is queued until the server is ready.

When you call listen, you inform TCP/IP that you intend to be a server and accept incoming requests from the IP network. By doing so, socket status is changed from active status to passive.

A passive socket does not initiate a connection; it waits for clients to connect to it.

The listen() call variables are shown in Figure 1.

Figure 1. Variables used by the listen call

*---------------------------------------------------------------*
* Variables used by the Listen Call                             *
*---------------------------------------------------------------*
 01  backlog-queue                  pic 9(8) binary value 10.
 01  socket-descriptor              pic 9(4) binary.
*---------------------------------------------------------------*
* Issue passive open via Listen call                            *
*---------------------------------------------------------------*
   call 'EZASOKET' using soket-listen
   socket-descriptor
   backlog-queue
   errno
   retcode.
 if retcode < 0 then
    - process error -

The backlog queue value is used by the TCP/IP system address space when a connect request arrives and your server program is busy processing the previous client request. TCP/IP queues new connection requests to the number you specify in the backlog queue parameter. If additional connection requests arrive, they are silently ignored by TCP/IP, since there is a limit to the size of the backlog queue parameter.

The system-wide limit is set in the TCP/IP system address space PROFILE.TCP/IP configuration data set by parameter SOMAXCONN. The default value of SOMAXCONN is ten, but you can configure it higher as follows:

;
; *************************************************************
; *  Set the listen queue to a maximum of 100                 *
; *************************************************************
;
SOMAXCONN 100

The value you specify on the listen() call in the backlog parameter cannot exceed the value set for SOMAXCONN in TCPIP.PROFILE. If you specify a backlog parameter of 200 and SOMAXCONN is set to 20, no error is returned, but your backlog queue size will be set to 20 instead of the 200 you requested.

There is a C header file called SOCKET.H (datasetprefix.SEZACMAC member SOCKET) in which there is a variable called SOMAXCONN. The shipped value of this variable is 10, as illustrated below:

/*
 *Maximum queue length specifiable by listen
/*
#define SOMAXCONN        10

The listen () call does not establish connections; it merely changes the socket to a passive state, so it is prepared to receive connection requests coming from the IP network. If a connection request for this server arrives between the time of the listen() call and the succeeding accept() call, it is queued according to the backlog value passed on the listen() call.