DATEPART

日付/時刻式の指定された部分の値を表す整数を返す、日付/時刻関数です。

Synopsis

DATEPART(datepart,date-expression)

引数

datepart	返す日付または時刻の情報のタイプ。日付または時刻の部分の名前 (または省略形)。この名前は大文字でも小文字でも指定できます。引用符で囲んでも囲まなくてもかまいません。datepart はリテラルまたはホスト変数として指定できます。
date-expression	datepart 値を返す元となる日付、時刻、またはタイムスタンプ式です。date-expression には、タイプ datepart の値を含める必要があります。

概要

DATEPART 関数は、指定された日付/時刻式についての datepart 情報を整数として返します。この情報を文字列として返すには、DATENAME を使用します。datepart 値が sqltimestamp (または sts) の場合は、後述のとおり、DATEPART はデータ型 TIMESTAMP または INTEGER のどちらかを返すことができます。

DATEPART が返すのは、date-expression の 1 要素のみの値です。複数の日付部分を含む文字列を返すには、TO_DATE を使用します。

この関数は、ObjectScript から DATEPART()Opens in a new tab メソッド呼び出しを使用して呼び出すこともできます。

$SYSTEM.SQL.DATEPART(datepart,date-expression)

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

Datepart 引数

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

日付部分	省略形	返り値
year	yyyy, yy	1840-9999
quarter	qq, q	1-4
month	mm, m	1-12
week	wk, ww	1-53
weekday	dw	1-7 (Sunday、...、Saturday)
dayofyear	dy, y	1-366
day	dd, d	1-31
hour	hh	0-23
minute	mi, n	0-59
second	ss, s	0-59
millisecond	ms	0-999 (3 桁の精度)
sqltimestamp	sts	SQL_TIMESTAMP ： yyyy-mm-dd hh:mm:ss

このテーブルに示されている返り値は、それぞれの日付部分の既定値です。これらの日付部分のいくつかの返り値は、各種日付/時刻オプションで SET OPTION コマンドを使用することで変更できます。

week ： Caché は、Caché の既定のアルゴリズムと ISO 8601 標準アルゴリズムのいずれかを使用して、特定の日付がその年の何週目にあたるかを判定するように構成できます。詳細は、"WEEK" 関数を参照してください。

weekday ： Caché の曜日に関する既定では、日曜日を週の最初の曜日として指定します (weekday=1)。ただし、週の最初の曜日を別の値に構成したり、月曜日を週の最初の曜日として指定する ISO 8601 標準を適用することができます。詳細は、"DAYOFWEEK" 関数を参照してください。ObjectScript の $ZDATE および $ZDATETIME 関数は、0 から 6 まで (1 から 7 ではない) の数値で曜日をカウントします。

second ： date-expression に秒の小数部が含まれている場合、Caché は整数コンポーネントとして整数秒、および小数コンポーネントとして秒の小数部を含む 10 進数として second を返します。精度は切り捨てられません。

millisecond ： Caché は、3 桁の精度の小数部を返します。末尾のゼロは削除されます。date-expression に 3 桁より高い精度の小数部がある場合、Caché はそれを 3 桁に切り捨てます。

sqltimestamp ： Caché は、入力データをタイムスタンプ形式に変換し、必要に応じて、時間要素のためにゼロ値を指定します。データ型 TIMESTAMP またはデータ型 INTEGER のどちらかを返すことができます (以下を参照)。sqltimestamp (略名 sts) datepart 値は、DATEPART と一緒にのみ使用します。この値を他のコンテキストで使用しようとしないでください。

datepart は、引用符で囲んだ文字列としてや、引用符なしで、または引用符で囲んだ文字列を括弧で囲んで指定できます。どう指定されているかに関係なく、datepart ではリテラル置換は実行されません。リテラル置換は date-expression で実行されます。datepart のすべての値は、sqltimestamp (または sts) を除き、データ型 INTEGER の値を返します。sqltimestamp は、その値をデータ型 TIMESTAMP の文字列として返します。

日付の入力形式

date-expression 引数は、以下のいずれかの形式になります。

Caché %Date 論理値 (+$H)
Caché %TimeStamp (%Library.TimeStampOpens in a new tab) 論理値 (YYYY-MM-DD HH:MM:SS.FFF)。ODBC 形式とも呼ばれます。
Caché %String (互換性のある) 値

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

99999,99999 ($H 形式)
Sybase/SQL-Server-date Sybase/SQL-Server-time
Sybase/SQL-Server-time Sybase/SQL-Server-date
Sybase/SQL-Server-date (既定時刻は 00:00:00)
Sybase/SQL-Server-time (既定日付は 01/01/1900)

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 は、スラッシュ (/)、ハイフン (-)、またはピリオド (.) です。

年が 2 桁で表示される場合、Caché はスライディング・ウィンドウを確認して日付を解釈します。スライディング・ウィンドウのシステムの既定は、%DATE ユーティリティで設定できます。これは、“InterSystems のドキュメントの使用法” の “旧ドキュメント” の章でのみ説明されています。現在のプロセスのスライディング・ウィンドウの設定の詳細は、ObjectScript の $ZDATE、$ZDATEH、$ZDATETIME、および $ZDATETIMEH の各関数のドキュメントを参照してください。

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

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

date-expression で時刻形式が設定されているが、日付形式が指定されていない場合、既定で DATENAME は 2 (月曜日) の曜日値を持つ日付 1900–01–01 になります。

sqltimestamp では、時刻は 24 時間制で返されます。秒の小数部は切り捨てられます。

無効な引数のエラー・コード

無効な datepart オプションを指定した場合、DATEPART では SQLCODE -8 エラー・コードが生成され、%msg "'badopt' は認識されている DATEPART オプションではありません" が表示されます。

無効な date-expression 値 (アルファベット・テキスト文字列など) を指定した場合、DATEPART では SQLCODE -400 エラー・コードが生成され、%msg "Datepart() 関数への入力が無効です： DATEPART('year','badval')" が表示されます。検証に合格できない date-expression を指定した場合 (下記参照)、DATEPART では SQLCODE -400 エラー・コードが生成され、%msg "予期しないエラーが発生しました： <ILLEGAL VALUE>datepart" が表示されます。

範囲と値のチェック

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

有効な date-expression は、日付文字列 (yyyy-mm-dd)、時刻文字列 (hh:mm:ss)、または日付/時刻文字列 (yyyy-mm-dd hh:mm:ss) で構成されます。日付と時刻の両方が指定されている場合は、両方が有効でなければなりません。例えば、時刻文字列が指定されていない場合は年数値を返すことができますが、無効な時刻文字列が指定されている場合は年数値を返すことができません。
日付文字列は完全であると同時に、要素数、各要素の桁数、および区切り文字に適切な形式が使用されている必要があります。例えば、日の値が省略されている場合、年数値を返すことはできません。年は 4 桁で指定される必要があります。
時刻文字列は、適切な区切り文字で適切にフォーマットされている必要があります。時刻要素の値はゼロの場合もあるため、1 つ以上の時刻要素を省略でき (区切り文字はそのまま残す場合と省略する場合がある)、これらの要素はゼロ値として返されます。したがって、'hh:mm:ss'、'hh:mm:'、'hh:mm'、'hh::ss'、'hh::'、'hh'、および ':::' は、すべて有効です。時間 (Hour) 要素を省略するには、date-expression に文字列の日付部分がないことと、少なくとも 1 つの区切り文字 (:) があることが必要です。
日付/時刻値は、有効な範囲内にある必要があります。年は 1841 から 9999、月は 1 から 12、日は 1 から 31、時間は 0 から 23、分は 0 から 59、秒は 0 から 59 がそれぞれ有効範囲です。
月の日数は、該当月と該当年に合ったものでなければなりません。例えば、日付 '02–29' が有効なのは、指定された年がうるう年の場合のみです。
日付値または時刻値が 10 よりも小さい場合、そのほとんどの先頭のゼロは、記載、省略のどちらでもかまいません。ただし、10 よりも小さい時間 (Hour) 値が日付/時刻文字列の一部の場合は、その先頭にゼロを付ける必要があります。その他の非標準的な整数値は許可されません。例えば、'07' または '7' は有効な日値ですが、'007'、'7.0'、または '7a' は無効です。
date-expression で時刻形式が指定されているが、日付形式が指定されていない場合、DATEPART は時刻コンポーネント値の範囲検証を実行しません。

