40.2  –  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.

40.3  –  Returns

     0   Indicates that the routine executed successfully.
    -1   Indicates an invalid time argument or invalid results.

40.4  –  Example

    See the sample program for the vmsgmtime routine.

40.5  –  Related Functions

    Function: utc_vmsmklocaltime

41  –  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.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>
    $