VA FileMan 22.2 Developer's Guide HTML Manual Banner
VA Office of Information and Technology (OIT) Banner

Main Section User Manual Advanced User Manual

Coordinated Universal Time (UTC) API

$$UTC^DIUTC(): Return GMT in VA FileMan Internal Format with Time Zone Offset

The $$UTC^DIUTC API returns the Greenwich Mean Time (GMT) represented in standard VA FileMan internal date/time format with an internal three-digit time zone offset appended to the end. The calculation for the internal offset is:

  1. Convert the external offset to minutes.

  2. Divide value from Step 1 by 5.

  3. Add value from Step 2 to 500.

For example:

    -07:00 = -420 minutes, divided by 5 = -84, and added to 500 = 416

There may be other output variables based on the value of the extended_output_flag input parameter. The details for the other output values are documented in the “Output” section.

To determine the offset, the API needs to have the timezone and country input parameters. These values are determined using the following algorithm:

The following errors are returned based on the evaluation of the input parameters:

Input Parameters

(Required) Standard internal or external VA FileMan DateTime (e.g., NOW, T@12A). The Time portion of the input is required.

NOTE: The NOW input parameter is based on the current system time. If NOW is passed in with a timezone and country input parameter that is different than the system’s time zone and country, inconsistent output may occur.


(Optional) Can be either of the following:

  • Pointer to the WORLD TIMEZONES (#1.71) file.

  • Value from the NAME (#.01) field if the WORLD TIMEZONES (#1.71) file (e.g., EASTERN).
institution: (Optional) Pointer to the INSTITUTION (#4) file.
country: (Optional) Can be either of the following:
  • Pointer to the COUNTRY CODE (#779.004) file.

  • Valid entry from the uppercase DESCRIPTION (#2) field of the COUNTRY CODE (#779.004) file.
extended_output_flag: (Optional) This parameter is an indicator of whether to do either of the following:
  • Return the default output (GMT+offset in internal format).

  • Include any extended return values.
If the extended_output_flag parameter is set to:
  • Null or Missing—Only the default value is outputted.

  • 1—Additional values are returned as documented in the “Output” section.

The function can have two different outputs depending on the value of the extended_input_flag input parameter. If the extended_output_flag is set to:

Example 1

The default output DUZ(2) variable is used, as shown below:

>W $$UTC^DIUTC(3160816.120016)
Example 2

The extended output DUZ(2) variable is used, as shown below:

>W $$UTC^DIUTC("T+1@11",,,,1)
3160811.150000452^AUG 11, 2016@15:00:00 (UTC-04:00)^-04:00^EASTERN^UNITED STATES^EDT^DAYLIGHT SAVINGS^SOFTWARE SERVICE
Example 3

The time zone and country are passed in, as shown below:

3160815.133449452^AUG 15, 2016@13:34:49 (UTC-04:00)^-04:00^EASTERN^UNITED STATES
Example 4

The time zone and country are passed in and extended output, as shown below:

>W $$UTC^DIUTC("2/1/16@1500","CENTRAL",,"UNITED STATES",1)
3160201.210000428^FEB 01, 2016@21:00:00 (UTC-06:00)^-06:00^CENTRAL^UNITED STATES
Example 5

The institution is passed in and extended output, as shown below:

>W $$UTC^DIUTC("Jan 15, 2016@11",,1,,1)
3160115.160000440^JAN 15, 2016@16:00:00 (UTC-05:00)^-05:00^EASTERN^UNITED STATES
Error Messages Returned

The following table lists the possible error messages returned with the $$UTC^DIUTC API:

Date/Time parameter is missing.
Institution parameter cannot include Country or Timezone parameter.
Timezone parameter must include Country parameter.
Country parameter must include Timezone parameter.
Extended parameter must be NULL or a 1 for extended output.
Cannot determine Country and Timezone from the Institution.
Cannot determine User location.
Cannot determine Country and Timezone from User location.
Invalid Timezone.
Invalid Country.
Mismatch of Country and Timezone.

NOTE: All of the error messages returned from the $$UTC^DIUTC API are preceeded by a: -1^. For example, “-1^Invalid Country”.


VA (Internet) / VA (Intranet) / OIT / EPMO / Site Map / Terms of Use / VA Privacy Policy / Accessibility

Reviewed/Updated: January 22, 2018

If you have questions, need more information, or are having accessibility problems with this Web site, please contact us by E-Mail: Webmasters