Oracle

Collegare database Oracle: connessione, utente in sola lettura, schema corrente, dialetto, procedure e REF CURSOR, errori ORA-.

Oracle è il database della maggior parte degli ERP a cui Prynt si collega. Questa guida tratta la connessione, l'utente del database, le particolarità Oracle dei dataset e gli errori che puoi incontrare. I concetti generali sono in Sorgenti dati e Dataset.

Collegare un database Oracle

Crea una sorgente dati di tipo Oracle e configura una connessione per ogni ambiente. Prynt si collega con il driver ODP.NET managed e costruisce il descrittore di connessione da questi campi: non incolli mai una stringa di connessione o un alias TNS.

Hosttestoobbligatorio: L'host del database. Con un gateway, come lo vede il gateway (erp-db.local, 10.0.0.12); diretta, un nome DNS pubblico.
Portaintero: La porta del listener, predefinita 1521 (i listener TCPS usano spesso la 2484). Le connessioni dirette ammettono 1521–1526, 2483, 2484.
Service nametestoobbligatorio: Il servizio, per esempio ORCLPDB1 o la PDB dell'ERP. Le connessioni tramite SID non sono supportate: usa il service name.
Utente, Passwordcredenzialiobbligatorio: Un utente dedicato in sola lettura (vedi sotto).
Schema correntetesto: Il proprietario delle tabelle dell'ERP, per scrivere "FROM CLIENTI" invece di "FROM ERP.CLIENTI" (vedi sotto).
Schemi nell'esploratoreelenco: I proprietari che l'esploratore del database elenca. Vuoto = tutti gli schemi che l'utente vede, tranne quelli gestiti da Oracle.
TLSmodalità: Disattivato (solo dietro un gateway), oppure TCPS: Obbligatorio, Verifica la CA, Verifica certificato e host.

Impostazioni della connessione Oracle
Campo	Tipo	Descrizione
`Host`obbligatorio	testo	L'host del database. Con un gateway, come lo vede il gateway (erp-db.local, 10.0.0.12); diretta, un nome DNS pubblico.
`Porta`	intero	La porta del listener, predefinita 1521 (i listener TCPS usano spesso la 2484). Le connessioni dirette ammettono 1521–1526, 2483, 2484.
`Service name`obbligatorio	testo	Il servizio, per esempio ORCLPDB1 o la PDB dell'ERP. Le connessioni tramite SID non sono supportate: usa il service name.
`Utente, Password`obbligatorio	credenziali	Un utente dedicato in sola lettura (vedi sotto).
`Schema corrente`	testo	Il proprietario delle tabelle dell'ERP, per scrivere "FROM CLIENTI" invece di "FROM ERP.CLIENTI" (vedi sotto).
`Schemi nell'esploratore`	elenco	I proprietari che l'esploratore del database elenca. Vuoto = tutti gli schemi che l'utente vede, tranne quelli gestiti da Oracle.
`TLS`	modalità	Disattivato (solo dietro un gateway), oppure TCPS: Obbligatorio, Verifica la CA, Verifica certificato e host.

In una rete privata (il caso tipico di un ERP), collegati tramite il Prynt Gateway: niente da aprire nel firewall, e le credenziali sono cifrate per il gateway.
Oracle in un cloud pubblico (OCI, AWS RDS, Azure) può usare una connessione diretta su TCPS.

Salva la connessione prova la connessione: Connesso · 31 ms · Oracle 19c · utente PRYNT_READER. La prova legge anche privilegi e ruoli della sessione e avvisa in caso di privilegi DBA o ANY, privilegi CREATE, grant di scrittura o tabelle possedute.

Un utente in sola lettura

Prynt legge soltanto, ma dagli un utente che non può scrivere: un utente dedicato con CREATE SESSION e READ (o SELECT) sulle tabelle e viste che servono ai tuoi template, e EXECUTE solo sulle routine in sola lettura usate dai dataset Funzione. La prova della connessione offre questo script quando l'utente ha più privilegi del necessario:

Oracle · utente in sola letturaSQL

