| MIL 10 Reference
| Customize Help
| Save Settings

MappControl


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
MappCloseConnection
MappControlObject
Synopsis
Control an application environment setting.
Syntax
void MappControl(
MIL_ID ContextAppId, //in
MIL_INT64 ControlType, //in
MIL_INT ControlValue //in
)
Description

This function controls the settings of a MIL application environment. These settings include printing error messages to the screen, parameter checking, logging trace information, as well as on-board memory and processing compensation modes. This function can also clear current and/or global errors.

In multi-thread environments, an MappControl() call applies to all application threads running MIL, unless specifically limited to the calling thread by adding M_THREAD_CURRENT to the ControlType parameter. When you override settings for a specific thread, a subsequent call to change those settings from any other thread will not change the settings. For example, if you enable trace printing for a particular thread, that thread will ignore calls from other threads that try to change trace printing setting. Note that any thread created by the current thread will automatically inherit all the current thread's settings, but it will not inherit this exclusivity.

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.
ControlType

Specifies the type of application environment setting to control.

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

ControlValue

Specifies the setting's new value.

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

Parameter associations

The tables below list possible values for the ControlType and ControlValue parameters.

The following ControlType and corresponding ControlValue parameter settings are used to manage error functionality in the application.

function map For managing error functionality
CollapseControlType Description
ControlValue
Collapse M_CLEAR_ERROR +

Clears current and/or global errors.

(summarize)
Collapse M_DEFAULT

Specifies to clear both current and global errors.
Collapse M_CURRENT

Specifies to clear only current errors.
Collapse M_GLOBAL

Specifies to clear only global errors.
Collapse M_ERROR +

Sets whether the printing of error messages to screen is enabled. INQ

(summarize)
Collapse M_PRINT_DISABLE

Specifies not to print error messages. If error printing is disabled, you can still check for error, using MappGetError().

(summarize)
Collapse M_PRINT_ENABLE

Specifies to print error messages.

This is the default value.

(summarize)
Collapse M_THROW_EXCEPTION

Specifies that when an error occurs, a .NET exception will be thrown instead of a message box being displayed.

M_THROW_EXCEPTION is only valid when working in a .NET environment.

(summarize)
Collapse M_ERROR_HOOKS

Sets whether an error event type (specified using MappHookFunction() set to M_ERROR_CURRENT, M_ERROR_GLOBAL, or M_ERROR_FATAL) will trigger the user defined function specified in MappHookFunction(). INQ

(summarize)
Collapse M_DISABLE

Specifies to not trigger the user defined function when an error event type occurs, as specified in MappHookFunction().

This ignores the functionality of MappHookFunction() with regard to error event types, until the functionality is restored using M_ERROR_HOOKS set to M_ENABLE.

(summarize)
Collapse M_ENABLE

Specifies to trigger the user defined function when an error event type occurs, as specified in MappHookFunction().

This is the default value.

(summarize)

The following ControlType and corresponding ControlValue parameter settings are used to control the application environment.

function map For specifying the type of application environment
CollapseControlType Description
ControlValue
Collapse M_DMIL_CONNECTION

Specifies the Distributed MIL monitoring configuration global permission level.

This allows or disallows another MIL application, the monitoring application, to provisionally access specified MIL objects in the current application, the publishing application. Each MIL object in the publishing application must individually allow either read only, or read/write access by calling MappControlObject() with M_DMIL_PUBLISH set to either M_READ_ONLY or M_READ_WRITE, respectively. Any MIL object not specified as read only or read/write is not be accessible by the monitoring application. INQ

(summarize)
Collapse M_DISABLE

Specifies that Distributed MIL monitoring configuration is disabled in the current application. Once disabled, a monitoring application cannot access any MIL objects in the current application.

(summarize)
Collapse M_DMIL_CONTROL

Specifies that MIL objects in the current application can be accessed with either read only or read/write permission, depending on how that MIL object was specified with MappControlObject().
Collapse M_DMIL_MONITOR

Specifies that MIL objects in the current application can be accessed only with read only permission, regardless of how that MIL object was specified with MappControlObject().
Collapse M_DMIL_CONNECTION_PORT

Specifies the listening port for a publishing application in the Distributed MIL monitoring configuration. If the publishing application has specified a listening port, the monitoring application connecting to the publishing application must specify that listening port. If the publishing application does not specify a listening port, the default listening port, set using the MILConfig utility, is used.

M_DMIL_CONNECTION_PORT only applies when the current application is a publishing application in a Distributed MIL monitoring configuration. INQ

(summarize)
Collapse Listening port

Specifies the listening port (an integer between 0 and 65535) that the current application will use to listen for connections from a monitoring application.
Collapse M_MEMORY +

Sets whether on-board memory compensation on the Host is enabled. On-board memory compensation allows memory to be allocated on Host when a system has insufficient memory to perform that memory allocation. INQ

(summarize)
Collapse M_COMPENSATION_DISABLE

Specifies that on-board memory compensation is disabled. If there is insufficient memory available for the allocation, an error is generated.

(summarize)
Collapse M_COMPENSATION_ENABLE

Specifies that on-board memory compensation is enabled.

This is the default value.

(summarize)
Collapse M_PARAMETER +

Sets whether the checking of parameters is enabled. INQ

(summarize)
Collapse M_CHECK_DISABLE

Specifies that checking of parameters is disabled. Note, if parameter checking is disabled (for example, to accelerate an application), unpredictable behavior can be expected when passing invalid parameters to a function.

(summarize)
Collapse M_CHECK_ENABLE

Specifies that checking of parameters is enabled.

This is the default value.

(summarize)
Collapse M_PROCESSING +

Sets whether the Host should compensate for processes that cannot be performed on-board due to board-specific limitations. INQ

(summarize)
Collapse M_COMPENSATION_DISABLE

Specifies that on-board processing compensation is disabled. If an operation cannot be performed by the system's on-board processor, an error is generated.

(summarize)
Collapse M_COMPENSATION_ENABLE

Specifies that on-board processing compensation is enabled. If an operation cannot be performed by the system's on-board processor, it will be performed by the Host.

This is the default value.

(summarize)
Collapse M_TRACE +

Sets the trace setting, which controls when a trace log is generated.

The trace log is a binary file with a .mtrace extension and is readable only with Matrox Profiler.

This control type is synchronous. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default trace setting, which either enables or disables generating a trace log, based on whether Matrox Profiler (or Matrox Interactive log) was used to start generating the log.

If Matrox Profiler (or Matrox Interactive log) started generating the trace log, this control value is the same as M_LOG_ENABLE.

If a MIL function started generating the trace log, this control value is the same as M_LOG_DISABLE.

(summarize)
Collapse M_LOG_DISABLE

Specifies the log disable setting, which stops generating the trace log.
Collapse M_LOG_ENABLE

Specifies the log enable setting, which starts generating the trace log.
Collapse M_TRACE_SAVE_TO_FILE

Transfers all gathered trace data from the temporary circular trace log buffer to an .mtrace file with the specified path and/or file name.

This control is typically used when you intend to generate a trace log to memory in Matrox Profiler. A trace log to memory uses a circular overwrite temporary buffer, which gets chronologically corrected into an .mtrace file when this control is called. The resulting .mtrace file only contains the most recent trace data present in the circular buffer.

When generating a trace log and gathering trace data directly to file, calling this control forces a flush to an .mtrace file that contains all trace data from the moment the trace started gathering data until the moment when this control is called.

(summarize)
Collapse M_NULL

Specifies to use the default path and default file name.
Collapse
M_PTR_TO_MIL_INT(
MIL_CONST_TEXT_PTR PathAndOrFileName
)

Casts the address of the string identifying the specified path and/or file name, from a MIL_CONST_TEXT_PTR to a MIL_INT.

(summarize)
Parameters

This parameter specifies the string whose address to cast.
MIL_TEXT("FileName") 1

Specifies the file name, but uses the default path. For instance, MIL_TEXT("Test.mtrace").
MIL_TEXT("Path") 1

Specifies the path, but uses the default file name. For instance, MIL_TEXT("D:\\MyFolder").

Note that every folder in the path must already exist. This control only uses existing folders.
MIL_TEXT("PathAndFileName") 1

Specifies the path and the file name. For instance, MIL_TEXT("D:\\MyFolder\\Test.mtrace").

Note that every folder in the path must already exist. This control only uses existing folders.

1 If you are passing the value in a variable, don't enclose it in MIL_TEXT().

You can add the following value to the above-mentioned values to set whether the control should be limited to the current thread.

function map For limiting effects to the current thread
CollapseCombination value Description
Collapse M_THREAD_CURRENT

Limits the effect of the control type setting to the current thread.

Note that when this value is added to M_TRACE, M_TRACE set to M_DEFAULT will adopt the current global trace state (enabled or disabled) of the MIL application.

(summarize)
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
DEFAULT CLEAR ERROR DEFAULT CURRENT GLOBAL ERROR PRINT DISABLE PRINT ENABLE THROW EXCEPTION ERROR HOOKS DISABLE ENABLE DMIL CONNECTION DISABLE DMIL CONTROL DMIL MONITOR DMIL CONNECTION PORT MEMORY COMPENSATION DISABLE COMPENSATION ENABLE PARAMETER CHECK DISABLE CHECK ENABLE PROCESSING COMPENSATION DISABLE COMPENSATION ENABLE TRACE DEFAULT LOG DISABLE LOG ENABLE TRACE SAVE TO FILE NULL THREAD CURRENT