Di seguito vengono elencati i dettagli più importanti per fare uso dei comandi del server eXtraWay. Si ricorda che i comandi del server si dividono in due categorie, quelli di “vecchio ordinamento”, di tipo binario, proprietario, e quelli di “nuovo ordinamento” che invece sono stati realizzati come comandi XML¹⁾.

In particolare questo documento si prefigge di dare comprensibilità ai comandi di “nuovo ordinamento”.

Perché si possa comprendere di cosa questo capitolo tratta si tenga in considerazione che il comando XML che il server interpreta deve avere una struttura nota ed alcune componenti obbligatorie. Esso è caratterizzato da un elemento “cmd” che deve contenere per forza di cose un attributo “c” ed un attributo “bits”. Il primo indica il comando, o macro comando, ed il secondo i suoi modificatori. Il comando può contenere a sua volta un'area XML (o meno) contenuta in un elemento “bst”.
Ecco quindi che avremo un comando semplice…

<?xml version="1.0"?> 
<cmd c="..." bits="..."/>

…ed un comando complesso…

   <?xml version="1.0"?>
   <cmd c="..." bits="...">
      <bst>
         ...
      </bst> 
   </cmd>

Se l'attributo c indica il comando è può assumere un solo valore, l'attributo bits può assumere valori diversi ma soprattutto combinazioni di valori. Avremo quindi uno di questi scenari

Ai comandi possono poi essere associati altri attributi che assumono, di volta in volta, significati diversi.
E' convenzione comune che i valori numerici possano essere espressi in diverso modo, sarà il server a stabilire autonomamente se il valore indicato debba considerarsi decimale o esadecimale²⁾ secondo il seguente criterio.

Si ricorda che solo una parte di questi comandi prevede che vengano tornati valori estesi.
Per tutti i comandi in cui non viene espressamente esplicitato si assume che il ritorno sia positivo o negativo ed esso va interpretato come segue

Di seguito tre semplici esempi.

<!-- Esito corretto -->
<rsp ack="1" e="0"/>

<!-- Esito corretto ma con segnalazione di errore latente -->
<rsp ack="1" e="882"/>

<!-- Esito non corretto. Errore di scrittura -->
<rsp ack="0" e="809"/>

L'elenco dei comandi viene posto in ordine numerico progressivo.
Per semplificarne la lettura essi vengono espressi con il loro valore esadecimale.
L'elenco è attualmente provvisorio e verrà completato man mano che sorgerà l'esigenza di commentare un singolo comando.

Questo comando consente di effettuare delle operazioni generiche

Avremo quindi…

Esempio del comando con bits valorizzato 7

<?xml version="1.0" encoding="windows1252"?>
<cmd c="4" bits="7"></cmd>

Esempio risposta del comando con bits valorizzato 7

<?xml version="1.0" encoding="windows-1252" ?>
<rsp ack="1" e="0">
  <dtl dtype="info" dval="3dgestio" /> 
  <dtl dtype="info" dval="acl" /> 
  <dtl dtype="info" dval="acque" /> 
  <dtl dtype="info" dval="albo" /> 
  <dtl dtype="info" dval="armi" /> 
  <dtl dtype="info" dval="articles" /> 
  <dtl dtype="info" dval="ascomunali" /> 
</rsp>

(Documentazione in fase di completamento)

Questo comando, di fatto, racchiude una serie di comandi diversi, molti dei quali hanno scopi del tutto disgiunti.
Il valore di bits associato ad essi è quindi una particolare combinazione di valori progressivi ed a bit.
Nella High Word vengono usati i bits per modificare il singolo comando⁴⁾ mentre nella Low Word si trova il comando numerico.

Di seguito i comandi disponibili (In fase di allestimento)

Tra essi vale la pena ricordare una batteria di comandi solitamente utilizzata per realizzare degli archivi che sono una copia clone, totale o parziale, di altri archivi esistenti. Tale copia può poi essere realizzata secondo i criteri per il suo utilizzo su supporto ottico o meno.
Per semplificare la vita agli utenti che si prefiggono tale obiettivo è stato creato un particolare comando che consente, con una sola operazione, di selezionare i documenti necessari e produrre un archivio completo ed utilizzabile direttamente su supporti ottici etc. etc.
Tale comando unisce il codice di bits 0x00000020 ad una serie di ulteriori flags.

Il comando tipo, per realizzare un archivio per CD rom, sarà quindi il seguente:

<?xml version="1.0" encoding="iso-8859-1"?>
<cmd c="5" bits="0xB2000020" arc="arcclone">
   <bst>([/doc/@anno]=2009)</bst>
</cmd>

Questo esempio crea un archivio clone dell'archivio corrente, che si chiamerà, come nome logico “arcclone” e sarà collocato parallelamente a quello di origine. La richiesta prevede che si clonino in questo secondo archivio solo i documenti del 2009.

Comandi per la gestione dei seriali.
Richiesta dei seriali

<?xml version="1.0" encoding="iso-8859-1"?>
<cmd c="5" bits="0x25"/>

Ottiene come risposta la seguente

<?xml version="1.0" encoding="iso-8859-1"?>
<rsp ack="1" e="0">
<dtl type="xml" value="0"/>
<dtl type="attach" value="183034"/>
</rsp>

Richiesta di impostare un seriale interno

<?xml version="1.0" encoding="iso-8859-1"?>
<cmd c="5" bits="0x26" serial="attach" num="183035"/>