-- Oracle: un utente dedicato a Prynt in sola lettura (da eseguire come DBA)CREATE USER PRYNT_READER IDENTIFIED BY "<una password robusta>";GRANT CREATE SESSION TO PRYNT_READER;-- READ (12.1.0.2+) consente SELECT ma non SELECT … FOR UPDATE; ripeti per ogni tabella o vista:GRANT READ ON ERP.CUSTOMERS TO PRYNT_READER;-- oppure, per tutte le tabelle del proprietario:BEGIN  FOR t IN (SELECT table_name FROM all_tables WHERE owner = 'ERP') LOOP    EXECUTE IMMEDIATE 'GRANT READ ON ERP."' || t.table_name || '" TO PRYNT_READER';  END LOOP;END;/-- Routine usate dai dataset Funzione (solo routine che leggono):GRANT EXECUTE ON ERP.PKG_PRINT TO PRYNT_READER;

Nuove tabelle dopo un aggiornamento dell'ERP

I grant sono per oggetto: una tabella aggiunta da un aggiornamento dell'ERP ha bisogno del suo grant. Senza, le query falliscono con ORA-00942.

Proprietari e schema corrente

Di solito l'utente in sola lettura non possiede le tabelle dell'ERP: il proprietario è, per esempio, ERP. Puoi scrivere il proprietario in ogni query (FROM ERP.CLIENTI) oppure impostarlo come schema corrente della connessione: Prynt esegue ALTER SESSION SET CURRENT_SCHEMA quando apre la sessione, e FROM CLIENTI si risolve in ERP.CLIENTI. Con uno schema corrente lo stesso SQL funziona in ogni installazione, comunque si chiami lì il proprietario, e anche i nomi di funzione senza proprietario si risolvono lì. I nomi senza virgolette sono in maiuscolo: clienti = CLIENTI.

Un gateway può limitare gli schemi che legge con AllowedSchemas in prynt-gateway.json.

TLS (TCPS)

Con TLS attivo Prynt si collega a un listener TCPS. Verifica certificato e host controlla anche il DN del certificato del server (eventualmente rispetto al DN del certificato del server che inserisci); Obbligatorio e Verifica la CA usano TCPS senza il controllo del DN.
Le connessioni sono senza wallet: il certificato del server deve essere considerato attendibile dall'archivio dei certificati del sistema operativo della macchina che si collega (l'host del gateway, oppure Prynt per le connessioni dirette). Certificati client e wallet non sono supportati.
Le connessioni dirette devono usare TLS. Dietro un gateway, nella tua rete, TLS si può disattivare; la prova lo segnala.

Scrivere query per Oracle

Dataset RIGHESQL

SELECT r.LINE_NO, r.ITEM, a.DESCRIPTION, r.QTY, r.PRICE  FROM DDT_LINES r  JOIN ITEMS a ON a.COMPANY = r.COMPANY AND a.CODE = r.ITEM WHERE r.COMPANY = :DITTA   AND r.DDT_ID  = :DOCUMENT_ID   AND (:ONLY_ACTIVE = 0 OR a.ACTIVE = 1) ORDER BY r.LINE_NO

Un dataset è una sola SELECT o WITH; un ; finale viene tolto. Niente blocchi PL/SQL e niente WITH FUNCTION: per la logica PL/SQL usa un dataset Funzione.
Le bind variable si scrivono :NOME, come in Oracle. I valori di sistema :DATE e :USER sono parole riservate di Oracle: Prynt li rinomina per te.
SQL Oracle come al solito: FETCH FIRST 10 ROWS ONLY, NVL/COALESCE, ||, FROM DUAL, SYSDATE, TRUNC(data), il quoting alternativo q'[l'articolo]'.
Il testo vuoto è NULL in Oracle: WHERE col = '' non è mai vero e un parametro di testo vuoto arriva come NULL. Filtro facoltativo: (:CLIENTE IS NULL OR c.CODICE = :CLIENTE).
Sì/no: prima di Oracle 23ai l'SQL non ha un tipo booleano, quindi un parametro boolean arriva come 1 o 0. I flag dell'ERP come NUMBER(1) o CHAR(1) 'S'/'N' arrivano come numeri o testi: confrontali in modo esplicito nelle espressioni.
L'ordinamento dei testi può seguire le regole linguistiche della sessione; per l'ordine binario usa ORDER BY NLSSORT(col, 'NLS_SORT=BINARY').

Date, numeri e NLS

