Click here to show toolbars of the Web Online Help System: show toolbars
 

Filters
Filter values by
  • General application settings
  • DMIL related settings
  • Error related settings
  • Trace-log settings
| Customize Help
| Save Settings

MappControl


Function Map
Syntax
Description
Parameters
- ContextAppId
Table: For specifying the application context
- ControlType
- ControlValue
Parameter Associations
Table: For managing error functionality
Table: For specifying the type of application environment
+ combination: For limiting effects to the current thread
Compilation information
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
Click to summarizeValue Description
Click to summarize M_DEFAULT

Specifies the current application context.
Click to summarize 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
Click to summarize
ControlType		 Description
ControlValue
Click to summarize M_CLEAR_ERROR +

Clears current and/or global errors.

(summarize)
Click to summarize M_DEFAULT

Specifies to clear both current and global errors.
Click to summarize M_CURRENT

Specifies to clear only current errors.
Click to summarize M_GLOBAL

Specifies to clear only global errors.
Click to summarize M_ERROR +

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

(summarize)
Click to summarize M_PRINT_DISABLE

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

(summarize)
Click to summarize M_PRINT_ENABLE

Specifies to print error messages.

This is the default value.

(summarize)
Click to summarize 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)
Click to summarize 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 using MappHookFunction(). INQ

(summarize)
Click to summarize 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 regards to error event types, until the functionality is restored using M_ERROR_HOOKS set to M_ENABLE.

(summarize)
Click to summarize 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
Click to summarize
ControlType		 Description
ControlValue
Click to summarize 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 MobjControl() 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)
Click to summarize 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)
Click to summarize 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 MobjControl().
Click to summarize 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 MobjControl().
Click to summarize 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)
Click to summarize 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.
Click to summarize 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)
Click to summarize 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)
Click to summarize M_COMPENSATION_ENABLE

Specifies that on-board memory compensation is enabled.

This is the default value.

(summarize)
Click to summarize M_PARAMETER +

Sets whether the checking of parameters is enabled. INQ

(summarize)
Click to summarize 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)
Click to summarize M_CHECK_ENABLE

Specifies that checking of parameters is enabled.

This is the default value.

(summarize)
Click to summarize M_PROCESSING +

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

(summarize)
Click to summarize 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)
Click to summarize 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)
Click to summarize 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)
Click to summarize 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)
Click to summarize M_LOG_DISABLE

Specifies the log disable setting, which stops generating the trace log.
Click to summarize M_LOG_ENABLE

Specifies the log enable setting, which starts generating the trace log.
Click to summarize 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 the .mtrace file that contains all trace data from the moment the trace started gathering data until the moment when this control is called.

(summarize)
Click to summarize M_NULL

Specifies to use the default path and default file name.
Click to summarize

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().

Combination value for M_CLEAR_ERROR; M_ERROR; M_MEMORY; M_PARAMETER; M_PROCESSING; M_TRACE.

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
Click to summarize
Combination value		 Description
Click to summarize 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