$ZDATETIMEH(datetime,dformat,tformat,monthlist,yearopt,startwin,endwin,mindate,maxdate,erropt,localeopt)
$ZDTH(datetime,dformat,tformat,monthlist,yearopt,startwin,endwin,mindate,maxdate,erropt,localeopt)
説明
$ZDATETIMEH は、指定された日付と時刻値を検証し、これを表示形式から内部形式に変換します。対応する $ZDATETIME 関数は、日付と時刻値を内部形式から表示形式に変換します。内部形式は、$HOROLOG または $ZTIMESTAMP によって使用される形式です。コンマで区切られた 2 つの数値の文字列として、日付と時刻値を表します。
返される値は、使用する引数によって異なります。
$ZDATETIMEH(datetime) は、日付と時刻値を "MM/DD/[YY]YY hh:mm:ss[.ffff]" 形式から $HOROLOG 形式に変換します。
構文 |
意味 |
MM |
2 桁の月 |
DD |
2 桁の日 |
[YY]YY |
1900 年から 1999 年までは 2 桁または 4 桁。1900 年より前、または 1999 年より後の年は 4 桁 |
hh |
24 時間形式の時間 |
mm |
分 |
ss |
秒 |
ffff |
小数秒 (小数点以下 0 から 9 桁まで) |
$ZDATETIMEH(datetime,dformat,tformat,monthlist,yearopt,startwin,endwin,mindate,maxdate,erropt) は、($ZDATETIMEを使用して) 最初に指定された日付と時刻値を $HOROLOG 形式または $ZTIMESTAMP 形式に変換します。dformat、tformat、yearopt、startwin および endwin の値は、$ZDATETIME によって使用される値と同一です。
ただし、dformat に 5、6、7、8、または 9 を指定した場合、$ZDATETIMEH は dformat コード 1、2、3、5、6、7、8、9 に対応するあらゆる外部アメリカ日付形式の日付を認識して変換します。有効なアメリカ日付形式のリストは、"$ZDATEH" を参照してください。dformat に 15 を使用している場合、$ZDATETIMEH は、曖昧でないあらゆるヨーロッパ日付形式の日付を認識して変換します。有効なヨーロッパ日付形式のリストは、"$ZDATEH" を参照してください。
また、dformat 値に 5、6、7、8、9、または 15 を指定した場合も、文字 “T” または “t” で指定した現在の日付を使用できます。T や t の後に、プラス記号 (+) またはマイナス記号 (-)、および現在の日付より前または後の日数を表す数値を記述することもできます。
$ZDATETIMEH は、関数呼び出しで指定した時刻形式に関係なく、8 つの時刻形式の時刻をすべて認識して変換します。さらに、$ZDATETIMEH は、接尾語 "AM、PM、NOON、MIDNIGHT" を認識して変換します。これらの接尾語は、大文字、小文字、または両方を混在させて表すことができます。これらの接尾語を文字に省略することもできます。
認識する形式は、以下のとおりです。
-
既定の日付形式、MM/DD/[YY]YY
-
形式 DDMmm[YY]YY
-
ODBC 形式 [YY]YY-MM-DD
-
形式、DD/MM/[YY]YY
-
形式 Mmm D, YYYY
-
形式 Mmm D YYYY
-
形式 Mmm DD YY
-
形式 YYYYMMDD (数値形式)
引数
datetime
$HOROLOG 形式に変換する日付と時刻の文字列。以下のいずれかを指定できます。
-
先頭に日付、その後に 1 つの空白スペース、時刻と続く、1 つの文字列に評価される式として指定します。
-
日付のみを指定する文字列として評価される式。tformat が 7 または 8 (この場合、深夜 (0) からのローカル・タイム・ゾーンのオフセットが既定時刻となる) の場合を除き、時刻の既定値は深夜 (0) となります。
-
文字コード “T” または “t” は、現在の日付を指定します。この文字の後に、オプションでプラス記号、またはマイナス記号、および現在の日付からのオフセットを日数で指定する整数を付けることができます。この日付式の後に、1 つの空白スペースと時刻式を付けることも、時刻を既定の深夜 (0) とすることもできます。(tformat が 7 または 8 の場合、時刻は既定の深夜 (0) からのローカル・タイム・ゾーンのオフセットとなります。)この現在の日付オプションを使用する場合、dformat の値として 5、6、7、8、9、または 15 を指定する必要があります。
有効な日付値、および時刻値は、現在のロケールの DateFormat 引数と TimeFormat 引数、および dformat 引数と tformat 引数に指定する値によって異なります。日付に関する詳細は、"$ZDATEH" を参照してください。
既定では、最も早い有効な datetime 日付は 1840 年 12 月 31 日です (内部 $HOROLOG 表現では 0)。DateMinimum プロパティの既定値は 0 であるため、既定では、日付は正の整数に制限されています。現在のロケールの DateMinimum プロパティが、過去の日付を表す負の整数以下の負の整数に設定されていれば、過去の日付を負の整数を使用して指定できます。DateMinimum の有効な最小値は -672045 であり、これは 0001 年 1 月 1 日に対応します。InterSystems IRIS では、ISO 8601 標準に準拠してグレゴリオ暦が "西暦 1 年" まで遡って適用された先発グレゴリオ暦が使用されています。その理由の 1 つは、グレゴリオ暦が採用された時期は国ごとに異なるからです。例えば、欧州大陸諸国の多くでは 1582 年に採用された一方で、英国と米国では 1752 年に採用されました。このため、ご使用の地域でグレゴリオ暦が採用された時期より前の InterSystems IRIS の日付は、その当時にその地域で採用されていた暦に基づいて記録された歴史上の日付に対応していない可能性があります。1840 年より前の日付の詳細は、"mindate" 引数を参照してください。
monthlist
区切り文字で区切られた月名または月の省略名の文字列に解決される式です。monthlist にある名前は、現在のロケールの MonthAbbr プロパティに指定されている既定の月の省略形の値、または MonthName に指定されている月名の値を置き換えます。
monthlist は、dformat が 2、5、6、7、9、15、18、または 20 の場合にのみ有効です。dformat がそれ以外の値の場合、$ZDATETIMEH は monthlist を無視します。
monthlist 文字列の形式は、以下のとおりです。
-
文字列の最初の文字は、区切り文字 (通常はスペース) です。monthlist 内の最初の月名の前と、各月名の間に、同じ区切り文字を置く必要があります。1 文字からなる任意の区切り文字を指定できます。この区切り文字は、指定された datetime 値の月、日、年の間に指定する必要があります。このため、スペースが通常推奨される区切り文字となります。
-
月名の文字列は、1 月 から 12 月に対応する 12 個の区切り値を含む必要があります。12 より多い、または 12 より少ない月名を指定することは可能ですが、datetime の月に該当する月名がない場合、<ILLEGAL VALUE> エラーが発生します。
monthlist を省略するか、monthlist の値として -1 を指定した場合は、現在のロケールの MonthAbbr または MonthName プロパティで定義されている月名のリストが $ZDATETIMEH で使用されます (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 を使用して、年を 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 桁の年で表します。 |
yearopt を省略するか、yearopt の値として -1 を指定した場合は、現在のロケールの YearOption プロパティが $ZDATETIMEH で使用されます (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 は、現在の年より前の年数で表される、スライディング・ウィンドウの最初の年を示す数値です。スライディング・ウィンドウは常に、startwin で指定した年の初日 (1 月 1 日) から開始します。
endwin
日付を 2 桁の年で表すスライディング・ウィンドウの最後を指定する数値です。yearopt が 3 あるいは 5 のとき、endwin をオプションで指定する必要があります。endwin は、その他の yearopt 値では無効になります。
yearopt=3 のとき、endwin はスライディング・ウィンドウの最後の日付を示す $HOROLOG 日付形式の絶対日付です。
yearopt=5 のとき、endwin は、現在の年から後の年数を示すスライディング・ウィンドウの最後の年を示す数値です。スライディング・ウィンドウは常に、endwin. で指定した年の 12 月 31 日で終了します。endwin を指定しない場合、既定は、startwin 以降 100 年後の 12 月 31 日です。
endwin を省略した場合または -1 を指定した場合、スライディング・ウィンドウの有効期限は 100 年間です。endwin 値を -1 とすると特殊なケースになります。endwin の値が -1 よりも大きい場合または小さい場合に erropt が返される場合でも、-1 の場合は必ず日付値が返されます。このため、100 年間のウィンドウを指定する場合は endwin を省略し、その他の場合でも endwin には負の値を指定しないようにすることをお勧めします。
startwin と endwin の両方を指定する場合、指定するスライディング・ウィンドウの年数は 100 年以内に収める必要があります。
mindate
有効な日付範囲 (両端を含む) の下限を指定する式です。$HOROLOG 整数日付カウント (例えば、1/1/2013 は 62823 と表される) または $HOROLOG 文字列値の形式で指定できます。$HOROLOG 日付文字列 (“62823,43200” など) の時刻部分は含めることも省略することもできますが、解析されるのは mindate の日付部分のみです。mindate より前の datetime 値を指定すると、<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 です。
-
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 $ZDATETIMEH("05/29/1805 12:00:00",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) の最大日付は BE 9999 年 12 月 31 日で $HOROLOG 2781687 に対応します。
maxdate より大きい datetime を指定すると、<VALUE OUT OF RANGE> エラーが発生します。
2980013 より大きい maxdate を指定すると、<ILLEGAL VALUE> エラーが発生します。
maxdate を指定する際は、mindate を指定しても指定しなくてもかまいません。mindate より小さい maxdate を指定すると、<ILLEGAL VALUE> エラーが発生します。
erropt
この引数に値を指定すると、datetime 値が無効または範囲外の場合に生じるエラーが抑制されます。$ZDATETIMEH 関数は、<ILLEGAL VALUE> または <VALUE OUT OF RANGE> エラーを生成する代わりに erropt 値を返します。
InterSystems IRIS は、datetime に対して標準の数値評価を実行します。これは常に mindate から maxdate までの範囲内の整数日付に評価される必要があります。したがって、7、"7"、+7、0007、7.0、"7 dwarves"、--7 は、すべて同じ日付値 (01/07/1841) に評価されます。既定では、2980013 を超える値または 0 未満の値は <VALUE OUT OF RANGE> エラーを生成します。小数値は <ILLEGAL VALUE> エラーを生成します。数値以外の文字列 (NULL 文字列を含む) は 0 に評価され、$HOROLOG の最初の日付 (12/31/1840) が返されます。
erropt 引数は、datetime の無効な値または範囲外の値が原因で生成されるエラーのみを抑制します。他の引数の無効な値、あるいは範囲外の値が原因で発生したエラーについては、erropt が指定されているかどうかに関係なく、常にエラーが生成されます。例えば、$ZDATETIMEH で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" です。
現在の日付
以下の例では、“T” または “t” 文字コードを使用して現在の日付を指定する方法を示します。ただし、dformat には 5、6、7、8、9、または 15 を指定する必要があります。
時刻が既定の 0 となっている現在の日付は、以下のとおりです。
WRITE $ZDATETIMEH("T",5)
時刻が既定の 0 となっている現在の日付の 3 日前は、以下のとおりです。
WRITE $ZDATETIMEH("T-3",5)
時刻が指定されている、現在の日付の 2 日後は、以下のとおりです。
WRITE $ZDATETIMEH("T+2 11:45:00",5)
$ZDATEH と $ZDATETIMEH
$ZDATETIMEH は、$ZDATEH に似ていますが、異なる点として、日付と時刻の値の両方を内部 $HOROLOG 形式に (時刻値を指定していない場合でも) 変換します。$ZDATEH は、日付値のみを $HOROLOG 形式に変換します。以下はその例です。
WRITE $ZDATEH("Nov 25, 2002",5)
これは、59133 を返します。
WRITE $ZDATETIMEH("Nov 25, 2002 10:08:09.539",5)
これは、59133,36489.539 を返します。
$ZDATETIMEH に値を指定しない場合
WRITE $ZDATETIMEH("Nov 25, 2002",5)
これは、59133.0 を返します。
時刻値を指定せず、tformat を 7 または 8 にして $ZDATETIMEH を指定する場合
WRITE $ZDATETIMEH("Nov 25, 2002",5,7)
59133,68400 のような値が返されます。ここで、時刻値は、深夜からのローカル・タイム・ゾーンのオフセットです。この場合、米国東部標準時間は、UTC から 5 時間オフセットされているので、ここでの時刻値は、19:00 (深夜から 5 時間オフセット) を表します。