Document revision date: 30 March 2001

This section provides information about using date/time formatting routines that allow you to specify input and output formats other than the standard operating system format for dates and times. These include international formats with appropriate language spellings for days and months.

If the desired language is English (the default language) and the desired format is the standard operating system format, then initialization of logical names is not required in order to use the date/time input and output routines. However, if the desired language and format are not the defaults, the system manager (or any user having CMEXEC, SYSNAM, and SYSPRV privileges) must initialize the required logical names.

27.6.1 Performing Date/Time Logical Initialization

As an alternative to the standard operating system format, the command procedure SYS$MANAGER:LIB$DT_STARTUP.COM defines several output formats for dates and times. This command procedure must be executed by the system manager before using any of the run-time library date/time routines for input or output formats other than the default. Ideally, this command procedure should be executed from a site-specific startup procedure.

In addition to defining the date/time formats, the LIB$DT_STARTUP.COM command procedure also defines spellings for date and time elements in languages other than English. If different language spellings are required, the system manager must define the logical name SYS$LANGUAGES before invoking LIB$DT_STARTUP.COM. The translation of SYS$LANGUAGES is then used to select which languages are defined.

Table 27-5 shows the available languages and their logical names.

Table 27-5 Available Languages for Date/Time Formatting

Language	Logical Name
Austrian	AUSTRIAN
Danish	DANISH
Dutch	DUTCH
Finnish	FINNISH
French	FRENCH
French Canadian	CANADIAN
German	GERMAN
Hebrew	HEBREW
Italian	ITALIAN
Norwegian	NORWEGIAN
Portuguese	PORTUGUESE
Spanish	SPANISH
Swedish	SWEDISH
Swiss French	SWISS_FRENCH
Swiss German	SWISS_GERMAN

For example, if the system managers want the spellings for French, German, and Italian languages to be defined, they must define SYS$LANGUAGES as shown, prior to invoking LIB$DT_STARTUP.COM:

$ DEFINE SYS$LANGUAGES FRENCH, GERMAN, ITALIAN

If the user requires an additional language, for example FINNISH, then the system manager must add FINNISH to the definition of SYS$LANGUAGES and reexecute the command procedure.

Date/Time Manipulation Option

The Date/Time Manipulation option provides date/time spelling support for four new languages. Users or application programmers can select the desired language by defining the logical name SYS$LANGUAGES. The new languages and their equivalent names are as follows:

Language	Equivalent Name
Chinese (simplified character)	Hanzi
Chinese (traditional character)	Hanyu
Korean	Hangul
Thai	Thai

Defining Date/Time Spelling

To define the spelling for Hanzi and Hanyu, define SYS$LANGUAGES as shown below, prior to invoking LIB$DT_STARTUP.COM:

$ DEFINE SYS$LANGUAGES HANZI, HANYU $ @SYS$MANAGER:LIB$DT_STARTUP

Predefined Output Formats

Figure 27-1 lists the new predefined date format logical names in the first column, their formats in the second column, and examples of the output generated using these formats in the third column.

Figure 27-1 Predefined Output Date Formats

Figure 27-2 lists the new predefined time format logical names in the first column, their formats in the second column, and examples of the output generated using these formats in the third column.

Figure 27-2 Predefined Output Time Formats

Thus, to select a particular format for a date or time, or both, you can define the LIB$DT_FORMAT logical name using the following logicals:

• LIB$DATE_FORMAT_nnn, where nnn can range from 001 to 047
• LIB$TIME_FORMAT_nnn, where nnn can range from 001 to 023

There are two methods by which date/time input and output formats can be selected:

• The language and format are determined at run time through the translation of the logical names SYS$LANGUAGE, LIB$DT_FORMAT, and LIB$DT_INPUT_FORMAT.
• The language and format are programmable at compile time through the use of the LIB$INIT_DATE_TIME_CONTEXT routine.

In general, if an application accepts text from a user or formats text for presentation to a user, you should use the logical name method of specifying language and format. With this method, the user assigns equivalence names to the logical names SYS$LANGUAGE, LIB$DT_FORMAT, and LIB$DT_INPUT_FORMAT, thereby selecting the language and input or output format of the date and time at run time.

If an application reads text from internal storage or formats text for internal storage or transmission, the language and format should be specified at compile time. If this is the case, the routine LIB$INIT_DATE_TIME_CONTEXT specifies the language and format of choice.

27.6.2.1 Formatting Run-Time Mnemonics

The format mnemonics listed in Table 27-6 define both input and output formats at run time.

Table 27-6 Format Mnemonics

Date	Explanation
!D0	Day; zero-filled
!DD	Day; no fill
!DB	Day; blank-filled
!WU	Weekday; uppercase
!WAU	Weekday; abbreviated, uppercase
!WC	Weekday; capitalized
!WAC	Weekday; abbreviated, capitalized
!WL	Weekday; lowercase
!WAL	Weekday; abbreviated, lowercase
!MAU	Month; alphabetic, uppercase
!MAAU	Month; alphabetic, abbreviated, uppercase
!MAC	Month; alphabetic, capitalized
!MAAC	Month; alphabetic, abbreviated, capitalized
!MAL	Month; alphabetic, lowercase
!MAAL	Month; alphabetic, abbreviated, lowercase
!MN0	Month; numeric, zero-filled
!MNM	Month; numeric, no fill
!MNB	Month; numeric, blank-filled
!Y4	Year; 4 digits
!Y3	Year; 3 digits
!Y2	Year; 2 digits
!Y1	Year; 1 digit
!Z4	Year; 4 digits
!Z3	Year; 3 digits
!Z2	Year; 2 digits (see LIB$CONVERT_DATE_STRING)
!Z1	Year; 1 digit
Time	Explanation
!H04	Hours; zero-filled, 24-hour clock
!HH4	Hours; no fill, 24-hour clock
!HB4	Hours; blank-filled, 24-hour clock
!H02	Hours; zero-filled, 12-hour clock
!HH2	Hours; no fill, 12-hour clock
!HB2	Hours; blank-filled, 12-hour clock
!M0	Minutes; zero-filled
!MM	Minutes; no fill
!MB	Minutes; blank-filled
!S0	Seconds; zero-filled
!SS	Seconds; no fill
!SB	Seconds; blank-filled
!C7	Fractional seconds; 7 digits
!C6	Fractional seconds; 6 digits
!C5	Fractional seconds; 5 digits
!C4	Fractional seconds; 4 digits
!C3	Fractional seconds; 3 digits
!C2	Fractional seconds; 2 digits
!C1	Fractional seconds; 1 digit
!MIU	Meridiem indicator; uppercase
!MIC	Meridiem indicator; capitalized (mixed case)
!MIL	Meridiem indicator; lowercase

27.6.2.2 Specifying Formats at Run Time

If an application accepts text from a user or formats text for presentation to a user, you should use the logical name method of specifying language and format. With this method, the user assigns equivalence names to the logical names SYS$LANGUAGE, LIB$DT_FORMAT, and LIB$DT_INPUT_FORMAT, thereby selecting the language and format of the date and time at run time. LIB$DT_INPUT_FORMAT must be defined using the mnemonics listed in Table 27-6. The possible choices for SYS$LANGUAGE and LIB$DT_FORMAT are defined in the SYS$MANAGER:LIB$DT_STARTUP.COM command procedure that is executed by the system manager before using these routines.

The following actions occur when any translation of a logical name fails:

• If the translation of SYS$LANGUAGE or any logical name relating to text fails, then English is used and a status of LIB$_ENGLUSED is returned.
• If the translation of LIB$DT_FORMAT, LIB$DT_INPUT_FORMAT, or any logical name relating to format fails, the operating system standard (SYS$ASCTIM) representation of the date and time is used, that is, dd-MMM-yyyy hh:mm:ss.cc, and a status of LIB$_DEFFORUSE is returned.

Since English is the default language and must therefore always be available, English spellings are not taken from logical name translations, but rather are looked up in an internal table.

27.6.2.3 Specifying Input Formats at Run Time

Using the logical name LIB$DT_INPUT_FORMAT, you can define your own input format at run time using the mnemonics listed in Table 27-6. Once an input format is defined, any dates or times that are input to the application are parsed against this format. For example:

$ DEFINE LIB$DT_INPUT_FORMAT - _$ "!MAU !DD, !Y4 !H02:!M0:!S0:!C2 !MIU"

A valid input date string would be as follows:

JUNE 15, 1993 08:45:06:50 PM

If the user has selected a language other than English, then the translation of SYS$LANGUAGE is used by the parser to recognize alphabetic months and meridiem indicators in the selected language.

Input Format String

The input format string used to define the input date/time format must contain at least the first seven of the following eight fields:

• Month (either alphabetic or numeric)
• Day of the month (numeric)
• Year (from 1 to 4 digits)
• Hour (12- or 24-hour clock)
• Minute of the hour
• Second of the minute
• Fractional seconds
• Meridiem indicator (required for 12-hour clock; illegal for 24-hour clock)

