Rational Developer for System z, Versión 7.6.1

Anotaciones para archivos fuente COBOL

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:
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:
  1. Nombre de acción
  2. 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:
    1. 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".
    2. 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.
    3. 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.
    4. las anotaciones opcionales pueden aparecer por cualquier orden entre otras anotaciones.
    5. 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.
    6. 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.
    7. 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.
    8. 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.
    9. Los nombres de elemento en anotaciones opcionales no son sensibles a mayúsculas/minúsculas.


Términos de uso | Comentarios

Este Information Center está basado en tecnología Eclipse. (http://www.eclipse.org)