flex_get_error_description |
Get Error Description
Usage
status = flex_get_error_description(u16 descriptionType, i32 errorCode, u16 commandID, u16 resourceID, i8* charArray, u32* sizeOfArray);
Purpose
Gets an error, command, and/or resource description string as an ASCII character array.
Parameters
| Name | Type | Description |
|---|---|---|
| descriptionType | u16 | type of description selector |
| errorCode | i32 | error code |
| commandID | u16 | command ID number |
| resourceID | u16 | resource ID number |
| charArray | [i8]* | character array |
| sizeOfArray | u32* | size of character array |
Parameter Discussion
descriptionType is the selector for the type of description string to return.
| descriptionType Constant | descriptionType Value |
| NIMC_ERROR_ONLY | 0 |
| NIMC_FUNCTION_NAME_ONLY | 1 |
| NIMC_RESOURCE_NAME_ONLY | 2 |
| NIMC_COMBINED_DESCRIPTION | 3 |
errorCode is an error code from a function return status or the error code returned from the Read Error Message function.
commandID is the command ID of a function.
resourceID is the resource ID of an axis, vector space, encoder, ADC, DAC, or other resource.
charArray is an array of ASCII characters containing the error, command, and/or resource description string. This function places all or part of the selected string in charArray, if sizeOfArray is greater than zero (> 0).
sizeOfArray is the number of characters in the description plus one for the NULL string terminator. As an input, this I/O parameter specifies the size of the allocated array. If sizeOfArray and/or charArray is NULL or zero (0), the required size of the array (not including the NULL terminator) is returned in the sizeOfArray parameter as an output.
Using This Function
This function returns the selected description string as an ASCII character array. You must allocate space for this array on the host computer before calling this function. You can use this function to generate a string for displaying a function name, a resource name, an error code description, or a complete error description string in response to an error code returned as a function status or the result of calling the Read Error Message function.
Not all input parameters are required for each description type. The following parameters are required to return an accurate description string:
| descriptionType | errorCode | commandID | resourceID |
| NIMC_ERROR_ONLY | required | not required | not required |
| NIMC_FUNCTION_NAME_ONLY | not required | required | not required |
| NIMC_RESOURCE_NAME_ONLY | not required | required | required |
| NIMC_COMBINED_DESCRIPTION | required | required | required |
Because resource IDs are not unique (for example, axis 1 and program 1 both are resource 1), the command ID is required to set the context and allow this function to generate the proper resource name string.
If NULL (or 0) is passed in either the charArray or sizeOfArray parameters, the required size of the array (not including the NULL terminator) is returned in the sizeOfArray parameter. You can use this feature when you want to allocate only the memory necessary to hold the description string. This function is then called twice: one time to get the required array size, and again to actually retrieve the description.
The number of characters required for the character array is always one more than the actual number of characters in the controller name due to the NULL terminator at the end of the string. If sizeOfArray is smaller than the actual description string, this function returns a partial string with the last three characters replaced by "..." to indicate that the string is not complete.
Example
After executing a Find Reference Index sequence on axis 1, a modal error is detected. A call to the Read Error Message function returns the following set of parameters:
commandID = 334
resourceID = 0x01
errorCode = –70124
To generate an error description string for display, call the Get Error Description function with these parameters, plus a descriptionType, sizeOfArray = 0 and charArray = NULL. When the function returns, sizeOfArray has the size of the description in it. Allocate memory for a character array of size sizeOfArray + 1. Call the Get Error Description function a second time passing in the same parameters as before except sizeOfArray is the value of sizeOfArray + 1 returned by the first function call, and charArray points to the character array just allocated. This function returns the following strings, depending upon the descriptionType selected:
| descriptionType Constant | String |
| NIMC_ERROR_ONLY | Error –70124 (NIMC_findIndexError); Find Index sequence did not find the index successfully |
| NIMC_FUNCTION_NAME_ONLY | Find Index (flex_find_index) |
| NIMC_RESOURCE_NAME_ONLY | Axis 0x01 |
| NIMC_COMBINED_DESCRIPTION | Error –70124 (NIMC_findIndexError) occurred in Find Index (flex_find_index) on Axis 0x01; Find Index sequence did not find the index successfully |