Transforming Non-XML Data

This section describes design-time and run-time steps required for creating and executing transformations involving non-XML data sources. It also describes how to create schemas (MFL files) for non-XML data using an included WebLogic Integration utility called Format Builder.

This section covers the following topics:

• Using Non-XML Data in Business Processes
• Using Format Builder to Create Format Schemas (MFL Files)
• Importing Existing Metadata to Create Format Schemas (MFL Files)
• Testing the Format Schemas (MFL Files)

Using Non-XML Data in Business Processes

Non-XML data that is sent to or received from legacy applications is often platform-specific information organized in a format unique to the machine on which the information originated. Non-XML data is not self-describing, so to be understood by an application, information about the format (metadata) of this data must be embedded within each application that uses non-XML data from a legacy application.

This section covers the following topics:

• Understanding Transformations That Use Non-XML Data
• Using WebLogic Integration for Transforming Non-XML Data

Understanding Transformations That Use Non-XML Data

Data transformation is the mapping and conversion of data from one format to another. For example, data in a non-XML format can be transformed to an XML format and the converse is also true, data in an XML format can be transformed to an non-XML format. In order to transform data, you must create a schema which contains a description (metadata) for each of the data fields in the non-XML data. During the transformation of data from a non-XML format to an XML format, each field of non-XML data is transformed to XML according to the metadata defined for that field. The metadata you specify must include the name of the field, the data type, the size, and an indication of whether the field is always present or optional. This description of the non-XML data is used to transform the data to XML, as shown in the following figure:

WebLogic Integration can also transform data from XML to non-XML format, as shown in the following figure:

WebLogic Integration can also transform data from one non-XML format to another non-XML format, as shown in the following figure:

Using WebLogic Integration for Transforming Non-XML Data

WebLogic Integration facilitates the integration of data from diverse enterprise applications by supporting the transformation of non-XML legacy system data to other data types (XML and Java primitives). Once legacy data is available as XML or a Java primitive, it can be used directly by WebLogic Integration business processes. WebLogic Integration supports transformations with non-XML data using the following data integration tools:

• Design-Time Component
• Format Builder
• WebLogic Workshop
• Run-Time Component

Steps 1-8 occur at design-time and step 9 occurs during run time, as shown in the following two figures.

The steps for an example non-XML to XML data transformation is shown in the following figure:

The steps for an example XML to non-XML transformation is shown in the following figure:

Steps 2-3 are done in the Format Builder tool and steps 4-8 are done in WebLogic Workshop.

Design-Time Component

Format Builder

A design-time component of WebLogic Integration is a Java application called Format Builder. In the first design-time phase (steps 2-3 in preceding figures), you use the Format Builder to create descriptions of non-XML data records. Specifically, you describe the layout and hierarchy of the non-XML data (the schema) in the Format Builder so it can be transformed to or from other data sources, like XML.

You can describe sequences of bytes as fields and specify, for each field, the type of data (floating point, string, and so on), the size of the data, and the name of the field. You can further define sets of fields (groups), multiple instances of fields and groups, and aggregation.

The description you create is saved in an XML grammar called Message Format Language (MFL). MFL documents contain metadata that describes the structure of the non-XML document. Once the non-XML document has been described via an MFL document, it can be used in XQuery data transformations just like XML documents that have been described by XML Schema (XSD) files.

You can also use Format Builder to retrieve, validate, and edit stored MFL documents and to test message format definitions with your own data. MFL documents are stored in the file system.

The test feature allows you to verify the MFL documents created in Format Builder by transforming a sample XML file to non-XML format, or transforming a sample non-XML file to XML format. You can save the transformed data in a file for future testing.

Note: To learn more about using Format Builder, see Using Format Builder to Create Format Schemas (MFL Files).

WebLogic Workshop

In this second design-time phase, you use WebLogic Workshop to create an application, project, and business process. For instructions on creating applications, projects, and business processes, see Creating a Business Process Application.

In order to map non-XML data in a transformation, you must first import an MFL file which describes the non-XML data into WebLogic Workshop. For instructions, see Selecting Source and Target Types.

You also use WebLogic Workshop to create a Transformation file, a method in the Transformation file, and a Client or Control node in a business process. The method contains a transformation, which when invoked by the business process during run time, maps data types. You design Control or Client nodes in your business process to call a method in a Transformation file, as shown in steps 6-8 in the preceding figures.

The following table lists the Client or Control nodes that can be added to a business process:

• Client Request
• Client Response
• Control Send
• Control Send with Return
• Control Receive

For instructions on add Client and Control nodes to a business process with Transformations, see Interacting With Clients and Interacting With Resources Using Controls, respectively.

Run-Time Component

If you design a Client and Control node to call a method in a Transformation file, during run time, the business process invokes the node and then that node invokes the method that contains the transformation. For example, a Client Receive node could receive non-XML data and pass that data to the transformation method, which transforms the non-XML data to XML data, as shown in the following figure:

Using Format Builder to Create Format Schemas (MFL Files)

WebLogic Integration uses MFL files to represent the schemas of non-XML documents, just as XSD files are used to represent the schemas of XML documents. At run-time WebLogic Integration uses these MFL files to carry out transformation operations involving non-XML data. This section provides information about creating these MFL files using Format Builder.

It includes the following topics:

• Understanding Data Formats
• Analyzing the Data to Be Transformed
• Using Format Builder

Understanding Data Formats

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

• Non-XML Data
• XML Documents
• MFL Documents

Non-XML 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. Non-XML data refers to both binary and text formatted data.

Note: The term non-XML data replaces the term Binary data that was used in previous versions of WebLogic Integration. (WebLogic Integration 7.0 or earlier.)

Unlike XML data, non-XML data is not self-describing. In other words, non-XML data does not include a description of how the data is grouped, divided into fields, or otherwise arranged. Non-XML 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 non-XML 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 non-XML 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 non-XML 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 or schema of your non-XML 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 non-XML 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 transform non-XML data to and from an XML document.

Listing : Example of Non-XML 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 the universal format for structured documents and data. Unlike non-XML data, XML data 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 that 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.

The following listing shows an example 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> 

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 non-XML data. When you use Format Builder to define the hierarchy of a non-XML 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 transformations. The information captured in the MFL document can also be used to generate a DTD that describes 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 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.

Note: You must specify unique field names in a single MFL document. To learn more, see A Note of Caution—Must Specify Unique Field and Group Names in the Same MFL File.

• 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.

Note: You must specify unique group names in a single MFL document. To learn more, see A Note of Caution—Must Specify Unique Field and Group Names in the Same MFL File.

• 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 Transformed

Before a message format can be created, the layout of the non-XML 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 WebLogic Integration. The sample purchase order illustrates how WebLogic Integration transforms data from one format to another.

For more information about this sample data, see Non-XML Data Mapping Sample.

The key to transforming non-XML data to and from XML is to create an accurate description of it. For non-XML 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 transformations.

Using Format Builder

Format Builder helps you create format descriptions for non-XML 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.

WebLogic Integration also provides utilities that allow you to import COBOL copybooks, import XML Schemas, and convert C structure definitions into MFL files. To learn more about these utilities, see Importing Existing Metadata to Create Format Schemas (MFL Files).

Starting Format Builder

You can launch Format Builder using one of the following options:

• To Start Format Builder From WebLogic Workshop
• To Start Format Builder on Windows Without Launching WebLogic Workshop
• To Start Format Builder on Linux Without Launching WebLogic Workshop

To Start Format Builder From WebLogic Workshop

1. Start WebLogic Workshop: choose Start —> Programs —> BEA WebLogic Platform 8.1 —> WebLogic Workshop 8.1.
2. The main WebLogic Workshop window is displayed.
3. From the WebLogic Workshop menu bar, choose Tools —> WebLogic Integration —> Format Builder.

The Format Builder main window is displayed.

To Start Format Builder on Windows Without Launching WebLogic Workshop

Choose Start —> Programs —> BEA WebLogic Platform 8.1 —> Other Development Tools —> Format Builder.

The Format Builder main window is displayed.

To Start Format Builder on Linux Without Launching WebLogic Workshop

1. In command line shell, go to the WebLogic Integration bin directory. For example, if WebLogic Platform is installed in the /usr2/bea directory, go to the /usr2/bea/weblogic81/integration/bin directory as shown here:

cd /usr2/bea/weblogic81/integration/bin 

2. Run the Format Builder start script, as shown here:

./fb.sh 

The Format Builder main 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.

The structure of the non-XML 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

Note: For additional information about Format Builder, see the help included with the Format Builder executable. (To access the Format Builder help, start the Format Builder as described in Starting Format Builder and then from the Format Builder menu bar, choose Help —> Help Topics.)

Using the Navigation Tree

The navigation tree represents the structure of the non-XML 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 non-leaf 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.

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 transformed 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.

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 first letter in the menu name. For example, press Alt + F to select the File menu option.

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.

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.

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.



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 transformed 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)
• My/Field (includes the back slash (/), which is an illegal character)
• My\Field (includes the forward slash (\), which is an illegal character)
• My:Field (includes a colon (:), which is an illegal character)
• My;Field (includes a semi-colon (;), which is an illegal character)

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.

Note: You must specify unique field names in a single MFL document. To learn more, see A Note of Caution—Must Specify Unique Field and Group Names in the Same MFL File.

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.



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

Category	Property	Description
Group Description	Name	The name of the group. The entry must comply with the conventions described in XML Element Naming Conventions.
	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.

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

To learn more, see the java.util.regex.Pattern class description.

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.



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

