ラージオブジェクト・インタフェース

The facilities Postgres provides to access large objects, both in the backend as part of user-defined functions or the front end as part of an application using the interface, are described below. (For users familiar with Postgres 4.2, PostgreSQL has a new set of functions providing a more coherent interface. The interface is the same for dynamically-loaded C functions as well as for XXX LOST TEXT? WHAT SHOULD GO HERE??. The Postgres large object interface is modeled after the UNIX file system interface, with analogues of open(2), read(2), write(2), lseek(2), etc. User functions call these routines to retrieve only the data of interest from a large object. For example, if a large object type called mugshot existed that stored photographs of faces, then a function called beard could be declared on mugshot data. Beard could look at the lower third of a photograph, and determine the color of the beard that appeared there, if any. The entire large object value need not be buffered, or even examined, by the beard function. Large objects may be accessed from dynamically-loaded C functions or database client programs that link the library. Postgres provides a set of routines that support opening, reading, writing, closing, and seeking on large objects.

Postgres システムでは、ユーザ定義 関数の一部としてバックエンド側で、もしくは、アプリケーション の一部としてフロントエンド側で、ラージオブジェクトへのアクセ スに使用されるインタフェースを提供しています。どちらも後で説 明します。( Postgres 4.2 に慣れて いるユーザ向けに、PostgreSQL はより 理路整然としたインタフェースを提供する新しい関数群を持っていま す。このインタフェースは、XXX(原稿から無くなっている? ここに は何が入るんだ? )だけでなく、動的に読み込まれる C 関数と同一で す。) (訳注: ")"が原文にありませんでした。旧訳に従いここで ")" を挿 入しています。) Postgres ラージオブジェクト・インタ フェースは、UNIX ファイルシステムにならって 作成され、open(2)read(2)write(2)lseek(2) などと酷似したインタフェースを持 っています。ユーザ関数は、ラージオブジェクトから必要なデータだ けを取り出す時にこれらの処理を呼び出します。例えば、顔写真を格 納する mugshot という名前のラージオブジェクト型があり、beard という名前の関数で、mugshot データについて宣言したとします。 beard 関数は写真の下 1/3 をみて、もしあれば、そこにあるひげの色 を測定するものとします。beard 関数では、ラージオブジェクトの値 全体をバッファに取り出すことも、全体を確認することも必要ありま せん。ラージオブジェクトは、動的に読み込まれる C 関数、または、ライブラリとリンクされたデー タベースクライアントプログラムのどちらからでもアクセスできます。 Postgres は、ラージオブジェクトにつ いて「開く」、「読む」、「書く」、「閉じる」、「シークする」機 能を提供しています。

ラージオブジェクトの作成

The routine

Oid lo_creat(PGconn *conn, int mode)
creates a new large object. The mode is a bitmask describing several different attributes of the new object. The symbolic constants listed here are defined in PGROOT/src/backend/libpq/libpq-fs.h The access type (read, write, or both) is controlled by OR ing together the bits INV_READ and INV_WRITE. If the large object should be archived -- that is, if historical versions of it should be moved periodically to a special archive relation -- then the INV_ARCHIVE bit should be set. The low-order sixteen bits of mask are the storage manager number on which the large object should reside. For sites other than Berkeley, these bits should always be zero. The commands below create an (Inversion) large object:
inv_oid = lo_creat(INV_READ|INV_WRITE|INV_ARCHIVE);

Oid lo_creat(PGconn *conn, int mode)
処理は、新しいラージオブジェクトを作成します。引数 mode は新 しいオブジェクト用の複数の異なる属性を示すビットマスクです。 以下で使用する定数シンボルは、 PGROOT/src/backend/libpq/libpq-fs.h で定義されています。(読み取り、書き込み、または両方といった) アクセスタイプは、INV_READ ビット、 INV_WRITE ビットの論理和で指定できます。ラ ージオブジェクトをアーカイブしたい、つまり、その複数世代のバー ジョンを定期的に特別なアーカイブリレーションに移動したい、場合 には、INV_ARCHIVE ビットを設定します。マスク の下位 16 ビットは、ラージオブジェクトが属するストレージマネージ ャの番号です。バークレイ以外のサイトでは、これらのビット列は常に 0 となります。次のコマンドは、(転置)ラージオブジェクトを作成 します。
inv_oid = lo_creat(INV_READ|INV_WRITE|INV_ARCHIVE);

ラージオブジェクトのインポート

To import a UNIX file as a large object, call

Oid lo_import(PGconn *conn, text *filename)
The filename argument specifies the UNIX pathname of the file to be imported as a large object.

UNIX ファイルをラージオブジェクトとしてイン ポートするには、

Oid lo_import(PGconn *conn, text *filename)
を呼び出します。引数 filename には、ラージオブジェクトとしてイ ンポートする UNIX ファイルのパス名を指定し ます。

ラージオブジェクトのエクスポート

To export a large object into UNIX file, call

int lo_export(PGconn *conn, Oid lobjId, text *filename)
The lobjId argument specifies the Oid of the large object to export and the filename argument specifies the UNIX pathname of the file.

ラージオブジェクトを UNIX ファイルにエクス ポートするには、

int lo_export(PGconn *conn, Oid lobjId, text *filename)
を呼び出します。引数 lobjId には、エクスポートしたいラージオブ ジェクトの oid を指定し、引数 filename には、 UNIX ファイルのパス名を指定します。

既存ラージオブジェクトを開く

To open an existing large object, call

int lo_open(PGconn *conn, Oid lobjId, int mode, ...)
The lobjId argument specifies the Oid of the large object to open. The mode bits control whether the object is opened for reading INV_READ), writing or both. A large object cannot be opened before it is created. lo_open returns a large object descriptor for later use in lo_read, lo_write, lo_lseek, lo_tell, and lo_close.

