> COBOL REFERENCE MANUAL

COBOL (COmmon Business-Oriented Language) nasce nel 1959 per iniziativa del DoD statunitense e del comitato CODASYL. È il linguaggio più longevo in ambito business/finanziario; si stima che oltre il 70% delle transazioni finanziarie globali tocchi codice COBOL.

Un programma COBOL è strutturato gerarchicamente: Program → Division → Section → Paragraph → Sentence → Statement.

*> Template minimo GnuCOBOL
       >>SOURCE FORMAT FREE

IDENTIFICATION DIVISION.
PROGRAM-ID.    nome-programma.
AUTHOR.        Nome Autore.
INSTALLATION.  Nome computer.
DATE-WRITTEN.  01 Jan 2025.
DATE-COMPILED. 01 Jan 2025.
SECURITY.      Confidential.

ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. Nome computer.
OBJECT-COMPUTER. Nome computer
    MEMORY SIZE dimensione-memoria [CHARACTERS | WORDS | MODULES]
    PROGRAM COLLATING SEQUENCE IS nome-alfabeto *> Stabilisce l'ordine di "valore" dei caratteri (MERGE e SORT)
    SEGMENT-LIMIT IS limite.
SPECIAL-NAMES.
    *> Classificazioni personalizzate
    CLASS nome IS val1, val2, ...
    DECIMAL-POINT IS COMMA
    CURRENCY SIGN IS carattere
    ALPHABET nome-alfabeto IS [ASCII | EBCDIC | NATIVE | STANDARD-1/2].
REPOSITORY.
    FUNCTION ALL INTRINSIC.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
    *> Associazione file
I-O-CONTROL.

DATA DIVISION.
FILE SECTION.
    *> Descrittori FD/SD
WORKING-STORAGE SECTION.
    *> Variabili globali del programma
LOCAL-STORAGE SECTION.
    *> Variabili locali (reinizializzate ad ogni CALL)
LINKAGE SECTION.
    *> Parametri passati da programma chiamante
SCREEN SECTION.
    *> Definizioni schermi interattivi

PROCEDURE DIVISION [USING param1 param2] [RETURNING ret].
DECLARATIVES.
      *> Gestione degli errori
END DECLARATIVES.

    *> Logica del programma
    STOP RUN.
END PROGRAM nome-programma.

01 Cliente.
   02 IDCliente    PIC 9(5).
   02 NomeCliente.
       03 Cognome  PIC X(20).
       03 Nome     PIC X(20).
   02 DataNascita.
       03 Giorno   PIC 99.
       03 Mese     PIC 99.
       03 Anno     PIC 9(4).
*> FILLER: campo senza nome (placeholder)
   02 FILLER       PIC X(5) VALUE SPACES.

*> CONSTANT (GnuCOBOL)
01 MAX-SIZE     CONSTANT AS 100.
78 PI-VALUE     VALUE 3.14159265.

*> RENAMES (66)
01 DataRec.
   02 Anno  PIC 9(4).
   02 Mese  PIC 99.
   02 Giorno PIC 99.
66 MeseGiorno RENAMES Mese THRU Giorno.

01 ContBin    PIC 9(4)  USAGE BINARY.         *> int16
01 ContBin4   PIC 9(9)  USAGE BINARY.         *> int32
01 ValFloat   USAGE COMP-1.                   *> float C
01 ValDouble  USAGE COMP-2.                   *> double C
01 ValPacked  PIC S9(7)V99 USAGE COMP-3.     *> packed dec
01 Puntatore  USAGE POINTER.                 *> void* C

COMP-X è una clausola USAGE specifica di GnuCOBOL e Micro Focus. Il comportamento dipende dal contesto:

*> Esempio pratico: buffer di byte per interop C
01 RawByte    PIC X(1) COMP-X VALUE 0.
01 Word16     PIC X(2) COMP-X.
01 DWord32    PIC X(4) COMP-X.
01 QWord64    PIC X(8) COMP-X.
01 Cnt8s      USAGE BINARY-CHAR.       *> int8_t
01 Cnt8u      USAGE BINARY-CHAR UNSIGNED. *> uint8_t
01 IntVal     USAGE BINARY-LONG.       *> int32_t
01 BigVal     USAGE BINARY-DOUBLE.     *> int64_t
01 FltVal     USAGE FLOAT-LONG.        *> double

01 StartNum  PIC 9(8)V99  VALUE 1234.56.
01 Formattato PIC $$,$$$,$$9.99.   *> $1,234.56
01 Data       PIC 99/99/9999.      *> 12/21/2024
01 SenzaZeri  PIC ZZZZ9.99.        *>    1234.56 (no leading zeros)
MOVE StartNum TO Formattato
DISPLAY Formattato.

REDEFINES permette di accedere alla stessa area di memoria con layout diversi (simile a union in C). Il campo ridefinito e quello originale condividono gli stessi byte fisici: scrivere in uno modifica l'altro.

*> Stesso storage, visto come testo o come numero
01 DataGrezza    PIC X(8).
01 DataNum       REDEFINES DataGrezza PIC 9(8).
01 DataStruct    REDEFINES DataGrezza.
   02 Anno         PIC 9(4).
   02 Mese         PIC 99.
   02 Giorno       PIC 99.
*> MOVE "20241225" TO DataGrezza
*> DISPLAY Anno    -> "2024"
*> DISPLAY DataNum -> 20241225

*> Union-style: interpretare lo stesso dato come int o float
01 RawArea       PIC X(4).
01 IntView       REDEFINES RawArea USAGE BINARY-LONG.
01 FloatView     REDEFINES RawArea USAGE FLOAT-SHORT.

*> REDEFINES in strutture di gruppo (subordinati)
01 Indirizzo.
   02 CodicePostale PIC X(5).
   02 CPStrutturato REDEFINES CodicePostale.
       03 Regione      PIC XX.
       03 Comune       PIC X(3).
   02 Citta         PIC X(30).

*> Tecnica classica per inizializzare una tabella con valori noti
01 MesiTable.
   02 MesiData.
       03 FILLER PIC X(9) VALUE "Gennaio  ".
       03 FILLER PIC X(9) VALUE "Febbraio ".
       03 FILLER PIC X(9) VALUE "Marzo    ".
       03 FILLER PIC X(9) VALUE "Aprile   ".
       *> ... (12 FILLER totali)
   02 FILLER REDEFINES MesiData.
       03 NomeMese PIC X(9) OCCURS 12 TIMES.
*> DISPLAY NomeMese(3)  -> "Marzo    "

FILLER e' un campo anonimo (senza nome referenziabile) che occupa spazio nel record ma non e' indirizzabile direttamente nel codice. Usi principali:

*> Record con FILLER per formato tracciato fisso
01 RecordFisso.
   02 RF-Codice     PIC 9(5).
   02 FILLER        PIC X(3) VALUE SPACES.   *> separatore
   02 RF-Nome       PIC X(30).
   02 FILLER        PIC X(12).              *> riservato
   02 RF-Importo    PIC 9(7)V99.

*> Da COBOL-85: la parola FILLER e' opzionale
01 RecordModerno.
   02 PIC X(5) VALUE SPACES.  *> FILLER implicito
   02 RM-Nome PIC X(20).

I livelli 88 definiscono nomi di condizione associati a un campo genitore. Non occupano memoria propria: sono alias booleani che testano se il genitore contiene determinati valori. Sono l'equivalente COBOL degli enum e dei flag booleani dei linguaggi moderni.

*> Booleano semplice (flag On/Off)
01 WS-EOF       PIC 9 VALUE 0.
   88 EOF-Reached  VALUE 1.
   88 Not-EOF      VALUE 0.

*> Stato con valori multipli (lista)
01 Stato          PIC X.
   88 StApertura   VALUE 'A'.
   88 StChiusura   VALUE 'C'.
   88 StErrore     VALUE 'E', 'F', 'G'.
   *> StErrore e' TRUE se Stato = 'E' OR 'F' OR 'G'

*> Range continuo con THRU
01 Voto           PIC 99.
   88 Insufficiente VALUE 0 THRU 17.
   88 Sufficiente   VALUE 18 THRU 23.
   88 Buono         VALUE 24 THRU 27.
   88 Ottimo        VALUE 28 THRU 30.
   88 VotoValido    VALUE 0 THRU 30.

*> Range combinato con valori singoli
01 CodiceResp     PIC X(2).
   88 RespOK       VALUES ARE "00", "02", "04".
   88 RespWarning  VALUES ARE "10" THRU "19".
   88 RespError    VALUES ARE "20" THRU "49", "99".

*> FALSE IS: permette SET ... TO FALSE
01 WS-Switch      PIC X VALUE 'N'.
   88 Attivato     VALUE 'Y' FALSE 'N'.

*> Su campo alfanumerico (HIGH-VALUES per EOF)
01 WS-Flag        PIC X.
   88 EOF-Flag     VALUE HIGH-VALUES.

SET condizione TO TRUE scrive nel campo genitore il primo valore della lista VALUE. E' il modo idiomatico COBOL per modificare lo stato di un flag senza conoscere il valore concreto.

*> SET ... TO TRUE: assegna il primo VALUE al genitore
SET EOF-Reached TO TRUE.    *> WS-EOF diventa 1
SET StApertura  TO TRUE.    *> Stato diventa 'A'
SET StErrore    TO TRUE.    *> Stato diventa 'E' (primo della lista)
SET Sufficiente TO TRUE.    *> Voto diventa 18 (inizio del range)

*> SET ... TO FALSE: richiede clausola FALSE IS nella definizione
SET Attivato TO FALSE.       *> WS-Switch diventa 'N'
*> ERRORE se FALSE IS non dichiarato: SET StApertura TO FALSE

*> Test diretto: il livello 88 e' gia' una condizione booleana
IF EOF-Reached
    DISPLAY "Fine file"
END-IF.

*> Negazione
IF NOT StApertura
    DISPLAY "Non in stato aperto"
END-IF.

*> In EVALUATE TRUE (pattern switch idiomatico)
EVALUATE TRUE
    WHEN Insufficiente DISPLAY "Bocciato"
    WHEN Sufficiente   DISPLAY "Sufficiente"
    WHEN Buono         DISPLAY "Buono"
    WHEN Ottimo        DISPLAY "Ottimo"
