niScope_InitWithOptions

NI High-Speed Digitizers Help (NI-SCOPE)

Edition Date: January 2017

Part Number: 370592AB-01

View Product Info

DOWNLOAD (Windows Only)


NI-SCOPE (English | Japanese)

C Function Prototype

ViStatus niScope_InitWithOptions (ViRsrc resourceName, ViBoolean IDQuery, ViBoolean resetDevice, ViString optionString, ViSession* newVi);

Purpose

Performs the following initialization actions:

  • Creates a new IVI instrument driver and optionally sets the initial state of the following session properties: Range Check, Cache, Simulate, Record Value Coercions
  • Opens a session to the specified device using the interface and address you specify for the resourceName
  • Resets the digitizer to a known state if resetDevice is set to VI_TRUE
  • Queries the instrument ID and verifies that it is valid for this instrument driver if the IDQuery is set to VI_TRUE
  • Returns an instrument handle that you use to identify the instrument in all subsequent instrument driver function calls

Related topics:

Parameters

Input
Name Type Description
resourceName ViRsrc Specifies the resource name of the device to initialize

ExampleDevice TypeSyntax
1 Traditional NI-DAQ device DAQ::1 (1 = device number)
2 NI-DAQmx device myDAQmxDevice (myDAQmxDevice = device name)
3 NI-DAQmx device DAQ::myDAQmxDevice (myDAQmxDevice = device name)
4 NI-DAQmx device DAQ::2 (2 = device name)
5IVI logical name or IVI virtual name myLogicalName (myLogicalName = name)

For Traditional NI-DAQ devices, the syntax is DAQ::n, where n is the device number assigned by MAX, as shown in Example 1.

For NI-DAQmx devices, the syntax is just the device name specified in MAX, as shown in Example 2. Typical default names for NI-DAQmx devices in MAX are Dev1 or PXI1Slot1. You can rename an NI-DAQmx device by right-clicking on the name in MAX and entering a new name.

An alternate syntax for NI-DAQmx devices consists of DAQ::NI-DAQmx device name, as shown in Example 3. This naming convention allows for the use of an NI-DAQmx device in an application that was originally designed for a Traditional NI-DAQ device. For example, if the application expects DAQ::1, you can rename the NI-DAQmx device to 1 in MAX and pass in DAQ::1 for the resource name, as shown in Example 4.

If you use the DAQ::n syntax and an NI-DAQmx device name already exists with that same name, the NI-DAQmx device is matched first.

You can also pass in the name of an IVI logical name or an IVI virtual name configured with the IVI Configuration utility, as shown in Example 5. A logical name identifies a particular virtual instrument. A virtual name identifies a specific device and specifies the initial settings for the session.

Caution  Traditional NI-DAQ and NI-DAQmx device names are not case-sensitive. However, all IVI names, such as logical names, are case-sensitive. If you use logical names, driver session names, or virtual names in your program, you must make sure that the name you use matches the name in the IVI Configuration Store file exactly, without any variations in the case of the characters.
idQuery ViBoolean Specify whether to perform an ID query.

When you set this parameter to VI_TRUE, NI-SCOPE verifies that the device you initialize is a type that it supports.

When you set this parameter to VI_FALSE, the function initializes the device without performing an ID query.

Defined Values

VI_TRUE—Perform ID query
VI_FALSE—Skip ID query

Default Value: VI_TRUE

resetDevice ViBoolean Specify whether to reset the device during the initialization process.
Note  For the NI 5112, repeatedly resetting the device may cause excessive wear on the electromechanical relays. Refer to NI 5112 Electromechanical Relays for recommended programming practices.

Default Value: VI_TRUE

Defined Values

VI_TRUE (1)—Reset device

VI_FALSE (0)—Do not reset device

optionString Specifies initialization commands. The following table lists the attributes and the name you use in the optionString to identify the attribute.

Attribute Name Attribute Values
RangeCheck - NISCOPE_ATTR_RANGE_CHECK VI_TRUE, VI_FALSE
QueryInstrStatus - NISCOPE_QUERY_INSTRUMENT_STATUS VI_TRUE, VI_FALSE
Cache - NISCOPE_ATTR_CACHE VI_TRUE, VI_FALSE
Simulate - NISCOPE_ATTR_SIMULATE VI_TRUE, VI_FALSE

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

You can use the option string to simulate a device. The DriverSetup flag specifies the model that is to be simulated and the type of the model. One example to simulate an NI PXI-5102 would be as follows:

Option String: Simulate = 1, DriverSetup = Model:5102; BoardType:PXI

Refer to the example niScope EX Simulated Acquisition for more information on simulation.

You can also use the option string to attach an accessory such as the NI 5900 to your digitizer session to allow the seamless use of the accessory:

Option String: DriverSetup = Accessory:Dev1

Refer to the example niScope EX External Amplifier for more information.

Output
Name Type Description
vi ViSession* Returns a session handle that you can use to identify the device in all subsequent NI-SCOPE function calls.

Return Value

Name Type Description
Status ViStatus Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows:

Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

WAS THIS ARTICLE HELPFUL?

Not Helpful