VARCHAR_FORMATスカラー関数

文字から可変長文字

文字表現

組み込み CHAR または VARCHAR データ・タイプでなければならない値を戻す式。 指定した引数が GRAPHIC または VARGRAPHIC のデータ・タイプであると、まず VARCHAR に変換されてから、関数が評価されます。

結果の長さ属性と実際の長さは、以下のように決定されます。

• string-expression が空ストリング定数の場合、結果の長さ属性は 1 です。
• それ以外の場合、結果の長さ属性は、string-expression の長さ属性と同じになります。
• 結果の実際の長さは、結果の長さ属性と string-expression の実際の長さのうちの最小値です。

結果の値は、character-expression の値と同じになります。

character-expression がグラフィック・データを返す場合、結果の CCSID は、グラフィック引数に対応する文字混合 CCSID になります。 character-expression がビット・データを返す場合、結果はビット・データになります。 それ以外の場合、 結果の CCSID は character-expression の CCSID と同じです。

タイム・スタンプから可変長文字

タイムスタンプ式

DATE または TIMESTAMP の値、または CLOB でも DBCLOB でもない日付またはタイム・スタンプの有効な文字ストリング表現またはグラフィック・ストリング表現を戻す式。 引数が日付またはタイム・スタンプのグラフィック・ストリング表現の場合、最初に引数が文字ストリングに変換されてから、関数が評価されます。

timestamp-expression が DATE または日付の有効なストリング表記である場合、時刻が午前 0 時ちょうど (00.00.00) であると想定して、最初に TIMESTAMP(0) 値に変換されます。 HH12 フォーマット・エレメントが指定され、最初の引数の時刻コンポーネントが 24:00:00 の場合、入力タイム・スタンプ値は 00:00:00 に調整され、日付が 1 日増分されます。

日時値の文字列表現の有効な形式については、 「日時値の文字列表現」を参照してください。

書式文字列

長さ属性が 255 バイト以下の、LOB 以外の組み込みの文字ストリング・データ・タイプまたはグラフィック・ストリング・データ・タイプを返す式。 値が CHAR および VARCHAR のいずれのデータ・タイプでもない場合、その値が暗黙的に VARCHAR にキャストされてから、関数が評価されます。 もし式がタイムスタンプデータ型を返す場合、結果として得られる部分文字列はタイムスタンプの書式設定のルールに従う必要があります。 式がタイム・ゾーン付きのタイム・スタンプを返す場合、結果のサブストリングは、タイム・ゾーン付きのタイム・スタンプのフォーマット設定の規則に準拠している必要があります。

値は、timestamp-expression のフォーマット設定方法を示すテンプレートです。

有効な format-string には、以下にリストするフォーマット・エレメントの組み合わせを含めることができます。 2 つのフォーマット・エレメントは、次の 1 つ以上の区切り文字を使用して区切ることができます。

• 負符号 (-)
• ピリオド (.)
• スラッシュ (/)
• コンマ (,)
• アポストロフィ (')
• セミコロン (;)
• コロン (:)
• ブランク ( )

区切り文字は format-string の先頭または末尾に指定することもできます。 format-string には、空ストリング、一連のブランク、または一連の区切り文字も使用できます。

下の表は、format-string に含めることができる有効なフォーマット・エレメントをリストしています。

表 1. フォーマット文字列の有効なフォーマット要素

フォーマット・エレメント	説明 (デフォルトは先行ゼロを戻すものと想定)
AM または PM 1	ピリオドが付かない午前/午後の指定子。 このフォーマット・エレメントは、「AM」または「PM」と厳密に一致するストリングを使用します。
A.M. または P.M. 1	ピリオドが付いた午前/午後の指定子。 このフォーマット・エレメントは、正確なストリング「A.M.」を使用します。 または「P.M.」。
CC	世紀 (00 から 99)。 4 桁の数字からなる年の最後の 2 桁がゼロの場合、結果はその年の最初の 2 桁になります。 それ以外の場合、結果はその年の最初の 2 桁 + 1 になります。
D 1	曜日 (1-7)。 1 は日曜日で、7 は土曜日です。
DD	月の日 (01 から 31)。
DDD	年の日 (001 から 366)。
FF または FFn	小数部分の秒 (0 から 999999)。 数値 n は、リターン値に含められる桁数を指定するために使用されます。 n の有効値は、先行ゼロの付かない 1 から 12 (FF1-FF12) です。 FF を指定することは、FF6 を指定することと同等です。 timestamp-expression のタイム・スタンプの精度がこのフォーマットで指定された桁数よりも少ない場合は、数字のゼロが指定された桁数の右側に埋め込まれます。
HH	時刻 (01 から 12)。
HH12	時刻 (01 から 12)。
HH24	時刻 (00 から 24)。
ID	ISO 曜日 (1-7)。 1 は月曜日で、7 は土曜日です。
IW	年の ISO 週番号 (01-53)。 週は月曜日から始まり、7 日間を含みます。 第 1 週は、木曜日が含まれる年の第 1 週目であり、これは 1 月 4 日が含まれる第 1 週と同等です。
I	ISO 年 (0-9)。 返される ISO 週番号に基づく年の最後の桁。
IY	ISO 年 (00-99)。 返される ISO 週番号に基づく年の最後の 2 桁。
IYY	ISO 年 (000-999)。 返される ISO 週番号に基づく年の最後の 3 桁。
IYYY	ISO 年 (0000-9999)。 年の最後の 4 桁は、戻される ISO の週に基づきます。
J	ユリウス日付 (0000000 から 9999999)。
MI	分 (00-59)。
MM	月 (01-12)。 1 月は 01。
MONTH、Month、または month 1、2	大文字、文頭のみ大文字、または小文字のフォーマットの英語での月の名前。
MON、Mon、または mon 1、2	大文字、文頭のみ大文字、または小文字のフォーマットの英語での 3 文字の月の省略名。
NNNNNN	マイクロ秒 (000000-999999)。 このフォーマットは、FF6 を指定するのと同等です。
Q	四半期 (1 から 4)。 1 月から 3 月が 1。
RR	年の最後の 2 桁 (00-99)。 RR の動作は YY と同様です。
RRRR	年 (0000 から 9999)。 RRRR の動作は YYYY と同様です。
SS	秒 (00-59)。
SSSSS	直前の真夜中からの秒数 (00000 から 86400)。
TZH	タイム・ゾーン (時)。(-24 から +24 まで。この範囲は夏時間調整に対応します。)
TZM	タイム・ゾーンの分 (00 から 59)。
W	月の週 (1 から 5)。 週 1 は、月の最初の日から始まり、7 日目に終了します。
WW	年の週 (01 から 53)。 週 1 は、1 月 1 日から始まり 1 月 7 日に終わります。
Y	年の最後の 1 桁 (0-9)。
YY	年の最後の 2 桁 (00-99)。
YYY	年の最後の 3 桁 (000-999)。
YYYY	年 (0000 から 9999)。
注: このフォーマット・エレメントでは、大文字小文字が区別されます。 フォーマット・エレメントがあいまいな場合は、大/小文字を区別しないフォーマット・エレメントが最初に考慮されます。 正確なスペルと大文字小文字の組み合わせだけが使用できます。 このフォーマット・エレメントが無効な大文字小文字の組み合わせで指定された場合、エラーが返されます。

timestamp-expression が TIMESTAMP WITHOUT TIME ZONE 値の場合、format-string に TZH または TZM が含まれていてはなりません。

結果は、timestamp-expression を format-string で指定された形式で表現したものです。 format-string は、1 つ以上の区切り文字で区切ることができる一連のフォーマット・エレメントとして解釈されます。 format-string 内の文字ストリングは、上の表内の一致する最長のフォーマット・エレメントとして解釈されます。 同じ文字を含む 2 つのフォーマット・エレメントが分離文字で区切られていない場合、仕様は、左から始めて、テーブル内の最も長いマッチング・エレメントとして解釈され、フォーマット・ストリングの残りの部分で一致が検出されるまで続きます。 例えば、「YYYYYYDD」は、フォーマット・エレメント「YYYY」、「YY」、および「DD」として解釈されます。

最初の引数がタイム・ゾーン付きのタイム・スタンプである場合、または 2 番目の引数がタイム・ゾーンのフォーマット・エレメントを含む定数である場合は、結果のストリングにタイム・ゾーン付きのタイム・スタンプが含まれます。 それ以外の場合は、結果のストリングにタイム・ゾーンは含まれません。

結果は、format-string で指定された形式の timestamp-expression を含む可変長文字ストリングになります。 format-string が定数の場合、結果の長さ属性は、最大 255 と format-string の長さ属性になります。 それ以外の場合、長さ属性は 255 です。 format-string は、結果の実際の長さも決定します。 実際の長さは、結果の長さ属性を超えてはなりません。

結果は NULL 値になることがあります。いずれかの引数が NULL 値である場合、結果は NULL 値になります。

結果の CCSID は、関数が呼び出されるコンテキストによって決まります。 詳細については、 文字列のエンコード・スキームとCCSIDルールを参照のこと。

10 進浮動小数点数から VARCHAR へ

数値式

組み込み数値データ・タイプの値を戻す式。 引数が 10 進浮動小数点値ではない場合、処理のために DECFLOAT(34) に変換されます。

書式文字列

CHAR、VARCHAR、または数値の組み込みデータ・タイプの値を返さなければならない式。 値が CHAR データ・タイプでも VARCHAR データ・タイプでもない場合、その値は関数を評価する前に暗黙的に VARCHAR にキャストされます。 指定した引数が GRAPHIC または VARGRAPHIC のデータ・タイプであると、まず VARCHAR に変換されてから、関数が評価されます。 実際の長さは、254 バイト以下でなければなりません。

値は、numeric-expression のフォーマット設定方法を示すテンプレートです。 format-string には、以下にリストするフォーマット・エレメントの有効な組み合わせが含まれていなければなりません。有効な組み合わせは、次の規則に従います。

• 符号のフォーマット・エレメント (「S」、「MI」、「PR」) を指定できるのは 1 回だけです。
• 小数点のフォーマット・エレメントを指定できるのは 1 回だけです。
• 英字のフォーマット・エレメントは、大文字で指定する必要があります。
• 接頭部のフォーマット・エレメントを指定できるのは、フォーマット・ストリングの先頭のみです。また、接頭部のフォーマット・エレメントの前に接頭部以外のフォーマット・エレメントがあってはなりません。 複数の接頭部のフォーマット・エレメントを指定するときには、どのような順番で指定してもかまいません。
• 接尾部のフォーマット・エレメントを指定できるのは、フォーマット・ストリングの末尾のみです。また、接尾部のフォーマット・エレメントの後に接尾部以外のフォーマット・エレメントがあってはなりません。 複数の接尾部フォーマット・エレメントを指定する場合は、任意の順序で指定できます。
• コンマのフォーマット・エレメントは、接頭部のフォーマット・エレメントではない最初のフォーマット・エレメントであってはなりません。 コンマのフォーマット・エレメントは、いくつでも使用することができます。
• ブランクをフォーマット・エレメントの間に指定することはできません。 前後のブランクを指定することはできますが、それらは結果のフォーマット設定で無視されます。

表 2. VARCHAR_FORMAT (数値から VARCHAR へ) 関数のフォーマット・エレメント

フォーマット・エレメント	説明
0	各 0 は、有効数字桁を表します。 数字の先行ゼロは、ゼロとしてフォーマット設定されます。
9	各 9 は、指定された位置に含めることができる有効数字を表します。 数字の先行ゼロは、ブランクとしてフォーマット設定されます。 区切り文字の左側に少なくとも 1 桁あるグループ区切り文字のみが生成されます。
S	接頭部 numeric-expression が負数の場合は、先行の負符号 (-) が含まれます。 numeric-expression が正数の場合、結果には先頭の正符号 (+) が含まれます。
$	接頭部 結果には、先頭のドル記号 ($) が含まれます。
MI	接尾部 numeric-expression が負の数値の場合、結果には末尾の負符号 (-) が含まれます。 numeric-expression が正数の場合、結果には末尾ブランクが含まれます。
PR	接尾部 numeric-expression が負数の場合、先頭の小なり文字 (<) と末尾の大なり文字 (>) が結果に含まれます。 numeric-expression が正数の場合、結果には先行ブランクと末尾ブランクが含まれます。
, (コンマ)	各コンマは、その左側に接頭部文字ではない文字がある場合、結果の指定の場所に組み込まれるグループ分離文字を表します。 このコンマはグループ分離文字として使用されます。
. (ピリオド/小数点)	ピリオドは、結果の指定の場所に組み込まれる小数点を表します。 このピリオドは小数点として使用されます。

フォーマット文字列が指定されていない場合、関数は次のようになります。 VARCHAR( 数値式 )。

結果は、format-string で指定された形式の numeric-expression 値 (丸められる場合があります) の表現になります。 フォーマット設定の前に、小数点の右側の桁数が format-string の小数点の右側の数字フォーマット・エレメントの数 ('0' または '9') より大きい場合は、ROUND 関数を使用して numeric-expression の値が丸められます。 format-string は、以下の規則に従って適用されます。

• 以下の条件のすべてを満たす場合、結果に含まれる小数点の左側には数字がありません。
  • -1 < rounded-input-value < 1
  • format-string に、小数点の左側の「0」フォーマット・エレメントが含まれていない。
  • format-string に、小数点の右側の桁フォーマット・エレメント (「0」または「9」) が含まれている。
• 以下の条件をすべて満たす場合、結果に含まれる暗黙的または明示的小数点の直前に、単一の 0 文字が組み込まれます。
  • rounded-input-value の値が 0 または -0 である。
  • format-string に、暗黙的または明示的小数点の左側の「9」桁フォーマット・エレメントだけが含まれる。
  • format-string に、小数点の右側の桁フォーマット・エレメントが含まれていない。
• フォーマット文字列に小数点の左側に「0」と「9」の両方のフォーマット要素が含まれている場合、フォーマット文字列の最初の数字フォーマット要素の位置によって、先頭の空白またはゼロの有無が決まります。 暗黙的または明示的小数点の左側で、一番左の「0」フォーマット・エレメントの後に指定されたすべての「9」フォーマット・エレメントは、「0」フォーマット・エレメントが指定された場合と同じように扱われます。 例えば、format-string 値「99099」は、値「99000」と同じです。
• rounded-input-value に含まれる小数点の右側の桁数が、format-string に含まれる小数点の右側の桁フォーマット・エレメントの数より少ない場合、結果には、format-string に含まれる小数点右側の桁フォーマット・エレメントの数に対応する数字の桁数になるまで右側にゼロが埋め込まれます。
• rounded-input-value に含まれる小数点の左側の桁数が、format-string に含まれる小数点の左側の桁フォーマット・エレメントの数より多い場合、結果は、format-string が結果で有効な値として生成する長さと一致する番号記号 (#) 文字のストリングになります。
• rounded-input-value の値が正または負の特殊値 Infinity、sNaN、または NaN を表す場合、format-string で指定されたフォーマットを使用せずに、ストリング「INFINITY」、「SNAN」、「NAN」、「-INFINITY」、「-SNAN」、または「-NAN」が返されます。 10 進浮動小数点の特殊値 sNaN は、ストリングに変換される場合、例外を生じません。
• format-string に符号フォーマット・エレメント「S」、「MI」、または「PR」がいずれも含まれていない場合、rounded-input-value の値が負であると、結果に負符号 (-) が組み込まれます。 そうでなければ、結果のストリングにブランクが組み込まれます。 負符号 (-) またはブランクは、結果の小数点の左側の最初の数字の直前、または小数点の左側に数字がない場合には、小数点の直前に置かれます。

結果は、rounded-input-value を可変長文字ストリングで表現したものになります。 単一の引数を指定した場合、長さ属性は 42 です。 それ以外の場合、長さ属性は 254 です。 結果の実際の長さは、format-string (指定されている場合) によって決まります。 指定されていない場合、結果の実際の長さは、rounded-input-value の値を表現可能な最小文字数になります。 結果のストリングが結果の長さ属性より長い場合、結果は切り捨てられます。

結果の CCSID は、関数が呼び出されるコンテキストによって決まります。 詳細については、 文字列のエンコード・スキームとCCSIDルールを参照してください

注

ユリウス暦およびグレゴリオ暦:

タイム・スタンプから可変長文字ストリングへの変換の場合、この関数では、1582 年 10 月 15 日のユリウス暦からグレゴリオ暦への移行が考慮されます。

決定論:

VARCHAR_FORMAT 決定論的な関数です。

「D」、「Y」、および「y」フォーマット・エレメントの使用:

Db2 for z/OS® 他のプラットフォームでサポートされている「DY」、「dy」、および「Dy」形式要素はサポートしていません。 「DY」または「Dy」がフォーマット・ストリングに指定されている場合、「D」フォーマット・エレメントに続けて「Y」または「y」フォーマット・エレメントがあるものとして解釈されます。 この動作は、今後のリリースで変更される可能性があります。 「D」に続く「Y」または「y」が、2 つの個別のフォーマット・エレメントとして解釈されるようにするには、「D」フォーマット・エレメントの後に区切り文字を含めてください。

代替構文:

TO_CHAR は VARCHAR_FORMAT の同義語です。