ITrace Interface Reference

Inherits IDispatch.

Collaboration diagram for ITrace:

Classes
struct	TraceBufferInformation
struct	TraceModuleInformation

Public Member Functions
HRESULT	ActivateAllModules (void)
HRESULT	DeactivateAllModules (void)
HRESULT	GetNumberOfModules ([out, retval] LONG *numberOfModules)
HRESULT	GetNumberOfBuffers ([out, retval] LONG *numberOfBuffers)
HRESULT	GetModuleList ([out, retval] SAFEARRAY(struct TraceModuleInformation)*traceInfo)
HRESULT	GetBufferList ([out, retval] SAFEARRAY(struct TraceBufferInformation)*traceInfo)
HRESULT	ClearAllBuffers (void)

Properties
IModules	Modules [get]
IBuffers	Buffers [get]

Detailed Description

Definition of the ITrace interface which gives access to internal tracing facility of the device.

The ITrace interface contains various methods to access the tracing facility of the device. It allows for adding new trace messages as well as for reading available trace messages which are added by other mlpi user applications or portions of the device firmware itself. Those trace messages can be seen as log messages which are collected in circular buffers, which then can be viewed, filtered or saved to disk. Trace messages come in handy during application development or debugging.

Definition at line 76 of file ITrace.idl.

Member Function Documentation

HRESULT ITrace::ActivateAllModules

(

void

)

This function activates all available modules. Only modules which are activated insert messages into a trace buffer. Messages, warnings or errors to modules which are deactivated are discarded.

Note

You can activate a specific module by using the method ActivateModule in the interface IModule.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

try
{
  connection.Trace.ActivateAllModules();
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

This method maps to the mlpiCore function mlpiTraceActivateAllModules, where you can find further documentation.

HRESULT ITrace::DeactivateAllModules

(

void

)

This function deactivates all available modules. Only modules which are activated insert messages into a trace buffer. Messages, warnings or errors to modules which are deactivated are discarded.

Note

You can deactivate a single module by using the method DeactivateModule in the interface IModule.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

try
{
  connection.Trace.DeactivateAllModules();
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

This method maps to the mlpiCore function mlpiTraceDeactivateAllModules, where you can find further documentation.

HRESULT ITrace::GetNumberOfModules

(

[out, retval] LONG *

numberOfModules

)

This method returns the number of currently available trace modules. Use the method GetModuleList to read a list of all available modules and their names.

Parameters

[out]

numberOfModules

Returns the number of available trace modules.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

try
{
  int numTraceModules = connection.Trace.GetNumberOfModules();

Console.WriteLine("Number of available Trace-Modules: " + numTraceModules.ToString());
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

This method maps to the mlpiCore function mlpiTraceGetNumberOfModules, where you can find further documentation.

HRESULT ITrace::GetNumberOfBuffers

(

[out, retval] LONG *

numberOfBuffers

)

This method returns the number of currently available trace buffers. Use the method GetBufferList to read a list of all available buffers and their names.

Parameters

[out]

numberOfBuffers

Returns the number of available trace buffers.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

try
{
  int numTraceBuffers = connection.Trace.GetNumberOfBuffers();

Console.WriteLine("Number of available Trace-Buffers: " + numTraceBuffers.ToString());
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

This method maps to the mlpiCore function mlpiTraceGetNumberOfBuffers, where you can find further documentation.

HRESULT ITrace::GetModuleList

(

[out, retval] SAFEARRAY(struct TraceModuleInformation)*

traceInfo

)

This method returns an array of all currently available trace modules.

Parameters

[out]

traceInfo

Returns an array of structures. Each element holds detailed information about a trace module.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

try
{
  // get the list of modules from the device
  TraceModuleInformation[] modules = (TraceModuleInformation[])connection.Trace.GetModuleList();

  // print each module information to console
  Console.WriteLine("ModuleName           IsActive ToMain ToStdOut ToSepar BufferName");
  foreach (TraceModuleInformation module in modules)
  {
    Console.WriteLine("{0, -22} {1, -7} {2, -7} {3, -7} {4, -7} {5}",
      module.moduleName,
      module.isActive.ToString(),
      module.toMainBuffer.ToString(),
      module.toStdOut.ToString(),
      module.toSeparateBuffer.ToString(),
      module.bufferName);
  }
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

This method maps to the mlpiCore function mlpiTraceGetNumberOfModules and mlpiTraceGetModuleList, where you can find further documentation.

HRESULT ITrace::GetBufferList

(

[out, retval] SAFEARRAY(struct TraceBufferInformation)*

traceInfo

)

This method returns an array of all currently available trace buffers.

Parameters

[out]

traceInfo

Returns an array of structures. Each element holds detailed information about a trace buffer.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

try
{
  // get the list of buffers from the device
  TraceBufferInformation[] buffers = (TraceBufferInformation[])connection.Trace.GetBufferList();

  // print each buffer information to console
  Console.WriteLine("BufferName           IsLocked   MaxSize  ActualSize");
  foreach (TraceBufferInformation buffer in buffers)
  {
    Console.WriteLine("{0, -22} {1, -7} {2, 8} {3, 8}",
      buffer.bufferName,
      buffer.isLocked.ToString(),
      buffer.maximumBufferSize,
      buffer.actualBufferSize
      );
  }
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

This method maps to the mlpiCore function mlpiTraceGetNumberOfBuffers and mlpiTraceGetBufferList, where you can find further documentation.

HRESULT ITrace::ClearAllBuffers

(

void

)

This method clears all messages in all currently available trace buffers.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

try
{
  connection.Trace.ClearAllBuffers();
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

This method maps to the mlpiCore function mlpiTraceClearAllBuffers, where you can find further documentation.

Property Documentation

IModules ITrace::Modules

get

This property returns a IModules object which allows access to different IModule objects. The IModules interface is a collection interface.

Parameters

[out]

modules

Returns an object of the type IModules.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

try
{
  // let's get the module object to the buffer which is called "MAIN"
  IModule module = connection.Trace.Modules["PLC_USER"];

  // let's activate the module
  module.ActivateModule();
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

IBuffers ITrace::Buffers

get

This property returns an IBuffers object which allows access to different IBuffer objects. The IBuffers interface is a collection interface.

Note

By definition there is always a trace buffer named "MAIN".

Parameters

[out]

buffers

Returns an object of the type IBuffers.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

try
{
  // let's get the buffer object to the buffer which is called "MAIN"
  IBuffer bufferMain = connection.Trace.Buffers["MAIN"];

  // use buffer object to print name of the buffer
  Console.WriteLine("BufferName: " + bufferMain.NameOfBuffer);
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

---

The documentation for this interface was generated from the following file:

• ITrace.idl