VARCHAR_FORMAT スカラー関数

VARCHAR_FORMAT 関数は、入力式の文字表現を戻します。

文字ストリングから VARCHAR へ

DATE または TIMESTAMP から VARCHAR へ

符号付き数値から VARCHAR へ

スキーマは SYSIBM です。

VARCHAR_FORMAT 関数のいずれかの引数が NULL 値の可能性がある場合、結果も NULL 値になる可能性があります。いずれかの引数が NULL 値の場合、結果は NULL 値になります。

文字ストリングから VARCHAR へ

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

結果は、引数の長さ属性と一致する長さ属性のある VARCHAR になります。結果の値は、character-expression の値と同じになります。

結果のコード・ページは、そのセクションのコード・ページです。

DATE または TIMESTAMP から VARCHAR へ

date-or-timestamp-expression

DATE または TIMESTAMP である値か、CLOB でも DBCLOB でもない日付またはタイム・スタンプの有効なストリング表記である値を戻す式。 Unicode データベースでは、式によって日付またはタイム・スタンプのグラフィック・ストリング表記が戻る場合、戻り値はまず文字ストリングに変換されてから、関数が評価されます。

入力式が戻す内容に応じて以下のようになります。

ストリングの場合は、format-string 引数も指定しなければなりません。
DATE または日付のストリング表記である場合、戻り値は午前 0 時ちょうど (00.00.00) の時刻コンポーネントを使用して最初に TIMESTAMP(0) 値に変換されます。
タイム・スタンプの有効なストリング表記である場合、最初に TIMESTAMP(12) 値に変換されます。

日付/時刻の値のストリング表記の有効なフォーマットのリストについては、日付/時刻の値のストリング表記を参照してください。

format-string1

次のいずれかの組み込みデータ・タイプの値を戻す式。

CHAR または VARCHAR
符号付き数値
日時
GRAPHIC または VARGRAPHIC (Unicode データベースのみ)

データ・タイプが CHAR または VARCHAR でない場合、関数が評価される前にデータ・タイプは VARCHAR に暗黙的にキャストされます。実際の長さは、255 バイト以下でなければなりません (SQLSTATE 22007)。この値は、timestamp-expression のフォーマット設定方法に関するテンプレートです。

デフォルトのフォーマット・ストリングは、特殊レジスター CURRENT LOCALE LC_TIME の値に基づきます。

フォーマット・ストリングを有効にするには、表 1 にリストしたフォーマット・エレメントの組み合わせを含める必要があります (SQLSTATE 22007)。2 つのフォーマット・エレメントは、オプションで以下の 1 つ以上の区切り文字で分離することができます。

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

区切り文字は format-string の始めまたは終わりにも指定できます。

