From ec144be17d809d32bb6e0aea7e6c18e4f644af88 Mon Sep 17 00:00:00 2001
From: Michael Wallner <mike@php.net>
Date: Fri, 26 Sep 2014 15:02:42 +0200
Subject: [PATCH] pq\Statement docs

---
 pq/Statement.md             | 11 +++++++++
 pq/Statement/__construct.md | 47 +++++++++++++++++++++++++++++++++++++
 pq/Statement/bind.md        | 42 +++++++++++++++++++++++++++++++++
 pq/Statement/desc.md        | 39 ++++++++++++++++++++++++++++++
 pq/Statement/descAsync.md   |  0
 pq/Statement/exec.md        | 29 +++++++++++++++++++++++
 pq/Statement/execAsync.md   | 16 +++++++++++++
 7 files changed, 184 insertions(+)
 create mode 100644 pq/Statement.md
 create mode 100644 pq/Statement/__construct.md
 create mode 100644 pq/Statement/bind.md
 create mode 100644 pq/Statement/desc.md
 create mode 100644 pq/Statement/descAsync.md
 create mode 100644 pq/Statement/exec.md
 create mode 100644 pq/Statement/execAsync.md

diff --git a/pq/Statement.md b/pq/Statement.md
new file mode 100644
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
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
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
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
index 0000000..e69de29
diff --git a/pq/Statement/exec.md b/pq/Statement/exec.md
new file mode 100644
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
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
+
-- 
2.30.2