Rational Developer for System z

Annotations for COBOL source files

This topic describes using annotations for COBOL source files.
The annotations in the source files have the following main components:
Note: For different languages the order of the components may vary. For example, when using COBOL, the comment indicator, may follow the annotation indicator. This topic uses COBOL as source language for data definition.

In order for the annotations to be ignored by the COBOL compiler, the annotations have to appear as a comment line. Therefore, COBOL annotations always have an asterisk (*) in column 7 to indicate a COBOL comment.

The format of the annotation indicator for COBOL annotations have an optional eye-catching format. In this description, an @ ("at" sign) is used. However, any other character can be defined as the annotation indicator. The annotation indicator is positioned in column 1 followed by up to 5 alphanumeric characters.

The format of the annotation content is as follows:
  1. Action name
  2. Data name that the Action name applies to.

To enable the annotation capability, the user has to create a synonym action XML file. The synonym action XML file is an XML file that defines a set of annotation words that are equivalent, in meaning to the actions already provided by the ItemExclusionArray,, ItemSelectionArray, and XMLNamesArray elements of the batch processor options file.

The user specifies (creates) the synonym action XML file on the command line when invoking the Batch processor (xsebatch). The comand is: xsebatch [-annot synFile]. For a complete description of the xsebatch command, see Starting the batch processor.

If the synonym action XML file is specified in this way, the annotation rules specified in the synonym action XML file apply to all Batch processor specification files (and therefore all subsequent services) generated in that particular invocation.

User can override (i.e., change) the synonym action XML file specified on the command line by using the "annotationsFile" attribute for input and output message elements (InputMessage and OutputMessage) in the Batch processor option specification file (ServiceSpecification.xml), see InputMessage and OutputMessage.

When the command line method is used to create and specify the synonym action XML file, the Batch processor ignores the ItemExclusionArray,, ItemSelectionArray, and XMLNamesArray elements of the batch processor options files and instead looks for the source data annotations that are defined in the synonym action XML file.

Figure 1 an example of a synonym action XML file that can be used to direct the processor to use the indicated annotations present in the COBOL source language sample.
Figure 1. Example of Synonym Action XML File
<?xml version="1.0" encoding="UTF-8"?>
<synactions:SynonymActions xmlns:synactions="http://www.ibm.com/xmlent/annot/emf/synactions">
  <synactions:ActionGroup lang="COBOL" format="fixed" indicator="@ANN"> 
    <synactions:ExcludeItem>
      <synactions:itemName annotatedAs="OMIT"/>
    </synactions:ExcludeItem> 
    <synactions:ItemSelection>
      <synactions:itemName annotatedAs="KEEP"/>
      <synactions:optional annotatedAs="OPTIONAL"/>
    </synactions:ItemSelection>
    <synactions:XMLNameSelection> 
      <synactions:itemName annotatedAs="OLDNAME"/>
      <synactions:xmlName annotatedAs="NEWNAME"/>
    </synactions:XMLNameSelection>
  </synactions:ActionGroup>
</synactions:SynonymActions>
Figure 2 is the XML Schema for the Synonym action XML file.
Figure 2. Synonym Action XML File Schema
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soannot="http://www.ibm.com/xmlent/annot/emf/synactions"
  targetNamespace="http://www.ibm.com/xmlent/annot/emf/synactions">
  <xsd:element name="itemName">
    <xsd:complexType>
      <xsd:attribute use="required" name="annotatedAs" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="ExcludeItem">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element minOccurs="1" maxOccurs="1" ref="soannot:itemName"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="XMLNameSelection">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element minOccurs="1" maxOccurs="1" ref="soannot:itemName"/>
        <xsd:element minOccurs="1" maxOccurs="1" ref="soannot:xmlName"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="ItemSelection">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element minOccurs="1" maxOccurs="1" ref="soannot:itemName"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="ActionGroup">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element minOccurs="1" maxOccurs="1" ref="soannot:ExcludeItem"/>
        <xsd:element minOccurs="1" maxOccurs="1" ref="soannot:ItemSelection"/>
        <xsd:element minOccurs="1" maxOccurs="1" ref="soannot:XMLNameSelection"/>
      </xsd:sequence>
      <xsd:attribute use="required" name="indicator" type="xsd:string"/>
      <xsd:attribute use="optional" name="lang" type="xsd:string"/>
      <xsd:attribute use="optional" name="format" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="xmlName">
    <xsd:complexType>
      <xsd:attribute use="required" name="annotatedAs" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="SynonymActions">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element minOccurs="1" maxOccurs="1" ref="soannot:ActionGroup"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>