I valori ammessi per l'attributo serial sono “xml” e “attach”.

(Documentazione in fase di completamento)

Questo comando consente di inviare a tutti i server (compreso o escluso il server Master) un comando da svolgere tra quelli di tipo amministrativo.
Il valore di bits indica le modalità con le quali il comando dev'essere svolto mentre il valore di num indica quale comando si intenda svolgere..

Di seguito i bits disponibili (In fase di allestimento)

I bits CMDMGR_INTERSRV_BROADCAST e CMDMGR_INTERSRV_FULLBROADCAST sono mutualmente esclusivi. In loro assenza dev'essere presente un attributi pid che indichi il Process ID del processo cui si vuole inviare il comando.

Di seguito i comandi (attributo num) disponibili (In fase di allestimento)

Esempi:
Richiede che tutti i server, tranne il Master, ricarichino le configurazioni dell'archivio sul quale si esegue il comando

<?xml version="1.0" encoding="iso-8859-1"?>
<cmd c="7" bits="2" num="2">
</cmd>

Richiede che tutti i server, Master compreso, chiudano l'archivio sul quale si esegue il comando

<?xml version="1.0" encoding="iso-8859-1"?>
<cmd c="7" bits="4" num="4">
</cmd>

Questo comando Esportazione consente di effettuare una esportazione di diverse componenti della base dati ma, principalmente, dei documenti della stessa.

Il comando principale (8) prevede un sub-comando, espresso nel campo bits che può prevedere a sua volta dei modificatori.E' quindi il classico caso di un comando che ha un sub-comando + bitmap
Vediamo di seguito come questi possano essere utilizzati.

Avremo quindi…

…ed avremo in 'bits' il codice del sub-comando richiesto. Si ricorda che esso potrà essere poi combinato con altri modificatori assumendo un valore misto.

In assenza di un modificatore di 'bits' che impone che l'esportazione avvenga senza utilizzare un file (0x80000000), tutti i comandi di esportazione prevedono la presenza di un attributo fn che deve definire il nome richiesto per l'esportazione. Tale valore può essere assoluto o relativo. Qualora relativo il suo punto d'origine si considera essere la directory dei temporanei del server.
Qualora tale nome non venga indicato, il server provvederà a generarne uno autonomamente⁹⁾

A questi sub-comandi possono applicarsi diversi ulteriori modificatori che verranno valutati di volta in volta.

Documentazione in fase di realizzazione

Documentazione in fase di realizzazione

Documentazione in fase di realizzazione

L'esportazione delle chiavi di un vocabolario richiede la presenza nel comando di alcuni attributi.
In particolare avremo

Esistono altri parametri, meno frequentemente utilizzati.

Richiediamo l'esportazione in forma compressa .zip del canale nDomanda nel file omonimo.

<?xml version="1.0"?>
<cmd c="x8" bits="x4" id="nDomanda" fn="nDomanda.zip"/>

La risposta evidenzia nel dettaglio il nome esteso del file (collocato nella directory dei temporanei di eXtraWay).

<?xml version="1.0" encoding="iso-8859-1"?>
<rsp ack="1" e="0"><dtl dtype="file" dval="/opt/it-3di/extraway/xw/tmp/hwtemp/nDomanda.zip"/>
</rsp>

Il sub-comando per l'esportazione di unità informative(documenti) può assumere 3 diversi valori (modificatori esclusi

Si può richiedere di esportare tutte le unità informative dell'archivio non indicando nulla di particolare ovvero esportare sottoinsiemi noti.
Per esprimere uno di tali sottoinsiemi si possono dichiarare:

Come detto tali valori sono alternativi ed il valore assegnato all'attributo sel ha la priorità sugli estermi numerici. Non è possibile quindi combinare le due impostazioni, ad esempio, per dichiarare un intervallo di numeri di documenti riferito alla selezione e non all'intero archivio. In tal caso la selezione dev'essere preventivamente ridotta a ciò che si intende esportare e nulla più.

Oltre a questo è anche possibile indicare un ulteriore attributo…

Oltre a questo si può richiedere di applicare un foglio di stile XSLT ai documenti prima di sottiporli ad esportazione. Ciò, ovviamente, impatta esclusivamente su quanto esportato lasciando invariato il contenuto dell'archivo.
Per scegliere questa funzionalità si possono seguire due metodi:

• Impostare un attributo fmode contenente il nome del file XSLT da applicare in fase di esportazione.

ovvero

• Introdurre nel comando XML un elemento bst all'interno del quale riportare integralmente il contenuto del file XSLT del quale si richiede l'applicazione.

La modalità complessa prevede che l'intero file ed ogni unità informativa esportata siano incapsulati in elementi di esportazione corredati da una batteria di attributi che indica una serie di informazioni.
Per l'archivio esse sono: Il nome dell'archivio dal quale si è compiuta l'esportazione, l'eventuale nome del file XSLT che è stato applicato in esportazione, il nome di file di selezione che ha regolato i documenti da esportare ovvero il primo ed ultimo numero di documento esportato.
Per il documento viene esportato un valore etichettato come nrecord che corrisponde, di fatto, al numero fisico del documento.

Nella modalità semplificata, questi elementi e corrispondenti attributi vengono trasformati in più sintetici commenti XML così da non impattare sulla struttura definitiva del file esportato. Questo è ancor più vero se l'esportazione viene effettuata in modalità nidificata, operazione che dovrebbe tentare la ricostruzione di XML complessivo che rappresenta un singolo archivio (o porzione) quando esso ha relazioni gerarchiche tra i documenti.
Quale che sia la modalità di esportazione dei documenti, essi vengono sempre esportati senza la signature, ovvero il check sum calcolato da eXtraWay per ogni documento, valore necessario a comprendere se esso abbia subito modifiche manuali o meno.

L'esportazione di unità informative prevede una serie di modificatori di seguito descritti:

Il comando di esportazione sicuramente più utilizzato, in quanto produce un file XML più simile all'originale, è il comando 0x00000007 ovvero l'esportazione in formato semplificato.
Come detto esso può prevedere che si esprima direttamente il foglio di stile XSLT da applicare nel comando stesso. Se ad esempio abbiamo il seguente XSLT…

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:fo="http://www.w3.org/1999/XSL/Format" xmlns:xw="http://www.3di.it/ns/xw-200303121136" >
<xsl:template match="//scheda_A/csm_def">
   <xsl:call-template name="fai_qualcosa"><xsl:with-param name="parametro" select="'para'" /></xsl:call-template>
</xsl:template>
</xsl:stylesheet>

…esso potrà essere indicato sia come nome del file nell'attributo fmode sia direttamente nell'elemento bst così com'è stato espresso.

Note:
L'esportazione è attualmente un comando che può essere richiesto direttamente dalla Console. Esso produce un'esportazione in formato semplificato, già filtrata per la selezione corrente. In tal caso, però, indipendentemente dal nome del file che si richiederà, la Console epura tale nome da ogni forma di percorso e quindi l'esportazione avverrà sempre nella directory dei temporanei di eXtraWay Server.

Esportazione in modalità semplificata senza allegati con file compresso .zip in modo implicito.

<?xml version="1.0" encoding="iso-8859-1"?>
<cmd c="0x8" bits="0x00000007" fn="myexport.zip"/>

La stessa cosa di cui all'esempio precedente può essere espressa in modo esplicito alzando il bit opportuno. Esportazione in modalità semplificata senza allegati con file compresso .zip in modo esplicito

<?xml version="1.0" encoding="iso-8859-1"?>
<cmd c="0x8" bits="0x08000007" fn="myexport.xml"/>

In ambo i casi i file risultante avrà estensione .zip e conterrà un file omonimo con estensione .xml

Esportazione in modalità semplificata con compressione zip ed indicazione della selezione che funge da filtro dell'esportazione. Richiesta degli allegati in forma normale(distribuzione in percorsi nel file .zip)

<?xml version="1.0" encoding="iso-8859-1"?>
<cmd c="0x8" bits="0x48000007" sel="3sea09ef721ab.tmp" fn="myexport.xml"/>

Esportazione in modalità semplificata con compressione zip ed indicazione dell'intervallo di documenti da esportare. Richiesta degli allegati senza percorso(nel file zip verranno esportati tutti nella radice dello zip stesso).

<?xml version="1.0" encoding="iso-8859-1"?>
<cmd c="0x8" bits="0x44000007" num="100000" num2="200000" fn="myexport.zip"/>

Esportazione in modalità semplificata di documenti selezionati con conversione degli ID d'allegato in percorsi relativi. Non vengono esportati allegati.

<?xml version="1.0" encoding="ISO-8859-1"?>
<cmd c="0x8" bits="0x00400007" sel="3se4104582abe17601.tmp"  fn="DCW_2008.zip"></cmd>

Documentazione in fase di realizzazione

Documentazione in fase di realizzazione

Documentazione in fase di realizzazione

I comandi per la gestione degli allegati si ottengono esprimendo un particolare valore nell'attributo bits, come da tabella seguente.

N.B.: Questo comando esiste solo dalla versione 23.0.2.0 candidate ovvero 23.0.3.0.

Il comando per la migrazione degli allegati da uno Storage ad uno differente dev'essere completato con ulteriori parametri rappresentati da attributi del comando.

Innanzitutto si deve poter esprimere l'intervallo di documenti su cui operare. Esso può essere espresso come intervallo di numeri fisici di documenti ovvero come selezione secondo il seguente schema.

• Si testa la presenza dell'attributo sel. Se esiste ed ha un valore non nullo si assume che esso sia l'id della selezione da utilizzare;
• Se la selezione non è stata espressa correttamente si cerca la presenza degli attributi num e num2 atti ad indicare gli estremi numerici entro cui operare.
  In assenza di un valore valido per num si parte dal primo documento dell'archivio.
  In assenza di un valore valido per num2 si arriva all'ultimo documento dell'archivio.
  Ovviamente, se i due valori non vengono espressi, si opera sull'intero archivio.

In secondo luogo si deve indicare lo Storage di destinazione. Esso può essere indicato secondo il seguente schema.

• Si verifica la presenza di un attributo dir. Se esso esiste ed ha un valore valido si confronta il contenuto con la configurazione dell'archivio. Il valore espresso può essere tanto un percorso assoluto quanto una label (Vds. Esempi). Se non viene riscontrato alcun valore si segnala l'errore e la procedura non prosegue.
• In assenza di un valore valido per dir si verifica la presenza dell'attributo id. Esso deve rappresentare un numero in base '0' da interpretarsi come segue:
  • 0 = Storage di primo livello, in pratica le directory ove sono collocati naturalmente gli allegati in prossimità degli XML che li referenziano;
  • 1 = Storage di secondo livello (il primo storage configurato nel file <nomearchivio>.conf.xml);
  • 2 = Storage di terzo livello (il secondo storage configurato nel file <nomearchivio>.conf.xml);
  • 3 … etc. etc.

E' utile sapere che:

1. Il server può indicare nel proprio log alcune informazioni utili quali:
   1. “Attachment <nome> in doc <numero> doesn't belong to a valid storage”: L'allegato non risulta essere collocato in alcuno degli storages configurati nel server. Questo avviene, ad esempio, quando l'allegato è referenziato con un percorso assoluto o relativo. L'allegato viene ignorato;
   2. “Error <codice> moving attachment <nome> in doc <numero> to <nuovo nome>”: Si tratta di un vero e proprio errore di copia. Potrebbe dipendere dalla mancanza di spazio sullo storage di destinazione o alla presenza di altro file con pari denominazione;
   3. “Attachment <nome> in doc <numero>, moved to <nuovo nome>”: Indica il corretto spostamento dell'allegato;
   4. “Attachment <nome> in doc <numero> already in required storage”: Indica che l'allegato si trova già nello storage richiesto. L'allegato rimane immodificato;
   5. “Attachment <nome> in doc <numero> can't be found”: Non è possibile reperire l'allegato indicato, esso viene ignorato;
2. Vengono inoltre ignorati e mai rimossi dallo storage di livello '0' tutti gli allegati che siano collocati nella vecchia modalità di storage (secondo lo schema <directory nomearchivio>.file\<numero>\<numero>.<estensione>), gli allegati originali che siano oggetto “diretto” di indicizzazione¹⁶⁾ nonchè quelli considerati allegati di servizio. Si dicono allegati di servizio tutti quelli che sono il frutto di una trasformazione compita tramite il File Conversion Service. In questo caso si compie un distinguo.
   1. Gli allegati di tipo testuale prodotti da FCS che siano necessari all'indicizzazione non vengono rimossi dal livello '0' perché la loro presenza piò essere fondamentale;
   2. Gli allagati di altra natura prodotti da FCS che non siano necessari all'indicizzazione possono essere spostati su storages diversi e seguono le sorti degli allegati standard¹⁷⁾.
3. Al termine dell'operazione (Vds. Esempi) viene tornato un breve elenco che indica quanti allegati siano stati spostati, quanti ignorati e quanti lasciati immodificati in quanto già in posizione corretta.

Supponiamo che un archivio sia stato configurato per usare altri storages oltre a quello principale.
Il suo file <nomearchivio>.conf.xml dovrà contenere una configurazione come la seguente:

...
<profile type="attach.idhome" value="d:\xw\db\dcw\xdocwaydoc\storage1\[Level 1],d:\xw\db\dcw\xdocwaydoc\storage2\[La casa di Pippo],d:\xw\db\dcw\xdocwaydoc\xdocwaydoc\storage3\[Level 2]"/>
...

La configurazione consente anche di indicare percorsi relativi alla collocazione dell'archivio.

La richiesta dell'elenco degli storages disponibili si esprime come segue:

<?xml version="1.0" encoding="ISO-8859-1"?>
<cmd c="xb" bits="0x00000010"/>

Risposta

<?xml version="1.0" encoding="iso-8859-1"?>
<rsp ack="1" e="0">
  <storages num="3">
	<storage level="1" dir="d:\xw\db\dcw\xdocwaydoc\storage1\" label="Level 1"/>
	<storage level="2" dir="d:\xw\db\dcw\xdocwaydoc\storage2\" label="La casa di Pippo"/>
	<storage level="3" dir="d:\xw\db\dcw\xdocwaydoc\xdocwaydoc\storage3\" label="Level 2"/>
  </storages>
</rsp>

Si noti che la label deriva da quanto indicato espressamente nel file di configurazione d'archivio mentre l'ordine di valutazione, dato dal level, corrisponde all'ordine in cui l'elenco è stato alimentato.

Richiesta di migrazione degli allegati.
Richiesta con indicazione della selezione e dell'etichetta desiderata

<?xml version="1.0" encoding="ISO-8859-1"?>
<cmd c="xb" bits="0x00000020" sel="3se1203fa78439b01" dir="Level 2"/>

Richiesta con indicazione della selezione e del percorso voluto

<?xml version="1.0" encoding="ISO-8859-1"?>
<cmd c="xb" bits="0x00000020" sel="3se1203fa78439b01" dir="d:\xw\db\dcw\xdocwaydoc\storage2"/>

Questa richiesta è in tutto equivalente alla precedente in quanto l'id del livello indicato conduce allo stesso storage.

<?xml version="1.0" encoding="ISO-8859-1"?>
<cmd c="xb" bits="0x00000020" sel="3se1203fa78439b01" id="2"/>

Richiesta con indicazione della selezione e dello storage richiesto.
Questa richiesta riporta alla collocazione originaria tutti gli allegati dei documenti selezionati che fossero collocati in storages differenti.

<?xml version="1.0" encoding="ISO-8859-1"?>
<cmd c="xb" bits="0x00000020" sel="3se1203fa78439b01" id="0"/>

A tutti i precedenti comandi la risposta avrà il seguente aspetto.

<rsp ack="1" e="0">
  <dtl dtype="moved" dval="81"/>
  <dtl dtype="unchanged" dval="6"/>
  <dtl dtype="skipped" dval="18"/>
</rsp>

Prevede un singolo parametro id che può assumere i valori:

Se il parametro non viene indicato il valore default è 1.

Le versioni antecedenti la 1.0.7-EE, se il valore impostato è pari a '3', eseguono prima il comando '2' e poi il comando '1'.
Purtroppo questo comportamento non è del tutto corretto quindi, per versioni di server antecedenti si suggerisce di inviare separatamente i due comandi, prima con valore '1' e poi con valore '2' mentre quest'accorgimento non è necessario per le versioni 1.0.7-EE e superiori.

Richiesta di riorganizzazione di tutti gli allegati .

<?xml version="1.0" encoding="ISO-8859-1"?>
<cmd c="xb" bits="0x00000080" id="1"/>

La risposta avrà il seguente aspetto.

<rsp ack="1" e="0">
   <dtl dtype="total" dval="103683"/>
   <dtl dtype="moved" dval="103677"/>
   <dtl dtype="skipped" dval="3"/>
   <dtl dtype="rmDirs" dval="1127"/>
   <dtl dtype="faults" dval="3"/>
   <dtl dtype="fault" dval="c:/xwee/db/dcw/xdocwaydoc/xdocwaydoc/2001/3dinbol/fascicoli/00_00/2001-00_00.00110.file/005322.txt"/>
   <dtl dtype="fault" dval="c:/xwee/db/dcw/xdocwaydoc/xdocwaydoc/2001/3dinbol/fascicoli/00_00/2001-00_00.00110.file/005568.txt"/>
   <dtl dtype="fault" dval="c:/xwee/db/dcw/xdocwaydoc/xdocwaydoc/2004/3dinbol/fascicoli/00_00/2004-00_00.00022.file/000000/000089.tif"/>
</rsp>

Questo comando consente la ridistribuzione delle unità informative nei files XML dell'archivio quando vengono cambiate le regole di file_location ovvero quando, pur avendo impostato una regola variabile, non è stato impostato il parametro 'move_always=“true”':

Si può indicare l'insieme dei documenti si cui operare introducendo l'attrubuto sel valorizzato con l'ID della selezione che li racchiude ovvero indicare l'intervallo di documenti fisici introducendo gli attributi num e num2. In assenza di entrambe le dichiarazioni, l'operazione di rilocazione avverrà per tutte le unità informative.

Ci sono inoltre dei modificatori che possono essere impostati nell'attributo bits

Avremo quindi…

<cmd c="0x13" bits="0"/>

…per una rilocazione completa dell'archivio…

<cmd c="0x13" bits="0" sel="3se12934ad4901"/>

…per la rilocazione di un ben preciso set di documenti ottenuto tramite una selezione …

<cmd c="0x13" bits="0" num="1" num2="10000"/>

…per la rilocazione di un set di documenti descritto da un range di numeri fisici di record…

<cmd c="0x13" bits="2"/>

…per una rilocazione completa dell'archivio senza indici cui far seguire un reindex.

Questo comando Estensione XSLT consente di associare ad ogni documento della banca dati (distinguendoli per singole primary nodes) un'elaborazione del contenuto del documento stesso sulla base di un foglio di stile XSLT. Il risultato può quindi essere utilizzato per di versi scopi come:

• Alimentare vocabolari con il contenuto di aree non altrimenti identificabili/componibili
• Sfruttare questi elaborati per la composizione dei titoli/cache dei documenti
• Ordinamento dei documenti sulla base di simili elaborati

Per ottenere questo risultato bisogna innanzitutto accoppiare ad ogni unità informativa un particolare file .xslt

<primary_node ud_name="doc" ud_container="list_of_doc" ud_xslt="change.xslt">
   ...
</primary_node>

Ovviamente il file dev'essere collocato in una posizione su disco corrispondente al percorso assoluto o relativo che viene indicato. Se il percorso è relativo, come avviene normalmente, la directory di riferimento è quella ove si trova l'archivio stesso. Nel nostro esempio, il file change.xslt si troverà nella stessa directory del file <nomearchivio>.conf.xml dal quale viene tratto l'esempio.

Avremo quindi…

In presenza di comando '1' o '4' l'elemento bst deve contenere una serie di elementi item, uno per ogni documento del quale si richiede il ritorno dell'elaborato XSLT. Il documento richiesto sarà riconoscibile per mezzo dell'attributo d. E' ammessa l'assenza dell'elemento bst e del suo contenuto se viene esplicitato l'attributo “sel” mostrato in seguito. In tal caso l'operazione viene compiuta a tappeto su tutti i documenti della selezione indicata.

Inoltre, per identificare l'insieme di documenti su cui operare, possono essere indicate i seguenti attributi

Richiesta di tornare al chiamante l'esito dell'estensione XSLT per i primi 5 documenti di una selezione

<cmd c="x16" bits="1" sel="3se440f508cb838a01">
   <bst>
      <item d="1"/>  <!-- Ovviamente questo non è il primo documento dell'archivio bensì della selezione -->
      <item d="2"/>
      <item d="3"/>
      <item d="4"/>
      <item d="5"/>
   </bst>
</cmd>

L'esito avrà l'aspetto seguente

