Time and Calendar Functions

year (int offset): int

month (int offset): int

week (int offset): int

day (int offset): int

dom (int offset): int

tdm (int offset): int

tom (int offset): int

dow (int offset): int

ndow (int offset): int

ldow (int zone,int offset): int

hour (int offset): int

lhour (int zone, int offset): int

minute (int offset): int

tod (int offset): int

ltod (int zone, int offset): int

tow (int offset): int

ltow (int zone, int offset): int

second (): var

second (var Time): var

minutesAgo (int bar): int

minutesWithin (int bar): var

workday (int offset): bool

market (int zone, int offset): bool

at (int hhmm): bool

dst (int zone, int offset): int

Parameters:

Usage:

wdate (int offset): var

ldate (int zone, int offset): var

wdateBar (int n): var

wdatef (string Format, string DateTime): var

strdate (string Format, int offset): string

strdate (string Format, int zone, int offset): string

strdate (string Format, var Date): string

nthDay(int Year, int Month, int Dow, int N): var

dmy (int YYYYMMDD): var

ymd (var Date): int

utm (var Date): int

mtu (int UnixTime): var

Parameters:

Usage:

timeOffset (int zone, int days, int hour, int minute): int

Parameters:

Usage:

Remarks:

• If not stated otherwise, all dates and times reflect the time stamp of the Close price at the end of the bar. Dates and times are normally UTC, also called "GMT" or "Zulu" time (Greenwich mean time without daylight saving time). Timestamps in historical data are supposed to be either UTC, or to be a date only with no additional time part, as for daily bars. It is possible to use historical data with local timestamps in the backtest, but this must be considered in the script since the date and time functions will then return the local time instead of UTC, and time zone functions cannot be used.
• All date and time functions return 0 or invalid values in the INITRUN when no asset was yet loaded and thus the bars and date ranges are not yet set up. For getting the current time at script start, use NOW for the offset. When offset is 0 or omitted, the end time of the current bar is returned. When offset is set to NOW, the current UTC time of the PC clock is returned. When a value > 30000 is used for offset, it is assumed a day number in DATE format, and the corresponding year, month, or day is returned. The offset parameter is affected by TimeFrame, f.i. when TimeFrame is 6 and offset is 3, the time of 3*6 = 18 bars ago is returned. Note that not all time/date functions support the special offset values.
• Be careful when checking time, because not all hours or minutes have an associated bar. For instance, if(hour == 17) will fail when no bar ends between 17:00:00 and 17:59:59 UTC. Better use the at function or check a time range.
• Date and time functions require a LookBack period of at least the highest used or returned bar offset.
• Most date and time functions return int, but some return var - take care of that when using the functions in a printf statement.
• In live trading the time functions are based on the broker's server time when supported by the API; otherwise on the PC time. The script must take care that rounding differences and small time deviations don't cause problems. For instance, the weekday (dow(0)) exactly at midnight can return different values depending on whether the server time is a second slower or faster than the PC time. So a tick can have a 23:59:59 time stamp, while the PC clock has already the next day at 00:00:00. When using daily bars, check the whole time and not only the day, or set the bar offset so that the bars do not change exactly at midnight.
• Time printing uses the Windows COleDateTime class, which rounds a DATE value to the next second. Therefore, minutes and seconds in time strings can differ by about 0.5 seconds to the minute and second functions, which round the time to the next millisecond.

Examples:

// buy at UTC midday on the last day of the month, 
// sell 2 trading days later
if(NumOpenLong == 0) { // nothing yet bought this month
  if((tom(0) == tdm(0)) && hour() >= 12)
    enterLong();
} else if(tdm(0) >= 2)
    exitLong();

// print New York local time to the log
printf(strdate("# NY: %H:%M",EST,0));

// close all position at 16:15 local time
if(at(1615)) {
  printf("\nClosing all positions");
  exitLong("**");
  exitShort("**");
}

// convert a time stamp from EST to UTC
TimeStamp -= (EST+dst(EST,TimeStamp))/24.;

See also: