SELECT

Use the SELECT command to monitor groups of sockets to determine when one or more of the sockets is ready for a read operation, is ready for a write operation, or has an exception pending.

Guidelines:

A close on the other side of a socket connection is reported not as an exception but as a read event, which returns 0 bytes of data.
When the CONNECT command is called with a socket descriptor in nonblocking mode, set up completion is reported as a write event on the socket.
The SELECT command returns an exception pending when either a connection is reset or when a TAKESOCKET command is completed for a socket that was previously given using the GIVESOCKET command.

Format


>>-SOCKET--(--"SELECT"--,--fdset--+------------+--)------------><
                                  '-,--timeout-'

Parameters

fdset

Specifies the set of socket descriptors to be monitored for activity. The fdset parameter is a string in the following format:

"READ" rdlist "WRITE" wrlist "EXCEPTION" exlist

where:

The rdlist value is a space-delimited list of sockets to be monitored for reading.
The wrlist value is a space-delimited list of sockets to be monitored for writing.
The exlist value is a space-delimited list of sockets to be monitored for exceptions.

To specify that all sockets are monitored, set the value of the rdlist, wrlist, or exlist string to an asterisk (*).

For example, if you want to monitor the sockets with files descriptors 1, 2, and 3 to determine when the socket has data to be read, issue the following command:

SOCKET("SELECT","READ 1 2 3 WRITE EXCEPTION",120);

This code example also sets a timeout parameter of 120 seconds.

To specify that no sockets are monitored, issue the following command:

SOCKET("SELECT","READ WRITE EXCEPTION",);

timeout

A positive integer that indicates the maximum length of time (in seconds) that the SELECT command will monitor the sockets. If no timeout parameter is specified, the sockets are monitored indefinitely.

Returned value

The command returns a string that contains the return code, the number of ready sockets, and information about the ready sockets. 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.

The following string is an example of what is returned by the SELECT command:

0 2 READ 1 3 WRITE EXCEPTION

In this example, 0 is the return code, 2 is the number of ready sockets, and 1 and 3 are the sockets that ready for READ operations. There are no sockets ready for WRITE operations or sockets with pending exceptions.

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:

9 EBADF
22 EINVAL
38 ENOTSOCK
45 EOPNOTSUPP

The following REXX socket API error numbers can be returned:

2001 EINVALIDRXSOCKETCALL
2005 ESUBTASKNOTACTIVE
ESOCKETNOTDEFINED
2012 EINVALIDNAME

LE C/C++ equivalent

This command has no LE C/C++ equivalent.

Code example

Figure 1. SELECT command example

/* REXX EZARXR24 */
/*
 * This is an example of a function command that can be used to
 * to determine if a connection is available. This procedure
 * would be called before calling the ACCEPT command.
 *
 * Two arguments are passed. The p_listensocketlist is a
 * list of 1 or more space-delimited socket descriptors to be
 * monitored. The p_timeout value is how long the SELECT
 * command should wait before returning.
 *
 * The monitored sockets can be BLOCKING or NON-BLOCKING
 * sockets.
 *
 * Example usage:
 *
 * INITIALIZE a socket set.
 * open a SOCKET descriptor.
 * BIND the socket to a well known port.
 * set the socket to passive mode using the LISTEN command.
 * LOOP:
 * Call the IsConnectionAvailable function
 * If a connection is available, ACCEPT the connection
 * and continue processing. Otherwise, do some other work,
 * and loop.
 *
 * Function Usage:
 *    l_retcode = IsConnectionAvailable(l_sockid,60);
 *
 * The function will return one of the following:
 *  - The list of socket descriptors that have
 *    connections pending.
 *
 *  - The string "TIMEOUT". This indicates the select command
 *    timed out before any connections arrived.
 *
 *  - the string "ERROR". This indicates an ERROR occurred
 *    when the SELECT command was issued.
 */
IsConnectionAvailable: PROCEDURE
Parse arg p_listensocketlist, p_timeout
l_fdset = "READ "p_listensocketlist" WRITE EXCEPTION";
l_retvalue = SOCKET("SELECT",l_fdset,p_timeout);
parse var l_retvalue l_retcode l_numSockets;
if l_retcode = 0 then do
   if l_numsocket > 0 then do
      parse value l_retvalue with 'READ' l_sockidrdlist 'WRITE' .;
      parse value l_retvalue with 'WRITE' l_sockidwrlist 'EXCEPTION' .
      parse value l_retvalue with 'EXCEPTION' l_sockidexlist;
      l_retcode = l_sockidrdlist;
   end
   else do
      Say "Select command timed out";
      l_retcode = "TIMEOUT"
   end;
end;
else do
   l_retcode = "ERROR";
end;
return l_retcode;

Tip: See the IOCTL command for another example on how to use SELECT command.