Mailing-List: contact dev-help@apr.apache.org; run by ezmlm
Precedence: bulk
Received-SPF: pass (asf.osuosl.org: domain of bojan@rexursive.com designates
 203.171.74.242 as permitted sender)
Message-ID: <20060505122424.garv5thxk4ckococ@www.rexursive.com>
Date: Fri, 05 May 2006 12:24:24 +1000
From: Bojan Smojver <bojan@rexursive.com>
To: APR Development List <dev@apr.apache.org>
Subject: [PATCH]: APU DBD documentation cleanup (some)
MIME-Version: 1.0
Content-Type: multipart/mixed;
	boundary="=_3bhh8j67gq4g"
Content-Transfer-Encoding: 7bit
User-Agent: Internet Messaging Program (IMP) H3 (4.1.1)

This message is in MIME format.

--=_3bhh8j67gq4g
Content-Type: text/plain;
	charset=ISO-8859-1;
	DelSp="Yes";
	format="flowed"
Content-Disposition: inline
Content-Transfer-Encoding: 7bit

Before I commit this, I would like to make sure that additional  
explanations are useful and based on real behaviour of DBD. There is  
some simplification in relation to apr_dbd_prepare() syntax, but  
that's on purpose.

-- 
Bojan

--=_3bhh8j67gq4g
Content-Type: text/x-patch;
	charset=ISO-8859-1;
	name="apr_dbd-docs.patch"
Content-Disposition: attachment;
	filename="apr_dbd-docs.patch"
Content-Transfer-Encoding: quoted-printable

Index: include/apr_dbd.h
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- include/apr_dbd.h=09(revision 399905)
+++ include/apr_dbd.h=09(working copy)
@@ -67,19 +67,33 @@
=20
 /** apr_dbd_open: open a connection to a backend
  *
- *  @param ptmp - working pool
+ *  @param pool - working pool
  *  @param params - arguments to driver (implementation-dependent)
  *  @param handle - pointer to handle to return
  *  @param driver - driver struct.
  *  @return APR_SUCCESS for success
  *  @return APR_EGENERAL if driver exists but connection failed
+ *  @remarks PostgreSQL: the params is passed directly to the PQconnectdb()
+ *  function (check PostgreSQL documentation for more details on the syntax=
).
+ *  @remarks SQLite2: the params is split on a colon, with the first part u=
sed
+ *  as the filename and second part converted to an integer and used as fil=
e
+ *  mode.
+ *  @remarks SQLite3: the params is passed directly to the sqlite3_open()
+ *  function as a filename to be opened (check SQLite3 documentation for mo=
re
+ *  details).
+ *  @remarks Oracle: the params can have "user", "pass", "dbname" and "serv=
er"
+ *  keys, each followed by an equal sign and a value. Such key/value pairs =
can
+ *  be delimited by space, CR, LF, tab, semicolon, vertical bar or comma.
+ *  @remarks MySQL: the params can have "host", "port", "user", "pass",
+ *  "dbname" and "sock" keys, each followed by an equal sign and a value.
+ *  Such key/value pairs can be delimited by space, CR, LF, tab, semicolon,
+ *  vertical bar or comma.
  */
 APU_DECLARE(apr_status_t) apr_dbd_open(const apr_dbd_driver_t *driver,
-                                       apr_pool_t *ptmp, const char *params=
,
+                                       apr_pool_t *pool, const char *params=
,
                                        apr_dbd_t **handle);
=20
-/** apr_dbd_close: close a connection to a backend.
- *  Only required for explicit close or
+/** apr_dbd_close: close a connection to a backend
  *
  *  @param handle - handle to close
  *  @param driver - driver struct.
@@ -132,8 +146,13 @@
  *  @param driver - the driver
  *  @param pool - a pool to use for error messages (if any).
  *  @param handle - the db connection
- *  @param transaction - ptr to a transaction.  May be null on entry
+ *  @param trans - ptr to a transaction.  May be null on entry
  *  @return 0 for success or error code
+ *  @remarks A cleanup function will be registered with the pool, which wil=
l
+ *  end the transaction unless apr_dbd_transaction_end() is called explicit=
ly.
+ *  @remarks If any of the query/select calls during a transaction return
+ *  non-zero status code, the transaction will inherit this code and any
+ *  further query/select calls will fail immediately.
  */
 APU_DECLARE(int) apr_dbd_transaction_start(const apr_dbd_driver_t *driver,
                                            apr_pool_t *pool,
@@ -146,7 +165,7 @@
  *
  *  @param driver - the driver
  *  @param handle - the db connection
- *  @param transaction - the transaction.
+ *  @param trans - the transaction.
  *  @return 0 for success or error code
  */
 APU_DECLARE(int) apr_dbd_transaction_end(const apr_dbd_driver_t *driver,
@@ -268,6 +287,13 @@
  *                 (eg within a Request in httpd)
  *  @param statement - statement to prepare.  May point to null on entry.
  *  @return 0 for success or error code
+ *  @remarks To specify parameters of the prepared query, use %s in place o=
f
+ *  database specific parameter syntax (e.g. for PostgreSQL, this would be =
$1,
+ *  $2, for SQLite3 this would be ? etc.). For instance: "SELECT name FROM
+ *  customers WHERE name=3D%s" would be a query that this function understa=
nds.
+ *  With PostgreSQL, you can also specify %d, which will set the data type =
of
+ *  the parameter to integer (check PostgreSQL PREPARE statment documentati=
on
+ *  for more details).
  */
 APU_DECLARE(int) apr_dbd_prepare(const apr_dbd_driver_t *driver, apr_pool_t=
 *pool,
                                  apr_dbd_t *handle, const char *query,

--=_3bhh8j67gq4g--