HP OpenVMS Systems Documentation
OpenVMS Programming Concepts Manual
220.127.116.11 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:
18.104.22.168 Specifying Output Formats at Compile Time
To specify an output format at compile time, the user must preinitialize the component LIB$K_OUTPUT_FORMAT. Two elements are associated with this output format string. One describes the date format fields, the other the time format fields. The order in which they appear in the string determines the order in which they are output. A single space is inserted into the output stream between the two elements, if the call to LIB$FORMAT_DATE_TIME specifies that both be output. For example:
(These mnemonics are listed in Table 27-6.) This format string represents the format used by the $ASCTIM system service for outputting times. Note that the middle delimiter is replaced by a space in the resultant output.
27.6.3 Converting with the LIB$CONVERT_DATE_STRING Routine
The LIB$CONVERT_DATE_STRING routine converts an absolute date/time string into an operating system internal format date/time quadword. You can optionally specify which fields of the input string can be defaulted (using the input-flags argument), and what the default values should be (using the defaults argument). By default, the time fields can be defaulted but the date fields cannot. Table 27-7 gives some examples of these default values.
You can use the optional defaulted-fields argument to LIB$CONVERT_DATE_STRING to determine which input fields were defaulted. That is, the defaulted-fields argument is a bit mask in which each set bit indicates that the corresponding field was defaulted in the input date/time string.
If you want to use LIB$CONVERT_DATE_STRING to return the current time as well as the current date, you can call the $NUMTIM system service and pass the timbuf argument, which contains the current date and time, to LIB$CONVERT_DATE_STRING as the defaults argument. This tells the LIB$CONVERT_DATE_STRING routine to take the default values for the date and time fields from the 7-word array returned by $NUMTIM.
LIV$CONVERT_DATE_STRING specifies 2-digit years from input by selecting the current century as the default for the century portion of the date. This is true when the !Y2 format is used. This selection may not be desirable for you since 00 would be interpreted as 1900 (and as 2000 on 1/1/2000).
A new format has been added so that you can select a new behavior for LIB$CONVERT_DATE_STRING. You can use the Z format in every place the Y format is used to represent years. The Z format acts exactly like the Y format except for !Z2. Using !Z2 causes LIB$CONVERT_DATE_STRING to interpret a 2-digit year of 99 as 1999 and a 2-digit year of 01 as 2001. The transition year is on a sliding scale determined by the current year minus 43. So if the current year is 1999, the transition year is 56. A 2-digit year greater or equal to this has a century of 1900 and a 2-digit year less than this has a century of 2000. Thus, the year 60 would be 1960 and the year 50 would be 2050. You can use the !Z2 format either in the logical LIB$DT_INPUT_FORMAT, or in the init-string parameter for a call to LIB$INIT_DATE_TIME_CONTEXT to establish the input format for LIB$CONVERT_DATE_STRING. Below is a list of the new Z formats:
27.6.4 Retrieving with LIB$GET_DATE_FORMAT Routine
The LIB$GET_DATE_FORMAT routine enables you to retrieve information about the currently selected input format. The string returned by LIB$GET_DATE_FORMAT parallels the currently defined input format string, consisting of the format punctuation (with most white space compressed) and legible mnemonics representing the various format fields.
Based on the currently defined input date/time format, LIB$GET_DATE_FORMAT returns a string comprised of the mnemonics that represent the current format. These mnemonics are listed in Table 27-11.
Table 27-12 gives some examples of input format strings and their resultant mnemonic strings (using English as the default language).
22.214.171.124 Using User-Defined Output Formats
In addition to the 40 date output formats and 20 time output formats, users can define their own date and time output formats using the logical names LIB$DATE_FORMAT_nnn and LIB$TIME_FORMAT_nnn, where nnn ranges from 501 to 999. (That is, values of nnn from 001 to 500 are reserved for use by Compaq Computer Corporation.) The mnemonics used to define output formats are listed in Table 27-6.
User-defined output formats must be defined as executive-mode logicals, and they must be defined in the table LNM$DT_FORMAT_TABLE. These formats are normally defined from the site-specific startup command procedure. The following example illustrates the steps the system manager must use to create a particular output format using French as the language:
After the system manager defines the desired formats, the user can access them by using the following commands:
In addition to creating their own date and time formats, users can also define their own language tables (provided they have the SYSNAM, SYSPRV and CMEXEC privileges). To create a language table, a user must define all the logical names required.
The following example defines a portion of the Dutch language table. This table is included in its entirety in the set of predefined languages provided with the international date/time formatting routines.
All logical names that are used to build a language are as follows:
The English definition of LIB$FORMAT_MNEMONIC is therefore as follows:
27.7 Coordinated Universal Time Format
This section provides information about VAX systems that supply system base date and time format other than the Smithsonian base date and time system. The other base date and time format system is the Coordinated Universal Time (UTC) system. UTC time is determined by a network of atomic clocks that are maintained by standard bodies in several countries. Formerly, applications that spanned time zones often used Greenwich Mean Time (GMT) as a time reference.
UTC binary timestamps are opaque octawords of 128-bits that contain several fields. Important fields of the UTC format are an absolute time value, a time differential factor (TDF) that contains the offset of the host node's clock from UTC, and an inaccuracy, or tolerance, that can be applied to the absolute time value. Unlike UTC, the operating system binary date and timestamps in the Smithsonian base date and time format represent only the local time of the host node; they do not contain TDF values or inaccuracy values.
The UTC system services allow applications to gain the benefits of a Coordinated Universal Time reference. The UTC system services enable applications to reference a common time standard independent of the host's location and local date and time value.
By calling the UTC system services, applications can perform the following functions:
System services that implement the UTC-format date and time are:
For specific implementation information about the UTC system services, see the OpenVMS System Services Reference Manual.
Some confusion might arise between records in a file and record variables. Where this chapter refers to a record variable, the term record variable is used; otherwise, record refers to a record in a file.
File attributes (organization, record structure, and so on) determine how data is stored and accessed. Typically, the attributes are specified by keywords when you open the data file.
Ordering of the data within a file is not important mechanically.
However, if you attempt to read data without knowing how it is ordered
within the file, you are likely to read the wrong data; if you attempt
to write data without knowing how it is ordered within the file, you
are likely to corrupt existing data.
28.1.1 Specifying File Attributes
You can specify large sets of attributes using the File Definition Language utility (FDL). You can specify all of the file attributes using OpenVMS RMS in a user-open routine (see Section 28.6). Typically, you need only programming language file specifiers. Use FDL only when language specifiers are unavailable.
Refer to the appropriate programming language reference manual for information about the use of language specifiers.
For complete information about how to use FDL, see the OpenVMS Record Management Utilities Reference Manual.
28.2 File Access Strategies
Files are owned by the process that creates them and receive the
default protection of the creating process. To create a file with
ownership and protection other than the default, use the File
Definition Language (FDL) attributes OWNER and PROTECTION in the file.
28.3.1 Read-Only Access
By default, the user of your program must have write access to a file in order for your program to open that file. However, if you specify use of the Fortran READONLY specifier when opening the file, the user needs only read access to the file to open it. The READONLY specifier does not set the protection on a file. The user cannot write to a file opened with the READONLY specifier.