DBImport – Manuale Utente

Transcript

Pagina 1 di 28
Versione 3 del 15/03/2013
Pagina 2 di 28
SOMMARIO
1
Introduzione ........................................................................................................................ 4
2
Descrizione del processo di importazione ............................................................................ 5
2.1
3
Invocazione ............................................................................................................................................ 5
File XML di importazione ...................................................................................................... 6
3.1
File principale, dati ................................................................................................................................... 6
3.1.1
Struttura file ...................................................................................................................................... 6
3.1.2
Proprietà dei nodi ............................................................................................................................... 7
3.2
File esterno per la definizione di un DDS .................................................................................................... 10
3.2.1
Struttura file ..................................................................................................................................... 10
3.2.2
Proprietà dei nodi .............................................................................................................................. 10
3.2.3
3.3
Esempio ........................................................................................................................................... 10
File esterno per la definizione dei Matching ................................................................................................. 11
3.3.1
Struttura file ..................................................................................................................................... 11
3.3.2
3.3.3
Esempio ........................................................................................................................................... 11
4
Trigger su eventi di importazione ...................................................................................... 12
4.1
Specifica dei trigger ................................................................................................................................ 12
4.1.1
Specifica all‟interno del file di importazione ............................................................................................ 12
4.1.2
Specifica in un file di definizione esterno ............................................................................................... 12
4.2
Parametri dei gestori degli eventi trigger .................................................................................................... 13
4.2.1
Gestori eventi OnFile* ........................................................................................................................ 13
4.2.2
Gestori eventi OnRecord* ................................................................................................................... 13
4.3
File esterno specifica trigger ..................................................................................................................... 14
4.3.1
Struttura file ..................................................................................................................................... 14
4.3.2
4.3.3
Esempio ........................................................................................................................................... 14
5
Tipi di dato supportati ....................................................................................................... 15
5.1
Note sui tipi Data/Ora.............................................................................................................................. 15
5.2
Gestione CCSID ...................................................................................................................................... 16
6
Flow Chart ......................................................................................................................... 17
7
File multimembro .............................................................................................................. 20
8
Il file WGDBIMPS ............................................................................................................... 21
9
Esempi di file di importazione ............................................................................................ 22
9.1
Esempio 1: Importazione in file esistente ................................................................................................... 22
9.2
Esempio 2: Richiamo comandi .................................................................................................................. 23
9.3
Esempio 3: Nuovo file da template ............................................................................................................ 24
9.4
Esempio 4: Specifica match ...................................................................................................................... 25
9.5
Esempio 5: Nuovo file da DDS .................................................................................................................. 26
9.6
Esempio 6: Tipi di dato ............................................................................................................................ 27
9.7
Esempio 7: DDS e Match in file esterni ....................................................................................................... 28
Pagina 3 di 28
1 INTRODUZIONE
DBImport è nato come prodotto per l‟importazione di dati sul database della piattaforma IBM iSeries.
I dati elaborati sono descritti in un formato neutro basato su files XML, realizzato affinchè DBImport fosse interfacciabile con
la più vasta quantità di fonte dati.
Quello che DBImport offre è:
-
Aggiunta dati ad un file esistente
-
Aggiornamento dati di un file esistente
-
Eliminazione dati da un file esistente
-
Creazione nuovi files
Il prodotto offre supporto multilingua, attraverso la possibilità di specificare il CCSID dei dati trattati a livello di singolo
campo.
Ogni file di importazione contiene al proprio interno uno o più lavori di importazione descritti da:
-
una serie di dati da importare
-
una lista di comandi da eseguire prima dell‟importazione
-
una lista di comandi da eseguire dopo l‟importazione
-
la struttura del file destinazione o il nome del file fisico da utilizzare come modello per la sua creazione
La procedura di importazione può essere personalizzata attraverso la realizzazione di programmi ILE da richiamare durante
le fasi dell‟importazione al fine di eseguire la validazione dei dati, l‟importazione vera e propria e la gestione degli errori.
Questi saranno riferiti come trigger all‟interno del documento.
Lo scopo di questo manuale è descrivere come realizzare un file di importazione con le informazioni corrette e come invocare
il programma di importazione.
Pagina 4 di 28
2 DESCRIZIONE DEL PROCESSO DI IMPORTAZIONE
2.1 Invocazione
Il programma (DBIMPXX) viene invocato dalla riga di comando specificando il file xml che descrive il lavoro di importazione
che deve svolgere.
Sintassi:
DBIMPXX filedilavoro [filedilog [livellodilog [fileerrori [ignorablank]]]]
Il file di lavoro è un file xml realizzato secondo il modello descritto nel documento “Struttura file XML di importazione”.
E‟ un parametro obbligatorio senza il quale il programma non può funzionare.
Il contenuto di questo file deve rispettare tutte le regole descritte nel documento sopracitato o la procedura di importazione
non andrà a buon fine.
In particolare: se la sintassi XML del file non è corretta (tag lasciati aperti) il programma terminerà senza eseguire alcuna
operazione; se invece è la semantica del file a non essere corretta (informazioni mancanti, collocate in maniera errata) il
risultato ottenuto non è prevedibile.
Le operazioni eseguite dal programma di importazione vengono loggate in un file (qualora non si disabiliti questo
comportamento).
Questo viene specificato tramite il parametro “file di log” (percorso assoluto sull‟IFS) e la quantità di informazioni da loggare
viene specificata con il parametro livello di log.
Qualora non venga specificato il file di log è “/webgate400/log/dbimpxx.log”.
Il livello di log di default è 1.
Livelli di log
0 – Nessun log
1 – Log su file delle operazioni eseguite (ed eventuali errori)
2 – Log su file e a schermo delle operazioni eseguite (ed eventuali errori)
3 – Log su file delle operazioni eseguite (ed eventuali errori) e dei dati elaborati
4 – Log su file e a schermo delle operazioni eseguite (ed eventuali errori) e dei dati elaborati
E‟ inoltre possibile abilitare la creazione di un file xml di importazione valido che contiene tutti i record che hanno fallito
l‟importazione, file che potrà essere usato per ritentare nuovamente l‟operazione.
Per abilitarlo è sufficiente specificarne il percorso come parametro della riga di invocazione.
Il parametro “ignorablank” è stato introdotto al fine di indicare ai programmi utilizzati come trigger quali campi del record
passato sono stati valorizzati da file di importazione e quali invece non sono stati indicati.
Esempi di invocazione
CALL PGM(DBIMPXX) PARM(„/temp/import.xml‟)
Importa dal file /temp/import.xml, log livello 1 sul file /webgate400/log/dbimpxx.log
CALL PGM(DBIMPXX) PARM(„/temp/import.xml‟ „/temp/import.log‟)
Importa dal file /temp/import.xml, log livello 1 sul file /temp/import.log
CALL PGM(DBIMPXX) PARM(„/temp/import.xml‟ „/temp/import.log‟ „3‟)
Importa dal file /temp/import.xml, log livello 3 (con dati) sul /temp/import.log
CALL PGM(DBIMPXX) PARM(„/temp/import.xml‟ „/temp/import.log‟ „2‟ „/temp/import.err.xml‟)
Importa dal file /temp/import.xml, log livello 2 sul file /temp/import.log e a schermo. I record non importati sono
salvati nel file /temp/import.err.xml
Pagina 5 di 28
3 FILE XML DI IMPORTAZIONE
3.1 File principale, dati
3.1.1 Struttura file
<?xml version=”1.0” encoding=”UTF-8” ?>
<IMPORT_DOCUMENT>
<FILE>
<MATCH>
<FIELD />
…
<FIELD />
</MATCH>
<DDS>
<FIELD />
…
<FIELD />
</DDS>
<EXEC_PRE>
<COMMAND>…</COMMAND>
…
<COMMAND>…</COMMAND>
</EXEC_PRE>
<RECORDS>
<RECORD>
//Descrizione record
</RECORD>
…
<RECORD>
//Descrizione record
</RECORD>
<RECORDS>
<EXEC_POST>
<COMMAND />
…
<COMMAND />
</EXEC_POST>
</FILE>
</IMPORT_DOCUMENT>
Pagina 6 di 28
3.1.2 Proprietà dei nodi
Di seguito è riportata una breve descrizione dei nodi che vanno a comporre il file di importazione XML.
Per ogni nodo è riportata la lista delle proprietà supportate, il contenuto e la cardinalità rispetto al nodo genitore.
 IMPORT_DOCUMENT
Proprietà
Nessuna
Contenuto
Root del documento, contiene tutti i tag che definiscono l‟importazione
Cardinalità
Ogni file XML che descrive un importazione contiene 1 nodo IMPORT_DOCUMENT
 IMPORT_DOCUMENT/FILE
Proprietà
name
nome del file in cui importare i dati
library
libreria in cui si trova il file
[member]
membro da utilizzare (opzionale, vedi capitolo “File multimembro”)
[match]
file contenente il mapping dei campi sorgente/destinazione (opzionale)
[dds]
file contenente il DDS della tabella destinazione (opzionale)
[template]
file da usare come template per la tabella destinazione (opzionale)
[onFileStart]
gestore trigger (libreria/nomepgm)
[onFileError]
[onFileFinish]
[onRecordValidate] gestore trigger (libreria/nomepgm)
[onRecordImport]
[onRecordError]
[onRecordDone]
[trigger]
file contenente le informazioni sui trigger da scatenare (opzionale)
[ccsid]
codice del character set del file (solo in creazione nuovo file)
Contenuto
Descrive un lavoro di importazione su file
Cardinalità
Ogni nodo IMPORT_DOCUMENT contiene 1..N nodi FILE
 IMPORT_DOCUMENT/FILE/MATCH
Qualora per un FILE il nodo MATCH non fosse specificato si assume che il nome dei campi sorgente (presenti all‟interno
dei nodi RECORD) coincidano con i nomi dei campi destinazione.
Proprietà
Nessuna
Contenuto
Contiene le informazioni per effettuare il mapping tra i campi sorgente e quelli destinazione
Cardinalità
Ogni nodo FILE contiene 0..1 nodi MATCH
Pagina 7 di 28
 IMPORT_DOCUMENT/FILE/MATCH/FIELD
Proprietà
source
nome del campo sorgente
dest
nome del campo destinazione
Contenuto
Nessuno
Cardinalità
Ogni nodo MATCH contiene 1..N nodi MATCH/FIELD
 IMPORT_DOCUMENT/FILE/DDS
Qualora per un FILE il nodo DDS non fosse specificato è necessario che esista un riferimento ad un file di template dal
quale recuperare le informazioni sulla struttura della tabella che ospiterà i dati oggetto dell‟importazione.
Proprietà
Nessuna
Contenuto
Contiene la descrizione dei campi nel file di destinazione
Cardinalità
Ogni nodo FILE contiene 0..1 nodi DDS
 IMPORT_DOCUMENT/FILE/DDS/FIELD
Proprietà
name
nome del campo
sqltype
tipo di campo (vedi paragrafo “Tipi di dato”)
dblen
lunghezza del campo (se applicabile, vedi paragrafo tipi di dato)
decimals
numero di decimali del campo (se applicabile, vedi paragrafo tipi di dato)
[tag]
nome del tag all‟interno dei nodi RECORD con cui ci riferiamo a questo campo (equivalente a
specificare un blocco match)
[ccsid]
Contenuto
Cardinalità
Ogni nodo DDS contiene 1..N nodi DDS/FIELD
 IMPORT_DOCUMENT/FILE/EXEC_PRE
Proprietà
Nessuna
Contenuto
Una lista di comandi da eseguire sulla macchina
Cardinalità
Ogni nodo FILE contiene 0..1 nodi EXEC_PRE
 IMPORT_DOCUMENT/FILE/EXEC_PRE/COMMAND
Proprietà
Nessuna
Contenuto
Riga di comando da eseguire
Cardinalità
Ogni nodo EXEC_PRE contiene 0..N nodi COMMAND
Pagina 8 di 28
 IMPORT_DOCUMENT/FILE/RECORDS
Proprietà
Nessuna
Contenuto
Records di lavoro
Cardinalità
Ogni nodo FILE contiene 1 nodo RECORDS
 IMPORT_DOCUMENT/FILE/RECORDS/RECORD
Proprietà
[verb]
indica l‟azione da eseguire sui dati (ADD / UPD / INS / DEL). Default: ADD
Contenuto
Dati di un record all‟interno del quale i campi sono identificati dai tag il cui nome è specificato nei nodi DDS/FIELD.
Es.
<F1>Valore campo</F1>
(F1 tag campo assegnato nel DDS/FIELD)
I campi sono descritti attraverso tag XML la cui sintassi è la seguente:
<NomeCampo>Valore campo</NomeCampo>
oppure
<FIELD name=”NomeCampo”>Valore campo</FIELD>
NomeCampo fa riferimento alla sorgente.
Cardinalità
Ogni nodo RECORDS contiene 1..N nodi RECORD
 IMPORT_DOCUMENT/FILE/EXEC_POST
Proprietà
Nessuna
Contenuto
Una lista di comandi da eseguire sulla macchina
Cardinalità
Ogni nodo FILE contiene 0..1 nodi EXEC_POST
 IMPORT_DOCUMENT/FILE/EXEC_POST/COMMAND
Proprietà
Nessuna
Contenuto
Riga di comando da eseguire
Cardinalità
Ogni nodo EXEC_POST contiene 0..N nodi COMMAND
Pagina 9 di 28
3.2 File esterno per la definizione di un DDS
<DDS>
<FIELD />
…
<FIELD />
</DDS>
Di seguito è riportata una breve descrizione dei nodi che compongono il file di descrizione di una tabella tramite il suo DDS.
 DDS
Root del documento.
Proprietà
Nessuna
Contenuto
Contiene la descrizione dei campi nel file di destinazione
Cardinalità
Ogni file XML che descrive un importazione contiene 1 nodo DDS
 DDS/FIELD
Proprietà
name
nome del campo
sqltype
tipo di campo (vedi paragrafo “Tipi di dato”)
dblen
lunghezza del campo (se applicabile, vedi paragrafo tipi di dato)
decimals
numero di decimali del campo (se applicabile, vedi paragrafo tipi di dato)
[tag]
nome del tag all‟interno dei nodi RECORD con cui ci riferiamo a questo campo (equivalente a
specificare un blocco match)
[ccsid]
Contenuto
Cardinalità
Ogni nodo DDS contiene 1..N nodi FIELD
3.2.3 Esempio
<DDS>
<FIELD name=”ID” sqltype=”INTEGER” />
<FIELD name=”Nome” sqltype=”CHAR” dblen=”30” />
<FIELD name=”Cognome” sqltype=”CHAR” dblen=”50” />
</DDS>
Pagina 10 di 28
3.3 File esterno per la definizione dei Matching
<MATCH>
<FIELD />
…
<FIELD />
</MATCH>
Di seguito è riportata una breve descrizione dei nodi che vanno a comporre il file di descrizione dei match.
 MATCH
Root del documento
Proprietà
Nessuna
Contenuto
Contiene le informazioni per effettuare il mapping tra i campi sorgente e quelli destinazione
Cardinalità
Ogni file XML che descrive un importazione contiene 1 nodo MATCH
 MATCH/FIELD
Proprietà
source
nome del campo sorgente
dest
nome del campo destinazione
Contenuto
Nessuno
Cardinalità
Ogni nodo MATCH contiene 1..N nodi MATCH/FIELD
3.3.3 Esempio
<MATCH>
<FIELD source=”FIELD01” dest=”ID” />
<FIELD source=”FIELD02” dest=”Nome” />
<FIELD source=”FIELD03” dest=”Cognome” />
</MATCH>
Pagina 11 di 28
4 TRIGGER SU EVENTI DI IMPORTAZIONE
Per aumentare la flessibilità e la modularità del prodotto è stato introdotto un sistema di trigger che consente una gestione
avanzata del processo di importazione mediante il richiamo di procedure esterne.
Sono stati previsti gli eventi descritti nella tabella che segue:
Nome
Evento
Utilizzo consigliato
onFileStart
Ogni volta che si apre un file tag
Notifica l‟inizio di un lavoro di importazione
onFileError
Alla chiusura del file tag se sono stati registrati Notifica la conclusione di un lavoro parzialmente o
errori
totalmente fallito
onFileFinish
Alla chiusura del file tag
Notifica la conclusione di un lavoro di
importazione (riuscito o meno)
onRecordValidate
Ogni volta che un record deve essere
elaborato
Consente la validazione dei dati all‟interno del
record prima della loro importazione
onRecordImport
Ogni volta che un record deve essere
elaborato (dopo la validazione)
Sovrascrive la funzione di importazione del record
onRecordError
Al termine di ogni importazione record fallita
Notifica importazione record fallita
onRecordDone
Al termine di ogni importazione record riuscita
Notifica importazione record riuscita
Ogni qual volta il processo di importazione si trova in una delle fasi sopra descritte DBImport verifica se è stato specificato
un gestore per tale evento e se è così lo richiama.
4.1 Specifica dei trigger
La specifica dei trigger da scatenare durante il processo di importazione può essere fatta all‟interno del file XML di
importazione o in un file esterno.
4.1.1 Specifica all’interno del file di importazione
I gestori per gli eventi vengono specificati come proprietà del tag file.
Sono state previste le proprietà: onFileStart, onFileError, onFileFinish, onRecordValidate, onRecordImport, onRecordError,
onRecordDone
Il valore di queste proprietà è una stringa “LIBRERIA/PROGGEST”
Es.
<?xml … ?>
<IMPORT_DOCUMENT>
…
<FILE … onRecordValidate=”MYLIB/VALIDATOR” onRecordError=”MYLIB/NOTIFYERR” … >
…
</FILE>
…
</IMPORT_DOCUMENT>
4.1.2 Specifica in un file di definizione esterno
Qualora non sia possibile o non sia indicato specificare tutti i gestori degli eventi all‟interno del file di importazione è possibile
ricorrere ad un file esterno in formato xml, la cui sintassi è specificata nel capitolo “File esterno specifica trigger”.
Ci si riferisce a questo file di specifica attraverso la proprietà “trigger” del tag FILE (permettendo l‟utilizzo di un set di gestori
diverso per ogni lavoro di importazione).
Qualora siano presenti informazioni sui trigger sia all‟interno del file xml di importazione che in un file esterno di specifica
trigger, le informazioni del file esterno (solo quelle definite) sovrascriveranno quelle del file di importazione.
Pagina 12 di 28
4.2 Parametri dei gestori degli eventi trigger
I programmi designati alla gestione degli eventi devono essere realizzati con una struttura fissa per consentire lo scambio di
informazioni con DBImport
4.2.1 Gestori eventi OnFile*
I parametri che vengono passati ai gestori di eventi tipo onFile (onFileStart, onFileError, onFileFinish) sono:
Numero Descrizione
1
Tipo
Percorso completo file xml di importazione
Alfanumerico 128 caratteri
DBImport non si aspetta valori di ritorno dalla chiamata ai gestori di questo tipo che quindi non influenzano in alcun modo il
comportamento del processo di importazione.
4.2.2 Gestori eventi OnRecord*
I parametri che vengono passati ai gestori degli eventi di tipo onRecord (onRecordValidate, onRecordImport, onRecordError,
onRecordDone) sono:
Numero Descrizione
Tipo
1
Buffer record
Alfanumerico
2
Dimensione in bytes del buffer record
Packed decimal 5,0
3
Schiera dei campi valorizzati („1‟ se il campo è citato)
Schiera 500 caratteri („0‟ o „1‟)
4
Azione richiesta (specificata come verb del record)
5
Esito dell‟operazione (impostato dal gestore)
Packed decimal 3,0
6
Messaggio di ritorno (impostato dal gestore)
7
Percorso completo file xml di importazione
Attraverso i parametri 5 e 6 i gestori degli eventi onRecord sono in grado di restituire un valore di ritorno a DBImport
influenzando il flusso di importazione dei dati.
L‟esito dell‟operazione segue la seguente condizione:
0
Operazione riuscita
> 0
Operazione riuscita (ma registra sul log il messaggio di ritorno)
< 0
Operazione fallita (errore)
Influenze sul flusso di importazione:
onRecordValidate
se il valore di ritorno è negativo il record non viene importato e viene marcato come fallito.
onRecordImport
se il valore di ritorno è negativo il record non viene importato e viene marcato come fallito.
onRecordError
nessuna influenza, solo notifica nei log.
onRecordDone
nessuna influenza, solo notifica nei log.
Il parametro numero 4 (Schiera dei campi valorizzati) è stato introdotto per consentire di discriminare i campi del record che
sono passati a *Blank per default o perché impostati a *Blank nel file di importazione.
In questa per ogni campo che è stato citato nell‟XML (anche se vuoto, es. <XCODIC />) il corrispondente carattere è
impostato „1‟. Per ogni campo che non viene citato il corrispondente carattere è impostato a „0‟.
Pagina 13 di 28
4.3 File esterno specifica trigger
<TRIGGERSET>
<EVENT />
…
<EVENT />
</ TRIGGERSET >
Di seguito è riportata una breve descrizione dei nodi che vanno a comporre il file di descrizione dei match.
 TRIGGERSET
