DATEADD

日付部分 (時刻や日など) の数値を、指定されたタイムスタンプに加算することによって計算された日付を返す、汎用日付/時刻関数です。

DATEADD(datepart,integer-exp,date-exp)

datepart	日付または時刻部分の名前 (または省略形)。引用符付き文字列として指定されます。
integer-exp	すべての数値タイプの数値式。値は、整数 (正または負) に切り捨てられます。この値は datepart の数を表し、date-exp に加算または減算されます。
date-exp	変更される日付/時刻式。これには日付文字列、タイムスタンプ文字列、または CURRENT_DATE などの関数を指定できます。返される値は常にタイムスタンプです。

DATEADD 関数は、指定された日付部分を指定された単位数でインクリメントすることで、日付/時刻式を変更します。例えば、datepart が 'month' で、integer-exp が 5 の場合は、DATEADD は date-exp に 5 か月をインクリメントします。また、integer-exp に負の整数を指定して、日付部分をデクリメントすることもできます。

計算された日付は、TIMESTAMP として返されます。DATEADD は、常に以下の形式の完全な日付/時刻式を返します。

小数秒を含む date-exp を指定した場合は、返り値にも小数秒が含まれます。date-exp の時刻部分を省略した場合、DATEADD は既定時刻の 00:00:00 を返します。date-exp の日付部分を省略した場合、DATEADD は既定日付の 1900–01–01 を返します。

同様の日付/時刻変更の演算は、TIMESTAMPADD ODBC スカラ関数を使用して実行できます。

以下のメソッド・コールを使用することで、Caché ObjectScript からこの関数を呼び出すこともできます。

$SYSTEM.SQL.DATEADD(datepart,integer-exp,date-exp)

datepart パラメータは、以下の日付/時刻コンポーネントの 1 つで、正式な名前 (日付部分列) または省略形 (省略形列) のいずれかになります。これらの datepart コンポーネント名と省略形では、大文字と小文字は区別されません。

日付部分	省略名	integer-exp が 1 の場合
year	yy	年に 1 をインクリメント。
quarter	qq	月に 3 をインクリメント。
month	mm	月に 1 をインクリメント。
week	wk	日に 7 をインクリメント。
day	dd	日に 1 をインクリメント。
hour	hh	時間に 1 をインクリメント。
minute	mi	分に 1 をインクリメント。
second	ss	秒に 1 をインクリメント。
millisecond	ms	.001 秒をインクリメント。

リテラルとして無効な datepart 値を指定した場合は、SQLCODE -8 エラー・コードが発行されます。一方、ホスト変数として無効な datepart 値を指定した場合は、SQLCODE エラーは発行されず、DATEPART 関数は NULL 値を返します。

日付部分をインクリメントまたはデクリメントすると、他の日付部分も適切に変更されます。例えば、時間のインクリメント結果が午前 0 時を超える場合、自動的に日がインクリメントされます。同様に、順次、月などがインクリメントされます。DATEADD は、各月の日数やうるう年を考慮に入れて、常に有効な日付を返します。例えば、1 月 31 日に 1 か月をインクリメントすると 2 月 28 日 (該当月の有効な最終日付) が返されますが、指定された年がうるう年の場合は 2 月 29 日が返されます。

date-exp パラメータは、以下のいずれかの形式で指定できます。小数秒は指定、省略のどちらでもかまいません。

Caché %String (または互換性) 値は、以下のいずれかの形式になります。

Sybase/SQL-Server-date は、以下の 5 形式のいずれかです。

mmdelimiterdddelimiter[yy]yy
dd Mmm[mm][,][yy]yy
dd [yy]yy Mmm[mm]
yyyy Mmm[mm] dd
yyyy [dd] Mmm[mm]

delimiter は、スラッシュ (/)、ハイフン (-)、またはピリオド (.) です。

Sybase/SQL-Server-time は、以下の 3 形式のいずれかです。

HH:MM[:SS:SSS][{AM|PM}]
HH:MM[:SS.S]
HH['']{AM|PM}

年が 2 桁で表示される場合、%DATE ユーティリティの移動日付ウィンドウが使用され (使用できる場合)、何世紀か判断されます。

DATEADD では、Sybase および Microsoft SQL Server との互換性が提供されています。

DATEADD は、入力値に対して以下のチェックを実行します。値がチェックに失敗した場合は、NULL 文字列が返されます。

以下の例は、指定された日付に 1 週を加算します。

SELECT DISTINCT DATEADD('week',1,'1999-12-20') AS NewDate
FROM Sample.Person

1 週の加算は 7 日の加算になるので、上記の例は 1999-12-27 00:00:00 を返します。この DATEADD では、時刻部分が省略されています。

以下の例は、元のタイムスタンプに 5 か月を加算します。

SELECT DISTINCT DATEADD('mm',5,'1999-12-20 12:00:00') AS NewDate
FROM Sample.Person

5 か月を加算すると年がインクリメントされるので、上記の例は 2000-05-20 12:00:00 を返します。

以下の例も、元のタイムスタンプに 5 か月を加算します。

SELECT DISTINCT DATEADD('mm',5,'1999-01-31 12:00:00') AS NewDate
FROM Sample.Person

上記の例は 1999-06-30 12:00:00 を返します。この DATEADD は、月だけでなく日の値も変更します。これは単純に月をインクリメントすると、無効な日付の 6 月 31 日となるためです。

以下の例は、元のタイムスタンプに 45 分を加算します。

SELECT DISTINCT DATEADD('mi',45,'1999-12-20 12:00:00') AS NewTime
FROM sample.person

上記の例は 1999-12-20 12:45:00 を返します。

以下の例も、元のタイムスタンプに 45 分を加算しますが、この場合は日付もインクリメントされます。

SELECT DISTINCT DATEADD('mi',45,'1999-12-20 23:30:00') AS NewTime
FROM sample.person

上記の例は 1999-12-21 00:15:00 を返します。

以下の例は、元のタイムスタンプに 45 分をデクリメントします。

SELECT DISTINCT DATEADD('mi',-45,'1999-12-20 12:00:00') AS NewTime
FROM Sample.Person

上記の例は 1999-12-20 11:15:00 を返します。

以下の例は、現在の日付に 60 日を加算し、結果を各月の長さに合わせて調整します。

SELECT DISTINCT DATEADD('dd',60,CURRENT_DATE) AS NewDate
FROM Sample.Person

以下の最初の例は指定された日付に 92 日を加算し、2 番目の例は指定された日付に 1 四半期を加算します。

SELECT DISTINCT DATEADD('dd',92,'1999-12-20') AS NewDate
FROM sample.person

SELECT DISTINCT DATEADD('qq',1,'1999-12-20') AS NewDate
FROM sample.person

最初の例は 2000-03-21 00:00:00 を返し、2 番目の例は 2000-03-20 00:00:00 を返します。1 四半期をインクリメントすると、月部分に 3 がインクリメントされ、必要に応じて年部分がインクリメントされます。また、結果月の最大日数に合わせて修正されます。

上記の例は、すべて datepart に省略形を使用しています。しかし、datepart には、以下の例のように正式な名前を指定することもできます。

SELECT DISTINCT DATEADD('day',92,'1999-12-20') AS NewDate
FROM sample.person