bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Translating Data

Building Format Definitions

Format definitions are the metadata used to parse or create binary data. WebLogic Integration helps you build format definitions for binary data that is to be translated to or from XML.

This section provides information about building format definitions using the Format Builder, WebLogic Integration's design-time component for integrating data. It includes the following topics:

- Understanding Data Formats

- Analyzing the Data to Be Translated

- Using the Format Builder

Understanding Data Formats

To understand how to use the Format Builder, it helps to understand the following format and document types:

- Binary (NonXML) Data

- XML Documents

- DTDs and XML Schemas

- MFL Documents

Binary (NonXML) Data

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

Unlike XML data, binary data is not self-describing. In other words, binary data does not include a description of how the data is grouped, divided into fields, or otherwise arranged. 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 that sequence.

For example, consider the following binary data string:

2231987

You can interpreted it in many different ways. For example:

- As a date: 2/23/1987

- As a phone number (223-1987)

Without a clear understanding of the purpose of this data string, the application cannot interpret the string appropriately.

In order for binary data to be understood by an application, the layout of the data must be embedded in the application itself. The character set used to encode the character data included in a binary file may also vary. 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.

You can use Format Builder to create a Message Format Language (MFL) file that describes the layout of your binary data. MFL is an XML language that includes elements for describing 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 at run time to translate data to and from an XML document.

Listing 3-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;

XML Documents

The eXtensible Markup Language (XML) is fast becoming the universal format for structured documents and data on the Web. Unlike binary data, XML is self-describing; it makes use of tags (words bracketed by '<' and '>') that signal the start and end of each block of data. These tags define the hierarchy of related data components which constitute the elements in a structured document.

The properties of XML make it suitable for representing and structuring data in a platform-neutral manner. By making the structure explicit, XML can simplify the task of exchanging data between applications. Because the data is presented in a standard form, applications on disparate systems can interpret it using XML parsing tools, instead of having to interpret data in proprietary binary formats.

Listing 3-2 shows an example of an XML document.

Listing 3-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>

DTDs and XML Schemas

The original XML recommendation only defined one way to describe the elements, attributes, and data types allowed in an XML document instance: the XML Document Type Definition (DTD). Subsequently, it became apparent that a more flexible and powerful way to describe the content model was required, and work began on the XML Schema definition language, which became available as a final recommendation in May of 2001.

An XML document is said to be valid if it conforms to the content model described in its associated DTD or XML Schema. Although the metadata required by an XML parser to validate an XML document can be conveyed in either a DTD or XML Schema, an XML Schema definition is more specific than a DTD; it provides much finer grained control over the content than a DTD.

Listing 3-3 shows an example of a Document Type Definition, or DTD.

Listing 3-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 3-4 shows an example of an XML Schema definition.

Listing 3-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>

MFL Documents

A Message Format Language (MFL) document (also known simply as a message format document) is a specialized XML document used to describe the layout of binary data. An MFL document conforms to the mfl.dtd, which includes elements and attributed used to describe each field of data, as well as groupings of fields (groups), repetition, and aggregation. When you use Format Builder to define the hierarchy of a binary record, the layout of fields, and the grouping of fields and groups, the information is saved as an MFL document that can then be used to perform run-time translations. The information captured in the MFL document can also be used to generate DTDs or XML Schemas that describe the content model for the output generated by the MFL document.

The top-level element of a message format document is the MessageFormat element, which defines the message format name and version. For example, the following is the root element of the sample po.mfl document installed with WebLogic Integration:

<MessageFormat name='PurchaseRequest' version='2.01'>

WebLogic Integration now supports Message Format Language Version 2.02. This version supports new features related to padding, truncation, and trimming. Message Format Language Version 2.01 is still supported.

The name assigned to the message format document becomes the root element in the XML instances that are generated based on the MFL document. For example, The following is the root element of any XML document generated based on the sample po.mfl document:

<PurchaseRequest>

The other elements and attributes available in an MFL document are used to define the following:

- Fields and Field Formats - A field is a sequence of bytes that is meaningful in the context of an application and that defines the format of a field. (For example, the field EMPNAME contains an employee name.) You can define the following formatting parameters:

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

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

- Occurrence - Indicates the number of times the field is shown in the message format. You can specify the number of times the field is to be shown, or define a delimiter that indicates the end of the repeating field.

- Optional - Indicates that the field may or may not be included in the format of the named message.

- Code Page - Identifies the type of character encoding used for the data in the field.

- Groups and Group Formats - A group is a collection of fields, comments, and other groups or references that are related in some way (for example, the fields PAYDATE, HOURS, and RATE belong to the PAYINFO group). The parameters you can define for a group include:

- Tagged - Means that a literal precedes the other content of the group, which may be other groups or fields.

- Occurrence - Indicates either the number of times the group is to be repeated in the message format, or a delimiter that marks the end of the repeated group. For more information about delimiters, see Specifying Delimiters.

- Choice of Children - Indicates that only one item in the group will appear in the message format.

- Optional - Indicates that the data in this structure may or may not be included in the named message format.

- References and Reference Formats - A reference indicates that another instance of the field or group format exists in the data. The format of a reference field or group is the same as the format original field or group, but you can change the optional setting and the occurrence setting for the reference field or group. For example, if your data includes a bill to address and a ship to address and the same format is used for both addresses, you can create the address format once, and then reference it. That is, you can create the an address definition for the bill to address and reference it for the ship to address.

- Comments - Notes containing 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. Sample data for a legacy purchase order, with corresponding MFL and XML documents for a purchase order record, are installed with ProductName. The sample purchase order illustrates how WebLogic Integration translates data from one format to another. For more information about this sample data, see Running the Purchase Order Sample.

The key to translating binary data to and from XML is to create an accurate description of it. 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

Use Format Builder to incorporate these elements into the format definitions used for data translations.

Using the Format Builder

Format Builder helps you create format descriptions for binary data and store them in MFL documents. Your description should include hierarchical and structural information derived from a 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 applying them to your data.

Starting Format Builder

To start Format Builder, choose Start—>Programs—>BEA WebLogic Platform 7.0—>WebLogic Integration 7.0—>Format Builder. The Format Builder window is displayed.

Using the Format Builder Window

The Format Builder window is split into two vertical panes. The left pane contains the navigation tree which shows the structural relationship of the groups and fields defined in the active MFL document. The right pane displays the properties that define the item.

Information about the file you are editing is displayed in the title bar of the Format Builder window.

Figure 3-1 Format Builder Window

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

The following topics explain how to use the various tools provided in the Format Builder window to navigate and execute commands:

- Using the Navigation Tree

- Using the Format Builder Menu Bar

- Using the Toolbar

- Using Drag and Drop

- Using the Shortcut Menus

Using the Navigation Tree

The navigation tree represents the structure of the binary data in a hierarchical layout. The root node of the navigation tree, the Message node, corresponds to the MFL document being created or edited. Child nodes are labeled with the names of groups or fields. Fields are represented by leaf nodes in the navigation tree. Groups contain fields or other groups and are represented by nonleaf nodes in the navigation tree.

The icon for each node encapsulates the following information about the node: whether the node represents a message, a group, a field, a comment, or a reference; 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 can add, delete, move, copy, or rename nodes in the navigation tree though menus or the toolbar. (For details, see Using the Format Builder Menu Bar and Using the Toolbar.)

The following table describes the icons displayed in the navigation tree.

Table 3-1 Navigation Tree Icons

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 belong to the PAYINFO group.) Defines the formatting for all items in the group.
| Optional Group | A group that may or may not be included in the message format.
| Repeating Group | A group that is included one or more times.
| Optional Repeating Group | A group that may or may not be included, but if included, may occur more than once.
| Group Reference | Indicates the existence of another instance of the group in the data. The format of a reference group is the same as that of the original group, but you can change the optional setting and the occurrence setting for the reference group.
| Group Choice | Indicates that only one of the items in the group is included in the message format.
| Field | Sequence of bytes that is meaningful in the context of the application and that defines the formatting for the field. (For example, the field EMPNAME contains an employee name.)
| Optional Field | A field that may or may not be included in the message format.
| Repeating Field | A field is included one or more times.
| Optional Repeating Field | A field that may or may not be included, but, if included, may occur more than once in the message format.
| Field Reference | Indicates the existence of another instance of the field in the data. The format of a reference field is the same as that of the original field, but you can change the optional setting and the occurrence setting for the reference field.
| Comment | Contains notes about the message format or the data translated by the message format.
| Collapse | A minus sign next to an item indicates that the specified item can be collapsed.
| Expand | A plus sign next an item indicates that the specified item can be expanded to show child items.

Using the Format Builder Menu Bar

The menu bar provides quick access to Format Builder functions.

Figure 3-2 Format Builder Menu Bar

The items available in a menu depend on the actions you have taken and the node currently selected in the navigation tree. If a menu item is not available, it is shown in gray in the menu.

You can display a menu in either of two ways:

- Click the name of the menu in the menu bar.

- On your keyboard, press Alt + key, where key is the underlined letter in the menu name.

To execute a command, select it from the menu. Some commands can also be executed via the keyboard shortcut indicated on the menu (For example, a Ctrl + key sequence.) The commands available on each menu are described in Format Builder Menus.

Using the Toolbar

The toolbar is a menu of icons that provide alternative ways to access frequently used commands.

Figure 3-3 Format Builder Toolbar

To execute a command, click the appropriate icon in the toolbar. If a command is unavailable, the icon for it appears grayed-out.

The following table describes the icons in the Format Builder tool bar.

Table 3-2 Format Builder Toolbar Icons

