The GWB plug-in feature is implemented as a Dynamic-Link Library (DLL). For Perl we provide a GWBplugin wrapper class contained in the Perl module file GWBplugin.pm which handles dealing with the C data type conversion and calling the DLL. This page answers common queries about how to use the Perl version of the plug-in feature. Since Perl is a dynamically typed language there are some minor differences with its results function compared to statically typed languages.
To use the GWBplugin class from the GWBplugin module you must first add the "src" folder in the GWB installation to Perl's module search path and then tell it to use the GWBplugin module.
use lib '/program files/gwb/src';
use GWBplugin;
Getting the Win32::API module.
The GWBPlugin module depends on the Perl Win32::API module. If you don't already have the Wind32::API module installed you can install it with the Perl Package Manager with the following command.
ppm install Win32-API
GWBplugin Perl wrapper class overview.
This is a synopsis of the Perl wrapper class provided in GWBplugin.pm in the "src" directory of the GWB installation folder.
# GWBplugin.pm
package GWBplugin;
our $ANULL = -999999
sub initialize # (app_name, file_name = 0, cmds = 0)
sub exec_cmd # (uline)
sub results # (value, units = 0, ix = 0, jy = 0)
sub destroy #
Initializing the GWB application you wish to use.
Within your code you must first create a "GWBplugin" object. Next, use the "initialize" function to start the GWB application of interest by passing the application name, a optional file name for the GWB application to write output to, and any command-line type arguments.
Syntax
sub initialize # (app_name, file_name = 0, cmds = 0)
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 the number zero 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 the number zero or an empty string for defaults.
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
use lib '/program files/gwb/src';
use GWBplugin;
...
my $myPlugin = new GWBplugin();
...
# plug-in SpecE8 with no output written and no options
my $success = $myPlugin->initialize("spece8");
...
# plug-in React with output written to output.txt and no options
my $success = $myPlugin->initialize("react","output.txt");
...
# plug-in X1t with no output written, no working directory change,
# and read input from pb_contam.x1t
my $success = $myPlugin->initialize("x1t","",
"-nocd -i \"c:/program files/gwb/script/pb_contam.x1t\"");
Configure and execute your calculations.
The "exec_cmd" function can be used to transmit commands to the plug-in. Each application has a chapter in the reference manual of the documentation on what commands are available. You use these commands to configure the application and then send a "go" command to trigger the calculations.
Syntax
sub exec_cmd # (uline)
Parameters
uline
A string containing the command you wish to send to the GWB application.
Retrieving the results using the GWB plug-in feature can be accomplished using the "results" function. The keywords, default units, and return types are the same as those listed in the Report Command chapter of the reference manual in the documentation. To use the results commands you provide the desired report command and keywords, optional desired units, and the node location of choice (X1t and X2t only).
Syntax
# results function
sub results # (value, units = 0, ix = 0, jy = 0)
Parameters
value
String containing the report command keyword and arguments.
units [optional]
String containing the units you would like the results returned in. Can be the number 0 or an empty string if you want default units.
ix [optional]
X node position.
jy [optional]
Y node position.
Return value
Array containing the requested results.
Remarks
Even when requesting a single value it is still returned as an array.
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
my @Species = $myPlugin->results("species");
# get aqueous species concentrations in mg/kg
my @Conc = $myPlugin->results("concentration aqueous","mg/kg");
# get pH at node 3,5
my ($pH) = $myPlugin->results("pH","",3,5);
Cleaning up.
The "destroy" function can be used to free up the underlying memory associated with the GWBplugin object.
Syntax
sub destroy # ()
Parameters
None.
Return value
None.
Remarks
None.
Examples
myPlugin->destroy();
Quickstart tutorials and examples
Step-by-step instructions for running GWBplugin Example 1 on the command line with Perl.
For this tutorial you will need to have ActivePerl for Windows installed. ActivePerl can be obtained from the ActiveState website. This example should work with other versions of Perl, but instructions on how to obtain the Win32::API module may be different.
The first thing you need to do is to open the command prompt ...
cmd.exe
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"
Add the GWB installation folder to your path ...
set path=C:\Program Files\GWB;%path%
If you haven't already installed the Win32::API module, do so now...
ppm install Win32-API
You are now ready to run the example with Perl ...
perl GWBplugin_Perl_Example1.pl
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!
Perl plug-in support
Why does it say the specified module could not be found when I try to run my program?
In order to locate the GWB DLLs the GWBplugin class uses you must add the GWB installation directory to the PATH environment variable. You might also get this error message if trying to use the 64-bit version of Perl with the 32-bit version of GWB or vice versa.
Where are the GWBplugin files that I need to use located?
The GWBplugin Perl wrapper class file (GWBplugin.pm) is installed to the "src" folder in the GWB directory.
For answers to additional questions please check the plug-in section of the reference manual in the documentation, our main support FAQ, or contact us.
