A COBOL code example only makes sense with two other files. The COBOL program holds the business logic, a copybook holds the record layout the program copies in at compile time, and JCL (Job Control Language) tells the mainframe which program to run and which files to give it. A modernization project needs all three, plus test data and change history.
- JCL is not a programming language for business logic: it names the program to run and its input and output files.
- A copybook is shared source text, usually a record layout, pulled into a COBOL program by a COPY statement.
- The DD names in the JCL must match the file names the COBOL program assigns, or the step fails.
- A modernization project needs source, copybooks, JCL, test data and change history together, not source alone.
What is JCL?
JCL stands for Job Control Language. IBM's mainframe textbook says it "is used to tell the system what program to execute, followed by a description of program inputs and outputs" (IBM Redbooks). It is the language of batch work on z/OS: a job is a list of steps, and each step runs one program against named files (data sets).
JCL does not calculate anything. It is closer to a run sheet than to a program. The same textbook notes that "a small subset of JCL accounts for at least 90% of what is actually used", and that subset is three statements.
| Statement | What IBM says it does | In plain words |
|---|---|---|
| JOB | "Provides a name (jobname) to the system for this batch workload." | Opens the job and carries accounting and job-wide settings |
| EXEC | "Provides the name of a program to execute." Each EXEC statement within the same job is a job step. | Runs one program or one stored procedure (PROC) |
| DD | "This statement links a data set or other I/O device or function to a ddname coded in the program." | Connects a file name inside the program to a real file |
Every JCL statement starts with two slashes in columns 1 and 2. A line starting with //* is a comment, and /* ends data typed inside the job.
JCL example: a two-step batch job
This job is a fictional nightly payment report. Step SORT01 sorts the daily payment file by account number (the first 10 bytes of each record) into a temporary data set. Step REPORT runs the COBOL program PAYRPT01 against the sorted file.
Three details are worth reading closely. The && prefix marks a temporary data set that lives only for the job. DISP=(NEW,PASS) creates it and passes it to a later step. COND=(0,NE,SORT01) skips the report step when the sort step ends with any return code other than 0.
//PAYRPT JOB (ACCT01),'DAILY PAYMENTS',CLASS=A,MSGCLASS=X,
// NOTIFY=&SYSUID
//* STEP 1: SORT TODAY'S PAYMENT FILE BY ACCOUNT NUMBER
//SORT01 EXEC PGM=SORT
//SORTIN DD DSN=PROD.PAYMENTS.DAILY,DISP=SHR
//SORTOUT DD DSN=&&SORTED,DISP=(NEW,PASS),
// UNIT=SYSDA,SPACE=(CYL,(5,1))
//SYSOUT DD SYSOUT=*
//SYSIN DD *
SORT FIELDS=(1,10,CH,A)
/*
//* STEP 2: RUN THE COBOL REPORT ONLY IF THE SORT ENDED WITH CODE 0
//REPORT EXEC PGM=PAYRPT01,COND=(0,NE,SORT01)
//STEPLIB DD DSN=PROD.PAYMENTS.LOADLIB,DISP=SHR
//PAYIN DD DSN=&&SORTED,DISP=(OLD,DELETE)
//SYSOUT DD SYSOUT=*
Illustrative example written for this page. Data set names, classes and accounting fields differ at every site.
COBOL code example with a copybook
IBM describes COBOL as "a high-level, English-like, compiled programming language that is developed specifically for business data processing needs" (IBM). Every program has the same four divisions: identification, environment, data and procedure. The example below reads the sorted payment file and prints a count and a total of posted payments.
The record layout is not typed into the program. It sits in a copybook, which IBM defines as "a source library containing pre-written text" that is copied into a source program at compile time (IBM Redbooks). The line COPY PAYREC pulls it in. Any other program that reads the same file copies the same layout, so a field changes in one place.
* PAYREC: ONE PAYMENT RECORD, 80 BYTES.
01 PAYMENT-RECORD.
05 PAY-ACCOUNT-NO PIC X(10).
05 PAY-DATE PIC 9(8).
05 PAY-AMOUNT PIC S9(7)V99 COMP-3.
05 PAY-STATUS PIC X.
88 PAY-POSTED VALUE 'P'.
88 PAY-REJECTED VALUE 'R'.
05 FILLER PIC X(56).
IDENTIFICATION DIVISION.
PROGRAM-ID. PAYRPT01.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT PAY-FILE ASSIGN TO PAYIN.
DATA DIVISION.
FILE SECTION.
FD PAY-FILE.
COPY PAYREC.
WORKING-STORAGE SECTION.
01 WS-EOF PIC X VALUE 'N'.
88 END-OF-FILE VALUE 'Y'.
01 WS-POSTED-COUNT PIC 9(7) VALUE ZERO.
01 WS-POSTED-TOTAL PIC S9(9)V99 COMP-3 VALUE ZERO.
01 WS-TOTAL-EDIT PIC Z,ZZZ,ZZZ,ZZ9.99-.
PROCEDURE DIVISION.
MAIN-PARA.
OPEN INPUT PAY-FILE
PERFORM UNTIL END-OF-FILE
READ PAY-FILE
AT END
SET END-OF-FILE TO TRUE
NOT AT END
IF PAY-POSTED
ADD 1 TO WS-POSTED-COUNT
ADD PAY-AMOUNT TO WS-POSTED-TOTAL
END-IF
END-READ
END-PERFORM
CLOSE PAY-FILE
MOVE WS-POSTED-TOTAL TO WS-TOTAL-EDIT
DISPLAY 'POSTED PAYMENTS: ' WS-POSTED-COUNT
DISPLAY 'POSTED TOTAL: ' WS-TOTAL-EDIT
GOBACK.
Illustrative example written for this page. PIC X(10) is 10 characters, PIC S9(7)V99 COMP-3 is a signed packed-decimal amount with two decimal places, and the 88 levels name the values a status byte can hold.
How do COBOL programs, copybooks and JCL fit together?
The three files meet at two points. At compile time, the compiler replaces each COPY statement with the text of the copybook. IBM notes that the compile job finds copybooks "by supplying a DD statement for SYSLIB", so even the compile depends on JCL. At run time, the name after ASSIGN TO in the program (PAYIN in the example) must match a DD name in the job step, and that DD statement points at the real file.
This is why a COBOL program alone tells you less than it seems. Without the copybook you cannot read a single record, and without the JCL you do not know which files the program touches, in what order, or what runs before and after it.
| Artifact | What it holds | What breaks without it |
|---|---|---|
| COBOL program | Business rules in the procedure division | Nothing to run |
| Copybook | Record layouts and shared constants | The program does not compile, and data files cannot be decoded |
| JCL job and PROCs | Step order, programs, files, conditions | No one knows how the program is run or what feeds it |
| Data files and database definitions | The records themselves | Nothing to test against |
What does COBOL and mainframe modernization need from a codebase?
IBM defines mainframe modernization as the process of updating or transforming legacy mainframe applications or systems, and warns that "mere code translation often fails to address the complexity of the problem modernization sets out to solve" (IBM). On COBOL in particular, it says that "an exclusive focus on language translation ignores the platform component" (IBM). That applies whether people or AI coding tools do the work: a tool given only the COBOL source cannot see the record layouts, the job flow or the expected output.
The same holds for Fortran, the other long-lived legacy language. IBM dates its commercial release to 1957 and notes that "it's still in use decades after its release" (IBM Heritage). Where COBOL runs business records, Fortran "has been designed from the ground up for computationally intensive applications in science and engineering" (fortran-lang.org). A Fortran codebase needs its build files, input decks and reference results in the same way.
| What to gather | Why the project needs it |
|---|---|
| All source, including dead and rarely run programs | Shows what is still called and what can be retired |
| Every copybook, at the version each program was compiled with | Record layouts drive every data conversion |
| JCL, PROCs and scheduler definitions | Give the order of work and the dependencies between jobs |
| Test data and expected outputs | Prove that the new system gives the same answers as the old one |
| Change history and tickets | Explain why a rule exists, which the code rarely says |
Common mistakes with legacy COBOL and JCL
Most trouble in legacy system modernization starts with an incomplete picture of the codebase.
- Collecting the COBOL source but not the copybooks, so nothing compiles off the mainframe.
- Ignoring JCL and scheduler definitions, then finding that the order of jobs was part of the business logic.
- Using copybooks from the current library when production programs were compiled against older versions.
- Treating packed-decimal (COMP-3) fields as text during a file transfer, which corrupts amounts.
- Testing new code without saved inputs and outputs from the old system to compare against.
- Losing the change history when source moves from a mainframe library tool into git.
Is a COBOL, Fortran or JCL codebase also a data asset?
It can be. AI data buyers have asked Origin for COBOL, Fortran and JCL codebases. The parts that matter are the ones a modernization project needs: source with copybooks, JCL, test data and change history, kept together. See selling source code for AI training, software test history and incident reviews for how each record type is treated.
Origin is an independent data partner. Your company decides what is shared and signs any license itself, and a buyer may pay Origin when a deal closes.
- Secrets and credentials: remove passwords, keys and connection strings from source, JCL and parameter files.
- Customer data: test files and saved outputs often hold real customer records. Replace or remove them; see how to de-identify company data.
- Personal data: programmer names and user IDs sit in comments, job cards and change history.
- Third-party and open-source code: check the license terms of vendor copybooks, purchased packages and open-source libraries before they leave the company.
- Customer contracts: code written for a client, or under an outsourcing agreement, may belong to the client or carry confidentiality terms.
- Tickets: if change history lives in a tracker, see how to export Jira and Confluence data.
Does your company hold records like these? See what your data is worth.
Common questions
What is JCL in simple terms?
JCL (Job Control Language) is the set of statements that tells an IBM mainframe which program to run and which files to use. It does not hold business logic. A job is built from JOB, EXEC and DD statements.
Is JCL a programming language like COBOL?
No. The JCL language describes work for the operating system: the steps of a job, the program each step runs and the files it reads and writes. The calculations happen in the programs it runs, which are often written in COBOL.
What is a COBOL copybook used for?
A COBOL copybook holds source text that several programs share, most often the layout of a record. A COPY statement pulls it into the program at compile time, so every program that reads a file uses the same field definitions.
What does a simple JCL example look like?
A simple JCL example has one JOB statement, one EXEC statement naming the program, and one DD statement for each file the program uses. The example on this page adds a second step that runs only when the first ends with return code 0.
What is the difference between COBOL modernization and mainframe modernization?
COBOL modernization updates or converts the COBOL applications. Mainframe modernization is wider: it also covers the data, the job flow, the transaction systems and the platform the code runs on. Both need more than the source code.
Can AI convert COBOL code to a modern language?
AI coding tools can read and translate COBOL, but translation alone is not a finished project. The tool also needs the copybooks, the JCL and test data with expected results, and people still have to check that the new system gives the same answers.