If the input format string specifies a 24-hour clock, the string contains only the first seven fields in the preceding list. If a 12-hour clock is specified, the eighth field (the meridiem indicator) is required.

The format string fields must appear in two groups: one for date and one for time (date and time fields cannot be intermixed within a group). For the input format, alphabetic case distinctions and abbreviation-specific codes have no significance. For example, the following format string specifies that the month name will be uppercase and spelled out in full:

!MAU !DD, !Y4 !H02:!M0:!S0:!C2 !MIU

If the input string corresponding to this format string contains a month name that is abbreviated and lowercase, the parse of the input string still works correctly. For example:

feb 25, 1988 04:39:02:55 am

If this input string is entered, the parse still recognizes "feb" as the month name and "am" as the meridiem indicator, even though the format string specified both of these fields as uppercase, and the month name as unabbreviated.

Punctuation in the Format and Input Strings

One important aspect to consider when formatting date/time input strings is punctuation. The punctuation referred to here is the characters that separate the various date/time fields or the date and time groups. Punctuation in these strings is important because it is used as an outline for the parser, allowing the parser to synchronize the input fields to the format fields.

There are three distinct classes of punctuation:

• None Although it is common for no punctuation to begin or end an input format string, you can specify a date/time format that also has no punctuation between the fields or groups of the format string. If this is the case, the corresponding input string must not have any punctuation between the respective fields or groups, although white space (see the next item in this list) may appear at the beginning or end of the input string.
• White space White space includes any combination of spaces and tabs. In the interpretation of the format string, any white space is condensed to a single space. When parsing an input string, white space is generally noted as synchronizing punctuation and is skipped; however, white space is significant in some situations, such as with blank-filled numbers.
• Explicit Explicit punctuation refers to any string of one or more characters that is used as punctuation and is not solely comprised of white space. Any white space appearing within an explicit punctuation string is interpreted literally; in other words, the white space is not compressed. In the format string, you can use explicit punctuation to denote a particular format and to guide the parser in parsing the input string. In the input string, you can use explicit punctuation to synchronize the parse of the input string against the format string. The explicit punctuation used should not be a subset of the valid input of any field that it precedes or follows it.

Punctuation is especially important in providing guidelines for the parser to translate the input date/time string properly.

Default Date/Time Fields

Punctuation in a date/time string is also useful for specifying which fields you want to omit in order to accept the default values. That is, you can control the parsing of the input string by supplying punctuation without the appropriate field values. If only the punctuation is supplied and a user-supplied default is not specified, the value of the omitted field defaults according to the following rules:

• For the date group, the default is the current date.
• For the time group, the default is 00:00:00.00.

Table 27-7 gives some examples of input strings (using punctuation to indicate defaulted fields) and their full translations (assuming a current date of 25-FEB-1993 and using the default input format).

Table 27-7 Input String Punctuation and Defaults

Input	Full Date/Time Input String
31	31-FEB-1993 00:00:00.00
-MAR	25-MAR-1993 00:00:00.00
-SEPTEMBER	25-SEP-1993 00:00:00.00
-1993	25-FEB-1993 00:00:00.00
23:	25-FEB-1993 23:00:00.00
:45:	25-FEB-1993 00:45:00.00
::23	25-FEB-1993 00:00:23.00
.01	25-FEB-1993 00:00:00.01

Note on the Changing Century

Because the default is the current date for the date group, if you specify a value of 00 with the !Y2 format, the year is interpreted as 1900. After January 1, 2000, the value 00 will be interpreted as 2000.

For example, 02/29/00 is interpreted as 29-FEB-1900, which results in LIB$_INVTIME because 1900 is not a leap year. After the turn of the century (the year 2000), 02/29/00 will be 29-FEB-2000, which is a valid date because 2000 is a leap year.

27.6.2.4 Specifying Output Formats at Run Time

If the logical name method is used to specify an output format at run time, the translations of the logical names SYS$LANGUAGE and LIB$DT_FORMAT specify one or more executive mode logical names which in turn must be translated to determine the actual format string. These additional logical names supply such things as the names of the days of the week and the months in the selected language (as determined by SYS$LANGUAGE). All of these logicals are predefined, so that a nonprivileged user can select any one of these languages and formats. In addition, a user can create his or her own languages and formats; however, the CMEXEC, SYSNAM and SYSPRV privileges are required.

To select a particular format for a date or time, or both, you must define the LIB$DT_FORMAT logical name using the following:

• LIB$DATE_FORMAT_nnn, where nnn ranges from 001 to 040
• LIB$TIME_FORMAT_nnn, where nnn ranges from 001 to 020

