Working in Multiple Time Zones

Multiple time zones

If your application uses external time-dependent data supplied by users worldwide, you are faced with the problem of converting all dates and times to the calendar in which your application is set up to run. The facilities described in this section help you with that task.

Obtaining time zone info

With the functions TimeZoneOffset, DaylightSavingStartDate and DayLightSavingEndDate you can obtain various time zone specific characteristics.

TimeZoneOffset(FromTimeZone, ToTimeZone)
DaylightSavingStartDate(year, TimeZone)
DaylightSavingEndDate(year, TimeZone)

The function TimeZoneOffset returns the offset in minutes between the time zones FromTimeZone and ToTimeZone. You can use the function DaylightSavingStartDate and DaylightSavingEndDate to retrieve the reference dates, within a particular time zone, corresponding to the begin and end date of daylight saving time.

Example

offset    := TimeZoneOffset('UTC', 'Eastern Standard Time');
             ! result: -300 [min]
startdate := DaylightSavingStartDate( '2001', 'Eastern Standard Time');
             ! result: "2001-04-01 02"

Converting reference dates

With the function ConvertReferenceDate you can convert reference dates to different time zones. Its syntax is:

ConvertReferenceDate(ReferenceDate, FromTimeZone, ToTimeZone[, IgnoreDST])

With the function you can convert a reference date ReferenceDate, within the time zone FromTimeZone, to a reference date within the time zone ToTimeZone. If the optional argument IgnoreDST is set to 1, AIMMS will ignore daylight saving time for both input and output reference dates (see also Support for Time Zones and Daylight Saving Time). By default, AIMMS will not ignore daylight saving time.

Example

UTCdate := ConvertReferenceDate("2001-05-01 12", 'Local', 'UTC');
           ! result: "2001-05-01 11"

Conventions and time zones

When your application needs to read data from or write data to a database or file with dates not specified in local time, some kind of conversion of all dates appearing in the data source is required during the data transfer. To support you with such date conversions, AIMMS allows you to override the default timeslot format of one or more calendars in your model through a unit Convention (see also Globally Overriding Units Through Conventions).

The TimeslotFormat attribute

In the TimeslotFormat attribute of a Convention you can specify the time slot format (see also Format of Time Slots and Periods) to be used for each Calendar while communicating with an external source. The syntax of the TimeslotFormat attribute is:

Syntax

timeslot-format-list:

Use in graphical user interface

When an active Convention overrides the time slot format for a particular calendar, all calendar elements will be displayed according to the time slot format specified in the Convention. The time slot format specified in the calendar itself is then ignored.

Reading and writing to file

If you use a Convention to override the time slot format while writing data to a data file, report file or listing file, AIMMS will convert all calendar elements to the format specified in the TimeslotFormat for that calendar in the Convention prior to writing the data. Similarly, when reading data from a data file, AIMMS will interpret the calendar slots present in the file according to the specified time slot format, and convert them to the corresponding calendar elements in the model.

Database communication…

When communicating calendar data to a database, there is one additional issue that you have to take into account, namely the data type of the column in which the calendar data is stored in the database table. If calendar data is stored in a string column, AIMMS will transfer data according to the exact date-time format specified in the TimeslotFormat attribute of the Convention, including any indicators for specifying the time zone and/or daylight saving time.

… for datetime columns

However, if the data type of the column is a special date-time data type, AIMMS will always communicate calendar slots as reference dates, which is the standard date-time string representation used by ODBC. In translating calendar slots to reference dates, AIMMS will adhere to the format specified in the TimeslotFormat attribute of either the Calendar itself, or as overridden in the currently active Convention.

Generated reference dates

The reference dates are generated according to the time zone specified in the %TZ specifier of the currently active TIMESLOT SPECIFIER. These dates always ignore daylight saving time (i.e. shift back by one hour if necessary), as daylight saving time cannot be represented in the fixed reference date format. Specifiers in the TIMESLOT FORMAT other than the %TZ specifier are not used when mapping to date-time values in a database. If you do not specify a %TZ specifier in the TIMESLOT FORMAT, AIMMS will assume that all date-time columns in a database are represented in the 'Local' time zone (the default).

Example

Consider the calendar HourCalendarLocalDST defined below.

Calendar HourCalendarLocalDST {
    Index           :  hd;
    Unit            :  hour;
    BeginDate       :  "2001-03-25 00";
    EndDate         :  "2001-03-25 06";
    TimeslotFormat  :  "%c%y-%m-%d %H:00%TZ('LocalDST')|\"\"|\" DST\"|";
}

If you want to transfer data defined over this calendar with a database table in which all dates are represented in UTC time, you should define a convention defined as follows.

Convention UTCConvention {
    TimeslotFormat  : {
        HourCalendarLocalDST : "%c%y-%m-%d %H:00%TZ('UTC')"
    }
}

When this convention is active, AIMMS will represent all calendar slots of the calendar HourCalendarLocalDST as reference dates according to the UTC time zone, by shifting as many hours as dictated by the local time zone and/or daylight saving time if applicable. Hence, when you use the convention UTCConvention during data transfer with the database, all calendar data slots will be in the expected format.

Working in Multiple Time Zones

Docs

Product

Support