This section describes design-time and run-time steps required for creating and executing transformations involving non-XML data sources. It also describes how to create schemas (MFL files) for non-XML data using an included WebLogic Integration utility called Format Builder.
This section covers the following topics:
Non-XML data that is sent to or received from legacy applications is often platform-specific information organized in a format unique to the machine on which the information originated. Non-XML data is not self-describing, so to be understood by an application, information about the format (metadata) of this data must be embedded within each application that uses non-XML data from a legacy application.
This section covers the following topics:
Data transformation is the mapping and conversion of data from one format to another. For example, data in a non-XML format can be transformed to an XML format and the converse is also true, data in an XML format can be transformed to an non-XML format. In order to transform data, you must create a schema which contains a description (metadata) for each of the data fields in the non-XML data. During the transformation of data from a non-XML format to an XML format, each field of non-XML data is transformed to XML according to the metadata defined for that field. The metadata you specify must include the name of the field, the data type, the size, and an indication of whether the field is always present or optional. This description of the non-XML data is used to transform the data to XML, as shown in the following figure:
WebLogic Integration can also transform data from XML to non-XML format, as shown in the following figure:
WebLogic Integration can also transform data from one non-XML format to another non-XML format, as shown in the following figure:
WebLogic Integration facilitates the integration of data from diverse enterprise applications by supporting the transformation of non-XML legacy system data to other data types (XML and Java primitives). Once legacy data is available as XML or a Java primitive, it can be used directly by WebLogic Integration business processes. WebLogic Integration supports transformations with non-XML data using the following data integration tools:
Steps 1-8 occur at design-time and step 9 occurs during run time, as shown in the following two figures.
The steps for an example non-XML to XML data transformation is shown in the following figure:
The steps for an example XML to non-XML transformation is shown in the following figure:
Steps 2-3 are done in the Format Builder tool and steps 4-8 are done in WebLogic Workshop.
A design-time component of WebLogic Integration is a Java application called Format Builder. In the first design-time phase (steps 2-3 in preceding figures), you use the Format Builder to create descriptions of non-XML data records. Specifically, you describe the layout and hierarchy of the non-XML data (the schema) in the Format Builder so it can be transformed to or from other data sources, like XML.
You can describe sequences of bytes as fields and specify, for each field, the type of data (floating point, string, and so on), the size of the data, and the name of the field. You can further define sets of fields (groups), multiple instances of fields and groups, and aggregation.
The description you create is saved in an XML grammar called Message Format Language (MFL). MFL documents contain metadata that describes the structure of the non-XML document. Once the non-XML document has been described via an MFL document, it can be used in XQuery data transformations just like XML documents that have been described by XML Schema (XSD) files.
You can also use Format Builder to retrieve, validate, and edit stored MFL documents and to test message format definitions with your own data. MFL documents are stored in the file system.
The test feature allows you to verify the MFL documents created in Format Builder by transforming a sample XML file to non-XML format, or transforming a sample non-XML file to XML format. You can save the transformed data in a file for future testing.
Note: To learn more about using Format Builder, see Using Format Builder to Create Format Schemas (MFL Files).
In this second design-time phase, you use WebLogic Workshop to create an application, project, and business process. For instructions on creating applications, projects, and business processes, see Creating a Business Process Application.
In order to map non-XML data in a transformation, you must first import an MFL file which describes the non-XML data into WebLogic Workshop. For instructions, see Selecting Source and Target Types.
You also use WebLogic Workshop to create a Transformation file, a method in the Transformation file, and a Client or Control node in a business process. The method contains a transformation, which when invoked by the business process during run time, maps data types. You design Control or Client nodes in your business process to call a method in a Transformation file, as shown in steps 6-8 in the preceding figures.
The following table lists the Client or Control nodes that can be added to a business process:
For instructions on add Client and Control nodes to a business process with Transformations, see Interacting With Clients and Interacting With Resources Using Controls, respectively.
If you design a Client and Control node to call a method in a Transformation file, during run time, the business process invokes the node and then that node invokes the method that contains the transformation. For example, a Client Receive node could receive non-XML data and pass that data to the transformation method, which transforms the non-XML data to XML data, as shown in the following figure:
WebLogic Integration uses MFL files to represent the schemas of non-XML documents, just as XSD files are used to represent the schemas of XML documents. At run-time WebLogic Integration uses these MFL files to carry out transformation operations involving non-XML data. This section provides information about creating these MFL files using Format Builder.
It includes the following topics:
To understand how to use the Format Builder, it helps to understand the following format and document types:
Because computers are based on the binary numbering system, a binary format is often used in applications to represent data. A file stored in binary format can be read by a computer, but not necessarily by a human. Binary formats are used for executable programs and numeric data; text formats are used for pure text. Many files contain a combination of binary and text formats. Non-XML data refers to both binary and text formatted data.
Note: The term non-XML data replaces the term Binary data that was used in previous versions of WebLogic Integration. (WebLogic Integration 7.0 or earlier.)
Unlike XML data, non-XML data is not self-describing. In other words, non-XML data does not include a description of how the data is grouped, divided into fields, or otherwise arranged. Non-XML data is a sequence of bytes that can be interpreted as an integer, a string, or a picture, depending on the intent of the application that generates that sequence.
For example, consider the following non-XML data string:
You can interpreted it in many different ways. For example:
Without a clear understanding of the purpose of this data string, the application cannot interpret the string appropriately.
In order for non-XML data to be understood by an application, the layout of the data must be embedded in the application itself. The character set used to encode the character data included in a non-XML file may also vary. For example, character data on an IBM mainframe is usually encoded using the EBCDIC character set, while data from a desktop computer is either ASCII or unicode.
You can use Format Builder to create a Message Format Language (MFL) file that describes the layout or schema of your non-XML data. MFL is an XML language that includes elements for describing each field of data, as well as groupings of fields (groups), repetition, and aggregation. The hierarchy of a non-XML record, the layout of fields, and the grouping of fields and groups are expressed in an MFL document. This MFL document is used at run time to transform non-XML data to and from an XML document.
Listing : Example of Non-XML Data
1234;88844321;SUP:21Sprockley's Sprockets01/15/2000123 Main St.; Austin;TX;75222;555 State St.;Austin;TX;75222;PO12345678;666123;150; Red Sprocket;
The eXtensible Markup Language (XML) is the universal format for structured documents and data. Unlike non-XML data, XML data is self-describing; it makes use of tags (words bracketed by '<' and '>') that signal the start and end of each block of data. These tags define the hierarchy of related data components that constitute the elements in a structured document.
The properties of XML make it suitable for representing and structuring data in a platform-neutral manner. By making the structure explicit, XML can simplify the task of exchanging data between applications. Because the data is presented in a standard form, applications on disparate systems can interpret it using XML parsing tools, instead of having to interpret data in proprietary binary formats.
The following listing shows an example XML document:
<?xml version="1.0"?>
<PurchaseRequest>
<PR_Number>1234</PR_Number>
<Supplier_ID>88844321</Supplier_ID>
<Supplier_Name>Sprockley's Sprockets</Supplier_Name>
<Requested_Delivery_Date>2000-01-15T00:00:00:000</Requested_Delivery_Date>
<Shipping_Address>
<Address>
<Street>123 Main St.</Street>
<City>Austin</City>
<State>TX</State>
<Zip>75222</Zip>
</Address>
</Shipping_Address>
</PurchaseRequest>
A Message Format Language (MFL) document (also known simply as a message format document) is a specialized XML document used to describe the layout of non-XML data. When you use Format Builder to define the hierarchy of a non-XML record, the layout of fields, and the grouping of fields and groups, the information is saved as an MFL document that can then be used to perform run-time transformations. The information captured in the MFL document can also be used to generate a DTD that describes the content model for the output generated by the MFL document.
The top-level element of a message format document is the MessageFormat element, which defines the message format name and version. For example, the following is the root element of the sample po.mfl document installed with WebLogic Integration:
<MessageFormat name='PurchaseRequest' version='2.01'>
WebLogic Integration supports Message Format Language Version 2.02. This version supports new features related to padding, truncation, and trimming. Message Format Language Version 2.01 is still supported.
The name assigned to the message format document becomes the root element in the XML instances that are generated based on the MFL document. For example, The following is the root element of any XML document generated based on the sample po.mfl document:
The other elements and attributes available in an MFL document are used to define the following:
Note: You must specify unique field names in a single MFL document. To learn more, see A Note of Caution—Must Specify Unique Field and Group Names in the Same MFL File.
Note: You must specify unique group names in a single MFL document. To learn more, see A Note of Caution—Must Specify Unique Field and Group Names in the Same MFL File.
Before a message format can be created, the layout of the non-XML data must be understood. Sample data for a legacy purchase order, with corresponding MFL and XML documents for a purchase order record, are installed with WebLogic Integration. The sample purchase order illustrates how WebLogic Integration transforms data from one format to another.
For more information about this sample data, see Non-XML Data Mapping Sample.
The key to transforming non-XML data to and from XML is to create an accurate description of it. For non-XML data (data that is not self-describing), you must identify the following elements:
Use Format Builder to incorporate these elements into the format definitions used for data transformations.
Format Builder helps you create format descriptions for non-XML data and store them in MFL documents. Your description should include hierarchical and structural information derived from a detailed analysis of your data. These format descriptions are stored in an MFL document. You can also use Format Builder to test your format descriptions before applying them to your data.
WebLogic Integration also provides utilities that allow you to import COBOL copybooks, import XML Schemas, and convert C structure definitions into MFL files. To learn more about these utilities, see Importing Existing Metadata to Create Format Schemas (MFL Files).
You can launch Format Builder using one of the following options:
To Start Format Builder From WebLogic Workshop
To Start Format Builder on Windows Without Launching WebLogic Workshop
Choose Start —> Programs —> BEA WebLogic Platform 8.1 —> Other Development Tools —> Format Builder.
The Format Builder main window is displayed.
To Start Format Builder on Linux Without Launching WebLogic Workshop
cd /usr2/bea/weblogic81/integration/bin
./fb.sh
The Format Builder window is split into two vertical panes. The left pane contains the navigation tree which shows the structural relationship of the groups and fields defined in the active MFL document. The right pane displays the properties that define the item.
Information about the file you are editing is displayed in the title bar of the Format Builder window.
The structure of the non-XML data is defined in the navigation tree through a combination of fields and groups that match the target data.
The following topics explain how to use the various tools provided in the Format Builder window to navigate and execute commands:
Note: For additional information about Format Builder, see the help included with the Format Builder executable. (To access the Format Builder help, start the Format Builder as described in Starting Format Builder and then from the Format Builder menu bar, choose Help —> Help Topics.)
The navigation tree represents the structure of the non-XML data in a hierarchical layout. The root node of the navigation tree, the Message node, corresponds to the MFL document being created or edited. Child nodes are labeled with the names of groups or fields. Fields are represented by leaf nodes in the navigation tree. Groups contain fields or other groups and are represented by non-leaf nodes in the navigation tree.
The icon for each node encapsulates the following information about the node: whether the node represents a message, a group, a field, a comment, or a reference; whether a group or field is repeating; whether a group is a Choice of Children; and whether a group or field is optional or mandatory.
You can add, delete, move, copy, or rename nodes in the navigation tree though menus or the toolbar. (For details, see Using the Format Builder Menu Bar and Using the Toolbar.)
The following table describes the icons displayed in the navigation tree.
The menu bar provides quick access to Format Builder functions.
The items available in a menu depend on the actions you have taken and the node currently selected in the navigation tree. If a menu item is not available, it is shown in gray in the menu.
You can display a menu in either of two ways:
To execute a command, select it from the menu. Some commands can also be executed via the keyboard shortcut indicated on the menu (For example, a Ctrl + key sequence.) The commands available on each menu are described in Format Builder Menus.
The toolbar is a menu of icons that provide alternative ways to access frequently used commands.
To execute a command, click the appropriate icon in the toolbar. If a command is unavailable, the icon for it appears grayed-out.
The following table describes the icons in the Format Builder tool bar.
When you right-click an item in the navigation tree, a menu of the most frequently used commands for that item is displayed. The following table describes the commands that are available from the shortcut menus.
Note: The availability of a command depends on the item you select and the previous actions you have taken.
You can drag and drop to copy and paste, or move items in the navigation tree.
Note: The node being copied or moved is always inserted as a sibling of the selected node during the drag-and-drop process. If you drag and drop the node onto the Message Format node, it is inserted as the last child.
The first step in creating a message format definition file is to create a message format (the root node of a message format file).
Note: The entry in the Name/XML Root field becomes the name of the root element of each XML instance generated based on this message format document. Therefore, the entry must comply with the conventions described in the following section, XML Element Naming Conventions.
Note: The Apply and Reset options are enabled only after changes are made in the detail window.
The names you assign to the root node, fields, groups, and references in a message format document are transformed to XML element names in the XML instances generated based on the message format document. Therefore, the names must comply with the following XML naming rules:
The following strings are examples of valid names:
The following strings are examples of invalid names:
A group is a collection of fields, comments, references, and other groups that are related in some way. For example, the fields PAYDATE, HOURS, and RATE might all belong to the PAYINFO group. You can create a group as a child of the message format item, as a child of another group, or as a sibling of a group or field.
Note: You must specify unique field names in a single MFL document. To learn more, see A Note of Caution—Must Specify Unique Field and Group Names in the Same MFL File.
The detail window for the group is displayed the right pane.
The name of the group. The entry must comply with the conventions described in XML Element Naming Conventions. |
|||
Select Choice of Children if only one of the items in the group will be included in the message format. |
|||
(Unless defined as Optional in the Group Description, all groups occur at least once.) |
Select this option to indicate that the group appears only once. |
||
Select this option to indicate that the group will repeat until the specified delimiter is encountered. |
|||
Select this option to indicate that the group will repeat the number of times specified in the field selected as the repeat field. |
|||
Select this option to indicate that the group will repeat the specified number of times. |
|||
Select this option to indicate that the group will repeat an unlimited number of times. |
|||
Select this option if the group is tagged, that is, if a literal precedes the other content of the group, which may be other groups or fields. |
|||
The termination point of a group can be specified by a delimiter: a string of characters that marks the end of a group of fields. The group continues until delimiter characters are encountered. Note: Normally, groups are not delimited. They are usually parsed by content; the group ends when all child objects have been parsed. For more information about delimiters, see Specifying Delimiters. Select from among the following options to specify the group delimiter attributes: |
|||
Select this option if the termination point of the group is marked with a delimiter character string, then enter the delimiter characters in the Value field. |
|||
Select this option if the termination point of the group is marked by a field that contains a delimiter character string. When you select this option, you are prompted to provide the following: Field—select the field that contains the delimiter character string. A list of valid fields is presented in a drop-down list. Default—enter the default delimiter character used if the selected field is not included in the data. This value is required. |
|||
Select this option to indicate that the delimiter marks both the end of the group of data, and the end of the last field of the group. The delimiter is shared by the group, and the last field of the group, to indicate the end of the data. |
The duplicate group contains the same values and child objects as the original. The name of the duplicate is the same as that of the original, with the addition of a prefix: New. Thus, for example, if the name of the original group is MyGroup1, then the name of the duplicate is NewMyGroup1.
Note: The Apply and Reset options are enabled only after changes are made in the detail window.
You can specify delimiters in Format Builder by entering the correct syntax. For example, if you want to specify a tab character as a delimiter ('\u009'), you must enter the construct \t to match it.
The following tables maps characters you can use as delimiters to the constructs you must use to designate these characters as delimiters.
To learn more, see the java.util.regex.Pattern class description.
A field is a sequence of bytes that is meaningful to an application. (For example, the field EMPNAME contains an employee name.) You can create a field as a child of the message format node, as a child of a group, or as a sibling of a group or another field. Field names are used as element names in the XML output; they must comply with the conventions described in XML Element Naming Conventions.
The detail window for the field is displayed the right pane.
The name of the field. The entry must comply with the conventions described in XML Element Naming Conventions and A Note of Caution—Must Specify Unique Field and Group Names in the Same MFL File. |
|||
Select this option if this is an optional field. Optional means that the data for the field may or may not be present. If the Optional option is selected for a file, then you must also set the Field is Tagged option from the Field Attributes pane. In addition, in the Field Is Tagged text box enter a unique value for each optional field in a group. Multiple groups can use the same tag value but the tag value for each optional field in a group must be unique. |
|||
Select the data type of the field from the drop-down list. The default is String. Note: Which field type you select dictates which field data options are displayed. For a list of data types supported by WebLogic Integration, see the online help of Format Builder. |
|||
(Unless defined as Optional in the Field Description, all fields occur at least once.) |
Select this option to indicate that the field appears only once. |
||
Select this option to indicate that the field will repeat until the specified delimiter is encountered. |
|||
Select this option to indicate that the field will repeat the number of times specified in the field selected as the repeat field. |
|||
Select this option to indicate that the field will repeat the specified number of times. |
|||
Select this option to indicate that the field will repeat an unlimited number of times. |
|||
(The Field Attributes properties that are displayed are dependent on the Type specified in the Field Description) |
Select this option if the field is tagged, that is, if a literal proceeds the data, indicating that the data is present. You must also choose the data type of the tag field from the drop-down list. For example in the following: SUP: is a tag and ACME INC is the field data. If you select the Field is Tagged option, enter the tag in the field to the right of the check box. |
||
Select this option to specify a value for the data in field that is inserted into the non-XML data if the field is not included in the XML. If the field is not included in the non-XML data and it is not optional, then the non-XML data fails to parse, even if a default value is given. |
|||
If the field is a date or time field, the base type indicates the type of characters (ASCII, EBCDIC, or Numeric) used to represent the data. |
|||
If the field is a date field with a 2-digit year, the year cutoff attribute allows the 2-digit year to be converted to a 4-digit year. If the 2-digit year is greater than or equal to the year cutoff value, a prefix of 19 is added to the year value. Otherwise a prefix of 20 is used. |
|||
The character encoding of the field data. The default code page is set by choosing Tools —> Options and selecting the default encoding from the Default Field Code Page drop down list. |
|||
Select from among the following options to specify the group delimiter attributes: |
|||
Select this option to set the length of variable-sized data types to a fixed value. When you select this option, you are prompted to provide the following: Length—enter the number of bytes in the field. Trim Leading/Trailing—removes the specified data from the leading or trailing edge of the data. Pad—if the XML data is shorter than the specified length, appends the specified data to correct its length. Select one of the following padding options:
Truncate—remove a specified number of characters from a field. Select any combination of the following truncation options:
If you select both truncation options, the Truncate First option is implemented initially, and the Truncate After option is invoked on the remaining characters. |
|||
Select this option to indicate that the termination point of a variable-sized data type is specified by an embedded length. An embedded length precedes the data field and indicates the number of bytes in the data. When you select this option, you are prompted to provide the following:
|
|||
Select this option to indicate that the termination point of a variable-sized data type is specified by a delimiter: a value that marks the end of the field. The field data continues until the delimiter is encountered. When you select this option, you are prompted to provide the following:
|
|||
Select this option if the termination point of a variable-sized data type is specified by a field that contains a delimiter value. When you select this option, you are prompted to provide the following:
For more information about delimiters, see Specifying Delimiters. |
|||
Specifies the number of digits (0-16) to the left of the decimal point. |
The duplicate field contains the same values as the original. The name of the duplicate is the same as that of the original, with the addition of a prefix: New. Thus, for example, if the name of the original field is MyField1, then the name of the duplicate is NewMyField1.
Note: The Apply and Reset options are enabled only after changes are made in the detail window.
Prior to the WebLogic Integration 7.0 release, no padding was performed on mandatory fields when data for the field did not exist at run time. For the WebLogic Integration 7.0 release and all subsequent releases, during an XML to non-XML transformation, a mandatory field that does not contain data is padded with the default value, if a default value has been specified. If no default value is specified and a field does not contain data at transformation time, an error occurs.
Note: Padding of mandatory fields is not supported for non-XML to XML transformations.
This feature is useful when a group is specified multiple times, but data is provided for only one occurrence. When padding of mandatory fields is invoked, all occurrences of a group for which data are not provided are padded with default values, if specified.
You must specify unique field (FieldFormat) and group (StructFormat) format names in a single MFL file. Format Builder allows the creation of duplicate field and group format names in the same MFL file but when an MFL file with duplicate names is imported into WebLogic Workshop causing the schemas project is built, errors will be reported, as shown in the following examples.
If the following example MFL file is imported into WebLogic Workshop, the build of the schema project fails because the field name: StockSymbol is used in two different groups:
<?xml version='1.0' encoding='windows-1252'?> <!DOCTYPE MessageFormat SYSTEM 'mfl.dtd'> <MessageFormat name='StockPrices' version='2.01'> <StructFormat name='PriceQuoteOne' repeat='*'> <FieldFormat name='StockSymbol' type='String' delim=':' codepage='windows-1252'/> <FieldFormat name='StockPrice' type='String' delim='|' codepage='windows-1252'/> </StructFormat> <StructFormat name='PriceQuoteTwo' repeat='*'> <FieldFormat name='StockSymbol' type='String' delim=':' codepage='windows-1252'/> <FieldFormat name='StockPrice' type='String' delim='|' codepage='windows-1252'/> </StructFormat> </MessageFormat>
The following schema build error is reported:
ERROR: Error compiling MFL file -C:\bea\weblogic81\DTGuide\Schemas\StockQuotesSameStructFormat.mfl: FieldFormat already defined: StockSymbol
If the following example MFL file is imported into WebLogic Workshop, the build of the schema project fails because the group name: PriceQuote is used twice, even though the first PriceQuote is nested in the group: Level:
<?xml version='1.0' encoding='windows-1252'?>
<!DOCTYPE MessageFormat SYSTEM 'mfl.dtd'>
<MessageFormat name='StockPrices' version='2.01'>
<StructFormat name='Level' repeat='*'>
<StructFormat name='PriceQuote' repeat='*'>
<FieldFormat name='StockSymbol' type='String' delim=':' codepage='windows-1252'/>
<FieldFormat name='StockPrice' type='String' delim='|' codepage='windows-1252'/>
</StructFormat>
</StructFormat>
<StructFormat name='PriceQuote' repeat='*'>
<FieldFormat name='StockSymbol' type='String' delim=':' codepage='windows-1252'/>
<FieldFormat name='StockPrice' type='String' delim='|' codepage='windows-1252'/>
</StructFormat>
</MessageFormat>
The following schema build error is reported:
ERROR: Error compiling MFL file - C:\bea\weblogic81\DTGuide\Schemas\StockQuotesSameNameInDiffGroup.mfl: StructFormat already defined: PriceQuote
Note: You can, however, use the same field and group names in different MFL files because the file name of the MFL document becomes the namespace for the field or group format names in WebLogic Workshop, making the field and group format names unique from file to file. For example, the StockPrice field in the Stock.mfl file is prefixed with the namespace:Stocks making it unique from the StockPrice field in the Price.mfl file which is prefixed with the namespace: Price.
Comments are notes about the message format or the data transformed by the message format. Comments are included in the message format definition for documentation and informational purposes only; they are unnumbered and are not transformed to XML or non-XML data. You can create a comment as a child or sibling of any message format, group, or field.
Note: Conventionally, a comment precedes the node it annotates.
Note: The Apply and Reset options are enabled only after changes are made in the detail window.
References allow you to reuse an existing field or group format in a new context. When you create a reference to an existing field or group, the same format is used, but you can modify the optional and occurrence properties for the reference field or group.
For example, if your data includes a bill to address and a ship to address and the same format is used for both addresses, you can create the address format once, and then reference it. That is, you can create the an address definition for the bill to address and reference it for the ship to address.
Note: A reference item is given exactly the same name as the original item, therefore, you should use a generic name, such as address, when you create a field or group that is be referenced. For instance, in the previous example, you can create an address group as a child of the bill_to group and then reference the address group from within the ship_to group.
The detail window for the reference is displayed. For example, the following figure shows the detail window for a Field Reference:
Note: The Apply and Reset options are enabled only after changes are made in the detail window.
The Format Builder palette allows you to store commonly used message format components so they are available whenever you need to insert them into your message format definitions.
The default palette, palette.xml, is an MFL document which is stored in the WebLogic Integration installation directory. The default palette contains common date formats, literals, and strings. You can use these items in the message formats you create, as well as add your own items to the default palette. You can also create your own MFL documents for use in the palette, or open and use items from any existing MFL document.
The following topics provide the information you need to use the palette:
You can copy items from the navigation tree to the palette, and vice versa. You can use drag and drop, or the commands available on the shortcut menu, to organize items in the palette. The contents of the palette are automatically saved when you exit Format Builder.
Note: Only copying items, whether from the navigation tree to the palette or vice versa, is allowed. You cannot move items between the windows.
The commands described in the following table are available from the Palette File menu.
Displays the Open dialog box to allow you to select and open an existing MFL document in the palette. |
|
Saves any changes you have made to the MFL document currently open in the palette. |
|
A shortcut menu is displayed when you right-click an item or folder in the palette. The following table describes the commands available from the shortcut menu.
Note: Some commands may be unavailable, depending on the item you select.
To copy an item from the document currently open in Format Builder to the palette:
The item is copied to the selected location.
Note: You cannot add an item that depends on the existence of another item to the palette. For example, you cannot add a field or group reference, and you cannot add an item for which a Repeat Field is specified.
Adding comments is possible, but not recommended because comments do not have unique names and therefore are indistinguishable on the palette.
To delete an item from the palette:
You are prompted to confirm the deletion.
To copy an item from the palette to a message format document currently open in Format Builder:
The item is copied to the selected location in the message format.
You can either save your MFL files directly into a Schemas folder in the file system or you can save the MFL file to the file system and later import the MFL file into a Schemas folder as described in the preceding bullets:
To save a message format file for the first time:
The Save As dialog box is displayed as shown in the following figure:
Note: If you do not include an extension in your filename, Format Builder automatically assigns the default extension:.mfl.
To save changes to an existing file, choose File —> Save.
To save an existing file to a new name, choose File —> Save As and follow steps 2 through 4 in the preceding procedure.
You can open a message format document on your file system as described in the this section.
To open an existing message format file:
The Open dialog box is displayed as shown in the following figure:
You can use the internationalization features in Format Builder by changing the options for an individual message file or by setting the default Format Builder options to include internationalization. For details, see:
To change options for a message format file:
The File Properties dialog box displays the Message Format Version and the Default Message Format (MFL) Encoding.
Your changes are reflected in the MFL document when you test it using Format Tester.
You can set several options to control the overall operation of Format Builder.
To set Format Builder options:
The Options dialog box is displayed.
Select the version to be associated with new MFL documents. Note: Each message format document is associated with its own message format version. The version specified for a message format can be changed from the default from the File Properties dialog box described in the preceding section Changing Options for a Message Format.. |
||
Select the character encoding to be associated with new MFL documents. The character encoding associated with an MFL document specifies the encoding used for the MFL document itself, and the XML output it generates. |
||
Select the code page, from the list of non-XML formats, to be used as the default code page for each field created in your MFL documents. A code page specifies the character encoding of the non-XML data in the field. |
||
Enter the number of spaces by which to indent the root element when generating the XML output. |
||
Enter the number of spaces by which to indent a new child element when generating the XML output. |
||
Generates a DTD document which captures the content model defined in the MFL document. If you specify Auto-generate DTD, when you save an MFL document to the file system, the DTD is saved in the same directory. |
The following menus are available in Format Builder: File, Edit, Insert, View, Tools, and Help.
The commands available on each menu are described in the following sections.
Note: Some commands may be unavailable, depending on which actions you have taken and what is selected in the navigation tree.
The following commands are available from the File menu.
Opens the File Properties dialog box for the active message format document. This dialog allows you to set options for the active MFL document (see Changing Options for a Message Format). Choose Tools —> Option to set defaults for the application (see Setting Format Builder Options). |
|
The following commands are available from the Edit menu.
The following commands are available from the Insert menu.
The following commands are available from the View menu.
Expands the entire navigation tree to show the child objects of all items in the navigation tree. |
|
Collapses the entire navigation tree to show only the root message format. |
The following commands are available from the Tools menu.
Displays a list of the installed importers. Choose the importer from which you want to import a message. |
|
The following commands are available from the Help menu.
Displays a list of common Format Builder tasks. Click a task to view the step-by-step instructions. |
|
Displays version and copyright information for the Format Builder and the JDK you are running. |
WebLogic Integration provides utilities that allow you to import COBOL copybooks, import XML Schemas, and convert C structure definitions into MFL files. The following topics explain how to perform these import operations:
WebLogic Integration includes a feature that allows you to import a COBOL copybook into Format Builder by creating a message definition to transform the COBOL data. When importing a copybook, you can use comments to document the imported copybook and the Groups and Fields it contains.
The COBOL Copybook Importer dialog box is displayed.
After you import a copybook, you can work in the same way you work with any message format definition. If you find an error or unsupported data type in the copybook, a message is displayed, informing you of the error. You can choose to have the error displayed or saved in a log file for future reference.
The following table provides a listing and descriptions of the sample files installed for the COBOL copybook importer. All directory names are relative; the specified directories are under the WL_HOME\integration\samples\di directory where WL_HOME is the top-level directory of your WebLogic Platform installation. (For example, if you installed WebLogic Platform in the c:\bea directory, the di directory is located at the following location: c:\bea\weblogic81\integration\samples\di.)
WebLogic Integration includes a C struct importer utility that converts a C struct definition into an MFL message definition by generating the following types of output data:
Whichever type of output you want, you must first specify a .c or .h input file, which must be parsed, and then select the desired structure. Then you can choose between MFL (default) or C code for your output.
All input to the parser must be valid C code. In addition, all external references, such as #include, #define, and typedef statements, must be resolved before you can use them. You can resolve them by editing them manually or by using the compiler's preprocessor.
Various platform-specific parameters may affect the description of data for C code. For example, the length of a long on a particular platform affects the non-XML data that conforms to a particular structure definition.
Two methods are available for dealing with these platform dependencies, depending on whether or not MFL is generated directly into Format Builder. If you want to generate MFL and have that MFL displayed immediately in Format Builder, you must supply the platform-dependent parameters in a configuration file.
Alternately, if you choose to generate your source in C, you may compile the C code on the desired machine. The compiler on that machine accounts for the necessary platform-dependent information. This approach allows you to produce an executable file that, when run, produces two files: an MFL document and non-XML data that conforms to that MFL. The MFL document can be opened in Format Builder and the non-XML data file can be opened in Format Tester.
Generating MFL directly into Format Builder requires platform configuration parameters found in an existing configuration file or a new configuration file created with the hardware profile editor. The hardware profile editor allows you to specify an existing profile that can be loaded, updated, and saved.
The source code for a utility that generates hardware profiles according to your needs is provided in the WL_HOME\integration\samples\di\CFG directory where WL_HOME is the top-level directory of your WebLogic Platform installation. (For example, if you installed WebLogic Platform in the c:\bea directory, the cfg directory is located at the following location: c:\bea\weblogic81\integration\samples\di\CFG.)
The following table provides a listing and descriptions of the sample files installed for the C struct importer. All directory names are relative; the specified directories are under WL_HOME\integration\samples\di directory where WL_HOME is the top-level directory of your WebLogic Platform installation. (For example, if you installed WebLogic Platform in the c:\bea directory, the di directory is located at the following location: c:\bea\weblogic81\integration\samples\di.)
To start the C Struct Importer:
The C Struct Importer dialog box is displayed.
The C Struct Importer dialog box allows you to specify import properties, as described in the following table:
Note: Initially, MFL is specified as the default output type.
The hardware profiles used by the C Struct Importer contain data size and alignment information for specific hardware and compiler combinations and are used to generate MFL for C structures. They are stored in configuration files that can be created, loaded, updated, and saved.
The cprofile.c source file in the WL_HOME\integration\samples\di\CFG directory is used to generate these profiles for any platform. This code is designed to be compiled and executed on the target platform with the compiler normally used. You should be able to compile and execute it on any platform with an ANSI standard C compiler in order to generate a profile configuration file that can be imported into the C Struct Importer. (Where WL_HOME is the top-level directory of your WebLogic Platform installation. For example, if you installed WebLogic Platform in the c:\bea directory, the CFG directory is located at the following location: c:\bea\weblogic81\integration\samples\di\CFG.)
To produce acceptable parser input, execute the appropriate commands for your platform:
VC++ Compiler
cl /P cprofile.c (output in cprofile.i)
GNU Compiler
gcc -P -E cprofile.c>cprofile.i
To execute the cprofile program and specify a hardware profile name, enter the following text at a command prompt:
cprofile configfilename [DESCRIPTION]
A description is optional. If you decide to provide one, put it in the configuration file as the value of DESCRIPTION. If the description contains embedded blanks, enclose it in quotes.
Upon completion, the Structure list is populated with the structures found in the input file.
Note: If your file does not parse correctly, we recommend that you proceed in one of two ways:
At this point, you must provide some profile configuration data to generate the MFL directly. You can do this by either creating a new hardware profile or specifying an existing profile.
Click Edit to open the hardware profile editor if you need to view or edit the profile parameters.
Note: Hardware profiles for common configurations are prebuilt and may be found in the WL_HOME\integration\samples\di\CFG directory. (Where WL_HOME is the top-level directory of your WebLogic Platform installation. For example, if you installed WebLogic Platform in the c:\bea directory, the CFG directory is located at the following location: c:\bea\weblogic81\integration\samples\di\CFG.)
If errors are detected during the generation process, the MFL Generation Errors dialog box is displayed providing you with an opportunity to view or file the error log.
After you determine which errors were generated, you can return to the C Struct Importer and repeat the applicable steps.
Upon completion, the Structure list is populated with the structures found in the input file.
Note: If your file does not parse correctly, we recommend that you proceed in one of two ways:
Messages are displayed if you are about to overwrite an existing file or if the code generation has succeeded or failed.
Note: You must copy the input file containing the struct declarations, as well. When compiled, both programs accept the name of the output file as an argument.
WebLogic Integration includes a feature that allows you to import an XML Schema into Format Builder. The imported XML Schema provides a starting point for creating the MFL message definitions used for transforming data between XML and non-XML formats.
To import a XML Schema from an XSD file:
The Select XSD File & Root Element dialog box is displayed.
A delimiter is a character that marks the end of the data field.
After you build a format schema, you can test it using the Format Tester. The Format Tester parses and reformats data as a validation test and then generates sample non-XML or XML data. This sample data can be edited, searched, and debugged to produce the expected results. Format Tester uses the data transformation run-time engine to perform the test transformation.
This section discusses the following topics:
The Format Tester dialog box is displayed as shown in the following figure:
The Format Tester dialog box is divided into three windows: the Non-XML window, the XML window, and the Debug window. Resize bars divide the windows. You can drag the resize bar to adjust window size, or click an arrow on the bar to show or hide a window. For example, you can click the left arrow on the bar dividing the Non-XML and XML windows to hide the Non-XML window. If a window is hidden, you can drag the bar or click the appropriate arrow to restore the window.
Note: When you open the Format Tester for the first time in a session, only the Non-XML and XML windows are visible. To open the Debug window, use the resize bar at the bottom of the Format Test dialog box, or choose Display —> Debug to toggle the Debug window on and off.
The following topics explain how to use various tools provided in the Format Tester dialog box to navigate and execute commands:
The following topics explain how to use each of these features to help you accomplish your task.
The Non-XML window can contain sample data that has been:
You can open an existing non-XML data file, edit or save the contents of the window, or clear the window as required for your test situation. For details, see Using the Menu Bar and Using the Shortcut Menus.
The Non-XML window of the Format Tester dialog box serves as a non-XML file editor. The window contains the following tabs:
The editor allows you to edit a hex byte or a text value. If a hex data value is modified, the corresponding text value is updated, and vice versa.
The data offset feature of the Hex tab allows you to display the data offsets as hexadecimal or decimal addresses.
To change the format of the data offsets:
The following two data offset options are displayed:
The Text tab of the Non-XML window displays the printable characters (usually in the form of words and numbers) and certain control characters (carriage return, tab, and so on). For example, carriage returns are shown as line breaks. Non-printable characters, are displayed as small squares.
The XML window can contain sample XML that has been:
You can open an existing XML file, edit or save the contents of the window, or clear the window as required for your test situation. For details, see Using the Menu Bar and Using the Shortcut Menus.
When XML is generated, the XML Formatting Options specified in the Format Builder options dialog box are used. For additional information, see Setting Format Builder Options.
The Debug window displays the actions that occur during a transformation, any errors that are encountered, and field and group values, along with delimiters. To determine the cause of an error, identify the last field that parsed successfully and examine the properties of the field listed after it in the navigation tree.
When you open the Format Tester for the first time in a session, only the Non-XML and XML windows are visible. To open the Debug window, choose Display —> Debug to toggle the Debug window on and off. The Debug window opens below the Non-XML and XML windows.
Debug output is restricted to the most recent 64 KB of messages. This restriction prevents large debug output from causing a JVM out of memory event.
The debug log feature allows you to save all debugging information in a file. For details, see Using the Debug Log.
Note: Use of the Debug window or log file increases the time required to transform from XML to non-XML.
You can change the dimensions of any window in the Format Tester by using the resize bars located between the Non-XML, XML, and Debug windows. To change the size of a window, select a resize bar and drag in the appropriate direction (up or down or to the left or right) to enlarge one of the windows and reduce the other.
Each resize bar also contains two directional buttons. Click the appropriate button to show or hide any of the three windows.
Format Tester functions can be accessed from the five menus listed in the menu bar at the top of the main window.
You can expand a Format Tester menu in either of two ways:
To execute a command, select it from the menu. Some commands can also be executed via the keyboard shortcut indicated on the menu (For example, a Ctrl + key sequence.) The commands available on each menu are described in the following sections.
The following commands are available from the File menu.
The following commands are available from the Edit menu.
The following commands are available from the Display menu.
The following commands are available from the Generate menu.
Generates non-XML data to match the MFL document specification. |
|
If checked, you are prompted to specify the following during the generation process: |
The following commands are available from the Transform menu.
When you right-click in the Non-XML, XML, or Debug window, a menu of the most frequently used commands for that window is displayed. The following table describes the commands that are available from the shortcut menus.
To test a message format definition:
The transformed data is displayed in the Non-XML or XML window as shown in the following figure:
Note: You can leave Format Tester open while you modify the message format document in Format Builder. Changes to the document are detected automatically by Format Tester.
The following topics explain how to use three Format Tester features to debug and correct your data:
The Find command allows you to search for hex or text values in the non-XML data.
To search for a hex or text value:
If the value is found, the cursor moves the location of the value. If the value is not found, the following message is displayed: The specified search string was not found.
The Go To command allows you to move the cursor to a specified hexidecimal or decimal address (offset).
To move to a specified offset:
Although debugging information is not saved by default, the Format Tester dialog box allows you to specify a debug log file. When you specify a debug log file, all debugging information generated during your testing session is appended to the specified file.
Note: The Debug Log check box on the File menu is toggled upon selection. If the check box is checked, choosing File —> Debug Log turns off logging to the file.
If you select an existing file, the new debug information is appended to the end of the existing file.