18 OCIのナビゲーショナル関数と型関数

この章では、Oracle Databaseから取り出されたオブジェクトをナビゲートするOCIナビゲーショナル関数について説明します。さらに、ここには型記述子オブジェクト(TDO)を取得する関数の説明も含まれています。

ナビゲーショナル関数および型関数の概要

オブジェクト・ナビゲーショナル・パラダイムの中では、データは参照によって接続されたオブジェクトのグラフとして表現されます。このグラフの中のオブジェクトに到達するには、参照をたどります。OCIは、Oracle Database内のオブジェクトにナビゲーショナル・インタフェースを提供します。この章では、これらのコールについて説明します。

アプリケーションがOCIEnvCreate()、OCIEnvNlsCreate()またはOCIInitialize() (非推奨)をOCI_OBJECTモードでコールすると、OCIオブジェクト環境は初期化されます。

オブジェクト型と存続期間

オブジェクト・インスタンスは、Oracle Databaseで定義された型の状態変化です。この項では、OCIでのオブジェクト・インスタンスの記述方法について説明します。OCIでは、オブジェクト・インスタンスは型、存続期間および参照可能性によって次のように分類されます。

永続オブジェクトはオブジェクト型のインスタンスの1つです。永続オブジェクトは、サーバー内の表の行中に常駐し、セッション(接続)の継続時間より長く存在できます。永続オブジェクトは、オブジェクト識別子を格納するオブジェクト参照によって識別できます。永続オブジェクトは、そのオブジェクト参照を確保することで取得できます。
一時オブジェクトはオブジェクト型のインスタンスです。一時オブジェクトは、セッション(接続)の継続時間より長く存在することはできず、一時的な計算結果を格納します。一時オブジェクトは、一時オブジェクト識別子を格納する参照によって識別できます。
値はユーザー定義型(オブジェクト型またはコレクション型)のインスタンスの1つであるか、組込みOracle型のいずれかです。オブジェクトとは異なり、オブジェクト型の値は、参照ではなくメモリー・ポインタによって識別されます。

値はスタンドアロン値または埋込み値になります。スタンドアロン値は、通常、SELECT文を発行することで取得されます。OCIでは、クライアント・プログラムがSQL文を発行することで、オブジェクト表の行を選択して値に代入することもできます。データベース内の参照可能オブジェクトは、参照によって識別できない値として表現できます。また、スタンドアロン値は、VARCHARやRAWのように、オブジェクト内の表外格納属性にしたり、VARCHAR、RAW、オブジェクトのように、コレクション内の表外格納要素にできます。

埋込み値は、格納インスタンス内に物理的に格納されます。埋込み値は、数値やネストしたオブジェクトなどのオブジェクト内の表内格納属性、またはコレクション内の表内格納要素にできます。

すべての値は、OCIでは一時的なものであるとみなされます。つまり、OCIは値のデータベースへの自動フラッシュをサポートしないため、クライアントは、値をデータベースに格納するためのSQL文を明示的に実行する必要があります。埋込み値は、格納インスタンスがフラッシュされるときにフラッシュされます。

図18-1に、インスタンスの型と存続期間による分類方法を示します。型には、オブジェクトまたはオブジェクトの値を指定できます。存続期間には、永続(セッションの継続時間より長く存在できる)または一時(セッションの継続時間より長く存在できない)を指定できます。

図18-1 インスタンスの型と存続期間による分類

「図18-1 インスタンスの型と存続期間による分類」の説明

各インスタンスの違いを、表18-1に示します。

表18-1 インスタンスの型と存続期間

特性	永続オブジェクト	一時オブジェクト	値
型	オブジェクト型	オブジェクト型	オブジェクト型、組込み、コレクション
最長存続期間	オブジェクトが削除されるまで	セッション	セッション
参照可能性	あり	あり	なし
埋込み可能性	なし	なし	あり

用語

この章では、次の用語が使用されます。

オブジェクトとは、一般に、永続オブジェクト、一時オブジェクト、オブジェクト型のスタンドアロン値、またはオブジェクト型の埋込み値のことです。
参照可能オブジェクトとは、永続オブジェクトまたは一時オブジェクトのことです。
スタンドアロン・オブジェクトとは、永続オブジェクト、一時オブジェクト、またはオブジェクト型のスタンドアロン値のことです。
埋込みオブジェクトとは、オブジェクト型の埋込み値のことです。
オブジェクトは、作成(新規作成)された場合、または更新済や削除済のマークが設定された場合に、使用済と表現されます。

関連項目:
異なるオブジェクト型を指す用語の詳細は、「永続オブジェクト、一時オブジェクトおよび値」を参照してください。

OCI関数の規則

各関数を記述する際に使用される規則は、「OCI関数の規則」を参照してください。関数ごとに次の情報が記載されている場合もあります。

