HP OpenVMS Systems Documentation

OpenVMS Utility Routines Manual

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

Format

#include <utc.h>

int utc_mulftime( *result, *utc1, factor)

• utc_t *result;
• const utc_t *utc1;
• const double factor ;

Input

utc1

Relative binary timestamp.

factor

Real scale factor (double-precision floating-point) (G format floating-point on VAX systems).

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.

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);

Multiplies a relative binary timestamp by an integer factor.

Format

#include <utc.h>

int utc_multime( *result, *utc1, factor)

• utc_t *result;
• const utc_t *utc1;
• long factor ;

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.

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)

• utc_t *utclp;
• utc_t *utcmp;
• utc_t *utchp;
• const utc_t *utc;

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.

Converts a relative binary timestamp to a tm structure.

Format

#include <utc.h>

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

• struct tm *timetm;
• long *tns;
• struct tm *inacctm;
• long *ins;
• const utc_t *utc;

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.

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)

• utc_t *result;
• const utc_t *utc1;
• const utc_t *utc2;

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).

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           */

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)

• utc_t *result;
• const utc_t *utc1;
• const utc_t *utc2;

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:

• absolute time - absolute time = relative time
• relative time - relative time = relative time
• absolute time - relative time = absolute time
• relative time - absolute time is undefined. See NOTES.

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.

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)

• const utc_t *utc;
• long *timadr;

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.

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)

• const utc_t *utc;
• long *timadr;

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.

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
 *****/

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)

• const utc_t *utc;
• long *timadr;

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 .

9.6 Example Using the DECdts API Routines

• Prompts the user to enter time coordinates.
• Stores those coordinates in a tm structure.
• Converts the tm structure to a utc structure.
• Determines which event occurred first.
• Determines if Event 1 may have caused Event 2 by comparing the intervals.
• Prints out the utc structure in ISO text format.

#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]
$