diff --git a/IPhreeqc.f.inc b/IPhreeqc.f.inc new file mode 100644 index 00000000..532f58af --- /dev/null +++ b/IPhreeqc.f.inc @@ -0,0 +1,85 @@ +C +C GetSelectedOutputValue TYPES +C + INTEGER :: TT_EMPTY + PARAMETER (TT_EMPTY=0) + + INTEGER :: TT_ERROR + PARAMETER (TT_ERROR=1) + + INTEGER :: TT_DOUBLE + PARAMETER (TT_DOUBLE=3) + + INTEGER :: TT_STRING + PARAMETER (TT_STRING=4) + +C +C IPQ_RESULT TYPES +C + + INTEGER :: IPQ_OK + PARAMETER (IPQ_OK=0) + + INTEGER :: IPQ_OUTOFMEMORY + PARAMETER (IPQ_OUTOFMEMORY=-1) + + INTEGER :: IPQ_BADVARTYPE + PARAMETER (IPQ_BADVARTYPE=-2) + + INTEGER :: IPQ_INVALIDARG + PARAMETER (IPQ_INVALIDARG=-3) + + INTEGER :: IPQ_INVALIDROW + PARAMETER (IPQ_INVALIDROW=-4) + + INTEGER :: IPQ_INVALIDCOL + PARAMETER (IPQ_INVALIDCOL=-5) + + INTEGER :: IPQ_BADINSTANCE + PARAMETER (IPQ_BADINSTANCE=-6) + +C +C function prototypes +C + + INTEGER(KIND=4) AccumulateLine + INTEGER(KIND=4) AddError + INTEGER(KIND=4) AddWarning + INTEGER(KIND=4) ClearAccumulatedLines + INTEGER(KIND=4) CreateIPhreeqc + INTEGER(KIND=4) DestroyIPhreeqc + INTEGER(KIND=4) GetComponentCount + LOGICAL(KIND=4) GetDumpFileOn + INTEGER(KIND=4) GetDumpStringLineCount + LOGICAL(KIND=4) GetDumpStringOn + LOGICAL(KIND=4) GetErrorFileOn + INTEGER(KIND=4) GetErrorStringLine + INTEGER(KIND=4) GetErrorStringLineCount + LOGICAL(KIND=4) GetLogFileOn + LOGICAL(KIND=4) GetLogStringLineCount + LOGICAL(KIND=4) GetLogStringOn + LOGICAL(KIND=4) GetOutputFileOn + INTEGER(KIND=4) GetOutputStringLineCount + LOGICAL(KIND=4) GetOutputStringOn + INTEGER(KIND=4) GetSelectedOutputColumnCount + LOGICAL(KIND=4) GetSelectedOutputFileOn + INTEGER(KIND=4) GetSelectedOutputRowCount + INTEGER(KIND=4) GetSelectedOutputValue + INTEGER(KIND=4) GetWarningStringLine + INTEGER(KIND=4) GetWarningStringLineCount + INTEGER(KIND=4) LoadDatabase + INTEGER(KIND=4) LoadDatabaseString + INTEGER(KIND=4) RunAccumulated + INTEGER(KIND=4) RunFile + INTEGER(KIND=4) RunString + INTEGER(KIND=4) SetDumpFileName + INTEGER(KIND=4) SetDumpFileOn + INTEGER(KIND=4) SetDumpStringOn + INTEGER(KIND=4) SetErrorFileOn + INTEGER(KIND=4) SetLogFileName + INTEGER(KIND=4) SetLogFileOn + INTEGER(KIND=4) SetLogStringOn + INTEGER(KIND=4) SetOutputFileName + INTEGER(KIND=4) SetOutputFileOn + INTEGER(KIND=4) SetOutputStringOn + INTEGER(KIND=4) SetSelectedOutputFileOn diff --git a/IPhreeqc.f90.inc b/IPhreeqc.f90.inc new file mode 100644 index 00000000..566e33bd --- /dev/null +++ b/IPhreeqc.f90.inc @@ -0,0 +1,448 @@ + ! GetSelectedOutputValue TYPES + INTEGER(KIND=4),PARAMETER :: TT_EMPTY = 0 + INTEGER(KIND=4),PARAMETER :: TT_ERROR = 1 + INTEGER(KIND=4),PARAMETER :: TT_DOUBLE = 3 + INTEGER(KIND=4),PARAMETER :: TT_STRING = 4 + + + ! ERROR RETURN TYPES + INTEGER(KIND=4),PARAMETER :: IPQ_OK = 0 + INTEGER(KIND=4),PARAMETER :: IPQ_OUTOFMEMORY = -1 + INTEGER(KIND=4),PARAMETER :: IPQ_BADVARTYPE = -2 + INTEGER(KIND=4),PARAMETER :: IPQ_INVALIDARG = -3 + INTEGER(KIND=4),PARAMETER :: IPQ_INVALIDROW = -4 + INTEGER(KIND=4),PARAMETER :: IPQ_INVALIDCOL = -5 + INTEGER(KIND=4),PARAMETER :: IPQ_BADINSTANCE = -6 + + + INTERFACE + FUNCTION AccumulateLine(ID,LINE) + INTEGER(KIND=4), INTENT(IN) :: ID + CHARACTER(LEN=*), INTENT(IN) :: LINE + INTEGER(KIND=4) :: AccumulateLine + END FUNCTION AccumulateLine + END INTERFACE + + + INTERFACE + FUNCTION AddError(ID,ERROR_MSG) + INTEGER(KIND=4), INTENT(IN) :: ID + CHARACTER(LEN=*), INTENT(IN) :: ERROR_MSG + INTEGER(KIND=4) :: AddError + END FUNCTION AddError + END INTERFACE + + + INTERFACE + FUNCTION AddWarning(ID,WARN_MSG) + INTEGER(KIND=4), INTENT(IN) :: ID + CHARACTER(LEN=*), INTENT(IN) :: WARN_MSG + INTEGER(KIND=4) :: AddWarning + END FUNCTION AddWarning + END INTERFACE + + + INTERFACE + FUNCTION ClearAccumulatedLines(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + INTEGER(KIND=4) :: ClearAccumulatedLines + END FUNCTION ClearAccumulatedLines + END INTERFACE + + + INTERFACE + FUNCTION CreateIPhreeqc() + INTEGER(KIND=4) :: CreateIPhreeqc + END FUNCTION CreateIPhreeqc + END INTERFACE + + + INTERFACE + FUNCTION DestroyIPhreeqc(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + INTEGER(KIND=4) :: DestroyIPhreeqc + END FUNCTION DestroyIPhreeqc + END INTERFACE + + + INTERFACE + SUBROUTINE GetComponent(ID,N,COMP) + INTEGER(KIND=4), INTENT(IN) :: ID + INTEGER(KIND=4), INTENT(IN) :: N + CHARACTER(LEN=*), INTENT(OUT) :: COMP + END SUBROUTINE GetComponent + END INTERFACE + + + INTERFACE + FUNCTION GetComponentCount(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + INTEGER(KIND=4) :: GetComponentCount + END FUNCTION GetComponentCount + END INTERFACE + + + INTERFACE + SUBROUTINE GetDumpFileName(ID,FNAME) + INTEGER(KIND=4), INTENT(IN) :: ID + CHARACTER(LEN=*), INTENT(OUT) :: FNAME + END SUBROUTINE GetDumpFileName + END INTERFACE + + + INTERFACE + FUNCTION GetDumpFileOn(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + LOGICAL(KIND=4) :: GetDumpFileOn + END FUNCTION GetDumpFileOn + END INTERFACE + + + INTERFACE + SUBROUTINE GetDumpStringLine(ID,N,LINE) + INTEGER(KIND=4), INTENT(IN) :: ID + INTEGER(KIND=4), INTENT(IN) :: N + CHARACTER(LEN=*), INTENT(OUT) :: LINE + END SUBROUTINE + END INTERFACE + + + INTERFACE + FUNCTION GetDumpStringLineCount(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + INTEGER(KIND=4) :: GetDumpStringLineCount + END FUNCTION GetDumpStringLineCount + END INTERFACE + + + INTERFACE + FUNCTION GetDumpStringOn(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + LOGICAL(KIND=4) :: GetDumpStringOn + END FUNCTION GetDumpStringOn + END INTERFACE + + + INTERFACE + FUNCTION GetErrorFileOn(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + LOGICAL(KIND=4) :: GetErrorFileOn + END FUNCTION GetErrorFileOn + END INTERFACE + + + INTERFACE + SUBROUTINE GetErrorStringLine(ID,N,LINE) + INTEGER(KIND=4), INTENT(IN) :: ID + INTEGER(KIND=4), INTENT(IN) :: N + CHARACTER(LEN=*), INTENT(OUT) :: LINE + END SUBROUTINE + END INTERFACE + + + INTERFACE + FUNCTION GetErrorStringLineCount(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + INTEGER(KIND=4) :: GetErrorStringLineCount + END FUNCTION GetErrorStringLineCount + END INTERFACE + + + INTERFACE + SUBROUTINE GetLogFileName(ID,FNAME) + INTEGER(KIND=4), INTENT(IN) :: ID + CHARACTER(LEN=*), INTENT(OUT) :: FNAME + END SUBROUTINE GetLogFileName + END INTERFACE + + + INTERFACE + FUNCTION GetLogFileOn(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + LOGICAL(KIND=4) :: GetLogFileOn + END FUNCTION GetLogFileOn + END INTERFACE + + + INTERFACE + SUBROUTINE GetLogStringLine(ID,N,LINE) + INTEGER(KIND=4), INTENT(IN) :: ID + INTEGER(KIND=4), INTENT(IN) :: N + CHARACTER(LEN=*), INTENT(OUT) :: LINE + END SUBROUTINE + END INTERFACE + + + INTERFACE + FUNCTION GetLogStringLineCount(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + INTEGER(KIND=4) :: GetLogStringLineCount + END FUNCTION GetLogStringLineCount + END INTERFACE + + + INTERFACE + FUNCTION GetLogStringOn(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + LOGICAL(KIND=4) :: GetLogStringOn + END FUNCTION GetLogStringOn + END INTERFACE + + + INTERFACE + SUBROUTINE GetOutputFileName(ID,FNAME) + INTEGER(KIND=4), INTENT(IN) :: ID + CHARACTER(LEN=*), INTENT(OUT) :: FNAME + END SUBROUTINE GetOutputFileName + END INTERFACE + + + INTERFACE + FUNCTION GetOutputFileOn(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + LOGICAL(KIND=4) :: GetOutputFileOn + END FUNCTION GetOutputFileOn + END INTERFACE + + + INTERFACE + SUBROUTINE GetOutputStringLine(ID,N,LINE) + INTEGER(KIND=4), INTENT(IN) :: ID + INTEGER(KIND=4), INTENT(IN) :: N + CHARACTER(LEN=*), INTENT(OUT) :: LINE + END SUBROUTINE + END INTERFACE + + + INTERFACE + FUNCTION GetOutputStringLineCount(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + INTEGER(KIND=4) :: GetOutputStringLineCount + END FUNCTION GetOutputStringLineCount + END INTERFACE + + + INTERFACE + FUNCTION GetOutputStringOn(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + LOGICAL(KIND=4) :: GetOutputStringOn + END FUNCTION GetOutputStringOn + END INTERFACE + + + INTERFACE + FUNCTION GetSelectedOutputColumnCount(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + INTEGER(KIND=4) :: GetSelectedOutputColumnCount + END FUNCTION GetSelectedOutputColumnCount + END INTERFACE + + + INTERFACE + FUNCTION GetSelectedOutputFileOn(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + LOGICAL(KIND=4) :: GetSelectedOutputFileOn + END FUNCTION GetSelectedOutputFileOn + END INTERFACE + + + INTERFACE + FUNCTION GetSelectedOutputRowCount(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + INTEGER(KIND=4) :: GetSelectedOutputRowCount + END FUNCTION GetSelectedOutputRowCount + END INTERFACE + + + INTERFACE + FUNCTION GetSelectedOutputValue(ID,ROW,COL,VTYPE,DVALUE,SVALUE) + INTEGER(KIND=4), INTENT(IN) :: ID + INTEGER(KIND=4), INTENT(IN) :: ROW + INTEGER(KIND=4), INTENT(IN) :: COL + INTEGER(KIND=4), INTENT(OUT) :: VTYPE + REAL(KIND=8), INTENT(OUT) :: DVALUE + CHARACTER(LEN=*), INTENT(OUT) :: SVALUE + INTEGER(KIND=4) :: GetSelectedOutputValue + END FUNCTION GetSelectedOutputValue + END INTERFACE + + + INTERFACE + SUBROUTINE GetWarningStringLine(ID,N,LINE) + INTEGER(KIND=4), INTENT(IN) :: ID + INTEGER(KIND=4), INTENT(IN) :: N + CHARACTER(LEN=*), INTENT(OUT) :: LINE + END SUBROUTINE + END INTERFACE + + + INTERFACE + FUNCTION GetWarningStringLineCount(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + INTEGER(KIND=4) :: GetWarningStringLineCount + END FUNCTION GetWarningStringLineCount + END INTERFACE + + + INTERFACE + FUNCTION LoadDatabase(ID,FILENAME) + INTEGER(KIND=4), INTENT(IN) :: ID + CHARACTER(LEN=*), INTENT(IN) :: FILENAME + INTEGER(KIND=4) :: LoadDatabase + END FUNCTION LoadDatabase + END INTERFACE + + + INTERFACE + FUNCTION LoadDatabaseString(ID,INPUT) + INTEGER(KIND=4), INTENT(IN) :: ID + CHARACTER(LEN=*), INTENT(IN) :: INPUT + INTEGER(KIND=4) :: LoadDatabaseString + END FUNCTION LoadDatabaseString + END INTERFACE + + + INTERFACE + SUBROUTINE OutputAccumulatedLines(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + END SUBROUTINE OutputAccumulatedLines + END INTERFACE + + + INTERFACE + SUBROUTINE OutputErrorString(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + END SUBROUTINE OutputErrorString + END INTERFACE + + + INTERFACE + SUBROUTINE OutputWarningString(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + END SUBROUTINE OutputWarningString + END INTERFACE + + + INTERFACE + FUNCTION RunAccumulated(ID) + INTEGER(KIND=4), INTENT(IN) :: ID + INTEGER(KIND=4) :: RunAccumulated + END FUNCTION RunAccumulated + END INTERFACE + + + INTERFACE + FUNCTION RunFile(ID,FNAME) + INTEGER(KIND=4), INTENT(IN) :: ID + CHARACTER(LEN=*), INTENT(IN) :: FNAME + INTEGER(KIND=4) :: RunFile + END FUNCTION RunFile + END INTERFACE + + + INTERFACE + FUNCTION RunString(ID,INPUT) + INTEGER(KIND=4), INTENT(IN) :: ID + CHARACTER(LEN=*), INTENT(IN) :: INPUT + INTEGER(KIND=4) :: RunString + END FUNCTION RunString + END INTERFACE + + + INTERFACE + FUNCTION SetDumpFileName(ID,FNAME) + INTEGER(KIND=4), INTENT(IN) :: ID + CHARACTER(LEN=*), INTENT(IN) :: FNAME + INTEGER(KIND=4) :: SetDumpFileName + END FUNCTION SetDumpFileName + END INTERFACE + + + INTERFACE + FUNCTION SetDumpFileOn(ID,DUMP_ON) + INTEGER(KIND=4), INTENT(IN) :: ID + LOGICAL(KIND=4), INTENT(IN) :: DUMP_ON + INTEGER(KIND=4) :: SetDumpFileOn + END FUNCTION SetDumpFileOn + END INTERFACE + + + INTERFACE + FUNCTION SetDumpStringOn(ID,DUMP_STRING_ON) + INTEGER(KIND=4), INTENT(IN) :: ID + LOGICAL(KIND=4), INTENT(IN) :: DUMP_STRING_ON + INTEGER(KIND=4) :: SetDumpStringOn + END FUNCTION SetDumpStringOn + END INTERFACE + + + INTERFACE + FUNCTION SetErrorFileOn(ID,ERR_ON) + INTEGER(KIND=4), INTENT(IN) :: ID + LOGICAL(KIND=4), INTENT(IN) :: ERR_ON + INTEGER(KIND=4) :: SetErrorFileOn + END FUNCTION SetErrorFileOn + END INTERFACE + + + INTERFACE + FUNCTION SetLogFileName(ID,FNAME) + INTEGER(KIND=4), INTENT(IN) :: ID + CHARACTER(LEN=*), INTENT(IN) :: FNAME + INTEGER(KIND=4) :: SetLogFileName + END FUNCTION SetLogFileName + END INTERFACE + + + INTERFACE + FUNCTION SetLogFileOn(ID,LOG_ON) + INTEGER(KIND=4), INTENT(IN) :: ID + LOGICAL(KIND=4), INTENT(IN) :: LOG_ON + INTEGER(KIND=4) :: SetLogFileOn + END FUNCTION SetLogFileOn + END INTERFACE + + + INTERFACE + FUNCTION SetLogStringOn(ID,LOG_STRING_ON) + INTEGER(KIND=4), INTENT(IN) :: ID + LOGICAL(KIND=4), INTENT(IN) :: LOG_STRING_ON + INTEGER(KIND=4) :: SetLogStringOn + END FUNCTION SetLogStringOn + END INTERFACE + + + INTERFACE + FUNCTION SetOutputFileName(ID,FNAME) + INTEGER(KIND=4), INTENT(IN) :: ID + CHARACTER(LEN=*), INTENT(IN) :: FNAME + INTEGER(KIND=4) :: SetOutputFileName + END FUNCTION SetOutputFileName + END INTERFACE + + + INTERFACE + FUNCTION SetOutputFileOn(ID,OUT_ON) + INTEGER(KIND=4), INTENT(IN) :: ID + LOGICAL(KIND=4), INTENT(IN) :: OUT_ON + INTEGER(KIND=4) :: SetOutputFileOn + END FUNCTION SetOutputFileOn + END INTERFACE + + + INTERFACE + FUNCTION SetOutputStringOn(ID,OUT_STRING_ON) + INTEGER(KIND=4), INTENT(IN) :: ID + LOGICAL(KIND=4), INTENT(IN) :: OUT_STRING_ON + INTEGER(KIND=4) :: SetOutputStringOn + END FUNCTION SetOutputStringOn + END INTERFACE + + + INTERFACE + FUNCTION SetSelectedOutputFileOn(ID,SEL_ON) + INTEGER(KIND=4), INTENT(IN) :: ID + LOGICAL(KIND=4), INTENT(IN) :: SEL_ON + INTEGER(KIND=4) :: SetSelectedOutputFileOn + END FUNCTION SetSelectedOutputFileOn + END INTERFACE diff --git a/IPhreeqc.h b/IPhreeqc.h new file mode 100644 index 00000000..98bdd1e9 --- /dev/null +++ b/IPhreeqc.h @@ -0,0 +1,1504 @@ +/*! @file IPhreeqc.h + @brief C/Fortran Documentation +*/ +#ifndef INC_IPHREEQC_H +#define INC_IPHREEQC_H + +#include "Var.h" + +/** + * @mainpage IPhreeqc Library Documentation + * + * @htmlonly + * + * + * + * + *
IPhreeqc.h C/Fortran Documentation
IPhreeqc.hpp C++ Documentation
Var.hIPhreeqc VARIANT Documentation
+ * @endhtmlonly + */ + +/*! \brief Enumeration used to return error codes. +*/ +typedef enum { + IPQ_OK = 0, /*!< Success */ + IPQ_OUTOFMEMORY = -1, /*!< Failure, Out of memory */ + IPQ_BADVARTYPE = -2, /*!< Failure, Invalid VAR type */ + IPQ_INVALIDARG = -3, /*!< Failure, Invalid argument */ + IPQ_INVALIDROW = -4, /*!< Failure, Invalid row */ + IPQ_INVALIDCOL = -5, /*!< Failure, Invalid column */ + IPQ_BADINSTANCE = -6 /*!< Failure, Invalid instance id */ +} IPQ_RESULT; + + +#if defined(__cplusplus) +extern "C" { +#endif + +/** + * Accumlulate line(s) for input to phreeqc. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @param line The line(s) to add for input to phreeqc. + * @retval IPQ_OK Success + * @retval IPQ_OUTOFMEMORY Out of memory + * @see ClearAccumulatedLines, OutputAccumulatedLines, RunAccumulated + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION AccumulateLine(ID,LINE)
+ *    INTEGER(KIND=4),   INTENT(IN)  :: ID
+ *    CHARACTER(LEN=*),  INTENT(IN)  :: LINE
+ *    INTEGER(KIND=4)                :: AccumulateLine
+ *  END FUNCTION AccumulateLine
+ *  
+ *
+ * @endhtmlonly + * + * @par C Example: + * \include AccumulateLine.c + * + * @par Fortran90 Example: + * see \ref GetDumpStringLine_f90 "GetDumpStringLine" + */ + IPQ_DLL_EXPORT IPQ_RESULT AccumulateLine(int id, const char *line); + + +/** + * Appends the given error message and increments the error count. + * Internally used to create an error condition. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @param error_msg The error message to display. + * @returns The current error count if successful; otherwise a negative value indicates an error occured (see \ref IPQ_RESULT). + * @see GetErrorString, GetErrorStringLine, GetErrorStringLineCount, OutputErrorString + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION AddError(ID,ERROR_MSG)
+ *    INTEGER(KIND=4),  INTENT(IN) :: ID
+ *    CHARACTER(LEN=*), INTENT(IN) :: ERROR_MSG
+ *    INTEGER(KIND=4)              :: AddError
+ *  END FUNCTION AddError
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT int AddError(int id, const char* error_msg); + + +/** + * Appends the given warning message and increments the warning count. + * Internally used to create a warning condition. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @param warn_msg The warning message to display. + * @returns The current warning count if successful; otherwise a negative value indicates an error occured (see \ref IPQ_RESULT). + * @see GetWarningString, GetWarningStringLine, GetWarningStringLineCount, OutputWarningString + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION AddWarning(ID,WARN_MSG)
+ *    INTEGER(KIND=4),  INTENT(IN) :: ID
+ *    CHARACTER(LEN=*), INTENT(IN) :: WARN_MSG
+ *    INTEGER(KIND=4)              :: AddWarning
+ *  END FUNCTION AddWarning
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT int AddWarning(int id, const char* warn_msg); + + + +/** + * Clears the accumulated input buffer. Input buffer is accumulated from calls to \ref AccumulateLine. + * @retval IPQ_OK Success. + * @retval IPQ_BADINSTANCE The given id is invalid. + * @see AccumulateLine, OutputAccumulatedLines, RunAccumulated + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION ClearAccumulatedLines(ID)
+ *    INTEGER(KIND=4), INTENT(IN) :: ID
+ *    INTEGER(KIND=4)             :: ClearAccumulatedLines
+ *  END FUNCTION ClearAccumulatedLines
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT IPQ_RESULT ClearAccumulatedLines(int id); + + +/** + * 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 + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION CreateIPhreeqc()
+ *    INTEGER(KIND=4)  :: CreateIPhreeqc
+ *  END FUNCTION CreateIPhreeqc
+ *  
+ *
+ * @endhtmlonly + * + * \anchor CreateIPhreeqc_c + * @par C Example: + * \include CreateIPhreeqc.c + * + * \anchor CreateIPhreeqc_f90 + * @par Fortran90 Example: + * \include F90CreateIPhreeqc.f90 + */ + IPQ_DLL_EXPORT int CreateIPhreeqc(void); + + +/** + * Release an IPhreeqc instance from memory. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @retval IPQ_OK Success + * @retval IPQ_BADINSTANCE The given id is invalid. + * @see CreateIPhreeqc + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION DestroyIPhreeqc(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    INTEGER(KIND=4)               :: DestroyIPhreeqc
+ *  END FUNCTION DestroyIPhreeqc
+ *  
+ *
+ * @endhtmlonly + * + * @par C Example: + * see \ref CreateIPhreeqc_c "CreateIPhreeqc" + * + * @par Fortran90 Example: + * see \ref CreateIPhreeqc_f90 "CreateIPhreeqc" + */ + IPQ_DLL_EXPORT IPQ_RESULT DestroyIPhreeqc(int id); + + +/** + * Retrieves the given component. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @param n The zero-based index of the component to retrieve. + * @return A null terminated string containing the given component. + * Returns an empty string if n is out of range. + * @see GetComponentCount + * @par Fortran90 Interface: + * (Note: N is one-based for the Fortran interface) + * @htmlonly + * + *
+ *  SUBROUTINE GetComponent(ID,N,COMP)
+ *    INTEGER(KIND=4),   INTENT(IN)   :: ID
+ *    INTEGER(KIND=4),   INTENT(IN)   :: N
+ *    CHARACTER(LEN=*),  INTENT(OUT)  :: COMP
+ *  END SUBROUTINE GetComponent
+ *  
+ *
+ * @endhtmlonly + * + * \anchor GetComponent_c + * @par C Example: + * \include GetComponent.c + * + * \anchor GetComponent_f90 + * @par Fortran90 Example: + * \include F90GetComponent.f90 + */ + IPQ_DLL_EXPORT const char* GetComponent(int id, int n); + + +/** + * 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). + * @see GetComponent + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION GetComponentCount(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    INTEGER(KIND=4)               :: GetComponentCount
+ *  END FUNCTION GetComponentCount
+ *  
+ *
+ * @endhtmlonly + * + * @par C Example: + * see \ref GetComponent_c "GetComponent" + * + * @par Fortran90 Example: + * see \ref GetComponent_f90 "GetComponent" + */ + IPQ_DLL_EXPORT int GetComponentCount(int id); + + +/** + * Retrieves the name of the dump file. This file name is used if not specified within DUMP input. + * The default value is dump.id.out. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @return filename The name of the file to write DUMP output to. + * @see GetDumpFileOn, GetDumpString, GetDumpStringOn, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileName, SetDumpFileOn, SetDumpStringOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  SUBROUTINE GetDumpFileName(ID,FILENAME)
+ *    INTEGER(KIND=4),   INTENT(IN)   :: ID
+ *    CHARACTER(LEN=*),  INTENT(OUT)  :: FILENAME
+ *  END SUBROUTINE GetDumpFileName
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT const char* GetDumpFileName(int id); + + +/** + * 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.id.out if unspecified) file, 0 (zero) otherwise. + * @see GetDumpString, GetDumpStringLine, GetDumpStringLineCount, GetDumpStringOn, SetDumpFileOn, SetDumpStringOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION GetDumpFileOn(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    LOGICAL(KIND=4)               :: GetDumpFileOn
+ *  END FUNCTION GetDumpFileOn
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT int GetDumpFileOn(int id); + + +/** + * 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 GetDumpFileOn, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileOn, GetDumpStringOn, SetDumpStringOn + * @par Fortran90 Interface: + * Not implemented. (see \ref GetDumpStringLineCount, \ref GetDumpStringLine) + * + * \anchor GetDumpString_c + * @par C Example: + * \include GetDumpString.c + */ + IPQ_DLL_EXPORT const char* GetDumpString(int id); + + +/** + * Retrieves the given dump 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 line. + * Returns an empty string if n is out of range. + * @pre \ref SetDumpStringOn must have been set to true (non-zero). + * @see GetDumpFileOn, GetDumpString, GetDumpStringLineCount, GetDumpStringOn, SetDumpFileOn, SetDumpStringOn + * @par Fortran90 Interface: + * @htmlonly + * (Note: N is one-based for the Fortran interface.) + * + *
+ *  SUBROUTINE GetDumpStringLine(ID,N,LINE)
+ *    INTEGER(KIND=4),   INTENT(IN)   :: ID
+ *    INTEGER(KIND=4),   INTENT(IN)   :: N
+ *    CHARACTER(LEN=*),  INTENT(OUT)  :: LINE
+ *  END SUBROUTINE GetDumpStringLine
+ *  
+ *
+ * @endhtmlonly + * + * \anchor GetDumpStringLine_f90 + * @par Fortran90 Example: + * \include F90GetDumpStringLine.f90 + */ + IPQ_DLL_EXPORT const char* GetDumpStringLine(int id, int n); + + +/** + * 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. + * @pre \ref SetDumpStringOn must have been set to true (non-zero). + * @see GetDumpFileOn, GetDumpString, GetDumpStringLine, GetDumpStringOn, SetDumpFileOn, SetDumpStringOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION GetDumpStringLineCount(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    INTEGER(KIND=4)               :: GetDumpStringLineCount
+ *  END FUNCTION GetDumpStringLineCount
+ *  
+ *
+ * @endhtmlonly + * + * @par Fortran90 Example: + * see \ref GetDumpStringLine_f90 "GetDumpStringLine" + */ + IPQ_DLL_EXPORT int GetDumpStringLineCount(int id); + + +/** + * 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 GetDumpFileOn, GetDumpString, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileOn, SetDumpStringOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION GetDumpStringOn(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    LOGICAL(KIND=4)               :: GetDumpStringOn
+ *  END FUNCTION GetDumpStringOn
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT int GetDumpStringOn(int id); + + +/** + * 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.id.err file, 0 (zero) otherwise. + * @see SetErrorFileOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION GetErrorFileOn(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    LOGICAL(KIND=4)               :: GetErrorFileOn
+ *  END FUNCTION GetErrorFileOn
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT int GetErrorFileOn(int id); + + +/** + * 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) + */ + IPQ_DLL_EXPORT const char* GetErrorString(int id); + + +/** + * 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 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 + * + *
+ *  SUBROUTINE GetErrorStringLine(ID,N,LINE)
+ *    INTEGER(KIND=4),   INTENT(IN)   :: ID
+ *    INTEGER(KIND=4),   INTENT(IN)   :: N
+ *    CHARACTER(LEN=*),  INTENT(OUT)  :: LINE
+ *  END SUBROUTINE GetErrorStringLine
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT const char* GetErrorStringLine(int id, int n); + + +/** + * 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 GetErrorFileOn, GetErrorString, GetErrorStringLine, OutputErrorString, SetErrorFileOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION GetErrorStringLineCount(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    INTEGER(KIND=4)               :: GetErrorStringLineCount
+ *  END FUNCTION GetErrorStringLineCount
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT int GetErrorStringLineCount(int id); + +/** + * Retrieves the name of the log file. The default name is phreeqc.id.log. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @return filename The name of the log file. + * @see GetLogFileOn, GetLogString, GetLogStringOn, GetLogStringLine, GetLogStringLineCount, SetLogFileName, SetLogFileOn, SetLogStringOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  SUBROUTINE GetLogFileName(ID,FILENAME)
+ *    INTEGER(KIND=4),   INTENT(IN)   :: ID
+ *    CHARACTER(LEN=*),  INTENT(OUT)  :: FILENAME
+ *  END SUBROUTINE GetLogFileName
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT const char* GetLogFileName(int id); + + +/** + * Retrieves the current value of the log file switch. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @return Non-zero if log messages are written to the phreeqc.id.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 + * + *
+ *  FUNCTION GetLogFileOn(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    LOGICAL(KIND=4)               :: GetLogFileOn
+ *  END FUNCTION GetLogFileOn
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT int GetLogFileOn(int id); + + +/** + * Retrieves the string buffer containing log output. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @return A null terminated string containing log output. + * @remarks Logging must be enabled through the use of the KNOBS -logfile option in order to receive any log messages. + * @pre \ref SetLogStringOn must have been set to true (non-zero) in order to recieve log output. + * @see GetLogFileOn, GetLogStringLine, GetLogStringLineCount, SetLogFileOn, GetLogStringOn, SetLogStringOn + * @par Fortran90 Interface: + * Not implemented. (see \ref GetLogStringLineCount, \ref GetLogStringLine) + * + * \anchor GetOutputString_c + * @par C Example: + * \include GetOutputString.c + */ + IPQ_DLL_EXPORT const char* GetLogString(int id); + + +/** + * Retrieves the given log 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 line. + * Returns an empty string if n is out of range. + * @pre \ref SetLogStringOn must have been set to true (non-zero). + * @see GetLogFileOn, GetLogString, GetLogStringLineCount, GetLogStringOn, SetLogFileOn, SetLogStringOn + * @par Fortran90 Interface: + * @htmlonly + * (Note: N is one-based for the Fortran interface.) + * + *
+ *  SUBROUTINE GetLogStringLine(ID,N,LINE)
+ *    INTEGER(KIND=4),   INTENT(IN)   :: ID
+ *    INTEGER(KIND=4),   INTENT(IN)   :: N
+ *    CHARACTER(LEN=*),  INTENT(OUT)  :: LINE
+ *  END SUBROUTINE GetLogStringLine
+ *  
+ *
+ * @endhtmlonly + * + * \anchor GetLogStringLine_f90 + * @par Fortran90 Example: + * \include F90GetLogStringLine.f90 + */ + IPQ_DLL_EXPORT const char* GetLogStringLine(int id, int n); + +/** + * Retrieves the number of lines in the current log string buffer. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @return The number of lines. + * @pre \ref SetLogStringOn must have been set to true (non-zero). + * @see GetLogFileOn, GetLogString, GetLogStringLine, GetLogStringOn, SetLogFileOn, SetLogStringOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION GetLogStringLineCount(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    INTEGER(KIND=4)               :: GetLogStringLineCount
+ *  END FUNCTION GetLogStringLineCount
+ *  
+ *
+ * @endhtmlonly + * + * @par Fortran90 Example: + * see \ref GetLogStringLine_f90 "GetLogStringLine" + */ + IPQ_DLL_EXPORT int GetLogStringLineCount(int id); + + +/** + * Retrieves the current value of the log string switch. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @return Non-zero if output is stored, 0 (zero) otherwise. + * @see GetLogFileOn, GetLogString, GetLogStringLine, GetLogStringLineCount, SetLogFileOn, SetLogStringOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION GetLogStringOn(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    LOGICAL(KIND=4)               :: GetLogStringOn
+ *  END FUNCTION GetLogStringOn
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT int GetLogStringOn(int id); + + +/** + * Retrieves the name of the output file. The default name is phreeqc.id.out. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @return filename The name of the output file. + * @see GetOutputFileOn, GetOutputString, GetOutputStringOn, GetOutputStringLine, GetOutputStringLineCount, SetOutputFileName, SetOutputFileOn, SetOutputStringOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  SUBROUTINE GetOutputFileName(ID,FILENAME)
+ *    INTEGER(KIND=4),   INTENT(IN)   :: ID
+ *    CHARACTER(LEN=*),  INTENT(OUT)  :: FILENAME
+ *  END SUBROUTINE GetOutputFileName
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT const char* GetOutputFileName(int id); + + +/** + * 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.id.out file, 0 (zero) otherwise. + * @see SetOutputFileOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION GetOutputFileOn(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    LOGICAL(KIND=4)               :: GetOutputFileOn
+ *  END FUNCTION GetOutputFileOn
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT int GetOutputFileOn(int id); + +/** + * Retrieves the string buffer containing phreeqc output. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @return A null terminated string containing phreeqc output. + * @pre \ref SetOutputStringOn must have been set to true (non-zero) in order to recieve phreeqc output. + * @see GetOutputFileOn, GetOutputStringLine, GetOutputStringLineCount, SetOutputFileOn, GetOutputStringOn, SetOutputStringOn + * @par Fortran90 Interface: + * Not implemented. (see \ref GetOutputStringLineCount, \ref GetOutputStringLine) + * + * \anchor GetOutputString_c + * @par C Example: + * \include GetOutputString.c + */ + IPQ_DLL_EXPORT const char* GetOutputString(int id); + +/** + * Retrieves the given output 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 line. + * Returns an empty string if n is out of range. + * @pre \ref SetOutputStringOn must have been set to true (non-zero). + * @see GetOutputFileOn, GetOutputString, GetOutputStringLineCount, GetOutputStringOn, SetOutputFileOn, SetOutputStringOn + * @par Fortran90 Interface: + * @htmlonly + * (Note: N is one-based for the Fortran interface.) + * + *
+ *  SUBROUTINE GetOutputStringLine(ID,N,LINE)
+ *    INTEGER(KIND=4),   INTENT(IN)   :: ID
+ *    INTEGER(KIND=4),   INTENT(IN)   :: N
+ *    CHARACTER(LEN=*),  INTENT(OUT)  :: LINE
+ *  END SUBROUTINE GetOutputStringLine
+ *  
+ *
+ * @endhtmlonly + * + * \anchor GetOutputStringLine_f90 + * @par Fortran90 Example: + * \include F90GetOutputStringLine.f90 + */ + IPQ_DLL_EXPORT const char* GetOutputStringLine(int id, int n); + +/** + * Retrieves the number of lines in the current output string buffer. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @return The number of lines. + * @pre \ref SetOutputStringOn must have been set to true (non-zero). + * @see GetOutputFileOn, GetOutputString, GetOutputStringLine, GetOutputStringOn, SetOutputFileOn, SetOutputStringOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION GetOutputStringLineCount(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    INTEGER(KIND=4)               :: GetOutputStringLineCount
+ *  END FUNCTION GetOutputStringLineCount
+ *  
+ *
+ * @endhtmlonly + * + * @par Fortran90 Example: + * see \ref GetOutputStringLine_f90 "GetOutputStringLine" + */ + IPQ_DLL_EXPORT int GetOutputStringLineCount(int id); + +/** + * Retrieves the current value of the output string switch. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @return Non-zero if output is stored, 0 (zero) otherwise. + * @see GetOutputFileOn, GetOutputString, GetOutputStringLine, GetOutputStringLineCount, SetOutputFileOn, SetOutputStringOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION GetOutputStringOn(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    LOGICAL(KIND=4)               :: GetOutputStringOn
+ *  END FUNCTION GetOutputStringOn
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT int GetOutputStringOn(int id); + + +/** + * 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 GetSelectedOutputFileOn, GetSelectedOutputRowCount, GetSelectedOutputValue, SetSelectedOutputFileOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION GetSelectedOutputColumnCount(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    INTEGER(KIND=4)               :: GetSelectedOutputColumnCount
+ *  END FUNCTION GetSelectedOutputColumnCount
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT int GetSelectedOutputColumnCount(int id); + + +/** + * 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.id.out if unspecified) file, 0 (zero) otherwise. + * @see GetSelectedOutputColumnCount, GetSelectedOutputRowCount, GetSelectedOutputValue, SetSelectedOutputFileOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION GetSelectedOutputFileOn(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    LOGICAL(KIND=4)               :: GetSelectedOutputFileOn
+ *  END FUNCTION GetSelectedOutputFileOn
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT int GetSelectedOutputFileOn(int id); + + +/** + * 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 GetSelectedOutputFileOn, GetSelectedOutputColumnCount, GetSelectedOutputValue, SetSelectedOutputFileOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION GetSelectedOutputRowCount(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    INTEGER(KIND=4)               :: GetSelectedOutputRowCount
+ *  END FUNCTION GetSelectedOutputRowCount
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT int GetSelectedOutputRowCount(int id); + + +/** + * 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. + * @see GetSelectedOutputFileOn, GetSelectedOutputColumnCount, GetSelectedOutputRowCount, SetSelectedOutputFileOn + * @remarks + * Row 0 contains the column headings to the selected_ouput. + * @par Examples: + * The headings will include a suffix and/or prefix in order to differentiate the + * columns. + * @htmlonly +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Input + +Headings +
+
+  SELECTED_OUTPUT
+    -reset false
+    -totals Ca Na
+
+
+
+  Ca(mol/kgw)  Na(mol/kgw)
+
+
+
+  SELECTED_OUTPUT
+    -reset false
+    -molalities Fe+2 Hfo_sOZn+
+
+
+
+  m_Fe+2(mol/kgw)  m_Hfo_sOZn+(mol/kgw)
+
+
+
+  SELECTED_OUTPUT
+    -reset false
+    -activities H+ Ca+2
+
+
+
+  la_H+  la_Ca+2
+
+
+
+  SELECTED_OUTPUT
+    -reset false
+    -equilibrium_phases Calcite Dolomite
+
+
+
+  Calcite  d_Calcite  Dolomite  d_Dolomite
+
+
+
+  SELECTED_OUTPUT
+    -reset false
+    -saturation_indices CO2(g) Siderite
+
+
+
+  si_CO2(g)  si_Siderite
+
+
+
+  SELECTED_OUTPUT
+    -reset false
+    -gases CO2(g) N2(g)
+
+
+
+  pressure "total mol" volume g_CO2(g) g_N2(g)
+
+
+
+  SELECTED_OUTPUT
+    -reset false
+    -kinetic_reactants CH2O Pyrite
+
+
+
+  k_CH2O dk_CH2O k_Pyrite dk_Pyrite
+
+
+
+  SELECTED_OUTPUT
+    -reset false
+    -solid_solutions CaSO4 SrSO4
+
+
+
+  s_CaSO4 s_SrSO4
+
+
+ * @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. + * @htmlonly + * + *

+ *  FUNCTION GetSelectedOutputValue(ID,ROW,COL,VTYPE,DVALUE,SVALUE)
+ *    INTEGER(KIND=4),   INTENT(IN)   :: ID
+ *    INTEGER(KIND=4),   INTENT(IN)   :: ROW
+ *    INTEGER(KIND=4),   INTENT(IN)   :: COL
+ *    INTEGER(KIND=4),   INTENT(OUT)  :: VTYPE
+ *    REAL(KIND=8),      INTENT(OUT)  :: DVALUE
+ *    CHARACTER(LEN=*),  INTENT(OUT)  :: SVALUE
+ *    INTEGER(KIND=4)                 :: GetSelectedOutputValue
+ *  END FUNCTION GetSelectedOutputValue
+ *  
+ * + * @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. + * \anchor GetSelectedOutputValue_c + * @par C Example: + * \include GetSelectedOutputValue.c + * + * \anchor F90GetSelectedOutputValue_f90 + * @par Fortran90 Example: + * \include F90GetSelectedOutputValue.f90 + */ + IPQ_DLL_EXPORT IPQ_RESULT GetSelectedOutputValue(int id, int row, int col, VAR* pVAR); + + +/** + * 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 GetWarningStringLine, GetWarningStringLineCount, OutputWarningString + * @par Fortran90 Interface: + * Not implemented. (see \ref GetWarningStringLineCount, \ref GetWarningStringLine, \ref OutputWarningString) + */ + IPQ_DLL_EXPORT const char* GetWarningString(int id); + + +/** + * 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 GetWarningString, GetWarningStringLineCount, OutputWarningString + * @par Fortran90 Interface: + * (Note: N is one-based for the Fortran interface.) + * @htmlonly + * + *
+ *  SUBROUTINE GetWarningStringLine(ID,N,LINE)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    LOGICAL(KIND=4),  INTENT(IN)  :: N
+ *    CHARACTER(LEN=*), INTENT(OUT) :: LINE
+ *  END SUBROUTINE GetWarningStringLine
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT const char* GetWarningStringLine(int id, int n); + + +/** + * 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 GetWarningString, GetWarningStringLine, OutputWarningString + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION GetWarningStringLineCount(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    INTEGER(KIND=4)               :: GetWarningStringLineCount
+ *  END FUNCTION GetWarningStringLineCount
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT int GetWarningStringLineCount(int id); + + +/** + * 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 (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 + * @remarks + * All previous definitions are cleared. + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION LoadDatabase(ID,FILENAME)
+ *    INTEGER(KIND=4),   INTENT(IN)  :: ID
+ *    CHARACTER(LEN=*),  INTENT(IN)  :: FILENAME
+ *    INTEGER(KIND=4)                :: LoadDatabase
+ *  END FUNCTION LoadDatabase
+ *  
+ *
+ * @endhtmlonly + * + * @par C Example: + * see \ref CreateIPhreeqc_c "CreateIPhreeqc" + * + * @par Fortran90 Example: + * see \ref CreateIPhreeqc_f90 "CreateIPhreeqc" + */ + IPQ_DLL_EXPORT int LoadDatabase(int id, const char* filename); + + +/** + * Load the specified string as a database into phreeqc. + * @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 + * @remarks + * All previous definitions are cleared. + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION LoadDatabaseString(ID,INPUT)
+ *    INTEGER(KIND=4),   INTENT(IN)  :: ID
+ *    CHARACTER(LEN=*),  INTENT(IN)  :: INPUT
+ *    INTEGER(KIND=4)                :: LoadDatabaseString
+ *  END FUNCTION LoadDatabaseString
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT int LoadDatabaseString(int id, const char* input); + + +/** + * Output the accumulated input buffer to stdout. This input buffer can be run with a call to \ref RunAccumulated. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @see AccumulateLine, ClearAccumulatedLines, RunAccumulated + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  SUBROUTINE OutputAccumulatedLines(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *  END SUBROUTINE OutputAccumulatedLines
+ *  
+ *
+ * @endhtmlonly + * + * @par Fortran90 Example: + * see \ref GetDumpStringLine_f90 "GetDumpStringLine" + */ + IPQ_DLL_EXPORT void OutputAccumulatedLines(int id); + + +/** + * Output the error messages normally stored in the phreeqc.id.err file to stdout. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @see GetErrorFileOn, GetErrorStringLine, GetErrorStringLineCount, SetErrorFileOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  SUBROUTINE OutputErrorString(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *  END SUBROUTINE OutputErrorString
+ *  
+ *
+ * @endhtmlonly + * + * @par C Example: + * see \ref GetComponent_c "GetComponent" + * + * @par Fortran90 Example: + * see \ref GetDumpStringLine_f90 "GetDumpStringLine" + */ + IPQ_DLL_EXPORT void OutputErrorString(int id); + + +/** + * Output the warning messages to stdout. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @see GetWarningString, GetWarningStringLine, GetWarningStringLineCount + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  SUBROUTINE OutputWarningString(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *  END SUBROUTINE OutputWarningString
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT void OutputWarningString(int id); + + +/** + * 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, ClearAccumulatedLines, OutputAccumulatedLines, RunFile, RunString + * @remarks + * 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 + * + *
+ *  FUNCTION RunAccumulated(ID)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    INTEGER(KIND=4)               :: RunAccumulated
+ *  END FUNCTION RunAccumulated
+ *  
+ *
+ * @endhtmlonly + * + * @par Fortran90 Example: + * see \ref GetDumpStringLine_f90 "GetDumpStringLine" + */ + IPQ_DLL_EXPORT int RunAccumulated(int id); + + +/** + * Runs the specified phreeqc input file. + * @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 + * + *
+ *  FUNCTION RunFile(ID,FNAME)
+ *    INTEGER(KIND=4),   INTENT(IN)  :: ID
+ *    CHARACTER(LEN=*),  INTENT(IN)  :: FNAME
+ *    INTEGER(KIND=4)                :: RunFile
+ *  END FUNCTION RunFile
+ *  
+ *
+ * @endhtmlonly + * + * @par C Example: + * see \ref CreateIPhreeqc_c "CreateIPhreeqc" + * + * @par Fortran90 Example: + * see \ref CreateIPhreeqc_f90 "CreateIPhreeqc" + */ + IPQ_DLL_EXPORT int RunFile(int id, const char* filename); + + +/** + * Runs the specified string as input to phreeqc. + * @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 + * + *
+ *  FUNCTION RunString(ID,INPUT)
+ *    INTEGER(KIND=4),  INTENT(IN)   :: ID
+ *    CHARACTER(LEN=*),  INTENT(IN)  :: INPUT
+ *    INTEGER(KIND=4)                :: RunString
+ *  END FUNCTION RunString
+ *  
+ *
+ * @endhtmlonly + * + * @par C Example: + * see \ref GetDumpString_c "GetDumpString" + * + */ + IPQ_DLL_EXPORT int RunString(int id, const char* input); + + +/** + * Sets the name of the dump file. This file name is used if not specified within DUMP input. + * The default value is dump.id.out. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @param filename The name of the file to write DUMP output to. + * @retval IPQ_OK Success. + * @retval IPQ_BADINSTANCE The given id is invalid. + * @see GetDumpFileName, GetDumpFileOn, GetDumpString, GetDumpStringOn, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileOn, SetDumpStringOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION SetDumpFileName(ID,FILENAME)
+ *    INTEGER(KIND=4),   INTENT(IN)   :: ID
+ *    CHARACTER(LEN=*),  INTENT(OUT)  :: FILENAME
+ *    INTEGER(KIND=4)                 :: SetDumpFileName
+ *  END FUNCTION SetDumpFileName
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT IPQ_RESULT SetDumpFileName(int id, const char* filename); + + +/** + * 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.id.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, GetDumpStringOn, GetDumpStringLineCount, SetDumpStringOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION SetDumpFileOn(ID,DUMP_ON)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    LOGICAL(KIND=4),  INTENT(IN)  :: DUMP_ON
+ *    INTEGER(KIND=4)               :: SetDumpFileOn
+ *  END FUNCTION SetDumpFileOn
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT IPQ_RESULT SetDumpFileOn(int id, int dump_on); + + +/** + * 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; + * 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 GetDumpFileOn, GetDumpStringOn, GetDumpString, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION SetDumpStringOn(ID,DUMP_STRING_ON)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    LOGICAL(KIND=4),  INTENT(IN)  :: DUMP_STRING_ON
+ *    INTEGER(KIND=4)               :: SetDumpStringOn
+ *  END FUNCTION SetDumpStringOn
+ *  
+ *
+ * @endhtmlonly + * + * @par C Example: + * see \ref GetDumpString_c "GetDumpString" + * + * @par Fortran90 Example: + * see \ref GetDumpStringLine_f90 "GetDumpStringLine" + */ + IPQ_DLL_EXPORT IPQ_RESULT SetDumpStringOn(int id, int dump_string_on); + + +/** + * Sets the error file switch on or off. This switch controls whether or not + * error messages are written to the phreeqc.id.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, 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 GetErrorFileOn, GetErrorStringLine, GetErrorStringLineCount, OutputErrorString + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION SetErrorFileOn(ID,ERR_ON)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    LOGICAL(KIND=4),  INTENT(IN)  :: ERR_ON
+ *    INTEGER(KIND=4)               :: SetErrorFileOn
+ *  END FUNCTION SetErrorFileOn
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT IPQ_RESULT SetErrorFileOn(int id, int error_on); + +/** + * Sets the name of the log file. The default value is phreeqc.id.log. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @param filename The name of the log file. + * @retval IPQ_OK Success. + * @retval IPQ_BADINSTANCE The given id is invalid. + * @see GetLogFileName, GetLogFileOn, GetLogString, GetLogStringOn, GetLogStringLine, GetLogStringLineCount, SetLogFileOn, SetLogStringOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION SetLogFileName(ID,FILENAME)
+ *    INTEGER(KIND=4),   INTENT(IN)   :: ID
+ *    CHARACTER(LEN=*),  INTENT(OUT)  :: FILENAME
+ *    INTEGER(KIND=4)                 :: SetLogFileName
+ *  END FUNCTION SetLogFileName
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT IPQ_RESULT SetLogFileName(int id, const char* filename); + +/** + * Sets the log file switch on or off. This switch controls whether or not phreeqc + * writes log messages to the phreeqc.id.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, 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 + * + *
+ *  FUNCTION SetLogFileOn(ID,LOG_ON)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    LOGICAL(KIND=4),  INTENT(IN)  :: LOG_ON
+ *    INTEGER(KIND=4)               :: SetLogFileOn
+ *  END FUNCTION SetLogFileOn
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT IPQ_RESULT SetLogFileOn(int id, int log_on); + +/** + * Sets the log string switch on or off. This switch controls whether or not the data normally sent + * to the log 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 output_string_on If non-zero, captures the log output into a string buffer; + * if zero, log output is not captured to a string buffer. + * @retval IPQ_OK Success. + * @retval IPQ_BADINSTANCE The given id is invalid. + * @see GetLogFileOn, GetLogStringOn, GetLogString, GetLogStringLine, GetLogStringLineCount, SetLogFileOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION SetLogStringOn(ID,LOG_STRING_ON)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    LOGICAL(KIND=4),  INTENT(IN)  :: LOG_STRING_ON
+ *    INTEGER(KIND=4)               :: SetLogStringOn
+ *  END FUNCTION SetLogStringOn
+ *  
+ *
+ * @endhtmlonly + * + * @par C Example: + * see \ref GetLogString_c "GetLogString" + * + * @par Fortran90 Example: + * see \ref GetLogStringLine_f90 "GetLogStringLine" + */ + IPQ_DLL_EXPORT IPQ_RESULT SetLogStringOn(int id, int log_string_on); + + +/** + * Sets the name of the output file. This file name is used if not specified within DUMP input. + * The default value is phreeqc.id.out. + * @param id The instance id returned from \ref CreateIPhreeqc. + * @param filename The name of the phreeqc output file. + * @retval IPQ_OK Success. + * @retval IPQ_BADINSTANCE The given id is invalid. + * @see GetOutputFileName, GetOutputFileOn, GetOutputString, GetOutputStringOn, GetOutputStringLine, GetOutputStringLineCount, SetOutputFileOn, SetOutputStringOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION SetOutputFileName(ID,FILENAME)
+ *    INTEGER(KIND=4),   INTENT(IN)   :: ID
+ *    CHARACTER(LEN=*),  INTENT(OUT)  :: FILENAME
+ *    INTEGER(KIND=4)                 :: SetOutputFileName
+ *  END FUNCTION SetOutputFileName
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT IPQ_RESULT SetOutputFileName(int id, const char* filename); + +/** + * Sets the output file switch on or off. This switch controls whether or not phreeqc + * writes to the phreeqc.id.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, 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 + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION SetOutputFileOn(ID,OUT_ON)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    LOGICAL(KIND=4),  INTENT(IN)  :: OUT_ON
+ *    INTEGER(KIND=4)               :: SetOutputFileOn
+ *  END FUNCTION SetOutputFileOn
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT IPQ_RESULT SetOutputFileOn(int id, int output_on); + +/** + * Sets the output string switch on or off. This switch controls whether or not the data normally sent + * to the output 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 output_string_on If non-zero, captures the phreeqc output into a string buffer; + * if zero, phreeqc output is not captured to a string buffer. + * @retval IPQ_OK Success. + * @retval IPQ_BADINSTANCE The given id is invalid. + * @see GetOutputFileOn, GetOutputStringOn, GetOutputString, GetOutputStringLine, GetOutputStringLineCount, SetOutputFileOn + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION SetOutputStringOn(ID,OUTPUT_STRING_ON)
+ *    INTEGER(KIND=4),  INTENT(IN)  :: ID
+ *    LOGICAL(KIND=4),  INTENT(IN)  :: OUTPUT_STRING_ON
+ *    INTEGER(KIND=4)               :: SetOutputStringOn
+ *  END FUNCTION SetOutputStringOn
+ *  
+ *
+ * @endhtmlonly + * + * @par C Example: + * see \ref GetOutputString_c "GetOutputString" + * + * @par Fortran90 Example: + * see \ref GetOutputStringLine_f90 "GetOutputStringLine" + */ + IPQ_DLL_EXPORT IPQ_RESULT SetOutputStringOn(int id, int output_string_on); + + +/** + * Sets the selected-output file switch on or off. This switch controls whether or not phreeqc writes output to + * the SELECTED_OUTPUT (selected.id.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, 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, GetSelectedOutputColumnCount, GetSelectedOutputRowCount, GetSelectedOutputValue + * @par Fortran90 Interface: + * @htmlonly + * + *
+ *  FUNCTION SetSelectedOutputFileOn(ID,SEL_ON)
+ *    INTEGER(KIND=4),  INTENT(IN) :: ID
+ *    LOGICAL(KIND=4),  INTENT(IN) :: SEL_ON
+ *    INTEGER(KIND=4)              :: SetSelectedOutputFileOn
+ *  END FUNCTION SetSelectedOutputFileOn
+ *  
+ *
+ * @endhtmlonly + */ + IPQ_DLL_EXPORT IPQ_RESULT SetSelectedOutputFileOn(int id, int sel_on); + + +// TODO int RunWithCallback(PFN_PRERUN_CALLBACK pfn_pre, PFN_POSTRUN_CALLBACK pfn_post, void *cookie, int output_on, int error_on, int log_on, int selected_output_on); + + +// TODO int CatchErrors(PFN_CATCH_CALLBACK pfn, void *cookie); + + +#if defined(__cplusplus) +} +#endif + +#endif // INC_IPHREEQC_H diff --git a/IPhreeqc.hpp b/IPhreeqc.hpp new file mode 100644 index 00000000..470d48c1 --- /dev/null +++ b/IPhreeqc.hpp @@ -0,0 +1,793 @@ +/*! @file IPhreeqc.hpp + @brief C++ Documentation +*/ + +#ifndef INC_IPHREEQC_HPP +#define INC_IPHREEQC_HPP + +#include +#include +#include +#include +#include +#include "IPhreeqcCallbacks.h" /* PFN_PRERUN_CALLBACK, PFN_POSTRUN_CALLBACK, PFN_CATCH_CALLBACK */ +#include "Var.h" /* VRESULT */ +#include "PHRQ_io.h" + +#if defined(_WINDLL) +#define IPQ_DLL_EXPORT __declspec(dllexport) +#else +#define IPQ_DLL_EXPORT +#endif + +class Phreeqc; +class IErrorReporter; +class CSelectedOutput; + +/** + * @class IPhreeqcStop + * + * @brief This class is derived from std::exception and is thrown + * when an unrecoverable error has occured. + */ +class IPQ_DLL_EXPORT IPhreeqcStop : std::exception +{ +}; + +/** + * @class IPhreeqc + * + * @brief Provides an interface to PHREEQC (Version 2)--A Computer + * Program for Speciation, Batch-Reaction, One-Dimensional Transport, + * and Inverse Geochemical Calculations + */ +class IPQ_DLL_EXPORT IPhreeqc : public PHRQ_io +{ +public: + /** + * Constructor. + * \anchor IPhreeqc_cpp + * @par Example: + * \include IPhreeqc.cpp + */ + IPhreeqc(void); + + /** + * Destructor + */ + virtual ~IPhreeqc(void); + +public: + + /** + * Accumlulate line(s) for input to phreeqc. + * @param line The line(s) to add for input to phreeqc. + * @retval VR_OK Success + * @retval VR_OUTOFMEMORY Out of memory + * @see ClearAccumulatedLines, OutputAccumulatedLines, RunAccumulated + */ + VRESULT AccumulateLine(const char *line); + + /** + * Appends the given error message and increments the error count. + * Internally used to create an error condition. + * @param error_msg The error message to display. + * @returns The current error count. + * @see GetErrorString, GetErrorStringLine, GetErrorStringLineCount, OutputErrorString + */ + size_t AddError(const char* error_msg); + + /** + * Appends the given warning message and increments the warning count. + * Internally used to create a warning condition. + * @param warning_msg The warning message to display. + * @returns The current warning count. + * @see GetWarningString, GetWarningStringLine, GetWarningStringLineCount, OutputWarningString + */ + size_t AddWarning(const char* warning_msg); + + /** + * Clears the accumulated input buffer. Input buffer is accumulated from calls to \ref AccumulateLine. + * @see AccumulateLine, GetAccumulatedLines, OutputAccumulatedLines, RunAccumulated + */ + void ClearAccumulatedLines(void); + + /** + * Retrieve the accumulated input string. The accumulated input string can be run + * with \ref RunAccumulated. + * @returns The accumulated input string. + * @see AccumulateLine, ClearAccumulatedLines, OutputAccumulatedLines, RunAccumulated + */ + const std::string& GetAccumulatedLines(void); + + /** + * Retrieves the given component. + * @param n The zero-based index of the component to retrieve. + * @return A null terminated string containing the given component. + * Returns an empty string if n is out of range. + * @see GetComponentCount, ListComponents + */ + const char* GetComponent(int n); + + /** + * Retrieves the number of components in the current list of components. + * @return The current count of components. + * @see GetComponent, ListComponents + */ + size_t GetComponentCount(void); + + + /** + * Retrieves the name of the dump file. This file name is used if not specified within DUMP input. + * The default value is dump.id.out, where id is obtained from \ref GetId. + * @return filename The name of the file to write DUMP output to. + * @see GetDumpFileOn, GetDumpString, GetDumpStringOn, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileName, SetDumpFileOn, SetDumpStringOn + */ + const char* GetDumpFileName(void)const; + + /** + * Retrieves the current value of the dump file switch. + * @retval true Output is written to the DUMP (dump.id.out if unspecified, where id is obtained from \ref GetId) file. + * @retval false No output is written. + * @see GetDumpStringLine, GetDumpStringLineCount, GetDumpStringOn, GetDumpString, SetDumpFileOn, SetDumpStringOn + */ + bool GetDumpFileOn(void)const; + + /** + * Retrieves the string buffer containing DUMP output. + * @return A null terminated string containing DUMP output. + * @pre + * \ref SetDumpStringOn must have been set to true in order to recieve DUMP output. + * @see GetDumpStringLine, GetDumpFileOn, GetDumpStringLineCount, GetDumpStringOn, SetDumpFileOn, SetDumpStringOn + */ + const char* GetDumpString(void)const; + + /** + * Retrieves the given dump line. + * @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. + * @see GetDumpFileOn, GetDumpString, GetDumpStringLineCount, GetDumpStringOn, SetDumpFileOn, SetDumpStringOn + */ + const char* GetDumpStringLine(int n); + + /** + * 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 GetDumpFileOn, GetDumpString, GetDumpStringLine, GetDumpStringOn, SetDumpFileOn, SetDumpStringOn + */ + int GetDumpStringLineCount(void)const; + + /** + * 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 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.id.err (where id is obtained from \ref GetId) file. + * @retval false No errors are written. + * @see SetErrorFileOn + */ + bool GetErrorFileOn(void)const; + + /** + * Retrieves the error messages from the last call to \ref RunAccumulated, \ref RunFile, \ref RunString, \ref LoadDatabase, or \ref LoadDatabaseString. + * @return A null terminated string containing error messages. + * @see GetErrorStringLine, GetErrorStringLineCount, GetErrorFileOn, OutputErrorString, SetErrorFileOn + */ + const char* GetErrorString(void); + + /** + * Retrieves the given error line. + * @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 + */ + const char* GetErrorStringLine(int n); + + /** + * Retrieves the number of lines in the current error string buffer. + * @return The number of lines. + * @see GetErrorStringLine, OutputErrorString + */ + int GetErrorStringLineCount(void)const; + + /** + * Retrieves the id of this object. Each instance receives an id which is incremented for each instance + * starting with the value zero. + * @return The id. + */ + int GetId(void)const; + + /** + * Retrieves the name of the log file. The default value is phreeqc.id.log, where id is obtained from \ref GetId. + * @return filename The name of the file to write to. + * @see GetLogFileOn, GetLogString, GetLogStringOn, GetLogStringLine, GetLogStringLineCount, SetLogFileName, SetLogFileOn, SetLogStringOn + */ + const char* GetLogFileName(void)const; + + /** + * Retrieves the current value of the log file switch. + * @retval true Log messages are written to the phreeqc.id.log (where id is obtained from \ref GetId) 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; + + /** + * Retrieves the string buffer containing phreeqc log output. + * @return A null terminated string containing log output. + * @pre + * \ref SetLogStringOn must have been set to true and enabled through the use of the KNOBS -logfile option in order to receive any log messages. + * @see GetLogStringLine, GetLogFileOn, GetLogStringLineCount, GetLogStringOn, SetLogFileOn, SetLogStringOn + */ + const char* GetLogString(void)const; + + /** + * Retrieves the given log line. + * @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 SetLogStringOn must have been set to true and enabled through the use of the KNOBS -logfile option in order to receive any log messages. + * @see GetLogFileOn, GetLogString, GetLogStringLineCount, GetLogStringOn, SetLogFileOn, SetLogStringOn + */ + const char* GetLogStringLine(int n)const; + + /** + * Retrieves the number of lines in the current log string buffer. + * @return The number of lines. + * @pre \ref SetLogStringOn must have been set to true and enabled through the use of the KNOBS -logfile option in order to receive any log messages. + * @see GetLogFileOn, GetLogString, GetLogStringLine, GetLogStringOn, SetLogFileOn, SetLogStringOn + */ + int GetLogStringLineCount(void)const; + + /** + * Retrieves the current value of the log string switch. + * @retval true Log output is stored. + * @retval false No log output is stored. + * @see GetLogFileOn, GetLogString, GetLogStringLine, GetLogStringLineCount, SetLogFileOn, SetLogStringOn + */ + bool GetLogStringOn(void)const; + + /** + * Retrieves the name of the output file. The default value is phreeqc.id.out, where id is obtained from \ref GetId. + * @return filename The name of the file to write phreeqc output to. + * @see GetOutputFileOn, GetOutputString, GetOutputStringOn, GetOutputStringLine, GetOutputStringLineCount, SetOutputFileName, SetOutputFileOn, SetOutputStringOn + */ + const char* GetOutputFileName(void)const; + + /** + * Retrieves the current value of the output file switch. + * @retval true Output is written to the phreeqc.id.out (where id is obtained from \ref GetId) file. + * @retval false No output is written. + * @see GetOutputFileOn, GetOutputString, GetOutputStringOn, GetOutputStringLine, GetOutputStringLineCount, SetOutputFileName, SetOutputFileOn, SetOutputStringOn + */ + bool GetOutputFileOn(void)const; + + /** + * Retrieves the string buffer containing phreeqc output. + * @return A null terminated string containing phreeqc output. + * @pre + * \ref SetOutputStringOn must have been set to true in order to recieve output. + * @see GetOutputStringLine, GetOutputFileOn, GetOutputStringLineCount, GetOutputStringOn, SetOutputFileOn, SetOutputStringOn + */ + const char* GetOutputString(void)const; + + /** + * Retrieves the given output line. + * @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 SetOutputStringOn must have been set to true. + * @see GetOutputFileOn, GetOutputString, GetOutputStringLineCount, GetOutputStringOn, SetOutputFileOn, SetOutputStringOn + */ + const char* GetOutputStringLine(int n)const; + + /** + * Retrieves the number of lines in the current output string buffer. + * @return The number of lines. + * @pre \ref SetOutputStringOn must have been set to true. + * @see GetOutputFileOn, GetOutputString, GetOutputStringLine, GetOutputStringOn, SetOutputFileOn, SetOutputStringOn + */ + int GetOutputStringLineCount(void)const; + + /** + * Retrieves the current value of the output string switch. + * @retval true Phreeqc output is stored. + * @retval false No phreeqc output is stored. + * @see GetOutputFileOn, GetOutputString, GetOutputStringLine, GetOutputStringLineCount, SetOutputFileOn, SetOutputStringOn + */ + bool GetOutputStringOn(void)const; + + /** + * Retrieves the number of columns in the selected-output buffer. + * @return The number of columns. + * @see GetSelectedOutputRowCount, GetSelectedOutputValue + */ + int GetSelectedOutputColumnCount(void)const; + + /** + * Retrieves the selected-output file switch. + * @retval true Output is written to the selected-output (selected.id.out if unspecified, where id is obtained from \ref GetId) file. + * @retval false No output is written. + * @see GetSelectedOutputValue, GetSelectedOutputColumnCount, GetSelectedOutputRowCount, SetSelectedOutputFileOn + */ + bool GetSelectedOutputFileOn(void)const; + + /** + * Retrieves the number of rows in the selected-output buffer. + * @return The number of rows. + * @see GetSelectedOutputColumnCount, GetSelectedOutputFileOn, GetSelectedOutputValue, SetSelectedOutputFileOn + */ + int GetSelectedOutputRowCount(void)const; + + /** + * Returns the \c VAR associated with the specified row and column. + * @param row The row index. + * @param col The column index. + * @param pVAR Pointer to the \c VAR to recieve the requested data. + * @retval VR_OK Success. + * @retval VR_INVALIDROW The given row is out of range. + * @retval VR_INVALIDCOL The given column is out of range. + * @retval VR_OUTOFMEMORY Memory could not be allocated. + * @retval VR_BADINSTANCE The given id is invalid. + * @see GetSelectedOutputColumnCount, GetSelectedOutputFileOn, GetSelectedOutputRowCount, SetSelectedOutputFileOn + * @remarks + * Row 0 contains the column headings to the selected_ouput. + * @par Examples: + * The headings will include a suffix and/or prefix in order to differentiate the + * columns. + * @htmlonly +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Input + + Headings +
+
+	  SELECTED_OUTPUT
+		-reset false
+		-totals Ca Na
+	
+
+
+	  Ca(mol/kgw)  Na(mol/kgw)
+	
+
+
+	  SELECTED_OUTPUT
+		-reset false
+		-molalities Fe+2 Hfo_sOZn+
+	
+
+
+	  m_Fe+2(mol/kgw)  m_Hfo_sOZn+(mol/kgw)
+	
+
+
+	  SELECTED_OUTPUT
+		-reset false
+		-activities H+ Ca+2
+	
+
+
+	  la_H+  la_Ca+2
+	
+
+
+	  SELECTED_OUTPUT
+		-reset false
+		-equilibrium_phases Calcite Dolomite
+	
+
+
+	  Calcite  d_Calcite  Dolomite  d_Dolomite
+	
+
+
+	  SELECTED_OUTPUT
+		-reset false
+		-saturation_indices CO2(g) Siderite
+	
+
+
+	  si_CO2(g)  si_Siderite
+	
+
+
+	  SELECTED_OUTPUT
+		-reset false
+		-gases CO2(g) N2(g)
+	
+
+
+	  pressure "total mol" volume g_CO2(g) g_N2(g)
+	
+
+
+	  SELECTED_OUTPUT
+		-reset false
+		-kinetic_reactants CH2O Pyrite
+	
+
+
+	  k_CH2O dk_CH2O k_Pyrite dk_Pyrite
+	
+
+
+	  SELECTED_OUTPUT
+		-reset false
+		-solid_solutions CaSO4 SrSO4
+	
+
+
+	  s_CaSO4 s_SrSO4
+	
+
+ * @endhtmlonly + */ + VRESULT GetSelectedOutputValue(int row, int col, VAR* pVAR); + + /** + * Retrieves the warning messages from the last call to \ref RunAccumulated, \ref RunFile, \ref RunString, \ref LoadDatabase, or \ref LoadDatabaseString. + * @return A null terminated string containing warning messages. + * @see GetWarningStringLine, GetWarningStringLineCount, OutputWarningString + */ + const char* GetWarningString(void); + + /** + * Retrieves the given warning line. + * @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 + */ + const char* GetWarningStringLine(int n); + + /** + * Retrieves the number of lines in the current warning string buffer. + * @return The number of lines. + * @see GetWarningStringLine, GetWarningString, OutputWarningString + */ + int GetWarningStringLineCount(void)const; + + /** + * Retrieves the current list of components. + * @return The current list of components. + * @see GetComponent, GetComponentCount + */ + std::list< std::string > ListComponents(void); + + /** + * Load the specified database file into phreeqc. + * @param filename The name of the phreeqc database to load. + * 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 + * @remarks + * All previous definitions are cleared. + */ + int LoadDatabase(const char* filename); + + /** + * 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 LoadDatabaseString + * @remarks + * All previous definitions are cleared. + */ + int LoadDatabaseString(const char* input); + + /** + * Output the accumulated input buffer to stdout. The input buffer can be run with a call to \ref RunAccumulated. + * @see AccumulateLine, ClearAccumulatedLines, RunAccumulated + */ + void OutputAccumulatedLines(void); + + /** + * Output the error messages normally stored in the phreeqc.id.err (where id is obtained from \ref GetId) + * file to stdout. + * @see GetErrorStringLine, GetErrorStringLineCount, GetErrorFileOn, SetErrorFileOn + */ + void OutputErrorString(void); + + /** + * Output the warning messages to stdout. + * @see GetWarningStringLine, GetWarningStringLineCount, GetWarningString + */ + void OutputWarningString(void); + + /** + * Runs the input buffer as defined by calls to \ref AccumulateLine. + * @return The number of errors encountered. + * @see AccumulateLine, ClearAccumulatedLines, OutputAccumulatedLines, RunFile, RunString + * @remarks + * 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. + */ + int RunAccumulated(void); + + /** + * Runs the specified phreeqc input file. + * @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. + */ + int RunFile(const char* filename); + + /** + * Runs the specified string as input to phreeqc. + * @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. + */ + int RunString(const char* input); + + /** + * Sets the name of the dump file. This file name is used if not specified within DUMP input. + * The default value is dump.id.out, where id is obtained from \ref GetId. + * @param filename The name of the file to write DUMP output to. + * @see GetDumpFileName, GetDumpFileOn, GetDumpString, GetDumpStringOn, GetDumpStringLine, GetDumpStringLineCount, SetDumpStringOn + */ + void SetDumpFileName(const char *filename); + + /** + * Sets the dump file switch on or off. This switch controls whether or not phreeqc writes to the DUMP (dump.id.out + * if unspecified, where id is obtained from \ref GetId) file. + * The initial setting is false. + * @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; + * 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 phreeqc.id.err (where id is obtained from \ref GetId) 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 name of the log file. The default value is phreeqc.id.log, where id is obtained from \ref GetId. + * @param filename The name of the file to write log output to. + * @see GetLogFileName, GetLogFileOn, GetLogString, GetLogStringOn, GetLogStringLine, GetLogStringLineCount, SetLogFileOn, SetLogStringOn + */ + void SetLogFileName(const char *filename); + + /** + * Sets the log file switch on or off. This switch controls whether or not phreeqc + * writes log messages to the phreeqc.id.log (where id is obtained from \ref GetId) 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 log string switch on or off. This switch controls whether or not the data normally sent + * to the log file are stored in a buffer for retrieval. The initial setting is false. + * @param bValue If true, captures log output into a string buffer; if false, log output is not captured to a string buffer. + * @see GetLogFileOn, GetLogString, GetLogStringOn, GetLogStringLine, GetLogStringLineCount, SetLogFileOn + */ + void SetLogStringOn(bool bValue); + + /** + * Sets the name of the output file. The default value is phreeqc.id.out, where id is obtained from \ref GetId. + * @param filename The name of the file to write phreeqc output to. + * @see GetOutputFileName, GetOutputFileOn, GetOutputString, GetOutputStringOn, GetOutputStringLine, GetOutputStringLineCount, SetOutputFileOn, SetOutputStringOn + */ + void SetOutputFileName(const char *filename); + + /** + * Sets the output file switch on or off. This switch controls whether or not phreeqc + * writes to the phreeqc.id.out file (where id is obtained from \ref GetId). This is the output that is normally generated + * when phreeqc is run. The initial setting is false. + * @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 output string switch on or off. This switch controls whether or not the data normally sent + * to the output file are stored in a buffer for retrieval. The initial setting is false. + * @param bValue If true, captures output into a string buffer; if false, output is not captured to a string buffer. + * @see GetOutputFileOn, GetOutputString, GetOutputStringOn, GetOutputStringLine, GetOutputStringLineCount, SetOutputFileOn + */ + void SetOutputStringOn(bool bValue); + + /** + * Sets the selected-output file switch on or off. This switch controls whether or not phreeqc writes output to + * the SELECTED_OUTPUT (selected.id.out if unspecified, where id is obtained from \ref GetId) 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); + +public: + // overrides + virtual void error_msg(const char *str, bool stop=false); + virtual void log_msg(const char * str); + virtual void output_msg(const char *str); + virtual void punch_msg(const char *str); + virtual void screen_msg(const char *str); + virtual void warning_msg(const char *str); + + virtual void fpunchf(const char *name, const char *format, double d); + virtual void fpunchf(const char *name, const char *format, char * d); + virtual void fpunchf(const char *name, const char *format, int d); + virtual void fpunchf_end_row(const char *format); + + virtual bool output_open(const char *file_name, std::ios_base::openmode mode = std::ios_base::out); + virtual bool punch_open(const char *file_name, std::ios_base::openmode mode = std::ios_base::out); + +protected: + int EndRow(void); + void AddSelectedOutput(const char* name, const char* format, va_list argptr); + void UnLoadDatabase(void); + + void check_database(const char* sz_routine); + int close_input_files(void); + int close_output_files(void); + void open_output_files(const char* sz_routine); + + void do_run(const char* sz_routine, std::istream* pis, PFN_PRERUN_CALLBACK pfn_pre, PFN_POSTRUN_CALLBACK pfn_post, void *cookie); + + void update_errors(void); + + +protected: +#if defined(_MSC_VER) +/* disable warning C4251: 'identifier' : class 'type' needs to have dll-interface to be used by clients of class 'type2' */ +#pragma warning(disable:4251) +#endif + + bool DatabaseLoaded; + bool ClearAccumulated; + bool UpdateComponents; + bool SelectedOutputOn; + bool OutputFileOn; + + bool LogFileOn; + bool ErrorOn; + bool DumpOn; + + bool DumpStringOn; + + bool OutputStringOn; + std::string OutputString; + std::vector< std::string > OutputLines; + + bool LogStringOn; + std::string LogString; + std::vector< std::string > LogLines; + + IErrorReporter *ErrorReporter; + std::string ErrorString; + std::vector< std::string > ErrorLines; + + IErrorReporter *WarningReporter; + std::string WarningString; + std::vector< std::string > WarningLines; + + CSelectedOutput *SelectedOutput; + std::string StringInput; + + std::string DumpString; + std::vector< std::string > DumpLines; + + std::list< std::string > Components; + + std::string PunchFileName; + std::string OutputFileName; + std::string ErrorFileName; + std::string LogFileName; + std::string DumpFileName; + +protected: + Phreeqc* PhreeqcPtr; + FILE *input_file; + FILE *database_file; + + friend class IPhreeqcLib; + static std::map Instances; + static size_t InstancesIndex; + const size_t Index; + +#if defined(_MSC_VER) +/* reset warning C4251 */ +#pragma warning(default:4251) +#endif + +#if defined(CPPUNIT) + friend class TestIPhreeqc; + friend class TestSelectedOutput; +#endif + +private: + /** + * Copy constructor not supported + */ + IPhreeqc(const IPhreeqc&); + + /** + * operator= not supported + */ + IPhreeqc& operator=(const IPhreeqc&); +}; + +#endif // INC_IPHREEQC_HPP diff --git a/IPhreeqcCallbacks.h b/IPhreeqcCallbacks.h new file mode 100644 index 00000000..0875d12e --- /dev/null +++ b/IPhreeqcCallbacks.h @@ -0,0 +1,19 @@ +#ifndef _INC_IPHREEQC_CALLBACKS_H +#define _INC_IPHREEQC_CALLBACKS_H + + +#if defined(__cplusplus) +extern "C" { +#endif + + +typedef int (*PFN_PRERUN_CALLBACK)(void *cookie); +typedef int (*PFN_POSTRUN_CALLBACK)(void *cookie); +typedef int (*PFN_CATCH_CALLBACK)(void *cookie); + + +#if defined(__cplusplus) +} +#endif + +#endif /* _INC_IPHREEQC_CALLBACKS_H */ diff --git a/Makefile.am b/Makefile.am index 8b11517d..a03c80f6 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,6 +1,6 @@ EXTRA_DIST = fwrap2.cpp fwrap3.cpp -AM_CPPFLAGS=-I$(top_srcdir)/include -I$(top_srcdir)/src/phreeqcpp -I$(top_srcdir)/src/phreeqcpp/phreeqc +AM_CPPFLAGS=-I$(top_srcdir)/src -I$(top_srcdir)/src/phreeqcpp -I$(top_srcdir)/src/phreeqcpp/phreeqc # libtool libraries to build lib_LTLIBRARIES=libiphreeqc.la @@ -141,10 +141,12 @@ libiphreeqc_la_SOURCES=\ phreeqcpp/phreeqc/utilities.cpp include_HEADERS=\ - $(top_srcdir)/include/IPhreeqc.h\ - $(top_srcdir)/include/IPhreeqc.hpp\ - $(top_srcdir)/include/IPhreeqcCallbacks.h\ - $(top_srcdir)/include/Var.h + $(top_srcdir)/src/IPhreeqc.h\ + $(top_srcdir)/src/IPhreeqc.hpp\ + $(top_srcdir)/src/IPhreeqcCallbacks.h\ + $(top_srcdir)/src/Var.h\ + $(top_srcdir)/src/phreeqcpp/PHRQ_io.h\ + $(top_srcdir)/src/phreeqcpp/Keywords.h if BUILD_FORTRAN @@ -155,8 +157,8 @@ libiphreeqc_la_SOURCES+=\ IPhreeqcF.f include_HEADERS+=\ - $(top_srcdir)/include/IPhreeqc.f90.inc\ - $(top_srcdir)/include/IPhreeqc.f.inc + $(top_srcdir)/src/IPhreeqc.f90.inc\ + $(top_srcdir)/src/IPhreeqc.f.inc endif diff --git a/Var.h b/Var.h new file mode 100644 index 00000000..af3dad1a --- /dev/null +++ b/Var.h @@ -0,0 +1,150 @@ +/*! @file Var.h + @brief %IPhreeqc VARIANT Documentation +*/ +// Var.h + +#ifndef __VAR_H_INC +#define __VAR_H_INC + +#if defined(_WINDLL) +#define IPQ_DLL_EXPORT __declspec(dllexport) +#else +#define IPQ_DLL_EXPORT +#endif + +/*! \brief Enumeration used to determine the type of data stored in a VAR. +*/ +typedef enum { + TT_EMPTY = 0, /*!< VAR contains no data */ + TT_ERROR = 1, /*!< vresult is valid */ + TT_LONG = 2, /*!< lVal is valid */ + TT_DOUBLE = 3, /*!< dVal is valid */ + TT_STRING = 4 /*!< sVal is valid */ +} VAR_TYPE; + +/*! \brief Enumeration used to return error codes. +*/ +typedef enum { + VR_OK = 0, /*!< Success */ + VR_OUTOFMEMORY = -1, /*!< Failure, Out of memory */ + VR_BADVARTYPE = -2, /*!< Failure, Invalid VAR type */ + VR_INVALIDARG = -3, /*!< Failure, Invalid argument */ + VR_INVALIDROW = -4, /*!< Failure, Invalid row */ + VR_INVALIDCOL = -5 /*!< Failure, Invalid column */ +} VRESULT; + +/*! \brief Datatype used to store SELECTED_OUTPUT values. +*/ +typedef struct { + VAR_TYPE type; /*!< holds datatype of VAR */ + union { + long lVal; /*!< valid when (type == TT_LONG) */ + double dVal; /*!< valid when (type == TT_DOUBLE) */ + char* sVal; /*!< valid when (type == TT_STRING) */ + VRESULT vresult; /*!< valid when (type == TT_ERROR) */ + }; +} VAR; + + +#if defined(__cplusplus) +extern "C" { +#endif + +/** Allocates a new string for use in a VAR and copies the passed string into it. + * @param pSrc Pointer to the VAR that will be initialized. + * @return A pointer to the string on success NULL otherwise. + */ +IPQ_DLL_EXPORT char* VarAllocString(const char* pSrc); + +/** Clears a VAR. + * @param pvar Pointer to the VAR that will be freed and initialized. + * @retval VR_OK Success. + * @retval VR_BADVARTYPE The \c VAR was invalid (probably uninitialized). + */ +IPQ_DLL_EXPORT VRESULT VarClear(VAR* pvar); + +/** Frees the destination VAR and makes a copy of the source VAR. + * @param pvarDest Pointer to the VAR to receive the copy. + * @param pvarSrc Pointer to the VAR to be copied. + * @retval VR_OK Success. + * @retval VR_BADVARTYPE The source and/or the destination are invalid (usually uninitialized). + * @retval VR_OUTOFMEMORY Memory could not be allocated for the copy. + * @return The return value is one of the following. + */ +IPQ_DLL_EXPORT VRESULT VarCopy(VAR* pvarDest, const VAR* pvarSrc); + +/** Frees a string allocated using VarAllocString. + * @param pSrc Pointer to the string to be freed. + */ +IPQ_DLL_EXPORT void VarFreeString(char* pSrc); + +/** Initializes a VAR. + * @param pvar Pointer to the VAR that will be initialized. + */ +IPQ_DLL_EXPORT void VarInit(VAR* pvar); + +#if defined(__cplusplus) +} +#endif + +#if defined(__cplusplus) + +#include // std::ostream + +inline std::ostream& operator<< (std::ostream &os, const VAR_TYPE& vt) +{ + switch(vt) + { + case TT_EMPTY: + os << "TT_EMPTY"; + break; + case TT_ERROR: + os << "TT_ERROR"; + break; + case TT_LONG: + os << "TT_LONG"; + break; + case TT_DOUBLE: + os << "TT_DOUBLE"; + break; + case TT_STRING: + os << "TT_STRING"; + break; + default: + os << (int)vt; + break; + } + return os; +} + +inline std::ostream& operator<< (std::ostream &os, const VRESULT& vr) +{ + switch(vr) + { + case VR_OK: + os << "VR_OK"; + break; + case VR_OUTOFMEMORY: + os << "VR_OUTOFMEMORY"; + break; + case VR_BADVARTYPE: + os << "VR_BADVARTYPE"; + break; + case VR_INVALIDARG: + os << "VR_INVALIDARG"; + break; + case VR_INVALIDROW: + os << "VR_INVALIDROW"; + break; + case VR_INVALIDCOL: + os << "VR_INVALIDCOL"; + break; + default: + os << (int)vr; + break; + } + return os; +} +#endif /* __cplusplus */ + +#endif /* __VAR_H_INC */