Esportazione

Top Previous Next

Invocazione del servizio di esportazione

L’esportazione dei dati in Check&In viene invocata mediante una chiamata http get alla pagina che contiene i dati della stampa, con gli stessi parametri utilizzati per la produzione della stampa più altri che indicano i parametri per l’esportazione. Il destinatario dell’esportazione è un file, salvato sul server o inviato al client, oppure una database.

I parametri forniti alla pagina sono i seguenti:

▪	template_out: è un parametro obbligatorio, indica il path del file contenente i parametri dell’esportazione;

▪	datafile: è un parametro opzionale significativo solo se l’esportazione non è su database; il path del file che contiene i dati esportati, deve essere un percorso valido sul server di Check&In, se non indicato allora i dati esportati sono inviati al client;

▪	username e password: credenziali di un utente dell’applicazione Check&In; questi parametri sono necessari se la chiamata è fatta da altre applicazioni e quindi non si utilizza la modalità di autenticazione standard basata su form di login. La password è criptata mediante l’utility pwdcrypt

Le modalità di chiamata del servizio sono quindi:

▪	l’applicazione compone una richiesta http get

▪	indica come parametro template_out il path del file di definizione dei parametri, posto in una cartella accessibile dal server di Check&In

▪	indica come parametri username e password

▪	se l’esportazione è su file, viene prodotto un file, in formato testo o xml, che è salvato sul server oppure inviato al client

Il file di definizione dei parametri

Il formato dei dati da caricare è specificato nel file contenente i parametri dell’importazione. Questo file è in formato xml ed ha il seguente formato

<export

<!-— parametri generali -->

format=formato di esportazione

root=elemento radice nella forma xml della pagina

<!—- parametri per tutti i formati di tipo file -->

mode=modalità di esportazione

encoding=stringa che identifica l'encoding del file di dati (ASCII, UTF8, ...)

<!-— parametri per il formato xml o xml con attributi -->

alias_root=tag usato per l’elemento radice nel formato xml

alias_record=tag usato per gli elementi record nel formato xml

<!—- parametri per l’esportazione su database -->

dbtype=per l’esportazione su database, tipo di database

DSN=la stringa di connnessione al database

query=testo della query eseguita per inserire ogni singolo record

<fieldlist> tag che indica l’elenco dei campi

<nome campo=nome dell’elemento xml da esportare

len=lunghezza del campo

/> parametri per un campo in caso di esportazione in un file di testo

<nome campo

alias=nome del tag nel file dati

/> parametri per un campo in caso di esportazione in un file xml

<nome campo

default=valore di default di un campo non esistente o nullo

format=formato per campi di tipo data-ora

/>altri parametri

</fieldlist>

</export>

Valori ammessi per i parametri

format: può valere fixed, xml, xmlattr, database; indica il formato dei dati a colonne a larghezza fissa, il formato xml, il formato (xmlattr) in cui per ogni record da esportare i campi sono inseriti come attributi del record anziché come elementi xml separati. Il formato xmlattr produce file più compatti rispetto ad xml. Il formato database si usa per inviare i dati ad un database, tramite l’istruzione sql specificata nel parametro query.

mode: può valere replace oppure append; si applica quando è indicato datafile, indica il comportamento nel caso in cui il file di destinazione esista già: se il modo è replace, il file viene sovrascritto, se invece mode è append, i dati vengono aggiunti al file. Se non indicato, il valore utilizzato è replace.

encoding: stringa con la descrizione della codifica usata per la scrittura del file (non significativo se il formato è database).

root: è un riferimento alla porzione di documento xml da usare per l’esportazione; partendo dalla forma xml della pagina, che si visualizza con il parametro aggiuntivo “format=xml”, root è l’elemento radice i cui figli corrispondono ai record che verranno esportati.

alias_root: è il nome da usare come nodo radice nel file xml prodotto, se non è indicato si mantiene il nome nei dati di Check&In (che è quello indicato nel parametro root).

alias_record: è il nome da usare come elemento che contiene un record di dati, nel file xml prodotto, se non è indicato si usa quello di Check&In; nel documento xml questi elementi sono i figli dell’elemento radice.

dbtype: si usa per il formato database, è una stringa che indica il tipo di database e può essere una fra "MSDE", "SQLSERVER", "ORACLE".

DSN: è la stringa di connessione, la sua struttura dipende dal tipo di database.

query: è la query di inserimento da usare.

La parte fieldlist è l’elenco dei campi oggetto dell’esportazione, ogni elemento figlio di fieldlist corrisponde ad un campo nei dati di Check&In; gli attributi hanno il seguente significato:

len: per il formato a posizioni fisse, indica la la lunghezza del campo;

alias: in caso di esportazione in file xml, indica il nome con cui il campo viene trascritto nel file di destinazione; se non è presente si mantiene il tag originale di Check&In (per vedere questi tag, richiamare la pagina con format=xml);

format: per valori di tipo data, questo attributo indica il formato per la conversione in stringa; sono valide tutte le stringhe che contengono le sequenze GG, MM, AA, AAAA, HH, NN, SS, dove AAAA è l’anno a 4 cifre, MM è il mese a 2 cifre o i minuti, NN sono i minuti; ad esempio: GGMMAAAA (giorno mese anno), GGMMAAAAHHNNSS (giorno, mese, anno, ore, minuti, secondi), GGMMAAHHMMSS (giorno, mese, anno, ore, minuti, secondi);

default: si usa per dare un valore di default ad un campo non presente nei dati esportati, oppure presente ma con valore nullo.

Esportazione in xml

