Contents
plxcobol: the COBOL dialect
plxcobol lets you write PostgreSQL functions with COBOL syntax (ISO/IEC
1989:2023, COBOL 2023, free format). At CREATE FUNCTION time plx transpiles the
body to plpgsql and stores the plpgsql in pg_proc.prosrc. The function runs on
the standard plpgsql interpreter.
The language name is plxcobol. It is a trusted language.
COBOL is verb-driven and unlike the other plx dialects, so it has its own front
end: data names are mapped to plpgsql identifiers (lower-cased, hyphens become
underscores), and compound statements use the COBOL 2023 explicit scope
terminators (END-IF, END-PERFORM, END-EVALUATE).
Setup
CREATE EXTENSION plx;
Function basics
A function body is a free-format COBOL program fragment: an optional
DATA DIVISION with a WORKING-STORAGE SECTION for locals, then an optional
PROCEDURE DIVISION header, then statements. A scalar function returns with
GOBACK RETURNING.
CREATE FUNCTION add(a int, b int) RETURNS int LANGUAGE plxcobol AS $$
WORKING-STORAGE SECTION.
01 RESULT PIC 9(9).
PROCEDURE DIVISION.
COMPUTE RESULT = A + B
GOBACK RETURNING RESULT.
$$;
Function arguments are referenced by name (case-insensitively). Most SQL
expressions are valid inside COMPUTE and conditions, because expressions are
passed through to plpgsql and SQL. The || operator and :: casts are not,
so use CONCAT(...) and CAST(x AS type). Outside a string literal or a
comment, a character that COBOL does not use, such as |, !, $, or @,
is rejected at CREATE FUNCTION time. A :: cast is not rejected, but the
function fails with a syntax error when it runs.
Local variables and types
Locals are declared in WORKING-STORAGE SECTION as level entries. A PICTURE
clause is mapped to a SQL type:
| PICTURE / clause | SQL type |
|---|---|
PIC 9(n), n up to 9 |
integer |
PIC 9(n), n up to 18 |
bigint |
PIC 9(n), larger |
numeric(n) |
PIC 9(i)V9(s) (implied decimal) |
numeric(i+s, s) |
PIC X(n), PIC A(n) |
varchar(n) |
PIC ... USAGE COMP-1 / COMP-2 (a PIC clause is required) |
real / double precision |
A leading S (sign) is accepted and ignored for typing. A VALUE clause becomes
the declaration’s initializer:
WORKING-STORAGE SECTION.
01 WS-COUNT PIC 9(9) VALUE 0.
01 WS-NAME PIC X(40).
01 WS-RATE PIC 9(3)V9(4).
For types a PICTURE cannot express (%TYPE, %ROWTYPE, RECORD, refcursor),
use a TYPE clause, whose text becomes the plpgsql type (it must be a type name
and nothing else):
01 WS-EMP TYPE emp%ROWTYPE.
01 WS-ROW TYPE RECORD.
01 WS-CUR TYPE refcursor.
A COBOL 2023 constant uses CONSTANT AS:
01 PI CONSTANT AS 3.14159.
Tables (arrays)
OCCURS n [TIMES] makes an item a table, mapped to a PostgreSQL array of the
element type (the fixed bound is not enforced). A VALUE clause gives each of
the n elements that value; without one the table starts as NULL. A subscript
WS-ARR(i) reads or writes element i (1-based):
01 WS-ARR PIC 9(9) OCCURS 5 TIMES.
...
COMPUTE WS-ARR(WS-I) = WS-I * WS-I *> write element
COMPUTE WS-SUM = WS-SUM + WS-ARR(WS-I) *> read element
Iterate the whole table with PERFORM v OVER ARRAY WS-ARR. A subscript is
recognized in MOVE/COMPUTE targets, in DISPLAY operands, and in
expressions; use COMPUTE (not
ADD/SUBTRACT) when an operand is a subscripted element.
Control flow
IF / ELSE
IF SCORE >= 90
MOVE "A" TO WS-GRADE
ELSE
MOVE "F" TO WS-GRADE
END-IF
Conditions may use the relational symbols (=, <>, <, >, <=, >=) or
the COBOL relational words (IS EQUAL TO, IS GREATER THAN,
IS GREATER THAN OR EQUAL TO, IS NOT EQUAL TO, and the LESS forms). AND,
OR, and NOT combine conditions. IS NULL and IS NOT NULL test for null.
EVALUATE
A subject makes a simple CASE; EVALUATE TRUE makes a searched CASE. Stacked
WHEN phrases share the following statements in both forms, and WHEN OTHER
is the default. A WHEN stacked directly before WHEN OTHER shares the
WHEN OTHER statements.
EVALUATE N
WHEN 1
MOVE "one" TO WS-R
WHEN 2
WHEN 3
MOVE "few" TO WS-R
WHEN OTHER
MOVE "many" TO WS-R
END-EVALUATE
EVALUATE TRUE
WHEN N > 0 MOVE "pos" TO WS-R
WHEN N < 0 MOVE "neg" TO WS-R
WHEN OTHER MOVE "zero" TO WS-R
END-EVALUATE
Loops
PERFORM has several inline forms, each closed by END-PERFORM:
PERFORM UNTIL WS-I > N
ADD 1 TO WS-I
END-PERFORM
PERFORM VARYING WS-I FROM 1 BY 1 UNTIL WS-I > N
ADD WS-I TO WS-TOTAL
END-PERFORM
PERFORM N TIMES
ADD 1 TO WS-COUNT
END-PERFORM
PERFORM VARYING tests UNTIL before each iteration and changes the control
variable itself, as COBOL does. After the loop the variable holds the first
value that satisfied UNTIL, or its value at EXIT PERFORM. A MOVE to the
variable or to the bound inside the body affects the next test.
EXIT PERFORM leaves the loop. EXIT PERFORM CYCLE ends the current
iteration; in a PERFORM VARYING the step and the UNTIL test then run as
usual. CONTINUE is a no-op.
Working with data
Assignment and arithmetic
MOVE assigns; COMPUTE evaluates an expression (with ** for exponent). The
arithmetic verbs ADD, SUBTRACT, MULTIPLY, and DIVIDE support the basic
forms, including GIVING:
MOVE 0 TO WS-TOTAL
COMPUTE WS-A = PI * R ** 2
ADD WS-I TO WS-TOTAL
SUBTRACT B FROM A GIVING WS-D
MULTIPLY A BY B GIVING WS-P
DIVIDE B INTO A GIVING WS-Q
DIVIDE a BY b needs GIVING, as in COBOL; without it plx rejects the
statement. DIVIDE a INTO b may omit GIVING and stores into b.
A value stored into a numeric PICTURE item keeps only the fractional digits
that the PICTURE allows, and the rest are truncated, as in COBOL.
COMPUTE WS-I = 7.9 stores 7 in a PIC 9(4) item, and MOVE 2.5 TO WS-I
stores 2. To round instead, write ROUNDED after the receiving field; it
rounds half away from zero:
COMPUTE WS-M ROUNDED = 2.0 / 3 *> PIC 9(3)V99: stores 0.67
ADD 1.5 TO WS-Q ROUNDED
MULTIPLY A BY B GIVING WS-P ROUNDED
This applies to MOVE, COMPUTE, the four arithmetic verbs, the
PERFORM VARYING control variable, and the VALUE clause (PIC 9(4) VALUE
2.5 starts at 2). ROUNDED MODE is not supported. An item declared with a
TYPE clause or USAGE COMP-1 / COMP-2, a whole table stored at once
(MOVE WS-A TO WS-B where WS-B has OCCURS), the loop variable of
PERFORM v OVER ARRAY, and a value stored by EXECUTE ... INTO,
FETCH-CURSOR, or GET, follow the SQL assignment rule, which rounds.
DIVIDE into a numeric PICTURE item divides as numeric, so the quotient
keeps its fraction until it is stored: DIVIDE 2 INTO 7 GIVING WS-M stores
3.50 in a PIC 9V99 item, and DIVIDE 4 INTO WS-A ROUNDED stores 1 when
WS-A is 3. In COMPUTE and in conditions, / follows SQL instead: the
quotient of two integers is truncated before ROUNDED can act, so
COMPUTE WS-C ROUNDED = WS-A / WS-B stores 0 when WS-A is 3 and WS-B
is 4. To keep the fraction, make one operand numeric, for example
WS-A * 1.0 / WS-B.
Iterating a query
PERFORM <record> OVER "<sql>" runs the loop body once per row. Field access on
the record is <record>.<column>. Add USING <args> for bind parameters or
non-literal SQL.
01 WS-ROW TYPE RECORD.
...
PERFORM WS-ROW OVER "SELECT id, amount FROM orders WHERE grp = $1" USING G
ADD WS-ROW.AMOUNT TO WS-TOTAL
END-PERFORM
Iterating an array
01 WS-V PIC 9(9).
...
PERFORM WS-V OVER ARRAY WS-VALUES
ADD WS-V TO WS-TOTAL
END-PERFORM
Dynamic SQL
EXECUTE runs dynamic SQL, with optional USING binds and INTO targets (in
either order):
EXECUTE "SELECT count(*) FROM t WHERE amount >= $1" USING WS-MIN INTO WS-COUNT
EXECUTE "INSERT INTO t(msg) VALUES ($1)" USING WS-NOTE
Cursors
01 WS-C TYPE refcursor.
01 WS-ROW TYPE RECORD.
...
OPEN-CURSOR WS-C FOR "SELECT v FROM t ORDER BY v"
FETCH-CURSOR WS-C INTO WS-ROW
PERFORM UNTIL WS-ROW IS NULL
ADD WS-ROW.V TO WS-TOTAL
FETCH-CURSOR WS-C INTO WS-ROW
END-PERFORM
CLOSE-CURSOR WS-C
MOVE-CURSOR WS-C and MOVE-CURSOR WS-C 3 map to plpgsql MOVE.
Diagnostics
GET ROW-COUNT INTO <var> maps to GET DIAGNOSTICS <var> = ROW_COUNT. FOUND
is available in conditions.
Set-returning functions
CREATE FUNCTION squares(n int) RETURNS SETOF int LANGUAGE plxcobol AS $$
WORKING-STORAGE SECTION.
01 WS-I PIC 9(9).
PROCEDURE DIVISION.
PERFORM VARYING WS-I FROM 1 BY 1 UNTIL WS-I > N
RETURN-NEXT WS-I * WS-I
END-PERFORM
GOBACK.
$$;
RETURN-QUERY "<sql>" returns the rows of a query (add USING for binds or a
non-literal command).
Calling a procedure
CALL "my_proc" USING WS-A WS-B
COMMIT and ROLLBACK are available in a procedure context.
Building strings in a loop
Concatenating onto a string in a loop is slow in plpgsql (O(n2), because text is
immutable and each step copies the whole string). STRING-APPEND <expr> TO <var>
lowers to the plx string builder (plx_strbuild), whose append is amortized
O(1):
01 WS-OUT PIC X(1) VALUE "".
...
PERFORM WS-ROW OVER "SELECT name FROM t ORDER BY id"
STRING-APPEND WS-ROW.NAME TO WS-OUT
STRING-APPEND "," TO WS-OUT
END-PERFORM
GOBACK RETURNING WS-OUT.
On PostgreSQL 18 this is amortized O(1) per append; on PostgreSQL 13 to 17 it is correct but not accelerated (the in-place optimization needs a PostgreSQL 18 feature).
STRING-APPEND treats a NULL value as nothing to append, and a NULL target as empty. The other dialects' append operators make the string NULL instead.
Errors
Raising
RAISE EXCEPTION "negative value" SQLSTATE "22023"
RAISE NOTICE "processed rows"
Levels are EXCEPTION (or ERROR), NOTICE, WARNING, INFO, LOG, and
DEBUG. DISPLAY emits a NOTICE, concatenating its operands. An operand is
a data name, a table element (WS-ARR(I)), or a literal; to display an
expression, COMPUTE it into a data item first. UPON <device> and
[WITH] NO ADVANCING are accepted and have no effect.
Handling
BEGIN-TRY
COMPUTE WS-Q = A / B
WHEN DIVISION-BY-ZERO
MOVE "cannot divide by zero" TO WS-MSG
WHEN OTHER
GET MESSAGE INTO WS-MSG
END-TRY
WHEN <condition> names a SQL condition (DIVISION-BY-ZERO,
UNIQUE-VIOLATION, and similar; hyphens become underscores). WHEN OTHER
catches everything. Inside a handler, GET retrieves stacked diagnostics:
GET MESSAGE, GET DETAIL, GET HINT, GET SQLSTATE, and GET CONTEXT, each
INTO <var>.
Assertions
ASSERT N > 0
Expressions
- String literals use
"..."or'...'; a doubled quote is a literal quote. - Concatenation and formatting:
DISPLAYconcatenates its operands. - Figurative constants:
ZERO/ZEROSmap to0,SPACE/SPACESto the empty string,NULLto SQLNULL. - Arithmetic:
+,-,*,/are as in SQL;**maps to SQL^(exponent) and%is modulo.COMPUTEevaluates the expression as SQL. - Comparisons use SQL three-valued logic. Use
IS NULL/IS NOT NULLto test for null.
Trigger functions
A function returning trigger can be used as a trigger. Assign to NEW fields
with MOVE (or COMPUTE) and return NEW:
CREATE FUNCTION stamp() RETURNS trigger LANGUAGE plxcobol AS $$
PROCEDURE DIVISION.
MOVE "row" TO NEW.TAG
GOBACK RETURNING NEW.
$$;
NEW, OLD, and the TG_ variables are available. Assigning to a record field
(MOVE e TO NEW.COL) works because a qualified name maps to new.col;
MOVE OLD TO NEW replaces the whole row.
Semantic differences
These are intentional. plx pins semantics to SQL and plpgsql.
- Decimal literals infer
numeric, not a floating-point type. - Integer division and modulo in expressions follow SQL (truncate toward
zero). The
DIVIDEverb into a numericPICTUREitem is the exception; see Assignment and arithmetic. - The number of integer digits in a
PICTUREis not enforced: aPIC 9(n)item holds any value of itsintegerorbiginttype, and a value too large for anumeric(p,s)item raises an error. COBOL would drop the high-order digits. - A condition must be a boolean expression; there is no COBOL 88-level or
class-condition abbreviation. An 88-level entry is rejected. A class
condition such as
N IS NUMERICis not rejected but mistranslated (ISis dropped), so write a SQL boolean expression. - Data names are function-scoped after mapping to plpgsql identifiers, so two
names that differ only by
-versus_collide.
Not supported
Rejected at CREATE FUNCTION time with a line number:
- Full program structure beyond a single procedure body:
IDENTIFICATION,ENVIRONMENT, andCONFIGURATIONdivisions, and named paragraphs or sections with out-of-linePERFORM <paragraph>. - Group items (subordinate level entries under an
01) inWORKING-STORAGE; declare elementary items, or use aTYPEclause for a composite plpgsql type. - Fixed-format source (columns, sequence area, indicator area). Use free format.
- Report Writer, screen sections, and object orientation.
Not translated: the standard COBOL intrinsic function library. A
FUNCTION name(...) call is passed through and fails when the function runs.
Use SQL functions inside expressions and SQL text.
See PARITY.md for the full plpgsql construct matrix and ARCHITECTURE.md for how plx maps to the plpgsql engine.