CURL.CBL¶

CURL.CBL - Manuale d'Uso¶

Introduzione¶

CURL.CBL è un modulo COBOL centralizzato per l'esecuzione di chiamate HTTP tramite il comando curl. Fornisce un'interfaccia standardizzata per effettuare richieste REST API, gestendo automaticamente: * Costruzione del comando curl * Gestione degli header HTTP (anche di grandi dimensioni) * Invio di body in formato JSON o Form URL-encoded * Parsing delle risposte ed estrazione di valori specifici * Retry automatico in caso di errori di rete * Logging e debug

Architettura¶

Flusso di Esecuzione¶

Programma Chiamante
        │
        ▼
   ┌─────────────────┐
   │    CURL.CBL     │
   │                 │
   │  1. Validazione │
   │  2. Creazione   │
   │     file config │
   │  3. Creazione   │
   │     file body   │
   │  4. Esecuzione  │
   │     curl        │
   │  5. Parsing     │
   │     risposta    │
   │  6. Cleanup     │
   └─────────────────┘
        │
        ▼
   Risposta al chiamante

File Temporanei¶

CURL.CBL crea i seguenti file temporanei nella cartella configurata:

File	Descrizione
`curl-YYYYMMDD-HHMMSS-pXXXXXXXX-config.txt`	File di configurazione curl (header)
`curl-YYYYMMDD-HHMMSS-pXXXXXXXX-body.json`	Body della richiesta
`curl-YYYYMMDD-HHMMSS-pXXXXXXXX-h.txt`	Header della risposta HTTP
`curl-YYYYMMDD-HHMMSS-pXXXXXXXX-rsp.txt`	Body della risposta
`curl-YYYYMMDD-HHMMSS-pXXXXXXXX-command.txt`	Comando eseguito (solo in debug)

I file vengono automaticamente eliminati in caso di successo (a meno che non sia attivo il debug).

Copybook di Riferimento¶

utilcurl.cpy¶

Il copybook principale contiene due strutture:

1. util-curl - Parametri Principali¶

01  util-curl.
    02 curl-operazione         pic x(20).
    02 curl-folder             pic x(30).
    02 curl-command            pic x(512).
    02 curl-post-params        pic x(512).
    02 curl-fl-add-server      pic x(01).
    02 curl-fl-save-log        pic x(01).
    02 curl-tag-esito          pic x(30).
    02 curl-esito-negativo     pic x(256).
    02 curl-file-esito         pic x(256).
    02 curl-header             pic x(16000) occurs 5 times.
    02 curl-o-esito            pic x(01).
    02 curl-o-msg              pic x(256).

2. util-curl-body-params - Parametri Body e Risposta¶

01  util-curl-body-params.
    02 curl-body-format        pic x(01).
    02 curl-body-use-raw       pic x(01).
    02 curl-body-raw           pic x(64000).
    02 curl-body-n-params      pic 9(02).
    02 curl-body-params.
       03 curl-body-param occurs 50 times.
          04 curl-body-p-nome    pic x(50).
          04 curl-body-p-valore  pic x(500).
          04 curl-body-p-tipo    pic x(01).
    02 curl-resp-n-params      pic 9(02).
    02 curl-resp-params.
       03 curl-resp-param occurs 20 times.
          04 curl-resp-p-tag     pic x(50).
          04 curl-resp-p-valore  pic x(32000).

Parametri di Input¶

Parametri Obbligatori¶

Campo	Descrizione
`curl-command`	URL da chiamare (o path relativo se `curl-fl-add-server = "S"`)

Parametri Opzionali¶

Campo	Valori	Default	Descrizione
`curl-operazione`	`ESEGUI-CURL`	`ESEGUI-CURL`	Operazione da eseguire
`curl-folder`	stringa	`generic`	Sottocartella per i file temporanei
`curl-fl-add-server`	`S`/`N`	`N`	Se `S`, antepone SERVER-WEB all'URL
`curl-fl-save-log`	`S`/`N`	`N`	Se `S`, mantiene i file di log anche in caso di successo
`curl-post-params`	stringa	-	Parametri POST inline (retrocompatibilità)
`curl-tag-esito`	stringa	-	Tag JSON da cercare per determinare l'esito
`curl-esito-negativo`	stringa	-	Valore del tag che indica errore

Header HTTP¶

Gli header vengono passati tramite l'array curl-header (5 elementi da 16000 caratteri ciascuno).

move "Authorization: Bearer eyJhbGc..." to curl-header (1)
move "Content-Type: application/json"   to curl-header (2)

