This document contains conceptual, procedural, and scenario information about utilities AMPscript functions.

Why Use the Utilities AMPscript Functions

You can use these functions to perform basic functions for an email message or landing page within your ExactTarget account. For example, you can use the Concat() function to bring together the values of several variables into a single text string within an email message.

How To Use the Utilities AMPscript Functions

Create your AMPscript using the functions below and place them in the content areas of email messages or landing pages.

Add(N1,N2)

Returns the sum of N1 and N2.

Arguments

  • N1    First value to add
  • N2    Second value to add

Example

Given @abc=10 and @def=20

%%=Add(@abc,@def)=%%

The system returns:

30 

AttributeValue(S1)

Returns the value of a subscriber attribute.

Arguments

  • S1    The name of the attribute to be returned

Example

Combined with a Lookup call to get the name of an attribute, you can retrieve an attribute's value and pass it into a variable. For example, this code retrieves the value of zipcode.

VAR @AttributeName, @AttributeValue
SET @AttributeName = Lookup("PostalCode","zipcode","PostalCode",Indianapolis)
SET @AttributeValue = AttributeValue(@AttributeName)

Base64Decode(S1,S2)

Decodes Base64 information into human-readable text.

Arguments

  • S1    The location of the Base64 text, either in a variable or a data extension field (via the Lookup() AMPscript function)
  • S2    The character type to be used in the decoding process, i.e. UTF-8, UTF-16 or other .NET-supported character type (Optional)
  • B1    Indicates whether the email send proceeds if the value of S1 is incorrectly coded. Valid values include the following:
    • 0 - The send proceeds even if that send encounters an error
    • 1 - The send fails if it encounters an error and no message goes out (this is the default behavior if not specified)

Example

%%[
VAR @encodedStr, @decodedStr
SET @encodedStr = Lookup("Base64Info", "ReceiptData", "ReceiptKey", 1)
SET @decodedStr = Base64Decode(@encodedStr,"UTF-8")
]%%

The Lookup() function retrieves the Base64 information from the data extension, and the Base64Decode() decodes the Base64 information and assigns that value to the @decodedStr variable in UTF-8 format. If for some reason the value of @encodedStr is incorrect, the 1 at the end of the Base64Decode() function causes the send to fail due to the error.

%%[
VAR @encodedStr, @decodedStr
SET @encodedStr = Lookup("Base64Info", "ReceiptData", "ReceiptKey", 0)
SET @decodedStr = Base64Decode(@encodedStr,"UTF-8", 1)
]%%

If the value was 0, the send would continue and the email would contain an empty string instead of the decoded data.

Base64Encode(S1)

Encodes human-readable text into Base64 information.

Arguments

  • S1    The location of the text to be encrypted, either in a variable or a data extension field (via the Lookup() AMPscript function)

Example

%%[
VAR @normalStr, @encodedStr
SET @normalStr = Lookup("ForBase64Info", "ReceiptData", "ReceiptKey", 1)
SET @encodedStr = Base64Encode(@normalStr)
]%%

The Lookup() function retrieves the text information from the data extension, and the Base64Encode() encodes the text into Base64 information and assigns that value to the @encodedStr variable.

Char(S1,S2)

Returns the ASCII character specified by the ASCII character code in the first parameter. An optional second parameter specifies the number of times to repeat the return of the ASCII character.

Arguments

  • S1    Character Code
  • S2    Number of times to repeat the ASCII character (Optional)

Example

Given the function below:

Char(65)

The system returns:

A

Given the function below:

Char(65,3)

The system returns:

AAA

Given the function below:

%%=CHAR(65)=%%%%=CHAR(66)=%%%%=CHAR(67)=%%

The system returns:

ABC

The code sample below pulls content from a data extension and replaces and carriage return-line feed combinations with an HTML <br> tag.

%%[

VAR @content, @replacedContent

/* This will pull the content out of the DE and replace any CR-LF's with HTML BR tags. */

SET @content = Lookup("ReplaceTest", "Value", "Key", "1")

SET @replacedContent = Replace(@content, Concat(CHAR(13), CHAR(10)), "<BR>")

]%% 
%%=V(@content)=%%

