|
Developing Business Rules
Ensemble Utility Functions
|
|
This appendix describes the Ensemble
utility functions that you can use in business rules and DTL data transformations. These include mathematical or string processing functions such as you may be accustomed to using in other programming languages. This appendix contains the following topics:
The following lists the utility functions built into Ensemble.
Note:
For boolean values, 1 indicates true and 0 indicates false.
Returns 1 (true) if
val contains the substring
str; otherwise 0 (false).
ConvertDateTime (
val,
in,
out,
file)
The default for
in and
out is %Q. Any %f elements in the
out argument are replaced with the
file string. If
val does not match the
in format,
out is ignored and
val is returned unchanged.
Returns a string representing a date/time value in the given format. The default format is ODBC format (%Q) in the server's local timezone.
Returns 1 (true) if
val does not contain the substring
str.
DoesNotIntersectList(
val,
items,
srcsep,
targetsep)
Returns 1 (true) if no item in the given source list (
val) appears in the target list (
items). For details on the arguments, see IntersectsList.
DoesNotStartWith(
val,
str)
Returns 1 (true) if
val does not start with the substring
str.
The Exists function provides a way to predict the results of the Lookup function. Exists returns 1 (true) if
val is a key defined within the table identified by
tab; otherwise it returns 0 (false).
If the argument
val evaluates to 1 (true), the If function returns the string value of its
true argument; otherwise it returns the string value of its
false argument.
Returns 1 (true) if
val is found in the comma-delimited string
items.
Returns 1 (true) if
val is found in the identified
file.
The function InFileColumn can have as many as 8 arguments. The full function signature is:
InFileColumn returns 1 (true) if
val is in the specified column in a table-formatted text
file. Arguments are as follows:
-
val (required) is the value.
-
file (required) is the text file.
-
-
-
-
-
-
Default
stripPadChars consists of a blank space followed by ASCII 9.
Returns 1 (true) if any item in the given source list (
val) appears in the target list (
items). The arguments
srcsep and
targetsep specify the list separators in the source and target lists respectively; for each of these, the default is
"><", which means that the lists are assumed to have the form
"<item1><item2><item3>"
if the target list has only a single item, this function is essentially the same as the Contains function. If the source list has only a single item, this function is essentially the same as the In function.
Returns the length of the given string. If you specify
delimiter, this function returns the number of substrings based on this delimiter.
Returns 1 (true) if the given value (
string) satisfies a SQL Like comparison with the given pattern string (
pattern). In SQL Like patterns, % matches 0 or more characters, and _ matches any single character. Note that an escape character can be specified by appending "%%" to the pattern, e.g. "#%SYSVAR_#_%%%#" to match any value string that starts with "%SYSVAR" followed by any single character, an underscore, and anything else.
The
Lookup() function searches for the key value specified by
keyvalue in the table specified by
table and returns its associated value. This returned value is equivalent to the following global:
If the key is not found in the table, the Lookup function returns the default value specified by the
default parameter. The
default parameter is optional, so if it is not specified and Lookup does not find a matching key, it returns an empty string. An exception is that if either the key value or the lookup table is empty, the
Lookup() function returns either the default value or the empty string depending on the value of the
defaultOnEmptyInput parameter as described in the following table. The default value of the
defaultOnEmptyInput parameter is 0 for compatibility with previous versions of Ensemble.
The
Exists() function returns true if a
Lookup() function with the same parameters would find the key value in the lookup table.
Returns the largest of a list of up to 8 values. List entries are separated by commas.
Returns the smallest of a list of up to 8 values. List entries are separated by commas.
Returns 0 (false) if
val is 1 (true); 1 (true) if
val is 0 (false).
Returns 1 (true) if
val is not found in the comma-delimited string
items.
Returns 1 (true) if
val is not found in the identified
file.
Returns 1 (true) if the given value (
string) does not satisfy a SQL Like comparison with the given pattern string (
pattern). See Like.
Reads the input string
val. Adds enough instances of
char to widen the string to
width characters. If
width is a positive value, the padding is appended to the right-hand side of the
val string. If
width is a negative value, the padding is prepended to the left-hand side of the
val string.
If the delimiter character
char is present in the string
val, this separates the string into pieces. If there are multiple pieces in the string,
from and
to specify which range of these pieces to return, starting at 1. If multiple pieces are returned, the delimiter in the return string is the same as the delimiter in the input string. For example:
ReplaceStr(
val,
find,
repl)
Reads the input string
val. Replaces any occurrences of string
find with the string
repl, and returns the resulting string.
Note:
Use ReplaceStr instead of the Replace function, which has been deprecated.
Returns
val rounded off to
n digits after the decimal point. If
n is not provided (that is,
Round(val)) the function drops the fractional portion of the number and rounds it to the decimal point, producing an integer.
Evaluates the rule specified in the
rulename with the given
context object and the given
activity label for the Rule Log and returns the value.
Evaluates the state of the given
ScheduleSpec string, named Schedule or Rule at the moment given by
ODBCDateTime. If
ScheduleSpec begins with '@' it is a Schedule name or Rule name, otherwise a raw Schedule string. If
ODBCDateTime is blank, the evaluation is done for the current time.
Returns 1 (true) if
val starts with the substring
str.
Reads the input string
val. Removes any characters matching the categories specified in the
act template and the
rem string, while retaining any characters found in the
keep string. Returns the resulting string. For details and examples, see the
$ZSTRIP function in the
Caché ObjectScript Reference.
Returns a substring of a string
str, starting at numeric position
n and continuing until numeric position
m. The number 1 indicates the first character in the string. If
m is not provided (that is,
SubString(str,n)) the function returns the substring from position
n to the end of the string.
Returns the string
str converted to lowercase.
Returns the string
str converted to uppercase.
Reads the input string
val. Translates each occurrence of a character in string
in to the character at the corresponding position in string
out, and returns the resulting string.
Syntax to Invoke a Function
When you reference an Ensemble function in a business rule or a DTL data transformation, the syntax must include parentheses. It must also include any input parameters, such as the numeric values for the mathematical functions Min, Max, or Round. If there are no input values for the function, then the open and close parentheses must be present, but empty.
The following are examples of valid function syntax:
If the value input to any function is a string that starts with a number, nonnumeric characters in the string are dropped and the numeric portion is used. The string
"3a" is treated like the number
3, so the function
Min("3a","2OfThem") returns the value
2. A string that begins with a nonnumeric character such as
"a123" has the numeric value
0.
The business rule syntax for utility functions differs from the DTL syntax in the following significant way:
-
Business rules reference the utility functions simply by name:
-
DTL uses two leading dots immediately before the function name, as if the function were a method:
The following DTL data transformation uses a utility function called
ToUpper() to convert a string to all uppercase characters. The <assign> statement references
ToUpper() using double-dot syntax, as if it were a method in the class:
Class User.NewDTL1 Extends Ens.DataTransformDTL
{
XData DTL
{
<?xml version="1.0" ?>
<transform targetClass='Demo.Loan.Msg.Approval'
sourceClass='Demo.Loan.Msg.Approval'
create='new' language='objectscript'>
<assign property='target.BankName'
value='..ToUpper(source.BankName)' action='set'/>
<trace value='Changed all lowercase letters to uppercase!' />
</transform>
}
}