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:

• If no optional input parameters are passed in, then the user's DUZ(2) variable is used to determine the user’s default institution within the INSTITUTION (#4) file; where the TIMEZONE (#801) and COUNTRY (#802) fields are located.
  
  
• If only the institution input parameter is passed in, the time zone and country are determined by fields in the INSTITUTION (#4) file.
  
  
• If the timezone and country input parameters are passed in, the offset is determined from the WORLD TIMEZONE (#1.71) file.

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

• If the timezone and country parameters cannot be determined by any of the methods above, an error message is returned.
  
  
• If the timezone parameter is passed into the API but the country parameter is not, an error message is returned.
  
  
• If the country parameter is passed into the API but the timezone parameter is not, an error message is returned.
  
  
• If the institution parameter is passed in with either the timezone or country parameter, or both, an error message is returned.
  
  
• Once the timezone and country input parameters are determined, they are validated for consistency. An error message is returned if they are inconsistent.
  
  For example: if the user passes in timezone = "Australian Eastern Time" and country = "Mexico", the $$UTC^DIUTC API returns an error message.

Format

    $$UTC^DIUTC(fm_datetime[,timezone][,institution][,country][,extended_output_flag])

Input Parameters

Output

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:

• Null or Missing—Default output (GMT+offset in internal format) is returned.
  
  
• 1—Output is multiple caret- (^) delimited pieces:
  
       Piece 1: GMT+offset in internal format (e.g, 3160105.080715416)
       Piece 2: GMT+offset in external format [e.g., JAN 5,2016@08:07:15 (UTC-7:00)]
       Piece 3: Offset in external format (e.g., -7:00)
       Piece 4: Time zone (e.g., EASTERN STANDARD TIME, ESTONIA STANDARD TIME)
       Piece 5: Country Name (e.g., UNITED STATES, FRANCE)
       Piece 6: Time zone abbreviation (e.g., EST, PST)
       Piece 7: Timeframe (e.g., DAYTLIGHT, STANDARD, SUMMER)
       Piece 8: Institution Name from the INSTITUTION (#4) file (e.g., CHEYENNE VAMC). This piece is set to null if timezone and country are passed in as input
                   parameters.

Examples

Example 1

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

>W $$UTC^DIUTC(3160816.120016)
3160816.160016452

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:

>W $$UTC^DIUTC("NOW","EASTERN",,"UNITED STATES",1)
3160815.133449452^AUG 15, 2016@13:34:49 (UTC-04:00)^-04:00^EASTERN^UNITED STATES
^EDT^DAYLIGHT SAVINGS^

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
^CST^STANDARD^

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
^EST^STANDARD^SOFTWARE SERVICE

Error Messages Returned

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

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