Nota: Gli header vengono scritti su un file di configurazione per superare il limite di 1024 caratteri della command line.

Body della Richiesta¶

Modalità 1: Tabella Parametri (per body piccoli)¶

move "J"                     to curl-body-format
move 3                       to curl-body-n-params

move "username"              to curl-body-p-nome (1)
move "mario.rossi"           to curl-body-p-valore (1)
move "S"                     to curl-body-p-tipo (1)

move "age"                   to curl-body-p-nome (2)
move "30"                    to curl-body-p-valore (2)
move "N"                     to curl-body-p-tipo (2)

move "active"                to curl-body-p-nome (3)
move "true"                  to curl-body-p-valore (3)
move "B"                     to curl-body-p-tipo (3)

Modalità 2: Body Raw (per body grandi, es. file base64)¶

move "S"                     to curl-body-use-raw
move '{"fileName":"test.csv","base64":"SGVsbG8gV29ybGQ=..."}'
                             to curl-body-raw

Formato Body (curl-body-format)¶

Valore	Descrizione	Content-Type
`J`	JSON	`application/json`
`F`	Form URL-encoded	`application/x-www-form-urlencoded`

Tipi Parametro (curl-body-p-tipo)¶

Valore	Descrizione	Esempio Output JSON
`S` o spazio	Stringa	`"nome": "valore"`
`N`	Numerico	`"età": 30`
`B`	Boolean	`"attivo": true`
`L`	Null	`"campo": null`
`R`	Raw (già formattato)	Viene inserito così com'è

Parametri Risposta¶

Per estrarre valori specifici dalla risposta JSON:

move 3                       to curl-resp-n-params
move "access_token"          to curl-resp-p-tag (1)
move "error"                 to curl-resp-p-tag (2)
move "error_description"     to curl-resp-p-tag (3)

Dopo la chiamata, i valori saranno disponibili in curl-resp-p-valore (n).

Parametri di Output¶

Campo	Descrizione
`curl-o-esito`	`S` = successo, `N` = errore
`curl-o-msg`	Messaggio descrittivo (in caso di errore)
`curl-file-esito`	Path del file contenente la risposta completa
`curl-resp-p-valore (n)`	Valori estratti dalla risposta JSON

Modalità di Utilizzo¶

Chiamata Base¶

WORKING-STORAGE SECTION.
copy "utilcurl.cpy".

PROCEDURE DIVISION.
    initialize util-curl util-curl-body-params

    move "https://api.example.com/endpoint" to curl-command

    call "CURL" using stringhe 
                      util-curl
                      util-curl-body-params

    if curl-o-esito = "S"
       display "Chiamata riuscita"
    else
       display "Errore: " curl-o-msg
    end-if

Chiamata POST con JSON¶

    initialize util-curl util-curl-body-params

    move "https://api.example.com/users" to curl-command
    move "J"                     to curl-body-format
    move 2                       to curl-body-n-params

    move "name"                  to curl-body-p-nome (1)
    move "Mario Rossi"           to curl-body-p-valore (1)
    move "S"                     to curl-body-p-tipo (1)

    move "email"                 to curl-body-p-nome (2)
    move "[email protected]"     to curl-body-p-valore (2)
    move "S"                     to curl-body-p-tipo (2)

    call "CURL" using stringhe 
                      util-curl
                      util-curl-body-params

Chiamata con Autenticazione Bearer¶

    initialize util-curl util-curl-body-params

    move "https://api.example.com/protected" to curl-command

    string "Authorization: Bearer " w-token
       delimited "  "          into curl-header (1)

    call "CURL" using stringhe 
                      util-curl
                      util-curl-body-params

Chiamata OAuth2 (Form URL-encoded)¶

    initialize util-curl util-curl-body-params

    move "https://auth.example.com/token" to curl-command
    move "F"                     to curl-body-format
    move 3                       to curl-body-n-params

    move "client_id"             to curl-body-p-nome (1)
    move "my-client-id"          to curl-body-p-valore (1)

    move "client_secret"         to curl-body-p-nome (2)
    move "my-secret"             to curl-body-p-valore (2)

    move "grant_type"            to curl-body-p-nome (3)
    move "client_credentials"    to curl-body-p-valore (3)

* Estrai il token dalla risposta
    move 1                       to curl-resp-n-params
    move "access_token"          to curl-resp-p-tag (1)

    call "CURL" using stringhe 
                      util-curl
                      util-curl-body-params

    if curl-o-esito = "S"
       move curl-resp-p-valore (1) to w-token
    end-if

