tz

An ObjectScript library for handling/converting time zones and timestamps in InterSystems IRIS.

Time zones are HARD! Let’s make them easy!!!

InterSystems “Bringing Ideas to Reality” Contest

This library was originally created/published for the InterSystems “Bringing Ideas to Reality” Contest.

See “Time zone conversion” on the InterSystems Ideas Portal.

Description

This ObjectScript library was created to easily handle the formatting and conversion of timestamps from one time zone to another using standard timezones and formatting directives found on most POSIX-based systems.

In general, when working with datetimes, there are two types of datetimes:

1. Absolute Time - i.e. Coordinated Universal Time (UTC)

   • Contains either a timezone specification or offset.
   • All UTC times are relative to time a the Royal Observatory in Greenwich, London (see Greenwich Mean Time).
   • UTC-0000 is the time at Greenwich
   • UTC-0100 is one hour west of Greenwich
   • UTC+0100 is one hour east of Greenwich

2. Local Time

   • No timezone or offset information is available.

If you know the Local Time and a timezone (or offset), you can determine an Absolute Time.

You can convert any Absolute Time to a Local Time for any timezone you desire.

This library will help you perform the conversions between various local times and absolute times.

tz.HL7 Basic Usage

// ConvertTz() Examples
set dt = ##class(tz.HL7).ConvertTz("20200102033045-0500", "America/Chicago")
set dt = ##class(tz.HL7).ConvertTz("20200102033045", "America/New_York", "America/Chicago")
set dt = ##class(tz.HL7).ConvertTz("20200102033045", "America/New_York", "America/Chicago", "HL7Local")
set dt = ##class(tz.HL7).ConvertTz("20200102033045", "America/New_York", "America/Chicago", "HL7WithOffset")
set dt = ##class(tz.HL7).ConvertTz("20200102033045", "America/New_York", "America/Chicago", "%Y-%m-%d %H:%M:%S")
// ToLocal() Examples

set dt = ##class(tz.HL7).ToLocal("20200102033045-0500", "America/Chicago")

set dt = ##class(tz.HL7).ToLocal("20200102033045", "America/Chicago", "America/Denver")
// WithOffset() Examples

set dt = ##class(tz.HL7).WithOffset("20200102033045-0500", "America/Chicago")

set dt = ##class(tz.HL7).WithOffset("20200102033045", "America/Chicago")

set dt = ##class(tz.HL7).WithOffset("20200102033045", "America/Chicago", "America/Denver")
// NowLocal() Example

set dt = ##class(tz.HL7).NowLocal("America/Chicago")
// NowWithOffset() Example

set dt = ##class(tz.HL7).NowWithOffset("America/Chicago")

Prerequisites

• IRIS 2022.1+ (for Embedded Python support)
• Python 3 installed on the system
• Currently only works on UNIX systems

Installation

There are several methods for installing this library:

1. Import classes directly into IRIS
2. Install the IPM/ZPM package
3. Docker

Option 1: Import Classes Directly into IRIS

Download the most recent exports/tz.Export.xml from the repository.

Import tz.Export.xml into your IRIS instance using the Import button found on the System Operation > Classes page in your Management Portal.

If you prefer loading tz.Export.xml from an IRIS terminal:

USER>do $system.OBJ.Load("/path/to/tz.Export.xml", "cuk")

Option 2: Install the IPM/ZPM package

Once package is approved, use zpm install the tz package:

USER>zpm
=============================================================================

|| Welcome to the Package Manager Shell (ZPM). version 0.7.4               ||

|| Enter q/quit to exit the shell. Enter ?/help to view available commands ||

|| Current registry https://pm.community.intersystems.com                  ||
zpm:USER>install tz

Option 3: Docker

If you prefer, you can load the library with docker, run the built-in tests, and experiment with the tz classes.

First, download/clone the repo to your local computer:

git clone git@github.com:jamerfort/iris-tz.git

Build and connect to your instance:

cd ./iris-tz
Rebuild/start the image
docker compose up --build -d
Connect to your instance
docker exec -it iris-tz iris terminal IRIS
Stop your containers
docker compose down

Verify/Test Installation

Run tests from your iris terminal:

// Built-in Tests
USER>do ##class(tz.TZ).Test()
109 Tests Successful!
// Experiment with the API

USER>zw ##class(tz.HL7).ConvertTz("20240102033045-0500", "America/New_York")

