En este tema se describe la utilización de anotaciones para archivos origen COBOL.
Las anotaciones de los archivos origen tienen los componentes principales siguientes:
- Indicador de comentario
- Indicador de anotación
- Contenido de anotación
Nota: Para los distintos lenguajes, puede variar el orden de los componentes.
Por ejemplo, cuando se utiliza COBOL, el indicador de comentario, puede seguir al indicador
de anotación. Este tema utiliza COBOL como lenguaje fuente para la definición de datos.
Para que el compilador COBOL pase por alto las anotaciones, éstas deben aparecer como una línea
de comentario. Por lo tanto, las anotaciones COBOL siempre tienen un asterisco (*) en la columna 7
para indicar un comentario COBOL.
El formato del indicador de anotación para las anotaciones COBOL tiene un formato llamativo
opcional. En esta descripción, se utiliza un carácter @ (signo "arroba"). Sin embargo, se puede definir cualquier
otro carácter como indicador de anotación. El indicador de anotación está posicionado en la columna 1 seguido
de hasta 5 caracteres alfanuméricos.
El formato del contenido de anotación es el siguiente:
- Nombre de acción
- Nombre de datos al que se aplica el nombre de acción.
Para habilitar la posibilidad de anotación, el usuario tiene que crear un archivo XML de
acciones sinónimas. El archivo XML de acciones sinónimas es un archivo XML que define un conjunto de palabras de
anotación que son equivalentes, en significado, a las acciones que ya se proporcionan por los elementos
ItemExclusionArray, ItemSelectionArray y
XMLNamesArray del archivo de opciones del procesador por lotes.
El usuario especifica (crea) el archivo XML de acciones sinónimas en la línea de mandatos cuando
se invoca el procesador por lotes (xsebatch). El mandato es: xsebatch [-annot
synFile]. Para ver
una descripción completa del mandato xsebatch, consulte la sección Iniciar el procesador por lotes.
Si el archivo XML de acciones sinónimas se especifica de esta manera, las normas de anotación
especificadas en el archivo XML de acciones sinónimas se aplican a todos los archivos de especificación
del procesador por lotes (y por lo tanto todos los servicios subsiguientes) generados en esa invocación
en particular.
El usuario puede alterar temporalmente (por ejemplo, cambiar) el archivo XML de acciones sinónimas especificadas
en la línea de mandatos utilizando el atributo "annotationsFile" para los elementos de mensaje de entrada y
salida (InputMessage y OutputMessage) en el archivo de especificación de opciones del procesador por lotes
(ServiceSpecification.xml), consulte las secciones InputMessage y OutputMessage.
Cuando se utiliza el método de línea de mandatos para crear y especificar el archivo XML de acciones sinónimas, el
procesador por lotes pasa por alto los elementos ItemExclusionArray,
ItemSelectionArray y XMLNamesArray de los
archivos de opciones de procesador por lotes y en su lugar busca las anotaciones de datos origen que se han definido en
el archivo XML de acciones sinónimas.
La
Figura 1 es un ejemplo de un
archivo XML de acciones sinónimas que se puede utilizar para indicar al procesador que utilice las
anotaciones indicadas presentes en el ejemplo de lenguaje fuente COBOL.
Figura 1. Ejemplo de archivo XML de acciones sinónimas<?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>
La
Figura 2
es
el esquema XML del archivo XML de acciones sinónimas.
Figura 2. Esquema de archivo XML de acciones sinónimas<?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>
Normas y condiciones para archivos de acciones sinónimas
- El contenido del archivo de acciones sinónimas debe coincidir con el esquema
especificado. Si no lo hace, el comportamiento del procesador por lotes será imprevisible.
- Si se especifica el archivo de acciones sinónimas en la línea de mandatos y también se han especificado archivos de
acciones sinónimas en el atributo annotationsFile, el archivo –annot de la línea de mandatos se altera temporalmente
por los sinónimos de anotación del archivo o archivos especificados en el atributo annotationsFile. Esto significa que
las anotaciones especificadas por el atributo annotationsFile tienen preferencia/prioridad sobre las anotaciones
especificadas por la línea de mandatos.
- Si se especifica un archivo o archivos de acciones sinónimas (en la línea de mandatos y/o en el
archivo de opciones de procesador por lotes) pero no existen realmente, el procesador por lotes
emite un aviso y prosigue, pasando por alto, el archivo especificado.
- Las anotaciones que no se listan en el archivo de acciones sinónimas se pasan por alto.
- Si el archivo de acciones sinónimas se especifica en la línea de mandatos, todas las apariciones de
ItemExclusionArray, ItemSelectionArray y
XMLNamesArray en los archivos de opciones de procesador por lotes se pasan por alto.
- Si el archivo de acciones sinónimas se especifica en el atributo "annotationsFile" para elementos de mensaje de
entrada y salida, todas las apariciones de (ItemExclusionArray,
ItemSelectionArray y XMLNamesArray de ese
elemento de especificación de mensaje (InputMessage u OutputMessage) se pasan por alto.
- Si el archivo de acciones sinónimas se especifica en la línea de mandatos o en el atributo
"annotationsFile" pero no se encuentran anotaciones en el archivo origen, se emite un
mensaje informativo
Normas y condiciones para anotar declaraciones de datos
- El carácter & está reservado y no se puede utilizar como primer
carácter en el indicador de anotación.
- El uso y el comportamiento de las anotaciones en el procesador por lotes es equivalente a los elementos
correspondientes (ItemExclusionArray,
ItemSelectionArray y XMLNamesArray) cuyo
significado sustituyen las anotaciones.
- Excepto por el indicador de comentario necesario ("*" en COBOL) y el carácter & reservado,
las anotaciones pueden contener caracteres alfanuméricos válidos para el nombre COBOL
establecido por el estándar COBOL y, en el caso de las anotaciones que corresponden
a "xmlName", nombres XML válidos por el estándar XML.
- Todas las anotaciones se procesan empezando por el principio del archivo origen y
hasta, pero sin incluir:
- la primera línea de la sentencia PROCEDURE DIVISION. (Si el archivo origen no contiene
PROCEDURE DIVISION, se procesan todas las anotaciones del origen)
o bien
- el siguiente grupo de nivel 01 disponible después del grupo de nivel 01 seleccionado para la
interfaz en una especificación de mensaje en particular.
- Para COBOL, la anotación se debe especificar con el indicador de comentario en
la columna 7.
- Anotación para una palabra de una sola acción no puede abarcar varias líneas de origen.
- Para COBOL, el archivo origen debe estar en registros COBOL origen de 80 columnas de
formato fijo (por especificación COBOL)
- Las anotaciones especificadas para "itemName" y "xmlName" de XMLNameSelection
deben aparecen en líneas consecutivas. Es decir, la anotación que corresponde a
"itemName" debe ir seguida en la siguiente línea por la correspondiente a "xmlName".
Si esta condición no se cumple, se emite un mensaje de error y se pasa por alto la anotación.
- El procesador de anotaciones no expande las sentencias COBOL COPY. Esto significa que se pasan por alto
las anotaciones contenidas en libros de copia anidados.
- Se debe tener cuidado cuando se suministra el archivo de acciones sinónimas para un origen COBOL
con contenido preexistente en el área del indicador. Parte del área del indicador preexistente
puede entrar en conflicto con las anotaciones especificadas en las acciones sinónimas. El comportamiento del procesador de anotaciones es imprevisible en estas situaciones.
- A continuación se proporcionan reglas y condiciones adicionales aplicables cuando se utiliza la
función de anotación optional:
- Un elemento COBOL anotado como "optional" debe estar incluido implícita o explícitamente en la
interfaz. En otras palabras, el elemento COBOL anotado como "optional" no debe estar en la lista del parámetro
ItemExclude. Si el elemento COBOL está en la lista del parámetro
ItemExclude, se emite un mensaje de aviso y se omite la anotación "optional".
- Si la anotación "optional" tiene un valor que no se corresponde con un nombre de elemento COBOL
válido, se emite un mensaje de aviso.
- Si el elemento COBOL correspondiente al parámetro "optional" también lo está redenominando el
elemento XMLNameSelection, el parámetro "optional" debe dar el nombre nuevo para el elemento
COBOL. Si esto no se realiza, se aplica la regla nº 2.
- las anotaciones opcionales pueden aparecer por cualquier orden entre otras
anotaciones.
- Las anotaciones opcionales afectan sólo a los esquemas XML generados y no a
los conversores COBOL generados ni a los mensajes procesados o generados por los conversores.
- Las anotaciones opcionales sólo se aplican a los escenarios de conversión
compilados. Se ignoran las anotaciones opcionales de los escenarios de conversión interpretativa.
- Sólo los elementos de grupo y los elementos elementales (excepto los de los niveles 01, 77 y 88) se
pueden anotar como "optional". Las anotaciones se ignoran si se especifican para elementos no soportados.
- Los elementos COBOL anotados como "optional" pueden tener una cláusula OCCURS; la faceta minOccurs
para estos elementos se sobrescribe y se establece en 0 en lugar del valor derivado normalmente de la cláusula OCCURS.
- Los nombres de elemento en anotaciones opcionales no son sensibles a mayúsculas/minúsculas.