GWBplugin – Creating a wrapper

Syntax

int c_initialize(
	void* plugin,
	const char* app_name,
	const char* file_name,
	const char* cmds
);

Parameters

plugin

A dereferencable pointer that points to a pointer which can be assigned a value. Keeps track of a particular plugged in GWB application.

app_name

A string containing the GWB application name you wish to use. Valid options are rxn, spece8, react, x1t, and x2t.

file_name [optional] (default: NULL or empty string)

A string containing the name of the file you want the GWB application to write its output to. Can be NULL or an empty string if you do not want the output to be written to a file.

cmds [optional] (default: NULL or empty string)

A string containing command-line options you could normally pass to the application when running it from the command-line. Can be NULL or an empty string.

Command-line options:

-cd

Change the working directory to the directory containing the input script specified with the -i option.

-nocd

Do not change the working directory.

-i <input_script>

Read initial input commands from the specified file.

-gtd <gtdata_dir>

Set directory to search for thermodynamic datasets.

-cond <cond_data>

Set the dataset for calculating electrical conductivity.

-d <thermo_data>

Set the thermodynamic dataset.

-s <surf_data>

Set a dataset of surface sorption reactions.

-iso <isotope_data>

Set a dataset of isotope fractionation factors.

Return value

Non-zero on success and zero on failure.

Remarks

• For this function to succeed you must have your GWB installation folder added to the PATH environment variable so all the required DLLs can be found.
• initialize must be done before trying to use any of the other functions.
• The plugin parameter is a "pointer to a pointer".

Examples

void* myPlugin = NULL;
...
// plug-in SpecE8 with no output written and no options
int success = c_initialize(&myPlugin,"spece8");
...
// plug-in React with output written to output.txt and no options
int success = c_initialize(&myPlugin,"react","output.txt");
...
// plug-in X1t with no output written, no working directory change,
//  and read input from pb_contam.x1t
int success = c_initialize(&myPlugin,"x1t",NULL,
     "-nocd -i \"c:/program files/gwb/script/pb_contam.x1t\"");

Syntax

int c_exec_cmd(
  void* plugin,
  char* uline
);

Parameters

plugin

A dereferencable pointer that has already been used with c_initialize. Keeps track of a particular plugged in GWB application.

uline

A string containing the command you wish to send to the GWB application.

Return value

Non-zero on success and zero on failure.

Remarks

None.

Examples

c_exec_cmd(&myPlugin,"3 mmol H+");
c_exec_cmd(&myPlugin,"2 mmol Ca++");
c_exec_cmd(&myPlugin,"5 mmolar Cl-");
c_exec_cmd(&myPlugin,"go");

Syntax

int c_results(
  void* plugin,
  void* data,
  const char* value,
  const char* units,
  int ix,
  int jy
);

Parameters

plugin

A dereferencable pointer that has already been used with c_initialize. Keeps track of a particular plugged in GWB application.

data

Address of data block to fill. Can be NULL.

value

String containing the report command keyword and arguments.

units [optional] (default: NULL or an empty string)

String containing the units you would like the results returned in. Can be NULL or an empty string if you want default units.

ix [optional] (default: 0)

X node position.

jy [optional] (default: 0)

Y node position.

Return value

The number of values written (or to be written) to the data block.

Remarks

• To determine the size of data block you will need first call this function with data parameter as NULL and with the rest of the parameters filled. If you know the report command you are using only returns a single value you can simply pass a pointer to the correct data type. Please see the "Appendix: Report Command" section in the GWB Reference Manual for details on data types and available keywords. The Reference Manual can be found in the documentation section of the website.
• If the command fails for any reason, for example if the requested data doesn't exist or the specified unit conversion failed, the data will be filled with ANULL (-999999.0).
• You will generally want to "#define ANULL -999999.0" (or language equivalent) somewhere in your wrapper.
• ix is only used when running X1t and X2t. Otherwise it is ignored.
• jy is only used when running X2t. Otherwise it is ignored.
• For languages that are dynamically typed (e.g. Python) you will either need to create multiple wrapper results functions (one for each possible data type: int, double, and char*) or pass the expected type as an extra parameter. It is also often best to omit the data parameter in the wrapper function. You then call c_results with a NULL value for data to get the size, allocate C compatible memory, call c_results with the data parameter, convert data, and then finally just return an array of the results. See GWBplugin.py for examples of this.

Examples

// get aqueous species names
int ndata = c_results(&myPlugin,NULL,"species");
char** Species = (char**) malloc(sizeof(char*) * ndata);
c_results(&myPlugin,Species,"species");

// get aqueous species concentrations in mg/kg
double* Conc = (double*) malloc(sizeof(double) * ndata);
c_results(&myPlugin,Conc,"concentration aqueous","mg/kg");

// get pH at node 3,5
double pH = ANULL;
c_results(&myPlugin,&pH,"pH",NULL,3,5);

Syntax

int c_results_c(
  void* plugin,
  void* data,
  const char* value,
  const char* units,
  int ix,
  int jy,
  int* slen
);

Parameters

plugin

A dereferencable pointer that has already been used with c_initialize. Keeps track of a particular plugged in GWB application.

data

Address of data block to fill. Can be NULL.

value

String containing the report command keyword and arguments.

units

String containing the units you would like the results returned in. Can be NULL or an empty string if you want default units.

ix

X node position.

jy

Y node position.

slen

Address of data block to fill with retrieved string lengths.

Return value

The number of values written (or to be written) to the data block.

Remarks

• To determine the size of data block you will need first call this function with data parameter as NULL and with the rest of the parameters filled. If you know the report command you are using only returns a single value you can simply pass a pointer to the correct data type. Please see the "Appendix: Report Command" section in the GWB Reference Manual for details on data types and available keywords. The Reference Manual can be found in the documentation section of the website.
• If the command fails for any reason, for example if the requested data doesn't exist or the specified unit conversion failed, the data will be filled with ANULL (-999999.0).
• ix is only used when running X1t and X2t. Otherwise it is ignored.
• jy is only used when running X2t. Otherwise it is ignored.

Examples

// get aqueous species names
int ndata = c_results(&myPlugin,NULL,"species");
char** Species = (char**) malloc(sizeof(char*) * ndata);
int* Lengths = (int*) malloc(sizeof(int) * ndata);
c_results_c(&myPlugin,Species,"species",NULL,0,0,Lengths);

Syntax

 void c_destroy(
  void* plugin
);

Parameters

plugin

A dereferencable pointer that has already been used with c_initialize. Keeps track of a particular plugged in GWB application.

Return value

None.

Remarks

None.

Examples

c_destroy(&myPlugin);