AMPscript Language Elements
AMPscript uses the following language elements:
- Attributes and Data Extensions
AMPscript can include numeric and string constants.
Numeric constant values consist of an unquoted set of numerals and can also include one decimal point and an introductory minus sign to indicate negative values. Numeric constant values cannot contain commas.
String (or text) constant values must use double or single quotes. String constants can escape the delimiting quote if they appear within the text by doubling it. The system does not recognize alternative quote characters, such as smart quotes.
Boolean constant values must use true or false and are case-insensitive.
Functions and scripts reference subscriber attributes, email attributes, and data extension column values as unquoted strings. If the attribute, data extension column, table, or relationship name includes a space or special character, enclose the value in square brackets.
You can define additional email attributes within the email and use them in substitutions or as parameters in AMPscript function calls. The Marketing Cloud must enable the use of additional email attributes for your account. Contact your Marketing Cloud relationship manager with any questions.
Declare, initialize, and modify variables within a script. Script statements and functions can then reference variables.
A variable declaration consists of the keyword VAR followed by one or more comma-delimited variable names. Variable names must begin with @ and include at least one other letter, number, or underscore. You cannot use spaces and commas in variable names:
A variable assignment consists of the keyword SET followed by the variable name, equal sign, and value.
- Declare - VAR @variable
- Set - SET <variable>=<constant function or attribute>
Declaring a variable with the VAR keyword adds an entry to the Variables Dictionary with the variable name as the key and NULL as the value. If an entry for that name already exists, the value of the variable sets to NULL. If you use the variable to control a FOR loop, an attempt to declare it will result in a validation or runtime error.
Use this syntax for simple comparison:
Comparison operators compare values. These operators are case-insensitive.
- == Is equal to
- != Is not equal to
- > Greater than
- < Less Than
- >= Greater than or equal to
- <= Less than or equal to
Use join operators to combine multiple conditions.
- AND - Both conditions must be true
- OR - Either condition must be true
The NOT operator reverses the result of any Boolean expression.
- NOT - Reverses the Boolean expression
Control the expression evaluation using parentheses:
- IF - Use the IF statement to perform conditional processing.
- ELSEIF - Use the ELSEIF statement to perform conditional processing. Multiple ELSEIF statements can appear within an IF block.
- ELSE - Use the ELSE statement to perform conditional processing. Only one else statement can appear within an IF block.
- ENDIF - Use the ENDIF statement to end an IF block. Only one ENDIF statement must appear at the end of an IF block.
The IF statement allows the conditional execution of any content within the IF block depending on the logic expressions it contains. IF statements may nest within IF statements.
The optional ELSE statement can appear only once after the IF and all ELSEIF statements and before the ENDIF to define default behavior if none of the preceding conditions evaluate True.
You can use multiple conditions for an IF or ELSEIF statement. Join these conditions with the AND or OR keywords and group them by parentheses to control the order of evaluation. The NOT keyword can be used to reverse the evaluation:
Expressions can include any of the input types:
- Attributes and data extension values
- Function calls
If the call does not include the comparison operator and second expression, this system assumes an equal operator with a comparison value of True.
This example demonstrates how to include a variable with a value and leave that variable out if it does not include a value:
The FOR statement allows content within the FOR block to iterate over a variable number of times.
The system locks the @Variable variable from modification within the process loop.
The start and end index expressions can use any one of the four types of input that evaluates to an integer:
- Numeric constant
- Attribute or data extension value
- Function call, such as LookupRows()
The TO or DOWNTO keywords determine whether the value of the variable increases or decreases by one (1) with each iteration of the FOR loop. The variable value sets or increments by one (1) at the end of each iteration of the loop. The system compares the end index expression to the new value of the counter variable. If the value did not yet reach the end value or did not equal the end value, the loop will continue.
The NEXT statement closes the FOR loop. Optionally, follow the statement with the variable name controlling the loop.
Assign variables a value using the SET statement. Initialize only one variable using a SET statement. An attempt to set a variable in use at the counter of a FOR loop will generate a validation or runtime error. The variable takes on the type of the assigned value.
The keywords Output and OutputLine returns the results of code executed inside a code block and includes the results in the rendered content. The OutputLine keyword also appends a carriage return and line feed (CRLF) to the end of the resolved content. Output and OutputLine works with the results of a nested function or script block, and they don't support the passing of direct literals.
Given the code below:
The system prints the current date and time. The OutputLine keyword would return the same information with a CRLF appended at the end.
Given the code below:
Note that the code in this example DOES NOT WORK:
Again, the code example above does not work because Output does not support the passing of direct literals.
Given the function below:
System prints "Exampl", as the Substring() function shown returns the first 6 characters in the text starting with the first character, and it appends a CRLF at the end of the results.
AMPscript may contain comments or non-executed notes that allow you, as the author, to document your code. You must open comments with the /* sequence and close comments with the */ sequence. Comments may span multiple lines.
These AMPscript functions include Enterprise awareness:
You can use the ENT. prefix with these functions to indicate to the system that the data extension operated on exists at the parent Enterprise level.
In the following example, the system looks up data from the MERCHANT data extension stored at the Enterprise Administrator level:
Rowsets contain one or more collections of data as rows, as addressed by the Row() function. Each row contains individual data points as fields, as addressed by the Field() function. AMPscript doesn't allow direct access to rowset data via functions such as v(). Ensure that the rowset contains data using Empty() or IsNull() before further processing, such as in a FOR loop.
The Empty() and IsNull() functions both return false if the rowset doesn't contain data.
To determine the number of rows (0-x), use only the Rowcount() function.