C++ Function call prototypes

C/C++ function call prototypes by category
with complete documentations and links to VisualBasic and LabView prototypes

-- Prototypes for Win98/ME/2k/XP --

Initialization

Pre-initialization (optional)

BOOLEAN SP_DisableDialog(void);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)

**This call is now recommended for use by all applications except those that specifically require a runtime dialog based message box.

A call to this DLL function call prevents DLL from displaying a dialog box used for runtime messaging as well as handling of USB device connect/disconnect system messages. ActiveX, LabView, and some other application interfaces have problems with the Dialog's resources occupying their program space and will crash on exit if the Dialog box is used. ALWAYS call this function FIRST THING when the program first starts if you plan to make use of it within your application.

This function has been greatly improved since it's introduction and is now recommend that it be used when possible instead of using the MsgEnable flag in the LL_USB.INI file. However, keep in mind that if many devices are initialized with a single call to one of the initialization functions, there will no longer be a dialog box displayed to indicate the current status of the initialization, which can sometimes give the application the appearance as being "hung" while it is off in the DLL for the amount of time required to initialize many devices. Therefore, it is recommended that if the dialog box is disabled with this function, the application should place the call to the initialization within a timer or thread and make use of the newer SP_InitAllDevices() documented elsewhere within this documentation. Using that function, the application timer or thread can constantly poll the status of the initialization while handling other tasks rather than do nothingat all until the initialation process is completed.

Arguments

Return type:: 8-bit. 1 (true) = success, 0 (false) = failed

Intialization of DEVICES - (threaded and non-threaded versions)

NOTE: The non-threaded version does not return until all devices are initialized, but is often most convenient when initializing only one or two devices.

Threaded version offers much more features including constant access to initialization status and allows application to take care of other business while the DLL handles the initialization in the background - especially useful when initializing 3 or more devices.

back to "function calls by category"
back to "Table of Contents"
back to "List of all function calls"

For "old style" initialization go here

Method #1 (recommended for initializing less than 3 devices)
One of the recommended methods for initializing devices.

BOOLEAN SP_InitAllDevices(

USHORT* pausDevList, BYTE* pbNumDevices,
DOUBLE* padblRate, BOOLEAN fShowDevList);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)
goto LabView prototype
goto C/C++ code example

This call is used to initialize all devices listed in "pausDevList". Unlike typical serial devices, USB type devices require an enumeration process, followed by each device being initialized to set it to certain configuration parameters. Place all of the device IDs that you wish to initialize in the array pointed to by pDevList. The number of devices is limited to 32. The DLL will attempt to initialize whichever IDs are in that list. Any devices that fail to initialize will be removed from the list. On return, the list will contain only valid device ID's that initialized properly.

If scanning, do not place the devices that are currently scanning in the list since the DLL will automatically attempt to close and reenumerate any device that is currently in the list including the ones that are scanning if they are in the list.

This NON-THREADED version of the initialization function calls will not return until all devices in the "pausDevList" array have been initialized. If more than a couple of devices are to be initialized, the THREADED version of the initialization function calls, "SP_InitAllDevices_Thread()" shown below is recommended.

Arguments

pausDevList:: Pointer to a 32-member array of 16-bit USHORT data types representing the LL_USB devices that you wish to intitialize.
pbNumDevices:: Pointer to an 8-bit data type (BYTE). The DLL will set this to the number of valid devices that it found from the pDevList array described above.
padblRate:: Pointer to a 32-member array of 64-bit double data types representing the rates for the LL_USB devices that you wish to intitialize. The offsets in the array of each rate should correspond with the offsets of the appropriate DeviceID in the pDevList array described above. When the call returns the pDevList array described above and this array will have only valid entries in them. The DLL will reorganize the arrays if any of the desired devices failed to initialize so that there are no "holes" in the arrays. The corresponding alignment of the two arrays will be maintained.
fShowDevList:: This is an 8-bit data type used as a flag to let the DLL know if you'd like it do display the devce lists during the init process. It is recommended to set this flag to 0 except for special trouble shooting circumstances. When this flag is set, the DLL will display Windows style message boxes showing the device ID lists as it sees them during various stages of the initialization process.
Return type:: 8-bit. 1 (true) = success, 0 (false) = failed

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

Method #2 (recommended for initializing 3 or more devices)
Another method for initializing devices.

Includes supporting functions (must be used together)

BOOLEAN SP_InitAllDevices_Thread(

USHORT* pausDevList, DOUBLE* padblRate, BOOLEAN fShowDevList);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)

This call is used to initialize all devices. Unlike typical serial devices, USB type devices require an enumeration process, followed by each device being initialized to set it to certain configuration parameters. Place all of the device IDs that you wish to initialize in the array pointed to by pDevList. The number of devices is limited to 32. The DLL will attempt to initialize whichever IDs are in that list. Continue to call make calls to SP_GetInitThreadStat(), at your convenience and when it returns zero the thread has terminated and initialization is complete. You then will need to call SP_GetLastInitDevAndRates() to get a listing of all the devices from your original list that successfully initialized and the rate adjustments (if any) that had to be made to each.

If scanning, do not place the devices that are currently scanning in the list since the DLL will automatically attempt to close and reenumerate any device that is currently in the list including the ones that are scanning if they are in the list.

This THREADED version of the initialization function calls allow the DLL to return immediately from the call, so that your application can do other tasks while the devices are being enumerated and initialized. However, you should wait until all devices have been initialized before using any of them. There are support function calls such as SP_GetLastInitStat(), shown elsewhere, which can be used to get the status of the devices as they initialize. This call is especially useful when many devices are being initialized at the same time since the process can take as long as 3 or more seconds per device which can make the application seem to hang when calling the non-threaded SP_InitAllDevices() version of this call.

Arguments

pausDevList:: Pointer to a 32-member array of 16-bit USHORT data types representing the LL_USB devices that you wish to intitialize.
padblRate:: Pointer to a 32-member array of 64-bit double data types representing the rates for the LL_USB devices that you wish to intitialize. The offsets in the array of each rate should correspond with the offsets of the appropriate DeviceID in the pDevList array described above. When the call returns the pDevList array described above and this array will have only valid entries in them. The DLL will reorganize the arrays if any of the desired devices failed to initialize so that there are no "holes" in the arrays. The corresponding alignment of the two arrays will be maintained.
fShowDevList:: This is an 8-bit data type used as a flag to let the DLL know if you'd like it do display the devce lists during the init process. It is recommended to set this flag to 0 except for special trouble shooting circumstances. When this flag is set, the DLL will display Windows style message boxes showing the device ID lists as it sees them during various stages of the initialization process.
Return type:: 8-bit. 1 (true) = success, 0 (false) = failed

   back to "Table of Contents"
   back to "function calls by category"
   back to "List of all function calls"

Getting init-thread status (use only with SP_InitAllDevices_Thread shown above)

BOOLEAN SP_GetInitThreadStat(void);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)

Use this call to get the current status of the intialization thread after calling SP_InitAllDevices_Thread() shown above. When zero is returned, the initialization of the devices is completed. You can then make a call to SP_GetLastInitDevAndRates() to get a list of all the devices that correctly initialized and their rates. See documentaion for that call further down.

Arguments
Return type:: 8-bit. 1 (true) = success, 0 (false) = failed

   back to "Table of Contents"
   back to "function calls by category"
   back to "List of all function calls"

Getting final device-init info (use only with SP_InitAllDevices_Thread shown above)

BOOLEAN SP_GetLastInitDevAndRates( USHORT* pausDevList, DOUBLE* padblRate);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)

Use this call to get a listing of all devices that were successfully initialized in the call to SP_InitAllDevices_Thread() shown above.

Arguments
pausDevList:: Pointer to a 32-member array of 16-bit USHORT data types. The DLL will fill this array with the device IDs from the list that was originally passed in the call to SP_InitAllDevices_Thread() that successfully initialized.
padblRate:: Pointer to a 32-member array of 64-bit DOUBLE data types. The DLL will fill this array with the final rates of all devices originally passed in the call to SP_InitAllDevices_Thread() that successfully initialized.
Return type:: 8-bit. 1 (true) = success, 0 (false) = failed

   back to "Table of Contents"
   back to "function calls by category"
   back to "List of all function calls"

Device rate and calibration

Changing rate

BOOLEAN SP_SendRate(

DOUBLE* pdblRate, USHORT usDevID);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)
goto C/C++ code example

This call is used to change the rate of a device. If scanning, do not place the devices that are currently scanning in the list since the DLL will automatically attempt to close and reenumerate any device that is currently in the list including the ones that are scanning if they are in the list.

Arguments

pdblRate:: Pointer to a 64 bit data variable. This is the rate that the DLL will attempt to set the device to. Due to certain limitations of the device all rates aren't valid and may be adjusted slightly by the DLL. For example, a requested rate of 1000Hz may be altered to 1000.7Hz. The value pointed to by dblRate will be set to the actual rate that the device was set to.
Return type:: 8-bit. 1 (true) = success, 0 (false) = failed

System calibration

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

BOOLEAN SP_SystemCalibration(

USHORT usDevID, BYTE bCurChan);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)

This call is used to recalibrate a device. A full-scale and offset calibration is performed.If scanning, do not place the devices that are currently scanning in the list since the DLL will automatically attempt to close and reenumerate any device that is currently in the list including the ones that are scanning if they are in the list.

Arguments

usDevID:: 16-bit data variable representing the device that you wish to calibrate.
bCurChan:: 8-bit data type representing the current channel the device listed above is set to. The DLL needs to do channel changes during the system calibration process. Passing it this parameter allows it to return the channel to the original setting before returning.
Return type:: 8-bit. 1 (true) = success, 0 (false) = failed

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

Basic I/O

change channel

BOOLEAN SP_SendChan(

USHORT usDevID, BYTE bCurChan, BYTE* pbReserved);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)
goto C/C++ code example

This call is used to change the active channel of a device. It can be used anytime once the device has been initialized.

Valid channels for a Model-301 are 0,1,6,7 and for a Model-302 are 0-7. During multi-channel scan mode (explained elsewhere in this document), the channel changes are ignored. Channel 7 is concidered the "offset" channel and channel 6 is concidered the "full-scale" channel.

Arguments

usDevID:: 16-bit data variable representing the device that you wish to send channel change to.
bCurChan:: 8-bit data type representing the current channel the device listed above is to be set to.
pbReserved:: Pointer to an 8-bit data variable. This is currently reserved for future use.
Return type:: 8-bit. 1 (true) = success, 0 (false) = failed

send analog output (Model 302 only)

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

BOOLEAN SP_SendDAC(

USHORT usDevID, DOUBLE dblVoltage, BYTE bDAC, BYTE* pbReserved);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)
goto C/C++ code example

This call is used to send an analog voltage to a Model 302.

Arguments

usDevID:: 16-bit data variable representing the device that you wish to send analog data to.
dblVoltage:: Voltage to send to Model-302
bDAC:: 8-bit data variable that represents the channel to send the analog voltage to
pbReserved:: Pointer to an 8-bit data variable. This is currently reserved for future use.
Return type:: 8-bit. 1 (true) = success, 0 (false) = failed

send digital output

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

BOOLEAN SP_SendDigOut(

USHORT usDevID, BYTE bDigOut, BYTE* pbReserved);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)
goto C/C++ code example

This call is used to send a digital output value to the device. It can be used anytime once the device has been initialized. Valid digital output values are 0-255.

Arguments

usDevID:: 16-bit data variable representing the device that you wish to send the digital output to.
bDigOut:: 8-bit data variable that represents the desired digital output.
pbReserved:: Pointer to an 8-bit data variable. This is currently reserved for future use.
Return type:: 8-bit. 1 (true) = success, 0 (false) = failed

read digital input

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

The digital input value is automatically returned whenever the device is read. It's recommended to use one of the functions listed below to retrieve the digital input value and then throw away any unneeded return values that the function call returns. Both are explained just a little further down within this documentation.

SP_ReadWriteOneDevice()
SP_GetOneConversion()

back to "Table of Contents"
back to "function calls by category"

direct read/write of device

The following table shows a function call that will probably not be needed by developers using nothing except newer "SP_" style function calls throughout their application. The followoing is just a newer version of the old "SP_ReadWriteOneDevice()" function call which is prototyped elsewhere in this documentation.

BOOLEAN SP_ReadWriteOneDevice( BOOLEAN fReadWrite, BYTE* pabDynamicDataArray, USHORT usDevID, UINT* puiNumBytes, BYTE* pbDigIn, BYTE bCurChan, UINT* puiFlags);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)

Use this function call to read or write directly to the device. This function is supplied to give more functionality and ease of use to the developers who developed applications early in the development stages of our USB devices who made use of the "DLL_ReadWriteOneDevice()" function call.

Arguments

fReadWrite:

8-bit data variable that indicates whether the request is for a READ(1) or a WRITE(0)

pabDynamicDataArray:

This argument is a pointer to an array of 8-bit data either to be written to or read from depending on the value of the "fReadWrite" variable. If doing a READ request then the array must be large enough to hold 32 bytes of data. If doing a WRITE request, then the array is to contain the 8 bytes of data to be written to the device. Although much of the data used in the read and write is made use of for many of the read/write operations, the array must still be sized to the full size as just mentioned.

usDevID:

16-bit data variable representing the device that you wish to calibrate.

puiNumBytes:

Pointer to a 32-bit data variable. The DLL will set this value to the number of bytes that was either written or read from the device.

pbDigIn:

Pointer to an 8-bit data variable. The DLL will set this value to the current digital input value. The DLL reads the digital input every time that it reads the device.

bCurChan:

An 8-bit data variable containing the current channel the device is set to. If an I/O error occurs during the call, the DLL will attempt to recover from the error. Depending on the severity of the error, the currently selected channel could be lost and required resetting by the DLL.

puiFlags:

Pointer to a 32-bit data variable. The DLL uses the various bits of this variable to let the application know the status of the device including any errors that occured while trying to read/write to the device. If the variable is zero when the call returns, then there were no errors. If it's not zero then the bits as described in the table below indicate the current condition of the device.

Even though the "PWR_NO_RESET_REQUIRED" is not set by the DLL in this function call when there are no errors, the developer can assume that the device has power. We leave this bit unset in this call when there are no errors to make it easier for the developer to trap for a non-zero return value rather than having to do a specific bit-test even though no errors occured. This bit flag is also used by other function calls that checks the current status of the devices.

PWR_NO_RESET_REQUIRED	0x1
PWR_NO_DEVICE	0x2
PWR_RESET_PIPE_FAILED	0x4
PWR_RESET_PIPE_SUCCESS	0x8
PWR_RESET_DEV_FAILED	0x10
PWR_RESET_DEV_SUCCESS	0x20
PWR_NO_POWER	0x40
PWR_YES_POWER	0x80

Return type:

8-bit. 1 (true) = success, 0 (false) = failed

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

Polled data mode

get one conversion

BOOLEAN SP_GetOneConversion(

USHORT usDevID, UINT* uiConvRawCount,
BYTE bCurChan, BYTE* pbDigIn);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)
goto C/C++ code example

This call is used to read a single conversion from the device.

Arguments

usDevID:

16-bit data variable representing the device that you wish to read the voltage data from

uiConvRawCount:

Pointer to a 32-bit variable to contain the 24-bit data returned by the device. We return this as 24-bit data rather than attempt to convert it to a voltage within the DLL since some programmers prefer to set their own voltage range to apply to the 24-bit data rather than use a standard +-5 Volts.

An example of converting the 24-bit data returned above to a range of +-5 volts is shown below:

: INT iCntTemp = uiConvRawCount;
DOUBLE Voltage = (iCntTemp - 8388608) * 0.00000059604645

pbDigIn:

Pointer to an 8-bit data variable. The DLL will set this value to the current digital input value. The DLL reads the digital input every time that it reads the device.

Return type:

8-bit. 1 (true) = success, 0 (false) = failed

Special note:: If this call returns zero that could indicate a variety of error conditions such as the power or USB cable being disconnected. To find out the cause of the problem, we recommend calling SP_CheckPower() described elsewhere in this document. This call also has a self-recovery mechanism built in to recover from certain errors.

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

Scanning data mode

start scan DLL_ (see following notes)

There are two suggested methods for starting a scan depending on the programming language you are using. We recommend that VisualBasic or VisualC++ (or any C language) use the following prototype. If it is difficult for your language to pass structured data, then you must use the SP_StartScan function call instead. That function takes the required scan parameters passed in an array and builds the structure within the DLL making the process a little slower than the more efficient function prototyped below. The "LabView" programing language is one example of where it is easier to use the "SP_StartScan()" function call.

BOOLEAN DLL_StartScan_DIO(

USHORT usDevID, PSCAN_OBJECT pScanObj, BYTE bReserved);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)
goto C/C++ code example

This call is used to place a device into scan mode. If this call returns success then the device will be in scan mode and you can begin reading the data from the device using the function calls explained below and elsewhere within this document.

Arguments

usDevID:: 16-bit data variable representing the device that you wish to start scanning.
pScanObj:: Pointer to a structure of type    PSCAN_OBJECT.    When using VisualC++ be sure to set the alignment for the struct to 4-bytes. You can do that at the following location within your IDE:
     Project\settings\C/C++-\code generation
You can also set it using #pragma directives surrounding the struct within your header file:
     #pragma pack(push, 4)
     #pragma pack(pop)
bReserved:: 8-bit data variable. This is currently reserved for future use.
Return type:: 8-bit. 1 (true) = success, 0 (false) = failed

start scan (special) SP_ (see following notes)

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

There are two suggested methods for starting a scan depending on the programming language you are using. We recommend that LabView developers use the following function and that VisualC++ and VisualBasic developers use DLL_StartScan_DIO() function shown further up within this document. The following is designed specifically for development languages such as LabView that make it difficult to pass structured data of various sizes to a function within a DLL. Such languages require incoding such data in to similiar data types and then passing it within an array which is then decoded by the DLL. Since there is overhead involved in the decoding of the array, this function isn't recommended except when necessary for applications such as LabView.

