Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy
eLink Information Integrator Doc Home | BEA eLink Information Integrator 1.0 User's Guide | Previous Topic | Next Topic | Contents | Index

Building Format Definitions

You can build and modify format definitions using one of the following methods:

- MsgDefAdmin importer utility-The importer utility is an easy-to-use command-line tool that allows you to store format definitions in the iiDatabase. You should use MsgDefAdmin to store formats whenever possible.

  Note: You must use the Formatter interface when using output operations or mapping format fields.

- Formatter interface-The interface allows you to populate screens with format definition data and store the information in the iiDatabase.

This section describes the following topics:

- Using MsgDefAdmin to Build Definitions

- Starting Formatter

- Alternative Input and Output Formats

Using MsgDefAdmin to Build Definitions

The MsgDefAdmin importer utility is an interpreter for four commands that let you add, retrieve, delete, and list message format definitions that are stored in the iiDatabase. MsgDefAdmin allows you to define message formats in an XML language called Message Definition Format Language (MFL). You can then import these textual descriptions into the iiDatabase. Message definitions that exist within the iiDatabase can also be listed, retrieved, or deleted using this utility.

Creating and Storing MFL Documents

An MFL document is a description of a message that is sent to an application. To create an MFL document, you need to translate messages into a textual description that conforms to the MFL document type definition (mfl.dtd). mfl.dtd defines valid elements and attributes necessary to create message formats. The attributes in mfl.dtd are the same ones that you can define using Formatter. Refer to MFL Document Type Definition for a listing of mfl.dtd and an example MFL document.

As an example, suppose you are integrating a payroll application. This payroll application uses a message that has the following structure:

NUM_EMPLOYEES 4-byte Little Endian integer
EMPLOYEE_REC Employee record
EMPLOYEE_NAME 32 characters
EMPLOYEE_SSN 11 characters
EMPLOYEE_PAY 15 bytes of Packed Decimal

Listing 3-1 is an example instance of payroll data that contains data for one employee. In the example, binary data is represented with a \x prefix to indicate that it is hexadecimal. This is done for illustration purposes only.

Listing 3-1 Instance of Payroll Data

>     \x01\x00\x00\x00JohnDoe\xFF......11122333300000000000000000000000063125F

The fields in this instance are defined as follows:

\x01\x00\x00\x00

  The NUM_EMPLOYEES field is one.

JohnDoe\xFF

  The EMPLOYEE_NAME field is delimited by \xFF byte.

111223333

  The EMPLOYEE_SSN field.

00000000000000000000000063125F

  The EMPLOYEE_PAY field is an unsigned packed field and has a value of $63,125.

You can create an MFL document for the payroll application by using the steps described in the following procedure.

1. Start a text editor.

2. Enter the following lines as the first lines in your MFL document.

   <?xml version='1.0'?>
   <!DOCTYPE MessageFormat SYSTEM `mfl.dtd'>

3. Specify the message definition name in the MessageFormat element. In this example, name this message PAYROLL_MSG by setting the name attribute of the MessageFormat element.

   <?xml version='1.0'?>
   <!DOCTYPE MessageFormat SYSTEM `mfl.dtd'>
   <MessageFormat name='PAYROLL_MSG'>

4. Define the NUM_EMPLOYEES field by adding a FieldFormat element and setting the name and type attributes.

   <?xml version='1.0'?>
   <!DOCTYPE MessageFormat SYSTEM `mfl.dtd'>
   <MessageFormat name='PAYROLL_MSG'>
   <FieldFormat name='NUM_EMPLOYEES'
   type='LittleEndian4'/>

5. Define the repeating EMPLOYEE_REC structure by adding a StructFormat element with the name attribute set to EMPLOYEE_REC. Because the structure repeats based on the NUM_EMPLOYEES field, set the repeatField attribute to point to the previously defined NUM_EMPLOYEES field.

   <?xml version='1.0'?>
   <!DOCTYPE MessageFormat SYSTEM `mfl.dtd'>
   <MessageFormat name='PAYROLL_MSG'>
   <FieldFormat name='NUM_EMPLOYEES'
   type='LittleEndian4'/>
   <StructFormat name='EMPLOYEE_REC'
   repeatField="NUM_EMPLOYEES">

6. Add additional fields to EMPLOYEE_REC by defining FieldFormat elements. Set the type attribute according to each field's type.

   1. Specify a delimiter attribute of hexadecimal FF for the EMPLOYEE_NAME field. Also, specify the EMPLOYEE_NAME field with an accessMode of Controlling. This indicates that when the data is reformatted, each repetition of the repeating component (EMPLOYEE_REC) is detected by the presence or absence of an EMPLOYEE_NAME field.

   2. Specify a length of eleven characters for the EMPLOYEE_SSN field to indicate the exact size of the string.

   3. Specify a length of fifteen bytes for the EMPLOYEE_PAY field.

      <?xml version='1.0'?>
      <!DOCTYPE MessageFormat SYSTEM `mfl.dtd'>
      <MessageFormat name='PAYROLL_MSG'>
      <FieldFormat name='NUM_EMPLOYEES'
      type='LittleEndian4'/>
      <StructFormat name='EMPLOYEE_REC'
      repeatField="NUM_EMPLOYEES">
      <FieldFormat name='EMPLOYEE_NAME' type='String'
      delim='\xFF'/>
      <FieldFormat name='EMPLOYEE_SSN' type='String'
      length='11'/>
      <FieldFormat name='EMPLOYEE_PAY' type='Upacked'
      length='15'/>

7. Add the end tags for the StructFormat and MessageFormat elements.

   <?xml version='1.0'?>
   <!DOCTYPE MessageFormat SYSTEM `mfl.dtd'>
   <MessageFormat name='PAYROLL_MSG'>
   <FieldFormat name='NUM_EMPLOYEES' type='LittleEndian4'/>
   <StructFormat name='EMPLOYEE_REC'
   repeatField="NUM_EMPLOYEES">
   <FieldFormat name='EMPLOYEE_NAME' type='String'
   delim='\xFF'/>
   <FieldFormat name='EMPLOYEE_SSN' type='String'
   length='11'/>
   <FieldFormat name='EMPLOYEE_PAY' type='Upacked'
   length='15'/>
   </StructFormat>
   </MessageFormat>

