27.7 OCIの型情報アクセッサ関数
OCIの型情報アクセッサ関数をリストし、説明します。
表27-11は、この項で説明しているOCIの型情報アクセッサ関数を示しています。
表27-11 型情報アクセッサ関数
関数 | 用途 |
---|---|
オブジェクト名配列の指定時にTDO配列を取得します。 |
|
スキーマ・レベルまたはパッケージ・レベル型の名前配列の指定時にTDO配列を取得します。 |
|
オブジェクト参照配列の指定時にTDO配列を取得します。 |
|
スキーマ・レベルまたはパッケージ・レベル型の名前の指定時にTDOを取得します。 |
|
オブジェクト名の指定時にTDOを取得します。 |
|
オブジェクト参照の指定時にTDOを取得します。 |
|
型がパッケージ型である場合に、そのパッケージ名を取得します。 |
27.7.1 OCITypeArrayByName()
名前配列の指定時にTDO配列を取得します。
用途
名前配列の指定時にTDO配列を取得します。
注意:
OCITypeArrayByName()
では、パッケージ・レベル型はサポートしていません。
構文
sword OCITypeArrayByName ( OCIEnv *envhp, OCIError *errhp, const OCISvcCtx *svc, ub4 array_len, const OraText *schema_name[], ub4 s_length[], const OraText *type_name[], ub4 t_length[], const OraText *version_name[], ub4 v_length[], OCIDuration pin_duration, OCITypeGetOpt get_option, OCIType *tdo[] );
パラメータ
- envhp (IN/OUT)
-
オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、
OCIEnvCreate()
、OCIEnvNlsCreate()
およびOCIInitialize()
(非推奨)の説明を参照してください。 - errhp (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - svc (IN)
-
OCIサービス・ハンドルです。
- array_len (IN)
-
取り出される
schema_name
、type_name
またはversion_name
エントリの数です。 - schema_name (IN、オプション)
-
取得される型に関連付けられているスキーマ名の配列です。この配列を指定する場合は、
array_len
個の要素が必要です。0 (ゼロ)を指定すると、デフォルト・スキーマが想定されます。指定しない場合、schema_name
の要素数をarray_len
にする必要があります。1つ以上のエントリでデフォルト・スキーマが必要であることを示す場合は、これらのエントリに対してゼロ(0)を指定します。 - s_length (IN)
-
schema_name
配列の対応するschema_name
エントリの長さに対応する各エントリを持つschema_name
の配列の長さです(バイト単位)。配列の要素数はarray_len
または0 (ゼロ) (schema_name
が指定されていない場合)のいずれかにする必要があります。 - type_name (IN)
-
取り出される型の名前の配列です。
array_len
個の要素が必要です。 - t_length (IN)
-
type_name
配列にある型名のバイト単位の長さの配列です。 - version_name (IN)
-
バージョン名は無視され、要求された型の最新バージョンが戻されます。リリース9.0以上は型の変更が可能であったため、それより前のリリースのアプリケーションで変更された型にアクセスすると、エラーが発生します。この場合は、最新の型定義を使用して、アプリケーションの変更、再コンパイルおよび再リンクを行う必要があります。
取り出される型に対応するバージョン名の配列です。この配列は、最新バージョンの取出しを示す0 (ゼロ)にするか、または
array_len
個の要素が必要です。0 (ゼロ)を指定すると、最新のバージョンが想定されます。指定しない場合、要素数を
array_len
にする必要があります。1つ以上のエントリで最新のバージョンが必要であることを示す場合は、これらのエントリに対してゼロ(0)を指定します。 - v_length (IN)
-
version_name
配列にあるバージョン名のバイト単位の長さの配列です。 - pin_duration (IN)
-
取り出された型用の確保継続時間(たとえば、カレント・トランザクションの終わりまで)です。各オプションの説明は、
oro.h
を参照してください。 - get_option (IN)
-
型をロードする場合のオプションです。値は次の2つのうちのいずれかです。
-
OCI_TYPEGET_HEADER
(ヘッダーのみがロードされる) -
OCI_TYPEGET_ALL
(TDOおよびすべてのADOとMDOがロードされる)
コメント
スキーマまたは型名配列に対応付けられている既存の型のポインタを取得します。
get_option
パラメータを使用すると、各ラウンドトリップごとにロードされるTDOの部分を制御できます。
この関数は、必須パラメータにNULL
がある場合、あるいはスキーマ名または型名に対応付けられたオブジェクト型が存在しない場合はエラーを戻します。
配列ではなく単一の型を取り出すには、OCITypeByName()
を使用します。
注意:
この関数で取得されたTDO (TDOまたは表定義の配列)は、渡されたサービス・ハンドル(接続)に対応するキャッシュの論理パーティションに属します。TDOまたは表が論理パーティション間で使用される場合、動作は不明であり、リリースによって変化する可能性があります。
27.7.2 OCITypeArrayByFullName()
スキーマ・レベルまたはパッケージ・レベル型の名前配列の指定時に、既存のTDO配列の最新バージョンを取得します。
用途
スキーマ・レベルまたはパッケージ・レベル型の名前配列の指定時に、既存のTDO配列の最新バージョンを取得します。
注意:
OCITypeArrayByFullName()
はOCITypeByFullName()
の配列バージョンです。したがって、これらの2つの関数は機能的に同一で、一方はOCITypeByName()
を使用してOCITypeArrayByFullName()
を実装し、もう一方はその逆になります。
構文
sword OCITypeArrayByFullName( OCIEnv *env, OCIError *err, const OCISvcCtx *svc, ub4 array_len, const oratext *full_type_name[], ub4 f_t_length[], const oratext *version_name[], ub4 v_length[], OCIDuration pin_duration, OCITypeGetOpt get_option, OCIType *tdo[])
パラメータ
- envhp (IN/OUT)
-
オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、
OCIEnvCreate()
、OCIEnvNlsCreate()
およびOCIInitialize()
(非推奨)の説明を参照してください。 - errhp (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - svc (IN)
-
OCIサービス・ハンドルです。
- array_len (IN)
-
取り出される
schema_name
、type_name
またはversion_name
エントリの数です。 - full_type_name (IN)
-
型の名前です。
full_type_name
が完全修飾されない場合、名前解決によって推定された型が判断されます。たとえば、SCOTT.MYPACK.MYTYPE
は、MYPACK
パッケージ内のMYTYPE
型を参照します。現行スキーマがSCOTT
である場合は、MYPACK.MYTYPE
となることもあります。PL/SQLの名前解決の詳細は、『Oracle Database PL/SQL言語リファレンス』を参照してください。これは、スキーマ・レベル型にも適用されます。スキーマ・レベル型を指定する場合は、文字列は
SCOTT.MYTYPE
、または単にMYTYPE
になります。 - f_t_length (IN)
-
バイトで示した
full_type_name
の長さです。 - version_name (IN)
-
バージョン名は無視され、要求された型の最新バージョンが戻されます。リリース9.0以上は型の変更が可能であったため、それより前のリリースのアプリケーションで変更された型にアクセスすると、エラーが発生します。この場合は、最新の型定義を使用して、アプリケーションの変更、再コンパイルおよび再リンクを行う必要があります。
取り出される型に対応するバージョン名の配列です。この配列は、最新バージョンの取出しを示す0 (ゼロ)にするか、または
array_len
個の要素が必要です。0 (ゼロ)を指定すると、最新のバージョンが想定されます。指定しない場合、要素数を
array_len
にする必要があります。1つ以上のエントリで最新のバージョンが必要であることを示す場合は、これらのエントリに対してゼロ(0)を指定します。 - v_length (IN)
-
version_name
配列にあるバージョン名のバイト単位の長さの配列です。 - pin_duration (IN)
-
取り出された型用の確保継続時間(たとえば、カレント・トランザクションの終わりまで)です。各オプションの説明は、
oro.h
を参照してください。 - get_option (IN)
-
型をロードする場合のオプションです。値は次の2つのうちのいずれかです。
-
OCI_TYPEGET_HEADER
(ヘッダーのみがロードされる) -
OCI_TYPEGET_ALL
(TDOおよびすべてのADOとMDOがロードされる)
コメント
スキーマまたはパッケージ型名配列に対応付けられている既存の型のポインタを取得します。
get_option
パラメータを使用すると、各ラウンドトリップごとにロードされるTDOの部分を制御できます。
この関数は、必須パラメータにNULL
がある場合、あるいはスキーマ名またはパッケージ型名に対応付けられたオブジェクト型が存在しない場合はエラーを戻します。
配列ではなく単一の型を取り出すには、OCITypeByFullName()
を使用します。
注意:
この関数で取得されたTDO (TDOまたは表定義の配列)は、渡されたサービス・ハンドル(接続)に対応するキャッシュの論理パーティションに属します。TDOまたは表が論理パーティション間で使用される場合、動作は不明であり、リリースによって変化する可能性があります。
27.7.3 OCITypeArrayByRef()
参照配列の指定時にTDO配列を取得します。
用途
参照配列の指定時にTDO配列を取得します。
構文
sword OCITypeArrayByRef ( OCIEnv *envhp, OCIError *errhp, ub4 array_len, const OCIRef *type_ref[], OCIDuration pin_duration, OCITypeGetOpt get_option, OCIType *tdo[] );
パラメータ
- envhp (IN/OUT)
-
オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、
OCIEnvCreate()
、OCIEnvNlsCreate()
およびOCIInitialize()
(非推奨)の説明を参照してください。 - errhp (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - array_len (IN)
-
取り出される
schema_name
、type_name
またはversion_name
エントリの数です。 - type_ref (IN)
-
取り出される型記述子オブジェクトの特定のバージョンを指し示す
OCIRef*
の配列です。この配列を指定する場合は、array_len
個の要素が必要です。 - pin_duration (IN)
-
取り出された型用の確保継続時間(たとえば、カレント・トランザクションの終わりまで)です。各オプションの説明は、
oro.h
を参照してください。 - get_option (IN)
-
型をロードする場合のオプションです。値は次の2つのうちのいずれかです。
-
OCI_TYPEGET_HEADER
(ヘッダーのみがロードされる) -
OCI_TYPEGET_ALL
(TDOおよびすべてのADOとMDOがロードされる)
コメント
スキーマまたは型名配列に対応付けられている既存の型のポインタを取得します。
この関数は、次の場合にエラーを戻します。
-
必須パラメータに
NULL
がある場合 -
スキーマまたは型名エントリに対応付けられている1つ以上のオブジェクト型が存在しない場合
型の配列ではなく、単一の型を取り出すには、OCITypeByRef()
を使用します。
注意:
この関数で取得されたTDO (TDOまたは表定義の配列)は、渡されたサービス・ハンドル(接続)に対応するキャッシュの論理パーティションに属します。TDOまたは表が論理パーティション間で使用される場合、動作は不明であり、リリースによって変化する可能性があります。
27.7.4 OCITypeByFullName()
スキーマ・レベルまたはパッケージ・レベル型の名前の指定時に、既存のTDOの最新バージョンを取得します。
用途
スキーマ・レベルまたはパッケージ・レベル型の名前の指定時に、既存のTDOの最新バージョンを取得します。
構文
sword OCITypeByFullName(OCIEnv *env, OCIError *err, const OCISvcCtx *svc, const oratext *full_type_name, ub4 f_t_length, const oratext *version_name, ub4 v_length, OCIDuration pin_duration, OCITypeGetOpt get_option, OCIType **tdo);
パラメータ
- env (IN/OUT)
-
オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、
OCIEnvCreate()
、OCIEnvNlsCreate()
およびOCIInitialize()
(非推奨)の説明を参照してください。 - err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - svc (IN)
-
OCIサービス・ハンドルです。
- full_type_name (IN)
-
型の名前です。
full_type_name
が完全修飾されない場合、名前解決によって推定された型が判断されます。したがって、オブジェクトへの完全なパス名には、スキーマ、パッケージ名および型名を含めることができます。たとえば、SCOTT.MYPACK.MYTYPE
は、MYPACK
パッケージ内のMYTYPE
型を参照します。現行スキーマがSCOTT
である場合は、MYPACK.MYTYPE
となることもあります。PL/SQLの名前解決の詳細は、『Oracle Database PL/SQL言語リファレンス』を参照してください。これは、スキーマ・レベル型にも適用されます。スキーマ・レベル型を指定する場合は、文字列は
SCOTT.MYTYPE
、または単にMYTYPE
になります。 - f_t_length (IN)
-
バイトで示した
full_type_name
の長さです。 - version_name (IN)
-
バージョン名は無視され、要求された型の最新バージョンが戻されます。リリース9.0以上は型の変更が可能であったため、それより前のリリースのアプリケーションで変更された型にアクセスすると、エラーが発生します。この場合は、最新の型定義を使用して、アプリケーションの変更、再コンパイルおよび再リンクを行う必要があります。
ユーザーが読取り可能な、型のバージョンです。最新のバージョンを取り出すには、
(text *) 0
を渡します。 - v_length (IN)
-
version_name
のバイト単位の長さです。 - pin_duration (IN)
-
確保継続時間です。
関連項目:
-
OCI_TYPEGET_HEADER
(ヘッダーのみがロードされる) -
OCI_TYPEGET_ALL
(TDOおよびすべてのADOとMDOがロードされる)
コメント
型名が単一の文字列として渡されるということから、シック・クライアントJDBCなど他のクライアントおよびドライバで単一の名前文字列に含まれる型名を簡単に解決することもできます。
リモート・パッケージ型フィールドを含んだパッケージ型は、OCITypeByFullName()
ではサポートされません。リモート・パッケージ型フィールドを含んだパッケージ型を取得しようとするとエラーが発生します。
この関数は、スキーマまたはパッケージの型名に関連付けられている既存の型へのポインタを取得します。必須パラメータにNULL
がある場合、スキーマまたはパッケージの型名に関連付けられたオブジェクト型が存在しない場合、またはversion_name
が存在しない場合はエラーを戻します。
注意:
スキーマおよびパッケージの型名は大/小文字の区別があります。SQLを使用して作成されている場合は、すべて大文字の文字列を使用する必要があります。すべて大文字でない場合、プログラムは停止します。
この関数では、常にサーバーへのラウンドトリップが発生します。そのため、この関数を繰り返しコールして型を取得すると、パフォーマンスが大幅に低下する可能性があります。ラウンドトリップを最小限にするため、アプリケーションでは、型ごとにこの関数をコールし、型オブジェクトをキャッシュできます。
この関数によって取得した型を解放するには、OCIObjectUnpin()
またはOCIObjectPinCountReset()
をコールします。
OCITypeArrayByName()
またはOCITypeArrayByRef()
をコールすることにより、アプリケーションでTDOの配列を取り出せます。
注意:
この関数で取得されたTDO (TDOまたは表定義の配列)は、渡されたサービス・ハンドル(接続)に対応するキャッシュの論理パーティションに属します。TDOまたは表が論理パーティション間で使用される場合、動作は不明であり、リリースによって変化する可能性があります。
27.7.5 OCITypeByName()
既存のTDOの最新バージョンを取得します。
用途
既存のTDOの最新バージョンを取得します。このコールでは、パッケージ・レベル型はサポートしていません。スキーマの名前および型の名前は、それぞれ別個の文字列に入力します。
構文
sword OCITypeByName ( OCIEnv *env, OCIError *err, const OCISvcCtx *svc, const OraText *schema_name, ub4 s_length, const OraText *type_name, ub4 t_length, const OraText *version_name, ub4 v_length, OCIDuration pin_duration, OCITypeGetOpt get_option OCIType **tdo );
パラメータ
- env (IN/OUT)
-
オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、
OCIEnvCreate()
、OCIEnvNlsCreate()
およびOCIInitialize()
(非推奨)の説明を参照してください。 - err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - svc (IN)
-
OCIサービス・ハンドルです。
- schema_name (IN、オプション)
-
型に関連付けられているスキーマの名前です。デフォルトでは、ユーザーのスキーマ名が使用されます。この文字列はすべて大文字であることが必要です。それ以外の場合は、OCIで内部エラーが発生してプログラムが停止します。
- s_length (IN)
-
schema_name
パラメータの長さ(バイト単位)です。 - type_name (IN)
-
取得する型の名前です。この文字列はすべて大文字であることが必要です。それ以外の場合は、OCIで内部エラーが発生してプログラムが停止します。
- t_length (IN)
-
type_name
パラメータの長さ(バイト単位)です。 - version_name (IN)
-
バージョン名は無視され、要求された型の最新バージョンが戻されます。リリース9.0以上は型の変更が可能であったため、それより前のリリースのアプリケーションで変更された型にアクセスすると、エラーが発生します。この場合は、最新の型定義を使用して、アプリケーションの変更、再コンパイルおよび再リンクを行う必要があります。
ユーザーが読取り可能な、型のバージョンです。最新のバージョンを取り出すには、
(text *) 0
を渡します。 - v_length (IN)
-
version_name
のバイト単位の長さです。 - pin_duration (IN)
-
確保継続時間です。
関連項目:
-
OCI_TYPEGET_HEADER
(ヘッダーのみがロードされる) -
OCI_TYPEGET_ALL
(TDOおよびすべてのADOとMDOがロードされる)
コメント
この関数は、スキーマまたは型名に関連付けられている既存の型へのポインタを取得します。必須パラメータにNULL
がある場合、スキーマまたは型名に関連付けられたオブジェクト型が存在しない場合、またはversion_name
が存在しない場合はエラーを戻します。
注意:
スキーマおよび型名は大/小文字の区別があります。SQLを使用して作成されている場合は、すべて大文字の文字列を使用する必要があります。すべて大文字でない場合、プログラムは停止します。
この関数では、常にサーバーへのラウンドトリップが発生します。そのため、この関数を繰り返しコールして型を取得すると、パフォーマンスが大幅に低下する可能性があります。ラウンドトリップを最小限にするため、アプリケーションでは、型ごとにこの関数をコールし、型オブジェクトをキャッシュできます。
この関数によって取得した型を解放するには、OCIObjectUnpin()
またはOCIObjectPinCountReset()
をコールします。
OCITypeArrayByName()
またはOCITypeArrayByRef()
をコールすることにより、アプリケーションでTDOの配列を取り出せます。
注意:
この関数で取得されたTDO (TDOまたは表定義の配列)は、渡されたサービス・ハンドル(接続)に対応するキャッシュの論理パーティションに属します。TDOまたは表が論理パーティション間で使用される場合、動作は不明であり、リリースによって変化する可能性があります。
27.7.6 OCITypeByRef()
参照の指定時にTDOを取得します。
用途
参照の指定時にTDOを取得します。
構文
sword OCITypeByRef ( OCIEnv *env, OCIError *err, const OCIRef *type_ref, OCIDuration pin_duration, OCITypeGetOpt get_option, OCIType **tdo );
パラメータ
- env (IN/OUT)
-
オブジェクト・モードで初期化されたOCI環境ハンドルです。詳細は、
OCIEnvCreate()
、OCIEnvNlsCreate()
およびOCIInitialize()
(非推奨)の説明を参照してください。 - err (IN/OUT)
-
OCIエラー・ハンドルです。エラーがある場合は、
err
に記録され、OCI_ERROR
が戻されます。OCIErrorGet()
をコールして診断情報を取得します。 - type_ref (IN)
-
取得する型記述子オブジェクトのバージョンを指し示す
OCIRef*
です。 - pin_duration (IN)
-
取り出す型に対する、カレント・トランザクションの終了までの確保継続時間です。各オプションの説明は、
oro.h
を参照してください。 - get_option (IN)
-
型をロードする場合のオプションです。値は次の2つのうちのいずれかです。
-
OCI_TYPEGET_HEADER
(ヘッダーのみがロードされる) -
OCI_TYPEGET_ALL
(TDOおよびすべてのADOとMDOがロードされる)
コメント
OCITypeByRef()
関数は、必須パラメータにNULL
がある場合、エラーを戻します。
注意:
この関数で取得されたTDO (TDOまたは表定義の配列)は、渡されたサービス・ハンドル(接続)に対応するキャッシュの論理パーティションに属します。TDOまたは表が論理パーティション間で使用される場合、動作は不明であり、リリースによって変化する可能性があります。