Creating an XML Handler using a COBOL data structure


   This tutorial will help you to understand:

 

 

1.        Launch XML Thunder.

2.        The welcome screen will appear and give you two different options, one to Create a New XML Handler  and one to Open existing handlers.  (If you disabled the welcome screen, please click  toolbar or choose XML Handler -> New from main menu.). For now, click the first option.





3.        If the wizard starts with the Begin panel, click Next.





4.        On the Source panel, choose COBOL data structure from the list, click Next.

 

5.        On the next panel, type in the path to the tutorial COBOL copybook example BNKREC.cpy or click  to locate it. Click Next.



 

6.        On the Copybook Format, choose Fixed Format click Next

 

 

7.        On the Names panel you should see the following screen. Leave the names unchanged. Click Next.




8.    On the XML panel choose Yes, if not already selected. Click Next.





9.    On the Finish panel, review the information and click Finish.





10.     After few moments, the XML Handler design window will be displayed. Each IDS group has become an XML element and each IDS field has become an attribute.





11.     We need to modify the new handler a bit before code generation. First, we will set the XML buffer size. Click XML Handler – Properties, switch to General pane and type 32000 in Buffer Size entry field. Click OK.





12.     Next, we will get rid of extra attributes on the XML side that we do not need and use the mapped fields for other purposes. On XML Handler - Edit Pane, select these nodes and click Delete . This action should release corresponding mapped IDS data field for each attribute.

attribute Bank-Counter

attribute Account-Counter

attribute Account-Address-Flag

attribute Account-Comment-Flag

attribute Account-Comment-Len



13.     Now we will assign repeating element counters. Select Bank-Counter field on IDS list and select BANK {0:10} repeating element on Edit pane. Click Map Count .





14.     Then, select Bank > Account-Counter field on IDS list and select ACCOUNT {0:40} repeating element on Edit pane. Click Map Count .





15.     Next, we will assign flag fields for optional elements. Select ACCOUNT-Address-Flag on IDS list and select ACCOUNT-Address on Edit pane. Click Map Count . Then, select ACCOUNT-Comment-Flag on IDS list and select ACCOUNT-Comment attribute on Edit pane. Click Map Count .



16.     Make Account-Comment attribute a variable length text by double-clicking ACCOUNT-Comment data node on Edit pane and setting variable length check-box on. Click OK. Then, select ACCOUNT-Comment attribute on Edit pane and select ACCOUNT-Comment-Len field on IDS list and click Map Length .



17.     The Logical IDS pane should display:





18.     The Edit pane should display:




19.     Click Generate or select Tools -> Generate… from the main menu.


20.     On the Generation dialog, adjust settings to generate a Writer, set the Program ID/Source Name to BNKRECW, set the destination folder, check the Generate IDS option, set its Source Name to BNKRECWC and click Generate .





21.     Upon normal completion, adjust settings to generate a Reader, set the Program ID/Source Name to BNKRECR, change the IDS Source Name to BNKRECRC option and click Generate .



22.     At the destination folder, you should now have BNKRECW.cbl, BNKRECR.cbl, BNKRECWC.cpy and BNKRECRC.cpy files, the XML Writer, Reader, Writer IDS and Reader IDS respectively. Main test programs BNKRECW_test.cbl and BNKRECR_test.cbl (located at Installation Folder/TutorTX/Main Test Programs) copy BNKRECWC and BNKRECRC copybooks and call BNKRECW and BNKRECR to demonstrate how an XML Writer and Reader can be used within a COBOL main program.



23.     Copy the following files to a temp folder:

BNKRECW_test.cbl
BNKRECR_test.cbl
BNKRECW.cbl
BNKRECR.cbl
BNKRECWC.cpy
BNKRECRC.cpy



24.     Launch your favorite COBOL IDE, load these files, compile them and run BNKRECW_test. It should produce BNKREC.xml. Now let’s analyze the most important sections of the BNKRECW_test.cbl program.





25.     The generated XML File will look like that:





26.    

       (...)

       ENVIRONMENT DIVISION.

       INPUT-OUTPUT SECTION.

       FILE-CONTROL.

 

              SELECT XML-FILE

                      ASSIGN TO WS-XML-FILE-NAME

                      ORGANIZATION IS SEQUENTIAL

                      FILE STATUS IS WS-FILE-STATUS.

 

       DATA DIVISION.

       FILE SECTION.

 

       FD  XML-FILE

           RECORD CONTAINS 1000 CHARACTERS.

 

       01  XML-FILE-REC.

           05  FILLER   PIC  X(1000).

 

       (...)

 

       WORKING-STORAGE SECTION.

 

       01  WS-DATA-FILE-NAME PIC X(100).

       01  WS-XML-FILE-NAME PIC X(100) VALUE "BNKREC.XML".

 

       01  WS-XML-BUFFER-MAX   PIC 9(9) VALUE 32000.

       01  WS-XML-FILE-RECSIZE PIC 9(9) VALUE 1000.

 

       01  WS-FILE-STATUS PIC X(2).

 

      *

      * XML Thunder generated copybook for XML Reader & Writer

      *

       COPY BNKRECRC.

 

       (...)

 

       PROCEDURE DIVISION.

       TESTMAIN-MAIN.

      *

      * Initialize program data structures

      *

           INITIALIZE XD-BANKS

           INITIALIZE CANAM-XML-BUFFER

           INITIALIZE CANAM-XML-STATUS

      *

      * Read XML text from the same file

      *

           MOVE "BNKREC.XML" TO WS-XML-FILE-NAME

           DISPLAY "Reading XML document from " WS-XML-FILE-NAME

 

           OPEN INPUT XML-FILE

           PERFORM VARYING WS-OUTLEN FROM 1 BY WS-XML-FILE-RECSIZE

             UNTIL WS-OUTLEN > WS-XML-BUFFER-MAX

                OR WS-FILE-STATUS NOT = "00"

             MOVE SPACES TO XML-FILE-REC

             READ XML-FILE

               AT END MOVE "99" TO WS-FILE-STATUS

             END-READ

             MOVE XML-FILE-REC

               TO XML-BUFFER(WS-OUTLEN: WS-XML-FILE-RECSIZE)

           END-PERFORM

           CLOSE XML-FILE

      *

      * Call XML Reader

      *

           CALL "BNKRECR" USING

                XD-BANKS CANAM-XML-BUFFER CANAM-XML-STATUS.

      *

      * Display XML Writer status

      *

           DISPLAY "Reader status"

           DISPLAY "CODE=" XML-RETURN-CODE.

           DISPLAY "MESSAGE=" XML-MESSAGE.

           DISPLAY "POSITION=" XML-POSITION.

           DISPLAY "SOURCE=" XML-SOURCE.

 

       (...)

 

       STOP RUN.

      *

      * Copyright Canam Software Labs, Inc.

      *
 
Run BNKRECW_test.cbl. It will read back the XML file. Let's take a look at the main section of this program.