Data Mapping Conversion

# Data Mapping Conversion

The eLink DIO product provides a method for data mapping and conversion for the eLink Platform environment. The eLink DIO product can transform data from one format to another, split a single input into multiple outputs (message explosion), or perform intelligent data dependant routing. Several applications work together to accomplish this task. The following information will outline these tasks.

- Creating Files for Conversion

- Developing Rules for Conversions Between FML Buffers and Other Applications

- Executing a Service Request with Data Mapping

## Creating Files for Conversion

You must create source and destination files prior to the conversion process. For converting non-FML to FML buffers or FML buffers to non-FML, you must have the following files:

- non-FML source file that meets the Mercator conversion standards

For information about the source file requirements, refer to the Mercator Help file.

- FML Field Definition file

  For information about creating an FML Field Definition file, refer to the BEA TUXEDO Programmer's Guide and the BEA TUXEDO Reference Manual on the BEA eLink Platform Online Documentation CD-ROM.

- FML Group Format file

  For information on the format and definition of the FML Group Format file, refer to the "Creating an FML Group Format File" section.

### Creating an FML Group Format File

An FML32 Group Format file (`*.fgf`) is used with an FML32 Field Definition Table to apply structure to FML32 fields received by the eLink DIO in an FML input buffer. Data structures applied to input FML32 buffers can range from simple to complex. A simple structure may be an FML Group Format that supplies the order of individual FML32 fields received by a service request. An example of a complex structure could have nested groups of data items with multiple occurrences of some or all of the groups or data items.

Listing 5-1 is the syntax for the FML Group Format file.

> Listing 5-1 Syntax for FML Group Format File

>     GROUP <groupname> [OCCURS n | s]
>           field-type FML-field-name [OCCURS n | s]
>     END

GROUP
  specifies a collection of data items that should be treated as an individual unit. The GROUP keyword marks the beginning of a group. Groups are terminated by the END keyword. GROUPS can be nested. The outermost group (or root) contains all of the fields or groups used in the FML32 buffer.

Note: The top GROUP (or root) cannot have an OCCURS clause.

<groupname>
  specifies the name for the group. You can use the name of the FML Field Definition file as the `groupname` for the top GROUP.

<field-type> <FML-field-name>
  specifies fields within an FML Group Format file. Fields are identified using the field type and the FML field name. Valid field types are string, long, short, char, double, float, or carray. The FML field name must match the name specified in the FML Field Definition file or an error will occur.

Note: Group names and field names must be unique within an FML Group Format file.

OCCURS n | S

  specifies the number of occurrences of a group or data item within a group.
specifying a number (`n`) denotes the number of times the specific group or data item occurs in an input FML32 buffer.

specifying the keyword `S` indicates that a group or data item has an indefinite number of occurrences. The number of groups or data items processed may vary from one service call to the next. The eLink DIO product determines how many occurrences of a group or data item exist in the input FML32 buffer and process the data accordingly. Only use the keyword S at the top group level under the outermost group.

The OCCURS parameter is optional. The default is 1 occurrence.

#### FML Group Format File Examples

Listing 5-2 is a simple FML Group Format file. This sample file supplies the order in which individual FML Fields are formatted for input to the data mapping process. This FML Group Format file specifies the structure to build using the FML32 data items in the input buffer with names that match the FML Group Format field names.

> Listing 5-2 Simple FML Group Format File Example

>     GROUP NAME
>           string FIRST_NAME
>           char MIDDLE_INIT
>           string LAST_NAME
>           int AGE
>     END

Listing 5-3 is a sample FML Group Format file with nested groups and occurrences. The GAA_ARRAY is the outermost group and will not support an OCCURS S clause. The valid top level groups in the following example are GAA_UPPER and GAA_SECOND. The OCCURS S definition in GAA_UPPER indicates that this top level group has an indefinite number of occurrences. GAA_UPPER contains another group, GAA_LOWER. Groups nested within groups other than the outermost group must have a fixed number of occurrences. GAA_LOWER occurs five times within each occurrence of GAA_UPPER.

> Listing 5-3 Sample FML Group Format File

>     GROUP GAA_ARRAY OCCURS
>           GROUP GAA_UPPER OCCURS S
>                 short EMA_S_SHORT
>                 GROUP GAA_LOWER OCCURS 5
>                       string  EMA_S_STR OCCURS 2
>                       long EMA_L_LONG OCCURS 4
>                 END
>                 string EMA_S_STR2
>           END
>           GROUP GAA_SECOND OCCURS 3
>                 short EMA_S_SHORT
>                 short EMA_S_CHAR
>           END
>     END

### Using the mti2fgf Utility

The BEA eLink DIO Design Client installs the mti2fgf utility. This utility takes a file containing Meta-Type Information and converts it back to FML Group Format language. This utility is helpful if you have the Meta-Type Information file, but no longer have the source FML Group Format file. After using the utility, the resulting `*.fgf` file is sent to stdout and can be used in the eLink DIO FML Importer.

To use the `mti2fgf` utility, issue the following command.

Listing 5-4 mti2fgf Utility

>     $ mti2fgf filename.mti

## Developing Rules for Conversions Between FML Buffers and Other Applications

After you transfer the necessary files to the development environment, you can begin the process for building a Mercator map file. The map file will contain the specific mapping rules used to transform input data to desired output data formats. The following tasks must be done in the development environment prior to the execution of a service request.

1. Set System Properties for the Mercator Open Edition Client

2. Create an FML Type Tree File Using the eLink DIO FML Importer

3. Create a Mercator Map File

### Set System Properties for the Mercator Open Edition Client

Before developing your data maps, you must put the Mercator Open Edition Client in your system path. Select Program>Settings>Control Panel>System Properties to access properties page. Select the Environment tab and enter the path for Mercator Open Edition Client under User Variables. The default installation directory is `C:\mercator`.

### Create an FML Type Tree File Using the eLink DIO FML Importer

To create an FML type tree file, complete the following tasks.

1. Obtain the desired FML Field Definition file from the execution environment.

2. Create the necessary FML Group file (`.fgf`). For information on the FML Group Format file, refer to the "Creating an FML Group Format File" section. For information on creating FML Field Definitions file, refer to the BEA TUXEDO Programmer's Guide and the BEA TUXEDO Reference Manual on the eLink Platform Online Documentation CDROM.

3. Access the eLink DIO FML Importer dialog box by invoking `elinkimprt.exe`. The FML Group Format File Selection dialog box displays.

   Browse to specify the following files on the FML Group Format File Selection.

   FML Group Format File (`.fgf`) specifies the FML Group Format file to use in the data mapping conversion. This file is used in conjunction with an FML Field Definition file for the conversion.

   Note: After selecting an FML Group Format file, the eLink DIO FML Importer will default the Type Tree and MTI file names to the same file name as the FML Group Format. The extensions will be unique, `*.mtt` and `*.mti` respectively.

   FML Field Definition File (`.fml`) specifies the FML buffer to use in the data mapping conversion.

   Type Tree File Name is the directory location and name of the FML type tree file to use for creating the Mercator Map file. If you reference only a file name and no directory path, the file will be created in the current directory.

   MTI File Name is the directory path and file name for the metadata associated with the FML type tree file. If you reference only a file name and no directory path, the file will be created in the current directory.

   Note: Check the Include /Q header information box when using eLink Data Integration Option with the TUXEDO /Q feature. Do not check the Include /Q header information box when using the BEA eLink Data Integration Option component with eLink for Mainframe.

   Click OK to validate the `.fgf` and `.fml` files and create the `.mtt` and `.mti` files.

   If the following screen displays, click No to overwrite the file. No is the default.

   Note: Do not click Yes. It will merge the existing tree with the new tree.

4. If the FML type tree processes without error, the following pop up will display. Click OK to continue with the process.

5. The Mercator Type Tree Maker displays the newly created FML type tree file. Click Close to save the type tree file.

#### FML Type Tree Fields

The FML type tree specifies the type definitions of the input and output files. There are four branches for the type tree file; Control, Field, Message, and SET. The SET line is not used.

- Control contains general information about the field, which is defined in the Header file.

- Field contains individual field definitions

- Message

  - Input contains one or more sets

  - Output contains header information plus one or more sets

- SETS contain multiple occurrences of zero or more specific FML fields. There may be multiple sets.

### Create a non-FML Type Tree File Using Importers

From your source file, create a type tree file (`*.mtt`).

1. Using the Mercator product, load your source file such as a COBOL copybook into the appropriate Importer and create a type tree file. For specific information about how to create a type tree using the Importer, refer to the Mercator Help file.

2. Using a text editor or the Mercator Type Editor, open the type tree file (*.mtt). If the type tree file does not contain the Control information (from the FML type tree file), add it into the header of the type tree file (*.mtt). This can be done by dragging and dropping the Control information from the FML type tree file into the other type tree file. Listing 5-5 is a sample of the header information that must be added to the COBOL type tree file before creating the Mercator map file (`.mmc`).

   Note: If you are using the TUXEDO /Q feature, refer to the "Control Information for TUXEDO /Q" section.

   > Listing 5-5 Sample COBOL Type Tree Header Information

   >     CONTROL
   >         FIELD
   >             FieldName
   >             Format
   >             Service

3. Within the non-FML type tree file, create a new category for the input and output cards. For example, create a new category named TuxMessage.

4. Select the new category that was created, for example TuxMessage. Under this category, create two new groups. One group for input messages and another group for output messages.

5. After creating the two new groups, double click on the input message group to open the component screen. Drag and drop the appropriate group under the record category into the component screen of the input message.

6. Double click on the output message group to open the component screen. Drag and drop the Header group under the Control category into the component screen of the output message. Then drag and drop the appropriate group under the Record category into the component screen of the output message.

7. Analyze the tree by selecting `Analyze` from the Tree menu. Select the Results button to view the analysis results. If there are no errors, save the file. If there are errors, refer to the Mercator Type Editor Reference Guide for information on resolving these errors. Be sure to save the file when finished.

#### Control Information for TUXEDO /Q

Control information is used to return /Q message attributes to specify data formats of /Q message attributes in output cards. Specifically,

- In the first output card of maps used with the generic translation server, specify the data format and optional service name for the purposes of forwarding. The header information must be present in maps called by the generic translation server because it provides the only means of specifying the format of the output data.

- In output cards calling TUXEDO services and /Q, use the control information to specify the data format, service name and /Q message attributes.

- In input cards calling /Q, the control information is included in the data if the -HDR option is specified. This data contains attributes of the received message.

The control information consists of the following elements.

> Table 5-1 Control Information

| Usage |  |
Element | Service / /Q | When Present | Description
Format | Both | Always | Specifies the desired format of the output buffer. Possible values are "CARRAY", "STRING", "FML", and "FMLV" (FML values). Abbreviations of these may also be used. These are respectively: "C", "S", "F", and "FV".
View | Both | Always | Specifies the name of the view if the Format type is VIEW. Note: This is not a valid format.
FieldName | Both | Always | Specifies the name of the FML field to be specified for the output data. This is used if the Format type is FMLV (FML values).
Priority | /Q | /Q only | On output, specifies the priority of the message to be sent. This overrides the -P option.
CorrID | /Q | /Q only | On output, specifies the correlation ID of the message to be sent. This overrides the -CID option.
ReplyQ | /Q | /Q only | On output, specifies the reply queue of the message to be sent. This overrides the -RQ option.
FailureQ | /Q | /Q only | On output, specifies the failure queue of the message to be sent. This overrides the -FQ option.
URCode | /Q | /Q only | On output, specifies the user return code of the message to be sent. This overrides the -UR option.

### Create a Mercator Map File

An input card and an output card must be created prior to compiling a Mercator map file (`*.mmc`). Input cards contain a type tree and an adapter. Use both type tree files for the buffer types (for example FML and COBOL copybook) that are being mapped. For information on how to build a Mercator map file, refer to the Mercator Map Editor Reference Guide and the Mercator Functions & Expressions Reference Guide.

1. Access the Mercator Map Editor window.

2. Set the map file name by selecting the Rename option from the Map menu. Enter a map name that is 8 characters or less, for example `FML2COB`.

3. After naming the map file, save the file by selecting File>Save As. Browse to select the directory and file name, for example `FML2COB`.

4. Activate the From side of the Mercator Map Editor window. To add an input card, select Add from the Card menu to display the Add Input Card dialog box.

   Enter a unique name for the new input card in the Card Name field.

   In the Type section, click File to browse and select the input card type tree file (`*.mtt`) for the File field.

   In the Name field of the Type section, click the Browse button to display the contents of the type tree file (`.mtt`). From the display, select the input record.

   Leave the default value, File, in the Data Source field.

   In the File section, you can use the Name field as a comment box. Enter a description of the input card as your comment. Text must be entered in this field.

   Note: The value in this field is ignored and has no effect on the data mapping process; therefore, you can use this field as a comment field.

   Click OK to create the input card.

5. Activate the To side of the Mercator Map Editor window. To add an output card, select Add from the Card menu to display the Add Output Card dialog box.

   Enter a unique name for the new output card in the Card Name field.

   In the Type section, click File to browse and select the output card type tree file (`*.mtt`) for the File field.

   In the Name field of the Type section, click the Browse button to display the contents of the type tree file (`.mtt`). From the display, select the output record.

   Leave the default value, File, in the Data Source field.

   In the File section, you can use the Name field as a comment box. Enter a description of the output card as your comment. Text must be entered in this field.

   Note: The value in this field is ignored and has no effect on the data mapping process; therefore, you can use this field as a comment field.

   Click OK to create the output card.