8. Save your message definition and exit from the text editor. You can now use MsgDefAdmin to add this message definition to the iiDatabase.

9. Open a DOS command-prompt window.

10. Change to the directory where MsgDefAdmin is installed (for example, C:\BEAII)

11. Type MsgDefAdmin and press Enter. The MsgDefAdmin importer utility appears as shown in Listing 3-2.

    Listing 3-2 MsgDefAdmin

- Copyright (c) 2000 BEA Systems, Inc.
All Rights Reserved.
Distributed under license by BEA Systems, Inc.
BEA eLink Information Integrator is a registered trademark.

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

- - - BEA eLink Information Integrator 1.0 - - -
- - - Message Definition Importer Tool - - -

Enter choice:
1) Add Message Definition
2) Get Message Definition
3) Delete Message Definition
4) List Message Definitions
Q) Quit >

1. Type 1 to select the Add Message Definition choice and press Enter. An additional prompt displays asking you to specify the name of the file containing the XML message definition.

2. Type the name of the message file you created with your text editor and press Enter. MsgDefAdmin processes the file, stores the message definition in the iiDatabase, and returns a message that the definition was successfully created.

3. Type Q at the prompt and press Enter to quit MsgDefAdmin.

Running MsgDefAdmin with command-line options

The MsgDefAdmin utility also supports execution in a non-interactive mode. Two command-line options are supported that allow you to import or export message definitions.

The MsgDefAdmin utility has the following command-line syntax:

MsgDefAdmin [-i | -e] <XML filename>

where

-i

  Denotes an import operation. MsgDefAdmin will import the message definitions in <XML filename> into the iiDatabase. The following example shows how to use -i.

  C:\BEAII>MsgDefAdmin -i payroll.xml employee_data.xml purchase_order.xml
  Processing file: payroll.xml
  Message Definition created!
  Processing file: employee_data.xml
  Message Definition created!
  Processing file: purchase_order.xml
  Message Definition created!

-e

  Denotes an export operation. MsgDefAdmin will export the message definitions in <XML filename> from the iiDatabase. Each definition that is exported is saved to a file using the name of the message definition as the file name and .xml as the filename extension. The following example shows how to use -e.

  C:\BEAII>MsgDefAdmin -e PAYROLL_MSG EMPLOYEE
  XML Document retrieved:
  Created file PAYROLL_MSG.xml
  ML Document retrieved: Created file EMPLOYEE.xml

<xml filename>

  Name of the XML file that contains or receives message definitions.

Converting Data Integration Option Formats to MFL

Information Integrator provides a utility called fgf2mfl to convert Data Integration Option FML group formats and meta-type information formats to MFL.

The fgf2mfl utility has the following syntax:

fgf2mfl [-f | -m] <filename>

where

-f

  Indicates that <filename> is a FML group format file.

-m

  Indicates that <filename> is a meta-type information format file.

<filename>

  Name of the Data Integration Option file that you want to convert to MFL.

If you invoke fgf2mfl without specifying a flag, fgf2mfl attempts to determine the file type from the filename extension. For example, an extension of .fgf specifies an FML group format, and an extension of .mti specifies a meta type format.

Starting Formatter

You can launch the Formatter interface using the steps described in the following procedure.

1. Double-click the Formatter icon. The Formatter Logon dialog box appears as in Figure 3-1.

   Note: If you do not have an assigned user ID and password, ask your system administrator to create them for you.

   Figure 3-1 Formatter Logon

2. Enter your user ID in the User ID field and press Tab.

3. Enter your password in the Password field and press Tab.

4. Select a database type from the DBMS drop-down list box. The Database field appears or disappears based on your selection.

   - If you selected the Microsoft SQL server type, specify the server in the Server field and the database in the Database field.

   - If you selected an Oracle database type, specify the server in the Server field.

5. Click OK. The Formatter main window appears as in Figure 3-2.

   Figure 3-2 Formatter Main Window

The Formatter is divided into two panes. Format components are displayed in a hierarchical organization in the left pane. When you select a component in the left pane, the right pane of the window displays detailed information about the selected component. The detailed information is kept in property sheets labeled with tabs.

Using Formatter to Build Definitions

You can use the Formatter to edit or create message format definitions. If you want to create a message definition from scratch, follow the instructions in Using MsgDefAdmin to Build Definitions. However, you must use Formatter to specify the mapping of data between message formats and any output operations performed on data items.

Using the Formatter, a message format definition is defined as a series of components. These components describe how to parse each piece of information in the message, how to output each piece of information, and how each piece of information relates to the message as a whole.

These components include:

- Literal-String of characters that exist in the message. For example, if a message always starts with a string of characters such as START, then this string is a literal.

- Field-Name for a piece of data.

- Input control-Describes how to parse an item of data. For example, an input control would describe that an item of data is an ASCII string that is delimited by a null character.

- Output control -Describes how to format output data. For example, an output control would describe that an item of data should be output as an EBCDIC string. Output operations associated with the output control could further describe that the EBCDIC string is right justified.

- Output operations-Describe an operation performed on the item of data when it is output. See the example given in the output control description.

- Flat format -Sequence of fields and controls that describe the format of a group of data items. For example, suppose three data items are a group. A flat format to describe how to parse this group would consist of three pairs of fields and input controls, one field and input control for each data item.

- Compound format-Sequence of flat formats.

To define a message format definition using Formatter, you must define the components of the message using a bottoms up strategy. A high-level approach is described in the following procedure.

1. Create the literals that are used in the message (delimiters, tags, and so forth)

2. Define the fields (data item names) of the message.

3. Define how to parse each data item of the message using an input control.

4. Define how to output each data item in an output control.

5. Define groups of data items by creating flat formats and adding fields and controls to these flat formats.

6. Define groups of flat formats by creating compound formats.

Literals

A literal is a string of characters that Formatter processes as:

- Delimiters

- Format terminators

- Repeating sequence terminators

- Default values

- Trim characters

- Prefixes and suffixes

- Pad characters

- Substitute values

- Comparison values

- Tag values

- Regular expressions

Formatter uses literals in input controls, output controls, operations, format terminators, and repeating sequence terminators. Valid literals include the printable characters A-Z, a-z, 0-9, and any keyboard character available by pressing Shift with another printable character; hex values that can include printable and non printable characters. Do not use single quotes in literal names. When literals are used as pad characters, only the first character is used.

Note: The maximum character length of a literal is 127.

Creating a Literal

You can create a literal using the steps described in the following procedure.

1. Select the Literals component category in the left pane of the Formatter window and right-click.

2. Select New from the pop up menu. A new literal component is added to the left pane, and the Literal property sheet is displayed in the right pane as in Figure 3-3.

   Figure 3-3 Literal Property Sheet

3. Type a unique name in the text box.

   Note: The literal name must be 32 characters or less. Single quotes, double quotes, and spaces should not be used in names.

4. Press Enter to finish defining the literal. The name is highlighted and moves to its alphabetical location in the list. This name is the default value of the literal.

5. Enter the value for the literal in the appropriate Property tab. You can enter ASCII or EBCDIC values in their associated tabs or enter hex values in the HEX Value window. Note that the ASCII and EBCDIC fields have a 127-character maximum (which equals a 254-character hex value).

   Note: You cannot drag and drop literals.

6. Click Apply to save your changes to the iiDatabase.

Fields

Fields are named items of message data and are the smallest possible container for information. In Formatter, the field name is the link between the input and output data. Each field can be used in multiple formats and associated with different input and output controls. To identify a field in a message, a combination of the field name and a control is used.

Note: Enter a unique name for each field. Field names can be up to 32 characters in length.

Creating a Field

1. Select the Fields component category in the left pane of the Formatter window and right-click.

2. Select New from the pop up menu. A new field component is added to the left pane and the fields property sheet is displayed in the right pane. The cursor is positioned in the text box as in Figure 3-4.

   Figure 3-4 Fields Property Sheet

1. Type a unique field name in the text box.

   Note: The field name must be 32 characters or less. Field names with quotes may only have single or double quotes, not both. Field names with spaces or underscores must be enclosed by single or double quotes. A field with the name Field_1 could be used as "Field_1" or `Field_1' (but not "Field_1' or `Field_").

2. Press Enter to finish defining the field. The field name moves to its alphabetical location in the list and is highlighted.

3. Optionally click the Comment field on the property sheet to add a descriptive comment for the field and type the comment.

   The Comment field does not retain formatted text when imported or exported. Using carriage returns in the Comment field is not recommended.

   Note: You can change the name of a field by double-clicking on the field name. Type the new name and press Enter to enter the name and position it in the list.

4. Click Apply to save your changes to the iiDatabase.

Input Controls

To build input formats, you must build input controls. Input controls are used to parse input data. The iiServer uses input controls to determine how to find the beginning and end of the data in a field.

An input control also determines whether the data for a field is mandatory or optional. Mandatory means that Formatter considers the parse successful if the parse start and end strings are found, even if the associated data is empty. If the parse is successful, the field passes the mandatory test and the parse continues. If the parse parameters are not found, the field fails the mandatory test and the parse fails for the rest of the format. Optional means that the parse continues even if parse parameters for the field are not found.

Input controls can use tags to separate data. Tags are sets of bits or characters explicitly defining a string of data. For example, <NAME> could mark the beginning of a name field in a message.

After an input control is created, it can be saved as an output control. For more information, refer to Saving an Input Control to an Output Control.

Creating an Input Control

You can create an input control using the steps described in the following procedure.

1. Select the Input Controls component category in the left pane of the Formatter window and right-click.

2. Select New. A new input control component is added to the left pane, and the input control property sheet is displayed in the right pane.

3. Type a descriptive input control name in the text box.

   Note: The input control name must be 32 characters or less. Single quotes, double quotes, and spaces should not be used in names. However, if using quotes, make sure they are not mismatched (for example, a single quote paired with a double quote).

4. Press Enter to finish defining the input control. The new input control moves to its alphabetical location in the list and is highlighted.

5. Click the Control Type drop-down list and select an input control type. Input control types describe the type of field parsed by Formatter. The valid control-type values are described in Table 3-1.

   ####

   Table 3-1 Input Control Type Values

   Input Control Type Value | Description
   --- | ---
   Data Only | Field has a data component only. Data is the value of the field.
   Tag and Data | Field has a literal tag and data component (in this order).
   Tag-Length and Data | Field has a tag, length, and data component (in this order).
   Length and Data | Field has a length and data component (in this order).
   Repetition Count | Field contains the count of a repeating component.
   Literal | Field value is a literal.
   Length-Tag and Data | Field has a length, tag, and data component (in this order).
   Regular Expression | Compares input data to the value of the literal parse control using pattern matching. A regular expression requires an associated string data type and a literal value.

6. Specify the values for the remaining fields on the Properties tab. Depending on the control type you selected, some fields are enabled or disabled. For example, you can define Data Only controls using the steps described in the following procedure.

   1. Select the input control type from the Type drop-down list in the Data section. The data types are described in Data Types.

   2. Select the input control termination type from the Termination drop-down list. The parse control termination type defines when Formatter should stop parsing for this field.

   3. Select one of the following options:

   - Enter the length of the data in the Length field if you selected Exact Length as your termination type.

   - Enter the number of bytes in the Length field that Formatter skips before looking for the termination control if you selected
     Minimum Length + Delimiter as your termination type. You also need to specify a delimiter from the Delimiter drop-down list.

   - Select a literal from the Delimiter drop-down list if you selected Delimiter as your termination type.

7. Select the Optional checkbox to make the input parse field optional. Optional means the parse continues even if parse parameters for the field are not found.

8. Click Apply to save your changes to the iiDatabase.

Saving an Input Control to an Output Control

You can save input controls as output controls. The output controls mirror (as closely as possible) the contents of the input control. You may have to modify the output control because certain properties of input controls do not have exact matches on the output control side.

You can save an input control as an output control using the steps described in the following procedure.

1. Select the input control you want to save in the left pane of the Formatter window and right-click. A pop-up menu appears.

2. Select Save as Output. The input control is saved as an output control with the prefix OFC_#_ and appears in the Output Controls list.

   For example, the first time the input control called Test is saved as an output control, it is saved as OFC_1_Test. The second time Test is saved, it is saved as OFC_2_Test, and so forth.

3. Select and modify the details on the Output Control property sheet to change or add information for the output control. See Creating an Output Control for more information about working with output property sheets.

Output Controls