BOOLEAN SP_StartScan(

USHORT usDevID, DOUBLE* padblScanObject);

Arguments

usDevID:: 16-bit data variable representing the device that you wish to send channel change to.
padblScanObject:: Pointer to an array of structured data. Each member of the structured data is cast as a double data type, placed into the array by the calling application, and then passed to the DLL. The DLL decodes the array for usage, and then recodes it before returning to the calling app.
Return type:: 8-bit. 1 (true) = success, 0 (false) = failed

read scan data DLL_ (see following notes)

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

There are two suggested methods for reading scan data depending on the programming language you are using. We recommend that VisualBasic or VisualC++ (or any C language) use the following prototype. If it is difficult for your language to pass structured data, then you must use the SP_ReadScanData function call instead. That function takes the required scan parameters passed in an array and builds the structure within the DLL making the process a little slower than the more efficient function prototyped below. The "LabView" programing language is one example of where it is easier to use the "SP_ReadScanData()" function call.

BOOLEAN DLL_ReadScanData_DIO(

USHORT usDevID, UINT* pauiDataBuff,
USHORT usNumPointsToRead, PSCAN_OBJECT pScanObj);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)
goto C/C++ code example

This call is used to read scan data from a device.

Arguments

usDevID:: 16-bit data variable representing the device that you wish to read scan data from
pScanObj:: Pointer to a structure of type    PSCAN_OBJECT.    When using VisualC++ be sure to set the alignment for the struct to 4bytes. You can do that at the following location within your IDE:
     Project\settings\C/C++-\code generation
You can also set it using #pragma directives surrounding the struct within your header file:
     #pragma pack(push, 4)
     #pragma pack(pop)
bReserved:: 8-bit data variable. This is currently reserved for future use.
Return type:: 8-bit. 1 (true) = success, 0 (false) = failed

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

read scan data (special) SP_ (see following notes)

There are two suggested methods for reading scan data depending on the programming language you are using. We recommend that LabView developers use the following function and that VisualC++ and VisualBasic developers use DLL_ReadScanData_DIO() function shown further up within this document. The following is designed specifically for development languages such as LabView that make it difficult to pass structured data of various sizes to a function within a DLL. Such languages require incoding such data in to similiar data types and then passing it within an array which is then decoded by the DLL. Since there is overhead involved in the decoding of the array, this function isn't recommended except when necessary for such applications such as LabView.

BOOLEAN SP_ReadScanData(

USHORT usDevID, USHORT usNumPointsToRead, UINT* pauiDataBuff, DOUBLE* padblScanObject);

This call is used to read scan data from a device. It's designed with the "LabView" development environment in mind.

Arguments

usDevID:

16-bit data variable representing the device that you wish to read scan data from.

usNumPointsToRead:

This is an 16-bit value that is set by the Application. This value should be set to the number of points that you wish to read with the call. This value must always be divisible by the total number of channels being scanned, which is also the minimum value that you set it to, with one exception:

: If you'd like to know how many points are available, you can set this value to 0 and make the call and then when you return, the SO_PointsInBuffer member of your ScanObject struct will contain the number of points available to be read. You can then make that value divisible by the total number of channels and repeat the call with the new request for the number of points you've just calculated.

It is recommended that you do not ask for a very large number of points (large number of scans) with each read. The reason is due to time slicing issues. If you make "usNumPointsToRead" and make the call, the DLL could take a long time to extract the data from it's buffer and make the transfer to your buffer before returning which could make your application appear to be "hung". If you see that you are falling behind in the buffer (SO_PointsInBuffer grows increasing large) it is better to make many consecutive calls to this function rather than try and ask for all the available data at once since that will allow your application a time slice between calls to handle any pending events (such as mouse movement etc).

pauiDataBuff:

Pointer to an array of 32-bit data.

NOTE: Please see "DLL_ReadScanData_DIO()" above for complete description of how the data is organized within this buffer.

padblScanObject:

Pointer to an array of structured data. Each member of the structured data is cast as a double data type, placed into the array by the calling application, and then passed to the DLL. The DLL decodes the array for usage, and then recodes it before returning to the calling app.

bReserved:

8-bit data variable. This is currently reserved for future use.

Return type:

8-bit. 1 (true) = success, 0 (false) = failed

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

read scan data with digital input DLL_ (see following notes)

