OCIキャラクタ・セット変換関数

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

表22-7に、OCIキャラクタ・セット変換関数を示します。

表22-7 OCIキャラクタ・セット変換関数

関数	用途
OCICharSetConversionIsReplacementUsed()	最後に起動された`OCINlsCharSetConvert()`または`OCICharSetToUnicode()`で、変換不可の文字に対して置換文字が使用されたかどうかを示します。
OCICharSetToUnicode()	マルチバイト文字列をUnicodeに変換します。
OCINlsCharSetConvert()	文字列を別のキャラクタ・セットに変換します。
OCIUnicodeToCharSet()	Unicode文字列をマルチバイトに変換します。

OCICharSetConversionIsReplacementUsed()

用途

最後に起動されたOCICharSetToUnicode()またはOCICharSetConvert()で、変換不可の文字に対して置換文字が使用されたかどうかを示します。

構文

boolean OCICharSetConversionIsReplacementUsed ( void *hndl );

パラメータ

hndl (IN/OUT): OCI環境ハンドルまたはユーザー・セッション・ハンドルへのポインタです。

Oracleキャラクタ・セットとUnicode（16ビット、固定幅Unicodeエンコーディング）間の変換がサポートされています。UnicodeからOracleキャラクタ・セットへの文字のマッピングが存在しない場合、置換文字が使用されます。したがって、元の文字へのラウンドトリップ変換を実行できない文字も存在します。一部の文字ではデータが失われます。

戻り値

OCICharSetConvert()またはOCICharSetToUnicode()が最後に起動された際、置換文字が使用されていればTRUEが戻されます。それ以外の場合は、FALSEが戻されます。

OCICharSetToUnicode()

用途

srcが指し示すマルチバイト文字列をUnicodeに変換し、dstが指し示す配列に追加します。

構文

sword OCICharSetToUnicode ( void              *hndl,
                            ub2               *dst,
                            size_t            dstlen,
                            const OraText     *src,
                            size_t            srclen,
                            size_t            *rsize );

パラメータ

hndl (IN/OUT): OCI環境ハンドルまたはユーザー・セッション・ハンドルへのポインタです。
dst (OUT): 宛先バッファへのポインタです。
dstlen (IN): 文字で示した宛先バッファのサイズです。
src (IN): マルチバイト・ソース文字列へのポインタです。
srclen (IN): バイトで示したソース文字列のサイズです。
rsize (OUT): 変換された文字数。NULLポインタの場合、何も戻されません。

ソースの制限または宛先の制限に達すると、変換は終了します。Unicode文字列に変換された文字数が戻されます。dstlenが0の場合、関数は文字列をスキャンし、文字数を数え、文字数をrsizeに戻しますが、文字列を変換しません。

OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR

OCINlsCharSetConvert()

用途

srcが指し示すsrcidによって指定されたキャラクタ・セットの文字列を、dstidで指定されたキャラクタ・セットに変換し、dstが指し示す配列に追加します。ソースまたは宛先のデータ・サイズの制限に達すると、変換は終了します。宛先バッファに変換されたバイト数が戻されます。

構文

sword OCINlsCharSetConvert ( void          *envhp,
                             OCIError      *errhp,
                             ub2           dstid,
                             void          *dstp,
                             size_t        dstlen,
                             ub2           srcid,
                             const void    *srcp,
                             size_t        srclen,
                             size_t        *rsize );

パラメータ

errhp (IN/OUT): OCIエラー・ハンドルです。エラーがある場合は、errhpに記録され、NULLポインタが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。
dstid (IN): 宛先バッファのキャラクタ・セットIDです。
dstp (OUT): 宛先バッファへのポインタです。
dstlen (IN): バイトで示した宛先バッファの最大サイズです。
srcid (IN): ソース・バッファのキャラクタ・セットIDです。
srcp (IN): ソース・バッファへのポインタです。
srclen (IN): バイトで示したソース・バッファの長さです。
rsize (OUT): 変換された文字数。ポインタがNULLの場合、何も戻されません。

ソースまたは宛先のキャラクタ・セットIDをOCI_UTF16IDで指定できますが、元のデータおよび変換されたデータの長さは文字数ではなく、バイト数で示されます。NULLデータが出現しても、変換は停止しません。キャラクタ・セット名からキャラクタ・セットIDを取得するには、OCINlsCharSetNameToId()を使用してください。宛先バッファ内の導出されたデータに置換文字が含まれているかどうかを調べるには、OCICharSetConversionIsReplacementUsed()を使用してください。バッファは、キャラクタ・セットに対して適切なバイト境界と位置が揃っている必要があります。たとえば、UTF-16の文字列を保持するには、ub2データ型を使用します。

戻り値

OCI_SUCCESSおよび変換されたバイト数、またはOCI_ERROR。

OCIUnicodeToCharSet()

用途

Unicode文字列をマルチバイト文字列に変換し、配列に追加します。

構文

sword OCIUnicodeToCharSet ( void        *hndl,
                            OraText     *dst,
                            size_t      dstlen,
                            const ub2   *src,
                            size_t      srclen,
                            size_t      *rsize );

パラメータ

hndl (IN/OUT): OCI環境ハンドルまたはユーザー・セッション・ハンドルへのポインタです。
dst (OUT): 宛先バッファへのポインタです。
dstlen (IN): バイトで示した宛先バッファの長さです。
src (IN): Unicode文字列へのポインタです。
srclen (IN): 文字で示したソース文字列のサイズです。
rsize (OUT): 変換されたバイト数です。NULLポインタの場合、何も戻されません。

ソースの制限または宛先の制限に達すると、変換は終了します。マルチバイト文字列に変換されたバイト数が戻されます。dstlenが0（ゼロ）の場合、変換を実行せずに、バイト数がrsizeに戻されます。

OCI環境ハンドルまたはユーザー・セッション・ハンドルで指定されたキャラクタ・セットにUnicode文字が変換できない場合、置換文字が使用されます。この場合、OCICharsetConversionIsReplacementUsed()がTRUEを戻します。

OCIEnvNlsCreate()関数のSQL CHARデータにOCI_UTF16IDが指定されている場合、エラーが発生します。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR