ADD_YEARS スカラー関数

ADD_YEARS 関数は、最初の引数に指定年数を足した日時値を戻します。

スキーマは SYSIBM です。

expression: 開始日付を指定する式。式は DATE、TIMESTAMP、CHAR、または VARCHAR データ・タイプの値を戻す必要があります。 Unicode データベースでは、式は GRAPHIC または VARGRAPHIC のデータ・タイプにすることもできます。 CHAR、VARCHAR、GRAPHIC、および VARGRAPHIC は、暗黙的キャストを介してサポートされます。 expression が CHAR、VARCHAR、GRAPHIC、または VARGRAPHIC のデータ・タイプである場合は、TIMESTAMP スカラー関数で使用できる有効なストリングでなければなりません。
数値式 (numeric-expression): expression で指定した開始日に加算する年数を指定する式。式は組み込み数値、CHAR、または VARCHAR データ・タイプの値を戻す必要があります。 Unicode データベースでは、式は GRAPHIC または VARGRAPHIC のデータ・タイプにすることもできます。 CHAR、VARCHAR、GRAPHIC、および VARGRAPHIC は、暗黙的キャストを介してサポートされます。 INTEGER でない式は、関数の評価の前に INTEGER にキャストされます。負の数値を使用することで、年数を減算することができます。

この関数の結果は、expression がタイム・スタンプの場合は expression と同じ精度のタイム・スタンプになります。そうでない場合、この関数の結果は日付になります。引数のいずれかが NULL になる可能性がある場合、結果も NULL になる可能性があります。引数のいずれかが NULL の場合、その結果は NULL 値です。

結果がうるう年の 2 月 29 日になる場合、日が 28 に変更され、SQLCA の警告標識が日付調整の発生を示すように設定されます。

例

今日が 2007 年 1 月 31 日であるとします。ホスト変数 ADD_YEAR に、今日に 1 年を足した値を設定します。
```
   SET :ADD_YEAR = ADD_YEARS(CURRENT_DATE, 1)
```
ホスト変数 ADD_YEAR には、2008-01-31 を表す値が設定されます。
DATE が、1965 年 7 月 27 日の値を設定されたホスト変数であるとします。ホスト変数 ADD_YEAR に、この日に 3 年を足した値を設定します。
```
   SET :ADD_YEAR = ADD_YEARS(:DATE,3)
```
ホスト変数 ADD_YEAR には、この日に 3 年を足した 1968-07-27 を表す値が設定されます。
ADD_YEARS 関数と日時算術計算のどちらを使用しても、同じ結果になります。以下の例でこれを示します。
```
   SET :DATEHV = DATE('2008-2-29') + 4 YEARS
   SET :DATEHV = ADD_YEARS('2008-2-29', 4)
```
どちらの場合も、ホスト変数 DATEHV には値 '2012-02-29' が設定されます。
今度は、同じ例で 3 年を加算します。
```
   SET :DATEHV = DATE('2008-2-29') + 3 YEARS
   SET :DATEHV = ADD_YEARS('2008-2-29', 3)
```
どちらの場合も、ホスト変数 DATEHV には値 '2011-02-28' が設定されます。
DATE が、1965 年 7 月 27 日の値を設定されたホスト変数であるとします。ホスト変数 ADD_YEAR に、この日から 3 年を引いた値を設定します。
```
   SET :ADD_YEAR = ADD_YEARS(:DATE,-3)
```
ホスト変数 ADD_YEAR には、1965 年 7 月 27 日から 3 年を引いた 1962-07-27 を表す値が設定されます。