There are two suggested methods for reading scan data with digital input depending on the programming language you are using. We recommend that VisualBasic or VisualC++ (or any C language) use the following prototype. If it is difficult for your language to pass structured data, then you must use the SP_ReadScanDataWithDigin() function call instead. That function takes the required scan parameters passed in an array and builds the structure within the DLL making the process a little slower than the more efficient function prototyped below. The "LabView" programing language is one example of where it is easier to use the "SP_ReadScanDataWithDigin()" function call.

BOOLEAN DLL_ReadScanDataWithDigin(

USHORT usDevID, UINT* pauiDataBuff, BYTE* pabDiginBuff,
BYTE* pbCurChan, USHORT usNumPointsToRead, PSCAN_OBJECT pScanObj);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)

This call is used to read scan data from a device.

Arguments

usDevID:
16-bit data variable representing the device that you wish to read scan data from.

pauiDataBuff:
Pointer to an array of 32-bit data. Each member of the this array contains the 24-bit data that corresponds with the 8-bit digital input value read by the device. When the device has been set to use this scanning mode, it will read the digital input each time it reads a point from the A/D converter. It will place the 24-bit data into this array and the 8-bit digital input in the pabDiginBuff at the same offsets. When reading the data from this array, use the same offset to read the data from the pabDiginBuff array. This type of scan is most useful for using the digital input value to trigger on, or mark certain data points as corresponding with certain digital input values.

Model-301
showing 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 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 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 digital-input-calibration type scan with multiple-scans
( 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 scans - 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 scan (all the data for all channels). The table below shows how the buffers will look when you ask for multiple scans. Asking for larger scans 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 scan -----| |----- second scan -----| |----- third scan -----|

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

pabDiginBuff

Pointer to an array of 8-bit data. When the device has been set to use this scanning mode, it will read the digital input each time it reads a point from the A/D converter. Each member of the this array contains the digital input value that corresponds with the 24-bit data read by the device. Please see the tables above for the coding of the array.

pbCurChan:

This is an 8-bit value that is set by the DLL prior to returning from the call. This should always equal zero if you've requested the correct number of points to be read to match the number of channels being scanned and the offset calibration if included. Be certain that you understand the buffer organizations as shown in the tables above. The number of points read should always be divisible by the TOTAL number of channels being read. If not the data stream will become corrupted.

usNumPointsToRead:

: If you'd like to know how many points are available, you can set this value to 0 and make the call and then when you return, the SO_PointsInBuffer member of your ScanObject struct will contain the number of points available to be read. You can then make that value divisible by the total number of channels and repeat the call with the new request for the number of points you've just calculated.

pScanObj:

Pointer to a structure of type PSCAN_OBJECT - see DLL_ReadScanData_DIO() function above for link to structure definition and details. When using VisualC++ be sure to set the alignment for the struct to 4bytes. You can do that at the following location within your IDE:
     Project / settings / C/C++- / code generation
You can also set it using #pragma directives surrounding the struct within your header file:
     #pragma pack(push, 4)
     #pragma pack(pop)

Return type:

8-bit. 1 (true) = success, 0 (false) = failed

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

read scan data with digital input (special) SP_ (see following notes)

There are two suggested methods for reading scan data with digital input depending on the programming language you are using. We recommend that LabView developers use the following function and that VisualC++ and VisualBasic developers use DLL_ReadScanDataWithDigin() function shown further up within this document. The following is designed specifically for development languages such as LabView that make it difficult to pass structured data of various sizes to a function within a DLL. Such languages require incoding such data in to similiar data types and then passing it within an array which is then decoded by the DLL. Since there is overhead involved in the decoding of the array, this function isn't recommended except when necessary for such applications such as LabView.

BOOLEAN SP_ReadScanDataWithDigin(

USHORT usDevID, UINT* pauiDataBuff, BYTE* pabDiginBuff,
BYTE* pbCurChan, USHORT usNumPointsToRead, DOUBLE* padblScanObject);

This call is used to read scan data from a device. It's designed with the "LabView" development environment in mind.

Arguments

usDevID:: 16-bit data variable representing the device that you wish to read scan data from.
pauiDataBuff:: Pointer to an array of 32-bit data.

NOTE: Please see "DLL_ReadScanDataWithDigin()" above for complete description of how the data is organized within this buffer.
pabDiginBuff: Pointer to an array of 8-bit data.

NOTE: Please see "DLL_ReadScanDataWithDigin()" above for complete description of how the data is organized within this buffer.
pbCurChan:
padblScanObject:: Pointer to an array of structured data. Each member of the structured data is cast as a double data type, placed into the array by the calling application, and then passed to the DLL. The DLL decodes the array for usage, and then recodes it before returning to the calling app.
bReserved:: 8-bit data variable. This is currently reserved for future use.
Return type:: 8-bit. 1 (true) = success, 0 (false) = failed

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

write to device while scanning (special) SP_ (see following notes)

This is the recommended function call to use to write (send a command and argument) to a device while in scanning mode.

BOOLEAN SP_WriteWhileScanning(

USHORT usDevID, BYTE bCmnd, BYTE bArg, UINT* puiCurWriteStat);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)

We recommend that developers use this call especially when writing repeatedly to a device while scanning. We developed this function specifically for the constant sending of digital outputs. Other ways of sending digital outputs such as "SP_SendDigout()" aren't as efficient while scanning since they require many different threads as well as memory usage that this one does not. When this function is used, the command is sent immediately to the device driver, inserted into it's code stream, and then executed at the most opportune time. We currently recommend only using this call for the "digital output" command 0x02 since that is the only one that has been fully tested at the time of this writing.

Arguments

usDevID:

16-bit data variable representing the device that you wish to write to while scanning.

bCmnd:

8-bit data type representing the command token to be sent to the device.
NOTE: We currently recommend only the use of the digital output command token, "2". Any other token could cause erroneous behavior

bArg

8-bit data type representing the command token to be sent to the device.
NOTE: We currently recommend only the use of the argument for the digital output command, "0-255".

puiCurWriteStat

Pointer to a 32-bit data type. Upon return, the variable pointed to will have various bits set to indicate the status of the write.

'NOTE: The following are possible bit settings for puiCurWriteStat shown above

#define SCAN_WRITE_DO_WRITE	0x01	(Caller sets) request to write cmnd and arg passed in call
#define SCAN_WRITE_PENDING	0x02	(DLL sets) write is pending
#define SCAN_WRITE_SUCCESS	0x04	(DLL sets) last write succeeded
#define SCAN_WRITE_FAILED	0x08	(DLL sets) write failed
#define SCAN_WRITE_CANCEL	0x10	(Caller sets) request cancel of write
#define SCAN_WRITE_RET_STATS	0x20	(Caller sets) request current status of the write
#define SCAN_WRITE_DEVICE_UNKNOWN	0x40	(DLL sets) could not find the device connected
#define SCAN_WRITE_DEVICE_NOT_SCANNING	0x80	(DLL sets) the device isn't scanning
#define SCAN_WRITE_MEMORY_ERR	0x100	(DLL sets) Failed to allocate memory for the write

Return type:

8-bit. 1 (true) = success, 0 (false) = failed

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

end scan DLL_ (see following notes)

There are two function calls available for ending a scan this version of the end-scan function is an old style. All but one of the aguments for this function are now ignored, so it is recommended that you now use the newer "SP_EndScan" function shown below.

Please use newer SP_EndScan function shown further down within this document BOOLEAN DLL_EndScan_DIO(

USHORT usDevID, BOOLEAN fReserved, UINT uiReserved, BYTE bReserved);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)

This function takes the device out of scanning mode and must be called to terminate a scan. If you are scanning, you must always call this function before exiting your application or reinitializing the scanning device.

Arguments

usDevID:: 16-bit data variable representing the device that you wish to end the scan.
fReserved:: value ignored but must be present
uiReserved:: value ignored but must be present
bEmptyBuffer:: value ignored but must be present
Return type:: 8-bit. 1 (true) = success, 0 (false) = failed

end scan (NEW) SP_ (see following notes)

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

There are two function calls available for ending a scan.
This is the recommended function call for taking the device out of scanning mode.

BOOLEAN SP_EndScan(

USHORT usDevID);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)
goto C/C++ code example

Arguments

usDevID:: 16-bit data variable representing the device that you wish to read scan data from
Return type:: 8-bit. 1 (true) = success, 0 (false) = failed

back to "DLL_EndScan( )"
back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

Miscellaneous functions

get last device initialization status

BOOLEAN SP_GetLastInitStat(USHORT* pDevList, UINT* puiFlags);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)

This call is used to determine that status of the devices from the last call to either SP_InitAllDevices_Thread() or SP_InitAllDevices().

Arguments

pDevList:: Pointer to a 32-member array of the 16-bit data that represent the devices that you wish to determine the status of. Please be sure to put only devices for which you want the status checked in this list and set the unused indexes to zero.
puiFlags:: Pointer to a 32-bit data variable. The DLL uses the various bits of this variable to let the application know the status of the device including any errors that occured while trying to read/write to the device during the last intitialization process. The SP_ style intitialization functions have built-in functionality to recover from errors, so even though an error flag bit is set, as long as the recovery bit flag is also set, there is nothing to worry about.

