From 9b3a5e3b03698523748507f4fb4d97fea96aa26c Mon Sep 17 00:00:00 2001 From: Scott R Charlton Date: Thu, 20 May 2010 05:58:25 +0000 Subject: [PATCH] updated docs git-svn-id: svn://136.177.114.72/svn_GW/IPhreeqc/trunk@4432 1feff8c3-07ed-0310-ac33-dd36852eb9cd --- doc/examples/F90GetComponent.f90 | 2 +- doc/examples/F90GetDumpStringLine.f90 | 80 ++++++++++++++++++++++++++ doc/examples/IPhreeqc.cpp | 59 +++++++++++++++++++ doc/examples/Makefile | 15 ++++- include/IPhreeqc.h | 81 ++++++++++++++++----------- include/IPhreeqc.hpp | 67 ++++++++++++---------- 6 files changed, 238 insertions(+), 66 deletions(-) create mode 100644 doc/examples/F90GetDumpStringLine.f90 create mode 100644 doc/examples/IPhreeqc.cpp diff --git a/doc/examples/F90GetComponent.f90 b/doc/examples/F90GetComponent.f90 index fbfdf250..7629ce37 100644 --- a/doc/examples/F90GetComponent.f90 +++ b/doc/examples/F90GetComponent.f90 @@ -21,7 +21,7 @@ PROGRAM example DO i=1,GetComponentCount(id) CALL GetComponent(id, i, comp) - WRITE(*,*) "comp ", i, "= ", comp + WRITE(*,*) "comp #", i, "= ", comp ENDDO IF (DestroyIPhreeqc(id).NE.IPQ_OK) THEN diff --git a/doc/examples/F90GetDumpStringLine.f90 b/doc/examples/F90GetDumpStringLine.f90 new file mode 100644 index 00000000..654b0fbb --- /dev/null +++ b/doc/examples/F90GetDumpStringLine.f90 @@ -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 diff --git a/doc/examples/IPhreeqc.cpp b/doc/examples/IPhreeqc.cpp new file mode 100644 index 00000000..f5edf497 --- /dev/null +++ b/doc/examples/IPhreeqc.cpp @@ -0,0 +1,59 @@ +#include +#include +#include + +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; +} diff --git a/doc/examples/Makefile b/doc/examples/Makefile index b156f600..a2b104c9 100644 --- a/doc/examples/Makefile +++ b/doc/examples/Makefile @@ -15,7 +15,8 @@ TARGETS = \ AccumulateLine \ CreateIPhreeqc \ GetComponent \ - GetDumpString + GetDumpString \ + IPhreeqc F90_TARGETS = \ @@ -39,6 +40,9 @@ GetComponent: GetComponent.lo $(IPHREEQC_LA) GetDumpString: GetDumpString.lo $(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) $(LIBTOOL) --mode=link $(CXX) $(LDFLAGS) -o $@ $< $(IPHREEQC_LA) $(FCLIBS) @@ -63,6 +67,9 @@ F90ClearAccumulatedLines: F90ClearAccumulatedLines.lo $(IPHREEQC_LA) .cxx.lo: $(LIBTOOL) --mode=compile $(CXX) $(CPPFLAGS) $(CFLAGS) -c -o $@ $< + +.cpp.lo: + $(LIBTOOL) --mode=compile $(CXX) $(CPPFLAGS) $(CFLAGS) -c -o $@ $< .f.lo: $(LIBTOOL) --mode=compile $(F77) $(FFLAGS) -c -o $@ $< @@ -75,7 +82,8 @@ LO_FILES = \ CreateIPhreeqc.lo \ DestroyIPhreeqc.lo \ GetComponent.lo \ - GetDumpString.lo + GetDumpString.lo\ + IPhreeqc.lo F90_LO_FILES = \ @@ -83,7 +91,8 @@ F90_LO_FILES = \ F90CreateIPhreeqc.lo \ F90DestroyIPhreeqc.lo \ F90GetComponent.lo \ - F90GetDumpStringLine.lo + F90GetDumpStringLine.lo \ + F90ClearAccumulatedLines.lo clean: diff --git a/include/IPhreeqc.h b/include/IPhreeqc.h index 2fd3af3d..e9d1f614 100644 --- a/include/IPhreeqc.h +++ b/include/IPhreeqc.h @@ -29,7 +29,7 @@ extern "C" { * @param line The line(s) to add for input to phreeqc. * @retval IPQ_OK Success * @retval IPQ_OUTOFMEMORY Out of memory - * @see OutputAccumulatedLines, RunAccumulated + * @see ClearAccumulatedLines, OutputAccumulatedLines, RunAccumulated * @par Fortran90 Interface: * @htmlonly * @@ -136,7 +136,7 @@ extern "C" { * Returns an empty string if n is out of range. * @see GetComponentCount * @par Fortran90 Interface: - * (Note: N is one-based for the fortran interface) + * (Note: N is one-based for the Fortran interface) * @htmlonly * * 
@@ -191,7 +191,7 @@ extern "C" {
  *  Retrieves the current value of the dump file switch.
  *  @param id            The instance id returned from \ref CreateIPhreeqc.
  *  @return              Non-zero if output is written to the DUMP (dump.out if unspecified) file, 0 (zero) otherwise.
- *  @see                 SetDumpFileOn, GetDumpStringLineCount, GetDumpStringLine, GetDumpString
+ *  @see                 GetDumpString, GetDumpStringLine, GetDumpStringLineCount, GetDumpStringOn, SetDumpFileOn, SetDumpStringOn
  *  @par Fortran90 Interface:
  *  @htmlonly
  *  
@@ -212,7 +212,7 @@ extern "C" {
  *  @param id            The instance id returned from \ref CreateIPhreeqc.
  *  @return              A null terminated string containing DUMP output.
  *  @pre                 \ref SetDumpStringOn must have been set to true (non-zero) in order to recieve DUMP output.
- *  @see                 SetDumpStringOn
+ *  @see                 GetDumpFileOn, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileOn, GetDumpStringOn, SetDumpStringOn
  *  @par Fortran90 Interface:
  *  Not implemented. (see \ref GetDumpStringLineCount, \ref GetDumpStringLine)
  *
@@ -230,7 +230,7 @@ extern "C" {
  *  @return              A null terminated string containing the given line.
  *                       Returns an empty string if n is out of range.
  *  @pre                 \ref SetDumpStringOn must have been set to true (non-zero).
- *  @see                 GetDumpStringLineCount, SetDumpStringOn
+ *  @see                 GetDumpFileOn, GetDumpString, GetDumpStringLineCount, GetDumpStringOn, SetDumpFileOn, SetDumpStringOn
  *  @par Fortran90 Interface:
  *  @htmlonly
  *  (Note: N is one-based for the Fortran interface.)
@@ -257,7 +257,7 @@ extern "C" {
  *  @param id            The instance id returned from \ref CreateIPhreeqc.
  *  @return              The number of lines.
  *  @pre                 \ref SetDumpStringOn must have been set to true (non-zero).
- *  @see                 GetDumpStringLine, SetDumpStringOn
+ *  @see                 GetDumpFileOn, GetDumpString, GetDumpStringLine, GetDumpStringOn, SetDumpFileOn, SetDumpStringOn
  *  @par Fortran90 Interface:
  *  @htmlonly
  *  
@@ -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.
  *  @return              Non-zero if output defined by the DUMP keyword is stored, 0 (zero) otherwise.
- *  @see                 SetDumpStringOn, GetDumpString
+ *  @see                 GetDumpFileOn, GetDumpString, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileOn, SetDumpStringOn
  *  @par Fortran90 Interface:
  *  @htmlonly
  *  
@@ -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.
  *  @param id            The instance id returned from \ref CreateIPhreeqc.
  *  @return              A null terminated string containing error messages.
+ *  @see                 GetErrorFileOn, GetErrorStringLine, GetErrorStringLineCount, OutputErrorString, SetErrorFileOn
  *  @par Fortran90 Interface:
  *  Not implemented. (see \ref GetErrorStringLineCount, \ref GetErrorStringLine, \ref OutputErrorString)
  */
@@ -330,8 +331,8 @@ extern "C" {
  *  Retrieves the given error line.
  *  @param id            The instance id returned from \ref CreateIPhreeqc.
  *  @param n             The zero-based index of the line to retrieve.
- *  @return              A null terminated string containing the given error line message.
- *  @see                 GetErrorStringLineCount, OutputErrorString
+ *  @return              A null terminated string containing the given line of the error string buffer.
+ *  @see                 GetErrorFileOn, GetErrorString, GetErrorStringLineCount, OutputErrorString, SetErrorFileOn
  *  @par Fortran90 Interface:
  *  (Note: N is one-based for the Fortran interface.)
  *  @htmlonly
@@ -353,7 +354,7 @@ extern "C" {
  *  Retrieves the number of lines in the current error string buffer.
  *  @param id            The instance id returned from \ref CreateIPhreeqc.
  *  @return              The number of lines.
- *  @see                 GetErrorStringLine, OutputErrorString
+ *  @see                 GetErrorFileOn, GetErrorString, GetErrorStringLine, OutputErrorString, SetErrorFileOn
  *  @par Fortran90 Interface:
  *  @htmlonly
  *  
@@ -372,7 +373,9 @@ extern "C" {
 /**
  *  Retrieves the current value of the log file switch.
  *  @param id            The instance id returned from \ref CreateIPhreeqc.
- *  @return              Non-zero if output is written to the phreeqc.log file, 0 (zero) otherwise.
+ *  @return              Non-zero if log messages are written to the phreeqc.log 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
  *  @par Fortran90 Interface:
  *  @htmlonly
@@ -412,7 +415,7 @@ extern "C" {
  *  Retrieves the number of columns in the selected-output buffer.
  *  @param id            The instance id returned from \ref CreateIPhreeqc.
  *  @return              The number of columns.
- *  @see                 GetSelectedOutputRowCount, GetSelectedOutputValue
+ *  @see                 GetSelectedOutputFileOn, GetSelectedOutputRowCount, GetSelectedOutputValue, SetSelectedOutputFileOn
  *  @par Fortran90 Interface:
  *  @htmlonly
  *  
@@ -432,7 +435,7 @@ extern "C" {
  *  Retrieves the selected-output file switch.
  *  @param id                    The instance id returned from \ref CreateIPhreeqc.
  *  @return                      Non-zero if output is written to the selected-output (selected.out if unspecified) file, 0 (zero) otherwise.
- *  @see                         SetSelectedOutputFileOn
+ *  @see                         GetSelectedOutputColumnCount, GetSelectedOutputRowCount, GetSelectedOutputValue, SetSelectedOutputFileOn
  *  @par Fortran90 Interface:
  *  @htmlonly
  *  
@@ -452,7 +455,7 @@ extern "C" {
  *  Retrieves the number of rows in the selected-output buffer.
  *  @param id            The instance id returned from \ref CreateIPhreeqc.
  *  @return              The number of rows.
- *  @see GetSelectedOutputColumnCount, GetSelectedOutputValue
+ *  @see                 GetSelectedOutputFileOn, GetSelectedOutputColumnCount, GetSelectedOutputValue, SetSelectedOutputFileOn
  *  @par Fortran90 Interface:
  *  @htmlonly
  *  
@@ -479,6 +482,7 @@ extern "C" {
  *  @retval IPQ_INVALIDCOL   The given column is out of range.
  *  @retval IPQ_OUTOFMEMORY  Memory could not be allocated.
  *  @retval IPQ_BADINSTANCE  The given id is invalid.
+ *  @see                     GetSelectedOutputFileOn, GetSelectedOutputColumnCount, GetSelectedOutputRowCount, SetSelectedOutputFileOn
  *  @remarks
  *  Row 0 contains the column headings to the selected_ouput.
  *  @par Examples:
@@ -663,7 +667,7 @@ Headings
  *  @param id            The instance id returned from \ref CreateIPhreeqc.
  *  @param n             The zero-based index of the line to retrieve.
  *  @return              A null terminated string containing the given warning line message.
- *  @see                 GetWarningStringLineCount, OutputWarningString
+ *  @see                 GetWarningString, GetWarningStringLineCount, OutputWarningString
  *  @par Fortran90 Interface:
  *  (Note: N is one-based for the Fortran interface.)
  *  @htmlonly
@@ -684,7 +688,7 @@ Headings
  *  Retrieves the number of lines in the current warning string buffer.
  *  @param id            The instance id returned from \ref CreateIPhreeqc.
  *  @return              The number of lines.
- *  @see                 GetWarningStringLine, OutputWarningString
+ *  @see                 GetWarningString, GetWarningStringLine, OutputWarningString
  *  @par Fortran90 Interface:
  *  @htmlonly
  *  
@@ -780,7 +784,7 @@ Headings
 /**
  *  Output the error messages normally stored in the phreeqc.err file to stdout.
  *  @param id            The instance id returned from \ref CreateIPhreeqc.
- *  @see                 GetErrorStringLine, GetErrorStringLineCount
+ *  @see                 GetErrorFileOn, GetErrorStringLine, GetErrorStringLineCount, SetErrorFileOn
  *  @par Fortran90 Interface:
  *  @htmlonly
  *  
@@ -804,7 +808,7 @@ Headings
 /**
  *  Output the warning messages to stdout.
  *  @param id            The instance id returned from \ref CreateIPhreeqc.
- *  @see                 GetWarningStringLine, GetWarningStringLineCount
+ *  @see                 GetWarningString, GetWarningStringLine, GetWarningStringLineCount
  *  @par Fortran90 Interface:
  *  @htmlonly
  *  
@@ -823,9 +827,9 @@ Headings
  *  Runs the input buffer as defined by calls to \ref AccumulateLine.
  *  @param id            The instance id returned from \ref CreateIPhreeqc.
  *  @return              The number of errors encountered.
- *  @see                 AccumulateLine, OutputAccumulatedLines, RunFile, RunString
+ *  @see                 AccumulateLine, ClearAccumulatedLines, OutputAccumulatedLines, RunFile, RunString
  *  @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.
  *  @par Fortran90 Interface:
  *  @htmlonly
@@ -838,6 +842,9 @@ Headings
  *
* * @endhtmlonly + * + * @par Fortran90 Example: + * see \ref GetDumpStringLine_f90 "GetDumpStringLine" */ IPQ_DLL_EXPORT int RunAccumulated(int id); @@ -890,6 +897,10 @@ Headings * * * @endhtmlonly + * + * @par C Example: + * see \ref GetDumpString_c "GetDumpString" + * */ 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. * The initial setting after calling \ref CreateIPhreeqc is off. * @param id The instance id returned from \ref CreateIPhreeqc. - * @param dump_on If non-zero, turns on output to the DUMP (dump.out if unspecified) file. + * @param dump_on If non-zero, turns on output to the DUMP (dump.out if unspecified) file; + * if zero, turns off output to the DUMP file. * @retval IPQ_OK Success. * @retval IPQ_BADINSTANCE The given id is invalid. - * @see GetDumpFileOn, GetDumpString, GetDumpStringLine, GetDumpStringLineCount, SetDumpStringOn + * @see GetDumpFileOn, GetDumpString, GetDumpStringLine, GetDumpStringOn, GetDumpStringLineCount, SetDumpStringOn * @par Fortran90 Interface: * @htmlonly * @@ -922,10 +934,11 @@ Headings * to the dump file are stored in a buffer for retrieval. The initial setting after calling * \ref CreateIPhreeqc is off. * @param id The instance id returned from \ref CreateIPhreeqc. - * @param dump_string_on If non-zero, captures the output defined by the DUMP keyword into a string buffer. + * @param dump_string_on If non-zero, captures the output defined by the DUMP keyword into a string buffer; + * if zero, output defined by the DUMP keyword is not captured to a string buffer. * @retval IPQ_OK Success. * @retval IPQ_BADINSTANCE The given id is invalid. - * @see GetDumpStringOn, GetDumpString, GetDumpStringLine, GetDumpStringLineCount + * @see GetDumpFileOn, GetDumpStringOn, GetDumpString, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileOn * @par Fortran90 Interface: * @htmlonly * @@ -952,10 +965,10 @@ Headings * error messages are written to the phreeqc.err file. The initial setting after calling * \ref CreateIPhreeqc is off. * @param id The instance id returned from \ref CreateIPhreeqc. - * @param error_on If non-zero, turns on output to the phreeqc.err 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_BADINSTANCE The given id is invalid. - * @see OutputErrorString, GetErrorStringLine, GetErrorStringLineCount + * @see GetErrorFileOn, GetErrorStringLine, GetErrorStringLineCount, OutputErrorString * @par Fortran90 Interface: * @htmlonly * @@ -976,9 +989,11 @@ Headings * writes log messages to the phreeqc.log file. The initial setting after calling * \ref CreateIPhreeqc is off. * @param id The instance id returned from \ref CreateIPhreeqc. - * @param log_on If non-zero, turns on output to the phreeqc.log 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_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 * @par Fortran90 Interface: * @htmlonly @@ -998,10 +1013,10 @@ Headings /** * 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 phreeqc.out file. This is the output normally generated * when phreeqc is run. The initial setting after calling \ref CreateIPhreeqc is off. * @param id The instance id returned from \ref CreateIPhreeqc. - * @param output_on If non-zero, turns on output to the phreeqc.out 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_BADINSTANCE The given id is invalid. * @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 - * the selected-output file. The initial setting after calling \ref CreateIPhreeqc is off. + * the SELECTED_OUTPUT (selected.out if unspecified) file. The initial setting after calling \ref CreateIPhreeqc is off. * @param id The instance id returned from \ref CreateIPhreeqc. - * @param sel_on If non-zero, turns on output to the SELECTED_OUTPUT (selected.out 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_BADINSTANCE The given id is invalid. - * @see GetSelectedOutputFileOn + * @see GetSelectedOutputFileOn, GetSelectedOutputColumnCount, GetSelectedOutputRowCount, GetSelectedOutputValue * @par Fortran90 Interface: * @htmlonly * diff --git a/include/IPhreeqc.hpp b/include/IPhreeqc.hpp index c3e60ba7..9d92956a 100644 --- a/include/IPhreeqc.hpp +++ b/include/IPhreeqc.hpp @@ -44,6 +44,9 @@ class IPQ_DLL_EXPORT IPhreeqc public: /** * Constructor. + * \anchor IPhreeqc_cpp + * @par Example: + * \include IPhreeqc.cpp */ IPhreeqc(void); @@ -72,7 +75,7 @@ public: /** * 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. * @returns The current warning count. */ @@ -88,7 +91,7 @@ public: * Retrieve the accumulated input string. The accumulated input string can be run * with \ref RunAccumulated. * @returns The accumulated input string. - * @see AccumulateLine, ClearAccumulatedLines, RunAccumulated + * @see AccumulateLine, ClearAccumulatedLines, OutputAccumulatedLines, RunAccumulated */ const std::string& GetAccumulatedLines(void); @@ -131,7 +134,7 @@ public: * @return A null terminated string containing the given line. * Returns an empty string if n is out of range. * @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); @@ -139,7 +142,7 @@ public: * Retrieves the number of lines in the current dump string buffer. * @return The number of lines. * @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; @@ -147,14 +150,14 @@ public: * Retrieves the current value of the dump string switch. * @retval true Output defined by the DUMP keyword 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; /** * Retrieves the current value of the error file switch. * @retval true Errors are written to the phreeqc.err file. - * @retval false No output is written. + * @retval false No errors are written. * @see SetErrorFileOn */ bool GetErrorFileOn(void)const; @@ -168,7 +171,7 @@ public: /** * 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. * @see GetErrorStringLineCount, OutputErrorString */ @@ -183,8 +186,10 @@ public: /** * Retrieves the current value of the log file switch. - * @retval true Output is written to the phreeqc.log file. - * @retval false No output is written. + * @retval true Log messages are written to the phreeqc.log file. + * @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 */ bool GetLogFileOn(void)const; @@ -198,7 +203,7 @@ public: 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. * @see GetSelectedOutputRowCount, GetSelectedOutputValue */ @@ -213,7 +218,7 @@ public: 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. * @see GetSelectedOutputColumnCount, GetSelectedOutputFileOn, GetSelectedOutputValue, SetSelectedOutputFileOn */ @@ -396,7 +401,7 @@ public: 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. * @see GetComponent, GetComponentCount */ @@ -405,10 +410,10 @@ public: /** * Load the specified database file into phreeqc. * @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. * @return The number of errors encountered. - * @see LoadDatabaseString + * @see LoadDatabaseString, UnLoadDatabase * @remarks * All previous definitions are cleared. */ @@ -418,7 +423,7 @@ public: * Load the specified string as a database into phreeqc. * @param input String containing data to be used as the phreeqc database. * @return The number of errors encountered. - * @see LoadDatabase + * @see LoadDatabaseString, UnLoadDatabase * @remarks * All previous definitions are cleared. */ @@ -447,7 +452,7 @@ public: * @return The number of errors encountered. * @see AccumulateLine, ClearAccumulatedLines, OutputAccumulatedLines, RunFile, RunString * @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. */ @@ -474,50 +479,54 @@ public: 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 DUMP (dump.out if unspecified) file. * The initial setting is false. - * @param bValue If true, turns on output to the DUMP (dump.out if unspecified) file. - * @see GetDumpStringLine, GetDumpStringLineCount, GetDumpFileOn, GetDumpString, GetDumpStringOn, SetDumpStringOn + * @param bValue If true, turns on output to the DUMP file; + * if false, turns off output to the DUMP file. + * @see GetDumpFileOn, GetDumpString, GetDumpStringOn, GetDumpStringLine, GetDumpStringLineCount, SetDumpStringOn */ void SetDumpFileOn(bool bValue); /** * 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. - * @param bValue If true, captures the output defined by the DUMP keyword into a string buffer. - * @see GetDumpStringLine, GetDumpStringLineCount, GetDumpString, GetDumpStringOn + * @param bValue If true, captures the output defined by the DUMP keyword into a string buffer; + * if false, output defined by the DUMP keyword is not captured to a string buffer. + * @see GetDumpFileOn, GetDumpString, GetDumpStringOn, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileOn */ void SetDumpStringOn(bool bValue); /** * 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. - * @param bValue If true, turns on output to the phreeqc.err file. + * error messages are written to the phreeqc.err file. The initial setting is false. + * @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 */ void SetErrorFileOn(bool bValue); /** * 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. - * @param bValue If true, turns on output to the phreeqc.log file. + * writes log messages to the phreeqc.log file. The initial setting is false. + * @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 */ void SetLogFileOn(bool bValue); /** * 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 phreeqc.out file. This is the output that is normally generated * when phreeqc is run. The initial setting is false. - * @param bValue If true, turns on output to the phreeqc.out file. + * @param bValue If true, writes output to the output file; if false, no output is written to the output file. * @see GetOutputFileOn */ void SetOutputFileOn(bool bValue); /** * 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. - * @param bValue If true, turns on output to the SELECTED_OUTPUT (selected.out if unspecified) file. + * the SELECTED_OUTPUT (selected.out if unspecified) file. The initial setting is false. + * @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 */ void SetSelectedOutputFileOn(bool bValue);