表 1. DATE または TIMESTAMP から VARCHAR へのフォーマット・エレメント
フォーマット・エレメント	説明
AM または PM	ピリオドが付かない午前/午後の指定子。このフォーマット・エレメントは、`locale-name` を指定した場合にはこれに依存します。それ以外は、特殊レジスター CURRENT LOCALE LC_TIME の値に依存します。
A.M. または P.M.	ピリオドが付いた午前/午後の指定子。このフォーマット・エレメントでは、正確なストリングの 'A.M.' または 'P.M.' を使用し、有効なロケール名に依存しません。
CC	世紀 (01-99)。4 桁の年の最後の 2 桁がゼロの場合は、結果はこの年の最初の 2 桁に 1 を足したものです。
DAY、Day、または day	大文字、タイトル文字、または小文字のフォーマットの曜日の名前。使用される言語は、`locale-name` を指定した場合にはこれに依存します。それ以外は、特殊レジスター CURRENT LOCALE LC_TIME の値に依存します。
DY、Dy、または dy	大文字、タイトル文字、または小文字のフォーマットの曜日の省略名。使用される言語は、`locale-name` を指定した場合にはこれに依存します。それ以外は、特殊レジスター CURRENT LOCALE LC_TIME の値に依存します。
D	曜日 (1-7)。曜日の最初の日は、`locale-name` を指定した場合にはこれに依存します。それ以外は、特殊レジスター CURRENT LOCALE LC_TIME の値に依存します。
DD	日 (01-31)。
DDD	年間通算日 (001-366)
FF または FFn	小数点以下の秒数 (0-999999999999)。n は戻り値の位取りを指定します。n の有効値は、先行ゼロの付かない 1 から 12 です。FF を指定することは、FF6 を指定することと同等です。入力タイム・スタンプの位取りが n 未満の場合、結果は後続ゼロで埋め込まれます。
HH	HH の動作は HH12 と同様です。
HH12	12 時間形式の時 (01-12)。
HH24	24 時間形式の時 (00-24)。
I	ISO 年 (0-9)。返される ISO 週番号に基づく年の最後の桁。
ID	ISO 曜日 (1-7)。1 は月曜日で、7 は土曜日です。
IW	年の ISO 週番号 (01-53)。週は月曜日から始まり、7 日から成ります。第 1 週は、木曜日が含まれる年の第 1 週目であり、これは 1 月 4 日が含まれる第 1 週と同等です。
IY	ISO 年 (00-99)。返される ISO 週番号に基づく年の最後の 2 桁。
IYY	ISO 年 (000-999)。返される ISO 週番号に基づく年の最後の 3 桁。
IYYY	ISO 年 (0000-9999)。返される ISO 週番号に基づく 4 桁の年。
J	ユリウス日 (紀元前 4713 年 1 月 1 日からの日数)。
MI	分 (00-59)。
MM	月 (01-12)。
MONTH、Month、または month	大文字、タイトル文字、または小文字のフォーマットの月の名前。使用される言語は、`locale-name` を指定した場合にはこれに依存します。それ以外は、特殊レジスター CURRENT LOCALE LC_TIME の値に依存します。
MON、Mon、または mon	大文字、タイトル文字、または小文字のフォーマットの月の省略名。使用される言語は、`locale-name` を指定した場合にはこれに依存します。それ以外は、特殊レジスター CURRENT LOCALE LC_TIME の値に依存します。
MS	ミリ秒 (000-999)。FF3 と同様。
NNNNNN	マイクロ秒 (000000-999999)。FF6 と同様。
Q	四半期 (1-4)。例えば、1 月から 3 月までの月では 1 が返されます。
RR	RR の動作は YY と同様です。
RRRR	RRRR の動作は YYYY と同様です。
SS	秒 (00-59)。
SSSSS	直近の午前 0 時からの秒数 (00000-86400)。
US	マイクロ秒 (000000-999999)。FF6 と同様。
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	4 桁の年 (0000-9999)。

表 1 内のフォーマット・エレメントは以下のものを除き、大文字と小文字の区別はありません。

AM、PM
A.M.、P.M.
DAY、Day、day
DY、Dy、dy
D
MONTH、Month、month
MON、Mon、mon

フォーマット・エレメントがあいまいな場合は、大/小文字を区別しないフォーマット・エレメントが最初に考慮されます。例えば、「DDYYYY」は「D の後に DY その後に YYY が続く」と解釈されるのではなく、「DD の後に YYYY が続く」と解釈されます。

locale-name

以下のフォーマット・エレメントに使用されるロケールを指定する文字定数。

AM、PM
DAY、Day、day
DY、Dy、dy
D
MONTH、Month、month
MON、Mon、mon

指定するロケール名は、大/小文字の区別がなく、有効なロケールでなければなりません (SQLSTATE 42815)。有効なロケールとその命名については、『SQL および XQuery のロケール名』を参照してください。デフォルトは CURRENT LOCALE LC_TIME 特殊レジスターの値です。

結果は、フォーマット・ストリングで指定したフォーマットの入力タイム・スタンプ式の表記です。フォーマット・ストリングは、1 つ以上の区切り文字で分離できる一連のフォーマット・エレメントとして解釈されます。フォーマット・ストリング内の文字のストリングは、表 1 にある一致する最長のフォーマット・エレメントとして解釈されます。同じ文字が含まれる 2 つのフォーマット・エレメントを区切り文字で区切らない場合は、この指定は、左から始めて上の表内の一致する最長のフォーマット・エレメントとして解釈され、このフォーマット・ストリングの残りに一致するものが見つかるまで続けられます。例えば、'YYYYYYDD' のフォーマット・エレメントは 'YYYY'、'YY'、および 'DD' と解釈されます。

結果は、可変長文字ストリングです。長さ属性は 255 です。環境または format-string のストリング単位が CODEUNITS32 である場合、結果のストリング単位は CODEUNITS32 です。それ以外の場合、結果のストリング単位は OCTETS です。 format-string は、結果の実際の長さも決定します。結果のストリングが結果の長さ属性を超える場合、結果は切り捨てられます。

結果のコード・ページは、そのセクションのコード・ページです。

符号付き数値から VARCHAR へ

numeric-expression

組み込み符号付き数値データ・タイプの値を戻す式。値のデータ・タイプが DECFLOAT でない場合、そのデータ・タイプは処理を行うために DECFLOAT(34) に変換されます。

format-string2

次のいずれかの組み込みデータ・タイプがある値を戻す式。

CHAR または VARCHAR
符号付き数値
日時
GRAPHIC または VARGRAPHIC (Unicode データベースのみ)

データ・タイプが CHAR または VARCHAR でない場合、関数が評価される前にデータ・タイプは VARCHAR に暗黙的にキャストされます。実際の長さは、255 バイト以下でなければなりません (SQLSTATE 22018)。この値は、10 進数浮動小数点式の入力をフォーマット設定する際のテンプレートとして使用されます。接頭部として指定するフォーマット・エレメントは、テンプレートの先頭でのみ使用できます。接尾部として指定するフォーマット・エレメントは、テンプレートの末尾でのみ使用できます。テンプレートには、複数の MI、S、または PR フォーマット・エレメントを含めることはできません (SQLSTATE 22018)。

フォーマット・ストリングが指定されない場合は、10 進数浮動小数点式の入力は SQL の 10 進浮動小数点定数の形式にフォーマット設定されます。結果の最初の文字は、10 進数浮動小数点式の入力が負であれば、負符号となります。負でなければ、最初の文字は数字です。10 進数浮動小数点式の入力がゼロの場合、結果は 0 になります。

表 2. 10 進数浮動小数点から VARCHAR へのフォーマット・エレメント
フォーマット・エレメント	説明
0	各 0 は、有効数字桁を表します。数字の先行ゼロは、ゼロで表示されます。
9	各 9 は、有効数字桁を表します。数字の先行ゼロは、ブランクで表示されます。
PL または pl	10 進数浮動小数点式の入力が正数を戻す場合は、指定された位置に正符号 (+) が追加されます。
G または g	ロケールで指定されているグループ分離文字が、指定された位置に追加されます。
D または d	ロケールで指定されている小数点区切り文字が、指定された位置に追加されます。
,	コンマが、グループ分離文字などとして、指定された位置に追加されます。
.	ピリオドが、小数点区切り文字などとして、指定された位置に追加されます。
S または s	接頭部: 10 進数浮動小数点式の入力が戻す内容に応じて以下のようになります。負数の場合は、結果に先行の負符号 (-) が追加されます。正数の場合は、結果に先行の正符号 (+) が追加されます。
$	接頭部: 結果に先行のドル記号 ($) が追加されます。
MI または mi	接尾部: 10 進数浮動小数点式の入力が戻す内容に応じて以下のようになります。負数の場合は、結果に末尾の負符号 (-) が追加されます。正数の場合は、結果に末尾ブランクが追加されます。
PR または pr	接尾部: 10 進数浮動小数点式の入力が戻す内容に応じて以下のようになります。負数の場合は、結果に先行の「より小さい」の文字 (<) と末尾の「より大きい」の文字 (>) が追加されます。正数の場合は、結果に先行スペースと末尾スペースが追加されます。

フォーマット・エレメントには、大/小文字の区別があります。

locale-name

グループ分離文字と小数点区切り文字を判別する際に使用するロケールを指定する文字定数。

結果は、10 進数浮動小数点式の入力の可変長文字ストリング表記です。長さ属性は 255 です。環境またはフォーマット・ストリングのストリング単位が CODEUNITS32 である場合、結果のストリング単位は CODEUNITS32 です。CODEUNITS32 でない場合、結果のストリング単位は OCTETS です。結果の実際の長さは、フォーマット・ストリングが指定された場合、それで決定されます。指定されなかった場合は、結果の実際の長さは、10 進数浮動小数点式の入力の値を表すことのできる最小の文字数です。結果のストリングが結果の長さ属性を超える場合、結果は切り捨てられます。

10 進数浮動小数点式の入力の値が以下の特殊値の場合、結果は次のようになります。

Infinity の場合、ストリング「INFINITY」が戻されます。
sNaN の場合、ストリング「SNAN」が戻されます。
NaN の場合、ストリング「NAN」が戻されます。

特殊値が負である場合、結果の先頭の文字は負符号 (-) になります。10 進浮動小数点の特殊値 sNaN は、ストリングに変換される場合、例外を生じません。

フォーマット・ストリングにフォーマット・エレメントの MI、S、または PR のいずれも含まれず、入力式の値が負の場合は、負符号 (-) が結果に含まれます。それ以外の場合は、ブランクが結果に含まれます。

入力式の小数点の左側の桁数がフォーマット・ストリングの小数点の左側の桁数より大きい場合、結果は 1 つ以上の番号記号 (#) 文字のストリングになります。入力式の小数点の右側の桁数がフォーマット・ストリングの小数点の右側の桁数より大きい場合、結果はフォーマット・ストリングの小数点の右側の桁数に丸められます。DECFLOAT の丸めモードは使用されません。VARCHAR_FORMAT の丸めの動作は、ROUND_HALF_UP の値と一致します。

結果のコード・ページは、そのセクションのコード・ページです。

注

ユリウス暦およびグレゴリオ暦: Timestamp から varchar への場合、この関数では、1582 年 10 月 15 日のユリウス暦から、グレゴリオ暦への移行が考慮されます。
決定論: VARCHAR_FORMAT は決定論的な関数です。ただし、以下の関数の呼び出しは、特殊レジスターの CURRENT LOCALE LC_TIME の値によって決まります。
- TIMESTAMP から VARCHAR で、format-string が明示的に指定されないか、または locale-name が明示的に指定されない場合で、以下のステートメントのいずれかが当てはまる場合:
  - format-string が定数でない
  - format-string が定数で、ロケールに依存するフォーマット・エレメントが含まれる
  特殊レジスターの値に依存するこれらの呼び出しは、特殊レジスターを使用できない場合、常に使用することができません (SQLSTATE 42621、428EC、または 429BX)。
代替構文: TO_CHAR は VARCHAR_FORMAT の同義語です。

例

例 1: 名前が SYSU で始まるすべてのシステム表の名前と作成タイム・スタンプを表示します。

   SELECT VARCHAR(TABNAME, 20) AS TABLE_NAME,
     VARCHAR_FORMAT(CREATE_TIME, 'YYYY-MM-DD HH24:MI:SS')
       AS CREATION_TIME
     FROM SYSCAT.TABLES
     WHERE TABNAME LIKE 'SYSU%'

この例では、以下の出力を戻します。

   TABLE_NAME           CREATION_TIME
   -------------------- -------------------
   SYSUSERAUTH          2000-05-19 08:18:56
   SYSUSEROPTIONS       2000-05-19 08:18:56

例 2: 変数 TMSTMP が TIMESTAMP として定義されており、 2007-03-09-14.07.38.123456 という値が設定されています。以下の各例では、VARCHAR_FORMAT 関数の呼び出しと結果のストリング値が示されています。各結果のデータ・タイプは VARCHAR(255) です。


関数呼び出し                                    結果
-------------------                          ------
VARCHAR_FORMAT(TMSTMP,'YYYYMMDDHHMISSFF3')  20070309020738123
VARCHAR_FORMAT(TMSTMP,'YYYYMMDDHH24MISS')   20070309140738
VARCHAR_FORMAT(TMSTMP,'YYYYMMDDHHMI')       200703090207

VARCHAR_FORMAT(TMSTMP,'HH12:MI:SS.MS')      14:07:38.123
VARCHAR_FORMAT(TMSTMP,'H12:MI:SS.US')      14:07:38.123456

VARCHAR_FORMAT(TMSTMP,'DD/MM/YY')           09/03/07
VARCHAR_FORMAT(TMSTMP,'MM-DD-YYYY')         03-09-2007
VARCHAR_FORMAT(TMSTMP,'J')                  2454169
VARCHAR_FORMAT(TMSTMP,'Q')                  1
VARCHAR_FORMAT(TMSTMP,'W')                  2
VARCHAR_FORMAT(TMSTMP,'IW')                 10
VARCHAR_FORMAT(TMSTMP,'WW')                 10
VARCHAR_FORMAT(TMSTMP,'Month','en_US')      March 
VARCHAR_FORMAT(TMSTMP,'MONTH','en_US')      MARCH 
VARCHAR_FORMAT(TMSTMP,'MON','en_US')        MAR 
VARCHAR_FORMAT(TMSTMP,'Day','en_US')        Friday 
VARCHAR_FORMAT(TMSTMP,'DAY','en_US')        FRIDAY 
VARCHAR_FORMAT(TMSTMP,'Dy','en_US')         Fri 
VARCHAR_FORMAT(TMSTMP,'Month','de_DE')      März 
VARCHAR_FORMAT(TMSTMP,'MONTH','de_DE')      MÄRZ 
VARCHAR_FORMAT(TMSTMP,'MON','de_DE')        MRZ 
VARCHAR_FORMAT(TMSTMP,'Day','de_DE')        Freitag 
VARCHAR_FORMAT(TMSTMP,'DAY','de_DE')        FREITAG 
VARCHAR_FORMAT(TMSTMP,'Dy','de_DE')         Fr

例 3: 変数の DTE が DATE で定義され、 2007-03-09 という値が設定されています。以下の各例では、いくつかの関数の呼び出しと結果のストリング値が示されています。各結果のデータ・タイプは VARCHAR(255) です。
```
関数呼び出し                                    結果
-------------------                          ------
VARCHAR_FORMAT(DTE,'YYYYMMDD')               20070309
VARCHAR_FORMAT(DTE,'YYYYMMDDHH24MISS')       20070309000000
```

例 4: 変数の POSNUM と NEGNUM が両方とも DECFLOAT(34) で定義され、POSNUM の値が 1234.56、POSNUM の値が -1234.56 です。以下の各例では、いくつかの VARCHAR_FORMAT の呼び出しと結果のストリング値が示されています。各結果のデータ・タイプは VARCHAR(255) です。


関数呼び出し                                    結果
-------------------                           ------
VARCHAR_FORMAT(POSNUM)                        '1234.56'
VARCHAR_FORMAT(NEGNUM)                        '-1234.56'
VARCHAR_FORMAT(POSNUM,'9999.99')              '1234.56'
VARCHAR_FORMAT(NEGNUM,'9999.99')              '1234.56'
VARCHAR_FORMAT(POSNUM,'99999.99')             ' 1234.56'
VARCHAR_FORMAT(NEGNUM,'99999.99')             ' 1234.56'
VARCHAR_FORMAT(POSNUM,'00000.00')             '01234.56'
VARCHAR_FORMAT(NEGNUM,'00000.00')             '01234.56'
VARCHAR_FORMAT(POSNUM,'9999.99MI')            '1234.56 '
VARCHAR_FORMAT(NEGNUM,'9999.99MI')            '1234.56-'
VARCHAR_FORMAT(POSNUM,'S9999.99')             '+1234.56'
VARCHAR_FORMAT(NEGNUM,'S9999.99')             '-1234.56'
VARCHAR_FORMAT(POSNUM,'9999.99PR')            ' 1234.56 '
VARCHAR_FORMAT(NEGNUM,'9999.99PR')            '<1234.56>'
VARCHAR_FORMAT(POSNUM,'S$9,999.99')           '+$1,234.56'
VARCHAR_FORMAT(NEGNUM,'S$9,999.99')           '-$1,234.56'

VARCHAR_FORMAT(POSNUM,'99,99,99')           '12,34,56'
VARCHAR_FORMAT(NEGNUM,'99,99,99')             '-12,34,56'
VARCHAR_FORMAT(POSNUM,'PL9999.99')            '+1234.56'
VARCHAR_FORMAT(NEGNUM,'PL9999.99')            '-1234.56'
VARCHAR_FORMAT(POSNUM,'9999PL')               '1234+'
VARCHAR_FORMAT(NEGNUM,'9999PL')               '1234'
VARCHAR_FORMAT(POSNUM,'9999.9')               '1234.6'
VARCHAR_FORMAT(NEGNUM,'9999.9')               '-1234.6'
VARCHAR_FORMAT(POSNUM,'9999')                 '1235'
VARCHAR_FORMAT(NEGNUM,'9999')                 '-1235'
VARCHAR_FORMAT(POSNUM,'99.99')                '#####'
VARCHAR_FORMAT(NEGNUM,'99.99')                '#####'
VARCHAR_FORMAT(POSNUM,'9999D99', 'en_US')     '1234.56'
VARCHAR_FORMAT(POSNUM,'9999D99', 'fr_FR')     '1234,56'
VARCHAR_FORMAT(POSNUM,'9G999D99', 'en_US')    '1,234.56'
VARCHAR_FORMAT(POSNUM,'9G999D99', 'de_DE')    '1.234,56'