viFindRsrc

NI-VISA 15.0 Help

Edition Date: June 2015

Part Number: 370131S-01

»View Product Info

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, and GPIB1::1::1::INSTR.

GPIB[0-9]*::?*INSTR

Matches GPIB0::2::INSTR and GPIB1::1::1::INSTR.

GPIB[^0]::?*INSTR

Matches GPIB1::1::1::INSTR but not GPIB0::2::INSTR or GPIB12::8::INSTR.

VXI?*INSTR

Matches VXI0::1::INSTR.

?*VXI[0-9]*::?*INSTR

Matches 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.

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
{VI_ATTR_GPIB_SECONDARY_ADDR > 0 && VI_ATTR_GPIB_SECONDARY_ADDR < 10}

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 ==
0xFF6 && !(VI_ATTR_VXI_LA ==0 || VI_ATTR_SLOT <= 0)}

Find all VXI instrument resources having manufacturer ID FF6 and which are not logical address 0, slot 0, or external controllers.


Related Topics

viClose

viFindNext

VISA Resource Template

WAS THIS ARTICLE HELPFUL?

Not Helpful