$ZDATETIME(hdatetime,dformat,tformat,precision,monthlist,yearopt,startwin,endwin,mindate,maxdate,erropt,localeopt)
$ZDT(hdatetime,dformat,tformat,precision,monthlist,yearopt,startwin,endwin,mindate,maxdate,erropt,localeopt)
引数
hdatetime
内部形式値として指定された日付と時刻。InterSystems IRIS 内部形式は、任意の開始ポイント (1840 年 12 月 31 日) からの日数で日付を表示し、その日の秒数で時刻を表示します。hdatetime の値は、以下のいずれかの形式の文字列である必要があります。
hdatetime は、文字列値、変数、式として指定できます。
hdatetime で日付部分の値のみが指定され、コンマが指定されない場合、日付のみが返されます。hdatetime で日付部分の値の後にコンマが指定され、時刻値が指定されない場合、時刻値として 00:00:00 が指定されます。
既定では、最も早い有効な hdatetime 日付は 0 です (1840 年 12 月 31 日)。DateMinimum プロパティの既定値は 0 であるため、既定では、日付は正の整数に制限されています。現在のロケールの DateMinimum プロパティが、過去の日付を表す負の整数以下の負の整数に設定されていれば、過去の日付を負の整数を使用して指定できます。DateMinimum の有効な最小値は -672045 であり、これは 0001 年 1 月 1 日に相当します。InterSystems IRIS では、ISO 8601 標準に準拠してグレゴリオ暦が "西暦 1 年" まで遡って適用された先発グレゴリオ暦が使用されています。その理由の 1 つは、グレゴリオ暦が採用された時期は国ごとに異なるからです。例えば、欧州大陸諸国の多くでは 1582 年に採用された一方で、英国と米国では 1752 年に採用されました。このため、ご使用の地域でグレゴリオ暦が採用された時期より前の InterSystems IRIS の日付は、その当時にその地域で採用されていた暦に基づいて記録された歴史上の日付に対応していない可能性があります。1840 年より前の日付の詳細は、"mindate" 引数を参照してください。
hdatetime 値が無効または範囲外の場合に生じるエラーは、erropt 引数で示されます。
precision
時刻を表すのに使用される、秒の小数部の精度を示す小数点以下の桁数を指定する整数値です。つまり、precision の値として 3 を入力すると、$ZDATETIME は秒数を小数点以下 3 桁まで表示します。precision の値として 9 を入力すると、$ZDATETIME は秒数を小数点以下 9 桁まで表示します。返す小数桁数をこの引数で指定します。精度を示す実際の有効桁数は hdatetime ソースによって決まります。例えば、$HOROLOG は小数秒を返しませんが、$ZTIMESTAMP と $NOW() は小数秒を返します。
サポートされている値は、以下のとおりです。
現在のロケールの TimePrecision プロパティから、precision値を取得します。既定は 0 です。precision を指定しなければ、これが既定の振る舞いになります。
ゼロ (0) 以上の n の値は、時刻を小数点以下の n 桁まで表すことを示します。
precision は hdatetime 形式に小数点以下の値 ($ZTIMESTAMP 形式) を含めることができ、選択した tformat オプションに秒が含まれている場合にのみ適用されます。末尾のゼロは、抑制されません。指定した有効桁数がシステムで利用できる有効桁数を超えている場合、有効桁数の余分な桁は、末尾のゼロとして返されます。9 の precision が指定された以下の例のように、Normalize()Opens in a new tab メソッドを使用することで、余分な末尾のゼロを抑制できます。
WRITE $ZDATETIME($ZTIMESTAMP,3,,9),!
WRITE ##class(%TimeStamp).Normalize($ZDATETIME($ZTIMESTAMP,3,,9))
ユーザのロケールの既定の時刻精度を決定するには、GetFormatItem()Opens in a new tab NLS クラス・メソッドを呼び出します。
WRITE ##class(%SYS.NLS.Format).GetFormatItem("TimePrecision")
ロケールの TimePrecision を任意の桁数 (最大 15 桁) に設定できます。
monthlist
区切り文字で区切られた月名または月の省略名の文字列に解決される式です。monthlist にある名前は、現在のロケールの MonthAbbr プロパティに指定されている既定の月の省略形の値、または MonthName に指定されている月名の値を置き換えます。
monthlist は、dformat が 2、5、6、7、9、18、または 20 の場合にのみ有効です。dformat がそれ以外の値の場合、$ZDATETIME は monthlist を無視します。
monthlist 文字列の形式は、以下のとおりです。
-
文字列の最初の文字は、区切り文字 (通常はスペース) です。monthlist 内の最初の月名の前と、各月名の間に、同じ区切り文字を置く必要があります。1 文字からなる任意の区切り文字を指定できます。この区切り文字は、返される日付値の月、日、年の間に表示されます。このため、スペースが通常推奨される区切り文字となります。
-
月名の文字列は、1 月 から 12 月に対応する 12 個の区切り値を含む必要があります。12 より多い、または 12 より少ない月名を指定することは可能ですが、hdatetime の月に該当する月名がない場合、<ILLEGAL VALUE> エラーが発生します。
monthlist を省略するか、monthlist の値として -1 を指定した場合は、現在のロケールの MonthAbbr または MonthName プロパティで定義されている月名のリストが $ZDATETIME で使用されます (localeopt=1、または monthlist の既定値が ODBC の月リスト (英語) である場合を除く)。localeopt が未指定で、dformat が 18 または 20 (イスラム暦の日付形式) の場合、monthlist の既定値はイスラム暦の月リスト (ラテン文字で表されたアラビア語の名前) になり、MonthAbbr および MonthName プロパティ値は無視されます。
ユーザのロケールの既定の月名および月名の省略形を決定するには、GetFormatItem()Opens in a new tab NLS クラス・メソッドを呼び出します。
WRITE ##class(%SYS.NLS.Format).GetFormatItem("MonthName"),!
WRITE ##class(%SYS.NLS.Format).GetFormatItem("MonthAbbr"),!
yearopt
dformat 値に 0、1、2、4、7、または 15 を使用して、年を 2 桁で表示する時間ウィンドウを指定する数値コードです。yearopt の値は以下のとおりです。
値 |
意味 |
-1 |
現在のロケールの YearOption プロパティから有効な yearopt 値を取得します。この既定値は 0 です。yearopt を指定しない場合、これが既定の振る舞いになります。 |
0 |
(%DATE ユーティリティにより構築される) プロセス特有のスライディング・ウィンドウが有効になっていない限り、20 世紀 (1900 年から 1999 年まで) の日付は 2 桁で表示します。スライディング・ウィンドウが有効な場合は、指定範囲内の日付のみ 2 桁の年で表示します。1900 年代以外もしくはプロセス特有のスライディング・ウィンドウ以外の日付は、すべて 4 桁で表示します。 |
1 |
20 世紀の日付は 2 桁の年、それ以外は 4 桁で表します。 |
2 |
すべての日付を 2 桁の年で表します。 |
3 |
startwin と (オプションで) endwin に定義した一時的なスライディング・ウィンドウ範囲内に収まる日付を、2 桁の年で表します。それ以外の日付は 4 桁で表します。yearopt=3 の場合、startwin と endwin は、$HOROLOG 形式の絶対日付です。 |
4 |
すべての日付を 4 桁の年で表します。 |
5 |
startwin と (オプションで) endwin に定義したスライディング・ウィンドウ範囲内に収まる日付をすべて、2 桁の年で表します。それ以外の日付は 4 桁で表します。yearopt=5 の場合、startwin と endwin は相対年になります。 |
6 |
2 桁の年で現在の世紀にあるすべての日付を表します。それ以外は 4 桁の年で表します。 |
ユーザのロケールの既定の年のオプションを決定するには、GetFormatItem()Opens in a new tab NLS クラス・メソッドを呼び出します。
WRITE ##class(%SYS.NLS.Format).GetFormatItem("YearOption")
yearopt を省略するか、yearopt の値として -1 を指定した場合は、現在のロケールの YearOption プロパティが $ZDATETIME で使用されます (localeopt=1、または yearopt の既定値が ODBC の年オプションである場合を除く)。localeopt=0 または未指定で、dformat が 18、19、20、または 21 (イスラム暦の日付形式) の場合、yearopt の既定値は ODBC の年オプション (4 桁の年) になります。イスラム暦の日付では、YearOption プロパティの値は無視されます。
startwin
日付を 2 桁の年で表す必要があるスライディング・ウィンドウの最初を指定する数値です。yearopt の値に 3 または 5 を使用する場合は、startwin を指定する必要があります。startwin は、他の yearopt 値では無効になります。
yearopt=3 のとき、startwin はスライディング・ウィンドウの最初の日付を示す $HOROLOG 日付形式の絶対日付です。
yearopt=5 のとき、startwin は、現在の年より前の年数で表される、スライディング・ウィンドウの最初の年を示す数値です。
endwin
日付を 2 桁の年で表すスライディング・ウィンドウの最後を指定する数値です。yearopt が 3 あるいは 5 のとき、endwin をオプションで指定する必要があります。endwin は、その他の yearopt 値では無効になります。
yearopt=3 のとき、endwin はスライディング・ウィンドウの最後の日付を示す $HOROLOG 日付形式の絶対日付です。
yearopt=5 のとき、endwin は、現在の年から後の年数を示すスライディング・ウィンドウの最後の年を示す数値です。
yearopt=5 のとき、スライディング・ウィンドウは常に startwin で指定する年の最初の日付 (1 月 1 日) で開始し、endwin で指定する年の最後の日付 (12 月 31 日) あるいは最後と暗示される年の最後の日付 (endwin が省略されているとき) で終了します。
endwin を省略した場合または -1 を指定した場合、スライディング・ウィンドウの有効期限は 100 年間です。endwin 値を -1 とすると特殊なケースになります。endwin の値が -1 よりも大きい場合または小さい場合に erropt が返される場合でも、-1 の場合は必ず日付値が返されます。このため、100 年間のウィンドウを指定する場合は endwin を省略し、その他の場合でも endwin には負の値を指定しないようにすることをお勧めします。
startwin と endwin の両方を指定する場合、指定するスライディング・ウィンドウの年数は 100 年以内に収める必要があります。
mindate
有効な日付範囲 (両端を含む) の下限を指定する式です。$HOROLOG 整数日付カウント (例えば、2/22/2018 は 64701 と表される) または $HOROLOG 文字列値の形式で指定できます。$HOROLOG 日付 (“64701,43200” など) の時刻部分は含めることも省略することもできますが、解析されるのは mindate の日付部分のみです。mindate より前の hdatetime 値を指定すると、<VALUE OUT OF RANGE> エラーが発生します。
mindate に指定できる値は以下のとおりです。
-
正整数 : mindate には、通常、1840 年 12 月 31 日より後の最も早い有効日付を設定するための正の整数を指定します。例えば、mindate に 21550 を指定すると、1900 年 1 月 1 日が最も早い有効日付として設定されます。有効な最大値は 2980013 です (9999 年 12 月 31 日)。
-
0 : 1840 年 12 月 31 日を最も早い日付として指定します。これは DateMinimum プロパティの既定値です。
-
-2 以下の負の整数 : 1840 年 12 月 31 日から遡ってカウントする最も早い日付を指定します。例えば、mindate に -14974 を指定すると、1800 年 1 月 1 日が最も早い有効日付として設定されます。負の mindate 値が有効となるのは、現在のロケールの DateMinimum プロパティがその値以下の負の整数に設定されている場合のみです。有効な最小値は -672045 です。-672045 より前の mindate は、<ILLEGAL VALUE> エラーを生成します。
-
mindate を省略するか、-1 を指定した場合は、現在のロケールの DateMinimum プロパティ値が既定値になります (localeopt=1 または mindate の既定値が 0 の場合を除く)。localeopt が未指定で dformat=3 の場合、mindate の既定値は 0 になります。localeopt が未指定で dformat が 18、19、20、または 21 (イスラム暦の日付形式) の場合、mindate の既定値は 0 になります。
DateMinimum プロパティは、以下のように取得および設定できます。
SET min=##class(%SYS.NLS.Format).GetFormatItem("DateMinimum")
WRITE "initial DateMinimum value is ",min,!
Permit18thCenturyDates
SET x=##class(%SYS.NLS.Format).SetFormatItem("DateMinimum",-51498)
SET newmin=##class(%SYS.NLS.Format).GetFormatItem("DateMinimum")
WRITE "set DateMinimum value is ",newmin,!!
RestrictTo19thCenturyDates
WRITE $ZDATETIME(-13000,1,,,,,,,-14974),!!
ResetDateMinimumToDefault
SET oldmin=##class(%SYS.NLS.Format).SetFormatItem("DateMinimum",min)
WRITE "reset DateMinimum value from ",oldmin," to ",min
mindate を指定する際は、maxdate を指定しても指定しなくてもかまいません。maxdate より大きい mindate を指定すると、<ILLEGAL VALUE> エラーが発生します。
maxdate
有効な日付範囲 (両端を含む) の上限を指定する式です。$HOROLOG 整数日付カウント (例えば、1/1/2100 は 94599 と表される) または $HOROLOG 文字列値の形式で指定できます。$HOROLOG 日付 (“94599,43200” など) の時刻部分は含めることも省略することもできますが、解析されるのは maxdate の日付部分のみです。
maxdate を省略するか、または -1 を指定すると、現在のロケールの DateMaximum プロパティから日付の上限が取得されます。既定値は、$HOROLOG の日付部分で許容される最大値である、2980013 (西暦 9999 年 12 月 31 日に対応) です。ただし、DateMaximum プロパティの適用は localeopt の設定によって制御されます。localeopt=1 (dformat=3 の場合の既定値) の場合、現在のロケール設定に関係なく、日付の既定最大値は ODBC の値 (2980013) になります。イスラム暦の日付形式でも ODBC の既定値が使用されます。タイ日付形式 (dformat=13) の最大日付は $HOROLOG 2781687 で、これは BE 9999 年 12 月 31 日に対応します。
maxdate より大きい hdatetime 日付を指定すると、<VALUE OUT OF RANGE> エラーが発生します。
2980013 より大きい maxdate を指定すると、<ILLEGAL VALUE> エラーが発生します。
maxdate を指定する際は、mindate を指定しても指定しなくてもかまいません。mindate より小さい maxdate を指定すると、<ILLEGAL VALUE> エラーが発生します。
erropt
この引数に値を指定すると、hdatetime 値が無効または範囲外の場合に生じるエラーが抑制されます。$ZDATETIME 関数は、<ILLEGAL VALUE> または <VALUE OUT OF RANGE> エラーを生成する代わりに erropt 値を返します。
-
検証:InterSystems IRIS は、hdatetime に対してキャノニック数値変換を実行します。 hdatetime の日付と時刻の部分は別々に解析されます。日付/時刻区切り文字として検出された最初のコンマを解析します。追加のコンマは、数値以外の文字として処理されます。
hdatetime 文字列の各部分の解析は、数値以外の最初の文字で停止します。したがって、64687AD,1234SECS などの hdatetime は、64687,1234 と同じです。数値以外の日付または時刻部分 (NULL 文字列を含む) は 0 に評価されます。したがって、hdatetime が空の文字列の場合は、$HOROLOG の最初の日付 (12/31/1840) が返されます。
ただし、日付部分の値が整数に評価されない (ゼロ以外の小数を含む) 場合、<ILLEGAL VALUE> エラーが発生します。
-
範囲:hdatetime の日付部分は mindate から maxdate までの範囲内の整数に評価される必要があります。既定では、2980013 を超える日付値または 0 未満の日付値は <VALUE OUT OF RANGE> エラーを生成します。mindate を負の数値に設定すると、1840 年 12 月 31 日より前の有効な日付の範囲を拡張できます。ただし、dformat 18、19、20、または 21 (ヒジュラ・イスラム暦) の日付の場合、-445031 より前の日付は、mindate がより早い日付に設定されていても、<ILLEGAL VALUE> エラーを生成します。
hdatetime の時刻部分に 86399 より大きい値を指定すると、<ILLEGAL VALUE> エラーが生成されます。負の hdatetime 時刻値を指定すると、<ILLEGAL VALUE> エラーが生成されます。
erropt 引数は、hdatetime の無効な値または範囲外の値が原因で生成されるエラーのみを抑制します。他の引数の無効な値、あるいは範囲外の値が原因で発生したエラーについては、erropt が指定されているかどうかに関係なく、常にエラーが生成されます。例えば、$ZDATETIME でendwin が startwin より前になる値のスライディング・ウィンドウを指定すると、常に <ILLEGAL VALUE> エラーが発生します。同様に、maxdate が mindate より小さい場合、<ILLEGAL VALUE> エラーが発生します。
localeopt
このブーリアン引数には、ロケールで指定される引数 dformat、tformat、monthlist、yearopt、mindate、および maxdate の既定値のソースとして、ユーザの現在のロケール定義または ODBC のロケール定義が指定されます。
-
localeopt=0 の場合は、これらすべての引数で現在のロケール定義の既定値が使用されます。
-
localeopt=1 の場合は、これらすべての引数で ODBC の既定値が使用されます。
-
localeopt が未指定の場合は、dformat 引数によってこれらの引数の既定値が決定されます。dformat=3 の場合は、ODBC の既定値が使用されます。dformat が 18、19、20、または 21 の場合は、現在のロケール定義に関係なく、イスラム暦の日付および時刻形式の既定値が使用されます。dformat がそれ以外の値の場合は、現在のロケール定義の既定値が使用されます。詳細は、"dformat" の説明を参照してください。
ODBC 標準ロケールは変更できません。これは、異なる各国語サポート (NLS) の選択を行った InterSystems IRIS プロセス間で移植できる、日付文字列および時刻文字列をフォーマットするために使用されます。ODBC ロケールの日付と時刻の定義は、以下のとおりです。
-
日付形式の既定は 3 です。したがって、dformat が未定義または -1 の場合は、日付形式 3 が使用されます。
-
日付の区切り文字の既定は "/" です。ただし、日付形式の既定は 3 で、これは日付の区切り文字として "-" を常に使用します。
-
年のオプションの既定は 4 桁です。
-
日付の最小値は 0 で、最大値は 2980013 ($HOROLOG の日数カウント) です。
-
英語の月名、月の省略形、曜日名、曜日の省略形、および "Noon" と "Midnight" の語が使用されます。
-
時刻形式は既定で 1 になります。時刻区切り文字は “.” です。時刻精度は 0 (小数秒なし) です。午前と午後の指定子は、"AM" と "PM" です。
例
以下の例は、現在の現地日付と現地時刻を表示します。また、ロケールの既定の日付および時刻形式を取ります。
WRITE $ZDATETIME($HOROLOG)
以下の例は、現在の日付と時刻を表示します。$ZTIMESTAMP には、現在の日付値と時刻値が協定世界時 (UTC) 日付/時刻として含まれます。dformat 引数は ODBC 日付形式を指定し、tformat 引数は 24 時間制を指定し、precision 引数は 6 桁の小数秒の有効桁数を指定します。
WRITE $ZDATETIME($ZTIMESTAMP,3,1,6)
2018/11/25 18:45:16.960000 のようにフォーマットされた、現在のタイムスタンプ日付と時刻を返します。
以下の例は、現地時間を UTC 時間に変換する方法と、その変換結果によりどのように日付が変更されるかを示します。ほとんどのタイム・ゾーンにおいて、以下の $ZDATETIME 演算のいずれかで、時間変換により日付変更が生じます。
SET local = $ZDATETIME("60219,82824",3,1)
SET utcwest = $ZDATETIME("60219,82824",3,7)
SET utceast = $ZDATETIME("60219,00024",3,7)
WRITE !,local,!,utcwest,!,utceast
日付と時刻の既定値のカスタマイズ
InterSystems IRIS の起動時、既定の日付および時刻の形式は、アメリカの日付および時刻形式 (例えば MM/DD/[YY]YY) に初期化されています。この形式およびその他の既定の形式を現在のロケール用に設定するには、SET ^SYS("NLS","Config","LocaleFormat")=1 のグローバル変数を設定します。これは、すべてのプロセスのすべての既定の形式を現在のロケール値に設定します。これらの既定は、このグローバルが変更されるまで維持されます。
Note:
ここでは、localeopt が未定義または 0 に設定されているときに適用されるユーザ・ロケール定義について説明します。localeopt=1 の場合、$ZDATETIME は、定義済みの ODBC ロケールを使用します。
以下の例で、最初の $ZDATETIME は、ロケールの既定形式で日付と時刻を返します。入力引数は、$ZTIMESTAMP 特殊変数、既定の dformat 引数と tformat 引数、および 2 小数桁に設定された precision です。ほとんどのロケールでは、最初の $ZDATETIME は、dformat=1 または、日付の区切り文字にスラッシュ、秒の小数部用の小数点区切り文字にドットを使用したアメリカ形式の日付と時刻を返します。
ChangeVals セクションでは、最初の SetFormatItem()Opens in a new tab メソッドは、2 つ目の $ZDATETIME で示されるように、ロケールの日付形式の既定値を dformat=4、またはヨーロッパ日付形式 (DD/MM/[YY]YY) に変更します。2 つ目の SetFormatItem() メソッドは、(dformat が -1、1、4、および 15 の場合に影響する) 日付区切り文字に対するロケールの既定値を変更します。この例では、3 つ目の $ZDATETIME で示されるように、日付区切り文字は、ドット (".") に設定されています。3 番目の SetFormatItem() メソッドは、最後の $ZDATETIME で示されるように、このロケールの小数点区切り文字をヨーロッパ標準 (“,”) に変更します。その後、このプログラムは日付形式の初期値をリストアします。
InitalizeLocaleFormat
SET ^SYS("NLS","Config","LocaleFormat")=1
InitialVals
SET fmt=##class(%SYS.NLS.Format).GetFormatItem("DateFormat")
SET sep=##class(%SYS.NLS.Format).GetFormatItem("DateSeparator")
SET dml=##class(%SYS.NLS.Format).GetFormatItem("DecimalSeparator")
WRITE !,$ZDATETIME($ZTIMESTAMP,,,2)
ChangeVals
SET x=##class(%SYS.NLS.Format).SetFormatItem("DateFormat",4)
WRITE !,$ZDATETIME($ZTIMESTAMP,,,2)
SET y=##class(%SYS.NLS.Format).SetFormatItem("DateSeparator",".")
WRITE !,$ZDATETIME($ZTIMESTAMP,,,2)
SET z=##class(%SYS.NLS.Format).SetFormatItem("DecimalSeparator",",")
WRITE !,$ZDATETIME($ZTIMESTAMP,,,2)
RestoreVals
SET x=##class(%SYS.NLS.Format).SetFormatItem("DateFormat",fmt)
SET y=##class(%SYS.NLS.Format).SetFormatItem("DateSeparator",sep)
SET z=##class(%SYS.NLS.Format).SetFormatItem("DecimalSeparator",dml)
WRITE !,$ZDATETIME($ZTIMESTAMP,,,2)