JCL: How a COBOL Program Gets Run

A major difference between modern scripting languages and COBOL on a mainframe is how they interact with the outside world. Modern scripts typically hardcode file paths or accept them via command-line arguments. In the mainframe world, COBOL programs are strictly executed by Job Control Language (JCL).

When you run a COBOL program on a mainframe, the JCL EXEC statement determines which compiled program to execute. The COBOL program itself knows almost nothing about the physical files on disk. This separation of logic and environment is one of COBOL’s biggest historical strengths: device independence.

The ASSIGN Clause and Device Independence

In COBOL, you never put a physical path (like C:\data\input.txt) directly in the FILE-CONTROL paragraph. Instead, you map an internal file to an external logical name using the ASSIGN TO clause.

By pointing to a DD name, the COBOL program remains device independent. You can change the physical data set (the DSN in JCL) or redirect output to a printer, all without needing to recompile the COBOL code.

What the JCL Actually Looks Like

Here is a complete, minimal job that runs the program above. This is real JCL as it would be submitted on z/OS — it cannot be executed here, because nothing outside a mainframe reads it, so read it rather than run it.

//PAYROLL  JOB (ACCT01),'MONTHLY RUN',CLASS=A,MSGCLASS=X
//*
//STEP010  EXEC PGM=PAYCALC
//STEPLIB  DD DSN=PROD.LOADLIB,DISP=SHR
//MYDD     DD DSN=PROD.PAYROLL.INPUT,DISP=SHR
//SYSOUT   DD SYSOUT=*

Six lines, and every one of them is doing a job:

• //PAYROLL JOB names the job and tells the system who to bill and where to send the printed output. Everything after it belongs to this job until the next JOB card.
• //STEP010 EXEC PGM=PAYCALC is the step that actually runs something. PAYCALC is the compiled load module — the name in PROGRAM-ID, not the name of the source file. A job can have many steps, and they run in order.
• //STEPLIB DD says which library holds that load module. Get this wrong and the job fails before your code runs at all.
• //MYDD DD DSN=... is the line that matters most here. MYDD is the same name the COBOL wrote in ASSIGN TO MYDD. That is the whole binding: the program names a DD, the JCL names a dataset, and the system connects them at run time. Point MYDD at a different DSN tomorrow and the program processes different data without being recompiled.
• //SYSOUT DD SYSOUT=* sends DISPLAY output to the job log.

Notice what is not in the COBOL: no path, no drive, no filename. That indirection is why a program written in 1985 can still be pointed at this year’s data.

Simulating JCL DD Mapping

Since we are running these examples in a GnuCOBOL environment instead of a z/OS mainframe, we don’t have JCL. However, GnuCOBOL uses environment variables as the equivalent of JCL DD statements.

By prefixing the ASSIGN name with dd_, you instruct the runtime exactly where the file lives. Below, we use COBOL’s SET ENVIRONMENT statement to dynamically assign the mapping before we open the file.

       IDENTIFICATION DIVISION.
       PROGRAM-ID. AssignTest.
       ENVIRONMENT DIVISION.
       INPUT-OUTPUT SECTION.
       FILE-CONTROL.
           SELECT MY-FILE ASSIGN TO MYDD
               ORGANIZATION IS LINE SEQUENTIAL.
       DATA DIVISION.
       FILE SECTION.
       FD  MY-FILE.
       01  MY-REC PIC X(10).
       PROCEDURE DIVISION.
           SET ENVIRONMENT "dd_MYDD" TO "testout.txt"
           OPEN OUTPUT MY-FILE
           WRITE MY-REC FROM "HELLO"
           CLOSE MY-FILE
           DISPLAY "File mapped successfully."
           STOP RUN.

File mapped successfully.

In a real production environment, you would never set the environment variable inside the COBOL program. The system operator sets it in the JCL before the program is executed.

Changing Files Without Recompiling

Because of this separation, we can map the exact same ASSIGN name to two completely different files dynamically, proving device independence in action:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. DeviceInd.
       ENVIRONMENT DIVISION.
       INPUT-OUTPUT SECTION.
       FILE-CONTROL.
           SELECT MY-FILE ASSIGN TO MYDD
               ORGANIZATION IS LINE SEQUENTIAL.
       DATA DIVISION.
       FILE SECTION.
       FD  MY-FILE.
       01  MY-REC PIC X(10).
       PROCEDURE DIVISION.
           SET ENVIRONMENT "dd_MYDD" TO "file1.txt"
           OPEN OUTPUT MY-FILE
           WRITE MY-REC FROM "DATA1"
           CLOSE MY-FILE
           
           SET ENVIRONMENT "dd_MYDD" TO "file2.txt"
           OPEN OUTPUT MY-FILE
           WRITE MY-REC FROM "DATA2"
           CLOSE MY-FILE
           
           DISPLAY "Wrote to two different files via DD remap."
           STOP RUN.

Wrote to two different files via DD remap.

Missing DD Allocations

On an IBM mainframe, failing to allocate a DD statement (i.e., forgetting to include it in your JCL) will cause a hard runtime error when the program attempts to OPEN the file.

A common misconception is that different FDs (File Descriptions) are entirely isolated. But because the ASSIGN clause is what determines the physical file, two different FDs pointing to the same ASSIGN name actually share the exact same physical disk file.

Since we haven’t mapped dd_A here, GnuCOBOL will physically create a file named A. Based on that, what will this output?

       IDENTIFICATION DIVISION.
       PROGRAM-ID. P.
       ENVIRONMENT DIVISION.
       INPUT-OUTPUT SECTION.
       FILE-CONTROL.
         SELECT F1 ASSIGN A ORGANIZATION LINE SEQUENTIAL.
         SELECT F2 ASSIGN A ORGANIZATION LINE SEQUENTIAL.
       DATA DIVISION.
       FILE SECTION.
       FD F1. 01 R1 PIC 99.
       FD F2. 01 R2 PIC 99.
       PROCEDURE DIVISION.
         OPEN OUTPUT F1. WRITE R1 FROM 42. CLOSE F1.
         OPEN INPUT F2. READ F2. ADD 1 TO R2. DISPLAY R2.
         STOP RUN.

43

Because dd_A was never defined in the environment, GnuCOBOL silently mapped both logic files to a physical file named exactly A. While this prevents a crash locally, relying on unallocated DD names is considered poor practice and will immediately crash a real mainframe job!