Upload File Base64 (Body Raw)¶

    initialize util-curl util-curl-body-params

    move "https://api.example.com/upload" to curl-command

    string "Authorization: Bearer " w-token
       delimited "  "          into curl-header (1)
    move "Content-Type: application/json"
                               to curl-header (2)

* Usa modalità RAW per body grandi
    move "S"                     to curl-body-use-raw
    string '{"fileName":"' w-filename '",'
           '"base64":"' w-base64-content '"}'
       delimited "  "          into curl-body-raw

    call "CURL" using stringhe 
                      util-curl
                      util-curl-body-params

Esempi Pratici¶

Esempio Completo: Autenticazione + Upload¶

Vedi FORS24.CBL per un esempio completo che: 1. Effettua una chiamata OAuth2 per ottenere un token 2. Usa il token per effettuare un upload di file 3. Gestisce gli errori in modo appropriato

Gestione Errori¶

Codici di Errore CURL¶

Exit Code	Descrizione
1	Protocollo non supportato
3	URL malformato
5	Impossibile risolvere proxy
6	Impossibile risolvere host
7	Impossibile connettersi al server
22	HTTP status >= 400
28	Timeout operazione
35	Errore SSL/TLS handshake
51	Certificato SSL non valido
52	Server non ha risposto
56	Errore ricezione dati
60	Certificato SSL non verificabile

Codici HTTP¶

Status	Descrizione
200	OK
201	Risorsa creata
400	Richiesta non valida
401	Non autorizzato
403	Accesso negato
404	Risorsa non trovata
429	Troppe richieste (rate limit)
500	Errore interno del server
502	Bad Gateway
503	Servizio non disponibile
504	Gateway timeout

Retry Automatico¶

CURL.CBL effettua automaticamente fino a 3 tentativi (configurabile) con un ritardo di 5 secondi tra un tentativo e l'altro. I seguenti errori non vengono ritentati: * Exit code 3 (URL malformato) * Exit code 5 (proxy non risolvibile) * Exit code 6 (host non risolvibile)

Note Tecniche e Limiti¶

Limiti Dimensionali¶

Campo	Dimensione Max
`curl-command` (URL)	512 caratteri
`curl-header` (singolo)	16.000 caratteri
`curl-body-p-valore` (singolo)	500 caratteri
`curl-body-raw`	64.000 caratteri
`curl-resp-p-valore` (singolo)	32.000 caratteri
Numero header	5
Numero parametri body	50
Numero parametri risposta	20

Limite Command Line¶

Il comando curl viene eseguito tramite C$SYSTEM che ha un limite di 1024 caratteri. Per superare questo limite: * Gli header vengono scritti su file e passati con l'opzione -K * Il body viene scritto su file e passato con l'opzione --data-binary "@file"

Configurazione¶

CURL.CBL legge la configurazione SERVER-WEB da AREAAPP se curl-fl-add-server = "S". I file temporanei vengono creati in: {ext-root-dir}/curl/{curl-folder}/

Debug¶

Per mantenere i file di log anche in caso di successo:

move "S" to curl-fl-save-log

Oppure attivare il debug globale tramite la configurazione standard (gesdebug).

Troubleshooting¶

Problema: "Invalid serialized unsecured/JWS/JWE object"¶

Causa: Il token JWT viene troncato. Soluzione: Verificare che: * curl-header sia sufficientemente grande (almeno 2048 per token standard) * Il token venga passato con la lunghezza corretta usando una sottostringa

Problema: Timeout frequenti¶

Causa: Server lento o rete instabile. Soluzione: I timeout sono configurati a: * Connect timeout: 30 secondi * Max time: 60 secondi

Problema: Errore SSL/Certificato¶

Causa: Certificato non valido o non verificabile. Soluzione: Verificare la configurazione SSL del server. Se necessario per test, si può aggiungere l'opzione --insecure (sconsigliato in produzione).

Problema: Body JSON malformato¶

Causa: Caratteri speciali non escapati nel body. Soluzione: Usare la modalità RAW (curl-body-use-raw = "S") e costruire manualmente il JSON, assicurandosi di escapare correttamente i caratteri speciali.

Problema: Risposta vuota¶

Causa: Il server non ha restituito un body. Soluzione: Verificare il file di risposta in curl-file-esito e gli header HTTP nel file -h.txt.

Changelog¶

Versione	Data	Modifiche
1.0	22/12/2024	Versione iniziale

Autore¶

Andrea Parmeggiani - Eurosystem2000

Estratto da documentazione interna ClickUp