Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 38 ยท Modern COBOL and Mainframes

JSON, XML and Object-Oriented COBOL

Learn modern COBOL features that connect old systems to new ones - JSON GENERATE and JSON PARSE, XML GENERATE and XML PARSE, calling web services and the object-oriented extensions CLASS-ID, METHOD-ID and INVOKE.

COBOL records are fixed-width bytes: position 1 to 8 is an account number, position 9 to 33 a name. Today's services speak JSON and XML, where data has names, nesting and variable length. For a mainframe application to take part in a web or mobile world it must convert between the two. The 2002 COBOL standard and later vendor releases added statements for exactly this, plus an object-oriented model. This lesson covers both and ends with a practical view of how COBOL actually meets web services.

Support differs between compilers. IBM Enterprise COBOL 6.x has the full JSON and XML statements; GnuCOBOL 3.2 supports parts of them; the object-oriented extensions are in IBM and Micro Focus products but not in GnuCOBOL. Check your compiler's manual before relying on a clause.

JSON GENERATE

JSON GENERATE turns a COBOL data item (usually a group) into JSON text. Take this structure:

COBOL
       01  CUSTOMER.
           05  CUST-ID       PIC 9(5).
           05  CUST-NAME     PIC X(10).
           05  CUST-ACTIVE   PIC X.
           05  CUST-ORDERS   OCCURS 2 TIMES.
               10  ORDER-NO  PIC 9(4).
               10  ORDER-AMT PIC 9(4)V99.
       01  JSON-OUT          PIC X(400).
       01  JSON-LEN          PIC 9(4) COMP.
COBOL
           JSON GENERATE JSON-OUT FROM CUSTOMER
               COUNT IN JSON-LEN
               NAME OF CUST-ID IS 'id'
                       CUST-NAME IS 'name'
               ON EXCEPTION
                   DISPLAY "JSON error " JSON-CODE
               NOT ON EXCEPTION
                   DISPLAY JSON-OUT (1:JSON-LEN)
           END-JSON

Typical rules:

  • Group items become objects, elementary items become members, OCCURS tables become arrays.
  • Numeric items are written as JSON numbers with the decimal point restored from the V in the PICTURE (PIC 9(4)V99 with 12.50 becomes 12.5, format details vary by compiler). Alphanumeric items become strings; trailing spaces are normally trimmed in text.
  • COUNT IN gives the number of characters produced, which you need to cut the output buffer.
  • NAME OF ... IS renames members; otherwise the COBOL data names are used. OMITTED or SUPPRESS ... WHEN leave out items, for instance empty values or FILLER.
  • ON EXCEPTION runs on errors such as a too-small output field; JSON-CODE holds the reason.

The output looks like {"id":42,"name":"Ada","orders":[{"ORDER-NO":1001,"ORDER-AMT":12.5},...]} (names and exact spelling depend on the compiler and your NAME OF).

JSON PARSE

JSON PARSE does the opposite: it reads JSON text and moves its values into matching COBOL items by name:

COBOL
           JSON PARSE JSON-IN INTO CUSTOMER
               WITH DETAIL
               NAME OF CUST-ID IS 'id'
               ON EXCEPTION
                   DISPLAY "Bad JSON, code " JSON-CODE
               NOT ON EXCEPTION
                   DISPLAY "Parsed customer " CUST-ID
           END-JSON

Members that have no matching COBOL item are ignored. Missing members leave the COBOL item unchanged, so initialize first. A value that cannot fit (a string longer than the field, a number too large for the PICTURE) raises an exception. WITH DETAIL selects detailed validation. For free-form JSON you can parse through a processing procedure style (supported in XML; JSON offers it in some compilers) or write a small scanner with UNSTRING.

flowchart LR
    R["COBOL record<br/>fixed-width bytes"] -->|"JSON GENERATE"| J["JSON text"]
    J -->|"HTTP"| W["Web / mobile client"]
    W -->|"HTTP"| J2["JSON text"]
    J2 -->|"JSON PARSE"| R2["COBOL record"]

JSON statements are the bridge between byte-oriented records and web formats.

XML GENERATE and XML PARSE

XML works similarly, with a few extras:

COBOL
           XML GENERATE XML-OUT FROM CUSTOMER
               COUNT IN XML-LEN
               WITH ENCODING 1208
               ON EXCEPTION
                   DISPLAY "XML error " XML-CODE
           END-XML

XML GENERATE produces elements named by data names (<CUSTOMER><CUST-ID>00042</CUST-ID>...). Phrases such as WITH ATTRIBUTES, NAMESPACE, TYPE OF ... IS ATTRIBUTE and WITH XML-DECLARATION control the shape. Encoding 1208 is UTF-8.

XML PARSE is event driven like a SAX parser: you give a processing procedure that the parser calls for every event (start of element, content characters, end of element). Special registers carry the information: XML-EVENT (the event name), XML-TEXT (current element or content text) and XML-CODE.

