HP OpenVMS Systems Documentation
HP OpenVMS Programming Concepts Manual
126.96.36.199 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:
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.
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:
A valid input date string would be as follows:
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.
The input format string used to define the input date/time format must contain at least the first seven of the following eight fields:
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:
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.
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:
Punctuation is especially important in providing guidelines for the parser to translate the input date/time string properly.
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:
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).
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.
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.
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:
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:
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-9 lists all predefined time format logical names, their formats, and examples of the output generated using those formats.
188.8.131.52 Specifying Formats at Compile Time
If an application reads text from internal storage or formats text for internal storage or transmission, you should specify the language and format at compile time. The routine LIB$INIT_DATE_TIME_CONTEXT allows the user to specify the language and format at compile time by initializing the context area used by LIB$FORMAT_DATE_TIME for output or LIB$CONVERT_DATE_STRING for input with specific strings, instead of through logical name translations. Note that when the text will be parsed by another program, LIB$INIT_DATE_TIME_CONTEXT expects all required context information (including spellings) to be specified. For applications where the context specifies a user's preferred format style, the spellings can be looked up from the logical name tables.
Only one context component can be initialized per call to LIB$INIT_DATE_TIME_CONTEXT. Table 27-10 lists the available components and their number of elements. (_ABB indicates an abbreviated version of the month and weekday names.)
To specify the actual values for these elements, you must use an initialization string in the following format:
In this format, [-] is a delimiting character that is not in any of the strings, and [string-n] is the spelling of the nth instance of the component.
For example, a string passed to this routine to specify the English spellings of the abbreviated month names might be as follows:
The string must contain the exact number of elements for the associated
component; otherwise the error LIB$_NUMELEMENTS is returned. Note that
the string begins and ends with a delimiter. Thus, there is one more
delimiter than the number of string elements in the initialization
To specify the input format mnemonics at compile time, the user must initialize the component LIB$K_FORMAT_MNEMONICS with the appropriate values. Table 27-11 lists the nine fields that must be initialized, in the appropriate order, along with their default (English) values.
For example, the following is a valid definition of the component LIB$K_FORMAT_MNEMONICS, using English as the natural language:
If the user were entering the same string using Austrian as the natural language, the definition of the component LIB$K_FORMAT_MNEMONICS would be as follows: