Documentation - DOKA-NG (Functional availability is per selected plan)

The time zone concept supports multi-entity installations whenever various users operate in various time zones. In the standard implementation, the time zone is kept the same for all users in a particular entity. (In the project overlay, the granularity can be increased enabling various users to be allocated to various time zones in the same entity.)

The concept covers the following specifications:

The times of specific incidents (login time, event time, SLA target time, login entries, etc.) are displayed in the local time for each user. At the same time, these times are stored and administered in the whole system for comparative purposes. This means that an administrator, for example, can identify the real time of an event. Although users in various time zones may be working on the same object (e.g. capturing a transaction in the US, releasing it in China), the depiction of the chronological sequence of events remains consistent and transparent for users across all time zones.

Banking entries (due dates, last date of shipment, value dates) are not affected by the concept.

Logically, the 'datetime' data type consists of a date and a time. Before the data type 'datetime' was introduced, such items were represented by two data fields (a date and a time, e.g. EVT/DAT and EVT/TIM). Saving the date in two fields like this makes it difficult to convert the information automatically (from time saved to time displayed) for different time zones.

The 'datetime' data type is only applied to datafields that describe points of time in real time. These include:

• EVT/DATTIM (when an event occured)
• TRN/INIDATTIM (when a transaction was saved)
• TRS/DATTIM (when a transaction was signed)
• WFE/TARDATTIM (target time for completion)

For a full list, see all the 'datetime' fields in the list of fields for each table.

The 'datetype' data type is used for datafields that indicate a general date (usually relevant to a specific location) and not a specific point in time defined down to the second. Such 'datetype' fields are not subject to change and will continue to be used as has been the case in the past for details of business dates (opening date, value date, due date, last date of shipment) as issued in SWIFT messages. For these dates, a geographical location is either legally implicit or explicit and the dates never change regardless of where in the world this information is displayed.

'datetype' will continue to be used in CBS/RNGMOD dates.

The following concepts are relevant for installations using time zones:

• TZSystem - the time zone from where the application as a whole is operated and in which all 'datetime' data elements are stored. This is typically, but not necessarily, the time zone in which the server is physically installed.
• TZUser - user time zone - the time zone in which the process is currently running. In the standard version, this is the time zone for the relevant entity.

All values are stored in the TZSystem's time zone. However, they are converted to and displayed in the TZUser's time zone. The technical conversion from a value stored internally in TZSystem is carried out via the display controls, or TDBasic functions, that convert or transfer the contents of a 'datetime' field into another format.

'today' and 'time' functions always deliver the date and time of the relevant process for the respective time zone. Thus, an American user will be able to see that a transaction was carried out at 11.00 a.m. on a given date, even though the system may well be running in China, and the event was carried out after midnight there on the following day.

For the 'datetime' data type, there is just one 'datetime' view type that is largely applied in 'read only' mode. These fields are stored as timestamps in the datebase (as is the already the case with 'datetype' data). All values are stored in the TZSystem's time zone. However, they are converted to the TZUser's time zone.

The DATTIMM module is used to edit 'datetime' data. This prepares the date and time taken from the field separately. The module is applied in info transactions (INFSMH, INFTRN) for example.

'datetype' and 'datetime' are NOT compatible in assignments (only DBSQLDate and FmtDate allow both types to be used as arguments). Appropriate TDBasic functions are available for the conversion.

[System]

TZSystem=<Name of system time zone>

TZUser=<Name of user time zone>

TZUser is defaulted from TZSystem. There is no default for TZSystem. If the entry has not been set, time zone conversion is deactivated.

[<UIL>-Longset]

DateTimeShort=<Short format for DateTime>

DateTimeLong=<Long format for DateTime>

DateTimeShort and DateTimeLong define output frames, according to DateShort and DateLong, with an expanded frame (see FmtDate).

The list of time zones is stored in a separate INI file 'ini/TZ.ini' (the format is similar to the Unix environment variable time zones, but with the difference that the time zone is left of the equals sign and that for the start and end of summer time, the two variations are not supported in the Julian calendar).

[Timezones]

tzname=offset[dstname[offset][,start[/time],end[/time]]]

tzname=Name of time zone

offset=[+ or -]hh[:mm[:ss]]

dstname=Alternative name for summer time

start=Mm.n.d with 1 ≤ m ≤ 12 (month), 1 ≤ n ≤ 5 (week in the month, 5 refers to the last week in the month), 0 ≤ d ≤ 6 (day of the week, 0 = Sunday)

time=hh[:mm[:ss]] (if not otherwise indicated, the default is 02:00:00)

Example:

[Timezones]

CET=+01:00CEST+02:00,M3.5.0/02:00,M10.5.0/02:00

When saving time in TZSystem, any possible shifts in summer time are ignored to avoid any ambiguous indications of time when converting to winter time.

