From 94517ccbe3607c9c3795acb696957ce3e7335493 Mon Sep 17 00:00:00 2001 From: Michael Wallner Date: Mon, 6 Oct 2014 09:23:58 +0200 Subject: [PATCH] pq/Cursor docs --- pq/Cursor.md | 26 +++++++++++++++ pq/Cursor/__construct.md | 21 ++++++++++++ pq/Cursor/close.md | 11 ++++++ pq/Cursor/fetch.md | 72 ++++++++++++++++++++++++++++++++++++++++ pq/Cursor/fetchAsync.md | 17 ++++++++++ pq/Cursor/move.md | 40 ++++++++++++++++++++++ pq/Cursor/moveAsync.md | 17 ++++++++++ pq/Cursor/open.md | 17 ++++++++++ 8 files changed, 221 insertions(+) create mode 100644 pq/Cursor.md create mode 100644 pq/Cursor/__construct.md create mode 100644 pq/Cursor/close.md create mode 100644 pq/Cursor/fetch.md create mode 100644 pq/Cursor/fetchAsync.md create mode 100644 pq/Cursor/move.md create mode 100644 pq/Cursor/moveAsync.md create mode 100644 pq/Cursor/open.md 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: + + 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 -- 2.30.2