LL_USB2k.DLL
Simplified Function Usage Overview
-- using the DLL --
introduction  -  ini file info  -  connecting  -  configuration  -  various I/O functions
scan (normal)  -  scan (using thermocouple amplifier)
list of all functions  -  ini file example  -  misc function protype information  -  Function Call Constants
For use with DLL version  8,18,2005,0  or newer -   not all API functions shown below are available in older versions of the DLL. To determine DLL version, right click on it from within Windows explorer and select  properties  and then  version from the drop-down menu.

The DLL is backward-compatible. If you have older software but want to use the new DLL, you can replace your older DLL  with the newer one - driver replacement may also be required when upgrading the DLL as discussed in  before starting  below.


An Introduction
Before starting
If you have never installed one of our Model-30x devices, you must use the Windows installation process that is described in various documents at our website. The installation documentation, drivers, DLL, and required .ini files are also available on floppy diskettes (or other medium) which is shipped with the actual hardware.

Once an initial successful installation has been made, regardless of the age of that installation, you can update older versions of both the driver and DLL by simply replacing older files with the newest ones. Please be aware that when updating, you must update both the driver and the DLL at the same time. To update, copy LL_USB2k.sys into your windows/system32/drivers/ directory (overwrite old) and the current DLL into the application directory. Do not place the DLL in any folder other than the same folder as the application that will be using it.


A little about the prototypes
IMPORTANT:   This simplified interface contains function calls prefixed with  "EX_"  which are designed to be used together. Please do not mix them with other function calls into aur DLL which are documented elsewhere that do not contain that prefix. Although such a mix may work, it could result in erroneous behaviour. There are some function calls that exist but have not yet been documented as well as others that will be added, so please continue to check back to this document.

Note that practically all functions return an 8-bit unsigned integer which is the same size as the "BOOLEAN" return type shown in the prototypes. Depending on your programming language this can be a value which is equal in size to one of the following:
Byte,  byte,  BYTE,  unsigned char,  uint8,  BOOLEAN
It is NOT the same as any of the following as some may assume it to be:
Bool,  Boolean,  BOOL
The device ID is located on the chip and other information supplied with your board(s). Multiple devices can be managed at the same time. When multiple device access is intended, we recommend initializing all the devices at the same time using the function call(s) provided for that purpose and then access each individually when making the other function calls into the DLL. Pass all the device IDs to the DLL in the initialization call. If one or more devices fail to enumerate, it will be removed from the list by the DLL, so be sure to check the list after the return from the call.

All calls into the DLL use the  __stdcall  calling convention which is also usually referred to as  "CALLBACK"  for casting purposes. Look  HERE  to find out more.

VisualBasic prototypes  and  LabView prototypes  are available as well. Protypes for C# can be derived from the C++ examples shown below.


Other things of interest
Due to the nature of an HTML page display, you can easily copy and paste the prototypes shown here directly into your application. For example, VisualBasic developers need only find the prototype for the EX_Connect function call, drag the mouse over it with the left mouse button pressed to highlight the text, hit Ctrl-C on the keyboard, and then go into the application where you want to paste it and hit Ctrl-V. Although the LabView environment is iconic, the developer still needs to declare the function call prototypes (as shown in the various example applications we provide) so this functionality is also useful to them as well as of course the C/C++ developers.

Much work has gone into the writing of this document (and others that are provided at the website) as well as the sample applications for developers of the various programming languages. Please make use of these resources before contacting Lawson Labs, Inc. for support regarding software development issues.


There is a special .INI file
for use with the simplified DLL API
A little about it
The   M30x_SP.ini  file included in the distribution can help eliminate some of the device configuration function calls that you may otherwise need to do. When devices are connected, the DLL will set certain default configuration parameters to make general running of the devices a relatively quick simple process of getting from the connect to actual scanning. For example, a simple call is required to connect and then a simple call to start the scanning process. Without any additional calls, or the existance of the special .ini file, once connected and the "RUN" (scanning) begun, the device would scan channel 0 and send the data to a logfile on the disk drive within the directory where the DLL resides   ( DLL should ALWAYS be in application directory ) In order to do anything different, other calls into the DLL would be required to change certain configruation options. Those calls can be eliminated by using the special .ini file and setting the configuration parameters there.

It's important to note that the .ini file must be located in your windows directory to be recognized! Be aware that the file is not required, but if it is found it will be analyzed by the DLL during connection for it's content. If a number that matches the Device ID that you are connecting to is found within that file, then the corresponding entries relating to that Device ID will also be analyzed and used if they are within valid ranges. If the values of any entry is not within a valid range then default values for those particular entries will be used instead. If there are no valid Device ID's found within that file, even though the file has been analyzed by the DLL before discovering that there are no valid Device IDs the entire content of the file will be ignored.

Here is a link showing the contents of a  M30x_SP.ini  file that has been configured for one of the test devices here at the shop:
       The LINK


The DLL API
( Application Programming Interface )
Go to   Function List  or scroll down and have a look
Connecting - this is required and always must be done first!
( use one of the following functions )


. ( C, C++ prototype )
 BOOLEAN EX_ConnectAllDevices ( BYTE* pbNumDevices, USHORT* pDevList, double* pdblRates );
Additional prototypes - LabView,   VisualBasic
-- Attempts to connect to all devices passed in 32-element array - pDevList. On return, that same list will also contain the Device ID's that were successfully connected - if the call returns success. If the call returns "failed" the device ID's in that list are meaningless and there was no successful connection made to any device. A successful enumeration to a device must be performed before any other interraction can occur.

Any device that successfully enumerates has it's data rate set equal to the rate that is passed in the list of data rates at the index offset that matches it's device ID index offset. Due to the architecture of the device a very slight adjustment may be made to the rate that is passed. For example, 1000Hz will be adjusted to 1000.521466Hz. If you need to know the adjusted rate, use the  EX_GetCalculatedRate()
IMPORTANT:   Please be aware that even though this function call may return true, that DOES NOT indicate that all or even one of the devices within your list were properly enumerated. You must check the contents of your lists upon return of this function call combined with the return value of the call. If the call returns true, then the devices still remaining within the device list were properly enumerated and those which were not were removed from the list. However, if the function call returned false, then none of the devices enumerated and there was an error in the attempt to enumerate. An example of an error that could cause the function call to return false is if the device driver was not loaded in memory, or perhaps the DLL and device driver version were not compatible. There is VerChck.exe  ( a utility )  available at our website that can be used for confirmation of driver and DLL compatibility.


. ( C, C++ prototype )
 BOOLEAN EX_ConnectOneDevice ( USHORT usDevID, double dblRate, BYTE bChan );
-- Attempts to connect to usDevID at the rate specified by dblRate and sets the channel to bChan. The call returns TRUE (1) upon success and FALSE (0) if it fails.
IMPORTANT:   If the function call returned false, then there was an error in the attempt to enumerate. An example of an error that could cause the function call to return false is if the device driver was not loaded in memory, or perhaps the DLL and device driver version were not compatible. There is VerChck.exe  ( a utility )  available at our website that can be used for confirmation of driver and DLL compatibility.


. ( C, C++ prototype )
 BOOLEAN EX_Connect ( USHORT* pDevID );
Additional prototypes - LabView,   VisualBasic
-- Attempts to connect to and then return the device ID of the first device that it finds. This is a simple and quick way to connect to a device when you know that you will have only one connected to your PC. The DLL will search for any Model 30x device which is connected to the PC. It will then enumerate the device and return the Device ID to you. If no device ID is returned, then no enumeration was successfully performed. If more than one Model 30x device is connected to your system, it is highly recommended that you use the   EX_ConnectAllDevices ( )   function call instead or erroneous behavior could result. A successful enumeration to a device must be performed before any other interraction can occur.

Upon successful enumeration the device is set to a default rate of 100Hz. and the channel that will be used for polled mode interraction as well as single channel scan mode is set to zero. The default scan mode is set to single-channel-scan. Any of the device setup options can be changed by using the various function calls available through the API.
IMPORTANT:   Please be aware that even though this function call may return true, that DOES NOT indicate that the device was properly enumerated. You must check the DevID that was returned combined with the return value of the call. If the call returns true, then a device was properly enumerated. However, if the function call returned false, then there was an error in the attempt to enumerate and the results of the device ID upon return from the call should be ignored. An example of an error that could cause the function call to return false is if the device driver was not loaded in memory, or perhaps the DLL and device driver version were not compatible. There is VerChck.exe  ( a utility )  available at our website that can be used for confirmation of driver and DLL compatibility.

. ( C, C++ prototype )
 BOOLEAN EX_CheckConnect ( USHORT usDevID );
Additional prototypes - LabView,   VisualBasic
Returns TRUE (one) if usDevID is connected.
Threaded DLL initialization and device connect - with EX_ functions
   - this ( or another connect method ) is required and always must be done first!


. ( C, C++ prototype )
 BOOLEAN EX_DLL_Init ( HANDLE hMainWin );
-- Attempts to initialize the DLL. This function is the first one to call before any other if you plan to use the  EX_  type threaded device connect. The related functions are explained next in this document. Your a handle to your application must be passed in the hMainWin. That handle needs to be non-zero, and will be used for identifying the device ID that you will be using in other calls. It will also be used in debug information if the debugging file output is enabled via the LL_USB.ini. The initialization involves validating DLL and device driver compatibility, as well as allocating memory and other resources that will be required for all other functions that will be used.

If this call returns FALSE, then the DLL initialization failed. Any of the  EX_  prefixed calls can be used after a successful return from this call.
IMPORTANT:   An example of an error that could cause the function call to return false is if the device driver was not loaded in memory, or perhaps the DLL and device driver version were not compatible. There is VerChck.exe  ( a utility )  available at our website that can be used for confirmation of driver and DLL compatibility.


. ( C, C++ prototype )
 BOOLEAN EX_ThreadedInitDev ( USHORT usDevID, double dblRate, BYTE bChan, UINT* uiInitStat, BOOLEAN fDeQueue );
-- Attempts to initialize the device ID passed in the usDevID variable. As of DLL version  4.13.2009.0,  the fDeQueue is ignored. It may be implemented in later DLL versions upon notification via this document.

The first call to this function by your application, must be preceded by a call to  EX_DLL_Init ( ).  The function returns FALSE if there is an error. Below are the numeric codes for an error or successful return:

Argument (Hex)
01 MDI_BUSY
02 MDI_DONE_ERROR
04 MDI_DONE_SUCCESS
08 MDI_DONE_BAD_DEV
10 MDI_DONE_BAD_NO_POWER
20 MDI_DONE_BAD_UNKNOWN_ERR
40 MDI_DLL_NEEDS_INIT
80 MDI_DONE_BAD_RATE

