Next: Miscellaneous, Previous: Writing/Reading Data, Up: Top
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 Database 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.
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
rfor reading,wfor writing orafor append (but since the object is empty to start with this is the same asw.) The return value is a large object port which can be used to read or write data to/from the object, or#fon failure in which casepg-error-messagefrom the connection should give some idea of what happened.In addition to returning
#fon failure this procedure throws amisc-errorif themodesstring is invalid.
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
rfor reading,wfor writing,afor append or+with any of the above indicating both reading and writing/appending.Ais equivalent to opening the port for writing and immediately doing a(pg-lo-seek)to the end. The return value is either an open large object port or#fon failure in which casepg-error-messagefrom the connection should give some idea of what happened.Throw
misc-errorif themodesis invalid.
Delete the large object identified by oid. Return
#tif the object was successfully deleted,#fotherwise, in which casepg-error-messageapplied toconnshould give an idea of what went wrong.
Return the integer identifier of the object to which a given port applies. port must be a large object port returned from
pg-lo-creatorpg-lo-open.
Return the position of the file pointer for the given large object port. port must be a large object port returned from
pg-lo-creatorpg-lo-open. The return value is either an integer greater than or equal to zero or#fif an error occurred. In the latter casepg-error-messageapplied toconnshould explain what went wrong.
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-creatorpg-lo-open. where is the position to set the pointer. whence must be one ofThe return value is an integer which is the new position relative to the beginning of the object, or a number less than zero if an error occurred.
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.
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.
Read num objects each of length siz from port. Return a string containing the data read from the port or
#fif an error occurred.
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
#fif an error occurred, in which casepg-error-messageshould be consulted to determine the failure.
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
#ton success,#fotherwise, in which casepg-error-messagemay offer an explanation of the failure.