プログラマーズ・ガイド

29.7 カートリッジ・サービス: 文字列のフォーマット・インタフェース

カートリッジ・サービスの文字列のフォーマット関数をリストし、説明します。

表29-6は、この項で説明している文字列のフォーマット関数を示しています。

表29-6 文字列のフォーマット関数

関数	用途
OCIFormatInit()	OCIFormatパッケージを初期化します。
OCIFormatString()	テキスト文字列を指定されたテキスト・バッファに書き込みます。
OCIFormatTerm()	OCIFormatパッケージを終了します。

29.7.1 OCIFormatInit()

OCIFormatパッケージを初期化します。

用途

OCIFormatパッケージを初期化します。

構文

sword OCIFormatInit( void      *hndl, 
                     OCIError  *err);

パラメータ

hndl (IN): OCI環境ハンドルまたはユーザー・セッション・ハンドルです。
err (IN/OUT): OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

このルーチンをコールしてから、他のOCIFormatルーチンをコールする必要があります。またこのルーチンは1度しかコールできません。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

関連トピック

OCIErrorGet()

29.7.2 OCIFormatString()

送られた引数リストを使用し、指定のフォーマット文字列に従って、指定されたテキスト・バッファにテキスト文字列を書き込みます。

用途

送られた引数リストを使用し、指定のフォーマット文字列に従って、指定されたテキスト・バッファにテキスト文字列を書き込みます。

構文

sword OCIFormatString( void          *hndl, 
                       OCIError      *err, 
                       OraText       *buffer, 
                       sbig_ora       bufferLength, 
                       sbig_ora      *returnLength, 
                       const OraText *formatString,... );

パラメータ

hndl (IN)

OCI環境ハンドルまたはユーザー・セッション・ハンドルです。

err (IN/OUT)

OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

buffer (OUT)

文字列を含むバッファです。

bufferLength (IN)

バイトで示したバッファの長さです。

returnLength (OUT)

バッファに書き込むバイト数です(終了のNULLを除く)。

formatString (IN)

リテラル・テキストとフォーマット指定の任意の組合せを指定できるフォーマット文字列です。フォーマット指定はパーセント文字(%)で区切られ、任意の数(ない場合もあります)のオプションのフォーマット修飾子が続き、必須の書式コードで終了します。フォーマット文字列が%で終わる場合、つまり、後続のフォーマット修飾子やフォーマット指定がない場合、アクションは実行されません。使用可能なフォーマット修飾子および書式コードについては、表29-7および表29-8で説明します。

... (IN)

OCIFormat型ラッパー形式の引数の可変数(variable)です。ここで、variableは使用される値を含む変数にする必要があります。OCIFormat型ラッパーへの引数として、定数の値または式は使用できません。使用可能なOCIFormat型ラッパーを次に示します。引数のリストは、OCIFormatEndで終了する必要があります。

OCIFormatUb1(ub1 variable);

OCIFormatUb2(ub2 variable);

OCIFormatUb4(ub4 variable);

OCIFormatUword(uword variable);

OCIFormatUbig_ora(ubig_ora variable);

OCIFormatSb1(sb1 variable);

OCIFormatSb2(sb2 variable);

OCIFormatSb4(sb4 variable);

OCIFormatSword(sword variable);

OCIFormatSbig_ora(sbig_ora variable);

OCIFormatEb1(eb1 variable);

OCIFormatEb2(eb2 variable);

OCIFormatEb4(eb4 variable);

OCIFormatEword(eword variable);

OCIFormatChar (text variable);

OCIFormatText(const text *variable);

OCIFormatDouble(double variable);

OCIFormatDvoid(const dvoid *variable);

OCIFormatEnd

このルーチンの最初のコールを実行する前に、OCIFormatInit()ルーチンのコールを実行してOCIFormatパッケージを使用できるように初期化する必要があります。このルーチンが必要なくなった場合は、OCIFormatTerm()ルーチンをコールしてOCIFormatパッケージを終了します。

フォーマット修飾子

フォーマット修飾子は、より詳細な出力が可能になるようにフォーマット指定を変更または拡張します。表29-7で説明するように、フォーマット修飾子は任意の順序で指定でき、すべてオプションです。

表29-7 フォーマット修飾子フラグ

フラグ	操作
`'-'`	フィールド内の出力を左揃えにします。
`'+'`	数値型の符号('+'または'–')を常に出力します。
`' '`	数値の符号が出力されない場合は、符号の位置が空白で出力されます。
`'0'`	数値出力に空白ではなく0 (ゼロ)を埋め込みます。

'+'および' 'の両方のフラグが同じフォーマット指定で使用されている場合、' 'フラグは無視されます。
'-'および'0'の両方のフラグが同じフォーマット指定で使用されている場合、'-'フラグは無視されます。

代替出力:

8進書式コードの場合は、先行0 (ゼロ)を追加します。
16進書式コードの場合は、先行'0x'を追加します。
浮動小数点書式コードの場合は、出力で常に基数文字が利用されます。

フィールド幅

<w>です。ここで、<w>は最小フィールド幅を指定する数値です。変換後の引数は、最低この幅で、必要に応じてさらに広い幅でフィールドに出力されます。変換後の引数の表示幅がフィールド幅より小さい場合、左側(左寄せの場合は右側)に埋込み文字が挿入され、フィールド幅を一定にします。通常、埋込み文字はスペースですが、ゼロ埋込みフラグが指定されている場合はゼロになります。<w>では特殊文字'*'が使用される場合があり、これはフィールド幅値に対して現在の引数が使用されていることを示します。実際のフィールドまたは精度は、後続の引数に従います。

精度

.<p> (ピリオドとそれに続く数値<p>)は、文字列から出力する表示位置の最大数、または10進数値の小数点の後の桁、あるいは整数型で出力する場合の最小桁数を指定します(相違を補うために先行0 (ゼロ)が追加されます)。特殊文字'*'は、<p>のかわりに使用され、現行の引数に精度値があることを示します。

引数索引

(<n>)です。ここで、<n>は最初の引数が1である引数リストへの整数の索引です。フォーマット情報として引数索引が指定されていない場合は、最初の引数が選択されます。次回もフォーマット情報として引数索引が指定されていない場合は、2番目の引数が選択され、以降同様に続きます。引数索引を持つまたは持たないフォーマット情報はともに任意の順序で指定でき、操作においてはお互いが独立しています。

たとえば、フォーマット文字列"%u %(4)u %u %(2)u %u"では、OCIFormatString()に指定された1番目、4番目、2番目、2番目および3番目の引数が選択されます。

書式コード

書式コードは文字列中の引数のフォーマット方法を指定します。

表29-8で説明するように、これらの書式コードは、大文字にすると、テキスト文字列を除くすべてのアルファベット文字が大文字で出力されます。テキスト文字列には、この変換は行われません。

表29-8 文字列中の引数のフォーマット方法を指定する書式コード

コード	操作
`'c'`	コンパイラ・キャラクタ・セット内のシングルバイト文字。
`'d'`	符号付き10進整数
`'e'`	形式`[-]<d><r>[<d>...]e+[<d>]<d><d>`の指数(科学的)表記法。ここで、`<r>`は現在の言語の基数文字、`<d>`は任意の1桁を示します。デフォルトの精度は、定数`OCIFormatDP`で指定されます。精度は、必要に応じてフォーマット修飾子として指定できます。精度として0 (ゼロ)を指定すると、基数文字が表示されません。また、指数は常に最低2桁で出力され、最大3桁まで指定できます(たとえば、1e+01、1e+10、1e+100など)。
`'f'`	形式`[-]<d>[<d>...]<r>[<d>...]`の固定小数点表記法。ここで、`<r>`は現在の言語に適切な基数文字、`<d>`は任意の1桁を示します。精度は、必要に応じてフォーマット修飾子として指定できます。精度として0 (ゼロ)を指定すると、基数文字が表示されません。デフォルトの精度は、定数`OCIFormatDP`で指定されます。
`'g'`	変数浮動小数点表記法。`'e'`または`'f'`を選択します。数値が指定された精度に適合する場合は`'f'`を選択します(指定されていない場合はデフォルトの精度)。指数フォーマットでより多くの桁を出力できる場合のみ`'e'`を選択します。数値に分数部分がない場合は基数文字は出力されません
`'i'`	`'d'`と同一
`'o'`	符号なし8進整数
`'p'`	オペレーティング・システム固有のポインタ印刷出力。
`'s'`	次の型ではデフォルトの書式コードを使用して引数を出力します。 `ociformatub<n>`、`ociformatuword`、`ociformatubig_ora`、`ociformateb<n>`および`ociformateword`。使用される書式コードは'u'です。 `ociformatsb<n>`、`ociformatsword`および`ociformatsbig_ora`。使用される書式コードは'd'です。 `ociformatchar` 使用される書式コードは'c'です。 `ociformattext` 後続の`NULL`が検出されるまでテキストを出力します。 `ociformatdouble` 使用される書式コードは'g'です。 `ociformatdvoid` 使用される書式コードは'p'です。 `' %' - print a '%'。`
`'u'`	符号なし10進整数
'x'	符号なし16進整数

例

OCIFormatString()を使用した、2つの方法での2つの国の日付のフォーマット

/* This example shows the power of arbitrary argument    */
/* selection in the context of internationalization.  A  */
/* date is formatted in two different ways for two different */
/* countries according to the format string, yet the      */
/* argument list submitted to OCIFormatString remains    */
/* invariant.                                            */

text      buffer[255];
ub1       day, month, year;
OCIError *err;
void     *hndl;
sbig_ora  returnLen;

/* Set the date. */

day   = 10;
month = 3;
year  = 97;

/* Work out the date in United States style: mm/dd/yy */
OCIFormatString(hndl, err,
                buffer, (sbig_ora)sizeof(buffer), &returnLen
                (const text *)"%(2)02u/%(1)02u/%(3)02u",
                OCIFormatUb1(day),
                OCIFormatUb1(month),
                OCIFormatUb1(year),
                OCIFormatEnd);    /* Buffer is "03/10/97". */

/* Work out the date in New Zealand style: dd/mm/yy */
OCIFormatString(hndl, err,
                buffer, (sbig_ora)sizeof(buffer), &returnLen
                (const text *)"%(1)02u/%(2)02u/%(3)02u",
                OCIFormatUb1(day),
                OCIFormatUb1(month),
                OCIFormatUb1(year),
                OCIFormatEnd);    /* Buffer is "10/03/97". */

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

関連トピック

29.7.3 OCIFormatTerm()

OCIFormatパッケージを終了します。

用途

OCIFormatパッケージを終了します。

構文

sword OCIFormatTerm( void     *hndl, 
                     OCIError *err);

パラメータ

hndl (IN): OCI環境ハンドルまたはユーザー・セッション・ハンドルです。
err (IN/OUT): OCIエラー・ハンドルです。エラーがある場合は、errに記録され、OCI_ERRORが戻されます。OCIErrorGet()のコールによって診断情報を取得できます。

この関数は、OCIFormatパッケージを使用しなくなってからコールする必要があります。また、コールは1度しか実行できません。

戻り値

OCI_SUCCESS、OCI_INVALID_HANDLEまたはOCI_ERROR。

関連トピック

OCIErrorGet()