While the thread is busy intializing the device, the call to this function will return TRUE, and the variable pointed to by  uiInitStat  will have the MDI_BUSY bit set.

After calling the first time, you can continue to call it, checking the value passed back to variable pointed to by uiInitStat. If you have more than one device, then call this function with each device ID. This function may be preferred over the   EX_ConnectAllDevices ( )   function call if you have many devices to connect, since being away within the  EX_ConnectAllDevices ( )   function can make the application appear as though it is "hung" if many devices are being connected. Using this function, the return from the function is quick as are the calls that you make later to find out the status of the connection to any of the devices.

Please make sure to call the associated function  EX_EndThreadedDevInit ( )   prior to exiting your application. That function is discussed next on this page.


. ( C, C++ prototype )
 BOOLEAN EX_EndThreadedDevInit ( void );
Use this call if you've made any calls to  EX_ThreadedInitDev ( ).

Configuration - several options
Use default,  read from .ini file,  or set any or all options programmaticly


. ( C, C++ prototype )
 BOOLEAN EX_GetConfiguration ( USHORT* pusDevID, BYTE* pbPollChan, BYTE* pbScanType, BYTE* pbChanCnt, double* pdblRate, UINT* puiDataLogMethod );
Additional prototypes - LabView,   VisualBasic
Use this function call to get the current configuration for a particular device. You must set the variable pointed to by pusDevID to the device ID that you'd like to check. All the other parameters are set by the DLL to their current values by the DLL upon a successful return. If the DLL failes to find the device ID in it's list of enumerated devices, it returns FALSE and sets the variable pointed to by pusDevID to zero.


. ( C, C++ prototype )
 BOOLEAN EX_CheckIniExist ( void );
Additional prototypes - LabView,   VisualBasic
A call to this function can let you know if the DLL can locate the M30x_SP.INI file which it can use while connecting to a device or in future calls that you can make using the related function calls provided with this API. On success the return is TRUE (one), otherwise it is FALSE.


. ( C, C++ prototype )
 BOOLEAN EX_SetDevToIniSetup ( USHORT usDevID );
Additional prototypes - LabView,   VisualBasic
Call this function to set a particular device to the settings that are in the M30x_SP.INI file. You can read about, and see an example of the file HERE

Note, that the DLL will automatically perform this function during the initial connect, so unless you've changed some of the parameters programmatically, then this call is somewhat redundant.


. ( C, C++ prototype )
 BOOLEAN EX_SetDevToDefaultSetup ( USHORT usDevID );
Additional prototypes - LabView,   VisualBasic
Call this function to set a particular device to the default settings stored within the DLL. Use of this function call could be useful if you think you may have configured the device incorrectly either by calls that make use of the .ini file, other function calls that set configuration parameters, or maybe inadvertently just by having some unusual settings in an existing .ini file that may have been read automatically by the DLL during connect due to a matching ID found within the file.




Calibration
Note that a system calibration is automatically performed whenever you signon to the device.
A signon is performed by all of the initialization related functions such as, EX_ConnectAllDevices, EX_Connect, EX_Run, EX_DLL_Init, etc.


. ( C, C++ prototype )
NOTE: "EX_" type call for system calibration not yet implemented, use instead:

BOOLEAN SP_SystemCalibration ( USHORT usDevID, BYTE bCurChan );
This function performs a system calibration. Note that a system calibration (comprised of a full-scale and offset calibration) is performed automatically within the hardware during a signon.




Various I/O


. ( C, C++ prototype )
 BOOLEAN EX_SendDAC ( USHORT usDevID, DOUBLE dblVoltage, BYTE bDAC );
Additional prototypes - LabView,   VisualBasic
-- used with Model-302 only. Sends analog output (specified by dblVoltage) to the device (specified by usDevID) to the DAC (specified by bDAC).



. ( C, C++ prototype )
 BOOLEAN EX_SendDigout ( USHORT usDevID, BYTE bDigOut );
Additional prototypes - LabView,   VisualBasic
-- send a digital output - with some built-in error protection. This digital output is slightly different than the others in that it incorporates a brief "wait" period of approximately 20 milliseconds to automatically compensate for the time which may be required for a previous I/O to complete.

This function does not take into concideration any "bit preservation" as does some of the other functions mentioned below. In other words - it writes to the digital output whatever value is passed in the argument  bDigOut.  If you need to write only certain bits, leaving others in their previous states, use one of the "bit-preserver compatible" functions shown below.


. ( C, C++ prototype )
 BOOLEAN EX_DigoutBitPreserve ( USHORT usDevID, BOOLEAN fDo, BYTE bPreserve );
Additional prototypes - LabView,   VisualBasic
-- Allows for option to preserve digital output bits while writing others. Send a digital output you want preserved then send the mask and send anything else and the masked bits will remain unchanged. If you want to set a bit-mask that will be used constantly, this may be an an easy way to set things up, then send digital outputs with the next function call shown. If you think you may be changing the mask constantly then the longer version,   EX_Digout_Quick_BP ( )   may be better for you.


. ( C, C++ prototype )
 BOOLEAN EX_Digout_Quick ( USHORT usDevID, BYTE bDigOut );
Additional prototypes - LabView,   VisualBasic
-- send a digital output - normal. If Bit-preserve was turned on with call to,   EX_DigoutBitPreserve ( )   then the mask passed as bPreserve in that call will prevent the masked bits from the digital output preceding that call from being changed. This function is "bit-preservation compatible".


. ( C, C++ prototype )
 BOOLEAN EX_Digout_Quick_BP ( USHORT usDevID, BYTE bDigOut, BYTE bBitPreserve );
Additional prototypes - LabView,   VisualBasic
-- send a digital output with bit-preservation during a  EX_ScanS1  scan, but not exclusive to the  EX_ScanS1  scan.

bBitPreserve  functions as a mask to prevent particular bits in digital output byte from being changed by this call. Any bit set in the  bBitPreserve  mask will be unchaged regardless of the state of that bit in bDigOut.

