TIMESTAMPDIFF
Synopsis
{fn TIMESTAMPDIFF(interval-type,startdate,enddate)}
引数
interval-type | 返り値が表示される時刻/日付間隔のタイプ。 |
startdate | タイムスタンプ値式。 |
enddate | startdate と比較されるタイムスタンプ値式。 |
概要
TIMESTAMPDIFF 関数は、指定された日付部分の間隔 (秒、日、週など) における指定された 2 つのタイムスタンプ間の差異を返します (つまり、一方のタイムスタンプからもう一方を引きます)。返される値は、2 つのタイムスタンプ間のこれらの間隔数を示す INTEGER です (enddate が startdate より前の場合、TIMESTAMPDIFF は負の INTEGER 値を返します)。
startdate と enddate はタイムスタンプです。これらのタイムスタンプは、%Library.TimeStampOpens in a new tab データ型形式 (yyyy-mm-dd hh:mm:ss.ffff) です。
interval-type 引数は、以下のタイムスタンプ間隔のいずれかになります。
-
SQL_TSI_FRAC_SECOND
-
SQL_TSI_SECOND
-
SQL_TSI_MINUTE
-
SQL_TSI_HOUR
-
SQL_TSI_DAY
-
SQL_TSI_WEEK
-
SQL_TSI_MONTH
-
SQL_TSI_YEAR
これらのタイムスタンプの間隔は、引用符なしで、または一重引用符や二重引用符で囲んで指定できます、大文字と小文字は区別されません。
TIMESTAMPDIFF と DATEDIFF では四半期 (3 か月の間隔) は処理されません。
TIMESTAMPDIFF は { } 括弧構文による ODBC スカラ関数としてのみ使用できる点に注意してください。同様の日付/時刻の比較の演算は、DATEDIFF 汎用関数を使用して、タイムスタンプで実行できます。
%TimeStamp 形式
startdate 引数または enddate 引数が %Library.TimeStampOpens in a new tab データ型形式 (yyyy-mm-dd hh:mm:ss.ffff) である場合、以下のルールが適用されます。
-
一方のタイムスタンプ式で時刻値のみが指定されており、interval-type で日付間隔 (日、週、月、または年) が指定されている場合、結果の間隔数の計算前に、タイムスタンプの欠けている日付部分は、既定で '1900–01–01' になります。
-
一方のタイムスタンプ式で日付値のみが指定されており、interval-type で時刻間隔 (時、分、秒、秒の小数部) が指定されている場合、結果の間隔数の計算前に、タイムスタンプの欠けている時刻部分は、既定で '00:00:00.000' になります。
-
任意の桁数の精度の秒の小数部を含めることができます。省略してもかまいません。SQL_TSI_FRAC_SECOND は、秒の小数部の差異を 1000 分の 1 秒 (3 桁の精度) 単位の整数として返します。
範囲と値のチェック
TIMESTAMPDIFF は、入力値に対して以下のチェックを実行します。
-
TIMESTAMPDIFF 処理を実行するには、startdate と enddate の指定された部分がすべて有効である必要があります。
-
日付文字列は完全であると同時に、要素数、各要素の桁数、および区切り文字に適切な形式が使用されている必要があります。年は 4 桁で指定される必要があります。無効な日付値を指定すると、SQLCODE -8 エラーになります。
-
日付値は、有効な範囲内にある必要があります。年は 0001 から 9999、月は 1 から 12、日は 1 から 31、時間は 00 から 23、分は 0 から 59、秒は 0 から 59 がそれぞれ有効範囲です。月の日数は、該当月と該当年に合ったものでなければなりません。例えば、日付 '02–29' が有効なのは、指定された年がうるう年の場合のみです。無効な日付値を指定すると、SQLCODE -8 エラーになります。
-
10 よりも小さい日付値 (月および日) の先頭の 0 は、記載、省略のどちらでもかまいません。その他の非標準的な整数値は許可されません。例えば、'07' または '7' は有効な日値ですが、'007'、'7.0'、または '7a' は無効です。
-
時刻値は、全体または一部を省略できます。startdate または enddate で不完全な時刻が指定されている場合、指定されていない部分に対して 0 が指定されます。
-
10 よりも小さい時間値の先頭の 0 は記載する必要があります。この先頭の 0 を省略すると、SQLCODE -8 エラーになります。
例
以下の例は、後者のタイムスタンプ (1999-12-20 12:00:00) が、前者のタイムスタンプよりも 7 か月分大きいので、7 を返します。
SELECT {fn TIMESTAMPDIFF(SQL_TSI_MONTH,
'1999-5-19 00:00:00','1999-12-20 12:00:00')}
以下の例は、後者のタイムスタンプ ('12:00:00') が、前者のタイムスタンプ (02:34:12) よりも 566 分大きいので、566 を返します。
SELECT {fn TIMESTAMPDIFF(SQL_TSI_MINUTE,'02:34:12','12:00:00')}
以下の例は、後者のタイムスタンプが前者のタイムスタンプよりも値が 1 日 (1440 分) 小さいので -1440 を返します。
SELECT {fn TIMESTAMPDIFF(SQL_TSI_MINUTE,'2017-04-06','2017-04-05')}