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;

1 - Parameters

    Input

 *utc

    Binary timestamp to be converted.

    Output

 *timadr

    Binary OpenVMS format time representing GMT or the UTC
    equivalent.

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

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

5 - Related Functions

    Function: utc_mkvmsgmtime