Output controls are used to format output data. iiServer uses output controls to determine how to justify and trim data, add prefixes or suffixes, or perform an arithmetic expression. Using the output control types of either Input Field Value = or Input Field Exists allows alternative output formatting. For more information on alternative output formatting, refer to Alternative Input and Output Formats.

The Output Control tab allows you to add a new output control, create and define default and length output operations, and assign case and justification operations to an output control.

Creating an Output Control

You can create an output control using the steps described in the following procedure.

1. Select Output Controls from the Formatter window tree and click the right mouse button. A pop-up menu appears with the New menu item. The right pane displays the current list of output controls.

2. Select New to create a new output control entry in the left pane and open the Output Control property sheet in the right pane. The cursor is positioned in the output control text box as in Figure 3-5.

   Figure 3-5 Output Control Property Tab

3. Type a unique output control name in the text box.

   Note: The output control name must be 32 characters or less. Single quotes, double quotes, and spaces should not be used in names. However, if using quotes, make sure the quotes are not mismatched (for example, a single quote with a double quote).

4. Press Enter to add the output control to the list of output controls.

   The output control is highlighted and its name appears in the Output Control name text box in the Output Control tab.

5. Click the Control Type drop-down list and select an output control type. The valid control-type values are described in Table 3-2.

   ####

   Table 3-2 Output Control Types

   Output Control Type | Description
   --- | ---
   Conditional Field | Mark field as output only if existence check field exists.
   Data Field (Name Search) | Map the output field to the input field by field name.
   Data Field (Tag Search) | Map the output field to the input field by tag value.
   Existence Check Field | Mark field as an existence check field.
   Input Field Exists | An input field exists.
   Input Field Value = | The input field's value equals a particular value.
   Literal | Field value is a literal.
   Rules Field | Output control is chosen based on rules evaluation.

   An output control defines how you want iiServer to output a message field. Output Control types identify how to map to the input data and the type of reformatting to use. The Data Field (Name Search) and Data Field (Tag Search) values map the output field to the input field by either name or tag. Other output control types define details concerning data mapping.

6. Specify the values for the remaining fields on the Properties tab. Depending on the control type you selected, some fields are enabled or disabled. For example, you can define Data Field (Name Search) output controls using the steps described in the following procedure.

   1. Select an operation to perform from the Output Operation drop-down list. The default is None. This value indicates that no operations are performed on the input data. In this case, the data is just copied.

   2. Select the Optional checkbox to make the output field optional. Optional means Formatter should continue with the output message if the field was not found in the input message or the input field was NULL.

      By default, the output control is mandatory. Mandatory means Formatter should fail with an error message if the field was not found in the input message or the input field was NULL, and there was no data-producing operation associated with the output control.

   3. Select a data type from the Data Type drop-down list if enabled.

   4. Choose from the following options:

   - Select a base data type from the Base Data Type drop-down list if you selected Date and Time, Date, Time, or Custom Date and Time as your data type.

   - Select a date/time format from the Data Format drop-down list if you selected Custom Date and Time as your data type.

7. Select the data type for the tag from the Tag Type drop-down list.

8. Click Apply to save your changes to the iiDatabase.

Assigning and Defining Output Control Attribute Operations

The Output Control Attribute Operations section of the Properties tab allows you to assign existing or define new default and length output operations. You can also assign case and justification operations in this section. You cannot change existing operations from this section; however, you can change operations using the Extended Properties tab. See Using the Extended Properties Tab for more information.

The Output Control Attribute Operations section is shown in Figure 3-6.

Figure 3-6 Output Control Attribute Operations Section

You can define new default or length output operations by using the steps described in the following procedure.

1. Type a default output operations name in the Name field of the Default group. If there are matches for the characters you are typing, the matches scroll as you type to allow you to select an existing item. A non-matching name is added as a new name.

2. Click the Value field and type a new value or select an existing value.

3. Type the name of a length output operation in the Name field of the Length group to define a new length. If there are matches for the characters you are typing, the matches scroll as you type to allow you to select an existing item. A non-matching name is added as a new name.

4. Click the Value field and type a new value or select an existing value.

5. Click the Pad field and type a new value or select a value from the drop-down list of literals to assign a pad character.

6. Click Apply to save your changes to the iiDatabase.

You can assign existing output operations by using the steps described in the following procedure.

1. Select the appropriate case from the Case group.

2. Select an output operations name in the Name field of the Default group. If there are matches for the characters you are typing, the matches scroll as you type to allow you to select an existing item.

3. Type a name in the Name field of the Length group to define a new length. If there are matches for the characters you are typing, the matches scroll as you type to allow you to select an existing item.

4. Click the Pad field and type a new value or select a value from the drop-down list of literals to assign a pad character.

5. Click Apply to save your changes to the iiDatabase.

Using the Extended Properties Tab

You can define and modify output operations and collections and assign them to an associated output control from the Extended Properties tab. If you select more than one output operation, a new output operation collection is created that begins with the name of the output control. If more than one output operation exists for a control, a number is appended to the name (for example, SS_1 for an output operation collection assigned to SS).

Selecting a case, justification, default, and length operation assigns them to a collection in the following order: default, case, length, and justify. This order is enforced by the initial assignment only.

The sections of the Extended Properties tab are labeled in Figure 3-7 and described in Table 3-3.

Figure 3-7 Extended Properties Tab

####

Table 3-3 Extended Properties

Label | Section | Description
--- | --- | ---
A | Available Operations | Available output operations and output operation collections in read-only mode. This list can be filtered. You can select any or all of the items in this list and apply them to the output control by dragging and dropping the items onto the control.
B | Add (>) and Remove (<) Buttons | The Add (< ) and Remove (>) buttons provide a fast way to perform specific tasks. The buttons behave differently, depending on what is selected. To assign operations to an output control, select the output control in the Formatter tree view, select the operations in the Available Operations list, and click >. To remove operations from an output control, select the output control in the Formatter tree view, select the operations in the Available Operations list, and click <. To remove an output operation or output operation collection, select it and click <. A confirmation box appears asking you to confirm the removal.
C | Selected Operations | The Selected operations list is a tree view containing a duplication of the output control from the main tree view; however, functionality not available in the main tree view is available in this list. With a collection selected, you can reorder the sequence of output operations in the output operations collections tab. Pop-up menus are available allowing you to create, remove, open, expand, and collapse items. Creating a new item with an output control selected in the tree view assigns the new item to the control. If an output operation or output operation collection is selected, you can access the pop-up menu and select Duplicate. Caution: A change made to any assigned component of an output control affects all controls that use that component.
D | Output Operation Collections | A list of output operation collections.
E | Action | Select Search to find items in the list of available output operations. Type the associated text in the Search text box. Select Filter to narrow the available output operations. Type the associated text in the Filter text box.
F | Filter Options | Use these options to either search or filter the available output operations. Only the Available Operations section is affected-the Formatter tree does not change.
G | Filter Text Box | Use the Filter text box to either search or filter criteria.
H | Operation Types | Select one or more items to filter. If you select Justify, Length is automatically selected also because these items are associated.
I | Hints | Hints guide you through the functionality of the tab. The hint changes to associate with the section in which you are positioned.
J | Apply Filter Button | Click this button to apply the filter. The list of operations is filtered to show only the selected items.
K | Clear Filter Button | Click this button to clear all parameters for searching and filtering. All available output operations are then displayed.

Saving an Output Control as an Input Control

You can save output controls as input controls. The input controls mirror (as closely as possible) the contents of the output control. The input control may have to be modified, because certain properties of output controls do not have exact matches on the input control side.

You can save an output control as an input control using the steps described in the following procedure.

1. Select the output control you want to save as an input control in the left pane of the Formatter window and right-click. A pop-up menu appears.

2. Select Save as Input. The output control is saved as an input control with the prefix IFC_ExistingName_# and appears in the Input Controls list.

   For example, the first time the output control Output_Control is saved as an input control, it is saved as IFC_1_Input_Control. The second time, it is saved as IFC_2_Input_Control.

   To change or add information for the input control, select it and modify the details on the Input Control property sheet.

Output Operation Collections

Use Output Operations Collections to group and sequence a series of output operations and other output operation collections. Operations are executed in the order in which they appear.

Note: You cannot create collections that contain themselves. If you see the Recursion icon, it is probable that something has corrupted the data in the iiDatabase.

You can define an output operation collection by using the steps described in the following procedure.

1. Select Output Operation Collection in the left pane of the Formatter window and right-click. A pop-up menu appears.

2. Select New. A new collection is added to the left pane.

   The cursor is positioned in the text box where you can type a unique Output Operation Collection name. Names must be 32 characters or less.

3. Press Enter to finish defining the Output Operation Collection. The new entry moves to its alphabetical location in the list and is highlighted.

4. Right-click the new collection and choose Add Output Operations. The Output Operations window appears as in Figure 3-8.

   Figure 3-8 Output Operations

5. Select the operations you want to add and click Accept Selection.

   Notes: To reorder component output operations or output operation collections, click and drag the component to the highest level of the collection.

   To move one operation to a partition preceding another operation, drag the operation that you want to move and place it on top of the operation that it should precede. You can rearrange the other components to fit the new order using this method.

Output Operations

Output operations provide the different actions that can be performed on an output field. Using operations, you can, for example, change the case of output data, perform mathematical expressions based on input field contents, and extract substrings.

Through the use of output operation collections, you can collect operations to perform them sequentially. For example, you can left justify and right trim a substring of the contents of an input field. The order in which these operations are defined in the collection is the order in which they are performed.

Available operations are described in Table 3-4.

####

Table 3-4 Output Operation Types

Output Operation Type | Description
--- | ---
Case | Case operations affect the case of the field data. The two defined case operations are LOWER_CASE and UPPER_CASE.
Default | Default operations provide a default value for a field if an input field either does not exist in the input message or has a length of zero.
Prefix/Suffix | Prefix/Suffix operations enable you to attach literals to the beginning or end of the field data. Note: The NULL value option forces the prefix/suffix value to be generated.
Justification | Justification operations justify field data to be left, center, or right within the length of the field. For pad characters, Justify operations must proceed a Length operation in a collection. To specify a pad character other than the default (a space), select the desired pad character in the associated Length operation. If Center Justify is specified, the data can be padded on both the left and right. The Justify and Length operations are related.
Length | Length operations ensure that an output string is given a length. If the data length is longer than the specified length, the data is truncated. If the data length is shorter than the specified length, pad characters are used. Non-numeric data types are padded on the right; numeric data types are padded on the left. The Length and Justify operations are related.
Math Expression | Math Expression operations output a value resulting from an arithmetic expression. The expression can be built using arithmetic operators, constants, and input field values. For more information, see Math Expression.
Substitute | Substitute operations enable you to define a list of input strings to substitute and the output strings to replace them. For each substitute item within a substitute operation, define a literal to look for as the input value, a literal to replace it with, and the data type in which to output the new data. For more information, see Substitute.
Substring | Substring operations enable you to extract a portion of an input string, defined by start byte position and length, and place it in the output field.
Trim | Trim operations remove a defined trim character to the right and left of the output data.

Default

You can define a default operation using the steps described in the following procedure.

1. Select the Default operation category in the left pane and right-click. A popup menu appears.

2. Select New. A new operation is added to the left pane.

   The cursor is positioned in the text box where you can type a unique operation name.

   Note: Default operation names have a 32-character maximum length.

3. Press Enter to finish defining the Default operation. The new entry moves to its alphabetical location in the list and is highlighted.

4. Select the Properties tab in the right pane.

5. Select a literal from the Default Value drop-down list to use as the default value.

6. Click Apply to save your changes to the iiDatabase.

Prefix/Suffix

Prefix/Suffix operations allow you to specify a literal for use as a prefix or suffix. Prefixes are added to the beginning of an output field. Suffixes are added to the end of an output field. For example, you may want to place a less-than sign (<) before and a greater-than sign (>) after the output data. This would require a Prefix of < and a Suffix of >. Any defined literal may be used as a prefix or suffix.

You can define a prefix/suffix operation using the steps described in the following procedure.

1. Select the Prefix/Suffix operation category in the left pane and right-click. A popup menu appears.

2. Select New. A new operation is added to the left pane.

   The cursor is positioned in the text box where you can type a unique Prefix/Suffix operation name.

   Note: Prefix/Suffix Operation names have a 32-character maximum length.

3. Press Enter to finish defining the Prefix/Suffix operation. The new entry moves to its alphabetical location in the list and is highlighted.

4. Select the Properties tab in the right pane.

5. Select the type of Prefix/Suffix from the Prefix/Suffix drop-down list. Select Prefix if the literal is to come before the output data or Suffix if the literal is to come after the output data.

6. Select a literal from the Value drop-down list.

7. Check the Null Action box if the input field is not present in the input message.

8. Click Apply to save your changes to the iiDatabase.

Length

You can define a Length operation by using the steps described in the following procedure.

1. Select the Length operation category in the left pane and right-click. A popup menu appears.

2. Select New. A new operation is added to the left pane.

   The cursor is positioned in the text box where you can type the new, unique Length operation name.

   Note: Length Operation names have a 32-character maximum length.

3. Press Enter to finish defining the Length operation. The new entry moves to its alphabetical location in the list and is highlighted.

4. Select the Properties tab in the right pane.

5. Select a pad character from the Pad Character drop-down list if the data length is less than the length specified for the output.

6. Use the Length field to specify the exact length for the output field.

7. Click Apply to save your changes to the iiDatabase.

Math Expression

Using math expression operations, you can output a value resulting from an arithmetic expression. The expression can be built using arithmetic operators, constants, and input field values.

When input field names are used in math expressions, the math expression parser extracts the current value for the fields specified in the math expression. Alternatively, you can define a single math expression to use input fields that are currently mapped to the output for which the output math expression is applied. The string $MAPPED_INFIELD in a math expression is used in place of or in addition to field names. The value of the input field that is currently mapped to the output field replaces $MAPPED_INFIELD.

For example, suppose the following relationships exist.

- inField1 has a value of 10 and maps to OutField1

- inField2 has a value of 200 and maps to OutField2

- inField3 has a value of 300 and maps to OutField3

If you apply the math expression inField1 + $MAPPED_INFIELD to OutField2, the result is 210. Likewise, if you apply the same math expression to OutField3, the result is 310.

The ability to substitute the value of the currently mapped input field is useful when the same calculation is applied to multiple input fields. Instead of defining a unique math expression with the same calculation for each field and explicitly naming fields in each math expression, define a single math expression containing $MAPPED_INFIELD. Use this math expression in all of the output controls associated with the output fields that are mapped to the input fields modifying the calculation.

Note: The math expression function ignores results and data from any previous operations.

For example, suppose you define an input message with fields InF1, InF2, and InF3, and an output message is defined with field OutF1. You could define a math expression as part of an output control associated with output message field

>      OutF1 as: InF1 + InF2 * -InF3

This expression is evaluated as InF1 + (InF2 *(- InF3)) based on the precedence rules.

Other expression examples include:

>     InF1 + -InF2
>     InF1 * 8
>     InF1 * 9.3
>     InF1 * -8
>     InF1 * -9.3
>     (InF1 + InF2) * 3/InF3
>     (InF1 * (InF2 + InF3) * 4)

You can define a math expression operation using the steps described in the following procedure.

1. Select the math expression output operation in the left pane of the Formatter window and right-click. A pop-up menu appears.

2. Select New. A new operation is added to the left pane.

   The cursor is positioned in the text box where you can type a unique math expression operation name.

3. Press Enter. The new entry is highlighted and moves to its alphabetical location in the list.

4. Click the Decimal Precision field as shown in Figure 3-9 and type the number of decimal points to which the expression result should be rounded.

   Figure 3-9 Math Expression Properties Tab

5. Select whether the expression result should be rounded up or down in the Round group.

6. Type the expression in the Math Expression field. Fields defined in mathematical expressions must be in quotes (for example, "field1" = "field2"). A field name cannot contain a dash (for example, if the field name is abc-def, rename the name to abc_def).

7. Click Apply to save your changes to the iiDatabase.

   Note: When multiplying fields in math expressions, multiply by 1.0 to avoid erroneous characters after the decimal. To set up an output control to handle a 6-digit ASCII number and insert a decimal, multiply the number by 1.000 where the number of zeroes after the decimal equals the amount of decimal precision required in the final number. Do not use terminating characters such as carriage returns or line feeds.

Substitute

Substitute operations enable you to define a list of input strings to substitute and the output strings to replace them.

For example, each time Formatter receives the value x as input, you want to output the value as xx. You can change the value from the input of x to the output of xx.

You can add a literal with the value NONE and assign it an output value. This acts as a default substitution if there is no match for the input value.

You can define a Substitute operation using the steps described in the following procedure.

1. Select Substitute operation in the left pane of the Formatter window and right-click. A pop-up menu appears.

2. Select New. A new operation is added to the left pane.

   The cursor is positioned in the text box, where you can type a unique Substitute operation name.

   Note: Substitute operation names have a 32-character maximum length.

3. Press Enter to finish defining the Substitute operation. The new entry is highlighted and moves to its alphabetical location in the list.

   The Substitute operation itself has no properties. You must add Substitute Items.

4. Select the substitute operation you want to add items to in the left pane of the Formatter window and right-click. A pop-up menu appears.

5. Select Add Substitute Items. The Literal dialog appears as in Figure 3-10.

   Figure 3-10 Literal

6. Select the literals you want to use as input strings and click Accept Selection.

7. Click the new substitute operation in the left pane. The corresponding Properties tab appears in the right pane.

8. Select for each substitute item:

   - A data type from the Output Data Type drop-down list.

   - A literal from the Output Value drop-down list. This value is substituted for the value specified in the Input Value drop-down list.

9. Click Apply to save your changes to the iiDatabase.

10. Repeat steps 8 and 9 for each substitute item.

Substring

Substring operations extract part of an input field's contents (defined by byte position and length) and places it in the output field. Only the String, Numeric, EBCDIC, and Binary data types can be used for substrings.

You can define a substring operation using the steps described in the following procedure.

1. Select the Substring operation category in the left pane and right-click. A popup menu appear.

2. Select New. A new operation is added to the left pane.

   The cursor is positioned in the text box where you can type the new, unique substring name.

   Note: Substring operation names have a 32-character maximum length.

3. Press Enter to finish defining the substring. The new entry moves to its alphabetical location in the list and is highlighted.

4. Select the Properties tab in the right pane.

5. Specify the starting position for the substring in the Substring Start field.

6. Specify the length of the substring in the Substring Length field.

7. Specify the literal to use as a padding character in the Pad Character drop-down list. The pad character is used if the length of the substring is greater than the length of the data, padding the data on the right.

8. Click Apply to save your changes to the iiDatabase.

Trim

You can define a Trim operation using the steps described in the following procedure.

1. Select the Trim operation category in the left pane and right-click. A popup menu appears.

2. Select New. A new operation is added to the left pane.

   The cursor is positioned in the text box where you can type a unique Trim operation name.

   Note: Trim Operation names have a 32-character maximum length.

3. Press Enter to finish defining the Trim operation. The new entry moves to its alphabetical location in the list and is highlighted.

4. Select the Properties tab in the right pane.

5. Select a literal to trim from the Trim Value drop-down list.

6. Select where you want to remove the Trim Value from the output field.

7. Click Apply to save your changes to the iiDatabase.

Formats

Use the Formats function to build both input and output formats. The formats can be either flat or compound.

The component formats of a compound format are either optional or mandatory. An optional component can have missing components, and the parse or reformat will still succeed. A mandatory component must exist, and all its mandatory components must also exist, or the parse or reformat will fail. The component formats are mandatory by default.

Before creating flat or compound formats, define their component parts. The component parts for each format are described in Table 3-5.

####

Table 3-5 Format Component Parts

Format | Components
--- | ---
Flat input format | Literals, fields, and input (parse) controls
Flat output format | Literals, fields, and output controls, output operations, and output operation collections
Compound input format | Flat input formats or other compound input formats
Compound output format | Flat output formats or other compound output formats

Creating a Format

You can create a new format using the steps described in the following procedure.

1. Select Formats from the tree in the Formatter window and click the right mouse button. A pop-up menu appears.

2. Select New. Hold down the right mouse button while navigating to the submenu to the right. This opens the submenu. Choose one of the following:

   - Select Compound to create a compound format, and select Input or Output to create an input format or output format respectively. A new format component is added to the left-hand pane.

   - Select Flat to create a flat format, and select Input or Output to create an input format or output format respectively. A new format component is added to the left-hand pane.

3. Type a unique format name in the text box and press Enter. The name is alphabetically inserted into the list of formats, and the associated tabs are displayed in the right pane.

4. Click the Properties tab if it is not already selected. Depending on which format you selected (compound versus flat and input versus output), different fields will display on the Properties tab. For example, you can create a flat input format using the steps described in the following procedure.

   1. Select the Random Field Order checkbox to specify the component format order as Random (fields can appear in any order). The default order is ordinal (the fields appear in the specified order in the input message).

   2. Click the Format Termination field to open the drop-down list and select a termination type. Format Termination types are described in Table 3-6.

      ####

      Table 3-6 Format Termination Types

      Format Termination Value | Description
      --- | ---
      Not Applicable | No data termination. Read to end of message.
      Delimiter | The format is terminated by a delimiter.
      Exact Length | The format has a fixed length.
      White Space Delimited | The format is terminated by a white space.
      Minimum Length + Delimiter | Parse a minimum number of characters and then look for a delimiter.
      Minimum Length + White Space | Parse a minimum number of characters and then look for a white space.

      If the termination type is Delimiter or Minimum Length + Delimiter, select a literal from the Delimiter drop-down list.

      If the termination type is Exact Length, Minimum Length + Delimiter, or Minimum Length + White Space, enter the fixed length of the field or the minimum number of characters to parse before looking for a delimiter or white space in the Length field.

   3. Select the format in the tree where you want to add fields and right-click. The pop-up menu appears.

   4. Select Add Field Components from the pop-up menu. The Field dialog appears displaying a list of the fields.

   5. Select the fields that you want to add and click Accept Selection. The fields are added to the format tree.

      Notes: When selecting components for the format, make sure each component has associated input controls and fields on its property sheets.

      To select fields used in another format, click the Format Filter drop-down list and select a format. The field list changes to list only fields that appear in the selected format. To return to the complete list of fields, click the Format Filter drop-down list and select Not Applicable.

   6. Click Apply to save your changes to the iiDatabase.

Saving a Flat Input Format as a Flat Output Format

The flat output format mirrors, as much as possible, the contents of the flat input format; however, the termination type, length, and delimiter are defaulted for the output flat format.

You can save a flat input format as a flat output format using the steps described in the following procedure.

1. Select the flat input format you want to save as a flat output format in the left pane of the Formatter window and right-click. A pop-up menu appears.

2. Select Save as Output. A confirmation box appears asking if you are sure you want to save the flat input format as a flat output format. Click Yes. A new flat output format OFF_ExistingName_# appears in the Formats section of the tree.

   For example, the first time the flat input format is saved as a flat output format, it is saved as OFF_NewInputFormat_1. The second time, it is saved as OFF_NewInputFormat_2.

   The Objects Created Summary dialog appears containing a list with the new format name and any controls created.

3. Select a control and modify its details to change information for the output controls created.

Alternative Input and Output Formats

Alternative formats are a special form of compound format in which one format in a set of alternatives will apply to a message. For example, if an alternative format is named A, it may contain component formats B, C, and D. A message of format A may actually be of variation B, C, or D.

Exactly one of the alternatives must apply or the entire alternative compound format does not apply.

An alternative format can be used anywhere a format can be used, and each component format can be any kind of its respective parent input or output format.

Optional Components and Fields

Optional components and fields are each characterized as optional within the context of a compound object.

For example, a compound format composed of component formats may have a mix of mandatory and optional component formats. A format may also have a mix of mandatory and optional fields.

If a mandatory component (of a format or field) is not present in a message, the compound or flat format does not apply. However, if an optional component is not present, Formatter continues to the next component. All component formats in an Alternative Compound should be mandatory.

Alternative Input Formats

If an alternative input format is applied to an input message, the first component of the alternative format is compared to the message. If it parses with the first component format, parsing is finished. If parsing fails, Formatter tries the second component format. If that fails, it tries the next component format. If all components fail to parse, then the parse for the entire alternative input format fails.

Alternative Input Formats and Parsing

If a format has optional fields and the fields are delimited and not tagged, it may be impossible to determine which of the optional fields occur in an input message. For example, if a simple space-delimited format is:

>     [F1] F2 [F3] [F4]

The first, third, and fourth fields are optional. If an input message value1 value2 value3 is received, there is no way, without some rules to remove ambiguity, to determine if the message is actually F1 F2 F3, F2 F3 F4, or F1 F2 F4.

Alternative input formats enable you to specify all possible configurations of mandatory and optional fields in a format. You must explicitly define all possible combinations to avoid possible parsing errors-Formatter does not recursively try all combinations.

As an example, if you have the following input format:

>     Field 1: optional, comma delimited
>     Field 2: mandatory, colon delimited
>     Field 3: optional, comma delimited
>     Field 4: optional, forward-slash delimited

The input message "field1,field2:field3,field4/" parses into four fields correctly. However, "field1 field2:field3,field4/" fails. The first field of the format is comma delimited and parsed as "field1 field2:field3". The second field is colon delimited, so Formatter looks for a colon in "field4/", detects the end of the message, and fails to parse.

You have to explicitly define all possible combinations (F1 F2 F3, F2 F3 F4, F1 F2 F4). In this case, the second alternative format would have three fields, starting with the mandatory colon-delimited field.

For alternative formats, you determine the order in which alternative components are parsed. Remember that components are taken on a first-parsed, only-parsed basis. With that in mind, component order is critical.

For example, if you have a message "abcde," you could specify two alternatives (or more). It could be parsed into a 5-byte field or two separate fields, one 2-bytes long and one 3-bytes long. If the 5-byte field format is the first alternative, you will never parse using the second format. If two parses are valid for the same input, only the first occurs.

Alternative Output Formats

To format an alternative output format, Formatter attempts to create the first component of the alternative format. If creating the first component is successful, formatting is finished. If it fails, Formatter tries to create the second component, and so on. If all components fail to be created, formatting the alternative output format fails.

For information on using alternative formats in Formatter, refer to Output Controls.

Note: A component is not created if a mandatory component or field for the output format is not present in the incoming message.

Tagged Input Formats

A compound format can have a property of Tagged Ordinal. This means that the first field in each component format is a literal. The component format can be flat or compound.

Tagged Input with Alternative Component Example

Tagged input formats can be useful when used in conjunction with alternative formats. The following is an example of what might come in the data segment of a SWIFT message.

>     ":10:f1 f2 f3<CRLF>:20:C/1234/<CRLF>first description<CRLF>second description<CRLF>:30:f4,f5<CRLF>"

The following is a loose definition of the format:

>     :10: field1 field2 field3 <CRLF>
>     :20: [C/acctnum/< CRLF>] (optional)
>     desc1 <CRLF>
>     [desc2 <CRLF>] (optional)
>     :30:first, second <CRLF>

Parse segment :20: using the following rules:

- If there are two slash-delimited fields before the <CRLF>, the credit code and account number exist.

- If not, continue with the mandatory desc1 field, followed by an optional desc2 field.

- Do not run into the :30: segment by parsing ":30:first, second" into the <CRLF>-delimited desc2 field when the desc2 field is not present (it is optional).

With tagged formats, you now have a way to ensure that you do not overrun the boundaries of the :20: segment. Any trailing optional fields in a tagged flat format can be parsed or determined to be absent by parsing only up to the component boundary, instead of looking for a field delimiter (or other termination) beyond the component boundary.

Define a compound tagged format with three components as follows:

>     Segment10 :
>     	First Field Literal ":10:"
>     	space-delim field
>     	space-delim field
>     	<CRLF> delim field

>     Segment20 : Alternative format with two components

>     Segment20_1 (this is the first alternative component)
>     	First Field Literal ":20:"
>     	Credit Code : slash delim, mandatory
>     	AcctNum :  /<CRLF> delim, mandatory
>     	desc1 : <CRLF> delim, mandatory
>     	desc2 : <CRLF> delim, optional

>        Segment20_2 (this is the second alternative component)
>     	First Field Literal ":20:"
>     	desc1 : <CRLF> delim, mandatory
>     	desc2 : <CRLF> delim, optional

>     Segment30 :
>        First Field Literal ":30:"
>        comma delim field
>        <CRLF> delim field

When parsing a Segment20, the parser first attempts to parse Segment20_1. If it fails, it parses the second alternative. The credit code and account number are not part of this particular :20: segment.

You could have different first field literals for 20_1 and 20_2 (for example, :20A: and :20B:) like SWIFT sometimes does.

You can include tagged input format as a component of a compound, where the other components can be any other kind of input format. For SWIFT, you might define a SWIFT 570 message as a compound ordinal of three components:

>     	Basic Header : Ordinal Flat Format
>     	570 Data Segment : Tagged Compound Format
>     	Trailer : Random Tagged Flat

Tagged formats do not apply to output formats. An output format can certainly have a first field literal, but calling it a tagged format does not gain anything. It is only when you need an additional way to determine message boundaries when parsing an input message where first field literals become necessary.

Alternative Output Format Example

Creating an output format is conceptually clearer. You define a set of alternatives, then define an alternative compound having all of the alternatives as components, sequenced in order of desirability. As with input formats, it may be appropriate to order alternatives from specific to general. (This is not always the case. Many times, order is irrelevant on output because of mutually exclusive mandatory fields; there is only one format that applies.)

Using the previous description of a :20: segment, assume you have to create a :20: segment instead of parsing it. You do not know what kind of input message you had, whether it was a Segment20_1, Segment20_2, or some other input format that allowed a parse of some or all of the fields required for a segment 20.

You cannot just say you have some optional leading fields CreditCode and AcctNum, because you have to put in a <CRLF> if the fields exist, but not if they do not.

Create a set of two alternatives:

>     Seg20_1 1literal :20:
>     	2CreditCode Mandatory with / delim
>     	3AcctNum Mandatory with /<CRLF> delim
>     	4desc1 Mandatory with <CRLF> delim
>     	5desc2 Optional with <CRLF> delim

>     Seg20_2 1literal :20:
>     	2desc1 Mandatory with <CRLF> delim
>     	3desc2 Optional with <CRLF> delim

Notice the similarity between the two. It is easy to go from most specific to more general by using the Formatter Save As and Field Delete features. By having several mandatory fields in a format, you are ANDing their existence together. All must be present to create the given format. If you sequenced Seg20_2 before Seg20_1 in the alternative output (compound) format, Seg20_1 would never be applied.

Copyright © 2000 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.