Connectionクラス

13.10 Connectionクラス

Connectionクラスは、特定のデータベースとの接続を示します。接続の内部で、SQL文が実行され、結果が戻ります。

表13-11 Connectionクラスで使用される列挙値

属性	オプション
FailOverEventType	`FO_BEGIN`は、接続の切断が検出され、フェイルオーバーが開始されることを示します。 `FO_END`は、フェイルオーバーが正常に終了し、`Connection`が使用できるようになったことを示します。 `FO_ABORT`は、フェイルオーバーが成功せず再試行されないことを示します。 `FO_REAUTH`は、ユーザー・セッションが再認証されたことを示します。 `FO_ERROR`は、フェイルオーバーが成功しなかったが、アプリケーションがエラーを処理してフェイルオーバーを再試行できることを示します。
FailOverType	`FO_NONE`は、フェイルオーバーに対する保護をユーザーが要求しなかったことを示します。 `FO_SESSION`は、セッションのフェイルオーバーのみをユーザーが要求したことを示します。 `FO_SELECT`は、選択のフェイルオーバーをユーザーが要求したことを示します。
ProxyType	`PROXY_DEFAULT`はデータベース・ユーザー名を示します。

表13-12 Connectionメソッドの概要

メソッド	概要
changePassword()	現行ユーザーのパスワードを変更します。
commit()	前回のコミットまたはロールバック以降の変更をコミットし、セッションが保持するデータベース・ロックを解放します。
createStatement()	SQL文を実行する`Statement`オブジェクトを作成します。
flushCache()	接続に関連付けられているオブジェクト・キャッシュをフラッシュします。
getClientCharSet()	デフォルトのクライアント・キャラクタ・セットを戻します。
getClientCharSetUString()	`UString`のうちグローバリゼーション対応のクライアント・キャラクタ・セットを戻します。
getClientNCHARCharSet()	デフォルトのクライアント`NCHAR`キャラクタ・セットを戻します。
getClientNCHARCharSetUString()	`UString`のうちグローバリゼーション対応のクライアントの`NCHAR`キャラクタ・セットを戻します。
getClientVersion()	使用されたクライアントのバージョンを戻します。
getLTXID()	パッケージ`DBMS_APP_CONT`の様々なコールで使用される可能性のある論理トランザクションIDを戻します。
getMetaData()	接続からアクセス可能なオブジェクトのメタデータを戻します。
getOCIServer()	接続に関連付けられているOCIサーバー・コンテキストを戻します。
getOCIServiceContext()	接続に関連付けられているOCIサービス・コンテキストを戻します。
getOCISession()	接続に関連付けられているOCIセッション・コンテキストを戻します。
getServerVersion()	使用されたOracleサーバーのバージョンを`string`として戻します。
getServerVersionUString()	使用されたOracleサーバーのバージョンを`UString`として戻します。
getStmtCacheSize()	文キャッシュのサイズを取得します。
getTag()	接続に関連付けられているタグを戻します。
isCached()	指定の文がキャッシュされるかどうかを決定します。
pinVectorOfRefs()	`Ref`オブジェクトのベクター全体を1回のラウンドトリップでオブジェクト・キャッシュに確保します。確保されたオブジェクトは、`OUT`パラメータのベクターを介して使用できます。
postToSubscriptions()	通知をサブスクリプションにポストします。
readVectorOfBfiles()	サーバーへの1回のラウンドトリップで複数の`Bfile`を読み取ります。
readVectorOfBlobs()	サーバーへの1回のラウンドトリップで複数の`Blob`を読み取ります。
readVectorOfClobs()	サーバーへの1回のラウンドトリップで複数の`Clob`を読み取ります。
registerSubscriptions()	通知に関して複数の`Subscription`を登録します。
rollback()	前回のコミットまたはロールバック以降の変更をすべてロールバックし、セッションが保持するデータベース・ロックを解放します。
setStmtCacheSize()	文キャッシュを有効化または無効化します。
setTAFNotify()	`Connection`オブジェクトに対するフェイルオーバー・コールバック関数を登録します。
terminateStatement()	`Statement`オブジェクトをクローズし、そのオブジェクトに関連付けられているすべてのリソースを解放します。
unregisterSubscription()	`Subscription`の登録を解除し、通知をオフにします。
writeVectorOfBlobs()	サーバーへの1回のラウンドトリップで複数の`Blob`を書き込みます。
writeVectorOfClobs()	サーバーへの1回のラウンドトリップで複数の`Clob`を書き込みます。

