eNames [LJM User's Guide]

Write/Read multiple device registers in one command, each register specified by name. This function is designed to condense communication into arrays. Moreover, consecutive values can be accessed by specifying a starting register name, and a number of values.

Syntax

LJM_ERROR_RETURN LJM_eNames(
int Handle,
int NumFrames,
const char ** aNames,
const int * aWrites,
const int * aNumValues,
double * aValues,
int * ErrorAddress)

Parameters

Handle [in]

A device handle. The handle is a connection ID for an active device. Generate a handle with LJM_Open or LJM_OpenS.

NumFrames [in]

The total number of frames to access.  A frame consists of one or more values, based on NumValues.

aNames [in]

An array of names that specify the Modbus register(s) to write/read. To access a consecutive group of values, populate an element of the aNames array with the starting name, and then increase the NumValues parameter according to the group size.

aWrites [in]

An array containing the desired type of access, which is either read (0) or write (1). The array size should be the same as the aNames array.

aNumValues [in]

An array that contains the per-name number of consecutive values.  An entry in the array should be set to 1 for frames without consecutive register accesses. The array size should be the same as the aNames array.

aValues [in/out]

An array of values transferred to/from the device. The array size should be the sum of all elements in the aNumValues array. For values in the array that are being sent, data is automatically converted into the correct data type. For incoming values, data is converted to a double automatically.

ErrorAddress [out]

If error, the address responsible for causing an error.

Returns

LJM errorcodes or 0 for no error.

Remarks

LJM_eNames is for programs that need to write and read multiple, arbitrary values in a single function call. For example, a PID loop may read inputs and set outputs in a single function call. In this way, the communication overhead is reduced. There are simpler single value functions and simpler multiple value functions for programs that do not need such a level of communication optimization.

To use LJM_eNames

1. List of values that need to be accessed.

2. Decide how each value will be accessed: read or write.

3. Note values which are consecutive and have the same access (read or write). Only use the first name in a consecutive group and increase the NumValues parameter according to the group size.

4. Define NumFrames by counting all the values to access (step 1), then subtract consecutive values already accounted for in NumValues .

5. Insert data to be written to the device at the appropriate index of aValues.

6. Read data from aValues array after function is executed.

As an example of the above use-case, consider reading AIN0-2, setting DAC0 to 4.6V, and reading the state of DIO4.

1. Values that need to be accessed: [AIN0, AIN1, AIN2, DAC0, DIO4]

2. Reading the first 3 values, writing to the 4th value, and reading from the 5th [R, R, R, W, R]

3. Seeing that the first 3 values are consecutive and are all being read, the situation can be simplified.  The array size of aNames, aTypes, and aWrites is reduced.

4. aNames = [AIN0, DAC0, DIO4]

5. aWrites = [LJM_READ, LJM_WRITE, LJM_READ] - LJM_READ is 0; LJM_WRITE is 1.

6. aNumValues = [3, 1, 1] - The number of values is increased for the first frame only.

7. The number of frames is 3

8. Set the analog output voltage to 4.6V by setting the fourth value.  aValues = [0, 0, 0, 4.6, 0]

9. Read the first three values of aValues to get AIN0 through AIN2; read the fifth value to get FIO4

Example

Read analog inputs 0 through 2, set DAC0 to 4.6V, and read FIO4

int LJMError;
int errorAddress;
const char * aNames[3] = {"AIN0", "DAC0", "FIO4"};
int aWrites[3] = {LJM_READ, LJM_WRITE, LJM_READ};
int aNumValues[3] = {3, 1, 1};
double aValues[5];
aValues[3] = 4.6;

// handle comes from LJM_Open()
LJMError = LJM_eNames(handle, 3, aNames, aWrites, aNumValues, aValues, &errorAddress);
if (LJMError != LJME_NOERROR) {
    // Deal with error
}
printf("AIN0: %f\n", aValues[0]);
printf("AIN1: %f\n", aValues[1]);
printf("AIN2: %f\n", aValues[2]);
printf("FIO4: %f\n", aValues[4]);