Datetime services

Use Datetime services to build or increment a date/time. The services in datetime provide more explicit timezone processing than similar services in the date category.

Providing Time Zones

You can specify timezone input parameters to the datetime services in the following formats:

  • As a full name.

    Example: Asia/Tokyo America/Los_Angeles

    You can use java.time.ZoneId.getAvailableZoneIds. () method to obtain a list of the valid full name time zone IDs that your JVM version supports.

  • As UTC.

    Example: UTC - 5h

  • As a custom time zone ID, in the format GMT[+ | -]hh[ [:]mm].

    Example: GMT+2:00 Time zones 2 hours east of Greenwich GMT-3:00 Time zones 3 hours west of Greenwich (that is, Argentina Standard Time and Brazil Eastern Time)

    GMT+9:30 Time zones 9.5 hours east of Greenwich (that is, Australian Central Time)

  • As a three-letter abbreviation.

    Example: PST Pacific Standard Time

    Important: As some three-letter abbreviations can represent multiple time zones (for example, CST could represent both U.S. Central Standard Time and China Standard Time), all abbreviations are deprecated. Use the full name, UTC, or custom time zone ID GMT formats instead.

build

Builds a date/time string that uses the specified pattern and the supplied date/time elements.

Input parameters
pattern
String. The pattern with which to format the string. For more information about these pattern letters and symbols, see the Oracle Java™ API documentation for the DateTimeFormatter class.
year
String. The year expressed as a 4-digit Integer. If you do not specify year, the year is from the current date, which is determined by the JVM in which webMethods Integration runs. If you specify an invalid value for year, the service ends with an error from the JDK.
month
String. The month expressed as an Integer where January is 1. If you do not specify month, the month is from the current date, which is determined by the JVM in which webMethods Integration runs. If you specify an invalid value for month, the service ends with an error from the JDK.
dayofmonth
String. The day of the month expressed as an Integer, starting with 1 as the first day of the month. If you do not specify dayOfMonth, the day of the month will be from the current date, which is determined by the JVM in which webMethods Integration runs. If you specify an invalid value for day, the service ends with an error from the JDK.
hour
String. The hour of the day expressed as an Integer from 0 through 23. If you do not specify hour, the hour is from the current time, which is determined by the JVM in which webMethods Integration runs. If you specify an invalid value for hour, the service ends with an error from the JDK.
minute
String. The minute expressed as an Integer from 0 through 59. If you do not specify minute, the minute is from the current time, which is determined by the JVM in which webMethods Integration runs. If you specify an invalid value for minute, the service ends with an error from the JDK.
second
String. The seconds of the hour expressed as an Integer from 0 through 59. If you do not specify second, the second will be from the current time, which is determined by the JVM in which webMethods Integration runs. If you specify an invalid value for second, the service ends with an error from the JDK.
millis
String. The number of milliseconds expressed as a Long. If you do not specify millis, the millis is from the current time, which is determined by the JVM in which webMethods Integration runs. If you specify an invalid value for millis, the service ends with an error from the JDK.
timezone
String. The time zone. If you specify a value for timezone, the service ignores the useSystemTimeZone parameter value. It is recommended to supply the full name for timezones, such as Asia and Tokyo, or use UTC. If pattern includes a timezone, you must specify timezone input parameter value or set useSystemTimeZone to true.
useSystemTimeZone
String. Indicates whether the service uses the time zone of the webMethods Integration JVM if timezone was not specified. Set to:
  • true to use the time zone of webMethods Integration when timezone is not specified.
  • false if you do not want the service to use the timezone of webMethods Integration if timezone was not set. The default is false.

If pattern includes a timezone, you must specify the timezone input parameter value or set useSystemTimeZone to true.

To match the behavior of date:dateTimeBuild that produced a date and time that always included a timezone set useSystemTimeZone to true. This ensures that if timezone is not specified, the resulting date or time will include a time zone.

locale
String. The locale in which to express the date.
Output parameters
value
String. The formatted date and time.
Note: The build service replaces the date:dateBuild and date:dateTimeBuild services which are deprecated.

If you specify a parameter that does not exist in the supplied pattern, the service ignores that parameter.

If you do not specify a timezone, useSystemTimeZone is set to false, and the pattern includes a time zone, the service ends with an exception.

If a time zone is provided as input to the service either in the timezone parameter or by setting useSystemTimeZone to true, the build service calculates the date/time starting with a "zoned" date/time. The resulting values can differ when daylight savings time transitions are in effect. If no time zone is provided as input to the service either by not specifying timezone or by setting useSystemTimeZone to false, then the build service calculates the date/time starting with an "unzoned" date/time.

The build service is similar to date:dateBuild and date:dateTimeBuild, however, the build service allows the building of a date and time that does not include a time zone. Furthermore, the build service assembles a date/time using each of the provided parameters. Therefore the build service can build a date and time with a value that would be invalid in the current time zone, such as a date/time that would fall into the gap of a daylight saving time transition. This is unlike the date:dateBuild and date:dateTimeBuild services which build a local java.util.Date object that uses the timezone of the machine running webMethods Integration. The date:dateBuild and date:dateTimeBuild service then applies the offset between the local timezone and the specified timezone.