<rsp ack="1" e="0">
   <bst>
      <item d="1" dln="123">  <!-- Viene tornato anche il numero fisico del documento -->
         <!-- Frammento XML corrispondente all'esito della lavorazione XSLT -->
      </item>
      <item d="2" dln="234">
         ...
      </item>
      <item d="3" dln="235">
         ...
      </item>
      <item d="4" dln="236">
         ...
      </item>
      <item d="5" dln="367">
         ...
      </item>
   </bst>
</rsp>

Richiesta ricostruzione on-line di tutti gli elaborati XSLT dei documenti in archivio senza intervento sugli indici

<cmd c="x16" bits="2"/>

Richiesta ricostruzione bacth dell'elaborato XSLT per i primi 1000 documenti dell'archivio senza ricostruzione indici grazie al flag aggiuntivo.

<cmd c="x16" bits="0x80000003" num2="1000"/>

Richiesta traduzione dei numeri logici di selezione in numeri fisici

<cmd c="x16" bits="4" sel="3se440f508cb838a01"/>

Il risultato avrà un aspetti simile al seguente:

<rsp ack="1" e="0">
  <bst>
    <item d="1" dln="54948"/>
    <item d="2" dln="55169"/>
    <item d="3" dln="57247"/>
    <item d="4" dln="58002"/>
    <item d="5" dln="58478"/>
    <item d="6" dln="63914"/>
    <item d="7" dln="100592"/>
    <item d="8" dln="101196"/>
    <item d="9" dln="104929"/>
    <item d="10" dln="131387"/>
    <item d="11" dln="188857"/>
    <item d="12" dln="198055"/>
    <item d="13" dln="199931"/>
    <item d="14" dln="200636"/>
    <item d="15" dln="206653"/>
  </bst>
</rsp>

Il comando di Search & Replace consente di identificare un valore contenuto in un componente dell'unità informativa XML (che si tratti di attributo o elemento) e sostituirlo con altro valore. Il confronto può essere effettuato sia in forma case sensitive che in forma case insensitive e la sostituzione può interessare tanto l'intero valore del componente quanto una sequenza di caratteri al suo interno eventualmente ripetuta più volte.

Avremo quindi…

Inoltre, per identificare l'insieme di documenti su cui operare, possono essere indicate i seguenti attributi

Il comando prevede uno stato di avanzamento che può essere sfruttato dal chiamante.

Il comando torna un acknowledge positivo o negativo ed implementa uno stato d'avanzamento.

L'esito del comando produce un output xml composto da una serie di elementi dtl²⁰⁾ aventi due attributi, dtype e dval. Di seguito una panoramica dei valori che si possono ottenere in risposta.

Richiesta di sostituzione sull'intero archivio dell'intero valore di un attributo in modo case insensitive

<cmd c="x17" bits="0"
     id="/iter/@d_abbreviata"
     key="regio decr. leg."
     key2="regio D.L."/>

Richiesta di sostituzione su alcuni documenti selezionati in un archivio un valore contenuto anche più volte in un elemento in modo case insensitive

<cmd c="x17" bits="2"
     id="/iter/rtf/contenitore/testo"
     key="M.C.T.C."
     key2="Motorizzazione Civile"
     sel="3se4415f8502b0ea01">
</cmd>

Il comando in esame nasce per occuparsi di attività da svolgere su singoli indici, in particolare la loro rimozione dall'attuale vocabolario (Drop) ovvero la loro generazione, anche ex-novo (Build-Rebuild). Esso è disponibile dalla versione 23.0.0.1 e successive.
In un secondo momento è stato ampliato per occuparsi, di fatto, di tutti gli indici di un archivio in modo cumulativo.
Si ricorda che in questo caso, parlando di Indice ci si riferisce a quello che solitamente è noto anche come Vocabolario ovvero la collezione di tutte le chiavi che si riferiscono ad un singolo canale di ricerca²³⁾ e le relative catene di riferimenti che consentono la selezione dei documenti.
Analogamente, di seguito di indicherà con Drop l'abbattimento di indice esistente, con Rebuild la ricostruzione dell'indice esistente e precedentemente svuotato e con Build la generazione di un indice in precedenza mai esistito, quindi un vocabolario del tutto nuovo.
Per quanto concerne il rifacimento complessivo di tutti gli indici siamo soliti riferirci al concetto di Catalogazione o Indicizzazione Off Line che in questo caso viene definita Fast.

Avremo quindi…

I suddetti valori di bits possono essere combinati col valore 0x80000000 per effettuare l'operazione di indicizzazione/drop/reindicizzazione di uno o più indici ignorando l'eventuale presenza dello stato di “Maintenance in corso”. Questo bit è da utilizzarsi quando una precedente operazione di manutenzione straordinaria è stata troncata maldestramente e lo stato di manutenzione permane. In alternativa, ovviamente, si può far ricorso al comando amministrativo 0x5.

Oltre al comando “c” ed ai parametri indicati con l'attributo “bits” è necessario identificare su quale Vocabolario si intende operare. Per farlo si possono usare due diversi metodi basati sugli attributi “id” e “key”.
Ovviamente nel caso di ricostruzione integrale degli indici questo parametro viene ignorato.

