Runtime components : Core components : Formatters : Concepts : Built-in FormatElements
  
Built-in FormatElements
The structure of formatter definition mirrors the structure of the corresponding data. In the structure of data, there are data field, and composite of data fields. Accordingly, there are field format element and composite format element in the structure of formatter definition.
Following is an example of the formatter definition:
<format.xml>
  <format id="PersonFormat">
    <record>
      <fString dataName="name" encoding="cp937"/>
      <selfLength/>
      <fInteger dataName="age" byteOrdering="host"/>
      <selfLength/>
    </record>
  </format>
</format.xml>
Where:
▪ <fString> and <fInteger> are field format elements
▪ <selfLength> is a kind of format decorator
▪ <record> is a kind of composite format element
In this example, each tag is instantiated as a formatter element that can format or unformat the corresponding data element.
Generally speaking, there are three kinds of format element: composite format element, field format element and format decorator.
Following are the component initializing parameters for all the built-in format elements:
<?xml version="1.0"?>
<btt.xml>
  <kColl id="components">
    <kColl id="format">
      <field id="initializer"
             value="com.ibm.btt.format.FormatInitializer" />
      <field id="extFile" value="format.xml" />
      <kColl id="classTable">
        <field id="record" value="com.ibm.btt.format.impl.RecordFormat" />
        <field id="indexed" value="com.ibm.btt.format.impl.IndexedFormat" />
        <field id="fString" value="com.ibm.btt.format.impl.StringFormat" />
        <field id="fInteger" value="com.ibm.btt.format.impl.IntegerFormat" />
        <field id="fFloat" value="com.ibm.btt.format.impl.FloatFormat" />
        <field id="fPacked" value="com.ibm.btt.format.impl.PackedFormat" />
        <field id="fPackedDate" value="com.ibm.btt.format.impl.PackedDateFormat" />
        <field id="hexDelim" value="com.ibm.btt.format.impl.HexDelimiter" />
        <field id="fixedLength" value="com.ibm.btt.format.impl.FixedLength" />
        <field id="maxLength" value="com.ibm.btt.format.impl.MaximumLength" />
        <field id="nullCheck" value="com.ibm.btt.format.impl.NullCheckeDecorator" />
        <field id="selfLength" value="com.ibm.btt.format.impl.SelfLength" />
        <field id="format" value="com.ibm.btt.format.impl.FormatDefine" />
        <field id="refFmt" value="com.ibm.btt.format.impl.ReferenceFormat" />
      </kColl>
    </kColl>
  </kColl>
</btt.xml>
See
Composite format element
Field Format Element
Format Decorator
Special Format Element
See also
Concepts
Composite format element
Every composite format element is a subclass of com.ibm.btt.format.CompositeFormat. The classes listed below are all in package com.ibm.btt.format.impl.
RecordFormat
(Format/unformat a composite of data fields.)
<record>
  <fString dataName="name"/>
  <fInteger dataName="age"/>
</record>
Attributes
N/A
IndexedFormat
(Format/unformat an indexed composite of data fields. For example java.util.List)
<indexed dataName="ilist" elementType="java.lang.String">
  <fString dataName="CURSOR"/>
  <fHexDelim hexDelimCharStr="FE" />
</indexted>
Attributes
times
The size of indexed composite data. It can be a int value or “*”
elementType
If the structrued data is java object, you must specify the type of element in the list.
XMLFormat
(Format/unformat a XML structured string)
<fmtDef id="stockFmt">
  <fXML dataName="stockCtxData">
    <fString dataName="code" />
    <fString dataName="price" />
  </fXML>
</fmtDef>
Attributes
N/A
JSONFormat
(Format/unformat JSON structured string)
<fJSON id="JSONChannelFormatter">
  <record dataName="json_request">
    <fString dataName="action" />
    <fString dataName="data_formatter" />
    <fString dataName="response_formatter" />
    <fString dataName="data" escape="true" />
  </record>
</fJSON>
Attributes
N/A
See also
Built-in FormatElements
Field Format Element
Every field format element is a subclass of com.ibm.btt.format.FieldFormat. Because there are different types of data field, there are different kinds of field format element accordingly. The attributes of field format element customizes their behavior in the formatting and unformatting process. The classes listed in the following table are all in the package com.ibm.btt.format.impl.
Classes, Attributes and sample definitions of Field Format Element
 
