EXPORTAZIONE in formato JASCII

FORMATO DEL FILE

(i campi facoltativi sono indicati tra parentesi quadre)

La doppia barra commenta il resto della riga su cui si trova (in qualunque posizione).
Il punto e virgola sulla prima colonna commenta l'intera riga.
Un underscore a fine riga considera la riga successiva come una continuazione della precedente (come in Visual Basic).

IF:condizione;istruzione

L'istruzione specificata viene eseguita solo se la condizione è verificata. La condizione deve essere una condizione booleana contenente gli operatori   =   !=   <   >   <=   >=
E' possibile raggruppare predicati tra parentesi tonde. E' possibile usare AND logici (usare il simbolo && ) e OR logici (simbolo || ). Esempi:

IF:@@QTA=0;SKIP_TABLE
IF:@@QTA=0 && @@POS=1;SKIP_TABLE
IF:(@@QTA=0 && @@POS=1) || @@X > @@Y;SKIP_TABLE

INCLUDE

La clausola INCLUDE, che deve essere specificata sulla prima colonna della riga, carica all'interno del testo il contenuto del file specificato.
E' possibile eseguire inclusioni all'interno di files inclusi. Esempio:

INCLUDE=prova.txt
INCLUDE=x:\bin\esportazione\dtx.txt

CAPTION=

Inserire il titolo del formato di esportazione, ovvero la sua descrizione breve. Il valore inserito sarà utilizzato, ad esempio, nelle finestre di selezione del formato di esportazione da utilizzare.
La riga contenente il caption è facoltativa, ma nel caso sia presente DEVE essere la prima riga del file. Prima del CAPTION non sono ammesse neppure righe di commento o di qualunque altro genere.

EXPORT_TYPE={JASCII|TEXT}

L'opzione è facoltativa; il valore default è JASCII.

MACRO

