Date Conversion

Format

D [ n ] [ *m ] [ s ] [ fmt [ [ f1,  f2, f3, f4, f5 ] ] ] [ E ] [ L ]

The D code converts input dates from conventional formats to an internal format for storage. It also converts internal dates back to conventional formats for output. When converting an input date to internal format, date conversion specifies the format you use to enter the date. When converting internal dates to external format, date conversion defines the external format for the date.

If the D code does not specify a year, the current year is assumed. If the code specifies the year in two-digit form, the years from 0 through 29 mean 2000 through 2029, and the years from 30 through 99 mean 1930 through 1999.

You can set the default date format with the DATE.FORMAT command. A system-wide default date format can be set in the msg.text file of the UV account directory. Date conversions specified in file dictionaries or in ICONV or OCONV functions use the default date format except where they specifically override it. When NLS locales are enabled, the locale overrides any value set in the msg.text file.

Table 1. Override values
Value	Meaning	Special format options
n	Single digit (normally 1 through 4) that specifies the number of digits of the year to output. The default is 4.
*	Any single nonnumeric character that separates the fields in the case where the conversion must first do a group extraction to obtain the internal date. * cannot be a system delimiter.
m	Single digit that must accompany any use of an asterisk. It denotes the number of asterisk-delimited fields to skip in order to extract the date.
s	Any single nonnumeric character to separate the day, month, and year on output. s cannot be a system delimiter. If you do not specify s, the date is converted in 09 SEP 1996 form, unless a format option overrides it.
	If NLS locales are enabled and you do not specify a separator character or n, the default date form is 09 SEP 1996. If the Time category is active, the conversion code in the D_FMT field is used.
	If NLS locales are enabled and you do not specify an s or format option, the order and the separator for the day/month/year defaults to the format defined in the DI_FMT or in the D_FMT field. If the day/month/year order cannot be determined from these fields, the conversion uses the order defined in the DEFAULT_DMY_ORDER field. If you do not specify s and the month is numeric, the separator character comes from the DEFAULT_DMY_SEP field.
fmt	Specifies up to five of the following special format options that let you request the day, day name, month, year, and era name:
	Y [ n ]	Requests only the year number (n digits).
	YA	Requests only the name of the Chinese calendar year. If NLS locales are enabled, uses the YEARS field in the NLS.LC.TIME file.
	M	Requests only the month number (1 through 12).
	MA	Requests only the month name. If NLS locales are enabled, uses the MONS field in the NLS.LC.TIME file. You can use any combination of upper- and lowercase letters for the month; InfoSphere® DataStage® checks the combination against the ABMONS field, otherwise the MONS field.
	MB	Requests only the abbreviated month name. If NLS locales are enabled, uses the ABMONS field in the NLS.LC.TIME file; otherwise, uses the first three characters of the month name.
	MR	Requests only the month number in Roman numerals (I through XII).
	D	Requests only the day number within the month (1 through 31).
	W	Requests only the day number within the week (1 through 7, where Sunday is 7). If NLS locales are enabled, uses the DAYS field in the NLS.LC.TIME file, where Sunday is 1.
	WA	Requests only the day name. If NLS locales are enabled, uses the DAYS field in the NLS.LC.TIME file, unless modified by the format modifiers, f1, f2, and so forth.
	WB	Requests only the abbreviated day name. If NLS locales are enabled, uses the ABDAYS field in the NLS.LC.TIME file.
	Q	Requests only the quarter number within the year (1 through 4).
	J	Requests only the day number within the year (1 through 366).
	N	Requests only the year within the current era. If NLS locales are enabled, uses the ERA STARTS field in the NLS.LC.TIME file.
	NA	Requests only the era name corresponding to the current year. If NLS locales are enabled, uses the ERA NAMES or ERA STARTS fields in the NLS.LC.TIME file.
	Z	Requests only the time-zone name, using the name from the operating system.
[ f1, f2, f3, f4, f5 ]
	f1, f2, f3, f4, and f5 are the format modifiers for the format options. The brackets are part of the syntax and must be typed. You can specify up to five modifiers, which correspond to the options in fmt, respectively. The format modifiers are positional parameters: if you want to specify f3 only, you must include two commas as placeholders. Each format modifier must correspond to a format option. The value of the format modifiers can be any of the following:
	n	Specifies how many characters to display. n can modify any format option, depending on whether the option is numeric or text.
		If numeric, (D, M, W, Q, J, Y, 0), n prints n digits, right-justified with zeros. If text (MA, MB, WA, WB, YA, N, "text"), n left-justifies the option within n spaces.
	A[n]	Month format is alphabetic. n is a number from 1 through 32 specifying how many characters to display. Use A with the Y, M, W, and N format options.
	Z[n]	Suppresses leading zeros in day, month, or year. n is a number from 1 through 32 specifying how many digits to display. Z works like n, but zero-suppresses the output for numeric options.
	`text'	Any text enclosed in single or double quotation marks is treated as if there were no quotation marks and placed after the text produced by the format option in the equivalent position. Any separator character is ignored. `text' can modify any option.
E	Toggles the European (day/month/year) versus the U.S. (month/day/year) formatting of dates. Since the NLS.LC.TIME file specifies the default day/month/year order, E is ignored if you use a time convention.
L	Specifies that lowercase letters should be retained in month or day names; otherwise the routine converts names to all capitals. Since the NLS.LC.TIME file specifies the capitalization of names, L is ignored if you use a time convention.

The following table shows the format options you can use together:

Format Option: Use with These Options
Y: M, MA, D, J, [f1, f2, f3, f4, f5 ]
YA: M, MA, D, [f1, f , f3, f4, f5 ]
M: Y, YA, D, [f1, f2, f3, f4, f5 ]
MA: Y, YA, D, [f1, f2, f3, f4, f5 ]
MB: Y, YA, D, [f1, f2, f3, f4, f5 ]
D: Y, M, [f1, f2, f3, f4, f5 ]
N: Y, M, MA, MB, D, WA [f1, f2, f3, f4, f5 ]
NA: Y, M, MA, MB, D, WA [f1, f2, f3, f4, f5 ]
W: Y, YA, M, MA, D
WA: Y, YA, M, MA, D
WB: Y, YA, M, MA, D
Q: [f1 ]
J: Y, [f1, f2, f3, f4, f5 ]
Z: [f1 ]

Each format modifier must correspond to a format option. The following table shows which modifiers can modify which options:

Table 2. Modifiers and options
Modifier	Option D	Option M	Option Y	Option J	Option W
A	no	yes	yes	no	yes
n	yes	yes	yes	yes	yes
Z	yes	yes	yes	yes	no
`text'	yes	yes	yes	yes	yes

Era Definitions

The ERA_NAMES field can contain a value followed by the format code %n[string].

Table 3. Era definitions
Format code	Value	Explanation
%	The value preceding the % specifies the era name (the fmt option NA for the D code). If there is no % following the value, %1 is the default. The rules are as follows:
	%0-%9	The number following the % (usually 1 or 2) specifies the first year in this era. Often the first year of an era (or part-year of an era) precedes some qualifying characters; therefore, the era is divided into two values, each with the same era name. One value ends in %1string, and the other in %2.
	%+	The era numbers count backwards relative to year numbers (that is, if era year 1 corresponds to Julian year Y, year 2 corresponds to Y-1, year 3 to Y-2, and so forth.
	%-	The same as %+, but uses negative era year numbers (for example, first year Y is -1,Y-1 is -2, y-2 is -3, and so forth.
	%Y	Uses the Julian year numbers for the era year numbers.
n	Single digit (0 through 9) or the characters +, - or Y. These characters specify how to calculate the era number.
string	Any string following the % is appended to the year number returned by the fmt option N.