$ZDATEH

単純な $ZDATEH 形式

$ZDATEH(date) は、MM/DD/[YY]YY 形式から $HOROLOG 形式の最初の整数に日付を変換します($HOROLOG は、2 つの整数で構成されます。最初の整数は日付、2 番目の整数は時刻です。)1900 年から 1999 年までは 2 桁または 4 桁で指定し、1900 年より前、または 1999 年より後の年は 4 桁で指定します。

$ZDATEH 形式のカスタマイズ

$ZDATEH(date,dformat,monthlist,yearopt,startwin,endwin,mindate,maxdate,erropt) は、指定された dformat の日付を $HOROLOG 形式に変換します。dformat、monthlist、yearopt、startwin、endwin、mindate、maxdate、および erropt の値は、$ZDATE によって使用される値と同一です。ただし、dformat に 5、6、7、8、9 を使用している場合、$ZDATEH は dformat コード 1、2、3、5、6、7、8、9 に対して定義されている (dformat コード 4 は除きます)、あらゆる外部日付形式の日付を認識して変換します。また、特別な相対 date 形式も認識します。相対 date 形式は、T または t ("today" の意味) で始まる文字列の後に、オプションでプラス記号 (+) またはマイナス記号 (-)、および現在の日付より前の、あるいは後の日数を表す整数値が続きます。

date

$HOROLOG 形式に変換する日付。引用符付き文字列として指定します。これは、明示的な日付、あるいは、"T" または "t" 文字列で表す暗黙の現在日付です。

明示的な日付は、dformat によってサポートされる形式で指定する必要があります。許可される形式は、dformat パラメータに応じて異なります。dformat が指定されていない場合、あるいは 1、2、3、4 の場合、許可される日付形式は 1 つだけです。dformat が 5、6、7、8、9、または 15 の場合は、複数の日付形式を使用できます。

dformat が 5、6、7、8、または 9 の場合、$ZDATEH では、曖昧ではないすべてのアメリカ日付形式を使用できます。dformat が 15 の場合、$ZDATEH では、曖昧ではないすべてのヨーロッパ日付形式を使用できます。有効な日付形式のリストは、以下を参照してください。$ZDATEH では、02/03/02 (2002 年 2 月 3 日) とヨーロッパ形式の 02/03/02 (2002 年 3 月 2 日) を区別できないので、dformat=4 は有効なアメリカ日付形式ではありません。許可されていない形式で日付を指定した場合や存在しない日付 (2002 年 2 月 31 日など) を指定した場合、$ZDATEH では <ILLEGAL VALUE> エラー・コードが生成されます($ZDATEH は、うるう年の確認も実行します。したがって、2004 年 2 月29 日は許可されますが、2003 年 2 月 29 日は許可されません)。

ロシア、ウクライナ、およびチェコのロケールでは、date の値は、DD.MM.YYYY のように、スラッシュではなくピリオドを日付部分の区切り文字として使用して指定する必要があります。

暗黙日付は、現在の (今日の) 日付を示す “T” または “t” の文字から成る文字列として指定されます。この文字列は、オプションでプラス記号、またはマイナス記号、および整数を含みます。これは、現在の日付からのオフセットの日数を指定します。例えば、"t+9" は現在の日付の 9 日後を表し、"t-12" は現在の日付の 12 日前を表します。暗黙日付は、dformat が 5、6、7、8、9、または 15 の場合にのみ使用できます。使用できる唯一の暗黙日付の形式は、"T" (または "t")、あるいは "T" (または "t") の後に符号と整数を続けて記述する形式です。整数以外の値、算術式、符号なしの整数、または整数なしの符号を指定した場合、Caché は <ILLEGAL VALUE> エラーを生成します。"T+0" および "T-0" は許可されており、現在の日付を返します。$HOROLOG 日付が有効な日付範囲外となるオフセットを指定した場合は、Caché は <VALUE OUT OF RANGE> エラーを生成します。

既定では、最も早い有効な date は 1840 年 12 月 31 日です (内部 $HOROLOG 表現では 0)。DateMinimum プロパティの既定値は 0 であるため、既定では、日付は正の整数に制限されています。現在のロケールの DateMinimum プロパティが、過去の日付を表す負の整数以下の負の整数に設定されていれば、過去の日付を負の整数を使用して指定できます。DateMinimum の有効な最小値は -672045 であり、これは 0001 年 1 月 1 日に相当します。Caché では、ISO 8601 標準に準拠してグレゴリオ暦が “西暦 1 年” まで遡って適用された先発グレゴリオ暦が使用されています。その理由の 1 つは、グレゴリオ暦が採用された時期は国ごとに異なるからです。例えば、欧州大陸諸国の多くでは 1582 年に採用された一方で、英国と米国では 1752 年に採用されました。このため、ご使用の地域でグレゴリオ暦が採用された時期より前の Caché の日付は、その当時にその地域で採用されていた暦に基づいて記録された歴史上の日付に対応していない可能性があります。1840 年より前の日付の詳細は、"mindate" パラメータを参照してください。

dformat

日付の形式です。有効な値は以下のとおりです。

以下は、この指定の説明です。

dformat の既定値

dformat を省略するか、-1 に設定した場合、dformat の既定値は localeopt パラメータと NLS の DateFormat プロパティに依存します。

• localeopt=1 の場合、dformat の既定値は ODBC 形式です。monthlist、yearopt、mindate、および maxdate パラメータの既定値も、ODBC 形式に設定されます。これは、dformat=3 を設定した場合と同じです。

• localeopt=0 または未指定の場合、dformat の既定値は NLS の DateFormat プロパティから取得されます。DateFormat=3 の場合、dformat の既定値は ODBC 形式です。ただし、DateFormat=3 は monthlist、yearopt、mindate、および maxdate パラメータの既定値に影響しません。これらは、NLS の現在のロケール定義で指定されます。

ユーザのロケールの既定の日付プロパティを決定するには、GetFormatItem()Opens in a new tab NLS クラス・メソッドを呼び出します。

  WRITE ##class(%SYS.NLS.Format).GetFormatItem("DateFormat"),!
  WRITE ##class(%SYS.NLS.Format).GetFormatItem("DateSeparator")

$ZDATEH は、dformat=1 または 4 の場合に、現在のロケールのDateSeparator プロパティの値 (/ または .) を、月、日、および年の区切り文字として使用します。

ヨーロッパ日付形式 (dformat=4、DD/MM/YYYY の順) は、ヨーロッパの多くの言語 (すべてではない) で既定です。これには、“/” を DateSeparator 文字として使用するイギリス英語、フランス語、ドイツ語、イタリア語、スペイン語、ポルトガル語、および “.” をDateSeparator 文字として使用するチェコ語 (csyw)、ロシア語 (rusw)、スロバキア語 (skyw)、スロベニア語 (svnw)、ウクライナ語 (ukrw) が含まれます。サポートされるロケールの既定の日付形式の詳細は、"Caché ObjectScript の使用法" の "日付" を参照してください。

monthlist

区切り文字で区切られた月名または月の省略名の文字列に解決される式です。monthlist にある名前は、現在のロケールの MonthAbbr プロパティに指定されている既定の月の省略形の値、または MonthName に指定されている月名の値を置き換えます。

monthlist は、dformat が 2、5、6、7、8、9、15、18、または 20 の場合にのみ有効です。dformat がそれ以外の値の場合、$ZDATEH は monthlist を無視します。

monthlist 文字列の形式は、以下のとおりです。

• 文字列の最初の文字は、区切り文字 (通常はスペース) です。monthlist 内の最初の月名の前と、各月名の間に、同じ区切り文字を置く必要があります。1 文字からなる任意の区切り文字を指定できます。この区切り文字は、指定された date 値の月、日、年の間に指定する必要があります。このため、スペースが通常推奨される区切り文字となります。

• 月名の文字列は、1 月 から 12 月に対応する 12 個の区切り値を含む必要があります。12 より多い、または 12 より少ない月名を指定することは可能ですが、date の月に該当する月名がない場合、<ILLEGAL VALUE> エラーが発生します。

monthlist を省略するか、monthlist の値として -1 を指定した場合は、現在のロケールの MonthAbbr または MonthName プロパティで定義されている月名のリストが $ZDATEH で使用されます (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

年を 2 桁で表示するか 4 桁で表示するかを指定する数値コード。有効な値は以下のとおりです。

yearopt を省略するか、yearopt の値として -1 を指定した場合は、現在のロケールの YearOption プロパティが $ZDATEH で使用されます (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 を省略した場合は) 暗示されている最後の年の最後の日 (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 より前の date 値を指定すると、<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 $ZDATEH("05/29/1805",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 より大きい date を指定すると、<VALUE OUT OF RANGE> エラーが発生します。

2980013 より大きい maxdate を指定すると、<ILLEGAL VALUE> エラーが発生します。

maxdate を指定する際は、mindate を指定しても指定しなくてもかまいません。mindate より小さい maxdate を指定すると、<ILLEGAL VALUE> エラーが発生します。

erropt

このパラメータに値を指定すると、date 値が無効または範囲外の場合に生じるエラーが抑制されます。$ZDATEH 関数は、<ILLEGAL VALUE> または <VALUE OUT OF RANGE> エラーを生成する代わりに erropt 値を返します。

Caché は、date に対して標準の数値評価を実行します。これは常に 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 パラメータは、date の無効な値または範囲外の値が原因で生成されるエラーのみを抑制します。他のパラメータの無効な値、または範囲外の値が原因で発生したエラーについては、erropt が指定されているかどうかに関係なく、常にエラーが生成されます。例えば、$ZDATEH でendwin が startwin より前になるスライディング・ウィンドウを指定すると、常に <ILLEGAL VALUE> エラーが発生します。同様に、maxdate が mindate より小さい場合、<ILLEGAL VALUE> エラーが発生します。

localeopt

このブーリアン・パラメータには、ロケールで指定されるパラメータ dformat、monthlist、yearopt、mindate、および maxdate の既定値のソースとして、ユーザの現在のロケール定義または ODBC のロケール定義が指定されます。

• localeopt=0 の場合は、これらすべてのパラメータで現在のロケール定義の既定値が使用されます。

• localeopt=1 の場合は、これらすべてのパラメータで ODBC の既定値が使用されます。

• localeopt が未指定の場合は、dformat パラメータによってこれらのパラメータの既定値が決定されます。dformat=3 の場合は、ODBC の既定値が使用されます。dformat が 18、19、20、または 21 の場合は、現在のロケール定義に関係なく、イスラム暦の日付形式の既定値が使用されます。dformat がそれ以外の値の場合は、現在のロケール定義の既定値が使用されます。詳細は、"dformat" の説明を参照してください。

ODBC ロケールは変更できません。これは、各国語サポート (NLS) の選択が異なる Caché プロセス間で移植できる日付文字列をフォーマットするために使用されます。localeopt=1 の場合、ODBC ロケールの日付定義は以下のとおりです。

• 日付形式の既定は 3 です。したがって、dformat が未定義または -1 の場合は、日付形式 3 が使用されます。

• 日付の区切り文字の既定は "/" です。ただし、日付形式の既定は 3 で、これは日付の区切り文字として "-" を常に使用します。

• 年のオプションの既定は 4 桁です。

• 日付の最小値は 0 で、最大値は 2980013 ($HOROLOG の日数カウント) です。

• 英語の月名、月の省略形、曜日名、および曜日の省略形が使用されます。

$ZDATEH で無効な値

以下の状況では、<FUNCTION> エラーが発生します。

• 無効な dformat コード (-1、1、2、3、4、5、6、7、8、9、および 15 のどれでもない整数値、0、または整数以外の値) を指定した場合。

• 無効な yearopt コード (-1 未満または 6 より大きい整数値、0、整数以外の値) を指定した場合。

• yearopt が 3 あるいは 5 のときに、startwin 値を指定しない場合。

以下の状況では、<ILLEGAL VALUE> エラーが発生します。

• 日付単位 (日、月、年) に無効な値を指定した場合。指定した場合は、<ILLEGAL VALUE> が発行されるのではなく、erropt 値が返されます。

• ODBC 日付形式の日付単位 (日、月、年) に余分な先頭のゼロを指定した場合。例えば、2007 年 2 月 3 日は、“2007–2–3” または “2007–02–03” で表せますが、“2007–002–03” に対して <ILLEGAL VALUE> を受け取ります。指定した場合は、<ILLEGAL VALUE> が発行されるのではなく、erropt 値が返されます。

• 指定された月数が monthlist の値よりも大きい場合。

• maxdate が mindate よりも小さい場合。

• endwin が startwin よりも小さい場合。

• startwin と endwin で、期間が 100 年より長い一時的なスライディング・ウィンドウが指定された場合。

以下の状況では、<VALUE OUT OF RANGE> エラーが発生します。

• 1840 年 12 月 31 日より前、あるいは 9999 年 12 月 31 日より後の日付 (あるいは "T" のオフセット) を指定して、erropt 値を指定しない場合。

• mindate と maxdate の範囲外にある、範囲内にあれば有効であった日付 (あるいは “T” のオフセット) を指定し、erropt 値を指定しない場合。

5、6、7、8、9、または 15 を dformat に指定した場合に使用できる日付形式

$ZDATEH の dformat に 5 ～ 9 を指定した日付形式では、曖昧ではないアメリカ形式の日付値をすべて使用できます。$ZDATEH の dformat に 15 を指定した日付形式では、曖昧ではないヨーロッパ形式の日付値をすべて使用できます。これらの日付形式で年を指定していない場合は、現在の年が指定されているものと見なされます。

以下の形式がサポートされています。

MMDD は、実装されていない形式です。

ユーティリティの代わりに使用する $ZDATEH

$ZDATEH 関数と日付ユーティリティのいずれかを選択する必要がある場合、以下の点に注意してください。

• %DATE あるいは %DI ユーティリティにある既存のエントリ・ポイントの代わりに $ZDATEH 関数を使用できます。

• $ZDATEH と $ZDATE は、%DATE、%DI、%DO のエントリ・ポイントの呼び出しよりも高速に処理できます。