Importing Meta Data

 

WebLogic Integration provides three utilities that allow you to import COBOL copybooks, convert C structure definitions, and convert FML Field table Classes into MFL files. The following topics provide information on how to perform these types of imports.

• Importing a COBOL Copybook

• Importing C Structures

• Importing an FML Field Table Class

 

---

Importing a COBOL Copybook

WebLogic Integration includes a feature that allows you to import a COBOL copybook into Format Builder creating a message definition to translate the COBOL data. When importing a copybook, comments are used to document the imported copybook and the Groups and Fields it contains.

To import a COBOL copybook:

1. Choose Tools—>Import—>COBOL Copybook Importer. The COBOL Copybook Importer dialog box displays.

   Figure 4-1 COBOL Copybook Importer

   
    

2. Enter data in the fields as described in the following table:

   Table 4-1 COBOL Copybook Importer Field Descriptions

   Field	Description
   File Name	Type the path and name of the file you want to import.
   Browse	Click to navigate to the location of the file you want to import.
   Byte Order
   Big Endian	Select this option to set the byte order to Big Endian. Note: This option is used for IBM 370, Motorola, and most RISC designs (IBM mainframes and most Unix platforms).
   Little Endian	Select this option to set the byte order to Little Endian. Note: This option is used for Intel, VAX, and Unisys processors (Windows, VMS, Digital, Unix, and Unisys).
   Character Set
   EBCDIC	Select this option to set the character set to EBCDIC. Note: These values are attributes of the originating host machine.
   ASCII	Select this option to set the character set to ASCII. Note: These values are attributes of the originating host machine.
   Other	The character encoding of the field data is selected using a list of code pages.
   Action Buttons
   OK	Imports the COBOL Copybook using the settings you defined.
   Cancel	Closes the dialog box and returns to Format Builder without importing.
   About	Displays information about the COBOL Copybook importer including version and supported copybook features.

   
    

Once you have imported a copybook, you may work with it as you would any message format definition. If an error or unsupported data type is encountered in the copybook, a message is displayed informing you of the error. You can choose to display the error or save the error to a log file for future reference.

The following table provides a listing and description of the sample files installed for the COBOL Copybook Importer. All directory names are relative to the WebLogic Integration installation directories in the samples\di\ subdirectory.

Table 4-2 COBOL Copybook Sample Files

Directory	File	Description
COBOL\	emprec5.cpy	Sample Copybook file.
COBOL\	emprec5.data	Test data corresponding to emprec5.cpy.

 

 

---

Importing C Structures

WebLogic Integration includes a C Struct importer utility that converts a C struct definition into an MFL Message Definition by generating the following two types of output data:

• MFL document

• C Code

Both the MFL document and C code output methods require a .c or .h input file to be specified, parsed, and the desired structure selected before choosing whether to generate MFL (default) or C code.

In addition to the requirement that all input to the parser consist of valid C code, all outside references, such as #include(s), #define(s), and typedef(s) must be resolved prior to use. This may require hand editing or use of the compiler's preprocessor.

There are platform considerations that affect the description of data for C code. For example, the length of a long on a platform will affect the binary data that conforms to a particular structure definition.

There are two methods for dealing with these platform dependencies depending on whether or not MFL is generated directly into Format Builder. If you want to generate MFL and have that MFL displayed immediately in Format Builder, you must supply the platform dependent parameters in a configuration file. Alternately, by choosing to generate C code source, you may compile the C code on the desired machine. The compiler on that machine accounts for the necessary platform dependent information. This will produce an executable file that when run will produce an MFL document and binary data that conforms to that MFL in separate files. The MFL document can be opened in Format Builder and the binary data file can be opened in Format Tester.

Generating MFL directly into Format Builder requires platform configuration parameters found in an existing configuration file or a newly generated configuration file created with the hardware profile editor. The hardware profile editor allows you to specify an existing profile that can be loaded, updated, and saved.

The source code for a utility that generates hardware profiles according to your needs is provided in the samples\di\cgf subdirectory.

C Struct Importer Sample Files

