Designer FormCalc Reference

AEM 6.2 Forms

Legal notices
For legal notices, see http://help.adobe.com/en_US/legalnotices/index.html.

Last updated 4/20/16

 Contents

About FormCalc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Using FormCalc in Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Simple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Logical OR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Logical AND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Unary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Equality and inequality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Relational . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
If expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
While expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
For expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Foreach expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Break expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Continue expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Building blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Reference Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Property and method calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Built-in function calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Alphabetical Functions List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Arithmetic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Abs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

i
 Avg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Ceil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Floor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Mod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Round . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Sum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Date and Time Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Structuring dates and times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Date2Num . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
DateFmt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
IsoDate2Num . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
IsoTime2Num . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
LocalDateFmt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
LocalTimeFmt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Num2Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Num2GMTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Num2Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Time2Num . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
TimeFmt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Financial Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Apr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
CTerm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
FV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
IPmt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
NPV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Pmt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
PPmt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
PV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Rate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Term . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Logical Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Choose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Exists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
HasValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Oneof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Within . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

ii
Miscellaneous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Eval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Null . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Ref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
UnitType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
UnitValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

String Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
At . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Concat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Decode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Encode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Left . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Len . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Lower . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Ltrim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Parse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Right . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Rtrim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Str . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Stuff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Substr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Uuid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Upper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
WordNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

URL Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Post . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Put . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

iii
About FormCalc 1

1. About FormCalc
Designer provides users with FormCalc, a simple yet powerful calculation language for those with
little or no scripting experience.
The form developer can incorporate calculations and scripting to create a richer experience for the
recipient of the form. FormCalc facilitates fast and efficient form design without requiring a knowl-
edge of traditional scripting techniques or languages.
The built-in functions in FormCalc cover a wide range of areas including mathematics, dates and
times, strings, finance, logic, and the web. These areas represent the types of data that typically occur
in forms, and the functions provide quick and easy manipulation of the data in a useful way.

1.1. Using FormCalc in Designer

Within Designer, JavaScript™ is the default scripting language, with FormCalc as the alternative.
Scripting takes place on the various events that accompany each form object, and you can use a
mixture of JavaScript and FormCalc in interactive forms.
If you are using a server-based process, such as forms generator, to create forms for viewing in an
internet browser, FormCalc scripts on certain form object events do not render onto the HTML
form. This functionality is intended to prevent Internet browser errors from occurring when users
work with the completed form.
RELATED LINKS:
Alphabetical Functions List

1
 Expressions

2. Expressions
Literals, operators, comments, keywords, identifiers, line terminators, and white space come
together to form a list of expressions, even if the list only contains a single expression. In general,
each expression in the list resolves to a value, and the value of the list as a whole is the value of the
last expression in the list.
For example, consider the following scenario of two fields on a form design:

Field name Calculations Returns

Field1 5 + Abs(Price) "Hello World" 10 * 3 50

+ 5 * 4

Field2 10 * 3 + 5 * 4 50

The value of bothField1andField2after the evaluation of each field’s expression list is50.
FormCalc divides the various types of expressions that make up an expression list into the following
categories:

2.1. Simple

2.1.1. About simple expressions

In their most basic form, FormCalc expressions are groups of operators, keywords, and literals
strung together in logical ways. For example, these are all simple expressions:
2
"abc"
2 - 3 * 10 / 2 + 7

Each FormCalc expression resolves to a single value by following a traditional order of operations,
even if that order is not always obvious from the expression syntax. For example, the following sets
of expressions, when applied to objects on a form design, produce equivalent results:

Expression Equivalent to Returns

"abc" "abc" abc

2 - 3 * 10 / 2 + 7 2 - (3 * (10 / 2)) + 7 -6

2
Expressions 2

Expression Equivalent to Returns

10 * 3 + 5 * 4 (10 * 3) + (5 * 4) 50

0 and 1 or 2 > 1 (0 and 1) or (2 >1) 1(true)

2 < 3 not 1 == 1 (2 < 3) not (1 == 1) 0(false)

As the previous table suggests, all FormCalc operators carry a certain precedence when they appear
within expressions. The following table illustrates this operator hierarchy:

Precedence Operator

Highest =

(Unary) - , + , not

*,/

+,-

< , <= , > , >= , lt , le , gt , ge

== , <> , eq , ne

& , and

Lowest | , or

2.1.2. Promoting operands

In cases where one or more of the operands within a given operation do not match the expected type
for that operation, FormCalc promotes the operands to match the required type. How this promo-
tion occurs depends on the type of operand required by the operation.

2.1.3. Numeric operations

When performing numeric operations involving non-numeric operands, the non-numeric oper-
ands are first promoted to their numeric equivalent. If the non-numeric operand does not success-
fully convert to a numeric value, its value is 0. When promoting null-valued operands to numbers,
their value is always zero.
The following table provides some examples of promoting non-numeric operands:

3
 Expressions

Expression Equivalent to Returns

(5 - "abc") * 3 (5 - 0) * 3 15

"100" / 10e1 100 / 10e1 1

5 + null + 3 5 + 0 + 3 8

2.1.4. Boolean operations

When performing Boolean operations on non-Boolean operands, the non-Boolean operands are
first promoted to their Boolean equivalent. If the non-Boolean operand does not successfully convert
to a nonzero value, its value is true (1); otherwise its value is false (0). When promoting null-valued
operands to a Boolean value, that value is always false (0). For example, the expression:
"abc" | 2

evaluates to1. That is, false | true = true, whereas

if ("abc") then
10
else
20
endif

evaluates to20.

2.1.5. String operations

When performing string operations on nonstring operands, the nonstring operands are first
promoted to strings by using their value as a string. When promoting null-valued operands to
strings, their value is always the empty string. For example, the expression:
concat("The total is ", 2, " dollars and ", 57, " cents.")

evaluates to"The total is 2 dollars and 57 cents."

NOTE: If during the evaluation of an expression an intermediate step yields NaN, +Inf, or -Inf, Form-
Calc generates an error exception and propagates that error for the remainder of the expression. As
such, the expression's value will always be 0. For example:
3 / 0 + 1

evaluates to 0.

4
Expressions 2

2.2. Assignment

An assignment expression sets the property identified by a given reference syntax to be the value of
a simple expression. For example:
$template.purchase_order.name.first = "Tony"

This sets the value of the form design object “first” toTony.
For more information on using syntax, see Referencing Objectsin Calculations and Scripts

2.3. Logical OR

A logical OR expression returns either true (1) if at least one of its operands is true (1), or false (0) if
both operands are false (0). If both operands are null, the expression returns null.

Expression Character representation

Logical OR |
or

These are examples of using the logical OR expression:

Expression Returns

1 or 0 1(true)

0 | 0 0(false)

0 or 1 | 0 or 0 1(true)

2.4. Logical AND

A logical AND expression returns either true (1) if both operands are true (1), or false if at least one
of its operands is false (0). If both operands are null, the expression returns null.

5
 Expressions

Expression Character representation

Logical AND &

and

These are examples of using the logical AND expression:

Expression Returns

1 and 0 0(false)

0 & 0 1(true)

0 and 1 & 0 and 0 0(false)

2.5. Unary

A unary expression returns different results depending on which of the unary operators is used.

Expression Character representation Returns

Unary - The arithmetic negation of the operand, or null if the operand is null.

+ The arithmetic value of the operand (unchanged), or null if its

operand is null.

not The logical negation of the operand.

NOTE: The arithmetic negation of a null operand yields the result null, whereas the logical negation of
a null operand yields the Boolean result true. This is justified by the common sense statement: If null
means nothing, then “not nothing” should be something.
These are examples of using the unary expression:

Expression Returns

-(17) -17

-(-17) 17

6
Expressions 2

Expression Returns

+(17) 17

+(-17) -17

not("true") 1 (true)

not(1) 0 (false)

2.6. Equality and inequality

Equality and inequality expressions return the result of an equality comparison of its operands.

Character
Expression representation Returns

Equality == eq True (1) when both operands compare identically, and false (0) if they
do not compare identically.

Inequality <> ne True (1) when both operands do not compare identically, and false (0) if
they compare identically.

The following special cases also apply when using equality operators:
• If either operand is null, a null comparison is performed. Null-valued operands compare iden-
tically whenever both operands are null, and compare differently whenever one operand is not
null.
• If both operands are references, both operands compare identically when they both refer to the
same object, and compare differently when they do not refer to the same object.
• If both operands are string valued, a locale-sensitive lexicographic string comparison is
performed on the operands. Otherwise, if they are not both null, the operands are promoted to
numeric values, and a numeric comparison is performed.
These are examples of using the equality and inequality expressions:

Expression Returns

3 == 3 1(true)

3 <> 4 1(true)

7
 Expressions

Expression Returns

"abc" eq "def" 0(false)

"def" ne "abc" 1(true)

5 + 5 == 10 1(true)

5 + 5 <> "10" 0(false)

2.7. Relational

A relational expression returns the Boolean result of a relational comparison of its operands.

Character
Expression representation Returns

Relational < lt True (1) when the first operand is less than the second operand, and
false (0) when the first operand is larger than the second operand.

> gt True (1) when the first operand is greater than the second operand, and
false (0) when the first operand is less than the second operand.

<= le True (1) when the first operand is less than or equal to the second
operand, and false (0) when the first operand is greater than the second
operand.

>= ge True (1) when the first operand is greater than or equal to the second
operand, and false (0) when the first operand is less than the second
operand.

The following special cases also apply when using relational operators:
• If either operand is null valued, a null comparison is performed. Null-valued operands
compare identically whenever both operands are null and the relational operator is
less-than-or-equal or greater than or equal, and compare differently otherwise.
• If both operands are string valued, a locale-sensitive lexicographic string comparison is
performed on the operands. Otherwise, if they are not both null, the operands are promoted to
numeric values, and a numeric comparison is performed.
These are examples of using the relational expression:

8
Expressions 2

Expression Returns

3 < 3 0(false)

3 > 4 0(false)

"abc" <= "def" 1(true)

"def" > "abc" 1(true)

12 >= 12 1(true)

"true" < "false" 0(false)

2.8. If expressions

An if expression is a conditional statement that evaluates a given simple expression for truth, and
then returns the result of a list of expressions that correspond to the truth value. If the initial simple
expression evaluates to false (0), FormCalc examines any elseif and else conditions for truth and
returns the results of their expression lists if appropriate.

Expression Syntax Returns

If if ( simple expression ) The result of the list of expressions associated with any
then valid conditions stated in the if expression.
list of expressions You are not required to have any elseif(...) or else
elseif ( simple expression ) statements as part of your if expression, but you must
then state the end of the expression with endif.
list of expressions
else
list of expressions
endif

These are examples of using the if expression:

Expression Returns

if ( 1 < 2 ) then 1 endif 1

if ( "abc" > "def") then 1 0

and 0 else 0 endif

9
 Expressions

Expression Returns

if ( Field1 < Field2 ) then Varies with the values ofField1andField2. For example, if Field1 is
Field3 = 0 elseif ( Field1 20 and Field2 is 10, then this expression sets Field3 to 40.
> Field2 ) then Field3 =
40 elseif ( Field1 == Field2
) then Field3 = 10 endif

2.9. While expressions

A while expression is an iterative statement or loop that evaluates a given simple expression. If the
result of the evaluation is true (1), FormCalc repeatedly examines the do condition and returns the
results of the expression lists. If the result is false (0), then control passes to the next statement.
A while expression is particularly well-suited to situations in which conditional repetition is needed.
Conversely, situations in which unconditional repetition is needed are often best dealt with using a
for expression.

Expressio
n Syntax Returns

While while ( simple expression The result of the list of expressions associated with the do
) do expression list condition.
endwhile

In the following example, the values of the elements are added to a drop-down list from an XML file
using the addItem method for all of the XML elements listed under list1 that are not equal to 3:
var List = ref(xfa.record.lists.list1)
var i = 0
while ( List.nodes.item(i+1).value ne "3")do
$.addItem (List.nodes.item(i).value,List.nodes.item(i+1).value)
i = i + 2
endwhile

2.10. For expressions

A for expression is a conditionally iterative statement or loop.

A for expression is particularly well-suited to looping situations in which unconditional repetition
is needed. Conversely, situations in which conditional repetition is needed are often best dealt with
using a while expression.

10
Expressions 2

The value of the for expression is the value of the last evaluation list that was evaluated, or false (0).
The for condition initializes a FormCalc variable, which controls the looping action.
In the upto variant, the value of the loop variable will iterate from the start expression to the end
expression in step expression increments. If you omit the step expression, the step increment
defaults to 1.
In the downto variant, the value of the loop variable iterates from the start expression to the end
expression in step expression decrements. If the step expression is omitted, the step decrements
defaults to -1.
Iterations of the loop are controlled by the end expression value. Before each iteration, the end
expression is evaluated and compared to the loop variable. If the result is true (1), the expression list
is evaluated. After each evaluation, the step expression is evaluated and added to the loop variable.
Before each iteration, the end expression is evaluated and compared to the loop variable. In addition,
after each evaluation of the do condition, the step expression is evaluated and added to the loop vari-
able.
A for loop terminates when the start expression has surpassed the end expression. The start expres-
sion can surpass the end expression in either an upwards direction, if you use upto, or in a downward
direction, if you use downto.

Expressio
n Syntax Returns

For for variable = start expression The result of the list of expressions
(upto | downto ) end expression associated with the do condition.
(step step expression ) do
expression list
endfor
The start, end, and step expressions must all be simple
expressions.

In the following example, the values of the elements are added to a drop-down list from an XML file
using the addItem method for all of the XML elements listed under list1:
var List = ref(xfa.record.lists.list1)
for i=0 upto List.nodes.length - 1 step 2 do
$.addItem (List.nodes.item(i).value,"")
endfor

2.11. Foreach expressions

A foreach expression iterates over the expression list for each value in its argument list.

11
 Expressions

The value of the foreach expression is the value of the last expression list that was evaluated, or zero
(0), if the loop was never entered.
The in condition, which is executed only once (after the loop variable has been declared) controls
the iteration of the loop. Before each iteration, the loop variable is assigned successive values from
the argument list. The argument list cannot be empty.

Expressio
n Syntax Returns

Foreach foreach variable in( argument list The value of the last expression list that was
)do evaluated, or zero(0), if the loop was never
expression list entered.
endfor
Use a comma (,) to separate more
than one simple expression in the
argument list.

In the following example, only the values of the “display” XML elements are added to the foreach
drop-down list.
foreach Item in (xfa.record.lists.list1.display[*]) do
$.addItem(Item,"")
endfor

2.12. Break expressions

A break expression causes an immediate exit from the innermost enclosing while, for, or foreach
expression loop. Control passes to the expression following the terminated loop.
The value of the break expression is always the value zero (0).

Expression Syntax Returns

Break break Passes control to the expression following the terminated loop.

In the following example, an if condition is placed in the while loop to check whether the current
value is equal to “Display data for 2”. If true, the break executes and stops the loop from continuing.
var List = ref(xfa.record.lists.list1)
var i=0
while (List.nodes.item(i+1).value ne "3") do
$.addItem(List.nodes.item(i).value,List.nodes.item(i+1).value)
i = i + 2
if (List.nodes.item(i) eq "Display data for 2" then
break

12
Expressions 2

endif
endwhile

2.13. Continue expressions

A continue expression causes the next iteration of the innermost enclosing while, for, or foreach
loop.
The value of the continue expression is always the value zero (0).

Expressio
n Syntax Returns

Continue continu When used in a while expression, control is passed to the while condition. When used
e in a for expression, control is passed to the step expression.

The object of the following example is to populate the drop-down list with values from the XML file.
If the value of the current XML element is “Display data for 3,” then the while loop exits via the break
expression. If the value of the current XML element is “Display data for 2”, then the script adds 2 to
the variablei(which is the counter) and immediately the loop moves on to its next cycle. The last two
lines are ignored when the value of the current XML element is “Display data for 2”.
var List = ref(xfa.record.lists.list1)
var i = 0
while (List.nodes.item(i+1).value ne "5") do
if (List.nodes.item(i) eq "Display data for 3") then
break
endif
if (List.nodes.item(i) eq "Display data for 2" then
i=i+2
continue
endif
$.addItem(List.nodes.item(i).value,List.nodes.item(i+1).value)
i=i+2
endwhile

2.14. Building blocks

The FormCalc language consists of building blocks that make up FormCalc expressions. Each Form-
Calc expression is a sequence of some combination of these building blocks.

13
 Expressions

2.14.1. Literals

Literals are constant values that form the basis of all values that pass to FormCalc for processing. The
two general types of literals are numbers and strings.

Number literals

A number literal is a sequence of mostly digits consisting of one or more of the following characters:
an integer, a decimal point, a fractional segment, an exponent indicator (“e” or “E”), and an option-
ally signed exponent value. These are all examples of literal numbers:
• -12
• 1.5362
• 0.875
• 5.56e-2
• 1.234E10
It is possible to omit either the integer or fractional segment of a literal number, but not both. In
addition, within the fractional segment, you can omit either the decimal point or the exponent value,
but not both.
All number literals are internally converted to Institute of Electrical and Electronics Engineers
(IEEE) 64-bit binary values. However, IEEE values can only represent a finite quantity of numbers,
so certain values do not have a representation as a binary fraction. This is similar to the fact that
certain values, such as 1/3, do not have a precise representation as a decimal fraction (the decimal
value would need an infinite number of decimal places to be entirely accurate).
The values that do not have a binary fraction equivalent are generally number literals with more than
16 significant digits prior to their exponent. FormCalc rounds these values to the nearest represent-
able IEEE 64-bit value in accordance with the IEEE standard. For example, the value:
123456789.012345678

rounds to the (nearest) value:

123456789.01234567

However, in a second example, the number literal:

99999999999999999

rounds to the (nearest) value:

100000000000000000

This behavior can sometimes lead to surprising results. FormCalc provides a function, Round, which
returns a given number rounded to a given number of decimal places. When the given number is
exactly halfway between two representable numbers, it is rounded away from zero. That is, the
number is rounded up if positive and down if negative. In the following example:

14
Expressions 2

Round(0.124, 2)

returns0.12,
and
Round(.125, 2)

returns0.13.
Given this convention, one might expect that:
Round(0.045, 2)

returns0.05.
However, the IEEE 754 standard dictates that the number literal0.045be approximated
to0.0449999999999999. This approximation is closer to0.04than to0.05. Therefore,
Round(0.045, 2)

returns0.04.
This also conforms to the IEEE 754 standard.
IEEE 64-bit values support representations like NaN (not a number), +Inf (positive infinity), and
-Inf (negative infinity). FormCalc does not support these, and expressions that evaluate to NaN,
+Inf, or -Inf result in an error exception, which passes to the remainder of the expression.

String literals

A string literal is a sequence of any Unicode characters within a set of quotation marks. For example:
"The cat jumped over the fence."
"Number 15, Main street, California, U.S.A"

The string literal""defines an empty sequence of text characters called the empty string.
To embed a quotation mark (") character within a literal string, you must insert two quotation
marks. For example:
"The message reads: ""Warning: Insufficient Memory"""

All Unicode characters have an equivalent 6 character escape sequence consisting of\ufollowed by
four hexadecimal digits. Within any literal string, it is possible to express any character, including
control characters, using their equivalent Unicode escape sequence. For example:
"\u0047\u006f\u0066\u0069\u0073\u0068\u0021"
"\u000d" (carriage return)
"\u000a" (newline character)

15
 Expressions

2.14.2. Operators

FormCalc includes a number of operators: unary, multiplicative, additive, relational, equality,

logical, and the assignment operator.
Several of the FormCalc operators have an equivalent mnemonic operator keyword. These keyword
operators are useful whenever FormCalc expressions are embedded in HTML and XML source text,
where the symbols less than (<), greater than (>), and ampersand (&) have predefined meanings and
must be escaped. The following table lists all FormCalc operators, illustrating both the symbolic and
mnemonic forms where appropriate.

Operator type Representations

Addition +

Division /

Equality == eq
<> ne

Logical AND & and

Logical OR | or

Multiplication *

Relational < lt (less than)

> gt (greater than)
<= le (less than or equal to)
>= ge (greater than or equal to)

Subtraction -

Unary -
+
not

2.14.3. Comments

Comments are sections of code that FormCalc does not execute. Typically comments contain infor-
mation or instructions that explain the use of a particular fragment of code. FormCalc ignores all
information stored in comments at run time.
You can specify a comment by using either a semi-colon (;) or a pair of slashes (//). In FormCalc, a
comment extends from its beginning to the next line terminator.

16
Expressions 2

Character name Representations

Comment ;
//

For example:
// This is a type of comment
First_Name="Tony"
Initial="C" ;This is another type of comment
Last_Name="Blue"

Commenting all FormCalc calculations on an event

Commenting all of the FormCalc calculations for a particular event generates an error when you
preview your form in the Preview PDF tab or when you view the final PDF. Each FormCalc calcula-
tion is required to return a value, and FormCalc does not consider comments to be values.
To prevent the commented FormCalc code from returning an error, you must do one of the
following actions:
• Remove the commented code from the event
• Add an expression that returns a value to the FormCalc code on the event
To prevent the value of the expression from producing unwanted results on your form, use one of
the following types of expressions:
• A simple expression consisting of a single character, as shown in the following example:
// First_Name="Tony"
// Initial="C"
// Last_Name="Blue"
//
// The simple expression below sets the value of the event to zero.
0
• An assignment expression that retains the value of the object. Use this type of expression if
your commented FormCalc code is located on the calculate event to prevent the actual value
of the object from being altered, as shown in the following example:
// First_Name="Tony"
// Initial="C"
// Last_Name="Blue"
//
// The assignment expression below sets the value of the current
// field equal to itself.
$.rawValue = $.rawValue

17
 Expressions

2.14.4. Keywords

Keywords in FormCalc are reserved words and are case-insensitive. Keywords are used as parts of
expressions, special number literals, and operators.
The following table lists the FormCalc keywords. Do not use any of these words when naming
objects on your form design.

and endif in step

break endwhile infinity then

continue eq le this

do exit lt throw

downto for nan upto

else foreach ne var

elseif func not while

end ge null

endfor gt or

endfunc if return

2.14.5. Identifiers

An identifier is a sequence of characters of unlimited length that denotes either a function or a

method name. An identifier always begins with one of the following characters:
• Any alphabetic character (based on the Unicode letter classifications)
• Underscore (_)
• Dollar sign ($)
• Exclamation mark (!)
FormCalc identifiers are case-sensitive. That is, identifiers whose characters only differ in case are
considered distinct.

18
Expressions 2

Character name Representations

Identifier A..Z,a..z
$
!
_

These are examples of valid identifiers:

GetAddr
$primary
_item
!dbresult

2.14.6. Line terminators

Line terminators are used for separating lines and improving readability.
The following table lists the valid FormCalc line terminators:

Character name Unicode characters

Carriage Return #xD

U+000D

Line Feed #xA

&#x000D;
&#D;

2.14.7. White space

White space characters separate various objects and mathematical operations from each other.
These characters are strictly for improving readability and are irrelevant during FormCalc
processing.

Character name Unicode character

Form Feed #xC

Horizontal Tab #x9

Space #x20

19
 Expressions

Character name Unicode character

Vertical Tab #xB

2.15. Variables

Within your calculations, FormCalc allows you to create and manipulate variables for storing data.
The name you assign to each variable you create must be a unique Identifiers.
For example, the following FormCalc expressions define the userName variable and set the value of
a text field to be the value of userName.
var userName = "Tony Blue"
TextField1.rawValue = userName

You can reference variables that you define in the Variables tab of the Form Properties dialog box in
the same way. The following FormCalc expression uses the Concat function to set the value of the
text field using the form variables salutation and name.
TextField1.rawValue = Concat(salutation, name)

NOTE: A variable you create using FormCalc will supersede a similarly named variable you define in
the Variables tab of the Form Properties dialog box.

2.16. Reference Syntax

FormCalc provides access to form design object properties and values using a reference syntax. The
following example demonstrates both assigning and retrieving object values:
Invoice_Total.rawValue = Invoice_SubTotal.rawValue * (8 / 100)

In this case the reference syntax Invoice_Total assigns the value of Invoice_SubTotal *
(8 / 100) to the field Invoice_Total.
In the context of form design, a fully qualified reference syntax enables access to all the objects on a
form design.
To make accessing object properties and values easier, FormCalc includes reference syntax shortcuts
to reduce the effort required to create references.

2.16.1. Current field or object

Refers to the current field or object

20
Expressions 2

Notation

Example

$ = "Tony Blue"

The above example sets the value of the current field or object to Tony Blue.

2.16.2. Data model root of xfa.datasets.data

Represents the root of the data model xfa.datasets.data.

Notation

$data

Example

$data.purchaseOrder.total

is equivalent to
xfa.datasets.data.purchaseOrder.total

2.16.3. Form object event

Represents the current form object event.

Notation

$event

Example

$event.name

is equivalent to
xfa.event.name

For more information, see Workingwith the Event Model.

21
 Expressions

2.16.4. Form model root

Represents the root of the form model xfa.form.

Notation

$form

Example

$form.purchaseOrder.tax

is equivalent to stating
xfa.form.purchaseOrder.tax

2.16.5. Host object

Represents the host object.

Notation

$host

Example

$host.messageBox("Hello world")

is equivalent to
xfa.host.messageBox("Hello world")

For more information, see Workingwith a Host Application

2.16.6. Layout model root

Represents the root of the layout modelxfa.layout.

Notation

$layout

22
Expressions 2

Example

$layout.ready

is equivalent to stating
xfa.layout.ready

2.16.7. Collection of data record

Represents the current record of a collection of data, such as from an XML file.

Notation

$record

Example

$record.header.txtOrderedByCity

references the txtOrderedByCity node within the header node of the current XML data.

2.16.8. Template model root

Represents the root of the template model xfa.template.

Notation

$template

Example

$template.purchaseOrder.item

is equivalent to
xfa.template.purchaseOrder.item

2.16.9. Data model root of xfa.datasets

Represents the root of the data modelxfa.datasets.

23
 Expressions

Notation

Example

!data

is equivalent to
xfa.datasets.data

2.16.10. Select all form objects

Selects all form objects within a given container, such as a subform, regardless of name, or selects all
objects that have a similar name.
You can use the ‘*’ (asterisk) syntax with JavaScript if it used with the resolveNode method.

Notation

Example

For example, the following expression selects all objects named item on a form:
xfa.form.form1.item[*]

2.16.11. Search for objects that are part of a subcontainer

You can use two dots at any point in your reference syntax to search for objects that are a part of any
subcontainer of the current container object, such as a subform.
You can use the ‘..’ (double period) syntax with JavaScript if it used with the resolveNode
method.

Notation

..

24
Expressions 2

Example

The expressionSubform_Page..Subform2means locate the nodeSubform_Page(as usual)

and find a descendant ofSubform_PagecalledSubform2.

Using the example tree above,

Subform_Page..TextField2

is equivalent to
Subform_Page.Subform1[0].Subform3.TextField2[0]

becauseTextField2[0]is in the firstSubform1node that FormCalc encounters on its search.

As a second example,
Subform_Page..Subform3[*]

returns all fourTextField2objects.

2.16.12. Denote an unnamed object or specify a property

The number sign (#) notation is used to denote one of the following items in a reference syntax:
• An unnamed object
• Specify a property in a reference syntax if a property and an object have the same name
You can use the ‘#’ (number sign) syntax with JavaScript if it used with the resolveNode method.

Notation

Example

The following reference syntax accesses an unnamed subform:

xfa.form.form1.#subform

The following reference syntax accesses the name property of a subform if the subform also contains
a field named name:
xfa.form.form1.#subform.#name

25
 Expressions

2.16.13. Occurrence value of an object

The square bracket ([ ]) notation denotes the occurrence value of an object.

In language-specific forms for Arabic, Hebrew, Thai, and Vietnamese, the reference syntax is always
on the right (even for right-to-left languages).

Notation

[ ]

Example

To construct an occurrence value reference, place square brackets ([ ]) after an object name, and
enclose within the brackets one of the following values:
• [ n ], wherenis an absolute occurrence index number beginning at 0. An occurrence number
that is out of range does not return a value. For example,
xfa.form.form1.#subform.Quantity[3]
refers to the fourth occurrence of the Quantity object.
• [ +/- n ], where n indicates an occurrence relative to the occurrence of the object making
the reference. Positive values yield higher occurrence numbers, and negative values yield lower
occurrence numbers. For example,
xfa.form.form1.#subform.Quantity[+2]
This reference yields the occurrence of Quantity whose occurrence number is two more than
the occurrence number of the container making the reference. For example, if this reference
was attached to the Quantity[2]object , the reference would be the same as
xfa.template.Quantity[4]
If the computed index number is out of range, the reference returns an error.
The most common use of this syntax is for locating the previous or next occurrence of a partic-
ular object. For example, every occurrence of the Quantity object (except the first) might use
Quantity[-1] to get the value of the previous Quantity object.
• [*]indicates multiple occurrences of an object. The first named object is found, and objects
of the same name that are siblings to the first are returned. Note that using this notation returns
a collection of objects. For example,
xfa.form.form1.#subform.Quantity[*]
• This expression refers to all objects with a name ofQuantitythat are siblings to the first
occurrence ofQuantityfound by the reference.

26
Expressions 2

Using the tree for reference, these expressions return the following objects:
• Subform_Page.Subform1[*]returns bothSubform1objects.
• Subform_Page.Subform1.Subform3.TextField2[*]returns
twoTextField2objects.Subform_Page.Subform1resolves to the
firstSubform1object on the left, andTextField2[*]evaluates relative to
theSubform3object.
• Subform_Page.Subform1[*].TextField1returns both of
theTextField1instances.Subform_Page.Subform1[*]resolves to
bothSubform1objects, andTextField1evaluates relative to theSubform1objects.
• Subform_Page.Subform1[*].Subform3.TextField2[1]returns the second and
fourthTextField2objects from the left.Subform_Page.Subform1[*]resolves to
bothSubform1objects, andTextField2[1]evaluates relative to theSubform3objects.
• Subform_Page.Subform1[*].Subform3[*]returns both instances of
theSubform3object.
• Subform_Page.*returns bothSubform1objects and theSubform2object.
• Subform_Page.Subform2.*returns the two instances of theNumericField2object.
• You can use the ‘ [ ]’ (square bracket) syntax with JavaScript if it used with the
resolveNode method.

2.17. Property and method calls

Designer defines a variety of properties and methods for all objects on a form design. FormCalc
provides access to these properties and methods and allows you to use them to modify the appear-
ance and behavior of objects on your form. Similar to a function call, you invoke properties and
methods by passing arguments to them in a specific order. The number and type of arguments in
each property and method are specific to each object type.
NOTE: Different form design objects support different properties and methods. For a complete list of the
properties and methods objects support, see Aboutthe Scripting Reference.

27
 Expressions

2.18. Built-in function calls

FormCalc supports a large set of built-in functions with a wide range of capabilities. The names of
the functions are case-insensitive, but unlike keywords, FormCalc does not reserve the names of the
functions. This means that calculations on forms with objects whose names coincide with the names
of FormCalc functions do not conflict.
Functions may or may not require some set of arguments to execute and return a value. Many func-
tions have arguments that are optional, meaning it is up to you to decide if the argument is necessary
for the particular situation.
FormCalc evaluates all function arguments in order, beginning with the lead argument. If an attempt
is made to pass less than the required number of arguments to a function, the function generates an
error exception.
Each function expects each argument in a particular format, either as a number literal or string
literal. If the value of an argument does not match what a function expects, FormCalc converts the
value. For example:
Len(35)

The Len function actually expects a literal string. In this case, FormCalc converts the argument from
the number 35 to the string “35”, and the function evaluates to 2.
However, in the case of a string literal to number literal, the conversion is not so simple. For example:
Abs("abc")

The Abs function expects a number literal. FormCalc converts the value of all string literals as 0. This
can cause problems in functions where a 0 value forces an error, such as in the case of the Apr func-
tion.
Some function arguments only require integral values; in such cases, the passed arguments are
always promoted to integers by truncating the fractional part.
Here is a summary of the key properties of built-in functions:
• Built-in function names are case-insensitive.
• The built-in functions are predefined, but their names are not reserved words. This means that
the built-in function Max never conflicts with an object, object property, or object method
named Max.
• Many of the built-in functions have a mandatory number of arguments, which can be followed
by a optional number of arguments.
• A few built-in functions, Avg, Count, Max, Min, Sum, and Concat, accept an indefinite
number of arguments.
For a complete listing of all the FormCalc functions, see the Alphabetical FunctionsList.

28
Alphabetical Functions List 3

3. Alphabetical Functions List

The following table lists all available FormCalc functions, provides a description of each function,
and identifies the category type to which each function belongs.

Function Description Type

Abs Returns the absolute value of a numeric value or expression. Arithmetic

Apr Returns the annual percentage rate for a loan. Financial

At Locates the starting character position of a string within another String

string.

Avg Evaluates a set of number values and/or expressions and returns the Arithmetic
average of the non-null elements contained within that set.

Ceil Returns the whole number greater than or equal to a given number. Arithmetic

Choose Selects a value from a given set of parameters. Logical

Concat Returns the concatenation of two or more strings. String

Count Evaluates a set of values and/or expressions and returns the number Arithmetic
of non-null elements contained within the set.

CTerm Returns the number of periods needed for an investment earning a Financial
fixed, but compounded, interest rate to grow to a future value.

Date Returns the current system date as the number of days since the Date and Time
Epoch

Date2Num Returns the number of days since the Epoch, given a date string. Date and Time

DateFmt Returns a date format string, given a date format style. Date and Time

Decode Returns the decoded version of a given string. String

Encode Returns the encoded version of a given string. String

Eval Returns the value of a given form calculation. Miscellaneous

Exists Determines whether the given parameter is a reference syntax to an Logical

existing object.

Floor Returns the largest whole number that is less than or equal to the Arithmetic
given value.

29
 Alphabetical Functions List

Function Description Type

Format Formats the given data according to the specified picture format String
string.

FV Returns the future value of consistent payment amounts made at Financial

regular intervals at a constant interest rate.

Get Downloads the contents of the given URL. URL

HasValue Determines whether the given parameter is an accessor with a Logical

non-null, non-empty, or non-blank value.

IPmt Returns the amount of interest paid on a loan over a set period of Financial
time.

IsoDate2Num Returns the number of days since the Epoch, given an valid date Date and Time
string.

IsoTime2Num Returns the number of milliseconds since the Epoch, given a valid Date and Time
time string.

Left Extracts a specified number of characters from a string, starting with String
the first character on the left.

Len Returns the number of characters in a given string. String

LocalDateFmt Returns a localized date format string, given a date format style. Date and Time

LocalTimeFmt Returns a localized time format string, given a time format style. Date and Time

Lower Converts all uppercase characters within a specified string to String

lowercase characters.

Ltrim Returns a string with all leading white space characters removed. String

Max Returns the maximum value of the non-null elements in the given Arithmetic
set of numbers.

Min Returns the minimum value of the non-null elements of the given set Arithmetic
of numbers.

Mod Returns the modulus of one number divided by another. Arithmetic

NPV Returns the net present value of an investment based on a discount Financial
rate and a series of periodic future cash flows.

Null Returns the null value. The null value means no value. Miscellaneous

Num2Date Returns a date string, given a number of days since the Epoch. Date and Time

30
Alphabetical Functions List 3

Function Description Type

Num2GMTime Returns a GMT time string, given a number of milliseconds from the Date and Time
Epoch.

Num2Time Returns a time string, given a number of milliseconds from the Date and Time
Epoch.

Oneof Returns true (1) if a value is in a given set, and false (0) if it is not. Logical

Parse Analyzes the given data according to the given picture format. String

Pmt Returns the payment for a loan based on constant payments and a Financial
constant interest rate.

Post Posts the given data to the specified URL. URL

PPmt Returns the amount of principal paid on a loan over a period of time. Financial

Put Uploads the given data to the specified URL. URL

PV Returns the present value of an investment of periodic constant Financial

payments at a constant interest rate.

Rate Returns the compound interest rate per period required for an Financial
investment to grow from present to future value in a given period.

Ref Returns a reference to an existing object. Miscellaneous

Replace Replaces all occurrences of one string with another within a specified String
string.

Right Extracts a number of characters from a given string, beginning with String
the last character on the right.

Round Evaluates a given numeric value or expression and returns a number Arithmetic
rounded to the given number of decimal places.

Rtrim Returns a string with all trailing white space characters removed. String

Space Returns a string consisting of a given number of blank spaces. String

Str Converts a number to a character string. FormCalc formats the result String
to the specified width and rounds to the specified number of decimal
places.

Stuff Inserts a string into another string. String

Substr Extracts a portion of a given string. String

Sum Returns the sum of the non-null elements of a given set of numbers. Arithmetic

31
 Alphabetical Functions List

Function Description Type

Term Returns the number of periods needed to reach a given future value Financial
from periodic constant payments into an interest-bearing account.

Time Returns the current system time as the number of milliseconds since Date and Time
the Epoch.

Time2Num Returns the number of milliseconds since the Epoch, given a time Date and Time
string.

TimeFmt Returns a time format, given a time format style. Date and Time

UnitType Returns the units of a unitspan. A unitspan is a string consisting of a Miscellaneous

number followed by a unit name.

UnitValue Returns the numeric value of a measurement with its associated Miscellaneous
unitspan, after an optional unit conversion.

Upper Converts all lowercase characters within a string to uppercase. String

Uuid Returns a Universally Unique Identifier (UUID) string to use as an String

identification method.

Within Returns true (1) if the test value is within a given range, and false (0) Logical
if it is not.

WordNum Returns the English text equivalent of a given number. String

32
Arithmetic Functions 4

4. Arithmetic Functions
Arithmetic functions perform a range of mathematical operations.

4.1. Abs

Returns the absolute value of a numeric value or expression, or returns null if the value or expression
is null.

4.1.1. Syntax

Abs(n1)

4.1.2. Parameters

Parameter Description

n1 A numeric value or expression to evaluate.

NOTE: FormCalc follows the IEEE-754 international standard when handling floating point numeric
values. For more information, see Numberliterals.

4.1.3. Examples

The following expressions are examples of using the Abs function:

Expression Returns

Abs(1.03) 1.03

Abs(-1.03) 1.03

Abs(0) 0

33
 Arithmetic Functions

4.2. Avg

Evaluates a set of number values and/or expressions and returns the average of the non-null
elements contained within that set.

4.2.1. Syntax

Avg(n1 [, n2 ...])

4.2.2. Parameters

Parameter Description

n1 The first numeric value or expression of the set.

n2(optional) Additional numeric values or expressions.

NOTE: FormCalc follows the IEEE-754 international standard when handling floating point numeric
values. For more information, see Numberliterals.

4.2.3. Examples

The following expressions are examples of using the Avg function:

Expression Returns

Avg(0, 32, 16) 16

Avg(2.5, 17, null) 9.75

Avg(Price[0], Price[1], Price[2], The average value of the first four non-null occurrences
Price[3]) ofPrice.

Avg(Quantity[*]) The average value of all non-null occurrences

ofQuantity.

34
Arithmetic Functions 4

4.3. Ceil

Returns the whole number greater than or equal to a given number, or returns null if its parameter
is null.

4.3.1. Syntax

Ceil(n)

4.3.2. Parameters

Parameter Description

n Any numeric value or expression.

The function returns0ifnis not a numeric value or expression.

NOTE: FormCalc follows the IEEE-754 international standard when handling floating point numeric
values. For more information, see Numberliterals.

4.3.3. Examples

The following expressions are examples of using the Ceil function:

Expression Returns

Ceil(2.5875) 3

Ceil(-5.9) -5

Ceil("abc") 0

Ceil(A) 100 if the value ofAis 99.999

4.4. Count

Evaluates a set of values and/or expressions and returns the count of non-null elements contained
within the given set.

35
 Arithmetic Functions

4.4.1. Syntax

Count(n1 [, n2 ...])

4.4.2. Parameters

Parameter Description

n1 A numeric value or expression.

n2(optional) Additional numeric values and/or expressions.

NOTE: FormCalc follows the IEEE-754 international standard when handling floating point numeric
values. For more information, see Numberliterals.

4.4.3. Examples

The following expressions are examples of using the Count function:

Expression Returns

Count("Tony", "Blue", 41) 3

Count(Customers[*]) The number of non-null occurrences ofCustomers.

Count(Coverage[2], "Home", 3, provided the third occurrence ofCoverageis non-null.

"Auto")

4.5. Floor

Returns the largest whole number that is less than or equal to the given value.

4.5.1. Syntax

Floor(n)

36
Arithmetic Functions 4

4.5.2. Parameters

Parameter Description

n Any numeric value or expression.

NOTE: FormCalc follows the IEEE-754 international standard when handling floating point numeric
values. For more information, see Numberliterals.

4.5.3. Examples

The following expressions are examples of using the Floor function:

Expression Returns

Floor(21.3409873) 21

Floor(5.999965342) 5

Floor(3.2 * 15) 48

4.6. Max

Returns the maximum value of the non-null elements in the given set of numbers.

4.6.1. Syntax

Max(n1 [, n2 ...])

4.6.2. Parameters

Parameter Description

n1 A numeric value or expression.

n2(optional) Additional numeric values and/or expressions.

37
 Arithmetic Functions

NOTE: FormCalc follows the IEEE-754 international standard when handling floating point numeric
values. For more information, see Numberliterals.

4.6.3. Examples

The following expressions are examples of using the Max function:

Expression Returns

Max(234, 15, 107) 234

Max("abc", 15, "Tony Blue") 15

Max("abc") 0

Max(Field1[*], Field2[0]) Evaluates the non-null occurrences of Field1 as well as the

first occurrence ofField2, and returns the highest value.

Max(Min(Field1[*], Field2[0]), The first expression evaluates the non-null occurrences

Field3, Field4) ofField1as well as the first occurrence ofField2, and returns
the lowest value. The final result is the maximum of the returned
value compared against the values ofField3andField4.
See also Min.

4.7. Min

Returns the minimum value of the non-null elements of the given set of numbers.

4.7.1. Syntax

Min(n1 [, n2 ...])

4.7.2. Parameters

Parameter Description

n1 A numeric value or expression.

n2(optional) Additional numeric values and/or expressions.

38
Arithmetic Functions 4

NOTE: FormCalc follows the IEEE-754 international standard when handling floating point numeric
values. For more information, see Numberliterals.

4.7.3. Examples

The following expressions are examples of using the Min function:

Expression Returns

Min(234, 15, 107) 15

Min("abc", 15, "Tony Blue") 15

Min("abc") 0

Min(Field1[*], Field2[0]) Evaluates the non-null occurrences ofSales_Julyas well as

the first occurrence ofSales_August, and returns the lowest
value.

Min(Max(Field1[*], Field2[0]), The first expression evaluates the non-null occurrences

Field3, Field4) ofField1as well as the first occurrence ofField2, and
returns the highest value. The final result is the minimum of the
returned value compared against the values ofField3and
Field4.
See also Max.

4.8. Mod

Returns the modulus of one number divided by another. The modulus is the remainder of the divi-
sion of the dividend by the divisor. The sign of the remainder always equals the sign of the dividend.

4.8.1. Syntax

Mod(n1, n2)

4.8.2. Parameters

Parameter Description

n1 The dividend, a numeric value or expression.

39
 Arithmetic Functions

Parameter Description

n2 The divisor, a numeric value or expression.

If n1 and/or n2 are not numeric values or expressions, the function returns 0.

NOTE: FormCalc follows the IEEE-754 international standard when handling floating point numeric
values. For more information, see Numberliterals.

4.8.3. Examples

The following expressions are examples of using the Mod function:

Expression Returns

Mod(64, -3) 1

Mod(-13,3) -1

Mod("abc", 2) 0

Mod(X[0], Y[9]) The first occurrence ofXis used as the dividend and the tenth
occurrence ofYis used as the divisor.

Mod(Round(Value[4], 2), The first fifth occurrence ofValuerounded to two decimal places
Max(Value[*])) is used as the dividend and the highest of all non-null occurrences
ofValueis used as the divisor.
See also Max and Round.

4.9. Round

Evaluates a given numeric value or expression and returns a number rounded to a given number of
decimal places.

4.9.1. Syntax

Round(n1 [, n2])

40
Arithmetic Functions 4

4.9.2. Parameters

Parameter Description

n1 A numeric value or expression to be evaluated.

n2(optional) The number of decimal places with which to evaluaten1to a maximum of 12.
If you do not include a value forn2, or ifn2is invalid, the function assumes the number of
decimal places is 0.

NOTE: FormCalc follows the IEEE-754 international standard when handling floating point numeric
values. For more information, see Numberliterals.

4.9.3. Examples

The following expressions are examples of using the Round function:

Expression Returns

Round(12.389764537, 4) 12.3898

Round(20/3, 2) 6.67

Round(8.9897, "abc") 9

Round(FV(400, 0.10/12, 904195.17. This takes the value evaluated using theFVfunction and
30*12), 2) rounds it to two decimal places.
See also FV.

Round(Total_Price, 2) Rounds off the value ofTotal_Priceto two decimal places.

4.10. Sum

Returns the sum of the non-null elements of a given set of numbers.

4.10.1. Syntax

Sum(n1 [, n2 ...])

41
 Arithmetic Functions

4.10.2. Parameters

Parameter Description

n1 A numeric value or expression.

n2(optional) Additional numeric values and/or expressions.

NOTE: FormCalc follows the IEEE-754 international standard when handling floating point numeric
values. For more information, see Numberliterals.

4.10.3. Examples

The following expressions are examples of using the Sum function:

Expression Returns

Sum(2, 4, 6, 8) 20

Sum(-2, 4, -6, 8) 4

Sum(4, 16, "abc", 19) 39

Sum(Amount[2], Amount[5]) Totals the third and sixth occurrences ofAmount.

Sum(Round(20/3, 2), Max(Amount[*]), Totals the value of 20/3 rounded to two decimal
Min(Amount[*])) places, as well as the largest and smallest non-null
occurrences ofAmount.
See also Max, Min, and Round.

42
Date and Time Functions 5

5. Date and Time Functions

Date and time functions deal specifically with creating and manipulating date and time values.

5.1. Structuring dates and times

5.1.1. Epoch

Date values and time values have an associated origin or epoch, which is a moment in time from
which time begins. Any date value and any time value prior to its epoch is invalid.
The unit of value for all date functions is the number of days since the epoch. The unit of value for
all time functions is the number of milliseconds since the epoch.
Designer defines day one for the epoch for all date functions as Jan 1, 1900, and millisecond one for
the epoch for all time functions is midnight, 00:00:00, Greenwich Mean Time (GMT). This defini-
tion means that negative time values can be returned to users in time zones east of GMT.

5.1.2. Date formats

A date format is a shorthand specification of how a date appears. It consists of various punctuation
marks and symbols that represent the formatting that the date must use. The following table lists
examples of date formats.

Date format Example

MM/DD/YY 11/11/78

DD/MM/YY 25/07/85

MMMM DD, YYYY March 10, 1964

The format of dates is governed by an ISO standard. Each country or region specifies its own date
formats. The four general categories of date formats are short, medium, long, and full. The following
table contains examples of different date formats from different locales for each of the categories.

43
 Date and Time Functions

Locale identifier and description Date format (Category) Example

en_GB DD/MM/YY (Short) 08/12/92

English (United Kingdom) 08/04/05

fr_CA YY-MM-DD (Medium) 92-08-18

French (Canada)

de_DE D. MMMM YYYY (Long) 17. Juni 1989

German (Germany)

fr_FR EEEE, ' le ' D MMMM YYYY (Full) Lundi, le 29 Octobre, 1990
French (France)

5.1.3. Time formats

A time format is a shorthand specification to format a time. It consists of punctuations, literals, and
pattern symbols. The following table lists examples of time formats.

Time format Example

h:MM A 7:15 PM

HH:MM:SS 21:35:26

HH:MM:SS 'o''clock' A Z 14:20:10 o’clock PM EDT

Time formats are governed by an ISO standard. Each nation specifies the form of its default, short,
medium, long, and full-time formats. The locale identifies the format of times that conform to the
standards of that nation.
The following table contains some examples of different date formats from different locales for each
of the categories.

Locale identifier and description Time format (Category) Example

en_GB HH:MM (Short) 14:13

English (United Kingdom)

fr_CA HH:MM:SS (Medium) 12:15:50

French (Canada)

de_DE HH:MM:SS z (Long) 14:13:13 -0400

German (Germany)

44
Date and Time Functions 5

Locale identifier and description Time format (Category) Example

fr_FR HH ' h ' MM Z (Full) 14 h 13 GMT-04:00

French (France)

5.1.4. Date and time picture formats

The following symbols must be used to create date and time patterns for date/time fields. Certain
date symbols are only used in Chinese, Japanese, and Korean locales. These symbols are also speci-
fied below.
NOTE: The comma (,), dash (-), colon (:), slash (/), period (.), and space ( ) are treated as literal values
and can be included anywhere in a pattern. To include a phrase in a pattern, delimit the text string
with single quotation marks ('). For example, 'Your payment is due no later than'
MM-DD-YYcan be specified as the display pattern.

Formatted value for English (USA) locale where

Date the locale-sensitive input value is 1/1/08 (which is
symbol Description January 1, 2008)

D 1 or 2 digit (1-31) day of the month 1

DD Zero-padded 2 digit (01-31) day of the month 01

J 1, 2, or 3 digit (1-366) day of the year 1

JJJ Zero-padded, three-digit (001-366) day of the 001

year

M One- or two-digit (1-12) month of the year 1

MM Zero-padded, two-digit (01-12) month of the 01

year

MMM Abbreviated month name Jan

MMMM Full month name January

E One-digit (1-7) day of the week, where 3 (because January 1, 2008 is a Tuesday)
(1=Sunday)

EEE Abbreviated weekday name Tue (because January 1, 2008 is a Tuesday)

EEEE Full weekday name Tuesday (because January 1, 2008 is a Tuesday)

45
 Date and Time Functions

Formatted value for English (USA) locale where

Date the locale-sensitive input value is 1/1/08 (which is
symbol Description January 1, 2008)

YY Two-digit year, where numbers less than 30 08

are considered to fall after the year 2000 and
numbers 30 and higher are considered to
occur before 2000. For example, 00=2000,
29=2029, 30=1930, and 99=1999

YYYY Four-digit year 2008

G Era name (BC or AD) AD

w One-digit (0-5) week of the month, where 1

week 1 is the earliest set of four contiguous
days ending on a Saturday

WW Two-digit (01-53) ISO-8601 week of the year, 01

where week 1 is the week containing January
4

Several additional date patterns are available for specifying date patterns in Chinese, Japanese, and
Korean locales.
Japanese eras can be represented by several different symbols. The final four era symbols provide
alternative symbols to represent Japanese eras.

CJK date
symbol Description

DDD The locale’s ideographic numeric valued day of the month

DDDD The locale’s tens rule ideographic numeric valued day of the month

YYY The locale’s ideographic numeric valued year

YYYYY The locale’s tens rule ideographic numeric valued year

g The locale’s alternate era name. For the current Japanese era, Heisei, this pattern displays the
ASCII letter H (U+48)

gg The locale’s alternate era name. For the current Japanese era, this pattern displays the ideograph
that is represented by the Unicode symbol (U+5E73)

ggg The locale’s alternate era name. For the current Japanese era, this pattern displays the ideographs
that are represented by the Unicode symbols (U+5E73 U+6210)

g The locale’s alternate era name. For the current Japanese era, this pattern displays the full width
letter H (U+FF28)

46
Date and Time Functions 5

CJK date
symbol Description

g g The locale’s alternate era name. For the current Japanese era, this pattern displays the ideograph
that is represented by the Unicode symbol (U+337B)

Formatted value
Time Locale-sensitive input for English
symbol Description value (USA) locale

h One- or two-digit (1-12) hour of the day (AM/PM) 12:08 AM or 2:08 PM 12 or 2

hh Zero-padded 2 digit (01-12) hour of the day 12:08 AM or 2:08 PM 12 or 02

(AM/PM)

k One- or two-digit (0-11) hour of the day (AM/PM) 12:08 AM or 2:08 PM 0 or 2

kk Two-digit (00-11) hour of the day (AM/PM) 12:08 AM or 2:08 PM 00 or 02

H One- or two-digit (0-23) hour of the day 12:08 AM or 2:08 PM 0 or 14

HH Zero-padded, two-digit (00-23) hour of the day 12:08 AM or 2:08 PM 00 or 14

K One- or two-digit (1-24) hour of the day 12:08 AM or 2:08 PM 24 or 14

KK Zero-padded, two-digit (01-24) hour of the day 12:08 AM or 2:08 PM 24 or 14

M One- or two-digit (0-59) minute of the hour 2:08 PM 8

NOTE: You must use this symbol with an hour
symbol.

MM Zero-padded, two-digit (00-59) minute of the hour 2:08 PM 08

NOTE: You must use this symbol with an hour
symbol.

S One- or two-digit (0-59) second of the minute 2:08:09 PM 9

NOTE: You must use this symbol with an hour and
minute symbol.

SS Zero-padded, two-digit (00-59) second of the 2:08:09 PM 09

minute
NOTE: You must use this symbol with an hour and
minute symbol.

FFF Three- digit (000-999) thousandth of the second 2:08:09 PM 09

NOTE: You must use this symbol with an hour,
minute, and seconds symbol.

A The part of the day that is from midnight to noon 2:08:09 PM PM

(AM) or from noon to midnight (PM)

47
 Date and Time Functions

Formatted value
Time Locale-sensitive input for English
symbol Description value (USA) locale

z ISO-8601 time-zone format (for example,Z, 2:08:09 PM -0400

+0500, -0030, -01, +0100)
NOTE: You must use this symbol with an hour
symbol.

zz Alternative ISO-8601 time-zone format (for 2:08:09 PM -04:00

example, Z, +05:00, -00:30, -01, +01:00)
NOTE: You must use this symbol with an hour
symbol.

Z Abbreviated time-zone name (for example, GMT, 2:08:09 PM EDT

GMT+05:00, GMT-00:30, EST, PDT)
NOTE: You must use this symbol with an hour
symbol.

Reserved symbols

The following symbols have special meanings and cannot be used as literal text.

Symbo
l Description

? When submitted, the symbol matches any one character. When merged for display, it
becomes a space.

* When submitted, the symbol matches 0 or Unicode white space characters. When merged
for display, it becomes a space.

+ When submitted, the symbol matches one or more Unicode white space characters. When
merged for display, it becomes a space.

5.1.5. Locales

For a list of supported languages, see Locales topic in the Using Designer guide.

5.2. Date

Returns the current system date as the number of days since the epoch.

48
Date and Time Functions 5

5.2.1. Syntax

Date()

5.2.2. Parameters

None

5.2.3. Examples

The following expression is an example of using the Date function:

Expression Returns

Date() 37875(the number of days from the epoch to September 12, 2003)

5.3. Date2Num

Returns the number of days since the epoch, given a date string.

5.3.1. Syntax

Date2Num(d [, f [, k ]])

5.3.2. Parameters

Parameter Description

d A date string in the format supplied byfthat also conforms to the locale given byk.

f(optional) A date format string. Iffis omitted, the default date formatMMM D, YYYYis used.

k(optional) A locale identifier string that conforms to the locale naming standards. Ifkis omitted (or is invalid),
the ambient locale is used.

The function returns a value of0 if any of the following conditions are true:
• The format of the given date does not match the format specified in the function.

49
 Date and Time Functions

• Either the locale or date format supplied in the function is invalid.

Insufficient information is provided to determine a unique day since the epoch (that is, any
information regarding the date is missing or incomplete).

5.3.3. Examples

The following expressions are examples of using the Date2Num function:

Expression Returns

Date2Num("Mar 15, 1996") 35138

Date2Num("1/1/1900", "D/M/YYYY") 1

Date2Num("03/15/96", "MM/DD/YY") 35138

Date2Num("Aug 1,1996", "MMM D, YYYY") 35277

Date2Num("96-08-20", "YY-MM-DD", "fr_FR") 35296

Date2Num("1/3/00", "D/M/YY") - Date2Num("1/2/00", "D/M/YY") 29

5.4. DateFmt

Returns a date format string, given a date format style.

5.4.1. Syntax

DateFmt([n [, k ]])

50
Date and Time Functions 5

5.4.2. Parameters

Parameter Description

n(optional) An integer identifying the locale-specific time format style as follows:

• 1 (Short style)
• 2 (Medium style)
• 3 (Long style)
• 4 (Full style)
Ifnis omitted (or is invalid), the default style value 0 is used.

k(optional) A locale identifier string that conforms to the locale naming standards. Ifkis omitted (or is invalid),
the ambient locale is used.

5.4.3. Examples

The following expressions are examples of using the DateFmt function:

Expression Returns

DateFmt(1) M/D/YY(if en_US locale is set)

DateFmt(2, "fr_CA") YY-MM-DD

DateFmt(3, "de_DE") D. MMMM YYYY

DateFmt(4, "fr_FR") EEEE D' MMMM YYYY

5.5. IsoDate2Num

Returns the number of days since the epoch began, given a valid date string.

5.5.1. Syntax

IsoDate2Num(d)

51
 Date and Time Functions

5.5.2. Parameters

Parameter Description

d A valid date string.

5.5.3. Examples

The following expressions are examples of using the IsoDate2Num function:

Expression Returns

IsoDate2Num("1900") 1

IsoDate2Num("1900-01") 1

IsoDate2Num("1900-01-01") 1

IsoDate2Num("19960315T20:20:20") 35138

IsoDate2Num("2000-03-01") - IsoDate2Num("20000201") 29

5.6. IsoTime2Num

Returns the number of milliseconds since the epoch, given a valid time string.

5.6.1. Syntax

IsoTime2Num(d)

5.6.2. Parameters

Parameter Description

d A valid time string.

52
Date and Time Functions 5

5.6.3. Examples

The following expressions are examples of using the IsoTime2Num function:

Expression Returns

IsoTime2Num("00:00:00Z") 1, for a user in the Eastern Time (ET) zone.

IsoTime2Num("13") 64800001, for a user located in Boston, U.S.

IsoTime2Num("13:13:13") 76393001, for a user located in California.

IsoTime2Num("19111111T131313+01") 43993001, for a user located in the Eastern Time (ET) zone.

5.7. LocalDateFmt

Returns a localized date format string, given a date format style.

5.7.1. Syntax

LocalDateFmt([n [, k ]])

5.7.2. Parameters

Parameter Description

n(optional) An integer identifying the locale-specific date format style as follows:

• 1 (Short style)
• 2 (Medium style)
• 3 (Long style)
• 4 (Full style)
Ifnis omitted (or is invalid), the default style value 0 is used.

k(optional) A locale identifier string that conforms to the locale naming standards. Ifkis omitted (or is
invalid), the ambient locale is used.

53
 Date and Time Functions

5.7.3. Examples

The following expressions are examples of the LocalDateFmt function:

Expression Returns

LocalDateFmt(1, "de_DE") tt.MM.uu

LocalDateFmt(2, "fr_CA") aa-MM-jj

LocalDateFmt(3, "de_CH") t. MMMM jjjj

LocalDateFmt(4, "fr_FR") EEEE j MMMM aaaa

5.8. LocalTimeFmt

Returns a localized time format string, given a time format style.

5.8.1. Syntax

LocalTimeFmt([n [, k ]])

5.8.2. Parameters

Parameter Description

n(Optional) An integer identifying the locale-specific time format style as follows:

• 1 (Short style)
• 2 (Medium style)
• 3 (Long style)
• 4 (Full style)
Ifnis omitted (or is invalid), the default style value 0 is used.

k(Optional) A locale identifier string that conforms to the locale naming standards. Ifkis omitted (or is invalid),
the ambient locale is used.

54
Date and Time Functions 5

5.8.3. Examples

The following expressions are examples of using the LocalTimeFmt function:

Expression Returns

LocalTimeFmt(1, "de_DE") HH:mm

LocalTimeFmt(2, "fr_CA") HH:mm:ss

LocalTimeFmt(3, "de_CH") HH:mm:ss z

LocalTimeFmt(4, "fr_FR") HH' h 'mm z

5.9. Num2Date

Returns a date string, given a number of days since the epoch.

5.9.1. Syntax

Num2Date(n [,f [, k ]])

5.9.2. Parameters

Parameter Description

n An integer representing the number of days.

Ifnis invalid, the function returns an error.

f(Optional) A date format string. If you do not include a value forf, the function uses the default date format
MMM D, YYYY.

k(Optional) A locale identifier string that conforms to the locale naming standards. If you do not include a
value for k, or if k is invalid, the function uses the ambient locale.

The function returns a value of 0 if any of the following conditions are true:
• The format of the given date does not match the format specified in the function.

55
 Date and Time Functions

• Either the locale or date format supplied in the function is invalid.

Insufficient information is provided to determine a unique day since the epoch (that is, any
information regarding the date is missing or incomplete.

5.9.3. Examples

The following expressions are examples of using the Num2Date function:

Expression Returns

Num2Date(1, "DD/MM/YYYY") 01/01/1900

Num2Date(35139, "DD-MMM-YYYY", "de_DE") 16-Mrz-199

6

Num2Date(Date2Num("Mar 15, 2000") - Date2Num("98-03-15", Jan 1, 1902

"YY-MM-DD", "fr_CA"))

5.10. Num2GMTime

Returns a GMT time string, given a number of milliseconds from the epoch.

5.10.1. Syntax

Num2GMTime(n [,f [, k ]])

5.10.2. Parameters

Parameter Description

n An integer representing the number of milliseconds.

Ifnis invalid, the function returns an error.

f(Optional) A time format string. If you do not include a value for f, the function uses the default time
formatH:MM:SS A.

k(Optional) A locale identifier string that conforms to the locale naming standards. If you do not include a value
fork, or if kis invalid, the function uses the ambient locale.

56
Date and Time Functions 5

The function returns a value of 0 if any of the following conditions are true:
• The format of the given time does not match the format specified in the function.
• Either the locale or time format supplied in the function is invalid.
Insufficient information is provided to determine a unique time since the epoch (that is, any
information regarding the time is missing or incomplete.

5.10.3. Examples

The following expressions illustrate using the Num2GMTime function:

Expression Returns

Num2GMTime(1, "HH:MM:SS") 00:00:00

Num2GMTime(65593001, "HH:MM:SS Z") 18:13:13 GMT

Num2GMTime(43993001, TimeFmt(4, "de_DE"), "de_DE") 12.13 Uhr GMT

5.11. Num2Time

Returns a time string, given a number of milliseconds from the epoch.

5.11.1. Syntax

Num2Time(n [,f [, k ]])

5.11.2. Parameters

Parameter Description

n An integer representing the number of milliseconds.

Ifnis invalid, the function returns an error.

f(Optional) A time format string. If you do not include a value forf, the function uses the default time
formatH:MM:SS A.

57
 Date and Time Functions

Parameter Description

k(Optional) A locale identifier string that conforms to the locale naming standards. If you do not include a value
fork, or ifkis invalid, the function uses the ambient locale.

The function returns a value of 0 if any of the following conditions are true:
• The format of the given time does not match the format specified in the function.
• Either the locale or time format supplied in the function is invalid.
Insufficient information is provided to determine a unique time since the epoch (that is, any
information regarding the time is missing or incomplete.

5.11.3. Examples

The following expressions illustrate using the Num2Time function:

Expression Returns

Num2Time(1, "HH:MM:SS") 00:00:00in Greenwich, England and09:00:00in

Tokyo.

Num2Time(65593001, "HH:MM:SS Z") 13:13:13EST in Boston, U.S.

Num2Time(65593001, "HH:MM:SS Z", 13:13:13 GMT-05:00to a German-Swiss user in

"de_DE") Boston, U.S.

Num2Time(43993001, TimeFmt(4, 13.13 Uhr GMT+01:00to a user in Zurich, Austria.

"de_DE"), "de_DE")

Num2Time(43993001, "HH:MM:SSzz") 13:13+01:00to a user in Zurich, Austria.

5.12. Time

Returns the current system time as the number of milliseconds since the epoch.

5.12.1. Syntax

Time()

58
Date and Time Functions 5

5.12.2. Parameters

None

5.12.3. Examples

The following expression is an example of using the Time function:

Expression Returns

Time() 71533235at precisely 3:52:15 P.M. on September 15th, 2003 to a user in the Eastern Standard
Time (EST) zone.

5.13. Time2Num

Returns the number of milliseconds since the epoch, given a time string.

5.13.1. Syntax

Time2Num(d [, f [, k ]])

5.13.2. Parameters

Parameter Description

d A time string in the format supplied by f that also conforms to the locale given by k.

f(Optional) A time format string. If you do not include a value forf, the function uses the default time
formatH:MM:SS A.

k(Optional) A locale identifier string that conforms to the locale naming standards. If you do not include a
value fork, or if kis invalid, the function uses the ambient locale.

The function returns a value of 0 if any of the following conditions are true:
• The format of the given time does not match the format specified in the function.

59
 Date and Time Functions

• Either the locale or time format supplied in the function is invalid.

Insufficient information is provided to determine a unique time since the epoch (that is, any
information regarding the time is missing or incomplete.

5.13.3. Examples

The following expressions illustrate using the Time2Num function:

Expression Returns

Time2Num("00:00:00 GMT", "HH:MM:SS 1

Z")

Time2Num("1:13:13 PM") 76393001to a user in California on Pacific Standard Time,

and 76033001when that same user is on Pacific Daylight
Savings Time.

Time2Num("13:13:13", "HH:MM:SS") - 8to a user in Vancouver and5to a user in Ottawa when on

Time2Num("13:13:13 GMT", "HH:MM:SS Standard Time. On Daylight Savings Time, the returned
Z")) / (60 * 60 * 1000) values are7and4, respectively.

Time2Num("13:13:13 GMT", "HH:MM:SS 47593001

Z", "fr_FR")

5.14. TimeFmt

Returns a time format, given a time format style.

5.14.1. Syntax

TimeFmt([n [, k ]])

60
Date and Time Functions 5

5.14.2. Parameters

Parameter Description

n(Optional) An integer identifying the locale-specific time format style as follows:

• 1 (Short style)
• 2 (Medium style)
• 3 (Long style)
• 4 (Full style)
If you do not include a value forn, or ifnis invalid, the function uses the default style value.

k(Optional) A locale identifier string that conforms to the locale naming standards. Ifkis omitted (or is invalid),
the ambient locale is used.

5.14.3. Examples

The following expressions are examples of using the TimeFmt function:

Expression Returns

TimeFmt(1) h:MM A(if en_US locale is set)

TimeFmt(2, "fr_CA") HH:MM:SS

TimeFmt(3, "fr_FR") HH:MM:SS Z

TimeFmt(4, "de_DE") H.MM' Uhr 'Z

61
 Financial Functions

6. Financial Functions
Financial functions perform a variety of interest, principal, and evaluation calculations related to the
financial sector.

6.1. Apr

Returns the annual percentage rate for a loan.

NOTE: Interest rate calculation methods differ from country to country. This function calculates an
interest rate based on U.S. interest rate standards.

6.1.1. Syntax

Apr(n1, n2, n3)

6.1.2. Parameters

Parameter Description

n1 A numeric value or expression representing the principal amount of the loan.

n2 A numeric value or expression representing the payment amount on the loan.

n3 A numeric value or expression representing the number of periods in the loan’s duration.

If any parameter is null, the function returns null. If any parameter is negative or 0, the function
returns an error.
NOTE: FormCalc follows the IEEE-754 international standard when handling floating point numeric
values. For more information, see Numberliterals.

6.1.3. Examples

The following expressions are examples that use the Apr function:

62
Financial Functions 6

Expression Returns

Apr(35000, 269.50, 360) 0.08515404566for a $35,000 loan repaid at $269.50 a month

for 30 years.

Apr(210000 * 0.75, 850 + 110, 0.07161332404

25 * 26)

Apr(-20000, 250, 120) Error

Apr(P_Value, Payment, Time) This example uses variables in place of actual numeric values or
expressions.

6.2. CTerm

Returns the number of periods needed for an investment earning a fixed, but compounded, interest
rate to grow to a future value.
NOTE: Interest rate calculation methods differ from country to country. This function calculates an
interest rate based on U.S. interest rate standards.

6.2.1. Syntax

CTerm(n1, n2, n3)

6.2.2. Parameters

Parameter Description

n1 A numeric value or expression representing the interest rate per period.

n2 A numeric value or expression representing the future value of the investment.

n3 A numeric value or expression representing the amount of the initial investment.

If any parameter is null, the function returns null. If any parameter is negative or 0, the function
returns an error.
NOTE: FormCalc follows the IEEE-754 international standard when handling floating point numeric
values. For more information, see Numberliterals.

63
 Financial Functions

6.2.3. Examples

The following expressions are examples that use the CTerm function:

Expression Returns

CTerm(0.02, 1000, 100) 116.2767474515

CTerm(0.10, 500000, 12000) 39.13224648502

CTerm(0.0275 + 0.0025, 1000000, 55000 176.02226044975

* 0.10)

CTerm(Int_Rate, Target_Amount, This example uses variables in place of actual numeric

P_Value) values or expressions.

6.3. FV

Returns the future value of consistent payment amounts made at regular intervals at a constant
interest rate.
NOTE: Interest rate calculation methods differ from country to country. This function calculates an
interest rate based on U.S. interest rate standards.

6.3.1. Syntax

FV(n1, n2, n3)

6.3.2. Parameters

Parameter Description

n1 A numeric value or expression representing the payment amount.

n2 A numeric value or expression representing the interest per period of the investment.

n3 A numeric value or expression representing the total number of payment periods.

The function returns an error if either of the following conditions are true:
• Either of n1 or n3 are negative or 0.

64
Financial Functions 6

• n2 is negative.
If any of the parameters are null, the function returns null.
NOTE: FormCalc follows the IEEE-754 international standard when handling floating point
numeric values. For more information, see Numberliterals.

6.3.3. Examples

The following expressions are examples of the FV function:

Expression Returns

FV(400, 0.10 / 12, 30 * 904195.16991842445. This is the value, after 30 years, of a $400 a
12) month investment growing at 10% annually.

FV(1000, 0.075 / 4, 10 * 58791.96145535981. This is the value, after 10 years, of a $1000 a

4) month investment growing at 7.5% a quarter.

FV(Payment[0], Int_Rate / This example uses variables in place of actual numeric values or
4, Time) expressions.

6.4. IPmt

Returns the amount of interest paid on a loan over a set period of time.
NOTE: Interest rate calculation methods differ from country to country. This function calculates an
interest rate based on U.S. interest rate standards.

6.4.1. Syntax

IPmt(n1, n2, n3, n4, n5)

6.4.2. Parameters

Parameter Description

n1 A numeric value or expression representing the principal amount of the loan.

n2 A numeric value or expression representing the annual interest rate of the investment.

65
 Financial Functions

Parameter Description

n3 A numeric value or expression representing the monthly payment amount.

n4 A numeric value or expression representing the first month in which a payment will be made.

n5 A numeric value or expression representing the number of months for which to calculate.

The function returns an error if either of the following conditions are true:
• n1, n2, or n3 are negative or 0.
• Either n4 or n5 are negative.
If any parameter is null, the function returns null. If the payment amount (n3) is less than the
monthly interest load, the function returns0.
NOTE: FormCalc follows the IEEE-754 international standard when handling floating point
numeric values. For more information, see Numberliterals.

6.4.3. Examples

The following expressions are examples that use the IPmt function:

Expression Returns

IPmt(30000, 0.085, 295.50, 624.8839283142.The amount of interest repaid on a $30000 loan at

7, 3) 8.5% for the three months between the seventh month and the tenth
month of the loan’s term.

IPmt(160000, 0.0475, 980, 7103.80833569485.The amount of interest repaid during the third
24, 12) year of the loan.

IPmt(15000, 0.065, 65.50, 0, because the monthly payment is less than the interest the loan accrues
15, 1) during the month.

6.5. NPV

Returns the net present value of an investment based on a discount rate and a series of periodic
future cash flows.
NOTE: Interest rate calculation methods differ from country to country. This function calculates an
interest rate based on U.S. interest rate standards.

66
Financial Functions 6

6.5.1. Syntax

NPV(n1, n2 [, ...])

6.5.2. Parameters

Parameter Description

n1 A numeric value or expression representing the discount rate over a single period.

n2 A numeric value or expression representing a cash flow value, which must occur at the end of a
period. It is important that the values specified inn2and beyond are in the correct sequence.

The function returns an error if n1 is negative or 0. If any of the parameters are null, the function
returns null.
NOTE: FormCalc follows the IEEE-754 international standard when handling floating point numeric
values. For more information, see Numberliterals.

6.5.3. Examples

The following expressions are examples that use the NPV function:

Expression Returns

NPV(0.065, 5000) 4694.83568075117, which is the net present value of an investment

earning 6.5% per year that will generate $5000.

NPV(0.10, 500, 1500, 4000, 11529.60863329007, which is the net present value of an
10000) investment earning 10% a year that will generate $500, $1500, $4000,
and $10,000 in each of the next four years.

NPV(0.0275 / 12, 50, 60, 273.14193838457, which is the net present value of an investment
40, 100, 25) earning 2.75% year that will generate $50, $60, $40, $100, and $25 in
each of the next five months.

6.6. Pmt

Returns the payment for a loan based on constant payments and a constant interest rate.

67
 Financial Functions

NOTE: Interest rate calculation methods differ from country to country. This function calculates an
interest rate based on U.S. interest rate standards.

6.6.1. Syntax

Pmt(n1, n2, n3)

6.6.2. Parameters

Parameter Description

n1 A numeric value or expression representing the principal amount of the loan.

n2 A numeric value or expression representing the interest rate per period of the investment.

n3 A numeric value or expression representing the total number of payment periods.

The function returns an error if any parameter is negative or 0. If any parameter is null, the function
returns null.
NOTE: FormCalc follows the IEEE-754 international standard when handling floating point numeric
values. For more information, see Numberliterals.

6.6.3. Examples

The following expressions are examples that use the Pmt function:

Expression Returns

Pmt(150000, 0.0475 / 855.17604207164, which is the monthly payment on a $150,000 loan at

12, 25 * 12) 4.75% annual interest, repayable over 25 years.

Pmt(25000, 0.085, 12) 3403.82145169876, which is the annual payment on a $25,000 loan at
8.5% annual interest, repayable over 12 years.

6.7. PPmt

Returns the amount of principal paid on a loan over a period of time.

68
Financial Functions 6

NOTE: Interest rate calculation methods differ from country to country. This function calculates an
interest rate based on US interest rate standards.

6.7.1. Syntax

PPmt(n1, n2, n3, n4, n5)

6.7.2. Parameters

Parameter Description

n1 A numeric value or expression representing the principal amount of the loan.

n2 A numeric value or expression representing the annual interest rate.

n3 A numeric value or expression representing the amount of the monthly payment.

n4 A numeric value or expression representing the first month in which a payment will be made.

n5 A numeric value or expression representing the number of months for which to calculate.

The function returns an error if either of the following conditions are true:
• n1, n2, or n3 are negative or 0.
• Either n4 or n5 is negative.
If any parameter is null, the function returns null. If the payment amount (n3) is less than the
monthly interest load, the function returns0.
NOTE: FormCalc follows the IEEE-754 international standard when handling floating point
numeric values. For more information, see Numberliterals.

6.7.3. Examples

The following expressions are examples that use the PPmt function:

Expression Returns

PPmt(30000, 0.085, 261.6160716858, which is the amount of principal repaid on a $30,000

295.50, 7, 3) loan at 8.5% for the three months between the seventh month and the tenth
month of the loan’s term.

69
 Financial Functions

Expression Returns

PPmt(160000, 0.0475, 4656.19166430515, which is the amount of principal repaid during the
980, 24, 12) third year of the loan.

PPmt(15000, 0.065, 0, because in this case the monthly payment is less than the interest the loan
65.50, 15, 1) accrues during the month, therefore, no part of the principal is repaid.

6.8. PV

Returns the present value of an investment of periodic constant payments at a constant interest rate.
NOTE: Interest rate calculation methods differ from country to country. This function calculates an
interest rate based on U.S. interest rate standards.

6.8.1. Syntax

PV(n1, n2, n3)

6.8.2. Parameters

Parameter Description

n1 A numeric value or expression representing the payment amount.

n2 A numeric value or expression representing the interest per period of the investment.

n3 A numeric value or expression representing the total number of payment periods.

The function returns an error if either n1 or n3 is negative or 0. If any parameter is null, the function
returns null.
NOTE: FormCalc follows the IEEE-754 international standard when handling floating point numeric
values. For more information, see Numberliterals.

6.8.3. Examples

The following expressions are examples that use the PV function:

70
Financial Functions 6

Expression Returns

PV(400, 0.10 / 12, 30 * 12) 45580.32799074439. This is the value after 30 years, of a $400 a
month investment growing at 10% annually.

PV(1000, 0.075 / 4, 10 * 4) 58791.96145535981. This is the value after ten years of a $1000 a
month investment growing at 7.5% a quarter.

PV(Payment[0], Int_Rate / This example uses variables in place of actual numeric values or
4, Time) expressions.

6.9. Rate

Returns the compound interest rate per period required for an investment to grow from present to
future value in a given period.
NOTE: Interest rate calculation methods differ from country to country. This function calculates an
interest rate based on U.S. interest rate standards.

6.9.1. Syntax

Rate(n1, n2, n3)

6.9.2. Parameters

Parameter Description

n1 A numeric value or expression representing the future value of the investment.

n2 A numeric value or expression representing the present value of the investment.

n3 A numeric value or expression representing the total number of investment periods.

The function returns an error if any parameter is negative or 0. If any parameter is null, the function
returns null.
NOTE: FormCalc follows the IEEE-754 international standard when handling floating point numeric
values. For more information, see Numberliterals.

71
 Financial Functions

6.9.3. Examples

The following expressions are examples that use the Rate function:

Expression Returns

Rate(12000, 8000, 5) 0.0844717712(or 8.45%), which is the interest rate per

period needed for an $8000 present value to grow to $12,000
in five periods.

Rate(10000, 0.25 * 5000, 4 * 12) 0.04427378243(or 4.43%), which is the interest rate per
month needed for the present value to grow to $10,000 in
four years.

Rate(Target_Value, Pres_Value[*], This example uses variables in place of actual numeric values
Term * 12) or expressions.

6.10. Term

Returns the number of periods needed to reach a given future value from periodic constant
payments into an interest bearing account.
NOTE: Interest rate calculation methods differ from country to country. This function calculates an
interest rate based on U.S. interest rate standards.

6.10.1. Syntax

Term(n1, n2, n3)

6.10.2. Parameters

Parameter Description

n1 A numeric value or expression representing the payment amount made at the end of each period.

n2 A numeric value or expression representing the interest rate per period of the investment.

n3 A numeric value or expression representing the future value of the investment.

The function returns an error if any parameter is negative or 0. If any parameter is null, the function
returns null.

72
Financial Functions 6

NOTE: FormCalc follows the IEEE-754 international standard when handling floating point numeric
values. For more information, see Numberliterals.

6.10.3. Examples

The following expressions are examples that use the Term function:

Expression Returns

Term(475, .05, 1500) 3.00477517728(or roughly 3), which is the number of

periods needed to grow a payment of $475 into $1500, with
an interest rate of 5% per period.

Term(2500, 0.0275 + 0.0025, 5000) 1.97128786369, which is the number of periods

needed to grow payments of $2500 into $5000, with an
interest rate of 3% per period.

Rate(Inv_Value[0], Int_Rate + This example uses variables in place of actual numeric

0.0050, Target_Value) values or expressions. In this case, the first occurrence of
the variableInv_Valueis used as the payment amount,
half a percentage point is added to the
variableInt_Rateto use as the interest rate, and the
variableTarget_Valueis used as the future value of the
investment.

73
 Logical Functions

7. Logical Functions
Logical functions are useful for testing and/or analyzing information to obtain a true or false result.

7.1. Choose

Selects a value from a given set of parameters.

7.1.1. Syntax

Choose(n, s1 [, s2 ...])

7.1.2. Parameters

Parameter Description

n The position of the value you want to select within the set. If this value is not a whole number, the
function roundsndown to the nearest whole value.
The function returns an empty string if either of the following conditions is true:
• nis less than 1.
• nis greater than the number of items in the set.
Ifnis null, the function returns null.

s1 The first value in the set of values.

s2(Optional) Additional values in the set.

7.1.3. Examples

The following expressions are examples that use the Choose function:

Expression Returns

Choose(3, "Taxes", "Price", "Person", Person

"Teller")

74
Logical Functions 7

Expression Returns

Choose(2, 10, 9, 8, 7, 6, 5, 4, 3, 2, 9
1)

Choose(Item_Num[0], Items[*]) Returns the value within the setItemsthat

corresponds to the position defined by the first
occurrence ofItem_Num.

Choose(20/3, "A", "B", "C", "D", "E", F

"F", "G", "H")

7.2. Exists

Determines whether the given parameter is a reference syntax to an existing object.

7.2.1. Syntax

Exists(v)

7.2.2. Parameters

Parameter Description

v A valid reference syntax expression.

Ifvis not a reference syntax, the function returns false (0).

7.2.3. Examples

The following expressions are examples that use the Exists function:

Expression Returns

Exists(Item) True (1) if the objectItemexists and false (0) otherwise.

Exists("hello world") False (0). The string is not a reference syntax.

75
 Logical Functions

Expression Returns

Exists(Invoice.Border.Edge[ True (1) if the objectInvoiceexists and has aBorderproperty, which

1].Color) in turn has at least one Edgeproperty, which in turn has
aColorproperty. Otherwise, the function returns false (0).

7.3. HasValue

Determines whether the given parameter is a reference syntax with a non-null, non-empty, or
non-blank value.

7.3.1. Syntax

HasValue(v)

7.3.2. Parameters

Parameter Description

v A valid reference syntax expression.

Ifvis not a reference syntax, the function returns false (0).

7.3.3. Examples

The following expressions are examples that use the HasValue function.

Expression Returns

HasValue(2) True (1)

HasValue(" ") False (0)

HasValue(Amount[* Error
])

HasValue(Amount[0 Evaluates the first occurrence ofAmountand returns true (1) if it is a non-null,
]) non-empty, or non-blank value.

76
Logical Functions 7

7.4. Oneof

Determines whether the given value is within a set.

7.4.1. Syntax

Oneof(s1, s2 [, s3 ...])

7.4.2. Parameters

Parameter Description

s1 The position of the value you want to select within the set. If this value is not a whole number, the
function roundss1down to the nearest whole value.

s2 The first value in the set of values.

s3(Optional) Additional values in the set.

7.4.3. Examples

The following expressions are examples that use the Oneof function:

Expression Returns

Oneof(3, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1) True (1)

Oneof("John", "Bill", "Gary", "Joan", True (1)

"John", "Lisa")

Oneof(3, 1, 25) False(0)

Oneof("loan", Fields[*]) Verifies whether any occurrence of Fieldshas

a value ofloan.

7.5. Within

Determines whether the given value is within a given range.

77
 Logical Functions

7.5.1. Syntax

Within(s1, s2, s3)

7.5.2. Parameters

Parameter Description

s1 The value to test for.

Ifs1is a number, the ordering comparison is numeric.
Ifs1is not a number, the ordering comparison uses the collating sequence for the current locale.
For more information, see Locales.
Ifs1is null, the function returns null.

s2 The lower bound of the test range.

s3 The upper bound of the test range.

7.5.3. Examples

The following expressions are examples that use the Within function:

Expression Returns

Within("C", "A", "D") True (1)

Within(1.5, 0, 2) True (1)

Within(-1, 0, 2) False (0)

Within($, 1, 10) True (1) if the current value is between 1 and 10.

78
Miscellaneous Functions 8

8. Miscellaneous Functions
Functions in this section do not fit within any other particular function category and are useful in a
variety of applications.

8.1. Eval

Returns the value of a given form calculation.

8.1.1. Syntax

Eval(s)

8.1.2. Parameters

Parameter Description

s A valid string representing an expression or list of expressions.

TheEvalfunction cannot refer to user-defined variables and functions. For example:
var s = "var t = concat(s, ""hello"")"
eval(s)
In this case, theEvalfunction does not recognizes, and so returns an error. Any subsequent functions
that make reference to the variablesalso fail.

8.1.3. Examples

The following expressions are examples that use the Eval function:

Expression Returns

eval("10*3+5*4") 50

eval("hello") error

79
 Miscellaneous Functions

8.2. Null

Returns the null value. The null value means no value.

8.2.1. Definition

Null()

8.2.2. Parameters

None

8.2.3. Examples

The following expressions are examples that use the Null function:

Expression Returns

Null() null

Null() + 5 5

Quantity = Null() Assignsnullto the objectQuantity.

Concat("ABC", Null(), "DEF") ABCDEF

See also Concat.

8.3. Ref

Returns a reference to an existing object.

8.3.1. Definition

Ref(v)

80
Miscellaneous Functions 8

8.3.2. Parameters

Parameters Description

v A valid string representing a reference syntax, property, method, or function.

If the given parameter is null, the function returns the null reference. For all other given parameters,
the function generates an error exception.

8.3.3. Examples

The following expressions are examples that use the Ref function:

Expressions Returns

Ref("10*3+5*4") 10*3+5*4

Ref("hello") hello

8.4. UnitType

Returns the units of a unitspan. A unitspan is a string consisting of a number followed by a unit
name.

8.4.1. Syntax

UnitType(s)

81
 Miscellaneous Functions

8.4.2. Parameters

Parameter Description

s A valid string containing a numeric value and a valid unit of measurement (unitspan). Recognized
units of measurement are:
• in, inches
• mm, millimeters
• cm, centimeters
• pt, points
• pc, picas
• mp, millipoints
Ifsis invalid, the function returnsin.

8.4.3. Examples

The following expressions are examples that use the UnitType function:

Expression Results

UnitType("36 in") in

UnitType("2.54centimeters") cm

UnitType("picas") pc

UnitType("2.cm") cm

UnitType("2.zero cm") in

UnitType("kilometers") in

UnitType(Size[0]) Returns the measurement value of the first occurrence ofSize.

82
Miscellaneous Functions 8

8.5. UnitValue

Returns the numerical value of a measurement with its associated unitspan, after an optional unit
conversion. A unitspan is a string consisting of a number followed by a valid unit of measurement.

8.5.1. Syntax

UnitValue(s1 [, s2 ])

8.5.2. Parameters

Parameters Description

s1 A valid string containing a numeric value and a valid unit of measurement (unitspan). Recognized
units of measurement are:
• in, inches
• mm, millimeters
• cm, centimeters
• pt, picas, points
• mp, millipoints

s2(optional) A string containing a valid unit of measurement. The function converts the unitspan specified
ins1to this new unit of measurement.
If you do not include a value fors2, the function uses the unit of measurement specified ins1.
Ifs2is invalid, the function converts s1into inches.

8.5.3. Examples

The following expressions are examples that use the UnitValue function:

Expression Returns

UnitValue("2in") 2

UnitValue("2in", "cm") 5.08

UnitValue("6", "pt") 432

83
 Miscellaneous Functions

Expression Returns

UnitValue("A", "cm") 0

UnitValue(Size[2], "mp") Returns the measurement value of the third occurrence

ofSizeconverted into millipoints.

UnitValue("5.08cm", 2
"kilograms")

84
String Functions 9

9. String Functions
String functions deal with the manipulation, evaluation, and creation of string values.

9.1. At

Locates the starting character position of a string within another string.

9.1.1. Syntax

At(s1, s2)

9.1.2. Parameters

Parameter Description

s1 The source string.

s2 The search string.

Ifs2is not a part ofs1, the function returns0.
Ifs2is empty, the function returns1.

9.1.3. Examples

The following expressions are examples that use the At function:

Expression Returns

At("ABCDEFGH", "AB") 1

At("ABCDEFGH", "F") 6

At(23412931298471, 29) 5, the first occurrence of29within the source string.

At(Ltrim(Cust_Info[0]), The location of the string555within the first occurrence

"555") ofCust_Info.
See also Ltrim.

85
 String Functions

9.2. Concat

Returns the concatenation of two or more strings.

9.2.1. Syntax

Concat(s1 [, s2 ...])

9.2.2. Parameters

Parameter Description

s1 The first string in the set.

s2(Optional) Additional strings to append to the set.

9.2.3. Examples

The following expressions are examples that use the Concat function:

Expression Returns

Concat("ABC", "DEF") ABCDEF

Concat("Tony", Space(1), "Blue") Tony Blue

See also Space.

Concat("You owe ", You owe One Thousand One Hundred Fifty-four
WordNum(1154.67, 2), ".") Dollars And Sixty-seven Cents.
See also WordNum.

9.3. Decode

Returns the decoded version of a given string.

86
String Functions 9

9.3.1. Syntax

Decode(s1 [, s2 ])

9.3.2. Parameters

Parameter Description

s1 The string to decode.

s2(Optional) A string identifying the type of decoding to perform. The following strings are valid decoding
strings:
• url (URL decoding)
• html (HTML decoding)
• xml (XML decoding)
If you do not include a value fors2, the function uses URL decoding.

9.3.3. Examples

The following expressions are examples that use the Decode function:

Expression Returns

Decode("&AElig;&Aacute;&Acirc;&Aacute; ÆÁÂÁÂ
&Acirc;", "html")

Decode("~!@#$%^&amp;*()_+|`{&quot;}[] ~!@#$%^&*()_+|`{""}[]<>?,./;':
&lt;&gt;?,./;&apos;:", "xml")

9.4. Encode

Returns the encoded version of a given string.

9.4.1. Syntax

Encode(s1 [, s2 ])

87
 String Functions

9.4.2. Parameters

Parameter Description

s1 The string to encode.

s2(Optional) A string identifying the type of encoding to perform. The following strings are valid encoding
strings:
• url (URL encoding)
• html (HTML encoding)
• xml (XML encoding)
If you do not include a value fors2, the function uses URL encoding.

9.4.3. Examples

The following expressions are examples that use the Encode function:

Expression Returns

Encode("""hello, world!""", "url") %22hello,%20world!%22

Encode("ÁÂÃÄÅÆ", "html") &#xc1;&#Xc2;&#Xc3;&#xc4;&#xc5;&#xc6;

9.5. Format

Formats the given data according to the specified picture format string.

9.5.1. Syntax

Format(s1, s2 [, s3 ...])

88
String Functions 9

9.5.2. Parameters

Parameter Description

s1 The picture format string, which may be a locale-sensitive date or time format.
See Locales.

s2 The source data to format.

For date picture formats, the source data must be either an ISO date-time string or an ISO date
string in one of two formats:
• YYYY[MM[DD]]
• YYYY[-MM[-DD]]
• HH[MM[SS[.FFF][z]]]
• HH[MM[SS[.FFF][+HH[MM]]]]
• HH[MM[SS[.FFF][-HH[MM]]]]
• HH[:MM[:SS[.FFF][z]
• HH[:MM[:SS[.FFF][-HH[:MM]]]]
• HH[:MM[:SS[.FFF][+HH[:MM]]]]
For time picture formats, the source data must be either an ISO date-time string or an ISO time
string in one of the following formats:
• HH[MM[SS[.FFF][z]]]
• HH[MM[SS[.FFF][+HH[MM]]]]
• HH[MM[SS[.FFF][-HH[MM]]]]
• HH[:MM[:SS[.FFF][z]
• HH[:MM[:SS[.FFF][-HH[:MM]]]]
• HH[:MM[:SS[.FFF][+HH[:MM]]]]
For date-time picture formats, the source data must be an ISO date-time string.
For numeric picture formats, the source data must be numeric.
For text picture formats, the source data must be textual.
For compound picture formats, the number of source data arguments must match the number of
subelements in the picture.

s3(Optional) Additional source data to format.

89
 String Functions

9.5.3. Examples

The following expressions are examples that use the Format function:

Expression Returns

Format("MMM D, YYYY", Sep 1, 2002

"20020901")

Format("$9,999,999.99", $1,234,567.89 in the U.S. and1 234 567,89Euros in

1234567.89) France.

9.6. Left

Extracts a specified number of characters from a string, starting with the first character on the left.

9.6.1. Syntax

Left(s, n)

9.6.2. Parameters

Parameter Description

s The string to extract from.

n The number of characters to extract.

If the number of characters to extract is greater than the length of the string, the function returns the
whole string.
If the number of characters to extract is 0 or less, the function returns the empty string.

9.6.3. Examples

The following expressions are examples that use the Left function:

90
String Functions 9

Expression Returns

Left("ABCDEFGH", 3) ABC

Left("Tony Blue", 5) "Tony "

Left(Telephone[0], 3) The first three characters of the first occurrence ofTelephone.

Left(Rtrim(Last_Name), The first three characters ofLast_Name.

3) See also Rtrim.

9.7. Len

Returns the number of characters in a given string.

9.7.1. Syntax

Len(s)

9.7.2. Parameters

Parameter Description

s The string to examine.

9.7.3. Examples

The following expressions are examples that use the Len function:

Expression Returns

Len("ABDCEFGH") 8

Len(4) 1

Len(Str(4.532, 6, 4)) 6
See also Str.

91
 String Functions

Expression Returns

Len(Amount[*]) The number of characters in the first occurrence ofAmount.

9.8. Lower

Converts all uppercase characters within a specified string to lowercase characters.

9.8.1. Syntax

Lower(s, [, k ])

9.8.2. Parameters

Parameter Description

s The string to convert.

k(Optional) A string representing a valid locale. If you do not include a value for k, the function uses the
ambient locale.
See Locales.
This function only converts the Unicode characters U+41 through U+5A (of the ASCII character
set) as well as the characters U+FF21 through U+FF3A (of the fullwidth character set)

9.8.3. Examples

The following expressions are examples that use the Lower function:

Expression Returns

Lower("ABC") abc

Lower("21 Main St.") 21 main st.

Lower(15) 15

Lower(Address[0]) This example converts the first occurrence ofAddressto all lowercase letters.

92
String Functions 9

9.9. Ltrim

Returns a string with all leading white space characters removed.

White space characters include the ASCII space, horizontal tab, line feed, vertical tab, form feed,
carriage return, and the Unicode space characters (Unicode category Zs).

9.9.1. Syntax

Ltrim(s)

9.9.2. Parameters

Parameter Description

s The string to trim.

9.9.3. Examples

The following expressions are examples that use the Ltrim function:

Expression Returns

Ltrim(" ABCD") "ABCD"

Ltrim(Rtrim(" Tony Blue ")) "Tony Blue"

See also Rtrim.

Ltrim(Address[0]) Removes any leading white space from the first

occurrence ofAddress.

9.10. Parse

Analyzes the given data according to the given picture format.

Parsing data successfully results in one of the following values:
• Date picture format: An ISO date string of the form YYYY-MM-DD.

93
 String Functions

• Time picture format: An ISO time string of the form HH:MM:SS.

• Date-time picture format: An ISO date-time string of the form YYYY-MM-DDTHH:MM:SS.
• Numeric picture format: A number.
• Text pictures: Text.

9.10.1. Syntax

Parse(s1, s2 )

9.10.2. Parameters

Parameter Description

s1 A valid date or time picture format string.

For more information on date and time formats, see Dateand Time Functions.

s2 The string data to parse.

9.10.3. Examples

The following expressions are examples that use the Parse function:

Expression Returns

Parse("MMM D, YYYY", "Sep 1, 2002") 2002-09-01

Parse("$9,999,999.99", "$1,234,567.89") 1234567.89in the U.S.

9.11. Replace

Replaces all occurrences of one string with another within a specified string.

9.11.1. Syntax

Replace(s1, s2 [, s3 ])

94
String Functions 9

9.11.2. Parameters

Parameter Description

s1 A source string.

s2 The string to replace.

s3(Optional) The replacement string.

If you do not include a value fors3, or ifs3is null, the function uses an empty string.

9.11.3. Examples

The following expressions are examples that use the Replace function:

Expression Returns

Replace("Tony Blue", "Tony", Chris Blue

"Chris")

Replace("ABCDEFGH", "D") ABCEFGH

Replace("ABCDEFGH", "d") ABCDEFGH

Replace(Comments[0], "recieve", Correctly updates the spelling of the wordreceivein the

"receive") first occurrence ofComments.

9.12. Right

Extracts a number of characters from a given string, beginning with the last character on the right.

9.12.1. Syntax

Right(s, n )

95
 String Functions

9.12.2. Parameters

Parameter Description

s The string to extract.

n The number of characters to extract.

Ifnis greater than the length of the string, the function returns the whole string.
Ifnis 0 or less, the function returns an empty string.

9.12.3. Examples

The following expressions are examples that use the Right function:

Expression Returns

Right("ABCDEFGH", 3) FGH

Right("Tony Blue", 5) " Blue"

Right(Telephone[0], 7) The last seven characters of the first occurrence ofTelephone.

Right(Rtrim(CreditCard_ The last four characters ofCreditCard_Num.

Num), 4) See also Rtrim.

9.13. Rtrim

Returns a string with all trailing white space characters removed.

White space characters include the ASCII space, horizontal tab, line feed, vertical tab, form feed,
carriage return, and the Unicode space characters (Unicode category Zs).

9.13.1. Syntax

Rtrim(s )

96
String Functions 9

9.13.2. Parameters

Parameter Description

s The string to trim.

9.13.3. Examples

The following expressions are examples that use the Rtrim function:

Expression Returns

Rtrim("ABCD ") "ABCD"

Rtrim("Tony Blue ") "Tony Blue"

Rtrim(Address[0]) Removes any trailing white space from the first occurrence
ofAddress.

9.14. Space

Returns a string consisting of a given number of blank spaces.

9.14.1. Syntax

Space(n )

9.14.2. Parameters

Parameter Description

n The number of blank spaces.

97
 String Functions

9.14.3. Examples

The following expressions are examples that use the Space function:

Expression Returns

Space(5) " "

Space(Max(Amount[*])) A blank string with as many characters as the value of the largest
occurrence ofAmount.
See also Max.

Concat("Tony", Space(1), Tony Blue

"Blue")

9.15. Str

Converts a number to a character string. FormCalc formats the result to the specified width and
rounds to the specified number of decimal places.

9.15.1. Syntax

Str(n1 [, n2 [, n3 ]])

9.15.2. Parameters

Parameter Description

n1 The number to convert.

n2(Optional) The maximum width of the string. If you do not include a value forn2, the function uses a value
of10as the default width.
If the resulting string is longer thann2, the function returns a string of * (asterisk) characters of
the width specified byn2.

n3(Optional) The number of digits to appear after the decimal point. If you do not include a value forn3, the
function uses 0 as the default precision.

98
String Functions 9

9.15.3. Examples

The following expressions are examples that use the Str function:

Expression Returns

Str(2.456) " 2"

Str(4.532, 6, 4) 4.5320

Str(234.458, 4) " 234"

Str(31.2345, 4, 2) ****

Str(Max(Amount[*]), 6, Converts the largest occurrence ofAmountto a six-character string with two
2) decimal places.
See also Max.

9.16. Stuff

Inserts a string into another string.

9.16.1. Syntax

Stuff(s1, n1, n2 [, s2 ])

9.16.2. Parameters

Parameter Description

s1 The source string.

n1 The position ins1to insert the new string s2.

Ifn1is less than one, the function assumes the first character position. Ifn1is greater than length
ofs1, the function assumes the last character position.

n2 The number of characters to delete from strings1, starting at character position n1.
Ifn2is less than or equal to 0, the function assumes 0 characters.

s2(Optional) The string to insert intos1.

If you do not include a value fors2, the function uses the empty string.

99
 String Functions

9.16.3. Examples

The following expressions are examples that use the Stuff function:

Expression Returns

Stuff("TonyBlue", 5, 0, " ") Tony Blue

Stuff("ABCDEFGH", 4, 2) ABCFGH

Stuff(Address[0], Len(Address[0]), This adds the wordStreetonto the end of the first
0, "Street") occurrence ofAddress.
See also Len.

Stuff("[email protected]", 0, cc:[email protected]
0, "cc:"

9.17. Substr

Extracts a portion of a given string.

9.17.1. Syntax

Substr(s1, n1, n2 )

9.17.2. Parameters

Parameter Description

s1 The source string.

n1 The position in string s1 to start extracting.

Ifn1 is less than one, the function assumes the first character position. Ifn1is greater than length
ofs1, the function assumes the last character position.

n2 The number of characters to extract.

Ifn2is less than or equal to 0, FormCalc returns an empty string. Ifn1 + n2is greater than the
length of s1, the function returns the substring starting at positionn1to the end ofs1.

100
String Functions 9

9.17.3. Examples

The following expressions are examples that use the Substr function:

Expression Returns

Substr("ABCDEFG", 3, 4) CDEF

Substr(3214, 2, 1) 2

Substr(Last_Name[0], 1, 3) Returns the first three characters from the first occurrence
ofLast_Name.

Substr("ABCDEFG", 5, 0) ""

Substr("21 Waterloo St.", 4, Water

5)

9.18. Uuid

Returns a Universally Unique Identifier (UUID) string to use as an identification method.

9.18.1. Syntax

Uuid([n ])

9.18.2. Parameters

Parameter Description

n A number identifying the format of the UUID string. Valid numbers are:
• 0 (default value): UUID string only contains hex octets.
• 1: UUID string contains dash characters separating the sequences of hex octets
at fixed positions.
If you do not include a value for n, the function uses the default value.

101
 String Functions

9.18.3. Examples

The following expressions are examples of the Uuid function:

Expression Returns

Uuid() A value such as3c3400001037be8996c400a0c9c86dd5

Uuid(0) A value such as3c3400001037be8996c400a0c9c86dd5

Uuid(1) A value such as1a3ac000-3dde-f352-96c4-00a0c9c86dd5

Uuid(7) A value such as1a3ac000-3dde-f352-96c4-00a0c9c86dd5

9.19. Upper

Converts all lowercase characters within a string to uppercase.

9.19.1. Syntax

Upper(s [, k ])

9.19.2. Parameters

Parameter Description

s The string to convert.

See Locales.

k(Optional) A string representing a valid locale. If you do not include a value for k, the ambient locale is used.
This function only converts the Unicode characters U+61 through U+7A (of the ASCII character
set) as well as the characters U+FF41 through U+FF5A (of the fullwidth character set).

9.19.3. Examples

The following expressions are examples that use the Upper function:

102
String Functions 9

Expression Returns

Upper("abc") ABC

Upper("21 Main St.") 21 MAIN ST.

Upper(15) 15

Upper(Address[0]) This example converts the first occurrence ofAddressto all uppercase letters.

9.20. WordNum
Returns the English text equivalent of a given number.

9.20.1. Syntax

WordNum(n1 [, n2 [, k ]])

9.20.2. Parameters

Parameter Description

n1 The number to convert.

If any of the following statements is true, the function returns * (asterisk) characters to indicate an
error:
• n1is not a number.
• The integral value ofn1is negative.
• The integral value ofn1is greater than 922,337,203,685,477,550.

103
 String Functions

Parameter Description

n2(Optional) A number identifying the formatting option. Valid numbers are:

• 0 (default value): The number is converted into text representing the simple
number.
• 1: The number is converted into text representing the monetary value with
no fractional digits.
• 2: The number is converted into text representing the monetary value with
fractional digits.
If you do not include a value forn2, the function uses the default value (0).

k(Optional) A string representing a valid locale. If you do not include a value fork, the function uses the
ambient locale.
See Locales.
As of this release, it is not possible to specify a locale identifier other than English for this
function.

9.20.3. Examples

The following expressions are examples that use the WordNum function.

Expression Returns

WordNum(123.45) One Hundred and Twenty-three Dollars

WordNum(123.45, 1) One Hundred and Twenty-three Dollars

WordNum(1154.67, 2) One Thousand One Hundred Fifty-four Dollars And

Sixty-seven Cents

WordNum(43, 2) Forty-three Dollars And Zero Cents

WordNum(Amount[0], 2) This example uses the first occurrence ofAmountas the conversion number.

104
URL Functions 10

10. URL Functions

URL functions deal with the sending and receiving of information, including content types and
encoding data, to any accessible URL locations.

10.1. Get

Downloads the contents of the given URL.

NOTE: Adobe® Acrobat®® and Adobe® Reader®® cannot verify that the form is certified until after the
initialize event initiates. To use the Get function on certified forms prior to the form rendering,
use the docReady event.

10.1.1. Syntax

Get(s)

10.1.2. Parameters

Parameter Description

s The URL to download.

If the function is unable to download the URL, it returns an error.

10.1.3. Examples

The following expressions are examples that use the Get function.

Expression Returns

Get("http://www.myweb.com/data/mydata.xml") XML data taken from the specified file.

Get("ftp://ftp.gnu.org/gnu/GPL") The contents of the GNU Public License.

Get("http://intranet?sql=SELECT+*+FROM+ The results of an SQL query to the specified

projects+FOR+XML+AUTO,+ELEMENTS") website.

105
 URL Functions

10.2. Post

Posts the given data to the specified URL.

NOTE: Acrobat and Adobe Reader cannot verify that the form is certified until after the initialize
event initiates. To use the Post function on certified forms prior to the form rendering, use the
docReady event.

10.2.1. Syntax

Post(s1, s2 [, s3 [, s4 [, s5 ]]])

10.2.2. Parameters

Parameter Description

s1 The URL to post to.

s2 The data to post.

If the function cannot post the data, it returns an error.

s3(Optional) A string containing the content type of the data to post. Here are valid content types:
• application/octet-stream (default value)
• text/html
• text/xml
• text/plain
• multipart/form-data
• application/x-www-form-urlencoded
• Any other valid MIME type
If you do not include a value fors3, the function sets the content type to the default value. The
application ensures that the data to post uses the correct format according to the specified content
type.

106
URL Functions 10

Parameter Description

s4(Optional) A string containing the name of the code page used to encode the data. Here are valid code page
names:
• UTF-8 (default value)
• UTF-16
• ISO-8859-1
• Any character encoding listed by the Internet Assigned Numbers Authority
(IANA)
If you do not include a value fors4, the function sets the code page to the default value. The
application ensures that encoding of the data to post matches the specified code page.

s5(Optional) A string containing any additional HTTP headers to be included with the posting of the data.
If you do not include a value fors5, the function does not include an additional HTTP header in the
post.
SOAP servers usually require a SOAPAction header when posting to them.

10.2.3. Examples

The following expressions are examples that use the Post function:

Expression Returns

Post("http://tools_build/scripts/jfech Posts some URL encoded login data to a server and

o.cgi", returns that server's acknowledgement page.
"user=joe&passwd=xxxxx&date=27/08/2002
",
"application/x-www-form-urlencoded")

Post("http://www.nanonull.com/TimeServ Posts a SOAP request for the local time to some server,
ice/ expecting an XML response back.
TimeService.asmx/getLocalTime", "<?xml
version='1.0'
encoding='UTF-8'?><soap:Envelope><soap
:Body>
<getLocalTime/></soap:Body>
</soap:Envelope>", "text/xml",
"utf-8",
"http://www.Nanonull.com/TimeService/g
etLocalTime")

107
 URL Functions

10.3. Put

Uploads the given data to the specified URL.

NOTE: Acrobat and Adobe Reader cannot verify that the form is certified until after the initialize
event initiates. To use the Put function on certified forms prior to the form rendering, use the
docReady event.

10.3.1. Syntax

Put(s1, s2 [, s3 ])

10.3.2. Parameters

Parameter Description

s1 The URL to upload.

s2 The data to upload.

If the function is unable to upload the data, it returns an error.

s3(Optional A string containing the name of the code page used to encode the data. Here are valid code page
) names:
• UTF-8 (default value)
• UTF-16
• ISO8859-1
• Any character encoding listed by the Internet Assigned Numbers Authority
(IANA)
If you do not include a value fors3, the function sets the code page to the default value. The
application ensures that encoding of the data to upload matches the specified code page.

10.3.3. Examples

The following expression is an example that use the Put function:

108
URL Functions 10

Expression Returns

Put("ftp://www.example.com/pub/fubu. Nothing if the FTP server has permitted the user to upload
xml", some XML data to thepub/fubu.xmlfile. Otherwise,
"<?xml version='1.0' this function returns an error.
encoding='UTF-8'?><msg>hello
world!</msg>")

NOTE: This example only works in the server environment and not in Acrobat or Adobe Reader. For
forms displayed in Acrobat and Adobe Reader, use the HTTP, HTTPS, and FILE protocols.

109