Scrivere messaggi nel joblog con SQL

Quasi nascosta tra i molti utili strumenti messi a disposizione da IBM nella libreria SYSTOOLS, troviamo la procedura LPRINTF. Questa procedura fa una cosa molto semplice: scrive un messaggio nel job log del lavoro che la richiama; ha un solo parametro di tipo VARCHAR in cui passare la stringa di caratteri da mostrare nel log. Di fatto, LPRINTF interfaccia la API Qp0zLprintf, rendendola facilmente richiamabile anche con SQL.
A cosa può servire LPRINTF ? Ci sono varie situazioni in cui può essere utile scrivere nel joblog delle informazioni aggiuntive rispetto a quelle fornite dal sistema. Un esempio significativo è quello di programmi in cui le istruzioni SQL vengono costruite dinamicamente in un campo, inserendo anche delle variabili. Dopo aver composto l’istruzione, con LPRINTF si può caricare nel job log la stringa che la contiene, in modo da poter verificare cosa non va in caso di errore o di funzionamento non desiderato.
Per richiamare LPRINTF da un programma RPG è sufficiente eseguire questa istruzione SQL:

         Exec SQL
            CALL SYSTOOLS.LPRINTF(:message) ;

Vediamo un esempio di programma che compone dinamicamente una istruzione SQL che popola una tabella, usando anche delle variabili. Di seguito l’istruzione che imposta lo statement SQL:

sqlStmt = 'CREATE TABLE mduca1.Faq40013T AS (' +    
'SELECT CodCliente, RagioneSociale, NazCl, '   +    
'd.Articolo, Descrizione, SUM(OrdQty)         '  +  
'FROM AnCli00f '                             +      
'JOIN OrdDt00f d ON CodCliente = OrdCli '    +      
'JOIN AnaArt00f a ON a.Articolo = d.Articolo ' +    
'WHERE NazCl = ' + pNation +  ' '     +             
'GROUP BY CodCliente, RagioneSociale, NazCl, ' +    
'd.Articolo, Descrizione '                     +    
'ORDER BY CodCliente)'                         +    
' WITH DATA'                                        
;    

Il programma estrae dall’anagrafica tutti i clienti della nazione ricevuta come parametro, insieme ad altri dati da ordini di vendita e anagrafica articoli, e li scrive nella tabella FAQ40013T.
Lanciamo il programma e verifichiamo il risultato.

call faq40013 parm('IT') 

Il programma non ha creato la tabella… normalmente dovremmo attivare il debug, rilanciare il programma e vedere il contenuto della variabile sql per capire il problema… ma con LPRINTF, è sufficiente visualizzare il job log del lavoro per avere sott’occhio l’istruzione:

Ecco l’errore: è stata definita una colonna con la funzione scalare SUM, ma non gli è stato assegnato un nome. L’istruzione CREATE TABLE richiede che ogni colonna della tabella che si va a creare abbia la sua denominazione univoca.
Correggiamo, rilanciamo e vediamo se funziona:

C’è ancora qualche problema… vediamo quale.

Stavolta mancano gli apici intorno al codice della nazione… correggiamo ancora e vediamo se questa è la volta buona !

Ora è tutto OK ! Grazie alla possibilità di vedere direttamente nel joblog l’istruzione, abbiamo potuto risolvere i problemi molto più velocemente. Ovviamente questo è un esempio semplice, ma in presenza di istruzioni SQL molto più complesse, l’aiuto di LPRINTF si rivela più prezioso.
Naturalmente nulla vieta di sfruttare LPRINTF per scrivere nel joblog qualsiasi altra informazione si ritenesse utile per monitorare meglio le proprie applicazioni.

La procedura LPRINTF è disponibile nel prodotto DB2 for i dalle versioni 7.3 (level 16) e 7.4 (level 4)

Il source completo del programma è disponibile su GitHub: https://github.com/MD2706GIT/FAQ400/blob/master/FAQ40013.sqlrpgle

DOCUMENTAZIONE:
Procedura LPRINTF: https://www.ibm.com/support/pages/systoolslprintf-procedure