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

Building Format Definitions

This chapter describes Information Integrator Formats and gives instructions on using the Formatter application. The following topics are discussed:

- Understanding Information Integrator Formats

- Using the Formatter Interface

- Using Formatter to Build Definitions

- Field Mapping and Transformation

- Example

Understanding Information Integrator Formats

Message formats define the layout of data that is to be processed by the IISERVER. This layout defines the actual "wire format" of the data that is communicated between collaborating applications. Each data item, such as a person's name, is defined as a field. For example, if a message consisted of an employee's name and an employee's Social Security Number, the message contains two fields. For each defined field, an input control and an output control must be defined. The input control indicates how to parse the field, and the output control indicates how to output the field. Groups of fields are called flat formats. Groups of flat formats are termed compound formats. By defining fields, controls, and formats, the layout of the data is made available to the IISERVER component, so that it can perform the defined translation and actions at run-time.

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

- MsgDefAdmin importer utility - An easy-to-use command-line tool that allows you to store format definitions in the Information Integrator Database. For instructions on using the MsgDefAdmin utility, refer to Using MsgDefAdmin.

- Formatter graphical user interface (GUI) - Allows you to populate screens with format definition data and store the information in the Information Integrator Database.

Using the Formatter Interface

The Formatter graphical user interface (GUI) allows you to create formats from the "bottom up." You create the formatter components first; then, you build the format. These components are generic and can be used for more than one format.

Starting Formatter

Start the Formatter GUI as follows:

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

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

   Figure 4-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 4-2.

   Figure 4-2 Formatter Main Window

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 the Formatter Window

Each Formatter window is split into two panes. The left pane displays a list of all Format Collections, Formats, Input Controls, Output Controls, Output Operations, Output Operation Collections, Fields, and Literals. Single-click each category to display a list of its contents in the right pane. Double-click each category to expand or display its contents in the left pane. For example, double-click to expand the Formats category to show all defined input and output formats. You can then double-click a format name (or click the + sign to its left) to display its associated fields or formats.

The right pane, or Property Sheet, is where you'll be adding the majority of information. It uses tabbed sheets to display the details for whichever object is currently selected. For example, if you have a field in an input format selected, it displays the Field and Input Control Names for that field on a Properties tab.

Note: You can open more than one Formatter window at a time for access to multiple component types at the same time. This is necessary when assigning fields and input or output controls to formats.

Opening a New Window

To open a new window, select New from the File menu.

Tip

When the Formatter window opens, it may default to a size too small to display all window components, including the Apply, Cancel, and Help buttons on some property sheets. Maximize the application or resize the window to see all window components.

Renaming Components

Formatter components can be renamed in the left pane of the Formatter window. To rename a component, follow these steps.

1. In the left pane of the Formatter window, select the component name.

2. Click again without moving the mouse a text box appears around the selected component name and is highlighted.

3. Edit the component name.

4. Press ENTER or click the mouse outside the component name text box. If there is no duplicate name, the component name is highlighted and moves to its alphabetical location in the list.

   Note: Formatter component names must be 32 characters or less.

Duplicating Components

Formatter components can be duplicated in the left pane of the Formatter window. To duplicate a component, follow these steps.

1. In the left pane of the Formatter window, select any user-defined component and right-click. A popup menu appears.

2. Select Duplicate. A copy of the component is made and a text box appears around the duplicated component name.

3. Type the new component name.

4. Press ENTER or click the mouse outside the component name text box. If there is no duplicate name, the component name is highlighted and moves to its alphabetical location in the list.

Deleting Components

Formatter components can be deleted in the left pane of the Formatter window. To delete a component, follow these steps.

1. In the left pane of the Formatter window, select any user-defined component and right-click. A popup menu appears.

2. Select Delete. A dialog box appears asking if you are sure you want to delete the component.

3. Choose either Yes or No to confirm or cancel your action.

Tips

To delete an input format with a field used in conditional branching, use one of the following methods:

- Export the format, delete the field, then import the format.

- Delete the rule from the field, then delete the field from the format.

Using the Used In Tab

The Used In tab displays a list of all places where the selected object is being used. For example, the Used In tab for an input control displays a list of all input formats containing the input control.

To view the Used In tab, follow these steps.

1. With the property sheet open for the object you are interested in, select the Used In tab. The Used In list appears.

2. To go to a specific component where the object is used, select the component and double-click. A new window opens with the component selected.

Using Open Item

The Open Item function opens a new window from within a properties tab or tree. The new window displays the information for the selected component in the tab. You can change the information in this window.

To find information about a component, follow these steps.

1. In a Formatter tab, right-click the item you want to see. A pop-up menu appears.

2. Choose Open Item. A new Formatter window appears displaying information for the selected item.

3. Either view or change the information in the window.

Using Drag and Drop

Use drag and drop to:

- Associate subordinate components from one window into the related Collection tab of another window. Example: associating fields or controls with a flat format.

- Associate input fields with output fields from the Field Map tab of a flat output format.

- Reorder fields (in flat input and output formats)

- Reorder formats (in compound and input and output formats)

- Map fields in the Field Mapping window

- Assign either a single or multiple output operations to an output control from the Output Operation Extended Properties tab

- Reorder the sequence of operations from the Output Operation Collections tab

Drag and drop works across both windows and panes. To copy an object using drag and drop, you must drag the object from the first window's tree to the second window's tab. You cannot drag and drop in the same pane unless you are reordering fields, formats, or output operations in a collection or using field mapping.

You can only drag and drop at the root level of the left pane tree view. When you drop an object, it's always added to the end of the list. Note that you can't drag and drop literals. You must select them from the appropriate drop-down lists.

Using Formatter to Build Definitions

The steps involved in creating a format definition using the Formatter GUI are as follows.

1. Defining Literals

2. Defining Fields

3. Defining Output Operations

4. Creating Output Operation Collections

5. Defining Input Controls

6. Defining Output Controls

7. Building Formats

These steps are described in the following sections.

Defining Literals

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

- Delimiters, prefixes and suffixes

- Default values

- Trim and pad characters

- Tag values

- Data Validation values

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, as well as hex values that can include printable and non-printable characters.

Notes: The maximum character length of a literal is 127.
Do not use single quotes in literal names.
When literals are used as pad characters, only the first character is used.

Creating a Literal

To create a Literal, follow these steps.

1. Right-click on Literals in the left pane of the Formatter window.

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 shown in Figure 4-3.

   Figure 4-3 Literal Property Sheet

3. Type the name you want to use to identify this Literal 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).

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

Tip

To change the name of a literal in the list:

1. Select the literal name.

2. Click again without moving the mouse. The literal name is now highlighted and in a text box.

3. Type the new name.

4. Press ENTER or click the mouse outside the name text box. The literal name is highlighted and moves to its alphabetical location in the list.

Defining 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.

Creating a Field

To create a field, follow these steps.

1. Right-click on Fields in the left pane of the Formatter window.

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 as shown in Figure 4-4.

   Figure 4-4 Fields Property Sheet

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

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

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

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

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

Tip

To change the name of a field:

1. Select the field name.

2. Click again without moving the mouse. The field name is now highlighted and in a text box.

3. Type the new name.

4. Press ENTER or click the mouse outside the name text box. The field name is highlighted and moves to its alphabetical location in the list.

Defining Output Operations

Output operations provide the different actions that can be performed on an output field. For example, using output operations, you can 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 output operations are described in the following sections.

Case

Case operations affect the case of the field data. Information Integrator includes two pre-defined case operations, as described below:

- LOWER_CASE - Converts String data to all lowercase letters. For example, ABC Corporation becomes abc corporation.

- UPPER_CASE - Converts String data to all uppercase letters. For example, ABC Corporation becomes ABC CORPORATION.

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. To define a default operation, follow the steps below.

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 database.

Justification

Justification operations justify field data to the left, center, or right within the length of the field. Information Integrator includes three pre-defined Justification operations, as described below:

