Using Genie Modules

Open Genie modules written in C or Fortran can be used to extend the functionality of the interface and may be loaded by selecting "Load Genie Module" from the "File" menu. For a detailed description of how to create Open Genie modules consult the Open Genie Reference manual. Input and transformation functions are two distinct types of functions which may be provided by modules and integrated into the interface.

Input module functions are used for reading data into new sets from files with data formats not natively supported by Genie, once loaded they will appear in the "Read" submenu of "File". When an input module is selected it will request a file in the normal manner and go on to create a new set.

Transformation module functions are used to create new sets from existing sets by transforming them in some way, once loaded, they can be used by selecting 'Module Transformations' from the Operations menu.

The gmodule_query function

Any module loaded into the interface must contain a special function called gmodule_query which is used to tell the interface how to handle the module. It should create a workspace containing the following five string arrays:

symbol - a list of functions provided by the module.
descrip - a description of what each function does (used by the interface to identify the functions to the user).
language - the language the module is written in (C or FORTRAN).
type - whether the functions are to "INPUT" or "TRANSFORM" a set.
extent - the default file extension for an input function (not used for transform functions).

The following is a gmodule_query function from a C module providing only one function to double the y array of a set:

void gmodule_query(GenieWorkspace* pars_get, GenieWorkspace* pars_put)
{
	const char* symbol[1] = {"double_them"};
	const char* descrip[1] = {"Double the y array"};
	const char* language[1] = {"C"};
	const char* type[1] = {"TRANSFORM"};
	const char* extent[1] = {"*"};
	if (!cmodule_version_ok(CMODULE_MAJOR_VERSION,CMODULE_MINOR_VERSION))
	{
		cmodule_print("Library version mismatch for
		double_them", CMODULE_PRINT_ERROR);
		return;
	}
	cmodule_put_string_array(pars_put,"symbol",symbol,1);
	cmodule_put_string_array(pars_put,"descrip",descrip,1);
	cmodule_put_string_array(pars_put,"language",language,1);
	cmodule_put_string_array(pars_put,"type",type,1);
	cmodule_put_string_array(pars_put,"extent",extent,1);
}

Additional functions

Additional functions have been added to the C module interface to allow interaction with the user through Tk dialogue boxes. Integers, floating point numbers, and strings can all be requested from the user using these functions and then used inside the module. The new functions are all prefixed with cmodule_inquire and include:

cmodule_inquire_begin - Begin constructing a new dialogue box.
cmodule_inquire_int - Add an integer field to an existing dialogue box.
cmodule_inqire_real - Add a real field to an existing dialogue box.
cmodule_inquire_double - Add a double field to an existing dialogue box.
cmodule_inquire_string - Add a string field to an existing dialogue box.
cmodue_inquire_end - stop adding fields to a dialogue box, display it, and get results.

The function prototypes are shown below:

void* cmodule_inquire_begin(const char* title);

void cmodule_inquire_int(void* dialog, const char* label, fort_int* val);

void cmodule_inquire_real(void* dialog, const char* label, fort_real* val);

void cmodule_inquire_double(void* dialog, const char* label, fort_double* val);

void cmodule_inquire_string(void* dialog, const char* label, char* val, fort_int len);

void cmodule_inquire_end(void* dialog);

To create a dialogue box simply follow these three steps:

  1. Call cmodule_inquire_begin with the title of the box, which will return a pointer to a new dialogue box.
  2. Pass this pointer to the other inquire functions to add fields to the box. Each field needs a text label and a pointer to a variable of the appropriate type, where the result will be stored.
  3. Call cmodule_inquire_end to display the box and get back the results.

A simple piece of C code to get two integer values from the user and add them together could be written as:

void *dialog;
fort_int a,b;
dialog = cmodule_inquire_begin("Add two numbers!");
cmodule_inquire_int(dialog, "value 1:", &a);
cmodule_inquire_int(dialog, "value 2:", &b);
cmodule_inquire_end(dialog);
a = a + b;