The order in which these logical names appear in the definition of LIB$DT_FORMAT determines the order in which they are output. A single space is inserted into the output string between the two elements, if the definition specifies that both are output. For example:

$ DEFINE LIB$DT_FORMAT LIB$DATE_FORMAT_006, LIB$TIME_FORMAT_012

This definition causes the date to be output in the specified format, followed by a space and the time in the specified format, as follows:

13 JAN 93 9:13 AM

Table 27-8 lists all predefined date format logical names, their formats, and examples of the output generated using those formats. (The mnemonics used to specify the formats are listed in Table 27-6.)

Table 27-8 Predefined Output Date Formats

Date Format Logical Name	Format	Example
LIB$DATE_FORMAT_001	!DB-!MAAU-!Y4	13-JAN-1993
LIB$DATE_FORMAT_002	!DB !MAU !Y4	13 JANUARY 1993
LIB$DATE_FORMAT_003	!DB.!MAU !Y4	13.JANUARY 1993
LIB$DATE_FORMAT_004	!DB.!MAU.!Y4	13.JANUARY.1993
LIB$DATE_FORMAT_005	!DB !MAU !Y2	13 JANUARY 93
LIB$DATE_FORMAT_006	!DB !MAAU !Y2	13 JAN 93
LIB$DATE_FORMAT_007	!DB.!MAAU !Y2	13.JAN 93
LIB$DATE_FORMAT_008	!DB.!MAAU.!Y2	13.JAN.93
LIB$DATE_FORMAT_009	!DB !MAAU !Y4	13 JAN 1993
LIB$DATE_FORMAT_010	!DB.!MAAU !Y4	13.JAN 1993
LIB$DATE_FORMAT_011	!DB.!MAAU.!Y4	13.JAN.1993
LIB$DATE_FORMAT_012	!MAU !DD, !Y4	JANUARY 13, 1993
LIB$DATE_FORMAT_013	!MN0/!D0/!Y2	01/13/93
LIB$DATE_FORMAT_014	!MN0-!D0-!Y2	01-13-93
LIB$DATE_FORMAT_015	!MN0.!D0.!Y2	01.13.93
LIB$DATE_FORMAT_016	!MN0 !D0 !Y2	01 13 93
LIB$DATE_FORMAT_017	!D0/!MN0/!Y2	13/01/93
LIB$DATE_FORMAT_018	!D0/!MN0-!Y2	13/01-93
LIB$DATE_FORMAT_019	!D0-!MN0-!Y2	13-01-93
LIB$DATE_FORMAT_020	!D0.!MN0.!Y2	13.01.93
LIB$DATE_FORMAT_021	!D0 !MN0 !Y2	13 01 93
LIB$DATE_FORMAT_022	!Y2/!MN0/!D0	93/01/13
LIB$DATE_FORMAT_023	!Y2-!MN0-!D0	93-01-13
LIB$DATE_FORMAT_024	!Y2.!MN0.!D0	93.01.13
LIB$DATE_FORMAT_025	!Y2 !MN0 !D0	93 01 13
LIB$DATE_FORMAT_026	!Y2!MN0!D0	930113
LIB$DATE_FORMAT_027	/!Y2.!MN0.!D0	/93.01.13
LIB$DATE_FORMAT_028	!MN0/!D0/!Y4	01/13/1993
LIB$DATE_FORMAT_029	!MN0-!D0-!Y4	01-13-1993
LIB$DATE_FORMAT_030	!MN0.!D0.!Y4	01.13.1993
LIB$DATE_FORMAT_031	!MN0 !D0 !Y4	01 13 1993
LIB$DATE_FORMAT_032	!D0/!MN0/!Y4	13/01/1993
LIB$DATE_FORMAT_033	!D0-!MN0-!Y4	13-01-1993
LIB$DATE_FORMAT_034	!D0.!MN0.!Y4	13.01.1993
LIB$DATE_FORMAT_035	!D0 !MN0 !Y4	13 01 1993
LIB$DATE_FORMAT_036	!Y4/!MN0/!D0	1993/01/13
LIB$DATE_FORMAT_037	!Y4-!MN0-!D0	1993-01-13
LIB$DATE_FORMAT_038	!Y4.!MN0.!D0	1993.01.13
LIB$DATE_FORMAT_039	!Y4 !MN0 !D0	1993 01 13
LIB$DATE_FORMAT_040	!Y4!MN0!D0	19930113

	privacy and legal statement
5841PRO_074.HTML