HP OpenVMS Utility Routines Manual


Previous Contents Index


utc_mulftime

Multiplies a relative binary timestamp by a floating-point value.

Format

#include <utc.h>

int utc_mulftime( *result, *utc1, factor)

Parameters

Input

utc1

Relative binary timestamp.

factor

Real scale factor (double-precision floating-point)

Output

result

Resulting relative binary timestamp.

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.
Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time argument or invalid results.
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); 
                                       
Related Functions utc_multime


utc_multime

Multiplies a relative binary timestamp by an integer factor.

Format

#include <utc.h>

int utc_multime( *result, *utc1, factor)

Parameters

Input

utc1

Relative binary timestamp.

factor

Integer scale factor.

Output

result

Resulting relative binary timestamp.

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.
Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time argument or invalid results.
Example See the sample program for the utc_mulftime routine. Related Functions utc_mulftime

utc_pointtime

Converts a binary timestamp to three binary timestamps that represent the earliest, most likely, and latest time.

Format

#include <utc.h>

int utc_pointtime( *utclp, *utcmp, *utchp, *utc)

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.

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.
Notes All outputs have zero inaccuracy. An error is returned if the input binary timestamp has an infinite inaccuracy. Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time argument.
Example See the sample program for the utc_addtime routine. Related Functions utc_boundtime , utc_spantime

utc_reltime

Converts a relative binary timestamp to a tm structure.

Format

#include <utc.h>

int utc_reltime( *timetm, *tns, *inacctm, *ins, *utc)

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.

Description

The Relative Time routine converts a relative binary timestamp to a tm structure. Additional returns include nanoseconds since time and nanoseconds of inaccuracy.
Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time argument or invalid results.
Example See the sample program for the utc_mulftime routine. Related Functions utc_mkreltime

utc_spantime

Given two (possibly unordered) binary timestamps, returns a single UTC time interval whose inaccuracy spans the two input binary timestamps.

Format

#include <utc.h>

int utc_spantime( *result, *utc1, *utc2)

Parameters

Input

utc1

Binary timestamp.

utc2

Binary timestamp.

Output

result

Spanning timestamp.

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).
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. Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time argument.
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           */ 
Related Functions utc_boundtime , utc_gettime , utc_pointtime


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 <utc.h>

int utc_subtime( *result, *utc1, *utc2)

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:

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.
Notes Although no error is returned, do not use the combination relative time - absolute time. Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time argument or invalid results.
Example See the sample program for the utc_binreltime routine. Related Functions utc_addtime

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 <utc.h>

int utc_vmsanytime( *timadr, *utc)

Parameters

Input

*utc

Binary timestamp.

Output

*timadr

Binary OpenVMS format time.

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.
Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time argument or invalid results.
Example See the sample program for the mkvmsanytime routine. Related Functions Function: utc_mkvmsanytime

utc_vmsgmtime

Converts a binary timestamp to a binary OpenVMS format time expressing GMT or the equivalent UTC.

Format

#include <utc.h>

int utc_vmsgmtime( *timadr, *utc)

Parameters

Input

*utc

Binary timestamp to be converted.

Output

*timadr

Binary OpenVMS format time representing GMT or the UTC equivalent.

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.
Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time argument or invalid results.
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 <utc.h> 
 
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 
 *****/ 
Related Functions Function: utc_mkvmsgmtime


utc_vmslocaltime

Converts a binary timestamp to a local binary OpenVMS format time, using the host system's time differential factor.

Format

#include <utc.h>

int utc_vmslocaltime( *timadr, *utc)

Parameters

Input

*utc

Binary timestamp.

Output

*timadr

Binary OpenVMS format time expressing local time.

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 .
Returns
0 Indicates that the routine executed successfully.
--1 Indicates an invalid time argument or invalid results.
Example See the sample program for the vmsgmtime routine. Related Functions Function: utc_vmsmklocaltime

9.6 Example Using the DECdts API Routines

This section contains a C programming example showing a practical application of the DECdts API programming routines. The program performs the following actions:


#include <time.h>   /* time data structures                   */ 
#include <utc.h>    /* 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[Return]
sys$library:dtss$shr.exe/share[Ctrl-z]
$ 


Previous Next Contents Index