"20240102033045-0500"

If you are using Docker or have a copy of the repo, you can reload changes to the tz source code from your iris terminal:

USER>do $system.OBJ.LoadDir("/home/irisowner/dev/src", "cuk",,1)
Load of directory started on 12/14/2024 00:40:14

Loading file /home/irisowner/dev/src/cls/tz/HL7.cls as cls

Imported class: tz.HL7

Loading file /home/irisowner/dev/src/cls/tz/TZ.cls as cls

Imported class: tz.TZ

Loading file /home/irisowner/dev/src/cls/tz/internal.cls as cls

Imported class: tz.internal

Loading file /home/irisowner/dev/src/cls/tz/Tests.cls as cls

Imported class: tz.Tests

Class tz.HL7 is up-to-date.

Class tz.TZ is up-to-date.

Class tz.Tests is up-to-date.

Class tz.internal is up-to-date.

Load finished successfully.

Supported Timezones

This library uses the IANA timezone database/information installed on your system to perform the necessary timezone conversions. This database is typically updated whenever you apply operating system patches.

For more information, check out this Wikipedia page.

Examples of valid timezones:

• America/New_York
• US/Eastern
• America/Chicago
• US/Central
• America/Denver
• US/Mountain
• America/Los_Angeles
• US/Pacific
• Europe/Brussels
• CET
• Europe/Athens
• EET

Supported Datetime Format Codes

This library uses a mixture of python and POSIX/libc calls to parse and format datetimes. The following format codes should work in most cases:

Though the above format codes likely cover most of your formatting needs, you may find that codes from the following resources may work as well:

• Python datetime module
• C strptime manpage

Flexible Datetime Parsing

If an input format is blank or not provided to the ##class(tz.TZ).Convert() method, the library attempts to determine if the provided datetime string matches one of the following formats (in this order):

• %Y%m%d%H%M%S%z
• %Y%m%d%H%M%S
• %Y-%m-%dT%H:%M:%S
• %Y-%m-%dT%H:%M:%SZ
• %Y-%m-%dT%H:%M:%S%z
• %Y%m%dT%H%M%S
• %Y%m%dT%H%M%SZ
• %Y%m%dT%H%M%S%z
• %Y-%m-%d %H:%M:%S %z
• %Y-%m-%d %H:%M:%S
• %m/%d/%Y %H:%M:%S %z
• %m/%d/%Y %H:%M:%S
• %Y-%m-%d %I:%M:%S %p %z
• %Y-%m-%d %I:%M:%S %p
• %m/%d/%Y %I:%M:%S %p %z
• %m/%d/%Y %I:%M:%S %p
• %Y-%m-%dT%H:%M
• %Y-%m-%dT%H:%MZ
• %Y-%m-%dT%H:%M%z
• %Y%m%dT%H%M
• %Y%m%dT%H%MZ
• %Y%m%dT%H%M%z
• %Y-%m-%d %H:%M %z
• %Y-%m-%d %H:%M
• %m/%d/%Y %H:%M %z
• %m/%d/%Y %H:%M
• %Y-%m-%d %I:%M %p %z
• %Y-%m-%d %I:%M %p
• %m/%d/%Y %I:%M %p %z
• %m/%d/%Y %I:%M %p
• %Y-%m-%d
• %m/%d/%Y

HL7 Date/Datetime Conversion - ##class(tz.HL7)

The tz.HL7 class provides several methods for converting HL7-formatted dates/datetimes to the desired timezone and/or format:

1. ConvertTz() converts HL7-formatted dates/datetimes to the desired timezone and/or format.

   • See docs/tz.HL7.ConvertTz.md

2. ToLocal() converts HL7-formatted dates/datetimes to the desired timezone with a format of YYYYMMDDHHMMSS.

   • See docs/tz.HL7.ToLocal.md

3. WithOffset() converts HL7-formatted dates/datetimes to the desired timezone with a format of YYYYMMDDHHMMSS±zzzz.

   • See docs/tz.HL7.WithOffset.md

4. NowLocal() returns the current local time for the given timezone with a format of YYYYMMDDHHMMSS.

   • See docs/tz.HL7.NowLocal.md

5. NowWithOffset() returns the current time with an offset for the given timezone with a format of YYYYMMDDHHMMSS±zzzz.

   • See docs/tz.HL7.NowWithOffset.md