mvIMPACT Acquire SDK C++
Logging

This section contains a detailed explanation how the log output for mvIMPACT Acquire devices is configured and how it works in general.

It is only necessary to understand all the details in this chapter if the default configuration shall be modified e.g. by a script or if a custom configuration shall be created and added to an installation package of an application. Otherwise using mvDeviceConfigure can be used to set up logging according to an applications needs. How to do this ist explained in the manual dealing with the GUI applications of mvIMPACT Acquire (e.g. https://www.matrix-vision.com/manuals/)

mvDebugFlags.mvd - The Activation Flags For Logging

The key to all *.log-output is a parameter file called "mvDebugFlags.mvd". The file itself is an XML file containing sections for each library and each device the user wants to get *.log output from. The first line in this file should be the XML declaration and therefore will look somehow like this:

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes" ?>

To form a well formed and valid XML document a root item must be introduced. For this file it will be a tag call DebugWriterList. The simplest structure this file can have therefore will be something like this:

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes" ?>
<DebugWriterList>
</DebugWriterList>

Within this root item an arbitrary number of log sections (tag name: DebugWriter ) can be placed. All other XML tags will be ignored.

The D ocument T ype D escription (DTD) for this file therefore can roughly be expressed like this:

<!DOCTYPE DebugWriterList [
<!ELEMENT DebugWriterList (DebugWriter*)>
<!ELEMENT DebugWriter (#PCDATA)>
]>

Log Sections

One log section in the *.mvd-file looks more or less like this:

<DebugWriter
name="mvDeviceManager"
flags="01111111"
outputmask="110"
outputfile="STDLOGDIR\mvDeviceManager.xml"
clearFile="1">
</DebugWriter>

A complete parameter file to define and configure *.log output for a certain module therefore could look like this:

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes" ?>
<DebugWriterList>
<DebugWriter
name="mvDeviceManager"
flags="01111111"
outputmask="110"
outputfile="STDLOGDIR\mvDeviceManager.xml"
clearFile="1">
</DebugWriter>
</DebugWriterList>

The meaning of the individual attributes will be explained in the following sub sections.

The order of appearance of the attributes is not defined and not all attributes are required. The following sample will all be valid *.log-configuration:

<DebugWriterList>
<DebugWriter
name="mvVirtualDevice-666"
flags="01111100"
outputmask="100"
outputfile="STDLOGDIR/mvVirtualDevice"
clearFile="1">
</DebugWriter>
<DebugWriter
flags="01111100"
outputmask="100"
name="mvVirtualDevice-667"
outputfile="STDLOGDIR/mvVirtualDevice">
</DebugWriter>
<DebugWriter
outputfile="STDLOGDIR/mvVirtualDevice"
name="mvVirtualDevice-668"
flags="01111100"
clearFile="1">
</DebugWriter>
<DebugWriter
outputfile="STDLOGDIR/mvVirtualDevice-669"
name="mvVirtualDevice-669"
flags="01111100"
clearFile="1"
stylesheet="none" >
</DebugWriter>
<DebugWriter
outputfile="STDLOGDIR/mvVirtualDevice"
name="mvVirtualDevice-670"
flags="01111110"
clearFile="1"
stylesheet="myStyleSheet.xsl"
fileFormat="xml" >
</DebugWriter>
<DebugWriter
outputfile="STDLOGDIR/mvVirtualDevice"
name="mvVirtualDevice-671"
flags="01111100"
clearFile="1"
fileFormat="text">
</DebugWriter>
<DebugWriter
flags="01111100"
outputmask="010"
name="mvVirtualDevice-672">
</DebugWriter>
</DebugWriterList>
Note
As it can be seen it the sample from above several devices / log configurations can use the same file to send their messages to.

The complete DTD for log configuration files looks like this:

<!DOCTYPE DebugWriterList [
<!ELEMENT DebugWriterList (DebugWriter*)>
<!ELEMENT DebugWriter (#PCDATA)>
<!ATTLIST DebugWriter
name CDATA #REQUIRED
flags CDATA #REQUIRED
outputmask CDATA "010"
outputfile CDATA #IMPLIED
clearFile CDATA "1"
fileFormat (xml | text | mvlog) 'xml'
stylesheet CDATA "mvIMPACT_acquireLogFile.xsl"
>
]>

Property 'name'

The name property is the name of the library (without extension) or the device for which *.log-output shall be generated. In this case, it's the mvDeviceManager library. For devices the name will build from the value of the property 'Family' in the device list, a dash ('-') and the current device ID. So e.g. mvVirtualDevice-666 would specify the log-section for a device belonging to the product family group mvVirtualDevice and has been assigned a device ID of 666. In the parameter file the corresponding section would look somehow like this:

<DebugWriter
name="mvVirtualDevice-666"
flags="01111111"
outputmask="110"
outputfile="STDLOGDIR\mvVirtualDevice-666"
clearFile="1">
</DebugWriter>
Note
This attribute is required.

Property 'flags'

The flags property is a string containing either 0 or 1 for each type of log message while 0 means that this *.log-messages will NOT be written to the log output and 1 that the messages will be sent to the log output.

From right to left the numbers have the following meaning:

  • information (these type of messages will only be available in debug builds)
  • important information (these type of messages will only be available in debug builds)
  • warning
  • error
  • fatal error
  • log message
  • general purpose

So something like this: flags="001110" will result in messages internally classified as important information (first "1" from the right), warning (2nd "1" from the right) or error to be sent to the output.

Note
This attribute is required.

Property "outputmask"

Log messages can be sent to multiple destinations. where the output will be sent to can be defined by the property "outputmask". It contains three digits (either "0" or "1") to activate certain destinations. The rightmost digit defines the system's standard output, the digit in the middle the system's standard debug output and the digit on the left a file.

From right to left the flags have the following meaning:

  • system standard output
  • system debug output
  • file

So outputmask="110" results in log messages to be sent to the system's standard debug output AND a file while outputmask="001" would send the log messages to the system's standard output only.

Note
This attribute is optional. If omitted messages will only be sent to the system debug output

Property "outputfile"

If log messages shall be sent to a file, this property should contain the name of the output file.

If the name of the output file starts with STDLOGDIR then the file will be created in the same folder where the file "mvDebugFlags.mvd" is located after the installation.

So outputfile="STDLOGDIR\\mvDeviceManager.xml" on Windows will send all log messages to "%ALLUSERS%\Documents\MATRIX VISION\mvIMPACT Acquire\Logs" (or "%MVIMPACT_ACQUIRE_DATA_DIR%\Logs" which will point to the same folder), while under Linux the log messages can be found in /opt/mvIMPACT_Acquire/data/logs .

Once a device has been initialized the name and the full path to the log file can be obtained by reading the value of the property mvIMPACT::acquire::InfoBase::logFile.

Note
It is NOT necessary to specify the file extension .xml explicitly. If the file name does not end with .xml it will be appended automatically. This however implies, that only the *.xml format is currently supported and later will be the default.
This attribute is optional. If omitted no messages will be sent to a file and no file will be created.

Property "clearFile"

Defines if new information is appended at the end of an existing file from a previous session ('0' ), or if a new file shall be created for each session ('1' ) overwriting existing files.

Note
The term session means the time the device drivers library is in process memory, which might be longer then the time the device is actually initialized. To remove a device driver from process memory, the device manager must be closed.
Appending to existing files is slow and might produce very large files when used over a long period of time which might affect the overall performance of the system. So using the append feature is an option, but it is NOT recommend. Only use it if necessary!
This attribute is optional. If omitted existing files will be overwritten.

Property "fileFormat"

Defines the output format for the log file output. It can be "text" for *.txt style output, "xml" for XML file output with a user definable stylesheet or 'mvlog' to create log files that can be displayed using mvLogFileViewer.html. If this parameter is not present XML file output will be used. Only in this mode the 'stylesheet' parameter will be taken into account.

Note
This attribute is optional. If omitted the XML format will be used.

Property "stylesheet"

Defines if a stylesheet shall be embedded into the log-file. If no stylesheet shall be referenced by the resulting log-file this property must be set to "none". Otherwise this property defines the name of the stylesheet file that will later be used to transform the log-file into the desired output format.

Note
This attribute is optional. If omitted the standard stylesheet "'mvIMPACT_acquireLogFile.xsl" will be embedded in the *.log-file. This stylesheet is part of the installation and will be installed to the same directory as the *.mvd-file.

Locating The File On Windows

mvDebugFlags.mvd on Windows will be installed to

  • "%ALLUSERS%\Documents\MATRIX VISION\mvIMPACT Acquire\Logs"
  • (or "%MVIMPACT_ACQUIRE_DATA_DIR%\Logs" which will point to the same folder)

whenever a device driver is installed. On Windows this is the one and only location, where this file can be located. Otherwise, no log-files will be created.

Locating The File On Linux

Whenever a Linux driver package will be installed, the "mvDebugFlags.mvd" file will be installed in the folder /opt/mvIMPACT_Acquire/data/logs . If you use another working directory, you have to copy the "mvDebugFlags.mvd" to this folder. E.g. if you work in /home/workspace and you execute your app from this folder, a copy of "mvDebugFlags.mvd" must be available there if you want logging.

Windows

Logging During Installation

All installation packages shipped on Windows platforms internally make use of the MSI (Microsoft Windows Installer™) technology. Most of the packages therefore will be *.msi files while some packages are distributed as so called bootstrappers which will be *.exe files. In case you ever run into trouble during the installation of a packages before contacting the support team please create a log-file of the installation process. This can be achieved like this:

// for *.msi files
msiexec /i myInstaller.msi /L*v nameOfTheLogFile.log
// for *.exe files
myInstaller.exe /log nameOfTheLogFile.log