| Oracle Call Interfaceプログラマーズ・ガイド 11g リリース1（11.1） E05677-02 |
|
 戻る |
 次へ |
この項では、OCI接続関数、認証関数および初期化関数について説明します。
表16-2 接続関数、認証関数および初期化関数
| 関数 | 用途 |
|---|---|
|
|
アプリケーション・コンテキストのネームスペース内のすべての属性値情報を消去します。 |
|
|
アプリケーション・コンテキストのネームスペース内の属性およびその関連値を設定します。 |
|
|
接続プールを初期化します。 |
|
|
接続プールを破棄します。 |
|
|
Oracleデータベースを停止します。 |
|
|
Oracleデータベース・インスタンスを起動します。 |
|
|
OCI環境を作成および初期化します。 |
|
|
環境ハンドルを初期化します。 |
|
|
OCI関数が実行される環境を作成および初期化します。この環境の作成時に、キャラクタ・セットIDおよび各国語キャラクタ・セットIDを設定できます。 |
|
|
OCIプロセス環境を初期化します。 |
|
|
単純なシングルセッション・ログイン。 |
|
|
この関数は、様々なモードでログイン・セッションを作成するために使用します。 |
|
|
サーバーに連結します。サーバー・コンテキスト・ハンドルを初期化します。 |
|
|
サーバーから連結解除します。サーバー・コンテキスト・ハンドルを未初期化します。 |
|
|
ユーザーを認証します。 |
|
|
ユーザー・セッションを終了します。 |
|
|
セッション・プールからセッションを取得します。 |
|
|
セッション・プールを初期化します。 |
|
|
セッション・プールを破棄します。 |
|
|
セッションを解放します。 |
|
|
共有メモリー・サブシステムから連結解除します。 |
用途
アプリケーション・コンテキストのネームスペース内のすべての属性値情報を消去します。
構文
sword OCIAppCtxClearAll ( void *sesshndl,
void *nsptr,
ub4 nsptrlen,
OCIError *errhp,
ub4 mode ;
パラメータ
セッション・ハンドルのポインタです。
ネームスペース文字列（現在はCLIENTCONTEXTのみ）へのポインタです。
ネームスペース文字列の長さです。
モード（デフォルトはOCI_DEFAULT）です。
OCIErrorGet()に渡すことができるエラー・ハンドルです。
戻り値
エラー番号を戻します。
コメント
これは、サーバーへの次回のコール時にサーバー側のコンテキスト情報をクリーン・アップします。このネームスペース情報は、情報がサーバーに送信されるとセッション・ハンドルから消去され、必要に応じて再設定する必要があります。
関連関数
用途
アプリケーション・コンテキストのネームスペース内の属性およびその関連値を設定します。
構文
sword OCIAppCtxSet ( void *sesshndl,
void *nsptr,
ub4 nsptrlen,
void *attrptr,
ub4 attrptrlen,
void *valueptr,
ub4 valueptrlen,
OCIError *errhp,
ub4 mode );
パラメータ
セッション・ハンドルのポインタです。
ネームスペース文字列（現在はCLIENTCONTEXTのみ）へのポインタです。
ネームスペース文字列の長さです。
属性文字列へのポインタです。
attrptrが指し示す文字列の長さです。
値文字列へのポインタです。
valueptrが指し示す文字列の長さです。
モード（デフォルトはOCI_DEFAULT）です。
OCIErrorGet()に渡すことができるエラー・ハンドルです。
戻り値
エラー番号を戻します。
コメント
セッション・ハンドルに設定された情報は、サーバーへの次回のコール時にサーバーに送信されます。
この情報は、情報がサーバーに送信されるとセッション・ハンドルから消去され、必要に応じて再設定する必要があります。
関連関数
用途
接続プールを初期化します。
構文
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の長さです。
次のモードがサポートされています。
通常、OCIConnectionPoolCreate()は、modeをOCI_DEFAULTに設定してコールします。
プール属性を動的に変更する（たとえば、connMin、connMaxおよびconnIncrの各パラメータを変更する）場合は、modeをOCI_CPOOL_REINITIALIZEに設定して、OCIConnectionPoolCreate()をコールします。このコールの実行時、他のパラメータは無視されます。
コメント
OUTパラメータpoolNameとpoolNameLenには、データベース名とその長さの引数のかわりに、後続のOCIServerAttach()とOCILogon2()コールで使用する値が格納されます。
関連関数
OCIConnectionPoolDestroy()、OCILogon2()、OCIServerAttach()
用途
接続プールを破棄します。
構文
sword OCIConnectionPoolDestroy ( OCICPool *poolhp,
OCIError *errhp,
ub4 mode );
パラメータ
作成したプールのプール・ハンドルです。
OCIErrorGet()に渡すことができるエラー・ハンドルです。
現在、この関数ではOCI_DEFAULTモードのみがサポートされています。
関連関数
用途
Oracleデータベース・インスタンスを停止します。
構文
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データベース・インスタンスを起動します。
構文
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を使用して動作中のインスタンス（存在する場合）を停止します。この問題は、通常とは異なる状況下でのみ使用します。
コメント
OCI_PRELIM_AUTHモードでSYSOPERまたはSYSDBAとしてデータベースに接続している必要があります。ディスパッチャを介して共有サーバーには接続できません（つまり、OCI_DBSTARTUPFLAG_FORCEを使用して動作中のインスタンスを再起動する場合）。クライアント側のパラメータ・ファイル（pfile）を使用するには、管理ハンドルでOCI_ATTR_ADMIN_PFILEを設定する必要があります。このように設定しない場合、サーバー側のパラメータ・ファイル（spfile）が使用されます。OCIDBStartup()をコールすると、サーバー上の1つのインスタンスが起動します。
関連関数
OCIAttrSet()、OCIDBShutdown()、OCIServerAttach()、OCISessionBegin()
用途
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_NO_MUTEX− このモードではmutex化されません。環境ハンドル、または環境ハンドルから導出されたハンドルで行われたすべてのOCIコールは、シリアライズする必要があります。
OCI_NEW_LENGTH_SEMANTICS− キャラクタ・セットに関係なく、すべてのハンドルに対して一貫してバイト長セマンティクスを使用します。
OCI_NCHAR_LITERAL_REPLACE_OFF− N置換をオフにします。このモードまたはOCI_NCHAR_LITERAL_REPLACE_ONを使用しない場合、置換は環境変数ORA_NCHAR_LITERAL_REPLACEによって決定されます。この環境変数は、TRUEまたはFALSEに設定できます。この環境変数をTRUEに設定すると、置換はオンになります。FALSEに設定すると、オフになります（OCIではデフォルトでこのように設定されています）。
メモリー・コールバック・ルーチンのユーザー定義コンテキストを指定します。
ユーザー定義のメモリー割当て関数を指定します。モードがOCI_THREADEDの場合、このメモリー割当てルーチンは、スレッド・セーフにしてください。
ユーザー定義のメモリー割当て関数の、コンテキスト・ポインタを指定します。
ユーザー定義のメモリー割当て関数によって割り当てられるメモリーのサイズを指定します。
ユーザー定義のメモリー再割当て関数を指定します。モードがOCI_THREADEDの場合、このメモリー割当てルーチンは、スレッド・セーフにしてください。
ユーザー定義のメモリー再割当て関数の、コンテキスト・ポインタを指定します。
メモリー・ブロックのポインタです。
新しく割り当てられるメモリーのサイズを指定します。
ユーザー定義のメモリー解放関数を指定します。モードがOCI_THREADEDの場合、このメモリー解放ルーチンは、スレッド・セーフにしてください。
ユーザー定義のメモリー解放関数の、コンテキスト・ポインタを指定します。
解放されるメモリーのポインタです。
環境の継続時間中に割り当てられるユーザー・メモリーの量を指定します。
コールによりユーザーに割り当てられた、サイズxtramemszのユーザー・メモリーのポインタを戻します。
コメント
このコールにより、ユーザーによって指定されたモードを使用して、すべてのOCIコールの環境が作成されます。
|
注意: このコールは、他のOCIコールより先に実行する必要があります。また、 OCIInitialize()およびOCIEnvInit()コールのかわりに使用してください。OCIInitialize()およびOCIEnvInit()コールは、下位互換性を保つためにサポートされます。 |
このコールでは、残りのOCI関数で使用される環境ハンドルが戻されます。OCIには、それぞれ独自の環境モードを持つ複数の環境が存在する可能性があります。この関数では、どのモードで初期化を要求されても、プロセス・レベルの初期化を実行します。たとえば、環境をOCI_THREADEDで初期化した場合は、OCIで使用されるすべてのライブラリもそのスレッド・モードで初期化されます。
N置換をオンにすると、OCIStmtPrepare()または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()およびOCIEnvInit()コールは使用しないでください。
例
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;
}
...
関連関数
OCIHandleAlloc()、OCIHandleFree()、OCIEnvInit()、OCIEnvNlsCreate()、OCITerminate()
用途
OCI環境ハンドルを割り当て、初期化します。
構文
sword OCIEnvInit ( OCIEnv **envhpp,
ub4 mode,
size_t xtramemsz,
void **usrmempp );
パラメータ
環境へのハンドルのポインタです。
環境モードの初期化を指定します。次のモードが有効です。
OCI_DEFAULT
OCI_ENV_NO_MUTEX
OCI_ENV_NO_UCB
OCI_DEFAULTモードの場合、OCIライブラリでハンドルが常にmutex化されます。OCI_NO_MUTEXモードの場合、この環境ではmutex化されません。
OCI_NO_MUTEXモードでは、環境ハンドルまたは環境ハンドルから導出されたハンドルで行われたすべてのOCIコールは、シリアライズする必要があります。シリアライズするには、独自のmutex化を行うか、または環境ハンドル上で操作中のスレッドを1つのみにします。
OCI_ENV_NO_UCBモードは、環境の初期化時に動的コールバック・ルーチンOCIEnvCallbackのコールを抑止するために使用します。デフォルトでは、このコールは抑止されません。
環境の継続時間中に割り当てられるユーザー・メモリーの量を指定します。
環境の継続時間中コールによってユーザー用に割り当てられた、xtramemszサイズのユーザー・メモリーのポインタを戻します。
コメント
|
注意: OCIEnvCreate()は、 OCIInitialize()コールおよびOCIEnvInit()コールのかわりに使用する必要があります。OCIInitialize()およびOCIEnvInit()コールは、下位互換性を保つためにサポートされます。 |
このコールは、OCI環境ハンドルの割当ておよび初期化を行います。すでに初期化済のハンドルには何も行いません。OCI_ERRORまたはOCI_SUCCESS_WITH_INFOが戻った場合は、この環境ハンドルを使用してOracle固有のエラーおよび診断を取得できます。
これはローカルに処理され、サーバー・ラウンドトリップはありません。
環境ハンドルは、OCIHandleFree()を使用して解放できます。
関連関数
OCIHandleAlloc()、OCIHandleFree()、OCIEnvCreate()、OCITerminate()
用途
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_NO_MUTEX− このモードではmutex化されません。環境ハンドル、または環境ハンドルから導出されたハンドルで行われたすべてのOCIコールは、シリアライズする必要があります。
OCI_NCHAR_LITERAL_REPLACE_OFF− N置換をオフにします。このモードまたはOCI_NCHAR_LITERAL_REPLACE_ONを使用しない場合、置換は環境変数ORA_NCHAR_LITERAL_REPLACEによって決定されます。この環境変数は、TRUEまたはFALSEに設定できます。この環境変数をTRUEに設定すると、置換はオンになります。FALSEに設定すると、オフになります（OCIではデフォルトでこのように設定されています）。
メモリー・コールバック・ルーチンのユーザー定義コンテキストを指定します。
ユーザー定義のメモリー割当て関数を指定します。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()を使用して環境ハンドルを作成すると、バインド・ハンドルおよび定義ハンドルの実際の長さと戻される長さは、常にバイト単位になります。これは、次のコールに適用されます。
環境の作成時に、この関数を使用して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置換をオンにすると、OCIStmtPrepare()または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()およびOCIEnvInit()コールは使用しないでください。
|
関連項目:
|
関連関数
OCIHandleAlloc()、OCIHandleFree()、OCITerminate()、OCINlsEnvironmentVariableGet()
用途
OCIプロセス環境を初期化します。
構文
sword OCIInitialize ( 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 ));
パラメータ
モードの初期化を指定します。次のモードが有効です。
OCI_DEFAULT− デフォルト・モード。
OCI_THREADED− スレッド環境。このモードでは、ユーザーに公開されていない内部データ構造がマルチ・スレッドによって同時にアクセスされないように保護します。
OCI_OBJECT− オブジェクト機能を使用します。
OCI_EVENTS− パブリッシュ / サブスクライブ通知を利用します。
メモリー・コールバック・ルーチン用のユーザー定義コンテキストです。
ユーザー定義のメモリー割当て関数です。modeがOCI_THREADEDの場合、このメモリー割当てルーチンは、スレッド・セーフにしてください。
ユーザー定義のメモリー割当て関数のためのコンテキスト・ポインタです。
ユーザー定義のメモリー割当て関数によって割り当てられるメモリーのサイズです。
ユーザー定義のメモリー再割当て関数です。modeがOCI_THREADEDの場合、このメモリー割当てルーチンは、スレッド・セーフにしてください。
ユーザー定義のメモリー再割当て関数のためのコンテキスト・ポインタです。
メモリー・ブロックのポインタです。
新しく割り当てられるメモリーのサイズです。
ユーザー定義のメモリー解放関数です。modeがOCI_THREADEDの場合、このメモリー解放ルーチンは、スレッド・セーフにしてください。
ユーザー定義のメモリー解放関数のためのコンテキスト・ポインタです。
解放されるメモリーのポインタです。
コメント
|
注意: OCIEnvCreate()は、 OCIInitialize()コールおよびOCIEnvInit()コールのかわりに使用する必要があります。OCIInitialize()およびOCIEnvInit()コールは、下位互換性を保つためにサポートされます。 |
このコールは、OCIプロセス環境を初期化します。OCIInitialize()は、他のOCIをコールする前にコールする必要があります。
この関数を使用すると、アプリケーションでコールバックを使用して固有のメモリー管理関数を定義できます。アプリケーションでこのようなメモリー管理関数（つまりメモリー割当て、メモリー再割当ておよびメモリー解放）がすでに定義されている場合は、この関数のコールバック・パラメータを使用して登録する必要があります。
これらのメモリー・コールバックはオプションです。アプリケーションで、この関数のメモリー・コールバックにNULL値を渡すと、デフォルトのプロセス・メモリー割当てメカニズムが使用されます。
|
関連項目:
|
例
次の文は、ユーザー定義メモリー関数がない場合に、スレッド・モードおよびオブジェクト・モードでOCIInitialize()をコールする方法の例です。
OCIInitialize((ub4) OCI_THREADED | OCI_OBJECT, (void *)0,
(void * (*)()) 0, (void * (*)()) 0, (void (*)()) 0 );
関連関数
OCIHandleAlloc()、OCIHandleFree()、OCIEnvCreate()、OCIEnvInit()、OCITerminate()
用途
この関数は、OCILogon2()またはOCILogon()を使用して取得したセッションを解放するために使用します。
構文
sword OCILogoff ( OCISvcCtx *svchp
OCIError *errhp );
パラメータ
OCILogon()またはOCILogon2()のコールに使用されたサービス・コンテキスト・ハンドルです。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
コメント
この関数は、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パラメータで指定されたエンコーディングであることが必要です。
user nameの長さは、エンコーディングの有無に関係なく、バイト単位です。
ユーザーのパスワードです。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。
passwordの長さは、エンコーディングの有無に関係なく、バイト単位です。
接続先のデータベース名です。OCIEnvNlsCreate()の直前のコールのcharsetパラメータで指定されたエンコーディングであることが必要です。
dbnameの長さは、エンコーディングの有無に関係なく、バイト単位です。
コメント
この関数は、アプリケーションのためのログイン・セッションを作成するときに使用します。
このコールは、渡されたサービス・コンテキスト・ハンドルの割当てを行います。このコールは、セッションに対応付けられたサーバーとユーザー・セッション・ハンドルの暗黙的な割当ても実行します。これらのハンドルは、サービス・コンテキスト・ハンドルに対して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データベース・サーバーへの接続で使用する接続文字列を示します。
接続プーリングの場合は、仮想接続を取得してセッションを開始するための接続プールを示します。この値は、OCIConnectionPoolCreate()コールによって戻されます。
セッション・プーリングの場合は、セッションを取得するプールを示します。この値は、OCISessionPoolCreate()コールによって戻されます。
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()コールで提供されたプロキシ資格証明を通じて与えられます。
コメント
なし
関連関数
OCILogon()、OCILogoff()、OCISessionGet()、OCISessionRelease()
用途
OCIオペレーションの対象となるデータ・ソースへのアクセス・パスを作成します。
構文
sword OCIServerAttach ( OCIServer *srvhp,
OCIError *errhp,
const OraText *dblink,
sb4 dblink_len,
ub4 mode );
パラメータ
このコールにより初期化される未初期化サーバー・ハンドルです。初期化済のサーバー・ハンドルを渡すとエラーが発生します。
エラー発生時の診断情報のためにOCIErrorGet()に渡すエラー・ハンドルです。
使用するデータベース・サーバーを指定します。このパラメータは、接続文字列またはサービス・ポイントを指定する文字列を指示します。接続文字列がNULLの場合、このコールは、デフォルト・ホストに接続します。文字列自体がUTF-16であるかないかは、アプリケーションの環境ハンドルのモードまたは設定によって決まります。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シャドウ・プロセスが開始されます。Oracleシャドウ・プロセスをクリーン・アップするには、OCISessionEnd()およびOCIServerDetach()をコールする必要があります。コールしないと、シャドウ・プロセスが蓄積され、LinuxまたはUNIXシステムのプロセス数が足りなくなります。データベースが再起動したときにプロセス数が不足している場合は、データベースが起動しないことがあります。
例
次のコードは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のみです。
コメント
このコールは、OCIServerAttach()のコールによって確立されたOCIオペレーションの対象となるデータ・ソースへのアクセスを削除します。
関連関数
用途
ユーザー・セッションを作成し、指定のサーバーに対してユーザー・セッションを開始します。
構文
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_DEFAULT− このモードでは、戻されるユーザー・セッション・コンテキストは、svchpに指定された、同じサーバー・コンテキストとともにのみ設定できます。エンコーディングについては、サーバー・ハンドルでは、環境ハンドルの設定が使用されます。
OCI_MIGRATE− このモードでは、新しいユーザー・セッション・コンテキストは、別のサーバー・ハンドルとともにサービス・ハンドルに設定されます。このモードは、ユーザー・セッション・コンテキストを確立します。移行可能なセッションを作成するには、サービス・ハンドルを移行不可能なセッションであらかじめ設定しておく必要があります。この移行不可能なセッションは移行可能なセッションの作成者セッションになります。つまり、移行可能なセッションの親は、移行不可能なセッションにしてください。
セッションが下位の接続プールを使用する場合、OCI_MIGRATEは使用しないでください。セッションの移行と多重化はユーザーに意識させることなく行われます。
OCI_PRELIM_AUTH− このモードは、特定の管理タスクを認証するためにOCI_SYSDBAまたはOCI_SYSOPERとともにのみ使用できます。
OCI_STMT_CACHE− 指定のサービス・ハンドルにおいてデフォルト・サイズの文キャッシュが可能です。アプリケーションが後からそのサービス・ハンドルでOCI_ATTR_STMTCACHESIZEを使用してサイズを明示的に設定する場合、このモードを渡すのはオプションです。
コメント
OCISessionBegin()コールは、サービス・コンテキスト・ハンドルに設定されたサーバー・セットに対して、ユーザーを認証するときに使用します。
|
注意: セッションを開始するときは戻されたエラーをすべてチェックしてください。たとえば、アカウントのパスワードの期限が切れた場合は、ORA-28001エラーが戻されます。 |
リリース8.1以上では、サーバー・ハンドルに要求を行う前に、そのサーバー・ハンドルに対してOCISessionBegin()をコールする必要があります。OCISessionBegin()は、サーバー・ハンドルによってサービス・コンテキスト内に指定されたユーザーによるOracleサーバーへの接続に対する認証のみをサポートします。つまり、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フラグを設定しないでください。オラクル社では、互換性上の理由によってのみ、このフラグを渡すことをお薦めします。接続プールを使用するときに、ユーザーには、セッションが実際の接続に対して透過的に多重化される独自の専用（仮想）接続を持っているように感じられるため、OCI_MIGRATEフラグは使用しないでください。
OCI_SYSDBA、OCI_SYSOPERおよびOCI_PRELIM_AUTHは、主ユーザー・セッション・コンテキストでのみ使用できます。
OCISessionBegin()のコール用に資格証明を与えるために、2通りの方法のうち1つがサポートされています。最初の方法は、OCISessionBegin()に渡されるユーザー・セッション・ハンドル内にデータベース認証用の有効なユーザー名とパスワードのペアを用意することです。この方法では、OCIAttrSet()を使用して、ユーザー・セッション・ハンドルに対してOCI_ATTR_USERNAME属性およびOCI_ATTR_PASSWORD属性を設定します。これにより、OCI_CRED_RDBMSを指定してOCISessionBegin()がコールされます。
|
注意: ユーザー名とパスワード属性は、 OCISessionEnd()を使用してユーザー・セッション・ハンドルを終了しても変更されず、以降のOCISessionBegin()のコールで再使用できます。再使用しない場合は、次回のOCISessionBegin()コールの前に新しい値を設定しなおす必要があります。 |
もう1つの資格証明の方法は、外部資格証明です。この方法では、OCISessionBegin()をコールする前に、ユーザー・セッション・ハンドルについて属性を設定する必要はありません。資格証明のタイプはOCI_CRED_EXTです。これは、Oracle7のconnect/構文と等価です。すでにOCI_ATTR_USERNAMEおよびOCI_ATTR_PASSWORDに値が設定してある場合、OCI_CRED_EXTを使用すると、これらの値は無視されます。
資格証明を設定するもう1つの方法では、OCI_MIGSESSION属性とともに、すでに認証されているユーザーのセッションIDを使用します。このIDは、OCIAttrGet()コールを使用して認証されたユーザーのセッション・ハンドルから抽出できます。
例
次のコードは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_SPC_HOMOGENEOUS以外の場合のみ使用されます。この場合、このハンドルで使用できる属性は次のとおりです。
OCI_ATTR_USERNAME
OCI_ATTR_PASSWORD
OCI_ATTR_INITIAL_CLIENT_ROLES
詳細は、「ユーザー・セッション・ハンドル属性」を参照してください。
デフォルトでは、Oracleデータベース・サーバーへの接続で使用する接続文字列を示します。
接続プーリングの場合は、仮想接続を取得してセッションを開始するための接続プールを示します。この値は、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_STMTCACHE− セッションでの文キャッシュを使用可能にします。
OCI_SESSGET_CREDEXT− 外部資格証明を使用して認証されたセッションを戻します。
接続プーリングの場合は、次のモードが有効です。
OCI_SESSGET_CPOOL− 接続プーリングを使用するには、このモードに設定する必要があります。
OCI_SESSGET_STMTCACHE− セッションでの文キャッシュを使用可能にします。
OCI_SESSGET_CREDPROXY− プロキシ・セッションを戻します。ユーザーには、OCISessionGet()コールで提供されたユーザー名によって認証されるセッションが、OCIConnectionPoolCreate()コールで提供されたプロキシ資格証明を通じて与えられます。
OCI_SESSGET_CREDEXT− 外部資格証明を使用して認証されたセッションを戻します。
セッション・プーリングの場合は、次のモードが有効です。
OCI_SESSGET_SPOOL− セッション・プーリングを使用する場合に設定する必要があります。
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が設定されていない場合は、異なるタグを持つセッションが戻されることはありません。
関連関数
OCISessionRelease()、OCISessionPoolCreate()、OCISessionPoolDestroy()
用途
セッション・プールを初期化します。データベースに対して、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()に渡される認証ハンドル（authInfoパラメータ）は無視されます。sessMinおよびSessIncrの値は、この場合のみ使用されます。このモードでは、プロキシ・セッションは作成できません。
OCI_SPC_NO_RLB: デフォルトでは、クライアントとサーバーにサポート機能があれば、セッション・プール内で実行時接続ロード・バランシングが有効化されます。ただし、実行時ロード・バランシングをオフにする場合は、OCISessionPoolCreate()のmodeパラメータに新しいモードである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, poolhp, (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);
関連関数
OCISessionRelease()、OCISessionGet()、OCISessionPoolDestroy()
用途
セッション・プールを破棄します。
構文
sword OCISessionPoolDestroy ( OCISPool *spoolhp,
OCIError *errhp,
ub4 mode );
破棄するセッション・プールのセッション・プール・ハンドルです。
OCIErrorGet()に渡すことができるエラー・ハンドルです。
現在、OCISessionPoolDestroy()がサポートするモードはOCI_DEFAULTおよびOCI_SPD_FORCEです。
modeをOCI_SPD_FORCEに設定してこの関数をコールし、アクティブなセッションがプール内に存在する場合、そのセッションはクローズし、プールは破棄されます。ただし、このモードを設定せず、ビジーなセッションがプール内に存在する場合は、エラーが戻されます。
関連関数
OCISessionPoolCreate()、OCISessionRelease()、OCISessionGet()
用途
この関数は、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パラメータは無視されます。
コメント
正しいタグを渡すように注意してください。デフォルト・セッションが要求され、ユーザーが（ALTER SESSIONコマンドを使用して）そのセッションの特定のプロパティを設定する場合、ユーザーは、正しいタグを使用してこのセッションにラベルを付ける必要があります。
これとは逆に、ユーザーがタグ付けされたセッションを要求して取得し、そのセッションのプロパティを変更した場合、ユーザーは、別のタグ（ある場合）を渡す必要があります。
セッション・プール・レイヤーで正しく処理が実行されるために、アプリケーション開発者は、正しいタグをOCISessionGet()コールおよびOCISessionRelease()コールに渡すように注意してください。
関連関数
OCISessionGet()、OCISessionPoolCreate()、OCISessionPoolDestroy()、OCILogon2()
用途
共有メモリー・サブシステムからプロセスを連結解除して共有メモリーを解放します。
構文
sword OCITerminate ( ub4 mode);
パラメータ
コール固有モードです。有効な値は次のとおりです。
OCI_DEFAULT− デフォルトのコールを実行します。
コメント
OCITerminate()は、各プロセス内で1回のみコールしてください。OCIInitialize()コールと対でコールします。このコールは共有メモリー・サブシステムからプロセスを連結解除してプロセスを終了します。また、プロセス・クリーン・アップ操作も行います。同一の共有メモリーに接続している2つ以上のプロセスが、OCITerminate()を同時にコールしている場合は、最も高速のプロセスによって、共有メモリー・サブシステムが完全に解放されて、速度の遅いプロセスは終了することになります。
関連関数
