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.
|
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)
| Valid Value | Description |
| "GPIB::22::INSTR" | GPIB board 0, primary address 22, no secondary address |
| "GPIB::22::5::INSTR" | GPIB board 0, primary address 22, secondary address 5 |
| "GPIB1::22::5::INSTR" | GPIB board 1, primary address 22, secondary address 5 |
| "VXI::64::INSTR" | VXI board 0, logical address 64 |
| "VXI1::64::INSTR" | VXI board 1, logical address 64 |
| "GPIB-VXI::64::INSTR" | GPIB-VXI board 0, logical address 64 |
| "GPIB-VXI1::64::INSTR" | GPIB-VXI board 1, logical address 64 |
| "ASRL2::INSTR" | COM port 2 |
| "SampleInstr" | Logical name "SampleInstr" |
| "Prefix" | Logical Name or Driver Session "Prefix" |
Using the optionsString Parameter
The following table lists the attributes and the name you use in the optionsString parameter to identify the attribute.
| Name in optionsString | Attribute Defined Constant |
| RangeCheck | PREFIX_ATTR_RANGE_CHECK |
| QueryInstrStatus | PREFIX_ATTR_QUERY_INSTRUMENT_STATUS |
| Cache | PREFIX_ATTR_CACHE |
| Simulate | PREFIX_ATTR_SIMULATE |
| RecordCoercions | PREFIX_ATTR_RECORD_COERCIONS |
| InterchangeCheck | PREFIX_ATTR_INTERCHANGE_CHECK |
| DriverSetup | PREFIX_ATTR_DRIVER_SETUP |
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:
| Attribute Name | Default Value |
| RangeCheck | VI_TRUE |
| QueryInstrStatus | VI_FALSE |
| Cache | VI_TRUE |
| Simulate | VI_FALSE |
| DriverSetup | VI_FALSE |
| InterchangeCheck | VI_FALSE |
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.