Le Stored Procedures, così come i Trigger, non fanno parte della natura del server eXtraWay ma ne rappresentano una forma dinamica d'estensione.

Da molto tempo a questa parte esiste la possibilità di realizzare una “DLL d'archivio”, vale a dire una libreria dinamica che viene chiamata dal server, se presente e configurata, per svolgere azioni specializzate in alcuni punti ben definiti¹⁾ per i quali sono stati realizzati degli entry point detti morsetti.

Col passare del tempo è risultato evidente che una simile realizzazione scarica su 3D Informatica tutto l'onere dello sviluppo e della manutenzione anche per azioni tutto sommato molto semplici, da svolgersi sia per completare/perfezionare i record che vengono salvati sia per decorare quelli che vengono mostrati.

Per questa ragione, sempre con la logica della libreria dinamica da evocare al momento giusto nel modo giusto, è stata realizzata una coppia di librerie dinamiche, liblua.[dll|so] e libluafunc.[dll|so], che assolve a questi compiti.

Le due librerie devono essere collocate come segue:

Per introdurre Stored Procedures e Triggers tra le funzionalità del Server eXtraWay abbiamo ritenuto di doverci avvalere di un linguaggio di scripting potente e di ampia diffusione.
Per tale ragione la scelta è caduta su Lua.
Si assume quindi che il lettore che voglia intraprendere la stesura di proprie Stored Procedures o Triggers acquisisca una ragionevole padronanza del linguaggio avvalendosi del suo Tutorial o del Reference.

Perché siano disponibili presso un archivio, le Stored Procedure ovvero i Trigger devono essere opportunamente registrati presso l'archivio stesso.

Nel file di configurazione dell'archivio devono essere previste le due tipologie documentali che descrivono ciò che verrà associato a queste azioni.
Si veda il seguente esempio

  <primary_node ud_name="xwStoredProcedure" ud_container="xwStoredProcedureList">
     <unique_rule search_rule="[XML,/xwStoredProcedure/@package]"/>
     <key name="XML,/xwStoredProcedure/" key_style="skip" path_style="container"/>
     <key name="XML,/xwStoredProcedure/@package" key_style="single"/>
     <key name="XML,/xwStoredProcedure/func/@id" key_style="single"/>
     <file_location mode="rule" rule="stored$/@XML,/xwStoredProcedure/@package@$;stored" move_always="yes"/>
  </primary_node>
  <primary_node ud_name="xwTrigger" ud_container="xwTriggerList">
     <unique_rule search_rule="[XML,/xwTrigger/@package]"/>
     <key name="XML,/xwTrigger/" key_style="skip" path_style="container"/>
     <key name="XML,/xwTrigger/@package" key_style="single"/>
     <file_location mode="rule" rule="trigger$/@XML,/xwTrigger/@package@$;trigger" move_always="yes"/>
  </primary_node>

Come si può notare, entrambe le tipologie prevedono di essere identificate tramite un @package e, nel solo caso delle Stored Procedures, ciascuna funzione appartenente ad un Package avrà un nome ben preciso.

Iniziamo col descrivere le Stored Procedures in quanto i Trigger sono sostanzialmente identici ma con dei vincoli intrinsechi.

Vediamo un esempio di record di configurazinoe di una Stored Procedure

<xwStoredProcedure package="unifolder.decorator" xmlns:xw="http://www.3di.it/ns/xw-200203121136">  
  <func id="loadRecordByNRecord"> 
    <parms> 
      <in> 
        <parm name="nRecord"/> 
      </in>  
      <out> 
        <parm name="result"/> 
      </out> 
    </parms> 
  </func>  
  <func id="loadRecordByID"> 
    <parms> 
      <in> 
        <parm name="nDoc"/> 
      </in>  
      <out> 
        <parm name="result"/> 
      </out> 
    </parms> 
  </func>  
  <xw:file name="./lua/decorator.lua"/>
</xwStoredProcedure>

