RMKeyToHandleList

This rmcall service searches for the specified adapter, device, or LDev. It also searches for Resource Manager nodes that match the key specified. A list of node handles found is returned in the HandleList structure provided by the caller.

Syntax

RMKeyToHandleList(hStartNode, SearchKey, HandleList);

Parameters

hStartNode (RMHANDLE) - input

The handle of the Resource Manager node at which to start the search. This node and all its descendents will be checked. The handle provided may be an adapter handle (HADAPTER) or logical device handle (HLDEV).

The following "pseudohandles" may also be used as a starting point for a search:

Pseudohandle             Nodes Searched
HANDLE_PHYS_TREE         Physical Device Nodes
HANDLE_SYS_TREE          Logical Device Nodes
HANDLE_DEFAULT_SYSBUS    System Bus Nodes (ISA/EISA/Micro Channel)
HANDLE_X_BUS             Planar Bus Nodes
HANDLE_PCI_BUS           PCI Bus Nodes

SearchKey (PSZ) - input

Pointer to an ASCIIZ string containing the key to be located. If the key supplied ends in an asterisk (*), then all keys that match the characters up to the asterisk will be returned. Key searches are treated as case-insensitive. For example, "FIXDSK_*" will return all fixed-disk logical device handles.

This service does not currently support full (regular pattern matching), for example, only the asterisk is supported.

Adapter key values are chosen at the discretion of the device-driver supplier and are subject to change.

HandleList (PHANDLELIST) - output

Pointer to the HANDLELIST structure.

Return Code

rc (APIRET) - returns

On systems where the Resource Manager driver is not installed, the library interface code will return RMRC_NOT_INSTALLED.

RMRC_IRQ_ENTRY_ILLEGAL

A Resource Manager service was issued at interrupt time. The Resource Manager service request can be issued only at task time or INIT time.

RMRC_NULL_POINTER

A Resource Manager service received a NULL value for a pointer that was expected to contain a valid 16:16 address.

RMRC_INVALID_PARM_VALUE

A nonhandle or nonpointer variable contains an invalid or out-of-range value because:

An invalid decode width was specified when allocating an I/O Port range.

A handle search is being performed with cMaxHandles set to 0.

RMRC_BAD_DEVICEHANDLE

The expected Resource Manager handles were not provided because the handle was not a valid Resource Manager handle or the handle did not point to the type of object the service required.

Remarks

None.

Example Code

C

#include <os2.h>
#include <rmcalls.h>

RMHANDLE       hStartNode;
PSZ            SearchKey;
PHANDLELIST    HandleList;
APIRET         rc;

rc = RMKeyToHandleList(hStartNode, SearchKey,
       HandleList);