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 binary or XML data. This sample data can be edited, searched, and debugged to produce the expected results. Format Tester uses the data translation run-time engine to perform the test translation.

This section discusses the following topics:

• Starting Format Tester

• Using the Format Tester Main Window

• Testing Format Definitions

• Debugging Format Definitions

 

---

Starting Format Tester

To start Format Tester:

1. Start Format Builder by choosing Start—>Programs—>BEA WebLogic E-Business Platform—>WebLogic Integration 2.1—>Format Builder. The Format Builder main window displays.

   Note: To run Format Tester, you must have a message format document open in Format Builder.

2. Choose Tools—>Test. The Format Tester dialog box displays.

   Note: The Tester works with the currently loaded message definition document.

   Figure 3-1 Format Tester Dialog Box

   
    

 

---

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.

• Using the Menu Bar

• Using the Shortcut Menus

• Using the Binary Window

• Using the XML Window

• Using the Debug Window

• Using the Resize Bars

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 + mnemonic key. Some menu commands are also executable using Ctrl + letter accelerator keys.

Figure 3-2 Menu Bar

 

File Menu

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.

 

Edit Menu

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.

 

Display Menu

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.

 

Generate Menu

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.

 

Translate Menu

The following commands are available from the Translate menu.

Table 3-5 Translate Menu Commands

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.

 

Using the Shortcut Menus

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.

 

Using the Binary Window

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:

• Hex Editor

• Text

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:

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

   • Offsets as Hexadecimal

   • Offsets as Decimal

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

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

The XML data panel displays XML data that has been converted or translated from the contents of the Binary panel, or XML that is to be converted to Binary. The contents of the XML panel can be cleared or edited to suit your needs. When XML is generated, the XML Formatting Options specified in the Format Builder options dialog box are used. Refer to Setting Format Builder Options for more information.

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

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.

The debug feature allows for full debug information to be captured to a file. See Using the Debug Log for more information.

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.

1. Start Format Builder.

2. Open a Message Format file.

3. Start Format Tester.

4. Click File—>Open Binary, or File—>Open XML to load the file you want to translate and view, or enter your own data in one of the two data windows.

5. Select Display—>Debug if you want to view the actions that take place during the translation operation. This step is optional, but you must open the Debug window prior to the translation operation in order to view any debug information later.

6. Select Translate—>Binary to XML, or Translate—>XML to Binary to translate your data to the appropriate format. The translated data displays in the Binary or XML window.

   Figure 3-3 Format Tester

   
    

7. Correct the errors, if present, and test the translation again.

8. Continue this process until the translation is successful.

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

• Positioning to an Offset

• Using the Debug Log

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.

1. From within Format Tester, choose File—>Open Binary to open the binary data file you want to search.

2. Choose Edit—>Find. The Find dialog box opens.

   Figure 3-4 Find Dialog Box

   
    

3. Enter the value you want to find.

4. Select Text or Hex to specify what type of value you are searching.

5. Specify the direction you want to search.

6. Specify the position in the file from which you want your search to begin.

7. Click OK. The Find dialog box disappears and your cursor displays next to the value for which you are searching.

8. Choose Edit—>Find Next to search to the next instance of the specified value.

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:

1. From within Format Tester, choose Edit—>Go To. The Go To dialog box displays.

   Figure 3-5 Goto Dialog Box

   
    

2. Enter the offset value you want to go to.

3. Select either Dec or Hex to specify the type of offset you want to go to.

4. Select either Forwards or Backwards to specify the direction you want your search to proceed within the file.

5. Select either Beginning of File, Current Position, or End of File to specify the starting position of your search within the file.

6. Click OK to have your cursor placed next to the offset you are looking for. The Go To dialog box disappears after you click the OK button.

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.