Mapping Definition

For each of the output port attributes, specify the structure and field that will feed the attribute. Structures that are detected in the binary data stream but that do not have specified mapping information do not generate output tuples.

Mapping is type-restrictive. In other words, the output port attribute type must be identical to the field type that is specified in the structure document.

If several mapping rules exist for an attribute and structure combination, the field cannot be predicted. In the following example, the SPL attribute RECORD_NUMBER either contains RecordNumber or RecordNumber2 from structure A:

<attribute name="RECORD_NUMBER">
	<from structure="A" field="RecordNumber"/>
	<from structure="A" field="RecordNumber2"/>
</attribute>

Ways to specify a mapping

If a field name is identical to the SPL attribute name, specify only the attribute name, for example:

<attribute name="RECORD_NUMBER"/>

If a field name is different from the SPL attribute name, specify the field name that should be mapped to the SPL attribute by using the <from/> XML element, for example:

<attribute name="RECORD_NUMBER">
	<from field="RecordNumber"/>
</attribute>

If a field name is identical to the SPL attribute name and if a subset of the structures will be mapped, specify the structure name by using the <from/> XML element. The structure name can be a fixed name or a regular expression in Perl style. If, for example, the event_0, event_1, submit_0, and submit_1 structures are specified in the structure definition document and if all structures have a RECORD_TYPE field, the following sample mapping selects the RECORD_TYPE fields of the submit_0 and submit_1 structures only:

<attribute name="RECORD_TYPE">
	<from structure="^submit_\d*$"/>
</attribute>

If a field name is different from the SPL attribute name and if a subset of the structures will be mapped, specify the field and the structure name by using the <from/> XML element, for example:

<attribute name="RECORD_TYPE">
	<from structure="submit_0" field="RecordType"/>
</attribute>

If fields from several structures should be mapped to an SPL attribute and if the field names are different for each structure, specify the mapping for each structure by using several <from/> XML elements, for example:

<attribute name="RECORD_TYPE">
	<from structure="submit_0" field="RecordType"/>
	<from structure="event_1" field="AnotherField"/>
</attribute>

If integer and floating point values should be converted to rstring values, specify the conversion using the XML <toString> element. For example, in the structure definition file, the event_0, event_1, submit_0, and submit_1 structures are specified. All structures have the RECORD_TYPE_AS_UINT16 field, which is uint16 type. The output port schema has the RECORD_LENGTH SPL attribute, which is of rstring type. Code that converts the uint16 value into an rstring value is generated:

<attribute name="RECORD_LENGTH">
	<from structure="^submit_\d*$" field="RECORD_LENGTH_AS_UINT16">
		<toString/>
	</from>
</attribute>

The <toString> XML element supports following XML attributes to format the output:

base

The field value is represented as a decimal (dec), hexadecimal (hex), or octal (oct) number. The default is a decimal representation.

width

The minimum number of characters to be printed. If the value to be printed is less than this number, the result is left-padded with blank spaces. If the result contains more characters, the value is not truncated. For example, if the integer value is 123 and you specify a width of 5, you get " 123". If you specify a width of 2, you get the not-truncated "123" value.

precision

For integers, the minimum number of digits to be written. A precision of 0 means that no characters are written for the value 0. If the value is shorter, the result is padded with leading zeros. If the result contains more characters, the value is not truncated.

For floating point values, this attribute specifies number of digits to be printed after the decimal point. The default value is 6.

showbase

If true, the number-to-string conversion adds a preceding number system identifier (0 for the octal number system, 0x for the hexadecimal number system). For more information, see the base attribute.

For example, <toString base="hex" showbase="true"/> converts 67 into 0x43, and <toString base="oct" showbase="true"/> converts the same value into 0103.

fill

A single character that is used for padding (see width) instead of blank spaces.

For example, the record length (name="RECORD_LENGTH") is represented with four hexadecimal digits (width="4"), leading 0x (showbase="true") and leading zeros (fill="0"). A decimal input value of 31 is converted into 0x001F, for example:

<attribute name="RECORD_LENGTH">
	<from structure="^submit_\d*$" field="RECORD_LENGTH_AS_UINT16">
		<toString base="hex" showbase="true" width="4" fill="0"/>
	</from>
</attribute>