mcStatusToString

Purpose

Converts a status code into a descriptive string.

Format

Input

Status

Nonzero status code returned from an ECU M&C function.

SizeOfString

SizeofString buffer (in bytes).

Output

ErrorString

ASCII string that describes Status.

Return Value

The return value indicates the status of the function call as a signed 32-bit integer. Zero means the function executed successfully. A negative value specifies an error, which means the function did not perform the expected behavior. A positive value specifies a warning, which means the function performed as expected, but a condition arose that may require attention.

Use the mcStatusToString function of the ECU M&C API to obtain a descriptive string for the return value.

Description

When the status code returned from an ECU M&C function is nonzero, an error or warning is indicated. This function is used to obtain a description of the error/warning for debugging purposes.

The return code is passed into the Status parameter. The SizeofString parameter indicates the number of bytes available in the string for the description. The description is truncated to size SizeofString if needed, but a size of 300 characters is large enough to hold any description. The text returned in ErrorString is null-terminated, so it can be used with ANSI C functions such as printf. For applications written in C or C++, each ECU M&C function returns a status code as a signed 32-bit integer. The following table summarizes the ECU M&C use of this status.

Status Code Use

The application code should check the status returned from every ECU M&C function. If an error is detected, you should close all ECU M&C handles and exit the application. If a warning is detected, you can display a message for debugging purposes or simply ignore the warning.

The following piece of code shows an example of handling ECU M&C status during application debugging.

status= ncDatabaseOpen ("TestDataBase.A2L", &MyDbHandle);

PrintStat (status, "mcOpenDatabase");

where the function PrintStat has been defined at the top of the program as:

void PrintStat(mcTypeStatus status, char *source)

{

char statusString[300];

if(status !=0)

{

mcStatusToString(status, sizeof(statusString), statusString);

printf("\n%s\nSource = %s\n", statusString, source);

if (status < 0)

{

mcDatabaseClose(MyDbHandle);

exit(1);

}

}

}

In some situations, you may want to check for specific errors in the code. For example, when mcCharacteristicRead times out, you may want to continue communication, rather than exit the application. To check for specific errors, use the constants defined in niemc.h. These constants have the same names as described in this help file. For example, to check for a function timeout, use:

if (status == mcErrorTimeout)

...