The select/selectex callable service checks the I/O status of multiple open file descriptors and message queues. The file descriptors can be for character special files, pipes, sockets, or files.
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1SEL): | 31-bit |
AMODE (BPX4SEL): | 64-bit |
ASC mode: | Primary mode |
Interrupt status: | Enabled for interrupts |
Locks: | Unlocked |
Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
|
AMODE 64 callers use BPX4SEL with the same parameters. All parameter addresses and addresses in parameter structures are doublewords.
The name of a fullword of which the first halfword (the high-order 16 bits) contains the number of message queues and the second halfword (the low-order 16 bits) contains the number of file descriptors.
The number of file descriptors should be the highest file descriptor that is being checked for status, plus 1.
For example, if you are interested in the I/O status of file descriptors 5 and 9, the second halfword of Number_msgsfds would be 10. Ten is the number of file descriptors that are contained in each of the bit sets (fd 0 through 9 equals 10 fds), and 10 is the highest file descriptor that is being checked, plus 1 (9 plus 1 equals 10). If you want to check file descriptors for status along with message queues, the highest file descriptor you can specify is 2047.
The number of message queues indicates the number of elements (queue IDs) in each of the arrays contained in Read_list, Write_list, and Exception_list. For example, if you specify a value of 10 in the first halfword of Number-msgsfds, it is expected that arrays of 10 elements each are given in Read_list, Write_list, and Exception_list. If you specify a value of 0, it is assumed that no arrays are given and that no message queues are to be checked. The maximum number of message queues that you can specify is 32 767.
The name of a field that contains the length, in bytes, of the Read_list. The length is actually the sum of the length (rounded up to a multiple of 4 bytes) of the bit set specifying file descriptors and the length of the array of message queue identifiers. When both file descriptors and message queues are specified, this field should contain a value greater than 256 bytes. If 0 is specified, the Read_list is not checked by the select service.
The name of a structure that contains the bit set for the specified file descriptors and/or the array of message queue identifiers. Note that the bit set must be padded with extra bytes, if necessary, to round up its length to the next multiple of 4 bytes. The bits in the bit set should be turned on for the corresponding descriptors to be checked for reading. The format of the bits can be specified with the User_option field. On return, the bits that are set indicate the descriptors that are ready for reading.
If Read_list contains both a bit set and an array of message queue identifiers, the bit set must be 256 bytes in length. If only file descriptors are to be checked, the bit set can have any valid size.
Each element of the array of message queue identifiers is 4 bytes in length. Elements with a value of -1 are acceptable and are ignored. On return, the array is altered such that message queue identifiers that do not meet the criterion are replaced with a value of -1.
The name of a field that contains the length, in bytes, of the Write_list. The length is actually the sum of the length (rounded up to a multiple of 4 bytes) of the bit set specifying file descriptors and the length of the array of message queue identifiers. When both file descriptors and message queues are specified, this field should contain a value greater than 256 bytes. If 0 is specified, the Write_list is not checked by the select service.
The name of a structure that contains the bit set for the specified file descriptors and/or the array of message queue identifiers. Note that the bit set must be padded with extra bytes, if necessary, to round up its length to the next multiple of 4 bytes. The bits in the bit set should be turned on for the corresponding descriptors to be checked for writing. The format of the bits can be specified with the User_option field. On return, the bits that are set indicate the descriptors that are ready for writing.
If Write_list contains both a bit set and an array of message queue identifiers, the bit set must be 256 bytes in length. If only file descriptors are to be checked, the bit set can have any valid size.
Each element of the array of message queue identifiers is 4 bytes in length. Elements with a value of -1 are acceptable and are ignored. On return, the array is altered such that message queue identifiers that do not meet the criterion are replaced with a value of -1.
The name of a field that contains the length in bytes of the Exception_list. The length is actually the sum of the length (rounded up to a multiple of 4 bytes) of the bit set specifying file descriptors and the length of the array of message queue identifiers. When both file descriptors and message queues are specified, this field should contain a value greater than 256 bytes. If 0 is specified, the Exception_list is not checked by select.
The name of a structure that contains the bit set for the specified file descriptors and/or the array of message queue identifiers. Note that the bit set must be padded with extra bytes, if necessary, to round up its length to the next multiple of 4 bytes. The bits in the bit set should be turned on for the corresponding descriptors to be checked for exceptions. The format of the bits can be specified with the User_option field. On return, the bits that are set indicate the descriptors that have had exceptions.
If Exception_list contains both a bit set and an array of message queue identifiers, the bit set must be 256 bytes in length. If only file descriptors are to be checked, the bit set can have any valid size.
Each element of the array of message queue identifiers is 4 bytes in length. Elements with a value of -1 are acceptable and will be ignored. On return, the array is altered such that message queue identifiers that do not meet the criterion are replaced with a value of -1.
If the timeout_pointer is zero, the select system call waits (indefinitely) until one of the selected descriptors is ready.
If the timeout value is 0, select returns immediately after checking the selected descriptors; no waiting is done.
If a doubleword is used for Ecb_pointer, the high half must be set to zero (ECBs must be below the bar). In this case, the high-order bit that indicates Ecb_pointer usage is the high bit in the lower half of the doubleword.
The list can contain the pointers for up to 1013 ECBs. The high-order bit of the last pointer in the list must be set to B'1'. If the input Ecb_pointer is a doubleword, the high half must be zero, and the bit that is checked is the high-order bit of the lower half of the doubleword. If the high-order bit is a 1, the lower half of the doubleword points to a list of Ecb_pointers. All Ecb_pointers in the list must be 31-bit pointers.
A dual-purpose field that is used as input to specify the format of the read, write, and exception bit lists, and as output to contain the first selected file descriptor that was not supported by the select service.
Word 1 Word 2 Word 3
------------------- ----------------------- ----------------------
31 30 29...3 2 1 0 63 62 61...35 34 33 32 95 94 93...67 66 65 64
------------------- ----------------------- ----------------------
Word 1 Word 2 Word 3
------------------- ----------------------- ----------------------
0 1 2 3...29 30 31 32 33 34 35...61 62 63 64 65 66.67...93 94 95
------------------- ----------------------- ----------------------
Return_code | Explanation |
---|---|
EINTR | The select service request was interrupted by a signal for the caller. |
EINVAL | One of the parameters contains a value that is not correct. The following reason codes can accompany this return code: JRNoLists, JRListTooShort, JRMsOutOfRange, JRInvUserOp, JRSecOutOfRange, JRNoFds, JRTooManyMsgQIds,JRTooManyFds, JRListLenBad. |
EIO | One of the descriptors in the select mask has become inoperative, and it is being included repeatedly in a select, even though other operations against this descriptor have been failing with EIO. A socket descriptor can become inoperative, for example, if TCP/IP is shut down. When a descriptor fails, a failure from select does not tell you which descriptor has failed. The select call usually succeeds, and the descriptors are reported to you as being ready for whatever events were specified on the select call. When the descriptor is subsequently used on a receive or other operation, you will receive the EIO failure and can then react to the problem with that individual descriptor. In general, you would close() the descriptor and remove it from the next select mask. If the individual descriptor's failing return code is ignored, however, and an inoperative descriptor is repeatedly selected on and used (even though each time it is used the call fails with EIO), the select call itself will eventually fail with EIO. |
The name of a fullword in which the select service stores the reason code. The select service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.
Number of fds = 60
Read_list_length = 8
Read_list = the bit representing fd 59 is set on (see User_option_field
to determine which bit that would be)
Write_list_length = 8
Write_list = the bit representing fd 6 is set on (see User_option_field
to determine which bit that would be)
Exception_list_length = 0
When the fullword value is between 65 536 and the system descriptor maximum, one of the lists that is passed is at least 8 192 bytes long, and the descriptor limit of the process is at least 65 536, the fullword value is considered as the number of descriptors in the lists, and no message queues will be processed.
The following example illustrates what you must do:
Suppose you want to check the read status for file descriptors 3 and 5 and the write status for message queues whose identifiers are 7 and 8.
Number of fds = 6 (the largest fd plus 1)
Number of message queues = 2
Read_list_length = 264 (256 byte bit set length + 8 byte array length) Read_list = the 256-byte bit set with appropriate bits set on for fds 3 and 5, followed by a two-element array that contains the value of -1 in both elements.
Write_list_length = 264 (same length as for read) Write_list = the 256-byte bit set with all its bits set off followed by the two-element array that contains the numbers 7 and 8.
Exception_list_length = 0
There are no restrictions on the use of the select service.
For an example using this callable service, see BPX1SEL (select) example.