NI SCOPE Setup Functions
ViStatus niScope_init (ViRsrc resourceName, ViBoolean IDQuery, ViBoolean resetDevice, ViSession* vi);
Performs the following initialization actions:
- Creates a new IVI instrument driver session
- Opens a session to the specific driver using the interface and address (devices) you specify in the resourceName
- Queries each instrument ID and checks that it is valid for NI-SCOPE
- Resets the digitizer(s) to a known state, if resetDevice is set to VI_TRUE
- Sends initialization commands to set the instrument(s) to the state necessary for the operation of the instrument driver
- Returns an instrument handle that you use to identify the instrument(s) in all subsequent instrument driver function calls
- NI-SCOPE Programming Flow
- NI-SCOPE Tutorial
| Input | ||
|---|---|---|
| Name | Type | Description |
| resourceName | ViRsrc | Specifies the device name assigned by Measurement & Automation Explorer (MAX) to an NI-SCOPE instrument, for example, PXI1Slot3, where PXI1Slot3 is an instrument resource name. This parameter accepts a comma-delimited list of strings in the form PXI1Slot3,PXI1Slot4, where PXI1Slot3 is one instrument resource name and PXI1Slot4 is another. |
| ! | Note You can only specify multiple instruments of identical model numbers, bus types, channel counts, and onboard memory sizes. The instruments must be in the same chassis. |
|---|
| Example # | Device Type | Syntax | Variable |
|---|---|---|---|
| 1 | NI-DAQmx device | myDAQmxDevice | (myDAQmxDevice = device name) |
| 2 | NI-DAQmx device | DAQ::myDAQmxDevice | (myDAQmxDevice = device name) |
| 3 | NI-DAQmx device | DAQ::2 | (2 = device name) |
| 4 | IVI logical name or IVI virtual name | myLogicalName | (myLogicalName = name) |
|
For NI-DAQmx devices, the syntax is just the device name specified in MAX, as shown in Example 1. 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 2. 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 3. 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 4. A logical name identifies a particular virtual instrument. A virtual name identifies a specific device and specifies the initial settings for the session. |
|---|
 |
Note 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 Default Value: VI_TRUE |
| resetDevice | ViBoolean |
Specify whether to reset the device during the initialization process. Defined Values VI_TRUE—Reset device Default Value: VI_TRUE |
| 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. |
| 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 |
ViStatus niScope_InitWithOptions (ViRsrc resourceName, ViBoolean IDQuery, ViBoolean resetDevice, ViString optionString, ViSession* newVi);
Performs the following initialization actions:
- Creates a new IVI instrument driver session and optionally sets the initial state of the following session properties: Range Check, Cache, Simulate, Record Value Coercions
- Opens a session to the device(s) specified using the interface and address you use for the resourceName
- Queries each instrument ID and verifies that it is valid for this instrument driver
- Resets the digitizer(s) to a known state if resetDevice is set to VI_TRUE
- Returns an instrument handle that you use to identify the instrument(s) in all subsequent instrument driver function calls
- NI-SCOPE Programming Flow
| Input | ||
|---|---|---|
| Name | Type | Description |
| resourceName | ViRsrc | Specifies the device name assigned by Measurement & Automation Explorer (MAX) to an NI-SCOPE instrument, for example, PXI1Slot3, where PXI1Slot3 is an instrument resource name. This parameter accepts a comma-delimited list of strings in the form PXI1Slot3,PXI1Slot4, where PXI1Slot3 is one instrument resource name and PXI1Slot4 is another. |
|
Note You can only specify multiple instruments of identical model numbers, bus types, channel counts, and onboard memory sizes. The instruments must be in the same chassis. |
|---|
| Example # | Device Type | Syntax | Variable |
|---|---|---|---|
| 1 | NI-DAQmx device | myDAQmxDevice | (myDAQmxDevice = device name) |
| 2 | NI-DAQmx device | DAQ::myDAQmxDevice | (myDAQmxDevice = device name) |
| 3 | NI-DAQmx device | DAQ::2 | (2 = device name) |
| 4 | IVI logical name or IVI virtual name | myLogicalName | (myLogicalName = name) |
|
For NI-DAQmx devices, the syntax is just the device name specified in MAX, as shown in Example 1. 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 2. 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 3. 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 4. A logical name identifies a particular virtual instrument. A virtual name identifies a specific device and specifies the initial settings for the session. |
|---|
|
Note 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 Default Value: VI_TRUE |
| resetDevice | ViBoolean |
Specify whether to reset the device during the initialization process. 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 a PXI-5105 would be as follows: Option String: Simulate = 1, DriverSetup = Model:5105; 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 PXI-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. |
| 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 |
ViStatus niScope_close (ViSession vi);
When you are finished using an instrument driver session, you must call this function to perform the following actions:
- Closes the instrument I/O session.
- Destroys the IVI session and all of its attributes.
- Deallocates any memory resources used by the IVI session.
- NI-SCOPE Programming Flow
| Input | ||
|---|---|---|
| Name | Type | Description |
| vi | ViSession | The instrument handle you obtain from niScope_init that identifies a particular instrument session. |
| 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 |
ViStatus niScope_LockSession (ViSession vi, ViBoolean* callerHasLock);
Obtains a multithread lock on the instrument session. Before doing so, it waits until all other execution threads have released their locks on the instrument session. Other threads might have obtained a lock on this session in the following ways:
- Your application called niScope_LockSession
- A call to the instrument driver locked the session
- A call to the IVI engine locked the session
After your call to niScope_LockSession returns successfully, no other threads can access the instrument session until you call niScope_UnlockSession. Use niScope_LockSession and niScope_UnlockSession around a sequence of calls to instrument driver functions if you require that the instrument retain its settings through the end of the sequence.
You can safely make nested calls to niScope_LockSession within the same thread. To completely unlock the session, you must balance each call to niScope_LockSession with a call to niScope_UnlockSession. If, however, you use the callerHasLock in all calls to niScope_LockSession and niScope_UnlockSession within a function, the IVI Library locks the session only once within the function regardless of the number of calls you make to niScope_LockSession. This allows you to call niScope_UnlockSession just once at the end of the function.
| Input | ||
|---|---|---|
| Name | Type | Description |
| vi | ViSession | The instrument handle you obtain from niScope_init that identifies a particular instrument session. |
| Output | ||
| Name | Type | Description |
| callerHasLock | ViBoolean* |
This parameter serves as a convenience. If you do not want to use this parameter, pass VI_NULL. Use this parameter in complex functions to keep track of whether you have obtained a lock and therefore need to unlock the session. Pass the address of a local ViBoolean variable. In the declaration of the local variable, initialize it to VI_FALSE. Pass the address of the same local variable to any other calls you make to niScope_LockSession or niScope_UnlockSession in the same function. |
| 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 |
ViStatus niScope_UnlockSession (ViSession vi, ViBoolean* callerHasLock);
Releases a lock that you acquired on an instrument session using niScope LockSession.
| Input | ||
|---|---|---|
| Name | Type | Description |
| vi | ViSession | The instrument handle you obtain from niScope_init that identifies a particular instrument session. |
| Output | ||
| Name | Type | Description |
| callerHasLock | ViBoolean* |
This parameter serves as a convenience; if you do not want to use this parameter, pass VI_NULL. Use this parameter in complex functions to keep track of whether you have obtained a lock and therefore need to unlock the session; pass the address of a local ViBoolean variable; in the declaration of the local variable, initialize it to VI_FALSE; pass the address of the same local variable to any other calls you make to niScope_LockSession or niScope_UnlockSession in the same function. |
| 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 |