HP OpenVMS Systems Documentation
OpenVMS Programming Concepts Manual
126.96.36.199 Calculating and Displaying Time with SYS$GETTIM and LIB$SUBX
Example 27-1 calculates differences between the current time and a time input in absolute format, and then displays the result as delta time. If the input time is later than the current time, the difference is a negative value (delta time) and can be displayed directly. If the input time is an earlier time, the difference is a positive value (absolute time) and must be converted to delta time before being displayed. To change an absolute time to a delta time, negate the time array by subtracting it from 0 (specified as an integer array) using the LIB$SUBX routine, which performs subtraction on signed two's complement integers of arbitrary length. For the absolute or delta time format, see Section 27.1.1 and Section 27.1.2.
If you are ignoring the time portion of date/time (that is, working
just at the date level), the LIB$DAY routine might simplify your
calculations. LIB$DAY returns to you the number of days from the base
system date to a given date.
The Convert Binary Time to ASCII String (SYS$ASCTIM) system service is the converse of the Convert ASCII String to Binary Time (SYS$BINTIM) system service. You provide the service with the time in the ASCII format shown in Section 27.3.2. The service then converts the string to a time value in 64-bit format. You can use this returned value as input to a timer scheduling service.
When you specify the ASCII string buffer, you can omit any of the fields, and the service uses the current date or time value for the field. Thus, if you want a timer request to be date independent, you could format the input buffer for the SYS$BINTIM service as shown in the following example. The two hyphens that are normally embedded in the date field must be included, and at least one blank must precede the time field.
When the SYS$BINTIM service completes, a 64-bit time value representing
"noon today" is returned in the quadword at BINARY_NOON.
The first field, indicating the number of days, must be specified as 0 if you are specifying a delta time for the current day.
The following example shows how to use the SYS$BINTIM service to obtain a delta time in system format:
If you are programming in VAX MACRO, you can also specify approximate delta time values when you assemble a program, using two MACRO .LONG directives to represent a time value in 100-ns units. The arithmetic is based on the following formula:
For example, the following statement defines a delta time value of 5 seconds:
The value 10 million is expressed as 10*1000*1000 for readability. Note that the delta time value is negative.
If you use this notation, however, you are limited to the maximum
number of 100-ns units that can be expressed in a longword. In time
values this is slightly more than 7 minutes.
The Convert Binary Time to Numeric Time (SYS$NUMTIM) system service converts a time in the system format into binary integer values. The service returns each of the components of the time (year, month, day, hour, and so on) into a separate word of a 7-word buffer. The SYS$NUMTIM system service and the format of the information returned are described in the OpenVMS System Services Reference Manual.
You use the SYS$ASCTIM system service to format the time in ASCII for inclusion in an output string. The SYS$ASCTIM service accepts as an argument the address of a quadword that contains the time in system format and returns the date and time in ASCII format.
If you want to include the date and time in a character string that
contains additional data, you can format the output string with the
Formatted ASCII Output (SYS$FAO) system service. The SYS$FAO system
service converts binary values to ASCII representations, and
substitutes the results in character strings according to directives
supplied in an input control string. Among these directives are !%T and
!%D, which convert a quadword time value to an ASCII string and
substitute the result in an output string. For examples of how to do
this, see the discussion of $FAO in the OpenVMS System Services Reference Manual.
The run-time LIB$ facility provides several date/time manipulation routines. These routines let you add, subtract, and multiply dates and times. Use the LIB$ADDX and LIB$SUBX routines to add and subtract times, since the times are defined in integer arrays. Use LIB$ADD_TIMES and LIB$SUB_TIMES to add and subtract two quadword times. When manipulating delta times, remember that they are stored as negative numbers. For example, to add a delta time to an absolute time, you must subtract the delta time from the absolute time. Use LIB$MULT_DELTA_TIME and LIB$MULTF_DELTA_TIME to multiply delta times by scalar and floating scalar.
Table 27-2 lists all the LIB$ routines that perform date/time manipulation.
27.3 Timer Routines Used to Obtain and Set Current Time
This section presents information about obtaining the current date and time, and setting current time. The run-time library (LIB$) facility provides date/time utility routines for languages that do not have built-in time and date functions. These routines return information about the current date and time or a date/time specified by the user. You can obtain the current time by using the LIB$DATE_TIME routine or by implementing the SYS$GETTIM system service. To set the current time, use the SYS$SETTIME system service.
Table 27-3 describes the date/time routines.
27.3.1 Obtaining Current Time and Date with LIB$DATE_TIME
The LIB$DATE_TIME routine returns a character string containing the current date and time in absolute time format. The full string requires a declaration of 23 characters. If you specify a shorter string, the value is truncated. A declaration of 16 characters obtains only the date. The following example displays the current date and time:
This call to SYS$GETTIM returns the current date and time in system format in the quadword buffer TIME.
The Convert Binary Time to ASCII String (SYS$ASCTIM) system service converts a time in system format to an ASCII string and returns the string in a 23-byte buffer. You call the SYS$ASCTIM system service as follows:
Because the address of a 64-bit time value is not supplied, the default value, 0, is used.
The string the service returns has the following format:
27.3.3 Setting the Current Time with SYS$SETIME
The Set System Time (SYS$SETIME) system service allows a user with the operator (OPER) and logical I/O (LOG_IO) privileges to set the current system time. You can specify a new system time (using the timadr argument), or you can recalibrate the current system time using the processor's hardware time-of-year clock (omitting the timadr argument). If you specify a time, it must be an absolute time value; a delta time (negative) value is invalid.
The system time is set whenever the system is bootstrapped. Normally you do not need to change the system time between system bootstrap operations; however, in certain circumstances you may want to change the system time without rebooting. For example, you might specify a new system time to synchronize two processors, or to adjust for changes between standard time and Daylight Savings Time. Also, you may want to recalibrate the time to ensure that the system time matches the hardware clock time (the hardware clock is more accurate than the system clock).
The DCL command SET TIME calls the SYS$SETIME system service.
If a process issues a delta time request and then the system time is changed, the interval remaining for the request does not change; the request executes after the specified time has elapsed. If a process issues an absolute time request and the system time is changed, the request executes at the specified time, relative to the new system time.
The following example shows the effect of changing the system time on an existing timer request. In this example, two set timer requests are scheduled: one is to execute after a delta time of 5 minutes and the other specifies an absolute time of 9:00.
The following example shows the output received from the preceding program. Assume the program starts execution at 8:45. Seconds later, the system time is set to 9:15. The timer request that specified an absolute time of 9:00 executes immediately, because 9:00 has passed. The request that specified a delta time of 5 minutes times out at 9:20.
27.4 Routines Used for Timer Requests
This section presents information about setting and canceling timer requests, and scheduling and canceling wakeups. Since many applications require the scheduling of program activities based on clock time, the operating system allows an image to schedule events for a specific time of day or after a specified time interval. For example, you can use timer system services to schedule, convert, or cancel events. For example, you can use the timer system services to do the following:
Table 27-4 describes system services that set, cancel, and schedule timer requests.