Come si realizza una tabella UDX

Come si crea una tabella UDX (User Defined eXtension Table)

Per realizzare una "tabella UDX" , che a volte è anche indicata come UDFT (User Defined Function Table), si deve creare un semplice file di testo. Questo file serve a registrare le funzioni e i comandi definiti dall'utente che GrADS può richiamare.

Ecco i passaggi e la struttura per la sua creazione:

Posizione del file

La posizione di questo file di testo non è fissa, ma deve essere specificata a GrADS tramite la variabile d'ambiente GAUDXT. Ad esempio, il file potrebbe trovarsi in una directory come $GABIN/gex/udxt o /usr/local/grads/udft.

In Windows, il percorso è spesso questo:

\OpenGrADS-2.2\Contents\Cygwin\Versions\2.2.1.oga.1\i686\gex\

La documentazione invece solitamente è in questa cartella:

\OpenGrADS-2.2\Contents\Resources\Documentation\opengrads\doc\udxt

Contenuto del file: Cinque record per funzione (o una riga strutturata)

Il file UDXT contiene informazioni su ciascuna funzione definita dall'utente. Tradizionalmente, la documentazione descrive cinque record per ogni funzione. Tuttavia, per le estensioni dinamiche di OpenGrADS (come quelle che usano gsudf.gex), queste informazioni sono spesso consolidate in una singola riga strutturata che riflette questi concetti.

La riga strutturata per ogni funzione o comando dovrebbe seguire questo formato (come visto negli esempi delle estensioni di OpenGrADS):

Tipo (Type): Indica se si tratta di una funzione definita dall'utente (udf) o di un comando definito dall'utente (udc).
API (API o I): Rappresenta il livello dell'API (Application Programming Interface). Spesso è 0 per le implementazioni attuali.
Nome (Name): Questo è il nome della funzione o del comando come verrà richiamato nel prompt di GrADS (es. speed, hello).
Funzione (Function): È il nome della funzione di ingresso (entry point) all'interno della libreria condivisa che GrADS chiamerà.
Libreria (Library): Specifica il percorso della libreria condivisa (spesso un file .gex o .so) che contiene l'implementazione della funzione o del comando. Il carattere ^ (accento circonflesso) indica che il percorso è relativo alla directory specificata dalla variabile d'ambiente GAUDXT.
Descrizione (Description, opzionale): Una breve stringa descrittiva che può essere visualizzata quando si interroga la tabella UDXT (ad esempio, con q udx).

# Sample GrADS table for Dynamic User Defined Commands/Functions.

# There are 2 types of extensions:

# udc user defined commands

# udf user defined functions

# This feature requires OpenGrADS v2.0.a4.oga.3 or later.

#.................................................................

# A

# P GrADS Library Library Short

# Type I Function Function Path Description

# ---- - ---------- ---------- -------------- -------------------------------

udf 0 " " " " " " "Streamfunction & Velocity Potential"

udf 0 fish f_fish ^fish.gex "Poisson solver"

udf 0 fish_psi f_psichi ^fish.gex "Compute streamfunction"

udf 0 fish_chi f_psichi ^fish.gex "Compute velocity potential"

udf 0 fish_vor f_psichi ^fish.gex "Compute vorticity"

udf 0 fish_div f_psichi ^fish.gex "Compute divergence"

#..........................................................................

Esempio pratico (da gsudf.gex)

L'estensione gsudf permette di scrivere funzioni di espressione GrADS utilizzando il linguaggio di scripting di GrADS stesso.

Se si desidera definire una funzione GrADS scritta come script (un .gsf), come la funzione speed che calcola la velocità del vento, l'entrata nel file UDXT sarà la seguente:

udf 0 speed f_gsudf gsudf.gex.so

Oppure, con un percorso relativo e una descrizione:

udf 0 speed f_gsudf ^gsudf.gex "The mag() function as gsUDF"

In questo esempio:

udf: Indica che si tratta di una funzione definita dall'utente.
0: Il livello dell'API.
speed: Il nome con cui si richiamerà la funzione in GrADS (es. display speed(ua,va)).
f_gsudf: Il punto di ingresso nella libreria gsudf.gex. Questa libreria agisce da "proxy", eseguendo lo script GrADS (speed.gsf) e interpretandone l'output.
gsudf.gex.so (o ^gsudf.gex): La libreria dinamica che gestisce l'esecuzione dello script. Questa libreria deve essere installata e accessibile al sistema operativo (tramite LD_LIBRARY_PATH su Linux/Unix).
"The mag() function as gsUDF": Una descrizione testuale.

Considerazioni aggiuntive:

Precedenza: Le funzioni definite dall'utente hanno la precedenza sulle funzioni intrinseche di GrADS, il che consente di sovrascrivere o estendere le funzionalità esistenti.
File correlati: Oltre alla tabella UDXT, la funzione o il comando stesso (es. lo script .gsf per le gsUDFs o la libreria .so/.gex compilata) deve esistere nella directory appropriata e seguire le specifiche del suo tipo.
Verifica: Dopo aver impostato il file UDXT e le variabili d'ambiente, è possibile verificare le estensioni caricate in GrADS con i comandi query udx e query udxt.
File UDXT: nella directory GEX esiste già un file senza estensione denominato UDXT che openGrADS legge all'inizio. Questo file contiene tutte le funzioni e i comandi che OpenGrADS dovrà considerare. Ogni nuovo comando o funzione deve essere correttamente riportato in questo file. Creare un qualsiasi altro file non produrrà l'effetto sperato semplicemente perché OpenGrADS lo ignorerà. Il contenuto del file UDXT, ottenuto tramite q udx, è consutabile in forma di tabella qui.