Category	Property	Description
Field Description	Name	The name of the field. The entry must comply with the conventions described in XML Element Naming Conventions and A Note of Caution—Must Specify Unique Field and Group Names in the Same MFL File.
	Optional	Select this option if this is an optional field. Optional means that the data for the field may or may not be present. If the Optional option is selected for a file, then you must also set the Field is Tagged option from the Field Attributes pane. In addition, in the Field Is Tagged text box enter a unique value for each optional field in a group. Multiple groups can use the same tag value but the tag value for each optional field in a group must be unique.
	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 WebLogic Integration, see the online help of Format Builder.
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 non-XML data if the field is not included in the XML. If the field is not included in the non-XML data and it is not optional, then the non-XML 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

Prior to the WebLogic Integration 7.0 release, no padding was performed on mandatory fields when data for the field did not exist at run time. For the WebLogic Integration 7.0 release and all subsequent releases, during an XML to non-XML transformation, 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 transformation time, an error occurs.

Note: Padding of mandatory fields is not supported for non-XML to XML transformations.

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.

A Note of Caution—Must Specify Unique Field and Group Names in the Same MFL File

You must specify unique field (FieldFormat) and group (StructFormat) format names in a single MFL file. Format Builder allows the creation of duplicate field and group format names in the same MFL file but when an MFL file with duplicate names is imported into WebLogic Workshop causing the schemas project is built, errors will be reported, as shown in the following examples.

If the following example MFL file is imported into WebLogic Workshop, the build of the schema project fails because the field name: StockSymbol is used in two different groups:

<?xml version='1.0' encoding='windows-1252'?>
<!DOCTYPE MessageFormat SYSTEM 'mfl.dtd'>
<MessageFormat name='StockPrices' version='2.01'>
	<StructFormat name='PriceQuoteOne' repeat='*'>
		<FieldFormat name='StockSymbol' type='String' delim=':' codepage='windows-1252'/>
		<FieldFormat name='StockPrice' type='String' delim='|' codepage='windows-1252'/>
	</StructFormat>
	<StructFormat name='PriceQuoteTwo' repeat='*'>
		<FieldFormat name='StockSymbol' type='String' delim=':' codepage='windows-1252'/>
		<FieldFormat name='StockPrice' type='String' delim='|' codepage='windows-1252'/>
	</StructFormat>
</MessageFormat> 

The following schema build error is reported:

ERROR: Error compiling MFL file -C:\bea\weblogic81\DTGuide\Schemas\StockQuotesSameStructFormat.mfl: 
FieldFormat already defined: StockSymbol 

If the following example MFL file is imported into WebLogic Workshop, the build of the schema project fails because the group name: PriceQuote is used twice, even though the first PriceQuote is nested in the group: Level:

<?xml version='1.0' encoding='windows-1252'?>
<!DOCTYPE MessageFormat SYSTEM 'mfl.dtd'>
<MessageFormat name='StockPrices' version='2.01'>
	<StructFormat name='Level' repeat='*'>
		<StructFormat name='PriceQuote' repeat='*'>
			<FieldFormat name='StockSymbol' type='String' delim=':' codepage='windows-1252'/>
			<FieldFormat name='StockPrice' type='String' delim='|' codepage='windows-1252'/>
		</StructFormat>
	</StructFormat>
	<StructFormat name='PriceQuote' repeat='*'>
		<FieldFormat name='StockSymbol' type='String' delim=':' codepage='windows-1252'/>
		<FieldFormat name='StockPrice' type='String' delim='|' codepage='windows-1252'/>
	</StructFormat>
</MessageFormat> 

The following schema build error is reported:

ERROR: Error compiling MFL file - C:\bea\weblogic81\DTGuide\Schemas\StockQuotesSameNameInDiffGroup.mfl:
 StructFormat already defined: PriceQuote 

Note: You can, however, use the same field and group names in different MFL files because the file name of the MFL document becomes the namespace for the field or group format names in WebLogic Workshop, making the field and group format names unique from file to file. For example, the StockPrice field in the Stock.mfl file is prefixed with the namespace:Stocks making it unique from the StockPrice field in the Price.mfl file which is prefixed with the namespace: Price.

Creating Comments

Comments are notes about the message format or the data transformed 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 non-XML 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.



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:



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

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.

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.

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.

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.
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.

Note: 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 a Message Format

You can either save your MFL files directly into a Schemas folder in the file system or you can save the MFL file to the file system and later import the MFL file into a Schemas folder as described in the preceding bullets:

• You can save MFL files directly into a Schemas project folder in the file system. For example, if your application saved in the c:\bea\weblogic81\apps\myApp directory contains the default Schemas project, you can save the MFL file directly into this c:\bea\weblogic81\apps\myApp\Schemas directory in the file system.
• You can save a message format document to your file system as described in this section and later when creating a transformation, you import this MFL file into a Schemas folder of a business process application. To learn more, see Importing Schemas.

To save a message format file for the first time:

1. In the Format builder menu bar, choose File —> Save As.

The Save As dialog box is displayed as shown in the following figure:



2. Navigate to the folder 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 an Existing Message Format File

You can open a message format document on your file system as described in the this section.