%%=V(@replacedContent)=%%

Concat(S1,S2,...Sn)

Concatenates the strings specified in the arguments.

Arguments

  • S1-Sn    Strings to concatenate

Example

%%=Concat("a","b","c")=%%

The system returns:

abc

DecryptSymmetric(S1, S2, S3, S4, S5, S6, S7, S8)

Decrypts encrypted data using the supplied algorithm and encryption values. You can supply either a value or a valid external key for the password, initialization vector, and Salt. You can also use the external keys if you have previously created keys in the Key Management section of the user interface. Otherwise, the function generates a password using the password parameter or stored value, the Salt parameter or stored value, and the IV parameter or stored value. If you do not pass or reference an initialization vector, the function uses the password parameter or stored value as the initialization vector. 

This function treats Salt and IV values (either directly provided or looked up by key) as hex strings, with each pair of characters repesenting a single byte in the larger strings. Do not attempt to use these values as a cipher string, as you cannot successfully decrypt those strings use this function.

Arguments

  • S1    Encrypted data passed to the function
  • S2    Algorithm used to encrypt the data:
    • aes - AES algorithm
    • des - DES algorithm
    • tripledes - TripleDES algorithm
      • Mode (Optional, for use with DES and TripleDES only):
        • cbc (default)
        • ecb
        • ofb
        • cfb
        • cts
      • Padding (Optional, for use with DES and TripleDES only):
        • none
        • pkcs7 (default)
        • zeros
        • ansix923
        • iso10126
  • S3    Password external key
  • S4    Password
  • S5    Salt external key
  • S6    Salt
  • S7    Initialization vector external key
  • S8    Initialization vector

Example

The example below sets the @clearData variable to the value of the @endData once the function decrypts that data. This example uses provided values for the password, salt, and IV, and it sets any external key values to the undeclared variable @null. Note that the Salt and IV values provided in the example below represent hex string values - the Salt value includes 8 bytes of information, and the IV value provides 16 bytes.

SET @clearData=DecryptSymmetric(@encData, "AES", @null, "aardvark", @null, "0000000000000000", @null, "00000000000000000000000000000000")
The example below uses external keys instead of provided values:
SET @clearData=DecryptSymmetric(@encData, "AES", @passwordExternalKey, @null, @saltExternalKey, @null, @IVExternalKey, @null)
SET @clearData=DecryptSymmetric(@encData, "AES", "passwordExternalKey", @null, "saltExternalKey", @null, "IVExternalKey", @null)

Divide(N1, N2)

Returns the result (quotient) of dividing the first argument by the second argument.

Arguments

  • N1    Value to be divided-the dividend.
  • N2    Value to divide by-the divisor.

Example

Given @abc=100 and @def=5

%%=Divide(@abc,@def)=%%

The system returns:

20

Domain(S1)

Returns the domain portion of an email address.

Arguments

  • S1    Email address

Example

%%=Domain(sales@example.com)=%%

The system returns:

example.com

EncryptSymmetric(S1, S2, S3, S4, S5, S6, S7, S8, S9, S10)

Encrypts plain text data using the supplied algorithm and encryption values. You can supply either a value or a valid external key for the password, initialization vector, and Salt. You can also use the external keys if you have previously created keys in the Key Management section of the user interface. Otherwise, the function generates a password using the password parameter or stored value, the Salt parameter or stored value, and the IV parameter or stored value. If you do not pass or reference an initialization vector, the function uses the password parameter or stored value as the initialization vector. All output provided by this function uses base 64 encoding. 

This function treats Salt and IV values (either directly provided or looked up by key) as hex strings, with each pair of characters repesenting a single byte in the larger strings. Do not attempt to use these values as a cipher string, as you cannot successfully encrypt those strings using this function.

