Utility Functions for Use in Productions

Returns 1 (true) if value contains the substring string; otherwise 0 (false). The following example tests for ABC within the value of a property of the source message:

Contains(source.SampleProperty,"ABC")

Reads the input string value 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.

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

Returns 1 (true) if value does not contain the substring string. For example:

DoesNotContain(source.SampleProperty,"ABC")

Returns 1 (true) if no item in the given source list (value) appears in the target list (items). For details on the arguments, see IntersectsList().

Returns 1 (true) if value does not match the pattern specified by pattern. pattern must be a string that uses syntax suitable for the ObjectScript pattern match operator. For example:

DoesNotMatch(source.SampleProperty,source,"ssn?3N1""-"2N1""-""4N")

Returns 1 (true) if value does not start with the substring string. For example:

DoesNotStartWith(source.SampleProperty,"ABC")

The Exists() function provides a way to predict the results of the Lookup() function. Exists() returns 1 (true) if value is a key defined within the table identified by tablename; otherwise it returns 0 (false).

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

Exists("Alert","Priority_FileOperation")

You can omit the double quotes around value, if that argument is a number.

If the argument value evaluates to 1 (true), the this function returns the string value of its true argument; otherwise it returns the string value of its false argument.

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

You can use this function with a list that uses a custom separator (rather than a comma). To do so, append two commas to the items list, followed by the custom separator. The system will parse the items argument, find the two sequential commas and then interpret the following character as the separator to use. For example (here using the equivalent method call from Ens.Util.FunctionSet):

ENSLIB>set items="a|b|c,,|"
 
ENSLIB>write ##class(Ens.Util.FunctionSet).In("a",items)
1

You can also use this function with a list in which each item is wrapped by a prefix and a suffix character. To do so, append two commas to the items list, followed by the prefix character and then the suffix character. For example:

ENSLIB>set items="<a><b><c>,,<>"
 
ENSLIB>w ##class(Ens.Util.FunctionSet).In("a",items)
1

Returns 1 (true) if value is found in the file whose name is filename.

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

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

InFileColumn() returns 1 (true) if value 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.

Returns 1 (true) if any item in the given source list (value) 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() function 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.

Returns the length of the given string. If you specify delimiter, this function returns the number of substrings based on this delimiter. For example, to get the number of characters in a property, do this:

Length(source.SampleProperty)

If the property contains commas, and you want to find how many comma-separated pieces it has, do this:

Length(source.SampleProperty,",")

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:

^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 follows:

The default value of the defaultOnEmptyInput parameter is 0.

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

Returns 1 (true) if value matches the pattern specified by pattern. pattern must be a string that uses syntax suitable for the ObjectScript pattern match operator. Any double quotation marks in this string must be double quoted. For example, to determine whether the value of a property matches the form of a valid U.S. Social Security Number, do this:

Matches(source.SampleProperty,source,"ssn?3N1""-"2N1""-""4N")

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

Max(source.SampleProperty1,source.SampleProperty2,source.SampleProperty3,10000)

This returns the value of the largest property (of those listed), or 10000, whichever is greater.

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

Min(source.SampleProperty1,source.SampleProperty2,source.SampleProperty3,0)

This returns the value of the smallest property (of those listed), or 0, whichever is smaller.

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

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

Returns 1 (true) if value is not found in the file whose name is filename.

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 value. 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 value string. If width is a negative value, the padding is prepended to the left-hand side of the value string.

If the delimiter character char is present in the string value, 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.

If you omit the delimiter character char and the from and to arguments, this function assumes that value is a comma-separated list and returns the first item from that list (A, in this example):

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

For the to argument, you can use "*" to refer to the last position in list. For both from and to arguments, you can use syntax that refers to positions relative to the last position. For example "*-1" means the position just before the last position.

The default char is a comma, the default from is 1, and the default to is from (return one piece). For details, see the ObjectScript $PIECE function. Note that in contrast to the ObjectScript function, you must use double quotes around "*" syntax.

Starting with the input string value, replaces any occurrences of string find with the string repl, and returns the resulting string. For example:

ReplaceStr(source.SampleProperty,"abc","ABC")

This example finds any occurrence of abc in the given property and replaces that with ABC.

See also Translate().

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

Returns value rounded off to n digits after the decimal point. If n is not provided (that is, Round(value)) the function drops the fractional portion of the number and rounds it to the decimal point, producing an integer. For example:

Round(source.SampleNumericProperty,2)

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 value starts with the substring string; otherwise 0 (false). The following example tests whether a property of the source message starts with ABC:

StartsWith(source.SampleProperty,"ABC")

Reads the input string value. 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 on these arguments, see $ZSTRIP.

For example, to remove numeric characters from a property of the source message:

Strip(source.SampleProperty,"*N")

To remove leading and trailing whitespace:

Strip(source.SampleProperty,"<>W")

Returns a substring of a string string, 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(string,n)) the function returns the substring from position n to the end of the string.

For example, to get the first five characters of a property, do this:

SubString(source.SampleProperty,1,5)

To get characters 10–15 of a property, do this:

SubString(source.SampleProperty,10,15)

SubString(source.SampleProperty,15)

Returns the string string converted to lowercase. For example:

ToLower(source.SampleProperty)

Returns the string string converted to uppercase. For example:

ToLower(source.SampleProperty)

Reads the input string value. Translates each occurrence of a character in string in to the character at the corresponding position in string out, and returns the resulting string.

Translate(source.SampleProperty,"abc","ABC")

This example finds any occurrence of a in the given property and replaces that with A, finds any occurrence of b and replaces that with B, and finds any occurrence of c and replaces that with C.

See also ReplaceStr().