ADLIB WIN is a set of sophisticated, high level, dynamically linked library (DLL) data acquisition
subroutines for programmers involved in the developing of process and/or data acquisition applications.
The functions supplied with ADLIB provide an easy to use interface to ADAC PCI series data acquisition
products, shielding the programmer from both the complexity of low level DAQ board programming and
the complicated DMA and interrupt handling mechanisms of the Windows environment. ADLIB supports
DMA and Software Polled data transfer methods for acquiring data on the ADAC PCI series cards.
ADLIB WIN removes the complex task of allocating suitable DMA, and Interrupt buffers by automatically
allocating buffer(s) when a DAQ board’s subsystem is initialized. The application programmer can then
retrieve a pointer to buffer and/or set up a windows message handler or CALLBACK routine that will be
called when each buffer has been completed. ADLIB allows N buffers of size M for each or the DAQ
board's logical devices and the only limitation on quantity and size of the buffer(s) is the amount of
available system memory.
ADLIB WIN buffer pointers are not just pointers to a DAQ board's subsystem data, they point to a
structure that contains the buffer type, size, linear data address, physical data address, current sample
count, hardware trigger points, completion flags, status flags and error flags.
ADLIB WIN provides support for an unlimited number of DAQ boards, the only restrictions being
available memory.
ADLIB WIN provides a multitasking environment through which multiple logical devices can run
concurrent and report directly back to the user application when the requested ADLIB service has
completed. ADLIB services can be either a single cycle or continuous cycle operation.
ADLIB WIN provides extensive error reporting through each library call and buffer structure. In addition,
ADLIB employs error control functions that can enable or disable certain types of error conditions.
The ADLIB WIN Series of drivers consists of the following:
ADLIB WDM – used with the ADAC PCI series of DAQ boards for Windows 98/ME/2000;
based on Microsoft’s Windows Driver Model, also includes support for ADAC PCI Series boards
for Windows NT 4.0.
Chapter 1 Introduction
1-2
1.2 SYSTEM REQUIREMENTS
ADLIB WIN runs on the IBM family of personal computers. Specifically IBM PC 486/Pentium and
compatibles. Minimum system requirements are:
• Microsoft Windows 98SE/ME/2000 or Windows NT 4.00
• One CD drive.
• One fixed disk drive.
It is recommended that 256Mb of RAM be available.
1.3 APPLICATION LANGUAGE REQUIREMENTS
The ADLIB-WIN API interface is provided through the Windows dynamic link library (DLL) interface
specification. Example programs are provided for each independent language, with various acquisition
methods demonstrated.
Languages supported are:
Microsoft Windows Languages
Visual Basic 32 bit
Visual C/C++ 32 bit
Chapter 3 Configuration, Capabilities and Initialization Files
2-1
2. INSTALLATION
2.1 INSTALLATION FROM WINDOWS for PCI CARD SUPPORT
If you are installing ADLIB WDM for a PCI based product, follow the installation instructions on the CD
provided with the PCI board.
If you are using ADLIB WDM with Windows NT 4.0, you must do the following:
1. Manually copy the “aPcixx.sys” file from the ADAC CD’s NT4 directory to your
\WinNT\system32\drivers directory.
2. From the ADAC CD’s NT4 directory, run the “aPci55xx.reg” file by double clicking on it, this will
update your registry to look for ADAC PCI boards.
3. Reboot your PC to load the ADAC drivers.
Chapter 3 Configuration, Capabilities and Initialization Files
2-2
2.2 SUMMARY OF DISK FILES FOR ADLIB WDM PCI CARD SUPPORT
\adlib (Root Directory)
license.txt
\alWdm
readme.txt
\alWdm\msc
adlerr.h ADLIB core error codes.
adlib.h ADLIB include file.
drverr.h ADLIB driver specific error codes.
adlcore.lib ADLIB import library.
\alWdm\vbasic
adlerr.bas ADLIB core error codes.
adlib.bas ADLIB include file.
drverr.bas ADLIB driver specific error codes.
\alWdm\drivers\ BOARD_TYPE
These directories contain the board specific drivers (*.dll) and capabilities (*.cap) file(s).
\alWdm\drivers\BOARD_TYPE\examples\msc
\Adlai01 examines the BUFFER_DONE message response handler
\Adlai02 examines the User polling of the BUFFER_DONE flag.
\Adlai04 examines the ABOUT Trigger mode.
\Adlai05 examines the BURST/SCAN MODE option.
\Adlai07 examines the Software Transfer method.
\Adlai08 examines the CALLBACK buffer response handler (MSC only).
\Adlda01 examines the Software Transfer method.
\Adlda02 examines the Single DAC BUFFER_DONE message response handler
\Adlda03 examines the Dual DAC BUFFER_DONE message response handlers
\Adldio01 examines the Software Transfer Digital Input/Output ports 0 & 1.
\Adldio23 examines the Software Transfer Digital Input/Output ports 2 & 3.
\Adlctr01 examines the Counter IN and Counter OUT functions.
\alWdm\drivers\ BOARD_TYPE \examples\vbasic
\Adlai01.frm examines the BUFFER_DONE message response handler
\Adlai02.frm examines the User polling of the BUFFER_DONE flag.
\Adlai04.frm examines the ABOUT Trigger mode.
\Adlai05.frm examines the BURST/SCAN MODE option.
\Adlai07.frm examines the Software Transfer method.
\Adlai08.frm examines the CALLBACK buffer response handler (MSC only).
\Adlda01.frm examines the Analog Output function.
\Adlda02.frm examines the Single DAC BUFFER_DONE message response handler
\Adlda03.frm examines the Dual DAC BUFFER_DONE message response handlers
\Adldio01.frm examines the Software Transfer Digital Input/Output ports 0 & 1
\Adldio23.frm examines the Software Transfer Digital Input/Output ports 2 & 3
\Adlctr01.frm examines the Counter IN and Counter OUT functions.
Chapter 3 Configuration, Capabilities and Initialization Files
3-3
3. CONFIGURATION, CAPABILITIES AND INITIALIZATION FILES
Beginning with ADLIB version 3.00, a configuration utility program ADACCONFIG.EXE is provided to
setup and configure your ADLIB boards within the PC. The utility provides all the necessary information to
create both the Configuration (.CON) and Initialization (.INI) files. The following sections provide the
necessary detailed information on the .con and .ini files for manual configuration on these files and are not
required reading when using the ADACCONFIG utility. The ADACCONFIG.EXE is located in your main
ADLIB directory or form the programs menu group chosen when ADLIB was installed.
3.1 CONFIGURATION (.CON) FILE
A Configuration file contains settings that apply for all applications running in the environment using the
ADLIB WIN Library. There is only one Configuration file per system. This file contains “static” systemwide configuration information about all the boards and drivers installed in the system. This file is read
when the environment is loaded by the user's application. The Configuration file has a .CON filename
extension.
Contents of the Configuration file include:
• The environment specific string name.
• An assigned DAQ board designator number for each installed board (this is the board’s “ID number”).
• The board specific string name.
• I/O or memory base address of each board.
• Path and filename of the capabilities file for each DAQ board (from the capabilities file, ADLIB WIN
knows the type of the board, and everything else about it).
• Path to directory containing board driver, for each unique type of board (the capabilities file specifies
the name of the file, but not the path).
• All available device subsections supported by each DAQ board.
3.2 CAPABILITIES (.CAP) FILE
A Capabilities file contains all the possible programmable options for each ADLIB function call for a
particular DAQ board. There is one Capabilities file per unique DAQ board, ADLIB uses this information
to validate all application program function call parameters, and when initializing a logical device fro m the
initialization file described below. The Capabilities file has a .CAP filename extension.
Contents include:
• Device capabilities: what features and options the DAQ board supports
• How the board's subsections are divided up into logical hardware devices (such as ADC0, DAC0,
DAC1, DOT0, DIN3, CTR0, etc.)
3.3 INITIALIZATION (.INI) FILE
The initialization file specifies how the programmable features of boards and logical devices are to be
initialized during the ADLIB device initialization function call. There is only one .INI file per application,
and the name and location is specified in the .CON file. This file is read durin g the allocation of a logical
device.
The initialization file reduces the amount of user programming required by initially setting the ADLIB
logical device subsystem database (LDSD) to the desired user application defaults. This feature allows only
the bare minimum amount of ADLIB calls to start a logical device. The Initialization file has an .INI
filename extension.
Chapter 3 Configuration, Capabilities and Initialization Files
3-4
Contents include:
One or more named sections, each corresponding to a Logical Device, including information for data
transfer method, number of channels enabled, channel gain settings, sampling mode, sampling rate,
notification method, and logical device option information.
If an .INI parameter is not specified, but the capabilities file indicated support for the option, the parameter
will default to the first option for that entry in the capabilities file.
Chapter 4 Application Development
4-1
4. APPLICATION DEVELOPMENT
4.1 OVERVIEW
The ADLIB WIN driver is an extensive set of both function and structure based library routines that provide
an easy to use, hardware independent, software interface to ADAC products. Developers are shielded from
the time consuming task of designing and interfacing to DAQ hardware in any environment. This allows the
programmer to spend less time in the development, design and coding of an application program.
4.2 OPERATING MODES
All ADLIB DAQ board acquisitions specify operation mode of the hardware and software. The modes
include the Software Cycles, Data Transfer and Notification Methods defined below.
Cycle Modes:
AL_SINGLE_CYCLE
AL_CONTINUOUS_CYCLE
Data Transfer Methods:
AL_DTM_SOFTWARE
When a FIFO is available, the driver collects all samples available in the
AL_DTM_DMA
See function AL_SetCycleMode(…)
In Single Cycle mode, after a device is started, it transfers a specified
number of samples between the device and one or more buffers in the
processor’s memory and then stops. After each buffer is filled, the
calling application program is “notified” that a transfer has completed.
In Continuous Cycle mode, after you start a device, it continues
transferring buffers in circular fashion. If you have more than one buffer
defined, it fills up the first, moves to the next, the next, etc., until it fills
the last one. Then the device “wraps around” and starts filling the first
buffer again. After each buffer is filled, the calling application program
is notified that a transfer has completed.
See function AL_SetDataTransferMethod(…)
The Software Transfer Methods assumes a hardware-clocking source is
selected.
FIFO each time the AL_GetDoneBufferPtr() function is called, returning
a pointer to the buffer only when it has filled with the specified number
of samples. It’s the applications responsibility to call the
AL_GetDoneBufferPtr() function in a timely manner, otherwise the
FIFO will overflow, generating an error condition. In this case a pointer
to the incomplete buffer will be returned with the appropriate error flags
set in the buffer structure itself.
The DMA Transfer Method is asynchronous, meaning the transfers
happen automatically in the background without software intervention
while the application program is doing something else. The application
program calls AL_GetDoneBufferPtr() function to determine if an input
buffer is ready for processing, or if an output buffer is ready to accept
new data.
Chapter 4 Application Development
4-2
Notification Methods:
AL_CHECK_BUFFER
See function AL_SetBufferDoneHandler(…)
This is a “synchronous” method where the application calls a
GetDoneBuffPtr() function to determine whether or not the buffer
transfer is complete. If any buffers have been completed, a pointer to the
first buffer completed is returned. The retrieval of buffers is always
done in a first completed, first returned order. Once the application has
processed the data in an input buffer, it must call a function to clear the
Buffer Done flag -- this tells the Library fun ctions that it is OK to reuse
the buffer. If the Library gets to the point where it needs to use the
buffer again, and the Buffer Done flag hasn’t cleared, the Library will
flag an error condition.
AL_POSTMESSAGE
This is an “asynchronous” method where the library sends a message to
the application when the buffer is done. The application sets up this
message handler function through the use of standard library routines.
That function would then process the data in the buffers. Again, the
application is responsible for clearing the Buffer Done flag as described
above. See below for Postmessage handler examples.
AL_POSTMESSAGE_PARAMS
This method is similar to the AL_POSTMESSAGE descrived above,
except that ADLIB calls the users message handler with the specified
lparam and wparam set by the AL_SetBufferDoneHandlerParams
function.
AL_CALLBACK
ADLIB calls a user defined “MSC CALLBACK” function per the
specified addrees per the AL_SetBufferDoneHandlerFunc. (MSC
Support Only)
C/C++ POSTMESSAGE HANDLER EXAMPLE
long OnBufferHandler(WPARAM wParam, LPARAM lParam)
{
float EngUnits[NUM_CHANNELS];
long lBuffNum;
/* Get the pointer to the buffer structure */
lpbuff = (LPBUFFSTRUCT)lParam;
/* the buffer number is wParam */
lBuffNum = wParam;
/* Check buffer status flags */
if (lpbuff->dwStatusFlags != BUFFER_FULL)
OnBufferError(lpbuff);
/* Convert to Eng. units */
AL_DemuxData(lhldAdc0, lpbuff, EngUnits, Buffersize);
/* Clear the buffer done flags */
AL_ClearBufferDoneFlag(lhldAdc0, lpbuff->dwBuffNum);
return(0);
}
Chapter 4 Application Development
4-3
Visual Basic for Windows Postmessage Handler Example
Global lpDataBuffStat As DATABUFFSTATUS
Global DataBuff(2048) As Integer
Global EngUnits(2048) As Single
Sub MsgBlaster1_Message (MsgVal As Integer, wParam As Integer, lParam As Long, ReturnVal As Long)
lBuffNum& = wParam
‘ Get the buffer status
errnum& = AL_GetBufferStatus(gblLhld&, lpDataBuffStat, DONE_BUFFER)
If errnum& < 0 Then End
' Check the status and error flags
If lpDataBuffStat.lStatusFlags <> BUFFER_FULL Then OnBufferError(lBuffNum&)
If lpDataBuffStat.lErrorFlags <> 0 Then OnBufferError(lBuffNum&)
errnum& = AL_CopyBuffer(gblLhld&, lBuffNum&, DataBuff(0), BufferStart, BufferEnd)
If errnum& < 0 Then End
errnum& = AL_DemuxDataSet(gblLhld&, lBuffNum&, EngUnits(0), BufferStart, BufferEnd)
If errnum& < 0 Then End
errnum& = AL_ClearBufferDoneFlag(gblLhld&, lBuffNum&)
If errnum& < 0 Then End
ReturnVal = 0
End Sub
4.3 LOGICAL DEVICES
The Interface Library defines a “Logical Device Subsystem” as being a software representation of a
functionally distinct subset of the hardware on a DAQ board. Each logical device deals with either Input or
Output data, but not both.
Typical Logical Devices on DAQ boards include:
• ADC section (with N channels).
• DAC section (with N channels).
• Digital Input section.
• Digital Output section.
• Counter/Timers
You can also allocate multiple Logical Devices for the same piece of hardware. Since a logical device is a
“software representation” of a subsection of a board, you can have more than one representation of the same
subsection of a board. In other words, you can assign more than one logical device to the same piece of
hardware.
It might be convenient, for example, to assign more than one logical device to an ADC subsection on a
board. Each logical device could be configured entirely differently (for things like channel/gain, sample rate,
buffer size, etc.) and an application program could switch between the two devices. To do this, the app
would have to separately allocate the logical devices, and do the “set” functions to configure each device.
Then, the first device would be initialized and started. To switch to an other logical device attached to the
same physical hardware, the app would stop the running device and initialize and start another.
Chapter 5 Program Development
5-1
5. PROGRAM DEVELOPMENT
5.1 INCLUDING ADLIB WIN IN C\C++
The sections presented below describe the mechanics of incorporating the ADLIB WIN library in a
Windows based application program. To add the ADLIB library into the Windows Application
Programming Interface (API) requires the inclusion of the following header files in your program.
1. “adlib.h” ADLIB API
2. “adlerr.h” ADLIB error codes
3. “drverr.h” ADLIB hardware generic error codes
5.1.1 Steps To Programming In C\C++
LHLD lhldAdc0; /* Define a handle variable for the ADC device. */
LPBUFFSTRUCT lpbuff; /* Define a pointer to an ADLIB data buffer structure */
ERRNUM errnum; /* Define an error number variable. */
/* Load and initialize the environment. */
errnum = AL_LoadEnvironment(“c:\adlib\alwdm\Pci55mfhr\examples\pci55xx\msc\adlai01\adlib.con”);
/* Allocate the ADC0 subsystem on board number 0. Reads in the current */
/* Loads the initialization file (.INI) and sets the LDSD as defined. */
lhldAdc0 = AL_AllocateDevice(“ADC0”, BoardNum);
/* Make any changes to the LDSD before initializing the device. All LDSD parameters are either set to
their initialization file (.INI) defaults when specified, otherwise each undefined parameter defaults to the
first or lowest option available in the DAQ board's capability file (.CAP). If the parameter can’t be found in
capabilities file the option is defined as unsupported. */
/* Initializes the hardware device to the current LDSD settings. */
errnum = AL_InitDevice(lhldAdc0);
/* Start the logical device. */
errnum = AL_StartDevice(lhldAdc0);
lpbuff = AL_GetDoneBuffPtr(lhldAdc0);
if (NULL != lpbuff)
{
if (lpbuff->lErrorFlag == 0)
DoSomethingWithBuffer(lpbuff);
else
HandleERROR();
}
AL_StopDevice(lhldAdc0);
AL_ReleaseDevice(lhldAdc0);
AL_ReleaseEnvironment();
Chapter 5 Program Development
5-2
5.2 INCLUDING ADLIB WIN IN VISUAL BASIC FOR WINDOWS
The sections presented below describe the mechanics of incorporating the ADLIB WIN library in a Visual
Basic for Windows based application program. To include the ADLIB library into the Windows
Application Programming Interface(API) add the following basic header files in your program MYPROG
.MAK application.
1. adlib.bas ADLIB API
2. adlerr.bas ADLIB error codes
3. drverr.bas ADLIB hardware generic error codes
5.2.1 Steps to Programming in Visual Basic For Windows
Global gblLhld As Long /* Define a handle variable for the ADC device. */
Global lpDataBuffStat DATABUFFSTATUS /* Define a pointer to an ADLIB data buffer
structure */
/* Load and initialize the environment. */
errnum&=AL_LoadEnvironment("c:\adlib\alwdm\Pci55mfhr\examples\pci55xx\vbasic\adlai01\adlib.con")
If errnum& < 0 Then
MsgBox "AL_LoadEnvironment Error", MB_ICONSTOP, "ADLIB Error"
Form_Unload (1)
End If
/* Allocate the ADC0 subsystem on board number 0. Reads in the current */
/* initialization file(.INI) and sets the LDSD as defined. */
gblLhld& = AL_AllocateDevice("ADC0", BoardNum&)
If gblLhld& < 0 Then
MsgBox "AL_AllocateDevice Error", MB_ICONSTOP, "ADLIB Error"
Form_Unload (1)
End If
/* Make any changes to the LDSD before initializing the device. All LDSD parameters are either set to
their initialization file (.INI) defaults when specified, otherwise each undefined parameter defaults to the
first or lowest option available in the DAQ board's capability file (.CAP). If the parameter can’t be found in
the capabilities file the option is defined as unsupported. */
errnum& = AL_SetTriggerMode(gblLhld&, "ABOUT_TRIG")
If errnum& < 0 Then
MsgBox "AL_SetTriggerMode Error", MB_ICONSTOP, "ADLIB Error"
Form_Unload (1)
End
End If
errnum& = AL_SetBufferSize(gblLhld&, 256)
If errnum& < 0 Then
MsgBox "AL_SetBufferSize Error", MB_ICONSTOP, "ADLIB Error"
Form_Unload (1)
End
End If
/* Initializes the hardware device to the current LDSD settings. */
errnum& = AL_InitDevice(gblLhld&)
If errnum& < 0 Then
MsgBox "AL_InitDevice Error", MB_ICONSTOP, "ADLIB Error"
Form_Unload (1)
End If
Chapter 5 Program Development
/* Start the logical device. */
errnum& = AL_StartDevice(gblLhld&)
If errnum& < 0 Then
MsgBox "AL_StartDevice Error", MB_ICONSTOP, "ADLIB Error"
Form_Unload (1)
End
End If
' Collect the data and display
errnum& = AL_GetBufferStatus(gblLhld&, lpDataBuffStat, DONE_BUFFER)
If errnum& = 1 Then 'The buffer is avaliable
' Check the status and error flags
If lpDataBuffStat.lStatusFlags <> BUFFER_FULL Then
Msg = "Incomplete Buffer Status = "
Msg = Msg & lpDataBuffStat.lStatusFlags
MsgBox Msg, MB_ICONSTOP, "ADLIB Buffer Status"
Form_Unload (1)
End If
If lpDataBuffStat.lErrorFlags <> 0 Then
Msg = "Buffer Error = "
Msg = Msg & lpDataBuffStat.lStatusFlags
MsgBox "Buffer Error", MB_ICONSTOP, "ADLIB Buffer Error"
Form_Unload (1)
End If
errnum& = AL_CopyBuffer(gblLhld&, lpDataBuffStat.lBuffNum, DataBuff(0), 0, 2048)
If errnum& < 0 Then
MsgBox "AL_CopyBuffer Error", MB_ICONSTOP, "ADLIB Error"
Form_Unload (1)
End If
errnum& = AL_DemuxDataSet(gblLhld&, lpDataBuffStat.lBuffNum, EngUnits(0), 0, 1)
If errnum& < 0 Then
MsgBox "AL_DemuxDataSet Error", MB_ICONSTOP, "ADLIB Error"
Form_Unload (1)
End If
errnum& = AL_ClearBufferDoneFlag(gblLhld&, lpDataBuffStat.lBuffNum)
If errnum& < 0 Then
MsgBox "AL_ClearBufferDoneFlag Error", MB_ICONSTOP, "ADLIB Error"
Form_Unload (1)
End If
lblShowData.Caption = Format$(DataBuff(0), "0") ' print the counts
lblShowVolts.Caption = Format$(EngUnits(0), "0.000") + " Volts" ' print the voltage
ElseIf errnum& < 0 Then 'An error occured in the AL_GetBufferStatus function call
MsgBox "AL_GetBufferStatus Error", MB_ICONSTOP, "ADLIB Error"
Form_Unload (1)
End If
errnum& = AL_StopDevice(gblLhld&)
If errnum& < 0 Then
MsgBox "AL_StopDevice Error", MB_ICONSTOP, "ADLIB Error"
End If
5-3
Chapter 5 Program Development
5-4
errnum& = AL_ReleaseDevice(gblLhld&)
If errnum& < 0 Then
MsgBox "AL_ReleaseDevice Error", MB_ICONSTOP, "ADLIB Error"
End If
errnum& = AL_ReleaseEnvironment()
If errnum& < 0 Then
MsgBox "AL_ReleaseEnvironment Error", MB_ICONSTOP, "ADLIB Error"
End If
5.3 EXAMPLE PROGRAMS
Included with ADLIB WIN is an extensive set of programming examples that provide conceptual
interpretations of interfacing to ADLIB to assist in the develop ment design of the user application. Each
example program is designed to exercise a specific area of the library to simplify the understanding of the
example's specific concept. See also, the comments provided at the beginning of each example program file
for detailed descriptions.
The following is the list of example programs:
Example programs are also provided for each specific board type, and are not necessarily generic to all
boards. The examples are located in each board (NAME) directory.
\Adlai01 examines the BUFFER_DONE message response handler
\Adlai02 examines the User polling of the BUFFER_DONE flag.
\Adlai04 examines the ABOUT Trigger mode.
\Adlai05 examines the BURST/SCAN MODE option.
\Adlai07 examines the Software Transfer method.
\Adlai08 examines the CALLBACK buffer response handler (MSC only).
\Adlda01 examines the Software Transfer method.
\Adlda02 examines the Single DAC BUFFER_DONE message response handler
\Adlda03 examines the Dual DAC BUFFER_DONE message response handlers
\Adldio01 examines the Software Transfer Digital Input/Output ports 0 & 1.
\Adldio23 examines the Software Transfer Digital Input/Output ports 2 & 3.
\Adlctr01 examines the Counter IN and Counter OUT functions.
Chapter 6 Memory Buffer Allocation
6-1
6. MEMORY BUFFER ALLOCATION
6.1 OVERVIEW
ADLIB WIN removes the complexity of allocating suitable DMA and Interrupt buffers by automatically
allocating buffer(s) when a DAQ board’s subsystem is initialized. The application programmer can then
retrieve a pointer to buffer and/or set up an ADLIB buffer message handler that will be called when each
buffer has been completed. ADLIB allows N buffers of size M for each DAQ board's logical device; the
only limitation on quantity and size of the buffer(s) is the amount of available host system memory.
6.2 POLLING or DMA SYSTEM BUFFER ALLOCATION
All buffers are allocated on behalf of ADLIB for DMA Acquisition during your applications device
initialization according to the buffer size and number of buffers specified.
6.3 THE BUFFER STRUCTURE
ADLIB WIN buffer pointers are not just pointers to a DAQ board's subsystem data, but are pointers to a
structure that contains the buffer type, size, linear data address, physical data address, current sample
count, hardware trigger points, completion flags, status flags, and error flags.
Some of these fields remain constant for the duration of the acquisition. Others contain relevant
information about the current condition of the buffer, and error conditions that occur in the hardware
device's subsystem during the current acquisition.
The three structure variables that provide state/status/error information are defined as follows:
DWORD dwDoneFlag
BUFFER_IDLE = 0 The buffer is available for use, but acquisition has not started
BUFFER_DONE = 1 The buffer has been filled with samples and is available for
BUFFER_INUSE = 2 The buffer is currently being filled with samples.
DWORD dwStatusFlag
BUFFER_EMPTY = 1 No samples are available in the buffer.
BUFFER_INCOMPLETE = 2 The output buffer has not read completely or and input has
BUFFER_COMPLETE = 4 The output buffer has been read completely.
BUFFER_FULL = 8 The input buffer has filled to capacity.
Beginning with Revision 3.0 of ADLIB, the upper word of the dwStatusFlag contains the hardware status
register state at the time of an error condition as described in the lErrorFlags below.
The Done Flag specifies the current state of a buffer. This flag can be set to
any of the three following conditions as defined in the ADLIB include file.
on this buffer.
use in the user application.
The Status Flag specifies the completion status of a buffer. This flag can be set
to any of the four following conditions as defined in the ADLIB include file.
not filled to capacity.
Chapter 6 Memory Buffer Allocation
6-2
long lErrorFlags
The Error Flags specify the condition that has stopped a buffer from
successfully completing. Although an error may be reported, this does not
indicate the BUFFER_FULL flag is not set. This would be the case if an error
was detected and enough samples were available to fill the buffer to capacity.
One or more of these flags may also be set together. If any of these flags have
set, checking the current hardware error conditions will usually reveal th e actual
condition that caused the acquisition runtime error. This flag can be set to any
of the four following conditions as defined in the ADLIB include file.
BUFFER_STOPPED = 1 An error occurred and the buffer(s) are no longer being serviced.
BUFFER_OVERRUN = 2 An error occurred when attempting to place the next sample
beyond the bounds of the buffer.
BUFFER_UNDERRUN = 4 An error occurred and the buffer is incomplete.
BUFFER_NEXTBUSY = 8 When attempting to access the next buffer, the current state of
the dwDoneFlag indicated the buffer was not yet available for
use. To release control of a buffer call the function
AL_ClearBufferDoneFlag(LHLD, lBufferNum)
The Buffer structure is defined as follows in ADLIB include file.
DWORD dwBufferSize; . /* Size of each buffer in samples. */
WORD huge * hpwBufferLinear; . /* App linear buffer address. */
LPVOID lpvDataBuffPhysical; /* Physical address for DMA buffer. Set to NULL when */
/* non DMA transfer mode. This address should not be */
/* used by a user App. */
DWORD dwBufferWrite; /* Number of data samples in the buffer. */
DWORD dwBufferRead; /* Number of data samples obtained from the buffer. */
WORD huge * hpwTrigPoint; /* App linear address of the trigger point. */
WORD huge * hpwTrigPointStart; /* App linear starting address of the pre-trigger data. */
DWORD dwDoneFlag; /* Buffer complete flag */
DWORD dwStatusFlags; /* Current status */
long lErrorFlags; /* Buffer errors */
DWORD dwBuffNum; /* Buffer number */
}DATABUFFER;
typedef DATABUFFER FAR * LPBUFFERSTRUCT;
In addition to the above structure that provides pointers to the data, a status structure is available. This
structure was originally created to provided support in Visual Basic, but can also be used in the C\C++
ADLIB API. See the ADLIB function AL_GetBufferStatus for details.
typedef struct tagDATABUFFSTAT
{
Chapter 6 Memory Buffer Allocation
DWORD dwBufferType; /* Data Buffer type. */
DWORD dwBufferSize; /* Size of each buffer in bytes. */
DWORD dwBufferWrite; /* Number of data samples in the buffer. */
DWORD dwBufferRead; /* Number of data samples obtained from the buffer. */
DWORD dwTrigPoint; /* App linear address of the trigger point. */
DWORD dwTrigPointStart; /* App lin ear starting address of the */
/* pre-trigger data. */
DWORD dwDoneFlag; /* Buffer complete flag */
DWORD dwStatusFlags; /* Current status */
long lErrorFlags; /* Buffer errors */
DWORD dwBuffNum; /* Buffer number ID */
}DATABUFFSTAT;
typedef DATABUFFSTAT FAR * LPDATABUFFSTATUS;
Visual Basic for Windows adlib.bas file
Type DATABUFFSTATUS
lBufferType As Long ' Data Buffer type.
lBufferSize As Long ' Size of each buffer in bytes.
lBufferWrite As Long ' Number of data samples in the buffer.
lBufferRead As Long ' Number of data samples obtained from the buffer.
lTrigPoint As Long ' App buffer position number of the trigger point.
lTrigPointStart As Long ' App buffer position number of the pre-trigger data.
lDoneFlag As Long ' Buffer complete flag
lStatusFlags As Long ' Current status
lErrorFlags As Long ' Buffer errors
lBuffNum As Long ' Buffer number ID
End Type
6-3
6.4 BUFFER NOTIFICATIONS
6.4.1 C\C++
The user application has three choices of obtaining a pointer to a buffer that has been completed
(BUFFER_DONE).
1. The first method involves calling the ADLIB function AL_GetDoneBuffPtr(LHLD), which will return
a pointer to the next completed buffer when available, otherwise this function returns NULL.
2. The second method uses Windows Post-message handler routine installed by the user application.
Each time a buffer is completed the user routine will be called, passing a pointer to the buffer in the
1Param parameter. See example program adlai01.
Example:
Chapter 6 Memory Buffer Allocation
6-4
long FAR PASCAL_ export AdlibBufferProc (hwnd, message, wParam, 1Param)
{
LPBUFFSTRUT 1pbuff;
lpbuff = (LPBUFFSTRUCT) 1Param;
/*do something with the buffer*/
}
3. The third method involves getting a pointer to a specific buffer with the ADLIB function
AL_GetBuffPtr(LHLD, BufferNumber). Once obtained, this pointer is valid until a device is either
released or re-initialized. The user application can then monitor the actual buffer status to determine
when the buffer is complete, the number of samples available and the current error condition. The
buffer still needs to be cleared with the AL_ClearBufferDoneFlag(LHLD) when running in a
continuous mode of operation, otherwise an error will be indicated in the buffer structure when the
driver attempts to re-use the buffer.
4. The fourth method uses a CALLBACK function supported by MSC only. Each time a buffer is
completed the CALLBACK routine will be invoked, passing a pointer to the buffer structure in the
LPBUFFSTRUCT parameter. See example program adlai08.
6.4.2 Visual Basic for Windows
1. The first method involves calling the ADLIB function AL_GetBufferStatus(LHLD, lpDataBuffStat As
DATABUFFSTATUS, lBuffNum) with the lBuffNum set to the predefined Global constant
DONE_BUFFER. Specifying DONE_BUFFER fills lpDataBuffStat with the current status on the next
buffer in sequence from 0 thru n that has been completed. The programmer must check the
lpDataBuffStat status flags for a BUFFER_FULL flag. Once the buffer is full the AL_CopyBuffer
function can be called to retrieve the data. See example program adlai02.
2. The second method uses Windows Post-message handler routine installed by the user application.
Each time a buffer is completed the user routine will be called, p assing the completed buffer number in
the wParam parameter. The programmer then uses the buffer number to check the status and copy the
data from the internal ADLIB buffer. See example program adlai01.
Example: ↓
Sub MsgBlaster1_Message (MsgVal As Integer, wParam As Integer, lParam As Long, ReturnVal As
Long)
' Collect the data and display
errnum& = AL_GetBufferStatus(gblLhld&, lpDataBuffStat, DONE_BUFFER)
If errnum& < 0 Then
MsgBox "AL_GetBufferStatus Error", MB_ICONSTOP, "ADLIB Error"
Form_Unload (1)
End If
' Check the status and error flags
If lpDataBuffStat.lStatusFlags <> BUFFER_FULL Then
Msg = "Incomplete Buffer Status = "
Msg = Msg & lpDataBuffStat.lStatusFlags
MsgBox Msg, MB_ICONSTOP, "ADLIB Buffer Status"
Form_Unload (1)
End If
Chapter 6 Memory Buffer Allocation
If lpDataBuffStat.lErrorFlags <> 0 Then
Msg = "Buffer Error = "
Msg = Msg & lpDataBuffStat.lStatusFlags
MsgBox "Buffer Error", MB_ICONSTOP, "ADLIB Buffer Error"
Form_Unload (1)
End If
errnum& = AL_CopyBuffer(gblLhld&, wParam, DataBuff(0), 0, 2048)
If errnum& < 0 Then
MsgBox "AL_CopyBuffer Error", MB_ICONSTOP, "ADLIB Error"
Form_Unload (1)
End If
errnum& = AL_DemuxDataSet(gblLhld&, wParam, EngUnits(0), 0, 1)
If errnum& < 0 Then
MsgBox "AL_DemuxDataSet Error", MB_ICONSTOP, "ADLIB Error"
Form_Unload (1)
End If
errnum& = AL_ClearBufferDoneFlag(gblLhld&, wParam)
If errnum& < 0 Then
MsgBox "AL_ClearBufferDoneFlag Error", MB_ICONSTOP, "ADLIB Error"
Form_Unload (1)
End If
End Sub
6-5
Chapter 6 Memory Buffer Allocation
6-6
Chapter 7 Dynamic Linking to ADLIB WIN
7-1
7. DYNAMIC LINKING TO ADLIB WIN
7.1 IMPLICIT LINKING C\C++
ADLIB WIN provides an import libraryadlcore.lib created from its DLL interface libraries. The import
library contains the necessary entry points to ADLIB that the linker uses to resolve external DLL
references in the user's application code. To include the import library in your application, add adlcore.lib
to the list of libraries supplied to the linker.
7.2 EXPLICIT LINKING C\C++
The ADLIB DLL adlcore.dll can also be linked to an application by specifying the name of the ADLIB
function in the IMPORTS section of your applications module definition (.DEF) file. The file adlib.h
contains all function prototypes exported by ADLIB. To include an ADLIB call, proceed the ADLIB
function name with ADLCORE as shown below in your .DEF file IMPORTS section.
To link with another compiler, such as Borland C++, use the LoadLibrary & GetProcAddress functions
along with the ADLIB imports.
7.3 VISUAL BASIC FOR WINDOWS
All available ADLIB function calls have been predefined in the file Ad lib.bas file. Each function has been
declared with the necessary DLL Library and function parameter type definitions. Adding the Adlib.bas
file to your programs .mak file provides all necessary interfaces to ADLIB.
Chapter 7 Dynamic Linking to ADLIB WIN
7-2
Chapter 8 Error Handling
8-1
8. ERROR HANDLING
8.1 OVERVIEW
All Library functions return 32-bit signed numbers (long). All the positive numbers, 0 through
2,147,483,647 inclusive (0 - 0x7FFFFFFF), are non-error return values from the function.
All the negative numbers are reserved for Error codes. The first 64K error codes, -1 through -65536
inclusive (0xFFFFFFFF - 0xFFFF0000), is reserved for “universal” error codes. The rest, -65537 through 2,147,483,648 inclusive (0xFFFEFFFF - 0x80000000), are used for “special” error codes.
“Universal” error codes are those that are common to all versions of the Library, for all environments, and
independent of any user code. “Special” error codes are for environment-specific messages, and for
application-specific registered messages.
8.2 ERROR CONTROL CONDITIONS
Several functions are available within the ADLIB library to control certain conditions under which an error
is reported from the library. The following is a list of these functions; see the specific function's definition
for complete details.
Each time the ADLIB library is to be used, the Environment configuration must be loaded and when all
devices have been released the Environment must be released. The AL_LoadEnvironment function loads
the information specified in the configuration file (.CON) that sp ecifies the path to the initialization file
(.INI) and the boards installed in the system. Both (.CON) and (.INI) files are created with ADACCONFIG
utility.
Visual Basic for Windows
Function AL_LoadEnvironment(ByVal lpstrEnvInfoSource As String) As Long
LPSTR lpstrEnvInfoSource address of the ADLIB environment filename.
The AL_LoadEnvironment function loads the ADLIB environment configuration file. This file contains
the environment specific settings and the board(s)' related initialization in formation required for the proper
operation of the ADLIB.
Parameter Description
lpstrEnvInfoSourcePoints to a null-terminated string that names the complete drive, path, and filename of the ADLIB configuration file (adlib.con). If this
parameter does not contain the full drive and path, ADLIB searches
the Windows directory.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
Related Functions:
AL_ReleaseEnvironment
Comments:
The application must call this function before attempting to make any ADLIB API function calls.
Program References:
All Examples
Supported Boards:
All
Chapter 9 Environment Configurations
9-2
9.2 AL_ReleaseEnvironment
Prototype C\C++
ERRNUM AL_ReleaseEnvironment(void);
Visual Basic for WindowsFunction AL_ReleaseEnvironment() As Long
void
no parameters
The AL_ReleaseEnvironment function releases all previously allocated logical device subsystem
databases(LDSD), board and environment structures, and associated memory.
Parameter Description
void Function takes no parameters.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
Comments:
Once called, all internal memory and structure pointers previously returned from ADLIB are considered
invalid. Further access to these pointers will address released system memory that may cause the system to
crash.
Related Functions:
AL_LoadEnvironment
Program References:
All Examples
Supported Boards:
All
Chapter 9 Environment Configurations
9-3
9.3 AL_SetEnvString
Prototype C\C++
ERRNUM AL_SetEnvString(LPSTR lpstrEnv);
Visual Basic for Windows
Function AL_SetEnvString(ByVal lpstrEnv As String) As Long
LPSTR lpstrEnv source address
The AL_SetEnvString function copies the lpstrEnv string to the ADLIB environment. The maximum
string length allowed is 80 characters, including the NULL termination character. If the input string
exceeds the 80 character limit the resulting string will be truncated and NULL padded.
Parameter Description
lpstrEnv Points to the user define environment description string.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
Related Functions:
AL_GetEnvString
Program References:
NONE
Supported Boards:
All
Chapter 9 Environment Configurations
9-4
9.4 AL_GetEnvString
Prototype C\C++
ERRNUM AL_GetEnvString(LPSTR lpstr, long lMaxLength);
Visual Basic for Windows
Function AL_GetEnvString(ByVal lpstr As String,
ByVal lMaxLength As Long) As Long
LPSTR lpstrEnv destination address
long lMaxLength the count in bytes to be copied
The AL_GetEnvString function copies lMaxLength bytes for the ADLIB environment string to the
destination string. If the size of the destination string length is less than the string to be copied, the
resulting string will be truncated and NULL padded.
Parameter Description
lpstrEnv Points to the input destination string.
lMaxLength Maximum length in bytes to be copied to the user string , including the NULL
termination character.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
Related Functions:
AL_SetEnvString
Program References:
NONE
Supported Boards:
All
Chapter 9 Environment Configurations
9-5
Chapter 10 Board Functions
10-1
10. BOARD FUNCTIONS
The Board Functions are used to retrieve information stored within the hardware, from the configuration
files and drivers in use.
10.1 AL_GetBoardHardwareId
Prototype C\C++
BOARDHWID AL_GetBoardHardwareId(BRDID brdid);
Visual Basic for Windows
Function AL_GetBoardHardwareId(ByVal brdid As Long) As Double
BRDID brdid ID number of the board
The AL_GetBoardHardwareId function retrieves the board's hardware register ID number.
Parameter Description
brdid Specifies the ID number of the board from which the hardware ID is to be
retrieved.
Returns:
On success BOARDHWID contains the board's hardware register ID number, otherwise BOARDHWID
contains the negative error code that occurred during the call.
Related Functions:
NONE
Program References:
NONE
Supported Boards:
All
Chapter 10 Board Functions
10-2
10.2 AL_GetBoardDriverVersion
Prototype C\C++
DRIVERVER AL_GetBoardDriverVersion(BRDID brdid);
Visual Basic for Windows
Function AL_GetBoardDriverVersion(ByVal brdid As Long) As Double
BRDID brdid ID number of the board
The AL_GetBoardDriverVersion function retrieves the board driver’s software version number.
Parameter Description
brdid Specifies the ID number of the board from which the board driver’s software
version number is to be retrieved.
Returns:
On success DRIVERVER contains the board driver’s software version number, otherwise DRIVERVER
contains the negative error code that occurred during the call.
Function AL_SetBoardString(ByVal brdid As Long, ByVal lpstrBrd As String) As Long
BRDID brdid ID number of the board
LPSTR lpstrBrd source address
The AL_SetBrdString function copies the lpstrBrd string to the ADLIB board string. The maximum
string length allowed is 80 characters, including the NULL termination character. If the input string
exceeds the 80 character limit the resulting string will be truncated and NULL padded.
Parameter Description
brdid Specifies the ID number of the board from which the board driver’s software
version number is to be retrieved.
lpstrBrd Points to the user define board description string.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
Related Functions:
AL_GetBoardString
Program References:
NONE
Supported Boards:
All
Chapter 10 Board Functions
10-4
10.4 AL_GetBoardString
Protype C\C++
ERRNUM AL_GetBoardString(BRDID brdid, LPSTR lpstr, long lMaxLength);
Visual Basic for Windows
Function AL_GetBoardString(ByVal brdid As Long, ByVal lpstr As String,
ByVal lMaxLength As Long) As Long
BRDID brdid ID number of the board
LPSTR lpstrBrd destination address
long lMaxLength the count in bytes to be copied
The AL_GetBrdString function copies lMaxLength bytes for the ADLIB board string to the destination
string. If the size of the destin ation string len gth is less than the string to be co pied, the resu lting strin g will
be truncated and NULL padded.
Parameter Description
brdid Specifies the ID number of the board from which the board driver’s software
version number is to be retrieved.
lpstrBrd Points to the input destination string.
lMaxLength Maximum length in bytes to be copied to the user string, including the NULL
termination character.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
Related Functions:
AL_SetBoardString
Program References:
NONE
Supported Boards:
All
Chapter 10 Board Functions
10-5
10.5 AL_GetBoardName
Protype C\C++
ERRNUM AL_GetBoardName(BRDID brdid, LPSTR lpstr, long lMaxLength);
Visual Basic for Windows
Function AL_GetBoardName(ByVal brdid As Long, ByVal lpstr As String,
ByVal lMaxLength As Long) As Long
BRDID brdid ID number of the board
LPSTR lpstrBrd destination address
long lMaxLength the count in bytes to be copied
The AL_GetBrdName function copies lMaxLength bytes for the ADLIB board string to the destination
string. If the size of the destin ation string len gth is less than the string to be co pied, the resu lting strin g will
be truncated and NULL padded.
Parameter Description
brdid Specifies the ID number of the board from which the board driver’s software
version number is to be retrieved.
lpstrBrd Points to the input destination string.
lMaxLength Maximum length in bytes to be copied to the user string, including the NULL
termination character.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
Related Functions:
NONE
Program References:
NONE
Supported Boards:
All
Chapter 10 Board Functions
10-6
10.6 AL_GetMfgProductId
Prototype C\C++
PRODID AL_GetBoardHardwareVersion(LHLD lhld);
Visual Basic for Windows
Function AL_GetBoardHardwareVersion(ByVal lhld As Long) As Double
BRDID brdid ID number of the board
The AL_GetMfgProductId function retrieves the board's Product ID number.
Parameter Description
brdid Specifies the ID number of the board from which the hardware version is to be
retrieved.
Returns:
On success PRODID contains the board's Product ID as specified in its capability file, otherwise PRODID
contains the negative error code that occurred during the call.
Related Functions:
NONE
Program References:
NONE
Supported Boards:
All
Chapter 12 Logical Device String Names
11-1
11. LOGICAL DEVICE ALLOCATIONS
Logical Devices are considered to be individual board subsections that can operate independently. For a
board that supports 1 AtoD port, 2 DtoA ports, 2 Digital input ports and 2 Digital output ports there would
be a total of 7 devices that can be allocated with the AL_AllocateDevice function. These devices consist of
“ADC0”, “DAC0”, “DAC1”, “DIN0”, “DIN1”, “DOT2” and “DOT3”. Each call to AL_AllocateDevice
will load the specified Logical Device per its associated settings specified in the initialization file (.INI)
and returns a LONG HANDLE to the LOGICAL DEVICE (LHLD) which is used in subsequent calls to
the device.
11.1 AL_AllocateDevice
Prototype C\C++
LHLD AL_AllocateDevice(LPSTR lpstrLogDev, long lBoardId); Visual Basic for Windows
Function AL_AllocateDevice(ByVal lpstrLogDev As String,
ByVal lBoardId As Long) As Long
LPSTR lpstrLogDev address of the device subsystem string type: (i.e. “ADC0”)
long lBoardId ID of the board
The AL_AllocateDevice function loads a device subsystem into the ADLIB logical device subsystem
database (LDSD). If the ADLIB information file exist (myinfo.ini) as specified in the myenv.con file, then
the LDSD is configured as defined. If the ADLIB information file does NOT exist or a configuration
parameter is not indicated within the myinfo.ini file source, the parameter will be set to its associated
capabilities file default(s) if available, otherwise the parameter is set to an ADLIB internal default. See the
individual function listing for its default behavior . Multiple configurations for the same hardware device
subsystem can also be allocated, but only one can be put into the running state at any time. See section
LOGICAL DEVICESfor additional details.
4.3
Parameter Description
lpstrLogDevPoints to th e logical device subsystem type to be allocated. The actual string is composed of the following type identifiers (see below) along with the ID
number of the device subsystem to be allocated. The available types are board
dependent and are specified in the [Board] entry section of the specific board’s
capability file.
“ADC#”
Specifies a specific analog input subsystem on the board to be allocated.
“DAC#”
Specifies a specific analog output subsystem on the board to be allocated.
‘DIN#”
Specifies a specific digital input subsystem on the board to be allocated.
“DOT#”
Specifies a specific digital output subsystem on the board to be allocated.
“COUNTER#”
Specifies a specific COUNTER subsystem on the board to be allocated.
lBoardIdSpecifies the specific board ID from which to logical device subsystem will be
allocated.
Chapter 12 Logical Device String Names
11-2
Returns:
On success returns a handle to the logical device subsystem that the application uses in all subsequent
library calls to the LDSD, otherwise LHLD contains a negative error code that occurred during the call.
Related Functions:
AL_ReleaseDevice
Program References:
All
Supported Logical Device Subsystems:
All
Chapter 12 Logical Device String Names
11-3
11.2 AL_ReleaseDevice
Prototype C\C++
ERRNUM AL_ReleaseDevice(LHLD lhld);
Visual Basic for Windows
Function AL_ReleaseDevice(ByVal lhld As Long) As Long
LHLD lhld handle of the LDSD to be released
The AL_ReleaseDevice function releases a logical device subsystem database (LDSD) and all associated
memory previously allocated to the device. Further calls to the LDSD will return an invalid LHLD error
code, all previously returned pointers from the LDSD to the user application that provide access to the
device or its data buffers are considered invalid (NULL) and must not be used by the application program.
Parameter Description
lhld Identifies the instance o f the logical device subsystem to be released.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
Notes
If the device is currently running, an error flag setting determines whether to stop and then release, or to
return a non-critical error and keep the device running. See the function AL_SetErrorOnReleaseRunning
for more information.
Visual Basic for Windows
Function AL_SetLdsString(ByVal lhld As Long, ByVal lpstrLds As String) As Long
LHLD lhld handle of the LDSD
LPSTR lpstrLds source address
The AL_SetLdsString function copies the lpstrLds string to the ADLIB LDSD string. The maximum
string length allowed is 80 characters, including the NULL termination character. If the input string
exceeds the 80 character limit the resulting string will be truncated and NULL padded.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpstrEnv Points to the user define Logical device description string.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
Related Functions:
AL_GetLdsString
Program References:
NONE
Supported Logical Device Subsystems:
All
Chapter 12 Logical Device String Names
11-5
11.4 AL_GetLdsString
Prototype C\C++
ERRNUM AL_GetLdsString(LHLD lhld, LPSTR lpstr, long lMaxLength);
Visual Basic for Windows
Function AL_GetLdsString(ByVal lhld As Long, ByVal lpstr As String,
ByVal lMaxLength As Long) As Long
LHLD lhld handle of the LDSD
LPSTR lpstrLds destination address
long lMaxLength the count in bytes to be copied
The AL_GetLdsString function copies lMaxLength bytes for the ADLIB LDSD string to the destination
string. If the size of the destin ation string len gth is less than the string to be co pied, the resu lting strin g will
be truncated and NULL padded.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpstrLds Points to the input destination string.
lMaxLength Maximum length in bytes to be copied to the user string , including the NULL
termination character.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
Related Functions:
AL_SetLdsString
Program References:
NONE
Supported Logical Device Subsystems:
All
Chapter 14 Logical Device Start / Stop Operations
12-1
12. LOGICAL DEVICE INITIALIZATIONS
Each Logical Device subsystem requires initialization before it can be used. The initialization consists of
passing the device initialization settings specified in the (.INI) file and ADLIB function call settings to the
specific boards lower level DLL and SYSTEM drivers. For the Pci5500 and PCI 55xx Series Cards, the
next step is to start the device with a call to the AL_StartDevice function for the ADC0, DAC0 or DAC1
devices. All other Pci5500 and PCI55xx devices begin operation after the AL_InitDevice function call.
12.1 AL_InitDevice
Prototype C\C++
ERRNUM AL_InitDevice(LHLD lhld);
Visual Basic for Windows
Function AL_InitDevice(ByVal lhld As Long) As Long
LHLD lhld handle of the LDSD to be initialized
The AL_InitDevice function initializes the actu al hardware device to the current ADLIB logical device
subsystem database(LDSD) settings. This function must be called before attempting to call the
AL_StartDevice function, failure to do so will result in an error. Once started, all ADLIB calls that affect
the functional state of the hardware device are still allowed, but the n ew setting is only reflected in LDSD,
and NOT in the actual hardware device itself. ADLIB functions that control the running state are reflected
in both the LDSD and actual hardware device itself. To update the actual state of the hardware device with
any changes made to the LDSD, AL_InitDevice function must be called once again. This allows changes to
be made to the functionality of the LDSD while the hardware device is still running. Multiple
configurations for the same hardware device subsystem can also be allocated with AL_AllocateDevice, but
only one can be initialized and started at any given time.
Parameter Description
lhld Identifies the instance of the logical device subsystem to be initialized.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
Note
If the device is currently running, an error flag setting determines whether to stop and then reinitialize the
hardware device or to return a non-critical error and keep the device running. See the function
AL_ErrorOnInitRunning for more information.
Related Functions:
NONE
Program References:
ALL
Supported Logical Device Subsystems:
All
Chapter 14 Logical Device Start / Stop Operations
13-2
13. LOGICAL DEVICE START / STOP OPERATIONS
Once a device has been fully configured and initialize it is ready to be started. Starting a device consist of
informing the hardware to begin it’s acquisition. Depending on the specified cycle mode of the device the
acquisition may be continuous or single cycle. For continuous mode the device acquisition may be stopped
at ant time with a call to AL_StopDevice. One a device is stopped; it may then be reinitialized and
restarted.
13.1 AL_StartDevice
Prototype C\C++
ERRNUM AL_StartDevice(LHLD lhld);
Visual Basic for Windows
Function AL_StartDevice(ByVal lhld As Long) As Long
LHLD lhld handle of the LDSD to be started
The AL_StartDevice function puts a device in the run mode. Depending on the current ADLIB transfer
mode this call may not return until completed. See AL_SetDataTransferMode for more details on ADLIB’s
foreground and background operations. Another feature of the PCI5500 ADC0 or Pci55xx ADC0 and
DAC0 allows the conversions to be controlled via software (CGEN Control) or an external signal after
AL_StartDevice is called, this feature is detailed in the user manual as ADC or DAC Software Gate an d
ADC or DAC External Gate features. To implement either Gating features using ADLIB, see the
AL_SetGateXXX functions described in this manual.
Parameter Description
lhld Identifies the instance of the logical device subsystem to be started.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
The Cycle Mode setting specifies the duration of the acquisition as either Continuous or Single Cycle. A
Continuous setting informs ADLIB to repeat the operation indefinitely, essentially reusing previous buffers
0-n over and over. In single Cycle Mode the acquisition stops when completed, essentially running until all
buffers have been used.
Supported Logical Device Subsystems:
Pci55xx Series: DIN0, DIN1, DIN2, DIN3, DOT0, DOT1, DOT2, DOT3, Options: SINGLE_CYCLE
Pci55xx Series: CTR0, CTR1, CTR2, CTR3, Options: SINGLE_CYCLE Note that CTR0, CTR1 Counters are referenced in the user manual as CNTR0/1 and
Timers CTR2, CTR3 are referenced in the user manual as TMR0/1.
Pci55xx Series: ADC0, DAC0, DAC1, Options: SINGLE_CYCLE or CONTINUOUS_CYCLE
Chapter 15 Logical Device Cycle Modes
14-2
14.2 AL_GetCycleMode
Prototype C\C++
ERRNUM AL_GetCycleMode(LHLD lhld, LPSTR lpstrMode, long lMaxLength);
Visual Basic for Windows
Function AL_GetCycleMode(ByVal lhld As Long, ByVal lpstrMode As String,
ByVal lMaxLength As Long) As Long
LHLD lhld handle of the LDSD
LPSTR lpstrModedestination address of the cycle mode string
long lMaxLength the count in bytes to be copied
The AL_GetCycleMode function retrieves the current software cycle operation mode of the LDSD.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpstrMode Points to the destination string for the copy.
lMaxLength Maximum length in bytes to be copied to the user string , including the NULL
termination character.
Returns:
On success ERRNUM is set to 1 and destination string lpstrMode is set to either AL_SINGLE_CYCLE or
AL_CONTINUOUS_CYCLE as defined in the ADLIB include file, otherwise ERRNUM contains the last
error code that occurred during the call and the destination string is considered invalid.
Related Functions:
AL_SetCycleMode
Supported Logical Device Subsystems:
Pci55xx Series: DIN0, DIN1, DIN2, DIN3, DOT0, DOT1, DOT2, DOT3
Pci55xx Series: CTR0, CTR1, CTR2, CTR3
Note that CTR0, CTR1 Counters are referenced in the user manual as CNTR0/1 and
Timers CTR2, CTR3 are referenced in the user manual as TMR0/1.
Pci55xx Series: ADC0, DAC0, DAC1
Chapter 16 Logical Device Transfer Methods
15-1
15. LOGICAL DEVICE TRANSFER METHODS
Depending on the acquisition needs, the device may be controlled through a Software control routine
within the board’s driver or via DMA through the PC’s system hardware. Typically high-speed acquisition
modes require DMA and slower modes can use software routines.
Supported Logical Device Subsystems:
Pci55xx Series: CTR0, CTR1, CTR2, CTR3, Options: SOFTWARE Note that CTR0, CTR1 Counters are referenced in the user manual as CNTR0/1 and
Timers CTR2, CTR3 are referenced in the user manual as TMR0/1.
Pci55xx Series: DIN0 to DIN3, DOT0 to DOT3, Options: SOFTWARE
Pci55xx Series: ADC0, DAC0, DAC1, Options: SOFTW ARE or DMA
Chapter 16 Logical Device Transfer Methods
15-2
15.2 AL_GetDataTransferMethod
Prototype C\C++
ERRNUM AL_GetDataTransferMethod(LHLD lhld, LPSTR lpstrMethod, long lMaxLen);
Visual Basic for Windows
Function AL_GetDataTransferMethod(ByVal lhld As Long,
ByVal lpstrMethod As String,
ByVal lLength As Long) As Long
LHLD lhld handle of the LDSD
LPSTR lpstrModedestination address of the transfer method string
long lMaxLength the count in bytes to be copied
The AL_GetDataTransferMethod function retrieves the data transfer method of the LDSD.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpstrMode Points to the destination string for the copy.
lMaxLength Maximum length in bytes to be copied to the user string , including the NULL
termination character.
Returns:
On success ERRNUM is set to 1 and destination string lpstrMethod is set to either
AL_DTM_SOFTWARE, AL_DTM_DMA, AL_DTM_IRQ or AL_DTM_C40PORT as defined in the
ADLIB include file, otherwise ERRNUM contains the last error code that occurred during the call and the
destination string is considered invalid.
Related Functions:
AL_SetDataTransferMethod
Supported Logical Device Subsystems:
Pci55xx Series: CTR0, CTR1, CTR2, CTR3
Note that CTR0, CTR1 Counters are referenced in the user manual as CNTR0/1 and
Timers CTR2, CTR3 are referenced in the user manual as TMR0/1.
Pci55xx Series: DIN0 to DIN3, DOT0 to DOT3
Pci55xx Series: ADC0, DAC0, DAC1
Chapter 17 Logical Device Status Information
16-1
16. LOGICAL DEVICE STATUS INFORMATION
The Device Status provides the current running condition of a device subsystem as. The Device Status is
useful for Single Cycle mode to determine when the entire acquisition has completed.
16.1 AL_GetDeviceStatus
Prototype C\C++
STATUS AL_GetDeviceStatus(LHLD lhld);
Visual Basic for Windows
Function AL_GetDeviceStatus(ByVal lhld As Long) As Long
LHLD lhld handle of the LDSD
The AL_GetDeviceStatus function returns the current hardware running status of a logical device
subsystem.
Parameter Description
lhld Identifies the instance of the logical device subsystem from which the status is to be
retrieved.
Returns:
On success STATUS is set to either AL_RUNNING or AL_STOPPED, otherwise STATUS contains a
negative error code that occurred during the call.
Related Functions:
NONE
Supported Logical Device Subsystems:
Pci55xx Series: CTR0, CTR1, CTR2, CTR3
Note that CTR0, CTR1 Counters are referenced in the user manual as CNTR0/1 and
Timers CTR2, CTR3 are referenced in the user manual as TMR0/1.
Pci55xx Series: DIN0 to DIN3, DOT0 to DOT3
Pci55xx Series: ADC0, DAC0, DAC1
Chapter 17 Logical Device Status Information
16-2
Chapter 18 Analog Output
17-1
17. ANALOG OUTPUT
The Analog Output function immediately sets the specified DtoA channel to specified voltage. This is
typically used for slower software transfer modes requiring level oriented voltage output application
requirements. For higher speed applications the DMA transfer mode allows timed waveform generation.
To use the AL_SetDAOutput function with the Pci55xx DAC0 or DAC1 the clocking source must also be
configured for “SOFTWARE_CONVERT”, in addition DAC0’s Trigger and Gating modes must be
DISABLED.
17.1 AL_SetDaOutput
Prototype C\C++
ERRNUM AL_SetDaOutput(LHLD lhld, double dData, long lUnits);
Visual for Basic Windows
Function AL_SetDaOutput(ByVal lhld As Long, ByVal dData As Double,
ByVal lUnits As Long) As Long
LHLD lhld handle of the LDSD
double dData output data
long lUnits specifies the output data units
The AL_SetDaOutput function immediately sets a hardware analog output port to the dData value.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
dData Specifies the data output value.
lUnits Sets the units in which the above dData output parameter is specified. The
available settings are defined as AL_VOLTS or AL_RAWDATA in the ADLIB
include file.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
The Digital Input/Output functions immediately reads or writes the specified Digital Port. For the Pci5500
and Pci55xx Digital IO Ports 0 & 1 are 8-bit ports and in addition the Pci55xx supports Digital Ports 2 & 3
as 16-bit ports. All of the Digital Input/Output functions read or write the full 8-bit or 16-bit value per call.
18.1 AL_DigInput
Prototype C\C++
STATUS AL_API AL_DigInput(LHLD lhld, long lChan, long lMaskBits);
Visual Basic for Windows
Function AL_DigInput(ByVal lhld As Long, ByVal lChan As Long,
ByVal lMaskBits As Long) As Long
LHLD lhld handle of the LDSD
double lChanspecifies the input port channel number
long lMaskBits specifies the input port masking bits
The AL_DigInput function immediately retrieves the input status of a digital input or digial output port.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lChan Always 0 for the PCI55xx Series, specifies the input port channel otherwise.
lMaskBits Selects the bits that the function will operate on. All bits set in the mask will
return their current state. Unselected mask bits will be set to zero.
Returns:
On success STATUS contains the current port data, otherwise ERRNUM contains the negative error code
that occurred during the call.
Note:
Digital IO Ports 0 & 1 for all supported hardware are only 8 bit ports. Digital Ports 2 & 3, for all except a
Pci5500 (which don’t have ports 2 & 3), are 16 bit ports. The lChan parameter for all Pci55xx boards
should be set to zero. All four digital ports are hardware programmable as either input or output ports and
can be represented by either DINx or DOTx, but not both. Port direction programming is determined by the
first call to either the AL_DigInput/AL_DigBitsTest functions for an input ports or the AL_DigOuput
function for an output port.
ERRNUM AL_API AL_DigOutput(LHLD lhld, long lChan, long lOutputData, long lMaskBits);
Visual Basic for Windows
Function AL_DigOutput(ByVal lhld As Long, ByVal lChan As Long,
ByVal lOutputData As Long,
ByVal lMaskBits As Long) As Long
LHLD lhld handle of the LDSD
long lChan specifies the output port channel number
long lOutputData specifies the data to be output
long lMaskBits specifies the output port masking bits
The AL_DigOutput function immediately sets a digital output port.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lChan Specifies the output port channel.
lOutputData Specifies the output data to be sent to the port.
lMaskBits Selects the bits that the function will operate on. All bits set in the mask will
be acted upon. Unselected bits in the mask will not change state.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the negative error code that occurred
during the call.
Note:
Digital IO channels 0 & 1 for all supported hardware are only 8 bit ports. Digital Channels 2 & 3, for all
except a Pci5500 (which don’t have ports 2 & 3), are 16 bit ports. The lChan parameter for all Pci55xx
boards should be set to zero. All four digital ports are hardware programmable as either input or output
ports and are represented by DOTx for output ports. Port direction programming is determined by the first
call to either the AL_DigInput or AL_DigOuput functions.
STATUS AL_API AL_DigBitsTest(LHLD lhld, long lChan, long lTestBits);
Visual Basic for Windows
Function AL_DigBitsTest(ByVal lhld As Long, ByVal lChan As Long,
ByVal lTestBits As Long) As Long
LHLD lhld handle of the LDSD
double lChanspecifies the input port channel number
long lTestBits specifies the input port bits to test
The AL_DigBitsTest function immediately retrieves input status of a digital input port.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lChan Specifies the input port channel.
lTestBits Selects the bits that the function will operate on. All bits set in the lTestBits
will be checked for a true (1) condition.
Note:
Digital IO channels 0 & 1 for all supported hardware are only 8 bit ports. Digital Channels 2 & 3, for all
except a Pci5500 (which don’t have ports 2 & 3), are 16 bit ports. The lChan parameter for all Pci55xx
boards should be set to zero. All four digital ports are hardware programmable as either input or output
ports and can be represented by either DINx or DOTx, but not both. Port direction programming is
determined by the first call to either the AL_DigInput/AL_DigBitsTest functions for an input ports or the
AL_DigOuput function for an output port.
Returns:
On success STATUS is set to one (1) if all of the lTestBits are true and set to zero (0) if any lTestBits are
false, otherwise STATUS contains the negative error code that occurred during the call.
Triggering allows the device acquisition to begin at some external event. Typically the device is completely
initialized and started then waits for an external event to trigger the device acquisition. The Pci5500 and
Pci55xx AtoD support the collecting data before a trigger, before and after a trigger or after a trigger. The
Pci55xx DtoA option supports support collecting data after a trigger.
Visual Basic for Windows
Function AL_SetTriggerMode(ByVal lhld As Long,
ByVal lpstrMode As String) As Long
LHLD lhld handle of the LDSD
LPSTR lpstrModeaddress of the trigger mode string
The AL_SetTriggerMode function sets the hardware trigger operation mode of the LDSD. For the 5500
and 55xx PCI series
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpstrMode Points to the desired trigger mode string. The available string settings are
device independent and are verified by ADLIB against the available trigger
mode options specified in the device's capabilities file.
Pci55xx Series Trigger Mode/Source Details:
MODE/SOURCE
DISABLED/DISABLED or
DISABLED/EXTERNAL – No external triggering. Acquisition starts with AL_StartDevice and
ends with AL_StopDevice.
POST_TRIG/DISABLED – INVALID setting, Post-Triggering requires an external trigger source.
POST_TRIG/EXTERNAL – Acquisition starts with the first external trigger after AL_StartDevice
and continues until completed.
PRE_TRIG/DISABLED Acquisition starts with AL_StartDevice and stops after receiving an
external trigger.
PRE_TRIG/EXTERNAL – Acquisition starts with the first external trigger after AL_StartDevice
and stops immediately after receiving the second external trigger.
ABOUT_TRIG/DISABLED – Acquisition starts with AL_StartDevice and after receiving an
external trigger, takes X more samples, then stops, where X is set with AL_SetPostSampleCount.
ABOUT_TRIG/EXTERNAL – Acquisition starts with the first external trigger after
AL_StartDevice and stops X samples after receiving the second external trigger, where X is set with
AL_SetPostSampleCount.
Chapter 20 Triggering Modes
19-2
Pci55xx Series Trigger and Buffer Considerations:
Depending on the number of Buffers and Cycle Mode specified, triggering maybe a continuous or single
cycle process for the “PRE_TRIG” and “ABOUT_TRIG” Modes. Because multiple buffers are available,
each buffer is considered individually in these trigger modes. Once a buffer completes, ADLIB moves on
to the next buffer and the whole triggering method begins again on that buffer and continues until all the
buffers are complete, or if in AL_CONTINUOUS CYCLE mode wrap to the first buffer and begins all
over again.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
Visual Basic for Windows
Function AL_SetTrigSourceSignal(ByVal lhld As Long,
ByVal lpstrSourceSignal As String) As Long
LHLD lhld handle of the LDSD
LPSTR lpstrSourceSignal address of the trigger source signal string
The AL_SetTrigSourceSignal function sets the hardware trigger source signal of the LDSD.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpstrSourceSignal Points to the desired trigger source signal string. The available string
settings are device independent and are verified by ADLIB against the
available trigger source signal options specified in the device's
capabilities file.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
ERRNUM AL_SetPostSampleCount(LHLD lhld, long lCount);
Visual Basic for Windows
Function AL_SetPostSampleCount(ByVal lhld As Long,
ByVal lCount As Long) As Long
LHLD lhld handle of the LDSD
long lCount specifies the number of sample counts
The AL_SetPostSampleCount fu nction sets the post trigger samples in the LDSD. This function is made
available for hardware devices that provide a post trigger counting mechanism. When the hardware device
receives a trigger, it provides (n) more samples, then stops. The post trigger samples specifies the number
of data samples to be obtained after a valid hardware trigger has been received.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lCount Sets the number of samples to be obtained after a trigger has been received. The available
ranges are device dependent and are verified by ADLIB against the min/max range
specified in the device's capabilities file.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
Visual Basic for Windows
Function AL_GetTriggerStruct(ByVal lhld As Long, lptrigStruct As TRIGGER) As Long
LHLD lhld handle of the LDSD
LPTRIG lptrigStruct address of the user trigger structure
The AL_GetTriggerStruct function provides access to all LDSD trigger settings.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lptrigStruct Specifies a 32 bit far pointer to a trigger information structure. This structure
has been pre-defined in the ADLIB include file and is defined as follows:
typedef struct tagTRIGGER
{
char achTrigModeName[MAX_OPTIONS_NAME_STRING];
long lTrigModeId;
char achTrigSrcName[MAX_OPTIONS_NAME_STRING];
long lTrigSrcId;
char achTrigSrcSignalName[MAX_OPTIONS_NAME_STRING];
long lTrigSrcSignalId;
long lTrigRateUnits;
double dTrigRate;
long lPostSampleCount;
}TRIGGER;
typedef TRIGGER FAR * LPTRIG;
Returns:
On success ERRNUM is set to 1 and the lptrigStruct structure is filled with the device's triggering settin gs,
otherwise ERRNUM contains the last error code that occurred during the call and the lptrigStruct structure
may contain invalid information.
Visual Basic for Windows
Function AL_SetTriggerOutput(ByVal lhld As Long,
ByVal lpstrMode As String) As Long
LHLD lhld handle of the LDSD
LPSTR lpstrModeaddress of the TriggerOutput mode string
The AL_SetTriggerOutput function sets the hardware TriggerOutput operation mode of the LDSD. For
the PCI 5500 and Pci55xx Series the AtoD device can be configured to output a signal when it has been
triggered. This allows multiple boards to be connected together which are triggered simultaneously form a
single trigger source that is daisy chained to additional boards.
For the Pci55xx Series the signal ADTGOUT is available to outpu t it’s trigger sour ce. Each time the ADC
is triggered from any of the available triggering sources the ADTGOUT signal pulses high for a period of
1 microsecond. This output can be used to synchronize the triggering of multiple A/D converters on
different PCI cards.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpstrMode Points to the desired TriggerOutput mode string. The available string settings
are
device independent and are verified by ADLIB against the available trigger
mode options specified in the device's capabilities file.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
ERRNUM AL_GetTriggerOutput(LHLD lhld, LPSTR lpstrTriggerOutput, long Maxlen);
Visual Basic for Windows
Function AL_GetTriggerOutput(ByVal lhld As Long, ByVal lpstrTriggerOutput As
String, ByVal lMaxlen As Long) As Long
LHLD lhld handle of the LDSD
LPSTR lpstrTriggerOutputdestination address of the TriggerOutput string
long lMaxLength the count in bytes to be copied
The AL_GetDataCode function retrieves the current TriggerOutput mode of the LDSD.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpstrTriggerOutput Points to the destination string for the copy.
lMaxLength Maximum length in bytes to be copied to the user string, including the
NULL termination character.
Returns:
On success ERRNUM is set to 1 and the destination string lpstrTriggerOutput is set to the LDSD
TriggerOutput mode, otherwise ERRNUM contains the last error code that occurred during the call and the
destination string is considered invalid.
Clocking Modes provides either accurate timed device conversions or software-controlled conversions.
The PCI55xx series the AtoD or DtoA devices can be clocked from one of four sources as specified below,
in addition the DAC1 device can be clocked for the same clocking source selected by DAC0. To use the
AL_SetDAOutput function with the Pci55xx DAC0 or DAC1 the clocking source must also be configured
for “SOFTWARE_CONVERT”, in addition DAC0’s Trigger and Gating modes must be DISABLED.
Visual Basic for Windows
Function AL_GetActualClkRate(ByVal lhld As Long, ByVal dActaulRate As Double)
As Long
LHLD lhld handle of the LDSD
double dActualRate points to a double value to receiving the value.
The AL_GetActualClkRate function is used to determine the frequency actually available by a device's
clocking hardware. The clock frequency specified in the AL_SetClockRate.vi function may not be
achievable due to hardware limitations.
Note: The AL_SetClockRate clocking rate parameters are not progr ammed to a device until it initialized
with AL_InitializeDevice. This function uses the clocking rate parameters from the last call to the
AL_SetClockRate function to determine the actual available hardware rate and does not reflect the current
devices programmed rate until the device has been initialized. Once a device has been initialized, if the
AL_SetClockRate is called again with different clocking rate parameters this function will n ot return the
current device's programmed clocking frequency until the device is re-initialized. Therefore this function
only returns the actual rate that can be set by the AL_SetClockRate function. To get the current Clocking
Rate programmed to the device, it must be initialized before calling this function.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
dActualRate Contains the actual hardware clocking rate.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
Visual Basic for Windows
Function AL_GetClockStruct(ByVal lhld As Long, lpclkStruct As CLOCK) As Long
LHLD lhld handle of the LDSD
LPTRIG lpclkStruct address of the user clock structure
The AL_GetClockStruct function provides access to all LDSD clock settings.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpclkStruct Specifies a 32 bit far pointer to a clocking information structure. This structure
has been pre-defined in the ADLIB include file and is defined as follows:
typedef struct tagCLOCK
{
char achClkSourceName[MAX_OPTIONS_NAME_STRING];
long lClkSourceId;
char achClkSrcSignalName[MAX_OPTIONS_NAME_STRING];
long lClkSrcSignalId;
double dClkRate;
long lClkRateUnits;
}CLOCK;
typedef CLOCK FAR * LPCLK;
Returns:
On success ERRNUM is set to 1 and the lpclkStruct structure is filled with the d evice's clocking settings,
otherwise ERRNUM contains the last error code that occurred during the call and the lpclkStruct structure
may contain invalid information.
Visual Basic for Windows
Function AL_SetClockOutput(ByVal lhld As Long,
ByVal lpstrMode As String) As Long
LHLD lhld handle of the LDSD
LPSTR lpstrModeaddress of the ClockOutput mode string
The AL_SetClockOutput function sets the hardware ClockOutput operation mode of the LDSD.
For the Pci55xx Series the signal ADCLKOUT is available to output it’s clocking source. Each time the
ADC is clocked from any of the available clocking sources the ADCLKOUT signal pulses high for a
period of 1 microsecond. This output can be used to synchronize the clocking of multiple A/D converters
on different PCI cards.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpstrMode Points to the desired ClockOutput string. The available string settings are device
independent and are verified by ADLIB against the available clock output
mode
options specified in the device's capabilities file.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
ERRNUM AL_GetClockOutput(LHLD lhld, LPSTR lpstrClockOutput, long lMaxlen);
Visual Basic for Windows
Function AL_GetClockOutput(ByVal lhld As Long, ByVal lpstrClockOutput As String,
ByVal lMaxlen As Long) As Long
LHLD lhld handle of the LDSD
LPSTR lpstrClockOutputdestination address of the ClockOutput string
long lMaxLength the count in bytes to be copied
The AL_GetClockOutput function retrieves the current ClockOutput state of the LDSD.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpstrClockOutput Points to the destination string for th e copy.
lMaxLength Maximum length in bytes to be copied to the user string , including the
NULL termination character.
Returns:
On success ERRNUM is set to 1 and the destination string lpstrClockOutput is set to the LDSD
ClockOutput state, otherwise ERRNUM contains the last error code that occurred during the call and the
destination string is considered invalid.
Gating allows either software or an external signal to enable or disable a devices clocking source.
The Pci55xx series AtoD and DtoA support the gating features. The “SWGATE” may be used to allow the
starting and stopping of either ADC0 or DAC1. The “SWGATE” mode may not be used to control the
external clock input (ADCLKIN). The “EXTGATE“ mode allows the ADC clock to be “switched (On and
Off) with the external ADTGIN input. The input is level sensitive and selectable as either active high or
active low control. If the on-board pacer clock drives the ADC, the external gate input is used to enable
and disable the ADC’s pacer clock after being polarity conditioned. The ADC clock will be enabled as
long as the gate input is in the active state.
Visual Basic for Windows
Function AL_GetGateStruct(ByVal lhld As Long, lpgateStruct As GATE) As Long
LHLD lhld handle of the LDSD
LPGATE lpgateStruct address of the user gate structure
The AL_GetGateStruct function provides access to all LDSD gate settings.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpgateStruct Specifies a 32 bit far pointer to a gate information structure. This structure has
been pre-defined in the ADLIB include file and is defined as follows:
typedef struct tagGATE
{
char achGateSourceName[MAX_OPTIONS_NAME_STRING];
long lGateSourceId;
long lGateLevel;
}GATE;
typedef GATE FAR * LPGATE;
Returns:
On success ERRNUM is set to 1 and the lpgateStruct structur e is filled with the device's gate settings,
otherwise ERRNUM contains the last error code that occurred during the call and the lpgateStruct structure
may contain invalid information.
Burst Mode uses a separate Burst Rate clock to initiate conversions. For the Pci55xx Series the Burst Rate
is defined as the time between ADC conversions and the duration of the burst is defined Burst Length.
When burst mode is enabled, each burst will be started by any of the three previously mentioned clock
sources, essentially the Clocking Source becomes the trigger of each Burst.
ERRNUM AL_SetBurstLength(LHLD lhld, long lBurstSamples);
Visual Basic for Windows
Function AL_SetBurstLength(ByVal lhld As Long,
ByVal lBurstSamples As Long) As Long
LHLD lhld handle of the LDSD
long lBurstSamples specifies the number of burst samples
The AL_SetBurstLength function sets the number of samples obtained during a burst in the LDSD. This
function is made available for hardware devices that provide burst length mechanism. When the hardware
device starts a burst, it provides (n) more samples, and then stops. The Burst samples specify the number of
data samples to be obtained after a valid hardware burst trigger.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lBurstSamples Sets the number of samples to be obtained after a Burst has been received. The
available range is device independent and is verified by ADLIB against the
min./max. burst length specified in the device's capabilities file.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
Related Functions:
AL_SetBurstMode
AL_SetBurstRate
AL_GetBurstStruct
Supported Logical Device Subsystems:
Pci55xx Series: ADC0, Options: valid values are from 1 to 65535 where the actual Burst Length is set to
(65536 - lBurstSamples).
Chapter 23 Burst Modes
22-3
22.3 AL_SetBurstRate
Prototype C\C++
ERRNUM AL_SetBurstRate(LHLD lhld, double dRate, long lUnits);
Visual Basic for Windows
Function AL_SetBurstRate(ByVal lhld As Long, ByVal dRate As Double,
ByVal lUnits As Long) As Long
LHLD lhld handle of the LDSD
double dRatespecifies the rate of burst clocks
long lUnits specifies the rate units
The AL_SetBurstRate function sets the hardware Burst rate clock of the LDSD.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
dRate Specifies the rate at which a burst clock will occur.
lUnits Sets the units in which the above rate parameter is specified. The available settings are
defined as AL_HERTZ or AL_TICS in the ADLIB include file.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the
call.
Supported Logical Device Subsystems:
Pci55xx Series: ADC0, Options: 1 to 65535 when specified in Tics where the actual
Burst Rate is set to (1,000,000 / (65536 – dRate)).
15.259 to max board speed when specified in Hertz.
(For both TICS and HERTZ, the actual max. speed
depends on the board type and gain selections. Please
refer to your hardware manual for details.
Visual Basic for Windows
Function AL_GetBurstStruct(ByVal lhld As Long, lpburstStruct As BURST) As Long
LHLD lhld handle of the LDSD
LPBURST lpburstStruct address of the user burst structure
The AL_GetBurstStruct function provides access to all LDSD burst settings.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpburstStruct Specifies a 32 bit far pointer to a Burst information structure. This
structure has been pre-defined in the ADLIB include file and is defined
as follows:
typedef struct tagBURST
{
char achBurstModeName[MAX_OPTIONS_NAME_STRING];
long lBurstModeId;
long lBurstRateUnits;
double dBurstRate;
long lBurstSamples;
}BURST;
typedef BURST FAR * LPBURST;
Returns:
On success ERRNUM is set to 1 and the lpburstStruct structure is filled with the device's burst setting s,
otherwise ERRNUM contains the last error code that occurred during the call and the lpburstStruct
structure may contain invalid information.
Channel selection allows the random ordering of channels to be programmed into the board channel RAM
list.
The Pci5500MF has 8 channels of single-ended analog inputs multiplexed to a 12-bit A/D converter and
supported by 176 elements of channel list RAM. This allows the board to access channels 0 to 7 in any
order.
The Pci55xx Series has 16 channels of analog inputs with programmable gain that’s multiplexed to the 12
or 16-bit A/D converter and supported by 176 elements of channel list RAM. This allows the board to
access channels and gains from 0 to 7 Differential and 0-15 Single Ended or Pseudo Differential in any
order.
Visual Basic for Windows
Function AL_SetChannelList(ByVal lhld As Long, lpchanlist As CHANLIST) As Long
LHLD lhld handle of the LDSD
LPCHANLIST lpchanlist address of the user channel list structure
The AL_SetChannelList function sets the active channel and gain settings in the LDSD. If a device
supports gain settings, the list is considered a channel and gain list, and must be set appropriately. See
examples below.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpchanlist Specifies a 32 bit far pointer to a channel information structure. This
structure has been predefined in the ADLIB include file and is defined
as follows:
typedef struct tagCHANLIST
{
long lType; /* 0 = Not Defined */
/* 1 = Use string list */
/* 2 = Use array of numbers */
char achChannelList[MAX_CHANLIST_STRLEN];
long lNumElements;
long alChannelList[MAX_CHANLIST_ARRAYLEN];
}CHANLIST;
typedef CHANLIST FAR * LPCHANLIST;
Chapter 24 Channel Selections
23-2
Returns:
On success ERRNUM is set to 1 and the information contained in th e lpchanlist structure is transferred to
the LDSD, otherwise ERRNUM contains the last error code that occurred during the call.
Visual Basic for Windows
Function AL_GetChannelList(ByVal lhld As Long, lpchanlist As CHANLIST) As Long
LHLD lhld handle of the LDSD
LPCHANLIST lpchanlist address of the user channel list structure
The AL_GetChannelList function retrieves the current LDSD channel and gain settings. If a device
supports gain settings, the list is considered a channel and gain list, and will be set in a channel then gain
sequence. See examples below.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpchanlist Specifies a 32 bit far pointer to a channel information structure. The structure
has been predefined in the ADLIB include file and is defined as follows:
typedef struct tagCHANLIST
{
long lType; /* 0 = Not Defined */
/* 1 = Use string list */
/* 2 = Use array of numbers */
char achChannelList[MAX_CHANLIST_STRLEN];
long lNumElements;
long alChannelList[MAX_CHANLIST_ARRAYLEN];
}CHANLIST;
typedef CHANLIST FAR * LPCHANLIST;
Returns:
On success ERRNUM is set to 1 and the lpchanlist structure is filled with the device's channel list settings,
otherwise ERRNUM contains the last error code that occurred during the call, and the lpchanlist structure
may contain invalid information.
Visual Basic for Windows
Function AL_GetMinStartChan(ByVal lhld As Long) As Long
LHLD lhld handle of the LDSD
The AL_GetMinStartChan function retrieves the current LDSD minimum starting channel for a device
subsystem.
Parameter Description
lhld Identifies the instance of the logical device subsystem from which the status is to be
retrieved.
Returns:
On success STATUS is set to LDSD minimum starting channel for that device subsystem, otherwise
STATUS contains a negative error code that occurred during the call.