既存のラージオブジェクトを開く場合は、

int lo_open(PGconn *conn, Oid lobjId, int mode, ...)
を呼び出します。引数 lobjId には開きたいラージオブジェクトの oid を指定します。引数 mode の各ビットは、そのオブジェクトを 読み取りのみ(INV_READ)、書き込みのみ(INV_WRITE)、その両方 できるように開くのかを制御するものです。 (訳注: 旧訳に合わせて、(INV_WRITE) を追加しています。) 作成していないラージオブジェクトを開くことはできません。 lo_open は、lo_read、lo_write、lo_lseek、lo_tell、lo_close で使 用するラージオブジェクト記述子を返します。

ラージオブジェクトにデータを書く

The routine

int lo_write(PGconn *conn, int fd, char *buf, int len)
writes len bytes from buf to large object fd. The fd argument must have been returned by a previous lo_open. The number of bytes actually written is returned. In the event of an error, the return value is negative.

int lo_write(PGconn *conn, int fd, char *buf, int len)
処理は、引数 len 長のバイトを、引数 buf から引数 fd が示すラー ジオブジェクトに書き込みます。引数 fd は事前に実行した lo_open の戻り値でなければいけません。実際に書き込まれたバイト数が返さ れます。エラーが発生した場合は、負の値を返します。

ラージオブジェクトのシーク

To change the current read or write location on a large object, call

int lo_lseek(PGconn *conn, int fd, int offset, int whence)
This routine moves the current location pointer for the large object described by fd to the new location specified by offset. The valid values for .i whence are SEEK_SET SEEK_CUR and SEEK_END.

ラージオブジェクトの現在の読み取り、または、書き込みを行なう位 置を変更するには、

int lo_lseek(PGconn *conn, int fd, int offset, int whence)
を呼び出します。この処理は、引数 fd で示すラージオブジェクトの現 在の位置を示すポインタを引数 offset で指定した新しい位置に変更し ます。引数 whence にて指定可能な値は、SEEK_SET、SEEK_CUR、 SEEK_END のいずれかです。

ラージオブジェクト記述子を閉じる

A large object may be closed by calling

int lo_close(PGconn *conn, int fd)
where fd is a large object descriptor returned by lo_open. On success, lo_close returns zero. On error, the return value is negative.

int lo_close(PGconn *conn, int fd)
を呼び出すことで、ラージオブジェクトを閉じることができます。こ こで、fd は lo_open の戻り値であるラージオブジェクト記述子です。 成功すると、lo_close は 0 を返します。失敗す ると、負の値を返します。