Measurement ADLIB WIN User Manual

ADLIB WIN Interface Library Software

User’s Manual for ADAC PCI Data Acquisition Boards
the smart approach to instrumentation
IOtech, Inc.
25971 Cannon Road
Cleveland, OH 44146-1833
Fax: (440) 439-4093
E-mail (sales):
sales@iotech.com
E-mail (post-sales): productsupport@iotech.com
Internet:
www.iotech.com
ADLIB WIN
© 2002 by IOtech, Inc. June 2004 Printed in the United States of America
Interface Library Software
for ADAC PCI Data Acquisition Boards
1107-0902 Rev 2.0
p/n
DAQ Board API Functions Version 4.00 06/20/2004

Contents

1. INTRODUCTION ......................................................................................1-1
1.1 OVERVIEW.................................................................................................................... 1-1
1.2 SYSTEM REQUIREMENTS .......................................................................................... 1-2
1.3 APPLICATION LANGUAGE REQUIREMENTS........................................................... 1-2
2. INSTALLATION........................................................................................2-1
2.1 INSTALLATION FROM WINDOWS for PCI CARD SUPPORT................................... 2-1
2.2 SUMMARY OF DISK FILES FOR ADLIB WDM PCI CARD SUPPORT...................... 2-2
3. CONFIGURATION, CAPABILITIES AND INITIALIZATION FILES .........3-3
3.1 CONFIGURATION (.CON) FILE ................................................................................... 3-3
i
3.2 CAPABILITIES (.CAP) FILE ......................................................................................... 3-3
3.3 INITIALIZATION (.INI) FILE .......................................................................................... 3-3
4. APPLICATION DEVELOPMENT .............................................................4-1
4.1 OVERVIEW.................................................................................................................... 4-1
4.2 OPERATING MODES.................................................................................................... 4-1
4.3 LOGICAL DEVICES...................................................................................................... 4-3
5. PROGRAM DEVELOPMENT...................................................................5-1
5.1 INCLUDING ADLIB WIN IN C\C++............................................................................... 5-1
5.1.1 Steps To Programming In C\C++ ........................................................................... 5-1
5.2 INCLUDING ADLIB WIN IN VISUAL BASIC FOR WINDOWS.................................... 5-2
5.2.1 Steps to Programming in Visual Basic For Windows............................................. 5-2
5.3 EXAMPLE PROGRAMS ............................................................................................... 5-4
6. MEMORY BUFFER ALLOCATION..........................................................6-1
6.1 OVERVIEW.................................................................................................................... 6-1
6.2 POLLING or DMA SYSTEM BUFFER ALLOCATION................................................. 6-1
Contents
ii
6.3 THE BUFFER STRUCTURE......................................................................................... 6-1
6.4 BUFFER NOTIFICATIONS ........................................................................................... 6-3
6.4.1 C\C++...................................................................................................................... 6-3
6.4.2 Visual Basic for Windows ....................................................................................... 6-4
7. DYNAMIC LINKING TO ADLIB WIN........................................................7-1
7.1 IMPLICIT LINKING C\C++ ............................................................................................ 7-1
7.2 EXPLICIT LINKING C\C++............................................................................................ 7-1
7.3 VISUAL BASIC FOR WINDOWS.................................................................................. 7-1
8. ERROR HANDLING.................................................................................8-1
8.1 OVERVIEW.................................................................................................................... 8-1
8.2 ERROR CONTROL CONDITIONS ............................................................................... 8-1
9. ENVIRONMENT CONFIGURATIONS......................................................9-1
9.1 AL_LoadEnvironment.................................................................................................. 9-1
9.2 AL_ReleaseEnvironment............................................................................................. 9-2
9.3 AL_SetEnvString.......................................................................................................... 9-3
9.4 AL_GetEnvString ......................................................................................................... 9-4
10. BOARD FUNCTIONS.............................................................................10-1
10.1 AL_GetBoardHardwareId ...................................................................................... 10-1
10.2 AL_GetBoardDriverVersion................................................................................... 10-2
10.3 AL_SetBoardString ................................................................................................ 10-3
10.4 AL_GetBoardString................................................................................................ 10-4
10.5 AL_GetBoardName ................................................................................................ 10-5
10.6 AL_GetMfgProductId ............................................................................................. 10-6
11. LOGICAL DEVICE ALLOCATIONS.......................................................11-1
11.1 AL_AllocateDevice ................................................................................................. 11-1
Contents
11.2 AL_ReleaseDevice.................................................................................................. 11-3
11.3 AL_SetLdsString .................................................................................................... 11-4
11.4 AL_GetLdsString....................................................................................................11-5
iii
12. LOGICAL DEVICE INITIALIZATIONS ...................................................12-1
12.1 AL_InitDevice.......................................................................................................... 12-1
13. LOGICAL DEVICE START / STOP OPERATIONS...............................13-2
13.1 AL_StartDevice.......................................................................................................13-2
13.2 AL_StopDevice ....................................................................................................... 13-3
14. LOGICAL DEVICE CYCLE MODES ......................................................14-1
14.1 AL_SetCycleMode .................................................................................................. 14-1
14.2 AL_GetCycleMode.................................................................................................. 14-2
15. LOGICAL DEVICE TRANSFER METHODS..........................................15-1
15.1 AL_SetDataTransferMethod..................................................................................15-1
15.2 AL_GetDataTransferMethod.................................................................................. 15-2
16. LOGICAL DEVICE STATUS INFORMATION........................................16-1
16.1 AL_GetDeviceStatus.............................................................................................. 16-1
17. ANALOG OUTPUT.................................................................................17-1
17.1 AL_SetDaOutput..................................................................................................... 17-1
18. DIGITAL INPUT/OUTPUT......................................................................18-1
18.1 AL_DigInput ............................................................................................................ 18-1
18.2 AL_DigOutput ......................................................................................................... 18-2
18.3 AL_DigBitsTest....................................................................................................... 18-3
19. TRIGGERING MODES...........................................................................19-1
Contents
iv
19.1 AL_SetTriggerMode ............................................................................................... 19-1
19.2 AL_SetTriggerSource ............................................................................................ 19-3
19.3 AL_SetTrigSourceSignal ....................................................................................... 19-4
19.4 AL_SetPostSampleCount...................................................................................... 19-5
19.5 AL_GetTriggerStruct.............................................................................................. 19-6
19.6 AL_SetTriggerOutput............................................................................................. 19-7
19.7 AL_GetTriggerOutput ............................................................................................ 19-8
20. CLOCKING MODES...............................................................................20-1
20.1 AL_SetClockSource ............................................................................................... 20-1
20.2 AL_SetClockRate ................................................................................................... 20-2
20.3 AL_GetActualClkRate ............................................................................................ 20-3
20.4 AL_MaxClkRate ...................................................................................................... 20-4
20.5 AL_GetClockStruct ................................................................................................ 20-5
20.6 AL_SetClockOutput ............................................................................................... 20-6
20.7 AL_GetClockOutput............................................................................................... 20-7
21. GATING MODES....................................................................................21-1
21.1 AL_SetGateSource................................................................................................. 21-1
21.2 AL_SetGateLevel....................................................................................................21-2
21.3 AL_GetGateStruct .................................................................................................. 21-3
21.4 AL_SetSwGate........................................................................................................ 21-4
21.5 AL_GetSwGate ....................................................................................................... 21-5
22. BURST MODES .....................................................................................22-1
22.1 AL_SetBurstMode .................................................................................................. 22-1
22.2 AL_SetBurstLength................................................................................................ 22-2
22.3 AL_SetBurstRate.................................................................................................... 22-3
22.4 AL_GetBurstStruct................................................................................................. 22-4
Contents
23. CHANNEL SELECTIONS.......................................................................23-1
23.1 AL_SetChannelList ................................................................................................ 23-1
23.2 AL_GetChannelList ................................................................................................ 23-3
23.3 AL_SetMinStartChan.............................................................................................. 23-5
23.4 AL_GetMinStartChan ............................................................................................. 23-6
23.5 AL_SetMaxEndChan .............................................................................................. 23-7
23.6 AL_GetMaxEndChan.............................................................................................. 23-8
23.7 AL_SetGainGlobal..................................................................................................23-1
24. INPUT CONFIGURATIONS....................................................................24-1
24.1 AL_SetInputConfigList .......................................................................................... 24-1
v
24.2 AL_GetInputConfigList.......................................................................................... 24-3
24.3 AL_SetInputConfigGlobal...................................................................................... 24-5
25. DATA OFFSETS ....................................................................................25-1
25.1 AL_SetDataOffsetList ............................................................................................ 25-1
25.2 AL_GetDataOffsetList............................................................................................ 25-3
25.3 AL_SetDataOffsetGlobal........................................................................................ 25-5
26. COUNTER / TIMERS..............................................................................26-1
26.1 AL_SetCtrMode....................................................................................................... 26-1
26.2 AL_GetCtrMode ...................................................................................................... 26-2
26.3 AL_CounterIn.......................................................................................................... 26-1
26.4 AL_CounterOut....................................................................................................... 26-2
27. BUFFER HANDLER FUNCTIONS......................................................... 27-1
27.1 AL_ClearBufferDoneFlag....................................................................................... 27-1
27.2 AL_GetDoneBuffPtr ............................................................................................... 27-2
27.3 AL_GetBuffPtr......................................................................................................... 27-3
Contents
vi
27.4 AL_CopyBuffer ....................................................................................................... 27-4
27.5 AL_SetBuffer........................................................................................................... 27-5
27.6 AL_GetBufferStatus............................................................................................... 27-6
27.7 AL_SetBufferDoneHandler....................................................................................27-7
27.8 AL_GetBufferDoneHandler.................................................................................... 27-9
27.9 AL_SetBufferDoneHandlerMsg........................................................................... 27-10
27.10 AL_GetBufferDoneHandlerMsg .......................................................................... 27-11
27.11 AL_SetBufferDoneHandlerFunc ......................................................................... 27-12
27.12 AL_SetBufferDoneHandlerParams..................................................................... 27-13
27.13 AL_SetNumOfBuffers .......................................................................................... 27-14
27.14 AL_GetNumOfBuffers.......................................................................................... 27-15
27.15 AL_SetBufferSize ................................................................................................. 27-16
27.16 AL_GetBufferSize................................................................................................. 27-17
27.17 AL_SetAutoInitBuffers......................................................................................... 27-18
27.18 AL_GetAutoInitBuffers ........................................................................................ 27-19
27.19 AL_SetPackedData............................................................................................... 27-20
27.20 AL_GetPackedData .............................................................................................. 27-21
28. DATA FORMATTING FUNCTIONS:......................................................28-1
28.1 AL_DemuxData.......................................................................................................28-1
28.2 AL_DemuxDataSet ................................................................................................. 28-2
29. ERROR HANDLING FUNCTIONS .........................................................29-1
29.1 AL_SetErrOnReInitRunning .................................................................................. 29-1
29.2 AL_GetErrOnReInitRunning.................................................................................. 29-2
29.3 AL_SetErrOnReleaseRunning............................................................................... 29-3
29.4 AL_GetErrOnReleaseRunning .............................................................................. 29-4
29.5 AL_GetBoardError ................................................................................................. 29-5
Contents
vii
30. ADLIB ERROR CODES .........................................................................30-1
31. BOARD DRIVER ERROR CODES.........................................................31-1
viii
Contents
Chapter 1 Introduction
1-1
1. INTRODUCTION
1.1 OVERVIEW
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” system­wide 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 errors flags */ if (lpbuff->lErrorFlags != 0) OnBufferError(lpbuff);
/* 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. */
errnum = AL_SetCycleMode(lhldAdc0, AL_SINGLE_CYCLE); errnum = AL_SetTriggerMode(lhldAdc0, “POST_TRIG”); errmum = AL_SetNumOfBuffers(lhldAdc0, 1); errmum = AL_SetBufferSize(lhldAdc0, 1000);
. .
/* 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.
C\C++ adlib.h file
typedef struct tagDATABUFFER { DWORD dwBufferType;
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 library adlcore.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.
IMPORTS ADLCORE.AL_LoadEnvironment ADLCORE.AL_ReleaseEnvironment . . .
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.
AL_SetErrOnReleaseRunning AL_GetErrOnReleaseRunning AL_SetErrOnReInitRunning AL_GetErrOnReInitRunning
Chapter 8 Error Handling
8-2
Chapter 9 Environment Configurations
9-1
9. ENVIRONMENT CONFIGURATIONS
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.
9.1 AL_LoadEnvironment Prototype C\C++
ERRNUM AL_LoadEnvironment(LPSTR lpstrEnvInfoSource);
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
lpstrEnvInfoSource Points 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 Windows Function 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.
Related Functions:
NONE
Program References:
NONE
Supported Boards: All
Chapter 10 Board Functions
10-3
10.3 AL_SetBoardString Prototype C\C++
ERRNUM AL_SetBoardString(BRDID brdid, LPSTR lpstrBrd);
Visual Basic for Windows
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
lpstrLogDev Points 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.
lBoardId Specifies 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.
Related Functions:
AL_AllocateDevice
Program References:
ALL
Supported Logical Device Subsystems: All
Chapter 12 Logical Device String Names
11-4
11.3 AL_SetLdsString Prototype C\C++
ERRNUM AL_SetLdsString(LHLD lhld, LPSTR lpstrLds);
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.
Related Functions:
AL_StopDevice
Program References:
Adlai01, Adlai02, Adlai04, Adlai05, Adlai07, Adlai08 Adlda02, Adlda03
Supported Logical Device Subsystems: Pci55xx Series: ADC0, DAC0, DAC1,
Chapter 14 Logical Device Start / Stop Operations
13-3
13.2 AL_StopDevice Prototype C\C++
ERRNUM AL_StopDevice(LHLD lhld);
Visual Basic for Windows
Function AL_StopDevice(ByVal lhld As Long) As Long
LHLD lhld handle of the LDSD to be stopped

The AL_StopDevice function disables the current acquisition and all logical device operations are stopped.

Parameter Description
lhld Identifies the instance of the logical device subsystem to be stopped.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the call.
Related Functions:
AL_StartDevice
Program References:
Adlai01, Adlai02, Adlai04, Adlai05, Adlai07, Adlai08 Adlda02, Adlda03
Supported Logical Device Subsystems: Pci55xx Series: ADC0, DAC0, DAC1
Chapter 15 Logical Device Cycle Modes
14-1
14. LOGICAL DEVICE CYCLE MODES
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.
14.1 AL_SetCycleMode Prototype C\C++
ERRNUM AL_SetCycleMode(LHLD lhld, LPSTR lpstrMode);
Visual Basic for Windows Function AL_SetCycleMode(ByVal lhld As Long, ByVal lpstrMode As String) As Long
LHLD lhld handle of the LDSD LPSTR lpstrMode address of the cycle mode string

The AL_SetCycleMode function sets the software cycle operation mode of the LDSD. See section

OPERATING MODES for additional details.
4.2
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpstrMode Points to the desired cycle mode string. The available settings are defined
in the ADLIB include file as follows:
AL_SINGLE_CYCLE complete acquisition and stop
AL_CONTINUOUS_CYCLE repeat acquisition
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the call.
Related Functions:
AL_GetCycleMode
Program References:
Adlai01, Adlai02, Adlai04, Adlai05, Adlai07, Adlai08 Adlda01, Adlda02, Adlda03
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 lpstrMode destination 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.
15.1 AL_SetDataTransferMethod Prototype C\C++
ERRNUM AL_SetDataTransferMethod(LHLD lhld, LPSTR lpstrMethod);
Visual Basic for Windows Function AL_SetDataTransferMethod(ByVal lhld As Long, ByVal lpstrMethod As String) As Long
LHLD lhld handle of the LDSD LPSTR lpstrMethod address of the transfer method string

The AL_SetDataTransferMethod function sets the hardware transfer operation method of the LDSD. See section

4.2 OPERATING MODES for additional details.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpstrMethod Points to the desired transfer mode string. The available settings are defined
in the ADLIB include file as follows:
AL_DTM_SOFTWARE software data transfers
AL_DTM_DMA DMA data transfers
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the call.
Related Functions:
AL_GetDataTransferMethod
Program References:
Adlai01, Adlai02, Adlai04, Adlai05, Adlai07, Adlai08 Adlda01, Adlda02, Adlda03
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 lpstrMode destination 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.
Related Functions:
NONE
Program References:
Adlda01
Supported Logical Device Subsystems: Pci55xx Series: DAC0, DAC1
Chapter 18 Analog Output
17-2
Chapter 19 Digital Input/Output
18-1
18. DIGITAL INPUT/OUTPUT
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 lChan specifies 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.
Related Functions:
AL_DigBitsTest
Program References:
Adldio01, Adldio23
Supported Logical Device Subsystems: Pci5500: DIN0, DIN1, DOT0, DOT1 Pci55xx Series: DIN0, DIN1, DIN2, DIN3, DOT0, DOT1, DOT2, DOT3
Program References:
Adldio01, Adldio23
Chapter 19 Digital Input/Output
18-2
18.2 AL_DigOutput Prototype C\C++
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.
Related Functions:
AL_DigInput AL_DigBitsTest
Program References:
Adldio01, Adldio23
Supported Logical Device Subsystems: Pci5500: DOT0, DOT1 Pci55xx Series: DOT0, DOT1, DOT2, DOT3
Program References:
Adldio01, Adldio23
Chapter 19 Digital Input/Output
18-3
18.3 AL_DigBitsTest Prototype C\C++
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 lChan specifies 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.
Related Functions:
AL_DigInput AL_DigOutput
Program References:
Adldio01, Adldio23
Supported Logical Device Subsystems: Pci5500: DIN0, DIN1, DOT0, DOT1 Pci55xx Series: DIN0, DIN1, DIN2, DIN3, DOT0, DOT1, DOT2, DOT3
Chapter 19 Digital Input/Output
18-4
Chapter 20 Triggering Modes
19-1
19. TRIGGERING MODES
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.
19.1 AL_SetTriggerMode Prototype C\C++
ERRNUM AL_SetTriggerMode(LHLD lhld, LPSTR lpstrMode);
Visual Basic for Windows Function AL_SetTriggerMode(ByVal lhld As Long, ByVal lpstrMode As String) As Long
LHLD lhld handle of the LDSD LPSTR lpstrMode address 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.
Related Functions:
AL_SetTriggerSource AL_SetTrigSourceSignal AL_SetPostSampleCount AL_GetTriggerStruct AL_SetTriggerOutput AL_GetTriggerOutput
Supported Logical Device Subsystems: Pci55xx Series: ADC0, Options: DISABLED, “POST_TRIG”, “PRE_TRIG”
or ABOUT_TRIG
Pci55xx Series: DAC0, Options: DISABLED, “POST_TRIG”
Chapter 20 Triggering Modes
19-3
19.2 AL_SetTriggerSource Prototype C\C++
ERRNUM AL_SetTriggerSource(LHLD lhld, LPSTR lpstrSource);
Visual Basic for Windows Function AL_SetTriggerSource(ByVal lhld As Long, ByVal lpstrSource As String) As Long
LHLD lhld handle of the LDSD LPSTR lpstrSource address of the trigger source string

The AL_SetTriggerSource function sets the hardware trigger source of the LDSD.

Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpstrSource Points to the desired trigger source string. The available string settings are
device independent and are verified by ADLIB against the available trigger source 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.
Related Functions:
AL_SetTriggerMode AL_SetTrigSourceSignal AL_SetPostSampleCount AL_GetTriggerStruct AL_SetTriggerOutput AL_GetTriggerOutput
Supported Logical Device Subsystems: Pci55xx Series: ADC0, DAC0, Options: DISABLED or “EXTERNAL”
Chapter 20 Triggering Modes
19-4
19.3 AL_SetTrigSourceSignal Prototype C\C++
ERRNUM AL_SetTrigSourceSignal(LHLD lhld, LPSTR lpstrSourceSignal);
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.
Related Functions:
AL_SetTriggerMode AL_SetTriggerSource AL_SetPostSampleCount AL_GetTriggerStruct AL_SetTriggerOutput AL_GetTriggerOutput
Supported Logical Device Subsystems: Pci55xx Series: ADC0, DAC0, Options: “FALLING_EDGE“ or “RISING_EDGE“
Chapter 20 Triggering Modes
19-5
19.4 AL_SetPostSampleCount Prototype C\C++
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.
Related Functions:
AL_SetTriggerMode AL_SetTriggerSource AL_SetTrigSourceSignal AL_GetTriggerStruct AL_SetTriggerOutput AL_GetTriggerOutput
Supported Logical Device Subsystems: Pci55xx Series: ADC0, Options: 0 to 65535 “ABOUT_TRIG” Triggermode
Chapter 20 Triggering Modes
19-6
19.5 AL_GetTriggerStruct Prototype C\C++
ERRNUM AL_GetTriggerStruct(LHLD lhld, LPTRIG lptrigStruct);
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.
Related Functions:
AL_SetTriggerMode AL_SetTriggerSource AL_SetTrigSourceSignal AL_SetPostSampleCount AL_SetTriggerOutput AL_GetTriggerOutput
Supported Logical Device Subsystems:
Pci55xx Series: ADC0, DAC0
Chapter 20 Triggering Modes
19-7
19.6 AL_SetTriggerOutput Prototype C\C++
ERRNUM AL_SetTriggerOutput(LHLD lhld, LPSTR lpstrMode);
Visual Basic for Windows Function AL_SetTriggerOutput(ByVal lhld As Long, ByVal lpstrMode As String) As Long
LHLD lhld handle of the LDSD LPSTR lpstrMode address 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.
Related Functions:
AL_SetTriggerMode AL_SetTriggerSource AL_SetTrigSourceSignal AL_SetPostSampleCount AL_GetTriggerStruct AL_GetTriggerOutput
Supported Logical Device Subsystems: Pci55xx Series: ADC0, Options: ENABLED, DISABLED
Chapter 20 Triggering Modes
19-8
19.7 AL_GetTriggerOutput Prototype C\C++
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 lpstrTriggerOutput destination 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.
Related Functions:
AL_SetTriggerMode AL_SetTriggerSource AL_SetTrigSourceSignal AL_SetPostSampleCount AL_GetTriggerStruct AL_SetTriggerOutput
Supported Logical Device Subsystems: Pci55xx Series: ADC0
Chapter 21 Clocking Modes
20-1
20. CLOCKING MODES
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.
20.1 AL_SetClockSource Prototype C\C++
ERRNUM AL_SetClockSource(LHLD lhld, LPSTR lpstrSource);
Visual Basic for Windows
Function AL_SetClockSource(ByVal lhld As Long, ByVal lpstrSource As String) As Long
LHLD lhld handle of the LDSD LPSTR lpstrSource address of the clock source string

The AL_SetClockSource function sets the hardware clocking source of the LDSD.

Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpstrSource Points to the desired clock source string. The available string settings are
device independent and are verified by ADLIB against the available clock source 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.
Related Functions:
AL_SetClockRate AL_GetActualClkRate AL_MaxClkRate AL_GetClockStruct
Supported Logical Device Subsystems: Pci55xx Series: ADC0,Options: “SOFTWARE_CONVERT“, “INTERNAL“,
“EXT_RISING_EDGE“ or “EXT_FALLING_EDGE“
Pci55xx Series: DAC0, DAC1Options: “SOFTWARE_CONVERT“, “INTERNAL“,
“EXT_RISING_EDGE“ or “EXT_FALLING_EDGE“
Pci55xx Series: DAC1 Options: In addition, setting DAC1 clock source to
“CLKSCR_DAC0_SELECTED“ will synchronize DAC1 to DAC0 clocking source.
Chapter 21 Clocking Modes
20-2
20.2 AL_SetClockRate Prototype C\C++
ERRNUM AL_SetClockRate(LHLD lhld, double dRate, long lUnits);
Visual Basic for Windows Function AL_SetClockRate(ByVal lhld As Long, ByVal dRate As Double, ByVal lUnits As Long) As Long
LHLD lhld handle of the LDSD double dRate specifies the rate of the clock long lUnits specifies the rate units

The AL_SetClockRate function sets the hardware clocking rate of the LDSD.

Parameter Description
lhld Identifies the instance of the logical device subsystem.
dRate Specifies the rate at which a clocking will occur.
lUnits Sets the units in which the above rate parameter is specified. The available
settings are defined as AL_HERTZ.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the call.
Related Functions:
AL_SetClockSource AL_GetActualClkRate AL_MaxClkRate AL_GetClockStruct
Supported Logical Device Subsystems: Pci5500, 5501, 5502: ADC0, Options: 0.23283e-3 to 100000 Pci5500, 5501, 5502: DAC0, DAC1, Options: 0.23283e -3 to 200000 Pci5503, 5504: ADC0, Options: 0.23283e -3 to 200000 Pci5503, 5504, DAC0, DAC1, Options: 0.23283e -3 to 200000
Chapter 21 Clocking Modes
20-3
20.3 AL_GetActualClkRate Prototype C\C++
(32 bit) ERRNUM AL_GetActualClkRate(LHLD lhld, double *dActualRate);
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.
Related Functions:
AL_SetClockSource AL_SetClockRate AL_MaxClkRate AL_GetClockStruct
Supported Logical Device Subsystems: Pci55xx Series: ADC0, DAC0, DAC1
Chapter 21 Clocking Modes
20-4
20.4 AL_MaxClkRate Prototype C\C++
(32 bit) ERRNUM AL_GetMaxClkRate(LHLD lhld, double *dMaxRate);
Visual Basic for Windows Function AL_GetMaxClkRate(ByVal lhld As Long, ByVal dMaxRate As Double) As Long
LHLD lhld handle of the LDSD
double dMaxRate points to a double value to receiving the value.
The AL_GetMaxClkRate function is used to determine the Maximum frequency actually available by a device's clocking hardware.
Parameter Description
lhld Identifies the instance of the logical device subsystem.
dMaxRate Contains the Maximum hardware clocking rate.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the call.
Related Functions:
AL_SetClockSource AL_SetClockRate AL_GetActualClkRate AL_GetClockStruct
Supported Logical Device Subsystems: Pci55xx Series: ADC0, DAC0, DAC1
Chapter 21 Clocking Modes
20-5
20.5 AL_GetClockStruct Prototype C\C++
ERRNUM AL_GetClockStruct(LHLD lhld, LPCLK lpclkStruct);
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.
Related Functions:
AL_SetClockSource AL_SetClockRate AL_GetActualClkRate AL_MaxClkRate
Supported Logical Device Subsystems: Pci55xx Series: ADC0, DAC0, DAC1
Chapter 21 Clocking Modes
20-6
20.6 AL_SetClockOutput Prototype C\C++
ERRNUM AL_SetClockOutput(LHLD lhld, LPSTR lpstrMode);
Visual Basic for Windows Function AL_SetClockOutput(ByVal lhld As Long, ByVal lpstrMode As String) As Long
LHLD lhld handle of the LDSD LPSTR lpstrMode address 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.
Related Functions:
AL_GetClockOutput
Supported Logical Device Subsystems: Pci55xx Series: ADC0, Options: ENABLED, DISABLED
Chapter 21 Clocking Modes
20-7
20.7 AL_GetClockOutput Prototype C\C++
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 lpstrClockOutput destination 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.
Related Functions:
AL_SetClockOutput
Supported Logical Device Subsystems: Pci55xx Series: ADC0
Chapter 21 Clocking Modes
20-8
Chapter 22 Gating Modes
21-1
21. GATING MODES
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 SWGATEmay be used to allow the starting and stopping of either ADC0 or DAC1. The SWGATEmode 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.
21.1 AL_SetGateSource Prototype C\C++
ERRNUM AL_SetGateSource(LHLD lhld, LPSTR lpstrSource);
Visual Basic for Windows Function AL_SetGateSource(ByVal lhld As Long, ByVal lpstrSource As String) As Long
LHLD lhld handle of the LDSD LPSTR lpstrSource address of the gate source string

The AL_SetGateSource function sets the hardware gate source of the LDSD.

Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpstrSource Points to the desired gate source string. The available string settings are device
independent and are verified by ADLIB against the available gate source 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.
Related Functions:
AL_SetGateLevel AL_GetGateStruct AL_SetSwGate AL_GetSwGate
Supported Logical Device Subsystems: Pci55xx Series: ADC0, DAC0, Options: DISABLED, “SWGATE” or “EXTGATE“
Note: for the Pci55xx Series the AL_TriggerMode must be to DISABLED for a “SWGATE” or “EXTGATE“ setting.
Chapter 22 Gating Modes
21-2
21.2 AL_SetGateLevel Prototype C\C++
ERRNUM AL_SetGateLevel(LHLD lhld, LPSTR lpstrGateLevel);
Visual Basic for Windows Function AL_SetGateLevel(ByVal lhld As Long, ByVal lpstrGateLevel As String) As Long
LHLD lhld handle of the LDSD LPSTR lpstrGateLevel address of the gate Level string

The AL_SetGateLevel function sets the hardware gate level of the LDSD.

Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpstrGateLevel Points to the desired gate level string. The available string settings are device
independent and are verified by ADLIB against the available gate source 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.
Related Functions:
AL_SetGateSource AL_GetGateStruct AL_SetSwGate AL_GetSwGate
Supported Logical Device Subsystems: Pci55xx Series: ADC0, DAC0, Options: “ACTIVE_HIGH“ or “ACTIVE_LOW“
Chapter 22 Gating Modes
21-3
21.3 AL_GetGateStruct Prototype C\C++
ERRNUM AL_GetGateStruct(LHLD lhld, LPGATE lpgateStruct);
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.
Related Functions:
AL_SetGateSource AL_SetGateLevel AL_SetSwGate AL_GetSwGate
Supported Logical Device Subsystems: Pci55xx Series: ADC0, DAC0
Chapter 22 Gating Modes
21-4
21.4 AL_SetSwGate Prototype C\C++
ERRNUM AL_SetSwGate(LHLD lhld, long lSwGate);
Visual Basic for Windows Function AL_SetSwGate(ByVal lhld As Long, ByVal lSwGate As Long) As Long
LHLD lhld handle of the LDSD long lSwGate specifies the desired state of the hardware gate

The AL_SetSwGate function enables or disables a hardware control gate.

Parameter Description
lhld Identifies the instance of the logical device subsystem.
lSwGate Specifies the hardware gate state. The available settings are defined in the
ADLIB include file as follows:
DISABLED The device is stopped.
ENABLED The device is enabled to run.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the call.
Related Functions:
AL_SetGateSource AL_SetGateLevel AL_GetGateStruct AL_GetSwGate
Supported Logical Device Subsystems: Pci55xx Series: ADC0,DAC0, Options: DISABLED or ENABLED
Chapter 22 Gating Modes
21-5
21.5 AL_GetSwGate Prototype C\C++
STATUS AL_GetSwGate(LHLD lhld);
Visual Basic for Windows Function AL_GetSwGateStatus(ByVal lhld As Long) As Long
LHLD lhld handle of the LDSD

The AL_GetSwGate function retrieves the current hardware control gate status.

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 DISABLED or ENABLED, otherwise STATUS contains a negative error code that occurred during the call.
Related Functions:
AL_SetGateSource AL_SetGateLevel AL_GetGateStruct AL_SetSwGate
Supported Logical Device Subsystems: Pci55xx Series: ADC0, DAC0
Chapter 22 Gating Modes
21-6
Chapter 23 Burst Modes
22-1
22. BURST MODES
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.
22.1 AL_SetBurstMode Prototype C\C++
ERRNUM AL_SetBurstMode(LHLD lhld, LPSTR lpstrMode);
Visual Basic for Windows Function AL_SetBurstMode(ByVal lhld As Long, ByVal lpstrMode As String) As Long
LHLD lhld handle of the LDSD LPSTR lpstrMode address of the Burst mode string

The AL_SetBurstMode function sets the hardware Burst operation mode of the LDSD.

Parameter Description
lhld Identifies the instance of the logical device subsystem.
lpstrMode Points to the desired Burst mode string. The available string settings are device
independent and are verified by ADLIB against the available Burst 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.
Related Functions:
AL_SetBurstLength AL_SetBurstRate AL_GetBurstStruct
Supported Logical Device Subsystems: Pci55xx Series: ADC0, Options: DISABLED or ENABLED
Chapter 23 Burst Modes
22-2
22.2 AL_SetBurstLength Prototype C\C++
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 dRate specifies 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.
Related Functions:
AL_SetBurstMode AL_SetBurstLength AL_GetBurstStruct
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.
Chapter 23 Burst Modes
22-4
22.4 AL_GetBurstStruct Prototype C\C++
ERRNUM AL_GetBurstStruct(LHLD lhld, LPBURST lpburstStruct);
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.
Related Functions:
AL_SetBurstMode AL_SetBurstLength AL_SetBurstRate
Supported Logical Device Subsystems: Pci55xx Series: ADC0
Chapter 24 Channel Selections
23-1
23. CHANNEL SELECTIONS
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.
23.1 AL_SetChannelList Prototype C\C++
ERRNUM AL_SetChannelList(LHLD lhld, LPCHANLIST lpchanlist);
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.
Related Functions:
AL_GetChannelList AL_SetMinStartChan AL_GetMinStartChan AL_SetMaxEndChan AL_GetMaxEndChan AL_SetGainGlobal
Examples:
string “0,1,2,3,4,5,6,7”
string with gains “0(1),1(2),2(4),3(8),4(1),5(2),6(4),7(8)”
array {0,1,2,3,4,5,6,7};
array with gains {0,1,1,2,2,4,3,8,4,1,5,2,6,4,7,8};
Supported Logical Device Subsystems:
Pci5500: ADC0, Options: Min/Max Channel Pci5501, Pci5503: ADC0, Options: Min/Max Channel, Gains = 1, 2, 5, 10 Pci5502, Pci5504: ADC0, Options: Min/Max Channel, Gains = 1, 10, 100, 1000
Chapter 24 Channel Selections
23-3
23.2 AL_GetChannelList Prototype C\C++
ERRNUM AL_GetChannelList(LHLD lhld, LPCHANLIST lpchanlist);
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.
Related Functions:
AL_SetChannelList AL_SetMinStartChan AL_GetMinStartChan AL_SetMaxEndChan AL_GetMaxEndChan AL_SetGainGlobal
Examples:
string “0,1,2,3,4,5,6,7”
string with gains “0(1),1(2),2(4),3(8),4(1),5(2),6(4),7(8)”
array {0,1,2,3,4,5,6,7};
array with gains {0,1,1,2,2,4,3,8,4,1,5,2,6,4,7,8};
Chapter 24 Channel Selections
23-4
Supported Logical Device Subsystems: Pci55xx Series: ADC0
Chapter 24 Channel Selections
23-5
23.3 AL_SetMinStartChan Prototype C\C++
ERRNUM AL_SetMinStartChan(LHLD lhld, long lMinChan);
Visual Basic for Windows Function AL_SetMinStartChan(ByVal lhld As Long, ByVal lMinChan As Long) As Long
LHLD lhld handle of the LDSD long lMinChan specifies the minimum channel number

The AL_SetMinStartChan function sets the LDSD maximum allowable starting channel number for a device subsystem.

Parameter Description
lhld Identifies the instance of the logical device subsystem. lMinChan Minimum channel number allowed.
Returns:
On success ERRNUM is set to 1, otherwise ERRNUM contains the last error code that occurred during the call.
Related Functions:
AL_SetChannelList AL_GetMinStartChan AL_SetMaxEndChan AL_GetMaxEndChan AL_SetGainGlobal
Supported Logical Device Subsystems: Pci55xx Series: ADC0, Options: 0 to 127
Chapter 24 Channel Selections
23-6
23.4 AL_GetMinStartChan Prototype C\C++
STATUS AL_GetMinStartChan(LHLD lhld);
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.
Related Functions:
AL_SetChannelList AL_SetMinStartChan AL_SetMaxEndChan AL_GetMaxEndChan AL_SetGainGlobal
Supported Logical Device Subsystems: Pci55xx Series: ADC0
Loading...