戻り値

表18-3にリストされている標準コード以外の値が関数によって戻される場合の、戻り値についての説明。

ナビゲーショナル関数の戻り値

表18-2は、 OCIナビゲーショナル関数によって通常戻される値を示しています。

表18-2 ナビゲーショナル関数の戻り値

戻り値	意味
`OCI_SUCCESS`	操作は成功しました。
`OCI_ERROR`	操作は失敗しました。関数に渡されたエラー・ハンドルに対して`OCIErrorGet()`をコールすることで特定のエラーを取り出せます。
`OCI_INVALID_HANDLE`	関数に渡されたOCIハンドルが無効です。

この章では、各関数に関する記述の後で関数固有の戻り値に関する情報を説明します。各関数から戻される特定のエラー・コードに関する情報は、次の項で記述します。

キャッシュ関数およびオブジェクト関数用のサーバー・ラウンドトリップ

個々のOCIキャッシュ関数およびオブジェクト関数に必要なサーバー・ラウンドトリップ回数を示す表は、表C-3を参照してください。

ナビゲーショナル関数エラー・コード

表18-3には、各OCIナビゲーショナル関数によって戻される外部Oracleエラー・コードがリストされています。表の後に各エラーの内容を説明します。

表18-3 OCIナビゲーショナル関数エラー・コード

関数	発生する可能性のあるORAエラー
`OCICacheFlush()`	24350, 21560, 21705
`OCICacheFree()`	24350, 21560, 21705
`OCICacheRefresh()`	24350, 21560, 21705
`OCICacheUnmark()`	24350, 21560, 21705
`OCICacheUnpin()`	24350, 21560, 21705
`OCIObjectArrayPin()`	24350, 21560
`OCIObjectCopy()`	24350, 21560, 21705, 21710
`OCIObjectExists()`	24350, 21560, 21710
`OCIObjectFlush()`	24350, 21560, 21701, 21703, 21708, 21710
`OCIObjectFree()`	24350, 21560, 21603, 21710
`OCIObjectGetAttr()`	21560, 21600, 22305
`OCIObjectGetInd()`	24350, 21560, 21710
`OCIObjectGetObjectRef()`	24350, 21560, 21710
`OCIObjectGetTypeRef()`	24350, 21560, 21710
`OCIObjectIsDirty()`	24350, 21560, 21710
`OCIObjectIsLocked()`	24350, 21560, 21710
`OCIObjectLock()`	24350, 21560, 21701, 21708, 21710
`OCIObjectLockNoWait()`	24350, 21560, 21701, 21708, 21710
`OCIObjectMarkDelete()`	24350, 21560, 21700, 21701, 21702, 21710
`OCIObjectMarkDeleteByRef()`	24350, 21560
`OCIObjectMarkUpdate()`	24350, 21560, 21700, 21701, 21710
`OCIObjectNew()`	24350, 21560, 21705, 21710
`OCIObjectPin()`	24350, 21560, 21700, 21702
`OCIObjectPinCountReset()`	24350, 21560, 21710
`OCIObjectPinTable()`	24350, 21560, 21705
`OCIObjectRefresh()`	24350, 21560, 21709, 21710
`OCIObjectSetAttr()`	21560, 21600, 22305, 22279, 21601
`OCIObjectUnmark()`	24350, 21560, 21710
`OCIObjectUnmarkByRef()`	24350, 21560
`OCIObjectUnpin()`	24350, 21560, 21710

表18-3のORAエラーは、次のとおりです。

ORA-21560 - 引数stringがNULL、無効または範囲外です。
ORA-21600 - パス式が長すぎます。
ORA-21601 - 属性がオブジェクトではありません。
ORA-21603 - プロパティID[string]は無効です。
ORA-21700 - オブジェクトが存在しないか、削除マークが設定されています。
ORA-21701 - 異なるサーバーにオブジェクトをフラッシュしようとしました。
ORA-21702 - オブジェクトがインスタンス化されていないか、またはキャッシュ内でインスタンス化解除されています
ORA-21703 - 変更されていないオブジェクトはフラッシュできません。
ORA-21704 - フラッシュを実行しないとキャッシュまたは接続を終了できません。
ORA-21705 - サービス・コンテキストが無効です。
ORA-21708 - 一時オブジェクトで不適切な操作が行われました。
ORA-21709 - 変更されたオブジェクトをリフレッシュできません。
ORA-21710 - 引数にはオブジェクトの有効なメモリー・アドレスが必要です。
ORA-22279 - LOBバッファリングが使用可能な状態では、操作を実行できません。
ORA-22305 - 属性/メソッド/パラメータ"string"が見つかりません。
ORA-24350 - OCIコールは使用できません。