I casi più comuni e meglio “coperti” da questa funzionalità sono quelli in cui si compia il Drop & Rebuild di una singola chiave già esistente senza apportare significativi interventi di modifica al conf che la riguarda, ovvero si provveda alla ricostruzione integrale degli indici dell'archivio. Questo in quanto il calcolo delle posizioni dei termini internamente al documento potrebbe causare condizioni non allineate se si fa, ad esempio, l'indicie di una chiave che precedentemente era skippata o più semplicemente si converte in multi valore una chiave che era precedentemente mono valore²⁵⁾. In tal caso, pur garantendo in linea di principio le adiacenze²⁶⁾ ci sono diversi aspetti tra cui il reverse dei termini che non può essere effettuato correttamente.
Alla luce di questa considerazione, la lavorazione di una singola chiave ha senso quando solo essa risulti danneggiata e debba essere ricostruita minimizzando gli impatti su un archivio in esercizio e/o quando ci si trovi in stato di sviluppo di un'applicazione e si debbano rapidamente cambiare le carte in tavola per quanto concerne una chiave precedentemente non indicizzata o indicizzata con criteri differenti, a patto d'accettare che l'archivio necessiti comunque di un'attività di reindicizzazione integrale.

Si ricorda in fine che attività che comportino un Drop di una o più chiavi di un archivio possono causare una crescita della dimensione degli indici apparentemente non giustificata. Essa può essere sanata con un semplice compattamento degli indici in quanto l'operazione di drop annulla gli indici che vanno buttati senza rimuoverli fisicamente per ridurre il tempo dell'operazione allo stretto necessario. L'operazione di Drop, quando invocata singolarmente e non unitamente ad una richiesta di Rebuild, provvede ad impostare la chiave del quale si richiede il Drop in modo che essa risulti da non indicizzare nel file <nomearchivio>.conf.xml come nell'esempio che segue.

   ...
   <key name="..." key_style="skip"/>
   ...

La dichiarazione della chiave per mezzo dell'attributo “id” comporta che in esso debba essere presente il percorso XML completo della chiave per la quale si richiede di compiere il Drop o il Build-Rebuild. Tale percorso può essere corredato dal prefisso che ne indica il macro-canale eXtraWay²⁷⁾ ma se esso viene omesso si identifica d'ufficio il macro-canale 'XML'.
Questa dichiarazione si presta sia per la funzionalità di Drop che per quella di Build o Rebuild.
Questa dichiarazione, inoltre, è da considerarsi prioritaria nei confronti della successiva. Se questa è presente, l'attributo “key” viene ignorato.

La dichiarazione della chiave per mezzo dell'attributo “key” comporta che in esso debba essere presente il codice di chiave di cui fare Drop o Rebuild. Mancando la definizione del macro-canale esso è, per definizione, 'XML,'.
Il valore della chiave può essere espresso sia in forma decimale che esadecimale (prefissandolo con un '0x' o una 'x') e può essere espresso indipendentemente sia con il suo valore “secco” sia con il suo valore di chiave già mascherato col valore 0x8080²⁸⁾.
In questo modo, per una chiave avente codice '60' i seguenti valori sono tutti leciti ed equivalenti.

Mancando la dichiarazione del percorso di chiave è evidente che questa dichiarazione non sia applicabile al caso del Build ma solo al Rebuild in quanto la chiave non potrebbe essere creata ed anzi deve per forza riferirsi a chiave esistente.

Se pure questo set di comandi sorge nell'intenzione di sanare singoli indici applicativi che risultassero danneggiati e/o costruire indici nuovi o rigenerare indici preesistenti secondo nuovi criteri, esso può essere utilizzato anche per le chiavi di servizio, per meglio intenderci quelle appartenenti al macro-canale UD.
In questo caso, viene ammesso il Drop ed il Rebuild mentre è assolutamente proibito il Build in quanto tali chiavi sono soggette a regole proprie.

Va inoltre ricordato che questo set di comandi assolve al compito di rielaborare i vocabolari, non di compiere interventi sul file di configurazione dell'archivio, attività per la quale esistono comandi appositi.
In altri termini, se si desidera ricostruire un indice in quanto si variano le sue caratteristiche - passando ad esempio da un indice di tipo multi ad un indice di tipo double - si assume che l'intervento sul file di configurazione venga compiuto manualmente o sfruttando uno dei suddetti comandi e che tale intervento preceda il Drop & Rebuild²⁹⁾.

<cmd c="x18" bits="1" id="/doc/nrecord"/>

Indica l'intenzione di Droppare la chiave XML,/doc/nrecord in quanto l'omissione del prefisso XML, rappresenta il default.

<cmd c="x18" bits="2" id="UD,/xw/MyData"/>

Richiede la creazione di un canale UD,/xw/MyData tra le chiavi di servizio. Secondo quando indicato precedentemente, questo comando è destinato a fallire in quanto non si possono creare nuove chiavi nel macro-canale di servizio UD.

<cmd c="x18" bits="3" key="x80Bf"/>

Richiede il Drop & Rebuild della chiave codificatala '0x80bf', vale a dire 'x03f', appartenente al macro-canale 'XML'.

<cmd c="x18" bits="3" id="XMl,/doc/oggetto" key="x80aa"/>

Richiede il Drop & Rebuild della chiave XML,/doc/oggetto con macro-canale XML esplicitato.
La dichiarazione del codice di chiave - 0x80aa, ovvero 0x2A, ovvero 42 - viene del tutto ignorata. Non viene compiuto alcun test sul fatto che la seconda dichiarazione combaci o meno con la prima ne l'operazione viene in qualche modo inibita a causa di una potenziale ambiguità. La dichiarazione per mezzo dell'attributo “key” viene semplicemente ignorata.

