VARCHAR_FORMAT
VARCHAR_FORMAT 関数は、最初の引数の文字ストリング表現を、オプションの format-string で示されたフォーマットで戻します。
タイム・スタンプから可変長文字に
>>-VARCHAR_FORMAT--(--timestamp-expression--+------------------+--)->< '-,--format-string-'
数値から可変長文字に
VARCHAR_FORMAT 関数のいずれかの引数が NULL 値の可能性がある場合、 結果も NULL 値になる可能性があります。 いずれかの引数が NULL 値の場合、結果は NULL 値になります。
文字から可変長文字に
- character-expression
- 組み込み文字ストリングまたはグラフィック・ストリングのデータ・タイプの値を戻す式。
- 引数が文字ストリングの場合 :
- 結果の長さ属性と実際の長さは、以下のようにして決まります。
- 文字式 が空ストリング定数の場合は、結果の長さ属性は 1。
- 空ストリング定数でない場合は、結果の長さ属性と実際の長さは、引数の長さ属性と同じになります。
- 結果の実際の長さは、結果の長さ属性と character-expression の実際の長さのうち、小さい方になります。
- 結果の CCSID は以下のように決定されます。
- 引数が SBCS データであれば、結果は SBCS データになる。結果の CCSID は、引数の CCSID と同一です。
- 引数が混合データ (DBCS 混用、DBCS 専用、または DBCS 択一) であれば、結果は混合データになる。結果の CCSID は、引数の CCSID と同一です。
- 結果の長さ属性と実際の長さは、以下のようにして決まります。
- 引数がグラフィック・ストリングの場合、DBCS グラフィック・データであってはなりません。
- 結果の長さ属性と実際の長さは、以下のようにして決まります (ここで、n は character-expression の長さ属性です)。
- character-expression が空のグラフィック・ストリング定数の場合、結果の長さ属性は 1 です。
- 結果が SBCS データの場合、結果の長さ属性は n です。
- 結果が混合データの場合、結果の長さ属性は (2.5*(n-1)) + 4 です。
- 結果の実際の長さは、結果の長さ属性と character-expression の実際の長さのうち、小さい方になります。
- 結果の CCSID は、現行サーバーにおけるデフォルト CCSID です。デフォルト CCSID が混合データの場合は、結果は混合データになります。 デフォルト CCSID が SBCS データの場合は、結果は SBCS データになります。
- 結果の長さ属性と実際の長さは、以下のようにして決まります (ここで、n は character-expression の長さ属性です)。
タイム・スタンプから可変長文字に
- timestamp-expression
- 日付、タイム・スタンプ、文字ストリング、またはグラフィック・ストリングのいずれかの組み込みデータ・タイプの値を戻す式。引数が DATE である場合、時刻が午前 0 時ちょうど (00.00.00) であると想定して、最初に TIMESTAMP(0) 値に変換されます。
timestamp-expression が文字ストリングまたはグラフィック・ストリングである場合、expression の値は日付またはタイム・スタンプの有効なストリング表現でなければなりません。最初に TIMESTAMP(12) 値に変換されます。 タイム・スタンプのストリング表現の有効な形式に ついては、日付/時刻の値のストリング表記を参照してください。
引数がストリングの場合は、format-string 引数も指定しなければなりません。
- format-string
- 組み込み文字ストリング・データ・タイプか、グラフィック・ストリング・データ・タイプを戻す式。
値が CHAR データ・タイプでも VARCHAR データ・タイプでもない場合、その値は関数を評価する前に暗黙的に VARCHAR にキャストされます。format-string には、timestamp-expression のフォーマット設定方法を示すテンプレートが含まれています。結果値は大/小文字の任意の文字を含むことができます。 有効
な形式は、以下にリストされた形式を任意に組み合わせたものであり、オプションで、有効な区切り文字で区切ることができます。有効な区切り文字は次のとおりです。
- 負符号 (-)
- ピリオド (.)
- スラッシュ (/)
- コンマ (,)
- アポストロフィ (′)
- セミコロン (;)
- コロン (:)
- ブランク ( )
| 形式 | 単位 |
|---|---|
| AM または PM 1、2 | ピリオドが付かない午前/午後の指定子。戻される午前/午後の指定子 は、ジョブのメッセージに使用される言語に基づいています。この午前/午後の指定子は、 ライブラリー *LIBL の中のメッセージ・ファイル QCPFMSG 内のメッセージ CPX9035 から取り出されます。 |
| A.M. または P.M. 1、2 | ピリオドが付いた午前/午後の指定子。このフォーマット・エレメントは、 「A.M.」または「P.M.」と正確に一致するストリングを使用し、ジョブのメッセージに使用される言語には 関係ありません。 |
| CC | 世紀 (00 から 99)。4 桁の年の最後の 2 桁がゼロの場合、結果は年の最初の 2 桁です。 それ以外の場合、結果は年の最初の 2 桁に 1 を加えた数です。 |
| DAY、Day、または day 1、2 | 大文字、タイトル文字、または小文字のフォーマットの曜日の名前。 戻される曜日の名前は、 ジョブのメッセージに使用される言語に基づいています。 曜日の名前は、ライブラリー *LIBL の中のメッセージ・ファイル QCPFMSG のメッセージ CPX9034 から検索されます。 |
| DY、Dy、または dy 1、3 | 大文字、タイトル文字、または小文字のフォーマットの曜日の省略名。 省略された曜日の名前は、ライブラリー *LIBL の中のメッセージ・ファイル QCPFMSG のメッセージ CPX9039 から検索されます。 |
| D 1 | 曜日 (1-7)。1 は日曜日です。 |
| DD | 日 (01 から 31)。 |
| DDD | 年間通算日 (001 から 366)。 |
| FF または FFn | 小数秒 (0 から 999999999999)。数値 n は、返される値に含む桁数を指定します。 n の有効な値は 1 から 12 です。デフォルトは 6 です。 |
| HH | HH の動作は HH12 と同様です。 |
| HH12 | 12 時間形式の時 (01-12)。 |
| HH24 | 24 時間形式の時刻 (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)。返される ISO の週に基づく年。 |
| J | ユリウス日付 (0000000 から 9999999)。 |
| MI | 分 (00 から 59)。 |
| MM | 月 (01 から 12)。 |
| MONTH、Month、または month 1、3 | 大文字、タイトル文字、または小文字のフォーマットの月の名前。 戻される月の名前は、 ジョブのメッセージに使用される言語に基づいています。 月の名前は、ライブラリー *LIBL の中のメッセージ・ファイル QCPFMSG のメッセージ CPX3BC0 から検索されます。 |
| MON、Mon、または mon 1、3 | 大文字、タイトル文字、または小文字のフォーマットの月の省略名。 戻される月の名前は、 ジョブのメッセージに使用される言語に基づいています。 月の名前は、ライブラリー *LIBL の中のメッセージ・ファイル QCPFMSG のメッセージ CPX8601 から検索されます。 |
| NNNNNN | マイクロ秒 (000000-999999)。FF6 と同様。 |
| Q | 四半期 (1 から 4)。 |
| RR | RR の動作は YY と同様です。 |
| RRRR | RRRR の動作は YYYY と同様です。 |
| SS | 秒 (00 から 59)。 |
| SSSSS | 前の深夜 12 時以降の秒数 (00000 から 86400)。 |
| 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)。 |
注 :
- このフォーマット・エレメントでは、大文字小文字が区別されます。フォーマット・エレメントがあいまいな場合は、大/小文字を区別しないフォーマット・エレメントが最初に考慮されます。
- 午前/午後の指定子として、A.M. と P.M. と同様に AM と PM のセットを format-string で使用できます。 結果ストリングには、実際の時刻値に適切な午前/午後の指定子が入ります。
- 正確なスペルと大文字小文字の組み合わせだけが使用できます。 このフォーマット・エレメントが無効な大文字小文字の組み合わせで指定された場合、エラーが返されます。
有効なフォーマット・ストリングの例を次に示します。
'HH24-MI-SS'
'HH24-MI-SS-NNNNNN'
'YYYY-MM-DD'
'YYYY-MM-DD-HH24-MI-SS'
'YYYY-MM-DD-HH24-MI-SS-NNNNNN'
'FF3.J/Q-YYYY'結果は、timestamp-expression を format-string で指定された形式で表現したものです。format-string は、1 つ以上の区切り文字で区切ることができる一連のフォーマット・エレメントとして解釈されます。format-string 内の文字ストリングは、前述の表のエレメントに一致する最長のフォーマット・エレメントとして解釈されます。2 つのフォーマット・エレメントが同じ文字で構成され、区切り文字で分離されていない場合、その指定は、左から始まり、前述の表のエレメントに一致する最長エレメントとして解釈され、フォーマット・ストリングの残りの部分について一致が見つかるまで続きます。 例えば、DDYYYY は D の後に DY その後に YYY が続くと解釈されるのではなく、DD の後に YYYY が続くと解釈されます。
format-string が指定されていない場合、timestamp-expression は、タイム・スタンプの可変長文字ストリング表現として戻されます。
結果のデータ・タイプは、format-string のデータ・タイプと同じです。結果の長さ属性は最大 255 で、format-string の長さ属性です。format-string は、結果の実際の長さも決定します。実際の長さは、結果の長さ属性を超えてはなりません。
結果の CCSID は format-string の CCSID と同じです。format-string が指定されていない場合、結果の CCSID は現行サーバーのデフォルトの SBCS CCSID になります。
数値から可変長文字に
- numeric-expression
- 任意の組み込み数値データ・タイプの値を戻す式。引数が 10 進浮動小数点値ではない場合、処理のために DECFLOAT(34) に変換されます。
- format-string
- 組み込み文字ストリング、グラフィック・ストリング、または数値のデータ・タイプを戻す式。
値が CHAR データ・タイプでも VARCHAR データ・タイプでもない場合、その値は関数を評価する前に暗黙的に VARCHAR にキャストされます。format-string には、numeric-expression のフォーマット設定方法を示すテンプレートが含まれています。format-string には、以下にリストするフォーマット・エレメントの有効な組み合わせが含まれていなければなりません。有効な組み合わせは、次の規則に従います。
- 符号のフォーマット・エレメント (「S」、「MI」、「PR」) を指定できるのは 1 回だけです。
- 小数点のフォーマット・エレメントを指定できるのは 1 回だけです。
- 英字のフォーマット・エレメントは、大文字で指定する必要があります。
- 接頭部のフォーマット・エレメントを指定できるのは、フォーマット・ストリングの先頭のみです。また、接頭部のフォーマット・エレメントの前に接頭部以外のフォーマット・エレメントがあってはなりません。複数の接頭部のフォーマット・エレメントを指定するときには、どのような順番で指定してもかまいません。
- 接尾部のフォーマット・エレメントを指定できるのは、フォーマット・ストリングの末尾のみです。また、接尾部のフォーマット・エレメントの後に接尾部以外のフォーマット・エレメントがあってはなりません。
- コンマおよび G のフォーマット・エレメントは、接頭部のフォーマット・エレメント以外の最初のフォーマット・エレメントにしてはなりません。 コンマまたは G のフォーマット・エレメントは、いくつでも使用することができます。
- ブランクをフォーマット・エレメントの間に指定することはできません。前後のブランクを指定することはできますが、それらは結果のフォーマット設定で無視されます。
| フォーマット・エレメント | 説明 |
|---|---|
| 0 | 各 0 は、有効数字桁を表します。数字の先行ゼロは、ゼロで表示されます。 |
| 9 | 各 9 は、有効数字桁を表します。数字の先行ゼロは、ブランクで表示されます。区切り文字の左に少なくとも 1 桁があるグループ区切り文字のみが生成されます。 |
| S | 接頭部: numeric-expression が負の数値の場合は、結果に先行の負符号 (-) が含まれます。numeric-expression が正数の場合は、結果に先行の正符号 (+) が含まれます。 |
| $ | 接頭部: 結果に先行のドル記号 ($) が含まれます。 |
| MI | 接尾部: numeric-expression が負の数値の場合は、結果に末尾の負符号 (-) が含まれます。numeric-expression が正数の場合は、結果に末尾ブランクが含まれます。 |
| PR | 接尾部: numeric-expression が負の数値の場合は、結果に先行の「より小さい」の文字 (<) と末尾の「より大きい」の文字 (>) が含まれます。numeric-expression が正数の場合は、結果に先行スペースと末尾スペースが含まれます。 |
| , | コンマが結果のその位置に含まれることを指定します。 このコンマは、グループ分離文字として使用されます。 |
| . | ピリオドが結果のその位置に含まれることを指定します。 このピリオドは小数点として使用されます。 |
| L | 接頭部または接尾部: ローカル通貨記号が結果のその位置に含まれることを指定します。 通貨記号は、ライブラリー *LIBL の中のメッセージ・ファイル QCPFMSG のメッセージ CPX8416 から検索されます。 |
| D | ローカルの小数点文字が結果のその位置に含まれることを指定します。 小数点文字は、ライブラリー *LIBL の中のメッセージ・ファイル QCPFMSG のメッセージ CPX8416 から検索されます。 |
| G | ローカルのグループ区切り文字が結果のその位置に含まれることを指定します。 ライブラリー *LIBL の中のメッセージ・ファイル QCPFMSG のメッセージ CPX8416 から検索されたローカルの小数点文字がピリオドである場合、グループ区切り文字はコンマになります。 ローカルの小数点文字がコンマの場合、グループ区切り文字はピリオドになります。 |
format-string が指定されていなければ、この関数は VARCHAR(numeric-expression) と同等です。
結果は、numeric-expression 値 (丸められる場合もあります) を format-string で指定されたフォーマットで表現したものです。小数点の右側の桁数が format-string 内の小数点の右側の桁フォーマット・エレメント (「0」または「9」) の数より大きい場合、フォーマット設定の前に、numeric-expression の値が ROUND 関数によって丸められます。
format-string は、以下の規則に従って、この rounded-input-value に適用されます。
- 以下の条件のすべてを満たす場合、結果に含まれる小数点の左側には数字がありません。
- -1 < rounded-input-value < 1
- format-string に、小数点の左側の「0」フォーマット・エレメントが含まれていない。
- format-string に、小数点の右側の桁フォーマット・エレメント (「0」または「9」) が含まれている。
- 以下の条件をすべて満たす場合、結果に含まれる暗黙的または明示的小数点の直前に、単一の 0 文字が組み込まれます。
- rounded-input-value の値が 0 または -0 である。
- format-string に、暗黙的または明示的小数点の左側の「9」桁フォーマット・エレメントだけが含まれる。
- format-string に、小数点の右側の桁フォーマット・エレメントが含まれていない。
- 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 は、format-string の CCSID と同一です。format-string が指定されていない場合、結果の CCSID は現行サーバーのデフォルトの SBCS CCSID になります。
注記
代替構文: TO_CHAR は VARCHAR_FORMAT の同義語です。
例
例: タイム・スタンプから可変長文字
- 文字変数 TVAR を、CORPDATA.IN_TRAY からの RECEIVED のタイム・スタンプ値のストリング表現 (YYYY-MM-DD HH24:MI:SS としてフォーマット) に設定します。
以下のストリングを戻します。SELECT VARCHAR_FORMAT(RECEIVED,'YYYY-MM-DD HH24:MI:SS') INTO :TVAR FROM CORPDATA.IN_TRAY WHERE SOURCE = 'CHAAS'
RECEIVED 列内の値が 2000 年の開始の 1 秒前 (December 31, 1999 at 23:59:59pm) とすると、次のストリングが戻されます。1988-12-22 14:07:21
フォーマット・ストリングで HH24 の代わりに HH12 が指定されていた場合は、結果が異なります。1999-12-31 23:59:591999-12-31 11:59:59
例: タイム・スタンプから可変長文字
- 変数 TMSTAMP が TIMESTAMP として定義されており、2007-03-09-14.07.38.123456 という値があるとします。以下の各例では、いくつかの関数の呼び出しと結果のストリング値が示されています。
各ケースの結果のデータ・タイプは VARCHAR(255) です。
Function invocation Result ------------------- ------ VARCHAR_FORMAT(TMSTAMP,'YYYYMMDDHHMISSFF3') 20070309020738123 VARCHAR_FORMAT(TMSTAMP,'YYYYMMDDHH24MISS') 20070309140738 VARCHAR_FORMAT(TMSTAMP,'YYYYMMDDHHMI') 200703090207 VARCHAR_FORMAT(TMSTAMP,'DD/MM/YY') 09/03/07 VARCHAR_FORMAT(TMSTAMP,'MM-DD-YYYY') 03-09-2007 VARCHAR_FORMAT(TMSTAMP,'J') 2454169 VARCHAR_FORMAT(TMSTAMP,'Q') 1 VARCHAR_FORMAT(TMSTAMP,'W') 2 VARCHAR_FORMAT(TMSTAMP,'IW') 10 VARCHAR_FORMAT(TMSTAMP,'WW') 10 VARCHAR_FORMAT(TMSTAMP,'Month') March VARCHAR_FORMAT(TMSTAMP,'MONTH') MARCH VARCHAR_FORMAT(TMSTAMP,'MON') MAR
例: タイム・スタンプから可変長文字
- 変数 DTE が DATE として定義されており、その値が「2007-03-09」であるとします。以下の各例では、いくつかの関数の呼び出しと結果のストリング値が示されています。
各ケースの結果のデータ・タイプは VARCHAR(255) です。
Function invocation Result ------------------- ------ VARCHAR_FORMAT(DTE,'YYYYMMDD') 20070309 VARCHAR_FORMAT(DTE,'YYYYMMDDHH24MISS') 20070309000000
例: タイム・スタンプから可変長文字
- タイム・スタンプの指定したストリング表現の時間をフォーマットします。
この SELECT ステートメントは以下の値を戻します。SELECT VARCHAR_FORMAT(TIMESTAMP('1979-04-07-14.00.00.000000'), 'HH'), VARCHAR_FORMAT(TIMESTAMP('1979-04-07-14.00.00.000000'), 'HH12') VARCHAR_FORMAT(TIMESTAMP('1979-04-07-14.00.00.000000'), 'HH24'), VARCHAR_FORMAT(TIMESTAMP('2000-01-01-00.00.00.000000'), 'HH'), VARCHAR_FORMAT(TIMESTAMP('2000-01-01-12.00.00.000000'), 'HH'), VARCHAR_FORMAT(TIMESTAMP('2000-01-01-24.00.00.000000'), 'HH'), VARCHAR_FORMAT(TIMESTAMP('2000-01-01-00.00.00.000000'), 'HH12'), VARCHAR_FORMAT(TIMESTAMP('2000-01-01-12.00.00.000000'), 'HH12'), VARCHAR_FORMAT(TIMESTAMP('2000-01-01-24.00.00.000000'), 'HH12'), VARCHAR_FORMAT(TIMESTAMP('2000-01-01-00.00.00.000000'), 'HH24'), VARCHAR_FORMAT(TIMESTAMP('2000-01-01-12.00.00.000000'), 'HH24'), VARCHAR_FORMAT(TIMESTAMP('2000-01-01-24.00.00.000000'), 'HH24') FROM SYSIBM.SYSDUMMY1;'02' '02' '14' '12' '12' '12' '12' '12' '12' '00' '12' '24'
例: 数値から可変長文字
- 変数 POSNUM および NEGNUM が DECFLOAT(34) として定義され、それぞれ値 '1234.56' および '-1234.56' を持っているとします。
以下の各例では、いくつかの関数の呼び出しと結果のストリング値が示されています。
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'