|
|
|
|
|
|
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
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:
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:
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
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.
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.
Deleting Components
Formatter components can be deleted in the left pane of the Formatter window. To delete a component, follow these steps.
Tips
To delete an input format with a field used in conditional branching, use one of the following methods:
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.
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.
Using Drag and Drop
Use drag and drop to:
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.
These steps are described in the following sections.
Defining Literals
A literal is a string of characters that Formatter processes as:
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.
Figure 4-3 Literal Property Sheet
Note: The literal name must be 32 characters or less. Single quotes, double quotes, and spaces should not be used in names.
Tip
To change the name of a literal 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.
Figure 4-4 Fields Property Sheet
Notes: The Comment field does not retain formatted text when imported or exported.
Using carriage returns in the Comment field is not recommended.
Tip
To change the name of a field:
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:
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.
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.
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:
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 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.
Note: Length Operation names have a 32-character maximum length.
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***
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.
Note: Math Expression names have a 32-character maximum length.
Note: Field names cannot contain dashes.
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.
Note: Prefix/Suffix operation names have a 32-character maximum length.
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.
Note: Substitute operation names have a 32-character maximum length.
Figure 4-5 Literal
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:
Note: Substring operation names have a 32-character maximum length.
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.
Note: Trim operation names have a 32-character maximum length.
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.
Note: The name must be 32 characters or less. Single quotes, double quotes, and spaces should not be used in names.
Figure 4-6 Output Operations
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.
Figure 4-7 Input Control Property Sheet
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 |
|
76201 |
String having an exact length |
Control Type = Data Only |
|
<Name>John Doe, |
String proceeded by a tag with a delimiter |
Control Type = Tag and Data |
|
<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 |
|
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 |
|
8,John Doe |
String that has a length given |
Control Type = Length and Data |
|
3 |
Field that specifies the number of occurrences of another field, 1 digit only |
Control Type = Repetition Count |
|
*Server |
Literal that must be present in message |
Control Type = Literal |
|
$198 |
String that begins with a $ followed by white space. |
Control Type = Regular Expression |
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.
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.
Note: The literal for the Tag Value must have been created previously.
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.
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.
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.
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.
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.
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.
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.
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.
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:
Note: Carets (^) and dollar signs ($) are not supported. Do not use them in REs without preceding them with a backslash character (\).
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.
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.
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:
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.
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.
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.
Figure 4-8 Output Control Property Tab
Note: The output control name must be 32 characters or less. Single quotes, double quotes, and spaces should not be used in names.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
|
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.
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:
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.
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.
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.
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.
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.
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.
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.
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:
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.
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:
To import Formatter components, follow these steps.
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.
Note: Note that field mappings are attached to flat output formats.
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
Note: You can double-click to open a format and view its details, but you cannot make changes to the format.
The Field Mapping window displays the type of information you requested in the tree view list.
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.
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.
We will now set up the calculation for this field. To set up the calculation, follow these steps.
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.
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.
Figure 4-14 Output Operations for Selection Tab
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.
Figure 4-15 Pay Field Properties
Figure 4-16 Output Control Properties Tab
|
|
|
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|