This topic describes using annotations for COBOL source
files.
The annotations in the source files have the following main components:
- Comment indicator
- Annotation indicator
- Annotation content
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:
- Action name
- 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:
- 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.
- 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.
- 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.
- Annotations that designate data items as "optional"
can appear in any order among other annotations.
- 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.
- Annotations that designate data items as "optional"
only apply to the Compiled conversion scenarios. Optional annotations
in the Interpretive conversion scenarios are ignored.
- 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.
- 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.
- Item names in optional annotations are not case
sensitive.