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

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

A positive integer representing the search stream identification number.

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

$ START: 
$     DEVICE_NAME = F$DEVICE("*0:","DISK","RA60") 
$     IF DEVICE_NAME .EQS. "" THEN EXIT 
$     SHOW SYMBOL DEVICE_NAME 
$     GOTO START 
      

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.