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
r
for reading,w
for writing ora
for append (but since the object is empty to start with this is the same asw
). Return a large object port which can be used to read or write data to/from the object, or#f
on failure in which casepg-error-message
from the connection should give some idea of what happened.In addition to returning
#f
on failure this procedure throws amisc-error
if themodes
string 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
r
for reading,w
for writing,a
for appending or+
with any of the above indicating both reading and writing/appending. Usinga
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 casepg-error-message
from the connection should give some idea of what happened.Throw
misc-error
if themodes
is invalid.
Delete the large object identified by oid. Return
#t
if the object was successfully deleted,#f
otherwise, in which casepg-error-message
applied toconn
should 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-creat
orpg-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-creat
orpg-lo-open
. Return either an integer greater than or equal to zero, or#f
if an error occurred. In the latter casepg-error-message
applied toconn
should 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-creat
orpg-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.
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
#f
if 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
#f
if an error occurred, in which casepg-error-message
should 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
#t
on success,#f
otherwise, in which casepg-error-message
may offer an explanation of the failure.