![[OpenVMS documentation]](../../images/openvms_doc_banner_top.gif)
|
![[Site home]](../../images/buttons/bn_site_home_off.gif)
![[Send comments]](../../images/buttons/bn_comments_off.gif)
![[Help with this site]](../../images/buttons/bn_site_help_off.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs_off.gif)
![[OpenVMS site]](../../images/buttons/bn_openvms_off.gif)
![[Compaq site]](../../images/buttons/bn_compaq_off.gif)
|
| Updated: 11 December 1998 |
|
|
|
|
| Updated: 11 December 1998 |
OpenVMS Programming Concepts Manual
| Previous | Contents | Index |
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. 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 6-10 lists the available components and their number of elements. (_ABB indicates an abbreviated version of the month and weekday names.)
| Available Component | Number of Elements |
|---|---|
| LIB$K_MONTH_NAME | 12 |
| LIB$K_MONTH_NAME_ABB | 12 |
| LIB$K_FORMAT_MNEMONICS | 9 |
| LIB$K_WEEKDAY_NAME | 7 |
| LIB$K_WEEKDAY_NAME_ABB | 7 |
| LIB$K_RELATIVE_DAY_NAME | 3 |
| LIB$K_MERIDIEM_INDICATOR | 2 |
| LIB$K_OUTPUT_FORMAT | 2 |
| LIB$K_INPUT_FORMAT | 1 |
| LIB$K_LANGUAGE | 1 |
To specify the actual values for these elements, you must use an initialization string in the following format:
"[delim][string-1][delim][string-2][delim]...[delim][string-n][delim]" |
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:
"|JAN|FEB|MAR|APR|MAY|JUN |JUL|AUG|SEP|OCT|NOV|DEC|" |
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
string.
6.6.2.6 Specifying Input Format Mnemonics at Compile Time
To specify the input format mnemonics at compile time, the user must initialize the component LIB$K_FORMAT_MNEMONICS with the appropriate values. Table 6-11 lists the nine fields that must be initialized, in the appropriate order, along with their default (English) values.
| Order | Format Field | Legible Mnemonic (Default) |
|---|---|---|
| 1 | Year | YYYY |
| 2 | Numeric month | MM |
| 3 | Numeric day | DD |
| 4 | Hours (12- or 24-hour) | HH |
| 5 | Minutes | MM |
| 6 | Seconds | SS |
| 7 | Fractional seconds | CC |
| 8 | Meridiem indicator | AM/PM |
| 9 | Alphabetic month | MONTH |
For example, the following is a valid definition of the component LIB$K_FORMAT_MNEMONICS, using English as the natural language:
|YYYY|MM|DD|HH|MM|SS|CC|AM/PM|MONTH| |
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:
|JJJJ|MM|TT|SS|MM|SS|HH| |MONAT| |
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:
"|!DB-!MAAU-!Y4|!H04:!M0:!S0.!C2|"
(These mnemonics are listed in Table 6-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.
13-JAN-1993 14:54:09:24 |
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 6-7 gives some examples of these default values.
The optional defaulted-fields argument to LIB$CONVERT_DATE_STRING can be used 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 to use 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 then as 2000 on 1/1/2000).
A new format has been added so that a new behavior can be selected for LIB$CONVERT_DATE_STRING. The Z format can be used 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. The !Z2 format can be used 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:
| Date | Explanation |
|---|---|
| !Z4 | Year; 4 digits |
| !Z3 | Year; 3 digits |
| !Z2 | Year; 2 digits (New behavior for the LIB$CONVERT_DATE_STRING routine) |
| !Z1 | Year; 1 digit |
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 6-11.
Table 6-12 gives some examples of input format strings and their resultant mnemonic strings (using English as the default language).
| Sample Format String | LIB$GET_DATE_FORMAT Value |
|---|---|
| !MAU !DD, !Y4 !H04:!M0:!S0:!C2 | MONTH DD, YYYY4 HH:MM:SS:CC2 |
| !MN0-!D0-!Y2 !H04:!M0:!S0.!C2 | MM-DD-YYYY2 HH:MM:SS.CC2 |
| !MN0/!D0/!Y2 !H02:!M0:!S0.!C2 !MIU | MM/DD/YYYY2 HH:MM:SS.CC2 AM/PM |
In addition to the 40 date output formats and 20 time output formats provided, 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 6-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 required of the system manager to create a particular output format using French as the language:
$ DEFINE/EXEC/TABLE=LNM$DT_FORMAT_TABLE LIB$DATE_FORMAT_501 - _$ "!WL, le !DD !MAL !Y4" $ DEFINE/EXEC/TABLE=LNM$DT_FORMAT_TABLE LIB$TIME_FORMAT_501 - _$ "!H04 heures et !M0 minutes" |
After the system manager defines the desired formats, the user can access them by using the following commands:
$ DEFINE SYS$LANGUAGE FRENCH $ DEFINE LIB$DT_FORMAT LIB$DATE_FORMAT_501, LIB$TIME_FORMAT_501 |
mardi, le 20 janvier 1993 13 heures et 50 minutes |
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.
$ CREATE/NAME/PARENT=LNM$SYSTEM_DIRECTORY/EXEC/PROT=(S:RWED,G:R,W:R) - _$ LNM$LANGUAGE_DUTCH $ DEFINE/EXEC/TABLE=LNM$LANGUAGE_DUTCH LIB$WEEKDAYS_L - _$ "maandag", "dinsdag", "woensdag", "donderdag", "vrijdag", - _$ "zaterdag", "zondag" $ DEFINE/EXEC/TABLE=LNM$LANGUAGE_DUTCH LIB$WEEKDAY_ABBREVIATIONS_L - _$ "maa", "din", "woe", "don", "vri", "zat", "zon" $ DEFINE/EXEC/TABLE=LNM$LANGUAGE_DUTCH LIB$MONTHS_L "januari", - _$ "februari", "maart", "april", "mei", "juni", "juli", "augustus", - _$ "september", "oktober", "november", "december" $ DEFINE/EXEC/TABLE=LNM$LANGUAGE_DUTCH LIB$MONTH_ABBREVIATIONS_L - _$ "jan", "feb", "mrt", "apr", "mei", "jun", "jul", "aug", "sep", - _$ "okt", "nov", "dec" $ DEFINE/EXEC/TABLE=LNM$LANGUAGE_AUSTRIAN LIB$RELATIVE_DAYS_L - _$ "gisteren", "vandaag", "morgen" |
All logical names that are used to build a language are as follows:
LIB$WEEKDAYS_[U|L|C]
These logical names supply the names of the weekdays, spelled out in full (uppercase, lowercase, or mixed case). Weekdays must be defined in order, starting with Monday.LIB$WEEKDAY_ABBREVIATIONS_[U|L|C]
These logical names supply the abbreviated names of the weekdays (uppercase, lowercase, or mixed case). Weekday abbreviations must be defined in order, starting with Monday.LIB$MONTHS_[U|L|C]
These logical names supply the names of the months, spelled out in full (uppercase, lowercase, or mixed case). Months must be defined in order, starting with January.LIB$MONTH_ABBREVIATIONS_[U|L|C]
These logical names supply the abbreviated names of the months (uppercase, lowercase, or mixed case). Month abbreviations must be defined in order, starting with January.LIB$MI_[U|L|C]
These logical names supply the spellings for the meridiem indicators (uppercase, lowercase, or mixed case). Meridiem indicators must be defined in order; the first indicator represents the hours 0:00:0.0 to 11:59:59.99, and the second indicator represents the hours 12:00:00.00 to 23:59:59.99.LIB$RELATIVE_DAYS_[U|L|C]
These logical names supply the spellings for the relative days (uppercase, lowercase, or mixed case). Relative days must be defined in order: yesterday, today, and tomorrow, respectively.LIB$FORMAT_MNEMONICS
This logical name supplies the abbreviations for the appropriate format mnemonics. That is, the information supplied in this logical name is used to specify a desired input format in the user-defined language. The format mnemonics, along with their English values, are listed in the order in which they must be defined.
- Year (YYYY)
- Numeric month (MM)
- Day of the month (DD)
- Hour of the day (HH)
- Minutes of the hour (MM)
- Seconds of the minute (SS)
- Parts of the second (CC)
- Meridiem indicator (AM/PM)
- Alphabetic month (MONTH)
The English definition of LIB$FORMAT_MNEMONIC is therefore as follows:
$ DEFINE/EXEC/TABLE=LNM$LANGUAGE_ENGLISH LIB$FORMAT_MNEMONICS - _$ "YYYY", "MM", "DD", "HH", "MM", "SS", "CC", "AM/PM ", "MONTH" |
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.
This chapter describes the run-time library (RTL) routines that allow access to various operating system components. It contains the following sections:
Section 7.1 describes how to use RTL routines to make system services return different types of strings.
Section 7.2 describes how to use RTL routines to provide access to the command language interpreter.
Section 7.3 describes how to use RTL routines to allow high-level language programs to use most VAX machine instructions or their Alpha equivalent.
Section 7.4 describes how to use RTL routines to allocate processwide resources to a single operating system process.
Section 7.5 describes how to use RTL routines to measure performance.
Section 7.6 describes how to use RTL routines to control output formatting.
Section 7.7 describes how to use RTL routines for miscellaneous interface routines.
Run-time library routines allow access to the following operating system components:
You can usually call the OpenVMS system services directly from your program. However, system services return only fixed-length strings. In some applications, you may want the result of a system service to be returned as a character array, dynamic string, or variable-length string. For this reason, the RTL provides jacket routines for the system services that return strings.
You call jacket routines exactly as you would the corresponding system service, but you can pass an output argument of any valid string class. The routines write the output string using the semantics (fixed, varying, or dynamic) associated with the string's descriptor.
The jacket routines follow the conventions established for all RTL routines, except that the arguments are listed in the order of the arguments for the corresponding system service. Thus, they may not be listed in the standard RTL order (read, modify, write).
For example, the LIB$SYS_ASCTIM routine calls the SYS$ASCTIM system service to convert a binary date and time value to ASCII text. It returns the resulting string using the semantics that the calling program specifies in the destination string argument.
For further information about the operations of the system services, see the OpenVMS System Services Reference Manual.
The RTL routines provide access to only the system services that produce output strings, which are listed in Table 7-1. The corresponding RTL routines recognize all VAX string classes.
The RTL does not provide jacket routines for all the system services that accept strings as input. Your program should pass only fixed-length or dynamic input strings to all system services and RTL jacket routines.
| Entry Point | System Service | Function |
|---|---|---|
| LIB$SYS_ASCTIM | $ASCTIM | Converts system time in binary form to ASCII text |
| LIB$SYS_FAO | $FAO | Converts a binary value to ASCII text |
| LIB$SYS_FAOL | $FAOL | Converts a binary value to ASCII text, using a list argument |
| LIB$SYS_GETMSG | $GETMSG | Obtains a system or user-defined message text |
| LIB$SYS_TRNLOG | $TRNLOG | Returns the translation of the specified logical name |
Two command language interpreters (CLIs) are available on the operating system: DCL and MCR. The run-time library provides several routines that provide access to the CLI callback facility. These routines allow your program to call the current CLI. In most cases, these routines are called from programs that execute as part of a command procedure. They allow the command procedure and the CLI to exchange information.
These routines call the CLI associated with the current process to perform the specified function. In some cases, however, a CLI is not present. For example, the program may be running directly as a subprocess or as a detached process. If a CLI is not present, these routines return the status LIB$_NOCLI. Therefore, you should be sure that these routines are called when a CLI is active. Table 7-2 lists the RTL routines that access the CLI.
| Entry Point | Function |
|---|---|
| LIB$GET_FOREIGN | Gets a command line |
| LIB$DO_COMMAND | Executes a command line after exiting the current program |
| LIB$RUN_PROGRAM | Runs another program after exiting the current program (chain) |
| LIB$GET_SYMBOL | Returns the value of a CLI symbol as a string |
| LIB$DELETE_SYMBOL | Deletes a CLI symbol |
| LIB$SET_SYMBOL | Defines or redefines a CLI symbol |
| LIB$DELETE_LOGICAL | Deletes a supervisor-mode process logical name |
| LIB$SET_LOGICAL | Defines or redefines a supervisor-mode process logical name |
| LIB$DISABLE_CTRL | Disables CLI interception of control characters |
| LIB$ENABLE_CTRL | Enables CLI interception of control characters |
| LIB$ATTACH | Attaches a terminal to another process |
| LIB$SPAWN | Creates a subprocess of the current process |
The following routines execute only when the current CLI is DCL:
| Previous | Next | Contents | Index |
|
|
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif) |
|
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
5841PRO_018.HTML
|