Contents
Functions
The Field Codes include the following functions:
String Functions
The Field Codes include the following string functions:
Find
Description
Finds a substring within a string. Returns the 0-
based character position of the found substring. Returns –1 if the substring is not found.
Syntax
Find(SearchIn, SearchFor
)
Argument |
Description |
---|---|
SearchIn |
The string to search in |
SearchFor |
The string to search for |
Remarks
Example |
Result |
---|---|
<$Find("Hello, World!", "H")$> |
0
|
<$Find("Hello, World!", "lo")$> |
3
|
<$Find("Hello, World!", "Qbert")$> |
-1
|
Left
Description
Returns a string containing a specified number of characters from the left side of a specified string.
Syntax
Left(String, Number
)
Argument |
Description |
---|---|
String |
The string from which the leftmost characters are returned. |
Number |
The number of characters to return. If 0, an empty string (""
) is returned. If greater than the length of String, then the entire string is returned. |
Remarks
Example |
Result |
---|---|
<$Left("Hello, World!", 5)$> |
"Hello"
|
<$Left("Hello, World!", 0)$> |
""
|
<$Left("Hello, World!", 25)$> |
"Hello, World!"
|
Length
Description
Returns the length of a string.
Syntax
Length(String
)
Remarks
Example |
Result |
---|---|
<$Length("Hello")$> |
5
|
Mid
Description
Returns a specified substring of a string.
Syntax
Mid(String, Start, Length
)
Argument |
Description |
---|---|
String |
The string from which the substring is returned. |
Start |
The 0-
based character position at which the substring begins. If Start is greater than the length of String, then
an empty string (""
) is returned. |
Length |
The number of characters to return. If Length is 0, then an empty string (""
) is returned. If Length is greater than the portion of String after Start, then all the characters
after Start are returned. |
Remarks
Example |
Result |
---|---|
<$Mid("Hello, World!", 2, 3)$> |
"llo"
|
<$Mid("Hello, World!", 25, 5)$> |
""
|
<$Mid("Hello, World!", 7, 25)$> |
"World!"
|
Replace
Description
Returns a string in which all instances of a specified substring have been replaced with another string.
Syntax
Replace(String, Find, ReplaceWith
)
Argument |
Description |
---|---|
String |
The string containing the substring to replace |
Find |
The substring to search for |
ReplaceWith |
The replacement string |
Remarks
Example |
Result |
---|---|
<$Replace("Hello", "l", "*")$> |
"He**o"
|
<$Mid("Hello", "j", "*")$> |
"Hello"
|
<$Mid("Hello", "Hello", "")$> |
""
|
Right
Description
Returns a string containing a specified number of characters from the right side of a specified string.
Syntax
Right(String, Number
)
Argument |
Description |
---|---|
String |
The string from which the rightmost characters are returned. |
Number |
The number of characters to return. If 0, an empty string (""
) is returned. If greater than the length of String, then the entire string is returned. |
Remarks
Example |
Result |
---|---|
<$Right("Hello, World!", 5)$> |
"orld!"
|
<$Right("Hello, World!", 0)$> |
""
|
<$Right("Hello, World!", 25)$> |
"Hello, World!"
|
ToLower
Description
Returns a string that has been converted to lowercase.
Syntax
ToLower(String
)
Remarks
Example |
Result |
---|---|
<$ToLower("Hello, World!")$> |
"hello, world!"
|
ToUpper
Description
Returns a string that has been converted to uppercase.
Syntax
ToUpper(String
)
Remarks
Example |
Result |
---|---|
<$ToUpper("Hello, World!")$> |
"HELLO, WORLD!"
|
Trim
Description
Returns a copy of a specified string without specified leading or trailing characters.
Syntax
Trim(String, [CharSet
])
Argument |
Description |
---|---|
String |
The string from which to trim |
CharSet |
Optional. The characters to trim. If omitted, then white space (" \t\r\n"
) is trimmed. |
Remarks
Example |
Result |
---|---|
<$Trim(" Howdie ")$> |
"Howdie"
|
<$Trim("Howdie", "Howd")$> |
"ie"
|
<$Trim("Howdy", "y")$> |
"Howd"
|
TrimLeft
Description
The same as Trim, except it trims only leading characters.
Syntax
TrimLeft(String, [CharSet
])
TrimRight
Description
The same as Trim, except it trims only trailing characters.
Syntax
TrimRight(String, [CharSet
])
Wrap
Description
Returns a string that has been word-wrapped to a specified line length.
Syntax
Trim(String, LineLength, [LinePrefix, [Eol
]])
Argument |
Description |
---|---|
String |
The string to wrap. |
LineLength |
The maximum length, in characters, of any line, including LinePrefix (if specified), but not Eol.
|
LinePrefix |
Optional. A string to prefix to each line. Often used to “quote” e-mails being replied to. If omitted, lines are not prefixed. |
Eol |
Optional. A string to use as a line terminator. If omitted, lines are terminated with "\r\n" as usual. |
Remarks
Example:
<$Wrap(> "Once upon a midnight dreary",<
11,<
">",<
"*\r\n")$>
Result:
>Once upon*<
>a midnight*<
>dreary*
Date and Time Functions
The Field Codes include the following date/time functions:
Date
Description
Returns a Date/Time constructed from individual components or a string.
Syntax
Date(Year, Month, Day
[, Hour[, Minute[, Second
]]])
Or
Date(String[, String])
Argument |
Description |
First argument |
The string to parse. |
Second argument |
Optional. The locale that must be used to parse the first segment. Some examples include: en_US for English (United States), en_GB for English (United Kingdom), and fr_FR for French (France). See See Values for fieldcode-format-locale Option for a complete list. |
Remarks
- When using the first syntax function, the optional arguments each default to 0 if omitted. For example, <$Date(1965, 11, 23)$> is equivalent to <$Date(1965, 11, 23, 0, 0, 0)$>.
- When using the second syntax function, the date is constructed by parsing the first string. If the optional argument is omitted, first the E-mail Server fieldcode-format-locale option (See fieldcode-format-locale) in the email-processing section is used if present. Otherwise, the platform locale is used. For example:
- <$Date("November 23, 1965 9:03 AM")$> if the fieldcode-format-locale option or platform locale is set to en_US.
- <$Date(“23 novembre 1965 21:03:00”, “fr_FR”)$>
Day
Description
Returns the numeric day component of a Date/Time (1 to 31)
.
Syntax
Day(DateTime
)
Hour12
Description
Returns the numeric hour component of a Date/Time based on a 12-hour clock (1 to 12)
.
Syntax
Hour12(DateTime
)
Hour24
Description
Returns the numeric hour component of a Date/Time based on a 24-hour clock (0 to 23)
.
Syntax
Hour24(DateTime
)
IsAm
Description
Returns a Boolean indicating whether a specified Date/Time is AM (between midnight and noon). True indicates AM and False indicates PM.
Syntax
IsAm(DateTime
)
IsPm
Description
Returns a Boolean indicating whether a specified Date/Time is PM (between noon and midnight). True indicates PM and False indicates AM.
Syntax
IsPm(DateTime
)
Minute
Description
Returns the numeric minute component of a Date/Time (0–59)
.
Syntax
Minute(DateTime
)
Month
Description
Returns the numeric month component of a Date/Time (1–12)
.
Syntax
Month(DateTime
)
MonthName
Description
Converts a month number or a Date/Time to a month name.
Syntax
MonthName(Arg[, String])
Argument |
Description |
First argument |
If it is a numeric value (1 to 12
), it is converted to the appropriate month name. If it is a Date/Time, the month number is extracted and converted. |
Second argument |
Optional. The locale that must be used to format the first argument. Some examples include: en_US for English (United States), en_GB for English (United Kingdom), and fr_FR for French (France). See See Values for fieldcode-format-locale Option for a complete list. |
Remarks
If the optional argument is omitted, first the E-mail Server fieldcode-format-locale option (See fieldcode-format-locale) in the email-processing section is used if present. Otherwise, the platform locale is used.
MonthNameShort
Description
The same as the MonthName, but this returns an abbreviated version of the month name instead.
Syntax
MonthNameShort(Arg[, String])
Argument |
Description |
First argument |
If it is a numeric value (1 to 12
), it is converted to the appropriate abbreviated name. If it is a Date/Time, the month number is extracted and converted. |
Second argument |
Optional. The locale that must be used to format the first argument. Some examples include: en_US for English (United States), en_GB for English (United Kingdom), and fr_FR for French (France). See See Values for fieldcode-format-locale Option for a complete list. |
Remarks
If the optional argument is omitted, first the E-mail Server fieldcode-format-locale option (See fieldcode-format-locale) in the email-processing section is used if present. Otherwise, the platform locale is used.
Second
Description
Returns the numeric second component of a Date/Time (0–59)
.
Syntax
Second (DateTime
)
Time
Description
Returns a Date/Time constructed from individual time components.
Syntax
Time ([Hour, [Minute, [Second
]]])
Remarks
The date components of the result (year, month, and day) are set to the current system date. The optional arguments default to 0 if omitted. If all the optional arguments are omitted, then the time is set to the current system time.
Example |
Result |
<$Time()$> |
2003-11-23 09:03:10
|
<$Time(15)$> |
2003-11-23 15:00:00
|
<$Time(15, 23, 10)$> |
2003-11-23 15:23:10
|
TimeGMT()
Description
Returns a Date/Time set to the current system time and converted to GMT (Greenwich mean time), also called Universal Time Coordinated, or UTC.
Syntax
TimeGMT()
ToTimeZoneDate
Returns a Date/Time constructed from a string and a time zone.
Syntax
ToTimeZoneDate(DateString, TimeZoneString)
Remarks
This date is constructed by parsing the <DateString> string and using the specified time zone <TimeZoneString>
. Examples include the following:
<$ToTimeZoneDate(Date(“November 23, 1965 9:03 AM”), “America/Los_Angeles”)$>
<$ToTimeZoneDate(Date(“11/23/65 9:03:00”), “Europe/Paris”)$>
Weekday
Description
Returns the numeric weekday component of a Date/Time (0 = Sunday to 6 = Saturday).
Syntax
Weekday (DateTime
)
WeekdayName
Description
Converts a number of a Date/Time to a weekday name.
Syntax
WeekdayName(Arg[, String])
WeekdayName String
|- valign="top"
| rowspan="1" colspan="1" |
Argument
| rowspan="1" colspan="1" |
Description
|- valign="top"
| rowspan="1" colspan="1" |
First argument
| rowspan="1" colspan="1" |
If it is a numeric value (0 to 6
), it is converted to the appropriate weekday name. If it is a Date/Time, the weekday number is extracted and converted.
|- valign="top"
| rowspan="1" colspan="1" |
Second argument
| rowspan="1" colspan="1" |
Optional. The locale that must be used to format the first argument. Some examples include: en_US for English (United States), en_GB for English (United Kingdom), andfr_FR for French (France). See See Values for fieldcode-format-locale Option for a complete list.
|}
Remarks
If the optional argument is omitted, first the E-mail Server fieldcode-format-locale option (See fieldcode-format-locale) in the email-processing section is used if present. Otherwise, the platform locale is used.
WeekdayNameShort
Description
The same as WeekdayName but this returns an abbreviated weekday name instead.
Syntax
WeekdayNameShort(Arg[, String])
WeekdayNameShort String
|- valign="top"
| rowspan="1" colspan="1" |
Argument
| rowspan="1" colspan="1" |
Description
|- valign="top"
| rowspan="1" colspan="1" |
First argument
| rowspan="1" colspan="1" |
If it is a numeric value (0 to 6
), it is converted to the appropriate abbreviated weekday name. If it is a Date/Time, the weekday number is extracted and converted.
|- valign="top"
| rowspan="1" colspan="1" |
Second argument
| rowspan="1" colspan="1" |
Optional. The locale that must be used to format the first argument. Some examples include: en_US for English (United States), en_GB for English (United Kingdom), and fr_FR for French (France). See See Values for fieldcode-format-locale Option for a complete list.
|}
Remarks
If the optional argument is omitted, first the E-mail Server fieldcode-format-locale option (See fieldcode-format-locale) in the email-processing section is used if present. Otherwise, the platform locale is used.
Year
Description
Returns the numeric year component of a Date/Time with the century.
Syntax
Year (DateTime
)
YearShort
Description
Returns the numeric year component of a Date/Time without the century (0
– 99
).
Syntax
YearShort (DateTime
)
Type Conversion
The Field Codes use the following type conversions:
Bool
Description
Returns a Boolean converted from a number or a string.
Syntax
Bool(Arg, [Default
])
Argument |
Description |
Arg |
If a number, then converts 0 to False and nonzero to True.
|
Remarks
Example |
Result |
<$Bool(0)$> |
False
|
<$Bool(25.23)$> |
True
|
<$Bool("Yes")$> |
True
|
<$Bool("off", True)$> |
False
|
<$Bool("Asteroids")$> |
False
|
<$Bool("Asteroids", True)$> |
True
|
Num
Description
Returns a number converted from a string.
Syntax
Num (String[, String]
)
Argument |
Description |
First argument |
The string to be converted. May be expressed in scientific notation. Returns 0 if the string is not recognizable as a number. Ignores nonnumeric characters following the number. |
Second argument |
Optional. The locale that must be used to parse the first argument. Some examples include: en_US for English (United States), en_GB for English (United Kingdom), and fr_FR for French (France). See the Values for fieldcode-format-locale Option in the eServices 8.1 Reference Manual for a complete list. |
Remarks
If the optional argument is omitted, first the E-mail Server fieldcode-format-locale option (see option description in the eServices 8.1 Reference Manual) in the email-processing section is used if present. Otherwise, the platform locale is used.
For clarity, the results shown in the Examples of Num String table appear with three digits after the decimal point and always in the en_US format. Default number formatting shows no digits after the decimal point. Use the Text function (see Field Codes in Standard Responses Reference: Text) or format operator (%) to override the default formatting.
Example |
Result |
---|---|
<$Num("10")$> |
10.000
|
<$Num("10.00")$> |
10.000 |
<$Num("10,00", "fr_FR")$> |
10.000
|
<$Num("12e-2")$> |
0.120
|
<$Num("12.2e2Zork")$> |
1220.000
|
<$Num("12,2e2Zork", "fr_FR")$> |
1220.000
|
<$Num("Zaxxon")$> |
0.000
|
Text
Text
Description
Returns a string converted from an argument of any data type. Use the format operator (:) as shorthand for this function.
Syntax
Text (Arg[, Pattern[, String]])
or
Arg:Pattern
Argument |
Description |
Arg |
The value to be converted |
Pattern |
Optional. The picture string to use for formatting. If omitted, default formatting is used. The syntax of the picture string depends on the data type. See Number Formatting - “Number Formatting (Arg is a Number)” ). |
String |
Optional. The locale that must be used to parse the first argument. Some examples include: en_US for English (United States), en_GB for English (United Kingdom), and fr_FR for French (France). See Values for the fieldcode-format-locale Option in the eServices 8.1 Reference Manual for a complete list. |
Number Formatting (Arg is a Number)
If Arg is a number, then the regular expression syntax of the optional pattern string is as follows:
-
#*.?#*
Where:
-
#
–The pound sign (#
) represents a digit. Any number of #
s, including 0 may appear before the decimal character. Specify the minimum number of digits that should appear to the left of the decimal. If the integer part of the formatted number contains fewer than the specified number of digits, the number is padded with leading zeros.
-
Any number of #
s, including 0, may appear after the decimal character. Specify the precision of the fractional part of the number. The number is rounded to the specified precision.
-
Only the decimal separator in the result is locale dependent (There is no grouping separator).
The Examples of Number Formatting table contains some examples.
Pattern |
Arg Value |
Locale |
Result |
---|---|---|---|
"" |
0 |
en_US
|
"0"
|
"" |
123.456 |
en_US
|
"123"
|
"#" |
0 |
en_US
|
"0"
|
"##" |
0 |
en_US
|
"00"
|
"##" |
123.456 |
en_US
|
"123"
|
"#." |
0 |
en_US
|
"0. "
|
"#." |
123.456 |
en_US
|
"123. "
|
".##" |
0 |
en_US
|
".00"
|
".##" |
0.456 |
en_US
|
".46"
|
".##" |
123.456 |
en_US
|
"123.46"
|
".##" |
20000.456 |
en_US
|
"20000.46"
|
".##" |
123.456 |
fr_FR
|
"123,46"
|
".##" |
20000.456 |
fr_FR
|
"20000,46"
|
Duration Formatting (Arg is a Number)
If Arg is a number, then the regular expression syntax of the optional pattern string is as follows:
-
(<dur>).?#*
Where:
<dur> represents a duration and can be any of the sequences in the following list. (Upper- or lowercase letters are accepted.)
HH
HH:MM
HH:MM:SS
MM
MM:SS
SS
H
H:MM
H:MM:SS
M
M:SS
S
-
<dur> may be followed by a .## string, which specifies the precision of the last element of the duration. Any C or % suffixes are ignored. When you format a value as a duration, the value is always assumed to be expressed in days.
The pound sign (#) represents a digit. Any number of #
s, including 0, may appear before the decimal character and specify the minimum number of digits that should appear to the left of the decimal. If the integer part of the formatted number contains fewer than the specified number of digits, the number is padded with leading zeroes.
Any number of #
s, including 0, may appear after the decimal character and specify the precision of the fractional part of the number. The number is rounded to the specified precision.
The Examples of Duration Formatting table contains some examples.
Pattern |
Arg Value |
Locale |
Result |
---|---|---|---|
"HH" |
10.5083 |
en_US
|
"11"
|
"HH.## " |
10.5083 |
en_US
|
"10.51"
|
"HH:MM" |
10.5083 |
en_US
|
"10:30"
|
"HH:MM.# " |
10.5083 |
en_US
|
"10:30.5"
|
"HH:MM:SS" |
10.5083 |
en_US
|
"10:30:30"
|
"MM" |
10.5083 |
en_US
|
"630"
|
"MM.## " |
10.5083 |
en_US
|
"630.50"
|
"MM:SS" |
10.5083 |
en_US
|
"630:30"
|
"SS" |
10.5083 |
en_US
|
"37830"
|
Currency Formatting (Arg is a Number)
If Arg is a number, then the regular expression syntax of the optional parameter string is as follows:
-
#*.?#*[Cc]
Where:
A C or a c means format as currency. The grouping separator, the decimal separator, and the currency sign in the result are locale dependent.
The Examples of Currency Formatting table contains some examples
Pattern |
Arg Value |
Locale |
Result |
---|---|---|---|
"C" |
12.34 |
en_US
|
"$12.34"
|
"C" |
-12.34 |
en_US
|
"($12.34)"
|
"#.#C" |
12.34 |
en_US
|
"$12.3"
|
"#.#C" |
-12.34 |
en_US
|
"($12.3)"
|
"C" |
12.34 |
en_GB
|
"£12.34
" |
"C" |
-12.34 |
en_GB
|
"-£12.34
" |
"#.#C" |
12.34 |
en_GB
|
"£12.3
" |
"#.#C" |
-12.34 |
en_GB
|
"-£12.3
" |
".##C" |
20000.456 |
en_US
|
"$20,000.46"
|
".##C" |
20000.456 |
fr_FR
|
"20 000,46 €" |
Percentage Formatting (Arg is a Number)
If Arg is a number, then the regular expression syntax of the optional pattern string is as follows:
-
#*.?#*%
Where:
The percent sign (%
) means multiply by 100 and append the locale-dependent sign for percent values. If the % appears by itself, the formatter rounds to the nearest integral value and omits a decimal point (equivalent to the format #%
).
The grouping separator, the decimal separator, and the percent sign in the result are locale dependent.
The Examples of Percentage Formatting table contains some examples.
Pattern |
Arg Value |
Locale |
Result |
---|---|---|---|
"%" |
0 |
en_US
|
"0%"
|
"%" |
0.123456 |
en_US
|
"12%"
|
"#.##%" |
0.123456 |
en_US
|
"12.35%"
|
"#.##%" |
0.123456 |
fr_FR
|
"12,35%"
|
Date/Time Formatting
Use elements shown in the Date/Time Pattern Letters table to construct a Date/Time pattern string. The letters must be in uppercase or lowercase, as shown in the table (for example, MM not mm). Characters that are not picture elements, or that are enclosed in single quotation marks, will appear in the same location and unchanged in the output string.
Element |
Meaning |
---|---|
d |
Day of month as digits, with no leading zero for single-digit days |
dd |
Day of month as digits, with leading zero for single-digit days |
ddd |
Day of week as a three-letter abbreviation |
dddd |
Day of week as its full name |
M |
Month as digits, with no leading zero for single-digit months |
MM |
Month as digits, with leading zero for single-digit months |
MMM |
Month as a three-letter abbreviation |
MMMM |
Month as its full name |
y |
Year as last two digits, but with no leading zero for years less than 10 |
yy |
Year as last two digits, but with leading zero for years less than 10 |
yyyy |
Year represented by full four digits |
h |
Hours, with no leading zero for single-digit hours; 12-hour clock |
hh |
Hours, with leading zero for single-digit hours; 12-hour clock |
H |
Hours, with no leading zero for single-digit hours; 24-hour clock |
HH |
Hours, with leading zero for single-digit hours; 24-hour clock |
m |
Minutes, with no leading zero for single-digit minutes |
mm |
Minutes, with leading zero for single-digit minutes |
s |
Seconds, with no leading zero for single-digit seconds |
ss |
Seconds, with leading zero for single-digit seconds |
tt |
Time-marker string, such as AM or PM |
The examples in the Examples of Date/Time Formatting table assume that the date being formatted is August 6, 2003, @ 15:05:10:
Pattern |
Locale |
Result |
---|---|---|
"MMMM d, yyyy @ hh:mm:ss tt" |
en_US
|
"August 6, 2003 @ 03:05:10 PM"
|
"MMMM dd, yyyy @ HH:mm:ss" |
en_US
|
"August 06, 2003 @ 15:05:10"
|
"dd MMMM yyyy HH:mm:ss" |
fr_FR
|
"06 aout 2003 15:05:10"
|
"MMM d, yy @ h:mm:ss tt" |
en_US
|
"Aug 6, 03 @ 3:05:10 PM"
|
"M/dd/yy" |
en_US
|
"8/06/03"
|
Boolean Formatting
A Boolean picture string is simply two words separated by a comma. The first word is used if the Boolean value is True, and the second is used otherwise.
The Examples of Boolean Formatting table shows some examples:
Field Code |
Result |
<$Text(True, "Yup,Nope")$> |
"Yup"
|
<$Text(False, "Si,No")$> |
"No"
|
<$Text(False, "walnut,peach")$> |
"peach"
|
String Formatting
Picture strings do not apply to string values. Strings are always output unchanged. If you want to output a piece of a string, or change the case, then you can use one of the string-manipulation functions previously described.
Mathematical Functions
The Field Codes include the following mathematical functions:
Abs
Description
Returns the absolute value of a number.
Syntax
Abs (Number
)
Remarks
The absolute value of a number is the number without regard to its sign.
Ceil
Description
Returns the ceiling of a number.
Syntax
Ceil (Number
)
Remarks
The ceiling of a number is the smallest integer that is greater than or equal to that number.
Floor
Description
Returns the floor of a number.
Syntax
Floor (Number
)
Remarks
The floor of a number is the largest integer that is less than or equal to that number.
Miscellaneous Functions
The Field Codes include the following miscellaneous functions:
If
Description
Returns either the second or the third argument, depending on the value of the first (Boolean) argument.
Syntax
If (Boolean, TrueResult, FalseResult)
IsBoolean
Description
Returns True if the data type of the argument is Boolean; otherwise, it returns False.
Syntax
IsBoolean (Arg)
IsDateTime
Description
Returns True if the data type of the argument is Date/Time, and False otherwise.
Syntax
IsDateTime (Arg
)
IsNumber
Description
Returns True if the data type of the argument is number, and False otherwise.
Syntax
IsNumber (Arg
)
IsString
Description
Returns True if the data type of the argument is string, and False otherwise.
Syntax
IsString (Arg
)
Type
Description
Returns the type name (String, Boolean, and so on) of its argument.
Syntax
Type (Arg)