viFindRsrc
Purpose
Queries a VISA system to locate the resources associated with a specified interface.
C Syntax
ViStatus viFindRsrc(ViSession sesn, ViString expr, ViPFindList findList, ViPUInt32 retcnt, ViChar instrDesc[])
Visual Basic Syntax
viFindRsrc&(ByVal sesn&, ByVal expr$, findList&, retcnt&, ByVal instrDesc$)
Resource Classes
VISA Resource Manager
Parameters
| Name | Direction | Description |
|---|---|---|
|
sesn |
IN |
Resource Manager session (should always be the session returned from viOpenDefaultRM()). |
|
expr |
IN |
This is a regular expression followed by an optional logical expression. Refer to the discussion of the Description String in the Description section of this operation. |
|
findList |
OUT |
Returns a handle identifying this search session. This handle will be used as an input in viFindNext(). |
|
retcnt |
OUT |
Number of matches. |
|
instrDesc |
OUT |
Returns a string identifying the location of a device. Strings can then be passed to viOpen() to establish a session to the given device. |
Return Values
| Completion Codes | Description |
|---|---|
|
VI_SUCCESS |
Resource(s) found. |
| Error Codes | Description |
|---|---|
|
VI_ERROR_INV_OBJECT |
The given session reference is invalid. |
|
VI_ERROR_NSUP_OPER |
The given sesn does not support this operation. This operation is supported only by a Resource Manager session. |
|
VI_ERROR_INV_EXPR |
Invalid expression specified for search. |
|
VI_ERROR_RSRC_NFOUND |
Specified expression does not match any devices. |
Description
The viFindRsrc() operation matches the value specified in the expr parameter with the resources available for a particular interface. A regular expression is a string consisting of ordinary characters as well as special characters. You use a regular expression to specify patterns to match in a given string; in other words, it is a search criterion. The viFindRsrc() operation uses a case-insensitive compare feature when matching resource names against the regular expression specified in expr. For example, calling viFindRsrc() with "VXI?*INSTR" would return the same resources as invoking it with "vxi?*instr".
On successful completion, this function returns the first resource found (instrDesc) and returns a count (retcnt) to indicate if there were more resources found for the designated interface. This function also returns, in the findList parameter, a handle to a find list. This handle points to the list of resources and it must be used as an input to viFindNext(). When this handle is no longer needed, it should be passed to viClose(). Notice that retcnt and findList are optional parameters. This is useful if only the first match is important, and the number of matches is not needed. If you specify VI_NULL in the findList parameter and the operation completes successfully, VISA automatically invokes viClose() on the find list handle rather than returning it to the application.
 |
Note The size of the instrDesc parameter should be at least 256 bytes. |
|
Note All resource strings returned by viFindRsrc() will always be recognized by viOpen(). However, viFindRsrc() will not necessarily return all strings that you can pass to viParseRsrc() or viOpen(). This is especially true for network and TCPIP resources. If a resource does not appear in the list, you can explicitly add it in the NI-VISA configuration utility (MAX on Windows, visaconf on UNIX), and then viFindRsrc() will return it. The configuration utility also has other options that expand or limit the set of resources that viFindRsrc() returns. |
The search criteria specified in the expr parameter has two parts: a regular expression over a resource string, and an optional logical expression over attribute values. The regular expression is matched against the resource strings of resources known to the VISA Resource Manager. If the resource string matches the regular expression, the attribute values of the resource are then matched against the expression over attribute values. If the match is successful, the resource has met the search criteria and gets added to the list of resources found.
| Special Characters and Operators |
Meaning |
|---|---|
|
? |
Matches any one character. |
|
\ |
Makes the character that follows it an ordinary character instead of special character. For example, when a question mark follows a backslash (\?), it matches the ? character instead of any one character. |
|
[list] |
Matches any one character from the enclosed list. You can use a hyphen to match a range of characters. |
|
[^list] |
Matches any character not in the enclosed list. You can use a hyphen to match a range of characters. |
|
* |
Matches 0 or more occurrences of the preceding character or expression. |
|
+ |
Matches 1 or more occurrences of the preceding character or expression. |
|
Exp|exp |
Matches either the preceding or following expression. The or operator | matches the entire expression that precedes or follows it and not just the character that precedes or follows it. For example, VXI|GPIB means (VXI)|(GPIB), not VX(I|G)PIB. |
|
(exp) |
Grouping characters or expressions. |
| Regular Expression | Sample Matches |
|---|---|
|
GPIB?*INSTR |
Matches GPIB0::2::INSTR, GPIB1::1::1::INSTR, and GPIB-VXI1::8::INSTR. |
|
GPIB[0-9]*::?*INSTR |
Matches GPIB0::2::INSTR and GPIB1::1::1::INSTR but not GPIB-VXI1::8::INSTR. |
|
GPIB[^0]::?*INSTR |
Matches GPIB1::1::1::INSTR but not GPIB0::2::INSTR or GPIB12::8::INSTR. |
|
VXI?*INSTR |
Matches VXI0::1::INSTR but not GPIB-VXI0::1::INSTR. |
|
GPIB-VXI?*INSTR |
Matches GPIB-VXI0::1::INSTR but not VXI0::1::INSTR. |
|
?*VXI[0-9]*::?*INSTR |
Matches VXI0::1::INSTR and GPIB-VXI0::1::INSTR. |
|
ASRL[0-9]*::?*INSTR |
Matches ASRL1::INSTR but not VXI0::5::INSTR. |
|
ASRL1+::INSTR |
Matches ASRL1::INSTR and ASRL11::INSTR but not ASRL2::INSTR. |
|
(GPIB|VXI)?*INSTR |
Matches GPIB1::5::INSTR and VXI0::3::INSTR but not ASRL2::INSTR. |
|
(GPIB0|VXI0)::1::INSTR |
Matches GPIB0::1::INSTR and VXI0::1::INSTR. |
|
?*INSTR |
Matches all INSTR (device) resources. |
|
?*VXI[0-9]*::?*MEMACC |
Matches VXI0::MEMACC and GPIB-VXI1::MEMACC. |
|
VXI0::?* |
Matches VXI0::1::INSTR, VXI0::2::INSTR, and VXI0::MEMACC. |
|
?* |
Matches all resources. |
|
visa://hostname/?* |
Matches all resources on the specified remote system. The hostname can be represented as either an IP address (dot-notation) or network machine name. This remote system need not be a configured remote system. |
|
/?* |
Matches all resources on the local machine. Configured remote systems are not queried. |
|
visa:/ASRL?*INSTR |
Matches all ASRL resources on the local machine and returns them in URL format (for example, visa:/ASRL1::INSTR). |
You can use the NI-VISA configuration utility (MAX on Windows, visaconf on UNIX) to access certain NI-VISA servers by default. All expressions without the preceding "/" will be matched with resources on the configured remote systems.
By using the optional attribute expression, you can construct flexible and powerful expressions with the use of logical ANDs (&&), ORs(||), and NOTs (!). You can use equal (==) and unequal (!=) comparators to compare attributes of any type, and other inequality comparators (>, <, >=, <=) to compare attributes of numeric type. Use only global attributes in the attribute expression. Local attributes are not allowed in the logical expression part of the expr parameter.
| Expr Parameter | Meaning |
|---|---|
|
GPIB[0-9]*::?*::?*::INSTR |
Find all GPIB devices that have secondary addresses from 1 to 9. |
|
ASRL?*INSTR{VI_ATTR_ASRL_BAUD == 9600} |
Find all serial ports configured at 9600 baud. |
|
?*VXI?INSTR{VI_ATTR_MANF_ID == |
Find all VXI instrument resources having manufacturer ID FF6 and which are not logical address 0, slot 0, or external controllers. |
Related Topics