END-EVALUATE.

*> In condizione di loop
PERFORM UNTIL EOF-Reached
    READ InputFile
        AT END SET EOF-Reached TO TRUE
        NOT AT END PERFORM ProcessaRecord
    END-READ
END-PERFORM.

*> Validazione input con range
ACCEPT Voto FROM CONSOLE.
IF NOT VotoValido
    DISPLAY "Voto non valido (0-30)"
END-IF.

La LOCAL-STORAGE SECTION, introdotta in COBOL 2002, e' una sezione della DATA DIVISION che dichiara variabili reinizializzate automaticamente ad ogni invocazione del programma (tramite CALL). La differenza fondamentale con la WORKING-STORAGE e' il ciclo di vita dei dati.

DATA DIVISION.
FILE SECTION.
    *> FD / SD
WORKING-STORAGE SECTION.
    *> Dati persistenti tra CALL
    01 WS-CallCount   PIC 9(5) VALUE 0.   *> inizializzato 1 volta
LOCAL-STORAGE SECTION.
    *> Dati reinizializzati ad ogni CALL
    01 LS-Temp        PIC X(50) VALUE SPACES. *> SPACES ad ogni CALL
    01 LS-Counter     PIC 9(3) VALUE 0.     *> 0 ad ogni CALL
    01 LS-NoValue     PIC X(10).              *> INDEFINITO ad ogni CALL
LINKAGE SECTION.
    *> Parametri dal chiamante

IDENTIFICATION DIVISION.
PROGRAM-ID. CONTATORE.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-Count PIC 9(3) VALUE 0.
LOCAL-STORAGE SECTION.
01 LS-Count PIC 9(3) VALUE 0.

PROCEDURE DIVISION.
    ADD 1 TO WS-Count.
    ADD 1 TO LS-Count.
    DISPLAY "WS: " WS-Count " LS: " LS-Count.
    EXIT PROGRAM.

*> Risultato dopo 3 CALL consecutive:
*> CALL 1: WS: 001 LS: 001
*> CALL 2: WS: 002 LS: 001  (LS reinizializzato!)
*> CALL 3: WS: 003 LS: 001  (LS reinizializzato!)

STRING Str1 DELIMITED BY SIZE
       Str2 DELIMITED BY SPACE
       Str3 DELIMITED BY "#"
       INTO Dest
       [WITH POINTER Ptr]
       [ON OVERFLOW ...]
END-STRING.

UNSTRING Sorgente
    DELIMITED BY "," OR " "
    INTO Parte1, Parte2
    [DELIMITER IN DelChar]
    [COUNT IN NumChar]
    [WITH POINTER Ptr]
    [TALLYING IN Count]
    [ON OVERFLOW ...]
END-UNSTRING.

FUNCTION UPPER-CASE(Str)       *> tutto maiuscolo
FUNCTION LOWER-CASE(Str)       *> tutto minuscolo
FUNCTION LENGTH(Str)           *> lunghezza in caratteri
FUNCTION TRIM(Str [LEADING|TRAILING]) *> rimozione spazi
FUNCTION REVERSE(Str)          *> inverti stringa
FUNCTION CONCATENATE(S1, S2)   *> join (GnuCOBOL)
FUNCTION SUBSTITUTE(Str, Da, A) *> replace
FUNCTION NUMVAL(Str)           *> stringa → numero
FUNCTION NUMVAL-C(Str [,Symbol]) *> stringa valuta → num
FUNCTION CHAR(N)               *> numero → ASCII char
FUNCTION ORD(Ch)               *> char → posizione

*> Conta caratteri
INSPECT Str TALLYING
    Count1 FOR CHARACTERS
    Count2 FOR ALL 'e'
    Count3 FOR LEADING ' '.

*> Sostituisce caratteri
INSPECT Str REPLACING
    ALL     'a' BY '@'
    LEADING ' ' BY '0'
    FIRST   'X' BY 'Y'
    CHARACTERS BY '*'.

*> Combina TALLYING e REPLACING
INSPECT Str
    TALLYING  Cnt FOR ALL 'e'
    REPLACING ALL 'e' BY '3'.

*> CONVERTING (mappatura carattere per carattere)
INSPECT Str CONVERTING "aeiou" TO "AEIOU".

*> ─── BEFORE / AFTER INITIAL ───
*> Limita l'azione a una porzione della stringa

*> Conta le 'a' solo PRIMA della prima virgola
INSPECT Str TALLYING
    Cnt FOR ALL 'a' BEFORE INITIAL ','.

*> Conta le 'a' solo DOPO la prima virgola
INSPECT Str TALLYING
    Cnt FOR ALL 'a' AFTER INITIAL ','.

*> Sostituisci spazi con zeri solo prima del primo '.'
INSPECT NumStr REPLACING
    LEADING ' ' BY '0' BEFORE INITIAL '.'.

*> Conversione case solo dopo un separatore
INSPECT Str CONVERTING
    "abcdefghijklmnopqrstuvwxyz" TO
    "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
    AFTER INITIAL ":".

INITIALIZE imposta i campi ai valori di default per tipo: SPACES per alfanumerici, ZEROS per numerici. Molto più sicuro di MOVE SPACES su un intero gruppo.

*> Inizializza tutti i campi di un record ai default
INITIALIZE Cliente.
*> Equivale a: MOVE SPACES TO ogni PIC X, MOVE ZEROS TO ogni PIC 9

*> Inizializza solo i campi alfanumerici
INITIALIZE Cliente REPLACING ALPHANUMERIC DATA BY SPACES.

*> Inizializza solo i numerici con un valore specifico
INITIALIZE Tabella REPLACING NUMERIC DATA BY -1.

*> INITIALIZE con ALL (COBOL 2002+): resetta anche FILLER
INITIALIZE Record1 WITH FILLER.

*> Categorie disponibili per REPLACING:
*>   ALPHABETIC, ALPHANUMERIC, NUMERIC,
*>   ALPHANUMERIC-EDITED, NUMERIC-EDITED,
*>   NATIONAL, DBCS

*> DEFAULT (COBOL 2014+): usa i VALUE dichiarati nei campi
INITIALIZE Cliente TO VALUE.
*> Ripristina i VALUE originali dalla definizione in DATA DIVISION

*> Chiama un paragrafo
PERFORM NomeParagrafo.
PERFORM NomeParagrafo THRU AltroParagrafo.

*> Ripeti N volte
PERFORM 5 TIMES
    DISPLAY "Loop"
END-PERFORM.

*> While (test prima)
PERFORM UNTIL Indice > 10
    ADD 1 TO Indice
END-PERFORM.

*> Do-While (test dopo)
PERFORM WITH TEST AFTER UNTIL Indice > 10
    ADD 1 TO Indice
END-PERFORM.

*> For loop
PERFORM VARYING I FROM 1 BY 1 UNTIL I > 10
    DISPLAY I
END-PERFORM.

*> For loop annidato
PERFORM VARYING I FROM 1 BY 1 UNTIL I > 3
    AFTER J FROM 1 BY 1 UNTIL J > 3
        DISPLAY I " " J
END-PERFORM.

*> PERFORM con paragrafo esterno e VARYING
PERFORM StampaRiga VARYING I FROM 1 BY 1 UNTIL I > 5.

GO TO Paragrafo.
*> DEPENDING ON: switch su variabile
GO TO Para1, Para2, Para3
    DEPENDING ON Scelta.
*> EXIT: uscita da paragrafo/sezione
EXIT PARAGRAPH. *> esce dal paragrafo corrente
EXIT PROGRAM.   *> ritorna al chiamante
EXIT SECTION.   *> esce dalla sezione corrente
STOP RUN.       *> termina il programma

*> ─── ALTER (COBOL-68/74 — OBSOLETO) ───
*> Modifica a runtime la destinazione di un GO TO
Dispatch.
    GO TO DefaultHandler.
DefaultHandler.
    DISPLAY "Nessun handler".
SpecialHandler.
    DISPLAY "Handler speciale".

*> Cambia la destinazione di Dispatch
ALTER Dispatch TO PROCEED TO SpecialHandler.
*> Ora GO TO in Dispatch salta a SpecialHandler

Gravity (fall-through): in COBOL, l'esecuzione scorre sequenzialmente da un paragrafo al successivo, senza fermarsi. Un paragrafo non è una funzione: senza STOP RUN, GO TO o EXIT, il controllo "cade" nel paragrafo seguente.

PROCEDURE DIVISION.
Main.
    DISPLAY "Inizio".
    PERFORM CalcolaIVA.
    DISPLAY "Fatto".
    STOP RUN.           *> SENZA questo, cade in CalcolaIVA!

CalcolaIVA.
    COMPUTE TotaleIVA = Imponibile * 1.22.
    *> Senza STOP RUN sopra, dopo Main il controllo
    *> cadrebbe qui per gravity, eseguendo CalcolaIVA
    *> DUE VOLTE: una via PERFORM, una via fall-through.

Stampa.
    DISPLAY "Totale: " TotaleIVA.
    *> Dopo CalcolaIVA, cade qui per gravity

*> Una SECTION raggruppa più paragrafi
SezioneUno SECTION.
    ParagA.
        DISPLAY "A".
        *> Cade in ParagB per gravity
    ParagB.
        DISPLAY "B".
        EXIT SECTION.  *> Esce dalla sezione

*> PERFORM SezioneUno esegue TUTTI i paragrafi
*> della sezione (ParagA + ParagB) e poi ritorna.

*> Array 1D — subscript parte da 1!
01 Tabella1.
   02 Amico   PIC X(15) OCCURS 5 TIMES.

*> Array 2D
01 TabClienti.
   02 Cliente OCCURS 10 TIMES.
       03 CNome   PIC X(20).
       03 CEmail  PIC X(40).

*> Tabella con INDEX esplicito
01 OrdineTab.
   02 Prodotto OCCURS 5 TIMES INDEXED BY I.
       03 ProdNome PIC X(10).
       03 ProdSize OCCURS 3 TIMES INDEXED BY J.
           04 TipoTaglia PIC A.

