IPhreeqc
Enumerations | Functions
IPhreeqc.h File Reference

C/Fortran Documentation. More...

#include "Var.h"

Go to the source code of this file.

Enumerations

enum  IPQ_RESULT {
  IPQ_OK = 0, IPQ_OUTOFMEMORY = -1, IPQ_BADVARTYPE = -2, IPQ_INVALIDARG = -3,
  IPQ_INVALIDROW = -4, IPQ_INVALIDCOL = -5, IPQ_BADINSTANCE = -6
}
 Enumeration used to return error codes. More...
 

Functions

IPQ_RESULT AccumulateLine (int id, const char *line)
 
int AddError (int id, const char *error_msg)
 
int AddWarning (int id, const char *warn_msg)
 
IPQ_RESULT ClearAccumulatedLines (int id)
 
int CreateIPhreeqc (void)
 
IPQ_RESULT DestroyIPhreeqc (int id)
 
const char * GetComponent (int id, int n)
 
int GetComponentCount (int id)
 
int GetCurrentSelectedOutputUserNumber (int id)
 
const char * GetDumpFileName (int id)
 
int GetDumpFileOn (int id)
 
const char * GetDumpString (int id)
 
const char * GetDumpStringLine (int id, int n)
 
int GetDumpStringLineCount (int id)
 
int GetDumpStringOn (int id)
 
const char * GetErrorFileName (int id)
 
int GetErrorFileOn (int id)
 
const char * GetErrorString (int id)
 
const char * GetErrorStringLine (int id, int n)
 
int GetErrorStringLineCount (int id)
 
int GetErrorStringOn (int id)
 
const char * GetLogFileName (int id)
 
int GetLogFileOn (int id)
 
const char * GetLogString (int id)
 
const char * GetLogStringLine (int id, int n)
 
int GetLogStringLineCount (int id)
 
int GetLogStringOn (int id)
 
int GetNthSelectedOutputUserNumber (int id, int n)
 
const char * GetOutputFileName (int id)
 
int GetOutputFileOn (int id)
 
const char * GetOutputString (int id)
 
const char * GetOutputStringLine (int id, int n)
 
int GetOutputStringLineCount (int id)
 
int GetOutputStringOn (int id)
 
int GetSelectedOutputColumnCount (int id)
 
int GetSelectedOutputCount (int id)
 
const char * GetSelectedOutputFileName (int id)
 
int GetSelectedOutputFileOn (int id)
 
int GetSelectedOutputRowCount (int id)
 
const char * GetSelectedOutputString (int id)
 
const char * GetSelectedOutputStringLine (int id, int n)
 
int GetSelectedOutputStringLineCount (int id)
 
int GetSelectedOutputStringOn (int id)
 
IPQ_RESULT GetSelectedOutputValue (int id, int row, int col, VAR *pVAR)
 
IPQ_RESULT GetSelectedOutputValue2 (int id, int row, int col, int *vtype, double *dvalue, char *svalue, unsigned int svalue_length)
 
const char * GetVersionString (void)
 
const char * GetWarningString (int id)
 
const char * GetWarningStringLine (int id, int n)
 
int GetWarningStringLineCount (int id)
 
int LoadDatabase (int id, const char *filename)
 
int LoadDatabaseString (int id, const char *input)
 
void OutputAccumulatedLines (int id)
 
void OutputErrorString (int id)
 
void OutputWarningString (int id)
 
int RunAccumulated (int id)
 
int RunFile (int id, const char *filename)
 
int RunString (int id, const char *input)
 
IPQ_RESULT SetBasicCallback (int id, double(*fcn)(double x1, double x2, const char *str, void *cookie), void *cookie1)
 
IPQ_RESULT SetBasicFortranCallback (int id, double(*fcn)(double *x1, double *x2, const char *str, int l))
 
IPQ_RESULT SetCurrentSelectedOutputUserNumber (int id, int n)
 
IPQ_RESULT SetDumpFileName (int id, const char *filename)
 
IPQ_RESULT SetDumpFileOn (int id, int dump_on)
 
IPQ_RESULT SetDumpStringOn (int id, int dump_string_on)
 
IPQ_RESULT SetErrorFileName (int id, const char *filename)
 
IPQ_RESULT SetErrorFileOn (int id, int error_on)
 
IPQ_RESULT SetErrorStringOn (int id, int error_string_on)
 
IPQ_RESULT SetLogFileName (int id, const char *filename)
 
IPQ_RESULT SetLogFileOn (int id, int log_on)
 
IPQ_RESULT SetLogStringOn (int id, int log_string_on)
 
IPQ_RESULT SetOutputFileName (int id, const char *filename)
 
IPQ_RESULT SetOutputFileOn (int id, int output_on)
 
IPQ_RESULT SetOutputStringOn (int id, int output_string_on)
 
IPQ_RESULT SetSelectedOutputFileName (int id, const char *filename)
 
IPQ_RESULT SetSelectedOutputFileOn (int id, int sel_on)
 
IPQ_RESULT SetSelectedOutputStringOn (int id, int sel_string_on)
 

Detailed Description

C/Fortran Documentation.

Enumeration Type Documentation

enum IPQ_RESULT

Enumeration used to return error codes.

Enumerator
IPQ_OK 

Success

IPQ_OUTOFMEMORY 

Failure, Out of memory

IPQ_BADVARTYPE 

Failure, Invalid VAR type

IPQ_INVALIDARG 

Failure, Invalid argument

IPQ_INVALIDROW 

Failure, Invalid row

IPQ_INVALIDCOL 

Failure, Invalid column

IPQ_BADINSTANCE 

Failure, Invalid instance id

Function Documentation

IPQ_RESULT AccumulateLine ( int  id,
const char *  line 
)

Accumlulate line(s) for input to phreeqc.

Parameters
idThe instance id returned from CreateIPhreeqc.
lineThe line(s) to add for input to phreeqc.
Return values
IPQ_OKSuccess
IPQ_OUTOFMEMORYOut of memory
See also
ClearAccumulatedLines, OutputAccumulatedLines, RunAccumulated
Fortran90 Interface:
FUNCTION AccumulateLine(ID,LINE)
  INTEGER(KIND=4),   INTENT(IN)  :: ID
  CHARACTER(LEN=*),  INTENT(IN)  :: LINE
  INTEGER(KIND=4)                :: AccumulateLine
END FUNCTION AccumulateLine
C Example:
#include <stdlib.h>
#include <IPhreeqc.h>
int main(void)
{
int id;
if (id < 0) {
return EXIT_FAILURE;
}
if (LoadDatabase(id, "phreeqc.dat") != 0) {
return EXIT_FAILURE;
}
if (AccumulateLine(id, "SOLUTION 1") != IPQ_OK) {
return EXIT_FAILURE;
}
if (AccumulateLine(id, "END") != IPQ_OK) {
return EXIT_FAILURE;
}
if (RunAccumulated(id) != 0) {
return EXIT_FAILURE;
}
if (DestroyIPhreeqc(id) != IPQ_OK) {
return EXIT_FAILURE;
}
return EXIT_SUCCESS;
}
Fortran90 Example:
see GetDumpStringLine
int AddError ( int  id,
const char *  error_msg 
)

Appends the given error message and increments the error count. Internally used to create an error condition.

Parameters
idThe instance id returned from CreateIPhreeqc.
error_msgThe error message to display.
Returns
The current error count if successful; otherwise a negative value indicates an error occured (see IPQ_RESULT).
See also
GetErrorString, GetErrorStringLine, GetErrorStringLineCount, OutputErrorString
Fortran90 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
int AddWarning ( int  id,
const char *  warn_msg 
)

Appends the given warning message and increments the warning count. Internally used to create a warning condition.

Parameters
idThe instance id returned from CreateIPhreeqc.
warn_msgThe warning message to display.
Returns
The current warning count if successful; otherwise a negative value indicates an error occured (see IPQ_RESULT).
See also
GetWarningString, GetWarningStringLine, GetWarningStringLineCount, OutputWarningString
Fortran90 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
IPQ_RESULT ClearAccumulatedLines ( int  id)

Clears the accumulated input buffer. Input buffer is accumulated from calls to AccumulateLine.

Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe given id is invalid.
See also
AccumulateLine, OutputAccumulatedLines, RunAccumulated
Fortran90 Interface:
FUNCTION ClearAccumulatedLines(ID)
  INTEGER(KIND=4), INTENT(IN) :: ID
  INTEGER(KIND=4)             :: ClearAccumulatedLines
END FUNCTION ClearAccumulatedLines
int CreateIPhreeqc ( void  )

Create a new IPhreeqc instance.

Returns
A non-negative value if successful; otherwise a negative value indicates an error occured (see IPQ_RESULT).
See also
DestroyIPhreeqc
Fortran90 Interface:
FUNCTION CreateIPhreeqc()
  INTEGER(KIND=4)  :: CreateIPhreeqc
END FUNCTION CreateIPhreeqc

C Example:
#include <stdlib.h>
#include <IPhreeqc.h>
int main(void)
{
int id;
if (id < 0) {
return EXIT_FAILURE;
}
if (LoadDatabase(id, "phreeqc.dat") != 0) {
return EXIT_FAILURE;
}
if (RunFile(id, "ex2") != 0) {
return EXIT_FAILURE;
}
if (DestroyIPhreeqc(id) != IPQ_OK) {
return EXIT_FAILURE;
}
return EXIT_SUCCESS;
}

Fortran90 Example:
PROGRAM example
USE iphreeqc
INTEGER(KIND=4) :: id
id = createiphreeqc()
IF (id.LT.0) THEN
stop
END IF
IF (loaddatabase(id, "phreeqc.dat").NE.0) THEN
CALL outputerrorstring(id)
stop
END IF
IF (runfile(id, "ex2").NE.0) THEN
CALL outputerrorstring(id)
stop
END IF
IF (destroyiphreeqc(id).NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
END PROGRAM example
IPQ_RESULT DestroyIPhreeqc ( int  id)

Release an IPhreeqc instance from memory.

Parameters
idThe instance id returned from CreateIPhreeqc.
Return values
IPQ_OKSuccess
IPQ_BADINSTANCEThe given id is invalid.
See also
CreateIPhreeqc
Fortran90 Interface:
FUNCTION DestroyIPhreeqc(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  INTEGER(KIND=4)               :: DestroyIPhreeqc
END FUNCTION DestroyIPhreeqc
C Example:
see CreateIPhreeqc
Fortran90 Example:
see CreateIPhreeqc
const char* GetComponent ( int  id,
int  n 
)

Retrieves the given component.

Parameters
idThe instance id returned from CreateIPhreeqc.
nThe zero-based index of the component to retrieve.
Returns
A null terminated string containing the given component. Returns an empty string if n is out of range.
See also
GetComponentCount
Fortran90 Interface:
(Note: N is one-based for the Fortran 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

C Example:
#include <stdlib.h>
#include <stdio.h>
#include <IPhreeqc.h>
int main(void)
{
int id, i;
if (id < 0) {
return EXIT_FAILURE;
}
if (LoadDatabase(id, "phreeqc.dat") != 0) {
return EXIT_FAILURE;
}
if (RunFile(id, "ex2") != 0) {
return EXIT_FAILURE;
}
for (i=0; i < GetComponentCount(id); ++i) {
printf("comp %d = %s\n", i, GetComponent(id, i));
}
if (DestroyIPhreeqc(id) != IPQ_OK) {
return EXIT_FAILURE;
}
return EXIT_SUCCESS;
}

Fortran90 Example:
PROGRAM example
USE iphreeqc
INTEGER(KIND=4) :: id
INTEGER(KIND=4) :: i
CHARACTER(LEN=40) :: comp
id = createiphreeqc()
IF (id.LT.0) THEN
stop
END IF
IF (loaddatabase(id, "phreeqc.dat").NE.0) THEN
CALL outputerrorstring(id)
stop
END IF
IF (runfile(id, "ex2").NE.0) THEN
CALL outputerrorstring(id)
stop
END IF
DO i=1,getcomponentcount(id)
CALL getcomponent(id, i, comp)
WRITE(*,*) "comp ", i, " = ", comp
END DO
IF (destroyiphreeqc(id).NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
END PROGRAM example
int GetComponentCount ( int  id)

Retrieves the number of components in the current component list.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
The current count of components. A negative value indicates an error occured (see IPQ_RESULT).
See also
GetComponent
Fortran90 Interface:
FUNCTION GetComponentCount(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  INTEGER(KIND=4)               :: GetComponentCount
END FUNCTION GetComponentCount
C Example:
see GetComponent
Fortran90 Example:
see GetComponent
int GetCurrentSelectedOutputUserNumber ( int  id)

Retrieves the current SELECTED_OUTPUT user number for use in subsequent calls to (GetSelectedOutputColumnCount, GetSelectedOutputFileName, GetSelectedOutputRowCount, GetSelectedOutputString, GetSelectedOutputStringLine, GetSelectedOutputStringLineCount, GetSelectedOutputValue, GetSelectedOutputValue2) routines. The initial setting after calling CreateIPhreeqc is 1.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
The current SELECTED_OUTPUT user number.
See also
GetNthSelectedOutputUserNumber, GetSelectedOutputCount, SetCurrentSelectedOutputUserNumber
Fortran90 Interface:
FUNCTION GetCurrentSelectedOutputUserNumber(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  INTEGER(KIND=4)               :: GetCurrentSelectedOutputUserNumber
END FUNCTION GetCurrentSelectedOutputUserNumber
const char* GetDumpFileName ( 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.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
filename The name of the file to write DUMP output to.
See also
GetDumpFileOn, GetDumpString, GetDumpStringOn, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileName, SetDumpFileOn, SetDumpStringOn
Fortran90 Interface:
SUBROUTINE GetDumpFileName(ID,FILENAME)
  INTEGER(KIND=4),   INTENT(IN)   :: ID
  CHARACTER(LEN=*),  INTENT(OUT)  :: FILENAME
END SUBROUTINE GetDumpFileName
int GetDumpFileOn ( int  id)

Retrieves the current value of the dump file switch.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
Non-zero if output is written to the DUMP (dump.id.out if unspecified) file, 0 (zero) otherwise.
See also
GetDumpString, GetDumpStringLine, GetDumpStringLineCount, GetDumpStringOn, SetDumpFileOn, SetDumpStringOn
Fortran90 Interface:
FUNCTION GetDumpFileOn(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  LOGICAL(KIND=4)               :: GetDumpFileOn
END FUNCTION GetDumpFileOn
const char* GetDumpString ( int  id)

Retrieves the string buffer containing DUMP output.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
A null terminated string containing DUMP output.
Precondition
SetDumpStringOn must have been set to true (non-zero) in order to receive DUMP output.
See also
GetDumpFileOn, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileOn, GetDumpStringOn, SetDumpStringOn
Fortran90 Interface:
Not implemented. (see GetDumpStringLineCount, GetDumpStringLine)

C Example:
#include <stdlib.h>
#include <stdio.h>
#include <IPhreeqc.h>
#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;
if (id < 0) {
return EXIT_FAILURE;
}
if (LoadDatabase(id, "phreeqc.dat") != 0) {
return EXIT_FAILURE;
}
if (SetDumpStringOn(id, TRUE) != IPQ_OK) {
return EXIT_FAILURE;
}
if (RunString(id, input) != 0) {
return EXIT_FAILURE;
}
printf("Dump:\n");
printf("%s\n", GetDumpString(id));
if (DestroyIPhreeqc(id) != IPQ_OK) {
return EXIT_FAILURE;
}
return EXIT_SUCCESS;
}
const char* GetDumpStringLine ( int  id,
int  n 
)

Retrieves the given dump line.

Parameters
idThe instance id returned from CreateIPhreeqc.
nThe zero-based index of the line to retrieve.
Returns
A null terminated string containing the given line. Returns an empty string if n is out of range.
Precondition
SetDumpStringOn must have been set to true (non-zero).
See also
GetDumpFileOn, GetDumpString, GetDumpStringLineCount, GetDumpStringOn, SetDumpFileOn, SetDumpStringOn
Fortran90 Interface:
(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

Fortran90 Example:
PROGRAM example
USE iphreeqc
INTEGER(KIND=4) :: id
INTEGER(KIND=4) :: i
CHARACTER(LEN=80) :: line
id = createiphreeqc()
IF (id.LT.0) THEN
stop
END IF
IF (setdumpstringon(id, .true.).NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (loaddatabase(id, "phreeqc.dat").NE.0) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "SOLUTION 1 Pure water").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "EQUILIBRIUM_PHASES 1").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, " Calcite 0 10").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "SAVE solution 1").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "SAVE equilibrium_phases 1").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "DUMP").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, " -solution 1").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, " -equilibrium_phases 1").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
WRITE(*,*) "Input:"
CALL outputaccumulatedlines(id)
IF (runaccumulated(id).NE.0) THEN
CALL outputerrorstring(id)
stop
END IF
WRITE(*,*) "Dump:"
DO i=1,getdumpstringlinecount(id)
CALL getdumpstringline(id, i, line)
WRITE(*,*) trim(line)
END DO
IF (destroyiphreeqc(id).NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
END PROGRAM example
int GetDumpStringLineCount ( int  id)

Retrieves the number of lines in the current dump string buffer.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
The number of lines.
Precondition
SetDumpStringOn must have been set to true (non-zero).
See also
GetDumpFileOn, GetDumpString, GetDumpStringLine, GetDumpStringOn, SetDumpFileOn, SetDumpStringOn
Fortran90 Interface:
FUNCTION GetDumpStringLineCount(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  INTEGER(KIND=4)               :: GetDumpStringLineCount
END FUNCTION GetDumpStringLineCount
Fortran90 Example:
see GetDumpStringLine
int GetDumpStringOn ( int  id)

Retrieves the current value of the dump string switch.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
Non-zero if output defined by the DUMP keyword is stored, 0 (zero) otherwise.
See also
GetDumpFileOn, GetDumpString, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileOn, SetDumpStringOn
Fortran90 Interface:
FUNCTION GetDumpStringOn(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  LOGICAL(KIND=4)               :: GetDumpStringOn
END FUNCTION GetDumpStringOn
const char* GetErrorFileName ( int  id)

Retrieves the name of the error file. The default name is phreeqc.id.err.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
filename The name of the error file.
See also
GetErrorFileOn, GetErrorString, GetErrorStringOn, GetErrorStringLine, GetErrorStringLineCount, SetErrorFileName, SetErrorFileOn, SetErrorStringOn
Fortran90 Interface:
SUBROUTINE GetErrorFileName(ID,FILENAME)
  INTEGER(KIND=4),   INTENT(IN)   :: ID
  CHARACTER(LEN=*),  INTENT(OUT)  :: FILENAME
END SUBROUTINE GetErrorFileName
int GetErrorFileOn ( int  id)

Retrieves the current value of the error file switch.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
Non-zero if errors are written to the phreeqc.id.err file, 0 (zero) otherwise.
See also
SetErrorFileOn
Fortran90 Interface:
FUNCTION GetErrorFileOn(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  LOGICAL(KIND=4)               :: GetErrorFileOn
END FUNCTION GetErrorFileOn
const char* GetErrorString ( int  id)

Retrieves the error messages from the last call to RunAccumulated, RunFile, RunString, LoadDatabase, or LoadDatabaseString.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
A null terminated string containing error messages.
See also
GetErrorFileOn, GetErrorStringLine, GetErrorStringLineCount, OutputErrorString, SetErrorFileOn
Fortran90 Interface:
Not implemented. (see GetErrorStringLineCount, GetErrorStringLine, OutputErrorString)

C Example:
#include <stdlib.h>
#include <stdio.h>
#include <IPhreeqc.h>
#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;
if (id < 0) {
return EXIT_FAILURE;
}
if (SetErrorStringOn(id, TRUE) != IPQ_OK) {
return EXIT_FAILURE;
}
if (RunString(id, input) != 0) {
printf("Error:\n");
printf("%s\n", GetErrorString(id));
return EXIT_FAILURE;
}
if (DestroyIPhreeqc(id) != IPQ_OK) {
return EXIT_FAILURE;
}
return EXIT_SUCCESS;
}
const char* GetErrorStringLine ( int  id,
int  n 
)

Retrieves the given error line.

Parameters
idThe instance id returned from CreateIPhreeqc.
nThe zero-based index of the line to retrieve.
Returns
A null terminated string containing the given line of the error string buffer.
See also
GetErrorFileOn, GetErrorString, GetErrorStringLineCount, OutputErrorString, SetErrorFileOn
Fortran90 Interface:
(Note: N is one-based for the Fortran 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 GetErrorStringLine

Fortran90 Example:
PROGRAM example
USE iphreeqc
INTEGER(KIND=4) :: id
INTEGER(KIND=4) :: i
CHARACTER(LEN=80) :: line
id = createiphreeqc()
IF (id.LT.0) THEN
stop
END IF
IF (seterrorstringon(id, .true.).NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "SOLUTION 1 Pure water").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "EQUILIBRIUM_PHASES 1").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, " Calcite 0 10").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "SAVE solution 1").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "SAVE equilibrium_phases 1").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
WRITE(*,*) "Input:"
CALL outputaccumulatedlines(id)
IF (runaccumulated(id).NE.0) THEN
WRITE(*,*) "Error:"
DO i=1,geterrorstringlinecount(id)
CALL geterrorstringline(id, i, line)
WRITE(*,*) trim(line)
END DO
stop
END IF
IF (destroyiphreeqc(id).NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
END PROGRAM example
int GetErrorStringLineCount ( int  id)

Retrieves the number of lines in the current error string buffer.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
The number of lines.
See also
GetErrorFileOn, GetErrorString, GetErrorStringLine, OutputErrorString, SetErrorFileOn
Fortran90 Interface:
FUNCTION GetErrorStringLineCount(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  INTEGER(KIND=4)               :: GetErrorStringLineCount
END FUNCTION GetErrorStringLineCount
int GetErrorStringOn ( int  id)

Retrieves the current value of the error string switch.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
Non-zero if output is stored, 0 (zero) otherwise.
See also
GetErrorFileOn, GetErrorString, GetErrorStringLine, GetErrorStringLineCount, SetErrorFileOn, SetErrorStringOn
Fortran90 Interface:
FUNCTION GetErrorStringOn(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  LOGICAL(KIND=4)               :: GetErrorStringOn
END FUNCTION GetErrorStringOn
const char* GetLogFileName ( int  id)

Retrieves the name of the log file. The default name is phreeqc.id.log.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
filename The name of the log file.
See also
GetLogFileOn, GetLogString, GetLogStringOn, GetLogStringLine, GetLogStringLineCount, SetLogFileName, SetLogFileOn, SetLogStringOn
Fortran90 Interface:
SUBROUTINE GetLogFileName(ID,FILENAME)
  INTEGER(KIND=4),   INTENT(IN)   :: ID
  CHARACTER(LEN=*),  INTENT(OUT)  :: FILENAME
END SUBROUTINE GetLogFileName
int GetLogFileOn ( int  id)

Retrieves the current value of the log file switch.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
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 also
SetLogFileOn
Fortran90 Interface:
FUNCTION GetLogFileOn(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  LOGICAL(KIND=4)               :: GetLogFileOn
END FUNCTION GetLogFileOn
const char* GetLogString ( int  id)

Retrieves the string buffer containing log output.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
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.
Precondition
SetLogStringOn must have been set to true (non-zero) in order to receive log output.
See also
GetLogFileOn, GetLogStringLine, GetLogStringLineCount, SetLogFileOn, GetLogStringOn, SetLogStringOn
Fortran90 Interface:
Not implemented. (see GetLogStringLineCount, GetLogStringLine)

C Example:
#include <stdlib.h>
#include <stdio.h>
#include <IPhreeqc.h>
#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"
"KNOBS \n"
" -logfile TRUE \n";
int main(void)
{
int id;
if (id < 0) {
return EXIT_FAILURE;
}
if (LoadDatabase(id, "phreeqc.dat") != 0) {
return EXIT_FAILURE;
}
if (SetLogStringOn(id, TRUE) != IPQ_OK) {
return EXIT_FAILURE;
}
if (RunString(id, input) != 0) {
return EXIT_FAILURE;
}
printf("Log:\n");
printf("%s\n", GetLogString(id));
if (DestroyIPhreeqc(id) != IPQ_OK) {
return EXIT_FAILURE;
}
return EXIT_SUCCESS;
}
const char* GetLogStringLine ( int  id,
int  n 
)

Retrieves the given log line.

Parameters
idThe instance id returned from CreateIPhreeqc.
nThe zero-based index of the line to retrieve.
Returns
A null terminated string containing the given line. Returns an empty string if n is out of range.
Precondition
SetLogStringOn must have been set to true (non-zero).
See also
GetLogFileOn, GetLogString, GetLogStringLineCount, GetLogStringOn, SetLogFileOn, SetLogStringOn
Fortran90 Interface:
(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

Fortran90 Example:
PROGRAM example
USE iphreeqc
INTEGER(KIND=4) :: id
INTEGER(KIND=4) :: i
CHARACTER(LEN=80) :: line
id = createiphreeqc()
IF (id.LT.0) THEN
stop
END IF
IF (setlogstringon(id, .true.).NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (loaddatabase(id, "phreeqc.dat").NE.0) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "SOLUTION 1 Pure water").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "EQUILIBRIUM_PHASES 1").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, " Calcite 0 10").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "SAVE solution 1").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "SAVE equilibrium_phases 1").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "DUMP").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, " -solution 1").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, " -equilibrium_phases 1").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "KNOBS").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, " -logfile TRUE").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
WRITE(*,*) "Input:"
CALL outputaccumulatedlines(id)
IF (runaccumulated(id).NE.0) THEN
CALL outputerrorstring(id)
stop
END IF
WRITE(*,*) "Log:"
DO i=1,getlogstringlinecount(id)
CALL getlogstringline(id, i, line)
WRITE(*,*) trim(line)
END DO
IF (destroyiphreeqc(id).NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
END PROGRAM example
int GetLogStringLineCount ( int  id)

Retrieves the number of lines in the current log string buffer.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
The number of lines.
Precondition
SetLogStringOn must have been set to true (non-zero).
See also
GetLogFileOn, GetLogString, GetLogStringLine, GetLogStringOn, SetLogFileOn, SetLogStringOn
Fortran90 Interface:
FUNCTION GetLogStringLineCount(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  INTEGER(KIND=4)               :: GetLogStringLineCount
END FUNCTION GetLogStringLineCount
Fortran90 Example:
see GetLogStringLine
int GetLogStringOn ( int  id)

Retrieves the current value of the log string switch.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
Non-zero if output is stored, 0 (zero) otherwise.
See also
GetLogFileOn, GetLogString, GetLogStringLine, GetLogStringLineCount, SetLogFileOn, SetLogStringOn
Fortran90 Interface:
FUNCTION GetLogStringOn(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  LOGICAL(KIND=4)               :: GetLogStringOn
END FUNCTION GetLogStringOn
int GetNthSelectedOutputUserNumber ( int  id,
int  n 
)

Retrieves the nth user number of the currently defined SELECTED_OUTPUT keyword blocks.

Parameters
idThe instance id returned from CreateIPhreeqc.
nThe zero-based index of the SELECTED_OUTPUT user number to retrieve.
Returns
The nth defined user number; a negative value indicates an error occured.
See also
GetCurrentSelectedOutputUserNumber, GetSelectedOutputCount, SetCurrentSelectedOutputUserNumber
Precondition
RunAccumulated, RunFile, RunString must have been called and returned 0 (zero) errors.
Fortran90 Interface:
(Note: N is one-based for the Fortran interface.)
FUNCTION GetNthSelectedOutputUserNumber(ID,N)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  INTEGER(KIND=4),  INTENT(IN)  :: N
  INTEGER(KIND=4)               :: GetNthSelectedOutputUserNumber
END FUNCTION GetNthSelectedOutputUserNumber
C Example:
see SetCurrentSelectedOutputUserNumber
const char* GetOutputFileName ( int  id)

Retrieves the name of the output file. The default name is phreeqc.id.out.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
filename The name of the output file.
See also
GetOutputFileOn, GetOutputString, GetOutputStringOn, GetOutputStringLine, GetOutputStringLineCount, SetOutputFileName, SetOutputFileOn, SetOutputStringOn
Fortran90 Interface:
SUBROUTINE GetOutputFileName(ID,FILENAME)
  INTEGER(KIND=4),   INTENT(IN)   :: ID
  CHARACTER(LEN=*),  INTENT(OUT)  :: FILENAME
END SUBROUTINE GetOutputFileName
int GetOutputFileOn ( int  id)

Retrieves the current value of the output file switch.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
Non-zero if output is written to the phreeqc.id.out file, 0 (zero) otherwise.
See also
SetOutputFileOn
Fortran90 Interface:
FUNCTION GetOutputFileOn(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  LOGICAL(KIND=4)               :: GetOutputFileOn
END FUNCTION GetOutputFileOn
const char* GetOutputString ( int  id)

Retrieves the string buffer containing phreeqc output.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
A null terminated string containing phreeqc output.
Precondition
SetOutputStringOn must have been set to true (non-zero) in order to receive phreeqc output.
See also
GetOutputFileOn, GetOutputStringLine, GetOutputStringLineCount, SetOutputFileOn, GetOutputStringOn, SetOutputStringOn
Fortran90 Interface:
Not implemented. (see GetOutputStringLineCount, GetOutputStringLine)

C Example:
#include <stdlib.h>
#include <stdio.h>
#include <IPhreeqc.h>
#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;
if (id < 0) {
return EXIT_FAILURE;
}
if (LoadDatabase(id, "phreeqc.dat") != 0) {
return EXIT_FAILURE;
}
if (SetOutputStringOn(id, TRUE) != IPQ_OK) {
return EXIT_FAILURE;
}
if (RunString(id, input) != 0) {
return EXIT_FAILURE;
}
printf("Output:\n");
printf("%s\n", GetOutputString(id));
if (DestroyIPhreeqc(id) != IPQ_OK) {
return EXIT_FAILURE;
}
return EXIT_SUCCESS;
}
const char* GetOutputStringLine ( int  id,
int  n 
)

Retrieves the given output line.

Parameters
idThe instance id returned from CreateIPhreeqc.
nThe zero-based index of the line to retrieve.
Returns
A null terminated string containing the given line. Returns an empty string if n is out of range.
Precondition
SetOutputStringOn must have been set to true (non-zero).
See also
GetOutputFileOn, GetOutputString, GetOutputStringLineCount, GetOutputStringOn, SetOutputFileOn, SetOutputStringOn
Fortran90 Interface:
(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

Fortran90 Example:
PROGRAM example
USE iphreeqc
INTEGER(KIND=4) :: id
INTEGER(KIND=4) :: i
CHARACTER(LEN=80) :: line
id = createiphreeqc()
IF (id.LT.0) THEN
stop
END IF
IF (setoutputstringon(id, .true.).NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (loaddatabase(id, "phreeqc.dat").NE.0) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "SOLUTION 1 Pure water").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "EQUILIBRIUM_PHASES 1").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, " Calcite 0 10").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "SAVE solution 1").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "SAVE equilibrium_phases 1").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, "DUMP").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, " -solution 1").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (accumulateline(id, " -equilibrium_phases 1").NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
WRITE(*,*) "Input:"
CALL outputaccumulatedlines(id)
IF (runaccumulated(id).NE.0) THEN
CALL outputerrorstring(id)
stop
END IF
WRITE(*,*) "Output:"
DO i=1,getoutputstringlinecount(id)
CALL getoutputstringline(id, i, line)
WRITE(*,*) trim(line)
END DO
IF (destroyiphreeqc(id).NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
END PROGRAM example
int GetOutputStringLineCount ( int  id)

Retrieves the number of lines in the current output string buffer.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
The number of lines.
Precondition
SetOutputStringOn must have been set to true (non-zero).
See also
GetOutputFileOn, GetOutputString, GetOutputStringLine, GetOutputStringOn, SetOutputFileOn, SetOutputStringOn
Fortran90 Interface:
FUNCTION GetOutputStringLineCount(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  INTEGER(KIND=4)               :: GetOutputStringLineCount
END FUNCTION GetOutputStringLineCount
Fortran90 Example:
see GetOutputStringLine
int GetOutputStringOn ( int  id)

Retrieves the current value of the output string switch.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
Non-zero if output is stored, 0 (zero) otherwise.
See also
GetOutputFileOn, GetOutputString, GetOutputStringLine, GetOutputStringLineCount, SetOutputFileOn, SetOutputStringOn
Fortran90 Interface:
FUNCTION GetOutputStringOn(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  LOGICAL(KIND=4)               :: GetOutputStringOn
END FUNCTION GetOutputStringOn
int GetSelectedOutputColumnCount ( int  id)

Retrieves the number of columns in the selected-output buffer.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
The number of columns.
See also
GetSelectedOutputFileOn, GetSelectedOutputRowCount, GetSelectedOutputValue, SetSelectedOutputFileOn
Fortran90 Interface:
FUNCTION GetSelectedOutputColumnCount(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  INTEGER(KIND=4)               :: GetSelectedOutputColumnCount
END FUNCTION GetSelectedOutputColumnCount
int GetSelectedOutputCount ( int  id)

Retrieves the count of SELECTED_OUTPUT blocks that are currently defined.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
The number of SELECTED_OUTPUT blocks.
See also
GetCurrentSelectedOutputUserNumber, GetNthSelectedOutputUserNumber, SetCurrentSelectedOutputUserNumber
Precondition
(RunAccumulated, RunFile, RunString) must have been called and returned 0 (zero) errors.
Fortran90 Interface:
FUNCTION GetSelectedOutputCount(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  INTEGER(KIND=4)               :: GetSelectedOutputCount
END FUNCTION GetSelectedOutputCount
C Example:
see SetCurrentSelectedOutputUserNumber
const char* GetSelectedOutputFileName ( int  id)

Retrieves the name of the current selected output file (see SetCurrentSelectedOutputUserNumber). This file name is used if not specified within SELECTED_OUTPUT input. The default value is selected_n.id.out.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
filename The name of the file to write SELECTED_OUTPUT output to.
See also
GetSelectedOutputFileOn, GetSelectedOutputString, GetSelectedOutputStringOn, GetSelectedOutputStringLine, GetSelectedOutputStringLineCount, SetCurrentSelectedOutputUserNumber, SetSelectedOutputFileName, SetSelectedOutputFileOn, SetSelectedOutputStringOn
Fortran90 Interface:
SUBROUTINE GetSelectedOutputFileName(ID,FILENAME)
  INTEGER(KIND=4),   INTENT(IN)   :: ID
  CHARACTER(LEN=*),  INTENT(OUT)  :: FILENAME
END SUBROUTINE GetSelectedOutputFileName
int GetSelectedOutputFileOn ( int  id)

Retrieves the current selected-output file switch (see SetCurrentSelectedOutputUserNumber).

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
Non-zero if output is written to the selected-output (selected_n.id.out if unspecified) file, 0 (zero) otherwise.
See also
GetSelectedOutputColumnCount, GetSelectedOutputRowCount, GetSelectedOutputValue, SetCurrentSelectedOutputUserNumber, SetSelectedOutputFileOn
Fortran90 Interface:
FUNCTION GetSelectedOutputFileOn(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  LOGICAL(KIND=4)               :: GetSelectedOutputFileOn
END FUNCTION GetSelectedOutputFileOn
int GetSelectedOutputRowCount ( int  id)

Retrieves the number of rows in the current selected-output buffer (see SetCurrentSelectedOutputUserNumber).

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
The number of rows.
See also
GetSelectedOutputFileOn, GetSelectedOutputColumnCount, GetSelectedOutputValue, SetCurrentSelectedOutputUserNumber, SetSelectedOutputFileOn
Fortran90 Interface:
FUNCTION GetSelectedOutputRowCount(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  INTEGER(KIND=4)               :: GetSelectedOutputRowCount
END FUNCTION GetSelectedOutputRowCount
const char* GetSelectedOutputString ( int  id)

Retrieves the string buffer containing the current SELECTED_OUTPUT (see SetCurrentSelectedOutputUserNumber).

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
A null terminated string containing SELECTED_OUTPUT.
Precondition
SetSelectedOutputStringOn must have been set to true (non-zero) in order to receive SELECTED_OUTPUT.
See also
GetSelectedOutputFileOn, GetSelectedOutputStringLine, GetSelectedOutputStringLineCount, GetSelectedOutputStringOn, SetSelectedOutputFileOn, SetCurrentSelectedOutputUserNumber SetSelectedOutputStringOn
Fortran90 Interface:
Not implemented. (see GetSelectedOutputStringLineCount, GetSelectedOutputStringLine)

C Example:
#include <stdlib.h>
#include <stdio.h>
#include <IPhreeqc.h>
#define TRUE 1
int main(void)
{
int id;
if (id < 0) {
return EXIT_FAILURE;
}
if (SetSelectedOutputStringOn(id, TRUE) != IPQ_OK) {
return EXIT_FAILURE;
}
if (LoadDatabase(id, "phreeqc.dat") != 0) {
return EXIT_FAILURE;
}
if (RunFile(id, "ex2") != 0) {
return EXIT_FAILURE;
}
printf("selected-output:\n");
printf("%s\n", GetSelectedOutputString(id));
if (DestroyIPhreeqc(id)) {
return EXIT_FAILURE;
}
return EXIT_SUCCESS;
}
const char* GetSelectedOutputStringLine ( int  id,
int  n 
)

Retrieves the given line of the current selected output string (see SetCurrentSelectedOutputUserNumber).

Parameters
idThe instance id returned from CreateIPhreeqc.
nThe zero-based index of the line to retrieve.
Returns
A null terminated string containing the given line. Returns an empty string if n is out of range.
Precondition
SetSelectedOutputStringOn must have been set to true (non-zero).
See also
GetSelectedOutputFileOn, GetSelectedOutputString, GetSelectedOutputStringLineCount, GetSelectedOutputStringOn, SetCurrentSelectedOutputUserNumber, SetSelectedOutputFileOn, SetSelectedOutputStringOn
Fortran90 Interface:
(Note: N is one-based for the Fortran interface.)
SUBROUTINE GetSelectedOutputStringLine(ID,N,LINE)
  INTEGER(KIND=4),   INTENT(IN)   :: ID
  INTEGER(KIND=4),   INTENT(IN)   :: N
  CHARACTER(LEN=*),  INTENT(OUT)  :: LINE
END SUBROUTINE GetSelectedOutputStringLine

Fortran90 Example:
PROGRAM example
USE iphreeqc
INTEGER(KIND=4) :: id
INTEGER(KIND=4) :: i
CHARACTER(LEN=400):: line
id = createiphreeqc()
IF (id.LT.0) THEN
stop
END IF
IF (setselectedoutputstringon(id, .true.).NE.ipq_ok) THEN
CALL outputerrorstring(id)
stop
END IF
IF (loaddatabase(id, "phreeqc.dat").NE.0) THEN
CALL outputerrorstring(id)
stop
END IF
IF (runfile(id, "ex2").NE.0) THEN
CALL outputerrorstring(id)
stop
END IF
WRITE(*,*) "selected-output:"
DO i=1,getselectedoutputstringlinecount(id)
CALL getselectedoutputstringline(id, i, line)
WRITE(*,*) trim(line)
END DO
IF (destroyiphreeqc(id).NE.ipq_ok) THEN
stop
END IF
END PROGRAM example
int GetSelectedOutputStringLineCount ( int  id)

Retrieves the number of lines in the current selected output string buffer (see SetCurrentSelectedOutputUserNumber).

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
The number of lines.
Precondition
SetSelectedOutputStringOn must have been set to true (non-zero).
See also
GetSelectedOutputFileOn, GetSelectedOutputString, GetSelectedOutputStringLine, GetSelectedOutputStringOn, SetCurrentSelectedOutputUserNumber, SetSelectedOutputFileOn, SetSelectedOutputStringOn
Fortran90 Interface:
FUNCTION GetSelectedOutputStringLineCount(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  INTEGER(KIND=4)               :: GetSelectedOutputStringLineCount
END FUNCTION GetSelectedOutputStringLineCount
Fortran90 Example:
see GetSelectedOutputStringLine
int GetSelectedOutputStringOn ( int  id)

Retrieves the value of the current selected output string switch (see SetCurrentSelectedOutputUserNumber).

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
Non-zero if output defined by the SELECTED_OUTPUT keyword is stored, 0 (zero) otherwise.
See also
GetSelectedOutputFileOn, GetSelectedOutputString, GetSelectedOutputStringLine, GetSelectedOutputStringLineCount, SetCurrentSelectedOutputUserNumber, SetSelectedOutputFileOn, SetSelectedOutputStringOn
Fortran90 Interface:
FUNCTION GetSelectedOutputStringOn(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  LOGICAL(KIND=4)               :: GetSelectedOutputStringOn
END FUNCTION GetSelectedOutputStringOn
IPQ_RESULT GetSelectedOutputValue ( int  id,
int  row,
int  col,
VAR pVAR 
)

Returns the VAR associated with the specified row and column. The current SELECTED_OUTPUT block is set using the SetCurrentSelectedOutputUserNumber method.

Parameters
idThe instance id returned from CreateIPhreeqc.
rowThe row index.
colThe column index.
pVARPointer to the VAR to receive the requested data.
Return values
IPQ_OKSuccess.
IPQ_INVALIDROWThe given row is out of range.
IPQ_INVALIDCOLThe given column is out of range.
IPQ_OUTOFMEMORYMemory could not be allocated.
IPQ_BADINSTANCEThe given id is invalid.
See also
GetCurrentSelectedOutputUserNumber, GetSelectedOutputFileOn, GetSelectedOutputColumnCount, GetSelectedOutputRowCount, GetSelectedOutputValue2, SetCurrentSelectedOutputUserNumber, SetSelectedOutputFileOn
Remarks
Row 0 contains the column headings to the selected_ouput.
Examples:
The headings will include a suffix and/or prefix in order to differentiate the columns.

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
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.
    FUNCTION GetSelectedOutputValue(ID,ROW,COL,VTYPE,DVALUE,SVALUE,SLENGTH)
      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),   INTENT(OUT), OPTIONAL :: SLENGTH
      INTEGER(KIND=4)                          :: GetSelectedOutputValue
    END FUNCTION GetSelectedOutputValue
    
Parameters
IDThe instance id returned from CreateIPhreeqc.
ROWThe row index.
COLThe column index.
VTYPEReturns the variable type. See VAR_TYPE.
DVALUEReturns the numeric value when (VTYPE=TT_DOUBLE) or (VTYPE=TT_LONG).
SVALUEReturns the string variable when (VTYPE=TT_STRING). When (VTYPE=TT_DOUBLE) or (VTYPE=TT_LONG) this variable is filled with a string equivalent of DVALUE.
SLENGTHOptional, if the length of SVALUE isn't sufficient to hold the entire string value, returns the required length, otherwise returns 0 (zero).
C Example:
#include <stdlib.h>
#include <stdio.h>
#include <IPhreeqc.h>
int main(void)
{
int id, i, j;
if (id < 0) {
return EXIT_FAILURE;
}
if (LoadDatabase(id, "phreeqc.dat") != 0) {
return EXIT_FAILURE;
}
if (RunFile(id, "ex2") != 0) {
return EXIT_FAILURE;
}
VAR v;
VarInit(&v);
printf("selected-output:\n");
for (i = 0; i < GetSelectedOutputRowCount(id); ++i) {
for (j = 0; j < GetSelectedOutputColumnCount(id); ++j) {
if (GetSelectedOutputValue(id, i, j, &v) == IPQ_OK) {
switch (v.type) {
case TT_LONG:
printf("%ld ", v.lVal);
break;
case TT_DOUBLE:
printf("%g ", v.dVal);
break;
case TT_STRING:
printf("%s ", v.sVal);
break;
case TT_EMPTY:
printf("<empty> ");
break;
case TT_ERROR:
printf("<error> ");
break;
}
}
VarClear(&v);
}
printf("\n");
}
if (DestroyIPhreeqc(id)) {
return EXIT_FAILURE;
}
return EXIT_SUCCESS;
}

Fortran90 Example:
PROGRAM example
USE iphreeqc
INTEGER(KIND=4) :: id
INTEGER(KIND=4) :: i
INTEGER(KIND=4) :: j
INTEGER(KIND=4) :: vt
REAL(KIND=8) :: dv
CHARACTER(LEN=40) :: sv
INTEGER(KIND=4) :: sl
id = createiphreeqc()
IF (id.LT.0) THEN
stop
END IF
IF (loaddatabase(id, "phreeqc.dat").NE.0) THEN
CALL outputerrorstring(id)
stop
END IF
IF (runfile(id, "ex2").NE.0) THEN
CALL outputerrorstring(id)
stop
END IF
WRITE(*,*) "selected-output:"
DO i=0,getselectedoutputrowcount(id)
DO j=1,getselectedoutputcolumncount(id)
IF (getselectedoutputvalue(id, i, j, vt, dv, sv, sl).EQ.ipq_ok) THEN
IF (vt.EQ.tt_double) THEN
WRITE(*,"(g12.6,A1)",advance="NO") dv, " "
ELSE IF (vt.EQ.tt_string) THEN
IF (sl.EQ.0) THEN
WRITE(*,"(A12,A1)",advance="NO") sv, " "
ELSE
WRITE(*,"(A12,A1)",advance="NO") "#ERR", " "
END IF
END IF
END IF
END DO
WRITE(*,*)
END DO
IF (destroyiphreeqc(id).NE.ipq_ok) THEN
stop
END IF
END PROGRAM example
IPQ_RESULT GetSelectedOutputValue2 ( int  id,
int  row,
int  col,
int *  vtype,
double *  dvalue,
char *  svalue,
unsigned int  svalue_length 
)

Returns the associated data with the specified row and column. The current SELECTED_OUTPUT block is set using the SetCurrentSelectedOutputUserNumber method.

Parameters
idThe instance id returned from CreateIPhreeqc.
rowThe row index.
colThe column index.
vtypeReceives the variable type. See VAR_TYPE.
dvalueReceives the numeric value when (VTYPE=TT_DOUBLE) or (VTYPE=TT_LONG).
svalueReceives the string variable when (VTYPE=TT_STRING). When (VTYPE=TT_DOUBLE) or (VTYPE=TT_LONG) this variable is filled with a string equivalent of DVALUE.
svalue_lengthThe length of the svalue buffer.
Return values
IPQ_OKSuccess.
IPQ_INVALIDROWThe given row is out of range.
IPQ_INVALIDCOLThe given column is out of range.
IPQ_OUTOFMEMORYMemory could not be allocated.
IPQ_BADINSTANCEThe given id is invalid.
See also
GetCurrentSelectedOutputUserNumber, GetSelectedOutputFileOn, GetSelectedOutputColumnCount, GetSelectedOutputRowCount, GetSelectedOutputValue, SetCurrentSelectedOutputUserNumber, SetSelectedOutputFileOn
Remarks
Row 0 contains the column headings to the selected_ouput.
Examples:
The headings will include a suffix and/or prefix in order to differentiate the columns.

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
C Example:
#include <stdlib.h>
#include <stdio.h>
#include <IPhreeqc.h>
const int SVALUE_LENGTH = 100;
int main(void)
{
int id, i, j, vtype;
double dvalue;
char svalue[SVALUE_LENGTH];
if (id < 0) {
return EXIT_FAILURE;
}
if (LoadDatabase(id, "phreeqc.dat") != 0) {
return EXIT_FAILURE;
}
if (RunFile(id, "ex2") != 0) {
return EXIT_FAILURE;
}
printf("selected-output:\n");
for (i = 0; i < GetSelectedOutputRowCount(id); ++i) {
for (j = 0; j < GetSelectedOutputColumnCount(id); ++j) {
if (GetSelectedOutputValue2(id, i, j, &vtype, &dvalue, svalue, SVALUE_LENGTH) == IPQ_OK) {
switch (vtype) {
case TT_LONG:
printf("%ld ", (long)dvalue);
break;
case TT_DOUBLE:
printf("%g ", dvalue);
break;
case TT_STRING:
printf("%s ", svalue);
break;
case TT_EMPTY:
printf("<empty> ");
break;
}
}
}
printf("\n");
}
if (DestroyIPhreeqc(id)) {
return EXIT_FAILURE;
}
return EXIT_SUCCESS;
}
const char* GetVersionString ( void  )

Retrieves the string buffer containing the version in the form of X.X.X-XXXX.

Returns
A null terminated string containing the IPhreeqc version number.
Fortran90 Interface:
SUBROUTINE GetVersionString(VERSION)
  CHARACTER(LEN=*), INTENT(OUT) :: VERSION
END SUBROUTINE GetVersionString
C Example:
#include <stdlib.h>
#include <stdio.h>
#include <IPhreeqc.h>
int main(void)
{
printf("Version:\n");
printf("%s\n", GetVersionString());
return EXIT_SUCCESS;
}
Fortran90 Example:
PROGRAM example
USE iphreeqc
CHARACTER(LEN=80) :: version
WRITE(*,*) "Version:"
CALL getversionstring(version)
WRITE(*,*) trim(version)
END PROGRAM example
const char* GetWarningString ( int  id)

Retrieves the warning messages from the last call to (RunAccumulated, RunFile, RunString, LoadDatabase, or LoadDatabaseString).

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
A null terminated string containing warning messages.
See also
GetWarningStringLine, GetWarningStringLineCount, OutputWarningString
Fortran90 Interface:
Not implemented. (see GetWarningStringLineCount, GetWarningStringLine, OutputWarningString)
const char* GetWarningStringLine ( int  id,
int  n 
)

Retrieves the given warning line.

Parameters
idThe instance id returned from CreateIPhreeqc.
nThe zero-based index of the line to retrieve.
Returns
A null terminated string containing the given warning line message.
See also
GetWarningString, GetWarningStringLineCount, OutputWarningString
Fortran90 Interface:
(Note: N is one-based for the Fortran interface.)
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
int GetWarningStringLineCount ( int  id)

Retrieves the number of lines in the current warning string buffer.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
The number of lines.
See also
GetWarningString, GetWarningStringLine, OutputWarningString
Fortran90 Interface:
FUNCTION GetWarningStringLineCount(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  INTEGER(KIND=4)               :: GetWarningStringLineCount
END FUNCTION GetWarningStringLineCount
int LoadDatabase ( int  id,
const char *  filename 
)

Load the specified database file into phreeqc.

Parameters
idThe instance id returned from CreateIPhreeqc.
filenameThe 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.
Returns
The number of errors encountered.
See also
LoadDatabaseString
Remarks
All previous definitions are cleared.
Fortran90 Interface:
FUNCTION LoadDatabase(ID,FILENAME)
  INTEGER(KIND=4),   INTENT(IN)  :: ID
  CHARACTER(LEN=*),  INTENT(IN)  :: FILENAME
  INTEGER(KIND=4)                :: LoadDatabase
END FUNCTION LoadDatabase
C Example:
see CreateIPhreeqc
Fortran90 Example:
see CreateIPhreeqc
int LoadDatabaseString ( int  id,
const char *  input 
)

Load the specified string as a database into phreeqc.

Parameters
idThe instance id returned from CreateIPhreeqc.
inputString containing data to be used as the phreeqc database.
Returns
The number of errors encountered.
See also
LoadDatabase
Remarks
All previous definitions are cleared.
Fortran90 Interface:
FUNCTION LoadDatabaseString(ID,INPUT)
  INTEGER(KIND=4),   INTENT(IN)  :: ID
  CHARACTER(LEN=*),  INTENT(IN)  :: INPUT
  INTEGER(KIND=4)                :: LoadDatabaseString
END FUNCTION LoadDatabaseString
void OutputAccumulatedLines ( int  id)

Output the accumulated input buffer to stdout. This input buffer can be run with a call to RunAccumulated.

Parameters
idThe instance id returned from CreateIPhreeqc.
See also
AccumulateLine, ClearAccumulatedLines, RunAccumulated
Fortran90 Interface:
SUBROUTINE OutputAccumulatedLines(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
END SUBROUTINE OutputAccumulatedLines
Fortran90 Example:
see GetDumpStringLine
void OutputErrorString ( int  id)

Output the error messages normally stored in the phreeqc.id.err file to stdout.

Parameters
idThe instance id returned from CreateIPhreeqc.
See also
GetErrorFileOn, GetErrorStringLine, GetErrorStringLineCount, SetErrorFileOn
Fortran90 Interface:
SUBROUTINE OutputErrorString(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
END SUBROUTINE OutputErrorString
C Example:
see GetComponent
Fortran90 Example:
see GetDumpStringLine
void OutputWarningString ( int  id)

Output the warning messages to stdout.

Parameters
idThe instance id returned from CreateIPhreeqc.
See also
GetWarningString, GetWarningStringLine, GetWarningStringLineCount
Fortran90 Interface:
SUBROUTINE OutputWarningString(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
END SUBROUTINE OutputWarningString
int RunAccumulated ( int  id)

Runs the input buffer as defined by calls to AccumulateLine.

Parameters
idThe instance id returned from CreateIPhreeqc.
Returns
The number of errors encountered.
See also
AccumulateLine, ClearAccumulatedLines, OutputAccumulatedLines, RunFile, RunString
Remarks
The accumulated input is cleared at the next call to AccumulateLine.
Precondition
LoadDatabase/LoadDatabaseString must have been called and returned 0 (zero) errors.
Fortran90 Interface:
FUNCTION RunAccumulated(ID)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  INTEGER(KIND=4)               :: RunAccumulated
END FUNCTION RunAccumulated
Fortran90 Example:
see GetDumpStringLine
int RunFile ( int  id,
const char *  filename 
)

Runs the specified phreeqc input file.

Parameters
idThe instance id returned from CreateIPhreeqc.
filenameThe name of the phreeqc input file to run.
Returns
The number of errors encountered during the run.
See also
RunAccumulated, RunString
Precondition
(LoadDatabase, LoadDatabaseString) must have been called and returned 0 (zero) errors.
Fortran90 Interface:
FUNCTION RunFile(ID,FNAME)
  INTEGER(KIND=4),   INTENT(IN)  :: ID
  CHARACTER(LEN=*),  INTENT(IN)  :: FNAME
  INTEGER(KIND=4)                :: RunFile
END FUNCTION RunFile
C Example:
see CreateIPhreeqc
Fortran90 Example:
see CreateIPhreeqc
int RunString ( int  id,
const char *  input 
)

Runs the specified string as input to phreeqc.

Parameters
idThe instance id returned from CreateIPhreeqc.
inputString containing phreeqc input.
Returns
The number of errors encountered during the run.
See also
RunAccumulated, RunFile
Precondition
(LoadDatabase, LoadDatabaseString) must have been called and returned 0 (zero) errors.
Fortran90 Interface:
FUNCTION RunString(ID,INPUT)
  INTEGER(KIND=4),  INTENT(IN)   :: ID
  CHARACTER(LEN=*),  INTENT(IN)  :: INPUT
  INTEGER(KIND=4)                :: RunString
END FUNCTION RunString
C Example:
see GetDumpString
IPQ_RESULT SetBasicCallback ( int  id,
double(*)(double x1, double x2, const char *str, void *cookie)  fcn,
void *  cookie1 
)

Sets a C callback function for Basic programs. The syntax for the Basic command is 10 result = CALLBACK(x1, x2, string$) The syntax for the C function is double my_callback(double x1, double x2, const char * string)

Parameters
idThe instance id returned from CreateIPhreeqc.
fcnThe name of a user-defined function.
cookie1A user defined value to be passed to the callback function.
Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe given id is invalid.
Fortran90 Interface:
see SetBasicFortranCallback
C Example:
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <IPhreeqc.h>
#define TRUE 1
const char input[] =
"SOLUTION 1-2 \n"
"END \n"
"EQUILIBRIUM_PHASES 1 \n"
" CO2(g) -1.5 10 \n"
"EQUILIBRIUM_PHASES 2 \n"
" Calcite 0 10 \n"
"SELECTED_OUTPUT 1 \n"
" -reset false \n"
"USER_PUNCH \n"
" -Heading pH SR(calcite) Year \n"
" 10 PUNCH -LA(\"H+\"), SR(\"calcite\") \n"
" 20 PUNCH CALLBACK(cell_no, -LA(\"H+\"), \"Year\") \n"
"END \n"
"RUN_CELLS \n"
" -cells 1-2 \n"
"END \n";
struct MyData {
double year;
};
double MyCallback(double x1, double x2, const char *str1, void *mydata)
{
/*
Use of a callback is optional.
The callback provides a way to obtain data from a Basic program
through the variables x1, x2, and str1, and send data to a
Basic program through the return value of the callback.
The void pointer mydata can be used to obtain data from the
calling program; in this example, it points to a structure.
The callback function is called whenever CALLBACK(x1, x2, str$)
is used in a Basic program (usually USER_PUNCH).
*/
if (strcmp(str1, "Year") == 0)
{
fprintf(stderr, "Callback for cell %d: pH %8.2f\n", (int) x1, x2);
return ((struct MyData *) mydata)->year;
}
return -1;
}
int main(void)
{
int id;
struct MyData mydata;
mydata.year = 2012.0;
if (id < 0) {
return EXIT_FAILURE;
}
if (LoadDatabase(id, "phreeqc.dat") != 0) {
return EXIT_FAILURE;
}
if (SetSelectedOutputFileOn(id, TRUE) != IPQ_OK) {
return EXIT_FAILURE;
}
if (SetBasicCallback(id, MyCallback, &mydata) != IPQ_OK) {
return EXIT_FAILURE;
}
if (RunString(id, input) != 0) {
return EXIT_FAILURE;
}
return EXIT_SUCCESS;
}
IPQ_RESULT SetBasicFortranCallback ( int  id,
double(*)(double *x1, double *x2, const char *str, int l)  fcn 
)

Sets a Fortran callback function for Basic programs. The syntax for the Basic command is 10 result = CALLBACK(x1, x2, string$) The syntax for the Fortran function is REAL(KIND=C_DOUBLE) my_callback(x1, x2, string), where x1 and x2 are REAL(KIND=C_DOUBLE) and string is a CHARACTER(KIND=C_CHAR).

Parameters
idThe instance id returned from CreateIPhreeqc.
fcnThe name of a REAL(KIND=C_DOUBLE) Fortran function with three arguments (two REAL(KIND=C_DOUBLE), and one CHARACTER(KIND=C_CHAR)).
Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe given id is invalid.
Fortran90 Interface:
!
! if using  include files (IPhreeqc.f.inc or IPhreeqc.f90.inc)
!
#ifdef IPHREEQC_NO_FORTRAN_MODULE
FUNCTION SetBasicFortranCallback(ID,FCN)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  INTERFACE
    DOUBLE PRECISION FUNCTION FCN(x1, x2, str)
      DOUBLE PRECISION, INTENT(in) :: x1
      DOUBLE PRECISION, INTENT(in) :: x2
      CHARACTER(*), INTENT(in)     :: str
    END FUNCTION
  END INTERFACE
  INTEGER(KIND=4)               :: SetBasicFortranCallback
END FUNCTION SetBasicFortranCallback
#else
!
! if using the fortran module (USE IPhreeqc)
! must also add IPhreeqc_interface.F90 to your project
!
FUNCTION SetBasicFortranCallback(ID,FCN)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  INTERFACE
    REAL(KIND=C_DOUBLE) FUNCTION fcn(x1, x2, str, l) BIND(C)
      USE ISO_C_BINDING
      IMPLICIT none
      REAL(KIND=C_DOUBLE),    INTENT(in)        :: x1, x2
      CHARACTER(KIND=C_CHAR), INTENT(in)        :: str(*)
      INTEGER(KIND=C_INT),    INTENT(in), VALUE :: l
    END FUNCTION fcn
  END INTERFACE
END FUNCTION SetBasicFortranCallback
#endif
Fortran90 Example:
MODULE mydata
DOUBLE PRECISION year
END MODULE mydata
MODULE callback
CONTAINS
REAL(kind=C_DOUBLE) FUNCTION mycallback(x1, x2, str, l) BIND(C, name='MyCallback')
USE mydata, ONLY : year
USE iso_c_binding
!
! Use of a callback is optional.
!
! The callback provides a way to obtain data from a Basic program
! through the variables x1, x2, and str, and send data to a
! Basic program through the return value of the callback.
!
! The callback function is called whenever CALLBACK(x1, x2, str$)
! is used in a Basic program (usually USER_PUNCH). See file "ic".
!
REAL(kind=C_DOUBLE), INTENT(in) :: x1, x2
CHARACTER(kind=C_CHAR), INTENT(in) :: str(*)
INTEGER(kind=C_INT), INTENT(in), value :: l
character(len=l) fstr
mycallback = -1.0
! An example of a datum available in main program
do i = 1, l
fstr(i:i) = str(i)
enddo
IF (trim(fstr) .EQ. "Year") THEN
WRITE (*,"(/a,i2,a,f8.2)") "Callback for cell ", int(x1), ": pH ", x2
mycallback = year
ENDIF
RETURN
END FUNCTION mycallback
END MODULE callback
PROGRAM advect
USE callback
USE mydata
USE iphreeqc
INTEGER :: id
!Create module, load database, define initial conditions and selected output
year = 2012.
id = createiphreeqc()
IF (loaddatabase(id, "phreeqc.dat") .NE. 0) THEN
CALL outputerrorstring(id)
stop
ENDIF
IF (setselectedoutputfileon(id, .true.) .NE. 0) THEN
CALL outputerrorstring(id)
stop
ENDIF
IF (setbasicfortrancallback(id, mycallback) .NE. 0) THEN
CALL outputerrorstring(id)
stop
ENDIF
IF (runfile(id, "ic") .NE. 0) THEN
CALL outputerrorstring(id)
stop
ENDIF
!Destroy module
IF (destroyiphreeqc(id) .NE. 0) CALL outputerrorstring(id)
END PROGRAM advect
File ic :
SOLUTION 1-2
END
EQUILIBRIUM_PHASES 1
CO2(g) -1.5 10
EQUILIBRIUM_PHASES 2
Calcite 0 10
SELECTED_OUTPUT 1
-reset false
USER_PUNCH
-Heading pH SR(calcite) Year
10 PUNCH -LA("H+"), SR("calcite")
20 PUNCH CALLBACK(cell_no, -LA("H+"), "Year")
END
RUN_CELLS
-cells 1-2
END
IPQ_RESULT SetCurrentSelectedOutputUserNumber ( int  id,
int  n 
)

Sets the current SELECTED_OUTPUT user number for use in subsequent calls to (GetSelectedOutputColumnCount, GetSelectedOutputFileName, GetSelectedOutputRowCount, GetSelectedOutputString, GetSelectedOutputStringLine, GetSelectedOutputStringLineCount, GetSelectedOutputValue, GetSelectedOutputValue2) routines. The initial setting after calling CreateIPhreeqc is 1.

Parameters
idThe instance id returned from CreateIPhreeqc.
nThe user number specified in the SELECTED_OUTPUT block.
Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe given id is invalid.
IPQ_INVALIDARGThe given user number is invalid.
See also
GetSelectedOutputColumnCount, GetSelectedOutputFileName, GetSelectedOutputRowCount, GetSelectedOutputString, GetSelectedOutputStringLine, GetSelectedOutputStringLineCount, GetSelectedOutputValue
Fortran90 Interface:
FUNCTION SetCurrentSelectedOutputUserNumber(ID,N)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  INTEGER(KIND=4),  INTENT(IN)  :: N
  INTEGER(KIND=4)               :: SetCurrentSelectedOutputUserNumber
END FUNCTION SetCurrentSelectedOutputUserNumber

C Example:
#include <stdlib.h>
#include <stdio.h>
#include <IPhreeqc.h>
int main(void)
{
int id, i, n, r, c;
char buffer[30];
FILE* f;
VAR v;
if (id < 0) {
return EXIT_FAILURE;
}
if (LoadDatabase(id, "phreeqc.dat") != 0) {
return EXIT_FAILURE;
}
if (RunFile(id, "multi_punch") != 0) {
return EXIT_FAILURE;
}
VarInit(&v);
for (i = 0; i < GetSelectedOutputCount(id); ++i) {
sprintf(buffer, "sel_out.%d.out", n);
if ((f = fopen(buffer, "w"))) {
for (r = 0; r < GetSelectedOutputRowCount(id); ++r) {
for (c = 0; c < GetSelectedOutputColumnCount(id); ++c) {
if (GetSelectedOutputValue(id, r, c, &v) == IPQ_OK) {
switch (v.type) {
case TT_LONG:
fprintf(f, "%ld,", v.lVal);
break;
case TT_DOUBLE:
fprintf(f, "%g,", v.dVal);
break;
case TT_STRING:
fprintf(f, "%s,", v.sVal);
break;
default:
fprintf(f, ",");
break;
}
}
VarClear(&v);
}
fprintf(f, "\n");
}
fclose(f);
}
}
if (DestroyIPhreeqc(id) != IPQ_OK) {
return EXIT_FAILURE;
}
return EXIT_SUCCESS;
}
File multi_punch :
SOLUTION 1
pH 7 charge
Na 1
Cl 1
Ca 1
C 2
END
CALCULATE_VALUES
TOTAL_C
-start
10 save TOT("C")
-end
END
EQUILIBRIUM_PHASES 1
CO2(g) -2
Dolomite 0
END
REACTION 1
HCl 1
0.1 mmol
END
GAS_PHASE
-fixed_volume
N2(g) 1.2
END
KINETICS
Calcite
-tol 1e-8
-m0 3.e-3
-m 3.e-3
-parms 50 0.6
END
SOLID_SOLUTION
Sulfate
-comp Anhydrite 1.0
-comp Barite 1.0
END
RUN_CELLS
-cell 1
SELECTED_OUTPUT
-file multi_punch_1.sel
-reset false
-sim
-state
-solution
-dist
-time
-step
-pH
-pe
-reaction
-temperature
-alkalinity
-ionic_strength
-water
-charge_balance
-percent_error
-totals Na Ca
-molalities Na+ HCO3-
-activities Ca+2 CO3-2
-equilibrium_phases CO2(g) dolomite
-saturation_indices Halite
-gases N2(g)
-kinetics Calcite
-solid_solutions Anhydrite Barite
-calculate_values TOTAL_C
-inverse false
SELECTED_OUTPUT 2
-file multi_punch_2.sel
-si Halite Calcite
USER_PUNCH 20
-heading Dummy
10 PUNCH "Dummy"
END
USER_PUNCH 2
-heading DUMMY_1 DUMMY_2
10 PUNCH "Dummy1", "Dummy2"
RUN_CELLS
-cell 1
SELECTED_OUTPUT 1
-active false
END
RUN_CELLS
-cell 1
SELECTED_OUTPUT 1
-active true
END
SOLUTION 2
pH 7 charge
END
SOLUTION 3
pH 7 charge
Na 1
Cl 1
END
INVERSE_MODELING
-solution 2 3
-phases
Halite
SELECTED_OUTPUT 3
-reset false
-file multi_punch_3.sel
END
RUN_CELLS
-cell 1
IPQ_RESULT SetDumpFileName ( int  id,
const char *  filename 
)

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.

Parameters
idThe instance id returned from CreateIPhreeqc.
filenameThe name of the file to write DUMP output to.
Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe given id is invalid.
See also
GetDumpFileName, GetDumpFileOn, GetDumpString, GetDumpStringOn, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileOn, SetDumpStringOn
Fortran90 Interface:
FUNCTION SetDumpFileName(ID,FILENAME)
  INTEGER(KIND=4),   INTENT(IN)   :: ID
  CHARACTER(LEN=*),  INTENT(OUT)  :: FILENAME
  INTEGER(KIND=4)                 :: SetDumpFileName
END FUNCTION SetDumpFileName
IPQ_RESULT SetDumpFileOn ( int  id,
int  dump_on 
)

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 CreateIPhreeqc is off.

Parameters
idThe instance id returned from CreateIPhreeqc.
dump_onIf non-zero, turns on output to the DUMP (dump.id.out if unspecified) file; if zero, turns off output to the DUMP file.
Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe given id is invalid.
See also
GetDumpFileOn, GetDumpString, GetDumpStringLine, GetDumpStringOn, GetDumpStringLineCount, SetDumpStringOn
Fortran90 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
IPQ_RESULT SetDumpStringOn ( int  id,
int  dump_string_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 CreateIPhreeqc is off.

Parameters
idThe instance id returned from CreateIPhreeqc.
dump_string_onIf 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.
Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe given id is invalid.
See also
GetDumpFileOn, GetDumpStringOn, GetDumpString, GetDumpStringLine, GetDumpStringLineCount, SetDumpFileOn
Fortran90 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
C Example:
see GetDumpString
Fortran90 Example:
see GetDumpStringLine
IPQ_RESULT SetErrorFileName ( int  id,
const char *  filename 
)

Sets the name of the error file. The default value is phreeqc.id.err.

Parameters
idThe instance id returned from CreateIPhreeqc.
filenameThe name of the error file.
Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe given id is invalid.
See also
GetErrorFileName, GetErrorFileOn, GetErrorString, GetErrorStringOn, GetErrorStringLine, GetErrorStringLineCount, SetErrorFileOn, SetErrorStringOn
Fortran90 Interface:
FUNCTION SetErrorFileName(ID,FILENAME)
  INTEGER(KIND=4),   INTENT(IN)   :: ID
  CHARACTER(LEN=*),  INTENT(OUT)  :: FILENAME
  INTEGER(KIND=4)                 :: SetErrorFileName
END FUNCTION SetErrorFileName
IPQ_RESULT SetErrorFileOn ( int  id,
int  error_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 CreateIPhreeqc is off.

Parameters
idThe instance id returned from CreateIPhreeqc.
error_onIf non-zero, writes errors to the error file; if zero, no errors are written to the error file.
Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe given id is invalid.
See also
GetErrorFileOn, GetErrorStringLine, GetErrorStringLineCount, OutputErrorString
Fortran90 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
IPQ_RESULT SetErrorStringOn ( int  id,
int  error_string_on 
)

Sets the error string switch on or off. This switch controls whether or not the data normally sent to the error file are stored in a buffer for retrieval. The initial setting after calling CreateIPhreeqc is on.

Parameters
idThe instance id returned from CreateIPhreeqc.
error_string_onIf non-zero, captures the error output into a string buffer; if zero, error output is not captured to a string buffer.
Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe given id is invalid.
See also
GetErrorFileOn, GetErrorStringOn, GetErrorString, GetErrorStringLine, GetErrorStringLineCount, SetErrorFileOn
Fortran90 Interface:
FUNCTION SetErrorStringOn(ID,ERR_STRING_ON)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  LOGICAL(KIND=4),  INTENT(IN)  :: ERR_STRING_ON
  INTEGER(KIND=4)               :: SetErrorStringOn
END FUNCTION SetErrorStringOn
C Example:
see GetErrorString
Fortran90 Example:
see GetErrorStringLine
IPQ_RESULT SetLogFileName ( int  id,
const char *  filename 
)

Sets the name of the log file. The default value is phreeqc.id.log.

Parameters
idThe instance id returned from CreateIPhreeqc.
filenameThe name of the log file.
Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe given id is invalid.
See also
GetLogFileName, GetLogFileOn, GetLogString, GetLogStringOn, GetLogStringLine, GetLogStringLineCount, SetLogFileOn, SetLogStringOn
Fortran90 Interface:
FUNCTION SetLogFileName(ID,FILENAME)
  INTEGER(KIND=4),   INTENT(IN)   :: ID
  CHARACTER(LEN=*),  INTENT(OUT)  :: FILENAME
  INTEGER(KIND=4)                 :: SetLogFileName
END FUNCTION SetLogFileName
IPQ_RESULT SetLogFileOn ( int  id,
int  log_on 
)

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 CreateIPhreeqc is off.

Parameters
idThe instance id returned from CreateIPhreeqc.
log_onIf non-zero, log messages are written to the log file; if zero, no log messages are written to the log file.
Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe 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 also
GetLogFileOn
Fortran90 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
IPQ_RESULT SetLogStringOn ( int  id,
int  log_string_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 CreateIPhreeqc is off.

Parameters
idThe instance id returned from CreateIPhreeqc.
log_string_onIf non-zero, captures the log output into a string buffer; if zero, log output is not captured to a string buffer.
Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe given id is invalid.
See also
GetLogFileOn, GetLogStringOn, GetLogString, GetLogStringLine, GetLogStringLineCount, SetLogFileOn
Fortran90 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
C Example:
see GetLogString
Fortran90 Example:
see GetLogStringLine
IPQ_RESULT SetOutputFileName ( int  id,
const char *  filename 
)

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.

Parameters
idThe instance id returned from CreateIPhreeqc.
filenameThe name of the phreeqc output file.
Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe given id is invalid.
See also
GetOutputFileName, GetOutputFileOn, GetOutputString, GetOutputStringOn, GetOutputStringLine, GetOutputStringLineCount, SetOutputFileOn, SetOutputStringOn
Fortran90 Interface:
FUNCTION SetOutputFileName(ID,FILENAME)
  INTEGER(KIND=4),   INTENT(IN)   :: ID
  CHARACTER(LEN=*),  INTENT(OUT)  :: FILENAME
  INTEGER(KIND=4)                 :: SetOutputFileName
END FUNCTION SetOutputFileName
IPQ_RESULT SetOutputFileOn ( int  id,
int  output_on 
)

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 CreateIPhreeqc is off.

Parameters
idThe instance id returned from CreateIPhreeqc.
output_onIf non-zero, writes output to the output file; if zero, no output is written to the output file.
Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe given id is invalid.
See also
GetOutputFileOn
Fortran90 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
IPQ_RESULT SetOutputStringOn ( int  id,
int  output_string_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 CreateIPhreeqc is off.

Parameters
idThe instance id returned from CreateIPhreeqc.
output_string_onIf non-zero, captures the phreeqc output into a string buffer; if zero, phreeqc output is not captured to a string buffer.
Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe given id is invalid.
See also
GetOutputFileOn, GetOutputStringOn, GetOutputString, GetOutputStringLine, GetOutputStringLineCount, SetOutputFileOn
Fortran90 Interface:
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
C Example:
see GetOutputString
Fortran90 Example:
see GetOutputStringLine
IPQ_RESULT SetSelectedOutputFileName ( int  id,
const char *  filename 
)

Sets the name of the current selected output file (see SetCurrentSelectedOutputUserNumber). This file name is used if not specified within SELECTED_OUTPUT input. The default value is selected_n.id.out.

Parameters
idThe instance id returned from CreateIPhreeqc.
filenameThe name of the file to write SELECTED_OUTPUT output to.
Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe given id is invalid.
See also
GetSelectedOutputFileName, GetSelectedOutputFileOn, GetSelectedOutputString, GetSelectedOutputStringOn, GetSelectedOutputStringLine, GetSelectedOutputStringLineCount, SetCurrentSelectedOutputUserNumber, SetSelectedOutputFileOn, SetSelectedOutputStringOn
Fortran90 Interface:
FUNCTION SetSelectedOutputFileName(ID,FILENAME)
  INTEGER(KIND=4),   INTENT(IN)   :: ID
  CHARACTER(LEN=*),  INTENT(OUT)  :: FILENAME
  INTEGER(KIND=4)                 :: SetSelectedOutputFileName
END FUNCTION SetSelectedOutputFileName
IPQ_RESULT SetSelectedOutputFileOn ( int  id,
int  sel_on 
)

Sets the selected-output file switch on or off. This switch controls whether or not phreeqc writes output to the current SELECTED_OUTPUT file (see SetCurrentSelectedOutputUserNumber). The initial setting after calling CreateIPhreeqc is off.

Parameters
idThe instance id returned from CreateIPhreeqc.
sel_onIf non-zero, writes output to the selected-output file; if zero, no output is written to the selected-output file.
Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe given id is invalid.
See also
GetSelectedOutputFileOn, GetSelectedOutputColumnCount, GetSelectedOutputRowCount, GetSelectedOutputValue, SetCurrentSelectedOutputUserNumber
Fortran90 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
IPQ_RESULT SetSelectedOutputStringOn ( int  id,
int  sel_string_on 
)

Sets the current selected output string switch on or off. This switch controls whether or not the data normally sent to the current selected output file (see SetCurrentSelectedOutputUserNumber) are stored in a buffer for retrieval. The initial setting after calling CreateIPhreeqc is off.

Parameters
idThe instance id returned from CreateIPhreeqc.
sel_string_onIf non-zero, captures the output defined by the SELECTED_OUTPUT keyword into a string buffer; if zero, output defined by the SELECTED_OUTPUT keyword is not captured to a string buffer.
Return values
IPQ_OKSuccess.
IPQ_BADINSTANCEThe given id is invalid.
See also
GetSelectedOutputFileOn, GetSelectedOutputStringOn, GetSelectedOutputString, GetSelectedOutputStringLine, GetSelectedOutputStringLineCount, SetCurrentSelectedOutputUserNumber, SetSelectedOutputFileOn
Fortran90 Interface:
FUNCTION SetSelectedOutputStringOn(ID,SELECTED_OUTPUT_STRING_ON)
  INTEGER(KIND=4),  INTENT(IN)  :: ID
  LOGICAL(KIND=4),  INTENT(IN)  :: SELECTED_OUTPUT_STRING_ON
  INTEGER(KIND=4)               :: SetSelectedOutputStringOn
END FUNCTION SetSelectedOutputStringOn
C Example:
see GetSelectedOutputString
Fortran90 Example:
see GetSelectedOutputStringLine