SELECTEX

The SELECTEX macro monitors a set of sockets, a time value, and an ECB or list of ECBs. It completes when either one of the sockets has activity, the time value expires, or the ECBs are posted.

To use the SELECTEX call as a timer in your program, take either of the following actions:

Set the read, write, and exception arrays to zeros.
Do not specify MAXSOC.

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.

Testing sockets

Read, write, and exception operations can be tested. The SELECTEX macro monitors activity on selected sockets to determine whether:

A buffer for the specified sockets contains input data. If input data is available for a given socket, a read operation on that socket does not block.
TCP/IP can accommodate additional output data. If TCP/IP can accept additional output for a socket, a write operation on the socket does not block.
An exceptional condition occurs on a socket.
A timeout occurs on the SELECTEX macro itself. A TIMEOUT period can be specified when the SELECTEX macro is issued.

Each socket descriptor is represented by a bit in a bit string.

Read operations

The ACCEPT, READ, READV, RECV, RECVFROM, and RECVMSG macros are read operations. A socket is ready for reading when data is received on it, or when an exception condition occurs.

To determine if a socket is ready for the read operation, set the appropriate bit in RSNDMSK to 1 before issuing the SELECTEX macro. When the SELECTEX macro returns, the corresponding bits in the RRETMSK indicate sockets ready for reading.

Write operations

A socket is selected for writing, ready to be written, when:

TCP/IP can accept additional outgoing data.
A connection request is received in response to an ACCEPT macro.
A CONNECT call for a nonblocking socket, which has previously returned ERRNO 36 (EINPROGRESS), completes the connection.

The WRITE, WRITEV, SEND, SENDMSG, or SENDTO macros block when the data to be sent exceeds the amount that TCP/IP can accept. To avoid this, you can precede the write operation with a SELECTEX macro to ensure that the socket is ready for writing. After a socket is selected for WRITE, your program can determine the amount of TCP/IP buffer space available by issuing the GETSOCKOPT macro with the SO_SNDBUF option.

To determine if a socket is ready for the write operation, set the appropriate bit in WSNDMSK to 1.

Exception operations

For each socket to be tested, the SELECTEX macro can check for an exception condition. The exception conditions are:

The calling program (concurrent server) has issued a GIVESOCKET command and the target subtask has successfully issued the TAKESOCKET call. When this condition is selected, the calling program (concurrent server) should issue CLOSE to dissociate itself from the socket.
A socket has received out-of-band data. For this condition, a READ macro returns the out-of-band data before the program data.

To determine whether a socket has an exception condition, use the ESNDMSK character string and set the appropriate bits to 1.

Returning the results

For each event tested by a xSNDMSK, a bit string records the results of the check. The bit strings are RRETMSK, WRETMSK, and ERETMSK for read, write, and exceptional events. On return from the SELECTEX macro, each bit set to 1 in the xRETMSK is a read, write, or exceptional event for the associated socket.

MAXSOC parameter

The SELECTEX call must test each bit in each string before returning results. For efficiency, the MAXSOC parameter can be used to specify the largest socket descriptor number that needs to be tested for any event type. The SELECTEX call tests only bits that are in the range 0 through the MAXSOC value minus 1.

Example: If MAXSOC value is set to 50, the range would be 0 – 49.

TIMEOUT parameter

If the time in the TIMEOUT parameter elapses before an event is detected, the SELECTEX macro returns and RETCODE is set to 0.


>>-EZASMI--TYPE=SELECTEX--,MAXSOC--=--+-address--+-------------->
                                      +-*indaddr-+   
                                      '-(reg)----'   

>--,ERRNO--=--+-address--+--,RETCODE--=--+-address--+----------->
              +-*indaddr-+               +-*indaddr-+   
              '-(reg)----'               '-(reg)----'   

>--+---------------------------+-------------------------------->
   '-,TIMEOUT--=--+-address--+-'   
                  +-*indaddr-+     
                  '-(reg)----'     

>--+------------------------------------------------------+----->
   '-,RSNDMSK--=--+-address--+--,RRETMSK--=--+-address--+-'   
                  +-*indaddr-+               +-*indaddr-+     
                  '-(reg)----'               '-(reg)----'     

>--+------------------------------------------------------+----->
   '-,WSNDMSK--=--+-address--+--,WRETMSK--=--+-address--+-'   
                  +-*indaddr-+               +-*indaddr-+     
                  '-(reg)----'               '-(reg)----'     

