GWBplugin – Getting started with C++

Syntax

int initialize(
  const char* app_name,
  const char* file_name = NULL,
  const char* cmds = NULL
);

Parameters

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]

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]

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.

Examples

#include "GWBplugin.h"

GWBplugin myPlugin;

// plug-in SpecE8 with no output written and no options
int success = myPlugin.initialize("spece8");

// plug-in React with output written to output.txt and no options
int success = myPlugin.initialize("react","output.txt");

// plug-in X1t with no output written, no working directory change,
//  and read input from pb_contam.x1t
int success = myPlugin.initialize("x1t",NULL,
     "-nocd -i \"c:/program files/gwb/script/pb_contam.x1t\"");

Syntax

int exec_cmd(
  char* uline
);

Parameters

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

myPlugin.exec_cmd("3 mmol H+");
myPlugin.exec_cmd("2 mmol Ca++");
myPlugin.exec_cmd("5 mmolar Cl-");
myPlugin.exec_cmd("go");

Syntax

int results(
  void* data,
  const char* value,
  const char* units = NULL,
  int ix = 0,
  int jy = 0
);

Parameters

data

Address of data block to fill. Can be NULL.

value

String containing the report command keyword and arguments.

units [optional]

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]

X node position.

jy [optional]

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).
• 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 = myPlugin.results(NULL,"species");
char** Species = new char*[ndata];
myPlugin.results(Species,"species");

// get aqueous species concentrations in mg/kg
double* Conc = new double[ndata];
myPlugin.results(Conc,"concentration aqueous","mg/kg");

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

For this tutorial you will need to have Microsoft's Visual Studio (or Intel's C++ compiler) installed in addition to GWB 9.0.2 (or later). If you do not already have Visual Studio you can use the free Community edition found on the Visual Studio download page.

The first thing you need to do is to open the Visual Studio Command Prompt – Or Intel's ...

Then create a working folder ...

mkdir "%homepath%\GWBplugin"

Change to that folder ...

cd "%homepath%\GWBplugin"

Copy the "src" folder from GWB installation – default install path shown ...

copy /Y "C:\Program Files\GWB\src"

Copy the GWBplugin.lib file from GWB installation – default install path shown ...

copy /Y "C:\Program Files\GWB\gwbplugin.lib"

Add the GWB installation folder to your path ...

set path=C:\Program Files\GWB;%path%

Compile the example file and tell the compiler to use the GWBplugin libary – For Intel use icl instead of cl...

cl GWBplugin_Cpp_Example1.cpp gwbplugin.lib

You are now ready to run the example ...

GWBplugin_Cpp_Example1.exe

Which should produce output similar to the following ...

Beginning run.
Finished run.

concentration of Cl- in molal is       0.05
concentration of Cl- in mg/kg is       1770

There are 4 aqueous species.

Cl-  =       1770 mg/kg
H+   = 1.139e-005 mg/kg
HCl  = 1.234e-011 mg/kg
OH-  =    0.02039 mg/kg

Congratulations on plugging into the GWB!

For this tutorial you will need to have MinGW with the g++ compiler and MSYS installed in addition to GWB 9.0.2 (or later).

The first thing you need to do is to launch the MinGW Shell ...

Then create a working folder ...

mkdir -p ~/GWBplugin

Change to that folder ...

cd ~/GWBplugin

Copy the "src" folder from GWB installation – default install path shown ...

cp /c/program\ files/gwb/src/* .

Copy the GWBplugin.lib file from GWB installation – default install path shown ...

cp /c/program\ files/gwb/gwbplugin.lib .

Add the GWB installation folder to your path ...

PATH=/c/program\ files/gwb:$PATH

Compile the example file and tell the compiler to use the GWBplugin libary ...

g++ GWBplugin_Cpp_Example1.cpp GWBplugin.lib -o GWBplugin_Cpp_Example1.exe

You are now ready to run the example ...

./GWBplugin_Cpp_Example1.exe

Which should produce output similar to the following ...

Beginning run.
Finished run.

concentration of Cl- in molal is       0.05
concentration of Cl- in mg/kg is       1770

There are 4 aqueous species.

Cl-  =       1770 mg/kg
H+   = 1.139e-005 mg/kg
HCl  = 1.234e-011 mg/kg
OH-  =    0.02039 mg/kg

Congratulations on plugging into the GWB!

For this tutorial you will need to have Microsoft's Visual Studio 2017 installed in addition to GWB11 (or later). If you do not already have Visual Studio you can use the free Community edition found on the Visual Studio download page.

The first thing you need to do is to open Visual Studio ...

Then create a new project ... Ctrl+Shift+N

Select the 'Visual C++' project type and use the 'Empty Project' Template. Give the project a name e.g. 'GWBplugin_example1'. Click 'OK' ...

Select the project in the 'Solution Explorer' (Ctrl+Alt+L opens it if it isn't already). Right click the project and select 'Add' then 'Existing Item...' (Shift+Alt+A)

Browse to the 'src' subfolder of your GWB installation and select the 'GWBpugin_Cpp_example1.cpp' file and click 'Add'

Right click the project and open its 'Properties' ... Alt+Enter

Select 'All Configurations' in the Configuration dropdown menu...

Select the platform matching the version of GWB you have installed in the Platform dropdown menu: 'x64' for 64-bit GWB or 'Win32' for 32-bit GWB

Select the 'VC++ Directories' page under the 'Configuration Properties' section

Edit the 'Include Directories' value.

Add the 'src' folder of the GWB installation and click 'OK'

Edit the 'Library Directories' value.

Add the GWB installation folder and click 'OK'

Under 'Configuration Properties' – 'Linker' – 'Input' edit the 'Additional Dependencies' value

Add gwbplugin.lib and click 'OK'

Under 'Configuration Properties' – 'Linker' – 'System' select 'Console (/SUBSYSTEM:CONSOLE)' as the 'SubSystem' value

Under 'Configuration Properties' – 'Debugging' add the GWB install folder to the path in the 'Environment' variable. You can now click 'OK' to save the settings and close the project properties ...

Before building the solution select the correct platform in the configuration dropdown

You are now ready to 'Build Solution' under the 'Build' menu ... Ctrl-Shift-B

Make sure the project builds correctly and there are no errors ...

You can now 'Start Without Debugging' ... Ctrl-F5
Note: If you need to debug your program you must attach a debugger after the 'initialize' call to GWBplugin otherwise your program will encounter a run-time error. A good way to do this is to put in a getchar() call or something that will pause the program until you can attach the debugger.

Assuming everything is setup correctly and built without errors your program should launch and give output like this ...

Congratulations on plugging into the GWB!