<cmd c="x18" bits="4"/>

Richiede il Drop & Rebuild di tutte le chiavi dell'archivio.
Nell'esempio non vengono riportati gli attributi id e key in quanto, anche qualora presenti, il loro contenuto verrebbe del tutto ignorato.

<cmd c="x18" bits="8"/>

Richiede il ricalcolo integrale delle chiavi di univocità dell'archivio.
Nell'esempio non vengono riportati gli attributi id e key in quanto, anche qualora presenti, il loro contenuto verrebbe del tutto ignorato.

La risposta fornita dal server, secondo gli standard indicati in testa a questo documento, può assumere uno di questi aspetti:

In risposta al rifacimento di una chiave viene indicato il suo codice di chiave ed il suo percorso.

<rsp ack="1" e="0">
   <dtl d_type="key" d_val="x8081"/>
   <dtl d_type="fn" d_val="XML"/>
   <dtl d_type="id" d_val="/doc/oggetto"/>
</rsp>

In risposta al rifacimento di tutte le chiavi dell'archivio viene indicato il numero complessivo di documenti elaborati.

<rsp ack="1" e="0">
   <dtl d_type="NDoc" d_val="1924382"/>
</rsp>

Con l'introduzione del concetto di Plug-In ci si è posti nella condizione di poter estendere ad un ampio grado di libertà le funzionalità del server.
Evocare direttamente un comando presente in un Plug-In del server è una sorta d'estensione dei comandi XML appena esposti ma diversamente da essi affida ad una più versatile verbosità le sorti del comando e non ad una codifica stringente.
La conformazione del comando è tuttavia molto simile. Ciascun comando è rappresentato da un elemento cmd che deve contenere un attributo c il cui valore DEVE essere 0.
Questo consente al server di distinguere un comando XML standard dai comandi destinati ai Plug-In.
Mentre sparisce l'attributo 'bits', appare un attributo func il cui scopo è presto detto.
Esso si compone di due parti, separate da un punto (.). La prima parte rappresenta il nome della Classe da evocare. Tra tutti i Plug-In disponibili il server cercherà, seguendo un criterio d'ordine di valutazione, quello che espone tale Classe. A destra del punto, invece, sarà presente il nome del metodo della classe indicata da evocare con una chiamata standard, così come standard sarà la risposta ottenuta. Il tutto viene poi impacchettato nuovamente nel messaggio di risposta ed inviato al richiedente.

Di seguito un esempio di comando per il Plug-In XTree ed il comando treeList

<?xml version="1.0"?>
<cmd c="0" func="XTree.treeList" arc="rubricaIBC"/>

Si noti che tutti i Plug-In che prevedono un input in forma XML ed un output nella stessa forma, consentono la presenza di diversi parametri nel comando.
Ciascun parametro può essere espresso tanto con un'elemento quanto con un attributo, ed eccezione di c e func che devono essere attributi di cmd. In questo modo si possono anche inviare batterie di parametri per mezzo di elementi ripetibili.
In pratica il seguente comando ha una forma differente ma una sostanza equivalente a quella del precedente.

<?xml version="1.0"?>
<cmd c="0" func="XTree.treeList">
   <arc>rubricaIBC</arc>
</cmd>

Si presti attenzione al Case del nome della classe e del metodo da evocare che dev'essere sensitive rispetto a quanto esposto dal Plug-In.

I comandi di vecchio tipo ancora supportati dal server eXtraWay verranno man mano sostituiti da comandi XML ma, sino ad allora e per garantire compatibilità col passato, essi permangono.
Non sarebbe ragionevole ne coerentemente fattibile dare evidenza di tali comandi ma, almeno per alcuni di essi, è utile conoscere il variare dei comportamenti al variare dell'utilizzo del comando stesso.

Di seguito alcuni dettagli per questi comandi.

Usato tanto per creare un archivio quanto per resettare il contenuto del suo catalogo³⁰⁾ e dei suoi indici, ma non dei dati, fa sì che un nuovo archivio eXtraWay venga realizzato presso il File System ovvero che un archivio esistente venga riportato alla sua condizione originaria.

Creare un archivio si può fare ad esempio partendo esclusivamente dal file nomearchivio.conf.xml, nel quale si siano già disegnate le caratteristiche delle unità informative e delle chiavi delle stesse, ovvero in totale assenza di un simile file, operazione che comporta la realizzazione di un file di configurazione d'archivio “vuoto” da utilizzare come template per la compilazione definitiva.

Il comando prevede diversi parametri, tesi a garantire che venga registrato l'alias associato all'archivio, alla salvaguardia dei seriali che risultassero già presenti ed altre attività. In particolare esso ha subito un'aampliamento non indifferente a partire dal server '23'.

Il comando³¹⁾ prevede i seguenti parametri:

Oltre a questi valori, il comando prevede due stringhe. Una rappresenta il nome logico dell'archivio, quello al quale si dovrà accoppiare nel file xw.ini il nome fisico, ed appunto il nome fisico dell'archivio. Essi devono avere una corretta corrispondenza se già presenti nel file xw.ini pena la nullità del comando.

Qualora il comando non possa essere espresso dichiarando i bits indicati sopra, gli stessi possono essere impostati aggiungendo al nome fisico dell'archivio le seguenti etichette.

In particolare, il concetto di archivio “Lucene” verrà chiarito meglio in apposita documentazione.