Text - Format date/time

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. Can also be used to adjust the specified date/time to some other date/time offset.

Practical Usage

Can be used to transform an existing date and time format so that it matches a required format. For example, an application being automated may require a date to be input 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. Alternatively, it can be used for data entry when sending keystrokes to an application when a date/time is needed and will vary depending on what day the task is run.

General Parameters

Property	Type	Required	Default	Markup	Description
Date time format	Text	Yes	(Empty)	DATETIMEFORMAT="dd/mm/yyyy hh:nn:ss"	The format that should be used when the date 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 following syntax can used to create a date/time format: y = year m = month d = day h = hour n = minutes s = seconds hh = leading zero (Example: 03) h = no leading zero (Example: 3) Note: The result will appear in its entirety in the Formatted date time field.
Populate variable with result	Text	Yes	(Empty)	RESULTVARIABLE="varname"	The name of an existing variable in which to populate the formatted date/time.
12 hour format	Yes/No	No	Yes	SPECIFIED12HOUR="no"	Specifies whether hours of the day will be based on a 12 or 24 hour clock. If set to YES (default), a 12 hour clock format will be used. If set to NO, a 24 hour clock format will be used.
Include AM/PM in result	Yes/No	No	No	INCLUDEAMPM="yes"	Indicates whether an AM or PM indicator should be added to the end of the formatted time value. If set to YES, the formatted time will be followed with an AM or PM indicator. If set to NO (default), no AM/PM indicator will be included. This option is only available if the 12 hour format parameter is set to YES.

Advanced Parameters

Property	Type	Required	Default	Markup	Description
Action	Text (options)	No	Use current date time	ACTION="current" ACTION="specified" ACTION="prompt"	Indicates the type of date/time value to be formatted. The available options are: Use current date time (default): The current date and time will be formatted. Use specified date time: The date and time value specified will be formatted. Prompt user: At runtime, a dialog is presented prompting the user to select a date/time to be formatted.
Use specified date time	Text	Yes if action set to specified date time	Current date/time	PECIFIEDDATETIME= "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	PROMPTTYPE="datetime" PROMPTTYPE="date" PROMPTTYPE="time"	Specifies whether the prompt dialog box should prompt for the date, the time, or both. The available options are: Prompt for date and time - The user will be prompted for both the date and the time. A date/time calendar will appear allowing the user to select a specific date and time. Prompt for time only - The user will be prompted for the time only. A time calendar will appear allowing the user to select a specific time. Prompt for date only - The user will be prompted for the date only. A date calendar will appear allowing the user to select a specific date.
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).

Description tab - A custom description can be provided on the Description tab to convey additional information or share special notes about a task step.

Error Causes tab - Specify how this step should behave upon the occurrence of an error. (Refer to Task Builder > Error Causes Tab for details.)

On Error tab - Specify what AWE should do if this step encounters an error as defined on the Error Causes tab. (Refer to Task Builder > On Error Tab for details.)

Examples

The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.

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"></AMVARIABLE>
<AMTEXTFORMATDATETIME DATETIMEFORMAT="m-d-yyyy h-nn-ss" INCLUDEAMPM="YES" RESULTVARIABLE="theDateTime" 
ACTION="prompt" PROMPTMESSAGE="Please select date/time." />
<AMMESSAGEBOX>%theDateTime% is the date and 
time selected.</AMMESSAGEBOX>

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>
<AMVARIABLE NAME="PriorDate"></AMVARIABLE>
<AMTEXTFORMATDATETIME DATETIMEFORMAT="mm-dd-yyyy" 
RESULTVARIABLE="CurrentDate" />
<AMTEXTFORMATDATETIME DATETIMEFORMAT="mm-dd-yyyy" 
RESULTVARIABLE="PriorDate" ADJUSTDAY="-30" />
<AMRUN FILE="notepad" />
<AMSENDKEY>The Current Date is %CurrentDate%
The Date 30 days ago was %PriorDate%</AMSENDKEY>

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.

<AMMESSAGEBOX BUTTONS="ok_cancel" ONSECONDBUTTONCLICK="stop">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. 
</AMMESSAGEBOX>
<AMVARIABLE NAME="FirstOfThisMonth"></AMVARIABLE>
<AMVARIABLE NAME="FirstOfNextMonth"></AMVARIABLE>
<AMVARIABLE NAME="LastOfThisMonth"></AMVARIABLE>
<!-- 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. -->
<AMTEXTFORMATDATETIME DATETIMEFORMAT="mm-01-yyyy" 
RESULTVARIABLE="FirstOfThisMonth" />
<!-- 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. -->
<AMTEXTFORMATDATETIME DATETIMEFORMAT="mm-01-yyyy" 
RESULTVARIABLE="FirstOfNextMonth" 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. -->
<AMTEXTFORMATDATETIME DATETIMEFORMAT="mm-dd-yyyy" 
RESULTVARIABLE="LastOfThisMonth" ACTION="specified" 
SPECIFIEDDATETIME="%FirstOfNextMonth%" SPECIFIEDFORMAT="mmddyyyy" 
ADJUSTDAY="-1" />
<AMMESSAGEBOX>The first day of this month 
was:&#xD;&#xA;%FirstOfThisMonth%&#xD;&#xA;&#xD;&#xA;The 
first day of next month is: &#xD;&#xA;%FirstOfNextMonth%&#xD;&#xA;&#xD;&#xA;The 
last day of this month is: &#xD;&#xA;%LastOfThisMonth%</AMMESSAGEBOX>

Copyright © Fortra, LLC and its group of companies.
All trademarks and registered trademarks are the property of their respective owners.
v10 | 202212080228 | December 2022