Defining Data Structures with Message Format Language

21 Defining Data Structures with Message Format Language

This chapter provides instructions for defining MFL structures in JDeveloper, which can then be used in XQuery Mapper tools to automatically transform data between XML and non-XML formats. This chapter also describes how to add MFL resources to projects in the Oracle Service Bus Console.

This chapter includes the following topics:

Introduction to the Format Builder

The Format Builder tool helps you create descriptions of non-XML data records, letting you to describe the layout and hierarchy of the non-XML data so that it can be transformed to or from XML.

With Format Builder, you can describe sequences of bytes as fields. Each field description includes the type of data (floating point, string, and so on), the size of the data, and the name of the field. Format Builder allows you to further define groupings of fields (Groups), repetition of fields and groups, and aggregation.

About MFL Files

The descriptions you create in Format Builder are saved in an XML grammar called Message Format Language (MFL). MFL documents are used at runtime to transform an instance of a non-XML data record to an instance of an XML document (or vice-versa). A Message Format Language (MFL) document is a specialized XML document used to describe the layout of binary data. It is an Oracle proprietary language you can use to define rules that transform formatted binary data into XML data. An MFL document conforms to the mfl.dtd, which includes elements and attributes that describe each field of data, as well as groupings of fields (groups), repetition, and aggregation.

When you create business services or proxy services of Messaging Service type, you can select MFL types as the request message type or the response message type of the service.

Valid Names for Formats, Fields, and Groups

Message formats, fields, and groups are identified by a name. This name is used as the XML tag when non-XML data is transformed to XML. Therefore the name must conform to the XML rules for a name.

The format guidelines for a name are as follows:

Must start with a letter or underscore.
Can contain letters, digits, colon, the period character, the hyphen character, or the underscore character.

The following are valid name examples:

MyField
MyField1
MyField_again
MyField-again

The following are invalid name examples:

1MyField - may not start with a digit

My>Field - the greater-than sign (>) is an illegal character

My Field - a space is not permitted

My/Field - the back slash (/), which is an illegal character

My\Field - the forward slash (\), which is an illegal character

My:Field - a semi-colon (;), which is an illegal character

Supported Character Delimiters

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

Table 21-1 Character Delimiters

Construct	Matches
x	The character x
\\	The backlash
\0n	The character with octal value 0n (<= n <= 7)
\0nn	The character with octal value 0nn (0 <= n <= 7)
\0mnn	The character with octal value 0mnn (0 <= m <= 3, 0 <= n <= 7)
\xhh	The character with hexadecimal value 0xhh
\uhhhh	The character with hexadecimal value 0xhhhh
\xff	The end-of-file (EOF) character
\t	The tab character ('\u0009')
\n	The newline (line feed) character ('\u000A')
\r	The carriage-return character ('\u000D')
\f	The form-feed character ('\u000C')
\a	The alert (bell) character ('\u0007')
\e	The escape character ('\u001B')
\cx	The control character corresponding to x

For more information, see http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html.

Working with MFL Resources in the Oracle Service Bus Console

When you use the Format Builder in JDeveloper to define the hierarchy of a binary record, the layout of fields, and the grouping of fields and groups, the information is saved as an MFL document that can then be used to perform runtime translations.

An MFL document can also be used in Format Builder to generate the corresponding DTD that describes its content model.

How to Create MFL Resources in the Console

You define the message format using the Format Builder in JDeveloper. If you are using the Oracle Service Bus Console, you can create MFL resources to upload the MFL files that you already created in JDeveloper. You can also import the MFL resources into the console. For more information, see Importing and Exporting Resources and Configurations . Use the procedure below to upload an MFL file into an MFL resource.

Before you Begin

Create the MFL file in the Format Builder in JDeveloper, as described in Creating the MFL Message Structure.

To add an MFL resource in the console:

In the Project Navigator, right-click the project or folder to contain the new MFL file, point to Create, and select Resources. Click Transformations, click MFL, and then click OK.

The Create MFL dialog appears.
Click Browse next to the File Upload field and then navigate to and select the MFL file you created in JDeveloper.

The Resource Name field is automatically populated with the file name minus the file extension. You can change this name.
Optionally, enter a brief description of the resource.
Click Create.

The text of the MFL file appear in the MFL Definition Editor.
To modify the schema, do the following:
1. Click Edit Source in the toolbar.
  
  The Edit Source dialog appears.
2. To browse to and select a new MFL file to upload, click Browse.
3. To modify the contents of the file, update the code directly in the Contents section of the dialog.
4. Click Save.
In the MFL Definition Editor toolbar, click Save.
To end the session and deploy the configuration to the runtime, click Activate.

How to Edit MFL Resources in the Console

The recommended way to modify an MFL file is to use the Format Builder in JDeveloper. For more information about working with the Format Builder, see Creating the MFL Message Structure..

If you are using the Oracle Service Bus Console, you can upload the updated file from JDeveloper, or you can modify the code directly in the console (not recommended).

To update an MFL resource in the console:

In the Project Navigator, expand the project and folders containing the MFL resource to edit.
Right-click the resource name, and select Open.
Click Edit Source in the toolbar.

The Edit Source dialog appears.
To browse to and select a new or updated MFL file to upload, click Browse.
To modify the contents of the file, update the code directly in the Contents section of the dialog.
Click Save.
In the MFL Definition Editor toolbar, click Save.
To end the session and deploy the configuration to the runtime, click Activate.

Creating the MFL Message Structure

An MFL message structure can contain one or more fields, groups of fields, references and comments.

Using Drag and Drop in the Format Builder

You can use the drag and drop feature of the Format Builder to copy or move the items in the tree view. To move an item, simply drag and drop the item to its new location. To copy an item, press and hold the CTRL key while you drag and drop the item.

How to Create an MFL File in JDeveloper

Creating an MFL file automatically generates the root node of the message format file with the same name that you give to the MFL file. The root node name must comply with XML element naming conventions because it becomes the root element in the transformed XML document.

To create an MFL file in JDeveloper:

In the Application Navigator, right-click the project or folder to contain the new MFL resource, point to New, and select MFL.

The Create MFL dialog appears.
Enter a name and, optionally, a brief description of the resource.
Click Finish.

The Format Builder appears.
Define the message format using any of the following instructions.

How to Create a Group

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

To create a group:

Select a node in the tree view in the left pane.
Choose Insert > Group > As Child if you want to create the group as the child of the message format or another group. Choose Insert > Group > As Sibling if you want to create the group as the sibling of another group or a field. The Group Details window displays in the right pane.
Enter data in the fields as appropriate.

For additional information and instructions, see Configuring the MFL Message Structure and Group Configuration Window.
Click Apply to save your changes to the message format file, or click Reset to discard your changes to the detail window and reset all fields to the last saved value.

How to Create a Field

