User manual

Programmer’s Guide Page 17 of 66
3. Programming an Acqiris Instrument
3.1. Programming Hints
When programming an Acqiris instrument it is important to remember that the Acqiris driver must be freshly loaded
(this is usually automatic) by any process that uses the modules. This means that each process starts over with a
completely clean view of the system and no knowledge of any previously determined calibration constants or
settings. Thus a calibration ought to be done, or loaded, before the modules are used for any acquisitions. Of course
the system may have to be recalibrated later if the temperature of the modules is changing. Users cannot expect to
control Acqiris modules with a succession of process invocations with each one executing a single command.
The Agilent Acqiris AqDrv device driver is thread-safe, i.e. its API can be called simultaneously from multiple
threads. All of the driver functions are reentrant. The thread safety is guaranteed by using instrument-based mutual
exclusion for functions taking an instrument handle as input parameter, and a global lock for the other functions. This
means that access to a given instrument is serialized using a lock, ensuring that only one thread reads from or writes
to that instrument (and associated variables) at any time. However, calls to functions to discover, initialize or close
instruments, while the instrument(s) are still in use in other threads, should be avoided to prevent errors due to
concurrent attempts to obtain the global lock. Finally, remember that even though the driver is thread-safe, great care
is always required when designing applications using multiple threads to avoid problems such as race conditions or
starvation.
Be sure to read the comments on the functions and their parameters in chapter 2, DEVICE DRIVER FUNCTION
REFERENCE of the Programmer's Reference Manual. Another valuable source is the header files:
AcqirisInterface.h, AcqirisD1Interface.h, or AcqirisT3Interface.h for C-like environments, or the equivalent .bas
or .vb files for Visual Basic.
The examples below do not check the return value of the Acqrs_… functions. In real applications, you should
always check the return values of functions.
3.2. Device Initialization
Before any (real or simulated) device can be used, each device must be initialized with a separate call to the function
Acqrs_InitWithOptions. For real devices, you can also use the slightly simpler function Acqrs_init. Both functions
return the instrumentID (whose value will be different for each device), which must be subsequently used in any
other function call. The arguments IDQuery and resetDevice are currently ignored. The use of the string arguments
resourceName and optionsString are explained with the initialization scenarios in the following sections.
If you use modules that are connected via AS bus, you need to configure them as MultiInstruments. This lets you
treat them as normal instruments with an increased number of channels. E.g. you can connect 3 DC270‟s to form a
single 12-channel, 1 GS/s digitizer.
If needed, and before initializing the devices, a call to either
Acqrs_getNbrInstruments can be used to learn how many instruments have been found. However, a side-
effect of this call will be to select the use of single instruments. This can be manually circumvented as
discussed below.
or
AcqrsD1_multiInstrumentAutoDefine can be used to automatically combine as MultiInstruments modules
that are connected via AS bus and return the total number of instruments found, including individual
modules without AS bus connections. It automatically searches for all sets of modules that are connected
with AS bus, and configures each such block as a single MultiInstrument.
As an alternative to automatic MultiInstrument definition, you can initialize each module individually with the
function Acqrs_InitWithOptions, and then combine some of them with the function AcqrsD1_multiInstrDefine.
This method provides better control over which modules are combined and in what order, at the expense of careful
book keeping of which instrumentID‟s are available. For details, please refer to the section 3.2.8, Manual Definition
of MultiInstruments.
NOTE: Slow instrument detection may occur on systems with a VISA installation. To skip the VISA detection, you
may edit the "AqDrv4.ini" file and manually add the string below. Note that VXI instruments use VISA, and that this
procedure can therefore not be used. The "AqDrv4.ini" file will be searched in the directory pointed to by the
environment variable "AcqirisDxDir".
DDRMANAGER_NO_VISA = 1