13.10.1 changePassword()

データベースに現在接続しているユーザーのパスワードを変更します。

構文	説明
void changePassword( const string &user, const string &oldPassword, const string &newPassword)=0;	ユーザーのパスワードを変更します。
void changePassword( const UString &user, const UString &oldPassword, const UString &newPassword)=0;	ユーザーのパスワードを変更します(Unicodeサポート)。クライアントの`Environment`をOCCIUTIF16モードで初期化する必要があります。

パラメータ	説明
user	データベースに現在接続しているユーザーを指定します。
oldPassword	ユーザーの現行のパスワードを指定します。
newPassword	ユーザーの新規パスワードを指定します。

13.10.2 commit()

前回のコミットまたはロールバック以降の変更をすべてコミットし、セッションが現在保持しているデータベース・ロックを解放します。

構文

void commit()=0;

13.10.3 createStatement()

指定されたSQL文でStatementオブジェクトを作成します。

このメソッドのキャッシュ対応バージョンでは、一致するtagを持つ文がキャッシュ内で最初に検索され、その文が戻されます。このような文が見つからない場合は、sqlパラメータと一致する文がキャッシュ内で検索され、その文が戻されます。一致する文が見つからない場合は、NULLのtagを持つ新規の文が作成され、戻されます。sqlパラメータが空でtagの検索に失敗すると、このコールではERRORが生成されます。

このメソッドのキャッシュなしバージョンでは、常に新規の文が作成され、戻されます。

構文	説明
Statement* createStatement( const string &sql="")=0;	指定されたSQL文をキャッシュ内で検索して戻します。見つからない場合は、新規の文を作成します。
Statement* createStatement( const string &sql, const string &tag)=0;	一致するタグを持つ文をキャッシュ内で検索します。見つからない場合は、指定されたSQLの内容を持つ新規の文を作成します。
Statement* createStatement( const UString &sql)=0;	指定されたSQL文をキャッシュ内で検索して戻します。見つからない場合は、新規の文を作成します。グローバリゼーション対応の場合です。
Statement* createStatement( const Ustring &sql, const Ustring &tag)=0;	一致するタグを持つ文をキャッシュ内で検索して戻します。見つからない場合は、指定されたSQLの内容を持つ新規の文を作成します。グローバリゼーション対応の場合です。

パラメータ	説明
sql	Statementオブジェクトに関連付けるSQL文字列を指定します。
tag	キャッシュから取り出す必要のある文に関連付けられているタグを指定します。文キャッシュが無効化されている場合は無視されます。

13.10.4 flushCache()

接続に関連付けられているオブジェクト・キャッシュをフラッシュします。

構文

void flushCache()=0;

13.10.5 getClientCharSet()

セッションのキャラクタ・セットを戻します。

構文

string getClientCharSet() const=0;

13.10.6 getClientCharSetUString()

UStringのうちグローバリゼーション対応のクライアント・キャラクタ・セットを戻します。

構文

UString getClientCharSetUString() const=0;

13.10.7 getClientNCHARCharSet()

セッションのNCHARキャラクタ・セットを戻します。

構文

string getClientNCHARCharSet() const=0;

13.10.8 getClientNCHARCharSetUString()

UStringのうちグローバリゼーション対応のクライアントのNCHARキャラクタ・セットを戻します。

構文

UString getClientNCHARCharSetUString() const=0;

13.10.9 getClientVersion()

アプリケーションが実行時に使用するクライアント・ライブラリのバージョンを戻します。

このメソッドは、アプリケーションの実行時にOCCIクライアントのバージョンを確認し、アプリケーションで使用しているコード・パスが、複数の異なるクライアント・パッチ・セットを使用する別々のコード・パスかどうかを判断するために使用されます。

パラメータmajorVersionおよびminorVersionの値には、マクロOCCI_MAJOR_VERSIONおよびOCCI_MINOR_VERSIONがそれぞれ使用されます。これらのマクロは、OCCIクライアント・ライブラリのメジャー・バージョンとマイナー・バージョンを定義します。戻されたバージョンを比較します。