The logical equivalent is:
    NewDigOut = (LastDigOut AND bBitPreserve) OR (bDigOut AND NOT(bBitPreserve)

It must be noted that this is the same call used by the DLL's EX_ScanS1_GetTemperature  function. Neither this call or the call to  EX_ScanS1_GetTemperature()  can be made while the other one is in progress, as may be the case if each call is placed within it's own thread.

. ( C, C++ prototype )
 BOOLEAN EX_GetDigin ( USHORT usDevID, BYTE* pbDigIn );
Additional prototypes - LabView,   VisualBasic
-- Gets the current digital input value and sets your variable, "pbDigIn" to it. Returns True if it succeeded in reading the digital input.


. ( C, C++ prototype )
 BOOLEAN EX_GetOneConversion ( USHORT usDevID, double* pdblMilliVolts );
Additional prototypes - LabView,   VisualBasic
-- Reads the voltage from the channel that is currently selected into variable pointed to by pdblMilliVolts. Use   EX_SetPolledModeChan ( )   to set that channel.


. ( C, C++ prototype )
 BOOLEAN EX_SetPolledModeChan ( USHORT usDevID, BYTE bChan );
Additional prototypes - LabView,   VisualBasic
-- Sets the channel that will be used for reading analog data while in polled mode, or in any of the single-channel scanning modes. Valid channels for a Model-301 are 0,1,6,7 and valid channels for a Model 302 are 0,1,2,3,4,5,6,7. Channel 6 always returns the Full-Scale voltage and channel 7 always returns the offset voltage.

Scanning related functions   ( normal )


. ( C, C++ prototype )
 BOOLEAN EX_SetScanType ( USHORT usDevID, BYTE bScanType );
Additional prototypes - LabView,   VisualBasic
-- setup for the type of scanning you want to do. Here are the available types for bScanType:
1 SINGLE_CHAN_SCAN
2 MULTI_CHAN_SCAN
3 MULTI_CHAN_CAL_SCAN
4 SINGLE_CHAN_DIGIN_SCAN
5 MULTI_CHAN_DIGIN_SCAN
6 MULTI_CHAN_CAL_DIGIN_SCAN
The default after a connection is "SINGLE_CHAN_SCAN", scanning channel "0". All of the single-channel scan modes scan the channel that has been selected using function call,   EX_SetPolledModeChan ( )   which is documented elsewhere. The channels to be used for multi-chan type of scan modes are selected using,   EX_SetMultiChanScanChans ( )   which is also documented elsewhere. Note that the calibration type scans add channel 7 to the data that is returned. Using a typical multi-channel scan mode, it's not possible to read the data from channel 7 without including all the other channels in the scan. This mode allows you to get the offset voltage (chan 7) regardless of the number of channels you scan. You may have already guessed that scanning a regular multi-channel scan with all 8 channels (model 302) returns the same voltages as if you use one of the cal-scan modes.
. ( C, C++ prototype )
 BOOLEAN EX_GetScanType ( USHORT usDevID, BYTE* pbScanType );
Additional prototypes - LabView,   VisualBasic
Sets variable pointed to by pbScanType to the scan type for the usDevID. See documentation above for information about scan type settings.



. ( C, C++ prototype )
 BOOLEAN EX_SetScanAvg ( USHORT usDevID, BYTE bAvg );
Additional prototypes - LabView,   VisualBasic
setup for averaging of scan data to be performed within the DLL
This function is provided for simplfying the averaging of the scan data. This is a "running" average.

Valid values for bAvg are 0 to 255. Passing a value greater than 0 will cause the DLL to setup buffering to manage the scan averaging. Setting the value to 1 creates the same data as if it were 0 except the extra overhead created by the DLL allocating and setting up for averaging, so a value of 1 is redundant and a waste of resources.

When the averaging feature is put to use, the DLL will allocate a buffer for each channel that is being scanned. When the scan first starts, the DLL will preload the buffer up to the limit of bAvg with the data from the first scan. Each channel's buffer is a circular buffer and each additional scan's data point will go into the buffer, and the buffer pointer will be incremented for the next scan's data point. All the points in the buffer will then be added together and divided by the value of bAvg. That averaged data will then be managed in the same way as if averaging wasn't even being used.


. ( C, C++ prototype )
 BOOLEAN EX_GetScanAvg ( USHORT usDevID, BYTE* pbAvg );
Additional prototypes - LabView,   VisualBasic
Sets variable pointed to by pbAvg to the current setting that is used by the DLL. A value of zero indicates that the DLL is not configured to do averaging and no resources have been allocated for that purpose.Any other value means the opposite. See the documentation above for the averaging usage.



. ( C, C++ prototype )
 BOOLEAN EX_SetMultiChanScanChans ( USHORT usDevID, BYTE bChanCnt );
Additional prototypes - LabView,   VisualBasic
-- Sets the number of channels to scan in mulit-channel scan mode. The Model-302 has a possible 8 channels, and the Model-301 has 4. Channels are scanned sequentially, so if you set bChanCnt to 4 for the Model-302 then you'd scan, channels 0,1,2, and 3. The same setting for the Model-301 would scan 0,1,6,7.
. ( C, C++ prototype )
 BOOLEAN EX_GetMultiChanScanChans ( USHORT usDevID, BYTE* pbChanCnt );
Additional prototypes - LabView,   VisualBasic
Sets variable pointed to by pbChanCnt to the number of channels currently set to be scanned for the usDevID. See documentation above for information about scan channel settings.



. ( C, C++ prototype )
 BOOLEAN EX_SetDataLogOptions ( USHORT usDevID, UINT uiDataLogMethod, UINT uiLogFileMaxSize, UINT uiMisc );
Additional prototypes - LabView,   VisualBasic
-- Allows you to set the way that the scan data will be recorded. By default, the scan data is written to a disk file within the directory where the DLL resides   ( DLL should ALWAYS be in application directory )  which has a naming that looks like, "ScanLog_0.txt" where the numeric value is incremented with each new scan that is started during the duration of time the current application is loaded. If the application is closed (the DLL automatically unloads from memory as a result) and is then reopened the numeric indicator within the filename will start again at zero. So, if you never call this function all you need to do is start the scan using one of the functions like  EX_Run ( )  and then stop the scan with a function like  EX_Stop ( )  after you think you've collected enough data. With many editors (such as the Windows Notepad), you can even open the data log file (that is being written) periodically to check the contents while the scan is running. Be sure not to forget that you are scanning or you may return to find a very large disk file. The   SCAN_LIMIT_LOG_FILE_SIZE  flag bit of   uiDataLogMethod  was implemented as of DLL version  DLL version 7,26,2005,0 , prior to that date it was within the prototype but not functional.

The scan data can also be written to memory (instead of the disk file) where you can read it, or it can be written both to a disk file (for analyzing later) and to memory (for presenting at runtime). If you use the option for the scan data to be written to memory, you must use the appropriate function call to retrieve the data and you must do so diligently - for example  EX_GetScanDataDbl ( )  documented further down is an example of one of the calls available to retrieve the scan data when the write-to-memory option is used. There is also an option to set the approximate size that the data log file can grow to. If uiLogFileMaxSize is set to zero there will be no limit set and the file will be written to until the scan is stopped. Below are the values that can be used for the  uiDataLogMethod  parameter:
Argument (Hex)
O1 SCAN_USE_DATA_LOG_FILE
02 SCAN_USE_DATA_ARRAY
04 SCAN_STOP_ON_DATA_ARRAY_WRAP
08 SCAN_LIMIT_LOG_FILE_SIZE
If you are only logging ONLY to a data log file, the scan will end automatically if the data log file size reaches  uiLogFileMaxSize (if that value is greater than zero and   SCAN_LIMIT_LOG_FILE_SIZE  is set). Anytime the  SCAN_STOP_ON_DATA_ARRAY_WRAP  bit of   uiDataLogMethod  are set, the scan will stop automatically when a data wrap of the memory buffer occurs. A data-buffer wrap can occur if the scan is set to log to memory and the application does not call into the DLL frequently enough to keep the data buffer emptied.

More options may be added to this function at a later date.
. ( C, C++ prototype )
 BOOLEAN EX_GetDataLogOptions ( USHORT usDevID, UINT* puiDataLogMethod, UINT* puiLogFileMax, UINT* puiMisc );
Additional prototypes - LabView,   VisualBasic
Sets variable pointed to by puiDataLogMethod to number (bitwise) that represents the data log option. Sets variable pointed to by puiLogFileMax to number that represents the maximum data log file size. The puiMisc variable is currently ignored. See documentation above for more information.



. ( C, C++ prototype )
 BOOLEAN EX_SetMultiChanScanChans_TO_LOG ( USHORT usDevID, BYTE bScanChansToLog );
Additional prototypes - LabView,   VisualBasic
-- Allows you to set the which channels will be logged to the data log file when writing to the log file is implemented. The default ( if you never call this function ) is for all channels that are currently being scanned to be logged.

The argument  bScanChansToLog  is a bit-mask of the channels to log. Here are some examples:
1.) Passing a value of 255 ( binary  11111111 ) will log all the channels that you are currently scanning.
2.) Passing a value of 85   ( binary  01010101 ) will log 0, 2, 4, and 6
3.) Passing a value of 6     ( binary  00000110 ) will log 1 and 2
Of course, regardless of the mask, only channels that are currently being scanned will be logged to the log file.

Remember, the default for logging data is to log to data file only. You have to specifically call  EX_SetDataLogOptions  to change the logging method. If you are logging only to memory, or in addition to the log file, this call has no effect on what data is logged to memory. When memory logging is implemented all data for all channels that are currently scanning is logged to memory.
. ( C, C++ prototype )
 BOOLEAN EX_GetMultiChanScanChans_TO_LOG ( USHORT usDevID, BYTE* pbScanChansToLog );
Additional prototypes - LabView,   VisualBasic
Sets variable pointed to by pbScanChansToLog to number (bitwise) that represents the scan channels that will be logged to disk file. See documentation above for information about bit settings.



. ( C, C++ prototype )
 BOOLEAN EX_Run ( USHORT usDevID );
Additional prototypes - LabView,   VisualBasic
-- Runs the scan using the scan type and logging method set by the other function calls which are documented elsewhere.
. ( C, C++ prototype )
 BOOLEAN EX_CheckRun ( USHORT usDevID );
Additional prototypes - LabView,   VisualBasic
Returns TRUE (one) if scan is running



. ( C, C++ prototype )
 BOOLEAN EX_CheckScanStatus ( USHORT usDevID, UINT* puiNumScansRemainingInBuff, BOOLEAN* pfStillScanning, UINT* puiStatusCode) );
Additional prototypes - LabView,   VisualBasic
-- Use this function to find out the status of the current scan run. The  puiNumScansRemainingInBuff.  only is valid when doing a scan that is logging data to memory. This will let you know how many scans are waiting in the data buffer used exclusively for that type of scan. It's suggested that the number returned by the  puiNumScansRemainingInBuff  argument be used in subsequent calls to get the scan data.

There are other buffers as well such as the one that is shared between the DLL and driver as well as a small buffer within the device (hardware) itself. The status of the latter two buffer's "overflow" (also known as wrapping) can be determined by reading one of the flags of the  puiStatusCode  function call argument. Below is a list of the bit flags and their meaning.
Argument (Hex)
0x1 NOT_SCANNING
0x2 HALTED
0x4 DISCONNECTED
0x8 SCAN_COMPLETED
0x10 MISSING_DIGIN_BUFF
0x20 BUFF_TOO_SMALL
0x40 MICRO_BUFF_WRAP
0x80 MEM1_BUFF_WRAP
0x100 MEM2_BUFF_WRAP
0x200 NO_DATA

Note the two buffer flags. The first represents the buffer that is shared between the DLL and the device driver, and the second represents the data that the DLL maintains to place the converted scans into until the application reads them.

The  NO_DATA  flag is set if there is no data to be read. This can be quite common if you are set to scan a slow scan but call into the DLL for data frequently. All it means is that even though the scan may be running fine, there just isn't any data available yet for reading.

The  MISSING_DIGIN_BUFF  isn't used at the time of this writing. I hope to implement it at a later date to verify the passing of a valid digital input data buffer for calls that make use of the digital input type scans - this one does not.

The  SCAN_COMPLETED  is set if the scan was preconfigured to stop under certain circumstances - for example when the log file reached a certain size, or a predefined amount of scanning time has elapsed. When this flag is set, it's still possible for the   pfStillScanning  to be set as well since the   pfStillScanning  variable indicates that the even though there is no data being taken by the DLL, the scan is still running in the background (no errors occurred causing it to prematurely halt) and has to be ended by the normal means by the application calling the usual functions to end the scan,   EX_Stop  and   EX_StopComplete. 

This is a good function to call if you are using the "log to memory" option in your application. Call this first to discover the number of scans currently in the buffer and then use the appropriate call to remove the scans and manage that data within your application. If using only the "log to disk file" method, then this function is also quite useful as explained in the previous paragraph.


. ( C, C++ prototype )
 BOOLEAN EX_GetScanDataDbl ( USHORT usDevID, double* pdblDataBuff, UINT uiNumScansToReturn, BOOLEAN fGetAllRequested,
        UINT* puiNumScansReturned, UINT* puiNumScansRemainingInBuff, BOOLEAN* pfStillScanning, UINT* puiTotalBuffSize, UINT* puiStatusCode);
Additional prototypes - LabView,   VisualBasic
-- retrieve the voltages. This function returns the voltage (+-5Volt). You must supply a data buffer of type "double" sized to equal  uiNumScansToReturn * number of channels being scanned. It's best to set the size of the requested amount   uiNumScansToReturn,  based on the value returned in  puiNumScansRemainingInBuff  from either a previous call to this function with  uiNumScansToReturn = 0,  or a previous call (recommended) to  EX_CheckScanStatus(...), discussed elsewhere on this page. Keep in mind, when determining the size of the buffer based on  puiNumScansRemainingInBuff,   your buffer must be a size equal to at least   puiNumScansRemainingInBuff * number of channels being scanned.  It's important to understand that One Scan is equal to the data collected for the number of channels that make up the scan - one channel of data is considered to be One Point not One Scan.

If   fGetAllRequested  is set equal to 1, then the call will return all the scans that are currently in it's buffer - this is risky   since the buffer passed must be large enough to handle whatever may be returned or a system crash can occur. You should never set   fGetAllRequested  unless you are scanning at a slow rate.  

Occassionally a scan can halt based on either errors associated with hardware (power outage, cable disconnect, etc) or with software (based on timeouts and such controlled by other functions) and that information can be obtained by looking at the  pfStillScanning  flag. If the scan is running, that value will be set to 1. The function returns various codes within the   puiStatusCode  variable. The codes are bit-settings which can also be considered to be "flag bits". Below is the value of bit settings and what they mean.
Argument (Hex)
0x01 NOT_SCANNING
0x02 HALTED
0x04 DISCONNECT
0x08 SCAN_COMPLETED
0x10 MISSING_DIGIN_BUFF
0x20 BUFF_TOO_SMALL
0x40 MICRO_BUFF_WRAP
0x80 MEM1_BUFF_WRAP
0x100 MEM2_BUFF_WRAP
0x200 NO_DATA

