Notes C API探訪: ConvertTIMEDATEToText(関数)

ConvertTIMEDATEToText関数は、TIMEDATE型変数に格納されている日時データを、フォーマット情報を元にテキストにします。

#include <misc.h>
STATUS LNPUBLIC ConvertTIMEDATEToText (
  const void far *IntlFormat,
  const TFMT far *TextFormat,
  const TIMEDATE far *InputTime,
  char far *retTextBuffer,
  WORD TextBufferLength,
  WORD far *retTextLength);

IntlFormatは、国際化フォーマットに関する構造体INTLFORMATのデータを指定します。ヌルポインタを指定するとデフォルト値が使用されます。
TextFormatは、出力するパートを選択する構造体TFMTのデータを指定します。ヌルポインタを指定するとデフォルト値が使用されます。
InputTimeは、テキストに変換したい日時データを指定します。
retTextBufferとTextBufferLengthは、出力先となる文字列へのポインタとそのサイズを指定します。通常、MAXALPHATIMEDATE定数＋1のバッファを用意します。
retTextLengthは、実際に出力先の文字列に書き込まれた文字列のサイズが返ります。
戻り値はSTATUS型で、失敗した時はNOERROR値以外になります。

INTLFORMAT

INTLFORMAT構造体は、国際化に関するフォーマット情報で日時の他に通貨に関する情報も含まれています。

#include <intl.h>

// Flags
#define	CURRENCY_SUFFIX 		0x0001
#define	CURRENCY_SPACE			0x0002
#define	NUMBER_LEADING_ZERO		0x0004
#define	CLOCK_24_HOUR			0x0008
#define	DAYLIGHT_SAVINGS		0x0010
#define	DATE_MDY				0x0020
#define	DATE_DMY				0x0040
#define	DATE_YMD				0x0080
#define DATE_4DIGIT_YEAR		0x0100
#define TIME_AMPM_PREFIX		0x0400 
#define	DATE_ABBREV				0x0800

// String size
#define	ISTRMAX 5
#define	YTSTRMAX 32

typedef struct {
  WORD Flags;  // Flags (see above)
  BYTE CurrencyDigits;
  BYTE Length;  // Length of this structure THIS MUST BE SET TO THE EXACT SIZE OF THE STRUCTURE WHEN ITS POINTER IS PASSED AS AN ARGUMENT
  int TimeZone;
  char AMString[ISTRMAX];
  char PMString[ISTRMAX];
  char CurrencyString[ISTRMAX];
  char ThousandString[ISTRMAX];
  char DecimalString[ISTRMAX];
  char DateString[ISTRMAX];
  char TimeString[ISTRMAX];
  char YesterdayString[YTSTRMAX];
  char TodayString[YTSTRMAX];
  char TomorrowString[YTSTRMAX];
} INTLFORMAT;

通常、このフォーマット情報は一から設定する必要はなく、OSGetIntlSettings関数でデフォルト情報を取得し、必要な箇所だけ変更するようにします。

#include <misc.h>
void LNPUBLIC OSGetIntlSettings(
  INTLFORMAT far *retIntlFormat,
  WORD BufferSize);

日本語環境の場合、デフォルトでは以下のような設定値になります。

INTLFORMAT size: 139
Flags: 18c
> CURRENCY_SUFFIX: false
> CURRENCY_SPACE: false
> NUMBER_LEADING_ZERO: true
> CLOCK_24_HOUR: true
> DAYLIGHT_SAVINGS: false
> DATE_MDY: false
> DATE_DMY: false
> DATE_YMD: true
> DATE_4DIGIT_YEAR: true
> TIME_AMPM_PREFIX: false
> DATE_ABBREV: false
CurrencyDigits: 0
Length: 139
TimeZone: -9
AMString: AM
PMString: PM
CurrencyString: ¥
ThousandString: ,
DecimalString: .
DateString: /
TimeString: :
YesterdayString: 昨日
TodayString: 今日
TomorrowString: 明日

なお、ConvertTIMEDATEToText関数でIntlFormat引数にヌルポインタを渡すと、OSGetIntlSettings関数から取得したこのデフォルトのフォーマット情報が利用されています。

TFMT

TFMT構造体は、日時を出力する際にどこを見せて、何を見せないかを定義します。

#include <misc.h>
typedef struct {
  BYTE Date;  /* Date Display Format */
  BYTE Time;  /* Time Display Format */
  BYTE Zone;  /* Time Zone Display Format */
  BYTE Structure;  /* Overall Date/Time Structure */
} TFMT;

Dateは日付に関しての表示、非表示を示します。TDFMT_FULLがデフォルトです。

#include <misc.h>
#define	TDFMT_FULL			0		/* year, month, and day */
#define	TDFMT_CPARTIAL		1		/* month and day, year if not this year */
#define	TDFMT_PARTIAL		2		/* month and day */
#define	TDFMT_DPARTIAL		3		/* year and month */
#define TDFMT_FULL4			4		/* year(4digit), month, and day */
#define TDFMT_CPARTIAL4		5		/* month and day, year(4digit) if not this year */
#define TDFMT_DPARTIAL4		6		/* year(4digit) and month */

Timeは時刻に関しての表示、非表示を示します。TTFMT_FULLがデフォルトです。

#include <misc.h>
#define	TTFMT_FULL			0		/* hour, minute, and second */
#define	TTFMT_PARTIAL		1		/* hour and minute */
#define	TTFMT_HOUR			2		/* hour */

Zoneはタイムゾーンに関しての表示、非表示を示します。TZFMT_NEVERがデフォルトです。

#include <misc.h>
#define	TZFMT_NEVER			0		/* all times converted to THIS zone */
#define	TZFMT_SOMETIMES		1		/* show only when outside this zone */
#define	TZFMT_ALWAYS		2		/* show on all times, regardless */

Structureは全体の構造に関して表示、非表示を示します。TSFMT_DATETIMEがデフォルトです。

#include <misc.h>
#define	TSFMT_DATE			0		/* DATE */
#define	TSFMT_TIME			1		/* TIME */
#define	TSFMT_DATETIME		2		/* DATE TIME */
#define	TSFMT_CDATETIME		3		/* DATE TIME or TIME Today or TIME Yesterday */

なお、ConvertTIMEDATEToText関数でTextFormat引数にヌルポインタを渡すと、各設定値のデフォルトが適用されます。

ConvertTextToTIMEDATE

ConvertTextToTIMEDATE関数は、フォーマットに準じた日時の文字列を日時データに変換します。

#include <misc.h>
STATUS LNPUBLIC ConvertTextToTIMEDATE (
  const void far *IntlFormat,
  const TFMT far *TextFormat,
  char far * far *Text,
  WORD MaxLength,
  TIMEDATE far *retTIMEDATE);

IntlFormatとTextFormatはConvertTIMEDATEToTextと同じです。
TextとMaxLengthにフォーマット化された日時文字列とその長さを指定します。
retTIMEDATEにTIMEDATE変数へのポインタを指定します。

まとめ

Notes/Dominoの日時データに関するトピックを4回に分けて紹介しました。この他にもユリウス日との相互変換用関数や、Tick値(=10ms)に関する便利な定義、TIMEDATE_PAIR型の存在などがあります。TIMEDATE_PAIR型については、複数値についての探訪でご紹介できると思っています。振り返れば、関数の戻り値がTRUEとFALSEで真逆の意味を持ったり、最小単位がミリ秒ではなく10ミリ秒であったり、フォーマットにも独特の仕様があったりと、なかなかクセが強い印象でした。フォーマットについては、Notes/Dominoの「＠関数」に精通している人であれば、@Text関数がこの仕様を受け継いでいる、というか引きずっている印象を持つかもしれませんね。