Open Core Interface - MLPI
MLPI-MotionLogicProgrammingInterface(mlpi4LabVIEW)  1.26.2
Functions
Auxiliary function
ParameterLib
Collaboration diagram for Auxiliary function:

Functions

MLPIRESULT mlpiParameterReadListLength (const MLPIHANDLE connection, const ULLONG address, const ULLONG sidn, ULONG *numElements, ULONG *numMaxElements, ULONG *elementSize)
 
MLPIRESULT mlpiParameterImportFile (const MLPIHANDLE connection, const WCHAR16 *path, MlpiSidnError *errorList, const ULONG numElements, ULONG *numElementsRet, const WCHAR16 *mapping)
 
MLPIRESULT mlpiParameterExportFile (const MLPIHANDLE connection, const WCHAR16 *path, const WCHAR16 *exportPattern, MlpiSidnError *errorList, const ULONG numElements, ULONG *numElementsRet)
 
MLPIRESULT mlpiParameterReadEverything (const MLPIHANDLE connection, MlpiReadEverything *readEverything, const ULONG numElements, UCHAR *data, const ULONG dataSize)
 
MLPIRESULT mlpiParameterExportFileStartProcess (const MLPIHANDLE connection, const WCHAR16 *path, const WCHAR16 *exportPattern, PROCESSHANDLE *process)
 
MLPIRESULT mlpiParameterImportFileStartProcess (const MLPIHANDLE connection, const WCHAR16 *path, const WCHAR16 *mapping, PROCESSHANDLE *process)
 
MLPIRESULT mlpiParameterImportExportStatus (const MLPIHANDLE connection, const PROCESSHANDLE process, MlpiParamProcessStatus *status, ULONG *currentCount, ULONG *expectedCount, ULONG *errorsCount, MlpiSidnError *errorList, ULONG numElements)
 
MLPIRESULT mlpiParameterImportExportGetInfo (const MLPIHANDLE connection, const PROCESSHANDLE process, WCHAR16 *pattern, ULONG numElementsPattern, WCHAR16 *file, ULONG numElementsFile)
 
MLPIRESULT mlpiParameterImportExportAbort (const MLPIHANDLE connection, const PROCESSHANDLE process)
 
MLPIRESULT mlpiParameterWriteAccessSetup (const MLPIHANDLE connection, MlpiParamWriteAccess *writeAccess, const ULONG numElements, PROCESSHANDLE *process)
 
MLPIRESULT mlpiParameterWriteAccessStatus (const MLPIHANDLE connection, const PROCESSHANDLE process, const BOOL8 waitForWriteAccess, const ULONG timeout, MlpiParamWriteAccess *writeAccess, const ULONG numElements, ULONG *numElementsRet)
 
MLPIRESULT mlpiParameterWriteAccessAbort (const MLPIHANDLE connection, const PROCESSHANDLE process)
 

Detailed Description

These functions support import, export and further activities in relation to parameters.

Function Documentation

MLPIRESULT mlpiParameterReadListLength ( const MLPIHANDLE  connection,
const ULLONG  address,
const ULLONG  sidn,
ULONG *  numElements,
ULONG *  numMaxElements,
ULONG *  elementSize 
)

This function reads the current and maximum length of a list parameter.

Parameters
[in]connectionHandle for multiple connections.
[in]addressAddress identifying the object to be accessed. Use macro MLPI_ADDRESS_x to generate an address field.
[in]sidnID of parameter to be accessed. Use macro MLPI_SIDN_x to get the desired ID.
[out]numElementsPointer to variable where the number of current elements in the list will be stored.
[out]numMaxElementsPointer to variable where the maximum number of elements that can be in the list will be stored.
[out]elementSizePointer to variable where the size in bytes of single list element will be stored.
Returns
Return value indicating success (>=0) or error (<0).
Note
Many parameters are volatile and may change. This means that also the length of a parameter list may change between a call to mlpiParameterReadListLength and mlpiParameterReadData.
Example:
1 // Read the length of parameter 'C-0-1010'.
2 ULONG numElements = 0;
3 ULONG numMaxElements = 0;
4 ULONG elementSize = 0;
5 MLPIRESULT result = mlpiParameterReadListLength(connection, 0, MLPI_SIDN_C(1010), &numElements, &numMaxElements, &elementSize);
MLPIRESULT mlpiParameterImportFile ( const MLPIHANDLE  connection,
const WCHAR16 *  path,
MlpiSidnError *  errorList,
const ULONG  numElements,
ULONG *  numElementsRet,
const WCHAR16 *  mapping 
)

This function imports a parameter file from CF-card. The string 'mapping' can give information on which instance should be imported and to which number of instance it should be written.

Parameters
[in]connectionHandle for multiple connections.
[in]pathAbsolute path of file which should be imported.
[out]errorListPointer to an array of structure where the wrong parameter and the error codes will be stored
[in]numElementsNumber of MlpiSidnError elements available in 'errorList' for writing.
[out]numElementsRetNumber of elements needed to collect all information of import errors.
[in]mappingString which tells you which parameter instance should be imported and to which instance number.
The general structure is a tag list of jobs: {JobPart;}
Each job is separated by a semicolon. When no job is given, all parameters will be imported to the instance written in the header of the sercos ASCII file.
A job has the following structure: [InstanceMapping]:Parametertype (in squared brackets).
Parametertype is represented by A, C, K, M, N, O, S and P.
In part InstanceMapping, you can select which parameter is imported to which instance. If given a single number only, this instance will be imported. If there is a parameter file in which data are associated with another instance number, one instance can be mapped to the other using '>'. It's also possible to map one instance to a range of instances.
Examples:
[1]:A will import axis parameter for axis 1.
[1>3]:A will map axis parameter from instance 1 to 3.
[1>2-5]:A will map axis parameter from instance 1 to axis 2 till 5.
Returns
Return value indicating success (>=0) or error (<0).
Example:
1 // Import axis parameter from given file with included parameters for instance 1 to axis 6
2 WCHAR path[] = L"/ata0b/importFile.par";
3 MlpiSidnError errorList[10] = {0}; // array to store errors which occur during import
4 ULONG numElementsRet = 0;
5 WCHAR mapping[] = L"[1>6]:A";
6 MLPIRESULT result = mlpiParameterImportFile(connection, path, errorList, _countof(errorList), &numElementsRet, mapping);
MLPIRESULT mlpiParameterExportFile ( const MLPIHANDLE  connection,
const WCHAR16 *  path,
const WCHAR16 *  exportPattern,
MlpiSidnError *  errorList,
const ULONG  numElements,
ULONG *  numElementsRet 
)

This function exports parameters to a file on CF-card. In String 'exportPattern' the instances can be selected.

Parameters
[in]connectionHandle for multiple connections.
[in]pathAbsolute path of file where exported parameter will be stored.
[in]exportPatternString where you can select which instances and which types of parameter should be exported.
The general structure is a tag list of jobs: (JobPart;)*
All jobs are separated by a semicolon. When no job is selected, no parameter will be exported.
The structure of a job is the following: [InstanceRanges]:ParameterType[ParameterRanges] (with all squared brackets).
The elements "[InstanceRanges]:" and "[ParameterRanges]" are optional. If these elements are not part of a string, the whole available range is used. The element ParameterType is mandatory.
"[InstanceRanges]:" and "[ParameterRanges]" can be lists of numbers, ranges or words "TO_SAVE" (all parameters which are needed to restore) or "MODIFIED" (all modified parameters). The stated words cannot be combined with the list of numbers or ranges. Furthermore, "MODIFIED" is only available for sercos parameters. When related parameter not exist on sercos device none parameter will export.
Examples:
A;C will export all axis and control parameters for each instance.
[2]:A will export all axis parameter for axis 2.
A[1-5] will export axis parameter A-0-0001 till A-0-0005 for each axis.
[1,3-4,5]:A[8-9,11-13] Will export axis parameters (A-0-0008, A-0-0009, A-0-0011, A-0-0012, A-0-0013) for axis 1, 3, 4 and 5.
A[TO_SAVE];[1-3]:S[MODIFIED] Will export parameters of all axes which are needed to resore and all modified parameters of sercos device 1 till 3.
[out]errorListPointer to an array of structures where the wrong parameter and the error codes will be stored
[in]numElementsNumber of MlpiSidnError elements available in 'errorList' for reading.
[out]numElementsRetNumber of elements used or needed. When this is greater than numElements, all elements in the array are filled out but some information about errors is lost.
Returns
Return value indicating success (>=0) or error (<0).
Example:
1 // Export Parameter A-0-0001 till A-0003 for axis 2 and all control parameters
2 WCHAR path[] = L"/ata0b/exportFile.par";
3 WCHAR exportPattern[] = L"[2]:A[1-3];C";
4 MlpiSidnError errorList[10] = {0}; // array to store errors that occur during export
5 ULONG numElementsRet = 0;
6 MLPIRESULT result = mlpiParameterExportFile(connection, path, exportPattern, errorList, _countof(errorList), &numElementsRet);
MLPIRESULT mlpiParameterReadEverything ( const MLPIHANDLE  connection,
MlpiReadEverything *  readEverything,
const ULONG  numElements,
UCHAR *  data,
const ULONG  dataSize 
)