To open an existing message format file:

1. In the Format Builder menu bar, choose File —> Open.

The Open dialog box is displayed as shown in the following figure:



2. Locate and select the desired file.
3. Click Open.

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.



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.



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

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 non-XML 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 non-XML 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.

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, 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.

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.

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.

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.

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.

Tools Menu

The following commands are available from the Tools menu.

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.
Options	Displays the Format Builder Options dialog box.

Help Menu

The following commands are available from the Help menu.

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.

Importing Existing Metadata to Create Format Schemas (MFL Files)

WebLogic Integration provides utilities that allow you to import COBOL copybooks, import XML Schemas, and convert C structure definitions into MFL files. The following topics explain how to perform these import operations:

• Importing a COBOL Copybook
• Importing C Structures

Importing a COBOL Copybook

WebLogic Integration includes a feature that allows you to import a COBOL copybook into Format Builder by creating a message definition to transform the COBOL data. When importing a copybook, you can use comments 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 box is displayed.



2. Designate the properties, as described in the following table:

   Property	Value	Description
   File Name	text string	Type the full pathname of the file you want to import or use the Browse button to navigate to the location of the file.
   Byte Order	Big Endian	Select this option for IBM 370, Motorola, and most RISC designs (IBM mainframes and most UNIX platforms).
   	Little Endian	Select this option for Intel, VAX, and Unisys processors (Windows, VMS, Digital, UNIX, and Unisys)
   Character Set Note: The character set is an attribute of the originating host machine.	EBCDIC	Select this option to set the character set to EBCDIC.
   	US-ASCII	Select this option to set the character set to US-ASCII.
   	Other	Select character encoding of the field data by using a list of code pages.

3. Click one of the following:
• OK—imports the COBOL Copybook using the settings you defined.
• Cancel—closes the dialog box and returns you to Format Builder without importing.
• About—displays information about the COBOL Copybook importer, including the version being used and copybook features that are supported.

After you import a copybook, you can work in the same way you work with any message format definition. If you find an error or unsupported data type in the copybook, a message is displayed, informing you of the error. You can choose to have the error displayed or saved in a log file for future reference.

The following table provides a listing and descriptions of the sample files installed for the COBOL copybook importer. All directory names are relative; the specified directories are under the WL_HOME\integration\samples\di directory where WL_HOME is the top-level directory of your WebLogic Platform installation. (For example, if you installed WebLogic Platform in the c:\bea directory, the di directory is located at the following location: c:\bea\weblogic81\integration\samples\di.)

Directory	File	Description
COBOL\	emprec5.cpy	Sample copybook file
COBOL\	emprec5.data	Test data corresponding to emprec5.cpy

Importing C Structures

WebLogic Integration includes a C struct importer utility that converts a C struct definition into an MFL message definition by generating the following types of output data:

• MFL document
• C code

Whichever type of output you want, you must first specify a .c or .h input file, which must be parsed, and then select the desired structure. Then you can choose between MFL (default) or C code for your output.

All input to the parser must be valid C code. In addition, all external references, such as #include, #define, and typedef statements, must be resolved before you can use them. You can resolve them by editing them manually or by using the compiler's preprocessor.

Various platform-specific parameters may affect the description of data for C code. For example, the length of a long on a particular platform affects the non-XML data that conforms to a particular structure definition.

Two methods are available for dealing with these platform dependencies, depending on whether or not MFL is generated directly into Format Builder. If you want to generate MFL and have that MFL displayed immediately in Format Builder, you must supply the platform-dependent parameters in a configuration file.

Alternately, if you choose to generate your source in C, you may compile the C code on the desired machine. The compiler on that machine accounts for the necessary platform-dependent information. This approach allows you to produce an executable file that, when run, produces two files: an MFL document and non-XML data that conforms to that MFL. The MFL document can be opened in Format Builder and the non-XML data file can be opened in Format Tester.

Generating MFL directly into Format Builder requires platform configuration parameters found in an existing configuration file or a new configuration file created with the hardware profile editor. The hardware profile editor allows you to specify an existing profile that can be loaded, updated, and saved.

The source code for a utility that generates hardware profiles according to your needs is provided in the WL_HOME\integration\samples\di\CFG directory where WL_HOME is the top-level directory of your WebLogic Platform installation. (For example, if you installed WebLogic Platform in the c:\bea directory, the cfg directory is located at the following location: c:\bea\weblogic81\integration\samples\di\CFG.)

Sample C Struct Importer Files

The following table provides a listing and descriptions of the sample files installed for the C struct importer. All directory names are relative; the specified directories are under WL_HOME\integration\samples\di directory where WL_HOME is the top-level directory of your WebLogic Platform installation. (For example, if you installed WebLogic Platform in the c:\bea directory, the di directory is located at the following location: c:\bea\weblogic81\integration\samples\di.)

