Changeset 7909

Timestamp:

Jul 14, 2006, 2:17:19 PM (20 years ago)

Author:

jhoblitt

Message:

add psDBLastInsertID()
add psDBExplicitTrans()
add psDBTransaction()
add psDBCommit()
add psDBRollback()
add p_psDBRunQueryPrepared()
add p_psDBFetchResult
add database subsubsecionts for Transaction Control Database Functions and Low Level Database Functions

Location:

trunk/doc/pslib

Files:

• ChangeLogSDRS.tex (modified) (2 diffs)
• psLibSDRS.tex (modified) (2 diffs)

trunk/doc/pslib/ChangeLogSDRS.tex

@@ -1 @@
-%%% $Id: ChangeLogSDRS.tex,v 1.207 2006-07-11 03:23:10 jhoblitt Exp $
+%%% $Id: ChangeLogSDRS.tex,v 1.208 2006-07-15 00:17:19 jhoblitt Exp $
 
 \subsection{Changes from version 00 to version 01}
@@ -911 +911 @@
 \item add \code{psTimeStrptime()}
 \item add \code{psTimeStrftime()}
-\end{itemize}
+\item add \code{psDBLastInsertID()}
+\item add \code{psDBExplicitTrans()}
+\item add \code{psDBTransaction()}
+\item add \code{psDBCommit()}
+\item add \code{psDBRollback()}
+\item add \code{p_psDBRunQueryPrepared()}
+\item add \code{p_psDBFetchResult}
+\item add database subsubsecionts for ``Transaction Control Database Functions'' and ``Low Level Database Functions''
+\end{itemize}

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.418 2006-07-11 03:23:10 jhoblitt Exp $
+%%% $Id: psLibSDRS.tex,v 1.419 2006-07-15 00:17:19 jhoblitt Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -4126 +4126 @@
 indicate an error.
 
+\begin{prototype}
+long psDBLastInsertID(
+    psDB *dbh                          ///< Database handle
+);
+\end{prototype}
+
+Returns the last value created in an ``auto-increment'' field.
+
+
+\subsubsection{Transaction Control Database Functions}
+
+By default the database functions shall behave as if each operation effects a
+permanent change to the database.  An API is provided to change this behavior
+such that operations may be grouped together into a ``transaction'' that is
+atomic.
+
+\begin{prototype}
+bool psDBExplicitTrans(
+    psDB *dbh,                          ///< Database handle
+    bool mode                           ///< transactions enable/disable
+);
+\end{prototype}
+
+Enable/Disable explicit transactions.  When enabled \code{psDBCommit()} must
+be called to make changes to the database's state persistent.
+
+\begin{prototype}
+bool psDBTransaction(
+    psDB *dbh                           ///< Database handle
+);
+\end{prototype}
+
+Start a new transaction.
+
+\begin{prototype}
+bool psDBCommit(
+    psDB *dbh                           ///< Database handle
+);
+\end{prototype}
+
+Commit the current transaction.
+
+\begin{prototype}
+bool psDBRollback(
+    psDB *dbh                           ///< Database handle
+);
+\end{prototype}
+
+Undo the current transaction.
+
+
+\subsubsection{Low Level Database Functions}
+
+This collection of functions is primarily intended for us internally by the
+other database functions.  However, in certain cases their direct use may be
+needed to express semantics that are not supported by the public database
+interface.
+
+\begin{prototype}
+long p_psDBRunQueryPrepared(
+    psDB *dbh,                          ///< Database handle
+    const psArray *rowSet,              ///< row data as psArray of psMetadata
+    const char *format,                 ///< SQL string to execute
+    ...
+);
+\end{prototype}
+
+\code{p_psDBRunQueryPrepared()} is similar to \code{p_psDBRunQuery()} except
+that \code{format} is expected to be a query string with value ``place
+holders'' in it.  This allows the data in \code{rowSet} is inserted into the
+database via the use of a more efficent ``prepared query''.
+
+\begin{prototype}
+psArray *p_psDBFetchResult(
+    psDB *dbh                          ///< Database handle
+);
+\end{prototype}
+
+\code{p_psDBFetchResult()} is the inverse operation of \code{p_psDBRunQuery}.
+It shall load the latest result set from the database into an \code{psArray}
+and return it.
+
+
 \subsection{FITS I/O Functions}