|
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.
|
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 socketsRead, 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 operationsThe 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 operationsA 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 operationsFor 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 resultsFor 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 parameterThe 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 parameterIf 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.
|