Rational Developer for System z, Versión 7.6.1

Programas de utilidad de información de almacenamiento de ejecución de conversor

Los conversores XML de petición y respuesta proporcionan programas de utilidad para recuperar los tamaños de las áreas de almacenamiento respectivas que se deben proporcionar cuando se invocan los conversores.

Existen tres áreas de almacenamiento que el llamante deberá asignar dinámicamente antes de invocar los conversores. Estas áreas permiten almacenar las siguientes estructuras:

Normalmente, los usuarios de Enterprise Service Tools (EST) no tienen que preocuparse de asignar manualmente estas áreas, ya que el controlador del conversor generado maneja la asignación de estas áreas de forma adecuada para el entorno de ejecución. Si los conversores se despliegan en un entorno de ejecución personalizado, los programas de utilidad que aquí se describen pueden ser útiles para un componente que selecciona dinámicamente los conversores a invocar sin conocer las definiciones de estructura de lenguaje en las que se basa un conversor XML.

El Adaptador XML IMS para IMS Connect es un ejemplo de un componente que utiliza los programas de utilidad. Para continuar sin estado, el Adaptador XML IMS se basa en los programas de utilidad para determinar cuánto almacenamiento debe asignar antes de invocar los conversores.

Programas de utilidad de conversor XML de petición y respuesta

Los conversores XML de petición y respuesta consiste en una suite de programas que trabajan conjuntamente para realizar la conversión. Se pueden invocar los siguientes programas antes que el programa principal de conversión XML para preparar las áreas de almacenamiento necesarias o para comprobar las condiciones de límite. Tenga en cuenta que los parámetros que se pasan a estos programas se pasan por referencia y salida.

Para conversores XML COBOL, se puede utilizar la tabla siguiente como referencia:
Nombre: Conversor de XML a estructura de lenguaje:[Prefijo nombre programa] + 'J'
Descripción: Obtiene la longitud necesaria en bytes del almacenamiento intermedio de estructuras de lenguaje para la conversión de XML a estructura de lenguaje.
Parámetros: Nombre: Tipo: Salida
XML2LS-LANG-BUFFER-LENGTH Binario firmado de 4 bytes Longitud necesaria en bytes del almacenamiento intermedio de estructuras de lenguaje para la conversión de XML a estructura de lenguaje.
XML2LS-PROPERTIES 1 byte binario 8 indicadores de 1 bit para la conversión de XML a estructura de lenguaje.

Bit 8 (x'80') : indicador de múltiples segmentos Bit 7..1 : reservado para uso futuro.

Nombre: Conversor de XML a estructura de lenguaje:[Prefijo de nombre de programa] + 'L
Descripción: Obtiene la longitud necesaria en bytes del almacenamiento intermedio de estructuras de lenguaje para la conversión de XML a estructura de lenguaje.
Parámetros: Nombre: Tipo: Salida
LS2XML-LANG-BUFFER-LENGTH Binario firmado de 4 bytes Longitud necesaria en bytes del almacenamiento intermedio de estructuras de lenguaje para estructura de lenguaje a XML.
LS2XML-PROPERTIES 1 byte binario 8 indicadores de 1 bit para la conversión de estructura de lenguaje a XML.

Bit 8 (x'80') : indicador de múltiples segmentos Bit 7..1 : reservado para uso futuro.

Nombre: Conversor de XML a estructura de lenguaje:[Prefijo nombre programa] + 'K'
Descripción: Obtiene la longitud necesaria en bytes del almacenamiento intermedio XML para la conversión de estructura de lenguaje a XML.
Parámetros: Nombre: Tipo: Salida
LS2XML-XML-BUFFER-LENGTH Binario firmado de 4 bytes Longitud necesaria en bytes del almacenamiento intermedio de documentos XML para la conversión de estructura de lenguaje a XML.
Para conversores XML PL/I, se puede utilizar la tabla siguiente como referencia:
Nombre: Conversor de XML a estructura de lenguaje:[Prefijo nombre programa] + 'J'
Descripción: Obtiene los requisitos de almacenamiento de estructuras de lenguaje de petición
Parámetros: Nombre: Tipo: Salida
p_instruct_max_size Binario firmado de 4 bytes Longitud máxima en bytes de la estructura de lenguaje de petición
Nombre: Conversor de XML a estructura de lenguaje:[Prefijo de nombre de programa] + 'L
Descripción: Obtiene los requisitos de almacenamiento de estructura de lenguaje de respuesta
Parámetros: Nombre: Tipo: Salida
p_outstruct_max_size Binario firmado de 4 bytes Longitud máxima en bytes de la estructura de lenguaje de respuesta
Nombre: Conversor de XML a estructura de lenguaje:[Prefijo nombre programa] + 'K'
Descripción: Obtiene los requisitos de almacenamiento de documentos XML de respuesta
Parámetros: Nombre: Tipo: Salida
p_outxml_max_size Binario firmado de 4 bytes Longitud máxima en bytes del documento XML de respuesta

Longitud máxima en bytes de un estructura de lenguaje

La longitud máxima en bytes de un estructura de lenguaje utiliza el límite superior para todos los elementos de grupo y elementales de longitud variable de la estructura. Este valor representa cuánto almacenamiento ocupará la estructura de lenguaje en el peor de los casos.

Longitud máxima en bytes de mensajes XML

Basándose en la estructura o estructuras de lenguaje y en el esquema XML generado o correlacionado, la herramienta calcula el número máximo de bytes que se pueden ocupar por un documento XML derivado. El cálculo tiene en cuenta varios factores. Entre ellos:
  • La longitud de los nombres de códigos de elementos XML.
  • El número máximo de posiciones de carácter en cada elemento de datos cuando se convierte al formato de visualización.
  • El número máximo de bytes necesarios para representar un carácter en cada elemento de datos.
  • El número máximo de apariciones de cada elemento de datos.
  • La expansión de las 5 entidades predefinidas en XML (<,>,',",&); que se escapan a <, >, ', " y &.
    • Por ejemplo, un elemento de datos PIC X(5) cuyo contenido es a>b>c se expande a a>b>c en el documento XML de respuesta.
    • Por lo tanto, se supone que cada elemento de datos no numérico tiene un factor de expansión de 6, ya que la longitud de la entidad más larga es de 6 caracteres (").
  • Número máximo de apariciones de cada estructura de lenguaje (múltiples segmentos de IMS, sólo ascendente).
A continuación, se muestra detalladamente cómo se calcula el número máximo de bytes ocupados por un elemento de datos. Supongamos que:
  • El elemento de datos se declara como 05 OUT-ITEM PIC X/N/G(5) OCCURS 3.
  • El elemento de datos se correlaciona con el nombre de código de elemento XML out-field. Por lo tanto, los códigos de inicio y finalización son <out-field> y <out-field/>.
  • Cuando la página de códigos de respuesta es UTF-16, siempre son necesarios 2 bytes por carácter.
El número máximo de bytes se calcula mediante las fórmulas siguientes:
[Bytes occupied by XML element start and end tags] + 
[Max bytes occupied by data item in display format with entity expansion]
    = [Max bytes occupied by field]

[Bytes occupied by XML element start and end tags] 
    = [((Number of characters in the start tag +
      Number of characters in the end tag) * 
      Number of bytes per character) * (Total number of occurrences)] 
    = [ ((11 + 12) * (1 or 2)) * 3] 
    = 69 bytes (SBCS) or 138 bytes (UTF-16)

[Max bytes occupied by data item in display format with entity expansion]
    = [((Length of the longest predefined entity * 
      Number of characters in the field) *
      Number of bytes per character)) * 
      (Total number of occurrences)]
      = [ ((6 * 5) * (1 or 2)) * 3 ] 
      = 90 bytes (SBCS) or 180 bytes (UTF-16)
Por tanto, según las fórmulas anteriores, hay dos resultados posibles para el número máximo de bytes necesarios para representar OUT-ITEM en un documento XML:
  • Para una página de códigos de respuesta SBCS, el máximo es 69 + 90 = 159 bytes.
  • Para una página de códigos de respuesta UTF-16, el máximo es 138 + 180 = 318 bytes.

Programa de utilidad de agregado del controlador del conversor COBOL

La suite de programas de controlador de conversor COBOL contiene un programa de utilidad que proporciona toda la información disponible conocida por el conversor. Además de la información que se puede obtener de los programas de utilidad de conversor de petición y respuesta, los identificadores del juego de caracteres codificado (CCSID) del XML de petición, también se incluyen el XML de respuesta, el host y las páginas de códigos.

Se toma en consideración el diseño de mensajes multisegmento de IMS al calcular los requisitos de memoria para la estructura de lenguaje y de almacenamientos intermedios XML.

Nombre: Conversión de estructura de lenguaje a XML:[Prefijo de nombre de programa] + 'X'
Descripción:
  1. Obtiene los requisitos de almacenamiento intermedio de documentos XML y estructuras de lenguajes.
  2. Obtiene el XML de petición, el XML de respuesta y la información de página de códigos.
Parámetros: Nombre: Tipo: Salida:
XML2LS-LANG-BUFFER-LENGTH Binario firmado de 4 bytes Longitud necesaria en bytes del almacenamiento para la conversión de XML a estructura de lenguaje.
LS2XML-LANG-BUFFER-LENGTH Binario firmado de 4 bytes Longitud necesaria en bytes del almacenamiento intermedio de estructuras de lenguaje de respuestas.
LS2XML-XML-BUFFER-LENGTH Binario firmado de 4 bytes Longitud necesaria en bytes del almacenamiento intermedio para la conversión de estructura de lenguaje a XML.
XML2LS-XML-CCSID Binario firmado de 4 bytes Identificador de juego de caracteres codificado para la entrada de la conversión de XML a estructura de lenguaje.
HOST-LANG-CCSID Binario firmado de 4 bytes Identificador de juego de caracteres codificado para estructuras de lenguaje
LS2XML-XML-CCSID Binario firmado de 4 bytes Identificador de juego de caracteres codificado para la salida de la conversión de estructura de lenguaje a XML.
XML2LS-PROPERTIES 1 byte binario 8 indicadores de 1 bit para la conversión de XML a estructura de lenguaje.

Bit 8 (x'80') : indicador de múltiples segmentos Bit 7..1 : reservado para uso futuro.

LS2XML-PROPERTIES 1 byte binario 8 indicadores de 1 bit para la conversión de estructura de lenguaje a XML.

Bit 8 (x'80') : indicador de múltiples segmentos Bit 7..1 : reservado para uso futuro.

Programa de utilidad de agregado del controlador del conversor PL/I

La suite de programas del controlador de conversor PL/I contiene un programa de utilidad que proporciona toda la información disponible conocida para el conversor. Además de la información que se puede obtener de los programas de utilidad de conversor de petición y respuesta, los identificadores de juego de caracteres codificado (CCSID) de la petición, también se incluyen páginas de códigos de host y de respuesta.

Nombre: Conversión de estructura de lenguaje a XML:[Prefijo de nombre de programa] + 'X'
Descripción:
  1. Obtener los requisitos de almacenamiento de la estructura de lenguaje y el mensaje XML.
  2. Obtiene el XML de petición, el XML de respuesta y la información de página de códigos.
Parámetros: Nombre: Tipo: Salida:
p_instruct_max_size Binario firmado de 4 bytes Longitud máxima en bytes del documento XML de respuesta
p_outstruct_max_size Binario firmado de 4 bytes Longitud máxima en bytes de la estructura de lenguaje de respuesta
p_outxml_max_size Binario firmado de 4 bytes Longitud máxima en bytes de un mensaje XML derivado de la estructura de lenguaje de respuesta
p_inbound_ccsid Binario firmado de 4 bytes Identificador de juego de caracteres codificado para XML de petición
p_host_ccsid Binario firmado de 4 bytes Identificador de juego de caracteres codificado para estructuras de lenguaje
p_outbound_ccsid Binario firmado de 4 bytes Identificador de juego de caracteres codificado para XML de respuesta

Mensaje WSED0325U emitido durante la generación de los conversores XML COBOL

La longitud de un documento XML se puede derivar de la estructura de datos de respuesta y es sensible al valor del nivel de compilador. Se aplica un límite de 16.777.210 bytes (~16MB) a COBOL V3R3 y anteriores. Se aplica un límite de 33.554.432 bytes (32MB) para COBOL V3R4 y posteriores.

Tal como se ha descrito previamente, la herramienta calcula el tamaño máximo del documento XML de respuesta. El conversor XML de respuesta está limitado respecto al tamaño máximo del documento XML que puede generar. El límite superior es de aproximadamente 16 megabytes, ya que es el tamaño del almacenamiento intermedio XML declarado en el conversor. La recepción del mensaje WSED0235U durante la generación indica que el conversor de respuesta no podrá guardar en el almacenamiento intermedio el documento XML de respuesta en el peor de los casos. Teniendo esto en cuenta, se para la generación para impedir la creación de un conversor XML de respuesta que pueda fallar durante el tiempo de ejecución. El límite superior de 16 megabytes está relacionado con el tamaño máximo histórico de un elemento de datos COBOL, aunque el máximo se haya relajado a 128 megabytes en el último release de Enterprise COBOL for z/OS.

Programa de direccionamiento de conversión de ejemplo COBOL que utiliza programas de utilidad

A continuación se muestra un ejemplo de un programa que utiliza los programas de utilidad para manejar la conversión de mensajes XML COBOL que fluyen dentro y fuera de los programas de empresa. El ejemplo no tiene estado, ya que no necesita mantener un registro de las estructuras de lenguaje asociadas con cada programa de empresa. En este ejemplo se supone que cada programa empresarial lee en una estructura de petición y graba en una estructura de respuesta.
*          *********************************************
*    *********************************************************
*  *************************************************************
* EJEMPLO DE PROGRAMA DE DIRECCIONAMIENTO DE CONVERSIÓN MEDIANTE PROGRAMAS DE UTILIDAD
*  *************************************************************
*    *********************************************************
*          *********************************************
 IDENTIFICATION DIVISION.
  PROGRAM-ID. 'UTILEXMP'.
 DATA DIVISION.
 WORKING-STORAGE SECTION.
 01 FEEDBACK-CODE.
 02 CONDITION-TOKEN-VALUE.
 88 CEE000 VALUE X'0000000000000000'.
 88 CEE0E7 VALUE X'000101C749C3C5C5'.
 03 SEVERITY PIC S9(4) BINARY.
 03 MSG-NO PIC S9(4) BINARY.
 03 CASE-SEV-CTL PIC X.
 03 FACILITY PIC XXX.
 02 I-S-INFO PIC S9(9) BINARY.
 LOCAL-STORAGE SECTION.
 01 INSTRUCT-MAX-SIZE PICTURE S9(9) BINARY.
 01 INSTRUCT-HEAP-ID PIC S9(9) BINARY.
 01 INSTRUCT-STG-ADDR POINTER.
 01 OUTSTRUCT-MAX-SIZE PICTURE S9(9) BINARY.
 01 OUTSTRUCT-HEAP-ID PIC S9(9) BINARY.
 01 OUTSTRUCT-STG-ADDR POINTER.
 01 OUTXML-MAX-SIZE PICTURE S9(9) BINARY.
 LINKAGE SECTION.
 01 WEB-SERVICE-INTERFACE.
 02 SERVICE-ID PIC X(16).
 02 XML-INT-LEN PIC S9(9) BINARY.
 02 XML-INT-TXT PIC X(32768).  
 01 INSTRUCT PIC X.
 01 OUTSTRUCT PIC X.
 PROCEDURE DIVISION USING WEB-SERVICE-INTERFACE.
 MAINLINE SECTION.
* -------------------------------------------------------------
* OBTENER TAMAÑO MÁXIMO DE ESTRUCTURA DE LENGUAJE DE ENTRADA
* ------------------------------------------------------------- 
     EVAULATE SERVICE-ID
        WHEN 'EXAMPLE1'
            CALL 'CONV1J' USING INSTRUCT-MAX-SIZE
        WHEN 'EXAMPLE2'
            CALL 'CONV2J' USING INSTRUCT-MAX-SIZE
     END-EVAULATE
    
* -------------------------------------------------------------
* ASIGNAR ÁREA DE ALMACENAMIENTO PARA ESTRUCTURA DE LENGUAJE DE ENTRADA
* Y ESTABLECER DIRECCIONABILIDAD
* ------------------------------------------------------------- 
     INITIALIZE INSTRUCT-HEAP-ID
     CALL 'CEEGTST' USING
        INSTRUCT-HEAP-ID INSTRUCT-MAX-SIZE
        INSTRUCT-STG-ADDR FEEDBACK-CODE
     IF NOT CEE000 OF FEEDBACK-CODE
        DISPLAY 'GET HEAP STORAGE FAILED!'
        STOP RUN
     ELSE
        SET ADDRESS OF INSTRUCT
         TO INSTRUCT-STG-ADDR
     END-IF

* -------------------------------------------------------------
* LLAMAR A CONVERSOR DE ENTRADA PASANDO ÁREA DE ALMACENAMIENTO Y DOCUMENTO XML
* ------------------------------------------------------------- 
     EVAULATE SERVICE-ID
        WHEN 'EXAMPLE1'
            CALL 'CONV1I' USING
                INSTRUCT XML-INT-LEN XML-INT-TXT OMITTED
            RETURNING CONVERTER-RETURN-CODE     
        WHEN 'EXAMPLE2'
            CALL 'CONV2I' USING
                INSTRUCT XML-INT-LEN XML-INT-TXT OMITTED
            RETURNING CONVERTER-RETURN-CODE     
     END-EVAULATE

* -------------------------------------------------------------
* OBTENER TAMAÑO MÁXIMO DE ESTRUCTURA DE LENGUAJE DE SALIDA
* ------------------------------------------------------------- 
     EVAULATE SERVICE-ID
        WHEN 'EXAMPLE1'
            CALL 'CONV1L' USING OUTSTRUCT-MAX-SIZE
        WHEN 'EXAMPLE2'
            CALL 'CONV2L' USING OUTSTRUCT-MAX-SIZE
     END-EVAULATE
    
* -------------------------------------------------------------
* ASIGNAR ÁREA DE ALMACENAMIENTO PARA ESTRUCTURA DE LENGUAJE DE SALIDA
* Y ESTABLECER DIRECCIONABILIDAD
* ------------------------------------------------------------- 
     INITIALIZE OUTSTRUCT-HEAP-ID
     CALL 'CEEGTST' USING 
        OUTSTRUCT-HEAP-ID OUTSTRUCT-MAX-SIZE
        OUTSTRUCT-STG-ADDR FEEDBACK-CODE
     IF NOT CEE000 OF FEEDBACK-CODE
        DISPLAY 'GET HEAP STORAGE FAILED!'
        STOP RUN
     ELSE
        SET ADDRESS OF OUTSTRUCT
         TO OUTSTRUCT-STG-ADDR
     END-IF
  
* -------------------------------------------------------------
* LLAMAR A PROGRAMA DE EMPRESA PASANDO ESTRUCTURA DE LENGUAJE DE ENTRADA
* ------------------------------------------------------------- 
     EVAULATE SERVICE-ID
        WHEN 'EXAMPLE1'
            CALL 'BUSPROG1' USING INSTRUCT OUTSTRUCT
        WHEN 'EXAMPLE2'
            CALL 'BUSPROG2' USING INSTRUCT OUTSTRUCT
     END-EVAULATE

* -------------------------------------------------------------
* ASEGURARSE DE QUE EL ALMACENAMIENTO INTERMEDIO XML ES SUFICIENTEMENTE
* GRANDE PARA DEVOLVER EL RESULTADO DEL DOCUMENTO XML
* ------------------------------------------------------------- 
     EVAULATE SERVICE-ID
        WHEN 'EXAMPLE1'
            CALL 'CONV1K' USING OUTXML-MAX-SIZE
        WHEN 'EXAMPLE2'
            CALL 'CONV2K' USING OUTXML-MAX-SIZE
     END-EVAULATE
     
     IF OUTXML-MAX-SIZE > LENGTH OF XML-INT-TXT
        DISPLAY 'OUTBOUND XML BUFFER TOO SMALL!'
        STOP RUN
     END-IF  

* -------------------------------------------------------------
* LLAMAR A CONVERSOR DE SALIDA PARA GENERAR DOCUMENTO XML DE RESPUESTA
* ------------------------------------------------------------- 
     EVAULATE SERVICE-ID
        WHEN 'EXAMPLE1'
            CALL 'CONV1O' USING
                OUTSTRUCT XML-INT-LEN XML-INT-TXT OMITTED
            RETURNING CONVERTER-RETURN-CODE     
        WHEN 'EXAMPLE2'
            CALL 'CONV2O' USING
                OUTSTRUCT XML-INT-LEN XML-INT-TXT OMITTED
            RETURNING CONVERTER-RETURN-CODE     
     END-EVAULATE
     
* -------------------------------------------------------------
* LIMPIAR Y DEVOLVER AL INTERLOCUTOR
* ------------------------------------------------------------- 
     CALL 'CEEFRST' USING INSTRUCT-STG-ADDR FEEDBACK-CODE
     IF NOT CEE000 OF FEEDBACK-CODE
        DISPLAY 'FREE INSTRUCT STORAGE AREA FAILED!'
        STOP RUN
     END-IF       
     CALL 'CEEFRST' USING OUTSTRUCT-STG-ADDR FEEDBACK-CODE
     IF NOT CEE000 OF FEEDBACK-CODE
        DISPLAY 'FREE OUTSTRUCT STORAGE AREA FAILED!'
        STOP RUN
     END-IF       

     GOBACK.       

 END PROGRAM 'UTILEXMP'. 

Limitaciones: los valores que devuelve el programa de utilidad pueden ser invalidados modificando manualmente el código generado.


Términos de uso | Comentarios

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