$ZTIME (ObjectScript)
構文
$ZTIME(htime,tformat,precision,erropt,localeopt)
$ZT(htime,tformat,precision,erropt,localeopt)
引数
引数 | 説明 |
---|---|
htime | 数値、変数名、式として指定できる内部システム時刻 |
tformat | オプション — 時刻の値を返す形式を指定する整数値 |
precision | オプション — 時刻を表すときに、小数点以下の有効桁数を指定する数値省略した場合は、秒の小数部は切り捨てられます。 |
erropt | オプション — htime 引数が無効であると判断された場合に返される式 |
localeopt | オプション — どのロケールを使用するかを指定するブーリアン・フラグ。0 の場合は、現在のロケールが、時刻区切り文字などの文字、文字列、および時刻のフォーマットに使用するオプションを決定します。1 の場合は、ODBC ロケールが、これらの文字、文字列、およびオプションを決定します。ODBC ロケールは変更できません。これは、異なる各国語サポート (NLS) の選択を行った InterSystems IRIS プロセス間で移植できる、日付文字列および時刻文字列をフォーマットするために使用されます。既定値は 0 です。 |
指定の引数値間で省略された引数は、プレースホルダのコンマで示されます。末尾のプレースホルダのコンマは必要ありませんが、あってもかまいません。省略された引数を示すコンマの間に空白があってもかまいません。
概要
$ZTIME 関数は、特殊変数 $HOROLOG や $ZTIMESTAMP の時刻形式で指定された内部システム時刻 htime を、出力可能形式に変換します。オプションの引数を使用しない場合、時刻は “hh:mm:ss” 形式で返されます。“hh” は 24 時間制で表す時刻、“mm” は分、“ss” は秒です。それ以外の場合、時刻は tformat と precision の引数値で指定された形式で返されます。
引数
htime
この値は、その日の午前 0 時 00 分から経過した秒数を表します。$HOROLOG 値の秒の構成要素で、$PIECE($HOROLOG,",",2) を使用して抽出できます。htime は、整数、または precision で指定された精度の小数桁数を持つ小数です。
tformat 値が -1 ~ 4 の場合、htime の有効値は、0 ~ 86399 (-0 は0 として処理される) の範囲の整数部分にする必要があります。この範囲外の値では、<ILLEGAL VALUE> エラーが発生します。tformat 値が 9 および 10 の場合、htime の有効値に負の数字および 86399 より大きい値を含めることもできます。
tformat
サポートされている値は、以下のとおりです。
tformat | 説明 |
---|---|
-1 | 現在のロケールの TimeFormat プロパティから、有効な形式値を取得します。既定は 1 です。tformat を指定せず、localeopt が未指定または 0 の場合は、これが既定になります。 |
1 | 時刻を "hh:mm:ss" (24 時間) で表します。 |
2 | 時刻を “hh:mm” (24 時間) で表します。 |
3 | 時刻を “hh:mm:ss[AM/PM]” (12 時間) で表します。 |
4 | 時刻を “hh:mm[AM/PM]” (12 時間) で表します。 |
ユーザのロケールの既定の時刻形式を決定するには、GetFormatItem()Opens in a new tab NLS クラス・メソッドを呼び出します。
WRITE ##class(%SYS.NLS.Format).GetFormatItem("TimeFormat")
12 時間形式では、午前と午後を時間接尾語で表します。ここでは、AM と PM で表示されています。ユーザのロケールの既定の時間接尾語を決定するには、以下の NLS クラス・メソッドを呼び出します。
WRITE ##class(%SYS.NLS.Format).GetFormatItem("AM"),!
WRITE ##class(%SYS.NLS.Format).GetFormatItem("PM"),!
precision
この関数は、precision 引数で指定された小数点以下の桁数まで、秒の小数部を表示します。例えば precision の値に 3 を入力すると、$ZTIME は秒の小数部を小数点以下 3 桁まで表示します。また、precision が 9 の場合、$ZTIME は秒の小数部を小数点以下 9 桁まで表示します。サポートされている値は、以下のとおりです。
値 | 説明 |
---|---|
-1 | 現在のロケールの TimePrecision プロパティから precision 値を取得します。既定は 0 です。precision を指定しない場合は、これが既定の振る舞いになります。 |
n | ゼロ (0) 以上の n の値は、時刻を小数点以下の n 桁まで表すことを示します。 |
0 | 0 に設定された場合、または既定値の 0 である場合、秒の小数部は切り捨てられます。 |
ユーザのロケールの既定の時刻精度を決定するには、GetFormatItem()Opens in a new tab NLS クラス・メソッドを呼び出します。
WRITE ##class(%SYS.NLS.Format).GetFormatItem("TimePrecision")
erropt
この引数は、無効な htime 値に対応するエラー・メッセージを抑制します。<ILLEGAL VALUE> エラー・メッセージを生成する代わりに、関数は erropt で示された値を返します。
localeopt
この引数は、時刻のオプションのソースとして、ユーザの現在のロケール定義 (0) または ODBC ロケール定義 (1) を選択します。ODBC ロケールは変更できません。これは、異なる各国語サポート (NLS) の選択を行った InterSystems IRIS プロセス間で移植できる、日付文字列および時刻文字列をフォーマットするために使用されます。
ODBC ロケールの時刻定義は、以下のとおりです。
-
時刻形式の既定は 1 です。時刻区切り文字は ":" です。時刻精度は 0 (小数秒なし) です。
-
午前と午後の指定子は、"AM" と "PM" です。"Noon" と "Midnight" という単語が使用されます。
例
特殊変数 $HOROLOG を使用して現在の現地時刻を返すには、$PIECE 関数を使用して、$HOROLOG の秒の部分を指定する必要があります。以下は、24 時間形式 “13:55:11” で時刻を返します。
WRITE $ZTIME($PIECE($HOROLOG,",",2),1)
次の例では、現在時刻に対して htime が $PIECE($HOROLOG,",",2) に設定されています。これらの例は、さまざまな $ZTIME を使用し、異なる時刻形式を返す方法を示しています。
通常、以下の例は、"13:28:55" という形式の時刻を返します。しかし、この形式はロケールに依存します。
SET htime=$PIECE($HOROLOG,",",2)
WRITE $ZTIME(htime)
以下の例は、"13:28:55" の形式で時刻を返します。
SET htime=$PIECE($HOROLOG,",",2)
WRITE $ZTIME(htime,1)
以下の例は、"13:28:550.999" の形式で時刻を返します。
SET htime=$PIECE($HOROLOG,",",2)
WRITE $ZTIME(htime,1,3)
以下の例は、"13:28:55.999999999" の形式で時刻を返します。
SET htime=$PIECE($HOROLOG,",",2)
WRITE $ZTIME(htime,1,9)
以下の例は、"13:28" の形式で時刻を返します。
SET htime=$PIECE($HOROLOG,",",2)
WRITE $ZTIME(htime,2)
以下の例は、"01:28:24PM" の形式で時刻を返します。
SET htime=$PIECE($HOROLOG,",",2)
WRITE $ZTIME(htime,3)
以下の例は、"01:28PM" の形式で時刻を返します。
SET htime=$PIECE($HOROLOG,",",2)
WRITE $ZTIME(htime,4)
以下の例は、“13:45:56.021” の形式で時刻を返します。小数点以下有効桁数 3 桁で現在の UTC 時刻を返します。
SET t=$ZTIME($PIECE($ZTIMESTAMP,",",2),1,3)
WRITE "Current UTC time is ",t
無効な引数値
-
無効な tformat 値を指定すると、<FUNCTION> エラーが返されます。
-
0 ~ 86399 (以下) の許容範囲に含まれない値を htime に指定し、erropt 値を入力していない場合は、9 および 10 を除くすべての tformat に対して <ILLEGAL VALUE> エラーが返されます。
小数点区切り文字
$ZTIME は、整数と小数の区切り文字として、現在のロケールの DecimalSeparator プロパティ値を使用します。DecimalSeparator の既定値は “.” であり、すべてのドキュメントの例でこの区切り文字を使用しています。
ユーザのロケールの既定の小数点区切り文字を決定するには、GetFormatItem()Opens in a new tab NLS クラス・メソッドを呼び出します。
WRITE ##class(%SYS.NLS.Format).GetFormatItem("DecimalSeparator")
時刻区切り文字
既定では、InterSystems IRIS は、現在のロケールの TimeSeparator プロパティ値を使用して、時間文字列の区切り文字を判別します。既定の区切り文字は “:” です。すべてのドキュメントの例でこの区切り文字を使用しています。
ユーザのロケールの既定の時刻区切り文字を決定するには、以下の NLS クラス・メソッドを呼び出します。
WRITE ##class(%SYS.NLS.Format).GetFormatItem("TimeSeparator")
時間接尾語
既定では、InterSystems IRIS は現在のロケールのプロパティを使用して、時間の接尾語名を判別します。$ZTIME で、これらのプロパティ (および、対応する既定値) は以下のとおりです。
-
AM (“AM”)
-
PM (“PM”)
このドキュメントでは、これらのプロパティに常に既定値を使用します。
ユーザのロケールの既定の時間接尾語を決定するには、以下の NLS クラス・メソッドを呼び出します。
WRITE ##class(%SYS.NLS.Format).GetFormatItem("AM"),!
WRITE ##class(%SYS.NLS.Format).GetFormatItem("PM")
関連項目
-
$ZDATETIME 関数
-
$ZDATETIMEH 関数
-
$ZTIMEH 関数
-
$PIECE 関数
-
$HOROLOG 特殊変数
-
$ZTIMESTAMP 特殊変数