Fields are a sequence of bytes that have some meaning to an application. (For example, the field EMPNAME contains an employee name.) You can create a field as a child of the message format item, as a child of a group, or as a sibling of a group or another field.

To create a field:

Select a node in the tree view in the left pane.
Choose Insert > Field > As Child if you want to create the field as the child of the message format or group. Choose Insert > Field > As Sibling if you want to create the group as the sibling of another group or a field. The Field Details window displays in the right pane.
Enter data in the fields as appropriate.

For additional information and instructions, see Configuring the MFL Message Structure and Field Configuration Window.
Click Apply to save your changes to the message format file, or click Reset to discard your changes to the detail window and reset all fields to the last saved value.

How to Reference Groups or Fields

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

Note:

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

To reference a group or field:

Select a field or group in the tree pane.
Choose Edit > Copy.
Choose the proper sibling in the tree.
Choose Edit > Paste > As Reference.
Enter data in the fields as appropriate.

For additional information and instructions, see Configuring the MFL Message Structure and Format Builder Reference Configuration Window.
Click Apply to save your changes to the message format file, or click Reset to discard your changes to the detail window and reset all fields to the last saved value.

How to Add a Comment

Comments contain notes about the message format or the data transformed by the message format. Comments are included in the message format definition for informational purposes only. You can create a comment as a child or sibling of any message format, group, or field.

To add a comment:

Select an item in the tree view in the left pane.
Choose Insert > Comment > As Child if you want to create the comment as the child of the selected item. Choose Insert > Comment > As Sibling if you want to create the comment as the sibling of the selected item. The Comment Details window displays in the right pane.
Enter the comment text.
Click Apply to save your changes to the message format file, or click Reset to discard your changes to the detail window and reset all fields to the last saved value.

Configuring the MFL Message Structure

Once you create a field, group, or reference, you can configure certain attributes, such as whether a node is repeating and how often, or whether a node is fixed length or delimited.

How to Make a Node Recurring

A node can recur a fixed number of times, a number of times specified in the message, or an unlimited number of times.

To make a node recurring:

Double-click the group, field, or reference you want to make recurring in the tree view in the left pane.
In the occurrence section, do any of the following:
- To specify a delimiter the indicates recurrence, select Repeat Delimiter and enter the delimiter value in the associated field.
- To specify a field in the message that will indicate the number of time to repeat, select Repeat Field and then select the name of the field from the list of available options.
- To configure a specific number of times the node repeats, select Repeat Number and enter the number in the associated field.
- If the node can repeat unlimited number of times, select Unlimited.
Click Apply to save your changes to the message format file, or click Reset to discard your changes to the detail window and reset all fields to the last saved value.

How to Define Delimiters

Variable-sized data types can have their termination point specified by a delimiter. A delimiter is a character that marks the end of the field. The field data continues until the delimiter character is encountered. You can specify a delimiter either by reference or by value.

Specifying a Delimiter by Reference

To specify a delimiter by reference:

Select the group or field in the tree view in the left pane.
In the Termination section, select Delimiter.

The Attributes section appears.
Click Ref Fields.

The Select Reference Fields dialog appears.

Figure 21-1 Select Reference Fields

Description of "Figure 21-1 Select Reference Fields"
Select any reference fields in the left pane, and click the right-arrow button to move them into the selected fields pane on the right.
Click OK.
In the Values field, enter a default delimiter in case the reference field does not exist in the message.
Click Apply to save your changes to the message format file, or click Reset to discard your changes to the detail window and reset all fields to the last saved value.

Specifying a Delimiter by Value

To specify a delimiter by value:

Select the group or field in the tree view in the left pane.
In the Termination section, select Delimiter.

The Attributes section appears.
In the Values field, enter the delimiter or delimiters separated by the specified separator character.
For example, in the following list, the delimiter can be a comma, tilde, or semi-colon. The separator is a pipe (|).
```
,|~|;
```
If the field is optional, select the Optional check box. To ensure that the binary data contain the delimiter even if the field is not present, clear the check box.
Click Apply to save your changes to the message format file, or click Reset to discard your changes to the detail window and reset all fields to the last saved value.

Importing and Converting Metadata

Format Builder can import COBOL copybooks and gXML guideline files, and convert a C structure definition into MFL Message Definition.

How to Convert a Guideline XML File

Format Builder lets you import a guideline XML (gXML) file and convert it into a message definition, which you can modify and customize to suit your needs. gXML is an open specification designed to facilitate exchange of e-commerce guidelines for business documents (like purchase orders, invoices and so on) using XML. gXML version 0.71 is supported in this release.

To convert a gXML file:

Choose Tools > Import > EDI Importer.

The EDI Importer dialog appears.
Enter the gXML file path and name, or click Browse to navigate to and select the file to use.
Click OK.

How to Convert an XML Schema

Format Builder lets you import an XML Schema representing the desired XML representation of your non-XML document. This can provide you with a jump-start on specifying the format of your non-XML document.

To convert an XML schema:

Choose Tools > Import > XML Schema Importer.

The XML Schema Importer dialog appears.
Enter the XML schema file path and name, or click Browse to navigate to and select the file to use.
In the Root Element field, select the element from the XML schema to use as the root node for the MFL file.
In the MFL Field Delimiter Default field, enter the default value for the delimiter.
Click OK.

How to Convert a COBOL Copybook

Format Builder lets you import a COBOL copybook into Format Builder and create a message definition to transform the COBOL data. When importing a copybook, comments are used to document the imported copybook and the Groups and Fields it contains.

To convert a COBOL Copybook:

Choose Tools > Import > COBOL Copybook Importer.

The COBOL Copybook Importer dialog appears.
Enter the COBOL Copybook file path and name, or click Browse to navigate to and select the file to use.
Select one of the following:
- Big Endian: Sets the byte order to Big Endian.
  
  Note: This option is used for IBM 370, Motorola, and most RISC designs (IBM mainframes and most Unix platforms).
- Little Endian: Sets the byte order to Little Endian.
  
  Note: This option is used for Intel, VAX, and Unisys processors (Windows, VMS, Digital, Unix, and Unisys).
Select the character set from the following options:
- EBCDIC
- US-ASCII
  
  Note: The above two values are attributes of the originating host machine.
- Other (if you select this option, you must select the character set from the list of available options.
Once you have imported a copybook, you can work with it as you would any message format definition. If an error or unsupported data type is encountered in the copybook, a warning message informs you of the error. You can choose to display the error or save the error to a log file for future reference.

How to Convert C Structures

Format Builder includes a C structure importer utility that converts a C structure definition into an MFL Message Definition by generating MFL or C Code output.

When defining a conversion to MFL, you must provide some profile configuration data to generate the MFL directly. You can do this by creating a new hardware profile, or specifying an existing profile. If the generation is successful, the main Format Builder window appears with the MFL object listed in the navigation tree. The MFL object has 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 displays providing you the opportunity to view or file the error log. Once you have determined what errors were generated, you can return to the C Structure Importer and repeat the prior steps.

To convert a C Structure:

From the Format Builder main window, choose Tools > Import > C Struct Importer.

The C Structure Importer dialog appears.
Enter the path and name of the file to import, or click Browse to navigate to and select a file.
Click Parse.

The Structure field is populated with the list of structures found in the file you selected.
Select the structure you want to convert.
To generate MFL data, do the following:
1. Under Output, select the MFL option.
2. In the Structure field, select the desired structure from the list of available options.
3. In the Name field, select an existing hardware profile, or click New to create a new profile. On the dialog that appears, specify a name and description, modify the primitive data types and byte order, and click OK.
  
  Click Edit to open the hardware profile editor if you need to view or edit the profile parameters.
4. Click OK to generate the MFL file.
5. Click Display Error Log to view any errors encountered, click Save Error Log to save the error log to the location of your choice, or click Cancel to dismiss the MFL Generation Errors dialog box.
To generate C code, do the following:
1. Under Output, select the C Code option.
2. Enter a file name in either the MFL Gen or Data Gen field, or click Browse to select a file.
3. Click OK.
  
  You will be warned about overwriting existing files and notified about the success or failure of the code generation.
4. Copy the generated source code to the platform in question and compile and execute it.
  
  Note:
  
  You must copy the input file containing the structure declarations as well. Both programs, when compiled, take an argument of the output file name.
5. Copy the generated MFL or data back to the platform running Format Builder.

How to Convert an FML Field Table Class

The FML Field Table Class Importer facilitates the integration of WebLogic Tuxedo Connector and business process management (BPM) functionality. Tuxedo application buffers are translated to and from XML by the FML to XML Translator that is a feature of WebLogic Tuxedo Connector. The integration of Tuxedo with BPM functionality requires the creation of the XML that is passed between the WebLogic Tuxedo Connector Translator and the process engine. To create the necessary XML, use the FML Field Table Class Importer and the XML generation feature of Format Tester.

Before You Begin

Move the field tables associated with the FML buffer from the Tuxedo system to the WebLogic Server/WebLogic Tuxedo Connector environment.
Use the weblogic/wtc/jatmi/mkfldclass utility to build Java source code representing the field tables. For information about FML field table administration, see the WebLogic Server documentation.
Compile the source code. The resulting class files are called fldtbl classes because they implement the FldTbl interface. These class must be packaged in a JAR file that can be selected from the FML Field Table Class Importer dialog.

Note:

Because most users perform these steps when configuring WebLogic Tuxedo Connector, these class files may already exist. If you create Java classes using WebLogic Tuxedo Connector, you can place the .class files in the \ext directory. You can then populate the Available Fields list automatically from the FML Field Table Class Importer dialog box.

To create an XML document with the FML Field Table Class Importer:

Choose Tools > Import > EDI Importer.

The FML Field Table Class Importer dialog appears.
Click Select to select the JAR file containing the fldtbl classes.

The fldtbl classes are displayed in the Classes list. If the selected JAR file contains no fldtbl classes, an error message appears and the Fld Table Jar File and Classes fields are cleared.
In the Classes section, select one or more fldtbl class names from the list of available classes.
In the Available Fields list, select the fields from the list of options and then click Add.

This list does not allow duplicate names. Even if the name of a field appears in different field tables, it is included only once in the list.
To remove any fields added in error to the Selected Fields list, select the fields and click Remove.
Click OK.
Enter data in the fields as described in the following table:
Edit the created MFL document to specify the order and number of occurrences of the fields in the XML document to be passed to the WebLogic Tuxedo Connector FML/XML Translator from business process management (BMP).
Choose Tools > Test to display the Format Tester tool.
From the Format Tester menu bar, choose Generate > XML to create an XML document that conforms to the MFL document in Format Builder.
Edit the data content of the fields in the XML document as desired.
From the Format Tester menu bar, choose File > Save XML to save the XML document in a file with a specified name and location.

The created XML can be imported and used in business process management functions by using the XML instance editor. For information about importing XML, see the BPM documentation.

Deleting MFL Resources

If any resources reference the MFL file you want to delete, remove those references before deleting the file.

You can delete the MFL resource even if it is referenced by other resources, though this might result in conflicts due to unresolved references to the deleted resource.

How to Delete an MFL Resource

Before deleting an MFL resource, check for any references or dependencies. In the Oracle Service Bus Console, open the MFL file in the MFL Definition Editor and click the Tools icon in the upper right, and then select References to find out whether any services are using it. In JDeveloper, right-click the MFL file and select Explore Dependencies.

To delete an MFL resource:

In the Application Navigator or Project Navigator, expand the project and folders containing the XSL transformation to delete.
Right-click the name of the MFL file, and select Delete.
If you are using JDeveloper, a confirmation dialog displays the number of references for the MFL resource. Click Show Usages to view information about the references, and then click Yes to confirm that you want to delete the resource.
If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

Testing Format Definitions

Once you have built a format definition, you can test it using Format Tester.

Format Tester parses and reformats data as a validation test and generates sample non-XML or XML data. This sample data can be edited, searched, and debugged to product the expected results.

How to Start Format Tester

Format Tester is launched from the Format Builder and opens in a separate window.

To start Format Tester:

In Format Builder, open a message format document (MFL file).

Note:

To run Format Tester, you must have a message format document open in Format Builder.
From the Format Builder menu bar, choose Tools > Test.
The Format Tester dialog box appears.

Format Tester uses the currently loaded message definition document.

How to Test Using the Non-XML Window

The Non-XML data display panel acts as a hexadecimal editor or a text editor, depending on which tab is selected.

The hexadecimal editor panel displays data offsets, the hex value of individual bytes, and the corresponding text. The corresponding text can be optionally displayed as ASCII or EBCDIC characters. The editor allows for editing of the hex byte or the 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 hexadecimal editor allows you to display your data offsets as Hexadecimal or Decimal.

To change your data offsets:

Choose Display > Hex. The following two data offset options display.

Offsets as Hexadecimal
Offsets as Decimal

Click the display option that best suits your needs. The data offset panel of the Non-XML window dynamically changes to reflect your choice.

Using the Text Feature

To use the Text feature, select the Text tab from within the Non-XML window to view all printable characters, such as carriage returns. The Text window shows these as text with line breaks.

How to Test Using the XML Window

The XML data panel displays XML data that has been converted or transformed from the contents of the Non-XML panel. The contents of the XML panel can be cleared or edited to suit your needs.

You can also use this window to enter or generate the XML data to be transformed into non-XML format.

How to Test Using the Debug Window

The Debug window displays the actions that take place during the transformation operation, any errors that are encountered, and field and group values and delimiters. To determine the location of the error, determine the last field that parsed successfully and examine the specification of the next field on the tree pane of Format Builder.

When you open the Format Tester, 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.

Note:

Debug output is restricted to the most recent 64 KB of messages. Full debug information can be captured to a file. See Using the Debug Log for more information.

How to Debug Format Definitions

The following topics discuss the various Format Tester utilities you can use to debug and correct your data.

Searching for Values

The Find feature allows you to search for hex or text values in the Non-XML data. The following fields are available from the Find dialog.

To search for values:

From within the Format Tester, choose File > Open Non-XML to open the non-XML data file you want to search.
Choose Edit > Find.

The Find dialog appears.

Enter data in the fields as appropriate. See Table 21-2.

Table 21-2 Find Options

Field	Description
Value	Enter the value you want to find.
Text	Select this option if you want to find a text value.
Hex	Select this option if you want to find a hex value.
Forwards	Select this option if you want to search from the selected location to the end of the document.
Backwards	Select this option if you want to search from the selected location to the beginning of the document.
Beginning of File	Select this option if you want to start the search at the beginning of the file.
Current Position	Select this option if you want to start the search at the current cursor location.
End of File	Select the option if you want to start the search at the end of the file.
OK Button	Begins the search operation.
Cancel Button	Closes the Find dialog without performing a search.

Click OK to begin the Search operation.

Searching for Offsets

The Goto feature allows you to move the cursor in the Non-XML editor to a byte offset you specify. The following fields are available from the Goto dialog.

To move to a specified offset:

From within the Format Tester, choose File > Open Non-XML to open the non-XML data file you want to search.
Choose Edit > Go To.

The Goto dialog appears.

Enter data in the fields as appropriate. See Table 21-2.

Table 21-3 Goto Options

Field	Description
Offset	Enter the offset value you want to find.
Dec	Select this option if you want to go to a decimal value.
Hex	Select this option if you want to go to a hex value.
Forwards	Select this option if you want to search from the selected location to the end of the document.
Backwards	Select this option if you want to search from the selected location to the beginning of the document.
Beginning of File	Select this option if you want to start the search at the beginning of the file.
Current Position	Select this option if you want to start the search at the current cursor location.
End of File	Select the option if you want to start the search at the end of the file.
OK Button	Begins the search operation.
Cancel Button	Closes the Goto dialog without performing a search.

Click OK to begin the Search operation.

Using the Debug Log

The debug log allows you to save your debug information to a text file.

To use the debug log:

Select File > Debug Log.

A dialog appears, where you can enter a new path and file name or choose an existing file in which to save the debug information.

Note:

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

Format Tester Command Reference

This section describes the commands available from the Format Tester main menu.

File Menu

The following commands are available from the File menu.

Element	Description
Open Non-XML	Lets you select a non-XML file to be displayed in the Non-XML window. Note: The default file extension for non-XML files is.DATA.
Open XML	Lets you select a file to be displayed in the XML section of the Format Tester window. Note: The default file extension for XML files is.XML
Save Non-XML	Saves the contents of the Non-XML window.
Save XML	Saves the contents of the XML window.
Debug Log	Saves the debug information in a text file.
Close	Closes the Format Tester window.

Edit Menu

The following commands are available from the Edit menu.

Element	Description
Cut	Removes the currently selected text and places it on the clipboard for pasting into another location.
Copy	Copies the currently selected text and places it on the clipboard for pasting into another location.
Paste	Inserts the cut or copied text at the cursor location.
Find	Lets you to search for a hex or text value in the non-XML data.
Find Next	Continues your search to the next instance of the specified value.
Go To	Lets you move the cursor in the Non-XML editor to a specified byte offset.

Display Menu

The following commands are available from the Display menu.

Element	Description
XML	Lets the XML data panel be hidden or shown. If hidden, the non-XML data window expands to fill the width of the tester. The To XML button remains, but the splitter disappears.
Debug	Lets the Debug output window be hidden or shown.
Clear > Non-XML	Resets the contents of the Non-XML data window to be empty.
Clear > XML	Resets the contents of the XML window to be empty.
Hex > Offsets as Hexadecimal	Displays the offset values as hexadecimal. Selecting this option turns off the Offsets as Decimal display.
Hex > Offsets as Decimal	Displays the offset values as decimal. Selecting this option turns off the Offset as Hexadecimal display.

Generate Menu

The following commands are available from the Generate menu.

Element	Description
Non-XML	Generates non-XML data to match the current format specification.
XML	Generates XML data to match the current format specification.
Prompt while generating data	Select this option if you want to be prompted during the generation process to determine if optional fields or groups should be generated, determine which choice of children should be generated, and determine how many times a repeating group should repeat.

Transform Menu

The following commands are available from the Transform menu.

Element	Description
Non-XML to XML	Converts the contents of the Non-XML window to XML.
XML to Non-XML	Converts the contents of the XML window to non-XML data.

Using the Palette

The Format Builder palette allows you to store commonly used message format items and insert them into your message format definitions.

These items are stored in an XML document, and you can use the standard Windows drag and drop feature to copy items from the palette into your message format definition.

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

How to Display the Palette Window

To turn the palette display on or off, choose View > Show palette. If the palette is not currently displayed, it opens in a separate window next to the Format Builder window. If the palette is currently displayed, its window closes.

How to Add Items to the Palette

You cannot add nodes to the palette that depend on the existence of another node to the palette. For example, you cannot add Field or Group References, and you cannot add items that have a Repeat Field specified. You can add comments, but this is not recommended since comments do not have unique names and therefore are indistinguishable on the palette.

To add items to the palette:

From the navigation tree, choose the item you want to add to the palette.
Click and hold the left mouse button and drag the item into the palette window.
When the item is placed in the position you want it (as a sibling of the selected item), release the mouse button. The item is copied from the navigation tree to the palette window.

How to Add Palette Items to a Message Format

To copy items from the palette to a message format:

From the palette window, choose the item you want to add to your message format.
Click and hold the left mouse button and drag the item into the left pane of the Format Builder window.
When the item is placed in the position you want it (as the child or sibling of the desired item), release the mouse button. The item is copied from the palette to the message format.

Format Builder Supported Data Types

This section provides information about MFL data types, COBOL Copybook Importer data types, and unsupported C language features.

MFL Data Types

Table 21-4 lists the MFL data types that data transformer supports. These are metadata data types used in non-XML to XML or XML to non-XML conversions, and are specified in the "type" attribute of a Field Format element.

Table 21-4 Supported MFL Data Types

Data Type	Description
Binary (Base64 encoding)	Any character value accepted. Requires a length, length field, delimiter, or a delimiter field. Resulting XML data for this field is encoded using base-64.
Binary (Hex encoding)	Any character value accepted. Requires a length, length field, delimiter, or a delimiter field. Resulting XML data for this field is encoded using base-16.
Date: DD-MMM-YY	A string defining a date;for example, for example, 22-JAN-00.
Date: DD-MMM-YYYY	A string defining a date; for example,; for example, 22-JAN-2000.
Date: DD/MM/YY	A string defining a date; for example, 22/01/00.
Date: DD/MM/YYYY	A string defining a date; for example, 22/01/2000.
Date: DDMMMYY	A string defining a date; for example, 22JAN00.
Date: DDMMMYYYY	A string defining a date; for example, 22JAN2000.
Date: MM/DD/YY	A string defining a date; for example, 01/22/00.
Date: MM/DD/YYYY	A string defining a date; for example, 01/22/2000.
Date: MMDDYY	A six digit numeric string defining a date; for example, 012200.
Date: MMDDYYYY	An eight digit numeric string defining a date; for example, 01222000.
Date: MMM-YY	A string defining a date; for example, JAN-00.
Date: MMM-YYYY	A string defining a date; for example, JAN-2000.
Date: MMMDDYYYY	A string defining a date; for example, JAN222000.
Date: MMMYY	A string defining a date; for example, JAN00.
Date: MMMYYYY	A string defining a date; for example, JAN2000.
Date: Wed Nov 15 10:55:37 CST 2000	The default date format of the Java platform; for example, 'WED NOV 15 10:55:37 CST 2000'
Date: YY-MM-DD	A string defining a date; for example, 00-01-22. (The string: 00-01-22 defines the date January 22, 2000.)
Date: YY/MM/DD	A string defining a date; for example, 00/01/22. (The string: 00/01/22 defines the date January 22, 2000.)
Date: YYMMDD	A string defining a date; for example, 000122. (The string: 000122 defines the date January 22, 2000.)
Date: YYYY-MM-DD	A string defining a date; for example, 2000-01-22. (The string: 2000-01-22 defines the date January 22, 2000.)
Date: YYYY/MM/DD	A string defining a date; for example, 2000/01/22. (The string: 2000/01/22 defines the date January 22, 2000.)
Date: YYYYMMDD	An eight byte numeric string of the format YYYYMMDD. A base data of String or EBCDIC may be specified to indicate the character encoding.
DateTime: DD/MM/YY hh:mm	A string defining a date and time; for example, 22/01/00 12:24.
DateTime: DD/MM/YY hh:mm AM	A string defining a date and time; for example, 22/01/00 12:24 AM.
DateTime: DD/MM/YY hh:mm:ss	A string defining a date and time; for example, 22/01/00 12:24:00.
DateTime: DD/MM/YY hh:mm:ss AM	A string defining a date and time; for example, 22/01/00 12:24:00 AM.
DateTime: MM/DD/YY hh:mm	A string defining a date and time; for example, 01/22/00 12:24.
DateTime: MM/DD/YY hh:mi AM	A string defining a date and time; for example, 01/22/00 12:24 AM.
DateTime: MM/DD/YY hh:mm:ss	A string defining a date and time; for example, 01/22/00 12:24:00.
DateTime: MM/DD/YY hh:mm:ss AM	A string defining a date and time; for example, 01/22/00 12:24:00 AM.
DateTime: MMDDYYhhmm	A string of numeric digits defining a date and time; for example, 0122001224.
DateTime: YYYYMMDDhhmmss	A fourteen byte numeric string of the format YYYYMMDDHHMISS. A Base data type may be specified.
DateTime: MMDDYYhhmmss	A string of numeric digits defining a date and time; for example, 012200122400.
EBCDIC	A string of characters in IBM Extended Binary Coded Decimal Interchange Code. Requires a length, length field, delimiter, or a delimiter field.
Filler	A sequence of bytes that is not transformed to XML. This field of data is skipped over when transforming non-XML data to XML. When transforming XML to non-XML data, this field is written to the binary output stream as a sequence of spaces.
FloatingPoint: 4 bytes, Big-Endian	A four byte big endian floating point number that conforms to the IEEE Standard 754.
FloatingPoint, 4 bytes, Little-Endian	A four byte little endian floating point number that conforms to the IEEE Standard 754.
FloatingPoint: 8 bytes, Big-Endian	A eight byte big endian floating point number that conforms to the IEEE Standard 754.
FloatingPoint: 8 bytes, Little-Endian	A eight byte little endian floating point number that conforms to the IEEE Standard 754.
Integer: Signed, 1 byte	A one byte signed integer; for example, '56' is 0x38.
Integer: Unsigned, 1 byte	A one byte unsigned integer; for example, '128' is 0x80.
Integer: Signed, 2 byte, Big-Endian	A signed two-byte integer in big endian format; for example, '4660' is 0x1234.
Integer: Signed, 4 byte, Big-Endian	A signed four-byte integer in big endian format; for example, '4660' is 0x00001234.
Integer: Signed, 8 bytes, Big-Endian	A signed eight-byte integer in big endian format; for example, '4660' is 0x0000000000001234.
Integer: Unsigned, 2 byte, Big-Endian	An unsigned two-byte integer in big endian format; for example, '65000' is 0xFDE8.
Integer: Unsigned, 4 byte, Big-Endian	An unsigned four-byte integer in big endian format; for example, '65000' is 0x0000FDE8.
Integer: Unsigned, 8 bytes, Big-Endian	A unsigned eight-byte integer in big endian format; for example, '65000' is 0x000000000000FDE8.
Integer: Signed, 2 bytes, Little-Endian	A signed two-byte integer in little endian format; for example, '4660' is 0x3412.
Integer: Signed, 4 bytes, Little-Endian	A signed four-byte integer in little endian format; for example, '4660' is 0x34120000.
Integer: Signed, 8 bytes, Little-Endian	A signed eight-byte integer in little endian format; for example, '4660' is 0x3412000000000000.
Integer: Unsigned, 2 bytes, Little-Endian	An unsigned two-byte integer in little endian format; for example,'65000' is 0xE8FD.
Integer: Unsigned, 4 bytes, Little-Endian	An unsigned four-byte integer in little endian format; for example, '65000' is 0xE8FD0000.
Integer: Unsigned, 8 bytes, Little-Endian	A unsigned eight-byte integer in little endian format; for example, '65000' is 0xE8FD000000000000.
Literal	A literal value determined by the contents of the value attribute. When non-XML data is transformed to XML, the presence of the specified literal in the non-XML data is verified by WLXT. The literal is read, but is not transformed to the XML data. When XML data is transformed to a non-XML format, and a literal is defined as part of the non-XML format, WLXT writes the literal in the resulting Non-XML byte stream.
Numeric	A string of characters containing only digits; for example, '0' through '9'. Requires a length, length field, delimiter, or a delimiter field.
Packed Decimal: Signed	IBM signed packed format. Requires a length, length field, delimiter, or a delimiter field to be specified. The length or length field should specify the size of this field in bytes.
Packed Decimal: Unsigned	IBM unsigned packed format. Requires a length, length field, delimiter, or a delimiter field to be specified. The length or length field should specify the size of this field in bytes.
String	A string of characters. Requires a length, a length field, a delimiter, or a delimiter field. If no length, length field, or delimiter is defined for a data type String, a delimiter of "\x00" (a NUL character) will be assumed.
String: NUL terminated	A string of characters, optionally NUL (\x00) terminated, residing within a fixed length field. This field type requires a length attribute or length field which determines the amount of data read for the field. This data is then examined for a NUL delimiter. If a delimiter is found, data following the delimiter is discarded. If a NUL delimiter does not exist, the fixed length data is used as the value of the field.
Time: hhmmss	A string defining a time; for example, 122400.
Time: hh:mm AM	A string defining a time; for example, 12:24 AM.
Time: hh:mm	A string defining a time; for example, 12:24.
Time: hh:mm:ss AM	A string defining a time; for example, 12:24:00 AM.
Time: hh:mm:ss	A string defining a time; for example, 12:24:00.
Zoned Decimal: Leading sign	Signed zoned decimal format (US-ASCII or EBCDIC) where the sign indicator is in the first nibble. Requires a length, length field, delimiter, or a delimiter field to be specified. The length or length field should specify the size of this field in bytes. Note: This data type is supported with US-ASCII data only with Message Format Language Version 2.02
Zoned Decimal: Leading separate sign	Signed zoned decimal format (US-ASCII or EBCDIC) where the sign indicator is in the first byte. The first byte only contains the sign indicator and is separated from the numeric value. Requires a length, length field, delimiter, or a delimiter field to be specified. The length or length field should specify the size of this field in bytes. Note: This data type is supported with US-ASCII data only with Message Format Language Version 2.02.
Zoned Decimal: Signed	Signed zoned decimal format (US-ASCII or EBCDIC). Requires a length, length field, delimiter, or a delimiter field to be specified. The length or length field should specify the size of this field in bytes. Note: This data type is supported with US-ASCII data only with Message Format Language Version 2.02.
Zoned Decimal: Trailing separate sign	Signed zoned decimal format (US-ASCII or EBCDIC) where the sign indicator is in the last byte. The last byte only contains the sign indicator and is separated from the numeric value. Requires a length, length field, delimiter, or a delimiter field to be specified. The length or length field should specify the size of this field in bytes. Note: This data type is supported with US-ASCII data only with Message Format Language Version 2.02.
Zoned Decimal: Unsigned	Unsigned zoned decimal format (US-ASCII or EBCDIC). Requires a length, length field, delimiter, or a delimiter field to be specified. The length or length field should specify the size of this field in bytes. Note: This data type is supported with US-ASCII data only with Message Format Language Version 2.02.

COBOL Copybook Importer Data Types

The Format Builder tool provides a utility for the conversion of COBOL copybooks into MFL files. Table 21-5 lists the COBOL data types that can be converted to metadata data types and the support provided by the Importer. Support for these data types is limited. For example, the following formats are converted to an unsigned 4-byte integer type:

05 pic 9(5) comp-5
05 pic 9(5) comp-x

Additionally, the following generate errors:

05 pic X(5) comp-5
05 pic X(5) comp-x

In these samples, pic9(5) could be substituted for pic x(5).

The following values are defined as follows:

Supported: The data type will be correctly parsed by the importer and converted to a message format field or group.
Unsupported: The data type is not supported and the importer reports an error when the copybook is imported.
Ignored: The data type is parsed and a comment is added to the message format. No corresponding field or group is created.

Table 21-5 COBOL Data Types

COBOL Type	Support
BLANK WHEN ZERO (zoned)	supported
COMP-1, COMP-2 (float)	supported
COMP-3, PACKED-DECIMAL	supported
COMP, COMP-4, BINARY (integer)	supported
COMP, COMP-4, BINARY (fixed)	supported
COMP-5, COMP-X	supported
DISPLAY (alphanumeric)	supported
DISPLAY numeric (zoned)	supported
edited alphanumeric	supported
edited float numeric	supported
edited numeric	supported
group record	supported
INDEX	supported
JUSTIFIED RIGHT	ignored
OCCURS (fixed array)	supported
OCCURS DEPENDING (variable-length)	supported
OCCURS INDEXED BY	ignored
OCCURS KEY IS	ignored
POINTER	supported
PROCEDURE-POINTER	supported
REDEFINES	supported
SIGN IS LEADING SEPARATE (zoned)	supported
SIGN IS TRAILING (zoned)	supported
SIGN IS TRAILING SEPARATE (zoned)	supported
SIGN IS LEADING (zoned)	supported
SYNCHRONIZED	ignored
66 RENAMES	not supported
66 RENAMES THRU	not supported
77 level	supported
88 level (condition)	ignored

Some vendor-specific extensions are not recognized by the importer, however, any copybook statement that conforms to ANSI standard COBOL will be parsed correctly by the Importer. The Importer's default data model, which is based on the IBM mainframe model, can be changed in Format Builder to compensate for character set and data "endianness."

When importing copybooks, the importer may identify fields generically that, upon visual inspection, could easily be identified by a more specific data type. For this reason, the copybook importer creates comments for each field found in the copybook. This information is useful in assisting you in editing the MFL data to better represent the original copybook.

For example, this original copybook entry:

05 birth-date    picxx/xx/xx

results in s field of type EBCDIC with a length of 8. Closer inspection indicates that this is intended to be a date format and could be defined as a field of type Date: MM/DD/YY or a field of type Data: DD/MM/YY.

Unsupported C Language Features

The Format Builder provides a utility for the conversion of C structures into MFL files. This section lists the C Language constructs that cannot be converted to metadata data types. (This conversion occurs at design time.) The C struct Importer utility does not parse files containing anonymous unions, bit fields, or in-line assembler code. The following samples of unsupported features are taken from the preprocessor output of a hello.c file that contained a #include <windows.h> statement:

Anonymous unions

#line 353 "e:\\program files\\microsoft visual studio\\vc98\\include\\winnt.h"
typedef union_LARGE_INTEGER{
  struct {
    DWORD LowPart;
    LONG HighPart;
  };
  struct {
    DWORD LowPart;
    LONG HighPart;
  } u;
#line 363 "e:\\program files\\microsoft visual studio\\vc98\\include\\winnt.h"
    LONGLONG QuadPart;
} LARGE_INTEGER

Bit fields

typedef struct_LDT_ENTRY {
  WORD LimitLow;
  WORD BaseLow;
  union {
    struct {
      BYTE BaseMid;
      BYTE Flags1;
      BYTE Flags2;
      BYTE BaseHi;
    } Bytes;
    struct
      DWORD BaseMid : 8;
      DWORD Type : 5;
      DWORD Dpl : 2;
      DWORD Pres : 1;
      DWORD LimitHi : 4;
      DWORD Sys : 1;
      DWORD Reserved_0 : 1;
      DWORD Default_Big : 1;
      DWORD Granularity : 1;
      DWORD BaseHi : 8;
    } Bits;
  } HighWord;
} LDT_ENTRY, *PLDT_ENTRY;

