| Oracle® Call Interfaceプログラマーズ・ガイド 12c リリース1 (12.1) B72465-07 |
|
 前 |
 次 |
表16-1は、この項で説明しているOCIの接続関数、認証関数および初期化関数を示しています。
表16-2 接続関数、認証関数および初期化関数
| 関数 | 用途 |
|---|---|
アプリケーション・コンテキストのネームスペース内のすべての属性値情報を消去します。 |
|
アプリケーション・コンテキストのネームスペース内の属性およびその関連値を設定します。 |
|
接続プールを初期化します。 |
|
接続プールを破棄します。 |
|
Oracle Databaseを停止します |
|
Oracle Databaseのインスタンスを起動します。 |
|
OCI環境ハンドルを作成および初期化します。 |
|
OCI関数が実行される環境ハンドルを作成および初期化します。この環境の作成時に、キャラクタ・セットIDおよび各国語キャラクタ・セットIDを設定できます。 |
|
|
|
シングルセッション・ログインを単純化します。 |
|
様々なモードでログイン・セッションを作成します。 |
|
サーバーに連結します。サーバー・コンテキスト・ハンドルを初期化します。 |
|
サーバーから連結解除します。サーバー・コンテキスト・ハンドルを未初期化します。 |
|
ユーザーを認証します。 |
|
ユーザー・セッションを終了します。 |
|
セッション・プールからセッションを取得します。 |
|
セッション・プールを初期化します。 |
|
セッション・プールを破棄します。 |
|
セッションを解放します。 |
|
共有メモリー・サブシステムから連結解除します。 |
用途
アプリケーション・コンテキストのネームスペース内のすべての属性値情報を消去します。
構文
sword OCIAppCtxClearAll ( void *sesshndl,
void *nsptr,
ub4 nsptrlen,
OCIError *errhp,
ub4 mode ;
パラメータ
セッション・ハンドルのポインタです。
ネームスペース文字列(現在はCLIENTCONTEXTのみ)へのポインタです。
ネームスペース文字列の長さです。
OCIErrorGet()に渡すことができるエラー・ハンドルです。
モード(デフォルトはOCI_DEFAULT)です。
戻り値
エラー番号を戻します。
コメント
これは、サーバーへの次回のコール時にサーバー側のコンテキスト情報をクリーン・アップします。このネームスペース情報は、情報がサーバーに送信されるとセッション・ハンドルから消去され、必要に応じて再設定する必要があります。
関連関数
用途
アプリケーション・コンテキストのネームスペース内の属性およびその関連値を設定します。
構文
sword OCIAppCtxSet ( void *sesshndl,
void *nsptr,
ub4 nsptrlen,
void *attrptr,
ub4 attrptrlen,
void *valueptr,
ub4 valueptrlen,
OCIError *errhp,
ub4 mode );
パラメータ
セッション・ハンドルのポインタです。
ネームスペース文字列(現在はCLIENTCONTEXTのみ)へのポインタです。
ネームスペース文字列の長さです。
属性文字列へのポインタです。
attrptrが指し示す文字列の長さです。
値文字列へのポインタです。
valueptrが指し示す文字列の長さです。
OCIErrorGet()に渡すことができるエラー・ハンドルです。
モード(デフォルトはOCI_DEFAULT)です。
戻り値
エラー番号を戻します。
コメント
セッション・ハンドルに設定された情報は、サーバーへの次回のコール時にサーバーに送信されます。
この情報は、情報がサーバーに送信されるとセッション・ハンドルから消去され、必要に応じて再設定する必要があります。
接続プールを初期化します。
用途
接続プールを初期化します。
構文
sword OCIConnectionPoolCreate ( OCIEnv *envhp,
OCIError *errhp,
OCICPool *poolhp,
OraText **poolName,
sb4 *poolNameLen,
const OraText *dblink,
sb4 dblinkLen,
ub4 connMin,
ub4 connMax,
ub4 connIncr,
const OraText *poolUsername,
sb4 poolUserLen,
const OraText *poolPassword,
sb4 poolPassLen,
ub4 mode );
パラメータ
接続プールを作成する環境へのポインタです。
OCIErrorGet()に渡すことができるエラー・ハンドルです。
割当て済のプール・ハンドルです。
接続先の接続プール名です。
poolNameが指し示す文字列の長さです。
接続先のデータベース(サーバー)を指定します。
dblinkが指し示す文字列の長さです。
接続プールの最小接続数を指定します。有効な値は0 (ゼロ)以上です。
指定された数の接続がOCIConnectionPoolCreate()によってサーバーにオープンされます。接続プールを作成すると、必要なときのみ接続がオープンされます。通常、このパラメータは、アプリケーションで実行を予定している同時文の数に設定する必要があります。
データベースに対してオープンできる最大接続数を指定します。最大数に達すると、追加の接続はオープンしません。有効な値は1以上です。
現行の接続数がconnMax未満の場合、アプリケーションでは、データベースに対してオープンする接続に次回の増分を設定できます。有効な値は0以上です。
接続プーリングでは、暗黙的な1次セッションが必要です。この属性はそのセッションのユーザー名を指定します。
poolUsernameの長さです。
ユーザー名poolUsernameのパスワードです。
poolPasswordの長さです。
次のモードがサポートされています。
OCI_DEFAULT
OCI_CPOOL_REINITIALIZE
通常、OCIConnectionPoolCreate()は、modeをOCI_DEFAULTに設定してコールします。
プール属性を動的に変更する(たとえば、connMin、connMaxおよびconnIncrの各パラメータを変更する)には、modeをOCI_CPOOL_REINITIALIZEに設定して、OCIConnectionPoolCreate()をコールします。このコールの実行時、他のパラメータは無視されます。
コメント
OUTパラメータpoolNameとpoolNameLenには、データベース名とその長さの引数のかわりに、後続のOCIServerAttach()とOCILogon2()コールで使用する値が格納されます。
用途
接続プールを破棄します。
構文
sword OCIConnectionPoolDestroy ( OCICPool *poolhp,
OCIError *errhp,
ub4 mode );
パラメータ
作成したプールのプール・ハンドルです。
OCIErrorGet()に渡すことができるエラー・ハンドルです。
現在、この関数ではOCI_DEFAULTモードのみがサポートされています。
Oracle Databaseのインスタンスを停止します。
用途
Oracle Databaseのインスタンスを停止します。
構文
sword OCIDBShutdown ( OCISvcCtx *svchp,
OCIError *errhp,
OCIAdmin *admhp,
ub4 mode);
パラメータ
サービス・コンテキストへのハンドルです。svchpには、有効なサーバー・ハンドルおよび有効なユーザー・ハンドルを設定する必要があります。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
インスタンス管理ハンドルです。現在は使用されていません。(OCIAdmin *)0を渡します。
OCI_DEFAULT－ これ以上の接続は禁止されます。ユーザーがデータベースから切断されるまで待機します。
OCI_DBSHUTDOWN_TRANSACTIONAL－ これ以上の接続は禁止され、新しいトランザクションは許可されません。アクティブなトランザクションが完了するまで待機します。
OCI_DBSHUTDOWN_TRANSACTIONAL_LOCAL－ これ以上の接続は禁止され、新しいトランザクションは許可されません。ローカル・トランザクションが完了するまで待機します。
OCI_DBSHUTDOWN_IMMEDIATE－ 現在のコールが完了するまで待機しない、あるいはユーザーがデータベースから切断されるまで待機しません。コミットされていないトランザクションはすべて終了し、ロールバックされます。
OCI_DBSHUTDOWN_FINAL－ データベースを停止します。データベースがクローズされてマウントが解除された後、OCIDBShutdown()への2回目のコールでのみ使用する必要があります。
OCI_DBSHUTDOWN_ABORT－ 現在のコールが完了するまで待機しない、あるいはユーザーがデータベースから切断されるまで待機しません。コミットされていないトランザクションはすべて終了し、ロールバックはされません。データベースを停止する場合、これが最も速い処理方法ですが、次回のデータベースの起動時にインスタンスのリカバリが必要な場合があります。このため、このオプションは、バックグラウンド・プロセスが異常終了した場合など、通常とは異なる状況下で使用します。
コメント
停止するには、SYSOPERまたはSYSDBAとしてデータベースに接続している必要があります。ディスパッチャを介して共有サーバーには接続できません。OCI_DBSHUTDOWN_ABORT以外のモードで停止する場合、次の手順を使用します。
OCIDBShutdown()をOCI_DEFAULT、OCI_DBSHUTDOWN_TRANSACTIONAL、OCI_DBSHUTDOWN_TRANSACTIONAL_LOCALまたはOCI_DBSHUTDOWN_IMMEDIATEモードでコールし、これ以上の接続を禁止します。
必要なALTER DATABASEコマンドを発行し、データベースをクローズしてマウントを解除します。
OCIDBShutdown()をOCI_DBSHUTDOWN_FINALモードでコールし、インスタンスを停止します。
Oracle Databaseのインスタンスを起動します。
用途
Oracle Databaseのインスタンスを起動します。
構文
sword OCIDBStartup ( OCISvcCtx *svchp,
OCIError *errhp,
OCIAdmin *admhp,
ub4 mode,
ub4 flags);
パラメータ
サービス・コンテキストへのハンドルです。svchpには、有効なサーバー・ハンドルおよび有効なユーザー・ハンドルが設定されている必要があります。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
インスタンス管理ハンドルです。起動コールへの追加引数を渡すために使用します。OCI_ATTR_ADMIN_PFILEを設定していない場合は、(OCIAdmin *)0を渡します。
OCI_DEFAULT - これが唯一サポートされているモードです。インスタンスを起動しますが、データベースをマウントまたはオープンすることはありません。STARTUP NOMOUNTと同じです。
OCI_DEFAULT－ すべてのユーザーにデータベースへのアクセスを許可します。
OCI_DBSTARTUPFLAG_RESTRICT－ CREATE SESSION権限とRESTRICTED SESSION権限の両方を持つユーザー(通常はDBA)にのみデータベースへのアクセスを許可します。
OCI_DBSTARTUPFLAG_FORCE－ 新しいインスタンスを起動する前にABORTを使用して動作中のインスタンス(存在する場合)を停止します。この問題は、通常とは異なる状況下でのみ使用します。
コメント
SYSOPERまたはSYSDBAとしてOCI_PRELIM_AUTHモードでデータベースに接続する必要があります。ディスパッチャを介して共有サーバーには接続できません(つまり、OCI_DBSTARTUPFLAG_FORCEで実行中のインスタンスを再起動する場合)。クライアント側のパラメータ・ファイル(pfile)を使用するには、管理ハンドルでOCI_ATTR_ADMIN_PFILEを設定する必要があります。設定しない場合、サーバー側のパラメータ・ファイル(spfile)が使用されます。OCIDBStartup()のコールにより、サーバー上で1つのインスタンスが起動します。
OCI関数が実行される環境ハンドルを作成および初期化します。
用途
OCI関数が実行される環境ハンドルを作成および初期化します。
構文
sword OCIEnvCreate ( OCIEnv **envhpp,
ub4 mode,
const void *ctxp,
const void *(*malocfp)
(void *ctxp,
size_t size),
const void *(*ralocfp)
(void *ctxp,
void *memptr,
size_t newsize),
const void (*mfreefp)
(void *ctxp,
void *memptr))
size_t xtramemsz,
void **usrmempp );
パラメータ
エンコーディング設定がmodeで指定されている環境ハンドルへのポインタです。この設定は、envhppから導出された文ハンドルによって継承されます。
モードの初期化を指定します。次のモードが有効です。
OCI_DEFAULT - デフォルト値。非UTF-16エンコーディングです。
OCI_THREADED - スレッド環境を使用します。ユーザーに公開されていない内部データ構造体がマルチ・スレッドによって同時にアクセスされないように保護します。
OCI_OBJECT - オブジェクト機能を使用します。
OCI_EVENTS - パブリッシュ/サブスクライブ通知を利用します。
OCI_NO_UCB - 動的コールバック・ルーチンOCIEnvCallback()のコールを抑止します。デフォルトの動作では、環境の作成時にOCIEnvCallback()のコールが許可されます。
関連項目:
OCI_ENV_NO_MUTEX - このモードでは、相互排他(mutex)ロックは発生しません。環境ハンドル、または環境ハンドルから導出されたハンドルで行われたすべてのOCIコールは、シリアライズする必要があります。OCI_THREADEDは、OCI_ENV_NO_MUTEXを指定する場合にも指定する必要があります。
OCI_SUPPRESS_NLS_VALIDATION - NLS文字検証を抑制します。NLS文字検証は、Oracle Database 11g リリース1 (11.1)以上ではデフォルトでオンです。OCI_ENABLE_NLS_VALIDATIONを使用して、NLS文字検証を有効にします。詳細は「コメント」を参照してください。
OCI_NEW_LENGTH_SEMANTICS - キャラクタ・セットに関係なく、すべてのハンドルに対して一貫してバイト長セマンティクスを使用します。
OCI_NCHAR_LITERAL_REPLACE_ON - N置換をオンにします。
OCI_NCHAR_LITERAL_REPLACE_OFF - N置換をオフにします。このモードおよびOCI_NCHAR_LITERAL_REPLACE_ONのどちらも使用しない場合、置換は環境変数ORA_NCHAR_LITERAL_REPLACEによって決定されます。この値はTRUEまたはFALSEに設定できます。TRUEに設定すると置換がオンになり、設定しない場合はオフになりますが、オフがOCIでのデフォルト設定です。
OCI_ENABLE_NLS_VALIDATION - NLS文字検証を有効にします。詳細は「コメント」を参照してください。
メモリー・コールバック・ルーチンのユーザー定義コンテキストを指定します。
ユーザー定義のメモリー割当て関数を指定します。モードがOCI_THREADEDの場合、このメモリー割当てルーチンは、スレッド・セーフにしてください。
ユーザー定義のメモリー割当て関数の、コンテキスト・ポインタを指定します。
ユーザー定義のメモリー割当て関数によって割り当てられるメモリーのサイズを指定します。
ユーザー定義のメモリー再割当て関数を指定します。モードがOCI_THREADEDの場合、このメモリー割当てルーチンは、スレッド・セーフにしてください。
ユーザー定義のメモリー再割当て関数の、コンテキスト・ポインタを指定します。
メモリー・ブロックのポインタです。
新しく割り当てられるメモリーのサイズを指定します。
ユーザー定義のメモリー解放関数を指定します。モードがOCI_THREADEDの場合、このメモリー解放ルーチンは、スレッド・セーフにしてください。
ユーザー定義のメモリー解放関数の、コンテキスト・ポインタを指定します。
解放されるメモリーへのポインタです。
環境の継続時間中に割り当てられるユーザー・メモリーの量を指定します。
コールによりユーザーに割り当てられた、サイズxtramemszのユーザー・メモリーのポインタを戻します。
コメント
このコールにより、ユーザーによって指定されたモードを使用して、すべてのOCIコールの環境が作成されます。
注意:
このコールは、他のOCIコールより先に実行する必要があります。また、OCIInitialize()コールのかわりに使用してください。
このコールでは、残りのOCI関数で使用される環境ハンドルが戻されます。OCIには、それぞれ独自の環境モードを持つ複数の環境が存在する可能性があります。この関数では、どのモードで初期化を要求されても、プロセス・レベルの初期化を実行します。たとえば、環境をOCI_THREADEDで初期化した場合は、OCIで使用されるすべてのライブラリもそのスレッド・モードで初期化されます。
N置換をオンにすると、OCIStmtPrepare2()関数では、SQLテキストに対してN置換が実行され、生成されたSQLテキストは文ハンドルに格納されます。このため、アプリケーションがOCI_ATTR_STATEMENTを使用してSQLテキストをOCI文ハンドルから取得する場合、元のSQLテキストではなく変更されたSQLテキストが戻されます。
kshシェルでN置換をオンにするには、次のように指定します。
export ORA_NCHAR_LITERAL_REPLACE=TRUE
cshシェルでN置換をオンにするには、次のように指定します。
setenv ORA_NCHAR_LITERAL_REPLACE TRUE
リモート・データベースのリリースが10.2より前である場合、N置換は実行されません。
OCIライブラリを使用してDLLまたは共有ライブラリを記述している場合は、非推奨のOCIInitialize()コールのかわりにこのコールを使用します。
関連項目:
xtramemszパラメータおよびユーザー・メモリー割当ての詳細は、「ユーザー・メモリーの割当て」を参照してください
OCI_SUPPRESS_NLS_VALIDATIONモードおよびOCI_ENABLE_NLS_VALIDATIONモードでは、デフォルトで、クライアントとサーバーのキャラクタ・セットが同一で、クライアントとサーバーが両方ともOracle Database 11gリリース1 (11.1)以上である場合は、パフォーマンス向上のために文字データはOCIで検証されません。したがって、アプリケーションで不完全なマルチバイト文字を持つ文字列が挿入される場合(バインド変数の末尾など)、このような文字列はデータベースでそのまま保持されることがあります。
クライアントまたはサーバーがOracle Database 11gリリース1 (11.1)より前のリリースである場合、OCIで不完全な文字は使用できません。
Oracle Database 10gリリース2 (10.2)までデフォルトであったOCI_ENABLE_NLS_VALIDATIONモードでは、不完全なマルチバイト文字がデータベースで保持されなくなります(クライアントおよびサーバーのキャラクタ・セットが同一である場合)。アプリケーションで不完全なマルチバイト文字が生成される可能性があり、クライアントおよびサーバーのキャラクタ・セットが同一である環境でアプリケーションが実行可能な場合は、そのような不完全な文字が除去されるように、OCI_ENABLE_NLS_VALIDATIONモードを明示的に使用することをお薦めします。
例
N置換をオンにしたスレッド・セーフのOCI環境の作成
OCIEnv *envhp;
...
/* Create a thread-safe OCI environment with N' substitution turned on. */
if(OCIEnvCreate((OCIEnv **)&envhp,
(ub4)OCI_THREADED | OCI_NCHAR_LITERAL_REPLACE_ON,
(void *)0, (void * (*)(void *, size_t))0,
(void * (*)(void *, void *, size_t))0,
(void (*)(void *, void *))0,
(size_t)0, (void **)0))
{
printf("Failed: OCIEnvCreate()\n");
return 1;
}
...
OCI関数が実行される環境ハンドルを作成および初期化します。
用途
この関数は、OCIEnvCreate()関数の拡張バージョンです。
構文
sword OCIEnvNlsCreate ( OCIEnv **envhpp,
ub4 mode,
void *ctxp,
void *(*malocfp)
(void *ctxp,
size_t size),
void *(*ralocfp)
(void *ctxp,
void *memptr,
size_t newsize),
void (*mfreefp)
(void *ctxp,
void *memptr))
size_t xtramemsz,
void **usrmempp
ub2 charset,
ub2 ncharset );
パラメータ
エンコーディング設定がmodeで指定されている環境ハンドルへのポインタです。この設定は、envhppから導出された文ハンドルによって継承されます。
モードの初期化を指定します。次のモードが有効です。
OCI_DEFAULT - デフォルト値。非UTF-16エンコーディングです。
OCI_THREADED - スレッド環境を使用します。ユーザーに公開されていない内部データ構造体がマルチ・スレッドによって同時にアクセスされないように保護します。
OCI_OBJECT - オブジェクト機能を使用します。
OCI_EVENTS - パブリッシュ/サブスクライブ通知を利用します。
OCI_NO_UCB - 動的コールバック・ルーチンOCIEnvCallback()のコールを抑止します。デフォルトの動作では、環境の作成時にOCIEnvCallback()のコールが許可されます。
関連項目:
OCI_ENV_NO_MUTEX - このモードでは、相互排他(mutex)ロックは発生しません。環境ハンドル、または環境ハンドルから導出されたハンドルで行われたすべてのOCIコールは、シリアライズする必要があります。OCI_THREADEDは、OCI_ENV_NO_MUTEXを指定する場合にも指定する必要があります。
OCI_SUPPRESS_NLS_VALIDATION - NLS文字検証を抑制します。NLS文字検証は、Oracle Database 11g リリース1 (11.1)以上ではデフォルトでオンです。OCI_ENABLE_NLS_VALIDATIONを使用して、NLS文字検証を有効にします。詳細は「コメント」を参照してください。
OCI_NCHAR_LITERAL_REPLACE_ON - N置換をオンにします。
OCI_NCHAR_LITERAL_REPLACE_OFF - N置換をオフにします。このモードおよびOCI_NCHAR_LITERAL_REPLACE_ONのどちらも使用しない場合、置換は環境変数ORA_NCHAR_LITERAL_REPLACEによって決定されます。この値はTRUEまたはFALSEに設定できます。TRUEに設定すると置換がオンになり、設定しない場合はオフになりますが、オフがOCIでのデフォルト設定です。
OCI_ENABLE_NLS_VALIDATION - NLS文字検証を有効にします。詳細は「コメント」を参照してください。
メモリー・コールバック・ルーチンのユーザー定義コンテキストを指定します。
ユーザー定義のメモリー割当て関数を指定します。modeがOCI_THREADEDの場合、このメモリー割当てルーチンは、スレッド・セーフにしてください。
ユーザー定義のメモリー割当て関数の、コンテキスト・ポインタを指定します。
ユーザー定義のメモリー割当て関数によって割り当てられるメモリーのサイズを指定します。
ユーザー定義のメモリー再割当て関数を指定します。モードがOCI_THREADEDの場合、このメモリー割当てルーチンは、スレッド・セーフにしてください。
ユーザー定義のメモリー再割当て関数の、コンテキスト・ポインタを指定します。
メモリー・ブロックのポインタです。
新しく割り当てられるメモリーのサイズを指定します。
ユーザー定義のメモリー解放関数を指定します。モードがOCI_THREADEDの場合、このメモリー解放ルーチンは、スレッド・セーフにしてください。
ユーザー定義のメモリー解放関数の、コンテキスト・ポインタを指定します。
解放されるメモリーへのポインタです。
環境の継続時間中に割り当てられるユーザー・メモリーの量を指定します。
コールによりユーザーに割り当てられた、サイズxtramemszのユーザー・メモリーのポインタを戻します。
現行の環境ハンドルに対するクライアント側キャラクタ・セットです。0 (ゼロ)の場合は、NLS_LANG設定が使用されます。OCI_UTF16IDは有効な設定で、メタデータおよびCHARデータで使用されます。
現行の環境ハンドルに対するクライアント側各国語キャラクタ・セットです。0 (ゼロ)の場合は、NLS_NCHAR設定が使用されます。OCI_UTF16IDは有効な設定で、NCHARデータで使用されます。
戻り値
OCI_SUCCESS - 環境ハンドルは正常に作成されました。
OCI_ERROR - エラーが発生しました。
コメント
このコールにより、ユーザーによって指定されたモードを使用して、すべてのOCIコールの環境が作成されます。
OCIEnvNlsCreate()を使用して環境ハンドルを作成すると、バインド・ハンドルおよび定義ハンドルの実際の長さと戻される長さは、常にバイト単位で表されます。これは、次のコールに適用されます。
OCIBindByName()およびOCIBindByName2()
OCIBindByPos()およびOCIBindByPos2()
OCIBindDynamic()
OCIDefineByPos()およびOCIDefineByPos2()
OCIDefineDynamic()
環境の作成時に、この関数を使用してcharset IDおよびncharset IDを設定できます。これは、OCIEnvCreate()関数を拡張した関数です。
この関数は、クライアント側データベースおよび各国語キャラクタ・セットとしてcharsetおよびncharsetを0 (ゼロ)以外の値に設定し、NLS_LANGおよびNLS_NCHARで指定した値を置換します。charsetおよびncharsetが0 (ゼロ)の場合、この関数はOCIEnvCreate()の動作と完全に同じになります。charsetは、暗黙的なフォーム属性を持つメタデータおよびデータのエンコーディングを制御し、ncharsetは、SQLCS_NCHARフォーム属性を持つデータのエンコーディングを制御します。
OCI_UTF16IDは、OCIEnvNlsCreate()では設定できますが、NLS_LANGまたはNLS_NCHARでは設定できません。NLS_LANGおよびNLS_NCHARのキャラクタ・セットIDにアクセスするには、OCINlsEnvironmentVariableGet()を使用します。
このコールでは、残りのOCI関数で使用される環境ハンドルが戻されます。OCIには、それぞれ独自の環境モードを持つ複数の環境が存在する可能性があります。この関数では、どのモードで初期化を要求されても、プロセス・レベルの初期化を実行します。たとえば、環境をOCI_THREADEDで初期化した場合は、OCIで使用されるすべてのライブラリもそのスレッド・モードで初期化されます。
N置換をオンにすると、OCIStmtPrepare2()関数では、SQLテキストに対してN置換が実行され、生成されたSQLテキストは文ハンドルに格納されます。このため、アプリケーションがOCI_ATTR_STATEMENTを使用してSQLテキストをOCI文ハンドルから取得する場合、元のSQLテキストではなく変更されたSQLテキストが戻されます。
kshシェルでN置換をオンにするには、次のように指定します。
export ORA_NCHAR_LITERAL_REPLACE=TRUE
cshシェルでN置換をオンにするには、次のように指定します。
setenv ORA_NCHAR_LITERAL_REPLACE TRUE
リモート・データベースのリリースが10.2より前である場合、N置換は実行されません。
OCIライブラリを使用してDLLまたは共有ライブラリを記述している場合は、非推奨のOCIInitialize()コールのかわりにこのコールを使用します。
関連項目:
xtramemszパラメータおよびユーザー・メモリー割当ての詳細は、「ユーザー・メモリーの割当て」を参照してください
関連する関数でN置換を設定する方法を示すコード例については、「OCIEnvCreate()」を参照してください
OCI_SUPPRESS_NLS_VALIDATIONモードおよびOCI_ENABLE_NLS_VALIDATIONモードでは、デフォルトで、クライアントとサーバーのキャラクタ・セットが同一で、クライアントとサーバーが両方ともOracle Database 11gリリース1 (11.1)以上である場合は、パフォーマンス向上のために文字データはOCIで検証されません。したがって、アプリケーションで不完全なマルチバイト文字を持つ文字列が挿入される場合(バインド変数の末尾など)、このような文字列はデータベースでそのまま保持されることがあります。
クライアントまたはサーバーがOracle Database 11gリリース1 (11.1)より前のリリースである場合、OCIで不完全な文字は使用できません。
Oracle Database 10gリリース2 (10.2)までデフォルトであったOCI_ENABLE_NLS_VALIDATIONモードでは、不完全なマルチバイト文字がデータベースで保持されなくなります(クライアントおよびサーバーのキャラクタ・セットが同一である場合)。アプリケーションで不完全なマルチバイト文字が生成される可能性があり、クライアントおよびサーバーのキャラクタ・セットが同一である環境でアプリケーションが実行可能な場合は、そのような不完全な文字が除去されるように、OCI_ENABLE_NLS_VALIDATIONモードを明示的に使用することをお薦めします。
OCILogon2()またはOCILogon()を使用して取得したセッションを解放します。
用途
OCILogon2()またはOCILogon()を使用して取得したセッションを解放します。
構文
sword OCILogoff ( OCISvcCtx *svchp
OCIError *errhp );
パラメータ
コメント
この関数は、OCILogon2()またはOCILogon()を使用して取得したセッションを解放するために使用します。OCILogon()を使用した場合、この関数はその接続およびセッションを終了します。OCILogon2()を使用した場合、このコールの動作は、対応するOCILogon2()関数がコールされたときのmodeによって決まります。デフォルトでは、この関数は、セッションまたは接続をクローズします。接続プーリングの場合、この関数は、セッションをクローズして接続をプールに戻します。セッション・プーリングの場合、この関数は、セッションと接続のペアをプールに戻します。
関連項目:
アプリケーションのログオンおよびログオフの詳細は、「アプリケーションの初期化、接続およびセッション作成」を参照してください
用途
単純なログイン・セッションを作成します。
構文
sword OCILogon ( OCIEnv *envhp,
OCIError *errhp,
OCISvcCtx **svchp,
const OraText *username,
ub4 uname_len,
const OraText *password,
ub4 passwd_len,
const OraText *dbname,
ub4 dbname_len );
パラメータ
OCI環境ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
サービス・コンテキスト・ポインタです。
ユーザー名です。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。
usernameの長さは、エンコーディングの有無に関係なく、バイト単位です。
ユーザーのパスワードです。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。
passwordの長さは、エンコーディングの有無に関係なく、バイト単位です。
接続先のデータベース名です。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。
dbnameの長さは、エンコーディングの有無に関係なく、バイト単位です。
コメント
この関数は、アプリケーションのためのログイン・セッションを作成するときに使用します。
注意:
TPモニター・アプリケーションなどの複雑なセッションを必要とするユーザーは、「アプリケーションの初期化、接続およびセッション作成」を参照してください。
このコールは、渡されたサービス・コンテキスト・ハンドルの割当てを行います。このコールは、セッションに対応付けられたサーバーとユーザー・セッション・ハンドルの暗黙的な割当ても実行します。これらのハンドルは、サービス・コンテキスト・ハンドルに対してOCIArrayDescriptorAlloc()をコールすることにより取り出せます。
関連関数
用途
セッションを取得します。このセッションは、基礎となる新規の接続があるセッション、既存の接続プールから仮想接続によって開始されたセッション、または既存のセッション・プールからのセッションである場合があります。この関数がコールされるときのmodeによって、動作が決まります。
構文
sword OCILogon2 ( OCIEnv *envhp,
OCIError *errhp,
OCISvcCtx **svchp,
const OraText *username,
ub4 uname_len,
const OraText *password,
ub4 passwd_len,
const OraText *dbname,
ub4 dbname_len );
ub4 mode );
パラメータ
OCI環境ハンドルです。接続プーリングおよびセッション・プーリングの場合は、それぞれのプールが作成されたときの環境ハンドルに設定する必要があります。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
OCIサービス・コンテキスト・ポインタのアドレスです。サーバーおよびセッション・ハンドルが格納されます。
デフォルトでは、新しいセッションおよびサーバー・ハンドルが割り当てられ、接続およびセッションが開始し、サービス・コンテキストにこれらのハンドルが移入されます。
接続プーリングの場合、新しいセッション・ハンドルが割り当てられ、接続プールから仮想接続によってセッションが開始します。
セッション・プーリングの場合、サービス・コンテキストには、セッション・プールからセッション・ハンドルとサーバー・ハンドルの既存のペアが移入されます。
サーバーの属性、およびサービス・コンテキスト・ポインタに関連付けられたユーザーまたはセッション・ハンドルは変更できないことに注意してください。変更を行うと、OCIAttrSet()コールでエラーが戻されます。
変更できるサービス・コンテキスト属性は、OCI_ATTR_STMTCACHESIZEのみです。
セッションを認証するために使用するユーザー名です。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。
usernameの長さは、エンコーディングの有無に関係なく、バイト単位です。
ユーザーのパスワードです。接続プーリングでこのパラメータがNULLの場合、OCILogon2()では、プロキシ・ユーザーのログインとみなされます。このような場合は、プール・ユーザーがプロキシ・ユーザーの認証に使用され、プロキシ接続が暗黙的に作成されます。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。
passwordの長さは、エンコーディングの有無に関係なく、バイト単位です。
デフォルトでは、Oracle Databaseへの接続で使用する接続文字列を示します。
接続プーリングの場合は、仮想接続を取得してセッションを開始するための接続プールを示します。この値は、OCIConnectionPoolCreate()コールによって戻されます。
セッション・プーリングの場合は、セッションを取得するプールを示します。これは、OCISessionPoolCreate()コールによって戻されます。
dbnameは、OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。
dbnameの長さです。セッション・プーリングおよび接続プーリングの場合、この値は、それぞれOCISessionPoolCreate()コールまたはOCIConnectionPoolCreate()コールによって戻されます。
指定できる値は、次のとおりです。
OCI_DEFAULT
OCI_LOGON2_CPOOL
OCI_LOGON2_SPOOL
OCI_LOGON2_STMTCACHE
OCI_LOGON2_PROXY
デフォルト(プーリング以外の場合)では、次のモードが有効です。
OCI_DEFAULT－OCILogon()のコールと等価です。
OCI_LOGON2_STMTCACHE－ 文キャッシュを使用可能にします。
接続プーリングの場合は、次のモードが有効です。
OCI_LOGON2_CPOOLまたはOCI_CPOOL - 接続プーリングを使用する場合に設定する必要があります。
OCI_LOGON2_STMTCACHE－ 文キャッシュを使用可能にします。
接続プーリングでプロキシ認証を使用するには、パスワードはNULLに設定する必要があります。OCILogon2()コールで提供されたユーザー名によって認証されるセッションが、OCIConnectionPoolCreate()コールで提供されたプロキシ資格証明を通じて与えられます。
セッション・プーリングの場合は、次のモードが有効です。
OCI_LOGON2_SPOOL - セッション・プーリングを使用する場合に設定する必要があります。
OCI_LOGON2_STMTCACHE－ 文キャッシュを使用可能にします。
OCI_LOGON2_PROXY: プロキシ認証を使用します。OCILogon2()コールで提供されたユーザー名によって認証されるセッションが、OCISessionPoolCreate()コールで提供されたプロキシ資格証明を通じて与えられます。
コメント
なし。
用途
OCIオペレーションの対象となるデータ・ソースへのアクセス・パスを作成します。
構文
sword OCIServerAttach ( OCIServer *srvhp,
OCIError *errhp,
const OraText *dblink,
sb4 dblink_len,
ub4 mode );
パラメータ
このコールにより初期化される未初期化サーバー・ハンドルです。初期化済のサーバー・ハンドルを渡すとエラーが発生します。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
使用するデータベース・サーバーを指定します。このパラメータは、接続文字列またはサービス・ポイントを指定する文字列を指示します。接続文字列がNULLの場合、このコールは、デフォルト・ホストに接続します。文字列自体がUTF-16エンコーディング・モードであるかどうかは、アプリケーションの環境ハンドルのmodeまたは設定によって決まります。dblinkの長さは、dblink_lenで指定します。dblinkポインタは、戻り時にコール元によって解放されます。
mode =OCI_CPOOL時の接続先プールの名前です。この名前は、OCIConnectionPoolCreate()で作成された接続プールのpoolNameパラメータと同じ名前であることが必要です。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。
dblinkが指し示す文字列の長さです。接続文字列名または別名を有効にするには、dblink_lenは0 (ゼロ)以外にしてください。値はバイト単位です。
mode =OCI_CPOOL時のpoolNameの長さは、エンコーディングの有無に関係なく、バイト単位です。
様々な操作モードを指定します。次のモードが有効です。
OCI_DEFAULT - エンコーディングについて、この値では、サーバー・ハンドルで環境ハンドルの設定が使用されることを示しています。
OCI_CPOOL - 接続プーリングを使用します。
連結済のサーバー・ハンドルは、任意の接続セッション・ハンドルに設定されている可能性があるため、ここでのmode値は、セッション・ハンドルに対しては無効です。
コメント
このコールは、OCIアプリケーションと特定のサーバー間の対応付けを作成するときに使用します。
このコールでは、接続プーリングが有効になった時点で、OCIConnectionPoolCreate()がコールされ、poolNameが指定されていると想定しています。
このコールは、サーバー・コンテキスト・ハンドルを初期化しますが、ハンドルはOCIHandleAlloc()のコールを使用して事前に割り当てる必要があります。このコールによって初期化されたサーバー・コンテキスト・ハンドルは、OCIAttrSet()のコールを介してサービス・コンテキストに対応付けられます。対応付けを行うと、そのサーバーに対してOCIオペレーションを実行できます。
複数のサーバーに対してアプリケーションを実行している場合、複数のサーバー・コンテキスト・ハンドルを維持できます。OCIオペレーションは、現在サービス・コンテキストに対応付けられているサーバー・コンテキストに対して実行されます。
OCIServerAttach()が正常に完了すると、Oracle Databaseシャドウ・プロセスが開始されます。Oracle Databaseシャドウ・プロセスをクリーン・アップするには、OCISessionEnd()およびOCIServerDetach()をコールする必要があります。コールしないと、シャドウ・プロセスが蓄積され、LinuxまたはUNIXシステムのプロセス数が足りなくなります。データベースが再起動したときにプロセス数が不足している場合は、データベースが起動しないことがあります。
例
次のコードは、OCIServerAttach()の使用方法の例です。このコード・セグメントでは、サーバー・ハンドルを割り当て、連結コールを行い、サービス・コンテキスト・ハンドルを割り当て、最後にそれにサーバー・コンテキストを設定します。
OCIServerAttach()コールの使用
OCIHandleAlloc( (void *) envhp, (void **) &srvhp, (ub4)
OCI_HTYPE_SERVER, 0, (void **) 0);
OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0, (ub4) OCI_DEFAULT);
OCIHandleAlloc( (void *) envhp, (void **) &svchp, (ub4)
OCI_HTYPE_SVCCTX, 0, (void **) 0);
/* set attribute server context in the service context */
OCIAttrSet( (void *) svchp, (ub4) OCI_HTYPE_SVCCTX, (void *) srvhp,
(ub4) 0, (ub4) OCI_ATTR_SERVER, (OCIError *) errhp);
用途
OCIオペレーションの対象となるデータ・ソースへのアクセス・パスを削除します。
構文
sword OCIServerDetach ( OCIServer *srvhp,
OCIError *errhp,
ub4 mode );
パラメータ
未初期化状態にリセットされる初期化済サーバー・コンテキストへのハンドルです。ハンドルは割当て解除されません。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
様々な操作モードを指定します。有効なモードはデフォルト・モード用のOCI_DEFAULTのみです。
コメント
このコールは、OCIオペレーションの対象となるデータ・ソースへのアクセス・パスを削除します。アクセス・パスは、OCIServerAttach()のコールによって確立されました。
用途
ユーザー・セッションを作成し、指定のサーバーに対してユーザー・セッションを開始します。
構文
sword OCISessionBegin ( OCISvcCtx *svchp,
OCIError *errhp,
OCISession *usrhp,
ub4 credt,
ub4 mode );
パラメータ
サービス・コンテキストへのハンドルです。svchpには、有効なサーバー・ハンドルを設定する必要があります。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
このコールによって初期化されるユーザー・セッション・コンテキストへのハンドルです。
ユーザー・セッションの作成に使用する資格証明のタイプを指定します。credtの有効な値は次のとおりです。
OCI_CRED_RDBMS - 資格証明としてデータベースのユーザー名とパスワードを使用して認証します。このコールの前に、ユーザー・セッション・コンテキストにOCI_ATTR_USERNAMEとOCI_ATTR_PASSWORD属性を設定しておく必要があります。
OCI_CRED_EXT - 外部資格証明を使用して認証します。ユーザー名とパスワードは提供されません。
OCI_DEFAULT - このモードでは、戻されるユーザー・セッション・コンテキストは、svchpに指定されたサーバー・コンテキストとともにのみ設定できます。エンコーディングについては、サーバー・ハンドルでは、環境ハンドルの設定が使用されます。
OCI_MIGRATE - このモードでは、新しいユーザー・セッション・コンテキストを、サービス・ハンドル内で別のサーバー・ハンドルで設定できます。このモードにより、ユーザー・セッション・コンテキストが確立されます。移行可能なセッションを作成するには、サービス・ハンドルが移行不可能なユーザー・セッションですでに設定されている必要があります。これは、移行可能なセッションの「作成者」セッションになります。つまり、移行可能なセッションは、移行不可能な親セッションを持つ必要があります。
セッションが下位の接続プールを使用する場合、OCI_MIGRATEは使用しないでください。セッションの移行と多重化はユーザーに意識させることなく行われます。
OCI_SYSDBA - このモードでは、SYSDBAアクセス用に認証されます。
OCI_SYSOPER - このモードでは、SYSOPERアクセス用に認証されます。
OCI_SYSASM - このモードでは、SYSASMアクセス用に認証されます。
OCI_SYSBKB - このモードでは、SYSBACKUPアクセス用に認証されます。
OCI_SYSDGD - このモードでは、SYSDGアクセス用に認証されます。
OCI_SYSKMT - このモードでは、SYSKMアクセス用に認証されます。
OCI_PRELIM_AUTH - このモードは、特定の管理タスクを認証するためにOCI_SYSDBAまたはOCI_SYSOPERとともにのみ使用できます。
OCI_STMT_CACHE - 指定のサービス・ハンドルにおいてデフォルト・サイズの文キャッシュが可能です。アプリケーションが後からそのサービス・ハンドルでOCI_ATTR_STMTCACHESIZEを使用してサイズを明示的に設定する場合、このモードを渡すのはオプションです。
コメント
OCISessionBegin()コールは、サービス・コンテキスト・ハンドルに設定されたサーバー・セットに対して、ユーザーを認証するときに使用します。
注意:
セッションを開始するときは戻されたエラーをすべてチェックしてください。たとえば、アカウントのパスワードの期限が切れた場合は、ORA-28001エラーが戻されます。
リリース8.1以上では、サーバー・ハンドルに要求を行う前に、そのサーバー・ハンドルに対してOCISessionBegin()をコールする必要があります。OCISessionBegin()は、サーバー・ハンドルによってサービス・コンテキスト内に指定されたユーザーによるOracle Databaseへの接続に対する認証のみをサポートします。つまり、OCIServerAttach()をコールしてサーバー・ハンドルを初期化した後、指定のサーバーに対してユーザーを認証するためにOCISessionBegin()をコールする必要があります。
Unicodeを使用する場合は、modeまたは環境ハンドルを適切に設定し、セッション・ハンドルusrhpで設定されたユーザー名とパスワードをUnicodeにする必要があります。この関数をコールしてユーザー名とパスワードでセッションを開始する前に、OCIAttrSet()をコールして、これら2つのUnicode文字列を対応するバイト長でセッション・ハンドルに設定しておく必要があります。これは、OCIAttrSet()がvoidポインタのみを受け入れるためです。次に、OCISessionBegin()により文字列バッファが解釈されます。
指定のサーバー・ハンドルに対して、最初にOCISessionBegin()をコールした場合は、ユーザー・セッションは、移行可能モード(OCI_MIGRATE)では作成されません。
サーバー・ハンドルに対してOCISessionBegin()をコールした後、アプリケーションではOCISessionBegin()を再度コールし、別のユーザー・セッション・ハンドルを、別の(または同じ)資格証明と別の(または同じ)操作モードを使用して初期化できます。アプリケーションでユーザーをOCI_MIGRATEモードで認証する場合、サービス・ハンドルは、移行不可能なユーザー・ハンドルに関連付けられている必要があります。このユーザー・ハンドルのユーザーIDは、移行可能なユーザー・セッションの所有者IDになります。移行可能なすべてのセッションは、移行不可能な親セッションを持つ必要があります。
OCI_MIGRATEを指定しない場合、ユーザー・セッション・コンテキストは、svchpに設定されたサーバー・ハンドルと同じサーバー・ハンドルでしか使用できません。OCI_MIGRATEモードを指定した場合、ユーザー認証は、別のサーバー・ハンドルで設定できます。ただし、ユーザー・セッション・コンテキストは、同じデータベース・インスタンスに解決するサーバー・ハンドルでのみ使用できます。セキュリティ・チェックは、セッションの切替え中に行われます。セッションは、ユーザーIDが作成者のユーザーIDまたは固有のユーザーIDと同一であるプロセスに現在接続している移行不可能なセッションがある場合にかぎり、そのプロセスへ移行できます。
仮想サーバー・ハンドルが接続プールを指し示している(modeがOCI_CPOOLに設定された状態でOCIServerAttach()がコールされた)場合、OCISessionBegin()へのコールでOCI_MIGRATEフラグを設定しないでください。Oracle Databaseは、互換性上の理由によってのみ、このフラグを渡すことをサポートします。接続プールを使用するときに、セッションが実際の接続に対して透過的に多重化される独自の専用(仮想)接続を持っているように感じられるため、OCI_MIGRATEフラグは使用しないでください。
OCI_SYSDBA、OCI_SYSOPERおよびOCI_PRELIM_AUTHは、主ユーザー・セッション・コンテキストでのみ使用できます。
OCISessionBegin()のコール用に資格証明を与えるために、2通りの方法がサポートされています。最初の方法は、OCISessionBegin()に渡されるユーザー・セッション・ハンドル内にデータベース認証用の有効なユーザー名とパスワードのペアを用意することです。この方法では、OCIAttrSet()を使用して、ユーザー・セッション・ハンドルに対してOCI_ATTR_USERNAME属性およびOCI_ATTR_PASSWORD属性を設定します。これにより、OCI_CRED_RDBMSを指定してOCISessionBegin()がコールされます。
注意:
ユーザー名とパスワード属性は、OCISessionEnd()を使用してユーザー・セッション・ハンドルを終了しても変更されず、以降のOCISessionBegin()のコールで再使用できます。再使用しない場合は、次回のOCISessionBegin()コールの前に新しい値を設定しなおす必要があります。
2つ目の方法は、外部資格証明を使用することです。この方法では、OCISessionBegin()をコールする前に、ユーザー・セッション・ハンドルについて属性を設定する必要はありません。資格証明のタイプはOCI_CRED_EXTです。これは、Oracle7のconnect/構文と等価です。すでにOCI_ATTR_USERNAMEおよびOCI_ATTR_PASSWORDに値が設定してある場合、OCI_CRED_EXTを使用すると、これらの値は無視されます。
資格証明を設定するもう1つの方法では、OCI_MIGSESSION属性とともに、認証されているユーザーのセッションIDを使用します。このIDは、OCIAttrGet()コールを使用して認証されたユーザーのセッション・ハンドルから抽出できます。
例
次のコードはOCISessionBegin()の使用方法の例です。この例では、ユーザー・セッション・ハンドルを割り当て、ユーザー名とパスワードを設定し、OCISessionBegin()をコールして、最後にサービス・コンテキスト内にユーザー・セッションを設定します。
OCISessionBegin()コールの使用
/* allocate a user session handle */
OCIHandleAlloc((void *)envhp, (void **)&usrhp, (ub4)
OCI_HTYPE_SESSION, (size_t) 0, (void **) 0);
OCIAttrSet((void *)usrhp, (ub4)OCI_HTYPE_SESSION, (void *)"hr",
(ub4)strlen("hr"), OCI_ATTR_USERNAME, errhp);
OCIAttrSet((void *)usrhp, (ub4)OCI_HTYPE_SESSION, (void *)"hr",
(ub4)strlen("hr"), OCI_ATTR_PASSWORD, errhp);
checkerr(errhp, OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS,
OCI_DEFAULT));
OCIAttrSet((void *)svchp, (ub4)OCI_HTYPE_SVCCTX, (void *)usrhp,
(ub4)0, OCI_ATTR_SESSION, errhp);
関連関数
用途
OCISessionBegin()によって作成されたユーザー・セッション・コンテキストを終了します。
構文
sword OCISessionEnd ( OCISvcCtx *svchp,
OCIError *errhp,
OCISession *usrhp,
ub4 mode );
パラメータ
サービス・コンテキスト・ハンドルです。svchpには、有効なサーバー・ハンドルおよびユーザー・セッション・ハンドルを対応付ける必要があります。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
このユーザーの認証を解除します。このパラメータがNULLとして渡された場合は、サービス・コンテキスト・ハンドル内のユーザーの認証が解除されます。
有効なモードはOCI_DEFAULTのみです。
コメント
サービス・コンテキストに対応付けられているユーザー・セキュリティ・コンテキストがこのコールによって無効化されます。ユーザー・セッション・コンテキスト用の記憶域は解放されません。サービス・コンテキストによって指定されたトランザクションが暗黙的にコミットされます。トランザクション・ハンドルは、明示的に割り当てられ、使用されていない場合は、解放されます。このユーザーのためにサーバー上に割り当てられていたリソースが解放されます。ユーザー・セッション・ハンドルは、OCISessionBegin()の次回のコールで再使用できます。
用途
セッションを取得します。このセッションは、基礎となる新規の接続があるセッション、既存の接続プールから仮想接続によって開始されたセッション、または既存のセッション・プールからのセッションである場合があります。この関数がコールされるときのmodeによって、動作が決まります。
構文
sword OCISessionGet ( OCIenv *envhp,
OCIError *errhp,
OCISvcCtx **svchp,
OCIAuthInfo *authInfop,
OraText *dbName,
ub4 dbName_len,
const OraText *tagInfo,
ub4 tagInfo_len,
OraText **retTagInfo,
ub4 *retTagInfo_len,
boolean *found,
ub4 mode );
パラメータ
OCI環境ハンドルです。接続プーリングおよびセッション・プーリングの場合は、それぞれのプールが作成されたときの環境ハンドルに設定する必要があります。
OCIエラー・ハンドルです。
OCIサービス・コンテキスト・ポインタのアドレスです。サーバーおよびセッション・ハンドルが格納されます。
デフォルトでは、新しいセッションおよびサーバー・ハンドルが割り当てられ、接続およびセッションが開始し、サービス・コンテキストにこれらのハンドルが移入されます。
接続プーリングの場合、新しいセッション・ハンドルが割り当てられ、接続プールから仮想接続によってセッションが開始します。
セッション・プーリングの場合、サービス・コンテキストには、セッション・プールからセッション・ハンドルとサーバー・ハンドルの既存のペアが移入されます。
サーバーの属性、およびサービス・コンテキスト・ポインタに関連付けられたユーザー・ハンドルとセッション・ハンドルは変更しないでください。変更を行うと、OCIAttrSet()コールでエラーが戻されます。
変更できるサービス・コンテキスト属性は、OCI_ATTR_STMTCACHESIZEのみです。
セッションの取得時に使用する認証情報ハンドルです。
接続プーリングの場合、デフォルトでは、このハンドルはセッション・ハンドルのすべての属性を使用できます。
セッション・プーリングの場合、認証情報ハンドルは、セッション・プールのモードがOCI_SPC_HOMOGENEOUS以外の場合のみ使用されます。
OCIAuthInfoハンドルで設定できる属性は、セッション作成前属性とセッション作成後属性に分類できます。セッション作成前属性は次のとおりです。
セッション作成前属性
セッション作成前属性は、セッションを作成する前に指定する必要があるOCI属性です。これらの属性は、セッションの作成に使用され、セッションの作成後には変更できません。セッション作成前属性は次のとおりです。
OCI_ATTR_USERNAME
OCI_ATTR_PASSWORD
OCI_ATTR_CONNECTION_CLASS
OCI_ATTR_DISTINGUISHED_NAME
OCI_ATTR_INITIAL_CLIENT_ROLES
OCI_ATTR_EDITION
セッション作成後属性
セッション作成後属性は、セッションを作成した後で指定できるものです。これらは、セッションの作成後に、何度でも自由に変更できます。セッションが作成された後は、OCISessionハンドルで次の属性を設定できます。
OCI_ATTR_CLIENT_IDENTIFIER
OCI_ATTR_MODULE
OCI_ATTR_ACTION
OCI_ATTR_COLLECT_CALL_TIME
OCI_ATTR_DEFAULT_LOBPREFETCH_SIZE
OCI_ATTR_SESSION_STATE
関連項目:
demoディレクトリのcdemosp.c
属性の詳細は、「ユーザー・セッション・ハンドル属性」を参照してください
「コメント」の項
デフォルトでは、Oracle Databaseへの接続で使用する接続文字列を示します。
接続プーリングの場合は、仮想接続を取得してセッションを開始するための接続プールを示します。この値は、OCIConnectionPoolCreate()コールによって戻されます。
セッション・プーリングの場合は、セッションを取得するプールを示します。これは、OCISessionPoolCreate()コールによって戻されます。
dbNameの長さです。セッション・プーリングおよび接続プーリングの場合、この値は、それぞれOCISessionPoolCreate()またはOCIConnectionPoolCreate()のコールによって戻されます。
このパラメータは、セッション・プーリングでのみ使用します。
これは、ユーザーが使用するセッションのタイプを示します。デフォルト・セッションを使用する場合、このパラメータをNULLに設定する必要があります。このパラメータの詳しい説明は、「コメント」を参照してください。
バイトで示したtagInfoの長さです。セッション・プーリングでのみ使用します。
このパラメータは、セッション・プーリングでのみ使用します。これは、ユーザーに戻されるセッションのタイプを示します。このパラメータの詳しい説明は、「コメント」を参照してください。
バイトで示したretTagInfoの長さです。セッション・プーリングでのみ使用します。
このパラメータは、セッション・プーリングでのみ使用します。ユーザーが要求したセッションのタイプが戻された場合(つまり、tagInfoとretTagInfoの値が同じ場合)、foundはTRUEに設定されます。それ以外の場合、foundはFALSEに設定されます。
次のモードが有効です。
OCI_DEFAULT
OCI_SESSGET_CPOOL
OCI_SESSGET_SPOOL
OCI_SESSGET_CREDPROXY
OCI_SESSGET_CREDEXT - 異種プールでのみサポートされています。
OCI_SESSGET_PURITY_NEW
OCI_SESSGET_PURITY_SELF
OCI_SESSGET_SPOOL_MATCHANY
OCI_SESSGET_STMTCACHE
OCI_SESSGET_SYSDBA
デフォルト(プーリング以外)の場合では、次のモードが有効です。
OCI_SESSGET_STMTCACHE - セッションでの文キャッシュを使用可能にします。
OCI_SESSGET_CREDEXT - 外部資格証明を使用して認証されたセッションを戻します。
OCI_SESSGET_SYSDBA - プーリング以外またはセッション・プーリングについてSYSDBA権限を持つセッションを戻します。
接続プーリングの場合は、次のモードが有効です。
OCI_SESSGET_CPOOL - 接続プーリングを使用する場合に設定する必要があります。
OCI_SESSGET_STMTCACHE - セッションでの文キャッシュを使用可能にします。
OCI_SESSGET_CREDPROXY - プロキシ・セッションを戻します。ユーザーには、OCISessionGet()コールで提供されたユーザー名によって認証されるセッションが、OCIConnectionPoolCreate()コールで提供されたプロキシ資格証明を通じて与えられます。
OCI_SESSGET_CREDEXT - 外部資格証明を使用して認証されたセッションを戻します。
セッション・プーリングの場合は、次のモードが有効です。
OCI_SESSGET_SPOOL - セッション・プーリングを使用する場合に設定する必要があります。
OCI_SESSGET_SYSDBA - プーリング以外またはセッション・プーリングについてSYSDBA権限を持つセッションを戻します。
OCI_SESSGET_CREDEXT - 外部資格証明を使用して認証されたセッションを戻します。
OCI_SESSGET_CREDPROXY－ ユーザーには、OCISessionGet()コールで提供されたユーザー名によって認証されるセッションが、OCISessionPoolCreate()コールで提供されたプロキシ資格証明を通じて与えられます。
OCI_SESSGET_SPOOL_MATCHANY - タグ付けの動作を参照します。このモードに設定すると、要求されたタグと異なるタグを持つセッションを戻すことができます。「コメント」の項を参照してください。
データベース常駐接続プーリングの場合は、次のモードが有効です。
OCI_SESSGET_PURITY_SELF - アプリケーションでは前に使用したセッションを使用できます。アプリケーション固有のタグを指定することもできます。
OCI_SESSGET_PURITY_NEW - アプリケーションには、前のセッション状態で保持されていない新規セッションが必要です。これは、デフォルトです。
コメント
ユーザーは、タグを使用して、プール内のセッションをカスタマイズできます。クライアントは、デフォルト・セッションまたはタグが付いていないセッションをプールから取得して、特定の属性(グローバリゼーション設定など)をセッションに設定し、OCISessionRelease()コールでそのセッションをプールに戻すと、セッションに適切なラベル(タグ)を付けることができます。
ユーザーまたは他のユーザーは、OCISessionGet()コールで同じタグを指定して、同じ属性を持つセッションを要求できます。
タグ'A'を持つセッションをユーザーが要求し、一致するセッションが使用不可である場合は、適切に認証されたタグなしのセッション(NULLタグを持つセッション)が戻されます(そのセッションが使用可能な場合)。タグなしのセッションが使用不可で、OCI_SESSGET_SPOOL_MATCHANYが指定されている場合は、適切に認証されて異なるタグを持つセッションが戻されます。OCI_SESSGET_SPOOL_MATCHANYが設定されていない場合は、異なるタグを持つセッションが戻されることはありません。
次のコード例はセッション・プーリングを指定したOCI_ATTR_MODULEの使用方法を示しています。
OCIセッション・プーリングを指定したOCI_ATTR_MODULE属性の使用
Oratext *module = (Oratext*) "mymodule";
/* Allocate the pool handle */
checkerr(errhp,OCIHandleAlloc(envhp,(void**)&poolhp,
OCI_HTYPE_SPOOL,0,0));
checkerr(errhp,OCISessionPoolCreate(envhp,
errhp,poolhp,&poolname,&pnamelen,
(oratext*)conn_str,
len,min,max,incr,0,0,0,0,OCI_DEFAULT));
/* Allocate the auth handle for session get */
checkerr(errhp, OCIHandleAlloc(envhp,
(void**)&authp, OCI_HTYPE_AUTHINFO, 0,0));
checkerr(errhp,OCIAttrSet(authp, OCI_HTYPE_AUTHINFO,
username, strlen((char*)username), OCI_ATTR_USERNAME,errhp);
checkerr(errhp,OCIAttrSet(authp, OCI_HTYPE_AUTHINFO,
password, strlen((char*)password), OCI_ATTR_PASSWORD,
errhp));
checkerr(errhp,OCISessionGet(envhp,errhp,
&svchp,authp,poolname, pnamelen,0,0,0,0,0,
OCI_SESSGET_SPOOL));
/* Get the user handle from the service context handle */
checkerr(errhp, OCIAttrGet(svhcp, OCI_HTYPE_SVCCTX, &usrhp_svc,
0,OCI_ATTR_SESSION,errhp));
/* Set module name on the user handle that you obtained */
checkerr (errhp, OCIAttrSet(usrhp_svc, OCI_HTYPE_SESSION, module,
strlen((char*)module), OCI_ATTR_MODULE,errhp));
/* Make Database calls. */
OCIセッション・プールでサポートされている属性の制限
OCIセッション・プールを指定した、次のセッション作成前属性を使用できます。
OCI_ATTR_EDITION OCI_ATTR_DRIVER_NAME OCI_ATTR_USERNAME, OCI_ATTR_PASSWORD, OCI_ATTR_CONNECTION_CLASS, OCI_ATTR_PURITY
ただし、OCI_ATTR_EDITIONおよびOCI_ATTR_DRIVERNAMEは、OCISPoolハンドルの属性であるOCIAuthInfoハンドルで設定することによって、OCISessionPoolCreate()のコール中にのみ、指定することができます。これらは、個々のOCISessionGet()コールに渡されるOCIAuthInfoハンドルでは、指定することはできません。これにより、OCIセッション・プールの一部であるすべてのセッションがこれらの属性の統一した値を持つことが保証されます。
次のコード例はOCIセッション・プールを指定したOCI_ATTR_EDITION属性の使用方法を示しています。
OCIセッション・プーリングを指定したOCI_ATTR_EDITION属性の使用
/* allocate the auth handle to be set on the spool handle */
checkerr(errhp, OCIHandleAlloc(envhp,(void**)&authp_sp,
OCI_HTYPE_AUTHINFO, 0,0));
/* Set the edition on the auth handle */
checkerr(errhp,OCIAttrSet(authp_sp, OCI_HTYPE_AUTHINFO,
"Patch_Bug_12345", strlen("Patch_Bug_12345"),
OCI_ATTR_EDITION,errhp));
/* Allocate the pool handle */
checkerr(errhp,OCIHandleAlloc(envhp,(void**)&poolhp,
OCI_HTYPE_SPOOL,0,0));
/* Set the auth handle created above on the spool handle */
checkerr(errhp,OCIAttrSet(poolhp, OCI_HTYPE_SPOOL,authp_sp,
0,OCI_ATTR_SPOOL_AUTH,errhp));
checkerr(errhp,OCISessionPoolCreate(envhp,
errhp,poolhp,&poolname,&pnamelen,
(oratext*)conn_str,
len,min,max,incr,0,0,0,0,OCI_DEFAULT));
/* Allocate the auth handle for session get */
checkerr(errhp, OCIHandleAlloc(envhp,
(void**)&authp_sessget, OCI_HTYPE_AUTHINFO, 0,0));
checkerr(errhp,OCIAttrSet(authp_sessget, OCI_HTYPE_AUTHINFO,
username, strlen((char*)username), OCI_ATTR_USERNAME,errhp);
checkerr(errhp,OCIAttrSet(authp_sessget, OCI_HTYPE_AUTHINFO,
password, strlen((char*)password), OCI_ATTR_PASSWORD,
errhp));
checkerr(errhp,OCISessionGet(envhp,errhp,
&svchp,authp_sessget,poolname, pnamelen,0,0,0,0,0,
OCI_SESSGET_SPOOL));
OCIセッション・プールを指定した、すべてのセッション作成後属性を使用できます。ただし、セッション・プールは、セッションをエージ・アウトし、プール内で既存のセッションを再利用し、新しいセッションを透過的に再作成することが可能であるため、アプリケーションでは、プールからのセッションの取得後に必要とするセッション作成後属性を明示的に設定することをお薦めします。これにより、OCIセッション・プールによって戻された特定のセッションにかかわらず、アプリケーション・ロジックが機能することが保証されます。
OCIセッション・プーリングおよびデータベース常駐接続プーリング(DRCP)で使用するセッション・プールを初期化します。
用途
データベースに対して、sessMinの数のセッションおよび接続を開始します。この関数をコールする前に、OCIHandleAlloc()をコールしてセッション・プール・ハンドルのメモリーを割り当ててください。
構文
sword OCISessionPoolCreate ( OCIEnv *envhp,
OCIError *errhp,
OCISPool *spoolhp,
OraText **poolName,
ub4 *poolNameLen,
const OraText *connStr,
ub4 connStrLen,
ub4 sessMin,
ub4 sessMax,
ub4 sessIncr,
OraText *userid,
ub4 useridLen,
OraText *password,
ub4 passwordLen,
ub4 mode );
パラメータ
セッション・プールで作成する環境ハンドルへのポインタです。
OCIErrorGet()に渡すことができるエラー・ハンドルです。
初期化するセッション・プール・ハンドルへのポインタです。
戻されるセッション・プールの名前です。これは、環境内にあるすべてのセッション・プール間で一意の名前です。この値をOCISessionGet()コールに渡す必要があります。
バイトで示したpoolNameの長さです。
接続先のデータベースのTNS別名です。
バイトで示したconnStrの長さです。
セッション・プールの最小セッション数を指定します。
この数のセッションがOCISessionPoolCreate()で開始されます。セッションの開始後は、必要なときのみセッションをオープンします。
この値は、modeがOCI_SPC_HOMOGENEOUSに設定されている場合に使用されます。それ以外の場合、この値は無視されます。
セッション・プールでオープンできる最大セッション数を指定します。最大数に達すると、追加のセッションはオープンしません。有効な値は1以上です。
現行のセッション数がsessMax未満の場合、アプリケーションでは、開始するセッションに次回の増分を設定できます。有効な値は0以上です。
sessMin + sessIncrがsessMaxを超えることはできません。
セッションを開始するために使用するユーザーIDを指定します。
関連項目:
「コメント」の項の認証に関する注意。
バイトで示したユーザーIDの長さです。
ユーザーIDに対応するパスワードです。
バイトで示したパスワードの長さです。
次のモードがサポートされています。
OCI_DEFAULT - 新しいセッション・プールを作成します。
OCI_SPC_REINITIALIZE - セッション・プールの作成後、プール属性を動的に変更する(sessMin、sessMaxおよびsessIncrパラメータを変更する)場合は、modeをOCI_SPC_REINITIALIZEに設定してOCISessionPoolCreate()をコールします。modeがOCI_SPC_REINITIALIZEに設定されている場合、connStr、useridおよびpasswordは無視されます。
OCI_SPC_STMTCACHE - セッション・プール用にOCIの文キャッシュが作成されます。OCIの文キャッシュを使用可能にしてプールが作成されていない場合は、サーバー側の文キャッシュが自動的に使用されます。通常、クライアント側の文キャッシュを使用した方がパフォーマンスが向上することに注意してください。
関連項目:
OCI_SPC_HOMOGENEOUS - プール内のすべてのセッションは、OCISessionPoolCreate()に渡されるユーザー名とパスワードを使用して認証されます。この場合、OCISessionGet()に渡される認証ハンドル(authInfopパラメータ)は無視されます。sessMinおよびSessIncrの値は、この場合のみ使用されます。このモードでは、プロキシ・セッションは作成できません。このモードはデータベース常駐接続プーリング(DRCP)で使用できます。
OCI_SPC_NO_RLB - デフォルトでは、クライアントとサーバーにサポート機能があれば、セッション・プール内で実行時接続ロード・バランシングが有効化されます。これをオフにするには、OCISessionPoolCreate()の新しいモードであるOCI_SPC_NO_RLBモードを使用します。このモードを使用できるのは、プール作成時のみです。作成済のプールに対してこのモードを渡すと、ORA-24411エラーがスローされます。
コメント
セッション・プールでは、データベースへの接続として、ダイレクト接続とプロキシ接続の2通りの接続があります。プロキシ接続を行う場合、ユーザーにはConnect through Proxy権限が必要です。
セッション・プールの作成時に、useridおよびpasswordを指定する場合と指定しない場合があります。これらの値がNULLの場合は、このプールでプロキシ接続を行うことができません。modeをOCI_SPC_HOMOGENEOUSに設定した場合は、プロキシ接続を行うことができません。
useridとpasswordのペアは、OCISessionGet()コールの認証ハンドルを使用して指定することもできます。modeをOCI_SESSGET_CREDPROXYに設定してこの関数をコールした場合、ユーザーには、OCISessionGet()コールで提供されたuseridによって認証されるセッションが、OCISessionPoolCreate()コールで提供されたプロキシ資格証明を通じて与えられます。この場合、OCISessionGet()コールのパスワードは無視されます。
modeをOCI_SESSGET_CREDPROXYに設定しないでOCISessionGet()をコールした場合、ユーザーは、OCISessionGet()コールで提供された資格証明によって認証されるダイレクト・セッションを取得します。このコールで資格証明が提供されなかった場合、ユーザーは、OCISessionPoolCreate()コールの資格証明によって認証されるセッションを取得します。
例
次のコード例は、実行時ロード・バランシングを無効化する方法を示しています。
実行時ロード・バランシングの無効化
OCISessionPoolCreate(envhp, errhp, spoolhp, (OraText **)&poolName,
(ub4 *)&poolNameLen,
database, (ub4) strlen ((const signed char *) database),
sessMin, sessMax, sessIncr, (OraText *) appusername,
(ub4) strlen ((const signed char *) appusername),
(OraText *) apppassword,
(ub4) strlen ((const signed char *) apppassword),
OCI_SPC_HOMOGENEOUS | OCI_SPC_NO_RLB);
用途
セッション・プールを破棄します。
構文
sword OCISessionPoolDestroy ( OCISPool *spoolhp,
OCIError *errhp,
ub4 mode );
破棄するセッション・プールのセッション・プール・ハンドルです。
OCIErrorGet()に渡すことができるエラー・ハンドルです。
現在、OCISessionPoolDestroy()がサポートするモードはOCI_DEFAULTおよびOCI_SPD_FORCEです。
modeをOCI_SPD_FORCEに設定してこの関数をコールし、アクティブなセッションがプール内に存在する場合、そのセッションはクローズし、プールは破棄されます。ただし、このモードを設定せず、ビジーなセッションがプール内に存在する場合は、エラーが戻されます。
用途
OCISessionGet()を使用して取得したセッションを解放します。このコールの動作は、対応するOCISessionGet()関数をコールしたときのmodeによって決まります。デフォルトでは、この関数は、セッションまたは接続をクローズします。接続プーリングの場合、この関数は、セッションをクローズして接続をプールに戻します。セッション・プーリングの場合、この関数は、セッションと接続のペアをプールに戻し、保留状態のトランザクションがコミットされます。
構文
sword OCISessionRelease ( OCISvcCtx *svchp,
OCIError *errhp,
OraText *tag,
ub4 tag_len,
ub4 mode );
パラメータ
対応するOCISessionGet()のコール時に移入されたサービス・コンテキストです。
デフォルトでは、このハンドルに関連付けられたセッションおよび接続はクローズされます。
接続プーリングの場合は、セッションがクローズされ、接続がプールに対して解放されます。
セッション・プーリングの場合は、このサービス・コンテキストに関連付けられたセッションと接続のペアがプールに対して解放されます。
OCIエラー・ハンドルです。
このパラメータは、セッション・プーリングでのみ使用します。
OCI_SESSRLS_RETAGモードが指定されていない場合、このパラメータは無視されます。その場合、セッションには、このタグを使用してラベルが付けられ、プールに戻されます。このパラメータがNULLの場合、セッションにタグは付けられません。
このパラメータは、セッション・プーリングでのみ使用します。
タグの長さです。OCI_SESSRLS_RETAGモードが設定されていない場合、このパラメータは無視されます。
次のモードがサポートされています。
OCI_DEFAULT
OCI_SESSRLS_DROPSESS
OCI_SESSRLS_RETAG
接続プーリングの場合、デフォルトでは、OCI_DEFAULTのみ使用できます。
OCI_SESSRLS_DROPSESSおよびOCI_SESSRLS_RETAGは、セッション・プーリングでのみ使用できます。
OCI_SESSRLS_DROPSESSに設定すると、セッションはセッション・プールから削除されます。
OCI_SESSRLS_RETAGに設定した場合のみ、セッションのタグが変更されます。このモード以外に設定すると、tagパラメータおよびtag_lenパラメータは無視されます。
コメント
tagパラメータを使用する際には、正しいタグを渡すように注意してください。デフォルト・セッションが要求され、ユーザーが(ALTER SESSIONコマンドを使用して)そのセッションの特定のプロパティを設定する場合、ユーザーは、正しいタグを使用してこのセッションにラベルを付ける必要があります。
ただし、ユーザーがタグ付けされたセッションを要求して取得し、そのセッションのプロパティを変更した場合、ユーザーは、別のタグ(ある場合)を渡す必要があります。
セッション・プール・レイヤーで正しく処理が実行されるために、アプリケーション開発者は、正しいタグをOCISessionGet()コールおよびOCISessionRelease()コールに渡すように注意してください。
用途
共有メモリー・サブシステムからプロセスを連結解除して共有メモリーを解放します。
構文
sword OCITerminate ( ub4 mode);
コメント
OCITerminate()は、プロセスごとに一度だけコールする必要があり、これはOCIEnvCreate()、OCIEnvNlsCreate()および非推奨OCIInitialize()コールと同等のものです。このコールは、共有メモリー・サブシステムからのプロセスのデタッチおよび停止を試みます。また、追加のプロセス・クリーンアップ操作も実行します。同じ共有メモリーに接続している2つ以上のプロセスが同時にOCITerminate()をコールした場合、最も速かったコールにより共有メモリー・サブシステムが完全に解放され、その後のコールは終了されます。
