VARCHAR_FORMAT スカラー関数

文字ストリングから 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
• 符号付き数値
• Datetime
• 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 が続く」と解釈されます。

ロケール名

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

• 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
• 符号付き数値
• Datetime
• GRAPHIC または VARGRAPHIC (Unicode データベースのみ)

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

フォーマット・ストリングを指定しない場合、この関数は VARCHAR(DECFLOAT(numeric-expression)) と同等です。

表 2. 10 進数浮動小数点から VARCHAR へのフォーマット・エレメント

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

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

ロケール名

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

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

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

フォーマット・ストリングにフォーマット・エレメントの 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) です。

  Function invocation                          Result
  -------------------                          ------
  VARCHAR_FORMAT(TMSTMP,'YYYYMMDDHHMISSFF3')   20070309020738123
  VARCHAR_FORMAT(TMSTMP,'YYYYMMDDHH24MISS')    20070309140738
  VARCHAR_FORMAT(TMSTMP,'YYYYMMDDHHMI')        200703090207

  
  VARCHAR_FORMAT(TMSTMP,'HH12:MI:SS.MS AM')    02:07:38.123 PM
  VARCHAR_FORMAT(TMSTMP,'HH24: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')         MÄRZ 
  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) です。

  Function invocation                          Result
  -------------------                          ------
  VARCHAR_FORMAT(DTE,'YYYYMMDD')               20070309
  VARCHAR_FORMAT(DTE,'YYYYMMDDHH24MISS')       20070309000000
  

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

  Function invocation                           Result
  -------------------                           ------
  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,35'
  VARCHAR_FORMAT(NEGNUM,'99,99,99')             '   -12,35'
  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'