Add JSON to COBOL Batch Without New Middleware

The problem: your COBOL batch job just received JSON

A long-running batch program reads a fixed-layout file, validates business rules, and updates a VSAM file or Db2 table. A downstream team now sends the same data as JSON text—perhaps from a web frontend or an API gateway—and the business does not want to deploy a Java, Python, or Node.js middleware layer just to translate the message.

The useful takeaway: recent releases of IBM Enterprise COBOL for z/OS include intrinsic JSON functions, so you can map JSON directly into existing COBOL group items and elementary items. You still have to check the runtime status after every call, size receiving fields generously, and confirm that your target compiler supports the syntax.

How JSON-PARSE and JSON-GENERATE map to COBOL data

JSON-PARSE takes a JSON text and a COBOL data item. JSON object members become COBOL group items, JSON arrays become COBOL tables, and JSON name/value pairs become COBOL elementary items. The match is by data name, so the COBOL copybook must use the same names as the JSON keys. JSON-GENERATE does the reverse: it serializes a COBOL group item into JSON text. The optional SUPPRESS phrase can leave out elementary items that contain their initial or zero value, which keeps outbound payloads smaller.

Two runtime values report success or failure: JSON-CODE and JSON-STATUS. A zero JSON-CODE generally means the operation completed, but it is not a substitute for schema validation. A type mismatch can produce a default value instead of an error, and a JSON field with no matching COBOL item is silently ignored.

Worked example: parse an inbound order

The following structure is illustrative. Exact clauses, library names, and whether the feature is invoked as a function or a statement depend on your compiler release, so verify against the Enterprise COBOL programming guide before copying it into production.

       IDENTIFICATION DIVISION.
       PROGRAM-ID. ORDERIN.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       COPY ORDER-COPYBOOK.
       01  JSON-TEXT   PIC X(2000).
       01  PARSE-STAT  PIC S9(9) COMP.
       01  PARSE-STAT2 PIC S9(9) COMP.
       ...
       PROCEDURE DIVISION.
       MOVE inbound-record TO JSON-TEXT.
       *> Schematic: confirm exact syntax for your compiler release
       COMPUTE PARSE-STAT = FUNCTION JSON-PARSE(JSON-TEXT ORDER-RECORD)
       IF PARSE-STAT NOT EQUAL ZERO
           DISPLAY 'JSON-PARSE failed: ' PARSE-STAT
           MOVE 8 TO RETURN-CODE
           GOBACK
       END-IF.
       DISPLAY ORDER-CUSTOMER-ID ORDER-AMOUNT.

Where to run: compile in z/OS batch JCL or from z/OS UNIX System Services using your site's COBOL cataloged procedure. Required access: read authority to the copybook PDSE and update authority to the target program library. Meaningful placeholders: replace ORDER-COPYBOOK with your actual copybook, and JSON-TEXT with the field that holds the incoming JSON. Expected checks: compile return code 0 with no severity-12 errors; at runtime, PARSE-STAT is zero before the program touches ORDER-RECORD. Risks: if JSON-TEXT is shorter than the incoming document, the parse can fail or truncate; if a JSON key uses different casing than the COBOL data name, that field is ignored without an error.

Generate outbound JSON from an existing record

       COMPUTE GEN-STAT = FUNCTION JSON-GENERATE(ORDER-RECORD JSON-OUTPUT)
       IF GEN-STAT NOT EQUAL ZERO
           DISPLAY 'JSON-GENERATE failed: ' GEN-STAT
       ELSE
           DISPLAY JSON-OUTPUT
       END-IF.

Use SUPPRESS on elementary items that should be omitted when they hold default values. Remember that fixed-length COBOL records can truncate long arrays or strings unless the receiving item is sized generously or you use variable-length data.

Limitations and how to verify

• Name matching is exact and case-sensitive. A JSON field with no matching COBOL item is ignored, which can hide data loss.
• JSON-CODE indicates success or failure but does not replace schema validation.
• This feature is not part of ANSI COBOL 85 and may not exist in GnuCOBOL or older Micro Focus dialects.
• Syntax differs between IBM Enterprise COBOL, Micro Focus, and GnuCOBOL; code written for one compiler may not compile on another.

Practical check: build a minimal program that parses a known JSON document, DISPLAYs the resulting elementary items, then generates JSON back and compares the output to the expected text. Next, feed intentionally malformed JSON—such as a missing closing brace—to JSON-PARSE and confirm the program takes the error path before any file update runs. If JSON-CODE stays zero on bad input, your error handling is wrong, not the data.

Closing decision

Use intrinsic JSON handling when your compiler supports it, the payload fits your record layout, and you want to keep business rules inside COBOL. Introduce a separate transformation layer only when the JSON structure changes independently of the COBOL copybook, when payloads exceed fixed-record limits, or when your compiler lacks the functions. Either way, treat JSON-CODE as a required checkpoint, not an optional detail.