Note the two buffer flags. The first represents the buffer that is shared between the DLL and the device driver, and the second represents the data that the DLL maintains to place the converted scans into until the application reads them.

The  NO_DATA  flag is set if there is no data to be read. This can be quite common if you are set to scan a slow scan but call into the DLL for data frequently. All it means is that even though the scan may be running fine, there just isn't any data available yet for reading.

The  MISSING_DIGIN_BUFF  isn't used at the time of this writing. I hope to implement it at a later date to verify the passing of a valid digital input data buffer for calls that make use of the digital input type scans - this one does not.

The  SCAN_COMPLETED  is set if the scan was preconfigured to stop under certain circumstances - for example when the log file reached a certain size, or a predefined amount of scanning time has elapsed. When this flag is set, it's still possible for the   pfStillScanning  to be set as well since the   pfStillScanning  variable indicates that the even though there is no data being taken by the DLL, the scan is still running in the background (no errors occurred causing it to prematurely halt) and has to be ended by the normal means by the application calling the usual functions to end the scan,   EX_Stop  and   EX_StopComplete. 

If return is FALSE (or zero) the following could be reason
device ID not found, not connected, scan has halted for some reason (check status as discussed above), there are no scans in the buffer.
If return is TRUE (or one) the following could be reason
there is scan data equal to value of variable pointed to by  puiNumScansRemainingInBuff  waiting to be read.



. ( C, C++ prototype )
 BOOLEAN EX_GetScanDataDblDigin ( USHORT usDevID, double* pdblDataBuff, BYTE* pbDiginBuff,
                                UINT uiNumScansToReturn, BOOLEAN fGetAllRequested, UINT* puiNumScansReturned,
                                UINT* puiNumScansRemainingInBuff, BOOLEAN* pfStillScanning, UINT* puiTotalBuffSize, UINT* puiErrCode);
Additional prototypes - LabView,   VisualBasic
-- retrieve the voltages and corresponding digital input. Before proceeding, please read the documentation for  EX_GetScanDataDbl  (if you haven't already). Other than the addition of the digital input buffer, the two calls are the same. It's important to note that you must be running a digital input type of scan in order to use this function. There are various function calls that can be used to setup the scan. A couple that you should take a look at are,  EX_SetScanType  and  EX_SetMultiChanScanChans. 

This function call is designed to return digital input data along with the voltages. The data is returned in a buffer that is in perfect alignment with the voltage data so you can know the exact digital input that was recorded at the same time as the voltage. This can be especially useful for such things as recording voltage based on certain events. Simply connect the various digital inputs to an event (such as a solenoid switching) and then look for the bit corresponding to the digital input pin to change state and read the voltage that is aligned in the buffer with that digital input.

Based on what is discussed above, you may have already concluded the the voltage and digital input buffers must be the same size and that they are aligned with each other. For example when the call returns with an indication that there has been data returned, the first voltage in the voltage buffer   pdblDataBuff  will be the voltage that was read at the same time as the first digital input within the digital input buffer  pbDiginBuff.  

If return is FALSE (or zero) the following could be reason
device ID not found, not connected, scan has halted for some reason (check status as discussed above), there are no scans in the buffer.
If return is TRUE (or one) the following could be reason
there is scan data equal to value of variable pointed to by  puiNumScansRemainingInBuff  waiting to be read.



. ( C, C++ prototype )
 BOOLEAN EX_GetScanDataInt ( USHORT usDevID, INT* piDataBuff, UINT uiNumScansToReturn, BOOLEAN fGetAllRequested,
        UINT* puiNumScansReturned, UINT* puiNumScansRemainingInBuff, BOOLEAN* pfStillScanning, UINT* puiTotalBuffSize, UINT* puiStatusCode);
Additional prototypes - LabView,   VisualBasic
-- retrieve the voltages. This function returns the scan data as integer rawcount rather than doing the conversion within the DLL to a voltage for you. Below is an example that you can use to convert the rawcount to +-5volts
iRawCount = piDataBuff[eachIndex];
double dblMillivolts = (iRawCount - 8388608) * 0.00000059604645;
To help you understand the calculation, here is an explanation. The integer value returned is 24-bits - even though it's returned as an integer which is 32-bits, only 24 bits of it are used. So, looking at the first variable used in the parenthesis, you see a value that can be a maximum of 24-bits which means  16,777,215  which means a scaling factor of 1 part in 16,777,215 across the range of 10 volts. In other words, the smallest voltages possible would be approximately .00000059604645 volts. To change the range to +-5 we simply use 12-bits of the data on each end of the scale which is shown as the  8,388,608  value in the parenthesis. This range of +-5volts would give us minimal reading on each side of zero equal to 1/2 what we have with the 10 volts which would be approximately +-0.0000011920929volts.

You must supply a data buffer of type "integer" sized to equal  uiNumScansToReturn * number of channels being scanned.  It's best to set the size of the requested amount   uiNumScansToReturn,  based on the value returned in  puiNumScansRemainingInBuff  from either a previous call to this function with  uiNumScansToReturn = 0,  or a previous call (recommended) to  EX_CheckScanStatus(...) , discussed elsewhere on this page. Keep in mind, when determining the size of the buffer based on  puiNumScansRemainingInBuff,   your buffer must be a size equal to at least   puiNumScansRemainingInBuff * number of channels being scanned.  It's important to understand that One Scan is equal to the data collected for the number of channels that make up the scan - one channel of data is considered to be One Point not One Scan.

If   fGetAllRequested  is set equal to 1, then the call will return all the scans that are currently in it's buffer - this is risky   since the buffer passed must be large enough to handle whatever may be returned or a system crash can occur. You should never set   fGetAllRequested  unless you are scanning at a slow rate.  

Occassionally a scan can halt based on either errors associated with hardware (power outage, cable disconnect, etc) or with software (based on timeouts and such controlled by other functions) and that information can be obtained by looking at the  pfStillScanning  flag. If the scan is running, that value will be set to 1. The function returns various codes within the   puiStatusCode  variable. The codes are bit-settings which can also be considered to be "flag bits". Below is the value of bit settings and what they mean.
Argument (Hex)
0xO1 NOT_SCANNING
0x02 HALTED
0x04 DISCONNECT
0x08 SCAN_COMPLETED
0x10 MISSING_DIGIN_BUFF
0x20 BUFF_TOO_SMALL
0x40 MICRO_BUFF_WRAP
0x80 MEM1_BUFF_WRAP
0x100 MEM2_BUFF_WRAP
0x200 NO_DATA

Note the two buffer flags. The first represents the buffer that is shared between the DLL and the device driver, and the second represents the data that the DLL maintains to place the converted scans into until the application reads them.

The  NO_DATA  flag is set if there is no data to be read. This can be quite common if you are set to scan a slow scan but call into the DLL for data frequently. All it means is that even though the scan may be running fine, there just isn't any data available yet for reading.

The  MISSING_DIGIN_BUFF  isn't used at the time of this writing. I hope to implement it at a later date to verify the passing of a valid digital input data buffer for calls that make use of the digital input type scans - this one does not.

The  SCAN_COMPLETED  is set if the scan was preconfigured to stop under certain circumstances - for example when the log file reached a certain size, or a predefined amount of scanning time has elapsed. When this flag is set, it's still possible for the   pfStillScanning  to be set as well since the   pfStillScanning  variable indicates that the even though there is no data being taken by the DLL, the scan is still running in the background (no errors occurred causing it to prematurely halt) and has to be ended by the normal means by the application calling the usual functions to end the scan,   EX_Stop  and   EX_StopComplete. 

If return is FALSE (or zero) the following could be reason
device ID not found, not connected, scan has halted for some reason (check status as discussed above), there are no scans in the buffer.
If return is TRUE (or one) the following could be reason
there is scan data equal to value of variable pointed to by  puiNumScansRemainingInBuff  waiting to be read.



. ( C, C++ prototype )
 BOOLEAN EX_GetScanDataIntDigin ( USHORT usDevID, INT* piDataBufff, BYTE* pbDiginBuff,
                                UINT uiNumScansToReturn, BOOLEAN fGetAllRequested, UINT* puiNumScansReturned,
                                UINT* puiNumScansRemainingInBuff, BOOLEAN* pfStillScanning, UINT* puiTotalBuffSize, UINT* puiErrCode);
Additional prototypes - LabView,   VisualBasic
-- retrieve the scan data rawcount and corresponding digital input. Before proceeding, please read the documentation for  EX_GetScanDataInt  (if you haven't already). Other than the addition of the digital input buffer, the two calls are the same. It's important to note that you must be running a digital input type of scan in order to use this function. There are various function calls that can be used to setup the scan. A couple that you should take a look at are,  EX_SetScanType  and  EX_SetMultiChanScanChans. 

This function call is designed to return digital input data along with the voltages. The data is returned in a buffer that is in perfect alignment with the voltage data so you can know the exact digital input that was recorded at the same time as the voltage. This can be especially useful for such things as recording voltage based on certain events. Simply connect the various digital inputs to an event (such as a solenoid switching) and then look for the bit corresponding to the digital input pin to change state and read the voltage that is aligned in the buffer with that digital input.

Based on what is discussed above, you may have already concluded the the voltage and digital input buffers must be the same size and that they are aligned with each other. For example when the call returns with an indication that there has been data returned, the first voltage in the voltage buffer   pdblDataBuff  will be the voltage that was read at the same time as the first digital input within the digital input buffer  pbDiginBuff.  

If return is FALSE (or zero) the following could be reason
device ID not found, not connected, scan has halted for some reason (check status as discussed above), there are no scans in the buffer.
If return is TRUE (or one) the following could be reason
there is scan data equal to value of variable pointed to by  puiNumScansRemainingInBuff  waiting to be read.



. ( C, C++ prototype )
 BOOLEAN EX_SetLengthOfRunSec ( USHORT usDevID, UINT uiSeconds );
Additional prototypes - LabView,   VisualBasic
-- Set scan to stop after a particular amount of time. After the period set by   uiSeconds.  has elapsed, the scan data-taking thread within the DLL will end. This will end writing to the memory buffers and or disk file depending on the logging method that was in use. It is important to note that the usual function calls   EX_Stop ( )   and   EX_StopComplete ( )   used to end the scan still have to be made in order for all of the scan threads and processes to end and complete their cleanup procedures. This function when used together with the available function(s) to notify of the scan end such as   EX_SetRunEndBeepOptions ( )   described elsewhere, may be useful under certain circumstances. Confirmation of the scan completing can be verified within your code by calling  EX_CheckScanStatus ( )   and checking the   SCAN_COMPLETED  bit setting of the variable that you passed a pointer to in the call,  puiStatusCode.


. ( C, C++ prototype )
 BOOLEAN EX_SetScanEndEvent ( USHORT usDevID, BYTE bEvent, BOOLEAN fUseEventEnd );
Additional prototypes - LabView,   VisualBasic
-- Set scan to stop after a digital input event has occurred.

This function is only applicable to scan types that read digital input. Scan types must be set prior to starting the scan (unless the default single-channel scan is desired) by calling   EX_SetScanType ( )  and setting the appropriate flag bits. If the  fUseEventEnd  flag is set, then the scan thread within the DLL will stop running when it sees the event  fUseEventEnd  value on the digital input.

It is important to note that the usual function calls   EX_Stop ( )   and   EX_StopComplete ( )   used to end the scan still have to be made in order for ALL of the scan threads and processes to end and complete their cleanup procedures. This function when used together with the available function(s) to notify of the scan end such as   EX_SetRunEndBeepOptions ( )   described elsewhere, may be useful under certain circumstances. Confirmation of the scan completing can be verified within your code by calling  EX_CheckScanStatus ( )   and checking the  SCAN_COMPLETED  bit setting of the variable that you passed a pointer to in the call,  puiStatusCode.


. ( C, C++ prototype )
 BOOLEAN EX_SetRunEndBeepOptions ( USHORT usDevID, BOOLEAN fUseBeep,
                                UINT uiBeepFreq, UINT uiBeepDurationMs, UINT uiBeepIntervalSec, UINT uiBeepTimeoutSec );
Additional prototypes - LabView,   VisualBasic
-- Set scan-end notification by beeping the PC speaker. As is probably obvious by the name, this call allows you to set the PC speaker to make a beep tone when the scan has ended. This function when used together with the available function(s) to set a time limit for the scan such as   EX_SetLengthOfRunSec( )   described elsewhere, may be useful under certain circumstances. Another situation may be to use one of the digital input type scans (described elsewhere in detail) with a triggered event and when the event has been recorded, the scan can be ended and notification can come in the way of the beep tone even if you are not at your PC.

Setting up the beep is a simple process and allows for all kinds of options. For example, you can have the beep last for hours with a long interval between beeps or set one long contiuous beep that last several seconds or even minutes. The tone is also adjustable but may require some understanding of audible frequencies if you decide not to use the default setting of 440Hz. The default tone is easy on the ears and equivalent to an A note played on a musical instrument.

There are default settings that will be used if this function is called with the last four arguments set to zero. Likewise, you can set any of the four that you'd like to change simply by making them a non-zero value. Any values that are passed as zero will tell the DLL to use the default for that particular argument. here are the defaults:
            uiBeepFreq = 440Hz.   frequency of the beep
            uiBeepDurationMs = 50ms.   how long each beep tone will last
            uiBeepIntervalSec = 2sec.   the amount of silence between beeps
            uiBeepTimeoutSec = 10sec.   after this amount of time there will be no more beeps



. ( C, C++ prototype )
 BOOLEAN EX_Stop ( USHORT usDevID );
Additional prototypes - LabView,   VisualBasic
-- Step one of the two steps required to stop the scan that was started using   EX_Run ( ).   The ending of the scan is a two step process requiring two function calls into the DLL due to the use of threads to manage the data collection. Be sure to to call   EX_StopComplete ( )   after calling this function.


. ( C, C++ prototype )
 BOOLEAN EX_StopComplete ( USHORT usDevID );
Additional prototypes - LabView,   VisualBasic
-- Step two of the two steps required to stop the scan that was started using   EX_Run ( ).   The ending of the scan is a two step process requiring two function calls into the DLL due to the use of threads to manage the data collection. Be sure to to call   EX_Stop ( )   prior to calling this function.

Scanning related functions   ( special )
Designed specifically for use with our Model 35b thermocouple amplifier
The following functions are specific for our thermocouple amplifier and are therefore not elaborated on at this time except on a per/customer basis.


. ( C, C++ prototype )
 BOOLEAN EX_ScanS1_Setup ( USHORT usDevID, BYTE bNumChans, USHORT usIgnored, UINT uiTimeout );
Additional prototypes - LabView,   VisualBasic
-- setup the Thermocouple scan. Do this before starting the scan!


. ( C, C++ prototype )
 BOOLEAN EX_ScanS1_Run ( USHORT usDevID );
Additional prototypes - LabView,   VisualBasic
-- start the thermocouple scan.


. ( C, C++ prototype )
 BOOLEAN EX_ScanS1_GetTemperature ( USHORT usDevID, double* dblVoltages, BYTE bUnused, USHORT usAvg, UINT uiTimeout );
Additional prototypes - LabView,   VisualBasic
-- retrieve the temperature related voltages.


. ( C, C++ prototype )
 BOOLEAN EX_ScanS1_Stop ( USHORT usDevID );
Additional prototypes - LabView,   VisualBasic
-- end the thermocouple scan.


. ( C, C++ prototype )
 BOOLEAN EX_Digout_Quick_BP ( USHORT usDevID, BYTE bDigOut, BYTE bBitPreserve );
Additional prototypes - LabView,   VisualBasic
-- send a digital output with bit-preservation during a  EX_ScanS1  scan, but not exclusive to the  EX_ScanS1  scan.

bBitPreserve  functions as a mask to prevent particular bits in digital output byte from being changed by this call. Any bit set in the  bBitPreserve  mask will be unchaged regardless of the state of that bit in bDigOut.

The logical equivalent is:
    NewDigOut = (LastDigOut AND bBitPreserve) OR (bDigOut AND NOT(bBitPreserve)

It must be noted that this is the same call used by the DLL's EX_ScanS1_GetTemperature  function. Neither this call or the call to  EX_ScanS1_GetTemperature()  can be made while the other one is in progress, as may be the case if each call is placed within it's own thread.

Misc functions

. ( C, C++ prototype )
 BOOLEAN EX_SendChan ( USHORT usDevID, BYTE bChan, BYTE* pbLastDigin );
-- Sets the channel that will be used for reading analog data while in polled mode, or in any of the single-channel scanning modes. Valid channels for a Model-301 are 0,1,6,7 and valid channels for a Model 302 are 0,1,2,3,4,5,6,7. Channel 6 always returns the Full-Scale voltage and channel 7 always returns the offset voltage. This does basically the same thing as the function below, except also returns the last digital input in the variable pointed to by pbLastDigin.


. ( C, C++ prototype )
 BOOLEAN EX_SetPolledModeChan ( USHORT usDevID, BYTE bChan );
Additional prototypes - LabView,   VisualBasic
-- Sets the channel that will be used for reading analog data while in polled mode, or in any of the single-channel scanning modes. Valid channels for a Model-301 are 0,1,6,7 and valid channels for a Model 302 are 0,1,2,3,4,5,6,7. Channel 6 always returns the Full-Scale voltage and channel 7 always returns the offset voltage.
. ( C, C++ prototype )
 BOOLEAN EX_GetPolledModeChan ( USHORT usDevID, BYTE* bChan );
Additional prototypes - LabView,   VisualBasic
-- Gets the channel that will be used for reading analog data while in polled mode, or in any of the single-channel scanning modes. See information related information above.



. ( C, C++ prototype )
 BOOLEAN EX_SendRate ( USHORT usDevID , double* pdblRate );
Additional prototypes - LabView,   VisualBasic
-- send a rate (50-1000Hz). Device defaults to 100 when first connected using   EX_Connect ( ).   this allows rates within the range shown above to be set after the device is connected and not scanning.
. ( C, C++ prototype )
 BOOLEAN EX_GetCalculatedRate ( USHORT usDevID , double* pdblRate );
Additional prototypes - LabView,   VisualBasic
Get an actual possible device rate based on a rate. Due to the architecture of the device a very slight adjustment may be made to the rate that is passed during initialization or other function calls into the DLL that set the rate. For example, 1000Hz will be adjusted to 1000.521466Hz.

This call is used to determine what the actual rate is in case you need it for timing purposes. This function call is currently used for this purpose since if the adjusted rate were returned in a function call such as  EX_ConnectAllDevices,   and then in the case where the rate is slightly faster, the next call with the slightly faster rate would fail since the DLL does a boundary check against 1000Hz as a maximum rate. Likewise, some development interfaces do automatic truncating of the decimal places which could lead to a constantly changing rate with subsequent calls.

Passing any rate will return what the calculated rate for that rate will be. This call has nothing to do with what the current rate is. For example, if you make a variable of rate equal to 1000 and pass a pointer to that in this call, when the call returns that variable will be set to what the actual rate would be, if you were to use that rate.



. ( C, C++ prototype )
 BOOLEAN EX_SetStackedIRPcnt ( USHORT usDevID, BYTE bStackedCnt, BOOLEAN fOverride );
Additional prototypes - LabView,   VisualBasic
-- Sets the number of stacked IRPs  ( I/O Request Packets )   that the device driver will keep queued - making the retrieval of data much quicker than possible without stacking of the requested packets.

This configuratin setting has previously only been available through the  LL_USB.INI  configuration file. This function call allows you to override both the internal default of 20 stacked IRPs if the setting in the  LL_USB.INI  file is set to zero or any value that is set in that configuration file. The maximum is 40 and the minimum is 1. Values below 10 are not recommended and usually result in an inability of the driver to read the device quick enough to keep the device's data buffer emptied resulting in a "Microcode Buffer Wrap".

The reason this option is even made available rather than us just hard-coding this feature to the optimum value of 40, is because it does consume some memory, which is rarely although a possible issue on some systems. Here at the factory, we've run 24 devices with the stacked IRPs set to 40 on a single Windows-XP system with 128meg memory with no problems.

The arguments are first - the device ID, second - the count in a range of 1 to 40, third - whether to override the default or not.
Note:  the third parameter is provided mostly as a means by which to go back to using the settings from the .INI file  ( or the DLL's defaults if there is no .INI file present )  after you have already made the call to use your own parameters. So, that being said, to "override the .INI file settings"  set fOverride to TRUE and to use the .INI file settings set the parameter to FALSE.

. ( C, C++ prototype )
 BOOLEAN EX_GetStackedIRPcnt ( USHORT usDevID, BYTE* bStackedCnt, BOOLEAN* fOverride );
Additional prototypes - LabView,   VisualBasic
Get an actual possible device rate based on a rate. Due to the architecture of the device a very slight adjustment may be made to the rate that is passed during initialization or other function calls into the DLL that set the rate. For example, 1000Hz will be adjusted to 1000.521466Hz.

This call is used to determine what the actual rate is in case you need it for timing purposes. This function call is currently used for this purpose since if the adjusted rate were returned in a function call such as  EX_ConnectAllDevices,   and then in the case where the rate is slightly faster, the next call with the slightly faster rate would fail since the DLL does a boundary check against 1000Hz as a maximum rate. Likewise, some development interfaces do automatic truncating of the decimal places which could lead to a constantly changing rate with subsequent calls.


back to top




























































VisualBasic style prototypes

  Returns Function call name arglist
 
  Connecting
. Byte EX_Connect ( ByRef pDevID )
  Declare Function EX_Connect Lib "LL_USB2k.DLL"   ( ByRef pDevID As Integer) As Byte
 
. Byte EX_ConnectAllDevices ( ByRef pDevList, ByRef pdblRates, ByRef pbNumDevices )
  Declare Function EX_ConnectAllDevices Lib "LL_USB2k.DLL"   ( ByRef pDevList As Integer, ByRef pdblRates As Double, ByRef pbNumDevices As Byte ) As Byte
 
. Byte EX_CheckConnect ( ByVal pDevID As Integer )
  Declare Function EX_CheckConnect Lib "LL_USB2k.DLL"   ( ByVal pDevID As Integer ) As Byte
 
  Configuration
. Byte EX_GetConfiguration ( ByRef pusDevID, ByRef pbPollChan, ByRef pbScanType, ByRef pbChanCnt, ByRef pdblRate, ByRef puiDataLogMethod )
  Declare Function EX_GetConfiguration Lib "LL_USB2k.DLL"   ( ByRef pusDevID As Integer, ByRef pbPollChan As Byte,
                                                    ByRef pbScanType As Byte, ByRef pbChanCnt As Byte, ByRef pdblRate As Double, ByRef puiDataLogMethod As Long ) As Byte
 
. Byte EX_CheckIniExist no arg
  Declare Function EX_CheckIniExist Lib "LL_USB2k.DLL"   (  ) As Byte
 
. Byte EX_SetDevToIniSetup ( ByVal DevID )
  Declare Function EX_SetDevToIniSetup Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer ) As Byte
 
. Byte EX_SetDevToDefaultSetup ( ByVal DevID )
  Declare Function EX_SetDevToDefaultSetup Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer ) As Byte
 
. Byte EX_SendRate ( ByVal DevID, ByRef pdblRate )
  Declare Function EX_SendRate Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByRef pdblRate As Double ) As Byte
 
. Byte EX_GetCalculatedRate ( ByVal DevID, ByRef pdblRate )
  Declare Function EX_GetCalculatedRate Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByRef pdblRate As Double ) As Byte
 