構文

void getClientVersion(
   int &majorVersion,
   int &minorVersion,
   int &updateNum,
   int &patchNumber,
   int &portUpdateNum)

パラメータ	説明
majorVersion	クライアント・ライブラリのメジャー・バージョンです。
minorVersion	クライアント・ライブラリのマイナー・バージョンです。
updateNum	更新番号です。
patchNumber	ライブラリに適用されているパッチ番号です。
portUpdateNumber	ライブラリに適用されているポート固有のポート更新番号です。

13.10.10 getLTXID()

パッケージDBMS_APP_CONTの様々なコールで使用される可能性のある論理トランザクションIDを戻します。

構文

Bytes getLTXID() const = 0

13.10.11 getMetaData()

データベース内のオブジェクトのメタデータを戻します。

構文	説明
MetaData getMetaData( const string &object, MetaData::ParamType prmtyp=MetaData::PTYPE_UNK) const=0;	データベース内のオブジェクトのメタデータを戻します。
MetaData getMetaData( const UString &object, MetaData::ParamType prmtyp=MetaData::PTYPE_UNK) const=0;	データベース内のグローバリゼーション対応オブジェクトのメタデータを戻します。
MetaData getMetaData( const RefAny &ref) const=0;	参照を介してデータベース内のオブジェクトのメタデータを戻します。

パラメータ	説明
object	Statementオブジェクトに関連付けるSQL文字列を指定します。
prmtyp	表13-27のMetaDataクラスの列挙された`ParamType`の定義に従って、記述するスキーマ・オブジェクトの型を指定します。
ref	記述する型の型記述子オブジェクト(TDO)への`REF`を指定します。

13.10.12 getOCIServer()

接続に関連付けられているOCIサーバー・コンテキストを戻します。

構文

OCIServer* getOCIServer() const=0;

13.10.13 getOCIServiceContext()

接続に関連付けられているOCIサービス・コンテキストを戻します。

構文

OCISvcCtx* getOCIServiceContext() const=0;

13.10.14 getOCISession()

接続に関連付けられているOCIセッション・コンテキストを戻します。

構文

OCISession* getOCISession() const=0;

13.10.15 getServerVersion()

現行のConnectionオブジェクトによって使用されているデータベース・サーバーのバージョンを、stringとして戻します。これは、アプリケーションが異なるいくつかのコード・パスを使用し、複数の様々なサーバー・バージョンに接続するときに使用できます。

構文

string getServerVersion() const;

13.10.16 getServerVersionUString()

現行のConnectionオブジェクトによって使用されているデータベース・サーバーのバージョンを、UStringとして戻します。これは、アプリケーションが異なるいくつかのコード・パスを使用し、複数の様々なサーバー・バージョンに接続するときに使用できます。

構文

UString getServerVersionUString() const;

13.10.17 getStmtCacheSize()

文キャッシュのサイズを取得します。

構文

unsigned int getStmtCacheSize() const=0;

13.10.18 getTag()

接続に関連付けられているタグを戻します。ステートレスな接続プールからの接続にのみ有効です。

構文

string getTag() const=0;

13.10.19 isCached()

指定の文がキャッシュされるかどうかを決定します。

構文	説明
bool isCached( const string &sql, const string &tag="")=0;	一致するタグを持つ文をキャッシュ内で検索します。タグを指定しなければ、一致するSQL文がキャッシュ内で検索されます。
bool isCached( const Ustring &sql, const Ustring &tag)=0;	一致するタグを持つ文をキャッシュ内で検索します。タグを指定しなければ、一致するSQL文がキャッシュ内で検索されます。グローバリゼーション対応の場合です。

パラメータ	説明
sql	Statementオブジェクトに関連付けるSQL文字列を指定します。
tag	キャッシュから取り出す必要のある文に関連付けられているタグを指定します。文キャッシュが無効化されている場合は無視されます。

13.10.20 pinVectorOfRefs()

Refオブジェクトのベクター全体を1回のラウンドトリップでオブジェクト・キャッシュに確保します。確保されたオブジェクトは、OUTパラメータのベクターを介して使用できます。

構文	説明
template <class T> void pinVectorOfRefs( const Connection conn, vector <Ref<T>> & vect, vector <T> &vectObj, LockOptions lockOpt=OCCI_LOCK_NONE);	オブジェクトを戻します。
template <class T> void pinVectorOfRefs( const Connection *conn, vector <Ref<T>> & vect, LockOptions lockOpt=OCCI_LOCK_NONE);	オブジェクトを明示的に戻しません。アプリケーションでは、前に確保されたオブジェクトを戻す`ptr()`のコールにより特定の`Ref`オブジェクトを間接参照する必要があります。

パラメータ	説明
conn	接続を指定します。
vect	確保される`Ref`オブジェクトのベクターを指定します。
vectObj	確保操作の完了後にオブジェクトを含むベクターを指定します。これは`OUT`パラメータです。
lockOpt	表13-2の`LockOptions`の定義に従って、配列の確保時に使用するロック・オプションを指定します。サポートされている値は`OCCI_LOCK_NONE`のみです。

13.10.21 postToSubscriptions()

通知をサブスクリプションにポストします。

Subscriptionオブジェクトには有効なサブスクリプション名が必要であり、名前空間はNS_ANONYMOUSに設定する必要があります。ペイロードはこのコールを起動する前に設定される必要があります。そうしないと、ペイロードはNULLであるとみなされて配信されません。

コール元は、ポストしているコールが完了するまでペイロードを保持する必要があります。このコールはベスト・エフォート方式で保証され、通知は登録されたクライアントに最大1回送信されます。このコールは主として軽量通知に使用され、複数のシステム・イベントを処理するのに役立ちます。より確実な保証が必要な場合には、アプリケーションはOracleストリーム・アドバンスト・キューイング機能を使用可能です。

構文

void postToSubscriptions(
   const vector<aq::Subscription>& sub)=0;

パラメータ	説明
sub	ポスティングを受信するサブスクリプションのベクターを指定します。

13.10.22 readVectorOfBfiles()

サーバーへの1回のラウンドトリップで複数のBfileを読み取ります。Bfileをすべて読取り用にオープンしておく必要があります。

構文

void readVectorOfBfiles(
   const Connection *conn,
   vector<Bfile> &vec,
   oraub8 *byteAmts, 
   oraub8 *offsets, 
   unsigned char *buffers[], 
   oraub8 *bufferLengths);

パラメータ	説明
conn	接続を指定します。
vec	`Bfile`オブジェクトのベクターを指定します。各`Bfile`を読取り用にオープンしておく必要があります。
byteAmts	各`Bfile`から読み取るバイト数の配列です。各`Bfile`から読み取られた実際のバイト数が、この配列に戻されます。
offsets	`Bfile`内の読取り開始位置であるオフセットの配列です。
buffers	データ読取り先バッファのポインタの配列です。
bufferLengths	各バッファのサイズ(単位: バイト)の配列です。

13.10.23 readVectorOfBlobs()

サーバーへの1回のラウンドトリップで複数のBLOBを読み取ります。

構文

void readVectorOfBlobs(
   const Connection *conn,
   vector<Blob> &vec,
   oraub8 *byteAmts, 
   oraub8 *offsets, 
   unsigned char *buffers[], 
   oraub8 *bufferLengths);

パラメータ	説明
conn	接続を指定します。
vec	`Blob`オブジェクトのベクターです。
byteAmts	各`Blob`から読み取るバイト数の配列です。`Blob`から読み取られた実際のバイト数が、この配列に戻されます。
offsets	`Blob`内の読取り開始位置であるオフセットの配列です。
buffers	データ読取り先バッファのポインタの配列です。
bufferLengths	各バッファのサイズ(単位: バイト)の配列です。

13.10.24 readVectorOfClobs()

サーバーへの1回のラウンドトリップで複数のClobを読み取ります。すべてのClobは、同じキャラクタ・セット・フォームにあり、かつ同じキャラクタ・セットIDに属する必要があります。

構文説明

構文	説明
void readVectorOfClobs( const Connection conn, vector<Clob> &vec, oraub8 byteAmts, araub8 charAmts, oraub8 offsets, unsigned char buffers[], oraub8 bufferLengths);	このメソッドの一般的なフォームです。
void readVectorOfClobs( const Connection conn, vector<Clob> &vec, oraub8 byteAmts, araub8 charAmts, oraub8 offsets, utext buffers[], oraub8 bufferLengths);	`utext`バッファとともに使用するときの、このメソッドのフォームです。この場合、データはUTF16キャラクタ・セット・エンコーディングです。

void readVectorOfClobs(
   const Connection *conn,
   vector<Clob> &vec,
   oraub8 *byteAmts, 
   araub8 *charAmts,
   oraub8 *offsets, 
   unsigned char *buffers[], 
   oraub8 *bufferLengths);

このメソッドの一般的なフォームです。

void readVectorOfClobs(
   const Connection *conn,
   vector<Clob> &vec,
   oraub8 *byteAmts, 
   araub8 *charAmts,
   oraub8 *offsets, 
   utext *buffers[], 
   oraub8 *bufferLengths);

utextバッファとともに使用するときの、このメソッドのフォームです。この場合、データはUTF16キャラクタ・セット・エンコーディングです。

パラメータ	説明
conn	接続を指定します。
vec	`Clob`オブジェクトのベクターです。
byteAmts	各`Clob`から読み取るバイト数の配列です。`Clob`索引に対して`charAmts`が`NULL`または`0`である場合にのみ、使用されます。各`Clob`からの読取りバイト数を戻します。
charAmts	各`Clob`から読み取られる文字数の配列です。各`Clob`について読み取られた文字数を戻します。
offsets	`Clob`内の読取り開始位置であるオフセット(文字数)の配列です。
buffers	データ読取り先バッファのポインタの配列です。
bufferLengths	各バッファのサイズ(単位: バイト)の配列です。

13.10.25 registerSubscriptions()

通知に関してSubscriptionを登録します。

新規のクライアント・プロセスと停止後に再起動する既存のプロセスは、必要なサブスクリプションすべてに登録する必要があります。サーバーの停止および再起動中もクライアントが稼働している場合、このクライアントは引き続きDISCONNECTED登録に関する通知を受け取りますが、CONNECTED登録に関する通知はサーバーが停止している間に失われるため、受け取りません。

構文

void registerSubscriptions(
   const vector<aq::Subscription>& sub)=0;

パラメータ	説明
sub	通知用に登録するサブスクリプションのベクターです。

13.10.26 rollback()

前回のコミットまたはロールバック以降の変更をすべて削除し、セッションが現在保持しているデータベース・ロックを解放します。

構文

void rollback()=0;

13.10.27 setStmtCacheSize()

文キャッシュを有効化または無効化します。0 (ゼロ)以外の値を指定すると、指定したサイズのキャッシュによる文キャッシュが有効化されます。値0 (ゼロ)を指定すると、キャッシュが無効化されます。

構文

void setStmtCacheSize(
   unsigned int cacheSize)=0;

パラメータ	説明
cacheSize	キャッシュ内の文の最大数です。

13.10.28 setTAFNotify()

フェイルオーバーを構成済で、検出する必要のあるConnectionオブジェクトに対して、フェイルオーバー・コールバック関数を登録します。

OCCIがデフォルトの処理を続行できる場合、フェイルオーバー・コールバックはOCCI_SUCCESSを戻すことでそのことを示す必要があります。フェイルオーバー・イベントfoEventの定義については、表13-11を参照してください。foEventがFO_ERRORである場合、コールバック関数は、フェイルオーバーを再試行する必要があることを示すときにはFO_RETRYを戻し、フェイルオーバーの試行を終了するときにはOCCI_SUCCESSを戻すことができます。

構文

void setTAFNotify(
   int (*notifyFn)(
      Environment *env,
      Connection *conn,
      void *ctx,
      FailOverType foType,
      FailOverEventType foEvent),
   void *ctxTAF)

パラメータ	説明
notifyFn	フェイルオーバー・イベント時に起動されるユーザー定義のコールバック関数です。
env	障害の発生した`Connection`が作成された`Environment`オブジェクトです。
conn	コールバック関数を登録する、障害発生先として想定される`Connection`です。
ctx	コールバックの登録時にユーザーが提供するコンテキストです。
foType	構成済の`FailOverType`です。値は`FO_SESSION`または`FO_SELECT`です。各値の定義は表13-11を参照してください。
foEvent	コールバックをトリガーするフェイルオーバー・イベント・タイプである`FailOverEventType`です。値は`FO_BEGIN`、`FO_END`、`FO_ABORT`または`FO_ERROR`です。各値の定義は表13-11を参照してください。
ctxTAF	起動時にコールバック関数に戻されるユーザー・コンテキストです。