- LEFT_JUSTIFY - Left justifies the data in the field.

- RIGHT_JUSTIFY - Right justifies the data in the field.

- CENTER - Centers the data in the field.

  Note: For pad characters, a Justification operation must precede a Length operation in a collection (see Length for more information). To specify a pad character other than the default (space), select the desired pad character in the associated Length operation. If CENTER is specified for Justification, the data can be padded on both the left and right.

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 to fill in the remaining field length. Non-numeric data types are padded on the right; numeric data types are padded on the left.

Follow the steps below to define a Length operation.

1. Right-click the Length operation category in the left pane of the Formatter window. A popup menu appears.

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

3. Type a new, unique Length operation name.

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

4. Press Enter to finish defining the Length operation. The new entry moves to its alphabetical location in the list and is highlighted. The right pane displays the Length Properties tab.

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

   Pad characters are used to fill space to reach a specified field length, or when the Justify operations are used. For example, if the data length is 4, the field length is 7, and the padding character is an asterisk (*), the field would look as follows:

   data***

6. Enter the exact length for the output field in the Length field.

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

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.

The operators you can use in Math Expressions are: + - * / ( ) and Unary -. These operators are processed in the following order: ( ) * / + -. The operands you can use in Math Expressions are: Numeric, Constants, and Input Field Names.

Note: Field names with spaces or underscores must be surrounded by single or double quotes.

To define a Math Expression, follow the steps below.

1. Right-click the Math Expression output operation in the left pane of the Formatter window. A pop-up menu appears.

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

3. Type a new, unique Math Expression name.

   Note: Math Expression names have a 32-character maximum length.

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

5. In the Decimal Precision text box, type the number of decimal points to which you want the expression result rounded.

6. Select whether the expression result should be rounded up or down.

7. Type the expression in the Math Expression field. Fields defined in mathematical expressions must be in quotes (for example, "field1" = "field2").

   Note: Field names cannot contain dashes.

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

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.

To define a prefix/suffix operation, follow the steps below.

1. Right-click the Prefix/Suffix operation category in the left pane of the Formatter window. A pop-up menu appears.

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

3. Type a new, unique Prefix/Suffix operation name.

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

4. Press Enter to finish defining the Prefix/Suffix operation. The new entry moves to its alphabetical location in the list and is highlighted. The Properties tab displays in the right pane.

5. Select either Prefix or Suffix from the 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. Select the Null Action box if the input field is not present in the input message.

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

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, you 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.

Note: 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.

To define a Substitute operation, follow the steps below.

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

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

3. Type a new, unique Substitute operation name.

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

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

5. Right-click the new Substitute operation in the left pane of the Formatter window. A pop-up menu appears.

6. Select Add Substitute Items. The Literal dialog appears as in Figure 4-5.

   Figure 4-5 Literal

7. Select the literals you want to use as input strings and click Accept Selection. The Substitute items are added under the Substitute operation in the left pane.

8. Click one of the new Substitute items in the left pane. The corresponding Properties tab appears in the right pane.

9. Select the following:

   - A data type from the Output Data Type drop-down list. For an explanation of the supported data types, please refer to Data Types.

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

10. Click Apply to save your changes to the Database.

11. Repeat steps 8, 9, and 10 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.

To define a substring operation, follow the steps below:

1. Right-click the Substring operation category in the left pane of the Formatter window. A popup menu appears.

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

3. Type a new, unique Substring operation name.

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

4. Press Enter to finish defining the substring. The new entry moves to its alphabetical location in the list and is highlighted. The Properties tab displays in the right pane.

5. Specify the literal to use as a pad 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.

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

7. Select End of Field if you want the substring to extend from the specified Start field to the end of the field. Or, specify the length of the substring in the Substring Length field.

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

Trim

Trim operations remove a defined trim character from the right and left of the output data.

To define a Trim operation, follow the steps below.

1. Right-click the Trim operation category in the left pane of the Formatter window. A popup menu appears.

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

3. Type a new, unique Trim operation name.

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

4. Press Enter to finish defining the Trim operation. The new entry moves to its alphabetical location in the list and is highlighted. The Properties tab displays in the right pane.

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

6. Select where you want to remove the Trim Value from the output field in the Trim Type drop-down list.

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

Creating 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.

Follow the steps below to create an Output Operation Collection.

1. Right-click on Output Operation Collection in the left pane of the Formatter window. A pop-up menu appears.

2. Select New from the pop-up menu to create a new Output Operation Collection entry in the left pane.

3. Type a unique Output Operation Collection name in the text box.

   Note: The 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 Output Operation Collection. The new entry moves to its alphabetical location in the list and is highlighted.

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

   Figure 4-6 Output Operations

6. 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.

Defining 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.

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

1. Right-click on Input Controls in the left pane of the Formatter window.

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 as shown in Input Control Property Sheet.

   Figure 4-7 Input Control Property Sheet

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.

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

The procedures for creating each input control type are described in the following sections.

Examples of Input Controls

The following table contains examples of fields that might occur in message and the corresponding Input Control definition. In the table below, the following are previously defined Literals: BEA.Comma, <Name>, *Server, ^\$

####

Example Field in Message | Description | Input Control Definition
--- | --- | ---
John Doe, | String Delimited by a comma | Control Type = Data Only Type = String Termination = Delimiter Delimiter = BEA.Comma
76201 | String having an exact length | Control Type = Data Only Type = String Termination = Exact Length Length = 5
<Name>John Doe, | String proceeded by a tag with a delimiter | Control Type = Tag and Data Type = String Termination = Delimiter Delimiter = BEA.Comma Tag Type = String Tag Value = <Name> Tag Termination = Not Applicable
<Name>8,John Doe | String with a tag that has a length given in the order: tag, length, data | Control Type = Tag-Length and Data Type = String Length Type = Numeric Length Termination = Delimiter Length Delimiter = BEA.Comma Tag Type = String Tag Value = <Name> Tag Termination = Not Applicable
8,<Name>John Doe | String with a tag that has a length given in the order: length, tag, data | Control Type = Length-Tag and Data Type = String Length Type = Numeric Length Termination = Delimiter Length Delimiter = BEA.Comma Tag Type = String Tag Value = <Name> Tag Termination = Not Applicable
8,John Doe | String that has a length given | Control Type = Length and Data Type = String Length Type = Numeric Length Termination = Delimiter Length Delimiter = BEA.Comma
3 | Field that specifies the number of occurrences of another field, 1 digit only | Control Type = Repetition Count Type = Numeric Termination = Exact Length Length = 1
*Server | Literal that must be present in message | Control Type = Literal Termination = Not Applicable Literal = *Server
$198 | String that begins with a $ followed by white space. | Control Type = Regular Expression Termination = White Space Delimited Reg Exp = ^\$

Creating a Data Only Input Control

A Data Only input control specifies that, when parsing a message, any field associated with this input control has a data component only, not an associated length or tag data. For example, some message formats may have simple fields with Strings terminated by commas. The input control might look like:

>     Input Control Name: AsciiStringToComma
>     Control Type: Data Only
>     Optional/Mandatory: Mandatory
>     (Data) Type: String
>     (Data) Termination: Delimiter
>     (Data) Delimiter: Comma (Previously Defined Literal)

Note: The Input Control Type determines which fields require information. Fields containing "Not Applicable" do not require a value.

To create a Data Only input control, follow these steps.

1. With Data Only selected as the Input Control type, select a data type from the Type drop-down list.

2. If the selected data type is Date and Time, Date, Time, or Custom Date and Time, select the Base Type (String or Numeric) the data is output as.

3. If the selected data type is Custom Date and Time, select a date/time format from the Format drop-down list.

4. If your Custom Date and Time format string includes a 2-digit year, you also must choose a Year Cutoff value. The Year Cutoff value tells Formatter how to convert the 2-digit year to a 4-digit year. See Year Cutoff for details.

5. Select a termination type from the Termination drop-down list.

6. If you select Delimiter or Minimum Length + Delimiter as a termination type, select one from the Delimiter drop-down list.

7. If you select 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 literal or white space in the Length field.

8. If the data type requires a decimal, the Decimal Loc field is active. Enter a decimal location or use the arrows to select the desired number. Only a positive value is allowed and it must not be more than the number of digits the field can hold. The value determines how many digits are to the right of the decimal location when Formatter interprets the message data. For example, an input value of 12345 with a decimal location of 2 is interpreted as 123.45.

   Note: Note: Decimal location pertains only to IBM packed and zoned decimal data.

Creating a Tag and Data Input Control

The Tag & Data input control type indicates that there is a literal tag preceding the data. For example, some message formats use tagged fields to indicate the beginning of different sections of a message. If you're defining the start of the heading for a memo, you might define a Tag & Data input control specifying the To: section as: <MemoHead>FirstName,LastName. The input control for the first field might look like:

>     Input Control Name: AsciiStringMemoHeadTagToComma
>     Control Type: Tag & Data
>     Optional/Mandatory: Mandatory
>     Type: String
>     Termination: Delimiter
>     Delimiter: Comma (Previously Defined)
>     (Tag) Type: String
>     Tag Value: <MemoHead>
>     (Tag) Termination: Not Applicable

To create a Tag & Data input control, follow these steps.

1. With Tag & Data selected as the Input Control type, in the Tag section, select a data type for the tag data from the Type drop-down list.

2. From the Tag Value drop-down list, select a literal as the actual tag value to be searched for.

   Note: The literal for the Tag Value must have been created previously.

3. In the Tag section, select the termination type for the tag from the Termination drop-down list.

   The termination type tells Formatter when to stop parsing the tag value. When the tag delimiter is reached, the value that was parsed is compared to the value in the tag value field to determine if the data being searched for has been found.

4. If the tag termination is fixed-length, specify the exact tag length in the Length field.

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

6. In the Data section, select the data type from the Type drop-down list.

7. If the selected data type is Date and Time, Date, Time, or Custom Date and Time, select the Base Type (String or Numeric) the data is output as.

8. If the selected data type is Custom Date and Time, select a date/time format from the Format drop-down list.

9. If your Custom Date and Time format string includes a 2-digit year, you also must choose a Year Cutoff value. The Year Cutoff value tells Formatter how to convert the 2-digit year to a 4-digit year. See Year Cutoff for details.

10. Select a termination type from the Termination drop-down list.

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

12. If you select 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 literal or white space in the Length field.

13. If the data type for the data requires a decimal, the Decimal Loc field is active. Enter a decimal location or use the arrows to select the desired number. Only a positive value is allowed and it must not be more than the number of digits the field can hold. The value determines how many digits are to the right of the decimal location when Formatter interprets the message data. For example, an input value of 12345 with a decimal location of 2 is interpreted as 123.45.

    Note: Decimal location pertains only to IBM packed and zoned decimal data.

Creating a Tag, Length, and Data Input Control

Tag, Length & Data input controls specify that field data starts with a tag, includes embedded length information, and contains data. For example, you might have a tagged field in a random ordered input format that includes an embedded length. If you're defining a tagged, variable-length price figure, you might define the field to look like: <Price>7,1035.25,.

The input control might look like:

>     Input Control Name: PriceTagAndLengthToComma
>     Control Type: Tag, Length & Data
>     Optional/Mandatory: Optional
>     (Data) Type: String
>     (Length) Type: Numeric
>     (Length) Termination: Delimiter
>     (Length) Delimiter: Comma
>     (Tag) Type: String
>     Tag Value: <Price>
>     (Tag) Termination: Exact Length
>     (Tag) Length: 7

To create a Tag, Length & Data input control, follow these steps.

1. With Tag, Length & Data selected as the Input Control type, in the Tag section, select a data type for the tag data from the Type drop-down list.

2. From the Tag Value drop-down list, select a literal as the actual tag value to be searched for.

3. In the Tag section, select the termination type for the tag from the Termination drop-down list.

   The termination type tells Formatter when to stop parsing the tag value. When the tag delimiter is reached, the value that was parsed is compared to the value in the tag value field to determine if the data being searched for has been found.

4. If the tag termination is fixed-length, specify the exact tag length in the Length field.

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

6. In the Length section, select a data type for the length from the Type drop-down list.

7. Select the termination type for the length portion of the data from the Termination type.

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

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

10. In the Data section, select the data type from the Type drop-down list.

11. If the selected data type is Date and Time, Date, Time, or Custom Date and Time, select the Base Type (String or Numeric) the data is output as.

12. If the selected data type is Custom Date and Time, select a date/time format from the Format drop-down list.

13. If your Custom Date and Time format string includes a 2-digit year, you also must choose a Year Cutoff value. The Year Cutoff value tells Formatter how to convert the 2-digit year to a 4-digit year. See Year Cutoff for details.

14. Select a termination type from the Termination drop-down list.

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

16. If you select 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.

17. If the data type for the data requires a decimal, the Decimal Loc field is active. Enter a decimal location or use the arrows to select the desired number. Only a positive value is allowed and it must not be more than the number of digits the field can hold. The value determines how many digits are to the right of the decimal location when Formatter interprets the message data. For example, an input value of 12345 with a decimal location of 2 is interpreted as 123.45.

    Note: Note: Decimal location pertains only to IBM packed and zoned decimal data.

Creating a Length and Data Input Control

Length & Data input controls can be used to parse fields with variable length data. The embedded length indicates the length for the actual field data. For example, messages containing the name and selling price for various pieces of equipment. The bigger the piece of the equipment, the bigger the price. Keeping the messages as compact as possible might be important if you were sending them over a phone line. We will send the length of the selling price, then the price itself:

>     Input Control Name: AsciiNumericLengthAndPrice
>     Control Type: Length & Data
>     Optional/Mandatory: Mandatory
>     (Data) Type: String
>     (Length) Type: Numeric
>     (Length) Termination: Delimited
>     (Length) Delimiter: Comma

To create a Length & Data input control, follow these steps.

1. With Length & Data Only selected as the Input Control type, in the Length section, select a data type for the length from the Type drop-down list.

2. Select the termination type for the length portion of the data from the Termination type.

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

4. If you select 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.

5. In the Data section, select the data type from the Type drop-down list.

6. If the selected data type is Date and Time, Date, Time, or Custom Date and Time, select the Base Type (String or Numeric) the data is output as.

7. If the selected data type is Custom Date and Time, select a date/time format from the Format drop-down list.

8. If your Custom Date and Time format string includes a 2-digit year, you also must choose a Year Cutoff value. The Year Cutoff value tells Formatter how to convert the 2-digit year to a 4-digit year. See Year Cutoff for details.

9. Select a termination type from the Termination drop-down list.

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

11. If the data 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.

12. If the data type for the data requires a decimal, the Decimal Loc field is active. Enter a decimal location or use the arrows to select the desired number. Only a positive value is allowed and it must not be more than the number of digits the field can hold. The value determines how many digits are to the right of the decimal location when Formatter interprets the message data. For example, an input value of 12345 with a decimal location of 2 is interpreted as 123.45.

    Note: Note: Decimal location pertains only to IBM packed and zoned decimal data.

Creating a Repetition Count Input Control

Repetition Count input controls are used to indicate the number of times a component will repeat in the message. For example, an input format may include the daily sales figures for a traveling sales person. Some people in sales send daily updates as to the total amount sold per day. Others might send weekly updates, grouping 7 days together in a single message. The field containing the number of days being sent would need a repetition count input control like the following:

>     Input Control Name: AsciiNumericSalesRepCount
>     Control Type: Repetition Count
>     Optional/Mandatory: Mandatory
>     (Data) Type: Numeric
>     (Data) Termination: Delimiter
>     (Data) Delimiter: Comma

To create a Repetition Count input control, follow these steps.

1. With Repetition Count selected as the Input Control type, select a data type for the repetition count from the Type drop-down list.

2. Select a termination type from the Termination drop-down list.

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

4. If you select 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.

5. If the data type requires a decimal, the Decimal Loc field is active. Enter a decimal location or use the arrows to select the desired number. Only a positive value is allowed and it must not be more than the number of digits the field can hold. The value determines how many digits are to the right of the decimal location when Formatter interprets the message data. For example, an input value of 12345 with a decimal location of 2 is interpreted as 123.45.

   Note: Decimal location pertains only to IBM packed and zoned decimal data.

Creating a Literal Input Control

Formatter uses Literal input controls to make sure a specific literal value is in a message. If the message does not contain the literal and the Literal input control is mandatory, the parse fails. For example, a literal might mark the beginning or end of a component format within a compound input format. It may be as simple as "PART2:" as shown below:

Input Control Name: PART2Literal
Optional/Mandatory: Mandatory
Control Type: Literal
(Data) Termination: Delimiter
(Data) Delimiter: Colon
(Data) Literal: PART2

To create a Literal input control, follow these steps.

1. With Literal selected as the Input Control type, select the data type from the Type drop-down list.

2. Select the literal in the drop down list.

3. Select a termination type from the Termination drop-down list.

4. If you select Delimiter or Minimum Length + Delimiter as a termination type, select one from the Delimiter drop-down list.

5. If you select 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.

6. If the data type requires a decimal, the Decimal Loc field is active. Enter a decimal location or use the arrows to select the desired number. Only a positive value is allowed and it must not be more than the number of digits the field can hold. The value determines how many digits are to the right of the decimal location when Formatter interprets the message data. For example, an input value of 12345 with a decimal location of 2 is interpreted as 123.45.

   Note: Decimal location pertains only to IBM packed and zoned decimal data.

Creating a Length, Tag, and Data Input Control

Length, Tag & Data input controls specify that field data starts with embedded length information, has a tag, and contains data. For example, you might have a tagged field in a random ordered input format that includes an embedded length. If you're defining a tagged, variable-length price figure, you might define the field to look like: 7,<Price>1035.25,.

The input control might look like:

Input Control Name: PriceLengthAndTagToComma
Optional/Mandatory: Optional
Control Type: Length, Tag & Data
(Data) Type: String
(Data) Termination: Delimiter
(Data) Delimiter: Comma (Previously Defined)
(Length) Type: Numeric
(Length) Termination: Delimiter
(Length) Delimiter: Comma
(Tag) Type: String
Tag Value: <Price>
(Tag) Termination: Exact Length
(Tag) Length: 7

To create a Length, Tag & Data input control, follow these steps.

1. With Length, Tag & Data selected as the Input Control type, in the Length section, select the data type for the length from the Type drop-down list.

2. If the selected data type is Date and Time, Date, Time, or Custom Date and Time, select the Base Type (String or Numeric) the data is output as.

3. If the selected data type is Custom Date and Time, select a date/time format from the Format drop-down list.

4. If your Custom Date and Time format string includes a 2-digit year, you also must choose a Year Cutoff value. The Year Cutoff value tells Formatter how to convert the 2-digit year to a 4-digit year. See Year Cutoff for details.

5. Select the termination type for the length portion of the data from the Termination type.

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

7. If you select 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.

8. In the Tag section, select a data type for the tag data from the Type drop-down list.

9. From the Tag Value drop-down list, select a literal as the actual tag value to be searched for.

10. In the Tag section, select the termination type for the tag from the Termination drop-down list.

    The termination type tells Formatter when to stop parsing the tag value. When the tag delimiter is reached, the value that was parsed is compared to the value in the tag value field to determine if the data being searched for has been found.

11. If the tag termination is fixed-length, specify the exact tag length in the Length field.

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

13. In the Data section, select the data type from the Type drop-down list.

14. Select a termination type from the Termination drop-down list.

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

16. If the data 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.

17. If the data type for the data requires a decimal, the Decimal Loc field is active. Enter a decimal location or use the arrows to select the desired number. Only a positive value is allowed and it must not be more than the number of digits the field can hold. The value determines how many digits are to the right of the decimal location when Formatter interprets the message data. For example, an input value of 12345 with a decimal location of 2 is interpreted as 123.45.

    Note: Decimal location pertains only to IBM packed and zoned decimal data.

Creating a Regular Expression Input Control

Regular Expression (RE) input controls express rules for string pattern matching. Instead of direct character-by-character matches, the input control value is interpreted as a regular expression to match the input. String-matching capabilities for this feature comply with the POSIX 1003.2 standard for regular expressions. You can only build REs for ASCII data types (String or Numeric). Within REs, only printable ASCII characters are valid.

The following rules apply for REs:

- Ordinary characters (not specially defined for REs) act as one-character REs to match themselves. For example, if your RE is "X" in a parse control for a repeating field and your message is "X,Y,Z", you will get a match on the first repeating field.

- Backslashes (\) followed by special RE characters act as one-character REs that match the special character. Periods (.), asterisks (*), left square brackets ([), and backslashes (\) are special unless they are within square brackets (see below).

  Note: Carets (^) and dollar signs ($) are not supported. Do not use them in REs without preceding them with a backslash character (\).

- Periods (.) act as one-character REs that match any character except a new line character. For example, if your RE is "." in a parse control for a field and the contents of the field is "This is a sample.", you won't get a match for the field (no space following the sentence).

- Non-empty strings of characters enclosed in square brackets ([]) act as one-character REs that match any one character in the enclosed string. "[a]" searches for the letter "a" in a fields contents.

  The minus (-) character can be used to indicate a range of consecutive characters. For example, [0-9] is equivalent to [0123456789].

  Note that the right square bracket (]) does not terminate such a string when it is the first character within it (after an initial caret, if any). For example "[]a-f]" matches a right square bracket or one of the ASCII letters a through f inclusive. Also note that the four special characters (".", "*", "\", and "[") represent themselves within the square brackets, so "[*]" searches for an asterisk within field contents.

- A one-character RE followed by an asterisk (*) matches zero (0) or more occurrences of the RE. A one-character RE followed by a plus sign (+) matches zero (0) or one occurrence of the RE. If there are multiple strings matching the RE, the longest leftmost string permitting a match is chosen.

- A one-character RE followed by {m}, {m,}, or {m,n} matches a range of occurrences of the one-character. m and n must be non-negative integers less than 256. {m} matches exactly m occurrences. {m,} matches at least m occurrences. And {m,n} matches any number of occurrences between m and n inclusive. If a choice exists, the RE matches as many occurrences as possible.

  For example, "a{3,}" matches 3 or more concatenated "a" characters. This could also be done by REs of "aaa+" or "aaaa*". 7. If REs are concatenated, the merged RE matches the concatenation of the strings matched by each component of the RE. For example, "XY" matches strings containing those two letters side-by-side.

- A RE enclosed between parentheses ("(",")") is a RE that matches whatever the non-parenthesized RE matches. There is no difference between parenthesized and non-parenthesized REs. This is useful when using a complex RE with the + or * operator as in (AB)+ which matches AB, or ABAB, or ABABAB...

- A pipe (|) character indicates an "or". So "(RE1|RE2)" matches either RE1 or RE2.

Examples of regular expressions are:

####

Value | Expression
--- | ---
a | match a
\\ | match \
^a | match a, only if it begins a string
a$ | match a, only if it ends a string
- | match any one character
[abc] | match one of the characters a, b, or c
[^abc] | match any one character that is not a, b, or c
a+ | match a string of one or more of the character a
ab* | match the character a, optionally followed by any number of the character b
a{3} | match 3 or more concatenated characters a. Equivalent to aaa+ or aaaa*
(a|b|\|) | match either the character a or b or |

To create a Regular Expression input control:

1. With Regular Expression selected as the Input Control type, select the data type from the Type drop-down list. Regular Expressions may only be defined using the String data type.

2. Define a Literal for the regular expression. See Defining Literals for details. Regular expressions are strings that express rules for string pattern matching.

3. Select the new regular expression literal from the Delimiter drop-down list.

4. Select a termination type from the Termination drop-down list.

5. If you select Delimiter or Minimum Length + Delimiter as a termination type, select one from the Delimiter drop-down list.

6. If you select Exact Length, Minimum Length + Delimiter, or Minimum Length + White Space, type 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.

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.

To save an input control as an output control, follow these steps.

1. Right-click on the input control you want to save in the left pane of the Formatter window. 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.

Defining 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. Some output control types also allow alternative output formatting. For more information on alternative output formatting, refer to Alternative Input and Output Formats.

The Output Control Properties 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

To create an output control, follow these steps.

1. Right-click on Output Controls from the left pane of the Formatter window. A pop-up menu appears, and the right pane displays the current list of output controls.

2. Select New from the pop-up menu to create a new output control entry in the left pane and open the Output Control property sheet in the right pane, as shown in Figure 4-8.

   Figure 4-8 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.

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.

The procedures for creating each output control type are described in the following sections.

Creating a Data Field (Name Search) Output Control

Data Field (Name Search) output controls map the value of an input field directly to an output field. Formatter searches for the input field value by the field name specified. For example, if the contents of an output field are going to map directly to the contents of an input field, you could define a Data Field (Name Search) output control. The output control would look like:

>     Output Control Name: FieldNameWithComma
>     Output Control Type drop-down list: Data Field (Name Search)
>     Data Type drop-down list: String
>     Input Tag Value field: FirstName
>     Tag Before Length checkbox: (Not checked)
>     Optional checkbox: (Checked)

Notes: To add a comma suffix to the end of the field data, create a Suffix operation, then select it in the Output Operation drop-down list. See Defining Output Controls for more details.
The Output Control type determines which fields require information. Fields containing "Not Applicable" or "NONE" do not require a value.

To define a Data Field (Name Search) output control, follow these steps.

1. With Data Field (Name Search) selected in the Output Control Type drop-down list, select a data type for the output data from the Data Type drop-down list.

2. If the selected data type is Date and Time, Date, Time, or Custom Date and Time, select the Base Data Type (String or Numeric) the data will be output as.

3. If the selected data type is Custom Date and Time, select a date/time format from the Data Format drop-down list.

4. To perform an operation on the data, select one from the Output Operation drop-down list. See operations for details.

5. If the output data is to have an embedded length, specify the Length data type in the Length Type drop-down list.

6. If the output data is to have an associated tag, specify the data type for the tag in the Tag Type drop-down list.

7. If the tag should be output before the embedded length, check the Tag Before Length box.

8. If the output control parse is optional, check the Optional checkbox. Optional means that Formatter should continue with the output message if the field was NULL with no default value or was not referenced in the input layout.

   Note: By default, output controls are mandatory. Mandatory means if the associated input field is either NULL or not referenced in the input format, and there is no default value, the mandatory test fails and Formatter will not output data.

Creating a Data Field (Tag Search) Output Control

Data Field (Tag Search) output controls map the value of an input field directly to an output field. Formatter searches for the input field value by tag, looking for the specified literal tag value in the parsed input message. For example, in a random-ordered flat format, you will need to search for a specific tagged field in the parsed input data. If you're looking for an input Tag & Data field with <FirstName> as the tag and want to output the data minus the tag, the output control might look like:

>     Output Control Name: InTagDataOutDataComma
>     Output Control Type drop-down list: Data Field (Tag Search)
>     Data Type drop-down list: Numeric
>     Input Tag Value field: FirstName
>     Tag Before Length checkbox: (Not checked)
>     Optional checkbox: (Not checked)

Notes: To add a comma suffix to the end of the field data, create a Suffix operation, then select it in the Output Operation drop-down list. See Defining Output Controls for more details.
The Output Control type determines which fields require information. Fields containing "Not Applicable" or "NONE" do not require a value.

To define a Data Field (Tag Search) output control, follow these steps.

1. With Data Field (Tag Search) selected in the Output Control Type drop-down list, select a data type for the output data from the Data Type drop-down list.

2. If the selected data type is Date and Time, Date, Time, or Custom Date and Time, select the Base Data Type (String or Numeric) the data will be output as.

3. If the selected data type is Custom Date and Time, select a date/time format from the Data Format drop-down list.

4. To perform an operation on the data, select one from the Output Operation drop-down list. See operations for details.

5. If the output data is to have an embedded length, specify the Length data type in the Length Type drop-down list.

6. If the output data is to have an associated tag, specify the data type for the tag in the Tag Type drop-down list.

7. After selecting a Tag Type, choose a Literal from the Input Tag Value drop-down list as the tag.

8. If the tag should be output before the embedded length, check the Tag Before Length box.

9. Select a literal from the Input Tag Value drop-down list as the tag value to search for in the input message. This name must match the tag value in the input message exactly. The tag value will be output with the field data.

10. If the output control parse is optional, check the Optional checkbox. Optional means that Formatter should continue with the output message if the field was NULL with no default value or was not referenced in the input layout.

    Note: By default, output controls are mandatory. Mandatory means if the associated input field is either NULL or not referenced in the input format, and there is no default value, the mandatory test fails and Formatter will not output data.

Creating a Literal Output Control

Literal output controls insert a literal (static) value into the output message. For example, if there is a static value separating the header for a message from the body, you would add <BODY>. An output control might look like:

>     Output Control Name: Out<FirstName>Literal
>     Output Control Type drop-down list: Literal
>     Data Type (Data Types) drop-down list: String
>     Tag Before Length checkbox: (Not Checked)
>     Optional checkbox: (Not Checked)

Note: The Output Control type determines which fields require information. Fields containing "Not Applicable" or "NONE" do not require a value.

To define a Literal output control, follow these steps.

1. With Literal selected in the Output Control Type drop-down list, select a data type for the output data from the Data Type drop-down list.

2. If the selected data type is Date and Time, Date, Time, or Custom Date and Time, select the Base Data Type (String or Numeric) the data will be output as.

3. If the selected data type is Custom Date and Time, select a date/time format from the Data Format drop-down list.

4. To perform an operation on the data, select one from the Output Operation drop-down list. See operations for details.

5. If the output data is to have an embedded length, specify the Length data type in the Length Type drop-down list.

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

7. If the output data is to have an associated tag, specify the data type for the tag in the Tag Type drop-down list.

8. If the tag should be output before the embedded length, check the Tag Before Length box.

9. If the output control parse is optional, check the Optional checkbox. Optional means that Formatter should continue with the output message if the field was NULL with no default value or was not referenced in the input layout.

   Note: By default, output controls are mandatory. Mandatory means if the associated input field is either NULL or not referenced in the input format, and there is no default value, the mandatory test fails and Formatter will not output data.

Creating a Conditional Field Output Control

Conditional Field output controls mark a field as output only if a specific field exists. One other field in the output format must be associated with an Existence Check Field output control. For example, you may want to output an account number only if a person's name is in the input message. The output control might look like:

>     Output Control Name: IfPersonNameOutAccountComma
>     Output Control Type drop-down list: Conditional Field
>     Data Type (Data Types) drop-down list: String
>     Tag Before Length checkbox: (Not Checked)
>     Optional checkbox: Checked

Notes: The Output Control type determines which fields require information. Fields containing "Not Applicable" or "NONE" do not require a value.
Another field (in this example, the "PersonName" field) in the output format MUST be associated with an Existence Check Field output control for the Conditional Field output control to work correctly.

To define a Conditional Field output control, follow these steps.

1. With Conditional Field selected in the Output Control Type drop-down list, select a data type for the output data from the Data Type drop-down list.

2. If the selected data type is Date and Time, Date, Time, or Custom Date and Time, select the Base Data Type (String or Numeric) the data will be output as.

3. If the selected data type is Custom Date and Time, select a date/time format from the Data Format drop-down list.

4. To perform an operation on the data, select one from the Output Operation drop-down list. See operations for details.

5. If the output data is to have an embedded length, specify the Length data type in the Length Type drop-down list.

6. If the output data is to have an associated tag, specify the data type for the tag in the Tag Type drop-down list.

7. If the tag should be output before the embedded length, check the Tag Before Length box.

8. If the output control parse is optional, check the Optional checkbox. Optional means that Formatter should continue with the output message if the field was NULL with no default value or was not referenced in the input layout.

   Note: By default, output controls are mandatory. Mandatory means if the associated input field is either NULL or not referenced in the input format, and there is no default value, the mandatory test fails and Formatter will not output data.

Creating an Existence Check Field Output Control

Existence Check output controls are used to define the field on which a Conditional Field output control depends. See Creating a Conditional Field Output Control for more information.

Note: The Output Control type determines which fields require information. Fields containing "Not Applicable" or "NONE" do not require a value.

To define an Existence Check Field output control, follow these steps.

1. Select Existence Check Field as the output control type.

2. If the output control parse is optional, check the Optional checkbox. Optional means that Formatter should continue with the output message if the field was NULL with no default value or was not referenced in the input layout.

   Note: By default, output controls are mandatory. Mandatory means if the associated input field is either NULL or not referenced in the input format, and there is no default value, the mandatory test fails and Formatter will not output data.

Creating a Rules Field Output Control

Rules Field output control enables you to create several different output controls for a single output field by integrating the Rules application (see Defining Rules for more information) with the Formatter application. Formatter can then use the boolean logic capabilities of Rules to express and evaluate the conditions for formatting a field.

Based on the fields defined for the input format, you build different output controls for the same output field. This eliminates the need to create several output formats for a single input format. If no rule evaluates as "true," output data is formatted to the other settings in the Rules Field output control. Otherwise, the data is formatted according to the output control specified by the rule.

Notes: When you define rules for the output control, you cannot delete the fields used in the rules without first deleting the rules that use the fields.
The Output Control type determines which fields require information. Fields containing Not Applicable or NONE do not require a value.

To define a Rules Field output control, follow these steps.

1. Select Rules Field in the Output Control Type drop-down list.

2. Select a data type for the output data from the Data Type drop-down list.

3. If the selected data type is Date and Time, Date, Time, or Custom Date and Time, select the Base Data Type (String or Numeric) the data will be output as.

4. If the selected data type is Custom Date and Time, select a date/time format from the Data Format drop-down list.

5. To perform an operation on the data, select one from the Output Operation drop-down list. See operations for details.

6. If the output data is to have an embedded length, specify the Length data type in the Length Type drop-down list.

7. If the output data is to have an associated tag, specify the data type for the tag in the Tag Type drop-down list.

8. If the tag should be output before the embedded length, check the Tag Before Length box.

9. If the output control parse is optional, check the Optional checkbox. Optional means that Formatter should continue with the output message if the field was NULL with no default value or was not referenced in the input layout.

   Note: By default, output controls are mandatory. Mandatory means if the associated input field is either NULL or not referenced in the input format, and there is no default value, the mandatory test fails and Formatter will not output data.

To add the rules for the field, follow these steps.

1. Choose the Jump to Rules button. The Rules Login dialog box appears.

2. Login and type the rules for the field using the instructions found in Defining Rules.

3. Exit the Rules application. You are returned to the Formatter application.

Creating an Input Field Exists Output Control

Input Field Exists output controls indicate that the output format of which the control is part should be in the output message if it exists in the input message. For example, if a last name input field is in the input message, you may want to output the format that includes first, middle, and last names. You would have four fields in this format:

####

Field | Output Control Type
--- | ---
LastName | Input Field Exists
FirstName | Data Field (Name Search)
MiddleName | Data Field (Name Search)
LastName | Data Field (Name Search)

The output control for LastName might look like:

>     Output Control Name: IfMiddleNameOutData
>     Output Control Type drop-down list: Input Field Exists
>     Data Type (Data Types) drop-down list: String
>     Tag Before Length checkbox: (Not Checked)
>     Optional checkbox: Checked

Note: The Output Control type determines which fields require information. Fields containing "Not Applicable" or "NONE" do not require a value.

To define an Input Field Exists output control, follow these steps.

1. Select Input Field Exists as the output control type:

2. If the output control parse is optional, check the Optional checkbox. Optional means that Formatter should continue with the output message if the field was NULL with no default value or was not referenced in the input layout.

   Note: By default, output controls are mandatory. Mandatory means if the associated input field is either NULL or not referenced in the input format, and there is no default value, the mandatory test fails and Formatter will not output data.

Creating an Input Field Value = Output Control

Input Field Value = output controls indicate that the output format of which the control is part should be output if the value of the field equals a specific value. For example, if an input field contains security information, you may want to limit the data in the output message based on that information. The output control might look like:

>     Output Control Name: IfSecurity=HighThenOut
>     Output Control Type drop-down list: Input Field Value =
>     Input Field Value drop-down list: High
>     Tag Before Length checkbox: (Not Checked)
>     Optional checkbox: Checked

Note: The Output Control type determines which fields require information. Fields containing "Not Applicable" or "NONE" do not require a value.

To define an Input Field Value = output control, follow these steps.

1. Select Input Field Value = as the output control type:

2. Select a Literal from the Field Value drop-down list to compare the field contents to.

3. If the output control parse is optional, check the Optional checkbox. Optional means that Formatter should continue with the output message if the field was NULL with no default value or was not referenced in the input layout.

   Note: By default, output controls are mandatory. Mandatory means if the associated input field is either NULL or not referenced in the input format, and there is no default value, the mandatory test fails and Formatter will not output data.

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. The sections of the Extended Properties tab are labeled in Figure 4-9 and described in Table 4-1.

Figure 4-9 Extended Properties Tab

####

Table 4-1 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.

Notes: 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).

For more information on the output operations supported by Information Integrator, refer to Defining Output Controls.

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.

Building Formats

You use the Formats function in the left pane of the Formatter window to build both input and output formats. The formats can be either flat or compound.

Before you create flat or compound formats, you need to define their component parts. The component parts for each format are described below:

- 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 Flat Input Format

You create flat input formats by adding fields and the desired associated input control, one by one, until you've fully defined the format for the message. You may want to define formats to uniquely identify only the data you're interested in, or you may want to explicitly define a format for each logical piece of the message data.

To create a new flat input format, follow the steps below.

Note: When building Flat Input Formats, have two windows available: one for the new Format and one for Input Controls to be associated with input fields.

1. Right-click Formats in the left pane of the Formatter window. A pop-up menu appears.

2. Select New. A submenu opens.

3. Select Flat; then select Input. A new format component is added to the left-hand pane.

4. 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.

5. Select the Properties tab to define the properties for the flat input format.

6. If the fields for the format can appear in any order in the message, select the Random checkbox. If the fields for the format appear in a specific order in the message, the Random checkbox should be clear.

7. Select a termination type from the Format Termination drop-down list.

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

9. 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.

10. To add field and input control components to the format, select the Fields tab. The Fields sheet appears.

11. Open another Formatter window and display either Fields or Input Controls, depending on what you want to add to the new format.

12. Drag and drop the Fields or Input Controls into the window containing the new flat input format.

13. When you have added all the desired fields and input controls to the format, click Apply to save your changes to the Database.

Creating a Flat Output Format

A flat output format contains a list of fields with their associated output controls. To create a new flat output format, follow the steps below.

Note: When building Flat Output Formats, have two windows available: one for the new Format and one for the Output Controls to be associated with output Fields.

1. Right-click Formats in the left pane of the Formatter window. A pop-up menu appears.

2. Select New. A submenu opens.

3. Select Flat; then select Output. A new format component is added to the left-hand pane.

4. Type a unique format name in the text box and press Enter. The name is alphabetically inserted into the list of formats.

5. Right-click on the output component and select Add Field Components from the pop-up menu.

6. Either select the field(s) that you want to add, or to filter the fields, click the Format Filter arrow to open the drop-down list displaying the available formats. You can filter the list to display only the fields contained in:

   - a specific flat format.

   - all of the flat formats contained in a compound format.

     After you select a filter, the Components window displays only the filtered fields. To display the entire list of available formats and fields, select Not Applicable from the Format Filter drop-down.

7. When you have selected all the fields you want to add to the format, click Accept Selection. The fields are added to the format tree.

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

Creating a Compound Input Format

You create compound input formats by adding flat or other compound formats to the format. To create a new compound input format, follow the steps below.

Note: When building Compound Input Formats, have two windows available: one for the new Compound Format and one for other Formats to be placed within it.

1. Right-click Formats in the left pane of the Formatter window. A pop-up menu appears.

2. Select New. A submenu opens.

3. Select Compound; then select Input. A new format component is added to the left-hand pane.

4. Type a unique format name in the text box and press Enter. The name is alphabetically inserted into the list of formats in the left pane, and the Components and Properties sheets are displayed in the right pane.

5. To specify the order of component formats in the compound, select one of the following:

   - To have component formats appear in the specified order in the input message, select Ordinal.

   - To have the first field of each component be defined as a literal, select Tagged Ordinal.

   - To have only one component format appear in a message, select Alternative. See Alternative Input and Output Formats for more information.

6. To begin adding flat and compound format components, select the Components tab. The Components sheet appears.

7. Open another Formatter window and display the format list.

8. Drag and drop the flat and compound formats into the window containing the new compound input format.

9. When you have added all the desired formats to the new compound format, click Apply to save your changes to the Database.

Creating a Compound Output Format

You create compound output formats by adding flat or other compound formats to the format. To create a new compound output format, follow the steps below.

Note: When building Compound Output Formats, have two windows available: one for the new Compound Format and one for other Formats to be placed within it.

1. Right-click Formats in the left pane of the Formatter window. A pop-up menu appears.

2. Select New. A submenu opens.

3. Select Compound; then select Output. A new format component is added to the left-hand pane.

4. Type a unique format name in the text box and press Enter. The name is alphabetically inserted into the list of formats in the left pane, and the Components and Properties sheets are displayed in the right pane.

5. To specify the order of component formats in the compound, select one of the following:

   - To have component formats appear in the specified order in the input message, select Ordinal.

   - To have only one component format appear in a message, select Alternative. See Alternative Input and Output Formats for more information.

6. To begin adding flat and compound format components, select the Components tab. The Components sheet appears.

7. Open another Formatter window and display the format list.

8. Drag and drop the flat and compound formats into the window containing the new compound input format.

9. When you have added all the desired formats to the new compound format, click Apply to save your changes to the Database.

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.

Access Modes

Each output field has an associated Access Mode. Access Modes define how Formatter accesses fields in the input message to generate fields in the output message. You select output field access modes and associated input field names to tell Formatter how to map fields from the input message to fields in the output message.

Table 4-2 provides a description of each access mode supported in Formatter.

Table 4-2 Access Modes

####

Access Mode | Description
--- | ---
Not Applicable | Do not access any field instance. Use for the output of Literals.
Normal Access | Access the instance in the same repeating component as the current controlling field instance. If there is no controlling field, access the first instance. This behaves just like Access sibling instance.
Access with Increment | A field with this access mode is the controlling field for the repeating component. This accesses the current value and increments it.
Access Using Relative Index | The first field in a repeating component that Formatter encounters with this access mode is the controlling field for the repeating component. Any other field in the repeating component with this access mode behaves as if it is set to "Access sibling instance" or "Normal access" (access the sibling of the controlling field).
Access nth instance of field | Access the nth instance (n = 0 means get the first instance) of the field in the input message.
Controlling field | This field is the controlling field for the repeating component. On each repetition, access the next field instance that is still a child of the current controlling field instance of the parent format. If there is no parent controlling field, the repetitions end with the last field instance from the input message.
Access current instance | Access the same field instance as on the previous access (the first access will get the first instance of the field).
Access next instance | Access the next field instance relative to the previous access.
Access parent instance | Access the instance that is the first ancestor of the current controlling field instance.
Access sibling instance | Access the instance in the same repeating component as the current controlling field instance. If there is no controlling field, access the first instance.

Alternative Input and Output Formats

Alternative formats are compound formats 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.

Note: At least one of the alternatives must apply to a message; otherwise, the entire alternative 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.

Compound formats may contain a mix of mandatory and optional component formats. Additionally, these component formats may contain 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, the next component will be evaluated. We recommend that all component formats in an Alternative Format 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, the parse for the entire alternative input format fails.

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.

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

Alternative Output Format Example

To create an alternative output format, you define a set of alternatives, then define an alternative compound having all of the alternatives as components, sequenced in the order desired.

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.

Importing and Exporting Format Components

The Formatter application enables you to import or export one type of Formatter component at a time. Using Formatter's import and export functions, you can export format data from one database and import it to another.

Note: The export file generated by the Formatter application has a different format than the one generated by the command-line utility, NNFie. The export file generated by NNFie cannot be imported by the Formatter application. See BEA Information Integrator Installation and Administration Guide for details on how to use NNFie.

Exporting Components

You can export Formatter components to a file that can be later imported into the same database or a different installation (of the same version). To ensure that all Formatter component information necessary is available, Table 4-3 lists the export requirements.

Table 4-3 Export Requirements

####

If you export | Also export
--- | ---
an Input Format | Literals, Fields, Input Controls, Flat Input Formats, and Compound Input Formats.
an Output Format | Literals, Fields, Output Operations, Output Operation Collections, Output Controls, Flat Output Formats, and Compound Output Formats.

Note: Files exported using the Formatter application may not be imported using the NNFie tool. The same tool must be used to import components as was used to export the components.

To export Formatter components, follow these steps.

1. Select the component category (Formats, Input Controls, Output Controls, Fields, Literals, or Operations) for the type of component you want to export. Be sure the property sheet for the component category is open in the right pane.

2. Select the Export tab. A list of defined components appears. For example, if you selected Formats, a list of input and output formats appears.

3. Select the components to export:

   - To select individual components, click on each one in the list.

   - To select all components listed, click Select All.

   - To deselect the components you have selected, click Deselect All.

4. Choose the Export button. The Export File dialog box appears.

5. Select the drive, directory, and filename to export the components to and click OK. The file is saved with a .fmt extension. The selected components are exported and the dialog box closes.

Importing Components

Import enables you to load components from a file you previously exported from another database. To import a complete format, you must import each of its components separately, starting from the lowest-level components. Subordinate components must be imported prior to parent components. For example, to import a compound input format, you must have already imported all subordinate flat input formats and their subordinate components.

To import a complete format, import the components in the following order:

1. Literals

2. Output Operations

3. Output Operation Collections

4. Fields

5. Input (Parse) Controls

6. Output Format Controls

7. Flat Input Formats

8. Flat Output Formats

9. Compound Input Formats

10. Compound Output Formats

To import Formatter components, follow these steps.

1. Select the component category (Formats, Input Controls, Output Controls, Fields, or Literals) for the type of component you want to import. Be sure the property sheet is open in the right pane.

2. Select the Import tab. The Import dialog box appears.

3. Enter the complete path to the import file; or, choose the Browse button and select the drive, directory, and filename. A list of the components contained in the file appears.

4. Select the components to import:

   - To select individual components, click on each one in the list.

   - To select all components listed, choose the Select All button.

   - To deselect the components you have selected, choose the Deselect All button.

5. Choose the Import button. The components are imported into the database.

Tip

If a compound component contains other compound components, you must import the compound components it contains first. For example, the compound A12 within the compound B1 must be defined before compound B1 can be imported.

Field Mapping and Transformation

Information Integrator allows incoming data values to be mapped to different field names in the output. By default, input fields are mapped to output fields by matching names. However, when you define an output format, you can name your fields whatever you want, regardless of the field names in the input formats. Then, when you specify where to find the data from the input messages, you can map the input field name to your output field name.

Table 4-4 shows the input values and the output values to which they were mapped.

Table 4-4 Field Mapping Example

####

Input Values | Output Values
--- | ---
Acct X029 | ACCT
Tx Dep | TX
Amt 4000 | AMT
CC 044 | CountryName

To map an input format field to an output format field, follow these steps.

1. Select the format containing the field or fields that you want to map. If you do not select a format now, you can select it after you open the Field Mapping window.

   Note: Note that field mappings are attached to flat output formats.

2. To open the Field Mapping window (see Figure 4-10), choose one of the following:

   - From the Map Fields menu, choose Open Mapped Fields Window.

   - From the toolbar, choose the Map Fields icon.

   - From the main Formatter tree, press the right mouse button to open the pop-up menu and select Map Fields. You must have a format selected to use this method.

     The Field Mapping window opens displaying the selected format and its fields. If a single format was selected, some display data is available. If you did not select a format (or formats) in the Formatter tree, the Mapping Fields Reminder message box appears stating that you must open both an input and an output format. Click OK. The Field Mapping window opens with no data displayed.

     Figure 4-10 Field Mapping Window

3. Click Select Formats to Map. The Select Formats for Mapping window appears displaying input formats in a tree in the left pane and output formats in a tree in the right pane. The format you previously chose is selected. To deselect a format, click it.

   Note: You can double-click to open a format and view its details, but you cannot make changes to the format.

4. Select the input format and output format you want to map. You can only select one input and one output format.

5. Choose one of the following:

   - To map the formats and close the Field Mapping window, click OK.

   - To map the formats and keep the Field Mapping window open to map additional formats, click Apply.

   - To cancel and return to the previously selected formats, click Cancel. Depending on the size of the selected formats, processing may take several minutes. The status bar displays and updates the processing taking place. During this process, output fields are treated as follows:

   - If the output field was unmapped, Formatter searches for a matching field in the input format. If no match is found, it remains unmapped.

   - If the output field was previously mapped, Formatter searches for the mapped input field in the input format. If no match is found, Formatter searches for a matching field for the output field. If no match is then found, the output field becomes unmapped.

6. When processing completes, format information is displayed in the trees. If both an input and output format were selected, Mapped Fields is the default view. The Mapped Output Fields tab displays a list of fields from the output format and the input fields to which they are mapped. To have the two trees scroll and select the mapped fields, select a line in the list.

7. The Unmapped Output Fields tab displays a list of fields from the output format that could not be mapped to the selected input format. If there are unmapped fields, the tab is labeled Unmapped Output Fields. To have the output format tree scroll and select the unmapped field, select the line in the list.

8. To view only the input and output format trees, click Hide Tabs. The bottom pane of the window is hidden. To view this pane again, select Show Tabs.

9. The bottom pane of the window displays the mapped output fields. The information shown includes the input field and the output field it is mapped to, the output format the output field is associated with, and the field sequence (where the field is in the format). To view the list of unmapped output fields, choose the Unmapped Output Fields tab.

10. To view mapped fields for the output format, from the Map Fields menu, choose View Mapped Fields. To the right of each mapped output field is the name of the input field.

11. To view specific format and field information, from the Map Fields menu, choose one of the following:

    - Choose Format Types/Access Modes. The format type of Ordinal, Tagged Ordinal, or Alternative and access mode details are displayed.

    - Choose Optional/Repeating If a field is mandatory, nothing is displayed. If the field is optional or repeating, it is marked accordingly.

    - Choose Input/Output Control Types. The name and type of associated input and output controls for fields are displayed next to the field name.

      The Field Mapping window displays the type of information you requested in the tree view list.

12. Choose one of the following:

    - To close the Field Mapping window and apply changes to the database, click OK.

    - To apply changes to the database and keep the Field Mapping window, click Apply.

Example

This section outlines the procedure required to complete Step 4 in Using Information Integrator. In Step 4, you create the output operation to calculate the employee's weekly pay.

In the steps that follow, we will view formats created by MsgDefAdmin in Step 3 of the sample (see Step 3. Create the Message Format Descriptions in Using Information Integrator). We will also create the output operation to calculate the employee's weekly pay, create a suffix to mark the end of the calculated field, and create an output operation collection containing the calculation and the suffix.

To view the formats, follow these steps.

1. Open the Formatter application.

2. Double-click Formats in the left pane of the Formatter window. The formats contained in your database display.

3. Find II_payroll_msg2_O in the left pane (see Figure 4-11).

   Figure 4-11 II_payroll_msg_O in Formatter Window

   This is the format that was created by running MsgDefAdmin on the file II_payroll_msg2.xml. Refer to the Example section in Using MsgDefAdmin for more information.

4. Expand II_payroll_msg2_O by clicking the plus sign (+) to the left of the format name.

5. Find II_payroll_msg2_rep_O. This is the repeating "pay" field that was created by II_payroll_msg2.xml.

We will now set up the calculation for this field. To set up the calculation, follow these steps.

1. Double-click Output Operations in the left pane of the Formatter window.

2. Right-click Math Expression and choose New from the popup menu.

3. Type CALC_PAY as the name of the new Output Operation in the left pane and press Enter.

4. Type RATE * HOURS in the Mathematical Expression text area and click Apply. This creates the expression to calculate the employee's weekly pay. Figure 4-12 shows the math expression.

5. Select 2 in the Decimal Precision text area.

   Figure 4-12 CALC_PAY Math Expression

We will now create a NULL suffix to mark the end of the calculated field. To create the suffix, follow these steps.

1. Right-click Prefix/Suffix in the left pane and choose New from the popup menu.

2. Type SuffixNull as the name of the new Suffix in the left pane and press Enter.

3. From the Prefix/Suffix drop down list, choose Suffix.

4. From the Value drop down list, choose $LIT$_NUL.

5. Click Apply. This creates the suffix to mark the end of the calculated field. Figure 4-13 shows the suffix.

   Figure 4-13 NULL Suffix

We will now create an output operation collection to hold the math expression and suffix. To create the collection, follow these steps.

1. Right-click Output Operation Collections in the left pane and choose New from the popup menu.

2. Type CalcPay as the name of the new collection in the left pane and press Enter.

3. Right-click CalcPay in the left pane and choose Add Output Operations from the popup menu. The Output Operations for Selection tab displays (see Figure 4-14).

   Figure 4-14 Output Operations for Selection Tab

4. Select the CALC_PAY math expression and the SuffixNull suffix from the list and click Accept Selection. This adds the two output operations to the collection.

   Note: The CALC_PAY math expression should appear first in the output collection. If it does not, click on CALC_PAY and drag it to the top of the list.

We now need to assign the output operation collection to the PAY field so that the calculation will be performed on the field and the suffix will be added to the field. To do this, follow the steps below.

1. Double-click Formats in the left pane of the Formatter window. The formats contained in your database display.

2. Find II_payroll_msg2_rep_O in the left pane and expand it by clicking the plus sign (+) to the left of the format name.

3. Select the PAY field. The properties tab displays (see Figure 4-15).

   Figure 4-15 Pay Field Properties

4. Right-click on the Output Control Name text box and select Open Item from the popup menu. The Output Control Properties tab displays (see Figure 4-16).

   Figure 4-16 Output Control Properties Tab

5. From the Output Operation drop down list, choose the CalcPay collection and click Apply. This assigns the collection to the Pay field.

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