From e50a0ac32ef7a510441333f05d29a6921e0dac26 Mon Sep 17 00:00:00 2001
From: Michael Wallner <mike@php.net>
Date: Fri, 26 Sep 2014 13:17:44 +0200
Subject: [PATCH] pq\LOB docs

---
 pq/LOB.md             | 26 ++++++++++++++++++++++++++
 pq/LOB/__construct.md | 19 +++++++++++++++++++
 pq/LOB/read.md        | 33 +++++++++++++++++++++++++++++++++
 pq/LOB/seek.md        | 20 ++++++++++++++++++++
 pq/LOB/tell.md        | 17 +++++++++++++++++
 pq/LOB/truncate.md    | 14 ++++++++++++++
 pq/LOB/write.md       | 30 ++++++++++++++++++++++++++++++
 7 files changed, 159 insertions(+)
 create mode 100644 pq/LOB.md
 create mode 100644 pq/LOB/__construct.md
 create mode 100644 pq/LOB/read.md
 create mode 100644 pq/LOB/seek.md
 create mode 100644 pq/LOB/tell.md
 create mode 100644 pq/LOB/truncate.md
 create mode 100644 pq/LOB/write.md

diff --git a/pq/LOB.md b/pq/LOB.md
new file mode 100644
index 0000000..d36e84a
--- /dev/null
+++ b/pq/LOB.md
@@ -0,0 +1,26 @@
+# class pq\LOB
+
+A *large object*.
+
+> ***NOTE:***  
+  Working with *large objects* requires an active transaction.
+
+## Constants:
+
+* INVALID_OID  
+  0, representing an invalid OID.
+* <span class="constant">R</span>  
+  Read-only mode.
+* <span class="constant">W</span>  
+  Write-only mode.
+* RW  
+  Read/write mode.
+
+## Properties:
+
+* public (readonly) pq\Transaction $transaction  
+  The transaction wrapping the operations on the *large object*.
+* public (readonly) int $oid  
+  The OID of the *large object*.
+* public (readonly) resource $stream  
+  The stream connected to the *large object*.
diff --git a/pq/LOB/__construct.md b/pq/LOB/__construct.md
new file mode 100644
index 0000000..ae69dc2
--- /dev/null
+++ b/pq/LOB/__construct.md
@@ -0,0 +1,19 @@
+# void pq\LOB::__construct(pq\Transaction $txn[, int $oid = pq\LOB::INVALID_OID[, int $mode = pq\LOB::RW]])
+
+Open or create a *large object*.
+See pq\Transcation::openLOB() and pq\Transaction::createLOB().
+
+## Params:
+
+* pq\Transaction $txn  
+  The transaction which wraps the *large object* operations.
+* Optional int $oid = pq\LOB::INVALID_OID  
+  The OID of the existing *large object* to open.
+* Optional int $mode = pq\LOB::RW  
+  Access mode (read, write or read/write).
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
diff --git a/pq/LOB/read.md b/pq/LOB/read.md
new file mode 100644
index 0000000..92e9271
--- /dev/null
+++ b/pq/LOB/read.md
@@ -0,0 +1,33 @@
+# string pq\LOB::read([int $length = 0x1000[, int &$read = NULL]])
+
+Read a string of data from the current position of the *large object*.
+
+## Params:
+
+* Optional int $length = 0x1000  
+  The amount of bytes to read from the *large object*.
+* Optional int &$read = NULL  
+  The amount of bytes actually read from the *large object*.
+
+## Returns:
+
+* string, the data read.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pa\Exception\RuntimeException
+
+## Example:
+
+	<?php
+	
+	$connection = new pq\Connection;
+	$transaction = new pq\Transaction($connection);
+	
+	$data = $tansaction->openLOB(123)->read(100, $read);
+	
+	printf("Read %d bytes: '%s'\n", $read, $data);
+	
+	?>
diff --git a/pq/LOB/seek.md b/pq/LOB/seek.md
new file mode 100644
index 0000000..ac6137b
--- /dev/null
+++ b/pq/LOB/seek.md
@@ -0,0 +1,20 @@
+# int pq\LOB::seek(int $offset[, int $whence = SEEK_SET])
+
+Seek to a position within the *large object*.
+
+## Params:
+
+* int $offset  
+  The position to seek to.
+* Optional int $whence = SEEK_SET  
+  From where to seek (SEEK_SET, SEEK_CUR or SEEK_END).
+
+## Returns:
+
+* int, the new position.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
diff --git a/pq/LOB/tell.md b/pq/LOB/tell.md
new file mode 100644
index 0000000..08fcdbf
--- /dev/null
+++ b/pq/LOB/tell.md
@@ -0,0 +1,17 @@
+# int pq\LOB::tell()
+
+Retrieve the current position within the *large object*.
+
+## Params:
+
+None.
+
+## Returns:
+
+* int, the current position.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
diff --git a/pq/LOB/truncate.md b/pq/LOB/truncate.md
new file mode 100644
index 0000000..9d30aaa
--- /dev/null
+++ b/pq/LOB/truncate.md
@@ -0,0 +1,14 @@
+# void pq\LOB::truncate([int $length = 0])
+
+Truncate the *large object*.
+
+## Params:
+
+* Optional int $length = 0  
+  The length to truncate to.
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
diff --git a/pq/LOB/write.md b/pq/LOB/write.md
new file mode 100644
index 0000000..3ca9afe
--- /dev/null
+++ b/pq/LOB/write.md
@@ -0,0 +1,30 @@
+# int pq\LOB::write(string $data)
+
+Write data to the *large object*.
+
+## Params:
+
+* string $data  
+  The data that should be writte to the current position.
+
+## Returns:
+
+* int, the number of bytes written.
+
+## Throw:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
+
+## Example:
+
+	<?php
+	
+	$connection = new pq\Connection;
+	$transaction = $connection->startTransaction();
+	
+	$transaction->createLOB()->write("Hello World!");
+	$transaction->rollback();
+	
+	?>
-- 
2.30.2