13.10.29 terminateStatement()

Statementオブジェクトをクローズします。

構文	説明
void terminateStatement( Statement *stmt)=0;	`Statement`オブジェクトをクローズし、そのオブジェクトに関連付けられているすべてのリソースを解放します。
void terminateStatement( Statement *stmt, const string &tag)=0;	文にオプションのタグ`string`を付けてから文を解放し、キャッシュに戻します。
void terminateStatement( Statement* stmt, const UString &tag) = 0;	文にオプションのタグ`UString`を付けてから文を解放し、キャッシュに戻します。

パラメータ	説明
stmt	クローズする`Statement`です。
tag	文に関連付けるタグ`string`または`UString`です。

13.10.30 unregisterSubscription()

通知をオフにしてSubscriptionの登録を解除します。

構文

void unregisterSubscription(
   const aq::Subscription& sub)=0;

パラメータ	説明
sub	通知をオフにする`Subscription`です。

13.10.31 writeVectorOfBlobs()

サーバーへの1回のラウンドトリップで複数のBlobを書き込みます。

構文

void writeVectorOfBlobs(
   const Connection *conn,
   vector<Blob> &vec,
   oraub8 *byteAmts, 
   oraub8 *offsets, 
   unsigned char *buffers[], 
   oraub8 *bufferLengths);

パラメータ	説明
conn	接続を指定します。
vec	`Blob`オブジェクトのベクターです。
byteAmts	各`Blob`に書き込むバイト数の配列です。
offsets	`Blob`内での書込み開始位置であるオフセットの配列です。
buffers	データ書出し元バッファのポインタの配列です。
bufferLengths	各バッファのサイズ(単位: バイト)の配列です。

13.10.32 writeVectorOfClobs()

サーバーへの1回のラウンドトリップで複数のClobを書き込みます。すべてのClobは、同じキャラクタ・セット・フォームにあり、かつ同じキャラクタ・セットIDに属する必要があります。

構文説明

構文	説明
void writeVectorOfClobs( const Connection conn, vector<Clob> &vec, oraub8 byteAmts, araub8 charAmts, oraub8 offsets, unsigned char buffers[], oraub8 bufferLengths);	このメソッドの一般的なフォームです。
void writeVectorOfClobs( const Connection conn, vector<Clob> &vec, oraub8 byteAmts, araub8 charAmts, oraub8 offsets, utext buffers[], oraub8 bufferLengths);	`utext`バッファとともに使用するときの、このメソッドのフォームです。この場合、データはUTF16キャラクタ・セット・エンコーディングです。

void writeVectorOfClobs(
   const Connection *conn,
   vector<Clob> &vec,
   oraub8 *byteAmts, 
   araub8 *charAmts,
   oraub8 *offsets, 
   unsigned char *buffers[], 
   oraub8 *bufferLengths);

このメソッドの一般的なフォームです。

void writeVectorOfClobs(
   const Connection *conn,
   vector<Clob> &vec,
   oraub8 *byteAmts, 
   araub8 *charAmts,
   oraub8 *offsets, 
   utext *buffers[], 
   oraub8 *bufferLengths);

utextバッファとともに使用するときの、このメソッドのフォームです。この場合、データはUTF16キャラクタ・セット・エンコーディングです。

パラメータ	説明
conn	接続を指定します。
vec	`Clob`オブジェクトのベクターです。
byteAmts	各`Clob`に書き込まれるバイト数の配列です。`Clob`索引に対して`charAmts`が`NULL`または`0`である場合にのみ、使用されます。各`Clob`について書き込まれたバイト数を戻します。
charAmts	各`Clob`に書き込まれる文字数の配列です。各`Clob`について読み取られた文字数を戻します。
offsets	`Clob`内での書込み開始位置であるオフセット(文字数)の配列です。
buffers	データ書出し元バッファのポインタの配列です。
bufferLengths	各バッファのサイズ(単位: バイト)の配列です。