Prefix_InitWithOptions

ViStatus Prefix_InitWithOptions (ViRsrc resourceName, ViBoolean IDQuery, ViBoolean resetDevice, ViString optionsString, ViSession *instrumentHandle);

Purpose

This function performs the following initialization actions:

• Creates a new IVI instrument driver and optionally sets the initial state of the following session attributes:

  PREFIX_ATTR_INTERCHANGE_CHECK

  PREFIX_ATTR_RANGE_CHECK

  PREFIX_ATTR_QUERY_INSTRUMENT_STATUS

  PREFIX_ATTR_CACHE

  PREFIX_ATTR_SIMULATE

  PREFIX_ATTR_RECORD_COERCIONS

  PREFIX_ATTR_DRIVER_SETUP

• Opens a session to the specified device using the interface and address you specify for the Resource Name parameter.
• If the ID Query parameter is set to VI_TRUE, this function queries the instrument ID and checks that it is valid for this instrument driver.
• If the Reset parameter is set to VI_TRUE, this function resets the instrument to a known state.
• Sends initialization commands to set the instrument to the state necessary for the operation of the instrument driver.
• Returns a ViSession handle that you use to identify the instrument in all subsequent instrument driver function calls.

Note   This function creates a new session each time you invoke it. Although you can open more than one IVI session for the same resource, it is best not to do so. You can use the same session in multiple program threads. You can use the Prefix_LockSession and Prefix_UnlockSession functions to protect sections of code that require exclusive access to the resource.

Parameters

Name	Type	Description
resourceName	ViRsrc	Pass the resource name of the device to initialize. You can also pass the name of a driver session or logical name that you configure with the IVI Configuration utility. The driver session identifies a specific device and specifies the initial settings for the session. A logical Name identifies a particular driver session. Refer to the Parameter Discussion section for more information on resourceName.
IDQuery	ViBoolean	Specify whether you want the instrument driver to perform an ID Query. Valid Range: VI_TRUE (1)—Perform ID Query (Default Value) VI_FALSE (0)—Skip ID Query When you set this parameter to VI_TRUE, the driver verifies that the instrument you initialize is a type that this driver supports. Circumstances can arise where it is undesirable to send an ID Query command string to the instrument. When you set this parameter to VI_FALSE, the function initializes the instrument without performing an ID Query.
resetDevice	ViBoolean	Specify whether you want the to reset the instrument during the initialization procedure. Valid Range: VI_TRUE (1)—Reset Device (Default Value) VI_FALSE (0)—Don't Reset
optionsString	ViString	You can use this control to set the initial value of certain attributes for the session. Refer to the Parameter Discussion for more information on optionsString.
instrument Handle	ViSession (passed by reference)	Returns a ViSession handle that you use to identify the instrument in all subsequent instrument driver function calls. Note    This function creates a new session each time you invoke it. This is useful if you have multiple physical instances of the same type of instrument. Note    Avoid creating multiple concurrent sessions to the same physical instrument. Although you can create more than one IVI session for the same resource, it is best not to do so. A better approach is to use the same IVI session in multiple execution threads. You can use functions Prefix_LockSession and Prefix_UnlockSession to protect sections of code that require exclusive access to the resource.

Parameter Discussion

Using the resourceName Parameter

Refer to the following table below for the exact grammar to use for the resourceName parameter. Optional fields are shown in square brackets ([]).

Syntax

GPIB[board]::<primary address>[::secondary address]::INSTR

VXI VXI[board]::VXI logical address[::INSTR]

GPIB-VXI GPIB-VXI[board][::GPIB-VXI primary address]

::VXI logical address[::INSTR]

Serial ASRL<port>::INSTR

<LogicalName>

Optional Field and Value

If you do not specify a value for an optional field, the following values are used:

board - 0

secondary address - none (31)

Using the optionsString Parameter

The following table lists the attributes and the name you use in the optionsString parameter to identify the attribute.

The format of this string is, "AttributeName=Value" where AttributeName is the name of the attribute and Value is the value to which the attribute will be set. To set multiple attributes, separate their assignments with a comma.

The session uses the values you specify in the optionsString parameter. If you pass a NULL or an empty string for the optionsString parameter, and you pass either a DriverSession or logicalName to the resourceName parameter, the session uses the values specified in the IVI Configuration file. If you do not specify an attribute value in either the optionsString parameter or in the IVI Configuration file, the default value for the attribute is used.

The default values for the attributes are shown below:

True: 1, True, or VI_TRUE

False: 0, False, or VI_FALSE

Default Value: "Simulate=0,RangeCheck=1,QueryInstrStatus=0,Cache=1"

Return Values

Contains the status code that the function call returns. IVI engine functions can return error and warning values from several sets of status codes. Some status codes are unique to the IVI engine. Other status codes are the same codes that VISA Library functions return. Still others are error or warning values that functions in specific instrument drivers return. Each set of status codes has its own numeric range.

Regardless of the source of the status code, 0 always indicates success, a positive value indicates a warning, and a negative value indicates an error.

Related Topic

IVI Status Codes