Directory	File	Description
C	emprec5.h	C version of the emprec5.cpy sample Copybook file, with some typedefs.
C	emprec5n.h	Variant of the emprec5.h file in which a nested struct definition, but no typedef is used.
C	emprec5s.h	Simple version of the emprec5.h file.
C	ntfsez.h	Small sample, extracted from the ntfs.h file, designed to test recursive typedefs.
Cfg	cprofile.c	Source code for the cprofile.c utility; designed to generate profiles on various platforms.
The following .cfg files were generated by the cprofile program on various platforms. Each .cfg file contains a value for DESCRIPTION.
Cfg	dec8cc.cfg	DEC Alpha 1091, Digital UNIX 4.0e, cc compiler
Cfg	hp5cc.cfg	HP-UX B.11.00, cc compiler
Cfg	nt4bcc5.cfg	Windows NT 4.0, Borland 5.x compiler, default switches
Cfg	nt4vc6.cfg	Windows NT 4.0, Visual C++ 6.x compiler, default switches
Cfg	sun7cc.cfg	SunOS 5.8, cc compiler
Cfg	w95bcc5.cfg	Windows 95, Borland 5.x compiler, default alignment
Cfg	w95vc5.cfg	Windows 95, Visual C++ 5.x compiler, default alignment

Starting the C Struct Importer

To start the C Struct Importer:

1. Start Format Builder. For instructions, see Starting Format Builder.
2. Choose Tools —> Import —> C Struct Importer.

The C Struct Importer dialog box is displayed.


The C Struct Importer dialog box allows you to specify import properties, as described in the following table:

Note: Initially, MFL is specified as the default output type.

Category	Property	Description
Input	Input File	Type the full pathname of the file you want to import or use the Browse button to navigate to the location of the file.
	Structure	Drop-down list of structures found in the input file after parsing is successful.
	Parse	Select this option to parse the input file. If successful, the Structure list box is populated with the list of structures found in the input file.
Output	MFL	If you select this option, you can generate MFL from a structure definition and a hardware configuration file. The Hardware Profile dialog box is displayed with the following options. Name—Specify an existing profile either by entering the file name or using the Browse option. The prebuilt hardware profiles may be found in the samples\di\cfg directory. Save—saves the current hardware profile. Save As—allows you to save the current hardware profile under another name. Edit—allows you to edit the current hardware profile. New—allows you to create a new hardware profile.
	C Code	If you select this option, you can generate C source code to compile on the target machine and execute to produce MFL. The C Code File Names dialog box is displayed with the following options. MFL Gen—specifies the C source code file name that must be compiled on the target machine to generate MFL. Use the Browse option to navigate to the directory where you want the file to reside. Data Gen—specifies the C source code file name that must be compiled on the target machine for generating test data. Use the Browse option to navigate to the directory where you want the file to reside.

3. Click one of the following:
• OK—saves your hardware profile changes.
• Cancel—dismisses your hardware profile changes.
• About—displays information about the C Struct Importer, including the version number and the release date.

Understanding Hardware Profiles

The hardware profiles used by the C Struct Importer contain data size and alignment information for specific hardware and compiler combinations and are used to generate MFL for C structures. They are stored in configuration files that can be created, loaded, updated, and saved.

The cprofile.c source file in the WL_HOME\integration\samples\di\CFG directory is used to generate these profiles for any platform. This code is designed to be compiled and executed on the target platform with the compiler normally used. You should be able to compile and execute it on any platform with an ANSI standard C compiler in order to generate a profile configuration file that can be imported into the C Struct Importer. (Where WL_HOME is the top-level directory of your WebLogic Platform installation. For example, if you installed WebLogic Platform in the c:\bea directory, the CFG directory is located at the following location: c:\bea\weblogic81\integration\samples\di\CFG.)

Building the Hardware Profile Utility

To produce acceptable parser input, execute the appropriate commands for your platform:

• On Windows NT, use the VC++ preprocessor:

VC++ Compiler
cl /P cprofile.c (output in cprofile.i)

GNU Compiler
gcc -P -E cprofile.c>cprofile.i

• On UNIX

cc -P cprofile.c (output in cprofile.i)

Running the Hardware Profile Utility

To execute the cprofile program and specify a hardware profile name, enter the following text at a command prompt:

cprofile configfilename [DESCRIPTION] 

A description is optional. If you decide to provide one, put it in the configuration file as the value of DESCRIPTION. If the description contains embedded blanks, enclose it in quotes.

Generating MFL

To generate MFL:

1. Enter a filename in the Input File field, or click Browse and select a file from the list that is displayed.
2. Click Parse to parse the file.

Upon completion, the Structure list is populated with the structures found in the input file.

Note: If your file does not parse correctly, we recommend that you proceed in one of two ways:

3. Run your .h or .c source code through the compiler, preprocessor, and then run the processor output through the parser.
4. Comment out the character creating the parsing failure and attempt to parse again. Please note that the parser fails at the first instance of incompatible data it encounters. Therefore, repetition of this step may be required.
3. Select the desired structure from the Structure drop-down list.