Return type:

8-bit. 1 (true) = success, 0 (false) = failed

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

Get device status (single device)

BOOLEAN SP_GetDevStat(

USHORT usDevID, UINT* puiDevStat);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)

This call is used to get the current status of a multiple devices. It will determine it the USB cable is connected and if the device is enumerated and ready to be read or written to.

Arguments

usDevID:

16-bit data variable representing the device that you wish to check the status of.

puiDevStat:

The following table shows the possible values that the DLL will set the variable pointed to by puiDevStat, indicating the status of the device.

DEV_NOT_FOUND	0x0
DEV_FOUND	0x1
DEV_DISCONNECTED	0x2
DEV_ENUMERATED	0x4
DEV_READY	0x8
DEV_OWNED_BY_ANOTHER	0x10
DEV_UNKNOWN_ERR	0x20

Return type:

8-bit. 1 (true) = success, 0 (false) = failed

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

get device status (multiple devices)

BOOLEAN SP_GetDevStatEx(

UINT* puiaDevStat, USHORT* pausAllDevList, BYTE* pbNumDevices);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)

This call is used to get the current status of a multiple devices. It will determine it the USB cable is connected and if the device is enumerated and ready to be read or written to.

Arguments

puiaDevStat:

Pointer to a 32-member 32-bit array which you should pre-initialize to all zeros. The DLL will check the status of all devices listed in the "pausAllDevList" array and set the corresponding index within the array pointed to by this variable to the status of that device. The following table shows the possible status of a device.

DEV_NOT_FOUND	0x0
DEV_FOUND	0x1
DEV_DISCONNECTED	0x2
DEV_ENUMERATED	0x4
DEV_READY	0x8
DEV_OWNED_BY_ANOTHER	0x10
DEV_UNKNOWN_ERR	0x20

pausAllDevList:

Pointer to a 32-member array of the 16-bit data that represent the devices that you wish to determine the status of. Pleas be sure to put only devices for which you wan the status checked in this list and set the unused indexes to zero.

pbNumDevices:

Pointer to an 8-bit byte type variable that the DLL will set to the total number of valid devices that it finds.

Return type:

8-bit. 1 (true) = success, 0 (false) = failed

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

check power

BOOLEAN SP_CheckPower(

USHORT usDevID, BYTE bCurChan, BYTE* pbDigin, UINT* puiFlags);

goto VisualBasic prototype (Win98/ME)
goto VisualBasic prototype (Win2k/XP)

This call is used to determine if the main power cable is connected to the device. The main power cable controls the actual A/D converter while the USB cable supplies power to the portion of the hardware used to communicate with the device driver. If the main power is disconnected, communication to the hardware will not be lost, but A/D conversion will no longer be possible until the power is restored. If the power was disconnected prior to this call but has been reconnected, this call will attempt to reinitialize the A/D converter by attempting to retrieve on data point.

Arguments

usDevID:: 16-bit data variable representing the device that you wish to check the power for.
bCurChan:: An 8-bit data variable containing the current channel the device is set to. If an I/O error occurs during the call, the DLL will attempt to recover from the error. Depending on the severity of the error, the currently selected channel could be lost and required resetting by the DLL.
puiNumBytes:: Pointer to a 32-bit data variable. The DLL will set this value to the number of bytes that was either written or read from the device.
pbDigIn:: Pointer to an 8-bit data variable. The DLL will set this value to the current digital input value. The DLL reads the digital input every time that it reads the device.
puiFlags:: Pointer to a 32-bit data variable. The DLL uses the various bits of this variable to let the application know the status of the device including any errors that occured while trying to read/write to the device. If the variable is zero when the call returns, then there were no errors. If it's not zero then the bits as described in the table below indicates the current condition of the device.

Even though the "PWR_NO_RESET_REQUIRED" is not set by the DLL in this function call when there are no errors, the developer can assume that the device has power. We leave this bit unset in this call when there are no errors to make it easier for the developer to trap for a non-zero return value rather than having to do a specific bit-test even though no errors occured. This bit flag is also used by other function calls that checks the current status of the devices.

pausAllDevList:

pbNumDevices:

Pointer to an 8-bit byte type variable that the DLL will set to the total number of valid devices that it finds.

Return type:

8-bit. 1 (true) = success, 0 (false) = failed

back to "Table of Contents"
back to "function calls by category"
back to "List of all function calls"

reset a device

get copy of registry device list

boost process priority level

System calibration

C/C++ Developer's API usage examples

back

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