The following table provides a listing and description of the sample files installed for the C Struct Importer. All directory names are relative to the WebLogic Integration installation directory in the samples\di\ subdirectory.

Table 4-3 C Struct Importer Sample Files

Directory	File	Description
C	emprec5.h	A C version of the emprec5.cpy sample Copybook file, with some typedefs.
C	emprec5n.h	A variant of the emprec5.h file using a nested struct definition, but no typedefs.
C	emprec5s.h	A simple version of the emprec5.h file.
C	ntfsez.h	A small sample extracted from the ntfs.h file. Designed to test recursive typedefs.
Cfg	cprofile.c	The source code for the cprofile.c utility. This utility is designed to generate profiles on various platforms.
The following .cfg files were all generated by the cprofile program on various platforms. Each .cfg file contains the DESCRIPTION.
Cfg	dec8cc.cfg	DEC Alpha 1091, Digital Unix 4.0e, cc compiler.
Cfg	hp5cc.cfg	HP-UX B.11.00, cc compiler.
Cfg	nt4bcc5.cfg	Windows NT 4.0, Borland 5.x compiler, default switches.
Cfg	nt4vc6.cfg	Windows NT 4.0, Visual C++ 6.x compiler, default switches.
Cfg	sun7cc.cfg	SunOS 5.8, cc compiler.
Cfg	w95bcc5.cfg	Windows 95, Borland 5.x compiler, default alignment.
Cfg	w95vc5.cfg	Windows 95, Visual C++ 5.x compiler, default alignment.

 

Starting the C Struct Importer

To start the C Struct Importer:

1. Start Format Builder by choosing Start—>Programs—>BEA WebLogic E-Business Platform—>WebLogic Integration 2.1—>Format Builder. The Format Builder main window displays.

2. Choose Tools—>Import—>C Struct Importer. The C Struct Importer dialog box displays.

   Figure 4-2 C Struct Importer Dialog Box

   
    

The C Struct Importer dialog box opens with MFL specified as the default output and contains the following fields.

Table 4-4 C Struct Importer Field Descriptions

Field	Description
Input
Input File	Enter the path and name of the file you want to import.
Browse	Click Browse to navigate to the directory containing the file you want to use.
Structure	This list box is populated with the list of structures found in the input file after it has been successfully parsed.
Parse	Click Parse to parse the input file. If successful, the Structure list box is populated with the list of structures found in the input file.
Output
MFL	If you select this option button, you can generates MFL from a structure definition and a hardware configuration file. You will see the Hardware Profile group box.
C Code	If you select this option button, you can generate C source code to compile on the target machine and execute to produce MFL. You will see the C Code File Names group box.
Hardware Profile
Name	Specify an existing profile either by entering the file name or using the Browse button. The prebuilt hardware profiles may be found in the samples\di\cfg directory.
Browse	Click Browse to navigate to the directory containing the file you want to use.
Save	Saves the current hardware profile.
Save As	Saves the current hardware profile under another name.
Edit	Click Edit to edit the current hardware profile listed in the Hardware Profile Name field.
New	Click New to create a new hardware profile.

 

Figure 4-3 C Struct Importer Dialog Box

 

Table 4-5 C Struct Importer Dialog Box Fields

Field	Description
C Code File Names
MFL Gen	Specifies the C source code file name that must be compiled on the target machine to generate MFL.
Browse	Click Browse to navigate to the directory where you want the file to reside.
Data Gen	Specifies the C source code file name that must be compiled on the target machine for generating test data.
Browse	Click Browse to navigate to the directory where you want the file to reside.
Action Buttons
OK	Click OK to save your hardware profile changes.
Cancel	Click Cancel to dismiss your hardware profile changes.
About	Click About to view C Struct Importer version and date information.

 

Understanding Hardware Profiles

The hardware profiles used by the C Struct Importer contain data size and alignment information for specific hardware and compiler combinations and are used to generate MFL for C structures. They are stored in configuration files that can be created, loaded, updated, and saved.

The cprofile.c source file located in the samples\di\cfg directory is used to generate these profiles for any platform. This code is designed to be compiled and executed on the target platform with the complier normally used and should compile and execute on any platform with an ANSI standard C compiler in order to generate a profile configuration file that can be imported into the C Struct Importer.