At this point, you must provide some profile configuration data to generate the MFL directly. You can do this by either creating a new hardware profile or specifying an existing profile.

4. Specify an existing profile or create a new one by performing one of the following procedures:
• Specify an existing profile in one of the following ways: enter the filename in the Hardware Profile Name field, or click Browse to select a file from the list that is displayed.

Click Edit to open the hardware profile editor if you need to view or edit the profile parameters.

Note: Hardware profiles for common configurations are prebuilt and may be found in the WL_HOME\integration\samples\di\CFG directory. (Where WL_HOME is the top-level directory of your WebLogic Platform installation. For example, if you installed WebLogic Platform in the c:\bea directory, the CFG directory is located at the following location: c:\bea\weblogic81\integration\samples\di\CFG.)

• Click New to create a new hardware profile. The Hardware Profile editor is displayed with the default parameters loaded. Specify a name and description for the new profile, and modify the primitive data types and byte order as required.



5. Click OK to save your hardware profile changes and return to the C Struct Importer dialog box.
6. Click OK to generate your MFL. If the generation is successful, you are returned to Format Builder with an MFL object listed in the navigation tree. The MFL object reflects the same name as the input file used in the parse operation.

If errors are detected during the generation process, the MFL Generation Errors dialog box is displayed providing you with an opportunity to view or file the error log.



7. Click one of the following:
• Display Error Log—to view any errors encountered,
• Save Error Log—to save the error log to the location of your choice, or
• Cancel—to dismiss the MFL Generation Errors dialog box.

After you determine which errors were generated, you can return to the C Struct Importer and repeat the applicable steps.

Generating C Code

To generate C code:

1. Enter a filename in the Input File field, or click Browse and select a file from the list that is displayed.
2. Click Parse to parse the file.

Upon completion, the Structure list is populated with the structures found in the input file.

Note: If your file does not parse correctly, we recommend that you proceed in one of two ways:

3. Run your .h or .c source code through the compiler, preprocessor, and then run the processor output through the parser.
4. Comment out the character creating the parsing failure and attempt to parse again. Please note that the parser fails at the first instance of incompatible data it encounters. Therefore, repetition of this step may be required.
3. Select the desired structure from the Structure drop-down list.
4. Select the C Code option.
5. Enter a filename in either the MFL Gen or Data Gen field, or click Browse and select a file from the list that is displayed.
6. Click OK.

Messages are displayed if you are about to overwrite an existing file or if the code generation has succeeded or failed.

7. Copy the generated source code to the target platform, compile and execute it.

Note: You must copy the input file containing the struct declarations, as well. When compiled, both programs accept the name of the output file as an argument.

8. Copy the generated MFL or data back to the platform on which Format Builder is running.

Importing an XML Schema

WebLogic Integration includes a feature that allows you to import an XML Schema into Format Builder. The imported XML Schema provides a starting point for creating the MFL message definitions used for transforming data between XML and non-XML formats.

To import a XML Schema from an XSD file:

1. Choose Tools —> Import —> XML Schema Importer.

The Select XSD File & Root Element dialog box is displayed.

2. In the XML Schema Definition field, select an XSD file (ends in the .xsd extension.)
3. In the Root Element drop-down menu, select a root element.
4. Enter a value in the MFL Field Delimiter Default field.

A delimiter is a character that marks the end of the data field.

5. Click OK.

Note: Imported Element attributes are not converted.

Testing the Format Schemas (MFL Files)

After you build a format schema, you can test it using the Format Tester. The Format Tester parses and reformats data as a validation test and then generates sample non-XML or XML data. This sample data can be edited, searched, and debugged to produce the expected results. Format Tester uses the data transformation run-time engine to perform the test transformation.

This section discusses the following topics:

• Starting the Format Tester
• Using the Format Tester Dialog Box
• Testing Format Definitions
• Debugging Format Definitions

Starting the Format Tester

To start Format Tester:

1. Start Format Builder is not already running. For instructions, see Starting Format Builder.
2. Choose Tools —> Test.

The Format Tester dialog box is displayed as shown in the following figure:



The Format Tester dialog box is divided into three windows: the Non-XML window, the XML window, and the Debug window. Resize bars divide the windows. You can drag the resize bar to adjust window size, or click an arrow on the bar to show or hide a window. For example, you can click the left arrow on the bar dividing the Non-XML and XML windows to hide the Non-XML window. If a window is hidden, you can drag the bar or click the appropriate arrow to restore the window.

Note: When you open the Format Tester for the first time in a session, only the Non-XML and XML windows are visible. To open the Debug window, use the resize bar at the bottom of the Format Test dialog box, or choose Display —> Debug to toggle the Debug window on and off.

Using the Format Tester Dialog Box

The following topics explain how to use various tools provided in the Format Tester dialog box to navigate and execute commands:

• Using the Non-XML Window
• Using the XML Window
• Using the Debug Window
• Using the Resize Bars
• Using the Menu Bar
• Using the Shortcut Menus

