Rational Developer for System z, Version 7.6

Including COBOL source code comments in generated XSD and WSDL files

This topic describes an option that enables you to add the comments from a COBOL source code file to the XSD and WSDL files that are created when you generate a Web service using the bottom-up method and using compiled XML conversion in a single-service project.

This option is available both in the Create New Service Interface (bottom-up) wizard (see Setting preferences for COBOL XML converters) and in the command-line batch processor (see the property GEN_COMMENT_IN_XSD in CodegenProperty).

The following table shows the types of files that are used as input files and some of the files that are generated as output files when you create a Web service using the bottom-up method and using compiled XML conversion in the batch processor (see The available types of single-service projects):
Type of file: Purpose:
Input file: A COBOL source code file or copybook file This file contains the request language structure and the response language structure that you specify for the Web service.
Output WSDL and XSD files: A WSDL file This file describes the Web service.
Two XSD files These two files describe a message format that is derived from the the request language data structure and the response language data structure.

When the option described in this topic is enabled, the runtime code generator extracts the comments from the COBOL source code file and adds the comments to the WSDL file and to the two XSD files described in the previous table.

The following table describes this option in more detail:
Item: Description:
Which comment lines are extracted:
  • Every comment line is extracted starting at the beginning of the source file, and continuing up to but not including whichever of the following items comes first:
    • The very first PROCEDURE DIVISION statement. If the source file does not contain a PROCEDURE DIVISION statement, then every comment line is extracted from the source file.
    • The next available level 01 group after the level 01 group selected for the interface.
  • Comments are extracted only from the specified COBOL source code file itself and not from any COPY files that it may reference.

  • Only comment lines (created by placing a * in column 7) are extracted. Comment entries and optional paragraphs are not extracted.

Where the comment lines are placed in the XSD and WSDL files: The extracted comment lines within each level 01 COBOL data item in the COBOL source code file are added to the documentation element of the annotation element belonging to the top-level data type derived from that level 01 COBOL data item.
Entity references: Characters that are used in XML as pre-defined entity references are replaced by their expanded forms. For example, an ampersand symbol (&) is replaced by a string that represents the ampersand entity expansion.
Multibyte characters: Multibyte characters in the text of a COBOL comment must follow the rules given in the Enterprise COBOL documentation for multibyte characters.
Globalization concerns: The content of the COBOL comment lines is expected to follow the rules of the Enterprise COBOL version 3.4 and later. No attempts to manipulate, transform or translate the content (beyond what is described in this section) is done by the EST generation process.
Invalid XML code points: If invalid XML 1.0 codepoints appear in the COBOL comments and the copybook is given to the Rational® Developer for System z® tools for processing, then the behavior of the tool is unpredictable (The null character (0x00) is an example of invalid XML content).

Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)