グローバル環境でのOCIプログラミング

10.1 OCI NLS関数の使用

多くのOCI NLS関数では、次のいずれかを受け入れます。

環境ハンドル
ユーザー・セッション・ハンドル

OCI環境ハンドルは、クライアントNLS環境に関連付けられており、クライアントNLS環境変数によって初期化されます。サーバーに対してALTER SESSION文が使用されても、この環境は変わりません。環境ハンドルに関連付けられている文字セットは、クライアント文字セットです。

OCIセッション・ハンドルは、サーバー・セッション環境に関連付けられています。ALTER SESSION文によってセッション環境が変更されると、このNLS設定も変更されます。セッション・ハンドルに関連付けられている文字セットは、データベース文字セットです。

OCIセッション・ハンドルは、そのセッションで最初のトランザクションが始まるまで、どのNLS設定とも関連付けられていません。SELECT文では、トランザクションは始まりません。

関連項目:

OCI NLS関数の詳細は、『Oracle Call Interfaceプログラマーズ・ガイド』を参照してください

10.2 OCIでの文字セットの指定

OCI環境の作成時にOCIEnvNlsCreate関数を使用して、クライアント側データベースと各国語文字セットを指定します。この関数を使用すると、NLS_LANGおよびNLS_NCHAR初期化パラメータの設定に関係なく、アプリケーションで文字セット情報を動的に設定できます。また、1つのアプリケーションで、同じサーバー環境内で異なるクライアント環境に使用する複数の環境ハンドラを初期化できます。

AL16UTF16を除くOracle文字セットIDを指定するには、OCIEnvNlsCreate関数を通じてメタデータ、SQL CHARデータおよびSQL NCHARデータのエンコーディングを指定します。UTF-16データを指定するには、OCIEnvNlsCreate関数でOCI_UTF16IDを使用します。

関連項目:

OCIEnvNlsCreate関数の詳細は、『Oracle Call Interfaceプログラマーズ・ガイド』を参照してください

10.3 OCIでのロケール情報の取得

Oracleロケールは、言語、地域および文字セット定義で構成されます。ロケールは、曜日と月の名前、および日付、時刻、数値、通貨の書式などの表記規則を決定します。国際化されたアプリケーションは、ユーザーのロケール設定と文化的な慣習に従って動作します。たとえば、ロケールをドイツに設定すると、月日の名前がドイツ語で表示されます。

OCINlsGetInfo()関数を使用すると、次のロケール情報を取得できます。

曜日(翻訳済)
曜日の略称(翻訳済)
月名(翻訳済)
月名の略称(翻訳済)
はい/いいえ(翻訳済)
AM/PM (翻訳済)
AD/BC (翻訳済)
数値書式
借方/貸方
日付書式
通貨書式
デフォルトの言語
デフォルトの地域
デフォルトの文字セット
デフォルトの言語ソート
デフォルトのカレンダ

表10-1に、ロケール情報を戻すOCI関数を示します。

表10-1 ロケール情報を戻すOCI関数

関数	説明
`OCINlsGetInfo()`	ロケール情報を戻します。前述の説明を参照してください。
`OCINlsCharSetNameTold()`	指定されたOracle文字セット名のOracle文字セットIDを戻します。
`OCINlsCharSetIdToName()`	指定された文字セットIDのOracle文字セット名を戻します。
`OCINlsNumericInfoGet()`	最大文字サイズなど、指定された数値情報を戻します。
`OCINlsEnvironmentVariableGet()`	`NLS_LANG`からの文字セットID、または`NLS_NCHAR`からの各国語文字セットIDを戻します。

関連項目:

『Oracle Call Interfaceプログラマーズ・ガイド』

10.4 Oracleと他の規格とのロケール情報のマッピング

OCINlsNameMap関数は、Oracle文字セット名、言語名および地域名と、Internet Assigned Numbers Authority (IANA)名および国際標準化機構(ISO)名の間のマッピングを行います。

10.5 OCIでの文字列操作

文字列の操作用に、2種類のデータ構造がサポートされています。

ネイティブ・キャラクタ文字列
ワイド・キャラクタ文字列

ネイティブ・キャラクタ文字列は、Oracleのネイティブ文字セットでエンコードされます。ネイティブ・キャラクタ文字列を処理する関数は、その文字列の長さをバイト単位で計算して1単位として扱います。ワイド・キャラクタ(wchar)文字列関数は、文字列操作の柔軟性を高めます。この種の関数は、文字列の長さを文字数で計算し、文字ベースと文字列ベースの操作をサポートします。

ワイド・キャラクタのデータ型はOracle固有です。ANSI/ISOのC規格で定義されているwchar_tデータ型と混同しないでください。Oracleのワイド・キャラクタのデータ型は、すべてのプラットフォームで常に4バイトですが、wchar_tのサイズは実装とプラットフォームに依存します。Oracleのワイド・キャラクタのデータ型によって、ネイティブ・キャラクタは簡単に処理できる固定幅になるように正規化されます。これにより、Oracleのワイド・キャラクタ形式とネイティブ・キャラクタ形式の間でラウンドトリップ変換時にデータ消失が発生しないことが保証されます。

次の文字列操作が含まれます。

ネイティブ・キャラクタ形式とワイド・キャラクタ形式間の文字列の変換
文字の分類
大/小文字の変換
表示長の計算
比較、連結、検索などの一般的な文字列操作

表10-2に、OCI文字列操作関数を示します。

ノート:

表10-2では、マルチバイト文字列に言及している関数と説明は、ネイティブ・キャラクタ文字列に適用されます。

表10-2 OCI文字列操作関数

関数	説明
`OCIMultiByteToWideChar()`	ヌル文字で終了する文字列全体を`wchar`書式に変換します。
`OCIMultiByteInSizeToWideChar()`	文字列の一部を`wchar`書式に変換します。
`OCIWideCharToMultiByte()`	ヌル文字で終了するワイド・キャラクタ文字列全体をマルチバイト文字列に変換します。
`OCIWideCharInSizeToMultiByte()`	ワイド・キャラクタ文字列の一部をマルチバイト書式に変換します。
`OCIWideCharToLower()`	`wc`で指定された`wchar`文字を、指定したロケールに存在する場合は対応する小文字に変換します。対応する小文字が存在しない場合は、`wc`自体を戻します。
`OCIWideCharToUpper()`	`wc`で指定された`wchar`文字を、指定したロケールに存在する場合は対応する大文字に変換します。対応する大文字が存在しない場合は、`wc`自体を戻します。
`OCIWideCharStrcmp()`	2つのワイド・キャラクタ文字列を、バイナリ、言語または大/小文字を区別しない比較方法で比較します。ノート: `UNICODE_BINARY`ソート・メソッドは、`OCIWideCharStrcmp()`とともに使用して、指定されたワイド・キャラクタ引数の言語比較を実行することはできません。
`OCIWideCharStrncmp()`	この関数は`OCIWideCharStrcmp()`に似ています。2つのワイド・キャラクタ文字列を、バイナリ、言語または大/小文字を区別しない比較方法で比較します。`str1`から最大`len1`バイト、`str2`から最大`len2`バイトが比較されます。ノート: `OCIWideCharStrcmp()`と同様に、`UNICODE_BINARY`ソート・メソッドは、`OCIWideCharStrcmp()`とともに使用して、指定されたワイド・キャラクタ引数の言語比較を実行することはできません。
`OCIWideCharStrcat()`	`wsrcstr`で示された文字列のコピーを追加します。その後、結果文字列の文字数を戻します。
`OCIWideCharStrncat()`	`wsrcstr`で示された文字列のコピーを追加します。その後、結果文字列の文字数を戻します。最大`n`文字が追加されます。
`OCIWideCharStrchr()`	`wstr`で示された文字列の中で、最初に出現する`wc`を検索します。検索が正常終了した場合は、`wchar`へのポインタを戻します。
`OCIWideCharStrrchr()`	`wstr`で示された文字列の中で、最後に出現する`wc`を検索します。
`OCIWideCharStrcpy()`	`wsrcstr`で示された`wchar`文字列を`wdststr`で示された配列にコピーします。その後、コピーされた文字数を戻します。
`OCIWideCharStrncpy()`	`wsrcstr`で示された`wchar`文字列を`wdststr`で示された配列にコピーします。その後、コピーされた文字数を戻します。最大`n`文字が配列からコピーされます。
`OCIWideCharStrlen()`	`wstr`で示された`wchar`文字列にある文字数を計算し、その数を戻します。
`OCIWideCharStrCaseConversion()`	`wsrcstr`で示されたワイド・キャラクタ文字列をフラグの指定により大文字または小文字に変換し、その結果を`wdststr`で示された配列にコピーします。
`OCIWideCharDisplayLength()`	`wc`を表示するために必要な列位置の数を決定します。
`OCIWideCharMultibyteLength()`	`wc`をマルチバイト・エンコーディングで表す場合に必要なバイト数を決定します。
`OCIMultiByteStrcmp()`	2つのマルチバイト・キャラクタ文字列を、バイナリ、言語または大/小文字を区別しない比較方法で比較します。
`OCIMultiByteStrncmp()`	2つのマルチバイト・キャラクタ文字列を、バイナリ、言語または大/小文字を区別しない比較方法で比較します。`str1`から最大`len1`バイト、`str2`から最大`len2`バイトが比較されます。
`OCIMultiByteStrcat()`	`srcstr`で示されたマルチバイト文字列のコピーを追加します。
`OCIMultiByteStrncat()`	`srcstr`で示されたマルチバイト文字列のコピーを追加します。`srcstr`から最大`n`バイトが`dststr`に追加されます。
`OCIMultiByteStrcpy()`	`srcstr`が指し示すマルチバイト文字列を、`dststr`が指し示す配列にコピーします。これは、コピーされたバイト数を戻します。
`OCIMultiByteStrncpy()`	`srcstr`が指し示すマルチバイト文字列を、`dststr`が指し示す配列にコピーします。これは、コピーされたバイト数を戻します。ただし、`srcstr`が指し示す配列から`dststr`が指し示す配列にコピーされるのは、最大`n`バイトです。
`OCIMultiByteStrlen()`	`str`で示されたマルチバイト文字列のバイト数を戻します。
`OCIMultiByteStrnDisplayLength()`	`n`バイトの範囲内のすべての文字が占有する表示位置の大きさを戻します
`OCIMultiByteStrCaseConversion()`	文字列の一部をある文字セットから別の文字セットに変換します。

関連項目:

『Oracle Call Interfaceプログラマーズ・ガイド』

10.6 OCIでの文字の分類

表10-3に、OCIの文字の分類関数を示します。

表10-3 OCIの文字の分類関数

関数	説明
`OCIWideCharIsAlnum()`	ワイド・キャラクタが、アルファベット文字であるか10進数字であるかをテストします。
`OCIWideCharIsAlpha()`	ワイド・キャラクタが、アルファベット文字であるかどうかをテストします。
`OCIWideCharIsCntrl()`	ワイド・キャラクタが、制御文字であるかどうかをテストします。
`OCIWideCharIsDigit()`	ワイド・キャラクタが、10進数字であるかどうかをテストします。
`OCIWideCharIsGraph()`	ワイド・キャラクタが、図形文字であるかどうかをテストします。
`OCIWideCharIsLower()`	ワイド・キャラクタが、小文字であるかどうかをテストします。
`OCIWideCharIsPrint()`	ワイド・キャラクタが、印字可能文字であるかどうかをテストします。
`OCIWideCharIsPunct()`	ワイド・キャラクタが、句読点文字であるかどうかをテストします。
`OCIWideCharIsSpace()`	ワイド・キャラクタが、スペース文字であるかどうかをテストします。
`OCIWideCharIsUpper()`	ワイド・キャラクタが、大文字であるかどうかをテストします。
`OCIWideCharIsXdigit()`	ワイド・キャラクタが、16進数字であるかどうかをテストします。
`OCIWideCharIsSingleByte()`	`wc`がマルチバイトに変換されるとき、シングルバイト文字であるかどうかをテストします。

関連項目:

『Oracle Call Interfaceプログラマーズ・ガイド』

10.7 OCIでの文字セットの変換

Oracle文字セットとUnicode (16ビット、固定幅のUnicodeエンコーディング)間の変換がサポートされています。UnicodeからOracle文字セットへの文字のマッピングが存在しない場合、置換文字が使用されます。したがって、変換して元の文字セットに戻す場合、データが失われる可能性があります。

表10-4に、OCIの文字セット変換関数を示します。

表10-4 OCI文字セット変換関数

関数	説明
`OCICharSetToUnicode()`	`src`で示されたマルチバイト文字列をUnicodeに変換し、`dst`で示された配列に格納します。
`OCIUnicodeToCharSet()`	`src`で示されたUnicode文字列をマルチバイトに変換し、`dst`で示された配列に格納します。
`OCINlsCharSetConvert()`	文字列をある文字セットから別の文字セットに変換します。
`OCICharSetConversionIsReplacementUsed()`	`OCINlsCharSetConvert()`または`OCIUnicodeToCharSet()`の最後の起動時に変換できなかった文字に、置換文字が使用されたかどうかを示します。

関連項目:

10.8 OCIメッセージ関数

ユーザー・メッセージAPIには、カートリッジ開発者のための簡易インタフェースが用意されています。これによって、Oracleメッセージと同様にユーザー自身のメッセージを取り出すことができます。

表10-5に、OCIメッセージ関数を示します。

表10-5 OCIメッセージ関数

関数	説明
`OCIMessageOpen()`	`hndl`で示された言語で、メッセージ・ハンドルをオープンします。
`OCIMessageGet()`	`msgno`で識別されるメッセージ番号の付いたメッセージを取り出します。バッファが0(ゼロ)でない場合、この関数は`msgbuf`で指定されたバッファにメッセージをコピーします。
`OCIMessageClose()`	`msgh`で示されたメッセージ・ハンドルをクローズし、そのハンドルに関連付けられているメモリーをすべて解放します。

関連項目:

『Oracle Call Interfaceプログラマーズ・ガイド』

10.9 lmsgenユーティリティ

用途

lmsgenユーティリティは、テキスト・ベースのメッセージ・ファイル(.msg)をバイナリ形式(.msb)に変換します。これにより、ユーザーが提供するOracleメッセージとOCIメッセージを、必要な言語でOCI関数に戻すことができます。

サーバーが使用するメッセージは、$ORACLE_HOME/product_name/mesgディレクトリにあるバイナリ形式ファイル、あるいはそれに相当するオペレーティング・システム用ファイルに格納されます。このファイルには、次のファイル名規則に従って、サポート対象言語ごとに1バージョンずつ、複数のバージョンが存在します。

<product_id><language_abbrev>.msb

たとえば、ORAは製品ID(<product_id>)でFはフランス語の略称(<language_abbrev>)であるため、フランス語のサーバー・メッセージが含まれたファイルはoraf.msbと呼ばれます。product_nameの値はrdbmsであるため、$ORACLE_HOME/rdbms/mesgディレクトリにあります。

構文

LMSGEN text_file product facility [language] [-i indir] [-o outdir]

text_fileは、メッセージ・テキスト・ファイルです。
productは、製品の名前です。
facilityは、機能の名前です。
languageは、NLS_LANGパラメータで指定された言語に対応する、オプションのメッセージ言語です。メッセージ・ファイルに言語のタグが正しく付いていない場合は、言語パラメータが必要です。
indirは、テキスト・ファイルの場所を指定するオプション・ディレクトリです。
indirは、出力ファイルの場所を指定するオプション・ディレクトリです。

出力(.msb)ファイルは、$ORACLE_HOME/product/mesg/ディレクトリの下に生成されます。

テキスト・メッセージ・ファイル

テキスト・メッセージ・ファイルは、次のガイドラインに従う必要があります。

/および//で始まる行は内部コメントとして扱われ、無視されます。
メッセージ・ファイルに特定の言語のタグを付けるには、次のような行を含めます。

    #   CHARACTER_SET_NAME= Japanese_Japan.JA16EUC

各メッセージには、3つのフィールドがあります。

     message_number, warning_level, message_text

メッセージ番号は、メッセージ・ファイル内で一意であることが必要です。
warning_levelは、現在使用されていません。0を使用してください。
message_textは、511バイトを超えることはできません。

次に、Oracleメッセージ・テキスト・ファイルの例を示します。

/ Copyright (c) 2006 by Oracle.  All rights reserved.
/ This is a test us7ascii message file
# CHARACTER_SET_NAME= american_america.us7ascii
/
00000, 00000, "Export terminated unsuccessfully\n"
00003, 00000, "no storage definition found for segment(%lu, %lu)"

例: テキスト・メッセージ・ファイルからのバイナリ・メッセージ・ファイルの作成

次の表に、lmsgenパラメータのサンプル値を示します。

パラメータ	値
`product`	`myapp`
`facility`	`imp`
`language`	`AMERICAN`
`text_file`	`impus.msg`

テキスト・メッセージ・ファイル内の1行は、次のとおりです。

00128,2, "Duplicate entry %s found in %s"

lmsgenユーティリティは、テキスト・メッセージ・ファイル(impus.msg)をバイナリ形式のファイルimpus.msbに変換します。$ORACLE_HOME/myapp/mesgディレクトリがすでに存在している必要があります。

% lmsgen impus.msg myapp imp AMERICAN

出力結果は、次のようになります。

Generating message file impus.msg -->
$ORACLE_HOME/myapp/mesg/impus.msb

NLS Binary Message File Generation Utility: Version 10.2.0.1.0 - Production

Copyright (c) Oracle 1979, 2006.  All rights reserved.

CORE 10.2.0.1.0       Production