Converter runtime storage information utility programs

Edit online

The request XML and response XML converters provide utility programs for retrieving the sizes of the respective storage areas which must be provided when the converters are invoked.

There are three storage areas which the caller may need to allocate dynamically before invoking the converters. These areas are for storing the following structures:

Request language structure
Response language structure
Response XML document

Normally, users of Enterprise Service Tools (EST) need not be concerned with manually allocating these areas, since the generated converter driver handles the allocation of these areas in a runtime-appropriate way. If the converters are deployed into a custom runtime environment, the utility programs described here can be useful to a component which dynamically selects converters to call without having any knowledge of the language structure definitions on which an XML converter is based.

The IMS XML Adapter for IMS Connect is an example of a component which makes use of the utility programs. To remain stateless, the IMS XML Adapter relies on the utility programs to determine how much storage to allocate before invoking the converters.

Request XML and Response XML converter utility programs

The request XML and response XML converters consist of a suite of programs which work together to perform conversion. The following programs can be called before the main XML conversion program, to prepare the necessary storage areas or check boundary conditions. Note that the parameters passed to these programs are by reference and output only.

For COBOL XML converters, the following table can be used for reference:

Name:

XML to Language Structure Converter:[Program Name Prefix] + 'J'

Description:

Get the required length in bytes of the XML to language structure conversion language structure buffer

Parameters:

Name:	Type:	Output:
XML2LS-LANG-BUFFER-LENGTH	4 byte signed binary	Required length in bytes of the XML to language structure conversion buffer language structure buffer.
XML2LS-PROPERTIES	1 byte binary	8 1-bit Indicators for XML to language structure conversion. Bit 8 (x'80') : multisegment indicator Bit 7..1 : reserved for future use.

Name:

XML to Language Structure Converter:[Program Name Prefix] + 'L

Description:

Get the required length in bytes of the XML to language structure conversion language structure buffer.

Parameters:

Name:	Type:	Output:
LS2XML-LANG-BUFFER-LENGTH	4 byte signed binary	Required length in bytes of the language structure to XML language structure buffer.
LS2XML-PROPERTIES	1 byte binary	8 1-bit Indicators for language structure to XML conversion. Bit 8 (x'80'): multisegment indicator Bit 7..1 : reserved for future use.

Name:

XML to Language Structure Converter:[Program Name Prefix] + 'K'

Description:

Get the required length in bytes of the XML to language structure conversion XML buffer.

Parameters:

Name:	Type:	Output:
LS2XML-XML-BUFFER-LENGTH	4 byte signed binary	Required length in bytes of the language structure to XML conversion XML document buffer.

For PL/I XML converters, the following table can be used for reference:

Name:

XML to Language Structure Converter:[Program Name Prefix] + 'J'

Description:

Get request language structure storage requirements

Parameters

Name:	Type:	Output:
p_instruct_max_size	4 byte signed binary	Maximum length in bytes of the request language structure

Name:

XML to Language Structure Converter:[Program Name Prefix] + 'L

Description:

Get response language structure storage requirements

Parameters:

Name:	Type:	Output:
p_outstruct_max_size	4 byte signed binary	Maximum length in bytes of the response language structure

Name:

XML to Language Structure Converter:[Program Name Prefix] + 'K'

Description:

Get response XML document storage requirements

Parameters:

Name:	Type:	Output
p_outxml_max_size	4 byte signed binary	Maximum length in bytes of the response XML document

Maximum length in bytes of a language structure

The maximum length of a language structure uses the upper bound for all the variable length elementary and group items in the structure. This value represents how much storage would be occupied by the language structure in the worst case.

Maximum length in bytes of XML messages

Based on the language structure(s) and the generated or mapped XML schema, the tool computes the maximum number of bytes which could be occupied by a derived XML document. The computation takes several factors into account. They include:

Length of the XML element tag names.
Maximum number of character positions in each data item when convertered to display format.
Maximum number of bytes required to represent a character in each data item.
Maximum number of occurrences of each data item.
Expansion of the 5 predefined entities in XML (<,>,',",&); which are escaped to <, >, ', ", and &.
- For example, a PIC X(5) data item whose contents are a>b>c expand to a>b>c in the response XML document.
- Therefore, every non-numeric data item is assumed to have an expansion factor of 6, since the length of the longest entity is 6 characters (").
Maximum number occurrences of each language structure (IMS multisegment, bottom-up only).

The following shows in depth how the maximum number of bytes occupied by a data item is computed. Assume that:

The data item is declared as 05 OUT-ITEM PIC X/N/G(5) OCCURS 3.
The data item is mapped to the XML element tag name out-field. Therefore the start and end tags are <out-field> and <out-field/>.
When the response code page is UTF-16, 2 bytes are always required per character.

The maximum number of bytes is computed using the following formulas:

[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)

Thus, using the preceding formulas, there are two possible results for the max number of bytes needed to represent OUT-ITEM in an XML document:

For an SBCS response code page, the max is 69 + 90 = 159 bytes.
For UTF-16 response code page, the max is 138 + 180 = 318 bytes.

COBOL Converter driver aggregate utility program

The COBOL converter driver program suite contains a utility program which provides all the available information known to the converter. In addition to the information which can be learned from the request and response converter utility programs, the coded character set identifiers (CCSIDs) of the request XML, response XML, host, and code pages are also included.

The layout of IMS multisegment message layout is considered when computing the memory requirements for the language structure and XML buffers.

Name:

Language Structure to XML Conversion:[Program Name Prefix] + 'X'

Description:

Get language structure and XML document buffer storage requirements.
Get request XML, response XML, host, and code page information.

Parameters:

Name:	Type:	Output:
XML2LS-LANG-BUFFER-LENGTH	4 byte signed binary	Required length in bytes of the XML to language structure conversion buffer.
LS2XML-LANG-BUFFER-LENGTH	4 byte signed binary	Required length in bytes of the response language structure buffer.
LS2XML-XML-BUFFER-LENGTH	4 byte signed binary	Required length in bytes of the language structure ot XML conversion buffer.
XML2LS-XML-CCSID	4 byte signed binary	Coded CharacterSet IDentifier for XML to language structure conversion input.
HOST-LANG-CCSID	4 byte signed binary	Coded CharacterSet IDentifier for language structures.
LS2XML-XML-CCSID	4 byte signed binary	Coded CharacterSet IDentifier for language structure to XML conversion output.
XML2LS-PROPERTIES	1 byte binary	8 1-bit Indicators for XML to language structure conversion. Bit 8 (x'80') : multisegment indicator Bit 7..1 : reserved for future use.
LS2XML-PROPERTIES	1 byte binary	8 1-bit Indicators for language structure to XML conversion. Bit 8 (x'80'): multisegment indicator Bit 7..1 : reserved for future use.

PL/I Converter driver aggregate utility program

The PL/I converter driver program suite contains a utility program which provides all the available information known to the converter. In addition to the information which can be learned from the request and response converter utility programs, the coded character set identifiers (CCSIDs) of the request, host and response code pages are also included.

Name:

Language Structure to XML Conversion:[Program Name Prefix] + 'X'

Description:

Get language structure and XML message storage requirements.
Get request XML, response XML, host, and code page information.

Parameters:

Name:	Type:	Output:
p_instruct_max_size	4 byte signed binary	Maximum length in bytes of the response XML document
p_outstruct_max_size	4 byte signed binary	Maximum length in bytes of the response language structure
p_outxml_max_size	4 byte signed binary	Maximum length in bytes of an XML Message derived from the response language structure
p_inbound_ccsid	4 byte signed binary	Coded CharacterSet IDentifier for request XML
p_host_ccsid	4 byte signed binary	Coded CharacterSet IDentifier for language structures
p_outbound_ccsid	4 byte signed binary	Coded CharacterSet IDentifier for response XML

Message WSED0325U issued during generation of the COBOL XML Converters

The length of an XML document that can be derived from the response data structure and is sensitive to value of the compiler level. A limit of 16,777,210 bytes (~16MB) applies to COBOL V3R3 and earlier. A limit of 33,554,432 bytes (32MB) applies for COBOL V3R4 and later.

As described previously, the tool computes the maximum size of the response XML document. The response XML converter is bounded in regards to the maximum size of an XML document it can generate. The upper bound is approximately 16 megabytes, because that is the size of the XML buffer declared in the converter. Receipt of the message WSED0235U during generation indicates that the response converter would not be able to buffer the response XML document in the worst case. Taking this into account, generation is halted to prevent creation of an response XML converter which may fail at run time. The 16-megabyte upper bound is related to the historic maximum size of a COBOL data item, even though the maximum has been relaxed to 128-megabyte in the latest release of Enterprise COBOL for z/OS®.

COBOL Example conversion routing program using utilities

The following is an example of a program that uses the utility programs to handle conversion of COBOL XML messages flowing in and out of business programs. The example is stateless in that it doesn't need to keep record of the language structures associated with each business program. The assumption here is that every business program reads from an request structure and writes to an response structure.

*          *********************************************
*    *********************************************************
*  *************************************************************
*      EXAMPLE CONVERSION ROUTING PROGRAM USING UTILITIES
*  *************************************************************
*    *********************************************************
*          *********************************************
 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.
* -------------------------------------------------------------
* GET MAX SIZE OF INBOUND LANGUAGE STRUCTURE
* ------------------------------------------------------------- 
     EVAULATE SERVICE-ID
        WHEN 'EXAMPLE1'
            CALL 'CONV1J' USING INSTRUCT-MAX-SIZE
        WHEN 'EXAMPLE2'
            CALL 'CONV2J' USING INSTRUCT-MAX-SIZE
     END-EVAULATE
    
* -------------------------------------------------------------
* ALLOCATE STORAGE AREA FOR INBOUND LANGUAGE STRUCTURE
* AND ESTABLISH ADDRESSABILITY
* ------------------------------------------------------------- 
     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

* -------------------------------------------------------------
* CALL INBOUND CONVERTER PASSING STORAGE AREA AND XML DOCUMENT
* ------------------------------------------------------------- 
     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

* -------------------------------------------------------------
* GET MAX SIZE OF OUTBOUND LANGUAGE STRUCTURE
* ------------------------------------------------------------- 
     EVAULATE SERVICE-ID
        WHEN 'EXAMPLE1'
            CALL 'CONV1L' USING OUTSTRUCT-MAX-SIZE
        WHEN 'EXAMPLE2'
            CALL 'CONV2L' USING OUTSTRUCT-MAX-SIZE
     END-EVAULATE
    
* -------------------------------------------------------------
* ALLOCATE STORAGE AREA FOR OUTBOUND LANGUAGE STRUCTURE
* AND ESTABLISH ADDRESSABILITY
* ------------------------------------------------------------- 
     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
  
* -------------------------------------------------------------
* CALL BUSINESS PROGRAM PASSING INBOUND LANGUAGE STRUCTURE
* ------------------------------------------------------------- 
     EVAULATE SERVICE-ID
        WHEN 'EXAMPLE1'
            CALL 'BUSPROG1' USING INSTRUCT OUTSTRUCT
        WHEN 'EXAMPLE2'
            CALL 'BUSPROG2' USING INSTRUCT OUTSTRUCT
     END-EVAULATE

* -------------------------------------------------------------
* MAKE SURE OUTBOUND XML BUFFER IS LARGE ENOUGH TO RETURN
* XML DOCUMENT RESULT
* ------------------------------------------------------------- 
     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  

* -------------------------------------------------------------
* CALL OUTBOUND CONVERTER TO PRODUCE REPLY XML DOCUMENT
* ------------------------------------------------------------- 
     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
     
* -------------------------------------------------------------
* CLEAN UP AND RETURN TO CALLER
* ------------------------------------------------------------- 
     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'.

Limitations: The values that are returned by the utility programs can be invalidated by manual modification of the generated code.