Inline assembler code

_inline ULONGLONG
_stdcall
Int64ShrlMod32(
  ULONGLONG Value,
  DWORD ShiftCount
  )
{
  _asm {
   mov ecx, ShiftCount
   mov eax, dword ptr [Value]
   mov edx, dword ptr [Value+4]
   shrd eax, edx, cl
   shr edx, cl
  }
}

Format Builder Field Reference

This section describes the Format Builder windows and each of the properties displayed on the Format Builder windows.

Format Builder Window

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

Format Builder Tool Bar

Use the following Menu bar options to create and configure the structure of the MFL file. The menus that are available depend on what is selected in the left pane.

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

Format Builder Tree Pane

The Tree Pane represents hierarchical and structural information about the format of the non-XML data in a tree. The root node of the tree corresponds to the MFL document being created or edited, and you can create groups and fields under the root node. Following are the different types of elements you can create in the tree pane.

Message formats, fields, and groups are identified by a name, which is used as the XML tag when non-XML data is transformed to XML. Therefore the name must conform to the XML rules for a name.

Follow these guidelines when naming the nodes in your format tree:

Names must start with a letter or underscore.
Names can contain letters, digits, colon, the period character, the hyphen character, or the underscore character.

Element	Description
Message Format	The top level, or root, element.
Group	A collection of fields, comments, and other groups or references that are related in some way. For example, the fields `PAYDATE`, `HOURS`, and `RATE` could be part of the `PAYINFO` group. This defines the formatting for all items contained in the group.
Optional Group	A group that may or may not be included in the message format. This type of group is represented by a dotted line around its icon.
Repeating Group	A group that has one or more occurrences. This type of group is represented by a cascading icon.
Optional Repeating Group	A group that may or may not be included, but if included, occurs more than once.
Group Reference	An indicator that another instance of the group exists in the data. Reference groups have the same format as the original group, but you can change the optional setting and the occurrence setting for the reference group.
Group Choice	An indicator that only one of the items in the group will be included in the message format. This type of group is represented by a dot inside the icon.
Field	A sequence of bytes that have some meaning to an application. For example, the field `EMPNAME` might contain an employee name. Defines the formatting for the field.
Optional Field	A field that may or may not be included in the message format.
Repeating Field	A field that has one or more occurrences.
Field Reference	An indicator that another instance of the field exists in the data. Reference fields have the same format as the original field, but you can change the optional setting and the occurrence setting for the reference field.
Optional Repeating Field	A field that may or may not be included, but, if included, occurs more than once in the message format.
Comment	An indicator that contains notes about the message format or the data transformed by the message format.
Collapse	A minus sign next to an object indicates that it can be collapsed.
Expand	A plus sign next to an object indicates that it can be expanded to show more objects.