This function reads every element of a list of given parameters (Parameter structure). This means that you can read multiple parameters at once and you can read each element (value, default value, min, max, attribute, ...) of each parameter at once. All with a single function call instead of multiple calls to different functions. On the server side, the firmware tries to read the data in parallel where possible.

Parameters
[in]connectionHandle for multiple connections.
[out]readEverythingStructure where the information of all elements of the parameter are stored.
The address and the sidn are input parameters. They define the address identifying the object and the ID of the parameter to be accessed.
The elements attribute and IDN of an parameter have an fixed length. The values are stored in attribute and dataStatus.
All other elements have an variable length. Their values are written into 'data'. To access an element value, use the offsets. The length of the elements minimum, maximum and data is stored in dataLength. If the the parameter is a list its length of the data is stored in dataSize. In this case the maximum list length is stored in maxDataSize.
The parameter result indicates if this single request succeeded or failed. An error is returned if an general error occurred or if reading of one mandatory element failed (Parameter structure). Which elements are valid can be read via the validElements parameter.
[in]numElementsNumber of MlpiReadEverything elements available in 'readEverything' for reading.
[out]dataBuffer to store the data of all elements with variable length.
[in]dataSizeNumber of UCHAR elements available in 'data' for reading.
Returns
Return value indicating success (>=0) or error (<0). If an error is returned the data is invalid.
Note
If the parameter has a data length of one octet with a variable length and a data type is an extended character set, its data is converted to an an null-terminated WCHAR16 string. The attribute isn't converted in this case.
Example:
1 //reading every element of the parameters C-0-0400 and S-0-1002 of the device 1
2 MLPIRESULT result = MLPI_S_OK;
3 const ULONG numElements = 2;
4 UCHAR buffer[256] = {};
5 WCHAR16 idn[PARAM_MAX_IDN_STRING_LENGTH] = {L'0'};
6 MlpiReadEverything readEverything[numElements];
7 
8 readEverything[0].address = 0;
9 readEverything[0].sidn = MLPI_SIDN_C(400);
10 readEverything[1].address = MLPI_ADDRESS(MLPI_ADDRESS_MODE_PHYSICAL, 0, 1);
11 readEverything[1].sidn = MLPI_SIDN_S(1002);
12 
13 result = mlpiParameterReadEverything(connection, readEverything, numElements, buffer, _countof(buffer));
14 
15 // we use the helper class from #include <util/mlpiParameterHelper.h> to access the data
16 MlpiReadEverythingDataAccess dataAccess(readEverything, numElements, buffer, _countof(buffer));
17 for(ULONG i=0; numElements>i; i++)
18 {
19  memset(idn, 0, _countof(idn));
20  printf("\n\nData of Parameter %s", utilParameterParseIdn(readEverything[i].sidn, idn, _countof(idn)));
21  printf("\nParameter element 1 (DataStatus) = %lu", dataAccess.getDataStatus(i));
22  printf("\nParameter element 2 (Name) = %s", dataAccess.getName(i));
23  printf("\nParameter element 3 (Attribute) = 0x%x", dataAccess.getAttribute(i));
24  printf("\nParameter element 4 (Unit) = %s", dataAccess.getUnit(i));
25  // read data using the correct function
26  switch(dataAccess.getDataType(i))
27  {
28  case MLPI_TYPE_UCHAR:
29  {
30  const UCHAR *pMinValue = dataAccess.getMinimumValue<UCHAR>(i);
31  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %c", *pMinValue);
32  const UCHAR *pMaxValue = dataAccess.getMaximumValue<UCHAR>(i);
33  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %c", *pMaxValue);
34  const UCHAR *pData = dataAccess.getData<UCHAR>(i);
35  if (pData) printf("\nParameter element 7 (Data) = %c", *pData);
36  break;
37  }
38  case MLPI_TYPE_USHORT:
39  {
40  const USHORT *pMinValue = dataAccess.getMinimumValue<USHORT>(i);
41  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %u", *pMinValue);
42  const USHORT *pMaxValue = dataAccess.getMaximumValue<USHORT>(i);
43  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %u", *pMaxValue);
44  const USHORT *pData = dataAccess.getData<USHORT>(i);
45  if (pData) printf("\nParameter element 7 (Data) = %u", *pData);
46  break;
47  }
48  case MLPI_TYPE_SHORT:
49  {
50  const SHORT *pMinValue = dataAccess.getMinimumValue<SHORT>(i);
51  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %d", *pMinValue);
52  const SHORT *pMaxValue = dataAccess.getMaximumValue<SHORT>(i);
53  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %d", *pMaxValue);
54  const SHORT *pData = dataAccess.getData<SHORT>(i);
55  if (pData) printf("\nParameter element 7 (Data) = %d", *pData);
56  break;
57  }
58  case MLPI_TYPE_ULONG:
59  {
60  const ULONG *pMinValue = dataAccess.getMinimumValue<ULONG>(i);
61  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %lu", *pMinValue);
62  const ULONG *pMaxValue = dataAccess.getMaximumValue<ULONG>(i);
63  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %lu", *pMaxValue);
64  const ULONG *pData = dataAccess.getData<ULONG>(i);
65  if (pData) printf("\nParameter element 7 (Data) = %lu", *pData);
66  break;
67  }
68  case MLPI_TYPE_LONG:
69  {
70  const LONG *pMinValue = dataAccess.getMinimumValue<LONG>(i);
71  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %ld", *pMinValue);
72  const LONG *pMaxValue = dataAccess.getMaximumValue<LONG>(i);
73  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %ld", *pMaxValue);
74  const LONG *pData = dataAccess.getData<LONG>(i);
75  if (pData) printf("\nParameter element 7 (Data) = %ld", *pData);
76  break;
77  }
78  case MLPI_TYPE_ULLONG:
79  {
80  const ULLONG *pMinValue = dataAccess.getMinimumValue<ULLONG>(i);
81  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %llu", *pMinValue);
82  const ULLONG *pMaxValue = dataAccess.getMaximumValue<ULLONG>(i);
83  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %llu", *pMaxValue);
84  const ULLONG *pData = dataAccess.getData<ULLONG>(i);
85  if (pData) printf("\nParameter element 7 (Data) = %llu", *pData);
86  break;
87  }
88  case MLPI_TYPE_LLONG:
89  {
90  const LLONG *pMinValue = dataAccess.getMinimumValue<LLONG>(i);
91  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %lld", *pMinValue);
92  const LLONG *pMaxValue = dataAccess.getMaximumValue<LLONG>(i);
93  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %lld", *pMaxValue);
94  const LLONG *pData = dataAccess.getData<LLONG>(i);
95  if (pData) printf("\nParameter element 7 (Data) = %lld", *pData);
96  break;
97  }
98  case MLPI_TYPE_FLOAT:
99  {
100  const FLOAT *pMinValue = dataAccess.getMinimumValue<FLOAT>(i);
101  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %f", *pMinValue);
102  const FLOAT *pMaxValue = dataAccess.getMaximumValue<FLOAT>(i);
103  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %f", *pMaxValue);
104  const FLOAT *pData = dataAccess.getData<FLOAT>(i);
105  if (pData) printf("\nParameter element 7 (Data) = %f", *pData);
106  break;
107  }
108  case MLPI_TYPE_DOUBLE:
109  {
110  const DOUBLE *pMinValue = dataAccess.getMinimumValue<DOUBLE>(i);
111  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %f", *pMinValue);
112  const DOUBLE *pMaxValue = dataAccess.getMaximumValue<DOUBLE>(i);
113  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %f", *pMaxValue);
114  const DOUBLE *pData = dataAccess.getData<DOUBLE>(i);
115  if (pData) printf("\nParameter element 7 (Data) = %f", *pData);
116  break;
117  }
118  case MLPI_TYPE_UCHAR_ARRAY:
119  {
120  const UCHAR *pMinValue = dataAccess.getMinimumValue<UCHAR>(i);
121  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %c", *pMinValue);
122  const UCHAR *pMaxValue = dataAccess.getMaximumValue<UCHAR>(i);
123  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %c", *pMaxValue);
124  const UCHAR *pData = dataAccess.getData<UCHAR>(i);
125  for (ULONG j=0; dataAccess.getNumDataElements(i)>j; j++)
126  {
127  if (pData) printf("\nParameter element 7 (Data); List element %lu = %c", j, pData[j]);
128  }
129  break;
130  }
131  case MLPI_TYPE_USHORT_ARRAY:
132  {
133  const USHORT *pMinValue = dataAccess.getMinimumValue<USHORT>(i);
134  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %u", *pMinValue);
135  const USHORT *pMaxValue = dataAccess.getMaximumValue<USHORT>(i);
136  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %u", *pMaxValue);
137  const USHORT *pData = dataAccess.getData<USHORT>(i);
138  for (ULONG j=0; dataAccess.getNumDataElements(i)>j; j++)
139  {
140  if (pData) printf("\nParameter element 7 (Data); List element %lu = %u", j, pData[j]);
141  }
142  break;
143  }
144  case MLPI_TYPE_SHORT_ARRAY:
145  {
146  const SHORT *pMinValue = dataAccess.getMinimumValue<SHORT>(i);
147  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %d", *pMinValue);
148  const SHORT *pMaxValue = dataAccess.getMaximumValue<SHORT>(i);
149  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %d", *pMaxValue);
150  const SHORT *pData = dataAccess.getData<SHORT>(i);
151  for (ULONG j=0; dataAccess.getNumDataElements(i)>j; j++)
152  {
153  if (pData) printf("\nParameter element 7 (Data); List element %lu = %d", j, pData[j]);
154  }
155  break;
156  }
157  case MLPI_TYPE_ULONG_ARRAY:
158  {
159  const ULONG *pMinValue = dataAccess.getMinimumValue<ULONG>(i);
160  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %lu", *pMinValue);
161  const ULONG *pMaxValue = dataAccess.getMaximumValue<ULONG>(i);
162  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %lu", *pMaxValue);
163  const ULONG *pData = dataAccess.getData<ULONG>(i);
164  for (ULONG j=0; dataAccess.getNumDataElements(i)>j; j++)
165  {
166  if (pData) printf("\nParameter element 7 (Data); List element %lu = %lu", j, pData[j]);
167  }
168  break;
169  }
170  case MLPI_TYPE_LONG_ARRAY:
171  {
172  const LONG *pMinValue = dataAccess.getMinimumValue<LONG>(i);
173  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %ld", *pMinValue);
174  const LONG *pMaxValue = dataAccess.getMaximumValue<LONG>(i);
175  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %ld", *pMaxValue);
176  const LONG *pData = dataAccess.getData<LONG>(i);
177  for (ULONG j=0; dataAccess.getNumDataElements(i)>j; j++)
178  {
179  if (pData) printf("\nParameter element 7 (Data); List element %lu = %ld", j, pData[j]);
180  }
181  break;
182  }
183  case MLPI_TYPE_ULLONG_ARRAY:
184  {
185  const ULLONG *pMinValue = dataAccess.getMinimumValue<ULLONG>(i);
186  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %llu", *pMinValue);
187  const ULLONG *pMaxValue = dataAccess.getMaximumValue<ULLONG>(i);
188  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %llu", *pMaxValue);
189  const ULLONG *pData = dataAccess.getData<ULLONG>(i);
190  for (ULONG j=0; dataAccess.getNumDataElements(i)>j; j++)
191  {
192  if (pData) printf("\nParameter element 7 (Data); List element %lu = %llu", j, pData[j]);
193  }
194  break;
195  }
196  case MLPI_TYPE_LLONG_ARRAY:
197  {
198  const LLONG *pMinValue = dataAccess.getMinimumValue<LLONG>(i);
199  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %lld", *pMinValue);
200  const LLONG *pMaxValue = dataAccess.getMaximumValue<LLONG>(i);
201  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %lld", *pMaxValue);
202  const LLONG *pData = dataAccess.getData<LLONG>(i);
203  for (ULONG j=0; dataAccess.getNumDataElements(i)>j; j++)
204  {
205  if (pData) printf("\nParameter element 7 (Data); List element %lu = %lld", j, pData[j]);
206  }
207  break;
208  }
209  case MLPI_TYPE_FLOAT_ARRAY:
210  {
211  const FLOAT *pMinValue = dataAccess.getMinimumValue<FLOAT>(i);
212  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %f", *pMinValue);
213  const FLOAT *pMaxValue = dataAccess.getMaximumValue<FLOAT>(i);
214  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %f", *pMaxValue);
215  const FLOAT *pData = dataAccess.getData<FLOAT>(i);
216  for (ULONG j=0; dataAccess.getNumDataElements(i)>j; j++)
217  {
218  if (pData) printf("\nParameter element 7 (Data); List element %lu = %f", j, pData[j]);
219  }
220  break;
221  }
222  case MLPI_TYPE_DOUBLE_ARRAY:
223  {
224  const DOUBLE *pMinValue = dataAccess.getMinimumValue<DOUBLE>(i);
225  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %f", *pMinValue);
226  const DOUBLE *pMaxValue = dataAccess.getMaximumValue<DOUBLE>(i);
227  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %f", *pMaxValue);
228  const DOUBLE *pData = dataAccess.getData<DOUBLE>(i);
229  for (ULONG j=0; dataAccess.getNumDataElements(i)>j; j++)
230  {
231  if (pData) printf("\nParameter element 7 (Data); List element %lu = %f", j, pData[j]);
232  }
233  break;
234  }
235  case MLPI_TYPE_CHAR_UTF8_ARRAY :
236  case MLPI_TYPE_CHAR_UTF16_ARRAY:
237  {
238  const WCHAR16 *pMinValue = dataAccess.getMinimumValue<WCHAR16>(i);
239  if (pMinValue) printf("\nParameter element 5 (Minimum value) = %s", *pMinValue);
240  const WCHAR16 *pMaxValue = dataAccess.getMaximumValue<WCHAR16>(i);
241  if (pMaxValue) printf("\nParameter element 6 (Maximum value) = %s", *pMaxValue);
242  const WCHAR16 *pData = dataAccess.getData<WCHAR16>(i);
243  for (ULONG j=0; dataAccess.getNumDataElements(i)>j; j++)
244  {
245  if (pData) printf("\nParameter element 7 (Data); List element %lu = %s", j, pData[j]);
246  }
247  break;
248  }
249  default:
250  // unknown or invalid data type...
251  break;
252  }
253 }
MLPIRESULT mlpiParameterExportFileStartProcess ( const MLPIHANDLE  connection,
const WCHAR16 *  path,
const WCHAR16 *  exportPattern,
PROCESSHANDLE *  process 
)

This function exports parameters to a file on CF card in a asynchronous way. In string 'exportPattern', the instances can be selected.

Parameters
[in]connectionHandle for multiple connections.
[in]pathAbsolute path of file where exported parameter will be stored.
[in]exportPatternString where you can select which instances and which types of parameter should be exported.
The general structure is a tag list of jobs: (JobPart;)*
All jobs are separated by a semicolon. When no job is selected, no parameter will be exported.
The structure of a job is the following: [InstanceRanges]:ParameterType[ParameterRanges] (with all squared brackets).
The elements "[InstanceRanges]:" and "[ParameterRanges]" are optional. If these elements are not part of string, the whole available range is used. The element ParameterType is mandatory.
"[InstanceRanges]:" and "[ParameterRanges]" can be lists of numbers, ranges or words "TO_SAVE" (all parameters which are needed to restore) or "MODIFIED" (all modified parameters). The stated words cannot combined with list of numbers or ranges. Furthermore, "MODIFIED" is only available for sercos parameters. When related parameter not exist on sercos device none parameter will export.
Examples:
A;C will export all axis and control parameters for each instance.
[2]:A will export all axis parameter for axis 2.
A[1-5] will export axis parameter A-0-0001 till A-0-0005 for each axis.
[1,3-4,5]:A[8-9,11-13] Will export axis parameters (A-0-0008, A-0-0009, A-0-0011, A-0-0012, A-0-0013) for axis 1, 3, 4 and 5.
A[TO_SAVE];[1-3]:S[MODIFIED] Will export parameters of all axes which are needed to resore and all modified parameters of sercos device 1 till 3.
[out]processHandle of created process
Returns
Return value indicating success (>=0) or error (<0).
Example:
1 MLPIRESULT result;
2 MLPIHANDLE process;
3 result = mlpiParameterExportFileStartProcess(connection, L"/ata0b/export.par", L"C;A;M;N;K;O;S[TO_SAVE]", &process)
4 if (MLPI_FAILED(result))
5  printf("unable to start export with error code: %08X", result);
MLPIRESULT mlpiParameterImportFileStartProcess ( const MLPIHANDLE  connection,
const WCHAR16 *  path,
const WCHAR16 *  mapping,
PROCESSHANDLE *  process 
)

