APIs, JSON and the Outside World

For decades, COBOL systems communicated using fixed-width flat files and EBCDIC character sets. Today, they need to communicate with microservices, web browsers, and mobile applications. The lingua franca of modern communication is JSON (JavaScript Object Notation).

Rather than forcing developers to write complex C wrappers or Java bridge layers, modern COBOL compilers introduced native support for parsing and generating JSON payloads. In this lesson, we will explore the JSON GENERATE statement, a powerful tool for serializing COBOL data structures directly into web-ready JSON strings.

To see why COUNT IN is important, predict what happens to the fixed-length PIC X(50) receiving string after the JSON is generated. We will append a <END> marker to reveal any invisible characters:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. PRED-JSON.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 EMP-REC.
          05 EMP-NAME PIC X(10) VALUE "ALICE".
       01 JSON-OUTPUT PIC X(50).
       PROCEDURE DIVISION.
           JSON GENERATE JSON-OUTPUT FROM EMP-REC.
           DISPLAY JSON-OUTPUT "<END>".
           STOP RUN.

{"EMP-REC":{"EMP-NAME":"ALICE"}}                  <END>

While JSON GENERATE smartly trims trailing spaces from individual values (like “ALICE”), the target JSON-OUTPUT variable is still a fixed-length COBOL string. This means the resulting JSON payload is padded with spaces up to its 50-byte length! If we send this over a network, we waste bandwidth and risk confusing strict JSON parsers.

Generating Basic JSON

The JSON GENERATE statement takes a source COBOL data item (usually a Group Item) and serializes it into a receiving string.

Here is a basic example converting an employee record into JSON. Notice the output has trailing spaces because the receiving PIC X(100) variable is fixed-length!

       IDENTIFICATION DIVISION.
       PROGRAM-ID. JSON-GEN.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 EMP-REC.
          05 EMP-ID   PIC 9(4) VALUE 1234.
          05 EMP-NAME PIC X(10) VALUE "ALICE".
       01 JSON-OUTPUT PIC X(100).
       PROCEDURE DIVISION.
           JSON GENERATE JSON-OUTPUT FROM EMP-REC.
           DISPLAY JSON-OUTPUT.
           STOP RUN.

{"EMP-REC":{"EMP-ID":1234,"EMP-NAME":"ALICE"}}                                                      

Trimming the Output with COUNT IN

Because COBOL strings are fixed-length, sending JSON-OUTPUT directly over a network would transmit 90 bytes of empty space. The COUNT IN phrase solves this by storing the exact length of the generated JSON into a variable. You can then use reference modification (1:JSON-LEN) to extract exactly what you need.

       IDENTIFICATION DIVISION.
       PROGRAM-ID. JSON-CNT.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 EMP-REC.
          05 EMP-ID   PIC 9(4) VALUE 1234.
          05 EMP-NAME PIC X(10) VALUE "ALICE".
       01 JSON-OUTPUT PIC X(100).
       01 JSON-LEN    PIC 9(4).
       PROCEDURE DIVISION.
           JSON GENERATE JSON-OUTPUT FROM EMP-REC COUNT IN JSON-LEN.
           DISPLAY JSON-OUTPUT(1:JSON-LEN).
           STOP RUN.

{"EMP-REC":{"EMP-ID":1234,"EMP-NAME":"ALICE"}}

Exception Handling and Suppressing Fields

What if your receiving field isn’t large enough? JSON GENERATE will trigger an exception condition. You can handle this gracefully with the ON EXCEPTION phrase.

Additionally, you don’t always want to send every piece of data inside a record over an API. The SUPPRESS phrase allows you to exclude specific fields (like sensitive security data) from the generated JSON payload.

       IDENTIFICATION DIVISION.
       PROGRAM-ID. JSON-SUP.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 EMP-REC.
          05 EMP-ID   PIC 9(4) VALUE 1234.
          05 EMP-SSN  PIC X(9) VALUE "SECRET".
       01 JSON-OUT PIC X(100).
       01 JSON-LEN PIC 9(4).
       PROCEDURE DIVISION.
           JSON GENERATE JSON-OUT FROM EMP-REC COUNT IN JSON-LEN
             SUPPRESS EMP-SSN
           END-JSON.
           DISPLAY JSON-OUT(1:JSON-LEN).
           STOP RUN.

{"EMP-REC":{"EMP-ID":1234}}

A Note on OCCURS and JSON PARSE

While JSON GENERATE creates JSON, the JSON PARSE statement does the reverse: turning JSON into COBOL data structures. While this is fully implemented in IBM Enterprise COBOL, in GnuCOBOL 3.x, JSON PARSE is currently a syntax stub. It will compile (with a -Wpending warning) but silently skip parsing at runtime!

Another current limitation in GnuCOBOL 3.x is that JSON GENERATE does not fully support OCCURS arrays yet; it will typically emit only the first element of the array and issue a -Wpending compile warning.

For now, rely on JSON GENERATE for flat COBOL-to-API needs, and use specialized libraries or preprocessors if you need to ingest JSON or serialize complex arrays in GnuCOBOL.