JSON GENERATE
A COBOL record and a JSON document hold the same things and look nothing alike: a record is fixed bytes and a document is names and text. JSON GENERATE writes the second from the first, and it is the half of the JSON support of this compiler that works.
JSON GENERATE
The statement takes the record, the field that receives the text and a counter for the length of what it wrote:
IDENTIFICATION DIVISION.
PROGRAM-ID. J1.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 CUS-REC.
05 CUS-ID PIC 9(3).
05 CUS-NAME PIC X(10).
05 CUS-BAL PIC 9(5).
01 JSON-OUT PIC X(200).
01 JSON-LEN PIC 9(3).
PROCEDURE DIVISION.
MOVE 42 TO CUS-ID.
MOVE "Ada" TO CUS-NAME.
MOVE 1250 TO CUS-BAL.
JSON GENERATE JSON-OUT FROM CUS-REC COUNT JSON-LEN
DISPLAY "[" JSON-OUT(1:JSON-LEN) "]".
DISPLAY "length " JSON-LEN.
STOP RUN.
cobc -x -free -Wall -o j1 j1.cob
./j1
[{"CUS-REC":{"CUS-ID":42,"CUS-NAME":"Ada","CUS-BAL":1250}}]
length 057
The record is the outer object and the field names are the inner names, in the order of the data division. The name came out as Ada and not as ten characters with spaces, because the generator trims an alphanumeric field, and the identifier 42 lost the leading zero of its three digits, because the field is numeric and a JSON number has no leading zeros.
The counter said 57 and the document is 57 characters between the brackets. A program that writes the text to a file uses JSON-OUT(1:JSON-LEN), which is the whole reason the clause exists.
Numbers, decimals and strings
A packed decimal keeps its point and its sign, and an alphanumeric field becomes a quoted string:
IDENTIFICATION DIVISION.
PROGRAM-ID. J3.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 INV-REC.
05 INV-ID PIC X(4).
05 INV-AMOUNT PIC 9(5)V99 COMP-3.
05 INV-RATE PIC S9(3)V99 COMP-3.
01 JSON-OUT PIC X(300).
01 JSON-LEN PIC 9(3).
PROCEDURE DIVISION.
MOVE "A100" TO INV-ID.
MOVE 1250.75 TO INV-AMOUNT.
MOVE -12.50 TO INV-RATE.
JSON GENERATE JSON-OUT FROM INV-REC COUNT JSON-LEN
DISPLAY JSON-OUT(1:JSON-LEN).
STOP RUN.
cobc -x -free -Wall -o j3 j3.cob
./j3
{"INV-REC":{"INV-ID":"A100","INV-AMOUNT":1250.75,"INV-RATE":-12.50}}
The amount is 1250.75 as a JSON number, which is what a consumer with a decimal parser expects, and the rate keeps its minus sign and its two decimals as -12.50. Nothing about the packed format of the fields reached the document: the generator read the decimal value and wrote it as text, which is the one place in this course where a COMP-3 field crosses to the outside world without losing anything.
The COUNT and the field
Two fields belong to every JSON GENERATE: the receiving text and the COUNT of what went into it. The receiving field is fixed and the document is not, so a program has three things to decide:
- The field long enough for the largest record the program will generate. A field that is too short is a truncated document and no error.
- The count is the length to write or print, and it is the only way to know where the document ends inside the field.
- The code page is the one of the run, and a name with a character outside ASCII is written as that byte. The lesson on ASCII, EBCDIC and UTF-8 is the reason a document of non-ASCII names is worth a test of its own.
WITHIN, which does not build
The standard has a WITHIN clause that writes the inner object without the name of the record around it, which is what a caller that already has the field names wants. This compiler does not parse it:
cobc -x -free -Wall -o jw j2.cob
j2.cob:21: error: syntax error, unexpected Identifier
19 | MOVE 1250 TO CUS-BAL.
20 | JSON GENERATE JSON-OUT FROM CUS-REC COUNT JSON-LEN
21 > WITHIN CUS-REC
22 | DISPLAY "flat " JSON-OUT(1:JSON-LEN).
23 | MOVE "apple" TO ITEM-NAME(1).
The parser reaches the word and stops, so the clause is not in this build at all. A program that needs a flat object writes it with STRING and the field names, which is the same paragraph that writes an XML list, or it accepts the wrapper.
The reading direction is the next lesson, and it is the one that does not work: JSON PARSE builds and does nothing, so the page after this one is a hand-written parser.
Exercises
- Add a field of PIC X(6) to the record and print the document again. Where does its value appear?
- Give the amount of the second program a value with one decimal and read the document.
- Make the receiving field of the first program ten bytes long and print the count next to the text.
- Move a name with a quote in it into CUS-NAME and read the document.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does JSON GENERATE write for a group item?
Answer
An object named after the group, holding its fields
The record became the outer object CUS-REC with three members.
-
How does a numeric field appear in the document?
Answer
As a number, without the leading zeros of its digits
PIC 9(3) holding 42 was written as 42.
-
What does a packed decimal keep in the document?
Answer
Its decimal point and its sign, as a JSON number
1250.75 and -12.50 appeared as decimals.
-
What does the COUNT clause give?
Answer
The length of the document in the receiving field
The counter said 57 for the 57 characters between the brackets.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-REC. 05 W-ID PIC 9(3). 01 W-OUT PIC X(100). 01 W-LEN PIC 9(3). PROCEDURE DIVISION. MOVE 7 TO W-ID. JSON GENERATE W-OUT FROM W-REC COUNT W-LEN DISPLAY W-OUT(1:W-LEN). STOP RUN.Answer
{"W-REC":{"W-ID":7}}
The record is the outer object and a numeric field loses its leading zeros.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-REC. 05 W-NAME PIC X(6). 01 W-OUT PIC X(100). 01 W-LEN PIC 9(3). PROCEDURE DIVISION. MOVE "AB" TO W-NAME. JSON GENERATE W-OUT FROM W-REC COUNT W-LEN DISPLAY W-OUT(1:W-LEN). STOP RUN.Answer
{"W-REC":{"W-NAME":"AB"}}
An alphanumeric field is written as a string with its spaces trimmed.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC 9(4) VALUE 1250. 01 W-OUT PIC X(20). 01 W-LEN PIC 9(3). PROCEDURE DIVISION. DISPLAY W-A. STOP RUN.Answer
1250
The field has four digits and all of them are in use.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-N PIC 9(3) VALUE 0. 01 W-I PIC 9 VALUE 0. PROCEDURE DIVISION. PERFORM VARYING W-I FROM 1 BY 1 UNTIL W-I IS GREATER THAN 3 ADD W-I TO W-N END-PERFORM. DISPLAY W-N. STOP RUN.Answer
006
One, two and three add to six.
-
What is the risk of a receiving field that is too short?
Answer
A truncated document and no error
The document is text and the only limit is the field it goes into.
-
What does WITHIN do here?
Answer
Nothing: the compiler stops at the word with a syntax error
The build failed with syntax error, unexpected Identifier at that line.
The code on this page was built with cobc (GnuCOBOL) 3.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev