Next: Miscellaneous Procedures, Previous: Procedures for Copying Data, Up: The (database postgres*) Modules [Contents][Index]
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.
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.
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.
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.
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
.
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.
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.
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.
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.
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.
Next: Miscellaneous Procedures, Previous: Procedures for Copying Data, Up: The (database postgres*) Modules [Contents][Index]