Field Configuration Window

The Field Configuration window defines the fields contained in the message format. These fields are a sequence of bytes that have a meaning in terms of an application. For example, the field EMPNAME means employee name.

Table 21-6 Format Builder Field Description Properties

Element	Description
Name	The name of the field. This name must comply with XML element naming conventions.
Optional	Select this check box to make the field optional. Selecting this means that the data for the field may be present in the input. If this option is selected for a file, then you can set the Field is Tagged option from the Field Attributes pane. In addition to it, enter a unique value for each optional field in a group in the Field Is Tagged text box. 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 list of available options. The default type is String. Note: The Field Type that is selected dictates the Field Data Options that appear on the rest of the dialog

Element

Description

Name

The name of the field. This name must comply with XML element naming conventions.

Optional

Select this check box to make the field optional. Selecting this means that the data for the field may be present in the input.

If this option is selected for a file, then you can set the Field is Tagged option from the Field Attributes pane. In addition to it, enter a unique value for each optional field in a group in the Field Is Tagged text box. 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 list of available options. The default type is String.

Note: The Field Type that is selected dictates the Field Data Options that appear on the rest of the dialog

Select one of the options in Table 21-7 to indicate how often this field appears in the message format.

Table 21-7 Format Builder Field Occurrence Properties

Element	Description
Once	Select this option if the field appears only once. Note: Unless a field is defined as optional, the field occurs at least once.
Repeat Delimiter	Select this option if the field repeats until the specified delimiter is encountered. Enter the delimiter in the associated field.
Repeat Field	Select this option if the value of the repeat field at runtime is the number of times the field repeats. Select the repeat field name from the list of available options.
Repeat Number	Select this option if the field repeats a specified number of times. Enter the number of recurrences in the associated field.
Unlimited	Select this option if the field repeats an unlimited number of times.

