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

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

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

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.

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.

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,

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.

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.

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

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