Toolbar Icon | 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 pane, and its child objects, from the navigation tree. The item can be pasted elsewhere in the navigation 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 pane for insertion elsewhere in the navigation 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 indicates the action that can be undone. For example, if you change the name of a field to Address and click Apply, the tool tip displays the following message: Undo Apply Field Address. Format Builder supports multiple undoing of previous actions.
| Redo | Reverses the effects of an Undo command. The tool tip indicates the action that can be redone. For example, if you change the name of a field to Address and then Undo that change, the Redo tool tip displays the following message: Redo Apply Field Address. Format Builder supports multiple redoing of previous actions.
| Insert Field | Inserts a field as a sibling of the item selected in the navigation tree.
| Insert Group | Inserts a group as a sibling of the item selected in the navigation tree.
| Insert Comment | Inserts a comment as a sibling of the item selected in the navigation tree.
| 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 | Assigns the selected item to the next highest level in the navigation tree. For example, suppose Field1 is a child object of Group1. If you select Field1 and click the Promote tool, you make Field1 a sibling of Group1.
| Demote item | Assigns the selected item to the next lower level in the navigation tree. For example, suppose Group1 is the sibling of Field1 and it is listed immediately after Group1 in the navigation tree. If you select Field1 and click the Demote tool, you make Field11 a child of Group1.
| Expand All | Expands all the items in the navigation tree to show child items.
| Collapse All | Collapses the navigation tree to show first-level items only.
| Format Tester | Opens the Format Tester window.

Using the Shortcut Menus

When you right-click an item in the navigation tree, a menu of the most frequently used commands for that item is displayed. The following table describes the commands that are available from the shortcut menus.

Note: The availability of a command depends on the item you select and the previous actions you have taken.

Command | Description
--- | ---
Cut | Removes the item currently selected in the left pane, and its child objects, from the navigation tree.
Copy | Makes a copy of the item currently selected in the left pane for insertion elsewhere in the navigation tree.
Paste | Inserts the cut or copied item. An additional menu is displayed when you select Paste. You can paste the item as either a child or a sibling of the selected item. In addition, you can paste a reference to the cut or copied item as a sibling of the selected item.
Insert Group | Inserts a new group as either a child or a sibling of the selected item, depending on your specification.
Insert Field | Inserts a new field as either a child or a sibling of the selected item, depending on your specification.
Insert Comment | Inserts a comment as either a child or a sibling of the selected item, depending on your specification.
Duplicate | Makes a copy of the currently selected item and pastes it as a sibling. The duplicate item contains the same values and child objects as the original. The name of the duplicate is the same as that of the original, with the addition of a prefix: New. Thus, for example, if the name of the original item is MyGroup1, then the name of the duplicate is NewMyGroup1.
Delete | Deletes the selected item.

Using Drag and Drop

You can drag and drop to copy and paste, or move items in the navigation tree.

Note: The node being copied or moved is always inserted as a sibling of the selected node during the drag-and-drop process. If you drag and drop the node onto the Message Format node, it is inserted as the last child.

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 copy and paste 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 pasted the new location.

Creating Message Formats

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 detail window for the message format is displayed the right pane.

   Figure 3-4 Message Format Detail Window

2. Enter the name of the message format in the Name/XML root field.

   Note: The entry in the Name/XML Root field becomes the name of the root element of each XML instance generated based on this message format document. Therefore, the entry must comply with the conventions described in the following section, XML Element Naming Conventions.

3. Click one of the following:

   - Apply—updates the message format properties.

   - Reset—discards your changes to the detail window and resets all fields to the values that were last applied.

   - Help—displays online help information for the message format detail window.

   Note: The Apply and Reset options are enabled only after changes are made in the detail window.

XML Element Naming Conventions

The names you assign to the root node, fields, groups, and references in a message format document are translated to XML element names in the XML instances generated based on the message format document. Therefore, the names must comply with the following XML naming rules:

- A name must start with a letter or underscore.

- A name can contain letters, digits, periods, hyphens, or underscores.

The following strings are examples of valid names:

- MyField

- MyField1

- MyField_again

- MyField-again

The following strings are examples of invalid names:

- 1MyField (starts with a digit)

- My>Field (includes a greater-than sign (>), which is an illegal character)

- My Field (includes a space, which is not permitted)

Creating Groups

A group is a collection of fields, comments, references, and other groups that are related in some way. For example, the fields PAYDATE, HOURS, and RATE might all belong to 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 the an item in the navigation tree.

2. Choose one of the following:

   - If the selected item is the root node, or another group, and you want to create the group as the child of the selected item, choose Insert—>Group—>As Child.

   - If you want to create the group as a sibling the selected item, choose Insert—>Group—>As Sibling.

   The detail window for the group is displayed the right pane.

   Figure 3-5 Group Detail Window

3. Define the properties for the group as described in the following table.

   Table 3-3 Group Properties

   Category | Property | Description
   --- | --- | ---
   Group Description | Name | The name of the group. The entry must comply with the conventions described in XML Element Naming Conventions" on page 19.
   Optional | Select Optional if the group is optional.
   Choice of Children | Select Choice of Children if only one of the items in the group will be included in the message format.
   Group Occurrence (Unless defined as Optional in the Group Description, all groups occur at least once.) | Once | Select this option to indicate that the group appears only once.
   Repeat Delimiter | Select this option to indicate that the group will repeat until the specified delimiter is encountered.
   Repeat Field | Select this option to indicate that the group will repeat the number of times specified in the field selected as the repeat field.
   Repeat Number | Select this option to indicate that the group will repeat the specified number of times.
   Unlimited | Select this option to indicate that the group will repeat an unlimited number of times.
   Group Attributes | Group is Tagged | Select this option if the group is tagged, that is, if a literal precedes the other content of the group, which may be other groups or fields.
   Group Delimiter | The termination point of a group can be specified by a delimiter: a string of characters that marks the end of a group of fields. The group continues until delimiter characters are encountered. Note: Normally, groups are not delimited. They are usually parsed by content; the group ends when all child objects have been parsed. For more information about delimiters, see Specifying Delimiters. Select from among the following options to specify the group delimiter attributes:
   None | Select this option if there is no delimiter for the group.
   Delimited | Select this option if the termination point of the group is marked with a delimiter character string, then enter the delimiter characters in the Value field.
   Delimiter Field | Select this option if the termination point of the group is marked by a field that contains a delimiter character string. When you select this option, you are prompted to provide the following: Field—select the field that contains the delimiter character string. A list of valid fields is presented in a drop-down list. Default—enter the default delimiter character used if the selected field is not included in the data. This value is required.
   Delimiter is Shared | Select this option to indicate 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 by the group, and the last field of the group, to indicate the end of the data.

4. Click one of the following:

   - Apply—updates the group properties.

   - Duplicate—makes a copy of the group currently displayed and pastes it as a sibling.

   The duplicate group contains the same values and child objects as the original. The name of the duplicate is the same as that of the original, with the addition of a prefix: New. Thus, for example, if the name of the original group is MyGroup1, then the name of the duplicate is NewMyGroup1.

   - Reset—discards your changes to the detail window and resets all fields to the values that were last applied.

   - Help—displays online help information for the detail window.

   Note: The Apply and Reset options are enabled only after changes are made in the detail window.

Specifying Delimiters

You can specify delimiters in Format Builder by entering the correct syntax. For example, if you want to specify a tab character as a delimiter (`\u009'), you must enter the construct \t to match it.

The following tables maps characters you can use as delimiters to the constructs you must use to designate these characters as delimiters.

Table 3-4 Character Delimiters

Use this construct . . . | To designate the following character as a delimiter . . .
--- | ---
x | x
\\ | \ (backlash)
\0n | Character with octal value 0n (<= n <= 7)
\0nn | Character with octal value 0nn (0 <= n <= 7)
\0mnn | Character with octal value 0mnn (0 <= m <= 3, 0 <= n <= 7)
\xhh | Character with hexadecimal value 0xhh
\uhhhh | Character with hexadecimal value 0xhhhh
\t | Tab character ('\u0009')
\n | Newline (line feed) character ('\u000A')
\r | Carriage-return character ('\u000D')
\f | Form-feed character ('\u000C')
\a | Alert (bell) character ('\u0007')
\e | Escape character ('\u001B')
\cx | Control character corresponding to x

For more information, visit the following URL:

http://java.sun.com/j2se/1.4/docs/api/java/util/regex/Pattern.html

Creating Fields

A field is a sequence of bytes that is meaningful to an application. (For example, the field EMPNAME contains an employee name.) You can create a field as a child of the message format node, as a child of a group, or as a sibling of a group or another field. Field names are used as element names in the XML output; they must comply with the conventions described in XML Element Naming Conventions.

To create a field:

1. Select an item in the navigation tree.

2. Choose one of the following:

   - If you want to create the field as the child of the selected item, choose Insert—>Field—>As Child.

   - If you want to create the field as the sibling of the selected item choose Insert—>Field—>As Sibling.

   The detail window for the field is displayed the right pane.

   Figure 3-6 Field Detail Window

3. Define the properties for the field as described in the following table.

   Table 3-5 Field Properties

   Category | Property | Description
   --- | --- | ---
   Field Description | Name | The name of the field. The entry must comply with the conventions described in XML Element Naming Conventions" on page 19.
   Optional | Select this option if this is an optional field. Optional means that the data for the field may or may not be present.
   Type | Select the data type of the field from the drop-down list. The default is String. Note: Which field type you select dictates which field data options are displayed. For a list of data types supported by ProductName, see Supported Data Types.
   Field Occurrence (Unless defined as Optional in the Field Description, all fields occur at least once.) | Once | Select this option to indicate that the field appears only once.
   Repeat Delimiter | Select this option to indicate that the field will repeat until the specified delimiter is encountered.
   Repeat Field | Select this option to indicate that the field will repeat the number of times specified in the field selected as the repeat field.
   Repeat Number | Select this option to indicate that the field will repeat the specified number of times.
   Unlimited | Select this option to indicate that the field will repeat an unlimited number of times.
   Field Attributes (The Field Attributes properties that are displayed are dependent on the Type specified in the Field Description) | Field is Tagged | Select this option if the field is tagged, that is, if a literal proceeds the data, indicating that the data is present. You must also choose the data type of the tag field from the drop-down list. For example in the following: SUP:ACME INC SUP: is a tag and ACME INC is the field data. If you select the Field is Tagged option, enter the tag in the field to the right of the check box.
   Field Default Value | Select this option to specify a value for the data in field that is inserted into the binary data if the field is not included in the XML. If the field is not included in the binary data and it is not optional, then the binary data fails to parse, even if a default value is given.
   Data Base Type | If the field is a date or time field, the base type indicates the type of characters (ASCII, EBCDIC, or Numeric) used to represent the data.
   Year Cutoff | If the field is a date field with a 2-digit year, the year cutoff attribute 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 prefix of 19 is added to the year value. Otherwise a prefix of 20 is used.
   Code Page | The character encoding of the field data. The default code page is set by choosing Tools—>Options and selecting the default encoding from the Default Field Code Page drop down list.
   Value | The value displayed in a literal field.
   Field Attributes (Continued) | Termination | Select from among the following options to specify the group delimiter attributes:
   Length | Select this option to set the length of variable-sized data types to a fixed value. When you select this option, you are prompted to provide the following: Length—enter the number of bytes in the field. Trim Leading/Trailing—removes the specified data from the leading or trailing edge of the data. Pad—if the XML data is shorter than the specified length, appends the specified data to correct its length. Select one of the following padding options: Select the Trailing option to append padding at the end of a field. Select the Leading option to append padding at the beginning of a field. Truncate—remove a specified number of characters from a field. Select any combination of the following truncation options: Select the Truncate First option to remove the specified number of characters from the beginning of the field. Select the Truncate After option to remove the specified number of characters from the end of the field. If you select both truncation options, the Truncate First option is implemented initially, and the Truncate After option is invoked on the remaining characters.
   Field Attributes (Continued) | Termination (Continued) | Embedded Length | Select this option to indicate that the termination point of a variable-sized data type is specified by an embedded length. An embedded length precedes the data field and indicates the number of bytes in the data. When you select this option, you are prompted to provide the following: Type—specifies the data type and, if necessary, the length or delimiter for termination. Tag/Length Order—specifies the order of the tag and length fields when both are included. The default order is: tag, length. Trim Leading/Trailing—removes the specified data from the leading or trailing edge of the data. Truncate—remove a specified number of characters from a field. For more information, see the description of the Truncate option for the Length option.
   Delimiter | Select this option to indicate that the termination point of a variable-sized data type is specified by a delimiter: a value that marks the end of the field. The field data continues until the delimiter is encountered. When you select this option, you are prompted to provide the following: Value—enter the delimiter that marks the end of the field data. Trim Leading/Trailing—removes the specified data from the leading or trailing edge of the data. Truncate—remove a specified number of characters from a field. For more information, see the description of the Truncate option for the Length option.
   Field Attributes (Continued) | Termination (Continued) | Delimiter Field | Select this option if the termination point of a variable-sized data type is specified by a field that contains a delimiter value. When you select this option, you are prompted to provide the following: Field—select the field that contains the delimiter. Default—enter a default delimiter that can be used when the delimiter field is not present. You must enter a value in this field. Trim Leading/Trailing—removes the specified data from the leading or trailing edge of the data. Truncate—remove a specified number of characters from a field. For more information, see the description of the Truncate option for the Length option. For more information about delimiters, see Specifying Delimiters.
   |  | Decimal Position | Specifies the number of digits (0-16) to the left of the decimal point.

4. Click one of the following:

   - Apply—updates the field properties.

   - Duplicate—makes a copy of the field currently displayed and pastes it as a sibling.

   The duplicate field contains the same values as the original. The name of the duplicate is the same as that of the original, with the addition of a prefix: New. Thus, for example, if the name of the original field is MyField1, then the name of the duplicate is NewMyField1.

   - Reset—discards your changes to the detail window and resets all fields to the values that were last applied.

   - Help—displays online help information for the field detail window.

   Note: The Apply and Reset options are enabled only after changes are made in the detail window.

Padding Mandatory Fields

In previous releases of WebLogic Integration, no padding was performed on mandatory fields when data for the field did not exist at run time. In WebLogic Integration 7.0, during an XML-to-binary translation, a mandatory field that does not contain data is padded with the default value, if a default value has been specified. If no default value is specified and a field does not contain data at translation time, an error occurs.

Note: Padding of mandatory fields is not supported for binary-to-XML translations.

This feature is useful when a group is specified multiple times, but data is provided for only one occurrence. When padding of mandatory fields is invoked, all occurrences of a group for which data are not provided are padded with default values, if specified.

Creating Comments

Comments are 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; they are unnumbered and are not transformed to XML or binary data. You can create a comment as a child or sibling of any message format, group, or field.

Note: Conventionally, a comment precedes the node it annotates.

To create a comment:

1. Select an item in the navigation tree.

2. Choose one of the following:

   - If you want to create the comment as the child of the selected item, choose Insert—>Comment—>As Child.

   - If you want to create the comment as the sibling of the selected item, choose Insert—>Comment—>As Sibling.

3. Enter the comment text in the Comment Details field.

   Figure 3-7 Comment Detail Window

4. Click one of the following:

   - Apply—updates the comment text.

   - Reset—discards your changes to the detail window and resets all fields to the values that were last applied.

   - Help—displays online help information for the comment detail window.

   Note: The Apply and Reset options are enabled only after changes are made in the detail window.

Creating References

References allow you to reuse an existing field or group format in a new context. When you create a reference to an existing field or group, the same format is used, but you can modify the optional and occurrence properties for the reference field or group.

For example, if your data includes a bill to address and a ship to address and the same format is used for both addresses, you can create the address format once, and then reference it. That is, you can create the an address definition for the bill to address and reference it for the ship to address.

Note: A reference item is given exactly the same name as the original item, therefore, you should use a generic name, such as address, when you create a field or group that is be referenced. For instance, in the previous example, you can create an address group as a child of the bill_to group and then reference the address group from within the ship_to group.

To create a reference:

1. Select the item to be referenced in the navigation tree.

2. Choose Edit—>Copy.

3. Select an item at the desired location for the reference. When you paste the item as a reference in the next step, the reference is pasted as a sibling of the selected item.

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

   The detail window for the reference is displayed. For example, the following figure shows the detail window for a Field Reference.

   Figure 3-8 Field Reference Detail Window

5. Define the properties for the reference as described in the following table.

   Table 3-6 Reference Properties

   Category | Property | Description
   --- | --- | ---
   Field or Group Reference Description | Name | The name of the field or group for which you created this reference. This value cannot be changed.
   Optional | Select this option if the reference is optional.
   Field or Group Reference Occurrence (Unless defined as Optional all referenced items occur at least once.) | Once | Select this option to indicate that the referenced item appears only once.
   Repeat Delimiter | Select this option to indicate that the referenced item will repeat until the specified delimiter is encountered.
   Repeat Field | Select this option to indicate that the referenced item will repeat the number of times specified in the field selected as the repeat field.
   Repeat Number | Select this option to indicate that the referenced item will repeat the specified number of times.
   Unlimited | Select this option to indicate that the referenced item will repeat an unlimited number of times.

6. Click one of the following:

   - Apply—updates the reference properties.

   - Reset—discards your changes to the detail window and resets all fields to the values that were last applied.

   - Edit Reference—displays the detail window for the original item to allow you to edit the item.

   - Help—displays online help information for the reference detail window.

   Note: The Apply and Reset options are enabled only after changes are made in the detail window.

Working with the Palette

The Format Builder palette allows you to store commonly used message format components so they are available whenever you need to insert them into your message format definitions.

The default palette, palette.xml, is an MFL document which is stored in the WebLogic Integration installation directory. The default palette contains common date formats, literals, and strings. You can use these items in the message formats you create, as well as add your own items to the default palette. You can also create your own MFL documents for use in the palette, or open and use items from any existing MFL document.

The following topics provide the information you need to use the palette:

- Opening the Palette

- Using the Palette File Menu

- Using the Palette Shortcut Menu

- Copying Items From the Active Message Format to the Palette

- Deleting Items From the Palette

- Copying Palette Items from the Palette to the Active Message Format

Opening the Palette

To open the palette:

1. Start Format Builder.

2. Choose View—>Show Palette.

   The Palette window displays the default palette.

   Figure 3-9 Palette

You can copy items from the navigation tree to the palette, and vice versa. You can use drag and drop, or the commands available on the shortcut menu, to organize items in the palette. The contents of the palette are automatically saved when you exit Format Builder.

Note: Only copying items, whether from the navigation tree to the palette or vice versa, is allowed. You cannot move items between the windows.

Using the Palette File Menu

The commands described in the following table are available from the Palette File menu.

Table 3-7 Palette File Menu Commands

Command | Description
--- | ---
Open | Displays the Open dialog box to allow you to select and open an existing MFL document in the palette.
Save | Saves any changes you have made to the MFL document currently open in the palette.
Hide Palette | Closes the Palette window.

Using the Palette Shortcut Menu

A shortcut menu is displayed when you right-click an item or folder in the palette. The following table describes the commands available from the shortcut menu.

Note: Some commands may be unavailable, depending on the item you select.

Table 3-8 Palette Shortcut Menu Commands

Command | Description
--- | ---
Insert | Inserts a new folder. When you select this command, you are prompted to supply the name of the folder.
Rename | Renames a folder. When you select this command, you are prompted to supply the new name.
Delete | Deletes the selected 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 | Assigns the selected item to the next level up in the hierarchy. For example, suppose Field1 is a child of Group1. If you select Field1 and click the Promote tool, then Field1 becomes a sibling of Group1.
Demote | Assigns the selected item to the next lower level in the hierarchy. When you demote an item, it becomes a child of the sibling that immediately precedes it. For example, suppose Field1 is a sibling of Group1, and that it and immediately follows Group1. If you select Field1 and click the Demote tool, Field1 becomes a child of Group1.

Copying Items From the Active Message Format to the Palette

To copy an item from the document currently open in Format Builder to the palette:

1. If it is not already displayed, choose View—>Show Palette to display the palette.

2. In the navigation tree, select the item you want to add to the palette.

3. Drag the item to palette window, then drop it in the desired location in the hierarchy.

   The item is copied to the selected location.

Notes: You cannot add an item that depends on the existence of another item to the palette. For example, you cannot add a field or group reference, and you cannot add an item for which a Repeat Field is specified.

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

Deleting Items From the Palette

To delete an item from the palette:

1. Right-click the item to be deleted to display the shortcut menu.

2. Select Delete.

   You are prompted to confirm the deletion.

3. Click OK to delete the item.

Copying Palette Items from the Palette to the Active Message Format

To copy an item from the palette to a message format document currently open in Format Builder:

1. If it is not already displayed, choose View—>Show Palette to display the palette.

2. In the palette window, select the item you want to add to your message format.

3. Drag the item to navigation tree, then drop it in the desired location in the hierarchy.

   The item is copied to the selected location in the message format.

Saving or Storing a Message Format

You can save a message format document to your file system as described in the this section, or you can store the document in the repository, as described in Storing MFL Documents in the Repository.

To save a message format file for the first time:

1. Choose File—>Save As to display the Save As dialog box.

   Figure 3-10 Save As Dialog Box

2. Navigate to the directory in which you want to save the file.

3. Enter the name you want to assign to the file in the File Name field.

   Note: If you do not include an extension in your filename, Format Builder automatically assigns the default extension:.mfl.

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

To save changes to an existing file, choose File—>Save.

To save an existing file to a new name, choose File—>Save As and follow steps 2 through 4 in the preceding procedure.

Opening or Retrieving an Existing Message Format File

You can open a message format document on your file system as described in the this section, or you can retrieve the document from the repository, as described in Retrieving MFL Documents from the Repository.

To open an existing message format file:

1. Choose File—>Open to display the Open dialog box.

   Figure 3-11 Open Dialog Box

2. Locate and select the desired file.

3. Click Open to open the file in Format Builder.

Using Internationalization Features

You can use the internationalization features in Format Builder by changing the options for an individual message file or by setting the default Format Builder options to include internationalization. For details, see:

- Changing Options for a Message Format

- Setting Format Builder Options

Changing Options for a Message Format

To change options for a message format file:

1. Select the root node of the message format in the navigation tree.

2. Choose File—>Properties.

   The File Properties dialog box displays the Message Format Version and the Default Message Format (MFL) Encoding.

   Figure 3-12 File Properties Dialog Box

3. Select a type of character encoding for the MFL document from the list of encoding names and descriptions for this file. (To change the default settings for all new message format documents, choose Tools—>Options.)

4. Click OK.

   Your changes are reflected in the MFL document when you test it using Format Tester.

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 box is displayed.

   Figure 3-13 Format Builder Options Dialog Box

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

   Table 3-9 Format Builder Options

   Category | Option | Description
   --- | --- | ---
   N/A | Default Message Format Version | Select the version to be associated with new MFL documents. Note: Each message format document is associated with its own message format version. The version specified for a message format can be changed from the default from the File Properties dialog box described in the preceding section Changing Options for a Message Format..
   Character Encoding Options | Default Message Format (MFL) Encoding | Select the character encoding to be associated with new MFL documents. The character encoding associated with an MFL document specifies the encoding used for the MFL document itself, and the XML output it generates.
   Default Field Code Page | Select the code page, from the list of binary formats, to be used as the default code page for each field created in your MFL documents. A code page specifies the character encoding of the binary data in the field.
   XML Formatting Options | Initial Indent | Enter the number of spaces by which to indent the root element when generating the XML output.
   New Line Indent | Enter the number of spaces by which to indent a new child element when generating the XML output.
   XML Content Model Options | Auto-generate DTD | Generates a DTD document which captures the content model defined in the MFL document. If you specify Auto-generate DTD: When you save an MFL document to the file system, the DTD is saved in the same directory. When you store an MFL document in the repository, the DTD is also stored.
   Auto-generate Schema | Generates an XML Schema document which captures the content model defined in the MFL document. If you specify Auto-generate Schema: When you save an MFL document to the file system, the XML Schema document is saved in the same directory. When you store an MFL document in the repository, the XML Schema is also stored.

3. Click one of the following:

   - OK—saves your changes and dismisses the dialog box.

   - Cancel—discards your changes and dismisses the dialog box.

Format Builder Menus

The following menus are available in Format Builder: File, Edit, Insert, View, Repository, Tools, and Help.

The commands available on each menu are described in the following sections.

Note: Some commands may be unavailable, depending on which actions you have taken and what is selected in the navigation tree.

File Menu

The following commands are available from the File menu.

Table 3-10 File Menu Commands

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.
Properties | Opens the File Properties dialog box for the active message format document. This dialog allows you to set options for the active MFL document (see Changing Options for a Message Format). Choose Tools—>Option to set defaults for the application (see Setting Format Builder Options).
Exit | Exits the Format Builder.

Edit Menu

The following commands are available from the Edit menu.

Table 3-11 Edit Menu Commands

Command | Description
--- | ---
Undo action | Reverses the previous action. The Undo command on the Edit menu is constantly refreshed to indicate the action most recently performed that can be nullified. For example, if you change the name of a field to Field1 and click Apply, the listing for the Undo command contains the following text: Undo Apply Field Field1. Format Builder supports multiple undoing of previous actions.
Redo action | Reverses the effects of the Undo command. The Redo command in the Edit menu is constantly refreshed to indicate the action that can be redone. For example, if you change the name of a field to Field1 and then click Undo, the listing for the Redo command contains the following text: Redo Apply Field Field1. Format Builder supports multiple redoing of actions previously undone.
Cut | Removes the selected item along with its child objects. The item is placed in the clipboard and can be pasted in a new location. Note: This action is not available if the Message Format (root) item is selected.
Copy | Makes a copy of the selected item along with its child objects. The copy is placed in the clipboard and can be pasted in a new location. Note: This action is not available if the Message Format (root) item is selected.
Paste | Inserts the current contents of the clipboard. When you select Paste, the following Paste menu options are displayed: As Child As Sibling As Reference
Duplicate | Makes a copy of the currently selected item and pastes it as a sibling. The duplicate item contains the same values and child objects as the original. The name of the duplicate is the same as that of the original, with the addition of a prefix: New. Thus, for example, if the name of the original item is MyField1, then the name of the duplicate is NewMyField1.
Delete | Deletes the item selected in the navigation 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 | Assigns the selected item to the next level up in the hierarchy. For example, suppose Field1 is a child of Group1. If you select Field1 and select Promote, then Field1 becomes a sibling of Group1 and is inserted immediately after Group1.
Demote | Assigns the selected item to the next lower level in the hierarchy. When you demote an item, it becomes a child of the group that immediately precedes it. For example, suppose Field1 is a sibling of Group1 and immediately follows Group1. If you select Field1 and select Demote, Field1 becomes a child of Group1.

Insert Menu

The following commands are available from the Insert menu.

Table 3-12 Insert Menu Commands

Command | Description
--- | ---
Field | Inserts a new field. You can insert the field as either a child or sibling of the item selected in the navigation tree.
Group | Inserts a new group. You can insert the group as either a child or sibling of the item selected in the navigation tree.
Comment | Inserts a comment. You can insert the comment as either a child or sibling of the item selected in the navigation tree.

View Menu

The following commands are available from the View menu.

Table 3-13 View menu Commands

Command | Description
--- | ---
Show Palette | Displays the Palette window.
Expand All | Expands the entire navigation tree to show the child objects of all items in the navigation tree.
Collapse All | Collapses the entire navigation tree to show only the root message format.

Repository Menu

The following commands are available from the Repository menu.

Note: For details about using the repository, see Retrieving and Storing Repository Documents.

Table 3-14 Repository Menu Commands

Command | Description
--- | ---
Log In | Displays the ProductName Repository Login dialog box, allowing you to connect to the repository.
Log Out | Disconnects from the repository.
Retrieve | Retrieves a document from the repository.
Store | Stores the current document in the repository.
Store As | Stores the current document in the repository under a different name.

Tools Menu

The following commands are available from the Tools menu.

Table 3-15 Tools Menu Commands

Command | Description
--- | ---
Import | Displays a list of the installed importers. Choose the importer from which you want to import a message.
Test | Opens the Format Tester.
User Defined Types | Opens the Add/Remove User Defined Types dialog box.
Options | Displays the Format Builder Options dialog box.

Help Menu

The following commands are available from the Help menu.

Table 3-16 Help Menu Commands

Command | Description
--- | ---
Help Topics | Displays the online help in your default browser.
How Do I | Displays a list of common Format Builder tasks. Click a task to view the step-by-step instructions.
About | Displays version and copyright information for the Format Builder and the JDK you are running.