TIMESTAMP_FORMAT スカラー関数

スキーマは SYSIBM です。

ストリング式

この式は 組み込み CHAR または VARCHAR の データ・タイプの値を戻す必要があります。 Unicode データベースでは、指定した引数が GRAPHIC または VARGRAPHIC のデータ・タイプであると、まず VARCHAR に変換されてから、関数が評価されます。 string-expression には、format-string で指定したフォーマットに対応するタイム・スタンプの各構成要素が含まれている必要があります。

フォーマット・ストリング

この式は 組み込み CHAR または VARCHAR の データ・タイプの値を戻す必要があります。 Unicode データベースでは、指定した引数が GRAPHIC または VARGRAPHIC のデータ・タイプであると、まず VARCHAR に変換されてから、関数が評価されます。 実際の長さは、255 バイト以下でなければなりません (SQLSTATE 22007)。 値は、 string-expression がどのように解釈され、タイム・スタンプ値に変換されるかを示すテンプレートです。

有効な format-string には、少なくとも 1 つのフォーマット・エレメントが含まれている必要があり、タイム・スタンプのどのコンポーネントについても複数の指定が含まれていてはなりません。また、 表 1 に特に記載がない限り、フォーマット・エレメントの任意の組み合わせを含めることができます (SQLSTATE 22007)。 例えば、format-string には YY と YYYY の両方を含めることはできません。これは、それらが string-expression の年の構成要素を解釈するためにともに使用されてしまうためです。 下の表を参照して、どのフォーマット・エレメントを同時に指定できないかを確認してください。 2 つのフォーマット・エレメントは、オプションで以下の 1 つ以上の区切り文字で分離することができます。

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

区切り文字は format-string の始めまたは終わりにも指定できます。 これらの区切り文字は、フォーマット・ストリングで任意に組み合わせて使用できます (例えば、'YYYY/MM-DD HH:MM.SS')。 string-expression に指定された分離文字は、コンポーネントを分離するために使用され、 format-stringに指定された分離文字と一致する必要はありません。

表 1. TIMESTAMP_FORMAT 関数のフォーマット・エレメント

フォーマット・エレメント	タイム・スタンプの関連する構成要素	説明
AM または PM	時間	ピリオドが付かない午前/午後の指定子。 このフォーマット・エレメントは、locale-name が指定された場合、それによって決まります。 ロケール名が指定されなかった場合、このフォーマット・エレメントは特殊レジスター CURRENT LOCALE LC_TIME の値によって決まります。
A.M. または P.M.	時間	ピリオドが付いた午前/午後の指定子。 このフォーマット・エレメントは、正確なストリング A.M. または P.M. を使用し、有効なロケール名に依存しません。
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 は、string-expression 内に予想される桁数の指定に使用します。 n の有効値は、先行ゼロの付かない 1 から 12 です。 FF を指定することは、FF6 を指定することと同等です。 FF フォーマット・エレメントに対応する string-expression 内の構成要素の後に区切り文字が続いている場合、またはそれが最後の構成要素である場合、小数秒の桁数はフォーマット・エレメントで指定した桁数よりも少ないことがあります。 この場合は、指定した桁数の右側に数字のゼロが埋め込まれます。
HH	時間	HH の動作は HH12 と同様です。
HH12	時間	12 時間形式の時 (01-12)。 AM がデフォルトの午前/午後の指定子です。
HH24	時間	24 時間形式の時 (00-24)。
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 の値に依存します。
NNNNNN	マイクロ秒	マイクロ秒 (000000-999999)。 FF6 と同様。
RR	year	調整済み年の最後の 2 桁 (00-99)。
RRRR	year	4 桁の調整済み年 (0000-9999)。
SS	秒	秒 (00-59)。
SSSSS	時、分、および秒	直近の午前 0 時からの秒数 (00000-86400)。
Y	year	年の最後の 1 桁 (0-9)。 現在の年の最初の 3 桁が、完全な 4 桁の年の判別に使用されます。
YY	year	年の最後の 2 桁 (00-99)。 現在の年の最初の 2 桁が、完全な 4 桁の年の判別に使用されます。
YYY	year	年の最後の 3 桁 (000-999)。 現在の年の最初の桁が、完全な 4 桁の年の判別に使用されます。
YYYY	year	4 桁の年 (0000-9999)。

注: 表 1 のフォーマット要素は、以下を除き、大/小文字の区別がありません。

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

DAY、Day、day、DY、Dy、dy、および D のフォーマット・エレメントは結果のタイム・スタンプのいずれかの構成要素に提供されません。 ただし、これらのフォーマット・エレメントのいずれかに指定した値は、結果のタイム・スタンプの年、月、および日の構成要素の組み合わせに適切でなければなりません (SQLSTATE 22007)。 例えば、'en_US' という値を locale-name に使用した場合、string-expression に対する 'Monday 2008-10-06' という値は 'Day YYYY-MM-DD' という値には妥当です。 しかし、string-expression への 'Tuesday 2008-10-06' という値は同じ format-string ではエラーになります。

RR と RRRR の各フォーマット・エレメントは、次の表に従って現在の年の左端の 2 桁に基づく 2 桁の値または 4 桁の値を生成するために、入力された値を調整することによって年の指定の解釈方法を変更するために使用することができます。

現在の年の最後の 2 桁	string-expression 内の 2 桁の年	タイム・スタンプの年の構成要素の最初の 2 桁
00-50	00-49	現在の年の最初の 2 桁
51-99	00-49	現在の年 + 1 の最初の 2 桁
00-50	50-99	現在の年 - 1 の最初の 2 桁
51-99	50-99	現在の年の最初の 2 桁

例えば、現在の年が 2007 の場合、フォーマット 'RR' の '86' は 1986 を意味しますが、現在の年が 2052 の場合は 2086 を意味します。

format-string にタイム・スタンプの以下の構成要素の 1 つに対してフォーマット・エレメントが含まれていない場合は、以下のデフォルトが使用されます。

タイム・スタンプの構成要素	デフォルト
年	現在の年、4 桁
月	現在の月、2 桁
日	01 (現在の月の最初の日)
時	00
分	00
第 2 版	00
小数秒	結果のタイム・スタンプの精度に一致するゼロの数

format-string 内の対応するフォーマット・エレメントに有効数字桁数の最大数がないタイム・スタンプ値 (つまり、月、日、時、分、秒) のすべての構成要素に先行ゼロを指定できます。

タイム・スタンプの構成要素 (年、月、日、時、分、秒など) を表す string-expression のサブストリングには、対応するフォーマット・エレメントで指示されたタイム・スタンプのその構成要素の最大桁数より少ない桁数を含めることができます。 入力のない桁はデフォルトのゼロになります。 例えば、'YYYY-MM-DD HH24:MI:SS' の format-string を持つ場合、'999-3-9 5:7:2' の入力値では '0999-03-09 05:07:02' と同じ結果が生成されます。

format-string が指定されないと、string-expression は、 特殊レジスター CURRENT LOCALE LC_TIME の値に基づくデフォルトのフォーマットを使用して解釈されます。

精度定数 (precision-constant)

結果のタイム・スタンプの精度を指定する整数定数。 値の範囲は 0 から 12 です。 指定しない場合、タイム・スタンプの精度はデフォルトの 6 になります。

ロケール名

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

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

locale-name の値は大/小文字の区別がなく、有効なロケールでなければなりません (SQLSTATE 42815)。

有効なロケールとその命名については、 SQL および XQuery のロケール名を参照してください。

locale-name が指定されないと、 特殊レジスター CURRENT LOCALE LC_TIME の値が使用されます。

この関数の結果は TIMESTAMP 精度定数 に基づく精度でになります。 引数の最初の 2 つのいずれかが NULL 値になる可能性がある場合、結果も NULL 値になる可能性があります。引数の最初の 2 つのいずれかが NULL 値の場合、その結果は NULL 値です。