Table 21-8 Format Builder Field Attributes

Element	Description
Field is Tagged	Select this option if the field is a tagged field. Being tagged means that a literal precedes the data, indicating that the data is present. For example: `SUP:ACME INC, SUP:` is a tag. `ACME INC` is the field data. If you have selected the Field is Tagged option, enter the tag in the text box to the right of the check box.
Field Default Value	Select this option if the field has a default value. Then, enter the default value in the text box to the right of the check box.
Data Base Type	An indicator that determines the type of characters that make up the data if the field is a date or time field. Whether this field appears is based on the data type selected in the Type field in the Field Description section.
Year Cutoff	If the field is a date field that has a 2-digit year, the year cutoff allows the 2-digit year to be converted to a 4-digit year. If the 2-digit year is greater than or equal to the year cutoff value, a '19' prefix will be added to the year value. Otherwise a '20' prefix will be used. Whether this field appears is based on the data type selected in the Type field in the Field Description section.
Code Page	The code page encodes the String field data. Whether this field appears is based on the data type selected in the Type field in the Field Description section.
Value	The value that appears in a literal field. Whether this field appears is based on the data type selected in the Type field in the Field Description section.

Table 21-9 Format Builder Field Termination Properties Defined by Length

Element	Description
Length Tab
Value	Enter the number of bytes in the length field if the length field is a variable length. Variable-sized data types can be assigned a fixed length, eliminating the need to use a delimiter to specify the termination point of the field.
String Length in Characters	Select this check box if string is multi-byte encoded to calculate the length in number of characters instead of bytes. By default, the string length is in bytes.
Trim Tab
Trim Trailing	Select this option to trim data from the trailing edge of the field data. Enter the data to be trimmed in the field next to this option.
Trim Leading	Select this option to trim data from the leading edge of the field data. Enter the data to be trimmed in the field next to this option.
Pad Tab
Pad Value	Select this option if the data is shorter than the specified length, and enter the necessary value add to the data until it is of correct length. Select Trailing to append padding at the end of a field. Select Leading to append padding at the beginning of a field.

Table 21-10 Format Builder Field Termination Properties Defined by Imbedded Length

Element	Description
Description Tab
Type	Select the type of the imbedded length from the list of options.
Length	Select the this option to specify the number of bytes, and then enter the number in the corresponding field. Variable-sized data types can have their termination point specified by an imbedded length. An imbedded length precedes the data field and indicates how many bytes the data contains. This option is only available for certain data types selected for the imbedded length.
Delimiter	Select the this option to specify a delimiter, and then enter the delimiter value in the corresponding field. This option is only available for certain data types selected for the imbedded length.
Tag/Length Order Tab
Length Occurs Before Tag Field	Select this option to specify that the length field occurs before the tag field when both are present. The default is tag before length.
Trim Tab
Trim Trailing	Select this option to trim data from the trailing edge of the field data. Enter the data to be trimmed in the field next to this option.
Trim Leading	Select this option to trim data from the leading edge of the field data. Enter the data to be trimmed in the field next to this option.

Table 21-11 Format Builder Field Termination Properties Defined by Delimiter

Element	Description
Delimiter Tab	Variable-sized data types can have their termination point specified by a delimiter, which you can specify or which can be specified by a field containing the character. A delimiter is a character that marks the end of the field. The field data continues until the delimiter character is encountered.
Ref Fields	Click this button to specify a field that contains the delimiter character that indicates the termination point. On the dialog that appears, select the reference fields and click the right-arrow button. Click OK.
Values	Enter a default delimiter character to use when the delimiter field is not present. You must supply a default value.
Trim Tab
Trim Trailing	Select this option to trim data from the trailing edge of the field data. Enter the data to be trimmed in the field next to this option.
Trim Leading	Select this option to trim data from the leading edge of the field data. Enter the data to be trimmed in the field next to this option.

