|  | BEA eLink Data Integration Option 1.2 Information Center
HOME | SEARCH | CONTACT | PDF FILES | WHAT'S NEW
| TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC

Data Mapping Conversion

# Data Mapping Conversion

Data mapping allows data in different formats to be passed between a UNIX or Windows NT environment and a mainframe environment. Several applications work together to accomplish this task. The following information will outline these tasks.

- Preparing for Data Mapping Conversion

- Developing Rules for Conversions Between FML Buffers and Other Applications

- Required Files for Conversion Process

- Executing a Service Request with Data Mapping

## Preparing for Data Mapping Conversion

Before starting the development of a map file that will define the rules for data conversion, the development environment must be set up. Preparing the development environment includes the following steps.

- Creating Files for Conversion

- Transferring Files to Development Environment

### Creating Files for Conversion

You must create source and destination files prior to the conversion process.

- For converting COBOL copybooks to FML buffers or FML buffers to COBOL copybooks, you must have the following files:

- COBOL copybook that meets the Mercator conversion standards

For information about the copybook 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.

- FML Group file

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

- For converting SAP R/3 IDOCs to FML buffers or FML buffers to SAP R/3 IDOCs, you must have the following files:

- SAP IDOC file that meets the Mercator conversion standards

For information about the IDOC 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.

#### Creating an FML Group Format File

The FML Group Format file (`*.fgf`) allows you to group information on top of the FML Field Definition file.

Note: The FML Group Format file is not used when you have specified the `-NOMTI` option in the CLOPT parameter.

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

> Listing 4-1 Syntax for FML Group Format File

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

GROUP
  represents all of the fields or groups which will be used in the FML buffer. FML Groups are started using the GROUP keyword and ended using the END keyword. GROUPS can be nested.

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

OCCURS n

  tells FML how many occurrences exist for this group or field. The OCCURS clause is optional. A field or group without an OCCURS clause defaults to a single occurrence.

Listing 4-2 is a sample FML Group Format file with nested groups and occurrences.

> Listing 4-2 Sample FML Group Format File

>     GROUP fml_bufname
>           GROUP payroll  OCCURS 10
>                 GROUP name OCCURS 3
>                       string  FML_FNAME
>                       string  FML_LNAME
>                       string  FML_MIDDLE_INIT
>                 END
>                 long    HOURS WORKED OCCURS 10
>           END
>     END

#### Using the mti2fgf Utility

The BEA eLink Integrator component installs a utility that uses the Meta-Type Information file and transposes it to the original FML Group file format. In other words, you can take `sample.mti` and, using this utility, create `sample.fgf`. 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 Integrator FML and View Importer.

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

> Listing 4-3 mti2fgf Utility

>     $ mti2fgf filename.mti

### Transferring Files to Development Environment

Using a file transfer tool, such as FTP, transfer the following files to the Windows NT development environment.

Note: Be sure to specify ASCII mode.

- FML files (`.fml`) from an existing TUXEDO configuration

- COBOL copybooks from the mainframe

## 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 for the data being passed between a UNIX or Windows NT environment and a mainframe. 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 FML and View 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 FML and View Importer

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

1. Create the necessary FML Group file (`.fgf`) and FML Field Definition file (`.fml`). 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.

2. Access the eLink Integrator FML and View Importer dialog box by invoking `elinkimprt.exe`.

3. Select the type of input file by clicking one of the radio buttons under FML.

   1. If you select the FML Group Format radio box and click OK, 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.

   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 Mercator Integrator for DIO 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.

   2. If you click the Field Definition File radio button under the FML section and click OK, the Type Tree Filename screen displays.

      In the Type Tree Filename, browse to the directory where the output file resides.

      In the Root name of the Type Tree field, enter the base value of the type tree.

      Select the Include /Q header information check box, if you intend to use TUXEDO queues.

      In the display box, select the FML fields in the type 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 4-4 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 4-4 Sample COBOL Type Tree Header Information

   >     CONTROL
   >         FIELD
   >             FieldName
   >             Format
   >             Service
   >             View

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 4-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", "FMLV" (FML values) and "VIEW". Abbreviations of these may also be used. These are respectively: "C", "S", "F", "FV" and "V".
View | Both | Always | Specifies the name of the view if the Format type is VIEW
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`.

## Required Files for Conversion Process

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

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

- Copy of type tree Meta-Type Information (`.mti`) file saved as the Mercator map name (`FML2COB.mti` and `COB2FML.mti` - ASCII files)

  To obtain this file, copy the FML Meta-Type Information (`.mti`) file and rename it using the file name of both map files. For example, the FML type tree file is `sample.mti` and the Mercator map file is `FML2COB.mmc`. Copy `sample.mti` and rename it `FML2COB.mti`. The other map file is `COB2FML.mmc`. Then copy the `sample.mti` file and rename it to the `COB2FML.mti`.

  Note: This step must be done for all maps using this FML type tree.

  Note: No`.mti` file will exist if you are using the `-NOMTI` option in the CLOPT parameter when defining the server in the UBBCONFIG file.

- Type tree files (`fml.mtt` - Binary file)

- Mercator map files (`FML2COB.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 `FML2COB.mmc` file to Sun Solaris, the file is named `FML2COB.sun`.

- Client programs that create FML (ASCII file)

## Executing a Service Request with Data Mapping

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

1. Transfer Files to APPDIR in the Execution Environment

2. Set Environment Variables

3. Start BEA TUXEDO and Other Remote Applications

4. Write a Client Program to Create FML Buffers

5. Issue a Service Request for Data Mapping

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

   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.

### Transfer Files to APPDIR in the Execution Environment

Transfer the necessary files from the Windows NT development environment to the TUXEDO APPDIR directory in the execution environment. For information on required files for the execution environment, refer to the "Required Files for Conversion Process" section.

Note: If you ported the map files for HP-UX, AIX, or SUN Solaris, after you transfer the binary map files to the execution environment, rename the file so that the extension is `.mmc`. For example, rename `FML2COB.sun` to `FML2COB.mmc`.

### Set Environment Variables

Be sure to set the following environment variables.

- TUXDIR

- APPDIR

- FLDTBLDIR

- FLDTBLDIR32

- FIELDTBL

- FIELDTBL32

The following environment variables are platform-specific. Be sure to set the appropriate one for you execution environment.

- 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 Create FML Buffers

The client program should be a standard TUXEDO program that uses `FML32`. All data items and occurrences specified in the FML Group Format file must be added to the FML buffer or an error will occur. If the FML Group Format file specifies an array of 10, then 10 occurrences must be added using the `Fadd32` function or another appropriate function.

### Issue a Service Request for Data Mapping

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. The service name to call is the mainframe service being advertised.

TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC