Home Contents | # mtd16:trace | Mtd16 | Core4 Lua Commands

## SYNOPSIS

text = msg:trace()

## DESCRIPTION

The trace() command converts msg into human readable text useful for debugging. It makes use of the various lookup tables like mtd16.lutTag and others to generate useful output. Tag names are prefixed with an indicator of their type.

Calling a message in string context will automatically call the trace() function.

### Lookup tables

For each tag inside the message the trace function does a reverse lookup into mtd16.lutTag. If successful, the name is decorated with the data type of the contents and printed. If unsuccessful, the tag is printed hexadecimal, prefixed with 0x.

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.

### Filtering

If a table named mtd16.filterTrace exists, each tag is looked for in that table. 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.

## RETURN VALUE

A human readable string representation of msg.

## NOTES

The output of this function is meant for human consumption. Do not automatically process this text. If you need machine readable text, use mtd16:toText().

## EXAMPLE

Note how 1 is replaced by busy due to mtd16.lutFnord.

> > > > > >
mtd16.lutTag = { Test = 0xF00F, Fnord = 0x3001, State=0x1001 } mtd16.lutState = { idle = 0, busy = 1 } msg = mtd16.new("Test") msg:append("Fnord", "xyzzy") msg:append("State", 1) print(msg)
msgTest=(sFnord="xyzzy" iState=busy)

## SEE ALSO

#mtd16, mtd16.answerCode, mtd16.fromData, mtd16.fromText, mtd16.isNestedTag, mtd16.lutType, mtd16.new, mtd16.tagCode, mtd16.tagName, mtd16.tagNumber, mtd16.tagType, mtd16:append, mtd16:appendMessageCode, mtd16:contains, mtd16:get, mtd16:getNumber, mtd16:getString, mtd16:isEmpty, mtd16:isValid, mtd16:messageCode, mtd16:nextMessageCode, mtd16:pairs, mtd16:rewind, mtd16:tags, mtd16:toData, mtd16:toText