*> OCCURS con range variabile (ODO)
01 MaxItems PIC 99 VALUE 10.
01 ListaDin.
   02 Elem PIC X(10) OCCURS 1 TO 20 TIMES
              DEPENDING ON MaxItems.

*> Accesso a elementi
MOVE 'Joy'    TO Amico(1).
DISPLAY        Amico(2).
SET I J TO 1.
MOVE 'S' TO   TipoTaglia(I, J).
SET I UP BY 1.   *> incremento index
SET I DOWN BY 1. *> decremento index

*> Tabella con ASCENDING/DESCENDING KEY (per SEARCH ALL)
01 CodTab.
   02 CodEntry OCCURS 100 TIMES
              ASCENDING KEY IS CodID
              INDEXED BY KI.
       03 CodID   PIC 9(5).
       03 CodDesc PIC X(30).

*> SORT: ordina un file tramite file di lavoro
SORT WorkFile
    ON ASCENDING KEY  WIDNum
    [ON DESCENDING KEY WNome]
    USING  OrgFile
    GIVING SortedFile.

*> SORT con INPUT/OUTPUT PROCEDURE
SORT WorkFile ON ASCENDING KEY WIDNum
    INPUT PROCEDURE  IS ReadAndFilter
    OUTPUT PROCEDURE IS WriteOutput.

*> MERGE: unisce file già ordinati
MERGE WorkFile ON ASCENDING KEY WIDNum
    USING  File1, File2
    GIVING NewFile.

*> RELEASE (dentro INPUT PROCEDURE) → aggiunge record al sort
RELEASE WStudData FROM StudData.
*> RETURN (dentro OUTPUT PROCEDURE) → legge record dal sort
RETURN WorkFile INTO StudData AT END MOVE 'Y' TO Done.

Le procedure permettono di filtrare/trasformare i record prima e dopo l'ordinamento.

SORT WorkFile ON ASCENDING KEY WIDNum
    INPUT PROCEDURE  IS FiltraInput
    OUTPUT PROCEDURE IS ScriviOutput.

*> ─── INPUT PROCEDURE: legge, filtra e passa al sort ───
FiltraInput.
    OPEN INPUT OrgFile.
    PERFORM UNTIL EOF
        READ OrgFile AT END SET EOF TO TRUE END-READ
        IF NOT EOF
            IF Stato = "A"              *> filtra: solo attivi
                RELEASE WStudData FROM StudData
            END-IF
        END-IF
    END-PERFORM.
    CLOSE OrgFile.

*> ─── OUTPUT PROCEDURE: legge dal sort e scrive ───
ScriviOutput.
    OPEN OUTPUT SortedFile.
    PERFORM UNTIL SortDone
        RETURN WorkFile INTO StudData
            AT END SET SortDone TO TRUE
        END-RETURN
        IF NOT SortDone
            ADD 1 TO RecCount       *> conteggio
            WRITE OutRec FROM StudData
        END-IF
    END-PERFORM.
    CLOSE SortedFile.

La gestione file in COBOL si articola su tre livelli distribuiti tra le divisioni. Comprendere la relazione tra questi livelli e' fondamentale per qualsiasi programma batch o transazionale.

INPUT-OUTPUT SECTION.
FILE-CONTROL.
    SELECT [OPTIONAL] nome-file-logico
        ASSIGN TO "percorso-fisico"  *> o variabile WS
        ORGANIZATION IS tipo-org       *> SEQUENTIAL | LINE SEQUENTIAL | INDEXED | RELATIVE
        ACCESS MODE IS tipo-accesso     *> SEQUENTIAL | RANDOM | DYNAMIC
        [RECORD KEY IS campo-chiave]    *> solo INDEXED
        [ALTERNATE RECORD KEY IS campo
            [WITH DUPLICATES]]          *> solo INDEXED
        [RELATIVE KEY IS campo]         *> solo RELATIVE
        [FILE STATUS IS ws-status]      *> PIC XX per controllo errori
        [LOCK MODE IS tipo-lock]        *> MANUAL | AUTOMATIC | EXCLUSIVE
        .

FILE SECTION.
FD nome-file-logico                    *> DEVE corrispondere al nome nel SELECT
    [BLOCK CONTAINS n RECORDS]        *> blocco fisico (performance I/O)
    [RECORD CONTAINS n CHARACTERS]    *> lunghezza record fissa
    [RECORD IS VARYING IN SIZE
        FROM min TO max CHARACTERS
        DEPENDING ON ws-len]            *> record a lunghezza variabile
    [LABEL RECORDS ARE STANDARD]       *> label tape (obsoleto, ma richiesto in alcuni dialect)
    [DATA RECORD IS nome-record]       *> informativo
    [LINAGE IS n LINES]              *> per file di stampa
    [REPORT IS nome-report]            *> per Report Writer
    .
