1 DECdts You can use the Digital Distributed Time Service (DECdts) programming routines to obtain timestamps that are based on Coordinated Universal Time (UTC). You can also use the DECdts routines to translate among different timestamp formats and perform calculations on timestamps. Applications can use the timestamps that DECdts supplies to determine event sequencing, duration, and scheduling. Applications can call the DECdts routines from DECdts server or clerk systems. The Digital Distributed Time Service routines are written in the C programming language. You should be familiar with the basic DECdts concepts before you attempt to use the applications programming interface (API). The DECdts API routines can perform the following basic functions: o Retrieve timestamp information o Convert between binary timestamps that use different time structures o Convert between binary timestamps and ASCII representations o Convert between UTC time and local time o Convert the binary time values in the OpenVMS (Smithsonian- based) format to or from UTC-based binary timestamps (OpenVMS systems only) o Manipulate binary timestamps o Compare two binary time values o Calculate binary time values o Obtain time zone information DECdts can convert between several types of binary time structures that are based on different calendars and time unit measurements. DECdts uses UTC-based time structures and can convert other types of time structures to its own presentation of UTC-based time. 2 Time_Terminology Absolute time is a point on a time scale; absolute time measurements are derived from system clocks or external time- providers. For DECdts, absolute times reference the UTC standard and include the inaccuracy and other information. When you display an absolute time, DECdts converts the time to ASCII text, as shown in the following display: 1996-11-21-13:30:25.785-04:00I000.082 Relative time is a discrete time interval that is usually added to or subtracted from an absolute time. A time differential factor (TDF) associated with an absolute time is one example of a relative time. Note that a relative time does not use the calendar date fields, because these fields concern absolute time. Coordinated Universal Time (UTC) is the international time standard that DECdts uses. The zero hour of UTC is based on the zero hour of Greenwich Mean Time (GMT). The documentation consistently refers to the time zone of the Greenwich Meridian as GMT. However, this time zone is also sometimes referred to as UTC. The time differential factor (TDF) is the difference between UTC and the time in a particular time zone. OpenVMS systems do not have a default time zone rule. You select a time zone by defining sys$timezone_rule during the sys$manager:net$configure.com procedure, or by explicitly defining sys$timezone_rule. The OpenVMS time structure is based on Smithsonian time, which has a base date of November 17, 1858. The binary OpenVMS structure is a signed, 64-bit integer that has a positive value for absolute times. You can use the DECdts API to translate an OpenVMS structure representing an absolute time to or from the DECdts UTC-based binary timestamp. For detailed information about DECdts time representations, refer to the HP OpenVMS Utility Routines Manual. Unless otherwise specified, the default input and output parameters for the DECDts API routine commands are as follows: o If utc is not specified as an input parameter, the current time is used. o If inacc is not specified as an input parameter, infinity is used. o If no output parameter is specified, no result (or an error) is returned. 2 utc_abstime Computes the absolute value of a relative binary timestamp. Format #include int utc_abstime(result, *utc1) utc_t result; const utc_t *utc1; 3 Parameters Input utc1 Relative binary timestamp. Output result Absolute value of the input relative binary timestamp. 3 Description The Absolute Time routine computes the absolute value of a relative binary timestamp. The input timestamp represents a relative (delta) time. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. 3 Example The following example scales a relative time, computes its absolute value, and prints the result. utc_t relutc, scaledutc; char timstr[UTC_MAX_STR_LEN]; /* * Make sure relative timestamp represents a positive interval... */ utc_abstime(&relutc, /* Out: Abs-value of rel time */ &relutc); /* In: Relative time to scale */ /* * Scale it by a factor of 17... */ utc_multime(&scaledutc, /* Out: Scaled relative time */ &relutc, /* In: Relative time to scale */ 17L); /* In: Scale factor */ utc_ascreltime(timstr, /* Out: ASCII relative time */ UTC_MAX_STR_LEN, /* In: Length of input string */ &scaledutc); /* In: Relative time to */ /* convert */ printf("%s\n",timstr); /* * Scale it by a factor of 17.65... */ utc_mulftime(&scaledutc, /* Out: Scaled relative time */ &relutc, /* In: Relative time to scale */ 17.65); /* In: Scale factor */ utc_ascreltime(timstr, /* Out: ASCII relative time */ UTC_MAX_STR_LEN, /* In: Length of input string */ &scaledutc); /* In: Relative time to */ /* convert */ printf("%s\n",timstr); 2 utc_addtime Computes the sum of two binary timestamps; the timestamps can be two relative times or a relative time and an absolute time. Format #include int utc_addtime(result, *utc1, *utc2) utc_t result; const utc_t *utc1; const utc_t *utc2; 3 Parameters Input utc1 Binary timestamp or relative binary timestamp. utc2 Binary timestamp or relative binary timestamp. Output result Resulting binary timestamp or relative binary timestamp, depending on the operation performed: o relative time + relative time = relative time o absolute time + relative time = absolute time o relative time + absolute time = absolute time o absolute time + absolute time is undefined. See NOTES. 3 Description The Add Time routine adds two binary timestamps, producing a third binary timestamp whose inaccuracy is the sum of the two input inaccuracies. One or both of the input timestamps typically represent a relative (delta) time. The TDF in the first input timestamp is copied to the output. 3 Notes Although no error is returned, do not use the combination absolute time + absolute time. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. 3 Example The following example shows how to compute a timestamp that represents a time at least 5 seconds in the future. utc_t now, future, fivesec; reltimespec_t tfivesec; timespec_t tzero; /* * Construct a timestamp that represents 5 seconds... */ tfivesec.tv_sec = 5; tfivesec.tv_nsec = 0; tzero.tv_sec = 0; tzero.tv_nsec = 0; utc_mkbinreltime(&fivesec, /* Out: 5 secs in binary timestamp */ &tfivesec, /* In: 5 secs in timespec */ &tzero); /* In: 0 secs inaccuracy in timespec */ /* * Get the maximum possible current time... * (NULL input parameter is used to specify the current time.) */ utc_pointtime((utc_t *)0, /* Out: Earliest possible current time */ (utc_t *)0, /* Out: Midpoint of current time */ &now, /* Out: Latest possible current time */ (utc_t *)0);/* In: Use current time */ /* * Add 5 seconds to get future timestamp... */ utc_addtime(&future, /* Out: Future binary timestamp */ &now, /* In: Latest possible time now */ &fivesec); /* In: 5 secs */ 3 Related_Functions utc_subtime 2 utc_anytime Converts a binary timestamp to a tm structure, using the time differential factor (TDF) information contained in the timestamp to determine the TDF returned with the tm structure. Format #include int utc_anytime(timetm, *tns, *inacctm, *ins, *tdf, *utc) struct tm timetm; long *tns; struct tm *inacctm; long *ins; long *tdf; const utc_t *utc; 3 Parameters Input utc Binary timestamp. Output timetm Time component of the binary timestamp expressed in the timestamp's local time. tns Nanoseconds since time component of the binary timestamp. inacctm Seconds of inaccuracy component of the binary timestamp. If the inaccuracy is finite, then tm_mday returns a value of -1 and tm_ mon and tm_year return values of 0. The field tm_yday contains the inaccuracy in days. If the inaccuracy is infinite, all tm structure fields return values of -1. ins Nanoseconds of inaccuracy component of the binary timestamp. tdf TDF component of the binary timestamp in units of seconds east or west of GMT. 3 Description The Any Time routine converts a binary timestamp to a tm structure. The TDF information contained in the timestamp is returned with the time and inaccuracy components; the TDF component determines the offset from GMT and the local time value of the tm structure. Additional returns include nanoseconds since Time and nanoseconds of inaccuracy. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example The following example converts a timestamp, using the TDF information in the timestamp, then prints the result. utc_t evnt; struct tm tmevnt; timespec_t tevnt, ievnt; char tznam[80]; /* * Assume evnt contains the timestamp to convert... * * Get time as a tm structure, using the time zone information in * the timestamp... */ utc_anytime(&tmevnt, /* Out: tm struct of time of evnt */ (long *)0, /* Out: nanosec of time of evnt */ (struct tm *)0, /* Out: tm struct of inacc of evnt */ (long *)0, /* Out: nanosec of inacc of evnt */ (int *)0, /* Out: tdf of evnt */ &evnt); /* In: binary timestamp of evnt */ /* * Get the time and inaccuracy as timespec structures... */ utc_bintime(&tevnt, /* Out: timespec of time of evnt */ &ievnt, /* Out: timespec of inacc of evnt */ (int *)0, /* Out: tdf of evnt */ &evnt); /* In: Binary timestamp of evnt */ /* * Construct the time zone name from time zone information in the * timestamp... */ utc_anyzone(tznam, /* Out: Time zone name */ 80, /* In: Size of time zone name */ (long *)0, /* Out: tdf of event */ (long *)0, /* Out: Daylight saving flag */ &evnt); /* In: Binary timestamp of evnt */ /* * Print timestamp in the format: * * 1991-03-05-21:27:50.023I0.140 (GMT-5:00) * 1992-04-02-12:37:24.003Iinf (GMT+7:00) * */ printf("%d-%02d-%02d-%02d:%02d:%02d.%03d", tmevnt.tm_year+1900, tmevnt.tm_mon+1, tmevnt.tm_mday, tmevnt.tm_hour, tmevnt.tm_min, tmevnt.tm_sec, (tevnt.tv_nsec/1000000)); if ((long)ievnt.tv_sec == -1) printf("Iinf"); else printf("I%d.%03d", ievnt.tv_sec, (ievnt.tv_nsec/1000000)); printf(" (%s)\n", tznam); 3 Related_Functions utc_mkanytime, utc_anyzone, utc_gettime, utc_getusertime, utc_ gmtime, utc_localtime 2 utc_anyzone Gets the time zone label and offset from GMT, using the TDF contained in the input utc. Format #include int utc_anyzone(tzname, tzlen, *tdf, isdst, *utc) char tzname; size_t tzlen; long *tdf; int *isdst; const utc_t *utc; 3 Parameters Input tzlen Length of the tzname buffer. utc Binary time. Output tzname Character string that is long enough to hold the time zone label. tdf Longword with differential in seconds east or west of GMT. isdst Integer with a value of -1, indicating that no information is supplied as to whether it is standard time or daylight saving time. A value of -1 is always returned. 3 Description The Any Zone routine gets the time zone label and offset from GMT, using the TDF contained in the input utc. The label returned is always of the form GMT + n or GMT - n, where n is the TDF expressed in hours:minutes. (The label associated with an arbitrary time zone is not known; only the offset is known.) 3 Notes All of the output parameters are optional. No value is returned and no error occurs if the pointer is null. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or an insufficient buffer. 3 Example See the sample program for the utc_anytime routine. 3 Related_Functions utc_anytime, utc_gmtzone, utc_localzone 2 utc_ascanytime Converts a binary timestamp to an ASCII string that represents an arbitrary time zone. Format #include int utc_ascanytime(*cp, stringlen, *utc) char *cp; size_t stringlen; const utc_t *utc; 3 Parameters Input stringlen The length of the cp buffer. utc Binary timestamp. Output cp ASCII string that represents the time. 3 Description The ASCII Any Time routine converts a binary timestamp to an ASCII string that expresses a time. The TDF component in the timestamp determines the local time used in the conversion. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. 3 Example The following example converts a time to an ASCII string that expresses the time in the time zone where the timestamp was generated. utc_t evnt; char localTime[UTC_MAX_STR_LEN]; /* * Assuming that evnt contains the timestamp to convert, convert * the time to ASCII in the following format: * * 1991-04-01-12:27:38.37-8:00I2.00 */ utc_ascanytime(localtime, /* Out: Converted time */ UTC_MAX_STR_LEN, /* In: Length of string */ &evnt); /* In: Time to convert */ 3 Related_Functions utc_ascgmtime, utc_asclocaltime 2 utc_ascgmtime Converts a binary timestamp to an ASCII string that expresses a GMT time. Format #include int utc_ascgmtime(*cp, stringlen, *utc) char *cp; size_t stringlen; const utc_t *utc; 3 Parameters Input stringlen Length of the cp buffer. utc Binary timestamp. Output cp ASCII string that represents the time. 3 Description The ASCII GMT Time routine converts a binary timestamp to an ASCII string that expresses a time in GMT. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. 3 Example The following example converts the current time to GMT format. char gmTime[UTC_MAX_STR_LEN]; /* * Convert the current time to ASCII in the following format: * * 1991-04-01-12:27:38.37I2.00 */ utc_ascgmtime(gmTime, /* Out: Converted time */ UTC_MAX_STR_LEN, /* In: Length of string */ (utc_t*) NULL); /* In: Time to convert */ /* Default is current time */ 3 Related_Functions utc_ascanytime, utc_asclocaltime 2 utc_asclocaltime Converts a binary timestamp to an ASCII string that represents a local time. Format #include int utc_asclocaltime(*cp, stringlen, *utc) char *cp; size_t stringlen; const utc_t *utc; 3 Parameters Input stringlen Length of the cp buffer. utc Binary timestamp. Output cp ASCII string that represents the time. 3 Description The ASCII Local Time routine converts a binary timestamp to an ASCII string that expresses local time. OpenVMS systems do not have a default time zone rule. You select a time zone by defining sys$timezone_rule during the sys$manager:net$configure.com procedure, or by explicitly defining sys$timezone_rule. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. 3 Example The following example converts the current time to local time. char localTime[UTC_MAX_STR_LEN]; /* * Convert the current time... */ utc_asclocaltime(localTime, /* Out: Converted time */ UTC_MAX_STR_LEN, /* In: Length of string */ (utc_t*) NULL); /* In: Time to convert */ /* Default is current time */ 3 Related_Functions utc_ascanytime, utc_ascgmtime 2 utc_ascreltime Converts a relative binary timestamp to an ASCII string that represents the time. Format #include int utc_ascreltime(*cp, stringlen, *utc) char *cp; const size_t stringlen; const utc_t *utc; 3 Parameters Input utc Relative binary timestamp. stringlen Length of the cp buffer. Output cp ASCII string that represents the time. 3 Description The ASCII Relative Time routine converts a relative binary timestamp to an ASCII string that represents the time. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. 3 Example See the sample program for the utc_abstime routine. 3 Related_Functions utc_mkascreltime 2 utc_binreltime Converts a relative binary timestamp to two timespec structures that express relative time and inaccuracy. Format #include int utc_binreltime(*timesp, *inaccsp, *utc) reltimespec_t *timesp; timespec_t *inaccsp; const utc_t *utc; 3 Parameters Input utc Relative binary timestamp. Output timesp Time component of the relative binary timestamp, in the form of seconds and nanoseconds since the base time (1970-01- 01:00:00:00.0 + 00:00I0). inaccsp Inaccuracy component of the relative binary timestamp, in the form of seconds and nanoseconds. 3 Description The Binary Relative Time routine converts a relative binary timestamp to two timespec structures that express relative time and inaccuracy. These timespec structures describe a time interval. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example The following example measures the duration of a process, then prints the resulting relative time and inaccuracy. utc_t before, duration; reltimespec_t tduration; timespec_t iduration; /* * Get the time before the start of the operation... */ utc_gettime(&before); /* Out: Before binary timestamp */ /* * ...Later... * * Subtract, getting the duration as a relative time. * * NOTE: The NULL argument is used to obtain the current time. */ utc_subtime(&duration, /* Out: Duration rel bin timestamp */ (utc_t *)0, /* In: After binary timestamp */ &before); /* In: Before binary timestamp */ /* * Convert the relative times to timespec structures... */ utc_binreltime(&tduration, /* Out: Duration time timespec */ &iduration, /* Out: Duration inacc timespec */ &duration); /* In: Duration rel bin timestamp */ /* * Print the duration... */ printf("%d.%04d", tduration.tv_sec, (tduration.tv_nsec/10000)); if ((long)iduration.tv_sec == -1) printf("Iinf\n"); else printf("I%d.%04d\n", iduration.tv_sec, (iduration.tv_nsec/100000)); 3 Related_Functions utc_mkbinreltime 2 utc_bintime Converts a binary timestamp to a timespec structure. Format #include int utc_bintime(*timesp, *inaccsp, *tdf, *utc) timespec_t *timesp; timespec_t *inaccsp; long *tdf; const utc_t *utc; 3 Parameters Input utc Binary timestamp. Output timesp Time component of the binary timestamp, in the form of seconds and nanoseconds since the base time. inaccsp Inaccuracy component of the binary timestamp, in the form of seconds and nanoseconds. tdf TDF component of the binary timestamp in the form of signed number of seconds east or west of GMT. 3 Description The Binary Time routine converts a binary timestamp to a timespec structure. The TDF information contained in the timestamp is returned. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example See the sample program for the utc_anytime routine. 3 Related_Functions utc_binreltime, utc_mkbintime 2 utc_boundtime Given two UTC times, one before and one after an event, returns a single UTC time whose inaccuracy includes the event. Format #include int utc_boundtime(*result, *utc1, *utc2) utc_t *result; const utc_t *utc1; const utc_t *utc2; 3 Parameters Input utc1 Before binary timestamp or relative binary timestamp. utc2 After binary timestamp or relative binary timestamp. Output result Spanning timestamp. 3 Description Given two UTC times, the Bound Time routine returns a single UTC time whose inaccuracy bounds the two input times. This is useful for timestamping events; the routine gets the utc values before and after the event, then calls utc_boundtime to build a timestamp that includes the event. 3 Notes The TDF in the output UTC value is copied from the utc2 input. If one or both input values have infinite inaccuracies, the returned time value also has an infinite inaccuracy and is the average of the two input values. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid parameter order. 3 Example The following example records the time of an event and constructs a single timestamp, which includes the time of the event. Note that the utc_getusertime routine is called so the time zone information that is included in the timestamp references the user's environment rather than the system's default time zone. OpenVMS systems do not have a default time zone rule. You select a time zone by defining sys$timezone_rule during the sys$manager:net$configure.com procedure, or by explicitly defining sys$timezone_rule. utc_t before, after, evnt; /* * Get the time before the event... */ utc_getusertime(&before); /* Out: Before binary timestamp */ /* * Get the time after the event... */ utc_getusertime(&after); /* Out: After binary timestamp */ /* * Construct a single timestamp that describes the time of the * event... */ utc_boundtime(&evnt, /* Out: Timestamp that bounds event */ &before, /* In: Before binary timestamp */ &after); /* In: After binary timestamp */ 3 Related_Functions utc_gettime, utc_pointtime, utc_spantime 2 utc_cmpintervaltime Compares two binary timestamps or two relative binary timestamps. Format #include int utc_cmpintervaltime(*relation, *utc1, *utc2) enum utc_cmptype *relation; const utc_t *utc1; const utc_t *utc2; 3 Parameters Input utc1 Binary timestamp or relative binary timestamp. utc2 Binary timestamp or relative binary timestamp. Output relation Receives the result of the comparison of utc1:utc2, where the result is an enumerated type with one of the following values: o utc_equalTo o utc_lessThan o utc_greaterThan o utc_indeterminate 3 Description The Compare Interval Time routine compares two binary timestamps and returns a flag indicating that the first time is greater than, less than, equal to, or overlapping with the second time. Two times overlap if the intervals (time - inaccuracy, time + inaccuracy) of the two times intersect. The input binary timestamps express two absolute or two relative times. Do not compare relative binary timestamps and binary timestamps. If you do, no meaningful results and no errors are returned. This routine does a temporal ordering of the time intervals. utc1 is utc_lessThan utc2 iff utc1.time + utc1.inacc < utc2.time - utc2.inacc utc1 is utc_greaterThan utc2 iff utc1.time - utc1.inacc > utc2.time + utc2.inacc utc1 utc_equalTo utc2 iff utc1.time == utc2.time and utc1.inacc == 0 and utc2.inacc == 0 utc1 is utc_indeterminate with respect to utc2 if the intervals overlap. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument. 3 Example The following example checks to see if the current time is definitely after 1:00 P.M. today GMT. struct tm tmtime, tmzero; enum utc_cmptype relation; utc_t testtime; /* * Zero the tm structure for inaccuracy... */ memset(&tmzero, 0, sizeof(tmzero)); /* * Get the current time, mapped to a tm structure... * * NOTE: The NULL argument is used to get the current time. */ utc_gmtime(&tmtime, /* Out: Current GMT time in tm struct */ (long *)0, /* Out: Nanoseconds of time */ (struct tm *)0, /* Out: Current inaccuracy in tm struct */ (long *)0, /* Out: Nanoseconds of inaccuracy */ (utc_t *)0); /* In: Current timestamp */ /* * Construct a tm structure that corresponds to 1:00 PM... */ tmtime.tm_hour = 13; tmtime.tm_min = 0; tmtime.tm_sec = 0; /* * Convert to a binary timestamp... */ utc_mkgmtime(&testtime, /* Out: Binary timestamp of 1:00 PM */ &tmtime, /* In: 1:00 PM in tm struct */ 0, /* In: Nanoseconds of time */ &tmzero, /* In: Zero inaccuracy in tm struct */ 0); /* In: Nanoseconds of inaccuracy */ /* * Compare to the current time, noting the use of the * NULL argument... */ utc_cmpintervaltime(&relation, /* Out: Comparison relation */ (utc_t *)0, /* In: Current timestamp */ &testtime); /* In: 1:00 PM timestamp */ /* * If it is not later - wait, print a message, etc. */ if (relation != utc_greaterThan) { /* * Note: It could be earlier than 1:00 PM or it could be * indeterminate. If indeterminate, for some applications * it might be worth waiting. */ } 3 Related_Functions utc_cmpmidtime 2 utc_cmpmidtime Compares two binary timestamps or two relative binary timestamps, ignoring inaccuracies. Format #include int utc_cmpmidtime(*relation, *utc1, *utc2) enum utc_cmptype *relation; const utc_t *utc1; const utc_t *utc2; 3 Parameters Input utc1 Binary timestamp or relative binary timestamp. utc2 Binary timestamp or relative binary timestamp. Output relation Result of the comparison of utc1:utc2, where the result is an enumerated type with one of the following values: o utc_equalTo o utc_lessThan o utc_greaterThan 3 Description The Compare Midpoint Times routine compares two binary timestamps and returns a flag indicating that the first timestamp is greater than, less than, or equal to the second timestamp. Inaccuracy information is ignored for this comparison; the input values are, therefore, equivalent to the midpoints of the time intervals described by the input binary timestamps. The input binary timestamps express two absolute or two relative times. Do not compare relative binary timestamps and binary timestamps. If you do, no meaningful results and no errors are returned. The following routine does a lexical ordering on the time interval midpoints. utc1 is utc_lessThan utc2 iff utc1.time < utc2.time utc1 is utc_greaterThan utc2 iff utc1.time > utc2.time utc1 is utc_equalTo utc2 iff utc1.time == utc2.time 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument. 3 Example The following example checks if the current time (ignoring inaccuracies) is after 1:00 P.M. today local time. struct tm tmtime, tmzero; enum utc_cmptype relation; utc_t testtime; /* * Zero the tm structure for inaccuracy... */ memset(&tmzero, 0, sizeof(tmzero)); /* * Get the current time, mapped to a tm structure... * * NOTE: The NULL argument is used to get the current time. */ utc_localtime(&tmtime, /* Out: Current local time in tm struct */ (long *)0, /* Out: Nanoseconds of time */ (struct tm *)0, /* Out: Current inacc in tm struct */ (long *)0, /* Out: Nanoseconds of inaccuracy */ (utc_t *)0); /* In: Current timestamp */ /* * Construct a tm structure that corresponds to 1:00 P.M.... */ tmtime.tm_hour = 13; tmtime.tm_min = 0; tmtime.tm_sec = 0; /* * Convert to a binary timestamp... */ utc_mklocaltime(&testtime, /* Out: Binary timestamp of 1:00 P.M. */ &tmtime, /* In: 1:00 P.M. in tm struct */ 0, /* In: Nanoseconds of time */ &tmzero, /* In: Zero inaccuracy in tm struct */ 0); /* In: Nanoseconds of inaccuracy */ /* * Compare to the current time, noting the use of the * NULL argument... */ utc_cmpmidtime(&relation, /* Out: Comparison relation */ (utc_t *)0, /* In: Current timestamp */ &testtime); /* In: 1:00 P.M. timestamp */ /* * If the time is not later - wait, print a message, etc. */ if (relation != utc_greaterThan) { /* It is not later then 1:00 P.M. local time. Note that * this depends on the setting of the user's environment. */ } 3 Related_Functions utc_cmpintervaltime 2 utc_gettime Returns the current system time and inaccuracy as a binary timestamp. Format #include int utc_gettime(*utc) utc_t *utc; 3 Parameters Input None. Output utc System time as a binary timestamp. 3 Description The Get Time routine returns the current system time and inaccuracy in a binary timestamp. The routine takes the TDF from the operating system's kernel; the TDF is specified in a system-dependent manner. 3 Returns 0 Indicates that the routine executed successfully. -1 Generic error that indicates the time service cannot be accessed. 3 Example See the sample program for the utc_binreltime routine. 2 utc_getusertime Returns the time and process-specific TDF, rather than the system-specific TDF. Format #include int utc_getusertime(*utc) utc_t *utc; 3 Parameters Input None. Output utc System time as a binary timestamp. 3 Description The Get User Time routine returns the system time and inaccuracy in a binary timestamp. The routine takes the TDF from the user's environment, which determines the time zone rule. OpenVMS systems do not have a default time zone rule. You select a time zone by defining sys$timezone_rule during the sys$manager:net$configure.com procedure, or by explicitly defining sys$timezone_rule. 3 Returns 0 Indicates that the routine executed successfully. -1 Generic error that indicates the time service cannot be accessed. 3 Example See the sample program for the utc_boundtime routine. 3 Related_Functions utc_gettime 2 utc_gmtime Converts a binary timestamp to a tm structure that expresses GMT or the equivalent UTC. Format #include int utc_gmtime(*timetm, *tns, *inacctm, *ins, *utc) struct tm *timetm; long *tns; struct tm *inacctm; long *ins; const utc_t *utc; 3 Parameters Input utc Binary timestamp to be converted to tm structure components. Output timetm Time component of the binary timestamp. tns Nanoseconds since time component of the binary timestamp. inacctm Seconds of inaccuracy component of the binary timestamp. If the inaccuracy is finite, then tm_mday returns a value of -1 and tm_ mon and tm_year return values of zero. The field tm_yday contains the inaccuracy in days. If the inaccuracy is infinite, all tm structure fields return values of -1. ins Nanoseconds of inaccuracy component of the binary timestamp. If the inaccuracy is infinite, ins returns a value of -1. 3 Description The Greenwich Mean Time (GMT) routine converts a binary timestamp to a tm structure that expresses GMT (or the equivalent UTC). Additional returns include nanoseconds since time and nanoseconds of inaccuracy. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example See the sample program for the utc_cmpintervaltime routine. 3 Related_Functions utc_anytime, utc_gmtzone, utc_localtime, utc_mkgmtime 2 utc_gmtzone Gets the time zone label for GMT. Format #include int utc_gmtzone(*tzname, tzlen, *tdf, *isdst, *utc) char *tzname; size_t tzlen; long *tdf; int *isdst; const utc_t *utc; 3 Parameters Input tzlen Length of buffer tzname. utc Binary timestamp. This parameter is ignored. Output tzname Character string long enough to hold the time zone label. tdf Longword with differential in seconds east or west of GMT. A value of zero is always returned. isdst Integer with a value of zero, indicating that daylight saving time is not in effect. A value of zero is always returned. 3 Description The Greenwich Mean Time Zone routine gets the time zone label and zero offset from GMT. Outputs are always tdf = 0 and tzname = GMT. This routine exists for symmetry with the Any Zone (utc_ anyzone) and the Local Zone (utc_localzone) routines. 3 Notes All of the output parameters are optional. No value is returned and no error occurs if the tzname pointer is NULL. 3 Returns 0 Indicates that the routine executed successfully (always returned). 3 Example The following example prints out the current time in both local time and GMT time. utc_t now; struct tm tmlocal, tmgmt; long tzoffset; int tzdaylight; char tzlocal[80], tzgmt[80]; /* * Get the current time once, so both conversions use the same * time... */ utc_gettime(&now); /* * Convert to local time, using the process TZ environment * variable... */ utc_localtime(&tmlocal, /* Out: Local time tm structure */ (long *)0, /* Out: Nanosec of time */ (struct tm *)0, /* Out: Inaccuracy tm structure */ (long *)0, /* Out: Nanosec of inaccuracy */ &now); /* In: Current binary timestamp */ /* * Get the local time zone name, offset from GMT, and current * daylight savings flag... */ utc_localzone(tzlocal, /* Out: Local time zone name */ 80, /* In: Length of loc time zone name */ &tzoffset, /* Out: Loc time zone offset in secs */ &tzdaylight, /* Out: Local time zone daylight flag */ &now); /* In: Current binary timestamp */ /* * Convert to GMT... */ utc_gmtime(&tmgmt, /* Out: GMT tm structure */ (long *)0, /* Out: Nanoseconds of time */ (struct tm *)0, /* Out: Inaccuracy tm structure */ (long *)0, /* Out: Nanoseconds of inaccuracy */ &now); /* In: Current binary timestamp */ /* * Get the GMT time zone name... */ utc_gmtzone(tzgmt, /* Out: GMT time zone name */ 80, /* In: Size of GMT time zone name */ (long *)0, /* Out: GMT time zone offset in secs */ (int *)0, /* Out: GMT time zone daylight flag */ &now); /* In: Current binary timestamp */ /* * Print out times and time zone information in the following * format: * * 12:00:37 (EDT) = 16:00:37 (GMT) * EDT is -240 minutes ahead of Greenwich Mean Time. * Daylight savings time is in effect. */ printf("%d:%02d:%02d (%s) = %d:%02d:%02d (%s)\n", tmlocal.tm_hour, tmlocal.tm_min, tmlocal.tm_sec, tzlocal, tmgmt.tm_hour, tmgmt.tm_min, tmgmt.tm_sec, tzgmt); printf("%s is %d minutes ahead of Greenwich Mean Time\n", tzlocal, tzoffset/60); if (tzdaylight != 0) printf("Daylight savings time is in effect\n"); 3 Related_Functions utc_anyzone, utc_gmtime, utc_localzone 2 utc_localtime Converts a binary timestamp to a tm structure that expresses local time. Format #include int utc_localtime(*timetm, *tns, *inacctm, *ins, *utc) struct tm *timetm; long *tns; struct tm *inacctm; long *ins; const utc_t *utc; 3 Parameters Input utc Binary timestamp. Output timetm Time component of the binary timestamp, expressing local time. tns Nanoseconds since time component of the binary timestamp. inacctm Seconds of inaccuracy component of the binary timestamp. If the inaccuracy is finite, then tm_mday returns a value of -1 and tm_ mon and tm_year return values of zero. The field tm_yday contains the inaccuracy in days. If the inaccuracy is infinite, all tm structure fields return values of -1. ins Nanoseconds of inaccuracy component of the binary timestamp. If the inaccuracy is infinite, ins returns a value of -1. 3 Description The Local Time routine converts a binary timestamp to a tm structure that expresses local time. OpenVMS systems do not have a default time zone rule. You select a time zone by defining sys$timezone_rule during the sys$manager:net$configure.com procedure, or by explicitly defining sys$timezone_rule. Additional returns include nanoseconds since time and nanoseconds of inaccuracy. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example See the sample program for the utc_gmtzone routine. 3 Related_Functions utc_anytime, utc_gmtime, utc_localzone, utc_mklocaltime 2 utc_localzone Gets the local time zone label and offset from GMT, given utc. Format #include int utc_localzone(*tzname, tzlen, *tdf, *isdst, *utc) char *tzname; size_t tzlen; long *tdf; int *isdst; const utc_t *utc; #include int utc_localzone(*tzname, tzlen, *tdf, *isdst, *utc) 3 Parameters Input tzlen Length of the tzname buffer. utc Binary timestamp. Output tzname Character string long enough to hold the time zone label. tdf Longword with differential in seconds east or west of GMT. isdst Integer with a value of zero if standard time is in effect or a value of 1 if daylight savings time is in effect. 3 Description The Local Zone routine gets the local time zone label and offset from GMT, given utc. OpenVMS systems do not have a default time zone rule. You select a time zone by defining sys$timezone_rule during the sys$manager:net$configure.com procedure, or by explicitly defining sys$timezone_rule. 3 Notes All of the output parameters are optional. No value is returned and no error occurs if the pointer is null. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or an insufficient buffer. 3 Example See the sample program for the utc_gmtzone routine. 3 Related_Functions utc_anyzone, utc_gmtzone, utc_localtime 2 utc_mkanytime Converts a tm structure and TDF (expressing the time in an arbitrary time zone) to a binary timestamp. Format #include int utc_mkanytime(*utc, *timetm, tns, *inacctm, ins, tdf) utc_t *utc; const struct tm *timetm; long tns; const struct tm *inacctm; long ins; long tdf; 3 Parameters Input timetm A tm structure that expresses the local time; tm_wday and tm_yday are ignored on input. tns Nanoseconds since time component. inacctm A tm structure that expresses days, hours, minutes, and seconds of inaccuracy. If tm_yday is negative, the inaccuracy is considered to be infinite; tm_mday, tm_mon, tm_wday, tm_isdst, tm_gmtoff, and tm_zone are ignored on input. ins Nanoseconds of inaccuracy component. tdf Time differential factor to use in conversion. Output utc Resulting binary timestamp. 3 Description The Make Any Time routine converts a tm structure and TDF (expressing the time in an arbitrary time zone) to a binary timestamp. Required inputs include nanoseconds since time and nanoseconds of inaccuracy. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example The following example converts a string ISO format time in an arbitrary time zone to a binary timestamp. This may be part of an input timestamp routine, although a real implementation will include range checking. utc_t utc; struct tm tmtime, tminacc; float tsec, isec; double tmp; long tnsec, insec; int i, offset, tzhour, tzmin, year, mon; char *string; /* Try to convert the string... */ if(sscanf(string, "%d-%d-%d-%d:%d:%e+%d:%dI%e", &year, &mon, &tmtime.tm_mday, &tmtime.tm_hour, &tmtime.tm_min, &tsec, &tzhour, &tzmin, &isec) != 9) { /* Try again with a negative TDF... */ if (sscanf(string, "%d-%d-%d-%d:%d:%e-%d:%dI%e", &year, &mon, &tmtime.tm_mday, &tmtime.tm_hour, &tmtime.tm_min, &tsec, &tzhour, &tzmin, &isec) != 9) { /* ERROR */ exit(1); } /* TDF is negative */ tzhour = -tzhour; tzmin = -tzmin; } /* Fill in the fields... */ tmtime.tm_year = year - 1900; tmtime.tm_mon = --mon; tmtime.tm_sec = tsec; tnsec = (modf(tsec, &tmp)*1.0E9); offset = tzhour*3600 + tzmin*60; tminacc.tm_sec = isec; insec = (modf(isec, &tmp)*1.0E9); /* Convert to a binary timestamp... */ utc_mkanytime(&utc, /* Out: Resultant binary timestamp */ &tmtime, /* In: tm struct that represents input */ tnsec, /* In: Nanoseconds from input */ &tminacc, /* In: tm struct that represents inacc */ insec, /* In: Nanoseconds from input */ offset); /* In: TDF from input */ 3 Related_Functions utc_anytime, utc_anyzone 2 utc_mkascreltime Converts a null-terminated character string that represents a relative timestamp to a binary timestamp. Format #include int utc_mkascreltime(*utc, *string) utc_t *utc; char *string; 3 Parameters Input string A null-terminated string that expresses a relative timestamp in its ISO format. Output utc Resulting binary timestamp. 3 Description The Make ASCII Relative Time routine converts a null-terminated string, which represents a relative timestamp, to a binary timestamp. 3 Notes The ASCII string must be null-terminated. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. 3 Example The following example converts an ASCII relative time string to its binary equivalent. utc_t utc; char str[UTC_MAX_STR_LEN]; /* * Relative time of 333 days, 12 hours, 1 minute, 37.223 seconds * Inaccuracy of 50.22 sec. in the format: -333-12:01:37.223I50.22 */ (void)strcpy((void *)str, "-333-12:01:37.223I50.22"); utc_mkascreltime(&utc, /* Out: Binary utc */ str); /* In: String */ 3 Related_Functions utc_ascreltime 2 utc_mkasctime Converts a null-terminated character string that represents an absolute time to a binary timestamp. Format #include int utc_mkasctime(*utc, *string) utc_t *utc; char *string; 3 Parameters Input string A null-terminated string that expresses an absolute time. Output utc Resulting binary timestamp. 3 Description The Make ASCII Time routine converts a null-terminated string that represents an absolute time to a binary timestamp. 3 Notes The ASCII string must be null-terminated. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. 3 Example The following example converts an ASCII time string to its binary equivalent. utc_t utc; char str[UTC_MAX_STR_LEN]; /* * July 4, 1776, 12:01:37.223 local time * TDF of -5:00 hours * Inaccuracy of 3600.32 seconds */ (void)strcpy((void *)str, "1776-07-04-12:01:37.223-5:00 I 3600.32"); utc_mkasctime(&utc, /* Out: Binary utc */ str); /* In: String */ 3 Related_Functions utc_ascanytime, utc_ascgmtime, utc_asclocaltime 2 utc_mkbinreltime Converts a timespec structure expressing a relative time to a binary timestamp. Format #include int utc_mkbinreltime(*utc, *timesp, *inaccsp) utc_t *utc; const reltimespec_t *timesp; const timespec_t *inaccsp; 3 Parameters Input timesp A reltimespec structure that expresses a relative time. inaccsp A timespec structure that expresses inaccuracy. If tv_sec is set to a value of -1, the inaccuracy is considered to be infinite. Output utc Resulting relative binary timestamp. 3 Description The Make Binary Relative Time routine converts a timespec structure that expresses relative time to a binary timestamp. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example See the sample program for the utc_addtime routine. 3 Related_Functions utc_binreltime, utc_mkbintime 2 utc_mkbintime Converts a timespec structure to a binary timestamp. Format #include int utc_mkbintime(*utc, *timesp, *inaccsp) utc_t *utc; const timespec_t *timesp; const timespec_t *inaccsp; long tdf; 3 Parameters Input timesp A timespec structure that expresses time since 1970-01- 01:00:00:00.0+0:00I0. inaccsp A timespec structure that expresses inaccuracy. If tv_sec is set to a value of -1, the inaccuracy is considered to be infinite. tdf TDF component of the binary timestamp. Output utc Resulting binary timestamp. 3 Description The Make Binary Time routine converts a timespec structure time to a binary timestamp. The TDF input is used as the TDF of the binary timestamp. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example The following example obtains the current time from time(), converts it to a binary timestamp with an inaccuracy of 5.2 seconds, and specifies GMT. timespec_t ttime, tinacc; utc_t utc; /* * Obtain the current time (without the inaccuracy)... */ ttime.tv_sec = time((time_t *)0); ttime.tv_nsec = 0; /* * Specify the inaccuracy... */ tinacc.tv_sec = 5; tinacc.tv_nsec = 200000000; /* * Convert to a binary timestamp... */ utc_mkbintime(&utc, /* Out: Binary timestamp */ &ttime, /* In: Current time in timespec */ &tinacc, /* In: 5.2 seconds in timespec */ 0); /* In: TDF of GMT */ 3 Related_Functions utc_bintime, utc_mkbinreltime 2 utc_mkgmtime Converts a tm structure that expresses GMT or UTC to a binary timestamp. Format #include int utc_mkgmtime(*utc, *timetm, tns, *inacctm, ins) utc_t *utc; const struct tm *timetm; long tns; const struct tm *inacctm; long ins; 3 Parameters Input timetm A tm structure that expresses GMT. On input, tm_wday and tm_yday are ignored. tns Nanoseconds since time component. inacctm A tm structure that expresses days, hours, minutes, and seconds of inaccuracy. If tm_yday is negative, the inaccuracy is considered to be infinite. On input, tm_mday, tm_mon, tm_wday, tm_isdst, tm_gmtoff, and tm_zone are ignored. ins Nanoseconds of inaccuracy component. Output utc Resulting binary timestamp. 3 Description The Make Greenwich Mean Time routine converts a tm structure that expresses GMT or UTC to a binary timestamp. Additional inputs include nanoseconds since the last second of time and nanoseconds of inaccuracy. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example See the sample program for the utc_cmpintervaltime routine. 3 Related_Functions utc_gmtime 2 utc_mklocaltime Converts a tm structure that expresses local time to a binary timestamp. Format #include int utc_mklocaltime(*utc, *timetm, tns, *inacctm, ins) utc_t *utc; const struct tm *timetm; long tns; const struct tm *inacctm; long ins; 3 Parameters Input timetm A tm structure that expresses the local time. On input, tm_wday and tm_yday are ignored. tns Nanoseconds since time component. inacctm A tm structure that expresses days, hours, minutes, and seconds of inaccuracy. If tm_yday is negative, the inaccuracy is considered to be infinite. On input, tm_mday, tm_mon, tm_wday, tm_isdst, tm_gmtoff, and tm_zone are ignored. ins Nanoseconds of inaccuracy component. Output utc Resulting binary timestamp. 3 Description The Make Local Time routine converts a tm structure that expresses local time to a binary timestamp. OpenVMS systems do not have a default time zone rule. You select a time zone by defining sys$timezone_rule during the sys$manager:net$configure.com procedure, or by explicitly defining sys$timezone_rule. Additional inputs include nanoseconds since the last second of time and nanoseconds of inaccuracy. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example See the sample program for the utc_cmpmidtime routine. 3 Related_Functions utc_localtime 2 utc_mkreltime Converts a tm structure that expresses relative time to a relative binary timestamp. Format #include int utc_mkreltime(*utc, *timetm, tns, *inacctm, ins) utc_t *utc; const struct tm *timetm; long tns; const struct tm *inacctm; long ins; 3 Parameters Input timetm A tm structure that expresses a relative time. On input, tm_wday and tm_yday are ignored. tns Nanoseconds since time component. inacctm A tm structure that expresses seconds of inaccuracy. If tm_yday is negative, the inaccuracy is considered to be infinite. On input, tm_mday, tm_mon, tm_year, tm_wday, tm_isdst, and tm_zone are ignored. ins Nanoseconds of inaccuracy component. Output utc Resulting relative binary timestamp. 3 Description The Make Relative Time routine converts a tm structure that expresses relative time to a relative binary timestamp. Additional inputs include nanoseconds since the last second of time and nanoseconds of inaccuracy. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example The following example converts a string relative time in the format (1991-04-01-12:12:12.12I12.12) to a binary timestamp. This may be part of an input relative timestamp routine, though a real implementation will include range checking. utc_t utc; struct tm tmtime, tminacc; float tsec, isec; double tmp; long tnsec, insec; int i, tzhour, tzmin, year, mon; char *string; /* * Try to convert the string... */ if(sscanf(string, "%d-%d-%d-%d:%d:%eI%e", &year, &mon, &tmtime.tm_mday, &tmtime.tm_hour, &tmtime.tm_min, &tsec, &isec) != 7) { /* * ERROR... */ exit(1); } /* * Fill in the fields... */ tmtime.tm_year = year - 1900; tmtime.tm_mon = --mon; tmtime.tm_sec = tsec; tnsec = (modf(tsec, &tmp)*1.0E9); tminacc.tm_sec = isec; insec = (modf(isec, &tmp)*1.0E9); /* * Convert to a binary timestamp... */ utc_mkreltime(&utc, /* Out: Resultant binary timestamp */ &tmtime, /* In: tm struct that represents input */ tnsec, /* In: Nanoseconds from input */ &tminacc, /* In: tm struct that represents inacc */ insec); /* In: Nanoseconds from input */ 3 Related_Functions utc_reltime 2 utc_mkvmsanytime Converts a binary OpenVMS format time and TDF (expressing the time in an arbitrary time zone) to a binary timestamp. Format #include int utc_mkvmsanytime(*utc, *timadr, tdf) utc_t *utc; const long *timadr; const long tdf; 3 Parameters Input *timadr Binary OpenVMS format time. tdf Time differential factor to use in conversion. Output *utc Binary timestamp. 3 Description The Make VMS Any Time routine converts a binary time in the OpenVMS (Smithsonian) format and an arbitrary TDF to a UTC-based binary timestamp. Because the input and output values are based on different time standards, any input representing a value after A.D. 30,000 returns an error. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example The following example shows how to convert between OpenVMS format binary timestamps and UTC binary timestamps, while specifying the TDF for each. The TDF value determines the offset from GMT and the local time. /***** start example mkvmsanytime,vmsanytime *****/ #include main() { struct utc utcTime; int vmsTime[2]; SYS$GETTIM(vmsTime); /* read the current time */ /* * convert the VMS local time to a UTC, applying a TDF of * -300 minutes (the timezone is -5 hours from GMT) */ if (utc_mkvmsanytime(&utcTime,vmsTime,-300)) exit(1); /* * convert UTC back to VMS local time. A TDF of -300 is applied * to the UTC, since utcTime was constructed with that same value. * This effectively gives us the same VMS time value we started * with. */ if (utc_vmsanytime(vmsTime,&utcTime)) exit(2); } /**** end example ****/ 3 Related_Functions Function: utc_vmsanytime 2 utc_mkvmsgmtime Converts a binary OpenVMS format time expressing GMT (or the equivalent UTC) into a binary timestamp. Format #include int utc_mkvmsgmtime(*utc, *timadr) utc_t *utc; const long *timadr; 3 Parameters Input *timadr Binary OpenVMS format time representing GMT or the UTC equivalent. Output *utc Binary timestamp. 3 Description The Make VMS Greenwich Mean Time routine converts an OpenVMS format binary time representing GMT to a binary timestamp with the equivalent UTC value. Since the input and output values are based on different time standards, any input representing a value after A.D. 30,000 returns an error. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example See the sample program for the vmsgmtime routine. 3 Related_Functions Function: utc_vmsgmtime 2 utc_mkvmslocaltime Converts a local binary OpenVMS format time to a binary timestamp, using the host system's time differential factor. Format #include int utc_mkvmslocaltime(*utc, *timadr) const long *timadr; utc_t *utc; 3 Parameters Input *timadr Binary OpenVMS format time expressing local time. Output *utc Binary timestamp expressing the system's local time. 3 Description The Make VMS Local Time routine converts a binary OpenVMS format time, representing the local time of the host system, to a binary timestamp. The system's local time value is defined by the time zone rule in sys$timezone_rule, which is created by the system configuration process sys$manager:net$configure.com. 3 Notes If the routine call is made during a seasonal time zone change when the local time is indeterminate, an error is returned. For example, if the time zone change occurs at the current local time of 2:00 A.M. to a new local time of 1:00 A.M., and the routine is called between 1:00 A.M. and 2:00 A.M., it cannot be determined which TDF applies. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument, invalid results, or invalid routine call during a time zone change. 3 Example The following example shows how to retrieve the current local time of the system in the binary OpenVMS format, convert the OpenVMS format time to a UTC-based binary timestamp (using the system's TDF), and print an ASCII representation of the binary timestamp. /********* start example mkvmslocaltime *********/ #include main() { char outstring[UTC_MAX_STR_LEN]; struct utc utcTime; int vmsTime[2]; SYS$GETTIM(vmsTime); /* read current time */ if (utc_mkvmslocaltime(&utcTime,vmsTime)) /* convert the local time */ exit(1); /* vmsTime to UTC using */ /* the system tdf. */ /* convert to ISO ascii*/ utc_asclocaltime(outstring,UTC_MAX_STR_LEN,&utcTime); /* format and print */ printf("Current time=> %s\n",outstring); } /***** end example *****/ 3 Related_Functions Function: utc_vmslocaltime 2 utc_mulftime Multiplies a relative binary timestamp by a floating-point value. Format #include int utc_mulftime(*result, *utc1, factor) utc_t *result; const utc_t *utc1; const double factor; 3 Parameters Input utc1 Relative binary timestamp. factor Real scale factor (double-precision floating-point) Output result Resulting relative binary timestamp. 3 Description The Multiply a Relative Time by a Real Factor routine multiplies a relative binary timestamp by a floating-point value. Either or both may be negative; the resulting relative binary timestamp has the appropriate sign. The unsigned inaccuracy in the relative binary timestamp is also multiplied by the absolute value of the floating-point value. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example The following example scales and prints a relative time. utc_t relutc, scaledutc; struct tm sacledreltm; char timstr[UTC_MAX_STR_LEN]; /* * Assume relutc contains the time to scale. * Scale it by a factor of 17... */ utc_multime(&scaledutc, /* Out: Scaled rel time */ &relutc, /* In: Rel time to scale */ 17L); /* In: Scale factor */ utc_ascreltime(timstr, /* Out: ASCII rel time */ UTC_MAX_STR_LEN, /* In: Length of input str */ &scaledutc); /* In: Rel time to convert */ printf("%s\n",timstr); /* * Scale it by a factor of 17.65... */ utc_mulftime(&scaledutc, /* Out: Scaled rel time */ &relutc, /* In: Rel time to scale */ 17.65); /* In: Scale factor */ utc_ascreltime(timstr, /* Out: ASCII rel time */ UTC_MAX_STR_LEN, /* In: Input str length */ &scaledutc); /* In: Rel time to convert */ printf("%s\n",timstr); /* * Convert it to a tm structure and print it. */ utc_reltime(&scaledreltm, /* Out: Scaled rel tm */ (long *)0, /* Out: Scaled rel nano-sec */ (struct tm *)0, /* Out: Scaled rel inacc tm */ (long *)0, /* Out: Scd rel inacc nanos */ &scaledutc); /* In: Rel time to convert */ printf("Approximately %d days, %d hours and %d minutes\n", scaledreltm.tm_yday, scaledreltm.tm_hour, scaledreltm.tm_min); 3 Related_Functions utc_multime 2 utc_multime Multiplies a relative binary timestamp by an integer factor. Format #include int utc_multime(*result, *utc1, factor) utc_t *result; const utc_t *utc1; long factor; 3 Parameters Input utc1 Relative binary timestamp. factor Integer scale factor. Output result Resulting relative binary timestamp. 3 Description The Multiply Relative Time by an Integer Factor routine multiplies a relative binary timestamp by an integer. Either or both may be negative; the resulting binary timestamp has the appropriate sign. The unsigned inaccuracy in the binary timestamp is also multiplied by the absolute value of the integer. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example See the sample program for the utc_mulftime routine. 3 Related_Functions utc_mulftime 2 utc_pointtime Converts a binary timestamp to three binary timestamps that represent the earliest, most likely, and latest time. Format #include int utc_pointtime(*utclp, *utcmp, *utchp, *utc) utc_t *utclp; utc_t *utcmp; utc_t *utchp; const utc_t *utc; 3 Parameters Input utc Binary timestamp or relative binary timestamp. Output utclp Lowest (earliest) possible time that the input binary timestamp or shortest possible relative time that the relative binary timestamp can represent. utcmp Midpoint of the input binary timestamp or the midpoint of the input relative binary timestamp. utchp Highest (latest) possible time that the input binary timestamp or the longest possible relative time that the relative binary timestamp can represent. 3 Description The Point Time routine converts a binary timestamp to three binary timestamps that represent the earliest, latest, and most likely (midpoint) times. If the input is a relative binary time, the outputs represent relative binary times. 3 Notes All outputs have zero inaccuracy. An error is returned if the input binary timestamp has an infinite inaccuracy. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument. 3 Example See the sample program for the utc_addtime routine. 3 Related_Functions utc_boundtime, utc_spantime 2 utc_reltime Converts a relative binary timestamp to a tm structure. Format #include int utc_reltime(*timetm, *tns, *inacctm, *ins, *utc) struct tm *timetm; long *tns; struct tm *inacctm; long *ins; const utc_t *utc; 3 Parameters Input utc Relative binary timestamp. Output timetm Relative time component of the relative binary timestamp. The field tm_mday returns a value of -1 and the fields tm_year and tm_mon return values of zero. The field tm_yday contains the number of days of relative time. tns Nanoseconds since time component of the relative binary timestamp. inacctm Seconds of inaccuracy component of the relative binary timestamp. If the inaccuracy is finite, then tm_mday returns a value of -1 and tm_mon and tm_year return values of zero. The field tm_yday contains the inaccuracy in days. If the inaccuracy is infinite, all tm structure fields return values of -1. ins Nanoseconds of inaccuracy component of the relative binary timestamp. 3 Description The Relative Time routine converts a relative binary timestamp to a tm structure. Additional returns include nanoseconds since time and nanoseconds of inaccuracy. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example See the sample program for the utc_mulftime routine. 3 Related_Functions utc_mkreltime 2 utc_spantime Given two (possibly unordered) binary timestamps, returns a single UTC time interval whose inaccuracy spans the two input binary timestamps. Format #include int utc_spantime(*result, *utc1, *utc2) utc_t *result; const utc_t *utc1; const utc_t *utc2; 3 Parameters Input utc1 Binary timestamp. utc2 Binary timestamp. Output result Spanning timestamp. 3 Description Given two binary timestamps, the Span Time routine returns a single UTC time interval whose inaccuracy spans the two input timestamps (that is, the interval resulting from the earliest possible time of either timestamp to the latest possible time of either timestamp). 3 Notes The tdf in the output UTC value is copied from the utc2 input. If either input binary timestamp has an infinite inaccuracy, an error is returned. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument. 3 Example The following example computes the earliest and latest times for an array of 10 timestamps. utc_t time_array[10], testtime, earliest, latest; int i; /* * Set the running timestamp to the first entry... */ testtime = time_array[0]; for (i=1; i<10; i++) { /* * Compute the minimum and the maximum against the next * element... */ utc_spantime(&testtime, /* Out: Resultant interval */ &testtime, /* In: Largest previous interval */ &time_array[i]); /* In: Element under test */ } /* * Compute the earliest possible time... */ utc_pointtime(&earliest, /* Out: Earliest poss time in array */ (utc_t *)0, /* Out: Midpoint */ &latest, /* Out: Latest poss time in array */ &testtime); /* In: Spanning interval */ 3 Related_Functions utc_boundtime, utc_gettime, utc_pointtime 2 utc_subtime Computes the difference between two binary timestamps that express either an absolute time and a relative time, two relative times, or two absolute times. Format #include int utc_subtime(*result, *utc1, *utc2) utc_t *result; const utc_t *utc1; const utc_t *utc2; 3 Parameters Input utc1 Binary timestamp or relative binary timestamp. utc2 Binary timestamp or relative binary timestamp. Output result Resulting binary timestamp or relative binary timestamp, depending on the operation performed: o absolute time - absolute time = relative time o relative time - relative time = relative time o absolute time - relative time = absolute time o relative time - absolute time is undefined. See NOTES. 3 Description The Subtract Time routine subtracts one binary timestamp from another. The resulting timestamp is utc1 minus utc2. The inaccuracies of the two input timestamps are combined and included in the output timestamp. The TDF in the first timestamp is copied to the output. 3 Notes Although no error is returned, do not use the combination relative time - absolute time. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example See the sample program for the utc_binreltime routine. 3 Related_Functions utc_addtime 2 utc_vmsanytime Converts a binary timestamp to a binary OpenVMS format time. The TDF encoded in the input timestamp determines the TDF of the output. Format #include int utc_vmsanytime(*timadr, *utc) const utc_t *utc; long *timadr; 3 Parameters Input *utc Binary timestamp. Output *timadr Binary OpenVMS format time. 3 Description The VMS Any Time routine converts a UTC-based binary timestamp to a 64-bit binary time in the OpenVMS (Smithsonian) format. Because the input and output values are based on different time standards, any input representing a value before the Smithsonian base time of November 17, 1858 returns an error. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example See the sample program for the mkvmsanytime routine. 3 Related_Functions Function: utc_mkvmsanytime 2 utc_vmsgmtime Converts a binary timestamp to a binary OpenVMS format time expressing GMT or the equivalent UTC. Format #include int utc_vmsgmtime(*timadr, *utc) const utc_t *utc; long *timadr; 3 Parameters Input *utc Binary timestamp to be converted. Output *timadr Binary OpenVMS format time representing GMT or the UTC equivalent. 3 Description The OpenVMS Greenwich Mean Time routine converts a UTC-based binary timestamp to a 64-bit binary time in the OpenVMS (Smithsonian) format. The OpenVMS format time represents Greenwich Mean Time or the equivalent UTC. Because the input and output values are based on different time standards, any input representing a value before the Smithsonian base time of November 17, 1858 returns an error. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example The following example shows the following time zone and time format conversions: 1. Retrieve a binary timestamp representing UTC with the sys$getutc system service. 2. Convert the binary timestamp to a OpenVMS format binary time representing GMT 3. Convert the OpenVMS format binary time representing GMT back to a UTC-based binary timestamp with a TDF of 0 (zero) 4. Convert the UTC-based binary time to a binary OpenVMS format time representing the local time; use the TDF from the system /***** start example vmsgmtime, mkvmsgmtime, vmslocaltime *****/ #include main() { int status; struct utc utcTime; int vmsTime[2]; if (!((status=SYS$GETUTC(&utcTime))&1)) exit(status); /* read curr time as a utc */ /* * convert the utcvalue into a vms time, with a timezone of 0 * (GMT). Printing the resultant vmstime yields the time at * the prime meridian in Greenwich, not (necessarily) the * local time. */ if (utc_vmsgmtime(vmsTime,&utcTime)) exit(1); /* * Convert the vmstime (which is in GMT) to a utc */ if (utc_mkvmsgmtime(&utcTime, vmsTime)) exit(2); /* * convert the UTC to local 64-bit time. Note that this is the * value we would have read if we had issued a 'SYS$GETTIM' in * the initial statement. */ if (utc_vmslocaltime(vmsTime, &utcTime)) exit(3); } /***** end example *****/ 3 Related_Functions Function: utc_mkvmsgmtime 2 utc_vmslocaltime Converts a binary timestamp to a local binary OpenVMS format time, using the host system's time differential factor. Format #include int utc_vmslocaltime(*timadr, *utc) const utc_t *utc; long *timadr; 3 Parameters Input *utc Binary timestamp. Output *timadr Binary OpenVMS format time expressing local time. 3 Description The VMS Local Time routine converts a binary timestamp to a binary OpenVMS format time; the output value represents the local time of the host system. The system's offset from UTC and the local time value are defined by the time zone rule in sys$timezone_rule, which is created by the system configuration process sys$manager:net$configure.com. 3 Returns 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. 3 Example See the sample program for the vmsgmtime routine. 3 Related_Functions Function: utc_vmsmklocaltime 2 Example The following C programming example shows a practical application of the DECdts API programming routines. The program performs the following actions: o Prompts the user to enter time coordinates. o Stores those coordinates in a tm structure. o Converts the tm structure to a utc structure. o Determines which event occurred first. o Determines if Event 1 may have caused Event 2 by comparing the intervals. o Prints out the utc structure in ISO text format. #include /* time data structures */ #include /* utc structure definitions */ void ReadTime(); void PrintTime(); /* * This program requests user input about events, then prints out * information about those events. */ main() { struct utc event1,event2; enum utc_cmptype relation; /* * Read in the two events. */ ReadTime(&event1); ReadTime(&event2); /* * Print out the two events. */ printf("The first event is : "); PrintTime(&event1); printf("\nThe second event is : "); PrintTime(&event2); printf("\n"); /* * Determine which event occurred first. */ if (utc_cmpmidtime(&relation,&event1,&event2)) exit(1); switch( relation ) { case utc_lessThan: printf("comparing midpoints: Event1 < Event2\n"); break; case utc_greaterThan: printf("comparing midpoints: Event1 > Event2\n"); break; case utc_equalTo: printf("comparing midpoints: Event1 == Event2\n"); break; default: exit(1); break; } /* * Could Event 1 have caused Event 2? Compare the intervals. */ if (utc_cmpintervaltime(&relation,&event1,&event2)) exit(1); switch( relation ) { case utc_lessThan: printf("comparing intervals: Event1 < Event2\n"); break; case utc_greaterThan: printf("comparing intervals: Event1 > Event2\n"); break; case utc_equalTo: printf("comparing intervals: Event1 == Event2\n"); break; case utc_indeterminate: printf("comparing intervals: Event1 ? Event2\n"); default: exit(1); break; } } /* * Print out a utc structure in ISO text format. */ void PrintTime(utcTime) struct utc *utcTime; { char string[50]; /* * Break up the time string. */ if (utc_ascgmtime(string, /* Out: Converted time */ 50, /* In: String length */ utcTime)) /* In: Time to convert */ exit(1); printf("%s\n",string); } /* * Prompt the user to enter time coordinates. Store the * coordinates in a tm structure and then convert the * tm structure to a utc structure. */ void ReadTime(utcTime) struct utc *utcTime; { struct tm tmTime,tmInacc; (void)memset((void *)&tmTime, 0,sizeof(tmTime)); (void)memset((void *)&tmInacc, 0,sizeof(tmInacc)); (void)printf("Year? "); (void)scanf("%d",&tmTime.tm_year); tmTime.tm_year -= 1900; (void)printf("Month? "); (void)scanf("%d",&tmTime.tm_mon); tmTime.tm_mon -= 1; (void)printf("Day? "); (void)scanf("%d",&tmTime.tm_mday); (void)printf("Hour? "); (void)scanf("%d",&tmTime.tm_hour); (void)printf("Minute? "); (void)scanf("%d",&tmTime.tm_min); (void)printf("Inacc Secs? "); (void)scanf("%d",&tmInacc.tm_sec); if (utc_mkanytime(utcTime, &tmTime, (long)0, &tmInacc, (long)0, (long)0)) exit(1); } Assume the preceding program is named compare_events.c. To compile and link the program on a DECnet-Plus for OpenVMS system, enter the following command: $ cc compare_events.c/output=compare_events.obj $ link compare_events.obj, sys$input:/options sys$library:dtss$shr.exe/share $