ClassSample definition
Attributes
StringFormat
(Format/unformat a data field which is in type of java.lang.String)
<fString dataName="name" encoding="cp937"/>
encoding:
the encoding of string. If not specified, uses default encoding of java system.
formatAs: optional values are: lowercase,uppercase and nocasecast. default value is nocasecast.
unformatAs: optional values are: lowercase,uppercase and nocasecast. default value is nocasecast.
IntegerFormat
(Format/unformat a data field which is in type of byte, short, int or long)
<fInteger dataName="dInt" size="int" byteOrdering="pc"/>
For example, if you format an integer value of -1024 with this format element, you will get the binary message: 00FCFFFF (hex value).
If you unformat a binary message 00FCFFFF with this format element, you will get an integer value of -1024.
size:
optional values are: 1(byte), 2(short), 4(int), 8(long). default value is 4.
byteOrdering:
optional values are: pc(little-endian) and host(big-endian). default value is pc.
signRule:
optional values are: yes, no. default value is yes.
FloatFormat
(Format/unformat a data field which is in type of float or double)
<fFloat dataName="dFloat" size="float" byteOrdering="host"/>
For example, if you format a float value of -1024.5, you will get the binary message: C4801000 (hex value). If you unformat a binary message C4801000 with this format element, you will get a float value of -1024.5
size:
optional values are: 4(float), 8(double) default value is 4.
byteOrdering:
optional values are: pc(little-endian) and host(big-endian). default value is pc.
PackedFormat
(Format/unformat a data field which is in type of float/double/integer/long, target message is byte representation of the data field)
<fPacked dataName="dDouble" decPlaces="2" type="double"/>
For example, if you format a double value of -1024.5 with this format element, you will get the binary message: 0102450D (hex value).
decPlaces:
an integer value which is >=0 default value is 0.
signed:
optional values are: yes, no default value is: yes
type:
optional values are: float, double, int, long default value is: int
PackedDateFormat
(Format/unformat a data field which is in type of Date)
<fPackedDate dataName="aDate" />
For example, if you format a Date value of Fri Apr 24 10:00:00 GMT+03:00 1998, you will get the binary message: 240498 (hex value).
N/A
See also
Built-in FormatElements
Format Decorator
Formatter decorator follows the DECORATOR design pattern. You can add decorators for each format element. The decorator needs to be defined right after the format element. Every Format Decorator is a subclass of com.ibm.btt.format.BaseDecorator.
Following is a sample definition:
<format.xml>
  <format id="PersonFormat">
    <record>
      <fString dataName="name" encoding="cp937"/>
      <selfLength/>
      <fInteger dataName="age" byteOrdering="host"/>
      <selfLength/>
    </record>
  </format>
</format.xml>
Where, selfLength is a decorator. The first selfLength is decorator for fString. The second selfLenght is decorator for fInteger.
Decorator is used modify the binary message formatted by decorated format element and modify the binary message before the decorated format element unformat it.
Classes, Attributes and sample definitions of Format Decorator
 
ClassSample definition
Attributes
HexDelimiter
(Add a delimiter after the binary message)
<fInteger dataName="dInt" size="int" byteOrdering="pc"/>
<hexDelim hexDelimCharStr="DDDD" />
For example, if you format an integer value of -1024 with this format element, you will get the binary message: 00FCFFFFDDDD (hex value).
hexDelimCharStr:
a String that represents an array of hex values.
FixedLength
(Adjusts a formatted binary message to a fixed length by either truncating it or by padding and justifying it)
<fString dataName="name" encoding="cp937"/>
<fixedLength length="10" alignment="right"/>
For example, if you format a String “George” with this format element, you will get the binary message: 00000000C78596998785 (hex value). If you format a String “George. Wilhelm. T” with this format element, you will get the binary message: C785969987854B40E689 (hex value).
length:
an int value that indicates the length of the binary message.
default value is: 0.
padByte:
a byte in hex value representation. default value is: 00.
alignment:
optional values are: left, right.
default value is: left
MaximumLength
(Truncates the binary message if it is over the specified length. If the binary message is under the specified length, the decorator does not modify it)
<fString dataName="name" encoding="cp937"/>
<maxLength length="10"/>
For example, if you format a String “George. Wilhelm. T” with this format element, you will get the binary message: C785969987854B40E689 (hex value).
length:
a int value that indicates the maximum length of the binary message. default value is: 0.
NullCheckDecorator
(Handles conversions between binary message and data field when either the binary message is empty or the data field is null)
<fString dataName="name" encoding="cp937"/>
<nullCheck/>
For example, if you format a String which is null with this format element, you will get a binary message in 0 length. And if you unformat a binary message in 0 length, the format element will make no modification to the data field.
N/A
SelfLength
(Prefixes the length of the formatted binary message as an unsigned integer)
<fString dataName="name" encoding="cp937"/>
<selfLength/>
For example, if you format a String “George. Wilhelm. T”, you will get the binary message: 12C785969987854B40E68993888593944B40E3 (hex value).
size:
the length of prefix. default value is 1.
byteOrdering:
the byte ordering of prefix. optional values are: host, pc.
default value is: pc.
lengthIncluded:
whether to include the length of prefix when calculating the length of binary message. Optional values are: yes, no Default value is: no.
See also
Built-in FormatElements
Special Format Element
There are two format elements that do not extend CompositeFormat, FieldFormat or BaseDecorator. The special Format Element implements are com.ibm.btt.format.impl.FormatDefine and com.ibm.btt.format.impl.ReferenceFormat. They implement com.ibm.btt.format.FormatElement directly.
Classes, attributes and sample definitions
 
ClassSample definition
Attributes
FormatDefine
(used as a root format element in the format definition)
<format id="PersonFormat">
  <record>
    <fString dataName="name" encoding="cp937"/>
     <selfLength/>
       <fInteger dataName="age" byteOrdering="host"/>
     <selfLength/>
  </record>
</format>
id:
a String that represents the id of the format definition.
ReferenceFormat
(handles the reference relationship between format definitions)
<format id="AnotherFormat">
  <record>
    <fString dataName="field1" encoding="cp937"/>
    <selfLength/>
      <refFmt dataName="field2" refId="PersonFormat"/>
    <selfLength/>
  </record>
</format>
refId:
a String that represents the id of the referenced format element.
See also
Built-in FormatElements