Scope object is a member of the data object. It provides the ability to set and modify SQL expressions, which define the criteria by which the records are filtered. The SQL syntax can vary from one database system to another. The scope object can translate standard SQL syntax into one that is native to a specific database system thereby improving performance and resolving compatibility issues. Some database-specific features may be unavailable because of this translation. Set the check_syntax parameter to false to disable the translation, in which case the SQL expression will be used as is.

The object is exposed through the IScope interface.

Methods

Set

Sets an SQL expression to be used to filter records. The old object content is overwritten by a call to this method.

Function Set( sql, expression_id(optional, default = -1), check_syntax(optional, default = true) )

Parameters:
string sql - the WHERE clause of an SQL statement.
integer expression_id - the scope object can contain multiple sub-expressions joined by the AND operator.  Set this parameter to a unique value to be able to identify this sub-expression later.
boolean check_syntax - true: check the syntax and translate the expression into a database specific dialect; false: do not check syntax and leave the expression as is.

Return value:
none

Scope.Set "ID=25", 1, true

Modify

Modifies an existing sub-expression identified by expression_id or adds a new sub expression. Pass an empty string as the first parameter to remove an existing sub-expression.

Function Modify( sql, expression_id(optional, default = -1), check_syntax(optional, default = true) )

Parameters:
string sql - the WHERE clause of an SQL statement.
integer expression_id - the id of the sub-expression to be modified.
boolean check_syntax - true: check syntax and translate the expression into a database specific dialect; false: do not check syntax and leave the expression as is.

Return value:
none

Scope.Modify "ID=26", 1, true

Get

Gets the complete SQL expression stored in the scope object. You may request either the compiled or the original representation of the SQL expression. The compiled version has all custom fields expanded to their definitions and the syntax translated into that of the dialect of the database being used. You may pass a table alias as a parameter, in which case the compiled version will be returned and all the fields in the SQL statement will be pre-pended with that alias.

Function Get( how(optional, default = false) )

Parameters:
variant how - boolean - true: get the compiled expression; false: get the original expression. 
                     string - a table alias.

Return value:
string a compiled or original SQL expression

Scope.Get()