Building Format Definitions

 

The following sections provide information on building format definitions using the Format Builder included with BEA WebLogic XML/Non-XML Translator (hereafter referred to as XML Translator):

• Understanding the Data Formats Used with XML Translator

• Analyzing the Data to be Translated

• Using the Format Builder

The Format Builder included with XML Translator allows users to build format definitions for binary data that will be translated to or from XML. Format definitions are the metadata used to parse or create binary data.

 

---

Understanding the Data Formats Used with XML Translator

To understand how the Format Builder is used, it helps to understand the data formats used by XML Translator: binary data, XML, MFL, DTD and Schema.

About Binary Data (Non-XML Data)

Because computers are based on the binary numbering system, applications often use a binary format to represent data. A file stored in binary format is computer-readable but not necessarily human-readable. Binary formats are used for executable programs and numeric data, and text formats are used for textual data. Many files contain a combination of binary and text formats. Such files are usually considered to be binary files even though they contain some data in a text format.

Unlike XML data, binary data is not self-describing. In other words, binary data does not provide a description of how the data is grouped, divided into fields, or arranged in a layout. Binary data is a sequence of bytes that can be interpreted as an integer, a string, or a picture, depending on the intent of the application that generates the sequence of bytes. In order for binary data to be understood by an application, the layout must be embedded within each application that uses this data. Binary data may also be embedded using different character sets. For example, character data on an IBM mainframe is usually encoded using the EBCDIC character set while data from a desktop computer is either ASCII or unicode.

The Format Builder is used to create a Message Format Language (MFL) file that describes the layout of the binary data. MFL is an XML language that includes elements to describe each field of data, as well as groupings of fields (groups), repetition, and aggregation. The hierarchy of a binary record, the layout of fields, and the grouping of fields and groups are expressed in an MFL document. This MFL document is used by XML Translator at run-time to translate the data to and from an XML document.

Listing 2-1 Example of Binary Data

1234;88844321;SUP:21Sprockley's Sprockets01/15/2000123 Main St.; Austin;TX;75222;555 State St.;Austin;TX;75222;PO12345678;666123;150;Red Sprocket;

About XML Documents

Extended Markup Language, or XML, is a text format for exchanging data between different systems. It allows data to be described in a simple, standard, text-only format. In contrast to binary data, XML data embeds a description of the data within the data stream. Applications can share data more easily, since they are not dependent on the layout of the data being embedded within each application. Since the data is presented in a standard form, applications on disparate systems can interpret the data using XML parsing tools, instead of having to interpret data in proprietary binary formats.

Instances of XML documents contain character data and markup. The character data is referred to as content, while the markup provides hierarchy for that content. Markup is distinguished from text by angle brackets. Information in the space between the "<" and the ">" is referred to as the tags that markup the content. Tags provide an indication of what the content is for, and a mechanism to describe parent-child relationships. Listing 2-2 shows an example of an XML document.

Listing 2-2 Example of XML Document

<?xml version="1.0"?>
<PurchaseRequest>
 <PR_Number>1234</PR_Number>
 <Supplier_ID>88844321</Supplier_ID>
  <Supplier_Name>Sprockley&apos;s Sprockets</Supplier_Name>
  <Requested_Delivery_Date>2000-01-15T00:00:00:000</Requested_Delivery_Date>
  <Shipping_Address>
    <Address>
      <Street>123 Main St.</Street>
      <City>Austin</City>
      <State>TX</State>
      <Zip>75222</Zip>
    </Address>
  </Shipping_Address>
  </PurchaseRequest>

An XML document can conform to a content model. A content model allows Metadata about XML documents to be communicated to an XML parser. XML documents are said to be "valid" if they conform to a content model. A content model describes the data that can exist in an instance of an XML document. A content model also describes a top-level entity, which is a sequence of subordinate entities. These subordinate entities are further described by their tag names and data content. The two standard formats for XML content models are XML Document Type Definition (DTD) and XML Schema. A Schema is an XML document that defines what can be in an XML document. A DTD also defines what content can exist in an XML document, but the Schema definition is more specific than the DTD, and provides much finer-grained control over the content that can exist in an XML document.

Listing 2-3 shows an example of a Document Type Definition. Listing 2-4 shows an example of an XML Schema.

Listing 2-3 Example DTD

<!ELEMENT PurchaseRequest (PR_Number,Supplier_ID,Supplier_Name?,Requested_Delivery_Date,Shipping_Address,Billing_Address,Payment_Terms,Purchase_Items)>
<!ELEMENT PR_Number (#PCDATA) >
<!ATTLIST PR_Number type CDATA #FIXED "nonNegativeInteger">
<!ELEMENT Supplier_ID (#PCDATA) >
<!ATTLIST Supplier_ID type CDATA #FIXED "nonNegativeInteger">
<!ELEMENT Supplier_Name (#PCDATA) >
<!ATTLIST Supplier_Name type CDATA #FIXED "string">
<!ELEMENT Requested_Delivery_Date (#PCDATA) >
<!ATTLIST Requested_Delivery_Date type CDATA #FIXED "timeInstant">
<!ELEMENT Shipping_Address (Address)>
<!ELEMENT Address (Street,City,State,Zip)>
<!ELEMENT Street (#PCDATA) >
<!ATTLIST Street type CDATA #FIXED "string">
<!ELEMENT City (#PCDATA) >
<!ATTLIST City type CDATA #FIXED "string">
<!ELEMENT State (#PCDATA) >
<!ATTLIST State type CDATA #FIXED "string">
<!ELEMENT Zip (#PCDATA) >
<!ATTLIST Zip type CDATA #FIXED "nonNegativeInteger">

Listing 2-4 Example XML Schema

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/1999/XMLSchema">
<xsd:annotation>
	<xsd:documentation>
		This schema created for MFL MessageFormat PurchaseRequest.
	</xsd:documentation>
</xsd:annotation>

<xsd:element name="PurchaseRequest">
<xsd:complexType content="elementOnly">
<xsd:sequence>
	<xsd:element ref="PR_Number" minOccurs="1" maxOccurs="1"/>
	<xsd:element ref="Supplier_ID" minOccurs="1" maxOccurs="1"/>
	<xsd:element ref="Supplier_Name" minOccurs="0" maxOccurs="1"/>
	<xsd:element ref="Requested_Delivery_Date" minOccurs="1" maxOccurs="1"/>
	<xsd:element ref="Shipping_Address" minOccurs="1" maxOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="PR_Number" type="xsd:nonNegativeInteger"/>

<xsd:element name="Supplier_ID" type="xsd:nonNegativeInteger"/>

<xsd:element name="Supplier_Name" type="xsd:string"/>

<xsd:element name="Requested_Delivery_Date" type="xsd:timeInstant"/>

<xsd:element name="Shipping_Address">
<xsd:complexType content="elementOnly">
<xsd:sequence>
	<xsd:element ref="Address" minOccurs="1" maxOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

</xsd:schema>

About MFL Documents

Message Format Language (MFL) is an XML language that describes the layout of binary data. This language includes elements to describe each field of data, as well as groupings of fields (groups), repetition, and aggregation. The hierarchy of a binary record, the layout of fields, and the grouping of fields and groups is expressed in an MFL document. MFL documents are created using Format Builder. These MFL documents are then used to perform run-time translation. MFL documents are created for you when you define and save definitions from within Format Builder.

The MFL documents you create using Format Builder can contain the following elements:

• Message Format - The top level element. Defines the message name and MFL version.

• Field - Sequence of bytes that have some meaning to an application. (For example, the field EMPNAME contains an employee name.) Defines the formatting for the field. The formatting parameters you can define include:

  • Tagged - Indicates that a literal precedes the data field, denoting the beginning of the field.

  • Length - Indicates that a length value precedes the data field, denoting the length of this field.

  • Occurrence - Repeating fields appear more than once in the message format. You can set a specific number of times the field is to repeat, or define a delimiter to indicate the end of the repeating field.

  • Optional- The field may or may not be present in the named message format.

• Groups - Collections of fields, comments, and other groups or references that are related in some way (for example, the fields PAYDATE, HOURS, and RATE could be part of the PAYINFO group). The parameters you can define include:

  • Occurrence - Repeating groups appear more than once in the message format: You can set a specific number of times the group is to repeat, or define a delimiter to indicate the end of the repeating group.

  • Choice of Children - Defining a group as "Choice of Children" means that only one item in the group will appear in the message format.

  • Optional- The group of data within this structure may or may not be present in the named message format.

• References - Indicates that another instance of the field or group format exists in the data. Reference fields or groups have the same format as the original field or group, but you can change the optional setting and the occurrence setting for the reference field or group. For example, if you have a "bill to" address and a "ship to" address in your data, you only need to define the address format once. You can create the "bill to" address definition and create a reference for the "ship to" address.

• Comments - Notes or additional information about the message format.

 

---

Analyzing the Data to be Translated

Before a message format can be created, the layout of the binary data must be understood. Legacy purchase order sample data and corresponding MFL and XML documents for a purchase order record are included on the XML Translator CD-ROM. The sample purchase order illustrates how XML Translator translates data from one format to another. For more information on this sample data, refer to the BEA WebLogic XML/Non-XML Translator Samples Guide.

The key to translating binary data to and from XML is to create an accurate description of the binary data. For binary data (data that is not self-describing), you must identify the following elements:

• Hierarchical groups

• Group attributes, such as name, optional, repeating, delimited

• Data fields

• Data field attributes, such as name, data type, length/termination, optional, repeating

The Format Builder (the design-time portion of XML Translator) is used to build the format definitions that are used for data translations. For details on the steps you need to perform to thoroughly analyze your data, refer to the BEA WebLogic XML/Non-XML Translator Samples Guide.

 

---

Using the Format Builder

Format Builder assists you in creating format descriptions for binary data. You use Format Builder to create hierarchical and detail information derived from structural and detailed analysis of your data. These format descriptions are stored in an MFL document. You can also use Format Builder to test your format descriptions before you apply them to your actual data.

Starting Format Builder

To start Format Builder, choose Start-->Programs-->BEA WebLogic E-Business Platform-->Format Builder. The Format Builder main window displays. If you did not use the installation directory defaults, your path may be different.

Using the Format Builder Main Window

The main window of Format Builder is split into two panes. The left pane (the Tree Pane) shows the structural information for the data format. The right pane (the Properties Pane) shows the detail for the item selected in the tree pane.

Figure 2-1 Format Builder Main Window

The structure of the binary data is defined in the tree pane using a combination of fields and groups that match the target data.

The following topics discuss the parts of the main window and provide instructions for navigating and executing commands from the main window of Format Builder:

• Using the Tree Pane

• Using the Menu Bar

• Using the Toolbar

• Using Drag and Drop

• Using the Shortcut Menus

Using the Tree Pane

The Tree Pane represents hierarchical/structural information about the format of the binary data in a tree. The root node of the tree will correspond to the MFL document being created or edited. The root node is referred to as the Message node. Child nodes are labeled with group or field names. Fields are represented by leaf nodes in the tree. Groups contain fields or other groups and are represented by non-leaf nodes in the tree.

The icon for each node encapsulates information about the node. The icon indicates whether the node represents a message, a group, a field, a comment, or a reference. The icon also indicates whether a group or field is repeating, whether a group is a "Choice of Children", and whether a group or field is optional or mandatory. You also have the ability to add, delete, move, copy, or rename nodes in the tree. This is done through the menus or the toolbar (see Using the Menu Bar and Using the Toolbar).

The icons that appear in the Tree Pane are described in the following table.

Table 2-1 Tree Icon Descriptions

Tree Icon	Icon Name	Description
	Message Format	The top level element.
	Group	Collections of fields, comments, and other groups or references that are related in some way (for example, the fields PAYDATE, HOURS, and RATE could be part of the PAYINFO group). Defines the formatting for all items contained in the group.
	Optional Group	A group that has 0 or more occurrences.
	Repeating Group	A group that has one or more occurrences.
	Optional Repeating Group	May or may not be included, but if included, more than one will occur.
	Group Reference	Indicates that another instance of the group exists in the data. Reference groups have the same format as the original group, but you can change the optional setting and the occurrence setting for the reference group.
	Group Choice	Choose Choice of Children if only one of the items in the group will be included in the message format.
	Field	Sequence of bytes that have some meaning to an application. (For example, the field EMPNAME contains an employee name.) Defines the formatting for the field.
	Optional Field	A field that may or may not be present.
	Repeating Field	A field that has one or more occurrences.
	Field Reference	Indicates that another instance of the field exists in the data. Reference fields have the same format as the original field, but you can change the optional setting and the occurrence setting for the reference field.
	Optional Repeating Field	A field that has 0 or more occurrences.
	Comment	Contains notes about the message format or the data translated by the message format.
	Collapse	A minus sign next to an object indicates that it can be collapsed.
	Expand	A plus sign next an object indicates that it can be expanded to show more objects.

Using the Menu Bar

The Menu bar displays the menu headings. The menu items that are available depend on what is selected in the tree pane and the state of the tree. Click a menu heading to open the menu and choose a command.

Figure 2-2 Format Builder Menu Bar

Note: Menu items that appear in gray are unavailable for the current selection.

For a complete description of the menu commands, see Format Builder Menus.

Using the Toolbar

The toolbar provides buttons that access some of the frequently used commands in the menus. To activate a command, click its toolbar button. If a command is unavailable, its button appears "grayed-out."

Figure 2-3 Format Builder Toolbar

The toolbar buttons provided with Format Builder are described below:

Toolbar Button	Name	Description
	New	Creates a new Message Format
	Open	Opens an existing Message Format
	Save	Saves the current Message Format
	Cut	Removes the item currently selected in the left-hand pane, and it's child objects, from the tree. The item can be pasted elsewhere in the tree. Note: This action is not available if the Message Format (root) item is selected.
	Copy	Makes a copy of the item currently selected in the left-hand pane for insertion elsewhere in the tree. Note: This action is not available if the Message Format (root) item is selected.
	Paste as Sibling	Inserts the cut or copied item as a sibling object of the selected item.
	Paste as Reference	Inserts a reference to the cut or copied item as a sibling object of the selected item.
	Undo	Reverses the previous action. The tool tip changes to indicate the action that can be undone. For example, changing the name of a field to Address and clicking Apply causes the tool tip to read "Undo Apply Field Address". Format Builder supports multi-level undoing and redoing.
	Redo	Reverses the effects of an Undo command. The tool tip changes to indicate the action that can be redone. For example, changing the name of a field to Address and then undoing that action causes the tool tip to read "Redo Apply Field Address". Format Builder support multi-level undoing and redoing.
	Insert Field	Inserts a field as a sibling of the item selected in the tree pane.
	Insert Group	Inserts a group as a sibling of the item selected in the tree pane.
	Insert Comment	Inserts a comment as a sibling of the item selected in the tree pane.
	Move Up	Moves the selected item up one position under its parent.
	Move Down	Moves the selected item down one position under its parent.
	Promote item	Promotes the selected item to the next highest level in the tree. For example, Field1 is the child object of Group1. Selecting Field1 and clicking the Promote tool makes it a sibling of Group1.
	Demote item	Demotes the selected item to the next lower level in the tree. For example, Group1 is the sibling of Field1. Field1 immediately follows Group1 in the tree. Selecting Field1 and clicking the Demote tool makes it a child of Group1.
	Expand	Expands all items in the tree pane to show child items.
	Collapse	Collapses the tree pane to show first level items only.

Using the Shortcut Menus

Instead of using the standard menus to find the command you need, use the right mouse button to click an item in the tree pane. The menu that appears shows the most frequently used commands for that item.

The following commands are available from the Shortcut Menus.

Note: Some commands may be unavailable, depending on the item you have selected in the tree, or the state of the tree at the time.

Table 2-2 Shortcut Menus

Menu Command	Description
Cut	Removes the item currently selected in the left-hand pane, and it's child objects, from the tree.
Copy	Makes a copy of the item currently selected in the left-hand pane for insertion elsewhere in the tree.
Paste	Inserts the cut or copied item. An additional menu displays when you select Paste. You can choose to paste the item as a child or sibling of the selected item. In addition, you can choose to paste a reference to the cut or copied item as a sibling of the selected item.
Insert Group	Inserts a new group. You select whether to insert the group as a child or sibling of the selected item.
Insert Field	Inserts a new field. You select whether to insert the field as a child or sibling of the selected item.
Insert Comment	Inserts a comment. You select whether to insert the comment as a child or sibling of the selected item.
Duplicate	Makes a copy of the currently selected item. The duplicate item contains the same values as the original item. The name of the duplicate item is the same as the original item name, with the word "New" inserted before the original name. For example, duplicating a group called "Group1" results in a group with the name "NewGroup1". When you duplicate an item with a numeric value in its name, the new item name contains the next sequential number. For example, duplicating "NewGroup1" results in a group named "NewGroup2".
Delete	Deletes the selected item.

Using Drag and Drop

You can use the drag and drop feature of XML Translator to copy and/or move the items in the tree pane.

Note: The node being copied or moved is always inserted as a sibling of the selected node during the drag and drop process.

To use drag and drop to move an item:

1. Select the item you want to move.

2. Press and hold the left mouse button while you drag the item to the desired node.

3. When the item is in the desired location, release the left mouse button. The item is moved to the new location.

To use drag and drop to copy an item:

1. Select the item you want to copy.

2. Press and hold the CTRL key.

3. Keeping the CTRL key depressed, press and hold the left mouse button while you drag the item to the desired node.

4. With the sibling object selected, release the left mouse button. A copy of the item is placed at the new location.

Creating a Message Format

The first step in creating a Message Format Definition file is to create a message format (the root node of a message format file).

To create a message format:

1. Choose File-->New. The Message Format Pane displays in the detail window.

   Figure 2-4 Message Format Properties

   

2. Enter data in the fields as described in the following table.

   Note: The previous example and the examples that follow are based on MFL version 2.0 documents.

   Table 2-3 Message Format Properties

   Field	Description
   Message Format Properties
   Name	The name of the message format. This value will be used as the root element in the translated XML document. This name must comply with XML element naming conventions.
   Version	The version of MFL you are using. Version 1.0 of MFL was introduced with BEA eLink Information Integrator. Format Builder adds new features, and its default version is 2.0.
   Apply	Saves your changes to the message format document.
   Reset	Discards your changes to the detail window and resets all fields to the last saved values.

Valid Names

Message Formats, Fields, and Groups are identified by a Name. The name that is specified is used as the XML tag when binary data is translated to XML by XML Translator. Thus the name must conform to the XML rules for a name.

The rules for names are as follows:

• Must start with a letter or underscore

• Can contain letters, digits, the period character, the hyphen character, or the underscore character.

The following are valid name examples:

MyField
MyField1
MyField_again
MyField-again

The following are invalid name examples:

1MyField - may not start with a digit
My>Field - the greater-than sign (>) is an illegal character
My Field - a space is not permitted

Creating a Group

Groups are collections of fields, comments, references and other groups that are related in some way (for example, the fields PAYDATE, HOURS, and RATE could be part of the PAYINFO group). You can create a group as a child of the message format item, as a child of another group, or as a sibling of a group or field.

To create a group:

1. Select an item in the tree pane.

2. Choose Insert-->Group-->As Child if you want to create the group as the child of the message format or another group. Choose Insert-->Group-->As Sibling if you want to create the group as the sibling of another group or a field. The Group Details display in the detail window.

   Figure 2-5 Group Details

   

3. Enter data in the fields as described in the following table.

   Note: The following example applies to MFL version 2.0.

   Field	Description
   Group Description
   Name	The name of the group. This name must comply with XML element naming conventions.
   Optional	Choose Optional if this is an optional group.
   Choice of Children	Choose Choice of Children if only one of the items in the group will be included in the message format.
   Group Occurrence
   Occurrence	Choose one of the following to indicate how often this group appears in the message format: Once - Indicates the group appears only once. Repeat Delimiter - Indicates the group will repeat until the specified delimiter is encountered. Repeat Field - Indicates the group will repeat the number of times specified in the field denoted as the repeat field. Repeat Number - Indicates the group will repeat the specified number of times. Unlimited - Indicates the group ill repeat an unlimited number of times. Note: Unless a group is defined as Optional, all groups occur at least once.
   Group Delimiter
   Delimited	Select this option if the end of the group is marked with a delimiter. A delimiter identifies the end of a group of fields. Note: Normally, groups are not delimited. They are usually parsed by content (the group ends when all child objects have been parsed).
   Delimiter is Shared	Indicates that the delimiter marks both the end of the group of data, and the end of the last field of the group. The delimiter is shared among the group and the last field of the group, to delimit the end of the data.
   Delimiter Tab	Groups can have their termination point specified by a delimiter. A delimiter is a string of characters that marks the end of the group of fields. The group continues until the delimiter characters are encountered. Value - Enter the delimiter that marks the end of the group of fields.
   Delimiter Field Tab	Groups can have their termination point specified by a field that contains a delimiter character string. A delimiter is a string of characters that mark the end of the group. The group continues until the delimiter character string contained in the specified field is encountered. Field - Select the field that contains the delimiter character string. A list of valid fields will be presented in a drop-down list. Default - Enter the default delimiter character that will be used if the above field is not present in the data. This value is required.
   Group Update Buttons
   Apply	Saves your changes to the message format document.
   Duplicate	Makes a copy of the group currently displayed. The duplicate group contains the same values as the original group. The name of the duplicate group is the same as the original group name, with the word "New" inserted before the original name. For example, duplicating a group called "Group1" results in a group with the name "NewGroup1". When you duplicate an item with a numeric value in its name, the new item name contains the next sequential number. For example, duplicating "NewGroup1" results in a group named "NewGroup2".
   Reset	Discards your changes to the detail window and resets all fields to the last saved values.

Creating a Field

Fields are a sequence of bytes that have some meaning to an application. (For example, the field EMPNAME contains an employee name.) You can create a field as a child of the message format item, as a child of a group, or as a sibling of a group or another field. The field name is used as the element name in the XML document and must comply with XML naming conventions.

To create a field:

1. Select an item in the tree pane.

2. Choose Insert-->Field-->As Child if you want to create the field as the child of the message format or group. Choose Insert-->Field-->As Sibling if you want to create the field as the sibling of another field or a group. The Field Details display in the detail window.

   Figure 2-6 Field Details

   

3. Enter data in the fields as described in the following table.

   Note: The following example applies to MFL version 2.0.

   Field	Description
   Field Description
   Name	The name of the field. This name must comply with XML element naming conventions. Refer to Valid Names for more information.
   Optional	Select this option if this is an optional field. Optional means that the data for the field may or may not be present.
   Tagged	Select this option if this is a tagged field. Being tagged means that a literal precedes the data, indicating that the data is present. You must also choose the data type of the tag field from the drop-down list box. For example: SUP:ACME INC, SUP: is the tag. ACME INC is the field data.
   Tag	If you selected the Field is Tagged option, enter the tag here.
   Type	Select the data type of the field from the drop down list. The default is String. Note: The Field Type you select dictates the Field Data Options that appear on the dialog. Refer to Supported Data Types, for a list of data types supported by XML Translator.
   Field Occurrence
   Occurrence	Choose one of the following to indicate how often this field appears in the message format: Once - Indicates the field appears only once. Repeat Delimiter - Indicates the field will repeat until the specified delimiter is encountered. Repeat Field - Indicates the field will repeat the number of times specified in the field denoted as the repeat field. Repeat Number - Indicates the field will repeat the specified number of times. Unlimited - Indicates the field will repeat an unlimited number of times. Note: Unless a field is defined as optional, the field will occur at least one time.
   Note: The fields that display in the following sections of the dialog depend on the Field Type selected.
   Field Data Options
   Data Base Type	If the field is a date or time field, the base type indicates what type of characters (ASCII, EBCDIC, or Numeric) make up the data.
   Year Cutoff	If the field is a date field that has a 2-digit year, the year cutoff allows the 2-digit year to be converted to a 4-digit year. If the 2-digit year is greater than or equal to the year cutoff value, a '19' prefix will be added to the year value. Otherwise a '20' prefix will be used.
   Code Page	The character encoding of the field data.
   Value	The value that appears in a literal field.
   Field Delimiter (Termination)
   Length Tab	Variable-size data types can have their length specified by a specific length value. Value - Enter the length of the field data.
   Delimiter Tab	Variable-sized data types can have their termination point specified by a delimiter. A delimiter is a character that marks the end of the field. The field data continues until the delimiter character is encountered. Value - Enter the delimiter that marks the end of the field data.
   Length Field Tab	Variable-sized data types can have their termination point specified by a length field. A length field precedes the data field and indicates how many bytes the data contains. Type - Select the type of the length field. Length - Select this option if the length field is a variable length; then, enter the number of bytes in the length field. Delimiter - Select this option if the end of the length field is marked by a delimiter; then, enter the delimiter character. Length Occurs Before Tagged Field - Select this option if the length field should appear before the tag in the data. The default order is tag before length. Note: The Length and Delimiter selection will be disabled if the type of the length field determines its length (see Supported Data Types for more information on field types).
   Delimiter Field Tab	Variable-sized data types can have their termination point specified by a field that contains a delimiter character. A delimiter is a character that marks the end of the field. The field data continues until the field containing the delimiter character is encountered. Field - Select the field that contains the delimiter character. Default - Enter the delimiter character. You must supply a default value. The default is used when the delimiter field is not present.
   Field Update Buttons
   Apply	Saves your changes to the message format file.
   Duplicate	Makes a copy of the field currently displayed. The duplicate field contains the same values as the original field. The name of the duplicate field is the same as the original field name, with the word "New" inserted before the original name. For example, duplicating a field called "Field1" results in a field with the name "NewField1". When you duplicate an item with a numeric value in its name, the new item name contains the next sequential number. For example, duplicating "NewField1" results in a group named "NewField2".
   Reset	Discards your changes to the detail window and resets all fields to the last saved values.

Creating a Comment

Comments contain notes about the message format or the data translated by the message format. Comments are included in the message format definition for documentation and informational purposes only. You can create a comment as a child or sibling of any message format, group, or field. Comments are unnumbered in the MFL document and are not transformed to the XML or Binary data.

Note: Conventionally, the comment usually precedes the node it intends to document.

To create a comment:

1. Select an item in the tree pane.

2. Choose Insert-->Comment-->As Child if you want to create the comment as the child of the selected item. Choose Insert-->Comment-->As Sibling if you want to create the comment as the sibling of the selected item. The Comment Details display in the detail window.

   Figure 2-7 Comment Details

   

3. Enter data in the fields as described in the following table.

   Field	Description
   Comment Details	Enter the comment text.
   Apply	Saves your changes to the message format document.
   Reset	Discards your changes to the detail window and resets all fields to the last saved values.

Creating References

References indicate that the description of the field or group format has been previously defined and you want to reuse this description without re-entering the data. Reference fields or groups have the same format as the original field or group, but you can change only the optional setting and the occurrence setting for the reference field or group. For example, if you have a "bill to" address and a "ship to" address in your data and the format for the address is the same, you only need to define the address format once. You can create the "bill to" address definition and create a reference for the "ship to" address.

Note: References are named exactly the same as the original item. For example, the "bill to" address definition and the "ship to" address definition would be named the same. If you want to reuse a group definition, create a generic group and embed it within a specific group. For example, in the previous example, you can create an address group within a bill_to group and reference address within a ship_to group.

To create a reference:

1. Select a field or group in the tree pane.

2. Choose Edit-->Copy.

3. Choose the proper sibling in the tree.

4. Choose Edit-->Paste-->As Reference.

   Figure 2-8 Reference Details

   

5. Enter data in the fields as described in the following table.

   Field	Description
   Reference Description
   Name	Displays the name of the original field for group for which you created this reference. This value cannot be changed.
   Optional	Select this option if the reference field or group is optional.
   Occurrence
   Occurrence	Choose one of the following to indicate how often this reference field or group appears in the message format: Once - Indicates the reference appears only once. Repeat Delimiter - Indicates the reference will repeat until the specified delimiter is encountered. Repeat Field - Indicates the reference will repeat the number of times specified in the field denoted as the repeat field. Repeat Number - Indicates the reference will repeat the specified number of times. Unlimited - Indicates the reference will repeat an unlimited number of times.
   Field Update Buttons
   Apply	Saves your changes to the message format document.
   Edit Reference	Displays the detail window for the original item so you can edit the details of the referenced field or group.
   Reset	Discards your changes to the detail window and resets all fields to the last saved values.

Working with Pallets

The pallet allows you to store commonly used message format items and insert them into your message format definitions. These items are stored in an MFL document, and you can use the drag and drop feature (see Using Drag and Drop) to copy items from the pallet into your message format definition.

You may reorder or change the hierarchy within the pallets by using drag and drop or the Context menu. The contents of the pallet are automatically saved when you exit Format Builder.

Note: You can only copy items from the tree pane to the pallet and vice versa. You cannot move items between the windows.

The XML Translator pallet contains some common date formats, literals, and strings. You can use these items in the message formats you create, as well as adding your own items to the pallet.

Adding Items to the Pallet

To add items to the pallet:

1. Choose View-->Show Pallet to display the pallet.

   Note: If the Pallet window is already displayed, skip this step.

2. From the tree pane of the XML Translator window, choose the item you want to add to the pallet.

3. Click and hold the left mouse button and drag the item into the pallet window.

4. When the item is placed in the position you want it (as sibling of the desired item), release the mouse button. The item is copied from the XML Translator window to the pallet window.

   Notes: You cannot add any node that depends on the existence of another node to the pallet. For example, you cannot add Field or Group References, and you cannot add items that have a Repeat Field specified.

   Adding comments is possible, but not recommended since comments do not have unique names and therefore are indistinguishable on the pallet.

Deleting Items From the Pallet

To delete items from the pallet:

1. Select the item in the pallet to be deleted and click the right mouse button. The Shortcut Menu displays.

2. Choose Delete. A message displays asking you to confirm the deletion.

3. Click OK to delete the item.

Adding Pallet Items to a Message Format

To copy items from the pallet to a message format:

1. Choose View-->Show Pallet to display the pallet.

   Note: If the Pallet window is already displayed, skip this step.

2. From the pallet window, choose the item you want to add to your message format.

3. Click and hold the left mouse button and drag the item into the tree pane of the Format Builder window.

4. When the item is placed in the position you want it (as the sibling of the desired item), release the mouse button. The item is copied from the pallet to the message format.

Saving a Message Format

To save a message format file for the first time:

1. Choose File-->Save As. The Save As dialog displays.

   Figure 2-9 Save As Dialog

   

2. Navigate to the directory where you want to save the file.

3. In the File Name text box, type the name you want to assign to the file.

4. Format Builder automatically assigns the .mfl extension to message format files by default if no extension is given.

5. Click Save As to save the file in the specified location with the specified name and extension.

To save a message format file using the same name, choose File-->Save. The file is saved in the same location with the same name and extension.

To save a message format file using a different name, choose File-->Save As and follow steps 1 through 5 above.

Opening an Existing Message Format

To open an existing message format file:

1. Choose File-->Open. The Open dialog displays.

   Figure 2-10 Open Dialog

   

2. Navigate to the directory containing the desired file and select the file name.

3. Click Open. The file is loaded into Format Builder.

Importing a COBOL Copybook

XML Translator includes a feature that allows you to import a COBOL copybook into Format Builder creating a message definition to translate the COBOL data. When importing a copybook, comments are used to document the imported copybook and the Groups and Fields it contains.

To import a COBOL copybook:

1. Choose Tools-->Import-->COBOL Copybook Importer. The COBOL Copybook Importer dialog displays.

   

2. Enter data in the fields as described in the following table:

   Field	Description
   Filename	Type the path and name of the file you want to import.
   Browse	Click to navigate to the location of the file you want to import.
   Byte Order
   Big Endian	Select this option to set the byte order to Big Endian. Note: These values are attributes of the copybook data, not the copybook description file.
   Little Endian	Select this option to set the byte order to Little Endian. Note: These values are attributes of the copybook data, not the copybook description file.
   Character Set
   EBCDIC	Select this option to set the character set to EBCDIC. Note: These values are attributes of the copybook data, not the copybook description file.
   ASCII	Select this option to set the character set to ASCII. Note: These values are attributes of the copybook data, not the copybook description file.
   Action Buttons
   OK	Imports the COBOL Copybook using the settings you defined.
   Cancel	Closes the dialog and returns to Format Builder without importing.
   About	Displays information about the COBOL Copybook importer including version and supported copybook features.

Once you have imported a copybook, you may work with it as you would any message format definition. If an error or unsupported data type is encountered in the copybook, a message is displayed informing you of the error. You can choose to display the error or save the error to a log file for future reference.

Setting Format Builder Options

You can set several options to control the overall operation of Format Builder.

To set Format Builder options:

1. Choose Tools-->Options. The Options dialog displays.

   Figure 2-11 Format Builder Options Dialog

   

2. Enter data in the fields as described in the following table.

   Field	Definition
   Default Message Format Version	Select the MFL version used when creating new documents. Note: Message formats contain their own format version specified on the Message Format pane.
   XML Formatting Options
   Initial Indent	Enter the number of spaces to indent the first line of the Message Format document.
   New Line Indent	Enter the number of spaces to indent a new child line of the Message Format document.
   XML Content Model Options
   Auto-generate DTD	Generates a DTD document when you save the MFL document. This document will be placed in the same directory as the message format.
   Auto-generate Schema	Generates an XML Schema file when you save the MFL document.This document will be placed in the same directory as the message format.
   Action Buttons
   OK	Saves your changes and closes the dialog.
   Cancel	Discards your changes and closes the dialog.

Format Builder Menus

The following menus are available in Format Builder.

File Menu

The following commands are available from the File Menu.

Note: Some commands may be unavailable, depending on the actions you have taken.

Menu Command	Description
New	Creates a new Message Format document
Open	Opens an existing Message Format document
Close	Closes the current Message Format document
Save	Saves the current Message Format document
Save As	Saves the current Message Format under a different name document
Exit	Exits the Format Builder program

Edit Menu

The following commands are available from the Edit Menu.

Note: Some commands may be unavailable, depending on the actions you have taken and the state of the tree pane and its items.

Menu Command	Description
Undo	Reverses the previous action. The Undo command in the Edit Menu changes to indicate the action that can be undone. For example, changing the name of a field to Field1 and clicking Apply causes the Edit Menu to read "Undo Apply Field Field1".
Redo	Reverses the effects of an Undo command. The Redo command in the Edit Menu changes to indicate the action that can be redone. For example, changing the name of a field to Field1 and then undoing that action causes the Edit Menu to read "Redo Apply Field Field1".
Cut	Removes the item currently selected in the left-hand pane, and it's child objects, from the tree. This item is placed on the clipboard for pasting into another location. Note: This action is not available if the Message Format (root) item is selected.
Copy	Makes a copy of the item currently selected in the left-hand pane for insertion elsewhere in the tree. Note: This action is not available if the Message Format (root) item is selected.
Paste	Inserts the cut or copied item. An additional menu displays when you select Paste. You can choose to paste the item as a child or sibling of the selected item. In addition, you can choose to paste a reference as a sibling of the selected item.
Duplicate	Makes a copy of the item selected in the tree. The duplicate item contains the same values as the original item. The name of the duplicate item is the same as the original item name, but the word "New" is inserted before the original name. For example, duplicating an item called "Field1" results in an item with the name "NewField1". When you duplicate an item with a numeric value in its name, the new item name contains the next sequential number. For example, duplicating "NewGroup1" results in a group named "NewGroup2".
Delete	Deletes the item selected in the tree, as well as all child objects of that item.
Move Up	Moves the selected item up one position under its parent.
Move Down	Moves the selected item down one position under its parent.
Promote	Promotes the selected item to the next highest level in the tree. For example, Field1 is the child object of Group1. Selecting Field1 and clicking the Promote tool makes it a sibling of Group1.
Demote	Demotes the selected item to the next lower level in the tree. For example, Group1 is the sibling of Field1. Field1 immediately follows Group1 in the tree. Selecting Field1 and clicking the Demote tool makes it a child of Group1.

Insert Menu

The following commands are available from the Insert Menu.

Menu Command	Description
Field	Inserts a new field. You can choose whether to insert the field as a child or sibling of the item selected in the tree.
Group	Inserts a new group. You can choose whether to insert the group as a child or sibling of the item selected in the tree.
Comment	Inserts a comment. You can choose whether to insert the comment as a child or sibling of the item selected in the tree.

View Menu

The following commands are available from the View Menu.

Menu Command	Description
Show Pallet	Displays the pallet window. For more information on the pallet, see Working with Pallets.
Expand All	Expands the entire tree pane to show the child objects of all items in the tree.
Collapse All	Collapses the entire tree pane to show only the root message format.

Tools Menu

The following commands are available from the Tools Menu.

Menu Command	Description
Import	Displays a list of the installed importers. Choose the importer from which you want to import a message.
Options	Displays the Format Builder Options dialog. For more information, see Setting Format Builder Options.

Test Menu

The following command is available from the Test Menu.

Menu Command	Description
Message Format	Opens the Format Tester. Refer to Testing Format Definitions for more information.

Help Menu

The following commands are available from the Help Menu.

Menu Command	Description
Help Topics	Displays the main Help screen.
How Do I. . .	Provides step-by-step instructions for performing the basic tasks in Format Builder.
About	Displays version and copyright information about Format Builder.