Produce un file xml ben formato, sono possibili le due varianti xml ed xmlattr. Ecco un esempio di file di template:

</fieldlist>

</export>

Nell’ipotesti di partire da una stampa dei transiti, l’esportazione che usa il template sopra produce un file di questa forma:

<?xml version="1.0" encoding="utf-16" standalone="yes"?>

<lista>

<insediamento>VIA CURTATONE</insediamento>

<terminale>curtat.1</terminale>

<area>Curtatone</area>

</record>

<insediamento>VIA CURTATONE</insediamento>

<terminale>curtat.1</terminale>

<area>Curtatone</area>

</record>

...

</lista>

Con il formato xmlattr il file è più compatto:

<?xml version="1.0" encoding="utf-16" standalone="yes"?>

<lista>

...

</lista>

Esportazione a formato fisso

Se il formato è fixed, ogni record si scrive su una riga del file, i campi sono scritti nell’ordine con cui compaiono in fieldlist, ed occupano le lunghezze indicate dal parametro len. All’occorrenza, un campo viene allungato con spazi fino a raggiungere la lunghezza richiesta, l’allineamento prodotto è a sinistra, tranne per i campi di tipo numerico che sono allineati a destra. Esempio di file template:

</fieldlist>

</export>

Esportazione verso database

Nel caso il formato scelto sia database, per ogni record di dati viene eseguita la query indicata nel parametro query. L’operazione viene fatta dentro una unica transazione, per cui l’eventuale fallimento di un inserimento produce un annullamento completo (rollback).

La forma tipica della query è un istruzione sql di tipo INSERT, parametrica sui valori dei campi; i nomi dei parametri devono corrispondere con i nomi dei campi elencati nella sezione fieldlist, se per un campo è definito un alias, la corrispondenza è con l’alias anziché con il nome campo. I nomi dei parametri devono contenere dei prefissi per indicare il tipo, se questo non è stringa. L’eventuale default è il valore usato se il campo non ne possiede uno.

In questo esempio, i record raggruppati sottto l’elemento “lista” vengono inseriti nella tabella “tblexport” di un database SqlServer: la sezione fieldlist indica di mappare il campo “dataora” nel campo “datatimb”, il campo “codicebadge” in “codice” ed il campo “descrterminale” in “terminale” rispettivamente. Se manca la descrizione del terminale, si inserisce “******”.

<!— Si suppone di disporre della tabella tblexport:

create table tblexport (

CODICE varchar(10) null,

DATATIMB datetime null,

TERMINALE varchar(20) null

) go

-->

<export format="database"

dbType="SQLSERVER"

DSN="Persist Security Info=True;User ID=sa;Password=;Initial Catalog=DBStart;Data Source=localhost"

query="insert into tblexport (codice, datatimb, terminale) VALUES (@codice, @_dtdatatimb, @terminale)"

root="lista">

</fieldlist>

</export>

Specifica di date parametriche dentro la Url

E’ ragionevole costruire una url che richiama l’esportazione, in cui le date non sono fisse, ma sono relative alla data corrente. Questo è possibile con delle espressioni data da inserire nella url al posto di una data dell’intervallo o di tutte e due. Oltre all’espressione “NOW”, che indica la data ed ora attuale, sono accettate espressioni formate da una carattere che indica l’inizio o la fine di un periodo temporale, ed una parte che indica il periodo.

Nelle espressioni, inizio e fine si rappresentano con “I”, “F”, il periodo è un altro carattere che indica l’unità di misura (sono ammessi: anno=A, mese=M, settimana=S, giorno=G, ora=H, minuto=N), seguito eventualmente da un numero che segnala la ripetizione del periodo in avanti o all’indietro. In genere il numero è negativo e quindi si indica con il “-” davanti.

Risultano espressioni del tipo IA-2, che significa l’inizio di 2 anni fa, oppure FM, cioè la fine del mese corrente. La sintassi segue quindi il seguente schema:

esprData ::= NOW | periodo[numero]

periodo ::= {I | F}{A | M | S | G | H | N}

numero ::= numero, anche preceduto da "-"

Lo schema indica che numero è opzionale e che non sono ammessi spazi bianchi. Ad esempio, sono espressioni valide le seguenti:

Espressione	Significato	Valore (rispetto a: 4 nov. 2008 09:20)
IA	Inizio dell’anno in corso	01/01/2008 00:00:00
IA1	Inizio del prossimo anno	01/01/2009 00:00:00
FM-1	Fine del mese scorso	31/10/2008 23:59:59
FS	Fine della settimana corrente	09/11/2008 23:59:59 (domenica)
IS-1	Inizio della settimana scorsa	29/10/2008 00:00:00 (lunedì)
IH	Inizio dell’ora corrente	04/11/2008 09:00:00

Calcolo delle espressioni data

Le espressioni che non contengono la parte numero si calcolano prendendo l’inizio o la fine del periodo in cui cade la data odierna; l’inizio periodo è la data con l’ora alle 00:00, la fine periodo è la data con l’ora alle 23:59:59. Per il periodo S, settimana, la regola è che la settimana comincia il lunedì e finisce la domenica, quindi IS è l’ora 00:00 di lunedì scorso e FS è le 23:59:59 di domenica prossima.

Per calcolare le espressioni che contengono un numero dopo il codice del periodo, la regola è che prima si applica lo spostamento del numero di periodi indicati, e poi si calcola l’inizio o la fine del periodo. In questo modo per valutare l’espressione FM-3 (fine del mese -3 mesi) si va indietro di 3 mesi rispetto alla data odierna, e poi si calcola la fine del mese.