Testing Format Definitions

Once you have built a format definition, you can test it using the Format Tester feature of Format Builder. The Format Tester parses and reformats data as a validation test and generates sample binary or XML data. This sample data can be edited, searched, and debugged to produce the expected results. The Format Tester uses the XML Translator runtime engine to perform the test translation.

This section discusses the following topics:

Starting Format Tester

To start the tester:

Using the Format Tester Main Window

The following topics discuss the elements of the Format Tester main window and provide instructions for navigating and executing commands from the Format Tester main window.

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

Using the Menu Bar

The following menus are available in Format Tester. All Format Tester menus are expandable from your keyboard by pressing Alt + mnuemonic key. Some menu commands are also executable using Ctrl + letter accelerator keys.

Figure 3-2 Menu Bar

The following commands are available from the File menu.

Table 3-1 File Menu Commands

Menu Command	Description
Open Binary	Allows you to select a file to be displayed in the binary window. Note: The default file extension for binary files is .DATA.
Open XML	Allows you to 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 Binary	Allows you to save the contents of the binary window.
Save XML	Allows you to save the contents of the XML window.
Debug Log	Allows the debug information to be saved in a text file.
Close	Closes the Format Tester window.

The following commands are available from the Edit menu

Table 3-2 Edit Menu Commands

Menu Command	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	Allows you to search for a hex or text value in the binary data.
Find Next	Continues your search to the next instance of the specified value.
Go To	Allows you to move the cursor in the binary editor to a specified byte offset.

The following commands are available from the Display menu

Table 3-3 Display Menu Commands

Menu Command	Description
XML	Allows the XML data panel to be hidden or shown. If hidden, the binary window expands to fill the width of the tester. The To XML button remains, but the splitter disappears.
Debug	Allows the Debug output window to be hidden or shown.
Clear—>Binary	Resets the contents of the binary window to be empty.
Clear—>XML	Resets the contents of the XML window to be empty.
Clear—>Debug	Resets the contents of the debug 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. Mutually exclusive with the Offset as Hexadecimal selection.
Text—>Values in ASCII	Changes the character set used when displaying the text portion of the hex editor display to ASCII. Mutually exclusive with the Values in EBCDIC menu selection.
Text—>Values in EBCDIC	Changes the character set used when displaying the text portion of the hex editor display to EBCDIC. Mutually exclusive with the Values in ASCII menu selections.

The following commands are available from the Generate menu.

Table 3-4 Generate menu Commands

Menu Command	Description
Binary	Generates binary data to match the current format specification.
XML	Generates XML data to match the current format specification.
Prompt while generating data	If selected, you are 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.

The following commands are available from the Translate menu.

Table 3-5

Menu Command	Description
Binary to XML	Converts the contents of the binary window to XML.
XML to Binary	Converts the contents of the XML window to binary.

Translate Menu Commands

Instead of using the standard menus to find the command you need, use the right mouse button to click an item in the pop-up shortcut menu.

The following commands are available from the Shortcut menus.

Note: Some commands may be unavailable, depending on which display panel the mouse pointer is currently in.

Table 3-6 Shortcut Menu Commands

Menu Command	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 in the clipboard for pasting into another location.
Paste	Inserts the cut or copied text at the cursor location.
Clear	Resets the contents of the binary, XML, or Debug window to be empty.
Generate	Generates binary or XML data to match the current format specification.
To XML	Converts the contents of the binary window to XML.
To Binary	Converts the contents of the XML window to binary.
Text in ASCII	Changes the character set to ASCII when displaying text with the hex editor.
Text in EBCDIC	Changes the character set to EBCDIC when displaying text with the hex editor.

The binary data display panel acts as hexadecimal editor, displaying data offsets, the hex value of individual bytes, and the corresponding text, which can be optionally displayed as ASCII/EBCDIC characters. The Binary window consists of the following three tabs used to select which mode to display the data:

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:

Using the Escaped Text Feature

To use the Escaped Text feature, select the Escaped Text tab from within the Binary window to view non-printable characters as escape sequences. The Escaped Text window displays non-printable characters as hex values. For example, the Escaped Text window does not show line breaks, but escapes the carriage returns.

Using the Text Feature

To use the Text feature, select the Text tab from within the Binary window to view all printable characters. For example, carriage returns are shown as line breaks. If you have non-printable characters, the Text window displays them as small squares.

Using the XML Window

Using the Debug Window

The Debug window displays the actions that take place during the translation operation, any errors that are encountered, and field and group values along with 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 Binary 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 Binary 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.

Note: Using the Debug window or Log File increases the time required to translate from XML to Binary.

Using the Resize Bars

Resize bars are located between the Binary, XML, and Debug windows and enable each window to be resized to suit your needs. Each resize bar can selected and dragged up and down, or left or right, as appropriate, to enlarge one of the windows and reduce the other.

Each resize bar also contains two directional buttons that can be clicked to enlarge or diminish any of the three windows.

Testing Format Definitions

Perform the following steps to test a message format definition.

Note: You can leave Format Tester open while you modify the Message Format from within Format Builder. Any changes to the message definition are automatically detected by Format Tester.

Debugging Format Definitions

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

Searching For Values

The Format Tester Find feature allows you to search for hex or text values in the binary data. Perform the following steps to perform a hex or text value search.

Positioning to an Offset

The Format Tester GoTo feature allows you to move the cursor in the binary editor to a byte offset you specify.

To move to a specified offset:

Using the Debug Log

The Format Tester debug log feature allows you to save your debug information in a text file.

To use the Format Tester debug log, choose File—>Debug Log. You will be presented with a standard Save As dialog box from which you can select the destination directory and name for this log file. If you select an existing file, the new debug information will be appended onto the end of the existing file.

Format Tester saves debug logs to the currently selected directory or the last directory selected.