Message sets: Importing from COBOL copybooks to create message definitions

You can populate your message set with message definitions by importing COBOL copybook files, by using the "New Message Definition File From COBOL file" wizard or the mqsicreatemsgdefs command.

Tip: This topic is relevant only if you are using a message set to contain your message models. If you are using an application or library, use the New Message Model wizard, select COBOL as the data format that you are working with, then select Create a DFDL schema by importing a COBOL copybook or program; see Creating a DFDL schema file by using the New Message Model wizard.

Each COBOL copybook that you import results in a new message definition file. The root name of the message definition file defaults to the root name of the COBOL copybook file, but the "New Message Definition File From COBOL file" wizard allows you to choose a different root file name.

If the message definition file already exists, you must have permitted overwriting to occur for the import to proceed, in which case the existing content is deleted and re-created.

By default, all message definition files that are created as a result of COBOL copybook file import belong to the noTarget XML namespace and therefore reside in the (default) location in your workspace. This default namespace can be overridden by specifying a target namespace. See Namespaces with non-XML messages for reasons why you might want to do this.

In your COBOL copybook file there are typically one or more level 01 structures. You can select which of these structures to import. The import operation then imports those structures, plus any others that they require. All imported structures are converted into the equivalent elements, groups, and types in the message definition file.

You can also specify which of the selected level 01 structures are to be messages in the message definition file. The import operation creates a message and corresponding global element in the message definition file for each structure that you specify. If you do not specify that messages are to be created, you must create them manually using the Message Definition Editor after the import has completed.

If you import by using the "New Message Definition File From COBOL file" wizard, you can import only one COBOL copybook file with each import operation. If you use the command-line utility, you can import several COBOL copybook files in each import operation.

If your COBOL copybook file needs any other copybooks in order to compile successfully, you must provide these in the same directory, because a compilation of your copybook is performed as part of the import operation.

A report file is created during the import operation. This is located by default in the log folder of the message set. By default it takes the name of the message definition file, with .report.txt appended.

The copybook must not contain field names that are COBOL reserved keywords.

Physical information

In addition to creating logical information, the import can also create physical information. If the message set contains any Custom Wire Format (CWF) physical formats, the physical format properties for all CWF layers are populated. If the message set does not contain any CWF physical formats, only logical information is created. If you import from the command line, only logical information is created in the new message set by default. If you want physical information created as well, see Message Sets: Importing from the command line for details.

XML and TDS physical format properties are not populated and therefore take default values.

If you have one or more TDS layers, the import can cause entries in the task list, warning you that certain TDS properties must be set if the COBOL structures that you have imported were to appear in a TDS message.

If the TDS physical format is not applicable to your COBOL structures, you can ignore these task list entries because they are just warnings, they do not prevent your model being generated in another form, such as a message dictionary.

Because physical information is created, the application target environment (platform and compiler) is important because it governs the way that, for example, integers appear in the message. You can specify environment-specific information as part of the import operation, and the necessary properties are set accordingly. There is a range of environments supported; if your environment is not shown, choose the closest match and review the created physical information by using the Message Definition Editor after the import has completed.

Command-line invocation

The mqsicreatemsgdefs command-line utility allows you to import several COBOL files in a single operation. All the COBOL copybook files must be in single directory, and the directory location passed as a parameter to the utility.

You provide the necessary environment-specific information by using an XML file. This must contain an XML element called <COBOL> that holds one set of environment-specific information that applies to all COBOL copybook files that are imported during an invocation of the utility. A default XML file called mqsicreatemsgdefs.xml is supplied. If you want to apply different sets of information to different copybooks, you must create multiple XML files and run the utility multiple times.

The mqsicreatemsgdefs utility also allows you to create message set into which the message definition files are placed, as part of the import operation. You can also choose to base the message set created on an existing message set. This facility enables you to prepare an empty message set that contains a CWF physical format and pre-populated message set level CWF properties, which are then copied into the message set that is created by the import.