HP OpenVMS Systems Documentation

HP OpenVMS DCL Dictionary

Returns the device names of all devices on a system that meet the
specified selection criteria.

Note that the device names are returned in random order.

Format

F$DEVICE ([search_devnam],[devclass],[devtype], [stream-id])

Return Value

A character string containing the name of a device in the system's list
of devices. After the last device name in the system's device list is
returned, the F$DEVICE function returns a null string ("").

Arguments

search_devnam

Specifies the name of the device for which F$DEVICE is to search. The
asterisk (*) and the percent sign (%) wildcard characters are allowed
in the search_devnam argument.

Specify the search_devnam argument as a character
string expression.

devclass

Specifies the device class for which F$DEVICE is to search. Specify the
devclass argument as a character string expression
that corresponds to a valid device class name.

See the DVI$_DEVCLASS item in the $GETDVI system service for additional
information.

devtype

Specifies the device type for which F$DEVICE is to search. Specify the
devtype argument as a character string expression that
corresponds to a valid type name.

See the DVI$_DEVTYPE item in the $GETDVI system service for additional
information.

Note

Specifying a device type without specifying a device class will result
in an error.

stream-id

The search stream identification number is used to maintain separate
search contexts when you use the F$DEVICE function more than once and
when you supply different search criteria. If you use the F$DEVICE
function more than once in a command procedure and if you also use
different search criteria, specify stream-id arguments
to identify each search separately.

If the search criteria are changed in a call before the device name
list is exhausted, the context will be reinitialized and the search
will restart.

If you omit the stream-id argument, the F$DEVICE
function assumes an implicit single search stream. That is, the
F$DEVICE function starts searching at the beginning each time you
specify different search criteria.

Description

The F$DEVICE function allows you to search for devices that meet
certain search criteria by using the $DEVICE_SCAN system service.

The F$DEVICE function allows asterisk (*) and percent sign (%) wildcard
character searches based only on the device name; you must specify a
valid character string expression for the device class or device type.

You can use the F$DEVICE function in a loop in a command procedure to
return device names that match the specified selection criteria. Each
time the F$DEVICE function is executed, it returns the next device on
the system that matches the selection criteria. Note that devices are
returned in no particular order. After the last device name is
returned, the next F$DEVICE function returns a null string.

Note that you must maintain the context of the search string explicitly
(by specifying the stream-id argument) or implicitly
(by omitting the stream-id argument). In either case,
you must specify the same selection criteria each time you execute the
F$DEVICE system service with the same (explicit or implicit) stream.

Example

This command procedure displays the device names of all the RA60s on a
unit numbered 0.

Because no stream-id argument is specified, F$DEVICE
uses an implicit search stream. Each subsequent use of the F$DEVICE
function uses the same search criteria to return the next device name.
After the last device name is displayed, the F$DEVICE function returns
a null string and the procedure exits.