mtd16:toText

Converts the contents of msg into printable text.
If specified, the value of tag asks to convert only the data field with the given tag.

The default textual encoding uses numbers (encoded as text) for printing tagged values. This encoding can be parsed back into a valid message by calling mtd16.fromText().

Optionally, a human readable text format can be selected. This format generates symbolic names for tagged values, enums and bitfields by using lookup tables. It is possible to parse this format back, too, under the condition that all lookup tables have been set up properly so all tagged values in the text string can be found.

Each character in the string flags modifies the output format:

• 'N': Use names instead of numeric codes for all tag values, enum values and bitfields. The numeric codes are picked from the lookup tables in the global variable mtd16 (See below).
• 'H': Use hungarian notation: Prefix tag names with a short descriptor of the datatype (e.g. 'i' for Integer, 'dt' for DateTime, etc...) Only useful together with N, otherwise ignored.
• 'I': Put each tagged field onto it's own line. Indent by two spaces times the nesting level.
• 'F': Filter the output using the table mtd16.filterTrace. The result will most likely be no longer parseable by mtd16.fromText()!

Lookup tables ('N' option)

For each tag inside the message the function does a reverse lookup into mtd16.lutTag. If successful, the name is, if selected with the 'H' option, additionally decorated with the data type of the contents. If unsuccessful, the tag is generated in hexadecimal form.

For Integer values: If the first lookup provided a name and a lookup table mtd16.lutName exists, the value of the field is looked up reverse in that table. When successful, the printed value is replaced by the value found in the lookup table.

For Integer and BitArray values: If the first lookup provided a name and a lookup table mtd16.lutBitName exists, each set bit in the data value is taken separately and run as a reverse lookup through that table. For each successful lookup, the string key is insted added to the output. If multiple bits are set, the names are concatenated with the '|' character. Any remaining bits not in the lookup table are added, too, also with a '|' character as required.

Filtering ('F' option)

The 'F' option looks for a table named mtd16.filterTrace. For each tag a lookup is made into the table, using the numeric code of the tag. If a function is found, it is called as f(messageCode, tag, value, subMessageCode).

Here messageCode is the tag of the containing message, tag is the tag of the item being filtered and data is the contents of the item. Finally, if the item is nested, then subMessageCode contains the tag of the nested message. Without nesting it is the same as messageCode.

When the function returns non-nil, the function result is printed instead of the actual value. This is useful if sensitive data must be hidden from debug, e.g. passwords and keys.