Updated: 11 December 1998

OpenVMS Programming Concepts Manual

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, the logical name method of specifying language and format should be used. 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 is used to specify the language and format of choice.

6.6.2.1 Formatting Run-Time Mnemonics

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

Table 6-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

6.6.2.2 Specifying Formats at Run Time

If an application accepts text from a user or formats text for presentation to a user, the logical name method of specifying language and format should be used. 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 6-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 prior to 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.

6.6.2.3 Specifying Input Formats at Run Time

Using the logical name LIB$DT_INPUT_FORMAT, the user can define his or her own input format at run time using the mnemonics listed in Table 6-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 will contain 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 6-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 6-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.

6.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 6-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 6-6.)

Table 6-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

Table 6-9 lists all predefined time format logical names, their formats, and examples of the output generated using those formats.

Table 6-9 Predefined Output Time Formats

Time Format Logical	Format	Example
LIB$TIME_FORMAT_001	!H04:!M0:!S0.!C2	09:13:25.14
LIB$TIME_FORMAT_002	!H04:!M0:!S0	09:13:25
LIB$TIME_FORMAT_003	!H04.!M0.!S0	09.13.25
LIB$TIME_FORMAT_004	!H04 !M0 !S0	09 13 25
LIB$TIME_FORMAT_005	!H04:!M0	09:13
LIB$TIME_FORMAT_006	!H04.!M0	09.13
LIB$TIME_FORMAT_007	!H04 !M0	09 13
LIB$TIME_FORMAT_008	!HH4:!M0	9:13
LIB$TIME_FORMAT_009	!HH4.!M0	9.13
LIB$TIME_FORMAT_010	!HH4 !M0	9 13
LIB$TIME_FORMAT_011	!H02:!M0 !MIU	09:13 AM
LIB$TIME_FORMAT_012	!HH2:!M0 !MIU	9:13 AM
LIB$TIME_FORMAT_013	!H04!M0	0913
LIB$TIME_FORMAT_014	!H04H!M0m	09H13m
LIB$TIME_FORMAT_015	kl !H04.!M0	kl 09.13
LIB$TIME_FORMAT_016	!H04H!M0'	09H13'
LIB$TIME_FORMAT_017	!H04.!M0 h	09.13 h
LIB$TIME_FORMAT_018	h !H04.!M0	h 09.13
LIB$TIME_FORMAT_019	!HH4 h !MM	9 h 13
LIB$TIME_FORMAT_020	!HH4 h !MM min !SS s	9 h 13 min 25 s

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5841PRO_017.HTML