Lawson Labs, Inc.
USB Data Acquisition System
Developer's API guide
 

old   api.doc  archive
Download   301 / 302   drivers & sample apps from website
What's new
FAQ
Table of Contents

How to use this document
Getting started

LL_USB.INI file usage
Read all about it



API Overview
prototyping
variable types



Listing of all function calls
(no prototypes or other info)

List of all function calls



Function calls by category
Prototypes and info for all function calls by category

C/C++ style prototypes(Win 98/ME/2k/XP)
VisualBasic style prototypes (Win98 & WinME)
VisualBasic style prototypes (Win2k & WinXP
LabView style prototypes (Win98 & WinME)


API Usage Example
Examples showing coding for
initialization, rate change, syscal, digital I/O,
and use of polled and scanning modes
C/C++ Developer example
VisualBasic Developer example
LabView Developer example




























































 
Function calls by category
the following links will take you to standard   C/C++   prototypes and complete explanations for each of the function groups. There are additional links from there to prototypes and documentation for both   VisualBasic   and LabView   development languages.

Initialization
pre-initialization (optional)
intialization of Devices

Device rate and calibration
changing rate
system calibration


Basic I/O
change channel
send digital output
send analog output
read digital input
read or write of device

Polled data mode
get one conversion

Scanning data mode
start scan
read scan data
read scan data with digital input
end scan


back to Table of Contents























































Overview - All Platforms (Win-98/ME/2k/XP)


How to use this document

Getting started

This document is organized into sections to show various ways of interracting with our DLL. It is suggested that you make the "Table of Contents" your starting point. This document lists all DLL entry points with their prototypes in both C style and VisualBasic style as well as a brief description of each.

The DLL has a wide assortment of function calls. We are continuously updating the DLL with new entry points to make the developers task of communicating with our USB devices easier. In doing so, we also strive to keep the DLL backward compatible for those who have been using our earlier DLL and already have applications developed with particular DLL entry points and functionality taken into concideration.

As we add new entry points, we will sometimes prefix them a particular way to assist the developer in know which are the older and which are the newer entry points. A good example of this is entry points that begin with the "SP_" prefix. Such entry points are the easiest means to interface between the DLL and the application making the calls. However all "SP_" style function calls aren't best suited for every style of programming language. For example the following calls are most efficient and should be used when possible by applications using the C or VisualBasic programming language.
DLL_StartScan_DIO()
DLL_ReadScanData_DIO()
DLL_ReadScanDataWithDigin()

To take the explanation of the "SP_" prefixed function usage a little further, you'll notice that using the "SP_InitAllDevices(...)" entry point will do everything that a developer once had to do by doing the following calls and/or tasks:
  1.)   DLL_Init(...)
  2.)   DLL_ReadWriteDevice(...) - send signon token
  3.)   handle any errors such as reset of device if write failed
  4.)   DLL_ReadWriteDevice(...) - read bytes returned from signon
  5.)   handle any errors such as reset of device if bytes echoed above were incorrect
  6.)   DLL_ReadWriteDevice(...) - send rate
  7.)   handle any errors such as reset of device if write failed
  8.)   DLL_ReadWriteDevice(...) - read bytes returned from sending rate
  9.)   handle any errors such as reset of device if bytes echoed above were incorrect
10.)   DLL_SetRate - let DLL know what the new rate was set to

It should also be noted that any device can be reinitialized by calling the function described above with the single device placed in the Device ID list passed as an argument in the function call.

back






API Overview

Prototyping

This document lists all prototypes for all DLL entry points that currently exist. You may need to use only a handful of these function calls. We recommend using function calls prefixed with "SP_" for any new application development. The explanation in the "getting started" section of this documentation gives an example of why. As of this time, there aren't "SP_" related functions for every task that work best for every application. For example, when using a C or VB language, it's recommended that you continue to use the following two "old style" function calls rather than their "SP_" counterparts:
DLL_StartScan_DIO()
DLL_ReadScanData_DIO()
DLL_ReadScanDataWithDigin()
The functions above are more efficient than their  "SP_"  counterparts. The newer  "SP_"  functions that serve the same purpose were created for languages that have restrictions concerning passing of structured data between an application and DLL.

The "Table of Contents" contains links to all function call prototypes for use by various development environments as well as example code showing their usage. We have made many improvemnents in our API since it's beginning. We've created new entry points into our DLL that help make the developer's job easier. However, we still support the "old style" function calls that we created in the beginning stages of development. Some of the older calls are still the most efficient. The older style calls are prefixed with  DLL_  while the newer calls are prefixed with  SP_ . It's fine to mix some of the older ones with the newer ones to make coding of your applications a little easier. For example some very early developers used  "DLL_ReadWriteOneDevice(...)"  with a particular token to read one data point from the device and also had to deal with certain error conditions for example if the power supply to the hardware, or even the USB cable had been disconnected and then reconnected. Those developers can still use all of their original old style commands for initialization, but replace the old way of getting one data point with the new call to  "SP_GetOneConversion(...).

If a developer would prefer to use the old style method to read/write the a device, but would like to know the condition of the device and have the DLL try to recover from any errors, then they could replace the call to  "DLL_ReadWriteOneDevice(...)"  with a call to  "SP_ReadWriteOneDevice(...)"  as described elsewhere in this document. That function call not only attempts to read or write the device (depending on the argument) but also attempts to recover from any I/O error and then set flags (also passed as an argument) to indicate the current state of the device.

The prototypes shown in this document default to the  "C"  language style prototype. Following each prototype is a link to the VisualBasic style prototype for the function call.

It's important to note that our DLL uses a BOOLEAN data type in many of the prototypes. The size of that data type is one BYTE or 8-bits. That issue is also discussed in the "variable types" section of this document. Also note that the calling conventions is   "_stdcall". The data alignment for structured data is  "4 bytes"   which is the default for most simplified programming environments such as VisualBasic and LabView which don't have the option to set such an alignment. We suggest that VisualC++ programmers either set that option in their compiler settings or force the setting in their source files using the appropriate   "#pragma pack(push, 4)"   and   "#pragma pack(pop)"   directives.

back





Variable types

The following is a chart of the various data types used as either passed or return arguments in function calls to DLL. For those non-C programmers, note that an asterix following a variable within a prototype, such as BYTE*, indicates the argument to be a pointer to either a variable or an array of that data type. The function call prototypes will indicate whether the pointer is to a variable or an array.

  TYPE   SIZE
PREFIX
  EXAMPLE
  BOOLEAN   8-bit unsigned data type (1=TRUE, 0=FALSE)
  f
 fCallRetVal
  BYTE   8-bit unsigned data type
  b
 bNumChans
  USHORT   16-bit unsigned data type
  us
 usDeviceID
  SHORT   16-bit signed data type
  s
 sPlusMinusVal_16
  UINT   32-bit unsigned data type
  ui
 uiRawCount
  INT   32-bit signed data type
  i
 iPlusMinusVal_32
  DOUBLE   64-bit floating point data type
  dbl
 dblVoltage
  STRING   zero delimited string
  sz
 szMyString

Below is an example of a pointer to a unsigned short variable type followed by an example of a pointer to an array of unsigned short data types. Note that one example is prefixed with "pus" and the other with "paus".

  USHORT*   pointer to a 16-bit variable
  pus
 pusMyDevice
  USHORT*   pointer to array of 16-bit data types
  paus
 pausMyDevices

back to main page Table of Contents    (use browser "back" button to go back to other locations)








lawsnlab@lawsonlabs.com
last reviewed/modified: 9-29-03 (Tim Van Dusen)