increment

Increments or decrements a date and time by a specified amount of time.

Input parameters
startDate
String. Starting date and time.
startDatePattern
String. Pattern in which the startDate value is specified. For more information about these pattern letters and symbols, see the Oracle Java API documentation for the DateTimeFormatter class.
endDatePattern
String. Pattern in which to format the resulting date and time. For more information about these pattern letters and symbols, see the Oracle Java API documentation for the DateTimeFormatter class. If no endDatePattern is specified, the endDate is returned in the format that is specified in the startDatePattern parameter.
timezone
String. The time zone to use for parsing startDate and formatting endDate. The service uses timezone to parse the startDate String and convert it from the time zone that is specified in the input, if one was provided. For example, if the timezone input parameter is MST and the startDate is 2019-02-21 11:30:00 EST, then the service converts the startDate time from EST to MST. The service uses timezone when formatting endDate as a String. That is, the timezone determines the time zone in which the service expresses the endDate.
locale
String. Locale in which the endDate is to be expressed.
addYears
String. The number of years to add to startDate. The value must be an integer between -2147483648 and 2147483647.
addMonths
String. The number of months to add to startDate. The value must be an integer between -2147483648 and 2147483647.
addDays
String. The number of days to add to startDate. The value must be an integer between -2147483648 and 2147483647.
addHours
String. The number of hours to add to startDate. The value must be an integer between -2147483648 and 2147483647.
addMinutes
String. The number of minutes to add to startDate. The value must be an integer between -2147483648 and 2147483647.
addSeconds
String. The number of seconds to add to startDate. The value must be an integer between -2147483648 and 2147483647.
addMilliseconds
String. The number of milliseconds to add to startDate. The value must be an integer between -2147483648 and 2147483647.
useSystemTimeZone
String. Whether to use the system time zone to increment the date and time when the startDate value does not have a time zone. Set useSystemTimeZone to true to apply the system time zone during date and time calculation.
  • false if the startDate does not include a time zone, the timezone parameter was not set, and you want to increment the date and time without being affected by a timezone. This is the default.
  • true to use the system timezone when incrementing the startDate.

When useSystemTimeZone is false and no timezone is provided, the resulting endDate will not include a timezone. To match the behavior of date:incrementDate, which produced a date and time that always included a timezone, set useSystemTimeZone to true.

useSameInstant
String. Whether to use the same Instant, where Instant represents a moment on the timeline in UTC, or the same unzoned date or time when applying a different time zone. Using the same Instant will usually result in changes to the unzoned date or time when the time zone and it is offset are applied. Not using the same Instant results in the unzoned date or time being unchanged when the time is applied. If useSameInstant is true, the increment service uses the Instant (the absolute time with no time zones) to determine how the timezone value is used.

If useSameInstant is false, the increment service uses the unzoned date/time and changes only the time zone. The default is true.

Note: In this documentation, the term unzoned date/time is synonymous with the term local date/time. For example, if startDate is a date/time of 2019-02-25 08:25:00 CET (Central European Time, UTC+1:00) and the specified timezone value is America/New_York (EST, UTC-5:00) , the value of useSameInstant has the following impact:
  • If useSameInstant is true, then 2019-02-25 08:25:00 CET becomes 2019-02-25 02:25:00 EST
  • If useSameInstant is false, then 2019-02-25 08:25:00 CET becomes 2019-02-25 08:25:00 EST
Output parameters
endDate
String. The incremented date and time.
Note: The increment service replaces the date:incrementDate service that is deprecated.

The increment service can be used to decrement a date and time by specifying negative numbers. The addYears, addMonths , addDays, addHours , addMinutes, addSeconds, and addMilliSeconds input parameters can take positive or negative values.

The service ends with an exception if the format of the date that is specified in the startDate parameter does not match the format that is specified in the startDatePattern.

If endDatePattern includes a time zone, such as "z", then the input string and startDatePattern must also have time zone fields, or timeZone must be set, or useSystemTimeZone must be true. Otherwise, the service ends with an error.

If you specify only the startDate, startDatePattern, and endDatePattern input parameters and do not specify any of the optional input parameters to increment the period, the increment service just converts the format of startDate from startDatePattern to endDatePattern and returns it as endDate.

If you specify a value for timezone, the service ignores the useSystemTimeZone parameter value.

If you specify a value for timezone and the startDate includes a time zone, then the service uses the supplied timezone to convert the startDate time zone.

If you do not specify a value for timezone and the startDate includes a time zone, then the service uses the time zone in the startDate and ignores the useSystemTimeZone parameter.

If you do not specify a value for timezone, the startDate does not include a time zone, and useSystemTimeZone parameter is true, then the service uses the system time zone.

If startDate does not include a time zone, you do not specify a value for timezone, and useSystemTimeZone is false, the resulting endDate will not include a time zone.

The increment service is similar to date:incrementDate, however, the increment service provides more specific handling of time zones. To match the behavior of date:incrementDate, set useSameInstant to true.