Il documento di serializzazione fornisce la base dalla quale generare in automatico i componenti software (hpp e cpp) per la serializzazione delle strutture dati
I dati contenuti nel documento di serializzazione sono elencati in queste tabelle. Il documento è formato da una testata in stile 'C' (Testata C e C++) e da un corpo contenente parole chiave identificate da @. Per gli archivi btrieve il nome del file di serializzazione è formato dal prefisso "f" seguito dal codice procedura e dal nome della struttura dati serializzata; il suffisso è ".srl" (es: flsatit.srl è il file di serializzazione del record atit della procedura ls). I file si trovano in tre distinte sottodirectory dei sorgenti della procedura, tipicamente:
- db per i record del database (la stessa directory dove risiedono i sorgenti dei cursori btrieve)
- qr per i record delle query
- tr per i record delle transazioni di aggiornamento
Produzione dell'output
Il nome del file di serializzazione determina i nomi dei file di output hpp e cpp e delle classi in essi contenute. Il nome di output è generato dal nome del file di serializzazione a cui si sostuisce la prima lettera con 's'. Ad esempio: il file di serializzazione flsatit.srl genera slsatit.hpp, slsatit.cpp e le classi di serializzazione slsatit....
Il nome dei file e delle classi di output può essere forzato mediante l'indicazione del parametro @OutSrlName.
Il file di output vengono scritti soltanto se il nuovo contenuto è differente da quello già presente. In questo modo si evitano ricompilazioni inutili.
Output con merge in sorgenti già esistenti
In alcuni casi non si desidera produrre sorgenti separati per i serializzatori, ma si vuole includere il codice prodotto in sorgenti HPP e CPP già esistenti e che contengono altro codice scritto manualmente. In questo caso si utilizzano i parametri @OutHppMergeFile e @OutCppMergeFile per indicare i nomi (eventualmente comprensivo di pathname) dei file in cui scrivere rispettivamente le dichiarazioni e le definizioni. Si può anche utilizzare lo stesso nome di file come destinazione.
Il sorgente di destinazione dovrà contenere un blocco di testo contenuto tra frasi magiche. Tale blocco sarà sostituito dal codice generato.
La parte di dichiarazioni va nel blocco delimitato dalle due righe:
/** $$ ## xxxxxxxxxx.srl Declarations - Begin ##$$ **/
/** $$ ## xxxxxxxxxx.srl Declarations - End ##$$ **/
|
La parte di definizione va nel blocco delimitato dalle due righe
/** $$ ## xxxxxxxxxx.srl Definitions - Begin ##$$ **/
/** $$ ## xxxxxxxxxx.srl Definitions - End ##$$ **/
|
Dove xxxxxxxxxx.srl sta per il nome del file si serializzazione. In questo modo è all'ccorrenza possibile avere sorgenti che ricevono l'output di più serializzatori.
Se sono presenti, il codice prodotto sostituisce le frasi e tutto il codice in esse compreso. Se le frasi non sono presenti nel file di output, il codice prodotto (che comprende le frasi stesse) viene posto in coda al file (sarà cura dello sviluppatore spostare il codice generato --- comprese le frasi magiche --- nel punto giusto del programma). In tal modo, la prima volta che viene eseguita la serializzazione, le frasi magiche vengono aggiunte automaticamente.
L'uso dei parametri per la produzione dei file in merge permette comunque l'indicazione del parametro @OutSrlName che in questo caso ha il solo scopo di forzare il nome delle classi e non ovviamente quello del file di output.
Utilizzo dei serializzatori per le fli
I programmi di produzione delle fli tipicamente serializzano strutture dati multiple; tali strutture dati sono generiche, escono cioè dallo schema record - chiave - parametri. La serializzazione di tali strutture prevede che vengano fornite, per ciascuna struttura: il nome della struttura da serializzare (l'equivalente di @RootName), il nome della variabile che punta ai dati (l'equivalente di @DataName), il nome della classe di serializzazione da produrre (l'equivalente di @OutSrlName).
Solitamente è comodo che l'output di queste serializzazioni sia un sorgente unico, in merge. Si utilizzano pertanto i parametri OutHppMergeFile e @OutCppMergeFile per indicare il file o i file di output. Se viceversa si vuole produrre un sorgente a sè stante, si può indicare il parametro @OutSrlName per forzare il nome del file oppure non indicare nulla ed in tal caso il sorgente prende il nome default (dal file di seiralizzatore, con la prima lettera sostituita con una 's')
Documento di serializzazione - Corpo
Campo |
Descrizione |
Esempio |
@Namespace |
Indica il namespace CPP delle classi e delle funzioni generate. E' lo stesso utilizzato nei cursori btrieve |
FLS |
@ClassExport |
Prefisso per il class Export. Facoltativo. Se assente non c'è class export |
LS_DB_IMPCLA |
@IncludeDir |
Una o più directory in cui cercare gli header da includere, separate da virgole o spazi |
n:\arlib32\lisa\src\h |
@IncludeHdr |
Uno o più header da includere, separati da virgole o spazi. Può contenere il path, se non lo contiene, l'header viene cercato nelle directory indicate da @IncludeDir. Il path può utilizzare delle varaibili di environment, in caso la directory in cui si trovano gli header non sia fissa: la variabile di environment si indica tra parentesi precedute da $ |
tlsaang.h, n:\arlib32\lisa\src\h\tls-stru.h $(RSSVIROOT)\vsp\vp-stru.h in questo caso l'header viene cercato nella directory vsp sotto alla directory puntata dalla variabile di environment RSSVIROOT |
@Omit |
Contiene la lista dei campi dei tracciati che non devono essere serializzati (filler, tipi record delle tabelle, etc). I campi possono essere indicati con il nome semplice o con il nome completo della gerarchia della struttura 'C', a partire dal nome della struttura radice, con in punti separatori. Il campo può essere composto. I campi sono separati da virgole o spazi o possono essere indicati su più righe. |
filler tlsaang.fild |
@RootName |
Struttura radice da serializzare del record principale. E' la struttura principale da serializzare, tipicamente la struttura record dei file btrieve |
struct tlsaang |
@KeyName |
Struttura radice da serializzare per il record chiave. Facoltativo |
union ulsaang |
@XrefName |
Struttura radice da serializzare per il record degli Xef. Facoltativo |
struct xlsaang |
@PrmName |
Struttura radice da serializzare per l record relativi ad altri parametri e dati. Facoltativo |
struct clspgatit_prm |
@DataName |
Nome base per costruire le variabili. A questo nome verranno poi aggiunti (suffissi _key, _xref, _prm), prefissi (m_, p) |
Aang PgAtit |
@OutSrlName |
Il nome base dei sorgenti da produrre e delle classi in essi contenute. Se non indicato il nome è ottenuto dal nome del file di serializzazione sostiuendo al primo carattere la lettera 's' (ad esempio, da flsatit.srl vengono prodotti slsatit.hpp e slsatit.cpp e le classi di serializzazione slsatit...). |
pgatits (vengono prodotti i sorgenti pgatits.hpp e pgatits.cpp e le classi di serializzazione pgatits...) |
@OutHppMergeFile |
Nome del file hpp di output in cui effettuare il merge del codice delle dichiarazioni prodotto con quello già esistente. |
clspgatitsoap.hpp |
@OutCppMergeFile |
Nome del file cpp di output in cui effettuare il merge del codice delle dichiarazioni prodotto con quello già esistente. |
clspgatitsoap.cpp |
@OutCppDir |
Il pathname della directory dove creare i sorgenti CPP per i serializzatori. |
n:\arlib32\lisa\src\db |
@OutHppDir |
Il pathname della directory dove creare i sorgenti HPP per i serializzatori. |
n:\arlib32\lisa\src\h |
@OutCppHdrPref |
Nei sorgenti CPP generati, vengono inclusi gli header dei serializzatori. Gli header possono non essere nella stessa directroy, pertanto si deve poter indicare un predisso da porre davanti agli header inclusi. Questo parametro non è obbligtorio; se non presente i programmi vengono generati con gli header inclusi senza prefisso |
h\ |
@OutHppHdrIncl |
Nei sorgenti HPP generati, vengono inclusi gli header delle classi dei cursori o di altre strutture dati. Nel caso dei cursori il nome dell'header da includere è determinato automaticamente e questo parametro non deve essere indicato. Nel caso di altre classi definite appositamente, va indicato l'header della classe da includere |
clspgatitsoap.hpp |
@UnionValiFun |
Questo tag può contenere il codice sorgente delle routine di validazione delle union. Le ruotine qui definite vengono automaticamente inserite nella dichiarazione della classe a cui pertengono. Il tag deve essere chiuso da @/UnionValiFun. Facoltativo: se il campo è vuoto o assente non vengono generate ruotine di validazione, nè le corrispondenti dichiarazioni. |
Si veda ad esempio n:\arlib32\lisa\src\db\flsoope.srl |
@FliRec |
Questo tag viene utilizzato per serializzare le strutture dati per la produzione delle FLI (usante nelle stampe e nelle estrazioni su file). Contiene una terna di valori separati da virgole: il nome della struttura da serializzare, il nome della variabile che punta ai dati, il nome della classe di serializzazione da produrre |
Si veda ad esempio n:\arlib32\arutl\armo\aracps.srl |
e-mail