Arguments

  • S1    Plain text data passed to the function
  • S2    Algorithm used to encrypt the data:
    • aes - AES algorithm
    • des - DES algorithm
    • tripledes - TripleDES algorithm
      • Mode (Optional, for use with DES and TripleDES only):
        • cbc (default)
        • ecb
        • ofb
        • cfb
        • cts
      • Padding (Optional, for use with DES and TripleDES only):
        • none
        • pkcs7 (default)
        • zeros
        • ansix923
        • iso10126
  • S3    Password external key
  • S4    Password
  • S5    Salt external key
  • S6    Salt
  • S7    Initialization vector external key
  • S8  Initialization vector

Example

The example below sets the @encData variable to the encrypted value of the plain text supplied in the function (in this case, the word Example). This example uses provided values for the password, salt, and IV, and it sets any external key values to the undeclared variable @null. Note that the Salt and IV values provided in the example below represent hex string values - the Salt value includes 8 bytes of information, and the IV value provides 16 bytes.
SET @encData=EncryptSymmetric("Example", "AES", @null, "password", @null, "0000000000000000", @null, "00000000000000000000000000000000")
The examples below use external keys instead of provided values.
SET @encData=EncryptSymmetric("Example", "AES", @PasswordExternalKey, @null, @saltExternalKey, @null, @IVExternalKey, @null)
SET @encData=EncryptSymmetric("Example", "AES", "PasswordExternalKey", @null, "saltExternalKey", @null, "IVExternalKey", @null)

This example uses the ebc mode of the DES algorithm:

SET @encData=EncryptSymmetric("Example", "des;mode=ecb;padding=zeros", @null, "0x7FEBCBCBCB9BCB01", @null, @null, @null, @null)

Empty (V1)

Returns True if the value is the empty string or NULL.

Arguments

  • V1    Variable to evaluate

Example

Given @abc=27

%%=Empty(@abc)=%%

The system returns:

False

Format (V1, S1)

Formats the value according to the string you specify.

Arguments

  • V1    Variable to format
  • S1    A C# compatible format string. Valid values include:
    • MM/dd/yyyy
    • Cn (currency format where n represents the number of decimal places)

There are multiple possibilities for displaying the date using this function. For a more complete list, see the Microsoft help regarding the DateTimeFormatInfo Class.

For more information on formatting numeric strings, see the Microsoft help regarding the NumberFormatInfoClass.

Example 1

%%=Format(Now(),"MM/dd/yyyy")=%%

System returns today's date in MM/dd/yyyy format.

Example 2

%%=Format(@currency_variable,"$#,#.00;-$#,#.00")=%%

FormatCurrency(V1,S1,N1,S2)

Formats a specified string as a currency value.

Arguments

  • V1 - Value to receive the specified formatting
  • S1 - Culture code used to indicate the correct currency unit
  • N1 - (Optional) The number of decimal places to include in the formatted value
  • S2 - (Optional) The currency symbol to use with the value. This value overrides the value specified by the culture code in S1.

This function rounds the numbers up if the specified format uses fewer decimal points than the value itself and the remaining numbers are 5 or over. The function rounds the numbers down if the specified format uses fewer decimal points than the value itself and the remaining numbers total less than 5. 

Example 1

%%=FormatCurrency(1234.567,"en-US")=%%

System returns:

$1234.57

Example 2

%%=FormatCurrency(-12300099.45678,"fr_FR",3,"*$*")=%%

System returns:

$-12 300 099,457 *$*

FormatDate(V1,S1,S2,S3)

Formats a specified string as a date value.

Arguments

  • V1 - Value to receive the specified formatting
  • S1 - (Optional) Date format string used to format the specified value
  • S2 - (Optional) Time format string used the formation the specified value
  • S3 - (Optional) Culture code used to indicate the correct date format

This function rounds the numbers up if the specified format uses fewer decimal points than the value itself. 

Example

%%=FormatDate(2012-10-05 03:21:34.567890, "MMM DD, YYYY", "HH:MM:SS.MMM", "en-US")=%%

System returns:

Dec 10, 2012 03:21:34.567890

You can review available date and time formatting options in the AMPscript Syntax Guide.

FormatNumber(V1,P1,S1)

Formats a number value as specified by the AMPscript arguments.

Arguments

  • V1 - Value to receive the specified formatting.
  • P1 - Valid format type value:
    • C - Currency
    • D - Decimal
    • E - Exponential
    • F - Fixed point
    • G - General
    • N - Number
    • P - Percent
    • R - Round-trip
    • X - Hexadecimal
    • You can optionally follow this code with a number to indicate the precision of the number. For example, a currency value with a precision of 2 uses the parameter C2.
  • S1 - (Optional) Culture code used to indicate the correct date format

This function rounds the numbers up if the specified format uses fewer decimal points than the value itself and the remaining numbers are 5 or over. The function rounds the numbers down if the specified format uses fewer decimal points than the value itself and the remaining numbers total less than 5. 

Example 1

%%=FormatNumber(1234.567,"C2","en-US")=%%

System returns:

1234.57

Example 2

%%=FormatNumber(-12300099.45678,"N","fr-FR")=%%

System returns:

-12 300 099,4568'

GUID()

Returns a new GUID as a string value.

Example

var @myGUID
set @myGUID = GUID()

The system created the @myGUID variable and sets the value of that variable with the string generated by GUID().

IIf(E1,S1,S2)

Returns the second parameter if the first parameter evaluates True. Returns the third parameter if the first parameter evaluates False.

Arguments

  • E1    Expression to evaluate
  • S1    Value to return if the expression evaluates TRUE
  • S2    Value to return if the expression evaluates FALSE

Example

%%=IIF(EMPTY(@VAR),"123",@VAR)=%%

The system returns the value 123 if the @VAR variable is empty and returns the value of @VAR if it exists.

IndexOf(V1, S1)

Returns character position where string occurs in the variable. Index numbering begins with 1.

Arguments

  • V1    Variable to analyze
  • S1    Value whose character position to return

Example

Given @abc=You will love our product.

%%=IndexOf(@abc,"love")=%%

System returns:

10

For the code below, the system returns 1:

%%[
var @abc
Set @abc = "ab"
var @index
Set @index = IndexOf(@abc,"a")
Output(v(@index))
]%%

IsEmailAddress(S1)

Returns a true or false result indicating whether the string value passed in is a valid email address. This function uses the same email validation logic as the rest of the application.

Arguments

  • S1    The email address to be validated

Example

If the email address joe@example.com is valid, then the function listed below will return a "true" value. Otherwise, the function below returns a "false" value.

IsEmailAddress("joe@example.com")

IsNull(P1)

Returns a true value if the specified parameter is null.

Arguments

  • P1    Parameter to check for null value

Example

Given @Row is null

IsNull(@Row)

System returns:

true

IsPhoneNumber(P1)

Returns a true or false result indicating whether the string value passed in is a valid phone number. This function uses the same phone number validation as the SMS components of the application.

Argument

  • P1    The phone number to be validated

Example

 

If the phone number 555-555-5555 is valid, then the function listed below will return a "true" value. Otherwise, the function below returns a "false" value.

IsPhoneNumber("5555555555")

Length(V1)

Returns the character length of the string you specify.

Arguments

  • V1    Variable whose characters to count

Example

Given @abc=Hello world!

%%=Length(@abc)=%%

System returns:

12

Lowercase(S1)

Returns the specified value in all lowercase letters.

Arguments

  • S1    Value to return in lowercase letters

Example

Given @name=MARY KAY

%%=Lowercase(@name)=%%

System returns:

mary kay

MD5(S1,S2)

Converts a string to a 16-byte MD5 hash value. This function returns a hex representation of the 16-byte MD5 hash result. This is a one-way hash conversion and does not allow later decryption.

Arguments

  • S1    The string to convert to a hex representation of the 16-byte MD5 hash result
  • S2    (Optional) The character set to use for the encoding; this function defaults to UTC-8 if not specified. You can also specify         UTC-16.

Example

MD5("This is a string.")

Returns the MD5 hash tag 13562b471182311b6eea8d241103e8f0.

MD5("This is a string.", "UTF-16")

Returns the MD5 hash tag 992b4a733b5f27475f52021f09120cc5.

Mod(N1, N2)

Returns the remainder after dividing the first number by the second number.

Arguments

  • N1    Value to be divided-the dividend
  • N2    The value to divide by-the divisor

Example

Given @abc=10 and @def=4

%%=Mod(@abc,@def)=%%

System returns:

2

Multiply(N1, N2)

Returns the product of multiplying two numbers.

Arguments

  • N1    A factor to be multiplied
  • N2    A factor to be multiplied

Example

Given @abc=10 and @def=5

%%=Multiply(@abc,@def)=%%

System returns:

50

Output(C1)

Returns the results of AMPscript code executed within a code block (such as Concat() or V()) and includes the results inside the rendered content. The function does not return any passed direct literals.

Arguments

  • V1    The code that produces the results to be output by the system

Example

%%[ var @output
Set @output = "My output"
Output(Concat(@output," is a success!")) ]%%

System outputs:

My output is a success!

OutputLine(C1)

Returns the results of AMPscript code executed within a code block (such as Concat() or V())and includes the results inside the rendered content. This function also appends a CRLF following the results. The function does not return any passed direct literals.

Arguments

  • V1    The code that produces the results to be output by the system

Example

%%[ var @output
Set @output = "My output"
OutputLine(Concat(@output," is a success!")) ]%%

System outputs:

My output is a success!

Note that the system outputs the CRLF after the string of text.

ProperCase(S1)

Returns specified string with initial letter of each word capitalized.

Arguments

  • S1    String to return with initial capitalization

Example

Given @name=mary kay

%%=ProperCase(@name)=%%

System returns:

Mary Kay

Random(I1, I2)

Returns a random integer between the values you specify (inclusive).

Arguments

  • I1    The least value the returned random integer can be
  • I2    The greatest value the returned random integer can be

Example

Given @low=2 and @high=200

%%=Random(@low,@high)=%%

System returns a random value greater than or equal to 2 and less than or equal to 200.

RegExMatch(S1,S2,S3,S4...Sn)

Allows you to use a regular expression to search for information in a string.

Arguments

  • S1    The string to be searched
  • S2    The regular expression to use in the search
  • S3    The name or ordinal of the matching group to return
  • S4    Repeating string parameter of regular expression options to use

You can use any value from the .NET RegexOptions enumeration, such as IgnoreCase and Multiline.

Example

The sample AMPscript below shows how to assign regular expressions and use the RegExMatch function to search a string for results.

%%[
VAR @sourceStr, @regEx1, @regEx2

SET @sourceStr = "ABC_123_DEF_456";

/* RegEx without group names */
SET @regEx1 = ".*_([0-9]+)_.*_([0-9]+)"

/* RegEx with group names */
SET @regEx2 = ".*_(?<FirstNumber>[0-9]+)_.*_(?<SecondNumber>[0-9]+)"
]%%

By Group ID:
Group 1:  %%=RegExMatch(@sourceStr, @regEx1, 1)=%%
Group 2:  %%=RegExMatch(@sourceStr, @regEx1, "2")=%%

By Group Name:
First Number:   %%=RegExMatch(@sourceStr, @regEx2, "FirstNumber")=%%
Second Number:  %%=RegExMatch(@sourceStr, @regEx2, "SecondNumber")=%%

%%[
/* Check for possible match. */
VAR @result
SET @result = RegExMatch("ABC_dEF_GHI", ".*_(D..)_.*", 0, "IgnoreCase", "Multiline")
IF Length(@result) > 0 THEN]%%
  Matched!
%%[ ELSE ]%%
  No match...
%%[ ENDIF ]%%

Replace(V1, S1, S2)

Replaces the first string value with the second string value in the variable.

Arguments

  • V1    The variable on whose value the replace operates
  • S1    The string to replace
  • S2    The string to use to replace S1

Example

Given @name=The 2007 model is better.

%%=Replace(@name,"2007","2008")=%%

System returns:

The 2008 model is better.

ReplaceList(S1, S2, S3,...Sn)

Searches a string value for one or more string values you specify and replaces those values with another string value.

Arguments

  • S1    String value to search
  • S2    Replacement string
  • S3.Sn    String values to be replaced with the value in S2

Example

ReplaceList("ABCDEFG", "X", "A", "C", "E", "G")

System returns:

XBXDXFX

SHA1(S1,S2)

Returns an SHA1 hash tag based on the string value passed through the function.

Arguments

  • S1    The alphanumeric string on which the SHA1 hash tag is based
  • S2    (Optional) The character set to use for the encoding; this function defaults to UTF-8 if not specified. You can also specify UTF-16.

Example

%%=SHA1("Insert Text Here","UTF-16")=%%

The above function returns a hash tag in UTF-16 format based off of the text string "Insert Text Here."

SHA256(S1,S2)

Returns an SHA256 hash tag based on the string value passed through the function.

Arguments

  • S1    The alphanumeric string on which the SHA256 hash tag is based
  • S2    (Optional) The character set to use for the encoding; this function defaults to UTF-8 if not specified. You can also specify UTF-16.

Example

%%=SHA256("Insert Text Here","UTF-16")=%%

The above function returns a hash tag in UTF-16 format based off of the text string "Insert Text Here."

SHA512(S1,S2)

Returns an SHA512 hash tag based on the string value passed through the function.

Arguments

  • S1    The alphanumeric string on which the SHA512 hash tag is based
  • S2    (Optional) The character set to use for the encoding; this function defaults to UTF-8 if not specified. You can also specify UTF-16.

Example

%%=SHA512("Insert Text Here","UTF-16")=%%

The above function returns a hash tag in UTF-16 format based off of the text string "Insert Text Here."

StringToDate(S1,S2)

Parses a datetime string with the user's current settings and returns a .NET datetime object.

Arguments

  • S1    String to be parsed
  • S2    (Optional) The character set to use for the encoding; this function defaults to UTC-8 if not specified. You can also specify UTC-16.

Example

StringToDate("2009-10-31 08:00 AM")

System returns a datetime object with a value of 8am on October 31st, 2009.

StringToHex(S1,S2)

Returns the hex string of bytes that make up a string value.

Arguments

  • S1    The string to be encoded
  • S2    (Optional) The character set to use for the encoding; this function defaults to UTC-8 if not specified. You can also specify UTC-16.

Example

StringToHex("This is a string.")

Returns the hex string 54686973206973206120737472696e672e.

Substring(S1, I1, I2)

Returns the portion of the specified string starting with the specified character position and no longer than the specified length. If the specified character position is greater than the length of the specified string, an empty string is returned.

Arguments

  • S1    The string from which to return a portion
  • I1    The character position at which to begin the substring
  • I2    Maximum length of the substring

Example

%%=Substring("abcdef",2,2)=%%

System returns:

bc

Subtract(N1, N2)

Returns the difference of two integers.

Arguments

  • N1    Number from which to subtract N2
  • N2    Number to subtract from N1

Example

Given @abc=20 and @def=5

%%=Subtract(@abc,@def)=%%

System returns:

15

Trim(S1)

Returns the value of the string parameter with the leading and trailing white space removed.

Arguments

  • S1    String from which to trim white space

Example

%%=Trim("   Text   ")=%%

System returns:

Text

Uppercase (S1)

Returns the specified value in all uppercase letters.

Arguments

  • S1    Value to return in uppercase letters

Example

Given @name=mary kay

%%=Uppercase(@name)=%%

System returns:

MARY KAY

V(S1)

Outputs the value of a variable.

Arguments

  • S1    Name of the variable whose value to return

Example

%%[
Var @var1
Set @var1="Hello"
]%%
<p>%%=v(@var1)=%%</p>

System returns:

Hello

Was This Page Helpful?
Last updated by ryan.williams at 09:45, 24 Jun 2014