Importing a COBOL copybook as a DFDL schema

You can import a COBOL copybook as a DFDL schema file and apply it to the messages. This utility helps you to quickly create a schema with a valid format and to specify elements and values by using the DFDL editor.

Before you begin

Review the following considerations as you might want to edit the copybook before you import it:

  • The COBOL copybook must follow the standard format, for example, statements must be between columns 6 and 72.
  • The importer loads only objects that are labeled as 01.
  • The importer fails if it detects certain keywords such as TEXT and some characters such as TAB.
Note: If the import fails, cancel the import and edit the copybook before you import it again.

About this task

The COBOL copybook importer runs on Windows and Linux, but not on Mac OS. On 64-bit Red Hat Enterprise Linux and Ubuntu Linux (both 32-bit and 64-bit), additional operating system installation steps are required; see the help for IBM® Rational® Developer for z Systems®:

Features that use the COBOL importer do not work properly.


  1. In the Schema Library view of the Architecture School perspective, click Add, then click Other > DFDL Schema from the menu.

    Adding the DFDL schema

    The New DFDL Schema window is displayed.
    Choosing the DFDL schema
  2. In the New DFDL Schema window, click Import. All actions are described for reference.
    To specify the location of a DFDL schema file to add to the project.
    To open the file that is specified in the Current Location field in the DFDL editor. See Editing a DFDL schema.
    To add a DFDL schema file to the library. See Creating a DFDL schema.
    To create a DFDL schema from another type of data. The COBOL copybook is the only currently supported source for import. Go to the next step.
  3. The HCL OneTest API Tools program opens, which you use to open the HCL OneTest API project that contains the COBOL copybook source file you want to use to create the DFDL schema. Click File > New > Other from the menu.

    Opening the DFDL wizard

  4. Create the DFDL schema from existing source by expanding DFDL and selecting DFDL Schema From. Click Next.

    Create DFDL schema from an existing source.

  5. You want to use an existing COBOL source file, so click COBOL file, then click Next.

    Choose the source file for the DFDL schema.

  6. Complete the requested information.
    Select the source file
    1. Enter the Project. The Folder is optional. The Target file name defaults to the imported file name but you can change that name.
    2. Choose one of the following location options for the source COBOL copybook:
      Select source file from workspace
      Browse to a COBOL copybook in the current project to use as a source for the schema.
      Select source file from outside workspace
      Select from a list of previously used copybook locations, or click Browse to go to a location on your system or network that is outside your project workspace.
    3. Select Overwrite existing DFDL schema file if the file you specified exists and you want to replace the existing contents.
    4. Select Copy source file into the 'importFiles' directory of the target project if you want to copy the source file to the importFiles directory before you convert it.
    5. Click Next.
  7. Select the 01 level structures to import.
    Select the 01 level COBOL structures to import as messages
    The available structures are listed on the left side of the dialog. Highlight the structures that you want to include, then click >> to move them to the import list.
  8. Click Next to configure options such as how to handle null values, pad characters, encoding options, and more or click Finish to bypass this step and use the default import options.
    Choose import options
    Choose import options
    The DFDL schema is displayed and can be further edited.
    The imported schema displays
  9. The import action created the DFDL XSD schema but you must load that schema into HCL OneTest API.
    1. Click Change in the New DFDL Schema window.
    2. In the Select Location window, click Browse. The new schema is added to the schema library.
    3. In the Open window, select All Files for the Files of type field. Click Open. Browse xsd file
    The DFDL Schema Library lists the path to the imported DFDL schema file.

    Loaded DFDL file

    Note: The new DFDL schema contains a reference to a file named CobolDataDefinitionFormat.xsd, which is added automatically to the project_folder/IBMdefined folder by the import wizard. If you copy or move the new DFDL schema file to a new location, be sure to also copy or move the CobolDataDefinitionFormat.xsd file and keep it in the same relative position to the schema file.

What to do next

You can now apply this DFDL schema to a messaging action as shown:

Apply the schema to a messaging action