Root del documento
Proprietà
Nessuna
Contenuto
Contiene le informazioni per specificare i gestori esterni degli eventi di importazione
Cardinalità
Ogni file XML che descrive un importazione contiene 1 nodo TRIGGERSET
 TRIGGERSET/EVENT
Proprietà
name
nome dell‟evento
handler
programma gestore dell‟evento (formato LIBRERIA/PROGGEST)
Contenuto
Nessuno
Cardinalità
Ogni nodo TRIGGERSET contiene 1..N nodi EVENT.
4.3.3 Esempio
<TRIGGERSET>
<EVENT name=”onFileStart”
handler=”MYLIB/DBFILSTA” />
<EVENT name=”onFileError”
handler=”MYLIB/DBFILERR” />
<EVENT name=”onFileFinish”
handler=”MYLIB/DBFILFIN” />
<EVENT name=”onRecordValidate”
handler=”MYLIB/DBRECVAL” />
<EVENT name=”onRecordImport”
handler=”MYLIB/DBRECIMP” />
<EVENT name=”onRecordError”
handler=”MYLIB/DBRECERR” />
<EVENT name=”onRecordDone”
handler=”MYLIB/DBRECDON” />
</TRIGGERSET>
Nota. Non è necessario specificare tutti i trigger: per quelli che non sono specificati verranno utilizzate le funzioni interne del
DBImport.
Pagina 14 di 28
5 TIPI DI DATO SUPPORTATI
I tipi di dato supportati dal programma per la generazione dei files e l‟importazione dei dati sono identificati dalle seguenti
keywords:
-
SMALLINT
numero intero di 2 byte
-
INTEGER
-
BIGINT
-
REAL
numero in virgola mobile di 4 byte
-
DOUBLE
numero in virgola mobile di 8 byte
-
ZONED
numero decimale
-
PACKED
numero decimale
-
CHAR
stringa di lunghezza fissa
-
VARCHAR
stringa di lunghezza variabile
-
DATE
data
-
TIME
ora
-
TIMESTAMP
data e ora
Nella specifica del campo DDS il tipo di dato utilizzato influenza le proprietà che vanno specificate.
In particolare:
-
Per i numeri interi (SMALLINT, INTEGER, BIGINT), per quelli in virgola mobile (REAL, DOUBLE) e per i tipi di dato
tempo (DATE, TIME, TIMESTAMP) vanno specificate le proprietà name ed sqltype (eventualmente tag).
-
Per i numeri decimali (PACKED, ZONED) vanno specificate le proprietà name, sqltype, dblen (numero di cifre totali)
e decimals (numero di cifre decimali) (eventualmente tag).
-
Per i tipi stringa (CHAR, VARCHAR) vanno specificate le proprietà name, sqltype, dblen (numero di caratteri
massimo per la stringa) (eventualmente tag).
Se verranno specificate altre proprietà saranno ignorate.
5.1 Note sui tipi Data/Ora
Il formato della data DEVE ESSERE YYYY-MM-DD (anno mese giorno).
Il formato delle ore DEVE ESSERE hh.mm.ss (ore minuti secondi).
Il formato del timestamp DEVE ESSERE YYYY-MM-DD-hh.mm.ss.uuuuuu (anno mese giorno ore minuti secondi
microsecondi).
Se la data, l‟ora o il timestamp non rispettano questo formato il programma fallirà l‟importazione dell‟intero record!
[Aggiornamento: 2017/03/03] E' stata estesa la possibilità di gestire formati data e ora differenti, qualora il file di
destinazione dell'importazione esista già e preveda altri formati data e ora.
Al momento non è possibile specificare nella sezione DDS, formati data e ora diversi da quelli indicati.
Pagina 15 di 28
5.2 Gestione CCSID
I dati del file di importazione vengono rappresentati internamente al programma in codifica UTF-EBCDIC.
Poiché al momento della scrittura su database in campi di tipo CHAR ed in campi di tipo VARCHAR è necessaria una
conversione verso il formato dati del campo di destinazione, per evitare la perdita di dati è stato introdotta una gestione dei
CCSID (Coded Character Set IDentifier).
Al momento della scrittura di un dato di tipo CHAR oppure VARCHAR su database DBImport effettuerà una conversione in
automatico verso:
-
CCSID impostato sul CAMPO destinazione
oppure in mancanza
-
CCSID impostato sul FILE di destinazione
oppure in mancanza
-
CCSID dell‟utente che ha lanciato il lavoro
Durante la creazione di un nuovo file fisico da parte di DBImport viene impostato di default il CCSID 65535 (HEX, nessuna
conversione).
E‟ possibile specificare il CCSID desiderato per il file o per il singolo campo utilizzando l‟attributo CCSID dei tag FILE e dei tag
FIELD della DDS.
NOTA
I CCSID specificati come attributi nel file XML di importazione hanno validità solo al momento della creazione di un nuovo file
poiché, al momento della scrittura dei records sul file di destinazione, DBImport ricarica la descrizione del formato dati dal
file fisico.
E‟ possibile vedere come sono impostati i CCSID sul file fisico e sui suoi campi utilizzando i comandi DSPFD e DSPFFD su
iSeries.
Pagina 16 di 28
6 FLOW CHART
Di seguito alcuni grafici che mostrano la logica del processo di importazione.
Figura 1 - Flusso del programma
In figura 1 è mostrato il flusso principale del programma partendo dall‟invocazione dalla riga di comando. L‟unica funzione
del programma è l‟interpretazione delle istruzioni contenute nel file XML passato come parametro.
Qualora la sintassi del file XML passato fosse errata il programma terminerà senza eseguire nessuna operazione.
Qualora fosse la semantica del file XML ad essere errata i risultati che si possono ottenere non sono prevedibili.
Pagina 17 di 28
Figura 2 - Inizializzazione file fisico di destinazione
In figura 2 è mostrata la logica della procedura di inizializzazione del file fisico di destinazione dalla quale si possono
facilmente ricavare le priorità di cui tiene conto DBImport nel leggere le informazioni quando queste sono disponibili in forme
diverse (è il caso delle informazioni di DDS/template per creare il file fisico o delle informazioni di Match).
Pagina 18 di 28
Figura 3 - Importazione dei record
In figura 3 è mostrato il flusso di importazione dei records nel file fisico di destinazione. Se il programma si trova in modalità
“Insert only” (vero quando il file fisico di destinazione è stato creato dal DBImport) i files vengono semplicemente aggiunti al
file destinazione assieme all‟informazione sull‟operazione che si intendeva svolgere sui dati (ADD, UPD, INS o DEL) ed un
numero unico progressivo (RRN).
Pagina 19 di 28
7 FILE MULTIMEMBRO
Qualora nella specifica del tag FILE sia presente la proprietà “member” si assume che il file di destinazione debba essere
multimembro.
La gestione dei file fisici multimembro funziona solo per file fisici già esistenti e per i quali è stata specificato un numero
massimo di membri superiore ad 1.
Per i files di destinazione multimembro è possibile specificare il membro di destinazione per i files:
-
se non specifico il membro di destinazione verrà utilizzato *FIRST
-
se specifico come membro di destinazione *NEW verrà creato un nuovo membro dal nome casuale
-
se specifico un nome membro il programma tenterà di aprirlo, se non esiste tenta di crearlo
Figura 4 - Scelta membro file di destinazione
Il riferimento al membro utilizzato in fase di importazione viene scritto nel file WGDBIMPS in particolare nel campo WGMBRN
del record corrispondente al lavoro di importazione corrente.
Pagina 20 di 28
8 IL FILE WGDBIMPS
Al termine di ogni lavoro di importazione viene scritto un record nel file WG4SYSFD/WGDBIMPS con alcune informazioni sul
lavoro eseguito.
La struttura del file WGDBIMPS è la seguente:
WGK18I
Identificatore univoco della sessione di importazione (18 caratteri)
WGFNUM
Identificatore del blocco file all‟interno del file XML di importazione
WGJOBN
Nome job
WGUSER
Nome utente
WGJNUM
Numero processo
WGDATE
Data di fine importazione
WGTIME
Ora di fine importazione
WGFLIB
Libreria di destinazione per il lavoro di importazione corrente
WGFILE
File di destinazione per il lavoro di importazione corrente
WGMBRN
Membro all‟interno del file di destinazione per il lavoro corrente
WGXMLP
Path assoluto su IFS al file xml di importazione
WGLOGP
Path assoluto su IFS del file di log per il lavoro di importazione corrente
Pagina 21 di 28
9 ESEMPI DI FILE DI IMPORTAZIONE
Gli esempi che seguono sono tutti completi e funzionanti.
Ogni esempio è costruito apportando piccole modifiche al precedente.
In tutti gli esempi presentati è mostrato un solo lavoro di importazione (un solo blocco file) tuttavia è possibile racchiudere in
un unico file xml un numero illimitato di lavori di importazione specificando più nodi file.
9.1 Esempio 1: Importazione in file esistente
Scenario:
Importazione per un solo file di destinazione (esistente), dati da importare racchiusi in tag con lo stesso nome dei campi
destinazione.
<IMPORT_DOCUMENT>
<FILE name=”RUBRICA” library=”UTENTI”>
<RECORDS>
<RECORD>
<ID>12</ID>
<Nome>Mario</Nome>
<Cognome>Rossi</Cognome>
</RECORD>
<RECORD>
<ID>19</ID>
<Nome>Giovanni</Nome>
<Cognome>Bianchi</Cognome>
</RECORD>
<RECORD verb=”DEL”>
<ID>63</ID>
</RECORD>
</RECORDS>
</FILE>
</IMPORT_DOCUMENT>
A fronte di un file di input di questo tipo il programma apre il file di destinazione (UTENTI/RUBRICA) insersce due nuovi
records ed elimina il record che ha per id 63.
NOTA:
Si assume che ID sia la chiave primaria del file.
Se il file di destinazione non contiene chiavi primarie non è possibile aggiornare o eliminare i records.
Pagina 22 di 28
9.2 Esempio 2: Richiamo comandi
Scenario:
Importazione per un solo file di destinazione (esistente), dati da importare racchiusi in tag con lo stesso nome dei campi
destinazione. Prima dell‟importazione viene lanciato un comando e al termine della procedura di importazione ne vengono
lanciati due.
Aggiungendo un blocco EXEC_PRE prima di RECORDS specifichiamo una serie di comandi da lanciare prima di importare i
dati.
Aggiungendo un blocco EXEC_POST dopo la chiusura di RECORDS specifichiamo una serie di comandi da lanciare al termine
dell‟importazione.
<IMPORT_DOCUMENT>
<EXEC_PRE>
<COMMAND>CALL PGM(‘PrepDati’)</COMMAND>
</EXEC_PRE>
<RECORDS>
<RECORD>
<ID>12</ID>
<Nome>Mario</Nome>
</RECORD>
<RECORD>
<ID>19</ID>
</RECORD>
<ID>63</ID>
</RECORD>
</RECORDS>
<EXEC_POST>
<COMMAND>CALL PGM(‘ElimDati’)</COMMAND>
<COMMAND>CALL PGM(‘NotifDati’)</COMMAND>
</EXEC_POST>
</FILE>
</IMPORT_DOCUMENT>
A fronte di un file di input di questo tipo il programma:
-
esegue il comando specificato nell‟EXEC_PRE
-
apre il file di destinazione (UTENTI/RUBRICA) inserirà due nuovi records ed eliminerà il record che ha per id 63
-
esegue i comandi specificati nell‟EXEC_POST
Pagina 23 di 28
9.3 Esempio 3: Nuovo file da template
Scenario:
Importazione per un solo file di destinazione (non esistente), dati da importare racchiusi in tag con lo stesso nome dei campi
destinazione.
Il file di destinazione non esiste e verrà creato sulla base di un file già esistente nel sistema (che funge da template).
<IMPORT_DOCUMENT>
<FILE name=”RUBRICA” library=”UTENTI” template=”DEFFILES/RUBRICA”>
<EXEC_PRE>
</EXEC_PRE>
<RECORDS>
<RECORD>
<ID>12</ID>
<Nome>Mario</Nome>
</RECORD>
<RECORD>
<ID>19</ID>
</RECORD>
<ID>63</ID>
</RECORD>
</RECORDS>
<EXEC_POST>
</EXEC_POST>
</FILE>
</IMPORT_DOCUMENT>
-
esegue il comando nel blocco EXEC_PRE
-
verifica l‟esistenza del file di destinazione (UTENTI/RUBRICA)
-
se il file non esiste lo crea sulla base del file di template specificato (DEFFILES/RUBRICA) aggiungendo due colonne
(DBIMPRRN che contiene il numero univoco del record e DBIMPVERB che contiene il codice (ADD, UPD, INS o DEL)
dell‟azione che si vuole eseguire sul record)
-
importa i dati nel file destinazione (se il file è stato creato non esegue le operazioni sul file ma si limita ad inserire
tutti i record abbinandogli un codice univoco ed allegando il codice dell‟azione che si vuole eseguire sul record)
-
Pagina 24 di 28
9.4 Esempio 4: Specifica match
Scenario:
Importazione per un solo file di destinazione (non esistente). Nomi dei campi all‟interno del file identificati da nomi simbolici
specificati all‟interno di un blocco match.
Il file di destinazione non esiste e verrà creato sulla base di un file già esistente nel sistema (che funge da template).
<IMPORT_DOCUMENT>
<FILE name=”RUBRICA” library=”UTENTI” template=”DEFFILES/RUBRICA”>
<MATCH>
<FIELD source=”F1” dest=”ID” />
<FIELD source=”F2” dest=”Nome” />
<FIELD source=”F3” dest=”Cognome” />
</MATCH>
<EXEC_PRE>
</EXEC_PRE>
<RECORDS>
<RECORD>
<F1>12</F1>
<F2>Mario</F2>
<F3>Rossi</F3>
</RECORD>
<RECORD>
<F1>19</F1>
<F2>Giovanni</F2>
<F3>Bianchi</F3>
</RECORD>
<F1>63</F1>
</RECORD>
</RECORDS>
<EXEC_POST>
</EXEC_POST>
</FILE>
</IMPORT_DOCUMENT>
Il comportamento è lo stesso di cui all‟Esempio 3.
-
-
-
se il file non esiste lo crea sulla base del file di template specificato (DEFFILES/RUBRICA) aggiungendo due colonne
-
Pagina 25 di 28
9.5 Esempio 5: Nuovo file da DDS
Scenario:
Importazione per un solo file di destinazione (non esistente). Nomi dei campi all‟interno del file identificati da nomi simbolici
specificati all‟interno di un blocco DDS.
Il file di destinazione non esiste e verrà creato sulla base delle informazioni incluse nel blocco DDS.
<IMPORT_DOCUMENT>
<DDS>
<FIELD name=”ID” sqltype=”INTEGER” tag=”F1” />
<FIELD name=”Nome” sqltype=”CHAR” dblen=”30” tag=”F2” />
<FIELD name=”Cognome” sqltype=”CHAR” dblen=”50” tag=”F3” />
</DDS>
<EXEC_PRE>
</EXEC_PRE>
<RECORDS>
<RECORD>
<F1>12</F1>
<F2>Mario</F2>
<F3>Rossi</F3>
</RECORD>
<RECORD>
<F1>19</F1>
<F2>Giovanni</F2>
<F3>Bianchi</F3>
</RECORD>
<F1>63</F1>
</RECORD>
</RECORDS>
<EXEC_POST>
</EXEC_POST>
</FILE>
</IMPORT_DOCUMENT>
-
-
-
se il file non esiste lo crea sulla base delle informazioni contenute nel blocco DDS aggiungendo due colonne
-
-
Pagina 26 di 28
9.6 Esempio 6: Tipi di dato
Quest‟esempio non è mostrato un file di importazione bensì la descrizione di un file fisico contenente un campo per ogni tipo
di dato supportato.
…
<DDS>
<FIELD name=”FIELD01” sqltype=”SMALLINT”
tag=”F1”
/>
<FIELD name=”FIELD02” sqltype=”INTEGER”
tag=”F2”
/>
<FIELD name=”FIELD03” sqltype=”BIGINT”
tag=”F3”
/>
<FIELD name=”FIELD04” sqltype=”REAL”
tag=”F4”
/>
<FIELD name=”FIELD05” sqltype=”DOUBLE”
tag=”F5”
/>
<FIELD name=”FIELD06” sqltype=”ZONED”
dblen=”10”
decimals=”4”
tag=”F6”
/>
<FIELD name=”FIELD07” sqltype=”PACKED”
dblen=”10”
decimals=”2”
tag=”F7”
/>
<FIELD name=”FIELD08” sqltype=”CHAR”
dblen=”50”
tag=”F8”
/>
<FIELD name=”FIELD09” sqltype=”VARCHAR”
dblen=”50”
tag=”F9”
/>
<FIELD name=”FIELD10” sqltype=”DATE”
tag=”F10”
/>
<FIELD name=”FIELD11” sqltype=”TIME”
tag=”F11”
/>
<FIELD name=”FIELD12” sqltype=”TIMESTAMP”
tag=”F12”
/>
</DDS>
…
Un DDS definito in questo modo porta alla creazione di un file fisico con i seguenti campi:
-
FIELD01 numerico intero 2 byte
non nullo
-
non nullo
-
non nullo
-
FIELD04 numerico virgola mobile 4 byte
non nullo
-
FIELD05 numerico virgola mobile 8 byte
non nullo
-
FIELD06 numerico zonato 10 cifre (4 decimali)
non nullo
-
FIELD07 numerico packed 10 cifre (2 decimali)
non nullo
-
FIELD08 stringa lunghezza fissa (50 caratteri)
non nullo
-
FIELD09 stringa lunghezza variabile (50 caratteri)
non nullo
-
FIELD10 data
non nullo
-
FIELD11 tempo
non nullo
-
FIELD12 data ora
non nullo
-
DBIMPRRN numerico zonato 10 cifre (0 decimali)
chiave primaria
-
DBIMPVERB stringa fissa 3 caratteri
chiave primaria
Pagina 27 di 28
9.7 Esempio 7: DDS e Match in file esterni
In quest‟ultimo esempio son riportati 3 file che mostrano come descrivere i blocchi DDS e di Match all‟interno di files esterni
a quello di importazione.
Es. file “/temp/dds01.xml”
<DDS>
<FIELD name=”ID” sqltype=”INTEGER” />
<FIELD name=”Nome” sqltype=”CHAR” dblen=”30” />
<FIELD name=”Cognome” sqltype=”CHAR” dblen=”50” />
</DDS>
Es. file “/temp/match01.xml”
<MATCH>
<FIELD source=”FIELD01” dest=”ID” />
<FIELD source=”FIELD02” dest=”Nome” />
<FIELD source=”FIELD03” dest=”Cognome” />
</MATCH>
Es. file “import.xml”
<IMPORT_DOCUMENT>
<FILE name=”RUBRICA” library=”UTENTI” dds=”/temp/dds01.xml” match=”/temp/match01.xml”>
<EXEC_PRE>
</EXEC_PRE>
<RECORDS>
<RECORD>
<FIELD01>12</FIELD01>
<FIELD02>Mario</FIELD02>
<FIELD03>Rossi</FIELD03>
</RECORD>
<RECORD>
<FIELD01>19</FIELD01>
<FIELD02>Giovanni</FIELD02>
<FIELD03>Bianchi</FIELD03>
</RECORD>
</RECORDS>
<EXEC_POST>
</EXEC_POST>
</FILE>
</IMPORT_DOCUMENT>
NOTA. Nell‟esempio sono stati specificati un blocco di match ed uno di DDS. In questi casi il blocco di match è inutile poiché
potrebbe essere tranquillamente sostituito dalla proprietà “tag” dei nodi field del DDS.
Pagina 28 di 28

DBImport – Manuale Utente

Transcript

Documenti analoghi

mod 7.4.6 “gli adempimenti doganali nel commercio internazionale”

Armani record di abbonati

Import Documenti

Allegato 3

L`arte erotica da record

Norme e regolamenti

DEL 2016

Perché questo Guinness è un RecoRd Mondiale di SolidaRietà: con