M2 Report

Istruzione RAISE ERROR

L'istruzione RAISE ERROR attiva una condizione di errore, e ha la forma

RAISE ERROR codice descrizione

dove codice è una espressione di tipo INTEGER e descrizione è una espressione di tipo STRING.

La variabile ERROR_CODE esportata dal modulo m2runtime assume il valore indicato come codice. La descrizione, completata dal nome del modulo, dal nome della funzione, dal numero della riga del sorgente e dal codice di errore, viene assegnato alla variabile ERROR_MESSAGE esportata dal modulo m2runtime. Il messaggio completo assume questa forma:

modulo.funzione(), line n, code codice: descrizione

Se il chiamante non gestisce la condizione di errore tramite l'istruzione TRY, l'istruzione RAISE ERROR causa l'immediata terminazione del programma con un HALT().

Altrimenti l'istruzione RAISE ERROR non ha altri effetti oltre a quelli di impostare le variabili ERROR_CODE e ERROR_MESSAGE. E' responsabilità della funzione di impostare correttamente lo stato del programma prima di ritornare al chiamante.

L'istruzione RAISE ERROR può comparire solo in una funzione che ha l'attributo RAISE ERROR nella sua dichiarazione:

FUNCTION SquareRoot(x: REAL): REAL
RAISE ERROR
BEGIN
    IF x < 0.0 THEN
        RAISE ERROR 1 rtos(x) + ": invalid negative argument"
        RETURN 0.0
    END
    (* ... *)
END

Il messaggio di errore prodotto dalla funzione dovrebbe aiutare il chiamante a risolvere il problema. Ecco un decalogo di criteri da adottare per usare in modo corretto l'istruzione RAISE ERROR:

• Utilizzare un codice di errore diverso per condizioni diverse che si possono produrre all'interno di una funzione, in modo che il chiamante possa distinguere le diverse condizioni. Ad esempio, una numerazione progressiva 1, 2, 3, ... va bene. Il codice 0 non si può usare perché esprime la condizione "nessun errore". Ricordare di riportare questi codici nella documentazione della funzione.

• Se l'errore è in conseguenza del particolare valore di un argomento o di altro parametro di configurazione, riportare il valore non valido.

• Non inserire il nome del modulo e il nome della funzione: a questo provvede già M2.

• Se la funzione ha effetti collaterali, ripristinare il valore iniziale degli argomenti VAR e delle variabili globali che sono state modificate. Documentare i casi in cui il ripristino non è possibile; in questo caso adottare codici di errore differenziati, oppure impostare i dati ritornati in modo che il chiamante possa distinguere i due casi.

Osserviamo che il codice 0 annulla la condizione di errore. Pertanto questo codice è valido:

RAISE ERROR SUCCESS NIL