Skip to main content
Version: 7.9

Dates

Overview

Dates can normally be tricky since they generally require very specific formats. Furthermore, some functions/objects require a date object instead of a string. Fortunately, there are several ways to create and alter date objects with scripting in Ignition.

Python has some built-in libraries to create and manipulate dates and times. However, most users find both Ignition's built-in system functions and even Java's Calendar class easier to use. Regardless, this section will demonstrate some examples from each approach.

Ignition's System Functions

Ignition's system.date library has a large number of functions that provide easy access to datetime creation and manipulation. This page has just a few simple examples.

Creating Dates

New datetimes can be created by using either the system.date.now or system.date.getDate. The system.date.getDate function returns a datetime, but the time is set to midnight. However, we can use system.date.setTime to change the time.

Python - System Functions - Creating Dates
# Get the current datetime.
print system.date.now()

# Create a date. The time will be set to midnight.
newDate = system.date.getDate(2018, 10, 28)
print newDate

# Change the time on the new date to 11:30 am.
print system.date.setTime(newDate, 11, 30, 0)

Formatting Dates

When printed, datetimes default to a format like the following: Sun Jan 1 00:00:00 TZ 2018. However, this can be manipulated by using special characters in the system.date.format function:

Python - System Functions - Date Formatting
rightNow = system.date.now()

# Demonstrating the standard format.
print rightNow

# Demonstrating the modified format.
print system.date.format(rightNow, "yyyy-MM-dd HH:mm:ss")

Date Arithmetic

The system.date.add* functions can be used to add to or subtract some amount of time from a date. See the system.date.add* functions for more information.

Python - System Functions - Date Arithmetic
# Get the current datetime.
newDate = system.date.now()

# Change the time on the new date to 30 minutes ago.
print system.date.addMinutes(newDate, -30)

Date Formatting Characters

The following is a reference of date formatting characters that can be used by system.date.format or Java's DateFormat class. Additionally, there are many other non-scripting uses in Ignition (such as the Calendar component's Format String property) that can utilize this reference.

SymbolDescriptionPresentationExampleOther Notes
GEra designatorTextG=AD
yYearYearyyyy=1996; yy=96Lowercase y is the most commonly used year symbol
YWeek yearYearYYYY=2009; YY=09Capital Y gives the year based on weeks (ie. changes to the new year up to a week early)
MMonth in yearMonthMMMM=July; MMM=Jul; MM=07
wWeek in yearNumber27If Dec31 is mid-week, it will be in week 1 of the next year
WWeek in monthNumber2
DDay in yearNumber189
dDay in monthNumber10
FDay of week in monthNumber22nd Sunday of the month
EDay name in weekTextEEEE=Tuesday; E=Tue
uDay number of weekNumber1(1 = Monday, ..., 7 = Sunday)
aAm/Pm markerTextPM
HHour in day (0-23)Number0
hHour in am/pm (1-12)Number12
kHour in day (1-24)Number24
KHour in am/pm (0-11)Number0
mMinute in hourNumber30
sSecond in minuteNumber55
SMillisecondNumber978
zTime zoneGeneral time zonezzzz=Pacific Standard Time; z=PST
ZTime zoneRFC 822 time zoneZ=-0800
XTime zoneISO 8601 time zoneX=-08; XX=-0800; XXX=-08:00

Java's Calendar Class

caution

Ignition's System Functions vs Java's Calendar Class

While Java's Calendar class if useful, in many cases Ignition's built-in system.date functions are simpler to use. Furthermore, the system.date functions typically use the Calendar class to retrieve the current time, so you are not losing any functionality by using the system functions.

It is highly advisable to use Ignition's system functions to generate and manipulate dates. The information on this page pertaining to the Calendar class is maintained in the interest for legacy installations.

Creating Dates

To create an arbitrary date, you can use the java.util.Calendar class. It has various functions to alter the calendar fields, like Calendar.HOUR, Calendar.MONTH, and so on. After you're done manipulating the Calendar, you can use its getTime() function to retrieve the Date represented by the calendar. It also has a handy set() function that takes the common parameters of a Date. The one major "gotcha" here is that January is month zero, not month one. For example:

Python - Calendar Class - Creating Dates
from java.util import Calendar
cal = Calendar.getInstance()

# set year, month, day, hour, minute, second in one call
# This sets it to Feb 25th, 1:05:00 PM, 2010
cal.set(2010, 1, 25, 13, 5, 0)
myDate = cal.getTime()

Date Arithmetic

Often you'll have a Date object from a component like the Popup Calendar and want to alter it programmatically. Say, subtracting 8 hours from it, or something like that. The java.util.Calendar class is used for this as well. Following the example above, this code would subtract 8 hours from the variable myDate.

Python - Calendar Class - Date Arithmetic
from java.util import Calendar
cal = Calendar.getInstance()
cal.setTime(myDate)
cal.add(Calendar.HOUR, -8)
myNewDate = cal.getTime()

Python's Time and Datetime Libraries

Ignition's System Functions vs Python's LIbraries

Many components in Ignition that contain a Date property actually expect a Java calendar object. Creating a datetime object using Python's built-in libraries and passing them to a date property on a component will result in an exception.

As a result, it is highly recommended to use Ignition's built-in system.date functions.

Creating Dates - Python's Time Library

The time library can be use to return dates as well as time. Times are created as a tuple of integers. The integers represent the following values: year, month, day of the month, hour, minute, second, weekday, day of the year, daylight savings time)

Check out Python's time library documentation for more information.

Python - Python Library - time
import time

# Finds the current local time. The time is returned as a tuple of integers.
myTime = time.localtime()

# Print the time into a 24-character string with the following format: Sun Nov 20 12:00:00 2017
print time.asctime(myTime)

# Alternatively, we can reformat the time in a custom manner, then print it
print time.strftime('%H:%M:%S %b %d %Y', myTime)

Creating Dates - Python's Datetime Library

Python's datetime library offers a bit more flexibility since arithmetic can easily be applied. Additional information on the datetime library can be found in Python's official documentation.

Note the double use of datetime in the example below. This is because the datetime library has a class named datetime.

Python - Python Library - datetime
import datetime

# Returns the current datetime.
print datetime.datetime.now()

However, we can clean up the above by importing in the datetime class from the library:

Python - Python Library - datetime
# Imports the class named 'datetime' from the 'datetime' library, so we don't have to state it twice.
from datetime import datetime

# Returns the current datetime.
print datetime.now()

If you need to create a specific datetime, instead of just using the current, you can pass in the values directly when creating an instance of datetime:

Python - Python Library - Creating a New Time
from datetime import datetime

# Prints out the following datetime: 2018-01-02 03:04:05.000006
print datetime(2018,1,2,3,4,5,6)

Finding the difference between two datetime objects can easily be accomplished by using the '-' character

Python - Python Library - Date Difference
from datetime import datetime

rightNow = datetime.now()
someTime = datetime(2018,1,1,1,1,1,1)

# Find the difference between the two dates.
print someTime - rightNow

Date Arithmetic

With Python's built-in libraries, the timedelta class provides the simplest way to perform arithmetic on a date: It simply creates an object that effectively represents a duration. The duration can then be applied to a datetime.

Python - Python Library - Date Arithmetic
# We're including the timedelta class here
from datetime import datetime, timedelta

rightNow = datetime.now()

# Creating a timedelta object, and setting the hours to 8
offset = timedelta(hours = 8)

# Print the current time, and then print the time minus the offset.
print rightNow
print rightNow - offset