This function imports a parameter file from CF card in a asynchronous way. The string 'mapping' can give information on which instance should be imported and to which number of instance it should be written.

Parameters
[in]connectionHandle for multiple connections.
[in]pathAbsolute path of file which should be imported.
[in]mappingString which tells you which parameter instance should be imported and to which instance number.
The general structure is a tag list of jobs: {JobPart;}
Each job is separated by a semicolon. When no job is given, all parameters will be imported to the instance written in the header of the sercos ASCII file.
A job has the following structure: [InstanceMapping]:Parametertype (in squared brackets).
Parametertype is represented by A, C, K, M, N, O, S and P.
In part InstanceMapping, you can select which parameter is imported to which instance. If given a single number only, this instance will be imported. If there is a parameter file in which data are associated with another instance number, one instance can be mapped to the other using '>'. It's also possible to map one instance to a range of instances.
Examples:
[1]:A will import axis parameter for axis 1.
[1>3]:A will map axis parameter from instance 1 to 3.
[1>2-5]:A will map axis parameter from instance 1 to axis 2 till 5.
[out]processHandle of created process
Returns
Return value indicating success (>=0) or error (<0).
Example:
1 MLPIRESULT result;
2 MLPIHANDLE process;
3 // import everything of file /ata0b/import.par
4 result = mlpiParameterImportFileStartProcess(connection, L"/ata0b/import.par", L"", &process)
5 if (MLPI_FAILED(result))
6  printf("unable to start import with error code: %08X", result);
MLPIRESULT mlpiParameterImportExportStatus ( const MLPIHANDLE  connection,
const PROCESSHANDLE  process,
MlpiParamProcessStatus *  status,
ULONG *  currentCount,
ULONG *  expectedCount,
ULONG *  errorsCount,
MlpiSidnError *  errorList,
ULONG  numElements 
)