The following fields only appear if you select Literal in the Type field in the Field Description section.

Table 21-12 Format Builder Field Properties for Literal Data Types

Element Description

Element	Description
Value	An indicator that specifies the literal value. A literal value can be defined as a single value or it can be defined a list of values separated by the literal separator. When the Value is a list of values, the data for the literal field in the binary data will be one of values in the list.
Literal Separator	Supports enumeration of literal values. For literal type Field in MFL definition, a literal separator can be specified when multiple choices of value is needed for the Field. For example, segment terminators that are supported by both EDIFACT and X12 EDI standards are: `\r\n\, \r, \n, ',` and `~`. However, you can use Format Builder to support any other custom terminator. You can append the custom terminator to the existing list of literal values and use comma (`,`) as literal separator to separate multiple custom values. In the MFL file, you should see the following structure, <FieldFormat name='ISA_Terminator' type='Literal' value='\r\n,\r,\n,~,\|' literalSeparator=','/>

Value

An indicator that specifies the literal value. A literal value can be defined as a single value or it can be defined a list of values separated by the literal separator. When the Value is a list of values, the data for the literal field in the binary data will be one of values in the list.

Literal Separator

Supports enumeration of literal values. For literal type Field in MFL definition, a literal separator can be specified when multiple choices of value is needed for the Field.

For example, segment terminators that are supported by both EDIFACT and X12 EDI standards are: \r\n\, \r, \n, ', and ~. However, you can use Format Builder to support any other custom terminator. You can append the custom terminator to the existing list of literal values and use comma (,) as literal separator to separate multiple custom values.

In the MFL file, you should see the following structure,

<FieldFormat name='ISA_Terminator' type='Literal' value='\r\n,\r,\n,~,|' literalSeparator=','/>

Group Configuration Window

The Group Configuration window defines the groups contained in the message format. Groups are collections of fields, comments, and other groups or references that are related in some way. For example, the fields PAYDATE, HOURS, and RATE could be part of the PAYINFO group.

Table 21-13 Format Builder Group Description Properties

Element	Description
Name	The name of the group. This name must comply with 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.

Select one of the options in Table 21-14 to indicate how often this group appears in the message format.

Table 21-14 Format Builder Group Occurrence Properties

Element	Description
Once	Select this option if the group appears only once. Note: Unless a group is defined as optional, it occurs at least once.
Repeat Delimiter	Select this option if the group repeats until the specified delimiter is encountered. Enter the delimiter in the associated field.
Repeat Field	Select this option if the value of the repeat field at runtime is the number of times the group repeats. Select the repeat field name from the list of available options.
Repeat Number	Select this option if the group repeats a specified number of times. Enter the number of recurrences in the associated field.
Unlimited	Select this option if the group repeats an unlimited number of times.

Table 21-15 Format Builder Group Attributes

Element	Description
Group is Tagged	Select this option if this is a tagged group. If tagged, a literal precedes the data, indicating that the data is present. If you selected the Group is Tagged option, enter the tag in the text box to the right of the check box.

Element

Description

Group is Tagged

Select this option if this is a tagged group. If tagged, a literal precedes the data, indicating that the data is present.

If you selected the Group is Tagged option, enter the tag in the text box to the right of the check box.

Table 21-16 Format Builder Group Delimiter Properties

Element	Description
None	Select this option if the group has no delimiter
Delimited	Select this option if the end of the group is marked with a delimiter, which specifies the termination point for the group. A delimiter is a string of characters that marks the end of the group of fields. The group continues until the delimiter characters are encountered. If you select this option, enter the delimiter in the Value field. Note: Normally, groups are not delimited. They are usually parsed by content (the group ends when all child objects have been parsed).
Delimiter Field	Select this option if the group's termination point is specified by a field that contains a delimiter character string. If you select this option, select the Field that contains the delimiter character string, and enter a default delimiter character to use if the above field is not present in the data. This value is required.
Delimiter is Shared	Select this option if the delimiter marks both the end of the group of data, and the end of the last field of the group. The delimiter is shared among the group, and by the last field of the group, to delimit the end of the data.
Delimiter Is Not Optional	Select this option to indicate that the binary data contains the delimiter even if the group is not present.

Format Builder Reference Configuration Window

Use the Reference Configuration window to indicate the existence of another field or group format within the data. Reference fields or groups have the same format as the original field or group, but you can change the optional setting and the occurrence setting for the reference field or group. For example, if you have a "bill to" address and a "ship to" address in your data, you only need to define the address format once. You can create the "bill to" address definition and create a reference for the "ship to" address.

References are given the same name as the original item. For example, the "bill to" address definition and the "ship to" address definition would be named the same.

Table 21-17 Format Builder Reference Description Properties

Element	Description
Name	The name signifies the name for the original field or group for which you created this reference. This name must comply with XML element naming conventions.
Optional	Select Optional if the reference field or group is optional.

Table 21-18 Format Builder Reference Occurrence Properties

Element	Description
Once	Select this option if the reference appears only once. Note: Unless a reference is defined as optional, it occurs at least once.
Repeat Delimiter	Select this option if the reference repeats until the specified delimiter is encountered. Enter the delimiter in the associated field.
Repeat Field	Select this option if the value of the repeat field at runtime is the number of times the reference repeats. Select the repeat field name from the list of available options.
Repeat Number	Select this option if the reference repeats a specified number of times. Enter the number of recurrences in the associated field.
Unlimited	Select this option if the reference repeats an unlimited number of times.