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.
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.
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.
| 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. | |
| 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 | |
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.
[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)
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: |
|
||
| 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. |
|
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: |
|
||
| 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 | |
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.
* *********************************************
* *********************************************************
* *************************************************************
* 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.