Class

PostgreSQLLargeObject

Description

Stores a PostgreSQL large object.

Properties

Name	Type	Read-Only	Shared
Length	Integer	✓
Position	Integer

Methods

Name	Parameters	Returns
Close
Read	Count As Integer	String
Seek	Offset As Integer, Whence As Integer
Tell		Integer
Write	Data As String

Property descriptions

PostgreSQLLargeObject.Length

Length As Integer

Reads the length of the large object.

This property is read-only.

Gets the size of a large object:

// 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)

PostgreSQLLargeObject.Position

Position As Integer

Gets or sets the current position of the large object. The beginning of a large object is position 0.

Displays the current postion within the large object:

// 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

PostgreSQLLargeObject.Close

Close

Closes the large object.

PostgreSQLLargeObject.Read

Read(Count As Integer) As String

Reads Count bytes from the large object and returns them as a String.

Read the data in a large object:

// 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)

PostgreSQLLargeObject.Seek

Seek(Offset As Integer, Whence As 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:

largeObject.Seek(0, 0)

Seek to the end of the large object:

largeObject.Seek(0, 2)

Seek to the 10 bytes before the current position in the large object:

largeObject.Seek(10, 1)

PostgreSQLLargeObject.Tell

Tell As Integer

Returns the current position of the large object. The same as Position.

Displays the current position within the large object:

// 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

PostgreSQLLargeObject.Write

Write(Data As String)

Writes Data to the large object.

Writes data to a large object:

// 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:

db.ExecuteSQL "BEGIN TRANSACTION"

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

db.ExecuteSQL "END TRANSACTION"

Most large object operations will be performed using an instance of the PostgreSQLLargeObject class, which you will obtain by calling the OpenLargeObject method of the PostgreSQLDatabase class. There is no reason to ever create your own PostgreSQLLargeObject instance using New.

The PostgreSQLLargeObject class works similarly to 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:

largeObject.Seek(0, 2)

The following Seek positions the large object at its beginning:

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:

largeObject.Seek(-10, 1)

Sample code