Utility Functions for Use in Productions

This appendix describes the InterSystems IRIS® 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.

To define your own functions, see “Defining Custom Utility Functions” in Developing Productions.

Built-in Functions

The following lists the utility functions built into InterSystems IRIS.

Note:

For boolean values, 1 indicates true and 0 indicates false.

Contains(val,str)

Returns 1 (true) if val contains the substring str; otherwise 0 (false).

ConvertDateTime (val,in,out,file)

Reads the input string val as a time stamp in in format, and returns the same value converted to a time stamp in out format. See “Time Stamp Specifications for Filenames” in Configuring Productions.

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.

CurrentDateTime(format)

Returns a string representing a date/time value in the given format. For a list of possible formats, see the Date and Time Expansion section of the class reference for the FormatDateTimeOpens in a new tab method. For example, CurrentDateTime("%H") returns the current hour in 24–hour format as a 2–digit number. The default format is ODBC format (%Q) in the server's local timezone.

DoesNotContain(val,str)

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.

DoesNotMatch(val,pat)

Returns 1 (true) if val does not match the pattern specified by pat. pat must be a string that uses syntax suitable for the ? pattern matching operator in ObjectScript. For details, see the Pattern Match Operator reference page.

DoesNotStartWith(val,str)

Returns 1 (true) if val does not start with the substring str.

Exists(tab,val)

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).

The tab value must be enclosed in double quotes, for example:

Exists("Alert","Priority_FileOperation")

If(val,true,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.

In(val,items)

Returns 1 (true) if val is found in the comma-delimited string items.

InFile(val,file)

Returns 1 (true) if val is found in the identified file.

InFileColumn(...)

The function InFileColumn can have as many as 8 arguments. The full function signature is:

InFileColumn(val, file, columnId, rowSeparator, columnSeparator, columnWidth, lineComment, stripPadChars)

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 columnId is 1.
Default rowSeparator is ASCII 10. A negative rowSeparator value indicates the row length.
Default columnSeparator is ASCII 9. If columnSeparator is 0, the format of the file is said to be “positional.” In this case columnId means character position and columnWidth means character count.
Default columnWidth is 0.
Default lineComment is an empty string.
Default stripPadChars consists of a blank space followed by ASCII 9.

IntersectsList(val,items,srcsep,targetsep)

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>".

The IntersectsList utility works well with the square bracket [ ] syntax to match values of a virtual document property. If there is more than one instance of the segment type in a message, the square bracket syntax returns the multiple values in a string like <ValueA><ValueB><ValueC>.

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.

Length(string,delimiter)

Returns the length of the given string. If you specify delimiter, this function returns the number of substrings based on this delimiter.

Like(string,pattern)

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.

Lookup(table,keyvalue,default, defaultOnEmptyInput)

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:

^Ens.LookupTable(table,keyvalue)

The table value must be enclosed in double quotes, for example:

Lookup("Gender",source.{PID:Sex},,"U")

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.

defaultOnEmptyInput Value	key value and lookup table	Lookup() returns
0	either key value or lookup table is empty	empty string
1	key value is empty	empty string
1	lookup table is empty but key value is not	default value
2	lookup table is empty	empty string
2	key value is empty but lookup table is not	default value
3	either key value or lookup table is empty	default value

The Exists() function returns true if a Lookup() function with the same parameters would find the key value in the lookup table.

Matches(val,pat)

Returns 1 (true) if val matches the pattern specified by pat. pat must be a string that uses syntax suitable for the ? pattern matching operator in ObjectScript. For details, see the Pattern Match Operator reference page.

Max(...)

Returns the largest of a list of up to 8 values. List entries are separated by commas.

Min(...)

Returns the smallest of a list of up to 8 values. List entries are separated by commas.

Not(val)

Returns 0 (false) if val is 1 (true); 1 (true) if val is 0 (false).

NotIn(val,items)

Returns 1 (true) if val is not found in the comma-delimited string items.

NotInFile(val,file)

Returns 1 (true) if val is not found in the identified file.

NotLike(string,pattern)

Returns 1 (true) if the given value (string) does not satisfy a SQL Like comparison with the given pattern string (pattern). See Like.

Pad(val,width,char)

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.

Piece(val,char,from,to)

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:

Piece("A,B,C,D,E,F") returns "A"

Piece("A!B!C!D!E!F","!",2,4) returns "B!C!D"

The default char is a comma, the default from is 1, and the default to is from (return one piece). For details, see the $PIECE function in the ObjectScript Reference.

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.

RegexMatch(string,regex)

Given an input string val and a regular expression regex, returns 1 if val matches the regular expression; returns 0 otherwise.

Round(val,n)

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.

Rule(rulename,context,activity)

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.

Schedule(ScheduleSpec, ODBCDateTime)

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.

StartsWith(val,str)

Returns 1 (true) if val starts with the substring str.

Strip(val,act,rem,keep)

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 ObjectScript Reference.

SubString(str,n,m)

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.

ToLower(str)

Returns the string str converted to lowercase.

ToUpper(str)

Returns the string str converted to uppercase.

Translate(val,in,out)

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.

Note:

These functions are defined by methods in the class Ens.Util.FunctionSetOpens in a new tab.

Syntax to Invoke a Function

When you reference a 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:

Expression	Computed Value
Min(Age,80,Limit)	When Age is a property with the value 30 and Limit (likewise a property) has the value 65, the value of this expression is 30.
Round(1/3,2)	0.33
Min(10,Max(X,Y))	When X is a property with the numeric value 9.125, and Y (likewise a property) has the numeric value 6.875, the value of this expression is 9.125.

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:
ToUpper(value)
DTL uses two leading dots immediately before the function name, as if the function were a method:
..ToUpper(value)

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>
}

}

Debugging Routing Rules