| MIL 10 Reference
| Customize Help
| Save Settings

MappGetError


See also
Availability
Available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
MappFreeDefault
MappGetHookInfo
Synopsis
Get error codes and related information.
Syntax
MIL_INT MappGetError(
MIL_ID ContextAppId, //in
MIL_INT64 ErrorType, //in
void *ErrorPtr //out
)
Description

This function obtains current or global application error information, for example, error codes, error subcodes, error messages, error submessages, function codes, and function names. This function allows you to check for errors after each MIL function call or to get the first error that occurred after a series of MIL function calls.

A typical use of this function is to check whether a buffer allocation call was successful (MbufAllocColor(), MbufAlloc1d(), and MbufAlloc2d()) or to see if a function returns an error.

In multi-thread environments, an MappGetError() call returns information either with the first error-returning function of the current thread or, if there no errors in the current thread, it checks for errors in the other MIL running threads. To return only errors in the current thread, see the combination constants, described below.

This function can also be used to obtain information about a detected error when error-reporting to the screen has been disabled using MappControl().

To clear errors, call MappControl() with M_CLEAR_ERROR.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see if there is complementary information.
Parameters
This function is not supported on the selected boards.
Parameters
ContextAppId

Specifies the identifier of the application context to use.

function map For specifying the application context
CollapseValue Description
Collapse M_DEFAULT

Specifies the current application context.
Collapse Application Context Identifier

Specifies the application context identifier.
ErrorType

Specifies the type of error information to read. This parameter can be set to one of the values below.

See the Parameter associations section for possible values that can be specified.

ErrorPtr
Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):
  • array of type MIL_TEXT_CHAR
  • MIL_INT

Specifies the address in which to write the requested information.

The MappGetError() function also returns the error/function code; if you don't want to get an error message or function name, you can set this parameter to M_NULL.

See the Parameter associations section for possible values that can be returned.

Parameter associations

The table below lists possible values for the ErrorType parameter and possible values returned to the ErrorPtr parameter.

Unless otherwise specified, the following values require that you pass the ErrorPtr parameter the address of a MIL_INT.

function map For specifying the type of error information to read
CollapseErrorType Description
ErrorPtr
- Possible values returned
Collapse M_CURRENT +

Retrieves the error code returned by the last function call. The current-error code is reset to M_NULL_ERROR before each MIL function call and is set to a specific error code when an error occurs during the execution of a function.

(summarize)
Collapse M_CURRENT_FCT +

Retrieves the opcode associated with the last function called, when it returns an error.

(summarize)
Collapse M_CURRENT_SUB_1 +

Retrieves the first error subcode returned by the last function call.

Note, when there is no error, the error subcode is set to M_NULL_ERROR.

(summarize)
Collapse M_CURRENT_SUB_2 +

Retrieves the second error subcode returned by the last function call.

Note, when there is no error, the error subcode is set to M_NULL_ERROR.

(summarize)
Collapse M_CURRENT_SUB_3 +

Retrieves the third error subcode returned by the last function call.

Note, when there is no error, the error subcode is set to M_NULL_ERROR.

(summarize)
Collapse M_CURRENT_SUB_NB

Retrieves the number of error subcodes associated with the last function called, when it returns an error.

(summarize)
Collapse M_GLOBAL +

Retrieves the error code of the first error that has occurred since the last call to MappGetError() (with ErrorType set to M_GLOBAL). This value is reset to M_NULL_ERROR before the next call to a MIL function (other than MappGetError()).

(summarize)
Collapse M_GLOBAL_FCT +

Retrieves the opcode associated with the first error-generating function since the last call to MappGetError() (with ErrorType set to M_GLOBAL).

(summarize)
Collapse M_GLOBAL_SUB_1 +

Retrieves the first error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL).

Note, when there is no error, the error subcode is set to M_NULL_ERROR.

(summarize)
Collapse M_GLOBAL_SUB_2 +

Retrieves the second error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL).

Note, when there is no error, the error subcode is set to M_NULL_ERROR.

(summarize)
Collapse M_GLOBAL_SUB_3 +

Retrieves the third error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL).

Note, when there is no error, the error subcode is set to M_NULL_ERROR.

(summarize)
Collapse M_GLOBAL_SUB_NB

Retrieves the number of error subcodes associated with the first error that occurred since the last call to MappGetError() (with ErrorType set to M_GLOBAL).

(summarize)

You can add one or more of the following values to the above-mentioned values to set whether to return a message, make the inquire synchronous, or limit it to the current thread.

function map For error types
CollapseErrorType Description
ErrorPtr
- Possible values returned
Collapse M_MESSAGE

Retrieves the error message associated with the specified error type, or the function name associated with a function code, and writes it to the address specified by the ErrorPtr parameter. The error/function code is still returned by MappGetError(), but it is not written to the address specified by ErrorPtr.

Note that this value cannot be added to M_CURRENT_SUB_NB or M_GLOBAL_SUB_NB.

(summarize)
Collapse ErrorPtr data type info

Data type: array of type MIL_TEXT_CHAR
Array size: When reporting an error message or function name, the array must be at least M_ERROR_MESSAGE_SIZE (320) characters in size.

Collapse M_SYNCHRONOUS

Forces the function to wait for all pending calls to complete before continuing.

(summarize)
Collapse M_THREAD_CURRENT

Specifies that only errors are returned in the current thread.

(summarize)
Return value
The returned value is the requested error/function code. If the error code is read and it is equal to M_NULL_ERROR, no error has occurred.
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
DEFAULT CURRENT CURRENT FCT CURRENT SUB 1 CURRENT SUB 2 CURRENT SUB 3 CURRENT SUB NB GLOBAL GLOBAL FCT GLOBAL SUB 1 GLOBAL SUB 2 GLOBAL SUB 3 GLOBAL SUB NB MESSAGE SYNCHRONOUS THREAD CURRENT