Il termine MACRO è da intendersi nel senso in cui è usato nel linguaggio C: ogni occorrenza dell'identificatore di macro viene rigidamente sostituita dal valore assegnato alla macro. L'unica eccezione a questo comportamento è rappresentata da eventuali espressioni SQL che vengono interpretate immediatamente (cioè prima dell'assegnazione).
La definizione delle macro può avvenire nella sezione di intestazione del file oppure nell'intestazione di ciascuna table. Le macro definite nell'intestazione di una tabella hanno valore limitato alla tabella entro cui sono state definite.
Il nome di ogni macro DEVE iniziare con @@ (ad esempio: @@NOME). Gli oggetti il cui nome inizia con @@ sono macro.

E' possibile effettuare dichiarazioni di macro secondo uno dei seguenti formati:

La prima forma di dichiarazione consiste in una mera assegnazione di un certo valore alla macro. La seconda forma delle macro è interattiva in quanto richiede all'utente di indicare una risposta al momento dell'esportazione dei dati.
La dichiarazione di una macro interattiva deve essere redatta secondo una di queste sintassi:

Il valore di tutte le opzioni può essere indicato da una espressione SQL racchiusa tra §. Tale valore viene determinato immediatamente, e non viene espanso ad ogni citazione della macro.

Esempi di dichiarazione di macro interattive:

L'ordine di interpretazione delle macro è il seguente:

MACRO PREDEFINITE
Le seguenti macro sono predefinite e sono liberamente utilizzabili:

TEXT_HEADER e TEXT_FOOTER

Definiscono una o più righe di testo che vengono scritte in testa al file prodotto dall'esportazione. Ad esempio:

TEXT_HEADER=SPEED 2.0
TEXT_HEADER=DENSITY 8
TEXT_HEADER=SET CUTTER OFF

TEXT_FOOTER=PRINT 1,1

L'opzione può essere utilizzata sia sull'intestazione del file che sull'intestazione di ciascuna delle tabelle esportate.
L'opzione è utilizzabile solo se TIPO_EXPORT = TEXT.

OUTPUT_FILENAME_FORMAT

Nome del file di output. Se non specificato viene utilizzato un nome default.
Il nome del file può contenere variabili di ambiente del sistema operativo (esempio: %ProgramFilesDir%, oppure %TEMP%). Nel nome del file sono eseguite le seguenti sostituzioni:

Esempio: se oggi è il primo febbraio 2003 e sono le 12:15:44, l' istruzione OUTPUT_FILENAME_FORMAT=EXP_BOLLE_%d_%t.DAT produrrà un nome di file del tipo EXP_BOLLE_20030201_121544.DAT.

EMAIL_ADDRESS

Dopo la generazione del file viene proposta in automatico la spedizione dello stesso all’indirizzo specificato. Se l’indirizzo viene lasciato vuoto, l’indirizzo la spedizione sarà proposta ugualmente e l’indirizzo dovrà essere specificato al momento dell’invio.
E’ possibile indicare più indirizzi separati da puntoevirgola.

SCRIPT_VERSION

Identificativo della versione dello script utilizzato per generare l’output. E’ un valore alfanumerico che funge esclusivamente da riferimento.

SQL_EXECUTE_BEFORE_EXPORT

Istruzione SQL che viene eseguita prima dell’importazione. La clausola può essere ripetuta.
Tale istruzione può essere utile per la preparazione dei dati da esportare.

SQL_EXECUTE_AFTER_EXPORT

Istruzione SQL che viene eseguita dopo l’importazione. La clausola può essere ripetuta.
Tale istruzione può essere utile per la preparazione dei dati da esportare.

TABLE_START=nome tabella da esportare

Indicare l'inizio del blocco di istruzioni relative ad una tabella da cui si desidera esportare dati.
Il nome specificato non è necessariamente il nome della tabella fisica da esportare, ma è estremamente significativo sotto due aspetti:

A volte è necessario trattare più volte la stessa tabella nella stessa procedura di esportazione/reimportazione. Poiché è impossibile ripetere l'attributo TABLE_START con lo stesso nome di tabella bisogna utilizzare la clausola TABLE_NAME.

SQL_SELECT

Contiene l'istruzione di selezione dei dati che si desidera esportare.

NB: durante la preparazione all'esportazione JOLLY carica il riferimento ai dati da esportare sulla table TEMP.
La primary key dei records da esportare è caricata su TEMP.STR_CODICE (se testo) oppure TEMP.LO_KEY (se integer).
In genere si deve perciò costruire un JOIN con la table TEMP che renda i soli records che si desidera esportare.

MESSAGE_FIELD

Identifica il record e che viene utilizzata per la generazione di eventuali messaggi relativi a specifici records. Se non indicata, all'occorrenza viene utilizzato il primo campo (o la primary key, se definita). Non può essere un’espressione, deve essere per forza il nome di un campo (oppure può essere un’espressione SQL definita dalla clausola SQL_SELECT.

Esempio:            MESSAGE_FIELD = NUMERODOC

DATAFILE

Se questa clausola è assente, i dati vengono scritti sul file principale di esportazione.
Se invece la clausola è presente, i files vengono esportati, privi di qualunque indicazione di formattazione, sul file specificato. In luogo dei dati, sul file di esportazione principale comparirà l’indicazione

DATAFILE=nomefile

Se privo di path, nomefile sarà creato sulla cartella default. Se il file indicato esiste già, sarà cancellato senza alcun avvertimento prima di eseguire l’operazione di esportazione.
Vengono eseguite le stesse sostituzioni valide per OUTPUT_FILENAME_FORMAT.
L'opzione è valida solo se TIPO_EXPORT = JASCII.
Nomefile può contenere variabili di ambiente del sistema operativo (esempio: %ProgramFilesDir%, oppure %TEMP%).

SQL_EXECUTE_AFTER_ROW = espressione SQL

Consente di specificare una espressione SQL che deve essere eseguita subito dopo l’importazione di ogni riga; ogni espressione può occupare una riga. E’ possibile indicare il nome di campi della riga, compresi tra coppie di $. E’ possibile indicare più volte l’opzione.

SQL_EXECUTE_AFTER_EXPORT = espressione SQL
SQL_EXECUTE_BEFORE_EXPORT = espressione SQL

Consente di specificare una espressione SQL che deve essere eseguita al termine/ prima dell’importazione delle righe per la table; non vengono eseguite sostituzioni (salvo le macro, naturalmente). E’ possibile indicare più volte l’opzione.

IMPORT_OPTIONS

Questa clausola specifica una opzione che si desidera venga riportata sul file di output, in modo da poter essere utilizzata durante la successiva eventuale importazione.

Tale opzione non influisce in alcun modo sul processo di esportazione. La sintassi dell’opzione sarà valutata al momento dell’importazione.
La clausola può comparire più di una volta, per poter specificare più opzioni.
Se indicata nella sezione delle opzioni generali, la clausola sarà riportata nella sezione delle opzioni generali. Se indicata all’interno di una table, la clausola sarà riportata all’interno della table.

CHECK | WARNING

Durante l’esportazione viene verificato che l’espressione SQL specificata sia soddisfatta. Per soddisfatta si intende che l’espressione deve restituire almeno una riga.
Qualora l’espressione non sia soddisfatta viene emesso un messaggio e, nel caso di CHECK, viene immediatamente interrotta l’esportazione.
L’espressione deve essere delimitata da § e può contenere i campi esportati, delimitati da $. Ad esempio:

    CHECK=§SELECT fl_sum(cr_importo) != 0 FROM vendite WHERE lo_key = $LO_KEY$§

    WARNING=§SELECT codice FROM aa WHERE codice = ‘$codice$’;ARTICOLO NON ESISTENTE§

L'opzione è disponibile solo se EXPORT_TYPE=JASCII.

SINTASSI DEI CAMPI ESPORTATI

[nomecampo=]sql_field_name[,tipo[:len[:dec]][*]] [,REM] [,PK] [,FK: table] [,{autoincrement | compute} = §§sql expression§§][--commento]

NOMECAMPO è il nome del campo utilizzato nel file di output.

SQL_FIELD_NAME è il nome del campo nella tabella di origine. Può assumere valori espressi secondo una differente sintassi (vedi valori speciali SQL_FIELD_NAME).

Ogni campo viene esportato nel suo formato naturale, a meno che non gli vengano fornite specifiche istruzioni di formattazione

PK indica che la colonna fa parte della Primary Key per la table.

FK indica l'esistenza di una FOREIGN KEY con la table specificata; utilizzare il nome indicato sulla clausola TABLE_START. Non viene eseguito alcun controllo sul nome della tabella referenziata.

NB: le opzioni PK e FK possono essere utili perché caricano sul file esportato informazioni necessarie per il trattamento dei dati.

Per i tipi stringa e blob è possibile utilizzare, in alternativa alla dichiarazione di lunghezza del campo, l'indicatore * (asterisco), che indica che il campo è a lunghezza variabile. Il valore dei campi marcati con l'asterisco viene riportato su righe dati supplementari, in ordine di dichiarazione.

La clausola AUTOINCREMENT consiglia di generare un nuovo valore per il campo durante l'importazione (o quanto meno, segnala che ciò è possibile senza particolari problemi, in quanto il campo è una chiave di collegamento priva di valore intrinseco). Per la gestione delle foreign keys, vedi più sotto.

La clausola COMPUTE funziona in modo analogo ad AUTOINCREMENT, ma il valore che deve essere assunto dal campo viene determinato dall’espressione indicata. L’espressione sarà valutata al momento dell’importazione. Per referenziare dei campi della tabella metterli fra coppie di $$ (esempio: $$i_codice$$).
La clausola COMPUTE deve essere usata solo su campi di tipo integer.

La clausola REM fa in modo che il campo venga esportato normalmente, ma la dichiarazione per il dato sul file di output risulti commentata. Serve per quei campi che non possono essere importati nel database di destinazione.

Il commento finale deve iniziare con un doppio trattino ( -- ). Differisce dal commento standard (//) perché viene riportato sul file esportato, mentre il commento standard viene semplicemente e bellamente ignorato.

Valori speciali di SQL_FIELD_NAME

LOCAL QUERY (immediata)

SQL_FIELD_NAME può essere sostituito da una espressione SQL che viene eseguita al momento dell’esportazione. Tale espressione segue le seguenti regole:

Esempio di sintassi per una espressione SQL:

NOMECAMPO=§select str_codice_export FROM pconti WHERE str_codice = '$str_codice$'§,S:-30

LOCAL QUERY (da eseguirsi durante la successiva importazione)

SQL_FIELD_NAME può essere sostituito da una espressione SQL che viene eseguita al momento della eventuale successiva importazione (durante la scrittura dei dati, ovvero dopo aver verificato e deciso che la riga deve essere importata). Tale espressione segue le seguenti regole:

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_xxxx=comando. BEFORE fa eseguire il comando prima dell'esportazione, AFTER dopo che l'esportazione è terminata.
Il comando può contenere variabili di ambiente del sistema operativo (esempio: %ProgramFilesDir%, oppure %TEMP%).

MESSAGEBOX

Per emettere un messaggio è possibile usare la sintassi

MESSAGEBOX=TEXT=testo;CAPTION=titolo[;FLAGS=numero]

Il valore FLAGS=NUMERO può essere assegnato attraverso le comode macro predefinite (@@ICONQUESTION, @@ICONSTOP, ....). E' equivalente al corrispondente parametro della funzione MessageBox() di Windows (mettere in OR i valori per combinarli tra loro): 

OK = 0
CANCEL = 1
YESNO = 2
RETRY = 4
ICONSTOP = 16
ICONQUESTION = 32
ICONINFORMATION = 64
DEFBUTTON2 = 256
DEFBUTTON3 = 512

Se l'opzione FLAGS non è indicata, il valore utilizzato è MB_OK. Se l'utente fornisce alla MessageBox() una risposta diversa da IDOK, IDRETRY e IDYES l'operazione di esportazione viene interrotta.

ABORT

Interrompe l'esportazione emettendo un messaggio di errore.

ABORT=TEXT=testo;CAPTION=titolo

SKIP_TABLE=condizione

La tabella NON viene esportata. Questa clausola viene solitamente usata insieme alla clausola IF.

TEXT

La clausola TEXT indica l'inizio della sezione testo della sezione in cui deve essere indicato il testo da registrazione sul file per ciascuno dei records esportati. Il testo può contenere riferimenti campi della query, che vengono sostituiti con i corrispondenti valori, a patto che tali riferimenti siano racchiusi tra coppie di $. La sezione viene chiusa dalla clausola TABLE_END. Ad esempio

[...]
TEXT
TEXT 10,50,"3",0,1,1,"$$BA_str_articolo$$", 
BOX 24,121,700,571,3
BARCODE 38,825,"EAN128",33,1,0,2,2,"ABCX"
PRINT 1,$$BA_fl_qta$$
TABLE_END

SKIP_END_OF_WORK_MESSAGEBOX

Al termine dell'esportazione normalmente il programma mostra un messaggio di riepilogo delle operazioni eseguite e chiede all'utente se desidera vedere il file generato. Specificando l'opzione SKIP_END_OF_WORK_MESSAGEBOX tale messaggio non viene mostrato (a meno che non vi siano segnalazioni di errore o anomalia).

USE_STORED_PROCEDURE

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

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.

LOG_SQL_EXPORT

LOG_SQL_EXPORT=[filename]

Esporta le istruzioni SQL che hanno generato l'export sul file specificato. Se il file non è specificato, usa il nome del file del formato di exportazione e appone l'extensione .SQL.
Filename può contenere variabili di ambiente del sistema operativo (esempio: %ProgramFilesDir%, oppure %TEMP%).

FUNZIONI E COSTANTI

In luogo del nome di campo possono essere utilizzate le seguenti espressioni: