Rational Developer for System z, Version 7.6

Annotations for COBOL Source Files

This topic describes using annotations for COBOL source files.
The annotations in the source files have three 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 XMLNameArray 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 XMLNameArray 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: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 will be 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 will be overridden by annotation synonyms from the file(s) specified with the annotationsFile attribute. This means that the annotations specified by the annotationsFile attribute have 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 XMLNameArray 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 XMLNameArray 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 XMLNameArray) 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.


Terms of use | Feedback

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