Following are brief descriptions of the functions that convert expressions
from one data type to another. For more detailed information about a specific
function (such as usage and syntax), click the function name.
Determines whether the specified expression is a valid value
that can be converted to the specified simple data type.
convert
This function converts an expression from one supported data type to
another. Use the following syntax:
convert (source_expr, type_name)
where:
source_expr
is an expression of any supported data type. This expression
will be converted to the data type specified in type_name.
type_name
is the data type to which source_expr will be converted. Valid
entries are float, float[ ], integer, integer[ ], string, string[ ],
boolean, boolean[ ], time, and time[ ].
Note that if type_name is followed by square brackets ([ ]),
then source_expr must also be an array. Each element in the array
will be converted to type_name by the rules that apply for the
simple data type.
The results of the convert function vary depending on the data types
of source_exp and type_name. For summary information, select the data
type of source_expr from the list below.
NOTE Be
aware that using the convert function with certain data type combinations
results in syntax errors. For example, it is illogical to convert a time
data type to a boolean data type, so a syntax error occurs. As necessary,
use the is_valid function to verify an expression’s
type before using that expression in a convert function
Convert from boolean
If the source_expr is of type boolean, the results of the convert function
are as follows.
Convert from boolean to...
Results
boolean
No change.
float
If the boolean expression is true, the result is 1; if the boolean
expression is false, the result is 0.
integer
If the boolean expression is true, the result is 1; if the boolean
expression is false, the result is 0.
string
If the boolean expression is true, the result is "true";
if the boolean expression is false, the result is "false".
time
Syntax error.
Convert from float
If the source_expr is of type float, the results of the convert function
are as follows.
Convert from float to...
Results
boolean
If source_expr = 0, the result is false; if source_expr = 1,
the result is true.
If source_expr <> 0 or 1, a syntax error results.
float
No change.
integer
Converts the integer part of the source_expr (that is, truncates
all numbers to the right of the decimal point). An error occurs
if the result is not within the range for integers—see Integer.
string
Results in a string of numeric characters representing the float.
time
Uses the integer part of the source_expr as the number of seconds
to add to 1/1/1970 00:00:00 UTC (Coordinated Universal Time);
returns the new time.
UTC (Coordinated Universal Time)Formerly known as GMT (Greenwich Mean Time), UTC is the standard world-wide reference time zone.
For example, convert (5.3, time) returns 1/1/1970 00:00:05.
Convert from integer
If the source_expr is of type integer, the results of the convert function
are as follows.
Convert from integer to...
Results
boolean
If source_expr = 0, the result is false; if source_expr = 1,
the result is true.
If source_expr <> 0 or 1, a syntax error results.
float
Results in the equivalent float value.
integer
No change.
string
Results in a string of numeric characters representing the integer.
time
Uses the source_expr as the number of seconds to add to 1/1/1970
00:00:00 UTC (Coordinated Universal Time); returns the new time.
For example, convert (5, time) returns 1/1/1970 00:00:05.
Convert from string
If the source_expr is of type string, the results of the convert function
are as follows.
Convert from string to...
Results
boolean
Syntax error, unless source_expr - "true" or source_expr
= "false". (Any combination of upper and lower case
is acceptable.)
float
Syntax error, unless source_expr is a legitimate representation
of a float value.
integer
Syntax error, unless source_expr is a legitimate representation
of an integer value.
string
No change.
time
Syntax error, unless source_expr is a legitimate representation
of a time value and uses the format specified in the date/time
mask for the Process Engine.
See the Help for Process Engine
Administration
for information about the date/time mask.
Convert from time
If the source_expr is of type time, the results of the convert function
are as follows.
Convert from time to...
Results
boolean
Syntax error.
float
Returns the number of seconds between the current system time
and 1/1/1970 00:00:00 UTC (Coordinated Universal Time).
For example, if SysTime = 1/1/1970 00:00:28 UTC, convert (SysTime,
float) returns 28.
If the current system time is set to a time zone other than UTC,
the convert function makes the necessary adjustment. For example,
there is an 8-hour difference between PST and UTC; if SysTime
= 1/1/1970 00:00:28 PST (Pacific Standard Time) and the local
time zone is Pacific Standard Time, then convert(SysTime, float)
returns 28828—
8(hours) * 60(minutes) *60(seconds) + 28(seconds)
integer
Returns the number of seconds between the current system time
and 1/1/1970 00:00:00 UTC (Coordinated Universal Time).
For example, if SysTime = 1/1/1970 00:00:28 UTC, convert (SysTime,
integer) returns 28.
If the current system time is set to a time zone other than UTC,
the convert function makes the necessary adjustment. For example,
there is an 8-hour difference between PST and UTC; if SysTime
= 1/1/1970 00:00:28 PST (Pacific Standard Time) and the local
time zone is Pacific Standard Time, then convert(SysTime, integer)
returns 28828—
8(hours) * 60(minutes) *60(seconds) + 28(seconds)
string
Results in a string representation of the source_expr. Note that
this string uses the format specified in the date/time mask for
the Process Engine.
See the Help for Process Engine
Administration
for information about the date/time mask.
time
No change
numbertostring
This function converts a float or integer expression to a string expression,
using the format you specify. Use this function when you want to display
a number in a certain format (for example, $1,000,000). You can also use
the numbertostring function to round off numbers.
Use the following syntax:
numbertostring
(num_exp{, num_mask}opt)
where:
num_exp
is an expression of type float or type integer.
num_mask
is a numeric mask that determines
the format of the numbertostring function’s output.
While optional, note that if you do not enter a numeric mask,
the numbertostring function is equivalent to the convert function.
Numeric mask
A numeric mask is a template used to format the output of the numbertostring
function. A numeric mask is a string expression containing any valid combination
of the following components.
Component
Meaning
+ (plus)
When the first or last component in the mask, displays the sign
of the number.
When in a position other than first or last, the plus sign will
be inserted in the output string exactly where you put it in the
mask. For example:
numbertostring (12345, "###+##")
outputs 123+45
- (minus)
When the first or last component in the mask, displays a negative
sign if the number is negative, or displays a space if the number
is positive.
When in a position other than first or last, the minus sign will
be inserted in the output string exactly where you put it in the
mask. For example:
numbertostring (123456789, "###-##-####")
outputs 123-45-6789
# (number sign)
Displays a digit if it is significant. When the mask contains
more #s than there are significant digits, the rightmost #s receive
digits first and excess #s are filled with blanks.
0 (zero)
Displays a digit whether or not it is significant; leading and/or
trailing zeros can result.
. (decimal)
Determines where the decimal point goes. If not specified, the
decimal point is assumed to be at the right end of the mask. The
number is rounded off to fit into the mask. Only one decimal point
is allowed in a mask.
Numeric mask samples
Below is the resulting output when the numbertostring function converts
the following numbers: 0, +29, -3344, and 77.88369. The output is formatted
according to the numeric masks shown.
NOTE If
the mask is too small for the number, an error occurs. The mask is too
small if there are too few #s or 0s to the left of the decimal point.
For example, the mask ## is inadequate for the number 300.
Mask
0
+29
-3344
77.88369
0000
0000
0029
3344
0078
####
29
3344
78
$#,###
$
$29
$3,344
$78
+####
+
+29
-3344
+78
-####
29
-3344
78
####+
+
29+
3344-
78+
####-
29
3344-
78
##.##
.
29.
Runtime error
77.88
Rounding off numbers
To round off a number, use the numbertostring function and the appropriate
numeric mask. Each number is rounded off to fit the last place in the
mask. The following example rounds a number off to thousandths. In the
example, Number1 is the name of an expression of type float.
numbertostring (Number1, "#,###.###")
If Number1 = 3344.7788, the resulting output is:
3,344.779
is_valid
This function determines whether the specified expression is a valid
value that can be converted to the specified simple data type. This function
returns the boolean value true if the expression is valid; otherwise,
the function returns a value of false. It can be useful to verify an expression's
type via the is_valid function before using that expression in a convert
function. Use the following syntax:
is_valid (expr, type)
where:
expr
is any expression.
type
is a simple data type (boolean, float, integer, string, time).
Following are two examples using string expressions. The first example
returns true, the second example returns false. In the first example,
str = "true".
is_valid (str, boolean)
is_valid ("1.2.3", float)
The example below verifies whether the specified float expression is
valid for conversion to type integer; this example returns false because
the float value is out of the range of valid integer values.