HPSELECT

Syntax

  I16                    IV        CA        CA
  numselect := HPSELECT (numfiles, readmask, writemask,
                         CA             R        I32
                         exceptionmask, timeout, status);

Functional Return

numselect

16-bit signed integer (assigned functional return)

Returns a value representing the number of files that have selected true. The following values are returned:

Value	Meaning
n	The number of files that have selected true.
0	If a timeout value was assigned and the select "timed out".
-1	If an error occurred in the call, an internal error occurred, or if a soft interrupt occurred before any selected events or before the time limit expired.

Parameters

numfiles

integer by value (required)

Passes the number of files (number of files -1) whose bits will be checked by HPSELECT.

Note that this parameter does not represent the number of files where a bit in one of the masks is being set. It represents the highest file number (minus 1) that will be examined by HPSELECT.

readmask

character array by reference (optional)

Specifies which file numbers will be examined to see if the file that is ready for reading should be passed. The least significant bit of each 32-bit word represents the lowest file number in the word. The first word contains the bits for the first 32 files. Subsequent words contain the bits for additional groups of 32 files.

For each file number less than numfiles, the corresponding bit in the mask is set at return if the bit was set at entry and the file is ready for reading.

Bits representing file numbers greater than numfiles (minus 1) are ignored. The buffer containing the bit mask only needs to be as large as the number of 32-bit words required to contain the bits for numfiles files.

If a timeout is specified and the time limit has elapsed, the mask is cleared on return.

Default: No files are checked for reading.

writemask

character array by reference (optional)

Specifies which file numbers are to be examined to see if the file is ready for writing. The last significant bit of each 32-bit word represents the lowest file number in the word. The first word contains the bits for the first 32 files. Subsequent words contain the bits for additional groups of 32 files.

For each file number less than numfiles, the corresponding bit in the mask is set at return if the bit was set at entry and the file is ready for writing.

Bits representing file numbers greater than numfiles (minus 1) are ignored. The buffer containing the bit mask only needs to be as large as the number of 32-bit words required to contain the bits for numfiles files.

If a timeout is specified and the time limit has elapsed, the mask is cleared on return.

Default: No files are checked for writing.

exceptionmask

character array by reference (optional)

Specifies which file numbers are to be examined to see if the file has detected an exception condition. The last significant bit of each 32-bit word represents the lowest file number in the word. The first word contains the bits for the first 32 files. Subsequent words contain the bits for additional groups of 32 files.

For each file number less than numfiles, the corresponding bit in the mask is set at return if the bit was set at entry and the file has detected an exception condition.

Bits representing file numbers greater than numfiles (minus 1) are ignored. The buffer containing the bit mask only needs to be as large as the number of 32-bit words required to contain the bits for numfiles files.

If a timeout is specified and the time limit has elapsed, the mask is cleared on return.

Default: No files are checked for exception conditions.

timeout

record by reference (optional)

Specifies a maximum interval to wait for the selection to complete. If a timeout value of 0 is supplied, HPSELECT checks for the specified conditions, sets the return mask, and returns without blocking even if none of the specified conditions are true. If a timeout value is not specified, HPSELECT waits until an event causes one of the masks to be returned with a non-zero value.

The timeout value is specified by a 64-bit record containing the following two fields:

32-bit unsigned integer = seconds
32-bit integer = microseconds

Values up to 2**32 seconds can be specified.

Default: HPSELECT blocks until one of the specified conditions is true.

status

32-bit integer by reference (optional)

Returns the status of the HPSELECT call. If no errors or warnings are encountered, status returns 32 bits of zero. If errors or warnings are encountered, status is interpreted as two 16-bit fields.

Bits (0:16) comprise status.info. A negative value indicates an error condition, and a positive value indicates a warning condition. Refer to the MPE/iX Error Message Manual Volumes 1, 2 and 3 for a description of its value.

Bits (16:16) comprise status.subsys. The value represented by these bits defines the subsystem that set the status information. The subsystem identifier for HPSELECT is 143.

Possible error values of status.info are:

Value	Meaning
-9	Illegal parameter - the value of numfiles is negative or an invalid timeout value was specified.
-18	Bounds violation - one or more parameters point to an invalid address or to an address the user does not have access to.
-30	Invalid file reference - one or more of the bit masks specified an invalid file number.
-90	Timeout - the time limit expired before any selected events occurred.
-91	Soft interrupt - a soft interrupt occurred before any selected events occurred or before the time limit expired.
No status	If status is not passed in, no status is returned.

NOTE: HPSELECT will not ESCAPE if an error is detected and the status parameter was not supplied. Errors are also indicated by a -1 in the numselect parameter (functional return). For assurance of a successful completion, check the functional return. The only file type supported by HPSELECT is Net IPC. For all other file types, HPSELECT always returns TRUE.

Related Information