MappGetError

Filters
See also

User Guide:

Error reporting Modules, opcodes, and error handling Multi-threading

Reference:

MappControl MbufAlloc1d MbufAlloc2d MbufAllocColor

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/GPm

Available on Matrox Supersight

Function map

Examples

Function Map

Table:

For specifying the application context

- ErrorType

- ErrorPtr

Parameter Associations

Table:	For specifying the type of error information to read
+ combination:	For error types
+ combination:	For getting the message size

Return value

Compilation information

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.

For specifying the application context
Value	Description
M_DEFAULT	Specifies the current application context.
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.

For specifying the type of error information to read

For specifying the type of error information to read
ErrorType		Description
	ErrorPtr - Possible values returned	Description
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) Retrieves the error code returned by the last function call. (more details...)
	ErrorPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT
M_CURRENT_FCT +		Retrieves the opcode associated with the last function called, when it returns an error. (summarize) Retrieves the opcode associated with the last function called, when it returns an error. (more details...)
	ErrorPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT
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) Retrieves the first error subcode returned by the last function call. (more details...)
	ErrorPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT
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) Retrieves the second error subcode returned by the last function call. (more details...)
	ErrorPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT
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) Retrieves the third error subcode returned by the last function call. (more details...)
	ErrorPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT
M_CURRENT_SUB_NB		Retrieves the number of error subcodes associated with the last function called, when it returns an error. (summarize) Retrieves the number of error subcodes associated with the last function called, when it returns an error. (more details...)
	ErrorPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT
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) Retrieves the error code of the first error that has occurred since the last call to MappGetError() (with ErrorType set to M_GLOBAL). (more details...)
	ErrorPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT
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) Retrieves the opcode associated with the first error-generating function since the last call to MappGetError() (with ErrorType set to M_GLOBAL). (more details...)
	ErrorPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT
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) Retrieves the first error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL). (more details...)
	ErrorPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT
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) Retrieves the second error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL). (more details...)
	ErrorPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT
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) Retrieves the third error subcode of the first error that has occurred since the call to MappGetError() (with ErrorType set to M_GLOBAL). (more details...)
	ErrorPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT
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) 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). (more details...)
	ErrorPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT

Combination values for M_CURRENT; M_CURRENT_FCT; M_CURRENT_SUB_1; M_CURRENT_SUB_2; M_CURRENT_SUB_3; M_GLOBAL; M_GLOBAL_FCT; M_GLOBAL_SUB_1; M_GLOBAL_SUB_2; M_GLOBAL_SUB_3.

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.

For error types
ErrorType		Description
	ErrorPtr - Possible values returned	Description
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) 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. (more details...)
	ErrorPtr extra info	Data type info: Data type: array of type MIL_TEXT_CHAR (more details...) Data type: array of type MIL_TEXT_CHAR Required array size:(MappGetError() with a value + M_MESSAGE + M_STRING_SIZE) Note: You can also use M_ERROR_MESSAGE_SIZE as the array size. Data type info: Data type: array of type MIL_TEXT_CHAR (more details...) Data type: array of type MIL_TEXT_CHAR Required array size:(MappGetError() with a value + M_MESSAGE + M_STRING_SIZE) Note: You can also use M_ERROR_MESSAGE_SIZE as the array size.
M_SYNCHRONOUS		Forces the function to wait for all pending calls to complete before continuing. (summarize) Forces the function to wait for all pending calls to complete before continuing. (more details...)
M_THREAD_CURRENT		Specifies that only errors are returned in the current thread. (summarize) Specifies that only errors are returned in the current thread. (more details...)

Combination value for M_MESSAGE.

You can add the following value to the above-mentioned value to get the message's length.

For getting the message size
Combination value	Description
M_STRING_SIZE	Retrieves the length of the string, including the terminating null character ("\0").

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.