| Customize Help
| Save Settings

MappTrace


Function Map
Syntax
Description
Parameters
- ContextAppId
Table: For specifying the application context
- TraceType
Table: For specifying the trace type
- TraceTag
Table: For specifying the trace tag
- TraceValue
Table: For specifying the trace value
Table: For specifying the trace color
- TraceString
Table: For specifying the trace string
Table: For specifying the trace name
Compilation information
Synopsis
Create a user MIL trace marker or section in a trace log.
Syntax
void MappTrace(
MIL_ID ContextAppId, //in
MIL_INT64 TraceType, //in
MIL_INT64 TraceTag, //in
MIL_INT64 TraceValue, //in
MIL_CONST_TEXT_PTR TraceString //in
)
Description

This function creates a trace marker or section that allows runtime events to be easily identified in a trace log. Add a trace marker or section at places in your code that need attention, such as before entering or after exiting a block of code or before and after an external event. You can create a trace log using Matrox Profiler, or by calling MappControl() with M_TRACE set to M_LOG_ENABLE. See the Matrox Profiler and trace logs section of Chapter 50: Development and debugging tools and techniques for more information on creating a trace log.

When creating a trace marker, only a single function call to MappTrace() is needed (TraceType set to M_TRACE_MARKER). When creating a trace section, two calls to MappTrace() are needed, one function call to start the section and another call to end the section (TraceType set to M_TRACE_SECTION_START and M_TRACE_SECTION_END, respectively).

When creating a trace marker or section, you can assign it a trace tag (TraceTag), a trace value (TraceValue), and/or a trace string (TraceString). The trace tag is a fixed user-defined value that identifies the trace marker or section. The trace value and trace string are used to display information relevant to the current placement of the marker; typically, these are variables that depend on runtime events, such as the calculated or return value of a user-defined function. When reading a trace log with Matrox Profiler, you can directly search for your trace markers or sections and display the relevant information. Note that when creating a trace section, both calls to MappTrace() must have the same TraceTag value.

Optionally, this function can set additional trace tag information using TraceType set to M_TRACE_SET_TAG_INFORMATION. Once this additional tag information is set, all trace markers or sections that have the same TraceTag value will use the trace tag's color and name. When viewing an .mtrace file in Matrox Profiler, trace markers and sections display this new tag information, along with the original trace values and trace strings assigned when the trace marker or section was created. Together, these pieces of information add an extra level of convenience when searching for trace markers or sections.

Note that MappTrace() does nothing if you are not generating a trace log.

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

Specifies the type of trace marker to create.

function map For specifying the trace type
Click to summarizeValue Description
Click to summarize M_DEFAULT

Same as M_TRACE_MARKER.
Click to summarize M_TRACE_MARKER

Specifies to create a trace marker that identifies a single point in the code.
Click to summarize M_TRACE_SECTION_END

Specifies to end a user trace section. It must come after M_TRACE_SECTION_START, and must have the same TraceTag value as the corresponding start.

(summarize)
Click to summarize M_TRACE_SECTION_START

Specifies to start a user trace section. It must be followed by a call to MappTrace() with M_TRACE_SECTION_END.

(summarize)
Click to summarize M_TRACE_SET_TAG_INFORMATION

Specifies to associate a name and/or color with the specified trace tag. Trace markers or sections that have the same tag will display this color an/or name in Matrox Profiler.

Associating a color allows the user to quickly identify different trace markers or sections instead of seeing the same color for all user traces in Matrox Profiler. Associating a name to a marker or section can be helpful in searching for the marker's or section's name rather than its numerical TraceTag value.

Note that when generating a trace log in memory, the color and name associated with a trace tag might not be displayed, dependent on if the trace element associated with this call is still in memory or not.

(summarize)
TraceTag

Specifies a value that identifies this trace marker or section.

function map For specifying the trace tag
Click to summarizeValue Description
Click to summarize M_NULL

Specifies that no trace tag is used for this trace marker or section.
Click to summarize 1 <= Value <= 255

Specifies a user-defined value. When using Matrox Profiler, you can search for a marker or section based on its TraceTag value.

When creating a trace section, both the start function call and the end function call must specify the same TraceTag value.

When TraceType is set to M_TRACE_SET_TAG_INFORMATION, this value specifies the trace tag to apply the tag information to. All trace markers and sections with the same trace tag display the tag's color and/or name.

(summarize)
TraceValue

Specifies a value relevant to the trace marker or section, or relevant to the surrounding code.

function map For specifying the trace value
Click to summarizeValue Description
Click to summarize M_NULL

Specifies that no trace value is logged for this trace marker or section.
Click to summarize Value

Specifies a user-defined value.

When TraceType is set to M_TRACE_SET_TAG_INFORMATION, you can specify a color associated with the trace tag.

function map For specifying the trace color
Click to summarizeValue Description
Click to summarize M_DEFAULT

Specifies the default color.
Click to summarize
M_RGB888(
MIL_INT Red,
MIL_INT Green,
MIL_INT Blue
)

Specifies an RGB value used to clear an 8-bit 3-band buffer to an RGB color. Each value (red, green or blue) must not exceed 8 bits.

(summarize)
Parameters

Specifies the red component, as a value between 0 and 255.

Specifies the green component, as a value between 0 and 255.

Specifies the blue component, as a value between 0 and 255.
TraceString

Specifies a string relevant to the trace marker or section, or relevant to the surrounding code.

function map For specifying the trace string
Click to summarizeValue Description
Click to summarize M_NULL

Specifies that no trace string is logged for this trace marker or section.
Click to summarize MIL_TEXT("TraceString") 1

Specifies a user-defined string.

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

When TraceType is set to M_TRACE_SET_TAG_INFORMATION, you can specify a name associated with the trace tag.

function map For specifying the trace name
Click to summarizeValue Description
Click to summarize MIL_TEXT("M_DEFAULT") 1

Specifies the default name, which is equivalent to the value of the TraceTag parameter.
Click to summarize MIL_TEXT("TraceTagName") 1

Specifies a user-defined name for the trace tag.

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

Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
DEFAULT DEFAULT TRACE MARKER TRACE SECTION END TRACE SECTION START TRACE SET TAG INFORMATION NULL NULL DEFAULT NULL DEFAULT"