19 How Do I?

This chapter describes how to perform common tasks in Format Builder.

This section contains the following topics:

Section 19.1, "Create a Message Format"
Section 19.2, "Create a Group"
Section 19.3, "Create a Field"
Section 19.4, "Create a Comment"
Section 19.5, "Create a Reference"
Section 19.6, "Save a Document"
Section 19.7, "Use Format Tester"
Section 19.8, "Debug Format Definitions"
Section 19.9, "Search for Values"
Section 19.10, "Search for Offsets"
Section 19.11, "Use the Debug Log"
Section 19.12, "Character Delimiters"
Section 19.13, "Specify a Delimiter"
Section 19.14, "Delimiter Match Rule"

19.1 Create a Message Format

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

To create a message format:

Choose File > New. The Message Format Detail Window displays in the right pane.
Enter data in the fields as appropriate. See Message Format Detail Window for field definitions.

19.2 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 an item 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. See Group Detail Window for field definitions.
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.

Note:
The Apply and Reset buttons are only enabled once changes are made to the detail panel's components.

19.3 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 an item 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. See Field Detail Window for field definitions.
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.

Note:
The Apply and Reset buttons are only enabled once changes are made to the detail panel's components.

19.4 Create 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 create 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 desired comment text. For more information, see Comment Detail 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.

Note:
The Apply and Reset buttons are only enabled once changes are made to the detail panel's components.

19.5 Create a Reference

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

Note:

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

To create a reference:

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. See Section 13, "Reference Detail Window" for field definitions.
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.

Note:
The Apply and Reset buttons are only enabled once changes are made to the detail panel's components.

19.6 Save a Document

To save a message format file for the first time:

Choose File > Save As. The Save As dialog displays.
Navigate to the directory where you want to save the file.
In the File Name text box, type the name you want to assign to the file.
If no extension has been given, Format Builder automatically assigns the extension .MFL to message format files.
Click Save As to save the file in the specified location with the specified name and extension.

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

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

19.7 Use Format Tester

Format Tester parses and reformats data as a validation test. Using Format Tester, you can make sure the message formats you build using Format Builder produce the expected results.

Format Tester is available from Format Builder.

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

Note:
Format Tester uses the currently loaded message definition document.

Refer to Section 17, "Format Tester" for more information.

19.9 Search for Values

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

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 opens.
Enter data in the fields as appropriate (see Section 19.9, "Search for Values" for more information).
Click OK to begin the Search operation.

19.10 Search for Offsets

The Goto feature allows you to move the cursor in the Non-XML editor to a byte offset you specify.

To move to a specified offset:

Choose Edit > Find. The Goto dialog opens.
Enter data in the fields as appropriate (see Section 19.10, "Search for Offsets" for more information).
Click OK to begin the Search operation.

19.11 Use the Debug Log

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

To use the debug log, choose File > Debug Log. A dialog displays allowing you to 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.

19.12 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 19-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
\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://java.sun.com/j2se/1.4/docs/api/java/util/regex/Pattern.html.

19.13 Specify a Delimiter

You can specify a delimiter either by reference or by value.

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.

19.13.1 Specify by Reference

Specify one or more fields that contain the delimiter character. The delimiter is matched in the order the fields are listed. Clicking the Ref Fields button opens the Select Reference Fields dialog box. In this dialog box, you can select reference fields and set the order in which the delimiter is matched.

Figure 19-1 Select Reference Fields

Description of "Figure 19-1 Select Reference Fields"

In Figure 19-1, The left pane lists fields that can be used as reference. Select a field by clicking on it and clicking the double arrow button to add the field. After selecting the fields, you can arrange the order of the fields by selecting a field on the right pane and clicking on the up arrow or down arrow button to move the field up or down. Click OK. The selected fields names are displayed in the field to the right of the Ref Fields button. See Figure 19-2.

Figure 19-2 Reference Field

Description of "Figure 19-2 Reference Field"

19.13.2 Specify by Value

Enter the delimiter or delimiters separated by the specified Separator character. When both Ref Fields and Values are specified, the Ref Fields take precedence. If no delimiter match is found, the specified delimiter values are used to match the delimiter. Example values for Value(s) and Separator are:

Values = ,|~|;

Separator = |

The field delimiter can be comma, tilde, or semi-colon.

If the field is optional, the Optional check box is enabled and selected by default. To ensure that the binary data contain the delimiter even if the field is not present, you must clear the optional check box.

19.14 Delimiter Match Rule

You can specify rules to skip delimiters that occur inside the field data, so they are treated as field data instead of a delimiter. For instance, if the delimiter character is ;(semicolon), but the field data is A;B, the ; character occurring between A and B must not be considered as delimiter, but a part of field data. You can specify the following options to specify the delimiter match rule:

Data Delimiter
Escape Character
None

19.14.1 Data Delimiter

Specify the character that appears at the beginning and at the end of the field data. For example, if Data Delim Char is "(double quotation mark), the data appears as "A;B";. See Figure 19-3.

Figure 19-3 Data Delimiter

Description of "Figure 19-3 Data Delimiter"

19.14.2 Escape Character

Specify an escape character that precedes the delimiter character occurring as part of the field data. The escape character value can be obtained via a reference field and by specifying the value in the Esc Char field. For example, if the Esc Char is \\, then the data appears as A\\;B;. See Figure 19-4

Figure 19-4 Escape Character

Description of "Figure 19-4 Escape Character"

Note:

The field delimiter, and all the shared delimiters of the parent structure are skipped even if the field is not the last field in the structure. For example, consider the following MFL structure:

Root Element
Group1 with shared delimiter *
  Field1 with delimiter ,
  Field2 with delimiter "
Group2 with shared delimiter ~
 Field3 with delimiter ,
Optional field4 with delimiter ~

In this example, Field3 data might contain *,~ or, that are skipped by the specified escape character even if it is not the last field in Group2

19.14.3 None

Select this option if the delimiter match rule is not required.