This function returns the status of a parameter process (import or export).

Parameters
[in]connectionHandle for multiple connections.
[in]processHandle of process
[out]statusstatus of process
[out]currentCountcount of current parameters to export or import
[out]expectedCountcount of expected parameters to export or import
[out]errorsCountNumber of errors while import or export. When this is greater than numElements, all elements in the array are filled out but some information about errors is lost.
[out]errorListPointer to an array of structures where the wrong parameter and the error codes will be stored
[in]numElementsNumber of MlpiSidnError elements available in 'errorList' for reading.
Returns
Return value indicating success (>=0) or error (<0).
Example:
1 MLPIRESULT result;
2 MLPIHANDLE process;
3 result = mlpiParameterImportFileStartProcess(connection, L"/ata0b/import.par", L"", &process)
4 if (MLPI_FAILED(result))
5 {
6  printf("unable to start import with error code: %08X", result);
7  return;
8 }
9 
10 ULONG countCurrent = 0;
11 ULONG countExpected = 0;
12 ULONG countError = 0;
13 MlpiSidnError errorList[1024];
14 MlpiParamProcessStatus processStatus;
15 do
16 {
17  APICALL_AND_CHECK(mlpiParameterImportExportStatus(connection,importHandle,&processStatus,&countCurrent, &countExpected, &countError, errorList, 1024));
18  printf("\nImported %4u of %4u (errors %4u, state %u)",countCurrent, countExpected, countError, processStatus.processState);
19 } while ((processStatus.processState != MLPI_PROCESS_STATUS_ERROR) && (processStatus.processState != MLPI_PROCESS_STATUS_FINISHED));
MLPIRESULT mlpiParameterImportExportGetInfo ( const MLPIHANDLE  connection,
const PROCESSHANDLE  process,
WCHAR16 *  pattern,
ULONG  numElementsPattern,
WCHAR16 *  file,
ULONG  numElementsFile 
)

This function returns information about a parameter process (import or export).

Parameters
[in]connectionHandle for multiple connections.
[in]processHandle of process
[out]patternGiven pattern of process
[in]numElementsPatternSize of pattern
[out]fileGiven file of process
[in]numElementsFileSize of file
Returns
Return value indicating success (>=0) or error (<0).
Example:
1 MLPIRESULT result;
2 MLPIHANDLE process;
3 result = mlpiParameterImportFileStartProcess(connection, L"/ata0b/import.par", L"", &process)
4 if (MLPI_FAILED(result))
5 {
6  printf("unable to start import with error code: %08X", result);
7  return;
8 }
9 
10 WCHAR16 strPattern[256];
11 WCHAR16 strFile[256];
12 result = mlpiParameterImportExportGetInfo(connection, process, strPattern, 256, strFile, 256);
13 if (MLPI_FAILED(result))
14 {
15  printf("unable to abort import with error code: %08X", result);
16  return;
17 }
18 printf("import file: \"%s\", pattern: \"%s\", W2A16(strFile), W2A16(strPattern));
MLPIRESULT mlpiParameterImportExportAbort ( const MLPIHANDLE  connection,
const PROCESSHANDLE  process 
)

This function stops a given parameter process.

Parameters
[in]connectionHandle for multiple connections.
[in]processHandle of process
Returns
Return value indicating success (>=0) or error (<0).
Example:
1 MLPIRESULT result;
2 MLPIHANDLE process;
3 result = mlpiParameterImportFileStartProcess(connection, L"/ata0b/import.par", L"", &process)
4 if (MLPI_FAILED(result))
5 {
6  printf("unable to start import with error code: %08X", result);
7  return;
8 }
9 
10 result = mlpiParameterImportExportAbort(connection, process);
11 if (MLPI_FAILED(result))
12 {
13  printf("unable to abort import with error code: %08X", result);
14  return;
15 }
MLPIRESULT mlpiParameterWriteAccessSetup ( const MLPIHANDLE  connection,
MlpiParamWriteAccess *  writeAccess,
const ULONG  numElements,
PROCESSHANDLE *  process 
)

This function initializes a monitoring of parameters on a write access of the operation data. Not the modification of the operation data is monitored, but the write access. A process is started in the control. The status of this process can be read via the function mlpiParameterWriteAccessStatus. The process can be stopped via the function mlpiParameterWriteAccessAbort.

Note
A process is related to the connection that initialized the process. If the connection is terminated also the process will be stopped and the handle is not longer valid.
If the option 'auto_reconnect' is used for the connection and the connection is terminated, the process will also be stopped. A new monitoring will not automatically be initialized.
Parameters
[in]connectionHandle for multiple connections.
[in]writeAccessStructure which conntains the information of the parameters to be monitored.
[in]numElementsNumber of MlpiParamWriteAccess elements available in 'writeAccess'.
[out]processHandle of created process
Returns
Return value indicating success (>=0) or error (<0).
Example:
1 // initialize write access monitoring of parameters C-0-0400 and A-0-0024 of axis 5
2 MLPIRESULT result = S_OK;
3 PROCESSHANDLE process = 0;
4 MlpiParamWriteAccess writeAccess[] = {{0, MLPI_SIDN_C(400)}, {MLPI_ADDRESS(MLPI_ADDRESS_MODE_LOGICAL,0,5), MLPI_SIDN_A(24)}};
5 result = mlpiParameterWriteAccessSetup(connection, writeAccess, _countof(writeAccess), &process);
6 if(MLPI_FAILED(result))
7 {
8  printf("error during initialization of write access monitoring. result:0x%08X", result);
9  return result;
10 }
MLPIRESULT mlpiParameterWriteAccessStatus ( const MLPIHANDLE  connection,
const PROCESSHANDLE  process,
const BOOL8  waitForWriteAccess,
const ULONG  timeout,
MlpiParamWriteAccess *  writeAccess,
const ULONG  numElements,
ULONG *  numElementsRet 
)

This function reads the status of a write access monitoring process. The process has be initialized via the function mlpiParameterWriteAccessSetup. The written parameters will only be reseted if this function succeded.

Parameters
[in]connectionHandle for multiple connections.
[in]processHandle of process
[in]waitForWriteAccessSet this value 'true' to call this function synchronously. The function returns in this case if one monitored parameter has been written.
[in]timeoutTimeout in milliseconds if the value of 'waitForWriteAccess' is 'true'. Use MLPI_INFINITE for infinite wait.
[in]writeAccessStructure to store the information of (only) the written parameters.
[out]numElementsNumber of MlpiParamWriteAccess elements available in 'writeAccess'.
[out]numElementsRetNumber of elements used.
Returns
Return value indicating success (>=0) or error (<0).
Example:
1 // initialize write access monitoring of parameters C-0-0400 and A-0-0024 of axis 5
2 MLPIRESULT result = S_OK;
3 PROCESSHANDLE process = 0;
4 MlpiParamWriteAccess writeAccess[] = {{0, MLPI_SIDN_C(400)}, {MLPI_ADDRESS(MLPI_ADDRESS_MODE_LOGICAL,0,5), MLPI_SIDN_A(24)}};
5 result = mlpiParameterWriteAccessSetup(connection, writeAccess, _countof(writeAccess), &process);
6 if(MLPI_FAILED(result))
7 {
8  printf("error during initialization of write access monitoring. result:0x%08X", result);
9  return result;
10 }
11 
12 // modify parameter C-0-0400
13 result = mlpiParameterWriteDataUlong(connection, 0, MLPI_SIDN_C(400), (ULONG) 4000);
14 if(MLPI_FAILED(result))
15 {
16  printf("error writing parameter C-0-0400. result:0x%08X", result);
17  return result;
18 }
19 
20 // get status of process
21 ULONG numElementsRet=0;
22 WCHAR16 idn[PARAM_MAX_IDN_STRING_LENGTH] = {L'0'};
23 memset(idn, 0, _countof(idn));
24 result = mlpiParameterWriteAccessStatus(connection, process, FALSE, 0, writeAccess, _countof(writeAccess), &numElementsRet);
25 if(MLPI_FAILED(result))
26 {
27  printf("error getting status of write access monitoring. result:0x%08X", result);
28  return result;
29 }
30 for (ULONG i=0; numElementsRet>i; ++i)
31 {
32  printf("\nParameter %s has been written", utilParameterParseIdn(writeAccess[i].sidn, idn, _countof(idn)));
33 }
MLPIRESULT mlpiParameterWriteAccessAbort ( const MLPIHANDLE  connection,
const PROCESSHANDLE  process 
)

This function aborts a write access monitoring process.

Parameters
[in]connectionHandle for multiple connections.
[in]processHandle of process
Returns
Return value indicating success (>=0) or error (<0).
Example:
1 MLPIRESULT result = S_OK;
2 PROCESSHANDLE process = 0;
3 MlpiParamWriteAccess writeAccess[] = {{0, MLPI_SIDN_C(400)}, {MLPI_ADDRESS(MLPI_ADDRESS_MODE_LOGICAL,0,5), MLPI_SIDN_A(24)}};
4 result = mlpiParameterWriteAccessSetup(connection, writeAccess, _countof(writeAccess), &process);
5 if(MLPI_FAILED(result))
6 {
7  printf("error during initialization of write access monitoring. result:0x%08X", result);
8  return result;
9 }
10 
11 // cancel process
12 result = mlpiParameterWriteAccessAbort(connection, process);
13 if(MLPI_FAILED(result))
14 {
15  printf("error canceling of write access monitoring. result:0x%08X", result);
16  return result;
17 }