Di questo gruppo fanno parte le funzioni che consentono di gestire le varie fasi attraversate da un’interrogazione, dal parsing alla visualizzazione dei risultati. Questo gruppo di funzioni può essere diviso in due sottogruppi il primo, funzioni per l’esecuzione di un’interrogazione, permette di gestire l’esecuzione dell’interrogazione, mentre il secondo, funzioni per operare sui risultati di un’interrogazione, permette di gestire i risultati e la loro visualizzazione. Le API numero 7, 8 e 9 sono state pensate per poter memorizzare all’interno del file system i risultati di un’interrogazione in modo da poterli recuperare in un secondo momento. L’API numero 8 permette di ricostruire l’intera tabella dei risultati, mentre l’API numero 9 permette di estrarre solo un sottoinsieme di risultati.
Funzioni per l’esecuzione di un’interrogazione
API NR.2 - XCDE_Parse_Query_String
// IN Query_String: stringa contenente l’interrogazione da eseguire;
Funzioni ad alto livello API 1 – XCDE_Search
Funzioniabasso livello
API 2 – XCDE_Parse_Query_String API 3 – XCDE_Execute_Query
API 4 – XCDE_Compute_Table_Results Funzioni per l’esecuzione
di un’interrogazione
API 5 – XCDE_Get_Number_Results API 6 – XCDE_View_Result API 7 – XCDE_Write_Result_File API 8 – XCDE_Read_Result_File API 9 – XCDE_Read_Range_Result_File Funzioni per operare sui
risultati di un’interrogazione
Figura A.1 – Funzioni API
// OUT Console_Query: indirizzo della struttura ‘console query’;
int XCDE_Parse_Query_String (char *Query_String,
XCDE_Console_Query_Type *Console_Query);
Esegue il parsing dell’interrogazione contenuta nel primo parametro inserendo nella struttura dati Console_Query le informazioni riguardanti l’interrogazione e settando opportunamente i flag relativi allo stato dell’interrogazione [4.1]. Prende come parametri la stringa contenente l’interrogazione da eseguire ed il puntatore alla Console_Query. Il valore di ritorno della funzione è –2 in presenza di errori di sintassi nell’interrogazione, -1 in presenza di altri errori diversi da quelli di sintassi e 1 altrimenti.
API NR.3 - XCDE_Execute_Query
// IN Console_Query: indirizzo della struttura ‘console query’;
int XCDE_Execute_Query (XCDE_Console_Query_Type *Console_Query);
Esegue l’interrogazione le cui informazioni sono contenute nell’unico parametro
Console_Query. Ciò significa che in precedenza bisogna aver richiamato la funzione
XCDE_Parse_Query_String. L’effetto della chiamata di questa funzione è quello di trovare tutti i risultati dell’interrogazione inserendone le informazioni relative nella struttura dati Console_Query [4.1]. Il valore di ritorno della funzione è –2 in presenza di errori di sintassi nell’interrogazione, -1 in presenza di altri errori diversi da quelli di sintassi e 1 altrimenti.
API NR.4 - XCDE_Compute_Table_Results
// IN Index_Tree: indice del documento del quale calcolare la table results;
// OUT Table_Results: indirizzo della variabile che conterrà la tabella dei risultati;
// OUT Size_Table_Results: indirizzo della variabile che conterrà il numero di risultati trovati;
// IN Console_Query: indirizzo della struttura ‘console query’;
int XCDE_Compute_Table_Results (int Index_Tree,
XCDE_IL_Couple_Type ***Table_Results, int *Size_Table_Results,
XCDE_Console_Query_Type *Console_Query);
Riempie la tabella dei risultati sfruttando le informaioni contenute nella Console_Query. Ciò significa che in precedenza bisogna aver richiamato la funzione
XCDE_Execute_Query. Il valore di ritorno della funzione è –2 in presenza di errori di sintassi nell’interrogazione, -1 in presenza di altri errori diversi da quelli di sintassi e 1 altrimenti.
Funzioni per operare sui risultati di un’interrogazione
API NR.5 - XCDE_Get_Number_Results
// IN Tree: indirizzo dell’albero del quale calcolare il numero di risultati associati;
// OUT Number_Results: indirizzo della variabile che conterrà il numero di risultati;
// IN Console_Query: indirizzo della struttura ‘console query’;
int XCDE_Get_Number_Results (query_tree_node *Tree, int *Number_Results,
XCDE_Console_Query_Type *Console_Query);
Calcola il numero dei risultati senza però costruire la tabella dei risultati. In precedenza bisogna aver richiamato la funzione XCDE_Execute_Query. Il valore di ritorno della funzione è -1 in presenza di errori, 1 altrimenti.
API NR.6 - XCDE_View_Result
// IN Index_File: inice del documento del quale visualizzare i risultati;
// IN Table_Results: indirizzo della variabile che contiene la tabella dei risultati;
// IN Size_Table_Results: indirizzo della variabile che contiene il numero di risultati;
// IN Flag_Position: flag per la gestione delle posizioni;
// IN Console_Query: indirizzo della struttura ‘console query’;
int XCDE_View_Results (int Index_File,
XCDE_IL_Couple_Type **Table_Results, int Size_Table_Results,
unsigned char Flag_Position,
XCDE_Console_Query_Type *Console_Query);
Visualizza i risultati contenuti nella Table_Results passata come prametro. Ciò significa che in precedenza bisogna aver richiamato la funzione XCDE_Compute_Table_Results. Il primo parametro è l’indice, all’interno del vettore dei nomi dei file presenti nella struttura dati Console_Query, del file al quale sono associati i risultati da visualizzare.
Il parametro Flag_Position se settato a 0 permette di visualizzare gli snippet associati alle occorrenze trovate, se settato a 1, invece, permette di visualizzare anzicchè lo snippet associato all’occorrenza la sua posizione all’interno del file compresso. Questa opzione è prevista per fini di debugging.
Il valore di ritorno della funzione è –2 in presenza di errori di sintassi nell’interrogazione, -1 in presenza di altri errori diversi da quelli di sintassi e 1 altrimenti.
API NR.7 - XCDE_Write_Result_File
// IN Table_Results: indirizzo della variabile che contiene la tabella
dei risultati;
// IN Size_Table_Results: indirizzo della variabile che contiene il numero di risultati;
// IN filename: indirizzo della variabile che contiene il nome del file nel quale memorizzare la tabella dei risultati. Al nome del file inserito verrà aggiunto il suffiso
“.result”;
// IN Console_Query: indirizzo della struttura ‘console query’;
int XCDE_View_Results (XCDE_IL_Couple_Type **Table_Results, int Size_Table_Results,
char *filename,
XCDE_Console_Query_Type *Console_Query);
Memorizza nel file system il contenuto della Table_Results passata come primo parametro. Ciò significa che in precedenza bisogna aver richiamato la funzione
XCDE_Compute_Table_Results. L’utilità di questa funzione è quella di poter memorizzare i risultati di un’interrogazione per poi utilizzarli, tutti o una parte, in un momento successivo. I primi due parametri sono, rispettivamente, la Table_Results da memorizzare ed il numero di risultati contenuti nella Table_Results. Il parametro
filename è il prefisso del nome del file nel quale memorizzare la Table_Results. A questo nome verrà concatenato il suffisso “.result”. La Table_Results viene memorizzata in maniera compressa.
Il valore di ritorno della funzione è -1 in presenza di errori, 1 altrimenti.
API NR.8 - XCDE_Read_Result_File
// IN filename: indirizzo della variabile che contiene il nome del file dal quale recuperare la tabella dei risultati. Il nome del file inserito non deve contenere il suffiso
“.result”;
// OUT Table_Results: indirizzo della variabile che conterrà la tabella dei risultati;
// OUT Size_Table_Results: indirizzo della variabile che conterrà il numero di risultati;
// IN-OUT Console_Query: indirizzo della struttura ‘console query’;
int XCDE_Read_Result_File (char *filename,
XCDE_IL_Couple_Type ***Table_Results, int *Size_Table_Results,
XCDE_Console_Query_Type *Console_Query);
Recupera dal file system il contenuto del file passato come primo parametro, inserendolo nella Table_Results. Nella Console_Query, inoltre, verranno inserite le informazioni relative al numero di variabili contenute nell’interrogazione. Nessun’altra informazione relativa all’interrogazione, ai suoi risultati o al suo stato viene modificata. Il parametro
filename è il prefisso del nome del file dal quale recuperare la Table_Results. Questo nome non dovrà contenere il suffisso “.result” che sarà inserito automaticamente.
Il valore di ritorno della funzione è -1 in presenza di errori, 1 altrimenti.
API NR.9 - XCDE_Read_Range_Result_File
// IN filename: indirizzo della variabile che contiene il nome del file dal quale recuperare la tabella dei risultati. Il nome del file inserito non deve contenere il suffiso
“.result”;
// IN First_Range: estremo sinistro dell’intervallo dei risultati da recuperere;
// IN Last_Range: estremo destro dell’intervallo dei risultati da recuperere;
// OUT Table_Results: indirizzo della variabile che conterrà la tabella dei risultati;
// OUT Size_Table_Results: indirizzo della variabile che conterrà il numero di risultati;
// IN-OUT Console_Query: indirizzo della struttura ‘console query’;
int XCDE_Read_Range_Result_File (char *filename, int First_Range, int Last_Range,
XCDE_IL_Couple_Type ***Table_Results, int *Size_Table_Results,
XCDE_Console_Query_Type
*Console_Query);
Recupera dal file system un sottoinsieme dei risultati contenuti nel file passato come primo parametro, inserendolo nella Table_Results. L’intervallo di risultati da recuperare è determinato dai due parametri interi First_Range e Last_Range. I due estremi sono considerati come facenti parte dell’intervallo. Nella Console_Query, invece, verranno inserite le informazioni relative al numero di variabili contenute nell’interrogazione.
Nessun’altra informazione relativa all’interrogazione, ai suoi risultati o al suo stato viene modificata. Il parametro filename è il prefisso del nome del file dal quale recuperare la
Table_Results. Questo nome non dovrà contenere il suffisso “.result” che sarà inserito automaticamente.
Il valore di ritorno della funzione è -1 in presenza di errori, 1 altrimenti.