Diagnostics can be parameterized by means of an external configuration file in xml format. This user-specific configuration file can be loaded when starting the program. After this, the settings are available. The file is read by Diagnostics and not written to.
The file is structured in xml format (http://www.xml.org) and must include the encoding ISO-8859-1. This allows you to enter special characters (such as German umlauts ä, ö and ü) at any time using a simple text editor.
The root node has the name <config>. Further subnodes are described in the paragraph Parameters.
The typical configuration file as shown below contains two entries: autofilesavefilename and defaultfilesavedirectory. They are both located as a group under the parent node fileoptions:
<?xml version="1.0" encoding="ISO-8859-1" ?>
<config>
<fileoptions>
<autofilesavefilename>
<![CDATA[Diagnostics_<date>_<counter>.pdi]]
</autofilesavefilename>
<defaultfilesavedirectory>
c:\temp\Diagnostics
</defaultfilesavedirectory>
</fileoptions>
</config>
Changes to the file must be xml compliant. Otherwise, the file cannot be loaded. When starting Diagnostics, this is indicated by a diagnostic message. It states the row and column containing invalid code. The program is then launched without the invalid configuration file.
There are two ways to load the desired configuration file:
oAutomatically:
If there is a file with the name Diagnostics.config.xml in the start directory of Diagnostics, it is loaded automatically upon startup. The program then uses these settings as it runs.
oManually:
You can also load the configuration file explicitly from another location in the file system using a command line. This has precedence over the automatic call.
To do this, you can use the following syntax via the command line:
-userconfigfile <file name>.
In this case, the configuration file entered under <file name> is loaded.
The individual parameters are described where they appear within the configuration file Diagnostics.config.xml. It contains application examples. As this file is located in the program directory, it can be used as a template.
Moreover, the parameters are described in detail. The parameters are listed as xml paths, which describe their distinct position within the .xml file.
Parameter config/fileoptions/autofilesavefilename
When a file is saved, a file name can be generated automatically. The file name can consist of constant name elements, values (for example date or machine name) and a counter. The automatically generated name is then proposed, for example in the Save as dialog box. It can be accepted or overwritten.
The automatically generated name can be described by text and placeholders.
Example
Diagnostics_date=<date>.pdi results in the file name Diagnostics_date=2006-03-12.pdi (The current date is used.)
Write the placeholder in lower case letters. This means that <date> is valid, whereas <Date> is not recognized.
The newly generated file name may include characters that are not supported by the file system (for example, if the machine name is My?Machine). These characters are replaced by a lowercase x.
Example
My?File.pdi is replaced by MyxFile.pdi.
The following 8 characters are not supported by the file system and are therefore replaced:
\/:*?"<>|
The description (with placeholders) of the name to be generated includes special xml characters that cannot simply be written to an .xml file. Therefore, the description has to be enclosed in a CDATA section.
Example
Diagnostics_<date>.pdi has to be changed to <!CDATA[Diagnostics_<date>.pdi]] to be included in the .xml file.
Example of a description of a file name containing special characters, enclosed in a CDATA section.
<?xml version="1.0" encoding="ISO-8859-1" ?>
<config>
<fileoptions>
<autofilesavefilename>
<![CDATA[Diagnostics_<date>.pdi]]
</autofilesavefilename>
</fileoptions>
</config>>
Placeholders are surrounded by angle brackets. They have to be entered manually. The list provides an overview of the possible placeholders:
o<date>
Current date:
Format: yyyy-MM-dd
Examples
1999-12-01
2006-03-21
o<time>
Current time in 24-hour format:
Format: HH-mm-ss
Examples
07-41-29
19-41-29
o<counter>
The counter is an exception. First, it replaces the placeholder <counter> in the file name with a number, starting with 1. For example, this then results in a file name Diagnostics_1.pdi. Then, it verifies whether this file name already exists in the same directory. If it does, it increases the counter by 1 and repeats the process until it finds no file with the same name.
o<username>
Equivalent to User in the Machine info dialog box.
o<machinename>
Equivalent to Machine name in the Machine info dialog box.
o<hardwarecode>
Equivalent to Hardware code of the controller in the Machine info dialog box.
Examples of Calls With Possible Results
|
Call |
Result |
|---|---|
|
Diagnostics_<date>.pdi |
Diagnostics_2006-03-22.pdi |
|
Diagnostics_<date>_<counter>.pdi |
Diagnostics_2006-03-22_1.pdi |
|
Diagnostics_user=<username>_hw=<hardwarecode>_nr=<counter>.pdi |
Diagnostics_user=wsmith_hw=0540010000_nr=1.pdi |
|
Diagnostics_user=<username>_machine=<machinename>_hw=<hardwarecode>_date=<date>_time=<time>_nr=<counter>.pdi |
Diagnostics_user=wsmith_machine=MyMachine_hw=0540010000_date=2006-03-12_time=22-09-13 _nr=1.pdi |
Parameter config/fileoptions/defaultfilesavedirectory
The parameter config/fileoptions/defaultfilesavedirectory defines the default directory that is first shown when a Save as dialog box is opened. It allows you to change the directory and to save the file.
NOTE: When you open the Save as dialog box the next time, the directory defined in <defaultfilesavedirectory> is suggested again.
The following example defines c:\temp\Diagnostics as the default directory:
<?xml version="1.0" encoding="ISO-8859-1" ?>
<config>
<fileoptions>
<defaultfilesavedirectory>
c:\temp\Diagnostics
</defaultfilesavedirectory>
</fileoptions>
</config>>