Quello che ci dice questo record XML di configurazione è che esiste un Package, denominato unifolder.decorator sono presenti due Stored Procedures, rispettivamente loadRecordByNRecord e loadRecordByID.
Ciascuna Stored Procedure prevede uno o più parametri in ingresso ed in uscita²⁾.
Ciascuno parametro ha un name cui viene associato un valore verboso e può avere un valore sottinteso (default). In tal caso sarà presente un attributo default atto ad indicare tale valore.
In assenza del valore di default il parametro viene inizializzato con un valore nullo. Questo vale solo per i parametri in ingresso in quanto per quelli in uscita non è previsto un valore predefinito.

<xwStoredProcedure    package="unifolder.util">  
  <func id="closeFolder"> 
    <parms> 
      <in> 
        <parm name="nRecord"/>  
        <parm default="0" name="force"/> <!-- Valore di default del parametro 'force' -->
      </in>  
      <out> 
        <parm name="result"/> 
      </out> 
    </parms> 
  </func>  
  <xw:file name="./lua/decorator.lua"/>
 </xwStoredProcedure>

Al record XML di configurazione è associato uno ed un solo allegato di tipo LUA che deve contenere tutte le Stored Procedures indicate³⁾.

Secondo quanto detto, quindi, ogni Stored Procedure è identificabile per mezzo del suo fully qualified name. Nel nostro esempio avremo unifolder.decorator.loadRecordByNRecord e unifolder.decorator.loadRecordByID.

Vediamo un esempio di record di configurazinoe di una Trigger

<xwTrigger package="doc.beforeSave" xmlns:xw="http://www.3di.it/ns/xw-200203121136">  
  <func id="docCheck"/>  
  <xw:file name="./lua/doctrigger.lua"/>
</xwTrigger>

Le analogie con le Stored Procedures sono numerose ma con l'introduzione di una serie di vincoli.
Mentre per le Stored Procedures il nome del package è del tutto libero, il nome package di un Trigger è la combinazione della denominazione del Primary Node Element cui il Trigger si riferisce e l'evento cui il Trigger risponde.
Oltre a questo, i parametri in ingresso ed uscita sono fissati dalla natura del Trigger stesso e quindi non vanno elencati in questo record.
In assenza di un Trigger per un determinato evento occorso su un determinato tipo record, nessuna funzionalità verrà eseguita e la cosa in se non costituisce errore.
Vengono invece elencati i nomi di tutte le funzioni che devono essere chiamate e che verranno eseguite nello stesso ordine in cui gli elementi func sono presenti nell'XML, questo nell'ipotesi che si possano dover compiere diverse operazioni⁴⁾.
In presenza di molteplici chiamate in sequenza, i valori di output della funzione precedente possono essere usati per valorizzare i parametri in input della funzione successiva.

Anche in questo caso, al record XML di configurazione è associato uno ed un solo allegato di tipo LUA che deve contenere tutte le funzioni citate dal Trigger indicate. Per esso valgono le stesse considerazioni fatte per le Stored Procedures.

Secondo quanto detto quindi questo Trigger risponde all'evento beforeSave sul tipo record doc evocando la funzione docCheck.

Eventi Triggers

Al momento in cui questa documentazione viene redatta esistono i seguenti eventi:

Evento	Descrizione
beforeSave	Intervento sul record che si sta provvedendo ad inserire/modificare prima che il salvataggio abbia luogo e prima che l'archivio venga bloccato
onLoad	Intervento sul record che si sta provvedendo a caricare. Si noti che quest'attività viene compiuta sempre, in quanto Trigger. Questo può avere impatti considerevoli dal punto di vista prestazionale e può comportare il rischio di infinite loop. Per questa ragione si raccomanda di far uso di questo Trigger con estrema cautela e prediligere l'uso di una Stored Procedure qualora si intenda dare a questa funzionalità una finalità squisitamente decorativa.

Vediamo rapidamente un esempio di come dev'essere realizzato il codice LUA prendendo spunto dal Trigger docCheck.
Le funzioni utilizzate sono meglio descritte nella successiva Reference.

function docCheck(toBeSaved, numDoc)

	local newRecord = xw.prepareRecord(toBeSaved, nil) ;
	local codFasc = newRecord:getFirstNodeValue("//doc/rif_interni/rif/@cod_fasc", nil) ;
	local docType = newRecord:getFirstNodeValue("//doc/extra/content/@docType", nil) ;

	if ( 0 ~= #codFasc ) then -- only if a valid cod_fasc is present.

		local isComplete = isDocumentComplete(newRecord) ;

		-- Fascicolo will be changed anyway since i must set/reset record state each time it changes.
		
		local nodeNRecord = newRecord:selectFirstNode("//doc/@nrecord", nil) ;
		if ( nodeNRecord:isValid() ) then
			local nRecordValue = nodeNRecord:getValue() ;
			-- Got the NRecord of this "doc". Look for the corresponding "fascicolo" and change it.
			local fascicolo = xw.loadFirstRecordByQuery("([/fascicolo/@numero/]=\""..codFasc.."\")", "", "") ;
			fascicolo:lock() ;
			local docRefNode = fascicolo:selectFirstNode("//fascicolo/extra/content/documents/document/ref[@nrecord='"..nRecordValue.."']", nil) ;
			
			-- Define "complete" attribute value
			local completeStr = xw.choose((0 ~= isComplete), "1", "0") ;
			log.msg("This record completeness: "..completeStr) ;
			
			-- When saving the 'fascicolo' record I will check for completeness.
			if ( docRefNode:isValid() ) then
				-- Got it!
				docRefNode:setAttribute("complete", completeStr) ;
				fascicolo:save() ;
			else
				-- add the document reference lost.
				docRefNode = fascicolo:selectFirstNode("//fascicolo/extra/content/documents/document[@id='"..docType.."']", nil) ;
				if ( docRefNode:isValid() ) then
					log.error("Document ref "..nRecordValue.." still not present in 'fascicolo' "..codFasc) ;
					local refNode = docRefNode:appendChild("ref", "") ;
					refNode:setAttribute("nrecord", nRecordValue) ;
					refNode:setAttribute("complete", completeStr) ;
					fascicolo:save() ;
				else
					log.error("No document of type '"..docType.."' are expected in 'fascicolo' "..codFasc.."!") ;
					fascicolo:unlock() ; -- No condition to change 'fascicolo' record.
				end
			end
		end
	end
	
	return "" ; -- The doc record will be unchanged.
end

La funzione determina in primo luogo due valori del presente record di tipo doc, valori necessari per conoscere a quale fascicolo esso appartenga e quale sia la sua natura.
Solo qualora il documento sia associato ad un fascicolo si procede a richiamare una funzione, isDocumentComplete(newRecord) che compie delle verifiche sul documento stesso.
Quale che sia l'esito della suddetta verifica, si procede a ricercare il fascicolo avente corrispondente codFasc assumendo di identificarne uno ed uno soltato. In esso si determina la presenza di un riferimento al documento corrente (identificato tramite il suo nrecord.
A questo punto ci sono due casi: il fascicolo cita correttamente questo documento, ed in tal caso si provvede ad aggiungere al nodo del riferimento un attributo complete col giusto valore ('0' o '1'), oppure il fascicolo non cita ancora questo documento⁵⁾.
In questo secondo caso, si identifica la porzione del fascicolo ove sono raccolti i riferimenti alle topologie di documento corrispondenti al tipo del documento corrente e si correda tale nodo di un nuovo elemento ref che costituisca il legame con il presente documento tramite il suo nrecord apponendo analogamente al caso precedente anche la condizione di completezza nell'attributo complete.

Se quanto detto va regolarmente a buon fine, il fascicolo così modificato viene salvato. Si noti che il salvataggio del record di tipo fascicolo può a sua volta causare l'esecuzione di un Trigger per un proprio evento. Chi realizzerà i Trigger deve tenere conto del rischio di causare una eventuale condizione di loop o un effetto a catena.

La stesura di una Stored Procedure ovvero di un Trigger in Lua può essere effettuata avvalendosi dei seguenti metodi e tipi complessi.

Iniziamo dalla descrizione dei tipi complessi che si sommano ai tipi standard di Lua.

Ciascuno di tali tipi evoluti ha metodi propri, così come esistono metodi generali, riferiti tipicamente a chiamate dirette al server eXtraWay.

Evocare un metodo di un tipo evoluto prevede una sintassi lievemente differente da quella da adottare per evocare un metodo generico. Mentre il metodo generico prevede la sintassi… <namespace>.<nmetodo>(…) …il metodo evoluto richiede la forma… <tipo evoluto>:<metodo>(…) …per compiere una chiamata analoga. Si suggerisce quindi la massima attenzione nell'uso di . e :.

Di seguito il reference di dettaglio dei metodi con una notazione Lua.

Per ciascuno dei seguenti metodi verranno utilizzati i seguenti stili:

user defined type xw.choose(<espressione Lua>, <true value>, <false value>)

xwLuaRecordSet_t xw.executeQuery(<String> query, <String> sortRule, <String> arcName)

String xw.getCurrentArcName()

xwLuaRecord_t xw.loadFirstRecordByQuery(<String> query, <String> sortRule,<String> arcName)

xwLuaRecord_t xw.loadRecordById(<String> Id, <String> arcName)

xwLuaRecord_t xw.prepareRecord(<String> XML_Text, <String> arcName)

xwLuaRecordSet_t xw.refineQuery(<xwLuaRecordSet_> recordSet, <String> query, <String> sortRule, <String> arcName)

void log.error(<Sting> errMsg)

void log.msg(<Sting> infoMsg)

void log.warning(<Sting> warnMsg)

numeric #recordSet

xwLuaRecord_t recordSet:getAbsolute(<numeric> Position)

xwLuaRecord_t recordSet:getCurrent()
xwLuaRecord_t recordSet:getFirst()
xwLuaRecord_t recordSet:getLast()
xwLuaRecord_t recordSet:getNext()
xwLuaRecord_t recordSet:getPrev()

boolean recordSet:isValid()

xwLuaRecordSet_t recordSet:refine(<String> searchExpression, <String> sortRule)

xwLuaRecordSet_t recordSet:sort(<String> sortRule)

numeric record:bindToArc(<String> arcName)

String record:getArc()

String record:getFirstNodeValue(<String> xPath, <xwLuaNode_t>node)

numeric record:getId()

boolean record:isValid()

xwLuaRecord_t record:lock()

numeric record:save()

xwLuaNode_t record:selectFirstNode(<String> xPath, <xwLuaNode_t>node)

xwLuaNodeSet_t record:selectNodes(<String> xPath, <xwLuaNode_t>node)

numeric record:setContentFromRecord(<xwLuaRecord_t> sourceRecord)

numeric record:setContentFromString(<String> sourceString)

numeric record:setNodeValue(<String> xPath, <xwLuaNode_t>node, <String> value)

String record:toString()

void record:unlock()

numeric #nodeSet

numeric nodeSet:erase()

boolean nodeSet:isValid()

xwLuaNode_t nodeSet:getAbsolute(<numeric> Position)

xwLuaNode_t nodeSet:getCurrent()
xwLuaNode_t nodeSet:getFirst()
xwLuaNode_t nodeSet:getLast()
xwLuaNode_t nodeSet:getNext()
xwLuaNode_t nodeSet:getPrev()

numeric node:erase()

boolean node:isValid()

<String> node:getAttribute(<String> attrName)

<xwLuaNodeSet_t node:getAttributes()

<xwLuaNodeSet_t node:getChildren(<numeric> childType)

String node:getValue()

boolean node:hasAttribute(<String> attributeName)

boolean node:hasAttributes()

boolean node:hasChildren(<numeric> childType)

xwLuaNode_t node:insertAfter(<String> nodeName, <String> value)
xwLuaNode_t node:insertBefore(<String> nodeName, <String> value)
xwLuaNode_t node:insertNodeAfter(<xwLuaNode_t> node)
xwLuaNode_t node:insertNodeBefore(<xwLuaNode_t> node)

xwLuaNode_t node:insertFirstChild(<String> nodeName, <String> value)
xwLuaNode_t node:appendChild(<String> nodeName, <String> value)
xwLuaNode_t node:insertFirstNodeChild(<xwLuaNode_t> node)
xwLuaNode_t node:appendNodeChild(<xwLuaNode_t> node)

numeric node:removeAttribute(<String> attrName)

xwLuaNode_t node:replace(<xwLuaNode_t> node)

numeric node:setAttribute(<String> attrName, <String> value)

numeric node:setValue(<String> value)