表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()
をコールした場合、最も速かったコールにより共有メモリー・サブシステムが完全に解放され、その後のコールは終了されます。