TO_POSIXTIME (SQL)

構文

TO_POSIXTIME(date_string[,format])

説明

TO_POSIXTIME 関数は、さまざまな形式の日付/時刻文字列をデータ型 %Library.PosixTimeOpens in a new tab の %PosixTime タイムスタンプに変換します。TO_POSIXTIME は、64 ビットの符号付き整数としてエンコードされた 1970-01-01 00:00:00 の任意の開始ポイントからの経過秒数に基づいて計算された値として %PosixTime タイムスタンプを返します。この日付からの実際の経過秒数 (および秒の小数部) は、UNIX® タイムスタンプ (数値) です。 InterSystems IRIS は、UNIX® タイムスタンプをエンコードして、%PosixTime タイムスタンプを生成します。%PosixTime タイムスタンプ値はエンコードされるため、1970-01-01 00:00:00 は 1152921504606846976 として示されます。1970-01-01 00:00:00 より前の日付は、負の整数値で示されます。詳細は、"%PosixTime データ型" を参照してください。

TO_POSIXTIME ではタイムゾーンは変換されません。ローカル日付とローカル時刻はローカル %PosixTime タイムスタンプに変換され、UTC 日付と UTC 時刻は UTC %PosixTime タイムスタンプに変換されます。

%PosixTime でサポートされる最初の日付は 0001-01-01 00:00:00 で、論理値 -6979664624441081856 を持ちます。サポートされる最後の日付は 9999-12-31 23:59:59.999999 で、論理値 1406323805406846975 を持ちます。 これらの制限は、ODBC 日付形式の表示に関する制限に対応します。%Library.PosixTimeOpens in a new tab の MINVAL パラメータと MAXVAL パラメータを使用することで、これらの値をさらに制限できます。IsValid()Opens in a new tab メソッドを使用することで、数値が有効な %PosixTime 値であるかどうかを判定できます。

%PosixTime 値は、常に小数点以下 6 桁の精度の秒の小数部をエンコードします。%PosixTime の変換前、6 桁未満の精度の date_string は 6 桁になるように 0 が追加され、7 桁以上の精度の date_string は 6 桁に切り捨てられます。

date_string でタイムスタンプのコンポーネントを省略している場合、TO_POSIXTIME では不足コンポーネントを提供します。date_string と format の両方で年が省略されている場合、現在の年が yyyy の既定値として使用されます。date_string でのみ年が省略されている場合、00 が既定値として使用されますが、年の format 要素に従って 4 桁の年に拡張されます。日または月の値が省略されている場合、01 が dd の既定値として使用され、01-01 が mm-dd の既定値として使用されます。不足する時刻コンポーネントの既定値は 00 です。秒の小数部はサポートされていますが、明示的に指定する必要があります。既定では、秒の小数部は指定されません。

TO_POSIXTIME は、2 桁の年から 4 桁の年への変換をサポートしています。TO_POSIXTIME は、12 時間形式の時刻から 24 時間形式の時刻への変換をサポートしています。うるう年の検証も含めて、日付および時刻要素値の範囲の検証機能があります。範囲検証違反がある場合は、SQLCODE -400 エラーが生成されます。

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

$SYSTEM.SQL.Functions.TOPOSIXTIME(date_string,format)

TO_POSIXTIME 関数は、フィールドに既定値を指定するときにデータ定義で使用することができます。以下はその例です。

CREATE TABLE mytest
(ID NUMBER(12,0) NOT NULL,
End_Year DATE DEFAULT TO_POSIXTIME('12-31-2018','MM-DD-YYYY') NOT NULL)

TO_POSIXTIME は、CREATE TABLE 文や ALTER TABLE ADD COLUMN 文で使用できます。このコンテキストでは、date_string にリテラル値のみを使用できます。詳細は、"CREATE TABLE" コマンドを参照してください。

引数

日付/時刻文字列

date_string 引数では、日付/時刻文字列リテラルが指定されます。時刻コンポーネントなしで日付文字列を指定すると、TO_POSIXTIME によって時刻値 00:00:00 が指定されます。日付コンポーネントなしで時刻文字列を指定したときは、TO_POSIXTIME によって現在の年の日付 01–01 (1 月 1 日) が指定されます。

date_string の入力にはどのような種類の日付/時刻文字列でも指定できます。date_string の各文字は、以下の例外を除いて、format 文字列に対応している必要があります。

• 区切り文字のない date_string の場合を除き、先頭のゼロは指定しても省略してもかまいません。

• 年は 2 桁または 4 桁で指定できます。

• 月の省略形 (format MON) は、そのロケールでの月の省略形と一致している必要があります。ロケールによっては、月の省略形は、月の名前の先頭の連続文字でない場合があります。月の省略形では、大文字と小文字は区別されません。

• 月の名前 (format MONTH) は、完全な月名として指定する必要があります。ただし、TO_POSIXTIME では、format MONTH で完全な月名を必要としません。これは完全な月名の最初の文字 (複数可) を受け取り、月のリストからその先頭の文字シーケンスに対応する最初の月を選択します。そのため、英語では、"J" = "January"、"Ju" = "June"、"Jul" = "July" となります。指定されるすべての文字は、完全な月名の連続文字と一致する必要があります。完全な月名を逸脱した文字はチェックされません。例えば、"Fe"、"Febru"、および "FebruaryLeap" はすべて有効な値です。"Febs" は無効な値です。月の名前では、大文字と小文字は区別されません。

• 時刻値は、該当するロケール用に定義されている時刻区切り文字を使用して入力できます。出力タイムスタンプは必ず、ODBC 標準時刻区切り文字のコロン (:) とピリオド (.) で時刻値を表します。時刻要素を省略すると、既定で 00:00:00 が使用されます。

形式

format は、以下の規則に従って指定された 1 つまたは複数の形式要素の文字列です。

• 形式要素では、大文字と小文字は区別されません。

• 形式要素をどのような順序で、またはいくつ使うかについては、たいていの場合制限はありません。

• 形式文字列は、date_string の区切り文字に一致する、英数字でない区切り文字 (スペース、スラッシュ、ハイフンなど) で要素を区切ります。これらの区切り文字は出力文字列には表示されません。出力文字列では標準のタイムスタンプ区切り文字であるハイフン (日付値)、コロン (時刻値)、および秒の小数部がある場合は必要に応じてピリオドが使用されます。この区切り文字の使用は、NLS ロケールに対して定義されている DateSeparator に依存しません。

• 日付形式文字列 MMDDYYYY、DDMMYYYY、YYYYMMDDHHMISS、YYYYMMDDHHMI、YYYYMMDDHH、YYYYMMDD、YYYYDDMM、HHMISS、および HHMI には、区切り文字は必要ありません。不完全な日付形式 YYYYMM も使用でき、DD 値は 01 と見なされます。ただし、このような場合、最後の要素を除くすべての要素 (MM 値と DD 値など) の先頭にゼロを記述する必要があります。

• 有効な形式要素がない format の文字は無視されます。

年間通算日 (DDD 形式)

DDD を使用して、年間通算日 (1 月 1 日から経過した日数) を実際の日付に変換します。形式文字列 DDD YYYY は、整数の日数と 4 桁の年で構成される、対応する date_string と組み合わせる必要があります(2 桁の年は、DDD と共に使用する場合は RR (YY ではない) として指定する必要があります)。形式文字列 DDD の既定は、現在の年となります。経過した日数は、1 ～ 365 の範囲の正の整数である必要があります (YYYY がうるう年の場合は 366)。4 桁の年は、標準の InterSystems IRIS の日付範囲内 (1841 から 9999) で指定する必要があります(年を省略した場合、現在の年が既定値として使用されます)。DDD および年 (YYYY、RRRR、または RR) 形式要素は、任意の順序で指定できます。これらの間の区切り文字は必須です。この区切り文字として空白を使用することができます。以下の例は、この年間通算日の使用法を示しています。

SELECT TO_POSIXTIME('2018:160','YYYY:DDD')

形式文字列に DD と DDD 要素の両方が含まれる場合、DDD 要素が優勢です。以下の例に示すとおり、2008-12-31 00:00:00 ではなく 2008-02-29 00:00:00 が返されます。

SELECT TO_POSIXTIME('2018-12-31-60','YYYY-MM-DD-DDD')

TO_POSIXTIME では、年間通算日に対応する日付式を返すことができます。TO_CHAR では、日付式に対応する年間通算日を返すことができます。

例

以下の埋め込み SQL の例では、現在のローカル日付/時刻を %PosixTime 値に変換しています(format では任意の小数桁数を示すのに "ff" が使用されます。この例では、3 桁の精度になります。%PosixTime は、末尾に 0 を 3 つ追加して、これを 6 桁の精度としてエンコードします)。この例では、次に %Posix LogicalToOdbc()Opens in a new tab メソッドを使用し、精度の末尾の 0 を削除して、この値を ODBC タイムスタンプとして表示しています。

  SET tstime=$ZDATETIME($ZTIMESTAMP,3,1,3)
  WRITE "local datetime in : ",tstime,!
  &sql(SELECT
       TO_POSIXTIME(:tstime,'yyyy-mm-dd hh:mi:ss.ff')
       INTO :ptime)
  IF SQLCODE=0 { 
    WRITE "Posix encoded datetime: ",ptime,!
    SET ODBCout=##class(%PosixTime).LogicalToOdbc(ptime)
    WRITE "local datetime out: ",ODBCout  }
  ELSE { WRITE "SQLCODE error:",SQLCODE }

以下の例は、さまざまな形式で日付文字列を指定します。最初の例では既定の形式を使用しており、それ以外の例では format を指定しています。これらはすべて、date_string をタイムスタンプ値 2018–06–29 00:00:00 に変換します。

SELECT
       TO_POSIXTIME('29 JUN 2018'),
       TO_POSIXTIME('2018 Jun 29','YYYY MON DD'),
       TO_POSIXTIME('JUNE 29, 2018','month dd, YYYY'),
       TO_POSIXTIME('2018***06***29','YYYY***MM***DD'),
       TO_POSIXTIME('06/29/2018','MM/DD/YYYY'),
       TO_POSIXTIME('29/6/2018','DD/MM/YYYY')

以下の例では、YYYYMM 日付形式を指定しています。これは要素セパレータを必要としません。TO_POSIXTIME では、不足している日付値と時刻値が補われます。

 SELECT TO_POSIXTIME('201806','YYYYMM')

この例では、タイムスタンプ 2018–06–01 00:00:00 を返しています。

以下の例では、HH:MI:SS.FF 時刻形式のみを指定しています。TO_POSIXTIME では、不足している日付値が補われます。いずれの場合も、日付 2018–01–01 (2018 が現在の年の場合) が返されます。

SELECT TO_POSIXTIME('11:34','HH:MI:SS.FF'),
       TO_POSIXTIME('11:34:22','HH:MI:SS.FF'),
       TO_POSIXTIME('11:34:22.00','HH:MI:SS.FF'),
       TO_POSIXTIME('11:34:22.7','HH:MI:SS.FF'),
       TO_POSIXTIME('11:34:22.7000000','HH:MI:SS.FF')

秒の小数部は指定どおりに渡され、埋め込みや切り捨ては行われません。

関連項目

• SQL コマンド ： CREATE TABLE、ALTER TABLE

• SQL 関数 ： CAST、CONVERT、TO_CHAR、TO_DATE、TO_NUMBER、TO_TIMESTAMP、UNIX_TIMESTAMP

• ObjectScript 関数： $ZDATETIME、$ZDATETIMEH

• ObjectScript 特殊変数： $ZTIMESTAMP