pq\Statement docs

diff --git a/pq/Statement.md b/pq/Statement.md
new file mode 100644 (file)
index 0000000..764003f
--- /dev/null
+++ b/pq/Statement.md
@@ -0,0 +1,11 @@
+# class pq\Statement
+
+A named prepared statement.
+
+## Properties:
+
+* public (readonly) pq\Connection $connection  
+  The connection to the server.
+* public (readonly) string $name  
+  The identifiying name of the prepared statement.
+

diff --git a/pq/Statement/__construct.md b/pq/Statement/__construct.md
new file mode 100644 (file)
index 0000000..1d26caf
--- /dev/null
+++ b/pq/Statement/__construct.md
@@ -0,0 +1,47 @@
+# void pq\Statement::__construct(pq\Connection $conn, string $name, string $query[, array $types = NULL[, bool $async = FALSE]])
+
+Prepare a new statement.
+See pq\Connection::prepare().
+
+## Params:
+
+* pq\Connection $conn  
+  The connection to prepare the statement on.
+* string $name  
+  The name identifying this statement.
+* string $query  
+  The actual query to prepare.
+* Optional array $types = NULL  
+  A list of corresponding query parameter type OIDs.
+* Optional bool $async = FALSE  
+  Whether to prepare the statement [asynchronously](pq/Connection/: Asynchronous Usage).
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
+* pq\Exception\DomainException
+
+## Example:
+
+       <?php
+       
+       $connection = new pq\Connection;
+       $statement = new pq\Statement(
+               $connection,
+               "my_statement",
+               "SELECT \$1",
+               [pq\Types::INT4]
+       );
+       
+       $result = $statement->exec([123]);
+       $result->fetchCol($col);
+       
+       echo "Got: $col\n";
+       
+       ?>
+
+Yields:
+
+       Got: 123

diff --git a/pq/Statement/bind.md b/pq/Statement/bind.md
new file mode 100644 (file)
index 0000000..9fbf460
--- /dev/null
+++ b/pq/Statement/bind.md
@@ -0,0 +1,42 @@
+# void pq\Statement::bind(int $param_no, mixed &$param_ref)
+
+Bind a variable to an input parameter.
+  
+## Params:
+
+* int $param_no  
+  The parameter index to bind to.
+* mixed &$param_ref  
+  The variable to bind.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+
+
+## Example:
+
+       <?php
+       
+       $connection = new pq\Connection;
+       $statement = $connection->prepare("st1", 
+               "SELECT \$1 as first, \$2 as second", [pq\Types::INT4, pq\Types::INT4]);
+       
+       $statement->bind(1, $first);
+       $statement->bind(2, $second);
+       
+       $first = 1;
+       $second = 2;
+       
+       $result = $statement->exec();
+       foreach ($result->fetchRow(pq\Result::FETCH_ASSOC) as $col => $val) {
+               printf("%10s = %s\n", $col, $val);
+       }
+       
+       ?>
+
+Yields:
+
+        first = 1
+       second = 2

diff --git a/pq/Statement/desc.md b/pq/Statement/desc.md
new file mode 100644 (file)
index 0000000..bd82256
--- /dev/null
+++ b/pq/Statement/desc.md
@@ -0,0 +1,39 @@
+# array pq\Statement::desc()
+
+Describe the parameters of the prepared statement.
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, list of type OIDs of the substitution parameters.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
+* pq\Exception\DomainException
+
+## Example:
+
+       <?php
+       
+       $connection = new pq\Connection;
+       $types = new pq\Types($connection);
+       $statement = $connection->prepare("st1", 
+               "SELECT \$1, \$2", [pq\Types::XML, pq\Types::JSON]);
+       $description = $statement->desc();
+       
+       foreach($description as $typeOid) {
+               echo $types[$typeOid]->typname, "\n";
+       }
+       
+       ?>
+
+Yields:
+
+       xml
+       json

diff --git a/pq/Statement/descAsync.md b/pq/Statement/descAsync.md
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/pq/Statement/exec.md b/pq/Statement/exec.md
new file mode 100644 (file)
index 0000000..adc2001
--- /dev/null
+++ b/pq/Statement/exec.md
@@ -0,0 +1,29 @@
+# pq\Result pq\Statement::exec([array $params = NULL])
+
+Execute the prepared statement.
+
+## Params:
+
+* Optional array $params = NULL  
+  Any parameters to substitute in the preapred statement (defaults to any bou
+  nd variables).
+
+## Returns:
+
+* pq\Result, the result of the execution of the prepared statement.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
+
+## Example:
+
+       <?php
+       
+       $connection = new pq\Connection;
+       $statement = $connection->prepare("st1", "SELECT int4(\$1)");
+       $result = $statement->exec([123]);
+       
+       ?>

diff --git a/pq/Statement/execAsync.md b/pq/Statement/execAsync.md
new file mode 100644 (file)
index 0000000..f0530e5
--- /dev/null
+++ b/pq/Statement/execAsync.md
@@ -0,0 +1,16 @@
+# void pq\Statement::execAsync([array $params = NULL])
+
+[Asynchronously](pq/Connection/: Asynchronous Usage) execute the prepared statement.
+
+## Params:
+
+* Optional array $params = NULL  
+  Any parameters to substitute in the preapred statement (defaults to any bou
+  nd variables).
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
+