Importing Metadata

WebLogic Integration provides utilities that allow you to import COBOL copybooks, convert C structure definitions, and convert FML field table classes into MFL files. The following topics explain how to perform these import operations:

• 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 by creating a message definition to translate the COBOL data. When importing a copybook, you can use comments 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 is displayed.

   Figure 4-1 COBOL Copybook Importer

   
    

2. Designate the properties, as described in the following table.

   Table 4-1 COBOL Copybook Importer Properties

   Property	Value	Description
   File Name	text string	Type the full pathname of the file you want to import or use the Browse button to navigate to the location of the file.
   Byte Order	Big Endian	Select this option for IBM 370, Motorola, and most RISC designs (IBM mainframes and most UNIX platforms).
   	Little Endian	Select this option for Intel, VAX, and Unisys processors (Windows, VMS, Digital, UNIX, and Unisys)
   Character Set Note: The character set is an attribute of the originating host machine.	EBCDIC	Select this option to set the character set to EBCDIC.
   	US-ASCII	Select this option to set the character set to US-ASCII.
   	Other	Select character encoding of the field data by using a list of code pages.

   
    

3. Click one of the following:

   • OK—imports the COBOL Copybook using the settings you defined.

   • Cancel—closes the dialog box and returns you to Format Builder without importing.

   • About—displays information about the COBOL Copybook importer, including the version being used and copybook features that are supported.

After you import a copybook, you can work in the same way you work with any message format definition. If you find an error or unsupported data type in the copybook, a message is displayed, informing you of the error. You can choose to have the error displayed or saved in a log file for future reference.

The following table provides a listing and descriptions of the sample files installed for the COBOL copybook importer. All directory names are relative; the specified directories are under under SAMPLES_HOME\integration\samples\di where SAMPLES_HOME is the samples directory in your WebLogic Platform installation.

Table 4-2 Sample COBOL Copybook 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 types of output data:

• MFL document

• C code

Whichever type of output you want, you must first specify a .c or .h input file, which must be parsed, and then select the desired structure. Then you can choose between MFL (default) or C code for your output.

All input to the parser must be valid C code. In addition, all external references, such as #include, #define, and typedef statements, must be resolved before you can use them. You can resolve them by editing them manually or by using the compiler's preprocessor.

Various platform-specific parameters may affect the description of data for C code. For example, the length of a long on a particular platform affects the binary data that conforms to a particular structure definition.

Two methods are available 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, if you choose to generate your source in C, you may compile the C code on the desired machine. The compiler on that machine accounts for the necessary platform-dependent information. This approach allows you to produce an executable file that, when run, produces two files: an MFL document and binary data that conforms to that MFL. 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 new 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_HOME\integration\samples\di\cfg directory.

Sample C Struct Importer Files

The following table provides a listing and descriptions of the sample files installed for the C struct importer. All directory names are relative; the specified directories are under SAMPLES_HOME\integration\samples\di.

Table 4-3 Sample C Struct Importer Files  

Directory	File	Description
C	emprec5.h	C version of the emprec5.cpy sample Copybook file, with some typedefs.
C	emprec5n.h	Variant of the emprec5.h file in which a nested struct definition, but no typedef is used.
C	emprec5s.h	Simple version of the emprec5.h file.
C	ntfsez.h	Small sample, extracted from the ntfs.h file, designed to test recursive typedefs.
Cfg	cprofile.c	Source code for the cprofile.c utility; designed to generate profiles on various platforms.
The following .cfg files are generated by the cprofile program on various platforms. Each .cfg file contains a value for 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 Platform 7.0—>WebLogic Integration 7.0—>Format Builder. The Format Builder main window is displayed.

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

   Figure 4-2 C Struct Importer Dialog Box

   
    

The C Struct Importer dialog box allows you to specify import properties, as described in the following table.

Note: Initially, MFL is specified as the default output type.

Table 4-4 C Struct Importer Properties  

Category	Property	Description
Input	Input File	Type the full pathname of the file you want to import or use the Browse button to navigate to the location of the file.
	Structure	Drop-down list of structures found in the input file after parsing is successful.
	Parse	Select this option 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, you can generate MFL from a structure definition and a hardware configuration file. The Hardware Profile dialog box is displayed with the following options. Name—Specify an existing profile either by entering the file name or using the Browse option. The prebuilt hardware profiles may be found in the samples\di\cfg directory. Save—saves the current hardware profile. Save As—allows you to save the current hardware profile under another name. Edit—allows you to edit the current hardware profile. New—allows you to create a new hardware profile.
	C Code	If you select this option, you can generate C source code to compile on the target machine and execute to produce MFL. The C Code File Names dialog box is displayed with the following options. MFL Gen—specifies the C source code file name that must be compiled on the target machine to generate MFL. Use the Browse option 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. Use the Browse option to navigate to the directory where you want the file to reside.

 

Figure 4-3 C Struct Importer Dialog Box

 

3. Click one of the following:

   • OK—saves your hardware profile changes.

   • Cancel—dismisses your hardware profile changes.

   • About—displays information about the C Struct Importer, including the version number and the release date.

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 in the SAMPLES_HOME\integration\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 compiler normally used. You should be able to compile and execute it 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 appropriate commands for your platform:

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

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

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

• On UNIX

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

Running the Hardware Profile Utility

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

cprofile configfilename [DESCRIPTION]

A description is optional. If you decide to provide one, put it in the configuration file as the value of DESCRIPTION. If the description contains embedded blanks, enclose it in quotes.

Generating MFL

To generate MFL:

1. Enter a filename in the Input File field, or click Browse and select a file from the list that is displayed.

2. Click Parse to parse the file.

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

   Note: If your file does not parse correctly, we recommend that you proceed in one of two ways:

• Run your .h or .c source code through the compiler, preprocessor, and then run the processor output through the parser.

• Comment out the character creating the parsing failure and attempt to parse again. Please note that the parser fails at the first instance of incompatible data it encounters. Therefore, repetition of this step may be required.

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

   At this point, you must provide some profile configuration data to generate the MFL directly. You can do this by either 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 in one of the following ways: enter the filename in the Hardware Profile Name field, or click Browse to select a file from the list that is displayed.

     Click Edit to open the hardware profile editor if you need to view or edit the profile parameters.

   Note: 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. The Hardware Profile editor is displayed with the default parameters loaded. Specify a name and description for the new profile, and modify the primitive data types and byte order as required.

     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 is displayed providing you with an opportunity to view or file the error log.

   Figure 4-5 MFL Generation Errors Dialog Box

   
    

7. Click one of the following:

   • Display Error Log—to view any errors encountered,

   • Save Error Log—to save the error log to the location of your choice, or

   • Cancel—to dismiss the MFL Generation Errors dialog box.

After you determine which errors were generated, you can return to the C Struct Importer and repeat the applicable steps.

Generating C Code

To generate C code:

1. Enter a filename in the Input File field, or click Browse and select a file from the list that is displayed.

2. Click Parse to parse the file.

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

   Note: If your file does not parse correctly, we recommend that you proceed in one of two ways:

• Run your .h or .c source code through the compiler, preprocessor, and then run the processor output through the parser.

• Comment out the character creating the parsing failure and attempt to parse again. Please note that the parser fails at the first instance of incompatible data it encounters. Therefore, repetition of this step may be required.

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

4. Select the C Code option.

5. Enter a filename in either the MFL Gen or Data Gen field, or click Browse and select a file from the list that is displayed.

6. Click OK.

   Messages are displayed if you are about to overwrite an existing file or if the code generation has succeeded or failed.

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

   Note: You must copy the input file containing the struct declarations, as well. When compiled, both programs accept the name of the output file as an argument.

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

 

---

Importing an FML Field Table Class

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

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

FML Field Table Class Importer Prerequisites

Before 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. For information about FML Field Table Administration, see the WebLogic Server documentation.

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

The SAMPLES_HOME\integration\samples\di\fml directory contains several fldtbl class fields that you can use as samples. These samples allow you to start Format Builder without completing the previous three steps.

Note: Because most users perform these steps when configuring WebLogic Tuxedo Connector, these class files may already exist.

Sample FML Field Table Class Files

The following table provides a listing and descriptions of the sample files installed for the FML Field Table Class Importer. All files are in the SAMPLES_HOME\integration\samples\di\fml directory.

Table 4-5 FML Field Table Class Sample Files  

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

 

Creating XML with the FML Field Table Class Importer

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. You can then populate the Available Fields list automatically from the FML Field Table Class Importer dialog box.

1. Start Format Builder. The Format Builder main window is displayed.

2. Choose Tools—>Import—>FML Field Table Class Importer. The FML Field Table Class Importer dialog box is displayed.

   
    

3. In the Class Names field, enter the name of the fldtbl class file to be processed.

   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. Items in the list should be separated by commas. Name are not required 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 if they are not included in the Format Builder CLASSPATH, then an error dialog box is displayed. Even if an error occurs, however, the valid fldtbl classes in the list are processed.

4. Click Load. The names of the fields from the field tables are displayed in the Available Fields list. The Available Fields list does not allow duplicate names. Even if the name of a field appears in different field tables, it is included only once in the list.

5. Select the desired fields from the Available Fields list and click Add. The selected fields are displayed in the Selected Fields list. (To remove a field from the Selected Fields list, select it and click Remove.)

6. When your Selected Fields list is complete, click OK. The FML Field Table Class Importer dialog box closes and the name of the generated MFL is added to the Format Builder navigation tree. The selected fields are listed in the order in which they appear in the Selected Fields list.

7. Edit the created MFL document to specify the order and number of occurrences of the fields in the XML document to be passed to the WebLogic Tuxedo Connector FML/XML Translator from business process management (BMP).

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

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

   Format Tester creates an XML document that conforms to the MFL document in Format Builder.

10. Edit the data content of the fields in the XML document as desired.

11. Choose File—>Save XML to save the XML document in a file with a specified name and location.

    The created XML can be imported and used in business process management functions by using the XML instance editor. For information about importing XML, see the BPM documentation.