TIMESTAMPADD
Synopsis
{fn TIMESTAMPADD(interval-type,integer-exp,timestamp-exp)}
引数
| interval-type | キーワードとして指定される、integer-exp が表す時刻/日付間隔のタイプ。 |
| integer-exp | timestamp-exp に追加される整数値式。 |
| timestamp-exp | タイムスタンプ値式。integer-exp の値によって増加します。 |
概要
TIMESTAMPADD 関数は、指定された日付部分を指定された単位数でインクリメントすることで、日付/時刻式を変更します。例えば、interval-type が SQL_TSI_MONTH で、integer-exp が 5 の場合は、TIMESTAMPADD は timestamp-exp に 5 か月をインクリメントします。また、integer-exp に負の整数を指定して、日付部分をデクリメントすることもできます。
TIMESTAMPADD は、入力 timestamp-exp の %Library.TimeStampOpens in a new tab データ型形式 (yyyy-mm-dd hh:mm:ss.ffff) と同じデータ型のタイムスタンプを返します。
TIMESTAMPADD は { } 括弧構文による ODBC スカラ関数としてのみ使用できる点に注意してください。
同様の日付/時刻変更の演算は、DATEADD 汎用関数を使用して、タイムスタンプで実行できます。
間隔のタイプ
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_QUARTER
-
SQL_TSI_YEAR
これらのタイムスタンプの間隔は、引用符なしで、または一重引用符や二重引用符で囲んで指定できます、大文字と小文字は区別されません。
タイムスタンプ間隔をインクリメントまたはデクリメントすると、他の間隔も適切に変更されます。例えば、時間のインクリメント結果が午前 0 時を超える場合、自動的に日がインクリメントされます。同様に、順次、月などがインクリメントされます。TIMESTAMPADD は、各月の日数やうるう年を考慮に入れて、常に有効な日付を返します。例えば、1 月 31 日に 1 か月をインクリメントすると 2 月 28 日 (該当月の有効な最終日付) が返されますが、指定された年がうるう年の場合は 2 月 29 日が返されます。
3 桁の精度の秒の小数部でインクリメントあるいはデクリメントできます。1000 分の 1 秒単位の整数として秒の小数部を指定します (001 から 999)。
DATEADD と TIMESTAMPADD では四半期 (3 か月の間隔) が処理されます。DATEDIFF と TIMESTAMPDIFF では四半期は処理されません。
%TimeStamp 形式
timestamp-exp 引数が %Library.TimeStampOpens in a new tab データ型形式 (yyyy-mm-dd hh:mm:ss.ffff) である場合、以下のルールが適用されます。
-
timestamp-exp で時刻値のみが指定されている場合、結果のタイムスタンプの計算前に、timestamp-exp の日付部分は '1900–01–01' に設定されます。
-
timestamp-exp が日付値のみを指定する場合、timestamp-exp の時刻部分は結果のタイムスタンプが計算される前は '00:00:00' に設定されます。
-
timestamp-exp に秒の小数部を含めても省略してもかまいません。timestamp-exp には任意の桁数の精度を含めることができますが、interval-type SQL_TSI_FRAC_SECOND では正確に 3 桁の精度が指定されます。3 桁以外の SQL_TSI_FRAC_SECOND を指定しようとすると、予期しない結果が発生する可能性があります。
範囲と値のチェック
TIMESTAMPADD は、%Library.TimeStampOpens in a new tab 入力値に対して以下のチェックを実行します。
-
TIMESTAMPADD 処理を実行するには、timestamp-exp の指定された部分がすべて有効である必要があります。
-
日付文字列は完全であると同時に、要素数、各要素の桁数、および区切り文字に適切な形式が使用されている必要があります。年は 4 桁で指定される必要があります。無効な日付値を指定すると、SQLCODE -400 エラーになります。
-
日付値は、有効な範囲内にある必要があります。年は 1841 から 9999、月は 1 から 12、日は 1 から 31、時間は 00 から 23、分は 0 から 59、秒は 0 から 59 がそれぞれ有効範囲です。月の日数は、該当月と該当年に合ったものでなければなりません。例えば、日付 '02–29' が有効なのは、指定された年がうるう年の場合のみです。無効な日付値を指定すると、SQLCODE -400 エラーになります。
-
インクリメント (またはデクリメント) 結果として返される年は、1841 から 9999 までの範囲内にある必要があります。この範囲を超えると、<null> が返されます。
-
10 よりも小さい日付値の先頭のゼロは、記載、省略のどちらでもかまいません。その他の非標準的な整数値は許可されません。例えば、'07' または '7' は有効な日値ですが、'007'、'7.0'、または '7a' は無効です。10 よりも小さい日付値は、常に先頭の 0 がついた状態で返されます。
-
時刻値は、全体または一部を省略できます。timestamp-exp で不完全な時刻が指定されている場合、指定されていない部分に対して 0 が指定されます。
-
10 よりも小さい時間値の先頭の 0 は記載する必要があります。この先頭の 0 を省略すると、SQLCODE -400 エラーになります。
例
以下の例は、元のタイムスタンプに 1 週間を加算します。
SELECT {fn TIMESTAMPADD(SQL_TSI_WEEK,1,'2003-12-20 12:00:00')}1 週の加算は 7 日の加算になるので、上記の例は 2003-12-27 12:00:00 を返します。
以下の例は、元のタイムスタンプに 5 か月を加算します。
SELECT {fn TIMESTAMPADD(SQL_TSI_MONTH,5,'1999-12-20 12:00:00')}この例は 5 か月を加算すると年がインクリメントされるので、2000-05-20 12:00:00 を返します。
以下の例も、元のタイムスタンプに 5 か月を加算します。
SELECT {fn TIMESTAMPADD(SQL_TSI_MONTH,5,'1999-01-31 12:00:00')}上記の例は 1999-06-30 12:00:00 を返します。この TIMESTAMPADD は、月だけでなく日の値も変更します。これは単純に月をインクリメントすると、無効な日付の 6 月 31 日となるためです。
以下の例は、元のタイムスタンプに 45 分をインクリメントします。
SELECT {fn TIMESTAMPADD(SQL_TSI_MINUTE,45,'1999-12-20 00:00:00')}上記の例は 1999-12-20 00:45:00 を返します。
以下の例は、元のタイムスタンプに 45 分をデクリメントします。
SELECT {fn TIMESTAMPADD(SQL_TSI_MINUTE,-45,'1999-12-20 00:00:00')}上記の例は 1999-12-19 23:15:00 を返します。この場合は、時刻をデクリメントすると、日もデクリメントされます。
