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 $