Some parameters are common to many functions:
To maintain compatibility with as many languages as possible, every attempt has been made to keep the parameter types very basic. Also, many functions have multiple prototypes. The declarations that follow, are written in C.
To help those unfamiliar with strings in C, these functions expect null terminated 8 bit ASCII strings. How this translates to a particular development environment is beyond the scope of this documentation. A const char * is a pointer to a string that won’t be changed by the driver. Usually this means it can simply be a constant such as “this is a string”. A char * is a pointer to a string that will be changed. Enough bytes must be preallocated to hold the possible strings that will be returned. Functions with char * in their declaration will have the required length of the buffer documented below.
Pointers must be initialized in general, although null (0) can be passed for unused or unneeded values. The pointers for GetStreamData and RawIn/RawOut requests are not optional. Arrays and char * type strings must be initialized to the proper size before passing to the DLL.
Returns all the devices found of a given DeviceType and ConnectionType. Searching over Ethernet relies on the DiscoveryUDP function (Section 5.2.3), which might not work on certain network configurations.
ListAllS() is a special version where DeviceType and ConnectionType are strings rather than longs. This is useful for passing string constants in languages that cannot include the header file. The strings should contain the constant name as indicated in the header file (such as “LJ_dtUE9” and ”LJ_ctUSB”). The declaration for the S version of open is the same as below except for (const char *pDeviceType, const char *pConnectionType, …).
Declaration:
LJ_ERROR _stdcall ListAll ( long DeviceType,
long ConnectionType,
long *pNumFound,
long *pSerialNumbers,
long *pIDs,
double *pAddresses)
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
Outputs:
Call OpenLabJack() before communicating with a device. This function can be called multiple times, however, once a LabJack is open, it remains open until your application ends (or the DLL is unloaded). If OpenLabJack is called repeatedly with the same parameters, thus requesting the same type of connection to the same LabJack, the driver will simply return the same LJ_HANDLE every time. Internally, nothing else happens. This includes when the device is reset, or disconnected. Once the device is reconnected, the driver will maintain the same handle. If an open call is made for USB, and then Ethernet, a different handle will be returned for each connection type and both connections will be open.
OpenLabJackS() is a special version of open where DeviceType and ConnectionType are strings rather than longs. This is useful for passing string constants in languages that cannot include the header file. The strings should contain the constant name as indicated in the header file (such as “LJ_dtUE9” and ”LJ_ctUSB”). The declaration for the S version of open is the same as below except for (const char *pDeviceType, const char *pConnectionType, …).
Declaration:
LJ_ERROR _stdcall OpenLabJack ( long DeviceType,
long ConnectionType,
const char *pAddress,
long FirstFound,
LJ_HANDLE *pHandle)
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
Outputs:
The eGet and ePut functions do AddRequest, Go, and GetResult, in one step.
The eGet versions are designed for inputs or retrieving parameters as they take a pointer to a double where the result is placed, but can be used for outputs if pValue is preset to the desired value. This is also useful for things like StreamRead where a value is input and output (number of scans requested and number of scans returned).
The ePut versions are designed for outputs or setting configuration parameters and will not return anything except the errorcode.
eGetPtr() is a 32-bit and 64-bit pointer-address-safe version of the eGet function where the x1 parameter is a void *. This is required when passing a pointer safely to x1. When passing a non-pointer long value to x1, use the normal version of the function. The declaration for the Ptr version is the same as the normal version except for (…, void *x1).
eGetS() and ePutS() are special versions of these functions where IOType is a string rather than a long. This is useful for passing string constants in languages that cannot include the header file, and is generally used with all IOTypes except put/get config. The string should contain the constant name as indicated in the header file (such as “LJ_ioANALOG_INPUT”). The declarations for the S versions are the same as the normal versions except for (…, const char *pIOType, …).
eGetSS() and ePutSS() are special versions of these functions where IOType and Channel are strings rather than longs. This is useful for passing string constants in languages that cannot include the header file, and is generally only used with the put/get config IOTypes. The strings should contain the constant name as indicated in the header file (such as “LJ_ioPUT_CONFIG” and “LJ_chLOCALID”). The declaration for the SS versions are the same as the normal versions except for (…, const char *pIOType, const char *pChannel, …).
The declaration for ePut is the same as eGet except that Value is not a pointer (…, double Value, …), and thus is an input only.
Declaration:
LJ_ERROR _stdcall eGet ( LJ_HANDLE Handle,
long IOType,
long Channel,
double *pValue,
long x1)
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
Outputs:
Declaration:
LJ_ERROR _stdcall ePut ( LJ_HANDLE Handle,
long IOType,
long Channel,
double Value,
long x1)
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
Outputs:
This function passes multiple requests via arrays, then executes a GoOne() and returns all the results via the same arrays.
The parameters that start with “*a” are arrays, and all must be initialized with at least a number of elements equal to NumRequests.
Declaration:
LJ_ERROR _stdcall eAddGoGet ( LJ_HANDLE Handle,
long NumRequests,
long *aIOTypes,
long *aChannels,
double *aValues,
long *ax1s,
long *aRequestErrors,
long *GoError,
long *aResultErrors)
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
Outputs:
Adds an item to the list of requests to be performed on the next call to Go() or GoOne().
When AddRequest() is called on a particular Handle after a Go() or GoOne() call, all data from previous requests is lost and cannot be retrieved by any of the Get functions until a Go function is called again. This is on a device by device basis, so you can call AddRequest() with a different handle while a device is busy performing its I/O.
AddRequest() only clears the request and result lists on the device handle passed and only for the current thread. For example, if a request is added to each of two different devices, and then a new request is added to the first device but not the second, a call to Go() will cause the first device to execute the new request and the second device to execute the original request.
In general, the execution order of a list of requests in a single Go call is unpredictable, except that all configuration type requests are executed before acquisition and output type requests.
AddRequestPtr() is a 32-bit and 64-bit pointer-address-safe version of the Add function where the x1 parameter is a void *. This is required when passing a pointer safely to x1. When passing a non-pointer long value to x1, use the normal AddRequest() function. The declaration for the Ptr version of Add is the same as below except for (…, void *x1, …).
AddRequestS() is a special version of the Add function where IOType is a string rather than a long. This is useful for passing string constants in languages that cannot include the header file, and is generally used with all IOTypes except put/get config. The string should contain the constant name as indicated in the header file (such as “LJ_ioANALOG_INPUT”). The declaration for the S version of Add is the same as below except for (…, const char *pIOType, …).
AddRequestSS() is a special version of the Add function where IOType and Channel are strings rather than longs. This is useful for passing string constants in languages that cannot include the header file, and is generally only used with the put/get config IOTypes. The strings should contain the constant name as indicated in the header file (such as “LJ_ioPUT_CONFIG” and “LJ_chLOCALID”). The declaration for the SS version of Add is the same as below except for (…, const char *pIOType, const char *pChannel, …).
Declaration:
LJ_ERROR _stdcall AddRequest ( LJ_HANDLE Handle,
long IOType,
long Channel,
double Value,
long x1,
double UserData)
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
Outputs:
After using AddRequest() to make an internal list of requests to perform, call Go() to actually perform the requests. This function causes all requests on all open LabJacks to be performed. After calling Go(), call GetResult() or similar to retrieve any returned data or errors.
Go() can be called repeatedly to repeat the current list of requests. Go() does not clear the list of requests. Rather, after a call to Go(), the first subsequent AddRequest() call to a particular device will clear the previous list of requests on that particular device only.
Note that for a single Go() or GoOne() call, the order of execution of the request list cannot be predicted. Since the driver does internal optimization, it is quite likely not the same as the order of AddRequest() function calls. One thing that is known, is that configuration settings like ranges, stream settings, and such, will be done before the actual acquisition or setting of outputs.
Declaration:
LJ_ERROR _stdcall Go()
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
Outputs:
After using AddRequest() to make an internal list of requests to perform, call GoOne() to actually perform the requests. This function causes all requests on one particular LabJack to be performed. After calling GoOne(), call GetResult() or similar to retrieve any returned data or errors.
GoOne() can be called repeatedly to repeat the current list of requests. GoOne() does not clear the list of requests. Rather, after a particular device has performed a GoOne(), the first subsequent AddRequest() call to that device will clear the previous list of requests on that particular device only.
Note that for a single Go() or GoOne() call, the order of execution of the request list cannot be predicted. Since the driver does internal optimization, it is quite likely not the same as the order of AddRequest() function calls. One thing that is known, is that configuration settings like ranges, stream settings, and such, will be done before the actual acquisition or setting of outputs.
Declaration:
LJ_ERROR _stdcall GoOne( LJ_HANDLE Handle )
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
Outputs:
Calling either Go function creates a list of results that matches the list of requests. Use GetResult() to read the result and errorcode for a particular IOType and Channel. Normally this function is called for each associated AddRequest() item. Even if the request was an output, the errorcode should be evaluated.
None of the Get functions will clear results from the list. The first AddRequest() call subsequent to a Go call will clear the internal lists of requests and results for a particular device.
When processing raw in/out or stream data requests, the call to a Get function does not actually cause the data arrays to be filled. The arrays are filled during the Go call (if data is available), and the Get call is used to find out many elements were placed in the array.
GetResultS() is a special version of the Get function where IOType is a string rather than a long. This is useful for passing string constants in languages that cannot include the header file, and is generally used with all IOTypes except put/get config. The string should contain the constant name as indicated in the header file (such as “LJ_ioANALOG_INPUT”). The declaration for the S version of Get is the same as below except for (…, const char *pIOType, …).
GetResultSS() is a special version of the Get function where IOType and Channel are strings rather than longs. This is useful for passing string constants in languages that cannot include the header file, and is generally only used with the put/get config IOTypes. The strings should contain the constant name as indicated in the header file (such as “LJ_ioPUT_CONFIG” and “LJ_chLOCALID”). The declaration for the SS version of Get is the same as below except for (…, const char *pIOType, const char *pChannel, …).
It is acceptable to pass NULL (or 0) for any pointer that is not required.
Declaration:
LJ_ERROR _stdcall GetResult ( LJ_HANDLE Handle,
long IOType,
long Channel,
double *pValue)
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
Outputs:
Calling either Go function creates a list of results that matches the list of requests. Use GetFirstResult() and GetNextResult() to step through the list of results in order. When either function returns LJE_NO_MORE_DATA_AVAILABLE, there are no more items in the list of results. Items can be read more than once by calling GetFirstResult() to move back to the beginning of the list.
UserData is provided for tracking information, or whatever else the user might need.
None of the Get functions clear results from the list. The first AddRequest() call subsequent to a Go call will clear the internal lists of requests and results for a particular device.
When processing raw in/out or stream data requests, the call to a Get function does not actually cause the data arrays to be filled. The arrays are filled during the Go call (if data is available), and the Get call is used to find out many elements were placed in the array.
It is acceptable to pass NULL (or 0) for any pointer that is not required.
The parameter lists are the same for the GetFirstResult() and GetNextResult() declarations.
Declaration:
LJ_ERROR _stdcall GetFirstResult ( LJ_HANDLE Handle,
long *pIOType,
long *pChannel,
double *pValue,
long *px1,
double *pUserData)
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
Outputs:
Some special-channels of the config IOType pass IP address (and others) in a double. This function is used to convert the double into a string in normal decimal-dot or hex-dot notation.
Declaration:
LJ_ERROR _stdcall DoubleToStringAddress ( double Number,
char *pString,
long HexDot)
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
Outputs:
Some special-channels of the config IOType pass IP address (and others) in a double. This function is used to convert a string in normal decimal-dot or hex-dot notation into a double.
Declaration:
LJ_ERROR _stdcall StringToDoubleAddress ( const char *pString,
double *pNumber,
long HexDot)
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
Outputs:
Converts the given string to the appropriate constant number. Used internally by the S functions, but could be useful to the end user when using the GetFirst/Next functions without the ability to include the header file. In this case a comparison could be done on the return values such as:
if (IOType == StringToConstant("LJ_ioANALOG_INPUT"))
This function returns LJ_INVALID_CONSTANT if the string is not recognized.
Declaration:
long _stdcall StringToConstant ( const char *pString )
Parameter Description:
Returns: Constant number of the passed string.
Inputs:
Outputs:
Outputs a string describing the given error code or an empty string if not found.
Declaration:
void _stdcall ErrorToString ( LJ_ERROR ErrorCode,
char *pString)
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
Outputs:
Returns the version number of this Windows LabJack driver.
Declaration:
double _stdcall GetDriverVersion();
Parameter Description:
Returns: Driver version.
Inputs:
Outputs:
A utility function to convert thermocouple voltage readings to temperature.
Declaration:
LJ_ERROR _stdcall TCVoltsToTemp ( long TCType,
double TCVolts,
double CJTempK,
double *pTCTempK)
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
Outputs:
Sends a reset command to the LabJack hardware. Reset causes the device to go to the reset/power-up configuration.
Resetting the LabJack does not invalidate the handle, thus the device does not have to be opened again after a reset, but a Go call is likely to fail for a couple seconds after until the LabJack is ready.
Declaration:
LJ_ERROR _stdcall ResetLabJack ( LJ_HANDLE Handle );
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
Outputs:
An easy function that returns a reading from one analog input. This is a simple alternative to the very flexible IOType based method normally used by this driver.
When needed, this function automatically configures the specified channel(s) for analog input.
Declaration:
LJ_ERROR _stdcall eAIN ( LJ_HANDLE Handle,
long ChannelP,
long ChannelN,
double *Voltage,
long Range,
long Resolution,
long Settling,
long Binary,
long Reserved1,
long Reserved2)
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
Outputs:
An easy function that writes a value to one analog output. This is a simple alternative to the very flexible IOType based method normally used by this driver.
When needed, this function automatically enables the specified analog output.
Declaration:
LJ_ERROR _stdcall eDAC ( LJ_HANDLE Handle,
long Channel,
double Voltage,
long Binary,
long Reserved1,
long Reserved2)
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
An easy function that reads the state of one digital input. This is a simple alternative to the very flexible IOType based method normally used by this driver.
When needed, this function automatically configures the specified channel as a digital input.
Declaration:
LJ_ERROR _stdcall eDI ( LJ_HANDLE Handle,
long Channel,
long *State)
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
Outputs:
An easy function that writes the state of one digital output. This is a simple alternative to the very flexible IOType based method normally used by this driver.
When needed, this function automatically configures the specified channel as a digital output.
Declaration:
LJ_ERROR _stdcall eDO ( LJ_HANDLE Handle,
long Channel,
long State)
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
An easy function that configures and initializes all the timers and counters. This is a simple alternative to the very flexible IOType based method normally used by this driver.
When needed, this function automatically configures the needed lines as digital.
Declaration:
LJ_ERROR _stdcall eTCConfig ( LJ_HANDLE Handle,
long *aEnableTimers,
long *aEnableCounters,
long TCPinOffset,
long TimerClockBaseIndex,
long TimerClockDivisor,
long *aTimerModes,
double *aTimerValues,
long Reserved1,
long Reserved2)
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
1 Number of timers UE9:6, U6:4, U3:2
2 Number of counters UE9:2, U6:2, U3:2
3 Pin offset UE9:Ignored, U6:0-8, U3:4-8
4 Default constant UE9:LJ_tc750KHZ, U6:LJ_tc48MHZ, U3:LJ_tc48MHZ
An easy function that updates and reads all the timers and counters. This is a simple alternative to the very flexible IOType based method normally used by this driver.
Declaration:
LJ_ERROR _stdcall eTCValues ( LJ_HANDLE Handle,
long *aReadTimers,
long *aUpdateResetTimers,
long *aReadCounters,
long *aResetCounters,
double *aTimerValues,
double *aCounterValues,
long Reserved1,
long Reserved2)
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
Outputs:
1 Array size must be equal to the number of timers available on the device. UE9:6, U6:4, U3:2
2 Array size must be equal to the number of counters available on the device. UE9:2, U6:2, U3:2