*> Segue la definizione dei record (uno o piu' 01)
01 NomeRecord.
   02 Campo1 PIC ...
   02 Campo2 PIC ...

*> SD: Sort/merge file Descriptor (per file di lavoro SORT)
SD WorkFile.
01 WorkRecord.
   02 WKey   PIC 9(5).
   02 WData  PIC X(75).

Il legame e' basato sul nome-file-logico: il nome usato nel SELECT deve corrispondere esattamente a quello nell'FD. La SELECT definisce come si accede al file; la FD definisce cosa contiene il file.

*> ─── ENVIRONMENT DIVISION ───
FILE-CONTROL.
    SELECT ClienteFile               *> nome logico (1)
        ASSIGN TO "clienti.idx"      *> file fisico
        ORGANIZATION IS INDEXED        *> tipo organizzazione
        ACCESS MODE IS DYNAMIC         *> modalita' di accesso
        RECORD KEY IS CL-ID            *> chiave primaria (campo nel record FD)
        FILE STATUS IS WS-FS.

*> ─── DATA DIVISION ───
FILE SECTION.
FD ClienteFile                      *> stesso nome logico (1)
    RECORD CONTAINS 80 CHARACTERS.
01 ClienteRecord.
   02 CL-ID      PIC 9(5).          *> questa e' la RECORD KEY
   02 CL-Nome    PIC X(30).
   02 CL-Saldo   PIC S9(7)V99.
   02 FILLER     PIC X(36).

Il paragrafo I-O-CONTROL nella INPUT-OUTPUT SECTION specifica informazioni sul buffering, la condivisione di aree di memoria tra file, e il checkpoint/restart. E' opzionale ma importante per le ottimizzazioni I/O nei batch mainframe.

ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
    SELECT FileA ASSIGN TO "filea.dat".
    SELECT FileB ASSIGN TO "fileb.dat".
I-O-CONTROL.
    *> clausole di controllo I/O

I-O-CONTROL.
    *> Condivisione buffer: File1 e File2 usano la stessa area record
    *> (non possono essere letti contemporaneamente)
    SAME RECORD AREA FOR File1, File2.

    *> Checkpoint ogni 1000 record elaborati (mainframe)
    RERUN ON CheckFile EVERY 1000 RECORDS OF InputFile.

    *> Ottimizzazione scrittura (IBM)
    APPLY WRITE-ONLY ON OutputFile.

FILE-CONTROL.
SELECT ClienteFile
    ASSIGN TO "clienti.dat"
    ORGANIZATION IS LINE SEQUENTIAL
    ACCESS IS SEQUENTIAL
    [FILE STATUS IS WS-FileStatus].

*> Scrittura
OPEN OUTPUT ClienteFile.
    MOVE 1 TO IDNum.
    WRITE ClienteData [FROM WSCliente]
        [AFTER ADVANCING 1 LINE]
        [INVALID KEY DISPLAY "Errore"]
    END-WRITE.
CLOSE ClienteFile.

*> Lettura
OPEN INPUT ClienteFile.
PERFORM UNTIL EOF = 'Y'
    READ ClienteFile [INTO WSCliente]
        AT END MOVE 'Y' TO EOF
        NOT AT END DISPLAY WSCliente
    END-READ
END-PERFORM.
CLOSE ClienteFile.

*> Append
OPEN EXTEND ClienteFile.
    WRITE ClienteData.
CLOSE ClienteFile.

FILE-CONTROL.
SELECT ClienteFile ASSIGN TO "clienti.idx"
    ORGANIZATION IS INDEXED
    ACCESS MODE IS RANDOM    *> o DYNAMIC o SEQUENTIAL
    RECORD KEY IS IDNum
    [ALTERNATE RECORD KEY IS Cognome WITH DUPLICATES]
    FILE STATUS IS FS.

*> Aggiunta (WRITE)
OPEN I-O ClienteFile.
MOVE 99 TO IDNum.
WRITE ClienteData INVALID KEY DISPLAY "ID duplicato" END-WRITE.

*> Lettura per chiave (RANDOM)
MOVE 5 TO IDNum.
READ ClienteFile INVALID KEY DISPLAY "Non trovato" END-READ.

*> Aggiornamento
REWRITE ClienteData INVALID KEY DISPLAY "Errore" END-REWRITE.

*> Cancellazione
DELETE ClienteFile INVALID KEY DISPLAY "Non trovato" END-DELETE.

*> Lettura sequenziale (ACCESS DYNAMIC)
START ClienteFile KEY GREATER THAN IDNum
    INVALID KEY DISPLAY "Errore" END-START.
READ ClienteFile NEXT RECORD INTO WSCliente
    AT END MOVE 'Y' TO EOF END-READ.

Organizzazione RELATIVE: ogni record ha un numero relativo (posizione). Accesso diretto per numero, utile per tabelle di lookup su disco.

FILE-CONTROL.
SELECT SlotFile ASSIGN TO "slot.dat"
    ORGANIZATION IS RELATIVE
    ACCESS MODE IS DYNAMIC    *> o SEQUENTIAL o RANDOM
    RELATIVE KEY IS WS-Slot
    FILE STATUS IS WS-FS.

DATA DIVISION.
FILE SECTION.
FD SlotFile.
01 SlotRecord  PIC X(80).

WORKING-STORAGE SECTION.
01 WS-Slot  PIC 9(4).
01 WS-FS    PIC XX.

PROCEDURE DIVISION.
OPEN I-O SlotFile.

*> Scrittura diretta nello slot 5
MOVE 5 TO WS-Slot.
MOVE "Dati slot 5" TO SlotRecord.
WRITE SlotRecord INVALID KEY DISPLAY "Slot occupato" END-WRITE.

*> Lettura diretta per slot
MOVE 3 TO WS-Slot.
READ SlotFile INVALID KEY DISPLAY "Slot vuoto" END-READ.

*> Cancellazione
DELETE SlotFile INVALID KEY DISPLAY "Errore" END-DELETE.

*> Lettura sequenziale (ACCESS DYNAMIC)
MOVE 1 TO WS-Slot.
START SlotFile KEY NOT LESS THAN WS-Slot
    INVALID KEY DISPLAY "Errore" END-START.
READ SlotFile NEXT RECORD
    AT END DISPLAY "Fine" END-READ.

CLOSE SlotFile.

Il Report Writer (RW) automatizza intestazioni, piè pagina, subtotali e impaginazione. Richiede REPORT SECTION nella DATA DIVISION e verbi INITIATE/GENERATE/TERMINATE.

FILE-CONTROL.
SELECT ReportFile ASSIGN TO "report.txt".

FILE SECTION.
FD ReportFile REPORT IS VenditeReport.

REPORT SECTION.
RD VenditeReport
    CONTROLS ARE FINAL WS-Regione
    PAGE LIMIT IS 60 LINES
    HEADING 1
    FIRST DETAIL 5
    LAST DETAIL 55
    FOOTING 58.

*> PAGE HEADING — stampato in cima a ogni pagina
01 TYPE PAGE HEADING.
   02 LINE 1.
       03 COLUMN 1  PIC X(20) VALUE "REPORT VENDITE".
       03 COLUMN 60 PIC X(8)  SOURCE WS-Data.
   02 LINE 3.
       03 COLUMN 1  PIC X(10) VALUE "Regione".
       03 COLUMN 15 PIC X(10) VALUE "Prodotto".
       03 COLUMN 30 PIC X(10) VALUE "Importo".

*> CONTROL HEADING — all'inizio di ogni gruppo
01 TYPE CONTROL HEADING WS-Regione.
   02 LINE PLUS 1.
       03 COLUMN 1  PIC X(20) SOURCE WS-Regione.

*> DETAIL — riga di dettaglio per ogni GENERATE
01 RigaDettaglio TYPE DETAIL.
   02 LINE PLUS 1.
       03 COLUMN 15 PIC X(15) SOURCE WS-Prodotto.
       03 COLUMN 30 PIC $$$,$$9.99 SOURCE WS-Importo.

*> CONTROL FOOTING — alla fine di ogni gruppo (subtotale)
01 TYPE CONTROL FOOTING WS-Regione.
   02 LINE PLUS 1.
       03 COLUMN 20 PIC X(10) VALUE "Subtot:".
       03 COLUMN 30 PIC $$$,$$9.99 SUM WS-Importo.

*> REPORT FOOTING (FINAL) — totale generale
01 TYPE CONTROL FOOTING FINAL.
   02 LINE PLUS 2.
       03 COLUMN 20 PIC X(10) VALUE "TOTALE:".
       03 COLUMN 30 PIC $$$$,$$9.99 SUM WS-Importo.

*> PAGE FOOTING — piè pagina
01 TYPE PAGE FOOTING.
   02 LINE 58.
       03 COLUMN 30 PIC X(7)  VALUE "Pagina ".
       03 COLUMN 37 PIC Z9   SOURCE PAGE-COUNTER.

PROCEDURE DIVISION.
OPEN OUTPUT ReportFile.
INITIATE VenditeReport.       *> inizializza contatori e report

PERFORM UNTIL EOF
    READ InputFile AT END SET EOF TO TRUE END-READ
    GENERATE RigaDettaglio    *> produce una riga, gestisce automaticamente
                                *> page break, heading, footing, subtotali
END-PERFORM.

TERMINATE VenditeReport.      *> stampa gli ultimi footing e totali
CLOSE ReportFile.

*> Pattern alternativo con WRITE / ADVANCING
01 PrintLine  PIC X(80).
01 LineCount  PIC 99  VALUE ZERO.
       88 NuovaPagina VALUE 60 THRU 99.

WRITE PrintLine FROM Intestazione
    AFTER ADVANCING PAGE.
WRITE PrintLine FROM LineaDettaglio
    AFTER ADVANCING 1 LINE.
WRITE PrintLine FROM Separatore
    BEFORE ADVANCING 2 LINES.

*> GROUP INDICATE: stampa la regione solo sulla prima riga
01 RigaDettaglio TYPE DETAIL.
   02 LINE PLUS 1.
       03 COLUMN 1  PIC X(15) SOURCE WS-Regione
           GROUP INDICATE.           *> solo alla prima riga del gruppo
       03 COLUMN 20 PIC X(15) SOURCE WS-Prodotto.
       03 COLUMN 40 PIC $$$,$$9.99 SOURCE WS-Importo.

*> RESET ON: accumulatore che NON si azzera a ogni gruppo
01 TYPE CONTROL FOOTING WS-Regione.
   02 LINE PLUS 1.
       03 COLUMN 20 PIC X(12)     VALUE "Subtot:".
       03 COLUMN 40 PIC $$$,$$9.99 SUM WS-Importo.
       03 COLUMN 55 PIC $$$,$$9.99 SUM WS-Importo
           RESET ON FINAL.            *> totale progressivo, mai azzerato

*> USE BEFORE REPORTING: logica custom prima della stampa
DECLARATIVES.
Controllo-Dettaglio SECTION.
    USE BEFORE REPORTING RigaDettaglio.
Controllo-Dettaglio-Para.
    IF WS-Importo = 0
        SUPPRESS PRINTING          *> non stampare righe con importo zero
    END-IF.
END DECLARATIVES.

Il modulo viene caricato a runtime (dynamic linking). Il nome è risolto al momento dell'esecuzione. Richiede .so / .dll visibile.

CALL "nome-modulo" USING Arg1 Arg2.
*> Oppure con variabile
01 NomeModulo PIC X(20) VALUE "CALCOLA".
CALL NomeModulo USING Dati.   *> Risolto a runtime

Il modulo viene incorporato al momento della link (static linking). Richiede che tutti i moduli siano compilati insieme o linkati con -lnome.

*> Modo 1: flag compilatore (preferito)
cobc -x -fstatic-call main.cob MODULO.cob

*> Modo 2: direttiva nel sorgente (GnuCOBOL)
>>CALL-CONVENTION STATIC
CALL "CALCOLA" USING Dati.

*> Modo 3: con REPOSITORY (OO/moderni)
REPOSITORY.
    FUNCTION MiaFunzione
        AS "mia-funzione" IS STATIC.

CANCEL "nome-modulo".
*> Forza rilascio dalla memoria e reinizializza
*> le variabili globali del modulo alla prossima CALL

*> printf / puts
01 MsgBuf PIC X(80) VALUE "Ciao mondo!\n\x00".
CALL "puts"   USING BY REFERENCE MsgBuf.
CALL "printf" USING BY REFERENCE MsgBuf.

*> malloc / free
01 BufPtr  USAGE POINTER.
01 BufSize USAGE BINARY-LONG.
MOVE 1024 TO BufSize.
CALL "malloc" USING BY VALUE BufSize
    RETURNING BufPtr.
CALL "free"   USING BY VALUE BufPtr.

*> strlen
01 StrLen USAGE BINARY-LONG.
CALL "strlen" USING BY REFERENCE MsgBuf
    RETURNING StrLen.

*> memcpy
01 SrcBuf PIC X(100).
01 DstBuf PIC X(100).
01 BufLen USAGE BINARY-LONG VALUE 100.
CALL "memcpy"
    USING BY REFERENCE DstBuf
          BY REFERENCE SrcBuf
          BY VALUE     BufLen.

*> getenv
01 EnvPtr    USAGE POINTER.
01 EnvName   PIC X(20) VALUE "HOME\x00".
CALL "getenv" USING BY REFERENCE EnvName
    RETURNING EnvPtr.

*> system (shell command)
01 Cmd PIC X(80) VALUE "ls -l\x00".
CALL "system" USING BY REFERENCE Cmd.

*> CBL_OC_GETENV / CBL_OC_SETENV (GnuCOBOL native)
CALL "CBL_OC_GETENV"
    USING BY REFERENCE  EnvName
          BY REFERENCE  EnvValue.

*> CBL_GC_FORK (solo Unix)
CALL "CBL_GC_FORK" RETURNING PID.

*> Accesso a memoria tramite puntatore
01 RawPtr  USAGE POINTER.
01 ValAdr  USAGE BINARY-LONG BASED.
SET ADDRESS OF ValAdr TO RawPtr.
DISPLAY ValAdr.  *> deref del puntatore

*> open / read / write / close
01 FD-Sys   USAGE BINARY-LONG.
01 Flags    USAGE BINARY-LONG VALUE 0.    *> O_RDONLY=0
01 Mode     USAGE BINARY-LONG VALUE 0.
01 FilePath PIC X(40) VALUE "/etc/hostname\x00".
CALL "open"
    USING BY REFERENCE FilePath
          BY VALUE     Flags
          BY VALUE     Mode
    RETURNING FD-Sys.

01 Buffer   PIC X(256).
01 BufLen   USAGE BINARY-LONG VALUE 256.
01 BytesRd  USAGE BINARY-LONG.
CALL "read"
    USING BY VALUE     FD-Sys
          BY REFERENCE Buffer
          BY VALUE     BufLen
    RETURNING BytesRd.
CALL "close" USING BY VALUE FD-Sys.

CLASS-ID. todolist.
DATA DIVISION.
CLASS-STORAGE SECTION.
   01 ListName PIC X(20).
PROCEDURE DIVISION.
FACTORY.
   METHOD-ID. new.
   DATA DIVISION.
   LINKAGE SECTION.
       01 LName PIC X(20).
   PROCEDURE DIVISION USING LName
       RETURNING SELF.
       MOVE LName TO ListName.
       INVOKE SUPER "new"
           RETURNING SELF.
   END METHOD new.
END FACTORY.
END CLASS todolist.

REPOSITORY.
    CLASS TodoCls AS "todolist".
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WkTodo USAGE OBJECT REFERENCE TodoCls.

PROCEDURE DIVISION.
*> Crea istanza
INVOKE TodoCls "new"
    USING BY CONTENT "La mia lista"
    RETURNING WkTodo.
*> Chiama metodo
INVOKE WkTodo "PrintToDos".
*> Distruggi oggetto
INVOKE WkTodo "finalize".

CLASS-ID. Contatore.
DATA DIVISION.
CLASS-STORAGE SECTION.
   01 Valore PIC 9(5) VALUE ZERO.

PROCEDURE DIVISION.
FACTORY.
   METHOD-ID. new.
   PROCEDURE DIVISION RETURNING SELF.
       INVOKE SUPER "new" RETURNING SELF.
   END METHOD new.
END FACTORY.

OBJECT.
   *> Metodi di istanza (non FACTORY)
   METHOD-ID. Incrementa.
   PROCEDURE DIVISION.
       ADD 1 TO Valore.
   END METHOD Incrementa.

   METHOD-ID. GetValore.
   DATA DIVISION.
   LINKAGE SECTION.
       01 LVal PIC 9(5).
   PROCEDURE DIVISION RETURNING LVal.
       MOVE Valore TO LVal.
   END METHOD GetValore.
END OBJECT.
END CLASS Contatore.

*> Classe derivata che eredita da Contatore
CLASS-ID. ContatoreMax INHERITS Contatore.
DATA DIVISION.
CLASS-STORAGE SECTION.
   01 MaxVal PIC 9(5) VALUE 100.

PROCEDURE DIVISION.
OBJECT.
   *> Override del metodo Incrementa
   METHOD-ID. Incrementa OVERRIDE.
   PROCEDURE DIVISION.
       IF Valore < MaxVal
           INVOKE SUPER "Incrementa"
       END-IF.
   END METHOD Incrementa.
END OBJECT.
END CLASS ContatoreMax.

*> Definizione di un'interfaccia
INTERFACE-ID. Stampabile.
PROCEDURE DIVISION.
   METHOD-ID. Stampa.
   PROCEDURE DIVISION.
   END METHOD Stampa.
END INTERFACE Stampabile.

*> Classe che implementa l'interfaccia
CLASS-ID. Documento IMPLEMENTS Stampabile.
*> DEVE fornire implementazione di Stampa

*> Esempio pratico
01 CIntVal    USAGE BINARY-LONG.         *> int32_t
01 CUIntVal   USAGE BINARY-LONG UNSIGNED. *> uint32_t
01 CFloat     USAGE FLOAT-SHORT.          *> float
01 CDouble    USAGE FLOAT-LONG.           *> double
01 CString    PIC X(64).                  *> char[64]
01 CPtr       USAGE POINTER.              *> void*

// C
typedef struct {
    int32_t  id;
    char     nome[32];
    float    saldo;
    uint8_t  flag;
} Cliente;

*> COBOL equivalente
01 Cliente.
   02 ID      USAGE BINARY-LONG.
   02 Nome    PIC X(32).
   02 Saldo   USAGE FLOAT-SHORT.
   02 Flag    USAGE BINARY-CHAR UNSIGNED.

// C
union Dato {
    int32_t  intero;
    float    reale;
    char     bytes[4];
};

*> COBOL
01 DatoRaw   PIC X(4).
01 DatoInt   REDEFINES DatoRaw
               USAGE BINARY-LONG.
01 DatoFloat REDEFINES DatoRaw
               USAGE FLOAT-SHORT.

// C
typedef enum {
    APERTO = 0,
    CHIUSO = 1,
    ERRORE = 2
} Stato;

*> COBOL
01 StatoCod USAGE BINARY-LONG VALUE 0.
   88 APERTO   VALUE 0.
   88 CHIUSO   VALUE 1.
   88 ERRORE   VALUE 2.
*> Uso: SET APERTO TO TRUE.
*>      IF CHIUSO DISPLAY "Chiuso".

01 MioPtr    USAGE POINTER.
01 IntTarget USAGE BINARY-LONG BASED.  *> BASED = allocato via puntatore
01 FunzPtr   USAGE FUNCTION-POINTER.

*> Ottenere l'indirizzo di una variabile
SET MioPtr TO ADDRESS OF IntTarget.
*> Usare il puntatore (deref)
SET ADDRESS OF IntTarget TO MioPtr.
DISPLAY IntTarget.
*> NULL check
IF MioPtr = NULL
    DISPLAY "Puntatore nullo"
END-IF.
*> Puntatore a funzione (callback)
SET FunzPtr TO ENTRY "MiaFunzione".
CALL FunzPtr USING Parametro.

// C
int32_t valori[10];
valori[0] = 42;
valori[9] = 100;

*> COBOL (subscript parte da 1!)
01 TabellaValori.
   02 Valore USAGE BINARY-LONG
           OCCURS 10 TIMES.
MOVE  42  TO Valore(1).
MOVE 100  TO Valore(10).

// C
int32_t matrice[3][4];
matrice[1][2] = 7;

*> COBOL
01 Matrice.
   02 Riga OCCURS 3 TIMES INDEXED BY I.
       03 Cella USAGE BINARY-LONG
               OCCURS 4 TIMES INDEXED BY J.
SET I TO 2. SET J TO 3.
MOVE 7 TO Cella(I, J).

*> Stringa COBOL → C null-terminated
01 CobolStr  PIC X(30) VALUE "Ciao mondo".
01 CStr      PIC X(31).   *> +1 per \0
MOVE SPACES TO CStr.
MOVE CobolStr TO CStr.
*> Scrivere manualmente il terminatore null
MOVE X"00" TO CStr(FUNCTION LENGTH(
    FUNCTION TRIM(CobolStr)) + 1 : 1).

*> In alternativa con INSPECT
INSPECT CStr REPLACING TRAILING SPACES BY LOW-VALUES.

*> Stringa C → COBOL (pulizia null e padding)
INSPECT CStr REPLACING ALL X"00" BY SPACE.

*> Reference modification (substring)
*> variabile(start : lunghezza)
DISPLAY CobolStr(1 : 4).    *> "Ciao"
MOVE CobolStr(6 : 5) TO Parte2.  *> "mondo"

La SCREEN SECTION permette di costruire interfacce testuali interattive (TUI) tipo terminal. Richiede libreria curses/PDCurses. Compilare con cobc -x -lncurses prog.cob.

DATA DIVISION.
WORKING-STORAGE SECTION.
   01 WS-Nome     PIC X(30).
   01 WS-Eta      PIC 99.
   01 WS-Password PIC X(20).
   01 WS-Scelta   PIC 9.

SCREEN SECTION.
01 SchermoPrincipale
   BACKGROUND-COLOR 1    *> sfondo blu
   FOREGROUND-COLOR 7.   *> testo bianco
   *> Sfondo e titolo
   02 BLANK SCREEN.
   *> Titolo centrato riga 1
   02 LINE 1 COLUMN 30
         VALUE "=== GESTIONE CLIENTI ==="
         FOREGROUND-COLOR 6     *> giallo
         HIGHLIGHT.
   *> Label
   02 LINE 4 COLUMN 5
         VALUE "Nome: "
         FOREGROUND-COLOR 7.
   *> Campo input
   02 LINE 4 COLUMN 12
         PIC X(30)
         USING WS-Nome
         FOREGROUND-COLOR 3     *> ciano
         BACKGROUND-COLOR 0     *> nero
         REQUIRED AUTO.
   *> Età
   02 LINE 5 COLUMN 5
         VALUE "Eta:  ".
   02 LINE 5 COLUMN 12
         PIC 99 USING WS-Eta
         FOREGROUND-COLOR 6
         AUTO.
   *> Password con oscuramento
   02 LINE 6 COLUMN 5
         VALUE "Pass: ".
   02 LINE 6 COLUMN 12
         PIC X(20) TO WS-Password
         SECURE
         FOREGROUND-COLOR 6.
   *> Riga separatore
   02 LINE 8 COLUMN 1
         PIC X(80)
         VALUE ALL "-"
         FOREGROUND-COLOR 5.
   *> Messaggio stato
   02 LINE 22 COLUMN 1
         VALUE "F1=Aiuto  F3=Esci  INVIO=Conferma"
         REVERSE-VIDEO.

*> Schermo di sola visualizzazione
01 SchermoOutput.
   02 BLANK SCREEN.
   02 LINE 5 COLUMN 10
         VALUE "Risultato: ".
   02 LINE 5 COLUMN 22
         PIC X(40) FROM WS-Nome
         HIGHLIGHT.

PROCEDURE DIVISION.
   *> Visualizza e gestisce input
   DISPLAY SchermoPrincipale.
   ACCEPT  SchermoPrincipale.
   *> Solo visualizzazione
   DISPLAY SchermoOutput.
   *> Posizionamento diretto (senza SCREEN SECTION)
   DISPLAY "Testo" AT LINE 10 COLUMN 5
       FOREGROUND-COLOR 2.
   *> ACCEPT con posizionamento
   ACCEPT WS-Scelta AT LINE 10 COLUMN 20.

cobc [opzioni] file.cob [file2.cob ...] [-l libreria]

# Compila ed esegui
cobc -x hello.cob
./hello

# Free format esplicito
cobc -x -free hello.cob

# Con output rinominato
cobc -x -o programma hello.cob

# Solo il C generato (debug compilazione)
cobc -C hello.cob
cat hello.c

# Tutto in un colpo (statico)
cobc -x main.cob GETSUM.cob UTILS.cob

# Compila i moduli come shared library
cobc -m GETSUM.cob         # → GETSUM.so
cobc -m UTILS.cob          # → UTILS.so
# Compila il main (le CALL verranno risolte a runtime)
cobc -x main.cob           # → main
./main                     # cerca GETSUM.so, UTILS.so in COB_LIBRARY_PATH

# Compila oggetti C
cobc -C GETSUM.cob         # genera GETSUM.c
gcc -c GETSUM.c -o GETSUM.o $(cob-config --cflags)
# Link finale
cobc -x -fstatic-call main.cob GETSUM.o

*> COPY include un file .cpy o .cob come testo
COPY STDDEF.          *> cerca STDDEF.cpy in COB_COPY_DIR
COPY "include/common.cpy" REPLACING
    ==PREFISSO== BY ==WS==.   *> sostituzione testo

# Compilare con libmath, libncurses, ecc.
cobc -x prog.cob -lm -lncurses
# Libreria custom statica
cobc -x prog.cob -L/usr/local/lib -lmialib

# Linking con libreria dinamica
cobc -x prog.cob -ldl        # libdl per dlopen
export LD_LIBRARY_PATH=/path/to/libs:$LD_LIBRARY_PATH
./prog

*> Per usare funzioni da libm (math.h)
01 Angolo  USAGE FLOAT-LONG.
01 Coseno  USAGE FLOAT-LONG.
MOVE 1.5707963 TO Angolo.
CALL "cos"   USING BY VALUE Angolo   RETURNING Coseno.
CALL "sin"   USING BY VALUE Angolo   RETURNING Risultato.
CALL "sqrt"  USING BY VALUE Valore   RETURNING Radice.
CALL "pow"   USING BY VALUE Base Esp RETURNING Pot.
CALL "fabs"  USING BY VALUE Num      RETURNING Abs.
CALL "floor" USING BY VALUE Num      RETURNING Floor.
CALL "ceil"  USING BY VALUE Num      RETURNING Ceil.

*> Compilare: cobc -x prog.cob -lm

COBC    = cobc
COBFLAGS= -x -free -Wall -debug
LIBS    = -lncurses -lm

all: mioprog

mioprog: main.cob modulo1.cob modulo2.cob
    $(COBC) $(COBFLAGS) -o $@ $^ $(LIBS)

modulo1.so: modulo1.cob
    $(COBC) -m -free modulo1.cob

clean:
    rm -f mioprog *.so *.o *.c

Il metodo più comune: controllare il FILE STATUS dopo ogni operazione I/O.

FILE-CONTROL.
SELECT ClienteFile ASSIGN TO "clienti.dat"
    FILE STATUS IS WS-FS.

WORKING-STORAGE SECTION.
01 WS-FS  PIC XX.
   88 FS-OK     VALUE "00".
   88 FS-EOF    VALUE "10".
   88 FS-NOTFND VALUE "23".
   88 FS-DUPKEY VALUE "22".

OPEN INPUT ClienteFile.
IF NOT FS-OK
    DISPLAY "Errore apertura: " WS-FS
    STOP RUN
END-IF.

Le DECLARATIVES sono sezioni speciali nella PROCEDURE DIVISION che vengono invocate automaticamente dal runtime quando si verifica un errore I/O, una condizione di debug, o una label di report. Devono essere dichiarate prima di qualsiasi altro codice nella PROCEDURE DIVISION, racchiuse tra DECLARATIVES. e END DECLARATIVES.

PROCEDURE DIVISION.
DECLARATIVES.

*> Handler per errori su un file specifico
Errore-Clienti SECTION.
    USE AFTER STANDARD ERROR PROCEDURE ON ClienteFile.
Errore-Clienti-Para.
    DISPLAY "Errore I/O su ClienteFile: " WS-FS.
    EVALUATE WS-FS
        WHEN "35" DISPLAY "File non trovato"
        WHEN "30" DISPLAY "Errore I/O permanente"
        WHEN "41" DISPLAY "File gia' aperto"
        WHEN OTHER DISPLAY "Errore non previsto"
    END-EVALUATE.
    STOP RUN.

*> Handler generico per TUTTI i file in INPUT
Errore-Input SECTION.
    USE AFTER STANDARD ERROR PROCEDURE ON INPUT.
Errore-Input-Para.
    DISPLAY "Errore lettura generico: " WS-FS.

*> Handler per debug su un paragrafo (richiede DEBUGGING MODE)
Debug-Calcolo SECTION.
    USE FOR DEBUGGING ON CalcolaIVA.
Debug-Calcolo-Para.
    DISPLAY "[DEBUG] Entrato in CalcolaIVA"
    DISPLAY "  Riga:  " DEBUG-LINE
    DISPLAY "  Nome:  " DEBUG-NAME.

END DECLARATIVES.

*> ─── Dopo END DECLARATIVES: logica normale ───
Main-Logic SECTION.
Main-Para.
    OPEN INPUT ClienteFile.
    *> Se OPEN fallisce, il runtime chiama
    *> automaticamente Errore-Clienti SECTION
    PERFORM UNTIL EOF-Reached
        READ ClienteFile
            AT END SET EOF-Reached TO TRUE
        END-READ
    END-PERFORM.
    CLOSE ClienteFile.
    STOP RUN.

READ ClienteFile
    AT END
        SET EOF-Flag TO TRUE
    NOT AT END
        PERFORM ProcessaRecord
END-READ.

WRITE ClienteData
    INVALID KEY
        DISPLAY "Chiave duplicata o errore"
    NOT INVALID KEY
        ADD 1 TO RecordCount
END-WRITE.

ADD A TO B
    ON SIZE ERROR
        DISPLAY "Overflow aritmetico!"
        MOVE ZEROS TO B
    NOT ON SIZE ERROR
        CONTINUE
END-ADD.

COMPUTE Result = X / Y
    ON SIZE ERROR
        DISPLAY "Divisione per zero o overflow"
END-COMPUTE.

CALL "MODULO-ESTERNO" USING Dati
    ON EXCEPTION
        DISPLAY "Modulo non trovato o errore nel caricamento"
    NOT ON EXCEPTION
        DISPLAY "Chiamata riuscita"
END-CALL.

*> Exception handling moderno (supporto limitato nei compilatori)

*> RAISE: solleva un'eccezione
RAISE EXCEPTION EC-DATA-INCOMPATIBLE.

*> >>TURN: attiva il monitoraggio di eccezioni specifiche
>>TURN EC-SIZE CHECKING ON
>>TURN EC-BOUND CHECKING ON
>>TURN EC-DATA CHECKING ON

*> RESUME: dentro un handler, riprende l'esecuzione
*> RESUME AT NEXT STATEMENT — riprende dal punto successivo
*>                           all'istruzione che ha causato l'eccezione

*> Esempio: handler con RESUME
DECLARATIVES.
Err-Bound SECTION.
    USE AFTER EXCEPTION CONDITION EC-BOUND.
Err-Bound-Para.
    DISPLAY "Indice fuori range".
    RESUME AT NEXT STATEMENT.  *> continua dopo l'errore
END DECLARATIVES.

Da COBOL-85 è possibile annidare programmi all'interno di un programma contenitore. Ogni programma annidato ha il proprio scope di dati. Alternativa a CALL con moduli separati.

IDENTIFICATION DIVISION.
PROGRAM-ID. ProgrammaEsterno.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 Risultato   PIC 9(6) VALUE ZEROS.
01 Dato1       PIC 9(3) VALUE 100.
01 Dato2       PIC 9(3) VALUE 200.

PROCEDURE DIVISION.
    CALL "Calcolatore" USING Dato1 Dato2 Risultato.
    DISPLAY "Risultato: " Risultato.
    STOP RUN.

    *> ─── Programma annidato ───
    IDENTIFICATION DIVISION.
    PROGRAM-ID. Calcolatore.
    DATA DIVISION.
    WORKING-STORAGE SECTION.
    01 Temporaneo PIC 9(6).
    LINKAGE SECTION.
    01 L-A        PIC 9(3).
    01 L-B        PIC 9(3).
    01 L-Result   PIC 9(6).

    PROCEDURE DIVISION USING L-A L-B L-Result.
        COMPUTE L-Result = L-A + L-B.
    END PROGRAM Calcolatore.

END PROGRAM ProgrammaEsterno.

*> COMMON: il programma annidato è visibile anche dai fratelli
PROGRAM-ID. Utilita IS COMMON.

*> INITIAL: il programma viene reinizializzato ad ogni CALL
PROGRAM-ID. Contatore IS INITIAL.
*> Tutte le variabili tornano al VALUE originale ad ogni invocazione

*> GLOBAL: variabili visibili nei programmi annidati
01 SharedData PIC X(50) IS GLOBAL.
*> I programmi figli possono accedere a SharedData senza LINKAGE

I registri speciali sono variabili predefinite dal compilatore, disponibili senza dichiarazione in WORKING-STORAGE.

*> RETURN-CODE: comunicazione tra programmi
CALL "VALIDATORE" USING Dati.
IF RETURN-CODE NOT = 0
    DISPLAY "Validazione fallita, codice: " RETURN-CODE
END-IF.

*> Impostare il return code per il chiamante
MOVE 0 TO RETURN-CODE.
STOP RUN.       *> il sistema vede exit code 0

*> GOBACK al posto di STOP RUN (nei sottoprogrammi)
MOVE 4 TO RETURN-CODE.
GOBACK.          *> ritorna al chiamante, RC=4

*> SORT-STATUS: controllo dopo SORT
SORT WorkFile ON ASCENDING KEY WKey
    USING InFile GIVING OutFile.
IF SORT-STATUS NOT = 0
    DISPLAY "Errore SORT: " SORT-STATUS
END-IF.

*> NUMBER-OF-CALL-PARAMETERS (GnuCOBOL)
*> Utile per parametri opzionali in sottoprogrammi
IF NUMBER-OF-CALL-PARAMETERS < 3
    MOVE SPACES TO LParam3   *> default se non passato
END-IF.

*> COB-CRT-STATUS: rilevare tasti funzione (GnuCOBOL)
*> Richiede: SET ENVIRONMENT "COB_SCREEN_EXCEPTIONS" TO "Y"
ACCEPT WS-Campo AT LINE 5 COLUMN 10.
EVALUATE COB-CRT-STATUS
    WHEN 0    CONTINUE          *> Enter
    WHEN 1001 PERFORM Aiuto     *> F1
    WHEN 1003 STOP RUN         *> F3 = Esci
    WHEN 2005 CONTINUE         *> PgDn
END-EVALUATE.

Permette di accedere a una porzione di un campo alfanumerico senza definire sottocampi. Sintassi: campo(posizione : lunghezza). Posizione parte da 1.

01 Frase PIC X(20) VALUE "HELLO WORLD".

*> Estrazione substring
DISPLAY Frase(1 : 5).        *> "HELLO"
DISPLAY Frase(7 : 5).        *> "WORLD"

*> Lunghezza opzionale: dal punto fino alla fine
DISPLAY Frase(7 :).           *> "WORLD         " (fino alla fine)

*> Modifica in-place
MOVE "CIAO" TO Frase(1 : 4). *> "CIAOO WORLD"

*> Posizione e lunghezza possono essere variabili
01 Pos  PIC 99 VALUE 3.
01 Len  PIC 99 VALUE 4.
DISPLAY Frase(Pos : Len).     *> 4 caratteri dalla posizione 3

*> Su campi di gruppo (trattati come alfanumerici)
01 DataGrezza PIC X(8) VALUE "20241225".
DISPLAY DataGrezza(1 : 4).   *> "2024" (anno)
DISPLAY DataGrezza(5 : 2).   *> "12"   (mese)
DISPLAY DataGrezza(7 : 2).   *> "25"   (giorno)

*> Con FUNCTION LENGTH per calcoli dinamici
MOVE "!" TO Frase(FUNCTION LENGTH(Frase) : 1).
*> Mette "!" nell'ultima posizione

COBOL 2014 introduce la gestione dinamica della memoria, finora assente nel linguaggio. Queste feature hanno supporto limitato nei compilatori.

*> Tabella con dimensione allocata a runtime
01 TabDinamica.
   02 NumElementi PIC 9(5).
   02 Elemento PIC X(20)
       OCCURS DYNAMIC
       CAPACITY IN NumElementi.

*> Ridimensiona a runtime
ALLOCATE 100 CHARACTERS RETURNING Elemento.
*> oppure
ALLOCATE Elemento.

*> ALLOCATE: alloca memoria dinamica
01 Ptr USAGE POINTER.
01 Buffer PIC X(1024) BASED.

*> Alloca e associa a una variabile BASED
ALLOCATE Buffer RETURNING Ptr.

*> Alloca N caratteri generici
ALLOCATE 4096 CHARACTERS RETURNING Ptr
    ON EXCEPTION
        DISPLAY "Memoria insufficiente".

*> FREE: rilascia memoria allocata
FREE Ptr.
*> Dopo FREE, Ptr è NULL e Buffer non è più accessibile

Da COBOL 2002/2014: direttive del preprocessore per includere/escludere codice a compile time. Sintassi: >> in colonna 7+ (free) o colonna 7 (fixed).

*> Definizione costante di compilazione
>>DEFINE VERSIONE AS 2
>>DEFINE DEBUG-MODE AS 1
>>DEFINE PIATTAFORMA AS "LINUX"

*> Condizionale semplice
>>IF DEBUG-MODE = 1
    DISPLAY "[DEBUG] Valore: " Variabile.
>>END-IF

*> IF / ELSE
>>IF PIATTAFORMA = "LINUX"
    CALL "system" USING BY REFERENCE CmdLinux.
>>ELSE
    CALL "system" USING BY REFERENCE CmdWindows.
>>END-IF

*> Verifica se definito
>>IF VERSIONE IS DEFINED
    DISPLAY "Versione attiva".
>>END-IF

>>IF MODULO-EXTRA IS NOT DEFINED
    DISPLAY "Modulo extra non disponibile".
>>END-IF

*> Definizione da riga di comando (GnuCOBOL)
cobc -x -D DEBUG-MODE=1 -D PIATTAFORMA="LINUX" prog.cob

*> Attivazione/disattivazione in cascata
>>DEFINE LIVELLO AS 3
>>IF LIVELLO >= 2
    PERFORM LogDettagliato.
>>END-IF
>>IF LIVELLO >= 3
    PERFORM LogVerbose.
>>END-IF

La clausola COPY include testo da un copybook (.cpy) esterno. REPLACING permette sostituzioni testuali al momento dell'inclusione, fondamentale per il riuso delle strutture dati.

*> COPY base
COPY nome-copybook.
COPY "path/to/copybook.cpy".

*> COPY con REPLACING (pseudo-text delimiters ==...==)
COPY RECDEF REPLACING
    ==:PREFIX:== BY ==WS-CLI==
    ==:SIZE:==   BY ==100==.

*> REPLACING multipli sullo stesso COPY
COPY SQLTAB REPLACING
    ==:TABLE:==  BY ==CLIENTI==
    ==:KEY:==    BY ==ID-CLIENTE==
    ==:REC:==    BY ==REC-CLI==.

*> ─── File: RECDEF.cpy ───
01 :PREFIX:-Record.
   02 :PREFIX:-ID    PIC 9(5).
   02 :PREFIX:-Nome  PIC X(30).
   02 :PREFIX:-Stato PIC X.

*> ─── Nel programma: istanzia due volte ───
COPY RECDEF REPLACING ==:PREFIX:== BY ==WS-CLI==.
*> Genera: 01 WS-CLI-Record. 02 WS-CLI-ID PIC 9(5). ...

COPY RECDEF REPLACING ==:PREFIX:== BY ==WS-FOR==.
*> Genera: 01 WS-FOR-Record. 02 WS-FOR-ID PIC 9(5). ...

*> REPLACE opera su TUTTO il sorgente (non solo COPY)
REPLACE ==VECCHIO-NOME== BY ==NUOVO-NOME==.
*> Da qui in poi, ogni occorrenza viene sostituita

*> Disattivare REPLACE
REPLACE OFF.

Il file locking controlla l'accesso concorrente quando più programmi o thread accedono allo stesso file. Definito nella clausola SELECT e nei verbi I/O.

SELECT ClienteFile ASSIGN TO "clienti.dat"
    ORGANIZATION IS INDEXED
    ACCESS MODE IS DYNAMIC
    LOCK MODE IS MANUAL         *> lock esplicito per record
    WITH LOCK ON MULTIPLE RECORDS
    FILE STATUS IS WS-FS.

*> READ con lock esplicito (LOCK MODE MANUAL)
READ ClienteFile
    WITH LOCK                   *> blocca il record
    KEY IS IDCliente
    INVALID KEY DISPLAY "Non trovato"
END-READ.

*> READ senza lock (solo lettura)
READ ClienteFile
    WITH NO LOCK                *> non blocca
    KEY IS IDCliente
END-READ.

*> UNLOCK: rilascia i lock sul file
UNLOCK ClienteFile RECORDS.   *> rilascia tutti i record lockati
UNLOCK ClienteFile RECORD.    *> rilascia solo il record corrente

*> OPEN con sharing (chi altro può aprire il file)
OPEN I-O ClienteFile WITH LOCK. *> lock esclusivo
OPEN INPUT ClienteFile
    SHARING WITH ALL OTHER.      *> condiviso in lettura
OPEN I-O ClienteFile
    SHARING WITH NO OTHER.       *> esclusivo
OPEN I-O ClienteFile
    SHARING WITH READ ONLY.      *> altri possono solo leggere

Da COBOL 2014, con supporto in GnuCOBOL 3.x+, IBM Enterprise COBOL V6.2+ e Micro Focus.

WORKING-STORAGE SECTION.
01 Prodotto.
   02 ProdID     PIC 9(5) VALUE 12345.
   02 ProdNome   PIC X(20) VALUE "Widget".
   02 ProdPrezzo PIC 9(5)V99 VALUE 49.99.
   02 ProdAttivo PIC 9 VALUE 1.
01 JsonOutput PIC X(500).
01 JsonLen    PIC 9(5).

*> Generazione base
JSON GENERATE JsonOutput FROM Prodotto
    COUNT IN JsonLen
    ON EXCEPTION
        DISPLAY "Errore JSON GENERATE"
    NOT ON EXCEPTION
        DISPLAY JsonOutput(1 : JsonLen)
END-JSON.
*> Output: {"ProdID":12345,"ProdNome":"Widget","ProdPrezzo":49.99,"ProdAttivo":1}

*> Con NAME (rinomina chiavi JSON)
JSON GENERATE JsonOutput FROM Prodotto
    COUNT IN JsonLen
    NAME OF ProdID IS "id"
             ProdNome IS "name"
             ProdPrezzo IS "price"
             ProdAttivo IS "active"
END-JSON.
*> Output: {"id":12345,"name":"Widget","price":49.99,"active":1}

*> Con SUPPRESS (escludi campi)
JSON GENERATE JsonOutput FROM Prodotto
    COUNT IN JsonLen
    SUPPRESS ProdAttivo
END-JSON.

01 JsonInput  PIC X(500)
    VALUE '{"id":99,"name":"Gadget","price":19.99}'.
01 ParsedProd.
   02 ProdID     PIC 9(5).
   02 ProdNome   PIC X(20).
   02 ProdPrezzo PIC 9(5)V99.

JSON PARSE JsonInput INTO ParsedProd
    NAME OF ProdID IS "id"
             ProdNome IS "name"
             ProdPrezzo IS "price"
    ON EXCEPTION
        DISPLAY "Errore parsing JSON"
    NOT ON EXCEPTION
        DISPLAY "ID: " ProdID
        DISPLAY "Nome: " ProdNome
        DISPLAY "Prezzo: " ProdPrezzo
END-JSON.

*> Sintassi analoga a JSON
01 XmlOutput PIC X(1000).
01 XmlLen    PIC 9(5).

XML GENERATE XmlOutput FROM Prodotto
    COUNT IN XmlLen
    WITH ATTRIBUTES       *> oppure WITH ENCODING (UTF-8, ecc.)
    ON EXCEPTION
        DISPLAY "Errore XML"
END-XML.

XML PARSE XmlInput
    PROCESSING PROCEDURE IS HandleXml
END-XML.
*> HandleXml riceve eventi SAX: XML-EVENT, XML-TEXT, XML-NTEXT

COBOL su mainframe IBM usa Embedded SQL per interagire con DB2. Le istruzioni SQL sono racchiuse tra EXEC SQL e END-EXEC. Il precompilatore DB2 le converte in chiamate al database prima della compilazione COBOL.

WORKING-STORAGE SECTION.

*> SQLCA: area di comunicazione SQL (obbligatoria)
EXEC SQL INCLUDE SQLCA END-EXEC.

*> Host variables: variabili COBOL usate nelle query
01 WS-ID      PIC 9(5).
01 WS-Nome    PIC X(30).
01 WS-Saldo   PIC S9(9)V99 COMP-3.
01 WS-Ind     PIC S9(4) COMP.  *> indicator variable (null check)

*> SELECT singola riga (INTO host variables)
EXEC SQL
    SELECT NOME, SALDO
    INTO :WS-Nome, :WS-Saldo:WS-Ind
    FROM CLIENTI
    WHERE ID = :WS-ID
END-EXEC.
*> :WS-Ind = -1 se SALDO è NULL

*> INSERT
EXEC SQL
    INSERT INTO CLIENTI (ID, NOME, SALDO)
    VALUES (:WS-ID, :WS-Nome, :WS-Saldo)
END-EXEC.

*> UPDATE
EXEC SQL
    UPDATE CLIENTI SET SALDO = :WS-Saldo
    WHERE ID = :WS-ID
END-EXEC.

*> DELETE
EXEC SQL
    DELETE FROM CLIENTI
    WHERE ID = :WS-ID
END-EXEC.

*> Dichiarazione cursore
EXEC SQL
    DECLARE CUR-CLIENTI CURSOR FOR
    SELECT ID, NOME, SALDO FROM CLIENTI
    WHERE SALDO > :WS-MinSaldo
    ORDER BY NOME
END-EXEC.

*> Apertura, lettura, chiusura
EXEC SQL OPEN CUR-CLIENTI END-EXEC.

PERFORM UNTIL SQLCODE NOT = 0
    EXEC SQL
        FETCH CUR-CLIENTI
        INTO :WS-ID, :WS-Nome, :WS-Saldo
    END-EXEC
    IF SQLCODE = 0
        DISPLAY WS-ID " " WS-Nome " " WS-Saldo
    END-IF
END-PERFORM.

EXEC SQL CLOSE CUR-CLIENTI END-EXEC.

*> Gestione errori tipica
EVALUATE SQLCODE
    WHEN 0    CONTINUE
    WHEN 100  DISPLAY "Nessun dato trovato"
    WHEN -803 DISPLAY "Chiave duplicata"
    WHEN OTHER
        DISPLAY "Errore SQL: " SQLCODE
        DISPLAY "Messaggio: " SQLERRMC
END-EVALUATE.

CICS (Customer Information Control System) è il transaction monitor IBM per applicazioni online su mainframe. I programmi COBOL/CICS gestiscono transazioni interattive (schermate 3270, servizi web) tramite comandi EXEC CICS.

*> Differenze rispetto a COBOL batch:
*> - NON usare ACCEPT, DISPLAY, OPEN, READ, WRITE, CLOSE
*> - NON usare STOP RUN (usare EXEC CICS RETURN)
*> - I/O solo tramite EXEC CICS (SEND MAP, RECEIVE MAP, READ FILE, ecc.)

IDENTIFICATION DIVISION.
PROGRAM-ID. CICSPGM.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-Resp    PIC S9(8) COMP.
01 WS-Resp2   PIC S9(8) COMP.
01 WS-Data    PIC X(100).

PROCEDURE DIVISION.
    EXEC CICS HANDLE CONDITION
        ERROR(Errore-Para)
    END-EXEC.
    PERFORM Logica-Main.
    EXEC CICS RETURN END-EXEC.

Errore-Para.
    EXEC CICS SEND TEXT FROM("Errore!")
        LENGTH(7) ERASE END-EXEC.
    EXEC CICS RETURN END-EXEC.

EXEC CICS READ FILE('CUSTFILE')
    INTO(WS-Data)
    RIDFLD(WS-Key)
    LENGTH(WS-Len)
    RESP(WS-Resp)
    RESP2(WS-Resp2)
END-EXEC.

EVALUATE WS-Resp
    WHEN DFHRESP(NORMAL)   PERFORM Processa
    WHEN DFHRESP(NOTFND)   DISPLAY "Non trovato"
    WHEN DFHRESP(DISABLED) DISPLAY "File disabilitato"
    WHEN OTHER
        DISPLAY "Errore CICS RESP=" WS-Resp
END-EVALUATE.

Su mainframe IBM (z/OS), i programmi COBOL batch vengono eseguiti tramite JCL (Job Control Language). Il JCL definisce l'ambiente di esecuzione: file fisici, librerie, parametri e risorse.

//MYJOB   JOB (ACCT),'NOME',CLASS=A,MSGCLASS=X
//*
//STEP1   EXEC PGM=MIOPROG
//STEPLIB  DD  DSN=MY.LOAD.LIB,DISP=SHR
//*
// Associazione file logici COBOL → dataset fisici z/OS
//CLIENTI  DD  DSN=PROD.CLIENTI.VSAM,DISP=SHR
//REPORT   DD  DSN=PROD.REPORT.OUTPUT,
//             DISP=(NEW,CATLG,DELETE),
//             SPACE=(CYL,(5,2)),
//             DCB=(RECFM=FB,LRECL=80,BLKSIZE=0)
//SYSOUT   DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*

//COMPILE EXEC PGM=IGYCRCTL,PARM='RENT,OPT(2)'
//SYSIN    DD  DSN=MY.SOURCE.LIB(MIOPROG),DISP=SHR
//SYSLIB   DD  DSN=MY.COPYBOOK.LIB,DISP=SHR
//SYSLIN   DD  DSN=&&OBJ,DISP=(NEW,PASS),SPACE=(CYL,1)
//SYSPRINT DD  SYSOUT=*
//*
//LKED    EXEC PGM=IEWL,PARM='RENT,LIST,MAP'
//SYSLIN   DD  DSN=&&OBJ,DISP=(OLD,DELETE)
//SYSLMOD  DD  DSN=MY.LOAD.LIB(MIOPROG),DISP=SHR
//SYSPRINT DD  SYSOUT=*
//*
//RUN     EXEC PGM=MIOPROG
//STEPLIB  DD  DSN=MY.LOAD.LIB,DISP=SHR

*> Nel programma COBOL: imposta il codice di ritorno
MOVE 0 TO RETURN-CODE.   *> successo
MOVE 4 TO RETURN-CODE.   *> warning
MOVE 8 TO RETURN-CODE.   *> errore
MOVE 16 TO RETURN-CODE.  *> errore grave

// Nel JCL: condiziona i passi successivi
//STEP2   EXEC PGM=PROG2,COND=(4,LT,STEP1)
//* Esegue STEP2 solo se RETURN-CODE di STEP1 >= 4
//*
// Con IF/THEN/ELSE (JCL moderno):
//  IF (STEP1.RC = 0) THEN
//STEP2   EXEC PGM=PROG2
//  ELSE
//STEPERR EXEC PGM=ERRPGM
//  ENDIF

*> 'D' in colonna 7 = riga di debug (compilata solo con -fdebugging-line)
      *  Codice normale:
       MOVE 42 TO Valore.
      D DISPLAY "DEBUG: Valore = " Valore.

*> Attivazione:
cobc -x -fdebugging-line prog.cob
*> Senza il flag, le righe D sono ignorate dal compilatore.

# Compilazione per debugging completo
cobc -x -debug -g -fsource-location -Wall prog.cob

# Esecuzione con tracing a runtime
export COB_SET_TRACE=Y
./prog
# Stampa ogni statement eseguito: Source: 'prog.cob', Line: 42, ...

# Redirect trace su file
export COB_TRACE_FILE=debug.log
./prog

# Debug con gdb
cobc -x -g prog.cob
gdb ./prog
# In gdb: break cob_stop_run per fermarsi prima dell'uscita
# In gdb: print b_42 per vedere variabile dichiarata alla riga 42

*> Richiede SOURCE-COMPUTER con WITH DEBUGGING MODE
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. X86 WITH DEBUGGING MODE.

PROCEDURE DIVISION.
DECLARATIVES.
Debug-Handler SECTION.
    USE FOR DEBUGGING ON CalcolaIVA.
Debug-Para.
    DISPLAY "Entrato in CalcolaIVA"
    DISPLAY "DEBUG-LINE: " DEBUG-LINE
    DISPLAY "DEBUG-NAME: " DEBUG-NAME.
END DECLARATIVES.

*> DEBUG-ITEM contiene:
*>   DEBUG-LINE    - numero riga sorgente
*>   DEBUG-NAME    - nome del paragrafo/variabile monitorata
*>   DEBUG-CONTENTS - contenuto (valore precedente, se variabile)

*> Pattern: trace manuale con timestamp
01 WS-Debug-Ts PIC X(21).
MOVE FUNCTION CURRENT-DATE TO WS-Debug-Ts.
DISPLAY "[" WS-Debug-Ts "] CalcolaIVA: Imp="
    Imponibile " IVA=" TotaleIVA.

*> Pattern: dump di un record
DISPLAY "=== DUMP Cliente ===".
DISPLAY "  ID: ["   IDCliente   "]".
DISPLAY "  Nome: [" NomeCliente "]".
DISPLAY "  HEX: " FUNCTION ORD(IDCliente(1:1)).

*> Pattern: validazione invarianti
IF Totale < 0
    DISPLAY "ASSERT FAIL: Totale negativo = " Totale
    UPON STDERR
    STOP RUN
END-IF.

# 1. Compilare con simboli di debug
cobc -x -g -debug -fsource-location prog.cob

# 2. Lanciare gdb
gdb ./prog

# 3. Comandi gdb utili per COBOL

# Sessione di esempio
$ gdb ./prog
(gdb) break cob_stop_run
(gdb) run
(gdb) print b_WS_Totale
$1 = "00012345"
(gdb) print b_WS_FS
$2 = "00"
(gdb) x/10cb b_WS_Record
0x...:  0x4d 0x61 0x72 0x69 0x6f 0x20 0x20 0x20 ...
(gdb) backtrace
#0  cob_stop_run (status=0) at libcob/common.c:...
#1  prog_ () at prog.c:142