COBOL
           XML PARSE XML-IN
               PROCESSING PROCEDURE HANDLE-XML
               ON EXCEPTION DISPLAY "XML error " XML-CODE
           END-XML
       ...
       HANDLE-XML.
           EVALUATE XML-EVENT
               WHEN "START-OF-ELEMENT"
                   MOVE XML-TEXT TO CURRENT-TAG
               WHEN "CONTENT-CHARACTERS"
                   IF CURRENT-TAG = "CUST-ID"
                       MOVE XML-TEXT TO WS-ID
                   END-IF
           END-EVALUATE.

Because XML processing is handled outside your program logic, validate the incoming data (length, numeric content) before you use it in arithmetic or file keys, as discussed in file status and error handling.

Practical integration

Most teams do not make raw HTTP calls from COBOL. Common patterns:

  • CICS web services: a program becomes a service through CICS pipeline configuration (the translator maps a COBOL structure to JSON via a "language structure"); the program sees only its DFHCOMMAREA or channel containers (CICS).
  • z/OS Connect: a gateway that exposes CICS or Db2 programs as REST APIs, converting JSON to your COBOL copybook layout.
  • Message queues (IBM MQ): the program reads and writes message bodies, perhaps JSON built with JSON GENERATE.
  • Calling C or Java: through CALL with BY VALUE, or Java interoperability on IBM platforms.

The lesson of all these: keep a clean boundary. Convert JSON/XML at the edge and keep the business logic working on plain COBOL records.

Object-oriented COBOL

COBOL 2002 added classes, objects and methods. The syntax is verbose, but the ideas are familiar:

COBOL
       CLASS-ID. Account INHERITS Base.
       ENVIRONMENT DIVISION.
       CONFIGURATION SECTION.
       REPOSITORY.
           CLASS Base AS "java.lang.Object"
           CLASS Account AS "Account".
       OBJECT.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  balance   PIC S9(9)V99 COMP-3 VALUE 0.
       PROCEDURE DIVISION.
       METHOD-ID. deposit.
       DATA DIVISION.
       LINKAGE SECTION.
       01  amt       PIC S9(9)V99 COMP-3.
       PROCEDURE DIVISION USING BY VALUE amt.
           ADD amt TO balance.
       END METHOD deposit.
       END OBJECT.
       END CLASS Account.
  • CLASS-ID starts a class; INHERITS names the parent. The OBJECT paragraph holds instance data and methods; FACTORY holds class-level (static) ones.
  • METHOD-ID defines a method with a PROCEDURE DIVISION USING ... RETURNING ....
  • Callers use INVOKE acct "deposit" USING 100.00 or the inline form acct::deposit(100.00) (varies), after INVOKE Account "NEW" RETURNING acct. Object references are declared USAGE OBJECT REFERENCE.
  • IBM's implementation targets interoperation with Java classes; Micro Focus supports .NET and JVM versions.

OO COBOL is rare in legacy code, and many shops stick with procedural programs, subprograms and copybooks as their unit of reuse. If you meet it, you will recognize the vocabulary from Java or C#.

Modelling the conversion

Fixed-width to JSON and back is easy to show in Python. These blocks are stand-ins: they implement by hand the conversions that JSON GENERATE and JSON PARSE do for you.

Python Stand-in: JSON GENERATE for a fixed-width record with a table

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: JSON PARSE into fixed-width fields with size checks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The first block prints the compact JSON object for the customer, with orders containing amounts 12.5 and 5.0 ({"id":42,"name":"Ada Love","active":true,"orders":[{"orderNo":1001,"amount":12.5},{"orderNo":1002,"amount":5.0}]}). The second prints the fixed-width record 00042Ada and then the two errors, as an ON EXCEPTION branch would.

Common mistakes

  1. Output field too small for generated text: an exception, or a cut-off message if you ignore COUNT IN.
  2. Using DISPLAY JSON-OUT instead of JSON-OUT (1:JSON-LEN): you print trailing spaces too.
  3. Not initializing the target of JSON PARSE, so missing members keep old values.
  4. Assuming the data names are good JSON member names; rename with NAME OF.
  5. Doing business arithmetic on values straight out of a parse without validating them.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does JSON GENERATE do?

    GENERATE writes JSON from COBOL data; PARSE reads JSON into COBOL data.
  2. 2. How does XML PARSE hand data to your program?

    XML PARSE is event driven; XML-EVENT, XML-TEXT and XML-CODE describe each event.
  3. 3. Which clause gives the number of characters produced by JSON GENERATE?

    COUNT IN stores the length so you can use reference modification on the output buffer.
  4. 4. What does INVOKE do in object-oriented COBOL?

    INVOKE object "method" USING ... runs a method, much like CALL for programs.

Summary

  • JSON GENERATE/JSON PARSE and XML GENERATE/XML PARSE convert between COBOL records and web formats.
  • Use NAME OF, COUNT IN and ON EXCEPTION; validate and initialize data around a parse.
  • Real integrations usually go through CICS web services, z/OS Connect or message queues, keeping COBOL logic on plain records.
  • Object-oriented COBOL (CLASS-ID, METHOD-ID, INVOKE) exists but is uncommon; support depends on the compiler.

Next: GnuCOBOL and modernization