例

以下の例では、各 DATEPART は、日付時刻文字列の年の部分 (この場合は、2004) を整数として返します。date-expression はさまざまな形式で指定でき、datepart は正式な名前または省略形で指定できることに注意してください。引用符で囲んでも囲まなくてもかまいません。

SELECT DATEPART('yy','2004-12-20 12:00:00') AS YearDTS,
       DATEPART('year','2004-02-25') AS YearDS,
       DATEPART(YYYY,'02/25/2004') AS YearD,
       DATEPART(YEAR,59590) AS YearHD,
       DATEPART('Year','59590,23456') AS YearHDT

以下の例では、$HOROLOG 値に基づいて、現在の年と四半期が返されます。

SELECT DATEPART('yyyy',$HOROLOG) AS Year,DATEPART('q',$HOROLOG) AS Quarter

以下の埋め込み SQL の例では、ホスト変数を使用して DATEPART 引数の値を指定します。

  SET x="year"
  SET datein="2004-02-25"
  &sql(SELECT DATEPART(:x,:datein)
       INTO :partout)
  WRITE "the ",x," is ",partout

以下の例では、曜日で並べ替えて、Sample.Person テーブルから誕生日の曜日が返されます。

SELECT Name,DOB,DATEPART('weekday',DOB) AS bday
FROM Sample.Person
ORDER BY bday,DOB

以下の例では、各 DATEPART は、date-expression 文字列の分部分として 20 を返します。

SELECT DATEPART('mi','1999-1-20 12:20:07') AS Minutes,
       DATEPART('n','1999-02-20 10:20:') AS Minutes,
       DATEPART(MINUTE,'1999-02-20 10:20') AS Minutes

以下の例では、各 DATEPART は、date-expression 文字列の秒部分として 0 を返します。

SELECT DATEPART('ss','1999-02-20 03:20:') AS Seconds,
       DATEPART('S','1999-02-20 03:20') AS Seconds,
       DATEPART('Second','1999-02-20') AS Seconds

以下の例では、TIMESTAMP データ型として完全な SQL タイムスタンプが返されます。DATEPART は、欠けている時間情報を埋めて、タイムスタンプ '2004-02-25 00:00:00' を返します。

SELECT DATEPART(sqltimestamp,'2/25/2004') AS DTStamp

以下の例では、INTEGER データ型として完全な SQL タイムスタンプが返されます。DATEPART は、欠けている時間情報を埋めて、タイムスタンプ '2004-02-25 00:00:00' を返します。

SELECT DATEPART('sqltimestamp','2/25/2004') AS DTStampAsInt

以下の例は、日付と時刻を $HOROLOG 形式で指定して、タイムスタンプの '2004-02-25 06:30:56' を返します。

SELECT DATEPART(sqltimestamp,'59590,23456') AS DTStamp

以下の例では、DATEPART を使用するサブクエリを使用して、誕生日がうるう年の日付 (2 月 29 日) である人が返されます。

SELECT Name,DOB
FROM (SELECT Name,DOB,DATEPART('dd',DOB) AS DayNum,DATEPART('mm',DOB) AS Month FROM Sample.Person)
WHERE Month=2 AND DayNum=29