viFindRsrc

Syntax

viFindRsrc(ViSession sesn, ViString expr, ViPFindList findList, ViPUInt32 retcnt, ViPRsrc instrDesc);

Description

This function queries a VISA system to locate the resources associated with a specified interface. This function matches the value specified in the expr parameter with the resources available for a particular interface. On successful completion, it returns the first resource found in the list and returns a count to indicate if there were more resources found that match the value specified in the expr parameter.

Note: If you use the Agilent Connection Expert to put a resource into the ignored state, viFindRsrc and viFindNext will not find that resource. If an interface is in the ignored state, viFindRsrc and viFindNext will find neither the interface nor instruments on that interface.

Connection Expert's Address check property on an instrument also affects the operation of viFindRsrc and viFindNext for that instrument. Click here for more information on this interaction.

This function also returns 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.

The search criteria specified in the expr parameter have 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.

The optional attribute expression allows construction of expressions with the use of logical ANDs, ORs and NOTs. Equal (==) and unequal (!=) comparators can be used compare attributes of any type. In addition, other inequality comparators (>, <, >=, <=) can be used to compare attributes of numeric type. Only global attributes can be used in the attribute expression.

The syntax of expr is defined as follows. The grouping operator () in a logical expression has the highest precedence, The not operator ! in a logical expression has the next highest precedence after the grouping operator, and the or operator || in a logical expression has the lowest precedence.

Special Character	Meaning
&&	Logical AND
||	Logical OR
!	Logical negation (NOT)
()	Parentheses

 

expr :=	regularExpr ['{' attrExpr '}']
attrExpr :=	attrTerm | attrExpr '||' attrTerm
attrTerm :=	attrFactor | attrTerm '&&' attrFactor
attrFactor :=	'(' attrExpr ')' | '!' attrFactor | relationExpr
relationExpr :=	attributeId compareOp numValue | attributeId equalityOp stringValue
compareOp :=	'==' | '!=' | '>' | '<' | '>=' | '<='
equalityOp :=	'==' | '!='
attributeId :=	character (character|digit|underscore)*
numValue :=	digit+ |'-' digit+ |'0x' hex_digit+ | '0X' hex_digit+
stringValue :=	'"' character* '"'

Some examples are:

Expr	Meaning
GPIB[0-9]*::?*::?*::INSTR {VI_ATTR_GPIB_SECONDARY_ADDR > 0}	Find all GPIB devices that have secondary addresses greater than 0.
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 whose manufacturer ID is FF6 and who are not logical address 0, slot 0, or external controllers.

Local attributes are not allowed in the logical expression part of the expr parameter to the viFindRsrc operation. viFindRsrc uses a case-insensitive compare function when matching resource names against the regular expression specified in expr.

If the value VI_NULL is specified in the findList parameter of viFindRsrc and the return value is successful, VISA automatically invokes viClose on the find list handle rather than returning it to the application.

The findList and retCnt parameters to the viFindRsrc operation are optional. They can be used if only the first match is important and the number of matches is not needed. Calling viFindRsrc with "VXI?*INSTR" will return the same resources as invoking it with "vxi?*instr".

All resource strings returned by viFindRsrc must be recognized by viParseRsrc, viParseRsrcEx, and viOpen. However, not all resource strings that can be parsed or opened have to be findable.

Parameters

Name	Dir	Type	Description
sesn	IN	ViSession	Resource Manager session (should always be the Default Resource Manager for VISA returned from viOpenDefaultRM).
expr	IN	ViString	This expression sets the criteria to search an interface or all interfaces for existing devices. (See the following table for description string format.)
findList	OUT	ViPFindList	Returns a handle identifying this search session. This handle will be used as an input in viFindNext.
retcnt	OUT	ViPUInt32	Number of matches.
instrDesc	OUT	ViPRsrc	Returns a string identifying the location of a device. Strings can then be passed to viOpen to establish a session to the given device.
Description String for expr Parameter
Interface			Expression
GPIB			GPIB[0-9]*::?*INSTR
PXI			PXI?*INSTR
VXI			VXI?*INSTR
GPIB-VXI			GPIB-VXI?*INSTR
GPIB and GPIB-VXI			GPIB?*INSTR
All VXI			?*VXI[0-9]*::?*INSTR
ASRL			ASRL[0-9]*::?*INSTR
All			?*INSTR
Special Values for findList Parameter
Value			Action Description
VI_NULL			Do not return a find list handle.
Special Values for retcnt Parameter
Value			Action Description
VI_NULL			Do not return the number of matches.

Return Values

Type ViStatus	This is the function return status. It returns either a completion code or an error code as follows.
Completion Code	Description
VI_SUCCESS	Resource(s) found.
Error Codes	Description
VI_ERROR_INV_EXPR	Invalid expression specified for search.
VI_ERROR_INV_SESSION VI_ERROR_INV_OBJECT	The given session or object reference is invalid (both are the same value).
VI_ERROR_NSUP_OPER	The given sesn does not support this function.
VI_ERROR_RSRC_NFOUND	Specified expression does not match any devices.

See Also

viFindNext, viClose
Address Check, viFindRsrc, and viOpen