In addition to basic operators the attribute language also supports functions to perform additional attribute processing. Function references in expressions are case-insensitive.

In the function descriptions below parameters in angle brackets, for example <argument>, are required while arguments in square brackets, for example [argument], are optional. Ellipses mean the previous argument may be repeated any number of times.

Note that methods marked as [3.1] are either new to DataSplice 3.1 or have had their functionality altered.

Basic Functions

The following methods provide commonly used functionality.

Min ( <value1> [, ... ] )

Returns the smallest of a list of values. At least one argument must be supplied. For instance

:= min(5, ${SomeValue}, ${AnotherValue} + 1)

Max ( <value1> [, ... ] )

Works similarly to min, but returns the largest value in the list. 

Floor ( <value> )

Returns the largest integer less than the specified value.

Ceiling ( <value> )

Calculates the ceiling of the specified value.

Abs ( <value> ) [3.1]

Returns the absolute value of a number.

Round ( <value>[, <digits> ] )

Rounds the specified number to a particular number of digits. If digits is not specified (or is zero) the value is rounded to the nearest whole number. If digits is negative the value is rounded to number of places left of the decimal point. For instance, := round( 156, -1) returns 160.

Lower ( <text> )

This returns a value in lowercase. The single argument specifies the text to modify.

Upper ( <text> )

This returns things in uppercase. The single argument specifies the text to modify.

Length ( <text> )

Returns the number of characters in the specified argument.

Substring ( <text> )

Returns the part of the specified string. This takes two or three arguments: the text in question, the character index for the start of the substring, and optionally the number of characters to return.

:= substring("My Text", 0, 2) returns My and

:= substring("My Text", 3) returns Text.

Trim ( <text> ) [3.1]

Removes leading and trailing whitespace from the specified text.

Format ( <data>, <format> ) [3.1] 

Formats the specified value (numeric or date) as text. This uses the same format syntax used by the field validation styles.

NewGuid() [3.1]

Generates a new globally unique identifier (GUID) value.

Execute( <command> ) [3.1]

Parses and executes the specified command. The command must be a string that contains the expression to execute as described by this document. This will return the value of the expression, if any.

Conditional Functions

This set of functions provides logical control to combine other statements in complex ways.

Test ( <condition>, <true value>, <false value> )

Evaluates an expression and returns different values depending on the result. This function takes three arguments: an expression to evaluate, the value to return if the expression is true, and the value to return if it is false.
All of these arguments can themselves be expressions if desired. For instance:

:= test(${Status} == "Complete", upper(${Something}), ${First} || ${Last})

Decode ( <expression>, <test 1>, <value 1> [, <test 2>, <value 2> ]... [, <default> ] )

Compares the expression against several values to return a particular value. This will compare the specified expression to each test n statement in order and return the corresponding value term if the expressions match. Because the internal equality operator is used for the comparison the test case can be patterns to perform regular expression matches.
If an unmatched parameter occurs at the end and if if no matching value was found, it will be used as the default return value. Otherwise this function returns null if nothing matches.

:= Decode(${Status}, 10, "Critical", /^[56789]$/, "High", "Normal")

Eval ( <expression 1>, <value 1>, [, <expression 2>, <value 2> ]... )

Evaluates expressions in turn and returns the associated value for the first one that evaluates to true. This is similar to the Test function, except it supports any number of cases.

For instance, the example for Test above could be written as:

:= eval(${Status} == "Complete", upper(${Something}), true, ${First} || ${Last})

Nvl ( <value>[,  <default> ] ) [3.1]

Returns the specified value if it is not null, otherwise it returns default. In addition, the nvl function can be used to reference attributes that potentially are not defined, which would otherwise display an error message. So := nvl( ${Test Value} ) will return null and not display an error if Test Value is not defined.

Regular Expression Functions

Regular expressions provide powerful text matching capabilities based on patterns. DataSplice uses the common POSIX regular expression syntax used by many development libraries.

Match ( <text>, <expression> )

This returns whether or not a value matches a particular regular expression. This takes two arguments: the text to search and the pattern to match against. For instance:

:= match(${Email}, /\w+@\w+\.(com|net|org)/)

Note that the equality operator supports this same functionality. The above example could also be written:
:= ${Email} = /\w+@\w+\.(com|net|org)/

Find ( <text>, <expression>, [group] )

This is similar to match, but returns a matching subgroup from the pattern. This can take up to three arguments: the text to search, the pattern to use, and the index of the group to return. The last argument is optional.

Group indexes work as you would expect them to. 1 specifies the first set of parentheses, 2 the second, and so on. 0 refers to the entire match. If no group argument is specified, this function returns the first match group or the entire match if there are no parentheses in the pattern.

:= find(${Address}, /(\w+):\/\//)

This will return http if Address is http://www.datasplice.com. The function returns null if the text does not match the pattern.

Substitute ( <text>, <expression>, <replacement> [, <single> ] )

This performs text substitution using regular expressions. This function takes three arguments: the text to process, the pattern to use, and the replacement text. The replacement text can refer to backreferences in the pattern using \1, \2, etc. If single is true, then only the first match is replaced. The default is to replace all matches.

For instance, to change from <Last Name>, <First Name> to <First Name> <Last Name> we could use:

:= substitute(${FullName}, /(\w+),\s*(\w+)/, /\2 \1/)

Split ( <text>, <delimiter> )

Returns a list of values by splitting the input text based on the given delimiter.

Context Functions

These functions are provide access to data and contextual information within DataSplice.

Query ( <view name>, <field name>, <where clause>, [order by clause] )

This performs a query against a target view and returns a value from the first matching record. Up to four arguments can be specified: the name of the view to query, the name of the field that contains the desired value, and an order by statement to sort the returned records. The Order By argument is optional.

Example:

:= query("Child View", "ID", "User = ${DS_USER} and Status <> 4")

LocalQuery( <view name>, <field name>, <where clause>, [order by clause] ) [3.1]

Works the same as the query function except the search is always performed against the local client data, even when online. This allows locally modified values to be queried in connected contexts.

Count ( <view name>, <where clause> )

Returns the number of records that match the specified filter statement in a view. The syntax for the where clause argument is the same as for the query function.

LocalCount ( <view name>, <where clause )

Works the same as the count function except the search is always performed against the local client data, even when online.

HasPlugin( <plugin name> ) [3.1]

Return true if the specified plug-in has been loaded.

DisplayMode() [3.1]

Returns the current view display mode, which will be either filter, grid, or record.

RecordCount() [3.1]

Returns the number of records in the current display.

RecordIndex() [3.1]

Returns the zero-based index of the selected record in the current display.

FindRecord ( <where clause>, [start index] ) [3.1]

Returns the index (zero-based) of the first record in the current display that matches the specified filter. If start index is supplied, the search will begin at that index. The syntax for the where clause is the same as for the query and count functions.

IsInsert()

This takes zero arguments and returns whether or not the current record is a new record.

IsUpdate ()

This works similarly to IsInsert, but returns whether or not the current record is modified.

IsDelete ()

Again similar to IsInsert, but returns if the current record has been marked for deletion.

IsModified ( <field name> )

This returns whether or not a particular field in the current record is modified. The single argument should be the name of the field in question.

:= test(IsModified("Status"), "modified", "not modified")

OriginalValue( <field name> ) [3.1]

Returns the initial (unmodified) value of the specified field in the selected record.

HasFilterItem ( <field name> )

Returns whether or not a filter item for the specified field is specified in the current filter.

HasRecord()

Returns whether or not a record is currently selected.

IsConnected ()

Returns whether or not a connection is currently established with the server. If evaluated on the server this will always return true.

IsAdmin ()

Returns whether or not the user associated with the current connection is a member of the Administrators group.

IsServer ()

Returns whether or not the expression is being evaluated by the DataSplice server.

IsHandheld () [3.1]

Returns whether or not the expression is being evaluated on a handheld  device. 

HasError ()

This can be used during event processing to determine if an error has occurred. Otherwise this will return false.

HasConflict ()

This can be used during event processing to determine if an conflict has been detected. Otherwise this will return false.

Date/Time Functions

These functions simplify working with date values within expressions.

Now ()

Returns the current date and time.

CreateDate ( <year>, [month], [day], [hour], [minute], [second] | <milliseconds> ) [3.1]

Constructs a date and time value given the specified values. If values are not specified, values from January 1, 12:00 AM are used. The variant that accepts a single milliseconds parameter is suitable for turning dates that have been coerced to numeric values back into dates.

AlterDate ( <date>, <days>, [hours], [minutes], [seconds] )

Adds the specified amount of time to a particular date. The specified values can be negative to obtain a value prior to the date.

TruncateDate ( <date>, < "year" | "month" | "day" | "hour" | "minute" > )

Truncates a date to the specified precision. For example:

:= TruncateDate("2005-12-03 12:34:56 PM", "month")

returns 2005-12-01 12:00:00 AM.

CompareDates ( <lhs>, <rhs>, < "year" | "month" | "day" | "hour" | "minute" > )

Compares dates truncated to the specified precision. This is useful to determine if the values are on the same day even if the times are different.

This returns -1 if lhs is before rhs, 1 if it is after, and 0 if the truncated dates are the same.

GetDateTimePart ( <date>, < "year" | "month" | "day" | "hour" | "minute" | "seconds' > ) [3.1]

Returns the specified part of a particular date/time value.

Client Commands

In addition to the above expression commands, the following are available for Execute Command event and navigation actions. Because these functions have side effects, they cannot be used in attribute definitions or other condition expressions. Note that all of these commands are new to DataSplice 3.1.

These are useful to control the state of the Remote Client when various events occur.

Connect()/Disconnect()

Toggles the connection state with the DataSplice Server. 

LogOut()

Releases the current session and logs the user out of the application.

Commit() 

Commits all pending modifications to the server. 

Refresh() 

Reloads the current display. 

ViewSelection() 

Displays the main view selection screen. 

DisplayView ( <view name>, [action name] ) 

Displays the a particular view, using either the specified action or the default.

NavigateUp() 

Moves one level up in the current navigation stack. 

DisplayFilter() / DisplayGrid() / DisplayRecord() 

Toggles the display mode for the current view. 

MoveNext() / MovePrevious() 

Changes the selected record within the current display. 

SelectRecord ( <record index> ) 

Selects the record with the specified index (zero-based) in the current display. 

SelectField ( <field name> )

Moves the active cell to the named field in the selected record. 

CreateRecord() 

Creates a record and adds it to the current display. 

DeleteRecord() 

Marks the selected record(s) for delete. 

ResetRecord() 

Resets any modifications to the selected record(s). 

PerformAction ( <action name> ) 

Performs the named navigation action for the current view. 

CustomEvent ( <qualifier> ) 

Fires the specified custom event.