|
| |
IMPORTAZIONE in formato JASCII
FORMATO DEL FILE
JOLLY esegue importazioni di
dati all’interno del database leggendo dati da file scritti nel seguente
formato.
 | TABLE_START=nome (simbolico) della tabella |
| [TABLE_NAME=nome fisico della tabella] |
| NUMBER_OF_FIELDS=numero dei campi da
importare per la table |
| DATA_LENGTH={lunghezza di ogni riga di dati
(compreso l’asterisco che termina ogni riga) | VARIABLE (se la riga è a
lunghezza non fissa)} |
| [{IF_RECORD_EXISTS
| IF_ALREADY_IMPORTED} =
{ignore|ask|skip|update|delete_and_insert} [;if=§condizione sql§] [;sql_skip=§espressione
sql§] [;sql_update=§espressione sql§] [;sql_delete=§espressione sql§]] |
| [SQL_EXECUTE_BEFORE_IMPORT=espressione SQL]
|
| [SQL_EXECUTE_AFTER_IMPORT=espressione SQL]
|
| [SQL_EXECUTE_AFTER_ROW=espressione SQL]
|
| [DONT_REGISTER_IMPORTATION]
|
| [UPDATE_VIDEO_FREQUENCY=numero di records] |
| [LOGFILE={YES [:FIELDNAME] | NO} [, descrizione table]] |
| eventuali righe vuote |
| [eventuali altre tabelle, che devono rispettare lo
stesso formato, a partire dalla clausola TABLE_START fino alla clausola
DATA_END] |
| END_OF_FILE
|
E’ possibile importare fino a
24 tabelle nello stesso file.
VERSION
Numero di versione del formato di esportazione del file dati; valore exadecimale a 4
cifre: le prime due indicano la versione, le ultime 2 la release;
esempio: 0258 = 0x0102 = ver 1, rel 2.
Le versioni dei formati di importazione jascii sono le seguenti:
| versione |
data |
descrizione |
| 1.01 |
2003 |
versione iniziale della procedura |
| 1.02 |
15-02-2005 |
aggiunta della possibilità di esportazione di più
campi a lunghezza variabile (e non solamente di uno); anziché
essere registrati alla fine della prima (e unica) riga di dati, tali campi
vengono scritti in righe supplementari (una riga per ogni campo) |
La clausola UNIQUE_ID, inserita a partire dal luglio 2007, consente di identificare in modo univoco i files importati.
Serve per evitare di importare più volte, per errore, lo stesso file.
Il programma infatti si rifiuta di importare più di una volta files con lo stesso identificatore.
La clausola è facoltativa.
Se la clausola è presente, su NOMEFILE vengono
registrate le attività svolte dalla procedura di importazione. Se NOMEFILE
non è indicato, sarà utilizzato lo stesso nome del file dati con estensione .TXT.
Per attivare/disattivare le informazioni sulle singole tables, vedi la clausola LOGFILE=YES/NO.
Nomefile può contenere variabili di ambiente del sistema operativo
(esempio: %ProgramFilesDir%, oppure %TEMP%).
L'inserimento di questa clausola facoltativa
abilita/disabilita la proposta di lettura del file log (ovviamente solo se
questo è presente) al termine dell'esportazione. Il valore predefinito è NO.
Spesso, soprattutto se l'utente non è particolarmente brillante, la proposta di
lettura del file LOG (di cui non si capisce il significato né l'utilità) può
indurre confusione.
TABLE_NAME
Formato:
TABLE_NAME=nome fisico della tabella
La clausola è
facoltativa. Serve per quei (rari) casi in cui si desidera importare sulla
stessa tabella di destinazione dati provenienti da due tabelle diverse. In
questo caso è necessario usare due nomi diversi nella clausola TABLE_START, e
il nome reale della tabella di destinazione in TABLE_NAME.
Esempio:
TABLE_START=telefoni_telefoni
TABLE_NAME=telefoni
…..
TABLE_END
TABLE_START=telefoni_fax
TABLE_NAME=telefoni
…..
TABLE_END
OPZIONI
TABELLA
Le seguenti opzioni possono
essere indicate per ogni tabella.
| IF_RECORD_EXISTS
| IF_ALREADY_IMPORTED = {ignore|skip|update|delete_and_insert}[;if=§condizione
sql§] [;sql_skip=§espressione sql§] [;sql_update=§espressione sql§] [;sql_delete=§espressione
sql§]
Questa opzione consente di controllare la circostanza che il record sia già
stato importato, oppure che esista già sulla tabella di destinazione (le
due circostanze, ancorchè simili e spesso coincidenti, sono molto ben
distinte, soprattutto nel caso in cui la primary key sulla table di
destinazione sia generata al momento dell’importazione). Qualora sia
possibile, è preferibile usare il controllo sulla tabella di destinazione,
in quanto di più semplice ed efficace gestione.
NB: per utilizzare questa opzione è necessario aver definito la primary key
per la table. |
 | IF
ALREADY_IMPORTED >> se lo stesso record (stesso record significa:
stesso codice esportatore e
stessa primary key sulla tabella originale) è già stato importato |
| IF_RECORD_EXISTS
>> se il record esiste già nella table di destinazione; |
se la
condizione indicata è vera viene eseguita una delle seguenti operazioni:
| IGNORE: non viene eseguito alcun
controllo sull’esistenza del record; |
| ASK: viene chiesto all’utente cosa
fare; valore DEFAULT se l’opzione non viene indicata; |
| SKIP: il record viene semplicemente
ignorato; |
| UPDATE: il record viene aggiornato; |
| DELETE_AND_INSERT: il record viene
prima eliminato e poi importato. |
L’operazione viene eseguita solo se la condizione
(opzionale) risulta verificata; se la condizione non è verificata l’azione
eseguita è l’opposto di quella proposta: SKIP > UPDATE, UPDATE > SKIP,
DELETE > SKIP; la condizione può contenere:
| campi del record da importare compresi
tra $ e $ |
| campi del record esistente compresi
tra $@ e @$ (l’uso dei campi del record da importare è in generale
preferibile per motivi di performance) |
La
condizione deve essere un predicato booleano in sintassi SQL. Ad esempio:
| IF_RECORD_EXISTS=update; IF = $dt_update$ > $@dt_update@$
|
| IF_RECORD_EXISTS=delete; IF = $dt_update$ <= $@datetime_exportation@$
|
Possono essere opzionalmente indicate espressioni
SQL che sono collegate ai vari eventi e che vengono eseguite prima dell’evento
(solo se l’evento si verifica). Sulle espressioni SQL vengono eseguite le
stesse sostituzioni previste per la condizione.
L'opzione si ripercuote a cascata sulle tabella
collegate attraverso un legame di FOREIGN KEY (le righe figlie subiranno lo
stesso trattamento della riga padre) a meno di specifiche ulteriori condizioni
espresse sulle righe figlie.
Il valore default è:
| IF_RECORD_EXISTS
>> ASK
|
| IF ALREADY_IMPORTED >>
IGNORE (nessun controllo)
|
| DONT_REGISTER_IMPORTATION: qualora sia
abilitata l'opzione di registrazione delle righe importate, la tabella
risulta comunque esclusa da tale trattamento; |
| DONT_REGISTER_KEYS:
evita che venga registrato il valore di tutte le righe importate; può
essere usato solo da tabelle la cui Primary key non è referenziata da
Foreign Keys di altre tabelle; serve per velocificare (sostanzialmente) il
caricamento di tabelle con un enorme numero di righe; |
| SQL_EXECUTE_AFTER_ROW=espressione SQL: una o
più espressioni SQL che vengono eseguite per ogni riga subito dopo
l'importazione della riga; ogni espressione può occupare una riga. E’
possibile indicare il nome di campi della riga, compresi tra una coppia di
$. |
| SQL_EXECUTE_BEFORE_IMPORT=espressione
SQL:
una
o più espressioni SQL che vengono eseguite prima dell’importazione
della table; non vengono eseguite sostituzioni. |
| SQL_EXECUTE_AFTER_IMPORT=espressione SQL: una
o più espressioni SQL che vengono eseguite al termine dell’importazione
della table; non vengono eseguite sostituzioni. |
| [MESSAGE_FIELD=nomecampo]
il campo indicato sarà utilizzato per la compilazione del
registro di importazione e per tutti i messaggi utente |
| LOGFILE={YES [:FIELDNAME]
| NO} [,descrizione table] attiva/disattiva la registrazione su file
dei record importati. Presuppone l’esistenza di una clausola LOGFILE=filename.
Il campo referenziato nel file log sarà FIELDNAME; se FIELDNAME non viene
indicato (e/o se non viene indicata la clausola LOGFILE), sarà utilizzato
MESSAGE_FIELD o, in subordine, il primo campo della table. Il valore DEFAULT
è YES (attivato dalla clausola LOGFILE
generale). |
FORMATO CAMPO
Per ogni campo esportato si deve
inserire una riga che descrive nome, tipo e caratteristiche del campo.
La sintassi è la seguente:
[!]name tipo
[col_start {size|*}] [SQL=§espressione
SQL§] [PK] [FK:table] [autoincrement] [commenti]
| ! |
indica che il campo deve
essere riempito a spazî, e non trimmato;
per default il campo viene trimmato |
| name |
il nome del campo SQL |
| tipo |
il tipo di campo: può essere uno dei tipi già definiti per
l’esportazione |
| col_start |
colonna di inizio dei dati; il campo non è obbligatorio, ma se
non presente è obbligatorio che sia presente l’opzione SQL |
| size | * |
numero di colonne occupate dal campo nel file ascii;
il campo non è
obbligatorio, ma se non presente deve essere presente la clausola SQL.
Se
tipo = S, in luogo delle dimensioni del campo è possibile specificare un
asterisco, ad indicare che il campo ha dimensione variabile. Per ogni campo
marcato dall'asterisco il programma legge una riga di dati supplementare
rispetto a quella base, e l'associazione tra campo e riga viene realizzata
in funzione dell'ordine di dichiarazione dei campi. |
| SQL |
al campo sarà assegnato il risultato del dell’istruzione SQL
specificata;
è possibile referenziare il nome di altri campi della tabella purché indicati tra $$ e dichiarati prima del campo in trattamento;
esempio: SQL=§select valore FROM pconti WHERE str_codice = $str_conto$§
|
| PK |
indica che il campo fa parte della Primary Key per la table;
una
table dovrebbe sempre avere una PK quantomeno per la verifica
dell’esistenza o meno del record che si sta caricando; qualora una table
sia priva di PK non sarà eseguito alcun controllo di esistenza |
| FK:table |
indica
che il valore campo referenzia un corrispondente valore presente sulla
master table indicata. Il nome usato non è quello della tabella fisica (TABLE_NAME)
ma quello simbolico (TABLE_START).
Se il valore sulla master table viene modificato
dalla procedura di importazione (perché, ad esempio, si tratta di un campo
da generare come AUTOINCREMENT), il valore sulla tabella accessoria
sarà automaticamente e corrispondentemente modificato. In caso di tabelle
con primary key composta da più campi, l'ordine di riferimento è
strettamente posizionale. E' perciò rigorosamente necessario inserire i campi della foreign key sulla
detail table esattamente nello stesso ordine dei campi della primary key
sulla master table |
| AUTOINCREMENT |
il valore del campo sarà generato al momento dell’importazione
in modo da garantirne l’univocità;
si utilizza soprattutto (o meglio:
esclusivamente) per le primary keys prive di valore intrinseco; l’opzione AUTOINCREMENT
è incompatibile con l’opzione SQL
|
| REM |
REMarks, ovvero commento, ovvero il campo viene trattato sotto
tutti gli aspetti ma non viene scritto nel database di destinazione |
| commenti |
informazioni sul
significato o sulla struttura del campo |
SEZIONE DATI
La sezione
dati può avere due formati:
| può contenere una (o più) righe di dati per
ogni record da importare |
| DATAFILE=nomefile
specifica che i dati si trovano su nomefile; nomefile
può contenere variabili di ambiente del sistema operativo
(esempio: %ProgramFilesDir%, oppure %TEMP%). |
In entrambi i
casi i dati devono avere lo stesso formato e seguire le seguenti regole:
| ogni riga contiene un record a lunghezza fissa e chiuso da un asterisco;
fa eccezione il caso in cui si abbiano dati a lunghezza variabile, ciascuno
dei quali occupa una riga supplementare ed ha lunghezza, appunto, variabile; |
| eventuali sequenza di 'acapo' (CR/LF,
ascii #013#010) devono essere codificate come \| (ascii #092#124); |
| eventuali caratteri speciali (non
alfanumerici) vengono codificati con la sequenza \nn dove nn è il codice
esadecimale ASCII del carattere (numero su due posizioni); il back slash da
solo viene codificato come \\ (doppio backslash); |
| il separatore decimale per i campi
numerici è la virgola; |
| non devono essere indicati separatori
delle migliaia; |
| i valori NULL sono indicati dal descrittore (NULL)
parentesi comprese; ne consegue che i campi che possono contenere valori
NULL dovranno essere larghi almeno 6 colonne (per contenere il descrittore
speciale). |
OS_EXECUTE_BEFORE/OS_EXECUTE_AFTER (esecuzione comando Sistema Operativo)
Durante l'esecuzione dello script di esportazione è possibile eseguire dei
comandi batch (formato BAT o CMD) usando la sintassi: OS_EXECUTE_xxxxx=comando.
BEFORE fa eseguire il comando prima dell'esportazione, AFTER lo fa eseguire DOPO
l'esportazione.
Se il comando è definito sull'intestazione di una specifica
tabella, i comandi sono eseguiti rispettivamente prima o dopo l'esportazione
della tabella.
Il comando può contenere variabili di ambiente del sistema operativo (esempio:
%ProgramFilesDir%, oppure %TEMP%).
Per emettere un messaggio è possibile usare la sintassi (vedi MESSAGEBOX
esportazione per ulteriori dettagli sintattici)
MESSAGEBOX=TEXT=testo;CAPTION=titolo[;FLAGS=numero]
Interrompe l'importazione emettendo un messaggio di errore.
ABORT=TEXT=testo;CAPTION=titolo
Valori ammessi: ON, OFF. Default: ON.
Se l'opzione è attiva il programma carica tutti i comandi di esportazione su una table transitoria (SQL_batch) e quindi una
stored procedure (exec_SQL_batch()) per eseguirli. Questa modalità è utile in certi casi particolari per trattare dati che altrimenti creerebbero problemi di esecuzione.
DBS, ovvero DataBase System, indica il database su cui si sta operando.
I possibili valori sono ASA (Adaptive Server Anywhere), SQLSERVER, OTHER.
Il default è ASA.
UPDATE_VIDEO_FREQUENCY
UPDATE_VIDEO_FREQUENCY=numero di records
Indica ogni quanti records il programma deve
aggiornare il video durante la fase di importazione. Default = 7.
MACRO PREDEFINITE
In tutti i punti del file da
importare è possibile usare una delle seguenti macro predefinite. Risulta
particolarmente comodo utilizzare queste macro sulle clausole IMPORT_OPTIONS
del file che definisce il formato di esportazione.
| macro |
disponibile a partire dalla
versione |
valore sostituito |
| @@datetime_exportation |
1.02 |
timestamp (YYYY-MM-DD HH:MM:SS) del momento in cui è avvenuta l’esportazione |
| @@computer_name |
1.02 |
computer che esegue l'importazione |
| @@ |
1.02 |
nome dell'operatore che esegue l'importazione |
Pagina base del manuale
di JOLLY
ESPORTAZIONE in formato JASCII
|
