The contract: fixed-width and JSON

Everything in this project depends on one small agreement: a request is thirty bytes, an answer is fifty, and the fields sit at fixed positions. The COBOL core reads the first and writes the second; the Python layer produces the first from an HTTP body and turns the second into a response. Get the agreement wrong and both sides still run, which is why it is on the first page.

The two records

RequestLengthPictureExample
order id6X(6)C00001
SKU8X(8)WIDGET01
quantity59(5)00002
unit price in cents99(9)00123456
region2X(2)N1
total30
AnswerLengthPictureExample
order id6X(6)C00001
status29(2)00
net in cents119(11)00000246912
tax in cents119(11)00000032099
message20X(20)PRICED
total50

The copybook

The two records live in one file, and every program of the project that touches them copies it. This is the file, saved as priceif.cpy:

01 PRICE-REQUEST. 05 PR-ORDER-ID PIC X(6). 05 PR-SKU PIC X(8). 05 PR-QTY PIC 9(5). 05 PR-CENTS PIC 9(9). 05 PR-REGION PIC X(2). 01 PRICE-ANSWER. 05 PA-ORDER-ID PIC X(6). 05 PA-STATUS PIC 9(2). 05 PA-NET PIC 9(11). 05 PA-TAX PIC 9(11). 05 PA-MESSAGE PIC X(20).

The listing above is a fragment by nature: a copybook has no PROGRAM-ID and no divisions. The programs on the next pages write the same two records out inside themselves, because a code block on this site is one file and each program has to build on its own; in the shipped project they say COPY "priceif.cpy" and the compiler inserts exactly these lines. Both forms were built here, and the copybook form prints the same line as the written-out one.

The positions are worth checking with a program and not with a ruler. This one cuts the five fields out of a literal request and prints them beside the lengths the compiler reports:

IDENTIFICATION DIVISION. PROGRAM-ID. FIELDS. DATA DIVISION. WORKING-STORAGE SECTION. 01 REQ-LINE PIC X(30) VALUE "C00001WIDGET0100002000123456N1". 01 PRICE-REQUEST. 05 PR-ORDER-ID PIC X(6). 05 PR-SKU PIC X(8). 05 PR-QTY PIC 9(5). 05 PR-CENTS PIC 9(9). 05 PR-REGION PIC X(2). PROCEDURE DIVISION. MOVE REQ-LINE(1:6) TO PR-ORDER-ID MOVE REQ-LINE(7:8) TO PR-SKU MOVE REQ-LINE(15:5) TO PR-QTY MOVE REQ-LINE(20:9) TO PR-CENTS MOVE REQ-LINE(29:2) TO PR-REGION DISPLAY "order [" PR-ORDER-ID "]" DISPLAY "sku [" PR-SKU "]" DISPLAY "qty [" PR-QTY "]" DISPLAY "cents [" PR-CENTS "]" DISPLAY "region[" PR-REGION "]" DISPLAY "request " LENGTH OF REQ-LINE " bytes" DISPLAY "record " LENGTH OF PRICE-REQUEST " bytes" STOP RUN.

cobc -x -free -Wall -O2 -o fields fields.cob
./fields
echo $?

order [C00001]
sku   [WIDGET01]
qty   [00002]
cents [000123456]
region[N1]
request 30 bytes
record  30 bytes
0

Why the wire carries cents

The unit price and both amounts are integers of cents, not decimal numbers with an implied point. A fixed-width field of 9(7)V99 looks like the natural choice and it has one trap that costs a day to find: a MOVE from the alphanumeric request line into a numeric field with a V does not apply the implied decimal, it reads the digits as an integer. Nine characters 00123456 become 123456.00 and not 1234.56, and the invoice is a hundred times too large. The MOVE rules lesson is that rule in full, and capstone C met it in practice.

Cents have no such rule. The core multiplies the quantity by the cents, takes thirteen per cent with ROUNDED, and the only places decimals appear are the two the Python layer prints or the JSON it builds. A client that wants 2469.12 gets it from 246912, and both sides know which one is on the wire.

Status codes

CodeMeaningMessage in the answerHTTP in the service
00pricedPRICED200
04quantity is zeroQUANTITY IS ZERO422
08region is not one of fourUNKNOWN REGION422
12no SKUSKU IS EMPTY422

The status is part of the answer and not of the exit status of the program: one run of the core can price five orders and reject two, and the exit status says only that something was rejected. The mapping to HTTP is the Python layer\'s decision, and the error page shows what each one looks like to a client.

The JSON variant

A modern client sends JSON, and the COBOL core has no idea what JSON is. The conversion lives in the Python layer and nowhere else: the JSON body is turned into the thirty bytes, and the fifty bytes are turned back into a document. This is a real request and a real response from the service:

POST /price/json {"order_id": "C00007", "sku": "WIDGET07", "qty": 4, "price_cents": 2500, "region": "S2"}

{"order_id": "C00007", "status": "00", "net_cents": 10000, "tax_cents": 1300, "message": "PRICED", "http_status": 200}

Four units at twenty-five euros are a hundred, and thirteen per cent of that is thirteen: the numbers are in cents on both sides of the conversion and the JSON names them so. A request that fails the contract is a 400 and never reaches COBOL, which is the second benefit of converting at the edge: the core only ever sees a well-formed thirty-byte record.

JSONFixed fieldRule in the service
order_id1-6truncated to six, padded with spaces
sku7-14truncated to eight, padded with spaces
qty15-190 to 99999, else 400
price_cents20-280 to 999999999, else 400
region29-30one of N1, S2, E3, W4, else 400

The service\'s conversion functions are on the next pages but one, in the file server.py. The core itself is the next page, and it is one program of about eighty lines.

The COBOL was built with cobc (GnuCOBOL) 3.2.0 with -O2, the Python is Python 3.14.10, and everything ran on Alpine Linux 3.24.3 (x86_64) in a Docker container with nproc 4.

Article author: Arthur Isaev