Time Service Functions

The _now() function returns the current time based on a provided pattern. It uses the following format:

_now([pattern])

The default pattern (MM/dd/yyyy) returns the date in month/day/year format. So, for example, the date might return as 06/15/2006 if the function _now() is entered with no pattern.

Pattern characters can be assembled to provide the desired return. The following table lists the characters and the expected result. Characters are case-sensitive. All examples are based on a time of June 15, 2006 at 13:02:08 PM.

The function call must provide sufficient pattern characters to fill the field for those where length is specified. The following table provides a few examples:

Note: Special characters can be included in the pattern by using an apostrophe (‘) character. To avoid compiler confusion, surround the pattern string using double quote (“) characters.

In releases running under Java Version 1.6, the pattern character 'u' was used by iWay for advanced timing capabilities, and will continue to provide that service. The special iWay pattern characters are now supported in the _timer() function.

The _timer() function returns time values based on the request. It uses the following format:

_timer(type)

The _timer() function replaces the use of the _now() function with special iWay-specific patterns.

The supported types are listed and described in the following table.

If no type value is specified for the _timer() function, then the U (milliseconds) pattern character is used by default.

Note: Aliases are provided for the keywords, which reflect prior support for iWay pattern characters in the _now() function. iWay strongly discourages their use, and cannot guarantee that they will continue to be supported beyond iSM Version 7.0.

The pattern character ‘Un’ represents the best time available for the system at the nanosecond level. This method can only be used to measure elapsed time and is not related to any other notion of system or wall-clock time. The value returned represents nanoseconds since some fixed but arbitrary. This method provides nanosecond precision, but not necessarily nanosecond accuracy. No guarantees are made about how frequently values change.

The _tstamp() function returns a timestamp (accuracy to seconds) in ISO 8601 format.

This is a standard time function that is commonly used in many XML and web applications.

The _tstamp() function uses the following format:

_tstamp([locale])

The _ftstamp() function returns a fine timestamp (accuracy to milliseconds) in ISO 8601 format. This function uses the following format:

_ftstamp([compression] [locale])

For example:

_ftstamp() yields 2017-07-21T19:42:44:609Z

The special pattern of the word compressed eliminates the separator characters, yielding:

20170721194244609Z

The compressed option simplifies using the output in file names.

Users are cautioned that applications that employ local time may encounter issues across time zones or around time changes, such as daylight saving time (DST).

The _fmtdate() function formats a date according to a pattern when a date is provided in milliseconds since January 1, 1970, 00:00:00 GMT. It uses the following format:

_fmtdate(pattern,value [,language, [,country]])

For example:

_fmtdate('yyyy.MM.dd', _dateof('MM/dd/yyyy','06/25/2009')) yields the following:

 2009.06.25

It is sometimes desirable to obtain the date for some moment in relation to the current moment. For example, you may want the current date/time for a date one week in the past:

_fmtdate('yyyy/MM/dd hh:mm:ss',_imul(_isub(_timer(),_imul(86400,7)),1000))

Replace the 7 in this example with the number of days desired. 86400 is the number of seconds in a day.

For example, to return local time:

_fmtdate('dd-MMM-yyyy HH:mm:ss.SSS z',_timer(milliseconds))

The language argument is a valid ISO Language Code. These codes are the lowercase, two-letter codes as defined by ISO-639. You can find a full list of these codes at a number of websites, such as http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt.

The country argument is a valid ISO Country Code. These codes are the upper case, two-letter codes as defined by ISO-3166. You can find a full list of these codes at a number of websites, such as http://www.iso.org/iso/country_codes.htm.

The language and country codes affect the language of the result, not the time zone offset specified by the pattern. The country code is required only in cases in which the language code is ambiguous.

For example, one hour from this moment:

_fmtdate('EEE, dd-MMM-yyyy HH:mm:ss zzz', _iadd(_timer(),3600000), 'en')

yields the following:

Wed, 31-Dec-2012 19:04:00 EST

For example:

_fmtdate('EEE, dd-MMM-yyyy HH:mm:ss zzz', _iadd(_timer(),3600000), 'fr')

yields the following:

mer., 31-déc.-2012 19:04:00 EST

Note: Date operations can be performed by doing arithmetic on the values with appropriate patterns. The _timer() function returns the current time for this function.

The _dateof() function parses a date and returns the corresponding number of milliseconds since January 1, 1970, 00:00:00 GMT. It uses the following format:

dateof(pattern, value [,zone][,default])

For example:

_dateof('MM/dd/yyyy', '06/25/2009') yields the following:

 1245902400000

To create a duration suitable for date arithmetic, use the Zulu zone. This avoids any offset, so that a pattern, such as ss will give absolute seconds.

Note: The _iadd() and _isub() functions are preferred for date arithmetic because they operate on long integers with more precision than _add() and _sub().

Compute and display the time ten minutes ago. This example was run at 09/08/27 05:13:54.

_fmtdate('yy/MM/dd hh:mm:ss',_isub(_timer(),_dateof('mm',10,gmt)))

Results in 09/08/27 05:03:54.

The _dateadd() function adds the offset parameter to the date parameter. If the date and time is not provided, then the current date/time of iWay Service Manager (iSM) is used. This function uses the following format:

_dateadd(offset [,date])

[xxd][xxh][xxm]xx[s]

For example, _dateadd(1d) yields the following:

1477627200000

Note: This is assuming that the date and time of iSM is 10/27/2016 12:00:00 AM.

You may have a use case where you need to perform and display a date calculation on a fixed date (for example, adding a week to 10/27/2016). This may be accomplished by using several iSM functions. For example:

_fmtdate('yyyy-MM-dd hh:mm:ss a',_dateadd(7d,_dateof('MM/dd/yyyy','10/27/2016')))

Results in:

2016-11-03 12:00:00 AM

The _datesub() function subtracts the offset parameter from the date parameter. If the date and time is not provided, then the current date/time of iWay Service Manager (iSM) is used. This function uses the following format:

_datesub(offset [,date])

[xxd][xxh][xxm]xx[s]

For example, _datesub(1d) yields the following:

1477454400000

Note: This is assuming that the date and time of iSM is 10/27/2016 12:00:00 AM.

You may have a use case where you need to perform and display a date calculation on a fixed date (for example, subtracting a week from 10/04/2016). This may be accomplished by using several iSM functions. For example:

_fmtdate('yyyy-MM-dd hh:mm:ss a',_datesub(7d,_dateof('MM/dd/yyyy','10/04/2016')))

Results in:

2016-09-27 12:00:00 AM