Class

# PostgreSQLLargeObject

<div class="rst-class">

forsearch

</div>

Database

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

Stores a PostgreSQL large object.

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

| Name                                       | Type                               | Read-Only | Shared |
|--------------------------------------------|------------------------------------|-----------|--------|
| `Length<postgresqllargeobject.length>`     | `Integer</api/data_types/integer>` | ✓         |        |
| `Position<postgresqllargeobject.position>` | `Integer</api/data_types/integer>` |           |        |

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                 | Parameters                                                                                 | Returns                            | Shared |
|--------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------|--------|
| `Close<postgresqllargeobject.close>` |                                                                                            |                                    |        |
| `Read<postgresqllargeobject.read>`   | Count As `Integer</api/data_types/integer>`                                                | `String</api/data_types/string>`   |        |
| `Seek<postgresqllargeobject.seek>`   | Offset As `Integer</api/data_types/integer>`, Whence As `Integer</api/data_types/integer>` |                                    |        |
| `Tell<postgresqllargeobject.tell>`   |                                                                                            | `Integer</api/data_types/integer>` |        |
| `Write<postgresqllargeobject.write>` | Data As `String</api/data_types/string>`                                                   |                                    |        |

## Property descriptions

<div id="postgresqllargeobject.length">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

PostgreSQLLargeObject.Length

**Length** As `Integer</api/data_types/integer>`

> Reads the length of the large object.
>
> This property is read-only.
>
> Gets the size of a large object:
>
> ``` xojo
> ' db is a previously connected PostgreSQLDatabase
> ' objectID is an integer referring to a previously created large object
> Var largeObject As PostgreSQLLargeObject
> largeObject = db.OpenLargeObject(objectID)
>
> MessageBox("Object size in bytes: " + largeObject.Length.ToString)
> ```

<div id="postgresqllargeobject.position">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

PostgreSQLLargeObject.Position

**Position** As `Integer</api/data_types/integer>`

> Gets or sets the current position of the large object. The beginning of a large object is position 0.
>
> Displays the current position within the large object:
>
> ``` xojo
> ' db is a previously connected PostgreSQLDatabase
> ' objectID is an integer referring to a previously created large object
> Var largeObject As PostgreSQLLargeObject
> largeObject = db.OpenLargeObject(objectID)
>
> Var currentPos As Integer = largeObject.Position
> ```

## Method descriptions

<div id="postgresqllargeobject.close">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

PostgreSQLLargeObject.Close

**Close**

> Closes the large object.

<div id="postgresqllargeobject.read">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

PostgreSQLLargeObject.Read

**Read**(Count As `Integer</api/data_types/integer>`) As `String</api/data_types/string>`

> Reads *Count* bytes from the large object and returns them as a `String</api/data_types/string>`.
>
> Read the data in a large object:
>
> ``` xojo
> ' db is a previously connected PostgreSQLDatabase
> ' objectID is an integer referring to a previously created large object
> Var largeObject As PostgreSQLLargeObject
> largeObject = db.OpenLargeObject(objectID)
>
> Var data As String = largeObject.Read(largeObject.Length)
> ```

<div id="postgresqllargeobject.seek">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

PostgreSQLLargeObject.Seek

**Seek**(Offset As `Integer</api/data_types/integer>`, Whence As `Integer</api/data_types/integer>`)

> Positions the large object at *offset* relative to the beginning, end, or current position of the large object, as determined by the value of *whence*.
>
> Possible values for *whence* are as follows:
>
> | Value | Description                                                     |
> |-------|-----------------------------------------------------------------|
> | 0     | Offset is relative to the beginning of the large object.        |
> | 1     | Offset is relative to the current position of the large object. |
> | 2     | Offset is relative to the end of the large object.              |
>
> Seek to the beginning of the large object:
>
> ``` xojo
> largeObject.Seek(0, 0)
> ```
>
> Seek to the end of the large object:
>
> ``` xojo
> largeObject.Seek(0, 2)
> ```
>
> Seek to the 10 bytes before the current position in the large object:
>
> ``` xojo
> largeObject.Seek(10, 1)
> ```

<div id="postgresqllargeobject.tell">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

PostgreSQLLargeObject.Tell

**Tell** As `Integer</api/data_types/integer>`

> Returns the current position of the large object. The same as `Position<postgresqllargeobject.position>`.
>
> Displays the current position within the large object:
>
> ``` xojo
> ' db is a previously connected PostgreSQLDatabase
> ' objectID is an integer referring to a previously created large object
> Var largeObject As PostgreSQLLargeObject
> largeObject = db.OpenLargeObject(objectID)
>
> Var currentPos As Integer = largeObject.Tell
> ```

<div id="postgresqllargeobject.write">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

PostgreSQLLargeObject.Write

**Write**(Data As `String</api/data_types/string>`)

> Writes *Data* to the large object.
>
> Writes data to a large object:
>
> ``` xojo
> ' db is a previously connected PostgreSQLDatabase
> ' objectID is identifies a previously created large object
>
> Var largeObject As PostgreSQLLargeObject
> largeObject = db.OpenLargeObject(objectID)
>
> Var data As String = "misc data"
>
> Try
> largeObject.Write(data)
> Catch error As DatabaseException
> MessageBox("DB Error: " + error.Message)
> End Try
> ```

## Notes

PostgreSQL requires that all large object operations be performed inside of a transaction. Therefore, you must start a transaction before you perform your first large object operation, like this:

``` xojo
db.ExecuteSQL "BEGIN TRANSACTION"
```

After you have performed your last large object operation, you should close the transaction, like this:

``` xojo
db.ExecuteSQL "END TRANSACTION"
```

Most large object operations will be performed using an instance of the <span class="title-ref">PostgreSQLLargeObject</span> class, which you will obtain by calling the OpenLargeObject method of the `PostgreSQLDatabase</api/databases/postgresqldatabase>` class. There is no reason to ever create your own <span class="title-ref">PostgreSQLLargeObject</span> instance using `New</api/language/new>`.

The <span class="title-ref">PostgreSQLLargeObject</span> class works similarly to `BinaryStream</api/files/binarystream>`. As with BinaryStreams, PostgreSQLLargeObjects are always positioned at a certain location in the large object. Whenever you read or write to the large object, the position moves to just after the read or write. You can also set the position using the Position property. You can have more control over the position by using the Seek method.

For example, if you wanted to position a large object at its end, you could call Seek as follows:

``` xojo
largeObject.Seek(0, 2)
```

The following Seek positions the large object at its beginning:

``` xojo
largeObject.Seek(0, 0)
```

Offsets can be negative as well, For example, the following call of Seek positions the large object 10 bytes before its current position:

``` xojo
largeObject.Seek(-10, 1)
```

## Sample code

Read the data in a large object:

``` xojo
' db is a previously connected PostgreSQLDatabase
' objectID is an integer referring to a previously created large object
Var largeObject As PostgreSQLLargeObject
largeObject = db.OpenLargeObject(objectID)

Var data As String = largeObject.Read(largeObject.Length)
```

## Compatibility

|                       |                       |
|-----------------------|-----------------------|
| **Project Types**     | Console, Desktop, Web |
| **Operating Systems** | All                   |

<div class="seealso">

`Object</api/data_types/additional_types/object>` parent class; `PostgreSQLDatabase</api/databases/postgresqldatabase>` class.

</div>