Structure of the XML message

An XML schema defines the XML tags that correspond to the COBOL data structures used by the COBOL IMS application program. The XML schema used for XML conversion is based on the COBOL copybook of the COBOL IMS application program.

The XML schema is not required by IMS Connect, but the application programmer that develops the web service that generates the XML input messages needs it.

If you use IBM® Developer for System z® to automatically generate the XML converters from the COBOL copybook of the IMS application program, IBM Developer for System z also generates the XML schema for you.

The XML tags defined by the XML schema directly correspond to the fields of the COBOL data structure.

The following is an example of an input and output message data structure defined in the COBOL copybook of the sample phone book application program that is available at the IMS Enterprise Suite SOAP Gateway download site through www.ibm.com/software/data/ims/soap/.

        01  INPUT-MSG.
            02  IN-LL        PICTURE S9(3) COMP.
            02  IN-ZZ        PICTURE S9(3) COMP.
            02  IN-TRCD      PICTURE X(10).
            02  IN-CMD       PICTURE X(8).
            02  IN-NAME1     PICTURE X(10).
            02  IN-NAME2     PICTURE X(10).
            02  IN-EXTN      PICTURE X(10).
            02  IN-ZIP       PICTURE X(7).

        01  OUTPUT-MSG.
            02  OUT-LL       PICTURE S9(3) COMP.
            02  OUT-ZZ       PICTURE S9(3) COMP.
            02  OUT-MSG      PICTURE X(40).
            02  OUT-CMD      PICTURE X(8). 
            02  OUT-NAME1    PICTURE X(10).
            02  OUT-NAME2    PICTURE X(10).
            02  OUT-EXTN     PICTURE X(10).
            02  OUT-ZIP      PICTURE X(7). 
            02  OUT-SEGNO    PICTURE X(4)

Each field in the copybook has an equivalent XML tag that represents the field in the XML message. XML tags are case-sensitive. The dash symbol ‘-' in field names in the copybook is represented as an underscore ‘_' in the corresponding XML tags. The SOAP Gateway client has to build the XML message using that XML schema.

For example, the IN-TRCD field from the above copybook is represented in XML by the opening and closing tags <in_trcd> and </in_trcd>. In the data structure input message, the value of IN-TRCD should be placed in the byte positions 5 to 14. In the XML input message, the same value of IN-TRCD should be placed between the tags <in_trcd> and </in_trcd>.

An input messages from an IMS Connect client that uses the above example COBOL copybook of the phone book application has the following XML tags for the equivalent COBOL data structure fields:

<INPUTMSG>
<in_ll> </in_ll>
<in_zz> </in_zz>
<in_trcd> </in_trcd>
<in_cmd> </in_cmd>
<in_name1> </in_name1>
<in_name2> </in_name2>
<in_extn> </in_extn>
<in_zip> </in_zip>
</INPUTMSG>

The above COBOL copybook of the phone book application has the following XML tags for the equivalent outbound COBOL data structure fields:

<cbl:OUTPUTMSG>
<out_ll> </out_ll>
<out_zz> </out_zz>
<out_msg> </out_msg>
<out_cmd> </out_cmd>
<out_name1> </out_name1>
<out_name2> </out_name2>
<out_extn> </out_extn>
<out_zip> </out_zip>
<out_segno> </out_segno>
</cbl:OUTPUTMSG>

The input message XML tags must be wrapped by opening and closing XML tags based on the 01 INPUT-MSG. definition in the COBOL copybook. In the above example, the opening and closing tags are <INPUTMSG> and </INPUTMSG>.

The output message XML tags generated by the outbound converter are wrapped by opening and closing XML tags that correspond to the 01 OUTPUT-MSG. definition. In the above example, the opening and closing tags are <cbl:OUTPUTMSG> and </cbl:OUTPUTMSG>.

Look at the XML schemas to determine what these tags should be for each XML converter.

For each XML message, not all tags have to be specified, just like not all fields are required in the data structure message. The required fields are determined by the COBOL application.