>--+------------------------------------------------------+----->
   '-,ESNDMSK--=--+-address--+--,ERETMSK--=--+-address--+-'   
                  +-*indaddr-+               +-*indaddr-+     
                  '-(reg)----'               '-(reg)----'     

>--,SELECB--+---+--+-address--+--+----------+------------------->
            '-(-'  +-*indaddr-+  '-,'LIST')-'   
                   '-(reg)----'                 

>--+-------------------------+--+------------------------+-----><
   '-,ERROR--=--+-address--+-'  '-,TASK--=--+-address--+-'   
                +-*indaddr-+                +-*indaddr-+     
                '-(reg)----'                '-(reg)----'

Keyword

Description

MAXSOC

Input parameter. A fullword binary field that specifies the largest socket descriptor value being checked. The SELECTEX call tests only bits that are in the range 0 through the MAXSOC value minus 1. For example, if you set the MAXSOC value to 50, the range is 0 – 49.

ERRNO

Output parameter. A fullword binary field. If RETCODE is negative, this contains an error number.

RETCODE

Output parameter. A fullword binary field.

Value: Meaning
>0: The number of ready sockets.
Note: If the number of ready sockets is greater than 65535, only 65535 is reported.
0: Either the SELECTEX time limit has expired (ECB value is 0) or one of the caller's ECBs has been posted (ECB value is nonzero and the caller's descriptor sets is set to 0). The caller must initialize the ECB values to zero before issuing the SELECTEX socket command.
-1: Check ERRNO for an error code.

TIMEOUT

Input parameter.

If TIMEOUT is not specified, the SELECTEX call blocks until a socket becomes ready or until a user ECB is posted.

If a TIMEOUT value is specified, TIMEOUT is the maximum interval for the SELECTEX call to wait until completion of the call. If you want SELECTEX to poll the sockets and return immediately, TIMEOUT should be specified to point to a zero-valued TIMEVAL structure.

TIMEOUT is specified in the two-word TIMEOUT as follows:

TIMEOUT-SECONDS, word one of TIMEOUT, is the seconds component of the timeout value.
TIMEOUT-MICROSEC, word two of TIMEOUT, is the microseconds component of the timeout value (0—999999).

For example, if you want SELECT to timeout after 3.5 seconds, set TIMEOUT-SECONDS to 3 and TIMEOUT-MICROSEC to 500000. TIMEOUT, SELECTEX returns to the calling program.

RSNDMSK

Input parameter. The bit-mask array to control checking for read interrupts. If this parameter is not specified or the specified bit-mask is zeros, the SELECT does not check for read interrupts. The length of this bit-mask array is dependent on the value in MAXSOC and must be a multiple of 4 bytes. See Selecting requests in a concurrent server program for more information.

RRETMSK

Output parameter. The bit-mask array returned by the SELECT if RSNDMSK is specified. The length of this bit-mask array is dependent on the value in MAXSOC and must be a multiple of 4 bytes. See Selecting requests in a concurrent server program for more information.

WSNDMSK

Input parameter. The bit-mask array to control checking for write interrupts. If this parameter is not specified or the specified bit-mask is zeros, the SELECT does not check for write interrupts. The length of this bit-mask array is dependent on the value in MAXSOC and must be a multiple of 4 bytes. See Selecting requests in a concurrent server program for more information.

WRETMSK

Output parameter. The bit-mask array returned by the SELECT if WSNDMSK is specified. The length of this bit-mask array is dependent on the value in MAXSOC and must be a multiple of 4 bytes. See Selecting requests in a concurrent server program for more information.

ESNDMSK

Input parameter. The bit-mask array to control checking for exception interrupts. If this parameter is not specified or the specified bit-mask is zeros, the SELECT does not check for exception interrupts. The length of this bit-mask array is dependent on the value in MAXSOC and must be a multiple of 4 bytes. See Selecting requests in a concurrent server program for more information.

ERETMSK

Output parameter. The bit-mask array returned by the SELECT if ESNDMSK is specified. The length of this bit-mask array is dependent on the value in MAXSOC and must be a multiple of 4 bytes. See Selecting requests in a concurrent server program for more information.

SELECB

Input parameter. An ECB or list of ECB addresses which, if posted, causes completion of the SELECTEX.

If the address of an ECB list is specified, you must set the high-order bit of the last entry in the ECB list to 1 and you must also add the LIST keyword. The ECBs must reside in the caller's home address space.

Note: The maximum number of ECBs that can be specified in a list is 1013.

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.