IBM FileNet P8, Version 5.2.1            

Data type conversion functions

This section contains brief descriptions of the functions that convert expressions from one data type to another.

Table 1. Table of functions that convert one data type to another
Function What it does
convert Converts an expression from one supported data type to another.
numbertostring Converts an integer or float expression to a string expression, using a specified mask.
stringtotime Converts a string expression to a time expression, using a specified mask.
timetostring Converts a time expression to a string expression, using a specified mask.
is_valid 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:
Table 2. Parameters and description for convert function
Parameter Description
source_expr An expression of any supported data type. This expression is converted to the data type specified in type_name.
type_name

The data type to which source_expr is 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 is 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.

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.

Table 3. Results of the convert function when the data type is of type Boolean
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.

Table 4. Results of the convert function when the data type is of type float
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.
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.
Table 5. Results of the convert function when the data type is of type integer
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.

Table 6. Results of the convert function when the data type is of type string
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 workflow system.

Convert from time

If the source_expr is of type time, the results of the convert function are as follows.

Table 7. Results of the convert function when the data type is of type time
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 Pacific Standard Time (PST) and UTC; if SysTime = 1/1/1970 00:00:28 PST and the local time zone is PST, then convert(SysTime, float) returns 28828.0.

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 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 workflow system.

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:
Parameter Description
num_exp An expression of type float or type integer.
num_mask

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 is 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 is 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; both leading and 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:
Table 8. Parameters and description for is_valid function
Parameter Description
expr Any expression.
type 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.
is_valid (1e20, integer)


Last updated: October 2015
bpfe005.htm

© Copyright IBM Corporation 2015.