Text - Format date/time |
Declaration
|
<AMTEXT ACTIVITY="format_datetime" RESULTVARIABLE="text" DATETIMEFORMAT="text" INCLUDEAMPM="YES/NO" ACTION="text (options)" SPECIFIEDDATETIME="text" SPECIFIEDFORMAT="text" ADJUSTYEAR="number" ADJUSTMONTH="number" ADJUSTDAY="number" ADJUSTHOUR="number" ADJUSTMINUTE="number" ADJUSTSECOND="number" /> |
Description
Converts a date and time value into the specified format. The date and time format string defines the text representation of a date/time that results from this activity's formatting operation. It can also be used to adjust the specified date/time to some other date/time offset.
Practical Usage
Useful for transforming an existing date and time string so that it matches a required format, which can be ideal when interactions are performed with other programs, applications or systems that expect a specific format. For example, an application being automated may require a date to be entered in a specific format such as 'yyyy-dd-mm'. This activity can be used to modify the value accordingly. Also, enables you to generate formatted text representing the current date/time, or the date/time offset by a certain number of days/months/or years. The value generated can then be used to rename a file or create a folder for file archiving purposes.
|
NOTE: A list of common date/time format specifiers along with output examples are included below under Custom Date and Time Format Strings. |
Parameters
General
|
Property |
Type |
Required |
Default |
Markup |
Description |
|
Formatted date time |
--- |
--- |
--- |
--- |
Displays the current date/time in the adjusted format. Any modifications to the format are shown in real-time. This area is used as a visual parameter during design time, therefore, contains no properties or markups. |
|
Date time format |
Text |
Yes |
(Empty) |
DATETIMEFORMAT="dd/mm/yyyy hh:nn:ss" |
The format that should be used when the date/time is output. Press the drop-down arrow to select from a list of common formats or manually enter a custom format using valid characters. The result will appear in its entirety in the Formatted date time field. A list of common date/time format specifiers are included below under Custom Date and Time Format Strings. NOTE: To ensure that no formatting occurs when entering literal text, enclose the text string with single quotation marks (i.e.'literal text'). |
|
Populate variable with result |
Text |
Yes |
(Empty) |
RESULTVARIABLE="varname" |
The name of an existing variable in which to populate the formatted date/time. |
Advanced
|
Property |
Type |
Required |
Default |
Markup |
Description |
|
Action |
Text (options) |
No |
Use current date time |
|
Indicates the type of date/time value to be formatted. The available options are:
|
|
Use specified date time |
Text |
Yes if Action set to Specified date time |
Current date/time |
SPECIFIEDDATETIME= "6/12/2005 1:42:40 PM" |
Indicates the date/time to format. Press the down arrow to display a calendar interface in which to select the desired date/time or manually enter the value in the provided text-box. This parameter is active only if the Action parameter is set to Use specified date time. |
|
Will be in the format |
Text |
Yes if Action set to Specified date time |
m/d/yyyy h:nn:ss |
SPECIFIEDFORMAT= "dd/mm/yy hh:nn:ss" |
Specifies the format that should be applied when attempting to read the date/time entered. This parameter is available only if the Action parameter is set to Use specified date time. |
|
Prompt Message |
Text |
Yes if Action set to Prompt user |
(Empty) |
PROMPTMESSAGE= "Select date/time" |
Specifies the message that should appear along with the date/time prompt dialog box during runtime. This is useful in providing the user proper instructions (Example: Please select the date/time). This parameter is available only if the Action parameter is set to Prompt user. |
|
Prompt Type |
Text (options) |
No |
Prompt for date and time |
|
Specifies whether the prompt dialog box should prompt for the date, the time, or both. The available options are:
|
|
Adjust Year |
Number |
No |
0 |
ADJUSTYEAR="-4" |
Specifies the number of years the date should be adjusted by. A positive or negative number may be used (Example: entering "4" indicates plus 4 years, entering "-4" indicates minus 4 years). |
|
Adjust Hour |
Number |
No |
0 |
ADJUSTHOUR="4" |
Specifies the number of hours the date should be adjusted by. A positive or negative number may be used (Example: entering "4" indicates plus 4 hours, entering "-4" indicates minus 4 hours). |
|
Adjust Month |
Number |
No |
0 |
ADJUSTMONTH="4" |
Specifies the number of months the date should be adjusted by. A positive or negative number may be used (Example: entering "4" indicates plus 4 months, entering "-4" indicates minus 4 months). |
|
Adjust Minute |
Number |
No |
0 |
ADJUSTMINUTE="-5" |
Specifies the number of minutes the date should be adjusted by. A positive or negative number may be used (Example: entering "4" indicates plus 4 minutes, entering "-4" indicates minus 4 minutes). |
|
Adjust Day |
Number |
No |
0 |
ADJUSTDAY="-4" |
Specifies the number of days the date should be adjusted by. A positive or negative number may be used (Example: entering "4" indicates plus 4 days, entering "-4" indicates minus 4 days). |
|
Adjust Second |
Number |
No |
0 |
ADJUSTSECOND="-30" |
Specifies the number of seconds the date should be adjusted by. A positive or negative number may be used (Example: entering "30" indicates plus 30 seconds, entering "-30" indicates minus 30 seconds). |
Custom Date and Time Format Strings
To create format patterns for date and time values, combine the strings listed in the tables below. These strings represent the year, month, day, number and so on, in different formats.
Custom date specifiers
The following table describes the most common custom date format specifiers and displays an example result string produced by each. Note that format specifiers are case sensitive.
|
Specifier |
Description |
Example Result |
|
d |
Represents the day of the month, from 1 through 31. A single-digit day is formatted without a leading zero. For example, if given the first day of the month, this format returns "1". |
January 1, 2008 -> 1 |
|
dd |
Represents the day of the month, from 1 through 31. A single-digit day is formatted with a leading zero. For example, if given the first day of the month, this format returns "01". |
January 1, 2008 -> 01 |
| ddd |
Represents the abbreviated name of the day of the week (i.e. Sun). |
January 1, 2008 -> Tue |
|
dddd |
Represents the full name of the day of the week (i.e. Sunday). |
January 1, 2008 -> Tuesday |
|
M |
Represents the month as a number from 1 through 12. A single-digit month is formatted without a leading zero (i.e. March = 3). |
January 1, 2008 -> 1 |
|
MM |
Represents the month as a number from 01 through 12. A single-digit month is formatted with a leading zero (i.e. March = 03). |
January 1, 2008 -> 01 |
|
MMM |
Represents the abbreviated name of the month (i.e. December = Dec). |
January 1, 2008 -> Jan |
|
|
Represents the full name of the month (i.e. December). |
January 1, 2008 -> January |
|
y |
Represents the year, from 0 through 99. If the year has more than two digits, only the two low-order digits appear in the result. If the first digit of a two-digit year begins with a zero (for example, the year 3001), the number is formatted without a leading zero (i.e. 3001 = 1). |
January 1, 2008 -> 8 |
|
yy |
The year, from 00 through 99. If the year has more than two digits, only the two low-order digits appear in the result. If the two-digit year has fewer than two significant digits, the number is padded with leading zeros to produce two digits (i.e. 3001 = 01). |
January 1, 2008 -> 08 |
|
yyy |
Represents the year, with a minimum of three digits. If the year has more than three significant digits, they are included in the result string. If the year has fewer than three digits, the number is padded with leading zeros to produce three digits. |
January 1, 2008 -> 2008 |
|
yyyy |
Represents the year as a four-digit number. If the year has more than four significant digits, they are included in the result string. If the year has fewer than four digits, the number is padded with leading zeros to produce four digits. |
January 1, 2008 -> 2008 |
Custom Time specifiers
The following table describes the most common custom time format specifiers and displays an example result string produced by each. Note that format specifiers are case sensitive.
|
Format Specifier |
Description |
Example Result |
|
h |
Represents the hour, using a 12-hour clock from 1 to 12. The hour is represented by a 12-hour clock that counts the whole hours since midnight or noon. The hour is not rounded, and a single-digit hour is formatted without a leading zero. For example, given a time of 5:43 AM, this format specifier displays "5". |
8:10:23 AM -> 8 |
|
hh |
Represents the hour, using a 12-hour clock from 01 to 12. The hour is represented by a 12-hour clock that counts the whole hours since midnight or noon. The hour is not rounded, and a single-digit hour is formatted with a leading zero. For example, given a time of 5:43 AM, this format specifier displays "05". |
8:10:23 AM -> 08 |
|
H |
Represents the hour, using a 24-hour clock from 0 to 23. The hour is represented by a zero-based 24-hour clock that counts the hours since midnight. A single-digit hour is formatted without a leading zero. |
1:10:01 AM -> 1 1:10:01 PM -> 13 |
|
HH |
Represents the hour, using a 24-hour clock from 00 to 23. The hour is represented by a zero-based 24-hour clock that counts the hours since midnight. A single-digit hour is formatted with a leading zero. |
1:10:01 AM -> 01 1:10:01 PM -> 13 |
|
m |
Represents the minute as a number from 0 through 59. The minute represents whole minutes that have passed since the last hour. A single-digit minute is formatted without a leading zero. |
7:03:30 -> 3 |
|
mm |
Represents the minute as a number, from 00 through 59. The minute represents whole minutes that have passed since the last hour. A single-digit minute is formatted with a leading zero. |
7:03:30 -> 03 |
|
s |
Represents the seconds as a number from 00 through 59. The result returns whole seconds that have passed since the last minute. A single-digit second is formatted without a leading zero. |
10:52:07 -> 7 |
|
ss |
Represents the seconds as a number from 00 through 59. The result returns whole seconds that have passed since the last minute. A single-digit second is formatted with a leading zero. |
10:52:07 -> 07 |
|
f |
Represents the tenths of a second in a time value. |
10:52:23.734 -> 7 |
|
ff |
Represents the hundreds of a second in a time value. |
10:52:23.734 -> 73 |
|
fff |
Represents the milliseconds in a time value. |
10:52:23.734 -> 734 |
|
t |
Represents the first character of the AM/PM designator (i.e. AM = A, PM = P). The AM designator is used for all times from 0:00:00 (midnight) to 11:59:59.999. The PM designator is used for all times from 12:00:00 (noon) to 23:59:59.999. |
13:30:28 -> P |
|
tt |
Represents the AM/PM designator. The AM designator is used for all times from 0:00:00 (midnight) to 11:59:59.999. The PM designator is used for all times from 12:00:00 (noon) to 23:59:59.999. |
13:30:28 -> PM |
|
z |
Represents the signed offset of the local operating system's time zone from Coordinated Universal Time (UTC), measured in hours. The offset is always displayed with a leading sign. A plus sign (+) indicates hours ahead of UTC, and a minus sign (-) indicates hours behind UTC. A single-digit offset is formatted without a leading zero. |
UTC +1:00 -> +1 |
|
zz |
Represents the signed offset of the local operating system's time zone from UTC, measured in hours. The offset is always displayed with a leading sign. A plus sign (+) indicates hours ahead of UTC, and a minus sign (-) indicates hours behind UTC. A single-digit offset is formatted with a leading zero. |
UTC +1:00 -> +01 |
|
zzz |
Represents the signed offset of the local operating system's time zone from UTC, measured in hours and minutes. The offset is always displayed with a leading sign. A plus sign (+) indicates hours ahead of UTC, and a minus sign (-) indicates hours behind UTC. A single-digit offset is formatted with a leading zero. |
UTC +1:00 -> +1:00 |
Examples
- The sample AML code below can be copied and pasted directly into the Steps Panel of the Task Builder.
- Parameters containing user credentials, files, file paths, and/or other information specific to the task must be customized before the sample code can run successfully.
Sample Task 1
A Format date time activity used to prompt the user for a specific date/time. A message box displays the date and time selected in the following format m-d-yyyy h-nn-ss.
|
<AMVARIABLE NAME="theDateTime" /> <AMTEXT ACTIVITY="format_datetime" RESULTVARIABLE="theDateTime" DATETIMEFORMAT="m-d-yyyy h-nn-ss" INCLUDEAMPM="YES" ACTION="prompt" PROMPTMESSAGE="Please select date/time." /> <AMSHOWDIALOG>%theDateTime% is the date and time selected.</AMSHOWDIALOG> |
Sample Task 2
This task uses the Format date time activity to format the current date to 30 days prior and writes the results in Notepad.
|
<AMVARIABLE NAME="CurrentDate" /> <AMVARIABLE NAME="PriorDate" /> <AMTEXT ACTIVITY="format_datetime" RESULTVARIABLE="CurrentDate" DATETIMEFORMAT="mm-dd-yyyy" /> <AMTEXT ACTIVITY="format_datetime" RESULTVARIABLE="PriorDate" DATETIMEFORMAT="mm-dd-yyyy" ADJUSTDAY="-30" /> <AMRUN FILE="notepad" /> <AMINPUT>The Current Date is %CurrentDate% The Date 30 days ago was %PriorDate%</AMINPUT> |
Sample Task 3
This task will demonstrate a method to obtain the first and last day of the current month using a few variables and the ‘Format Date Time’ action. The comments (shown in green) within this task will provide further explanation.
|
<AMSHOWDIALOG MESSAGE="This task will demonstrate a method to obtain the first and last day of the current month using a few variables and the ‘Format Date Time’ action. The comments (shown in green) within this task will provide further explanation. " BUTTONS="ok_cancel" ONSECONDBUTTONCLICK="stop" /> <AMVARIABLE NAME="FirstOfThisMonth" /> <AMVARIABLE NAME="FirstOfNextMonth" /> <AMVARIABLE NAME="LastOfThisMonth" /> <!-- To get the first of this month, hard code the datetime format to mm-01-yyyy. This automatically sets the date to the first day of the current month. --> <AMTEXT ACTIVITY="format_datetime" RESULTVARIABLE="FirstOfThisMonth" DATETIMEFORMAT="mm-01-yyyy" /> <!-- To get the first of next month, hard code the datetime format to mm-01-yyyy and adjust by 1 month. This sets the date to the first day of the next month. --> <AMTEXT ACTIVITY="format_datetime" RESULTVARIABLE="FirstOfNextMonth" DATETIMEFORMAT="mm-01-yyyy" ADJUSTMONTH="1" /> <!-- To get the last of this month, use the variable that holds the value of the first day of next month (%FirstOfNextMonth%) and adjust by -1 day. --> <AMTEXT ACTIVITY="format_datetime" RESULTVARIABLE="LastOfThisMonth" DATETIMEFORMAT="mm-dd-yyyy" ACTION="specified" SPECIFIEDDATETIME="%FirstOfNextMonth%" SPECIFIEDFORMAT="mmddyyyy" ADJUSTDAY="-1" /> <AMSHOWDIALOG>The first day of this month was: %FirstOfThisMonth% The first day of next month is: %FirstOfNextMonth% The last day of this month is: %LastOfThisMonth%</AMSHOWDIALOG> |