eiConsole v.24R1
Tutorial & Interface

eiConsole – Advanced Topics

Using Field Record Controls

Note: The Quick Start, Foundation, Topology and Data Mapping & Transformation tutorials should be completed before proceeding with the Data Mapping & Transformation Tutorials.

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-structured XML format. This tutorial will 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.

Before You Begin

Using Field Record Controls
Working Directory

Download the Using-Field-Record-Controls-Working-Directory.zip file with the sample Working Directory and unzip it on your computer to a convenient place. In our case, it’s c:\Users\{USER _NAME}\PilotFish eiConsole Working Directories\Using Field Record Controls where {USER_NAME} is the user’s name.

Open the eiConsole, browse to your Using Field Record Controls directory, and open it. The fully configured File Spec – Using Field Record Controls – Example route is included in the Working Directory. Your Route File Management screen will open, as shown below.

Next, follow the tutorial and walk through it step-by-step. You may check your work against the provided Route (Sample Data).

Create a New Route in the eiConsole

We’ll begin by creating a new Route similar to that used in Creating a Simple Route. We recommend naming it File Spec - Using Field Record Controls to fit with the title of this exercise.

Double-click on the File Spec - Using Field Record Controls

Set up a Directory/File Listener. Enter the string ..\..\in in the polling directory field

The polling directory can be found in:

c:\Users\{USER _NAME}\PilotFish eiConsole Working Directories\Using Field Record Controls\in

Set up a Directory/File Transport. Enter the string ..\..\out in the polling directory field.

The transport directory can be found in:

c:\Users\{USER _NAME}\PilotFish eiConsole Working Directories\Using Field Record Controls\out

The one modification we’ll make is to change the Directory/File Transport’s extension to xml:

Add a Format

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.

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

Right-click on Base and click Add New Record.

Right-click on Add New Record choose Add New Field and name a new filed RecType.

Set the length for the RecType field to 3 chars according to the table above.

Repeat these steps for each Record and Field. When completed, the structure should look like this:

Load in the farm.txt sample file. The file can be found in:

c:\Users\{USER _NAME}\PilotFish eiConsole Working Directories\Using Field Record Controls\data

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:

In this dialog, you can specify a “Record Control Type” via the drop-down and its name. Select the “Field Record Control” and leave the default name:

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 Definitions

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.

Each Control Case has an If Test Field (the name of the Control Field we’re testing), an Equals Value (the value we’re testing against), a Then Use Record (which Record to use if the Test Field matches Value), and an Occurrences Limit (how many times this case can apply). We’ll provide an entry for “ANI” against the Animal Record:

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:

Finally, click the “Execute Transform to XML” button to test the results:

Save the File Specification, close the Editor, return to the eiConsole.

Testing

With that, we’ve now completely configured our Route, as well. Switch to Testing Mode, place the farm.txt sample file into the polling directory, and let the test run all the way through. This file can be found in:

c:\Users\{USER _NAME}\PilotFish eiConsole Working Directories\Using Field Record Controls\data

The polling directory is:

c:\Users\{USER _NAME}\PilotFish eiConsole Working Directories\Using Field Record Controls\in

Click Execute Test.

Choose the Listener stage and click on the View Stage Output.

Here’s the resulting “before”:

Now go to the Source Transform stage and click again on the View Stage Output. 

And here’s the “after”:

You can use Record Controls inside Records as many layers deep as necessary.

This concludes the tutorial.