. Byte EX_SetStackedIRPcnt ( ByVal DevID, ByVal bStackedCnt, ByVal fOverride )
  Declare Function EX_SetStackedIRPcnt Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByVal bStackedCnt As Byte, ByVal fOverride As Byte ) As Byte
 
. Byte EX_GetStackedIRPcnt ( ByVal DevID, ByRef pbStackedCnt, ByRef pfOverride )
  Declare Function EX_GetStackedIRPcnt Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByRef pbStackedCnt As Byte, ByRef pfOverride As Byte ) As Byte
 
  Basic I/O
. Byte EX_SendDAC ( ByVal DevID, ByVal dblVoltage, ByVal bDAC )
  Declare Function EX_SendDAC Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByVal dblVoltage As Double, ByVal bDAC As Byte ) As Byte
 
. Byte EX_SendDigout ( ByVal DevID, ByVal bDigout )
  Declare Function EX_SendDigout Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByVal bDigout As Byte ) As Byte
 
. Byte EX_DigoutBitPreserve ( ByVal DevID, ByVal fDo, ByVal bPreserve )
  Declare Function EX_DigoutBitPreserve Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByVal fDo As Byte, ByVal bPreserve As Byte) As Byte
 
. Byte EX_Digout_Quick ( ByVal DevID, ByVal bDigout )
  Declare Function EX_Digout_Quick Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByVal bDigout As Byte ) As Byte
 
. Byte EX_Digout_Quick_BP ( ByVal DevID, ByVal bDigout, ByVal bBitPreserve )
  Declare Function EX_Digout_Quick_BP Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByVal bDigOut As Byte, ByVal bBitPreserve As Byte ) As Byte
 
. Byte EX_GetDigin ( ByVal DevID, ByRef pbDigIn )
  Declare Function EX_GetDigin Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByRef pbDigIn As Byte ) As Byte
 
. Byte EX_GetOneConversion ( ByVal DevID, ByRef pdblMilliVolts )
  Declare Function EX_GetOneConversion Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByRef pdblMilliVolts As Double ) As Byte
 
. Byte EX_SetPolledModeChan ( ByVal DevID, ByRef pbDigIn )
  Declare Function EX_SetPolledModeChan Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByVal bChan As Byte ) As Byte
 
  Scanning
. Byte EX_SetScanType ( ByVal DevID, ByVal bScanType )
  Declare Function EX_SetScanType Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByVal bScanType As Byte ) As Byte
 
. Byte EX_GetScanType ( ByVal DevID, ByRef pbScanType )
  Declare Function EX_GetScanType Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByRef pbScanType As Byte ) As Byte
 
. Byte EX_SetScanAvg ( ByVal DevID, ByVal bAvg )
  Declare Function EX_SetScanAvg Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByVal bAvg As Byte ) As Byte
 
. Byte EX_GetScanAvg ( ByVal DevID, ByRef pbAvg )
  Declare Function EX_GetScanAvg Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByRef pbAvg As Byte ) As Byte
 
. Byte EX_SetMultiChanScanChans ( ByVal DevID, ByVal bChanCnt )
  Declare Function EX_SetMultiChanScanChans Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByVal bChanCnt As Byte ) As Byte
 
. Byte EX_GetMultiChanScanChans ( ByVal DevID, ByRef pbChanCnt )
  Declare Function EX_GetMultiChanScanChans Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByRef pbChanCnt As Byte ) As Byte
 
. Byte EX_SetDataLogOptions ( ByVal DevID, ByVal uiDataLogMethod, ByVal uiLogFileMaxSize, ByVal uiMisc )
  Declare Function EX_SetDataLogOptions Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer,
                                                    ByVal uiDataLogMethod As Long, ByVal uiLogFileMaxSize As Long, ByVal uiMisc As Long ) As Byte
 
. Byte EX_GetDataLogOptions ( ByVal DevID, ByRef puiDataLogMethod, ByRef puiLogFileMaxSize, ByRef puiMisc )
  Declare Function EX_GetDataLogOptions Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer,
                                                    ByRef puiDataLogMethod As Long, ByRef puiLogFileMaxSize As Long, ByRef puiMisc As Long ) As Byte
 
. Byte EX_SetMultiChanScanChans_TO_LOG ( ByVal DevID, ByVal bScanChansToLog )
  Declare Function EX_SetMultiChanScanChans_TO_LOG Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByVal bScanChansToLog As Byte ) As Byte
 
. Byte EX_GetMultiChanScanChans_TO_LOG ( ByVal DevID, ByRef pbScanChansToLog )
  Declare Function EX_GetMultiChanScanChans_TO_LOG Lib "LL_USB2k.DLL"   ( ByVal DevID as Integer, ByRef bScanChansToLog As Byte ) As Byte
 
. Byte EX_Run ( ByVal DevID )
  Declare Function EX_Run Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer ) As Byte
 
. Byte EX_CheckRun ( ByVal DevID )
  Declare Function EX_CheckRun Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer ) As Byte
 
. Byte EX_CheckScanStatus ( ByVal DevID As Integer, ByRef puiNumScansRemainingInBuff as Long,
                                                                              ByRef pfStillScanning as Byte, ByRef puiStatusCode as Long ) As Byte
  Declare Function EX_CheckScanStatus Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByRef puiNumScansRemainingInBuff as Long,
                                                                              ByRef pfStillScanning as Byte, ByRef puiStatusCode as Long ) As Byte
 
. Byte EX_GetScanDataDbl ( ByVal DevID, ByRef pdblDataBuff, ByVal uiNumScansToReturn, ByVal fGetAllRequested, ByRef puiNumScansReturned
, ByRef puiNumScansRemainingInBuff, ByRef pfStillScanning, ByRef puiTotalBuffSize, ByRef puiErrCode )
  Declare Function EX_GetScanDataDbl Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByRef pdblDataBuff As Double, ByVal uiNumScansToReturn As Long,
                          ByVal fGetAllRequested as Byte, ByRef puiNumScansReturned As Long, ByRef puiNumScansRemainingInBuff As Long,
                          ByRef pfStillScanning As Byte, ByRef puiTotalBuffSize As Long, ByRef puiErrCode As Long ) As Byte
 
. Byte EX_GetScanDataDblDigin ( ByVal DevID, ByRef pdblDataBuff, ByRef pbDiginBuff, ByVal uiNumScansToReturn, ByVal fGetAllRequested, ByRef puiNumScansReturned,
ByRef puiNumScansRemainingInBuff, ByRef pfStillScanning, ByRef puiTotalBuffSize, ByRef puiErrCode )
  Declare Function EX_GetScanDataDblDigin Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByRef pdblDataBuff As Double, ByRef pbDiginBuff As Byte, ByVal uiNumScansToReturn As Long,
                          ByVal fGetAllRequested as Byte, ByRef puiNumScansReturned As Long, ByRef puiNumScansRemainingInBuff As Long,
                          ByRef pfStillScanning As Byte, ByRef puiTotalBuffSize As Long, ByRef puiErrCode As Long ) As Byte
 
. Byte EX_GetScanDataInt ( ByVal DevID, ByRef piDataBuff, ByVal uiNumScansToReturn, ByVal fGetAllRequested, ByRef puiNumScansReturned,
ByRef puiNumScansRemainingInBuff, ByRef pfStillScanning, ByRef puiTotalBuffSize, ByRef puiErrCode )
  Declare Function EX_GetScanDataInt Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByRef piDataBuff As Long, ByVal uiNumScansToReturn As Long,
                          ByVal fGetAllRequested as Byte, ByRef puiNumScansReturned As Long, ByRef puiNumScansRemainingInBuff As Long,
                          ByRef pfStillScanning As Byte, ByRef puiTotalBuffSize As Long, ByRef puiErrCode As Long ) As Byte
 
