From: Michael Wallner <mike@php.net>
Date: Mon, 6 Oct 2014 07:23:58 +0000 (+0200)
Subject: pq/Cursor docs
X-Git-Url: https://git.m6w6.name/?a=commitdiff_plain;h=94517ccbe3607c9c3795acb696957ce3e7335493;p=mdref%2Fmdref-pq

pq/Cursor docs
---

diff --git a/pq/Cursor.md b/pq/Cursor.md
new file mode 100644
index 0000000..9df566a
--- /dev/null
+++ b/pq/Cursor.md
@@ -0,0 +1,26 @@
+# class pq\Cursor
+
+Declare a cursor.
+
+## Constants:
+
+* BINARY  
+  Causes the cursor to return data in binary rather than in text format. You probalby do not want to use that.
+* INSENSITIVE  
+  The data returned by the cursor should be unaffected by updates to the tables underlying the cursor that take place after the cursor was opened.
+* WITH_HOLD  
+  The cursor should stay usable after the transaction that created it was successfully committed.
+* SCROLL  
+  Force that rows can be retrieved in any order from the cursor.
+* NO_SCROLL  
+  Force that rows are only retrievable in sequiential order.
+
+> ***NOTE:***  
+  See the [notes in the official PostgreSQL documentation](http://www.postgresql.org/docs/current/static/sql-declare.html#SQL-DECLARE-NOTES) for more information.
+
+## Properties:
+
+* public (readonly) pq\Connection $connection  
+  The connection the cursor was declared on.
+* public (readonly) string $name  
+  The identifying name of the cursor.
diff --git a/pq/Cursor/__construct.md b/pq/Cursor/__construct.md
new file mode 100644
index 0000000..f84a259
--- /dev/null
+++ b/pq/Cursor/__construct.md
@@ -0,0 +1,21 @@
+# void pq\Cursor::__construct(pq\Connection $conn, int $flags, string $query[, bool $async = FALSE])
+
+Declare a cursor.
+See pq\Connection::declare().
+
+## Params:
+
+* pq\Connection $connection  
+  The connection on which the cursor should be declared.
+* int $flags  
+  See pq\Cursor constants.
+* string $query  
+  The query for ehich the cursor should be opened.
+* bool $async  
+  Whether to declare the cursor [asynchronously](pq/Connection/: Asynchronous Usage).
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
diff --git a/pq/Cursor/close.md b/pq/Cursor/close.md
new file mode 100644
index 0000000..6566120
--- /dev/null
+++ b/pq/Cursor/close.md
@@ -0,0 +1,11 @@
+# void pq\Cursor::close()
+
+Close an open cursor.
+This is a no-op on already closed cursors.
+
+## Params:
+
+None.
+
+## Throws:
+
diff --git a/pq/Cursor/fetch.md b/pq/Cursor/fetch.md
new file mode 100644
index 0000000..d08949c
--- /dev/null
+++ b/pq/Cursor/fetch.md
@@ -0,0 +1,72 @@
+# pq\Result pq\Cursor::fetch([string $spec = "1"])
+
+Fetch rows from the cursor.
+See pq\Cursor::move().
+
+## Params:
+
+* Optional string $spec = "1"  
+  What to fetch.
+
+### Fetch argument:
+
+FETCH and MOVE usually accepts arguments like the following, where `count` is the number of rows:
+
+* NEXT
+* PRIOR
+* FIRST
+* LAST
+* ABSOLUTE `count`
+* RELATIVE `count`
+* `count`
+* ALL
+* FORWARD
+* FORWARD `count`
+* FORWARD ALL
+* BACKWARD
+* BACKWARD `count`
+* BACKWARD ALL
+
+See the [official PostgreSQL documentaion](http://www.postgresql.org/docs/current/static/sql-fetch.html) for details.
+
+## Returns:
+
+* pq\Result, the fetched row(s).
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
+
+## Example:
+
+	<?php
+	
+	$c = new pq\Connection;
+	$p = new pq\Cursor($c, "mycursor", pq\Cursor::WITH_HOLD,
+		"SELECT * FROM generate_series(0,29) s WHERE (s%2)=0");
+	
+	for ($r = $p->fetch(2); $r->numRows; $p->move(1), $r = $p->fetch(2)) {
+		foreach ($r as $row) {
+			foreach ($row as $col) {
+				echo "	$col";
+			}
+			echo "\n";
+		}
+	}
+	
+	?>
+
+Yields:
+
+	0
+	2
+	6
+	8
+	12
+	14
+	18
+	20
+	24
+	26
diff --git a/pq/Cursor/fetchAsync.md b/pq/Cursor/fetchAsync.md
new file mode 100644
index 0000000..25c069c
--- /dev/null
+++ b/pq/Cursor/fetchAsync.md
@@ -0,0 +1,17 @@
+# void pq\Cursor::fetchAsync([string $spec = "1"[, callable $callback = NULL]])
+
+[Asynchronously](pq/Connection/: Asynchronous Usage) fetch rows from the cursor.
+See pq\Cursor::fetch().
+
+## Params:
+
+* Optional string $spec = "1"  
+  What to fetch.
+* Optional callable $callback as function(pq\Result $res)  
+  A callback to execute when the result is ready.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
diff --git a/pq/Cursor/move.md b/pq/Cursor/move.md
new file mode 100644
index 0000000..f61014b
--- /dev/null
+++ b/pq/Cursor/move.md
@@ -0,0 +1,40 @@
+# pq\Result pq\Cursor::move([string $spec = "1"])
+
+Move the cursor.
+See pq\Cursor::fetch().
+
+## Params:
+
+* Optional string $spec = "1"  
+  What to fetch.
+
+### Fetch argument:
+
+FETCH and MOVE usually accepts arguments like the following, where `count` is the number of rows:
+
+* NEXT
+* PRIOR
+* FIRST
+* LAST
+* ABSOLUTE `count`
+* RELATIVE `count`
+* `count`
+* ALL
+* FORWARD
+* FORWARD `count`
+* FORWARD ALL
+* BACKWARD
+* BACKWARD `count`
+* BACKWARD ALL
+
+See the [official PostgreSQL documentaion](http://www.postgresql.org/docs/current/static/sql-move.html) for details.
+
+## Returns:
+
+* pq\Result, command status.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
diff --git a/pq/Cursor/moveAsync.md b/pq/Cursor/moveAsync.md
new file mode 100644
index 0000000..b651cc3
--- /dev/null
+++ b/pq/Cursor/moveAsync.md
@@ -0,0 +1,17 @@
+# void pq\Cursor::moveAsync([string $spec = "1"])
+
+[Asynchronously](pq/Connection/: Asynchronous Usage) move the cursor.
+See pq\Cursor::move().
+
+## Params:
+
+* Optional string $spec = "1"  
+  What to fetch.
+* Optional callable $callback as function(pq\Result $res)  
+  A callback to execute when the command completed.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
diff --git a/pq/Cursor/open.md b/pq/Cursor/open.md
new file mode 100644
index 0000000..5badc90
--- /dev/null
+++ b/pq/Cursor/open.md
@@ -0,0 +1,17 @@
+# void pq\Cursor::open()
+
+Reopen a cursor.
+This is a no-op on already open cursors.
+
+> ***NOTE:***  
+  Only cursors closed by pq\Cursor::close() will be reopened.
+
+## Params:
+
+None.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException