Message sets: Importing from C header files to create message definitions
Create a message definition file from a C header file for use in the MRM and IDOC domains.
You can populate your message set with message definitions by importing C header files, by using either the New Message Definition File From C header file wizard or the mqsicreatemsgdefs command.
Each C header file 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 C header file, but the "New Message Definition File From C header 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 an import from a C header file 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 C header file there are typically one or more C 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 structures are to be messages in the message definition file. The import operation creates a message and a 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 C header file" wizard you can import only one C header file with each import operation. But, if you import by using the command-line utility, you can import several C header files in each import operation.
If your C header file needs any other header files for a successful compilation, you must provide these and specify their location, because a compilation of your header file 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.
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. Also, if you import from the command line, only logical information is created in the new message set by default.
XML and TDS physical format properties are not populated and so 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 C structures you have imported were to appear in a TDS message.
If the TDS physical format is not applicable to your C 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 C header files in a single operation. All the C header files must be placed in the same directory and the directory location passed as a parameter to the utility.
You provide the necessary environment-specific information, and
include file location information by using an XML file. This must
contain an XML element called <C> which holds
one set of information that applies to all C header files 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
header files, 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 this new message set on an existing message set. This facility enables you to prepare an empty message set containing a CWF physical format and message set level CWF properties already populated, which then gets copied into the message set created by the import.