Rules and conditions for synonym action files

  • Content of the synonym action file must match the schema specified. If it does not, the behavior of the Batch processor is unpredictable.
  • If synonym action file is specified on the command line and there are synonym action files that are also specified on the annotationsFile attribute, the –annot file from the command line is overridden by annotation synonyms from the file(s) specified with the annotationsFile attribute. This means that the annotations specified by the annotationsFile attribute has precedence/priority over the annotations specified by the command line.
  • If the synonym action file or files are specified (on the command line and/or in the Batch processor options file) but they do not actually exist, the Batch processor issues a warning and proceeds by ignoring the specified file.
  • Annotations which are not listed in the synonym action file are ignored.
  • If the synonym action file is specified on the command line, all occurrences of ItemExclusionArray,, ItemSelectionArray, and XMLNamesArray in the batch processor options files are ignored.
  • If the synonym action file is specified on the "annotationsFile" attribute for input and output message elements , all occurrences of (ItemExclusionArray,, ItemSelectionArray, and XMLNamesArray in that message specification element (InputMessage or OutputMessage) are ignored.
  • If the synonym action file is specified on the command line or on the "annotationsFile" attribute but no annotations are found in the source file, an informational message is issued

Rules and conditions for annotating data declarations

  • The ampersand sign (&) is reserved and cannot be used as the first character in the annotation indicator.
  • Use and behavior of annotations in the Batch processor is equivalent to the corresponding elements (ItemExclusionArray, ItemSelectionArray, and XMLNamesArray) whose meaning the annotations are replacing.
  • Except for the required comment indicator ("*" in COBOL) and the reserved & (ampersand sign), annotations can contain alphanumeric characters valid for the COBOL name set per COBOL standard and, in the case of annotations that correspond to "xmlName", valid XML names per XML standard.
  • All annotations are processed starting at the beginning of the source file, up to but not including either :
    • the very first PROCEDURE DIVISION statement. (If the source file does not contain a PROCEDURE DIVISION, all annotations in the source are processed)

      or

    • the next available level 01 group after the level 01 group selected for the interface in a particular message specification.
  • For COBOL, the annotation must be specified with the comment indicator in column 7.
  • Annotation for a single action word cannot span multiple source lines.
  • For COBOL, the source file must be in fixed-format 80-column source COBOL records (per COBOL specification)
  • Annotations specified for "itemName" and "xmlName" of the XMLNameSelection must appear on consecutive lines. That is, annotation that corresponds to "itemName" must be followed on the next line by the one corresponding to "xmlName". If this condition is not met, an error message is issued and the annotation is ignored.
  • COBOL COPY statements are not expanded by the annotation processor. This means that annotations contained within nested copybooks are ignored.
  • Care should be taken when supplying the synonym action file for a COBOL source containing pre-existing content in the indicator area. Some of the pre-existing indicator area content may conflict with the annotations specified in the synonym actions. Behavior of the annotation processor is unpredictable in such situations.
  • The following are additional rules and conditions when annotations that designate data items as "optional" are used:
    1. COBOL item annotated as "optional" must implicitly or explicitly be included in the interface. In other words, the COBOL item annotated as "optional" must not be listed on the ItemExclude parameter. If the COBOL item is listed on the ItemExclude parameter, a warning message is issued and the "optional" annotation is ignored.
    2. If the annotation that designates a data item as "optional" has a value that does not correspond to a valid COBOL item name, a warning message is issued.
    3. If the COBOL item corresponding to the "optional" parameter is also being renamed by the XMLNameSelection`element, the "optional" parameter must list the new name for the COBOL element. If this is not performed, then rule #2 takes effect.
    4. Annotations that designate data items as "optional" can appear in any order among other annotations.
    5. Annotations that designate data items as "optional" affect only the generated XML Schemas and not the generated COBOL converters or the messages that are processed or generated by the converters.
    6. Annotations that designate data items as "optional" only apply to the Compiled conversion scenarios. Optional annotations in the Interpretive conversion scenarios are ignored.
    7. Only group items and elementary items (other than Level 01, 77, and 88) can be annotated as "optional". Annotations are ignored if specified for unsupported items.
    8. COBOL items annotated as "optional" can have an OCCURS clause; minOccurs facet for these items are overwritten and set to 0 instead of the value normally derived from the OCCURS clause.
    9. Item names in optional annotations are not case sensitive.


Feedback