diff --git a/doc/Makefile b/doc/Makefile index 983c8684..319217b9 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,5 +1,17 @@ TARGET = IPhreeqc.chm +HEADERS = \ + ../include/IPhreeqc.h \ + ../include/Var.h \ + ../include/IPhreeqc.hpp + +EXAMPLES = \ + examples/AccumulateLine.c \ + examples/CreateIPhreeqc.c \ + examples/GetDumpString.c \ + examples/F90GetDumpLine.f90 + + all: $(TARGET) IPhreeqc.chm: IPhreeqc.hhp TOC.hhc html/index.html @@ -8,7 +20,7 @@ IPhreeqc.chm: IPhreeqc.hhp TOC.hhc html/index.html view: $(TARGET) cygstart $(TARGET) -html/index.html: Doxyfile ../include/IPhreeqc.h ../include/Var.h ../include/IPhreeqc.hpp +html/index.html: Doxyfile $(HEADERS) $(EXAMPLES) doxygen clean: diff --git a/doc/examples/DestroyIPhreeqc.c b/doc/examples/DestroyIPhreeqc.c deleted file mode 100644 index f0ebd946..00000000 --- a/doc/examples/DestroyIPhreeqc.c +++ /dev/null @@ -1,19 +0,0 @@ -#include -#include - -int main(void) -{ - int id; - - id = CreateIPhreeqc(); - if (id < 0) { - return EXIT_FAILURE; - } - - if (DestroyIPhreeqc(id) != IPQ_OK) { - OutputError(id); - return EXIT_FAILURE; - } - - return EXIT_SUCCESS; -} diff --git a/doc/examples/F90AccumulateLine.f90 b/doc/examples/F90GetComponent.f90 similarity index 62% rename from doc/examples/F90AccumulateLine.f90 rename to doc/examples/F90GetComponent.f90 index c6d95160..e6bca002 100644 --- a/doc/examples/F90AccumulateLine.f90 +++ b/doc/examples/F90GetComponent.f90 @@ -1,6 +1,8 @@ PROGRAM example INCLUDE "IPhreeqc.f90.inc" INTEGER(KIND=4) :: id + INTEGER(KIND=4) :: i + CHARACTER(LEN=40) :: comp id = CreateIPhreeqc() IF (id.LT.0) THEN @@ -12,24 +14,18 @@ PROGRAM example STOP ENDIF - IF (AccumulateLine(id, "SOLUTION 1").NE.IPQ_OK) THEN + IF (RunFile(id, "ex2").NE.0) THEN CALL OutputError(id) STOP ENDIF - IF (AccumulateLine(id, "END").NE.IPQ_OK) THEN - CALL OutputError(id) - STOP - ENDIF + DO i=1,GetComponentCount(id) + CALL GetComponent(id, i, comp) + WRITE(*,*) "comp ", i, "= ", comp + ENDDO - IF (RunAccumulated(id).NE.0) THEN - CALL OutputError(id) - STOP - ENDIF - IF (DestroyIPhreeqc(id).NE.IPQ_OK) THEN CALL OutputError(id) STOP ENDIF - END PROGRAM example diff --git a/doc/examples/F90GetDumpLine.f90 b/doc/examples/F90GetDumpLine.f90 new file mode 100644 index 00000000..f282bc51 --- /dev/null +++ b/doc/examples/F90GetDumpLine.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 OutputError(id) + STOP + ENDIF + + IF (LoadDatabase(id, "phreeqc.dat").NE.0) THEN + CALL OutputError(id) + STOP + ENDIF + + IF (AccumulateLine(id, "SOLUTION 1 Pure water").NE.IPQ_OK) THEN + CALL OutputError(id) + STOP + ENDIF + + IF (AccumulateLine(id, "EQUILIBRIUM_PHASES 1").NE.IPQ_OK) THEN + CALL OutputError(id) + STOP + ENDIF + + IF (AccumulateLine(id, " Calcite 0 10").NE.IPQ_OK) THEN + CALL OutputError(id) + STOP + ENDIF + + IF (AccumulateLine(id, "SAVE solution 1").NE.IPQ_OK) THEN + CALL OutputError(id) + STOP + ENDIF + + IF (AccumulateLine(id, "SAVE equilibrium_phases 1").NE.IPQ_OK) THEN + CALL OutputError(id) + STOP + ENDIF + + IF (AccumulateLine(id, "DUMP").NE.IPQ_OK) THEN + CALL OutputError(id) + STOP + ENDIF + + IF (AccumulateLine(id, " -solution 1").NE.IPQ_OK) THEN + CALL OutputError(id) + STOP + ENDIF + + IF (AccumulateLine(id, " -equilibrium_phases 1").NE.IPQ_OK) THEN + CALL OutputError(id) + STOP + ENDIF + + WRITE(*,*) "Input:" + CALL OutputLines(id) + + IF (RunAccumulated(id).NE.0) THEN + CALL OutputError(id) + STOP + ENDIF + + WRITE(*,*) "Dump:" + DO i=1,GetDumpLineCount(id) + CALL GetDumpLine(id, i, line) + WRITE(*,*) TRIM(line) + ENDDO + + IF (DestroyIPhreeqc(id).NE.IPQ_OK) THEN + CALL OutputError(id) + STOP + ENDIF +END PROGRAM example diff --git a/doc/examples/GetComponent.c b/doc/examples/GetComponent.c new file mode 100644 index 00000000..1e83669e --- /dev/null +++ b/doc/examples/GetComponent.c @@ -0,0 +1,34 @@ +#include +#include +#include + +int main(void) +{ + int id, i; + + id = CreateIPhreeqc(); + if (id < 0) { + return EXIT_FAILURE; + } + + if (LoadDatabase(id, "phreeqc.dat") != 0) { + OutputError(id); + return EXIT_FAILURE; + } + + if (RunFile(id, "ex2") != 0) { + OutputError(id); + return EXIT_FAILURE; + } + + for (i=0; i < GetComponentCount(id); ++i) { + printf("comp %d = %s\n", i, GetComponent(id, i)); + } + + if (DestroyIPhreeqc(id) != IPQ_OK) { + OutputError(id); + return EXIT_FAILURE; + } + + return EXIT_SUCCESS; +} diff --git a/doc/examples/GetDumpString.c b/doc/examples/GetDumpString.c new file mode 100644 index 00000000..fb07b96b --- /dev/null +++ b/doc/examples/GetDumpString.c @@ -0,0 +1,50 @@ +#include +#include +#include + +#define TRUE 1 + +const char input[] = + "SOLUTION 1 Pure water \n" + "EQUILIBRIUM_PHASES 1 \n" + " Calcite 0 10 \n" + "SAVE solution 1 \n" + "SAVE equilibrium_phases 1 \n" + "DUMP \n" + " -solution 1 \n" + " -equilibrium_phases 1\n"; + +int main(void) +{ + int id; + + id = CreateIPhreeqc(); + if (id < 0) { + return EXIT_FAILURE; + } + + if (LoadDatabase(id, "phreeqc.dat") != 0) { + OutputError(id); + return EXIT_FAILURE; + } + + if (SetDumpStringOn(id, TRUE) != IPQ_OK) { + OutputError(id); + return EXIT_FAILURE; + } + + if (RunString(id, input) != 0) { + OutputError(id); + return EXIT_FAILURE; + } + + printf("Dump:\n"); + printf("%s\n", GetDumpString(id)); + + if (DestroyIPhreeqc(id) != IPQ_OK) { + OutputError(id); + return EXIT_FAILURE; + } + + return EXIT_SUCCESS; +} diff --git a/doc/examples/Makefile b/doc/examples/Makefile index a6a88cdb..ff9dcb8c 100644 --- a/doc/examples/Makefile +++ b/doc/examples/Makefile @@ -13,31 +13,42 @@ IPHREEQC_LA = ../../_build/src/libiphreeqc.la TARGETS = \ AccumulateLine \ - F90AccumulateLine \ CreateIPhreeqc \ + GetComponent \ + GetDumpString + + +F90_TARGETS = \ F90CreateIPhreeqc \ - DestroyIPhreeqc \ - F90DestroyIPhreeqc + F90GetComponent \ + F90GetDumpLine -all: $(TARGETS) +all: $(TARGETS) $(F90_TARGETS) AccumulateLine: AccumulateLine.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) - CreateIPhreeqc: CreateIPhreeqc.lo $(IPHREEQC_LA) $(LIBTOOL) --mode=link $(CXX) $(LDFLAGS) -o $@ $< $(IPHREEQC_LA) +GetComponent: GetComponent.lo $(IPHREEQC_LA) + $(LIBTOOL) --mode=link $(CXX) $(LDFLAGS) -o $@ $< $(IPHREEQC_LA) + +GetDumpString: GetDumpString.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) + F90CreateIPhreeqc: F90CreateIPhreeqc.lo $(IPHREEQC_LA) $(LIBTOOL) --mode=link $(CXX) $(LDFLAGS) -o $@ $< $(IPHREEQC_LA) $(FCLIBS) -DestroyIPhreeqc: DestroyIPhreeqc.lo $(IPHREEQC_LA) - $(LIBTOOL) --mode=link $(CXX) $(LDFLAGS) -o $@ $< $(IPHREEQC_LA) - -F90DestroyIPhreeqc: F90DestroyIPhreeqc.lo $(IPHREEQC_LA) +F90GetComponent: F90GetComponent.lo $(IPHREEQC_LA) + $(LIBTOOL) --mode=link $(CXX) $(LDFLAGS) -o $@ $< $(IPHREEQC_LA) $(FCLIBS) + +F90GetDumpLine: F90GetDumpLine.lo $(IPHREEQC_LA) $(LIBTOOL) --mode=link $(CXX) $(LDFLAGS) -o $@ $< $(IPHREEQC_LA) $(FCLIBS) @@ -58,11 +69,19 @@ F90DestroyIPhreeqc: F90DestroyIPhreeqc.lo $(IPHREEQC_LA) LO_FILES = \ AccumulateLine.lo \ - F90AccumulateLine.lo \ CreateIPhreeqc.lo \ - F90CreateIPhreeqc.lo \ DestroyIPhreeqc.lo \ - F90DestroyIPhreeqc.lo + GetComponent.lo \ + GetDumpString.lo + + +F90_LO_FILES = \ + F90AccumulateLine.lo \ + F90CreateIPhreeqc.lo \ + F90DestroyIPhreeqc.lo \ + F90GetComponent.lo \ + F90GetDumpLine.lo + clean: - $(LIBTOOL) --mode=clean rm -f *~ $(TARGETS) $(LO_FILES) + $(LIBTOOL) --mode=clean rm -f *~ $(TARGETS) $(F90_TARGETS) $(LO_FILES) $(F90_LO_FILES) diff --git a/include/IPhreeqc.h b/include/IPhreeqc.h index 7f56b209..3a3fe060 100644 --- a/include/IPhreeqc.h +++ b/include/IPhreeqc.h @@ -35,6 +35,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 OutputLines, RunAccumulated * @par Fortran90 Interface: * @htmlonly * @@ -52,7 +53,7 @@ extern "C" { * \include AccumulateLine.c * * @par Fortran90 Example: - * \include F90AccumulateLine.f90 + * see \ref GetDumpLine_f90 "GetDumpLine" */ DLL_EXPORT IPQ_RESULT AccumulateLine(int id, const char *line); @@ -74,7 +75,7 @@ extern "C" { /** * Create a new IPhreeqc instance. * @return A non-negative value if successful; otherwise a negative value indicates an error occured (see \ref IPQ_RESULT). - * @see DestroyIPhreeqc + * @see DestroyIPhreeqc, UnLoadDatabase * @par Fortran90 Interface: * @htmlonly * @@ -86,9 +87,11 @@ extern "C" { * * @endhtmlonly * + * \anchor CreateIPhreeqc_c * @par C Example: * \include CreateIPhreeqc.c * + * \anchor CreateIPhreeqc_f90 * @par Fortran90 Example: * \include F90CreateIPhreeqc.f90 */ @@ -100,7 +103,7 @@ extern "C" { * @param id The instance id returned from \ref CreateIPhreeqc. * @retval IPQ_OK Success * @retval IPQ_BADINSTANCE The given id is invalid. - * @see CreateIPhreeqc + * @see CreateIPhreeqc, UnLoadDatabase * @par Fortran90 Interface: * @htmlonly * @@ -114,10 +117,10 @@ extern "C" { * @endhtmlonly * * @par C Example: - * \include DestroyIPhreeqc.c + * see \ref CreateIPhreeqc_c "CreateIPhreeqc" * * @par Fortran90 Example: - * \include F90DestroyIPhreeqc.f90 + * see \ref CreateIPhreeqc_f90 "CreateIPhreeqc" */ DLL_EXPORT IPQ_RESULT DestroyIPhreeqc(int id); @@ -142,12 +145,20 @@ extern "C" { * * * @endhtmlonly + * + * \anchor GetComponent_c + * @par C Example: + * \include GetComponent.c + * + * \anchor GetComponent_f90 + * @par Fortran90 Example: + * \include F90GetComponent.f90 */ DLL_EXPORT const char* GetComponent(int id, int n); /** - * Retrieves the number of components in the current simulation. + * Retrieves the number of components in the current component list . * @param id The instance id returned from \ref CreateIPhreeqc. * @return The current count of components. * A negative value indicates an error occured (see \ref IPQ_RESULT). @@ -163,6 +174,12 @@ extern "C" { * * * @endhtmlonly + * + * @par C Example: + * see \ref GetComponent_c "GetComponent" + * + * @par Fortran90 Example: + * see \ref GetComponent_f90 "GetComponent" */ DLL_EXPORT int GetComponentCount(int id); @@ -173,10 +190,11 @@ extern "C" { * @param n The zero-based index of the line to retrieve. * @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 GetDumpLineCount, SetDumpStringOn * @par Fortran90 Interface: * @htmlonly - * (Note: N is one-based for the fortran interface.) + * (Note: N is one-based for the Fortran interface.) * *
  *  SUBROUTINE GetDumpLine(ID,N,LINE)
@@ -187,6 +205,10 @@ extern "C" {
  *  
*
* @endhtmlonly + * + * \anchor GetDumpLine_f90 + * @par Fortran90 Example: + * \include F90GetDumpLine.f90 */ DLL_EXPORT const char* GetDumpLine(int id, int n); @@ -195,7 +217,8 @@ extern "C" { * Retrieves the number of lines in the current dump string buffer. * @param id The instance id returned from \ref CreateIPhreeqc. * @return The number of lines. - * @see GetDumpLineCount, SetDumpStringOn + * @pre \ref SetDumpStringOn must have been set to true (non-zero). + * @see GetDumpLine, SetDumpStringOn * @par Fortran90 Interface: * @htmlonly * @@ -207,14 +230,17 @@ extern "C" { * * * @endhtmlonly + * + * @par Fortran90 Example: + * see \ref GetDumpLine_f90 "GetDumpLine" */ DLL_EXPORT int GetDumpLineCount(int id); /** - * Retrieves the current value of the dump flag. + * Retrieves the current value of the dump file switch. * @param id The instance id returned from \ref CreateIPhreeqc. - * @see SetDumpOn + * @see SetDumpOn, GetDumpLineCount, GetDumpLine, GetDumpString * @par Fortran90 Interface: * @htmlonly * @@ -233,18 +259,24 @@ extern "C" { /** * Retrieves the string buffer containing DUMP output. * @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 * @par Fortran90 Interface: * Not implemented. (see \ref GetDumpLineCount, \ref GetDumpLine) + * + * \anchor GetDumpString_c + * @par C Example: + * \include GetDumpString.c */ DLL_EXPORT const char* GetDumpString(int id); /** * Retrieves the current value of the dump string flag. - * @param id The instance id returned from \ref CreateIPhreeqc. - * @see SetDumpStringOn, GetDumpString + * @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 * @par Fortran90 Interface: * @htmlonly * @@ -264,9 +296,10 @@ 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. - * @see GetErrorLineCount + * @return A null terminated string containing the given error line message. + * @see GetErrorLineCount, OutputError * @par Fortran90 Interface: - * (Note: N is one-based for the fortran interface.) + * (Note: N is one-based for the Fortran interface.) * @htmlonly * *
@@ -285,7 +318,8 @@ extern "C" {
 /**
  *  Retrieves the number of lines in the current error string buffer.
  *  @param id            The instance id returned from \ref CreateIPhreeqc.
- *  @see                 GetErrorLine
+ *  @return              The number of lines.
+ *  @see                 GetErrorLine, OutputError
  *  @par Fortran90 Interface:
  *  @htmlonly
  *  
@@ -302,8 +336,9 @@ extern "C" {
 
 
 /**
- *  Retrieves the current value of the error flag.
+ *  Retrieves the current value of the error file switch.
  *  @param id            The instance id returned from \ref CreateIPhreeqc.
+ *  @return              Non-zero if errors are written to the phreeqc.err file, 0 (zero) otherwise.
  *  @see                 SetErrorOn
  *  @par Fortran90 Interface:
  *  @htmlonly
@@ -321,8 +356,9 @@ extern "C" {
 
 
 /**
- *  Retrieves the error messages from the last call to \ref RunAccumulated, \ref RunFile, \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.
+ *  @return              A null terminated string containing error messages.
  *  @par Fortran90 Interface:
  *  Not implemented. (see \ref GetErrorLineCount, \ref GetErrorLine, \ref OutputError)
  */
@@ -330,9 +366,10 @@ extern "C" {
 
 
 /**
- *  Retrieves the current value of the log flag.
+ *  Retrieves the current value of the log file switch.
  *  @param id            The instance id returned from \ref CreateIPhreeqc.
- *  @see SetLogOn
+ *  @return              Non-zero if output is written to the phreeqc.log file, 0 (zero) otherwise.
+ *  @see                 SetLogOn
  *  @par Fortran90 Interface:
  *  @htmlonly
  *  
@@ -349,9 +386,10 @@ extern "C" {
 
 
 /**
- *  Retrieves the current value of the output flag.
- *  @param id                 The instance id returned from \ref CreateIPhreeqc.
- *  @see SetOutputOn
+ *  Retrieves the current value of the output file switch.
+ *  @param id            The instance id returned from \ref CreateIPhreeqc.
+ *  @return              Non-zero if output is written to the phreeqc.out file, 0 (zero) otherwise.
+ *  @see                 SetOutputOn
  *  @par Fortran90 Interface:
  *  @htmlonly
  *  
@@ -367,8 +405,9 @@ extern "C" {
 
 
 /**
- *  Returns the number of columns currently contained within selected_output.
+ *  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
  *  @par Fortran90 Interface:
  *  @htmlonly
@@ -386,8 +425,9 @@ extern "C" {
 
 
 /**
- *  Retrieves the selected_output flag.
+ *  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                         SetSelectedOutputOn
  *  @par Fortran90 Interface:
  *  @htmlonly
@@ -405,8 +445,9 @@ extern "C" {
 
 
 /**
- *  Returns the number of rows currently contained within selected_output.
+ *  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
  *  @par Fortran90 Interface:
  *  @htmlonly
@@ -425,15 +466,15 @@ extern "C" {
 
 /**
  *  Returns the \c VAR associated with the specified row and column.
- *  @param id            The instance id returned from \ref CreateIPhreeqc.
- *  @param row  The row index.
- *  @param col  The column index.
- *  @param pVAR Pointer to the \c VAR to recieve the requested data.
- *  @retval IPQ_OK Success
- *  @retval IPQ_INVALIDROW The given row is out of range.
- *  @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.
+ *  @param id                The instance id returned from \ref CreateIPhreeqc.
+ *  @param row               The row index.
+ *  @param col               The column index.
+ *  @param pVAR              Pointer to the \c VAR to recieve the requested data.
+ *  @retval IPQ_OK           Success.
+ *  @retval IPQ_INVALIDROW   The given row is out of range.
+ *  @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.
  *  @remarks
  *  Row 0 contains the column headings to the selected_ouput.
  *  @par Examples:
@@ -575,8 +616,8 @@ Headings
 
  *  @endhtmlonly
  *  @par Fortran90 Interface:
- *  ROW is 1-based for the fortran interface except that the column headings are stored in ROW=0.
- *  COL is 1-based for the fortran interface.
+ *  ROW is 1-based for the Fortran interface except that the column headings are stored in ROW=0.
+ *  COL is 1-based for the Fortran interface.
  *  @htmlonly
  *  
  *  
@@ -592,17 +633,24 @@ Headings
  *  
*
* @endhtmlonly + * @param ID The instance id returned from \ref CreateIPhreeqc. + * @param ROW The row index. + * @param COL The column index. + * @param VTYPE Returns the variable type. See \ref VAR_TYPE. + * @param DVALUE Returns the numeric value when (VTYPE=\ref TT_DOUBLE) or (VTYPE=\ref TT_LONG). + * @param SVALUE Returns the string variable when (VTYPE=\ref TT_STRING). When (VTYPE=\ref TT_DOUBLE) or (VTYPE=\ref TT_LONG) this variable is filled with a string equivalent of DVALUE. */ DLL_EXPORT IPQ_RESULT GetSelectedOutputValue(int id, int row, int col, VAR* pVAR); /** - * Retrieves the current value of the dump flag. + * Retrieves the given warning 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 warning line message. * @see GetWarningLineCount, OutputWarning * @par Fortran90 Interface: - * (Note: N is one-based for the fortran interface.) + * (Note: N is one-based for the Fortran interface.) * @htmlonly * *
@@ -620,6 +668,8 @@ 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                 GetWarningLine, OutputWarning
  *  @par Fortran90 Interface:
  *  @htmlonly
  *  
@@ -636,8 +686,10 @@ Headings
 
 
 /**
- *  Retrieves the warning messages from the last call to \ref RunAccumulated, \ref RunFile, \ref LoadDatabase, or \ref LoadDatabaseString.
+ *  Retrieves the warning 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 warning messages.
+ *  @see                 GetWarningLine, GetWarningLineCount, OutputWarning
  *  @par Fortran90 Interface:
  *  Not implemented. (see \ref GetWarningLineCount, \ref GetWarningLine, \ref OutputWarning)
  */
@@ -647,12 +699,13 @@ Headings
 /**
  *  Load the specified database file into phreeqc.
  *  @param id            The instance id returned from \ref CreateIPhreeqc.
- *  @param filename The name of the phreeqc database to load.
- *         The full path will be required if the file is not
- *         in the current working directory.
- *  @return The number of errors encountered.
+ *  @param filename      The name of the phreeqc database to load.
+ *                       The full path (or relative path with respect to the working directory)
+ *                       must be given if the file is not in the current working directory.
+ *  @return              The number of errors encountered.
+ *  @see                 LoadDatabaseString, UnLoadDatabase
  *  @remarks
- *  Any previous database definitions are cleared.
+ *  All previous definitions are cleared.
  *  @par Fortran90 Interface:
  *  @htmlonly
  *  
@@ -665,6 +718,12 @@ Headings
  *  
* * @endhtmlonly + * + * @par C Example: + * see \ref CreateIPhreeqc_c "CreateIPhreeqc" + * + * @par Fortran90 Example: + * see \ref CreateIPhreeqc_f90 "CreateIPhreeqc" */ DLL_EXPORT int LoadDatabase(int id, const char* filename); @@ -674,8 +733,9 @@ Headings * @param id The instance id returned from \ref CreateIPhreeqc. * @param input String containing data to be used as the phreeqc database. * @return The number of errors encountered. + * @see LoadDatabase, UnLoadDatabase * @remarks - * Any previous database definitions are cleared. + * All previous definitions are cleared. * @par Fortran90 Interface: * @htmlonly * @@ -695,6 +755,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 GetErrorLine, GetErrorLineCount * @par Fortran90 Interface: * @htmlonly * @@ -705,14 +766,20 @@ Headings *
* * @endhtmlonly + * + * @par C Example: + * see \ref GetComponent_c "GetComponent" + * + * @par Fortran90 Example: + * see \ref GetDumpLine_f90 "GetDumpLine" */ DLL_EXPORT void OutputError(int id); /** - * Output the accumulated input to stdout. This is the input that will be - * used for the next call to RunAccumulated. + * Output the accumulated input buffer to stdout. This input can be run with a call to \ref RunAccumulated. * @param id The instance id returned from \ref CreateIPhreeqc. + * @see AccumulateLine, RunAccumulated * @par Fortran90 Interface: * @htmlonly * @@ -723,6 +790,9 @@ Headings * * * @endhtmlonly + * + * @par Fortran90 Example: + * see \ref GetDumpLine_f90 "GetDumpLine" */ DLL_EXPORT void OutputLines(int id); @@ -730,6 +800,7 @@ Headings /** * Output the warning messages to stdout. * @param id The instance id returned from \ref CreateIPhreeqc. + * @see GetWarningLine, GetWarningLineCount * @par Fortran90 Interface: * @htmlonly * @@ -745,9 +816,10 @@ Headings /** - * Runs the accumulated input sent to AccumulateLine. + * Runs the input buffer defined by calls to \ref AccumulateLine. * @param id The instance id returned from \ref CreateIPhreeqc. * @return The number of errors encountered. + * @see AccumulateLine, OutputLines, RunFile, RunString * @remarks * The accumulated input is cleared upon a successful run (no errors). * @pre \ref LoadDatabase/\ref LoadDatabaseString must have been called and returned 0 (zero) errors. @@ -771,6 +843,7 @@ Headings * @param id The instance id returned from \ref CreateIPhreeqc. * @param filename The name of the phreeqc input file to run. * @return The number of errors encountered during the run. + * @see RunAccumulated, RunString * @pre \ref LoadDatabase/\ref LoadDatabaseString must have been called and returned 0 (zero) errors. * @par Fortran90 Interface: * @htmlonly @@ -784,6 +857,12 @@ Headings * * * @endhtmlonly + * + * @par C Example: + * see \ref CreateIPhreeqc_c "CreateIPhreeqc" + * + * @par Fortran90 Example: + * see \ref CreateIPhreeqc_f90 "CreateIPhreeqc" */ DLL_EXPORT int RunFile(int id, const char* filename); @@ -793,6 +872,7 @@ Headings * @param id The instance id returned from \ref CreateIPhreeqc. * @param input String containing phreeqc input. * @return The number of errors encountered during the run. + * @see RunAccumulated, RunFile * @pre \ref LoadDatabase/\ref LoadDatabaseString must have been called and returned 0 (zero) errors. * @par Fortran90 Interface: * @htmlonly @@ -811,13 +891,13 @@ Headings /** - * Sets the dump flag on or off. This flag controls whether or not phreeqc writes to the dump file. - * The default after calling \ref CreateIPhreeqc is off. + * 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. * @retval IPQ_OK Success * @retval IPQ_BADINSTANCE The given id is invalid. - * @see + * @see GetDumpOn, GetDumpString, GetDumpLine, GetDumpLineCount, SetDumpStringOn * @par Fortran90 Interface: * @htmlonly * @@ -834,13 +914,14 @@ Headings /** - * Sets the dump string flag on or off. This flag controls whether or not the data normally sent - * to the dump file is stored in a buffer for later retrieval. The default after calling + * 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 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. - * @retval IPQ_OK Success - * @retval IPQ_BADINSTANCE The given id is invalid. + * @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. + * @retval IPQ_OK Success. + * @retval IPQ_BADINSTANCE The given id is invalid. + * @see GetDumpStringOn, GetDumpString, GetDumpLine, GetDumpLineCount * @par Fortran90 Interface: * @htmlonly * @@ -852,18 +933,25 @@ Headings * * * @endhtmlonly + * + * @par C Example: + * see \ref GetDumpString_c "GetDumpString" + * + * @par Fortran90 Example: + * see \ref GetDumpLine_f90 "GetDumpLine" */ DLL_EXPORT IPQ_RESULT SetDumpStringOn(int id, int dump_string_on); /** - * Sets the error flag on or off. This flag controls whether or not - * error messages are written to the phreeqc.err file. The default after calling + * Sets the error file switch on or off. This switch controls whether or not + * 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. - * @retval IPQ_OK Success - * @retval IPQ_BADINSTANCE The given id is invalid. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @param error_on If non-zero turns on output to the phreeqc.err file. + * @retval IPQ_OK Success. + * @retval IPQ_BADINSTANCE The given id is invalid. + * @see OutputError, GetErrorLine, GetErrorLineCount * @par Fortran90 Interface: * @htmlonly * @@ -880,12 +968,12 @@ Headings /** - * Sets the log flag on or off. This flag controls whether or not phreeqc - * writes log messages to the phreeqc.log file. The default after calling + * Sets the log file switch on or off. This switch controls whether or not phreeqc + * 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. - * @retval IPQ_OK Success + * @param log_on If non-zero turns on output to the phreeqc.log file. + * @retval IPQ_OK Success. * @retval IPQ_BADINSTANCE The given id is invalid. * @see GetLogOn * @par Fortran90 Interface: @@ -905,13 +993,14 @@ Headings /** - * Sets the output flag on or off. This flag controls whether or not phreeqc - * writes output to phreeqc.out. This output is the output normally generated - * when phreeqc is run. The default 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. - * @retval IPQ_OK Success + * Sets the output file switch on or off. This switch controls whether or not phreeqc + * writes to the output file. This output 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. + * @retval IPQ_OK Success. * @retval IPQ_BADINSTANCE The given id is invalid. + * @see GetOutputOn * @par Fortran90 Interface: * @htmlonly * @@ -929,12 +1018,13 @@ Headings /** - * Sets the selected output flag on or off. This flag controls whether or not phreeqc writes output to - * the selected output file. The default 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. - * @retval IPQ_OK Success + * 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. + * @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. + * @retval IPQ_OK Success. * @retval IPQ_BADINSTANCE The given id is invalid. + * @see GetSelectedOutputOn * @par Fortran90 Interface: * @htmlonly * @@ -953,9 +1043,12 @@ Headings /** - * Unloads any database currently loaded into phreeqc. In addition, all - * previous phreeqc definitions (ie SOLUTIONS, EXCHANGERS, etc) are cleared from memory. - * @param id The instance id returned from \ref CreateIPhreeqc. + * Unloads the database currently loaded into phreeqc. In addition, all + * previous phreeqc definitions (i.e. SOLUTION, EXCHANGER, etc) are cleared from memory. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @retval IPQ_OK Success. + * @retval IPQ_BADINSTANCE The given id is invalid. + * @see DestroyIPhreeqc, LoadDatabase, LoadDatabaseString * @remarks * Use of the method is not normally necessary. It is called automatically * before each call to \ref LoadDatabase or \ref LoadDatabaseString.