• Set/GetContext(“TZUser”) sets the user time zone, initially this is the same as TZSystem (at the start of the session this is read from ETY (or possibly USR) and set initially).
• GetContext(“TZSystem”) reflects the system time zone, this cannot be set/amended.
• GetContentDatetime
• SetContentDatetime
• GetLockDateTime
• function DatetimeNow delivers the time 'now' in the TZSystem. If TZSystem has not been set, this reflects local time and the use of time zones is implicitly deactivated.
• function DatetimeGetDate( in arg datetime [, in Timezone text]) : DateType delivers the date part from arg, converted to the respective time zone.
• function DatetimeGetTime( in arg datetime [, in precision numeric [, in Timezone text]]) : numeric delivers the time part from arg in 'time' format, converted to the respective time zone. Precision refers to the legacy 'time' format with the default 7 (=msec).
• Sub DatetimeSetTime( inout arg datetime, in timearg numeric[, in Timezone text]) sets the time part from arg to timearg (indicated in the 'time' format') converted to the respective time zone.
• function DatetimeMake( in datearg datetype, in timearg numeric[, in Timezone text]) : DateTime creates a DateTime value in TZSystem from datearg and timearg (indicated in the 'time' format in the respective time zone).
• function DatetimeAdd( in arg datetime, in days numeric, in hours numeric)) hours is formatted in the same manner as 'time'.
• function DatetimeDiff( in arg1 datetime, in arg1 datetime,) : numeric delivers the difference in hours in the format similar to 'time'. Here, whole days can automatically be converted to hours and the result can be much larger than 24.
• Function FileDateTime(in filename text) delivers the timestamp of the last amendment in the TZSystem time zone.
• NULLDateTime new system constants for initialization.
• GetContent, SetContent, LoadContent allow 'datetime' fields to be dealt with.
• Today [( in Timezone text)] delivers the current date as a default in line with the respective 'TZUser'.
• Time [( in Timezone text)] delivers the current time as a default in line with the respective 'TZUser'.
• GetLockDate [( in Timezone text)] delivers the lock date as a default in line with the respective 'TZUser'.
• GetLockTime [( in Timezone text)] delivers the lock time as a default in line with the respective 'TZUser'.

The following functions also permit 'datetime' arguments in addition to 'datetype' arguments.

FmtDate, FmtDateShort and FmtDateLong, whereby FmtDate contains an additional format letter for time:

• h hours without a leading 0
• hh hours with a leading 0
• mm minutes with a leading 0
• ss seconds with a leading 0
• SS tenths of seconds with a leading 0
• SSS thousandths of seconds with a leading 0
• aa am/pm lower case, when used, hh is automatically adjusted to 1-12 values
• AA AM/PM upper case, when used, hh is automatically adjusted to 1-12 values
• ttttt time zone

DBSqlDate accepts 'datetype' or 'datetime' as an argument; the nature of their processing depends on the data type.

tdconst.ini contains the two symbolic constants 'tdContextTZuser' and 'tdContextTZSystem'.

For all functions with an optional 'time zone' argument the following applies:

Instead of the string that comprises the name of the system time zone, (the result of GetContext(tdContextTZSystem), 'tdContextTZSystem' can be used directly as an argument. Unless otherwise indicated, the 'TZUser' is used.

In most situations, therefore, developers do not have to worry about time zones.

The time part of 'datetime' (for DateTimeGetTime, DateTimeSetTime, DateTimeMake functions) is displayed as (hh+mm/100+ss/10000) in line with the established format for time. The most precise definition of time is 1/1000 sec (1 millisecond).

Time indications using 'decimals' in data fields refer to the precision of time in the datafield (0 = seconds, 3 = milliseconds = maximum precision). The default for decimal places is '0'.

In SYSMOD there are two global functions defined that can be used to convert string to TradeDesign timestamps.

Returns TradeDesign date from string ArgDateTxt given in any format

• ArgDateTxt - string with date
  
• ArgFmt - optional parameter with expected date format e.g.: DDMMYYYY, YYMMDD, DD-MMM-YY etc
  if the format is not provided - the function will try to guess format
  

Errorcodes:

For datetime conversion use correspondent function: DateTimeMakeFromString

Available separators are: “/”, “-”, “.”, “ ”, no separator

The date string might contain weekday (e.g. Sun, Sunday etc) which is ignored
The day might contain English suffix (i.e. 1st, 2nd, 3rd, 4th, etc) which is ignored

If date does not contain Year (e.g. 01/01 or January 1st) - the year is defaulted with today's year
If year is not complete (e.g. 31/12/20) the year will be complemented according to Swift rule:

The input string can be in any of the following formats (but not limited to them if respective ArgFmt provided):

• DD/MM/YYYY
  
• DD/Jan/YYYY
  
• YYYY-MM-DD
  
• YYYY-APR-DD
  
• MM/DD/YYYY
  
• MM/DD/YY
  
• YYYY/MM/DD
  
• YYYY/December/DD
  
• YY/MM/DD
  
• YY/Dec/DD
  
• DD/MM/YY
  
• DDMMYYYY
  
• MMDDYYYY
  
• DDMMYY
  
• MMDDYY
  
• YYYYMMDD
  
• YYMMDD
  
• DD January YYYY
  
• January DD YYYY
  
• YYYY January DD
  
• January 25th
  

Extracts TradeDesign datetime format from timestamp text ArgDateTxt
Datetime returned is in the current timezone of the system

Timestamp can be in any format
If datetime cannot be retrieved - errorcode 110 will be raised and NULLDATETIME returned

If timestamp does not contain some data, the missing data will be defaulted to epoch start timestamp
1970-01-01T00:00:00Z
In the current system timezone tdContextTZSYSTEM


Correspondent function to get Date only: DateFromString