eiConsole v.18R2
Tutorial & Interface
Using Field Record Controls
Overview
This interface and related tutorials demonstrate the use of the File Specification Editor in Route configurations to convert between fixed-width Formats which require conditional Record selection and XML. In this particular exercise, an existing Route (from “Training – Creating a Simple Route”) is modified to transform a fixed-width representation of a “farm” into a well-structure XML format. In this tutorial we’ll cover using “Field Record Controls” in File Specifications to conditionally select Records in a fixed-width format. This tutorial expands on the concepts of “File Specifications Handling Fixed-Width Files,” so users are expected to be familiar with that content.
How to Use This Example
Click the links below for the files you will need for this tutorial, then download the interface to get started. (Once logged into the eiConsole it immediately shows up in your “PIE” inbox for use.)
Sample Data
InterfaceNote: if you are not logged in to the eiConsole, or have arrived at this page via a browser, you will be prompted to login before the interface downloads into your eiConsole “PIE” inbox. Or if you have not downloaded and installed a FREE eiConsole Trial you will have the opportunity to register after you click the Interface Download link. Once you are logged in the interface will automatically download into your “PIE” inbox. First, you’ll see a screen pop up indicating that a new product is ready for download. Select the Download Now button. Once you’ve downloaded the Interface you can drag it into your current Working Directory and begin.
Next, follow the tutorial and walk through it step-by-step. You may check your work against the provided Route (Sample Data).
Creating and Configuring a new Route
Begin by creating and configuring a new Route similar to the one created in “File Specifications Handling Fixed-Width Files.” Select the “Source Transform” stage and add a new Format, this time called “Delimited Farm to XML”:
Select the “Delimited and Fixed-Width File” Transformer and click Edit to open the File Specification Editor:
Select “User-Defined” from the drop-down and configure this File Specification with “\r\n”-delimited Records and Fixed-Width Fields:
Create the following Records and Fields with these lengths:
- Animal
- RecType – 3
- ID – 5
- Type – 10
- Name – 10
- Flavor – 5
- Building
- RecType – 3
- ID – 5
- Type – 10
- Value – 6
- Employee
- RecType – 3
- ID – 5
- Type – 10
- Salary – 8
- Unknown
- Unknown 10
When completed, the structure should look like this:
Load in the “farm.txt” sample file:
There is one key difference between this File Specification and the one covered in the fixed-width tutorial: there are multiple Records. As you can see from the sample, there is no guaranteed order for the Records, nor is there any indication that there’s a particular occurrence limit; each Record can occur any number of times. Another facet is that each Record’s first three characters define the Record type. For example, “ANI” indicates an “Animal,” while “BUI” indicates a “Building.”
This is a fairly typical pattern for delimited and fixed-width formats. Some Field within the Record definition indicates the type of Record with varying levels of complexity. Some formats make use of many, many nested, conditionally-selected Records.
Selecting the Correct Record
In order to select our correct Record based on the first three characters (the “indicator”), we’ll need to make use of a File Specification concept called a “Record Control.” Record Controls are components that select or alter the contents of Records or Fields based on some configuration. The Record Control we’ll be using is called the “Field Record Control.” To make use of it, right-click on the “Base” Node and select “Specify Record Control”:
This will raise a dialog where you can select from a list of defined Record Controls:
As we have no such Record Controls defined, click the “Define new…” button to raise another dialog:
Click “Add Record Control,” then click “Select.” You should now see the Record Control entry in the structure panel:
Select the “Field RecordControl” entry and the bottom configuration panel should change to reflect it:
A Field Record Control has three components:
Control Fields, which are defined Fields (by position or by start / end) used for testing.
Control Cases, which are cases (tests) against Control Fields.
Default Cause, which is the default if no Control Cases evaluate to “true”.
Adding defintions
We’ll start by defining a Control Field. Right-click the Control Fields entry and select “Add.” This will raise a dialog where you can define a Control Field:
The first part is the “Field Name,” which is what we’ll be using to identify the Control Field in later cases. We’ll call ours “RecType”:
Next, we can define the Start and End of this Control Field. Since we’re testing the first three characters for “ANI,” “EMP,” or “BUI,” provide “1” and “3”:
Click “OK,” and then right-click on Control Cases and click “Add” to start defining our tests.
Define similar cases for EMP → Employee and BUI → Building.
Next, we’ll need to define a default Record if no match is found. Right-click on Default Case and select “Define”:
We’ll provide “Unknown” for our Default Record Name, then click “OK.” Our final configuration should look something like this:
Testing the results
Finally, click the “Execute Transform to XML” button to test the results:
Save the File Specification, close the Editor, return to the eiConsole, and test the Route from end to end using the provided sample file. Here’s the resulting “before”:
And here’s the “after”:
You can use Record Controls inside Records as many layers deep as necessary.
This concludes this tutorial.