Building the Hardware Profile Utility

To produce acceptable parser input, execute the following commands for each of the platforms listed.

• On Windows NT, use the VC++ preprocessor:

  cl /P cprofile.c (output in cprofile.i)- VC++ Compiler

  gcc -P -E cprofile.c>cprofile.i - GNU Compiler

• On Unix:

  cc -P cprofile.c (output in cprofile.i)

Running the Hardware Profile Utility

At a command prompt, enter the following text to execute the cprofile program and specify a hardware profile name:

cprofile configfilename [DESCRIPTION]

The optional description is placed in the configuration file as the DESCRIPTION value. If the description contains embedded blanks, enclose it in quotes.

Generating MFL

Perform the following steps to generate MFL.

1. Enter a file name in the Input File field, or click Browse to select a file.

2. Click Parse to parse the file.

   Upon completion, the Structure list box is populated with the list of structures found in the input file.

   Note: If your file does not parse correctly, it is recommended that you proceed in one of two ways:

   • Run your .h or .c source code through the compilers preprocessor and run that output through the parser.

   • Comment out the character creating the parse failure and attempt to parse again. Please note that the parser fails at the first failure it encounters.

3. Select the desired structure from the Structure drop-down list box.

   At this point, you must provide some profile configuration data to generate the MFL directly. You can do this by creating a new hardware profile, or specifying an existing profile.

4. Specify an existing profile or create a new one by performing one of the following procedures.

   • Specify an existing profile either by entering the file name in the Hardware Profile Name field, or click Browse to select a file. Click Edit to open the hardware profile editor if you need to view or edit the profile parameters.

     Hardware profiles for common configurations are prebuilt and may be found in the samples\c\cfg directory.

   • Click New to create a new hardware profile. This opens the Hardware Profile editor loaded with the default parameters. Specify a Profile Name, a description, and modify the primitive data types and byte order to suit you needs.

     Figure 4-4 C Struct Importer Hardware Profile Dialog Box

     
      

5. Click OK to save your hardware profile changes and return to the C Struct Importer dialog box.

6. Click OK to generate your MFL. If the generation is successful, you are returned to Format Builder with an MFL object listed in the navigation tree. The MFL object reflects the same name as the input file used in the parse operation.

   If errors are detected during the generation process, the MFL Generation Errors dialog box displays providing you the opportunity to view or file the error log.

   Figure 4-5 MFL Generation Errors Dialog Box

   
    

7. Click Display Error Log to view any errors encountered, click Save Error Log to save the error log to the location of your choice, or click Cancel to dismiss the MFL Generation Errors dialog box.

Once you have determined what errors were generated, you can return to the C Struct Importer and repeat the prior steps.

Generating C Code

Perform the following steps to generate C code.

1. Enter a file name in the Input File field, or click Browse to select a file.

2. Click Parse to parse the file.

   Upon completion, the Structure list box is populated with the list of structures found in the input file.

   Note: If your file does not parse correctly, it is recommended that you proceed in one of two ways:

   • Run your .h or .c source code through the compilers preprocessor and run that output through the parser.

   • Comment out the character creating the parse failure and attempt to parse again. Please note that the parser fails at the first failure it encounters.

3. Select the desired structure from the Structure drop-down list box.

4. Select the C Code option button.

5. Enter a file name in either the MFL Gen or Data Gen fields, or click Browse to select a file.

6. Click OK. You will be warned about overwriting existing files and notified about the success or failure of the code generation.

7. Copy the generated source code to the target platform and compile and execute it.

   Note: You must copy the input file containing the struct declarations as well. Both programs, when compiled, take an argument of the output file name.

8. Copy the generated MFL or data back to the platform running Format Builder.

 

---

Importing an FML Field Table Class

The FML Field Table Class Importer facilitates the integration of WebLogic Tuxedo Connector and business process management (BPM). Tuxedo application buffers are translated to/from XML by the FML to XML Translator that is a feature of WebLogic Tuxedo Connector.

The integration of Tuxedo with BPM requires the creation of the XML that is passed between WebLogic Tuxedo Connector Translator and the process engine. To this end, you can use the FML Field Table Class Importer and the XML generation feature of Format Tester to facilitate the creation of the necessary XML.

FML Field Table Class Importer Prerequisites

Perform the following steps prior to starting Format Builder.

1. Move the field tables associated with the FML buffer from the Tuxedo system to the WebLogic Server/WebLogic Tuxedo Connector environment.

2. Use the weblogic/wtc/jatmi/mkfldclass utility to build java source code representing the field tables. Please refer to the WebLogic Server documentation for information on FML Field Table Administration.

3. Compile the source code. The resulting class files are called fldtbl classes because they implement the FldTbl interface. These fldtbl classes must be moved to a location specified in the Format Builder CLASSPATH.

The samples/fml directory contains several fldtbl class fields that you can use as samples. These samples allow you to work through the following steps without having completed the previous three steps.

Note: These steps are normally done when configuring WebLogic Tuxedo Connector, so these class files may already exist.

FML Field Table Class Sample Files

The following table provides a listing and description of the sample files installed for the FML Field Table Class Importer. All directory names are relative to the WebLogic Integration installation directory in the samples\di\ subdirectory.

Table 4-6 FML Field Table Class Sample Files

Directory	File	Description
fml\	bankflds.class	A compiled source file that serves as input to the FML Field Table Class Importer.
fml\	bankflds.java	A fldtbl source file generated by the mkfldclass utility.
fml\	crdtflds.class	A compiled source file that serves as input to the FML Field Table Class Importer.
fml\	crdtflds.java	A fldtbl source file generated by the mkfldclass utility.
fml\	tBtest1flds32.class	A compiled source file that serves as input to the FML Field Table Class Importer.
fml\	tBtest1flds32.java	A fldtbl source file generated by the mkfldclass utility.

 

Creating XML with the FML Field Table Class Importer

Perform the following steps to create an XML document with the FML Field Table Class Importer.

Note: If you create java classes using WebLogic Tuxedo Connector, you can place the .class files in the \ext directory. Once you place them in the \ext directory you can populate the Available Fields list automatically from the FML Field Table Class Importer dialog box.

1. Start Format Builder. The Format Builder main window displays.

2. Choose Tools Import FML Field Table Class Importer. The FML Field Table Class Importer dialog box displays.

   
    

3. Enter the name of the fldtbl class file that is to be processed into the Class Names field.

   Because a single FML buffer may contain fields from several field tables, you can enter one or more fldtbl class name files in the Class Names field. The list should be comma separated and each name does not have to include the .class extension.

   Note: If any of the listed classes are not fldtbl classes created by the weblogic/wtc/jatmi/mkfldclass utility, or are not in Format Builder's CLASSPATH, then an error dialog box is displayed. However, the valid fldtbl classes in the list will still be processed.

4. Click Load. The names of the fields from the field tables appear in the Available Fields list. The Available Fields list does not allow for duplicate names. If the name of a field appears in different field tables, it will only appear once on the list.

5. Select the desired fields from the Available Fields list and click Add. The selected fields will appear in the Selected Fields list. To remove a field from the Selected Fields list, select the desired field and click Remove.

6. Click OK after you have successfully selected all the necessary field names. The FML Field Table Class Importer dialog box will closes and the generated MFL will appear in the Format Builder navigation tree. The selected fields will be listed in the order they appear in the selected Fields list.

7. Edit the created MFL document to specify the order and occurrences of the fields that will be in the XML document which is passed to the WebLogic Tuxedo Connector FML/XML Translator from business process management.

8. Choose—>Tools—>Test to open Format Tester.

9. From the Format Tester menu bar, choose Generate—>XML.

10. Format Tester now creates an XML document that conforms to the MFL document in Format Builder. Edit the data content of the fields as desired.

11. Choose File—>Save XML to save the XML document to the name and location of your choice.

    The created XML may be imported into business process management by using the XML instance editor. Refer to the business process management documentation for information on importing XML.