6. On the To side, formulate your mapping rules. You must define the Format field in the Header Control Group with a mapping rule. If the output record is a COBOL copybook, enter `="C"` as the rule in the Format field. If the output record is an FML buffer, enter `="FML"` as the rule in the Format field.

   Map the remaining fields. For information on mapping rules and defining functional maps, refer to the Mercator Functions & Expressions Reference Guide.

7. Compile your map file (`*.mmc`) by selecting the Build option from the Map menu. If errors occur during the build process, access the building results for an explanation of the error. Resolve the errors in the mappings and execute the build process again until no errors occur.

8. Save the compiled map file by selecting File>Save.

9. If your execution platform is HP-UX, AIX, or SUN Solaris, you must port the maps to these platforms. To port the map, select Map>Port and then select the platform from a list. When the port is complete, the files will be renamed with a platform-specific extension, such as `*.hp`.

## Executing a Service Request with Data Mapping

To set up the execution environment, complete the following tasks:

1. Transfer Files to the Execution Environment

2. Set Environment Variables

3. Start BEA TUXEDO and Other Remote Applications

4. Write a Client Program to Call eLink DIO Services

5. Issue a Service Request for Data Mapping

   The client program requests the mainframe service advertised by the eLink for Mainframe gateway.

### Transfer Files to the Execution Environment

After completing the development process, the following files must exist and be transferred to the execution environment.

- FML destination file (`*.fml` - ASCII file)

Transfer this file to the execution environment. Define the FLDTBLDIR32 to point to the file's directory structure. Also, define the FML Field Definition file with other FML32 tables in the FIELDTBL32 environment variable.

- Meta-Type Information file (`filename.mti` - ASCII files)

  Transfer the Meta-Type Information file to the directory listed as MTI_DIR in the SERVER section of the eLink DIO configuration file. If the eLink DIO configuration does not specify an MTI_DIR, then load these files to APPDIR.

- Mercator map files (`filename.mmc` - Binary file)

  Note: If you are executing on HP-UX, AIX, or SUN Solaris, the map files will have a platform-specific extension after the porting function. For example, after porting the `filename.mmc` file to Sun Solaris, the file is named `filename.sun`.

  Transfer the Mercator map files to the directory listed as MAP_DIR in the SERVER section of the eLink DIO configuration file. If the eLink DIO configuration does not specify a MAP_DIR, then load these files to APPDIR.

- Client programs that create input buffers for eLink DIO and call eLink DIO services.

### Set Environment Variables

Be sure to set the following environment variables.

- TUXDIR identifies the location of the eLink Platform installation.

- APPDIR identifies the location of user-developed eLink Platform application files.

- FLDTBLDIR identifies directories that contain FML Definition Tables.

- FLDTBLDIR32 identifies directories that contain FML Definition Tables.

- FIELDTBL identifies individual FML Definition Tables used by eLink Platform and eLink DIO.

- FIELDTBL32 identifies individual FML Definition Tables used by eLink Platform and eLink DIO.

The following environment variables are platform-specific. Be sure to set the appropriate one for your execution environment. These parameters identify to the system the location of shared libraries needed to execute eLink Platform and eLink DIO.

- LD_LIBRARY_PATH (for SUN Solaris)

- SHLIB_PATH (for HP-UX)

- LIBPATH (for AIX)

- PATH (for Windows NT)

### Start BEA TUXEDO and Other Remote Applications

After transferring the necessary files to the execution environment, be sure that the BEA TUXEDO and other products such as BEA eLink for Mainframe are running. For information on how to start these products, refer to the related BEA TUXEDO documentation and the BEA eLink for Mainframe online documentation CD.

### Write a Client Program to Call eLink DIO Services

The client program should be a standard TUXEDO program. This program should create and populate an FML32, STRING, or CARRAY buffer. The client calls a service advertised by the eLink DIO Server using this buffer as input. The eLink DIO Server performs data mapping and returns any required output to the client program.

### Issue a Service Request for Data Mapping

Execute client programs previously created to perform service calls to services supported by the eLink DIO Server.

After starting these products, you can issue a service request for data mapping. For information on setting up TUXEDO service requests, refer to the BEA TUXEDO documentation.

Note: Leave logging on during execution of your map files to assist in diagnostics if errors occur. Logging will produce a large amount of output. The log file (.log) can be accessed directly in the directory where the compiled map file (*.mmc) is located.

[Table of Contents] [Prev] [Next]