. Byte EX_GetScanDataIntDigin ( ByVal DevID, ByRef piDataBuff, ByRef pbDiginBuff, ByVal uiNumScansToReturn, ByVal fGetAllRequested, ByRef puiNumScansReturned,
ByRef puiNumScansRemainingInBuff, ByRef pfStillScanning, ByRef puiTotalBuffSize, ByRef puiErrCode )
  Declare Function EX_GetScanDataIntDigin Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByRef piDataBuff As Long, ByRef pbDiginBuff As Byte, ByVal uiNumScansToReturn As Long,
                          ByVal fGetAllRequested as Byte, ByRef puiNumScansReturned As Long, ByRef puiNumScansRemainingInBuff As Long,
                          ByRef pfStillScanning As Byte, ByRef puiTotalBuffSize As Long, ByRef puiErrCode As Long ) As Byte
 
. Byte EX_SetLengthOfRunSec ( ByVal DevID, ByVal uiSeconds )
  Declare Function EX_SetLengthOfRunSec Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByVal uiSeconds As Long ) As Byte
 
. Byte EX_SetRunEndBeepOptions ( ByVal DevID, ByVal fUseBeep, ByVal uiBeepFreq, ByVal uiBeepDurationMs, ByVal uiBeepIntervalSec, ByVal uiBeepTimeoutSec )
  Declare Function EX_SetRunEndBeepOptions Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer, ByVal fUseBeep As Byte,
                          ByVal uiBeepFreq As Long, ByVal uiBeepDurationMs As Long, ByVal uiBeepIntervalSec As Long, ByVal uiBeepTimeoutSec As Long ) As Byte
 
. Byte EX_Stop ( ByVal DevID )
  Declare Function EX_Stop Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer ) As Byte
 
. Byte EX_StopComplete ( ByVal DevID )
  Declare Function EX_StopComplete Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer ) As Byte
 
  Specialty scan  used for our thermocouple amplifier - documentation included with hardware purchase, and later within this document.
. Byte EX_ScanS1_Setup ( ByVal DevID, ByVal bNumChans, ByVal usAvg, ByVal uiTimeout )
  Declare Function EX_ScanS1_Setup Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer,
                                                    ByVal bNumChans As Byte, ByVal usAvg As Integer, ByVal uiTimeout As Long ) As Byte
 
. Byte EX_ScanS1_Run ( ByVal DevID )
  Declare Function EX_ScanS1_Run Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer ) As Byte
 
. Byte EX_ScanS1_GetTemperature ( ByVal DevID, ByRef pdblVoltages, ByVal usAvg, ByVal uiTimeout )
  Declare Function EX_ScanS1_GetTemperature Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer,
                                                    ByRef pdblVoltages As Double, ByVal bUnused as Byte, ByVal usAvg As Integer, ByVal uiTimeout As Long ) As Byte
 
. Byte EX_ScanS1_Stop ( ByVal DevID )
  Declare Function EX_ScanS1_Stop Lib "LL_USB2k.DLL"   ( ByVal DevID As Integer ) As Byte

back to top




























































LabView style prototypes

returns Function call name args
 
  Connecting
. uint8 EX_ConnectAllDevices ( uint16* pDevList, double* pdblRates, uint8* pbNumDevices );
 
. uint8 EX_Connect ( uint16* pDevID );
 
. uint8 EX_CheckConnect ( uint16 DevID );
 
  Configuration
. uint8 EX_GetConfiguration ( uint16* pDevList, uint8* pbPollChan, uint8* pbScanType, uint8* pbChanCnt, double* pdblRate, uint32* puiDataLogMethod );
 
. uint8 EX_CheckIniExist ( void );
 
. uint8 EX_SetDevToIniSetup ( uint16 DevID );
 
. uint8 EX_SetDevToDefaultSetup ( uint16 DevID );
 
. uint8 EX_SendRate ( uint16 DevID, double* pdblRate );
 
. uint8 EX_GetCalculatedRate ( uint16 DevID, double* pdblRate );
 
. uint8 EX_SetStackedIRPcnt ( uint16 DevID, uint8 bStackedCnt, uint8 fOverride );
 
. uint8 EX_GetStackedIRPcnt ( uint16 DevID, uint8* bStackedCnt, uint8* fOverride );
 
  Misc. I/O
. uint8 EX_SendDAC ( uint16 DevID, double dblVoltage, uint8 bDAC );
 
. uint8 EX_SendDigout ( uint16 DevID, uint8 bDigOut );
 
. uint8 EX_DigoutBitPreserve ( uint16 DevID, uint8 fDo, uint8 bPreserve );
 
. uint8 EX_Digout_Quick ( uint16 DevID, uint8 bDigOut );
 
. uint8 EX_GetDigin ( uint16 DevID, uint8* bDigIn );
 
. uint8 EX_SendDAC ( uint16 DevID, double* pdblVoltage, uint8 bDAC );
 
. uint8 EX_GetOneConversion ( uint16 DevID, double* pdblMilliVolts );
 
. uint8 EX_SetPolledModeChan ( uint16 DevID, uint8 bChan );
 
  Scanning
. uint8 EX_SetScanType ( uint16 DevID, uint8 bScanType );
 
. uint8 EX_GetScanType ( uint16 DevID, uint8* pbScanType );
 
. uint8 EX_SetScanAvg ( uint16 DevID, uint8 bAvg );
 
. uint8 EX_GetScanAvg ( uint16 DevID, uint8* pbAvg );
 
. uint8 EX_SetDataLogOptions ( uint16 DevID, uint32 uiDataLogMethod, uint32 uiLogFileMaxSize, uint32 uiMisc );
 
. uint8 EX_GetDataLogOptions ( uint16 DevID, uint32* puiDataLogMethod, uint32* puiLogFileMaxSize, uint32* puiMisc );
 
. uint8 EX_SetMultiChanScanChans_TO_LOG ( uint16 DevID, uint8 bScanChansToLog );
 
. uint8 EX_GetMultiChanScanChans_TO_LOG ( uint16 DevID, uint8* bScanChansToLog );
 
. uint8 EX_Run ( uint16 DevID );
 
. uint8 EX_CheckRun ( uint16 DevID );
 
. uint8 EX_CheckScanStatus ( uint16 DevID, uint32* puiNumScansRemainingInBuff, uint8* pfStillScanning, uint32* puiStatusCode );
 
. uint8 EX_GetScanDataDbl ( uint16 DevID, double* pdblDataBuff, uint32 uiNumScansToReturn, uint8 fGetAllRequested, uint32* puiNumScansReturned, uint32* puiNumScansRemainingInBuff, uint8* pfStillScanning, uint32* puiTotalBuffSize, uint32* puiErrCode);
 
. uint8 EX_GetScanDataDblDigin ( uint16 DevID, double* pdblDataBuff, uint8* pbDiginBuff, uint32 uiNumScansToReturn, uint8 fGetAllRequested, uint32* puiNumScansReturned, uint32* puiNumScansRemainingInBuff, uint8* pfStillScanning, uint32* puiTotalBuffSize, uint32* puiErrCode);
 
. uint8 EX_GetScanDataInt ( uint16 DevID, int32* piDataBuff, uint32 uiNumScansToReturn, uint8 fGetAllRequested, uint32* puiNumScansReturned, uint32* puiNumScansRemainingInBuff, uint8* pfStillScanning, uint32* puiTotalBuffSize, uint32* puiErrCode);
 
. uint8 EX_GetScanDataIntDigin ( uint16 DevID, int* piDataBuff, uint8* pbDiginBuff, uint32 uiNumScansToReturn, uint8 fGetAllRequested, uint32* puiNumScansReturned, uint32* puiNumScansRemainingInBuff, uint8* pfStillScanning, uint32* puiTotalBuffSize, uint32* puiErrCode);
 
. uint8 EX_SetLengthOfRunSec ( uint16 DevID, uint32 uiSeconds );
 
. uint8 EX_SetRunEndBeepOptions ( uint16 DevID, uint8 uiBeepFreq, uint32 uiBeepFreq, uint32 uiBeepDurationMs, uint32 uiBeepIntervalSec, uint32 uiBeepTimeoutSec);
 
. uint8 EX_Stop ( uint16 DevID );
 
. uint8 EX_StopComplete ( uint16 DevID );
 
  Specialty scan  used for our thermocouple amplifier - documentation included with hardware purchase, and later within this document.
. uint8 EX_ScanS1_Setup ( uint16 usDevID, uint8 bNumChans, uint16 usAvg, uint32 uiTimeout );
 
. uint8 EX_ScanS1_Run ( uint16 usDevID );
 
. uint8 EX_ScanS1_GetTemperature ( uint16 usDevID, double* pdblVoltages, uint8 bUnused, uint16 usAvg, uint32 uiTimeout );
 
. uint8 EX_ScanS1_Stop ( uint16 usDevID );

back to top

















































Function call listing
 
Connecting
EX_Connect
EX_ConnectAllDevices
EX_ConnectOneDevice
EX_CheckConnect

Configuration
EX_GetConfiguration
EX_CheckIniExist
EX_SetDevToIniSetup
EX_SetDevToDefaultSetup

Calibration
SP_SystemCalibration

Basic I/O
EX_SendDAC
EX_SendDigout
EX_Digout_Quick
EX_DigoutBitPreserve
EX_GetDigin

Misc function
EX_GetOneConversion
EX_SendChan
EX_SetPolledModeChan
EX_SendRate
EX_GetCalculatedRate

Scanning   ( normal )
EX_SetScanType
EX_GetScanType
EX_SetMultiChanScanChans
EX_GetMultiChanScanChans
EX_SetDataLogOptions
EX_GetDataLogOptions
EX_SetMultiChanScanChans_TO_LOG
EX_GetMultiChanScanChans_TO_LOG
EX_Run
EX_CheckRun
EX_CheckScanStatus
EX_GetScanDataDbl
EX_GetScanDataDblDigin
EX_GetScanDataInt
EX_GetScanDataIntDigin
EX_SetLengthOfRunSec
EX_SetRunEndBeepOptions
EX_Stop
EX_StopComplete

Scanning   ( special )
EX_ScanS1_Setup
EX_ScanS1_Run
EX_ScanS1_GetTemperature
EX_ScanS1_Stop
EX_Digout_Quick_BP

back to top




























































Function call constants
 
Connecting
EX_ThreadedInitDev

Argument (Hex) -   "InitStat"   ( Multiple Device Init )
01 MDI_BUSY
02 MDI_DONE_ERROR
04 MDI_DONE_SUCCESS
08 MDI_DONE_BAD_DEV
10 MDI_DONE_BAD_NO_POWER
20 MDI_DONE_BAD_UNKNOWN_ERR
40 MDI_DLL_NEEDS_INIT
80 MDI_DONE_BAD_RATE




Scan Startup   ( normal )
EX_SetScanType
EX_GetScanType

Argument (Dec) -   "ScanType"
1 SINGLE_CHAN_SCAN
2 MULTI_CHAN_SCAN
3 MULTI_CHAN_CAL_SCAN
4 SINGLE_CHAN_DIGIN_SCAN
5 MULTI_CHAN_DIGIN_SCAN
6 MULTI_CHAN_CAL_DIGIN_SCAN




Data Logging
EX_SetDataLogOptions
EX_GetDataLogOptions

Argument (Hex) -   "DataLogMethod"
0 SCAN_NO_DATA_LOG
01 SCAN_USE_DATA_LOG_FILE
02 SCAN_USE_DATA_ARRAY
04 SCAN_STOP_ON_DATA_ARRAY_WRAP
08 SCAN_LIMIT_LOG_FILE_SIZE




Scanning   ( normal )
EX_CheckScanStatus
EX_GetScanDataDbl
EX_GetScanDataDblDigin
EX_GetScanDataInt
EX_GetScanDataIntDigin

Argument (Hex) -   "StatusCode"
0x01 NOT_SCANNING
0x02 HALTED
0x04 DISCONNECT
0x08 SCAN_COMPLETED
0x10 MISSING_DIGIN_BUFF
0x20 BUFF_TOO_SMALL
0x40 MICRO_BUFF_WRAP
0x80 MEM1_BUFF_WRAP
0x100 MEM2_BUFF_WRAP
0x200 NO_DATA


back to top




























































.
A sample   M30x_SP.INI  file
  
 

;=============================================
;=============================================
;THIS FILE MUST BE PLACED IN WINDOWS DIRECTORY
;This file is used by file, "LL_USB2k.DLL" but may also be used by sample application file.
;If you use it for your own application, you should not remove any of the following entries
;  since doing so may create erroneous behaviour of the DLL. However, feel free to add your
;  own entries or modify the values of the ones shown below to fit your needs.
;Value inside of "[ ]" is your device ID(s) followed by values for that particular
;  device ID to be used for configuration. See end of this file for an explanation
;  of each of the values.
;=============================================
;=============================================

[5208]

tScan=1
Rate=100.00
LogScans=1
normalChan=0
multiChanScanNumChans=1



[10084]

tScan=1
Rate=600.00
LogScans=1
normalChan=0
multiChanScanNumChans=1



[0]  
==========================================================  
NOTE: anything below this line won't be used by the DLL
Below are sample values and explanation of what they mean.
==========================================================  

tScan=2
;type of scan 
;1 = single channel
;2 = multi-channel
;3 = multi-channel with calibration included
;4 = single-channel with digital input
;5 = multi-channel with digital input
;6 = multi-channel with calibration and digital input included


Rate=900.00
;internal data rate



LogScans=1
;1 = Log scan data to disk only ( same folder as where DLL is located )
;2 = Log scan data to memory only
;3 = Log scan data to memory and disk
;NOTE: the log file can become awkwardly large depending on scan rate & duration.


normalChan=0
;channel to use when in polled mode and single-channel scan mode
;legal values are 0,1,6,7 for a Model-301 and 0,1,2,3,4,5,6,7 for
;a Model-302


multiChanScanNumChans=1
;number of channels to use in multi-channel scan mode
;channels are sequential scanned beginning at channel 0

;legal values are 1,2,3,4 (legal channels are 0,1,6,7) for the Model 301 and
; 1, 2, 3, 4, 5, 6, 7, 8 (channels 0,1,2,3,4,5,6, and 7) for the Model 302.
;In "calibration scan mode" channel 7 (the offset channel) is always scanned and 
; the data is returned so there is no need to set that number when scanning in 
; that mode. It should be mentioned at this point, that the advantage of the 
; calibration scan mode is that channel 7 is always included in the returned data
; for a calibration type scan even if only 1 channel is requested to be scanned. 
; Typically channel 7 would only be returned if all channels below it were also 
; set for scanning.
back to top



























































Important function call prototype info
this is usually only applicable to C/C++ programmers who have the option to set calling conventions



If you do not set your IDE to use   "__stdcall"   calling convention you must preface each casting of function call pointer with the word   "CALLBACK"   like this:
typedef BOOLEAN(CALLBACK *P_DLL_EX_CONNECT) (USHORT* usDevID);
P_DLL_EX_CONNECT EX_Connect = NULL;

or just cast using the type _stdcall like this
typedef BOOLEAN(_stdcall *P_DLL_EX_CONNECT) (USHORT* usDevID);
P_DLL_EX_CONNECT EX_Connect = NULL;


otherwise you can simply do the following:
typedef BOOLEAN(*P_DLL_EX_CONNECT) (USHORT* usDevID);
P_DLL_EX_CONNECT EX_Connect = NULL;

back to top










































































Scan data and digital input buffering format
read important information at the end of the table about buffering of data for multiple scans returned
note that some function calls may return the data as type integer, while others may
return the data converted to a voltage with a data type of double.
read more about the buffering
Model-301
showing multi-chan digital-input type scan
( MULTI_CHAN_DIGIN_SCAN )
The following table shows how the buffers will look for a scan that includes 4 channels. Note that a Model-301 only has 4 channels: 0,1,6, and 7. Channel 6 is the full scale channel and 7 is the offset channel.
first row shows data, second shows digital input  
  pauiDataBuff   (24-bit data)
  channel 0
  channel 1
  channel 6
  channel 7
  pabDiginBuff   (8-bit digital input)
  channel 0
  channel 1
  channel 6
  channel 7


Model-302
showing multi-chan digital-input type scan
( MULTI_CHAN_DIGIN_SCAN )
The following table shows how the buffers will look for a scan that includes 4 channels. Note that a Model-302 can scan up to 8 channels and that all channels are scanned sequentially.
first row shows data, second shows digital input  
  pauiDataBuff   (24-bit data)
  channel 0
  channel 1
  channel 2
  channel 3
  pabDiginBuff   (8-bit digital input)
  channel 0
  channel 1
  channel 2
  channel 3


Model-302
showing multi-chan digital-input-calibration type scan
( MULTI_CHAN_CAL_DIGIN_SCAN )
The following table shows how the buffers will look for a scan that includes 4 channels. Note that a Model-302 can scan up to 8 channels and that all channels are scanned sequentially.
first row shows data, second shows digital input  
  pauiDataBuff   (24-bit data)
  channel 0
  channel 1
  channel 2
  channel 3
  channel 7 (offset)
  pabDiginBuff   (8-bit digital input)
  channel 0
  channel 1
  channel 2
  channel 3
  channel 7 (offset)


Model-302
showing multi-chan digital-input-calibration type scan with multiple-packets
( MULTI_CHAN_CAL_DIGIN_SCAN )
The following table shows how the buffers will look for a scan that includes 2 channels, except this time we'll ask for 3 packets - that means that   usNumPointsToRead will be set to 9.   I'll condense the table a little bit so it will all fit, so just look at the tables above for better descriptions of the actual labels if you need to. The two examples above show what the buffers will look like if you only ask for one packet (all the data for all channels). The table below shows how the buffers will look when you ask for multiple packets. Asking for larger packets is fine, but it's very important that the value you set "usNumPointsToRead"   is divisable by the number of channels that you're scanning. Be sure to include the calibration channel in that count. Since the calibration channel is actually one of the active channels, please note that a 6 channel scan and a 7 channel scan will both return 7 channels since the offset channel is automatically returned with that type of scan.
first row shows data, second shows digital input  
 
|----- first packet -----|
|----- second packet -----|
|----- third packet -----|
Data
ch 0
ch 1
ch 7
ch 0
ch 1
ch 7
ch 0
ch 1
ch 7
Digin
ch 0
ch 1
ch 7
ch 0
ch 1
ch 7
ch 0
ch 1
ch 7




Model-302
showing multi-chan digital-input-calibration type scan with multiple-packets
( MULTI_CHAN_CAL_DIGIN_SCAN )
The following table shows how the buffers will look for a scan that includes 2 channels, except this time we'll ask for 3 packets - that means that   usNumPointsToRead will be set to 9.   I'll condense the table a little bit so it will all fit, so just look at the tables above for better descriptions of the actual labels if you need to. The two examples above show what the buffers will look like if you only ask for one packet (all the data for all channels). The table below shows how the buffers will look when you ask for multiple packets. Asking for larger packets is fine, but it's very important that the value you set "usNumPointsToRead"   is divisable by the number of channels that you're scanning. Be sure to include the calibration channel in that count. Since the calibration channel is actually one of the active channels, please note that a 6 channel scan and a 7 channel scan will both return 7 channels since the offset channel is automatically returned with that type of scan.
first row shows data, second shows digital input  
 
|----- first packet -----|
|----- second packet -----|
|----- third packet -----|
Data
ch 0
ch 1
ch 7
ch 0
ch 1
ch 7
ch 0
ch 1
ch 7
Digin
ch 0
ch 1
ch 7
ch 0
ch 1
ch 7
ch 0
ch 1
ch 7
 


Most scan related function calls allow more than one scan to be read with each call into the DLL
Prior to retrieving the scan data, there are associated function calls that allow you to receive either the number of points, or the number of scans within the buffer. The function calls preceded with  EX_  provide you with number of scans, while most of the older calls provide you with the number of points.

Before making a call into the DLL to retrieve scan data, you will need to size your buffer appropriately. If you are provided with information concerning "number of points in the DLL buffer," you will need to round it off so that the number you request in the call to get the data is equivalent to an even number of channels per scan. For example, if you are doing a 5 channel scan and you are told that there are 18 points in the buffer, and you want to get all the data, the most you can request is 15 since 5 divides evenly into 15 but not into 18. If you do decide to get that many points, you will need to make sure your buffer is large enough. The contents of that buffer, for a model 302  ( remember the model 301 does not have 5 channels as shown further up )  for a multi-channel scan with digital input would then look like would then look like:

first row shows data, second shows digital input  
 
|----- first packet -----|
|----- second packet -----|
|----- third packet -----|
Data
ch 0
ch 1
ch 2
ch 3
ch 4
ch 0
ch 1
ch 2
ch 3
ch 4
ch 0
ch 1
ch 2
ch 3
ch 4
Digin
ch 0
ch 1
ch 2
ch 3
ch 4
ch 0
ch 1
ch 2
ch 3
ch 4
ch 0
ch 1
ch 2
ch 3
ch 4

If you are provided with number of scans, then you will need to size your buffer by multiplying the number of scans by the number of channels. Points are made up of 24-bits of data, and as mentioned elsehwere those points can be returned to you either as raw-data in the form of an integer type value, or the DLL can convert it to a voltage and return that to you, based on the function that you use to retrieve the data from the DLL.

top of this segment

back to page top

 this page last reviewed/modified: