max/iphreeqc
1
0
Fork 0
mirror of https://git.gfz-potsdam.de/naaice/iphreeqc.git synced 2025-12-16 16:44:49 +01:00
Code Issues Packages Projects Releases Wiki Activity

updated docs

Browse Source 
git-svn-id: svn://136.177.114.72/svn_GW/IPhreeqc/trunk@4432 1feff8c3-07ed-0310-ac33-dd36852eb9cd
This commit is contained in:
Scott R Charlton 2010-05-20 05:58:25 +00:00
parent 1873204b98
commit 9b3a5e3b03
6 changed files with 238 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/examples/F90GetComponent.f90
View File

@ -21,7 +21,7 @@ PROGRAM example
DO i=1,GetComponentCount(id) DO i=1,GetComponentCount(id)
CALL GetComponent(id, i, comp) CALL GetComponent(id, i, comp)
WRITE(*,*) "comp ", i, "= ", comp WRITE(*,*) "comp #", i, "= ", comp
ENDDO ENDDO
IF (DestroyIPhreeqc(id).NE.IPQ_OK) THEN IF (DestroyIPhreeqc(id).NE.IPQ_OK) THEN

80
doc/examples/F90GetDumpStringLine.f90 Normal file
View File

@ -0,0 +1,80 @@
PROGRAM example
INCLUDE "IPhreeqc.f90.inc"
INTEGER(KIND=4) :: id
INTEGER(KIND=4) :: i
CHARACTER(LEN=80) :: line
id = CreateIPhreeqc()
IF (id.LT.0) THEN
STOP
ENDIF
IF (SetDumpStringOn(id, .TRUE.).NE.IPQ_OK) THEN
CALL OutputErrorString(id)
STOP
ENDIF
IF (LoadDatabase(id, "phreeqc.dat").NE.0) THEN
CALL OutputErrorString(id)
STOP
ENDIF
IF (AccumulateLine(id, "SOLUTION 1 Pure water").NE.IPQ_OK) THEN
CALL OutputErrorString(id)
STOP
ENDIF
IF (AccumulateLine(id, "EQUILIBRIUM_PHASES 1").NE.IPQ_OK) THEN
CALL OutputErrorString(id)
STOP
ENDIF
IF (AccumulateLine(id, " Calcite 0 10").NE.IPQ_OK) THEN
CALL OutputErrorString(id)
STOP
ENDIF
IF (AccumulateLine(id, "SAVE solution 1").NE.IPQ_OK) THEN
CALL OutputErrorString(id)
STOP
ENDIF
IF (AccumulateLine(id, "SAVE equilibrium_phases 1").NE.IPQ_OK) THEN
CALL OutputErrorString(id)
STOP
ENDIF
IF (AccumulateLine(id, "DUMP").NE.IPQ_OK) THEN
CALL OutputErrorString(id)
STOP
ENDIF
IF (AccumulateLine(id, " -solution 1").NE.IPQ_OK) THEN
CALL OutputErrorString(id)
STOP
ENDIF
IF (AccumulateLine(id, " -equilibrium_phases 1").NE.IPQ_OK) THEN
CALL OutputErrorString(id)
STOP
ENDIF
WRITE(*,*) "Input:"
CALL OutputAccumulatedLines(id)
IF (RunAccumulated(id).NE.0) THEN
CALL OutputErrorString(id)
STOP
ENDIF
WRITE(*,*) "Dump:"
DO i=1,GetDumpStringLineCount(id)
CALL GetDumpStringLine(id, i, line)
WRITE(*,*) TRIM(line)
ENDDO
IF (DestroyIPhreeqc(id).NE.IPQ_OK) THEN
CALL OutputErrorString(id)
STOP
ENDIF
END PROGRAM example

59
doc/examples/IPhreeqc.cpp Normal file
View File

@ -0,0 +1,59 @@
#include <cstdlib>
#include <iostream>
#include <IPhreeqc.hpp>
int main(void)
{
IPhreeqc iphreeqc;
if (iphreeqc.LoadDatabase("phreeqc.dat") != 0) {
std::cout << iphreeqc.GetErrorString() << std::endl;
return EXIT_FAILURE;
}
iphreeqc.AccumulateLine("TITLE Example 2.--Temperature dependence of solubility");
iphreeqc.AccumulateLine(" of gypsum and anhydrite ");
iphreeqc.AccumulateLine("SOLUTION 1 Pure water ");
iphreeqc.AccumulateLine(" pH 7.0 ");
iphreeqc.AccumulateLine(" temp 25.0 ");
iphreeqc.AccumulateLine("EQUILIBRIUM_PHASES 1 ");
iphreeqc.AccumulateLine(" Gypsum 0.0 1.0 ");
iphreeqc.AccumulateLine(" Anhydrite 0.0 1.0 ");
iphreeqc.AccumulateLine("REACTION_TEMPERATURE 1 ");
iphreeqc.AccumulateLine(" 25.0 75.0 in 51 steps ");
iphreeqc.AccumulateLine("SELECTED_OUTPUT ");
iphreeqc.AccumulateLine(" -file ex2.sel ");
iphreeqc.AccumulateLine(" -temperature ");
iphreeqc.AccumulateLine(" -si anhydrite gypsum ");
iphreeqc.AccumulateLine("END ");
if (iphreeqc.RunAccumulated() != 0) {
std::cout << iphreeqc.GetErrorString() << std::endl;
return EXIT_FAILURE;
}
VAR v;
::VarInit(&v);
std::cout << "selected-output:" << std::endl;
for (int i = 0; i < iphreeqc.GetSelectedOutputRowCount(); ++i) {
for (int j = 0; j < iphreeqc.GetSelectedOutputColumnCount(); ++j) {
if (iphreeqc.GetSelectedOutputValue(i, j, &v) == VR_OK) {
switch (v.type) {
case TT_LONG:
std::cout << v.lVal << " ";
break;
case TT_DOUBLE:
std::cout << v.dVal << " ";
break;
case TT_STRING:
std::cout << v.sVal << " ";
break;
}
}
::VarClear(&v);
}
std::cout << std::endl;
}
return EXIT_SUCCESS;
}

15
doc/examples/Makefile
View File

@ -15,7 +15,8 @@ TARGETS = \
AccumulateLine \ AccumulateLine \
CreateIPhreeqc \ CreateIPhreeqc \
GetComponent \ GetComponent \
GetDumpString GetDumpString \
IPhreeqc
F90_TARGETS = \ F90_TARGETS = \
@ -39,6 +40,9 @@ GetComponent: GetComponent.lo $(IPHREEQC_LA)
GetDumpString: GetDumpString.lo $(IPHREEQC_LA) GetDumpString: GetDumpString.lo $(IPHREEQC_LA)
$(LIBTOOL) --mode=link $(CXX) $(LDFLAGS) -o $@ $< $(IPHREEQC_LA) $(LIBTOOL) --mode=link $(CXX) $(LDFLAGS) -o $@ $< $(IPHREEQC_LA)
IPhreeqc: IPhreeqc.lo $(IPHREEQC_LA)
$(LIBTOOL) --mode=link $(CXX) $(LDFLAGS) -o $@ $< $(IPHREEQC_LA)
F90AccumulateLine: F90AccumulateLine.lo $(IPHREEQC_LA) F90AccumulateLine: F90AccumulateLine.lo $(IPHREEQC_LA)
$(LIBTOOL) --mode=link $(CXX) $(LDFLAGS) -o $@ $< $(IPHREEQC_LA) $(FCLIBS) $(LIBTOOL) --mode=link $(CXX) $(LDFLAGS) -o $@ $< $(IPHREEQC_LA) $(FCLIBS)
@ -64,6 +68,9 @@ F90ClearAccumulatedLines: F90ClearAccumulatedLines.lo $(IPHREEQC_LA)
.cxx.lo: .cxx.lo:
$(LIBTOOL) --mode=compile $(CXX) $(CPPFLAGS) $(CFLAGS) -c -o $@ $< $(LIBTOOL) --mode=compile $(CXX) $(CPPFLAGS) $(CFLAGS) -c -o $@ $<
.cpp.lo:
$(LIBTOOL) --mode=compile $(CXX) $(CPPFLAGS) $(CFLAGS) -c -o $@ $<
.f.lo: .f.lo:
$(LIBTOOL) --mode=compile $(F77) $(FFLAGS) -c -o $@ $< $(LIBTOOL) --mode=compile $(F77) $(FFLAGS) -c -o $@ $<
@ -75,7 +82,8 @@ LO_FILES = \
CreateIPhreeqc.lo \ CreateIPhreeqc.lo \
DestroyIPhreeqc.lo \ DestroyIPhreeqc.lo \
GetComponent.lo \ GetComponent.lo \
GetDumpString.lo GetDumpString.lo\
IPhreeqc.lo
F90_LO_FILES = \ F90_LO_FILES = \
@ -83,7 +91,8 @@ F90_LO_FILES = \
F90CreateIPhreeqc.lo \ F90CreateIPhreeqc.lo \
F90DestroyIPhreeqc.lo \ F90DestroyIPhreeqc.lo \
F90GetComponent.lo \ F90GetComponent.lo \
F90GetDumpStringLine.lo F90GetDumpStringLine.lo \
F90ClearAccumulatedLines.lo
clean: clean:

81
include/IPhreeqc.h
View File

@ -29,7 +29,7 @@ extern "C" {
* @param line The line(s) to add for input to phreeqc. * @param line The line(s) to add for input to phreeqc.
* @retval IPQ_OK Success * @retval IPQ_OK Success
* @retval IPQ_OUTOFMEMORY Out of memory * @retval IPQ_OUTOFMEMORY Out of memory
* @see OutputAccumulatedLines, RunAccumulated * @see ClearAccumulatedLines, OutputAccumulatedLines, RunAccumulated
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
* <CODE> * <CODE>
@ -136,7 +136,7 @@ extern "C" {
* Returns an empty string if n is out of range. * Returns an empty string if n is out of range.
* @see GetComponentCount * @see GetComponentCount
* @par Fortran90 Interface: * @par Fortran90 Interface:
* (Note: N is one-based for the fortran interface) * (Note: N is one-based for the Fortran interface)
* @htmlonly * @htmlonly
* <CODE> * <CODE>
* <PRE> * <PRE>
@ -191,7 +191,7 @@ extern "C" {
* Retrieves the current value of the dump file switch. * Retrieves the current value of the dump file switch.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @return Non-zero if output is written to the <B>DUMP</B> (<B><I>dump.out</I></B> if unspecified) file, 0 (zero) otherwise. * @return Non-zero if output is written to the <B>DUMP</B> (<B><I>dump.out</I></B> if unspecified) file, 0 (zero) otherwise.
* @see SetDumpFileOn, GetDumpStringLineCount, GetDumpStringLine, GetDumpString * @see GetDumpString, GetDumpStringLine, GetDumpStringLineCount, GetDumpStringOn, SetDumpFileOn, SetDumpStringOn
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
* <CODE> * <CODE>
@ -212,7 +212,7 @@ extern "C" {
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @return A null terminated string containing <b>DUMP</b> output. * @return A null terminated string containing <b>DUMP</b> output.
* @pre \ref SetDumpStringOn must have been set to true (non-zero) in order to recieve <b>DUMP</b> output. * @pre \ref SetDumpStringOn must have been set to true (non-zero) in order to recieve <b>DUMP</b> output.
* @see SetDumpStringOn * @see GetDumpFileOn, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileOn, GetDumpStringOn, SetDumpStringOn
* @par Fortran90 Interface: * @par Fortran90 Interface:
* Not implemented. (see \ref GetDumpStringLineCount, \ref GetDumpStringLine) * Not implemented. (see \ref GetDumpStringLineCount, \ref GetDumpStringLine)
* *
@ -230,7 +230,7 @@ extern "C" {
* @return A null terminated string containing the given line. * @return A null terminated string containing the given line.
* Returns an empty string if n is out of range. * Returns an empty string if n is out of range.
* @pre \ref SetDumpStringOn must have been set to true (non-zero). * @pre \ref SetDumpStringOn must have been set to true (non-zero).
* @see GetDumpStringLineCount, SetDumpStringOn * @see GetDumpFileOn, GetDumpString, GetDumpStringLineCount, GetDumpStringOn, SetDumpFileOn, SetDumpStringOn
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
* (Note: N is one-based for the Fortran interface.) * (Note: N is one-based for the Fortran interface.)
@ -257,7 +257,7 @@ extern "C" {
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @return The number of lines. * @return The number of lines.
* @pre \ref SetDumpStringOn must have been set to true (non-zero). * @pre \ref SetDumpStringOn must have been set to true (non-zero).
* @see GetDumpStringLine, SetDumpStringOn * @see GetDumpFileOn, GetDumpString, GetDumpStringLine, GetDumpStringOn, SetDumpFileOn, SetDumpStringOn
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
* <CODE> * <CODE>
@ -277,10 +277,10 @@ extern "C" {
/** /**
* Retrieves the current value of the dump string flag. * Retrieves the current value of the dump string switch.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @return Non-zero if output defined by the <B>DUMP</B> keyword is stored, 0 (zero) otherwise. * @return Non-zero if output defined by the <B>DUMP</B> keyword is stored, 0 (zero) otherwise.
* @see SetDumpStringOn, GetDumpString * @see GetDumpFileOn, GetDumpString, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileOn, SetDumpStringOn
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
* <CODE> * <CODE>
@ -320,6 +320,7 @@ extern "C" {
* Retrieves the error messages from the last call to \ref RunAccumulated, \ref RunFile, \ref RunString, \ref LoadDatabase, or \ref LoadDatabaseString. * Retrieves the error messages from the last call to \ref RunAccumulated, \ref RunFile, \ref RunString, \ref LoadDatabase, or \ref LoadDatabaseString.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @return A null terminated string containing error messages. * @return A null terminated string containing error messages.
* @see GetErrorFileOn, GetErrorStringLine, GetErrorStringLineCount, OutputErrorString, SetErrorFileOn
* @par Fortran90 Interface: * @par Fortran90 Interface:
* Not implemented. (see \ref GetErrorStringLineCount, \ref GetErrorStringLine, \ref OutputErrorString) * Not implemented. (see \ref GetErrorStringLineCount, \ref GetErrorStringLine, \ref OutputErrorString)
*/ */
@ -330,8 +331,8 @@ extern "C" {
* Retrieves the given error line. * Retrieves the given error line.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @param n The zero-based index of the line to retrieve. * @param n The zero-based index of the line to retrieve.
* @return A null terminated string containing the given error line message. * @return A null terminated string containing the given line of the error string buffer.
* @see GetErrorStringLineCount, OutputErrorString * @see GetErrorFileOn, GetErrorString, GetErrorStringLineCount, OutputErrorString, SetErrorFileOn
* @par Fortran90 Interface: * @par Fortran90 Interface:
* (Note: N is one-based for the Fortran interface.) * (Note: N is one-based for the Fortran interface.)
* @htmlonly * @htmlonly
@ -353,7 +354,7 @@ extern "C" {
* Retrieves the number of lines in the current error string buffer. * Retrieves the number of lines in the current error string buffer.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @return The number of lines. * @return The number of lines.
* @see GetErrorStringLine, OutputErrorString * @see GetErrorFileOn, GetErrorString, GetErrorStringLine, OutputErrorString, SetErrorFileOn
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
* <CODE> * <CODE>
@ -372,7 +373,9 @@ extern "C" {
/** /**
* Retrieves the current value of the log file switch. * Retrieves the current value of the log file switch.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @return Non-zero if output is written to the <B><I>phreeqc.log</I></B> file, 0 (zero) otherwise. * @return Non-zero if log messages are written to the <B><I>phreeqc.log</I></B> file, 0 (zero) otherwise.
* @remarks
* Logging must be enabled through the use of the KNOBS -logfile option in order to receive any log messages.
* @see SetLogFileOn * @see SetLogFileOn
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
@ -412,7 +415,7 @@ extern "C" {
* Retrieves the number of columns in the selected-output buffer. * Retrieves the number of columns in the selected-output buffer.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @return The number of columns. * @return The number of columns.
* @see GetSelectedOutputRowCount, GetSelectedOutputValue * @see GetSelectedOutputFileOn, GetSelectedOutputRowCount, GetSelectedOutputValue, SetSelectedOutputFileOn
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
* <CODE> * <CODE>
@ -432,7 +435,7 @@ extern "C" {
* Retrieves the selected-output file switch. * Retrieves the selected-output file switch.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @return Non-zero if output is written to the selected-output (<B><I>selected.out</I></B> if unspecified) file, 0 (zero) otherwise. * @return Non-zero if output is written to the selected-output (<B><I>selected.out</I></B> if unspecified) file, 0 (zero) otherwise.
* @see SetSelectedOutputFileOn * @see GetSelectedOutputColumnCount, GetSelectedOutputRowCount, GetSelectedOutputValue, SetSelectedOutputFileOn
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
* <CODE> * <CODE>
@ -452,7 +455,7 @@ extern "C" {
* Retrieves the number of rows in the selected-output buffer. * Retrieves the number of rows in the selected-output buffer.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @return The number of rows. * @return The number of rows.
* @see GetSelectedOutputColumnCount, GetSelectedOutputValue * @see GetSelectedOutputFileOn, GetSelectedOutputColumnCount, GetSelectedOutputValue, SetSelectedOutputFileOn
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
* <CODE> * <CODE>
@ -479,6 +482,7 @@ extern "C" {
* @retval IPQ_INVALIDCOL The given column is out of range. * @retval IPQ_INVALIDCOL The given column is out of range.
* @retval IPQ_OUTOFMEMORY Memory could not be allocated. * @retval IPQ_OUTOFMEMORY Memory could not be allocated.
* @retval IPQ_BADINSTANCE The given id is invalid. * @retval IPQ_BADINSTANCE The given id is invalid.
* @see GetSelectedOutputFileOn, GetSelectedOutputColumnCount, GetSelectedOutputRowCount, SetSelectedOutputFileOn
* @remarks * @remarks
* Row 0 contains the column headings to the selected_ouput. * Row 0 contains the column headings to the selected_ouput.
* @par Examples: * @par Examples:
@ -663,7 +667,7 @@ Headings
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @param n The zero-based index of the line to retrieve. * @param n The zero-based index of the line to retrieve.
* @return A null terminated string containing the given warning line message. * @return A null terminated string containing the given warning line message.
* @see GetWarningStringLineCount, OutputWarningString * @see GetWarningString, GetWarningStringLineCount, OutputWarningString
* @par Fortran90 Interface: * @par Fortran90 Interface:
* (Note: N is one-based for the Fortran interface.) * (Note: N is one-based for the Fortran interface.)
* @htmlonly * @htmlonly
@ -684,7 +688,7 @@ Headings
* Retrieves the number of lines in the current warning string buffer. * Retrieves the number of lines in the current warning string buffer.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @return The number of lines. * @return The number of lines.
* @see GetWarningStringLine, OutputWarningString * @see GetWarningString, GetWarningStringLine, OutputWarningString
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
* <CODE> * <CODE>
@ -780,7 +784,7 @@ Headings
/** /**
* Output the error messages normally stored in the <B><I>phreeqc.err</I></B> file to stdout. * Output the error messages normally stored in the <B><I>phreeqc.err</I></B> file to stdout.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @see GetErrorStringLine, GetErrorStringLineCount * @see GetErrorFileOn, GetErrorStringLine, GetErrorStringLineCount, SetErrorFileOn
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
* <CODE> * <CODE>
@ -804,7 +808,7 @@ Headings
/** /**
* Output the warning messages to stdout. * Output the warning messages to stdout.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @see GetWarningStringLine, GetWarningStringLineCount * @see GetWarningString, GetWarningStringLine, GetWarningStringLineCount
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
* <CODE> * <CODE>
@ -823,9 +827,9 @@ Headings
* Runs the input buffer as defined by calls to \ref AccumulateLine. * Runs the input buffer as defined by calls to \ref AccumulateLine.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @return The number of errors encountered. * @return The number of errors encountered.
* @see AccumulateLine, OutputAccumulatedLines, RunFile, RunString * @see AccumulateLine, ClearAccumulatedLines, OutputAccumulatedLines, RunFile, RunString
* @remarks * @remarks
* The accumulated input is cleared upon a successful run (no errors). * The accumulated input is cleared at the next call to \ref AccumulateLine.
* @pre \ref LoadDatabase/\ref LoadDatabaseString must have been called and returned 0 (zero) errors. * @pre \ref LoadDatabase/\ref LoadDatabaseString must have been called and returned 0 (zero) errors.
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
@ -838,6 +842,9 @@ Headings
* </PRE> * </PRE>
* </CODE> * </CODE>
* @endhtmlonly * @endhtmlonly
*
* @par Fortran90 Example:
* see \ref GetDumpStringLine_f90 "GetDumpStringLine"
*/ */
IPQ_DLL_EXPORT int RunAccumulated(int id); IPQ_DLL_EXPORT int RunAccumulated(int id);
@ -890,6 +897,10 @@ Headings
* </PRE> * </PRE>
* </CODE> * </CODE>
* @endhtmlonly * @endhtmlonly
*
* @par C Example:
* see \ref GetDumpString_c "GetDumpString"
*
*/ */
IPQ_DLL_EXPORT int RunString(int id, const char* input); IPQ_DLL_EXPORT int RunString(int id, const char* input);
@ -898,10 +909,11 @@ Headings
* Sets the dump file switch on or off. This switch controls whether or not phreeqc writes to the dump file. * Sets the dump file switch on or off. This switch controls whether or not phreeqc writes to the dump file.
* The initial setting after calling \ref CreateIPhreeqc is off. * The initial setting after calling \ref CreateIPhreeqc is off.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @param dump_on If non-zero, turns on output to the <B>DUMP</B> (<B><I>dump.out</I></B> if unspecified) file. * @param dump_on If non-zero, turns on output to the <B>DUMP</B> (<B><I>dump.out</I></B> if unspecified) file;
* if zero, turns off output to the <B>DUMP</B> file.
* @retval IPQ_OK Success. * @retval IPQ_OK Success.
* @retval IPQ_BADINSTANCE The given id is invalid. * @retval IPQ_BADINSTANCE The given id is invalid.
* @see GetDumpFileOn, GetDumpString, GetDumpStringLine, GetDumpStringLineCount, SetDumpStringOn * @see GetDumpFileOn, GetDumpString, GetDumpStringLine, GetDumpStringOn, GetDumpStringLineCount, SetDumpStringOn
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
* <CODE> * <CODE>
@ -922,10 +934,11 @@ Headings
* to the dump file are stored in a buffer for retrieval. The initial setting after calling * to the dump file are stored in a buffer for retrieval. The initial setting after calling
* \ref CreateIPhreeqc is off. * \ref CreateIPhreeqc is off.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @param dump_string_on If non-zero, captures the output defined by the <B>DUMP</B> keyword into a string buffer. * @param dump_string_on If non-zero, captures the output defined by the <B>DUMP</B> keyword into a string buffer;
* if zero, output defined by the <B>DUMP</B> keyword is not captured to a string buffer.
* @retval IPQ_OK Success. * @retval IPQ_OK Success.
* @retval IPQ_BADINSTANCE The given id is invalid. * @retval IPQ_BADINSTANCE The given id is invalid.
* @see GetDumpStringOn, GetDumpString, GetDumpStringLine, GetDumpStringLineCount * @see GetDumpFileOn, GetDumpStringOn, GetDumpString, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileOn
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
* <CODE> * <CODE>
@ -952,10 +965,10 @@ Headings
* error messages are written to the <B><I>phreeqc.err</I></B> file. The initial setting after calling * error messages are written to the <B><I>phreeqc.err</I></B> file. The initial setting after calling
* \ref CreateIPhreeqc is off. * \ref CreateIPhreeqc is off.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @param error_on If non-zero, turns on output to the <B><I>phreeqc.err</I></B> file. * @param error_on If non-zero, writes errors to the error file; if zero, no errors are written to the error file.
* @retval IPQ_OK Success. * @retval IPQ_OK Success.
* @retval IPQ_BADINSTANCE The given id is invalid. * @retval IPQ_BADINSTANCE The given id is invalid.
* @see OutputErrorString, GetErrorStringLine, GetErrorStringLineCount * @see GetErrorFileOn, GetErrorStringLine, GetErrorStringLineCount, OutputErrorString
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
* <CODE> * <CODE>
@ -976,9 +989,11 @@ Headings
* writes log messages to the <B><I>phreeqc.log</I></B> file. The initial setting after calling * writes log messages to the <B><I>phreeqc.log</I></B> file. The initial setting after calling
* \ref CreateIPhreeqc is off. * \ref CreateIPhreeqc is off.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @param log_on If non-zero, turns on output to the <B><I>phreeqc.log</I></B> file. * @param log_on If non-zero, log messages are written to the log file; if zero, no log messages are written to the log file.
* @retval IPQ_OK Success. * @retval IPQ_OK Success.
* @retval IPQ_BADINSTANCE The given id is invalid. * @retval IPQ_BADINSTANCE The given id is invalid.
* @remarks
* Logging must be enabled through the use of the KNOBS -logfile option in order to receive any log messages.
* @see GetLogFileOn * @see GetLogFileOn
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
@ -998,10 +1013,10 @@ Headings
/** /**
* Sets the output file switch on or off. This switch controls whether or not phreeqc * Sets the output file switch on or off. This switch controls whether or not phreeqc
* writes to the output file. This is the output normally generated * writes to the <B><I>phreeqc.out</I></B> file. This is the output normally generated
* when phreeqc is run. The initial setting after calling \ref CreateIPhreeqc is off. * when phreeqc is run. The initial setting after calling \ref CreateIPhreeqc is off.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @param output_on If non-zero, turns on output to the <B><I>phreeqc.out</I></B> file. * @param output_on If non-zero, writes output to the output file; if zero, no output is written to the output file.
* @retval IPQ_OK Success. * @retval IPQ_OK Success.
* @retval IPQ_BADINSTANCE The given id is invalid. * @retval IPQ_BADINSTANCE The given id is invalid.
* @see GetOutputFileOn * @see GetOutputFileOn
@ -1023,12 +1038,12 @@ Headings
/** /**
* Sets the selected-output file switch on or off. This switch controls whether or not phreeqc writes output to * Sets the selected-output file switch on or off. This switch controls whether or not phreeqc writes output to
* the selected-output file. The initial setting after calling \ref CreateIPhreeqc is off. * the <B>SELECTED_OUTPUT</B> (<B><I>selected.out</I></B> if unspecified) file. The initial setting after calling \ref CreateIPhreeqc is off.
* @param id The instance id returned from \ref CreateIPhreeqc. * @param id The instance id returned from \ref CreateIPhreeqc.
* @param sel_on If non-zero, turns on output to the <B>SELECTED_OUTPUT</B> (<B><I>selected.out</I></B> if unspecified) file. * @param sel_on If non-zero, writes output to the selected-output file; if zero, no output is written to the selected-output file.
* @retval IPQ_OK Success. * @retval IPQ_OK Success.
* @retval IPQ_BADINSTANCE The given id is invalid. * @retval IPQ_BADINSTANCE The given id is invalid.
* @see GetSelectedOutputFileOn * @see GetSelectedOutputFileOn, GetSelectedOutputColumnCount, GetSelectedOutputRowCount, GetSelectedOutputValue
* @par Fortran90 Interface: * @par Fortran90 Interface:
* @htmlonly * @htmlonly
* <CODE> * <CODE>

67
include/IPhreeqc.hpp
View File

@ -44,6 +44,9 @@ class IPQ_DLL_EXPORT IPhreeqc
public: public:
/** /**
* Constructor. * Constructor.
* \anchor IPhreeqc_cpp
* @par Example:
* \include IPhreeqc.cpp
*/ */
IPhreeqc(void); IPhreeqc(void);
@ -72,7 +75,7 @@ public:
/** /**
* Appends the given warning message and increments the warning count. * Appends the given warning message and increments the warning count.
* Internally used to create an error condition. * Internally used to create a warning condition.
* @param warning_msg The warning message to display. * @param warning_msg The warning message to display.
* @returns The current warning count. * @returns The current warning count.
*/ */
@ -88,7 +91,7 @@ public:
* Retrieve the accumulated input string. The accumulated input string can be run * Retrieve the accumulated input string. The accumulated input string can be run
* with \ref RunAccumulated. * with \ref RunAccumulated.
* @returns The accumulated input string. * @returns The accumulated input string.
* @see AccumulateLine, ClearAccumulatedLines, RunAccumulated * @see AccumulateLine, ClearAccumulatedLines, OutputAccumulatedLines, RunAccumulated
*/ */
const std::string& GetAccumulatedLines(void); const std::string& GetAccumulatedLines(void);
@ -131,7 +134,7 @@ public:
* @return A null terminated string containing the given line. * @return A null terminated string containing the given line.
* Returns an empty string if n is out of range. * Returns an empty string if n is out of range.
* @pre \ref SetDumpStringOn must have been set to true. * @pre \ref SetDumpStringOn must have been set to true.
* @see GetDumpStringLineCount, GetDumpStringOn, GetDumpFileOn, GetDumpString, SetDumpFileOn, SetDumpStringOn * @see GetDumpFileOn, GetDumpString, GetDumpStringLineCount, GetDumpStringOn, SetDumpFileOn, SetDumpStringOn
*/ */
const char* GetDumpStringLine(int n); const char* GetDumpStringLine(int n);
@ -139,7 +142,7 @@ public:
* Retrieves the number of lines in the current dump string buffer. * Retrieves the number of lines in the current dump string buffer.
* @return The number of lines. * @return The number of lines.
* @pre \ref SetDumpStringOn must have been set to true. * @pre \ref SetDumpStringOn must have been set to true.
* @see GetDumpStringLine, GetDumpStringOn, GetDumpFileOn, GetDumpString, SetDumpFileOn, SetDumpStringOn * @see GetDumpFileOn, GetDumpString, GetDumpStringLine, GetDumpStringOn, SetDumpFileOn, SetDumpStringOn
*/ */
int GetDumpStringLineCount(void)const; int GetDumpStringLineCount(void)const;
@ -147,14 +150,14 @@ public:
* Retrieves the current value of the dump string switch. * Retrieves the current value of the dump string switch.
* @retval true Output defined by the <B>DUMP</B> keyword is stored. * @retval true Output defined by the <B>DUMP</B> keyword is stored.
* @retval false No output is stored. * @retval false No output is stored.
* @see GetDumpStringLine, GetDumpFileOn, GetDumpString, GetDumpStringLineCount, SetDumpFileOn, SetDumpStringOn * @see GetDumpFileOn, GetDumpString, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileOn, SetDumpStringOn
*/ */
bool GetDumpStringOn(void)const; bool GetDumpStringOn(void)const;
/** /**
* Retrieves the current value of the error file switch. * Retrieves the current value of the error file switch.
* @retval true Errors are written to the <B><I>phreeqc.err</I></B> file. * @retval true Errors are written to the <B><I>phreeqc.err</I></B> file.
* @retval false No output is written. * @retval false No errors are written.
* @see SetErrorFileOn * @see SetErrorFileOn
*/ */
bool GetErrorFileOn(void)const; bool GetErrorFileOn(void)const;
@ -168,7 +171,7 @@ public:
/** /**
* Retrieves the given error line. * Retrieves the given error line.
* @return A null terminated string containing the given error line message. * @return A null terminated string containing the given line of the error string buffer.
* @param n The zero-based index of the line to retrieve. * @param n The zero-based index of the line to retrieve.
* @see GetErrorStringLineCount, OutputErrorString * @see GetErrorStringLineCount, OutputErrorString
*/ */
@ -183,8 +186,10 @@ public:
/** /**
* Retrieves the current value of the log file switch. * Retrieves the current value of the log file switch.
* @retval true Output is written to the <B><I>phreeqc.log</I></B> file. * @retval true Log messages are written to the <B><I>phreeqc.log</I></B> file.
* @retval false No output is written. * @retval false No log messages are written.
* @remarks
* Logging must be enabled through the use of the KNOBS -logfile option in order to receive any log messages.
* @see SetLogFileOn * @see SetLogFileOn
*/ */
bool GetLogFileOn(void)const; bool GetLogFileOn(void)const;
@ -198,7 +203,7 @@ public:
bool GetOutputFileOn(void)const; bool GetOutputFileOn(void)const;
/** /**
* Returns the number of columns currently contained within selected-output buffer. * Retrieves the number of columns in the selected-output buffer.
* @return The number of columns. * @return The number of columns.
* @see GetSelectedOutputRowCount, GetSelectedOutputValue * @see GetSelectedOutputRowCount, GetSelectedOutputValue
*/ */
@ -213,7 +218,7 @@ public:
bool GetSelectedOutputFileOn(void)const; bool GetSelectedOutputFileOn(void)const;
/** /**
* Returns the number of rows currently contained within the selected-output buffer. * Retrieves the number of rows in the selected-output buffer.
* @return The number of rows. * @return The number of rows.
* @see GetSelectedOutputColumnCount, GetSelectedOutputFileOn, GetSelectedOutputValue, SetSelectedOutputFileOn * @see GetSelectedOutputColumnCount, GetSelectedOutputFileOn, GetSelectedOutputValue, SetSelectedOutputFileOn
*/ */
@ -396,7 +401,7 @@ public:
int GetWarningStringLineCount(void)const; int GetWarningStringLineCount(void)const;
/** /**
* Retrieves a list containing the current list of components. * Retrieves the current list of components.
* @return The current list of components. * @return The current list of components.
* @see GetComponent, GetComponentCount * @see GetComponent, GetComponentCount
*/ */
@ -405,10 +410,10 @@ public:
/** /**
* Load the specified database file into phreeqc. * Load the specified database file into phreeqc.
* @param filename The name of the phreeqc database to load. * @param filename The name of the phreeqc database to load.
* The full path will be required if the file is not * The full path (or relative path with respect to the working directory) will be required if the file is not
* in the current working directory. * in the current working directory.
* @return The number of errors encountered. * @return The number of errors encountered.
* @see LoadDatabaseString * @see LoadDatabaseString, UnLoadDatabase
* @remarks * @remarks
* All previous definitions are cleared. * All previous definitions are cleared.
*/ */
@ -418,7 +423,7 @@ public:
* Load the specified string as a database into phreeqc. * Load the specified string as a database into phreeqc.
* @param input String containing data to be used as the phreeqc database. * @param input String containing data to be used as the phreeqc database.
* @return The number of errors encountered. * @return The number of errors encountered.
* @see LoadDatabase * @see LoadDatabaseString, UnLoadDatabase
* @remarks * @remarks
* All previous definitions are cleared. * All previous definitions are cleared.
*/ */
@ -447,7 +452,7 @@ public:
* @return The number of errors encountered. * @return The number of errors encountered.
* @see AccumulateLine, ClearAccumulatedLines, OutputAccumulatedLines, RunFile, RunString * @see AccumulateLine, ClearAccumulatedLines, OutputAccumulatedLines, RunFile, RunString
* @remarks * @remarks
* The accumulated input is cleared upon a successful run (no errors). * The accumulated input is cleared at the next call to \ref AccumulateLine.
* @pre * @pre
* \ref LoadDatabase/\ref LoadDatabaseString must have been called and returned 0 (zero) errors. * \ref LoadDatabase/\ref LoadDatabaseString must have been called and returned 0 (zero) errors.
*/ */
@ -474,50 +479,54 @@ public:
int RunString(const char* input); int RunString(const char* input);
/** /**
* Sets the dump file switch on or off. This switch controls whether or not phreeqc writes to the dump file. * Sets the dump file switch on or off. This switch controls whether or not phreeqc writes to the <B>DUMP</B> (<B><I>dump.out</I></B> if unspecified) file.
* The initial setting is false. * The initial setting is false.
* @param bValue If true, turns on output to the <B>DUMP</B> (<B><I>dump.out</I></B> if unspecified) file. * @param bValue If true, turns on output to the <B>DUMP</B> file;
* @see GetDumpStringLine, GetDumpStringLineCount, GetDumpFileOn, GetDumpString, GetDumpStringOn, SetDumpStringOn * if false, turns off output to the <B>DUMP</B> file.
* @see GetDumpFileOn, GetDumpString, GetDumpStringOn, GetDumpStringLine, GetDumpStringLineCount, SetDumpStringOn
*/ */
void SetDumpFileOn(bool bValue); void SetDumpFileOn(bool bValue);
/** /**
* Sets the dump string switch on or off. This switch controls whether or not the data normally sent * Sets the dump string switch on or off. This switch controls whether or not the data normally sent
* to the dump file are stored in a buffer for retrieval. The initial setting is false. * to the dump file are stored in a buffer for retrieval. The initial setting is false.
* @param bValue If true, captures the output defined by the <B>DUMP</B> keyword into a string buffer. * @param bValue If true, captures the output defined by the <B>DUMP</B> keyword into a string buffer;
* @see GetDumpStringLine, GetDumpStringLineCount, GetDumpString, GetDumpStringOn * if false, output defined by the <B>DUMP</B> keyword is not captured to a string buffer.
* @see GetDumpFileOn, GetDumpString, GetDumpStringOn, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileOn
*/ */
void SetDumpStringOn(bool bValue); void SetDumpStringOn(bool bValue);
/** /**
* Sets the error file switch on or off. This switch controls whether or not * Sets the error file switch on or off. This switch controls whether or not
* error messages are written to the error file. The initial setting is false. * error messages are written to the <B><I>phreeqc.err</I></B> file. The initial setting is false.
* @param bValue If true, turns on output to the <B><I>phreeqc.err</I></B> file. * @param bValue If true, writes errors to the error file; if false, no errors are written to the error file.
* @see GetErrorStringLine, GetErrorStringLineCount, GetErrorFileOn, OutputErrorString * @see GetErrorStringLine, GetErrorStringLineCount, GetErrorFileOn, OutputErrorString
*/ */
void SetErrorFileOn(bool bValue); void SetErrorFileOn(bool bValue);
/** /**
* Sets the log file switch on or off. This switch controls whether or not phreeqc * Sets the log file switch on or off. This switch controls whether or not phreeqc
* writes log messages to the log file. The initial setting is false. * writes log messages to the <B><I>phreeqc.log</I></B> file. The initial setting is false.
* @param bValue If true, turns on output to the <B><I>phreeqc.log</I></B> file. * @param bValue If true, turns on output to the log file; if false, no log messages are written to the log file.
* @remarks
* Logging must be enabled through the use of the KNOBS -logfile option in order to receive any log messages.
* @see GetLogFileOn * @see GetLogFileOn
*/ */
void SetLogFileOn(bool bValue); void SetLogFileOn(bool bValue);
/** /**
* Sets the output file switch on or off. This switch controls whether or not phreeqc * Sets the output file switch on or off. This switch controls whether or not phreeqc
* writes to the output file. This is the output that is normally generated * writes to the <B><I>phreeqc.out</I></B> file. This is the output that is normally generated
* when phreeqc is run. The initial setting is false. * when phreeqc is run. The initial setting is false.
* @param bValue If true, turns on output to the <B><I>phreeqc.out</I></B> file. * @param bValue If true, writes output to the output file; if false, no output is written to the output file.
* @see GetOutputFileOn * @see GetOutputFileOn
*/ */
void SetOutputFileOn(bool bValue); void SetOutputFileOn(bool bValue);
/** /**
* Sets the selected-output file switch on or off. This switch controls whether or not phreeqc writes output to * Sets the selected-output file switch on or off. This switch controls whether or not phreeqc writes output to
* the selected-output file. The initial setting is false. * the <B>SELECTED_OUTPUT</B> (<B><I>selected.out</I></B> if unspecified) file. The initial setting is false.
* @param bValue If true, turns on output to the <B>SELECTED_OUTPUT</B> (<B><I>selected.out</I></B> if unspecified) file. * @param bValue If true, writes output to the selected-output file; if false, no output is written to the selected-output file.
* @see GetSelectedOutputColumnCount, GetSelectedOutputFileOn, GetSelectedOutputRowCount, GetSelectedOutputValue * @see GetSelectedOutputColumnCount, GetSelectedOutputFileOn, GetSelectedOutputRowCount, GetSelectedOutputValue
*/ */
void SetSelectedOutputFileOn(bool bValue); void SetSelectedOutputFileOn(bool bValue);