The following topics explain how to use each of these features to help you accomplish your task.

Using the Non-XML Window

The Non-XML window can contain sample data that has been:

• Generated based on the active MFL document.
• Transformed from the contents of the XML window.
• Specifically designed to test the active MFL document.

You can open an existing non-XML data file, edit or save the contents of the window, or clear the window as required for your test situation. For details, see Using the Menu Bar and Using the Shortcut Menus.

The Non-XML window of the Format Tester dialog box serves as a non-XML file editor. The window contains the following tabs:

• Hex—displays data offsets, the hex value of individual bytes, and the corresponding text, which can be displayed in either ASCII or EBCDIC format.
• Text—Text only display.

The editor allows you to edit a hex byte or a text value. If a hex data value is modified, the corresponding text value is updated, and vice versa.

Using the Data Offset Feature

The data offset feature of the Hex tab allows you to display the data offsets as hexadecimal or decimal addresses.

To change the format of the data offsets:

1. Choose Display —> Hex.

The following two data offset options are displayed:

• Offsets as Hexadecimal
• Offsets as Decimal
2. Select an option that best suits your needs. The data offset portion of the Non-XML window changes dynamically to reflect your choice.

Using the Text Feature

The Text tab of the Non-XML window displays the printable characters (usually in the form of words and numbers) and certain control characters (carriage return, tab, and so on). For example, carriage returns are shown as line breaks. Non-printable characters, are displayed as small squares.

Using the XML Window

The XML window can contain sample XML that has been:

• Generated based on the active MFL document.
• Transformed from the contents of the Non-XML window.
• Specifically designed to test the active MFL document.

You can open an existing XML file, edit or save the contents of the window, or clear the window as required for your test situation. For details, see Using the Menu Bar and Using the Shortcut Menus.

When XML is generated, the XML Formatting Options specified in the Format Builder options dialog box are used. For additional information, see Setting Format Builder Options.

Using the Debug Window

The Debug window displays the actions that occur during a transformation, any errors that are encountered, and field and group values, along with delimiters. To determine the cause of an error, identify the last field that parsed successfully and examine the properties of the field listed after it in the navigation tree.

When you open the Format Tester for the first time in a session, only the Non-XML and XML windows are visible. To open the Debug window, choose Display —> Debug to toggle the Debug window on and off. The Debug window opens below the Non-XML and XML windows.

Debug output is restricted to the most recent 64 KB of messages. This restriction prevents large debug output from causing a JVM out of memory event.

The debug log feature allows you to save all debugging information in a file. For details, see Using the Debug Log.

Note: Use of the Debug window or log file increases the time required to transform from XML to non-XML.

Using the Resize Bars

You can change the dimensions of any window in the Format Tester by using the resize bars located between the Non-XML, XML, and Debug windows. To change the size of a window, select a resize bar and drag in the appropriate direction (up or down or to the left or right) to enlarge one of the windows and reduce the other.

Each resize bar also contains two directional buttons. Click the appropriate button to show or hide any of the three windows.

Using the Menu Bar

Format Tester functions can be accessed from the five menus listed in the menu bar at the top of the main window.

You can expand a Format Tester 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 the following sections.

File Menu

The following commands are available from the File menu.

Command	Description
Open Non-XML	Displays the Open dialog box to allow you to select and open a file in the Non-XML window. Note: The default file extension for non-XML files is .DATA.
Open XML	Displays the Open dialog box to allow you to select and open a file in the XML window. Note: The default file extension for XML files is .XML.
Save Non-XML	Displays the Save dialog box to allow you to save the contents of the Non-XML window.
Save XML	Displays the Save dialog box to allow you to save the contents of the XML window.
Debug Log	Displays the Save dialog box to allow you to save the debugging information in a text file.
Close	Closes the Format Tester window.

Edit Menu

The following commands are available from the Edit menu.

Command	Description
Cut	Removes the currently selected text and places it on the clipboard for pasting in another location.
Copy	Copies the currently selected text and places it on the clipboard for pasting in another location.
Paste	Inserts the cut or copied text at the cursor location.
Find	Allows you to search for a hex or text value. This command applies to the content of the Non-XML window only. Note: The text search is case sensitive.
Find Next	Repeats the last Find from the current cursor position. This command applies to the content of the Non-XML window only.
Go To	Allows you to move the cursor to a specified byte offset in the Non-XML window.

Display Menu

The following commands are available from the Display menu.

Command	Description
XML check box	Check to display the XML window, uncheck to hide the window. When unchecked, the Non-XML window expands to fill the Format Tester dialog box.
Debug check box	Check to display the Debug window, uncheck to hide the window.
Clear —> Non-XML	Clears the contents of the Non-XML window.
Clear —> XML	Clears the contents of the XML window.
Clear —> Debug	Clears the contents of the Debug window.
Hex —> Offsets as Hexadecimal option button	Displays the offset values as hexadecimal. Mutually exclusive with the Hex —> Offsets as Decimal option.
Hex —> Offsets as Decimal option button	Displays the offset values as decimal. Mutually exclusive with the Hex —> Offsets as Hexadecimal option.

Generate Menu

The following commands are available from the Generate menu.

Command	Description
Non-XML	Generates non-XML data to match the MFL document specification.
XML	Generates XML data to match the MFL document specification.
Prompt while generating data check box	If checked, you are prompted to specify the following during the generation process: Whether or not to include optional fields or groups in the output. Which choice of children to include in the output. The number of times to include repeating fields or groups in the output.

Transform Menu

The following commands are available from the Transform menu.

Command	Description
Non-XML to XML	Based on the MFL document specification, converts the contents of the Non-XML window to XML. The XML output is displayed in the XML window.
XML to Non-XML	Based on the MFL document specification, converts the contents of the XML window to non-XML data. The non-XML output is displayed in the Non-XML window.

Using the Shortcut Menus

When you right-click in the Non-XML, XML, or Debug window, a menu of the most frequently used commands for that window is displayed. The following table describes the commands that are available from the shortcut menus.

Command	Description
Cut	Removes the currently selected text and places it on the clipboard for pasting in another location.
Copy	Copies the currently selected text and places it in the clipboard for pasting in another location.
Paste	Inserts the cut or copied text at the cursor location.
Clear	Clears the contents of the Non-XML, XML, or Debug window.
Generate	Generates non-XML or XML data to match the MFL document specification. This command is only available on the Non-XML and XML shortcut menus.
To XML	Converts the contents of the Non-XML window to XML. This command is only available on the Non-XML shortcut menu.
To Non-XML	Converts the contents of the XML window to non-XML. This command is only available on the XML shortcut menu.
Text in ASCII	Changes the character set used for the text displayed in the text portion of the Hex tab to ASCII.
Text in EBCDIC	Changes the character set used for the text displayed in the text portion of the Hex tab to EBCDIC.

Testing Format Definitions

To test a message format definition:

1. Start Format Builder.
2. Open a Message Format file.
3. Start Format Tester.
4. Choose File —> Open Non-XML, or File —> Open XML to load the file you want to transform and view, or enter your own data in one of the two data windows.
5. Choose Display —> Debug if you want to view the actions that take place during the transformation operation. This step is optional. If you want to be able to view debugging information later, you must open the Debug window before starting the transformation operation.
6. Choose Transform —> Non-XML to XML, or Transform —> XML to Non-XML to transform your data to the appropriate format.

The transformed data is displayed in the Non-XML or XML window as shown in the following figure:



7. Correct any errors and test the transformation again.
8. Repeat steps 6 and 7 until the transformation is successful.

Note: You can leave Format Tester open while you modify the message format document in Format Builder. Changes to the document are detected automatically by Format Tester.

Debugging Format Definitions

The following topics explain how to use three Format Tester features to debug and correct your data:

• Searching for Values
• Positioning to an Offset
• Using the Debug Log

Searching for Values

The Find command allows you to search for hex or text values in the non-XML data.

To search for a hex or text value:

1. In the Format Tester dialog box, choose File —> Non-XML to open the non-XML data file you want to search.
2. Choose Edit —> Find to open the Find dialog box.



3. Enter the target of the search in the Value field.
4. Select the Text or Hex option button to specify the value type.
5. Select the Forwards or Backwards option button to specify the search direction.
6. Select the Beginning of File, Current Position, or End of File option button to specify the search starting position.
7. Click OK to dismiss the Find dialog box and execute the specified search.

If the value is found, the cursor moves the location of the value. If the value is not found, the following message is displayed: The specified search string was not found.

8. To repeat the search from the current cursor position, choose Edit —> Find Next.

Positioning to an Offset

The Go To command allows you to move the cursor to a specified hexidecimal or decimal address (offset).

To move to a specified offset:

1. In the Format Tester dialog box, choose Edit —> Go To to display the Go To dialog box.



2. Enter the target offset in the Offset field.
3. Select the Dec or Hex option button to specify the type of offset.
4. Select the Forwards or Backwards option button to specify the direction.
5. Select the Beginning of File, Current Position, or End of File option button to specify the starting position.
6. Click OK to dismiss the dialog box and move the cursor to the specified offset.

Using the Debug Log

Although debugging information is not saved by default, the Format Tester dialog box allows you to specify a debug log file. When you specify a debug log file, all debugging information generated during your testing session is appended to the specified file.

To specify a debug log file:

1. In the Format Tester dialog box, choose the File —> Debug Log to display the Save dialog box.

Note: The Debug Log check box on the File menu is toggled upon selection. If the check box is checked, choosing File —> Debug Log turns off logging to the file.

2. Select the desired directory, and then do one of the following:
• To create a new log file, enter the name in the File name field and then click Save.
• To use an existing log file, select the file and then click Save.

If you select an existing file, the new debug information is appended to the end of the existing file.