Prynt non cambia le impostazioni NLS della sessione. I parametri sono passati con il loro tipo (un parametro date arriva come DATE Oracle a mezzanotte), quindi non dipendono mai da NLS_DATE_FORMAT.
Evita le conversioni implicite nell'SQL, come TO_CHAR(SYSDATE) senza formato o il confronto tra una data e un testo: il loro risultato dipende dalle impostazioni NLS della sessione. Scrivi il formato (TO_DATE('2026-09-27', 'YYYY-MM-DD')) oppure, meglio, restituisci date e numeri e lascia la formattazione al template.
Per includere un giorno intero: d.DATA >= :DAL AND d.DATA < :AL + 1.
Un DATE di Oracle ha sempre un'ora: dai al campo un formato come dd/MM/yyyy, altrimenti stampa anche 00:00.

Tipi di dati

NUMBER(p,0), p ≤ 18integer: Colonne intere.
NUMBER, FLOAT, BINARY_FLOAT/DOUBLEdecimal: Altri numeri, anche NUMBER senza precisione, COUNT(*), SUM e calcoli.
VARCHAR2, CHAR, NVARCHAR2, CLOB, NCLOB, LONGstring: Anche intervalli, XMLTYPE e JSON come testo. I LOB vengono letti per intero.
DATE, TIMESTAMPdateTime: Un DATE ha sempre un'ora.
TIMESTAMP WITH (LOCAL) TIME ZONEdateTime: Convertito in UTC.
RAW, LONG RAW, BLOBbinary: Immagini da un campo.
BOOLEAN (23ai)boolean: Booleani SQL nativi.

Tipi Oracle e tipi dei campi di Prynt
Campo	Tipo	Descrizione
`NUMBER(p,0), p ≤ 18`	integer	Colonne intere.
`NUMBER, FLOAT, BINARY_FLOAT/DOUBLE`	decimal	Altri numeri, anche NUMBER senza precisione, COUNT(*), SUM e calcoli.
`VARCHAR2, CHAR, NVARCHAR2, CLOB, NCLOB, LONG`	string	Anche intervalli, XMLTYPE e JSON come testo. I LOB vengono letti per intero.
`DATE, TIMESTAMP`	dateTime	Un DATE ha sempre un'ora.
`TIMESTAMP WITH (LOCAL) TIME ZONE`	dateTime	Convertito in UTC.
`RAW, LONG RAW, BLOB`	binary	Immagini da un campo.
`BOOLEAN (23ai)`	boolean	Booleani SQL nativi.

Tipi oggetto, collection, BFILE, VECTOR e cursori annidati non sono supportati come colonne (SQL_TYPE_NOT_SUPPORTED): convertili nella query.

Funzioni, procedure e REF CURSOR

Un dataset con origine Funzione chiama una routine: sceglila dall'elenco (PROPRIETARIO.FUNZIONE o PROPRIETARIO.PACKAGE.FUNZIONE) per vederne gli argomenti, e collega ogni argomento IN, nell'ordine. I nomi senza proprietario si risolvono nello schema corrente e nei sinonimi; le routine tramite database link sono rifiutate.

Funzione PIPELINEDTABLE(…): Oppure una funzione che restituisce una collection di un tipo oggetto: una riga per elemento, una colonna per attributo.
Funzione → SYS_REFCURSORcursore: Le righe del cursore.
Procedura con OUT SYS_REFCURSORcursore: Esattamente un cursore OUT, gli altri argomenti IN: le righe del cursore.
Funzione → valoreFROM DUAL: Una riga con una colonna che ha il nome della funzione.
Funzione → oggettouna riga: Una colonna per attributo.

Routine che un dataset Funzione può leggere
Campo	Tipo	Descrizione
`Funzione PIPELINED`	TABLE(…)	Oppure una funzione che restituisce una collection di un tipo oggetto: una riga per elemento, una colonna per attributo.
`Funzione → SYS_REFCURSOR`	cursore	Le righe del cursore.
`Procedura con OUT SYS_REFCURSOR`	cursore	Esattamente un cursore OUT, gli altri argomenti IN: le righe del cursore.
`Funzione → valore`	FROM DUAL	Una riga con una colonna che ha il nome della funzione.
`Funzione → oggetto`	una riga	Una colonna per attributo.

Come il motore chiama le routineSQL

-- Una procedura con un solo OUT SYS_REFCURSOR: il motore esegueBEGIN ERP.PKG_PRINT.DDT_LINES(:DITTA, :CURSOR, :DOCUMENT_ID); END; -- Una funzione pipelined (o che restituisce una collection):SELECT * FROM TABLE(ERP.PKG_PRINT.DDT_LINES(:DOCUMENT_ID))

Gli argomenti sono convertiti nei tipi dichiarati (non serve TO_DATE). Gli ultimi argomenti con un valore predefinito si possono omettere.
Non utilizzabili: funzioni con argomenti OUT, procedure senza un cursore OUT o con altri argomenti OUT, routine che restituiscono tipi solo PL/SQL (BOOLEAN, RECORD).
Le routine devono solo leggere: girano in una transazione in sola lettura con i commit disattivati, quindi una scrittura fallisce (ORA-01456, ORA-14551) e così un COMMIT (ORA-00034). Le procedure che riempiono tabelle di lavoro vanno sostituite, per esempio con una funzione pipelined.
Le colonne dei cursori si conoscono solo eseguendoli: Esegui, poi Aggiorna campi.

Risolvere gli errori ORA-

Gli errori del database mostrano il codice Oracle (ORA-00904), con riga e colonna per gli errori di sintassi e di nome. I messaggi arrivano nella lingua del server del database.

ORA-00942SQL: Tabella o vista inesistente: il nome non si risolve (scrivi il proprietario o imposta lo schema corrente) oppure l'utente non ha il grant.
ORA-00904SQL: Identificatore non valido: un nome di colonna sbagliato, o un nome minuscolo tra virgolette.
ORA-01722SQL: Numero non valido: una conversione implicita di un testo che non è un numero.
ORA-01013timeout: La query è stata annullata al suo timeout (SQL_TIMEOUT): aggiungi filtri o indici, oppure alza il timeout del dataset.
ORA-01017accesso: Utente o password non validi (anche ORA-28000 account bloccato, ORA-28001 password scaduta). La sorgente dati resta non disponibile finché non lo correggi.
ORA-12514listener: Il listener non conosce il service name: controlla il servizio (non il SID).
ORA-12541, ORA-12170rete: Nessun listener su host e porta, oppure timeout di connessione: controlla host, porta e firewall dal server del gateway.
ORA-01435schema: Lo schema corrente non esiste: controlla come è scritto nella connessione.
ORA-01456, ORA-00034sola lettura: Una routine ha provato a scrivere o a fare commit: le sorgenti dati sono in sola lettura.

Errori Oracle frequenti
Campo	Tipo	Descrizione
`ORA-00942`	SQL	Tabella o vista inesistente: il nome non si risolve (scrivi il proprietario o imposta lo schema corrente) oppure l'utente non ha il grant.
`ORA-00904`	SQL	Identificatore non valido: un nome di colonna sbagliato, o un nome minuscolo tra virgolette.
`ORA-01722`	SQL	Numero non valido: una conversione implicita di un testo che non è un numero.
`ORA-01013`	timeout	La query è stata annullata al suo timeout (SQL_TIMEOUT): aggiungi filtri o indici, oppure alza il timeout del dataset.
`ORA-01017`	accesso	Utente o password non validi (anche ORA-28000 account bloccato, ORA-28001 password scaduta). La sorgente dati resta non disponibile finché non lo correggi.
`ORA-12514`	listener	Il listener non conosce il service name: controlla il servizio (non il SID).
`ORA-12541, ORA-12170`	rete	Nessun listener su host e porta, oppure timeout di connessione: controlla host, porta e firewall dal server del gateway.
`ORA-01435`	schema	Lo schema corrente non esiste: controlla come è scritto nella connessione.
`ORA-01456, ORA-00034`	sola lettura	Una routine ha provato a scrivere o a fare commit: le sorgenti dati sono in sola lettura.

Gli errori di rete e di accesso (ORA-12xxx, ORA-01017, ORA-28000, istanza ferma) fanno fallire le generazioni con 503 DATA_SOURCE_UNAVAILABLE; gli errori delle query con 422 DATASET_FAILED. Prova la connessione sulla sorgente dati mostra il motivo completo.

Vedi anche

PostgreSQL per i database PostgreSQL, Gateway per le reti private.