6 Procedures for Managing Large Objects

Note

All of the operations on large objects must be carried out inside a BEGIN TRANSACTION/END TRANSACTION pair. Failure to do this will result in a loss of synchronization between the back-end and the libpq library, resulting in an unusable connection to the database, and possible corruption of data.

To keep things running smoothly, certain read and write operations flush their internal buffers every once in a while. If there are problems, they throw a lob flush error. In the case where an error occurs during the process (Guile) wind-down, the error message is displayed to stderr instead. There are also Error seeking on lo port, Error reading from lo port and fport_write; these are normal (scheme world) errors.

Additionally, both pg-lo-creat and pg-lo-open can throw Invalid mode specification and memory errors.

Guile-PG displays large-object port objects in the following format:

#<PG-LO-PORT:MODE: ALOD:OID:CONN>

mode is one of closed, input-output, input, output or bogus; alod is a large-object descriptor (small integer similar to a file descriptor); oid is the OID (integer); and conn is the printed representation of the connection (see Procedures for managing connections). Everything else appears literally as shown here (including the space in front of alod, unfortunately). This format will likely change by the time Guile-PG 1.0 is released.

Procedure: pg-lo-creat conn modes ¶

Create a new large object and open a port over it for reading and/or writing. modes is a string describing the mode in which the port is to be opened. The mode string must include one of r for reading, w for writing or a for append (but since the object is empty to start with this is the same as w). Return a large object port which can be used to read or write data to/from the object, or #f on failure in which case pg-error-message from the connection should give some idea of what happened.

In addition to returning #f on failure this procedure throws a misc-error if the modes string is invalid.

Procedure: pg-lo-open conn oid modes ¶

Open a port over an existing large object. The port can be used to read or write data from/to the object. oid should be an integer identifier representing the large object. modes must be a string describing the mode in which the port is to be opened. The mode string must include one of r for reading, w for writing, a for appending or + with any of the above indicating both reading and writing/appending. Using a is equivalent to opening the port for writing and immediately doing a (pg-lo-seek) to the end. Return either an open large object port or #f on failure, in which case pg-error-message from the connection should give some idea of what happened.

Throw misc-error if the modes is invalid.

Procedure: pg-lo-unlink conn oid ¶

Delete the large object identified by oid. Return #t if the object was successfully deleted, #f otherwise, in which case pg-error-message applied to conn should give an idea of what went wrong.

Procedure: pg-lo-get-oid port ¶

Return the integer identifier of the object to which a given port applies. port must be a large object port returned from pg-lo-creat or pg-lo-open.

Procedure: pg-lo-tell port ¶

Return the position of the file pointer for the given large object port. port must be a large object port returned from pg-lo-creat or pg-lo-open. Return either an integer greater than or equal to zero, or #f if an error occurred. In the latter case pg-error-message applied to conn should explain what went wrong.

Procedure: pg-lo-seek port where whence ¶

Set the position of the next read or write to/from the given large object port. port must be a large object port returned from pg-lo-creat or pg-lo-open. where is the position to set the pointer. whence must be one of

SEEK_SET

Relative to the beginning of the file.

SEEK_CUR

Relative to the current position.

SEEK_END

Relative to the end of the file.

Return an integer which is the new position relative to the beginning of the object, or a number less than zero if an error occurred.

Note

It is possible to seek beyond the end of file opened only for reading, in which case subsequent reads of the port will return an EOF object.

Procedure: pg-lo-import conn filename ¶

Create a new large object and loads it with the contents of the specified file. filename must be a string containing the name of the file to be loaded into the new object. Return the integer identifier (OID) of the newly created large object, or #f if an error occurred, in which case pg-error-message should be consulted to determine the failure.

Procedure: pg-lo-export conn oid filename ¶

Write the contents of a given large object to a file. oid is the integer identifying the large object to be exported and filename the name of the file to contain the object data. Return #t on success, #f otherwise, in which case pg-error-message may offer an explanation of the failure.