Difference between revisions of "String Expressions"

From Agility
Jump to: navigation, search
(Created page with "Category:FastNET")
 
(Created page for string expressions description plus general functions.)
Line 1: Line 1:
 
[[Category:FastNET]]
 
[[Category:FastNET]]
 +
 +
= Introduction =
 +
Within the framework there are many places where the user may specify a free format "string expression" in place of a text string.
 +
 +
e.g.
 +
: Initial / Default Values for a field
 +
: The label on a Treeview Element
 +
: The Definition of a HTML link or in line form
 +
: The building of the HTML string used by the integrated email system.
 +
 +
It is the users responsibility to ensure that the syntax is correct. Full parsing and analysis of the string is not done when it is saved.
 +
 +
Note that when building up “raw” HTML strings care needs to be taken to ensure that HTML control characters are not accidentally included in any data strings. e.g. if a "Less than" sign is required within the data it should be entered as "&amp;lt;"  rather than "<".
 +
 +
String expressions allows to define complex text values definitions. It allows to use static texts, database fields values, concatenation operations and string functions.
 +
 +
Example:
 +
 +
: "http://”+pmAsset.Code+”/test”+left(pmAsset.TempCode,3)
 +
 +
 +
String constant needs to be specified in quotes or double quotes:
 +
: '…' or "…."
 +
 +
Database field reference needs to be build as "TableName"."FieldName" e.g.:
 +
: pmAsset.Description
 +
 +
 +
= String Expression Functions =
 +
 +
==Concatenation Operators for String values==
 +
 +
{| class="wikitable"
 +
!Operator
 +
!Description
 +
|-
 +
| + (plus)
 +
|Combines the fields without inserting any spaces or characters in between e.g. “John” + “Smith” will appear as “JohnSmith”
 +
|-
 +
|, (comma)
 +
|Combines the fields with a comma character in between e.g. “John” , “Smith” will appear as “John,Smith”
 +
|}
 +
 +
==Operators==
 +
{| class="wikitable"
 +
!Operator
 +
!Description
 +
|-
 +
| +
 +
| Numerical sum, datetime plus number of days, strings concatenation
 +
|-
 +
| -
 +
| Numerical  substract, datetime minus number of days,
 +
|-
 +
| *
 +
| Numerical multiply
 +
|-
 +
| /
 +
| Numerical divide
 +
|-
 +
| ( )
 +
| Brackets to change order of evaluation of expressions
 +
|-
 +
| =  !=
 +
| Relations equal and not equal, result logical true or false
 +
|-
 +
| > <
 +
| Relations greater and less, result logical true or false
 +
|-
 +
| >=    <=
 +
| Relations greater or equal and less or equal, result logical true or false
 +
|-
 +
| And
 +
| Logical And of two logical values
 +
|-
 +
| Or
 +
| Logical Or of two logical values
 +
|-
 +
| Not
 +
| Logical Not of logical value
 +
|-
 +
| A Like B
 +
| Returns true if string value A matches regular expression B as string
 +
|-
 +
| A Matches B
 +
| Returns true if string value A matches regular expression B as string
 +
|-
 +
| A IN (ConstantList)
 +
| Returns true if result of expression A will be from the set specified in the list of constant valueswhich will be in the form of  (‘Constant1’,’Constant2’,’Constant3’,...)
 +
|}
 +
 +
==String Constants==
 +
{| class="wikitable"
 +
!Operator
 +
!Description
 +
|-
 +
| “This is a fixed string”
 +
| Use of “double quotes” to identify a fixed string.
 +
|-
 +
| ‘So is this’
 +
| Use of ‘single quotes’ to identify a fixed string.
 +
|-
 +
| T”<text>“ T’<text>‘
 +
| String constants which will be translated before using. In example T”Save” will be translated to current language and in polish it could be “Zapisz”
 +
|-
 +
| YYYY-MM-DD
 +
| Date constant
 +
|-
 +
| HH-MM
 +
| Time constant
 +
|-
 +
| 99999999
 +
|Integer value
 +
|-
 +
| 9999999.99999
 +
| Decimal value
 +
|-
 +
| True
 +
| Logical true
 +
|-
 +
| False
 +
| Logical false
 +
|}
 +
 +
==String Functions==
 +
{| class="wikitable"
 +
!Operator
 +
!Description
 +
|-
 +
| SUBSTRING
 +
|Extracts a string from within another string. SUBSTRING( SourceString, StartPosition, Length) N.B. the first character is position 0
 +
e.g.
 +
SUBSTRING (“JohnSmith, 4 , 2) would return “Sm”
 +
|-
 +
| LEFT
 +
| Extracts the leftmost characters from a string.
 +
LEFT (SourceString, Length)
 +
e.g.
 +
LEFT “JohnSmith”,4) would return “John”.
 +
|-
 +
| RIGHT
 +
| Extracts the leftmost characters from a string.
 +
RIGHT (SourceString, Length)
 +
e.g.
 +
RIGHT (“JohnSmith”,5) would return “Smith”.
 +
|-
 +
| UPPER
 +
| Converts the whole of a string into UPPER CASE. UPPER (SourceString)
 +
e.g.
 +
UPPER (“JohnSmith”) would return “JOHNSMITH”)
 +
|-
 +
| LOWER
 +
| Converts the whole of a string into lower case. LOWER (SourceString)
 +
e.g.
 +
LOWER (“JohnSmith”) would return “johnsmith”)
 +
|-
 +
| IF ( A , B , C )
 +
| If logical value of A is true result is value of B, else result is value of C.
 +
|-
 +
| HTMLENCODE()
 +
| Encodes a string replacing any sensitive HTML control characters by their HTML equivalent. e.g. &amp; by &amp;amp;, “ by &quot; etc.
 +
|-
 +
| HTMLENCODECR()
 +
| As above but also preserves the carriage returns in the string by replacing them with <nowiki><BR></nowiki>
 +
|-
 +
| INDEXOF(“A”,”B”)
 +
| Returns the position of String “B” within String “A”. If String “B” is not found -1 is returned. Otherwise the position of the string is returned. NB the first character position will be position 0. It is a case sensitive search so convert to upper/lower before searching if you don’t want this.
 +
|}
 +
 +
==FastNET - Specific Functions==
 +
When using a function its format should be Function(Argument1, Argument2,….) if no arguments are required the () must still be present.
 +
 +
For a full list of the currently supported FastNET Functions see the separate section.
 +
 +
Example:
 +
:<code>NOW()  + UserName()</code>
 +
 +
Will build a string containing the current date, time and the name of the currently logged in user.
 +
 +
==User Defined Variables (#VariableName)==
 +
 +
Within the framework it is possible for any form to pass information to a subsidiary form by using the User Defined variables. These field are defined in the link parameters of the parent form and are automatically carried forward to all child forms.
 +
They are accessed by prefixing the name given in the calling form by a hash mark (#).
 +
So if a variable is defined as “CurrentCustomerID” in the calling program its value can be referenced in every subsequent child form as #CurrentCustomerID. See the notes below regarding the Attribute expression to ensure correct interpretation of the value in subsequent programs.
 +
 +
==Database Fields==
 +
 +
The expression may also contain Database fields and these can be either directly from the current Business Object’s dataset or be obtained from another table which is linked to the current Business object.
 +
However where the link between the current Business Object is undefined or could be ambiguous there is a facility to tell the framework the precise method to be used to obtain the information. The keyword “constrains” is used to indicate the presence of this complex relationship.
 +
Simple and unambiguously related fields
 +
Where information is required from a table and field forming part of the business Object or obtainable without any ambiguity then all that needs to be specified is:-
 +
 +
:<code>TableName.FieldName</code>
 +
 +
The software will do the rest, by using the Metadata, it will work out the optimum method to access the information required.
 +
Ambiguously related fields
 +
Where information is required from a table and field forming part of the business Object or obtainable is ambiguous then the software will attempt to use the shortest least complex relationship. However this is not always the required behavior.
 +
 +
To Override this behavior the CONSTRAINS clause is required:
 +
 +
:<code>RequiredTableName.RequiredFieldName CONSTRAINS RequiredTableName ( LinkTable.LinkField, LinkTable.LinkField ……….)</code>
 +
 +
The links are specified from the “child to the RequiredTableName and only need be specified sufficiently to indicate the route to be used to establish the link.

Revision as of 14:12, 24 August 2016


Introduction

Within the framework there are many places where the user may specify a free format "string expression" in place of a text string.

e.g.

Initial / Default Values for a field
The label on a Treeview Element
The Definition of a HTML link or in line form
The building of the HTML string used by the integrated email system.

It is the users responsibility to ensure that the syntax is correct. Full parsing and analysis of the string is not done when it is saved.

Note that when building up “raw” HTML strings care needs to be taken to ensure that HTML control characters are not accidentally included in any data strings. e.g. if a "Less than" sign is required within the data it should be entered as "&lt;" rather than "<".

String expressions allows to define complex text values definitions. It allows to use static texts, database fields values, concatenation operations and string functions.

Example:

"http://”+pmAsset.Code+”/test”+left(pmAsset.TempCode,3)


String constant needs to be specified in quotes or double quotes:

'…' or "…."

Database field reference needs to be build as "TableName"."FieldName" e.g.:

pmAsset.Description


String Expression Functions

Concatenation Operators for String values

Operator Description
+ (plus) Combines the fields without inserting any spaces or characters in between e.g. “John” + “Smith” will appear as “JohnSmith”
, (comma) Combines the fields with a comma character in between e.g. “John” , “Smith” will appear as “John,Smith”

Operators

Operator Description
+ Numerical sum, datetime plus number of days, strings concatenation
- Numerical substract, datetime minus number of days,
* Numerical multiply
/ Numerical divide
( ) Brackets to change order of evaluation of expressions
=  != Relations equal and not equal, result logical true or false
> < Relations greater and less, result logical true or false
>= <= Relations greater or equal and less or equal, result logical true or false
And Logical And of two logical values
Or Logical Or of two logical values
Not Logical Not of logical value
A Like B Returns true if string value A matches regular expression B as string
A Matches B Returns true if string value A matches regular expression B as string
A IN (ConstantList) Returns true if result of expression A will be from the set specified in the list of constant valueswhich will be in the form of (‘Constant1’,’Constant2’,’Constant3’,...)

String Constants

Operator Description
“This is a fixed string” Use of “double quotes” to identify a fixed string.
‘So is this’ Use of ‘single quotes’ to identify a fixed string.
T”<text>“ T’<text>‘ String constants which will be translated before using. In example T”Save” will be translated to current language and in polish it could be “Zapisz”
YYYY-MM-DD Date constant
HH-MM Time constant
99999999 Integer value
9999999.99999 Decimal value
True Logical true
False Logical false

String Functions

Operator Description
SUBSTRING Extracts a string from within another string. SUBSTRING( SourceString, StartPosition, Length) N.B. the first character is position 0

e.g. SUBSTRING (“JohnSmith, 4 , 2) would return “Sm”

LEFT Extracts the leftmost characters from a string.

LEFT (SourceString, Length) e.g. LEFT “JohnSmith”,4) would return “John”.

RIGHT Extracts the leftmost characters from a string.

RIGHT (SourceString, Length) e.g. RIGHT (“JohnSmith”,5) would return “Smith”.

UPPER Converts the whole of a string into UPPER CASE. UPPER (SourceString)

e.g. UPPER (“JohnSmith”) would return “JOHNSMITH”)

LOWER Converts the whole of a string into lower case. LOWER (SourceString)

e.g. LOWER (“JohnSmith”) would return “johnsmith”)

IF ( A , B , C ) If logical value of A is true result is value of B, else result is value of C.
HTMLENCODE() Encodes a string replacing any sensitive HTML control characters by their HTML equivalent. e.g. & by &amp;, “ by " etc.
HTMLENCODECR() As above but also preserves the carriage returns in the string by replacing them with <BR>
INDEXOF(“A”,”B”) Returns the position of String “B” within String “A”. If String “B” is not found -1 is returned. Otherwise the position of the string is returned. NB the first character position will be position 0. It is a case sensitive search so convert to upper/lower before searching if you don’t want this.

FastNET - Specific Functions

When using a function its format should be Function(Argument1, Argument2,….) if no arguments are required the () must still be present.

For a full list of the currently supported FastNET Functions see the separate section.

Example:

NOW() + UserName()

Will build a string containing the current date, time and the name of the currently logged in user.

User Defined Variables (#VariableName)

Within the framework it is possible for any form to pass information to a subsidiary form by using the User Defined variables. These field are defined in the link parameters of the parent form and are automatically carried forward to all child forms. They are accessed by prefixing the name given in the calling form by a hash mark (#). So if a variable is defined as “CurrentCustomerID” in the calling program its value can be referenced in every subsequent child form as #CurrentCustomerID. See the notes below regarding the Attribute expression to ensure correct interpretation of the value in subsequent programs.

Database Fields

The expression may also contain Database fields and these can be either directly from the current Business Object’s dataset or be obtained from another table which is linked to the current Business object. However where the link between the current Business Object is undefined or could be ambiguous there is a facility to tell the framework the precise method to be used to obtain the information. The keyword “constrains” is used to indicate the presence of this complex relationship. Simple and unambiguously related fields Where information is required from a table and field forming part of the business Object or obtainable without any ambiguity then all that needs to be specified is:-

TableName.FieldName

The software will do the rest, by using the Metadata, it will work out the optimum method to access the information required. Ambiguously related fields Where information is required from a table and field forming part of the business Object or obtainable is ambiguous then the software will attempt to use the shortest least complex relationship. However this is not always the required behavior.

To Override this behavior the CONSTRAINS clause is required:

RequiredTableName.RequiredFieldName CONSTRAINS RequiredTableName ( LinkTable.LinkField, LinkTable.LinkField ……….)

The links are specified from the “child to the RequiredTableName and only need be specified sufficiently to indicate the route to be used to establish the link.

Retrieved from "http://agilitywiki.northeurope.cloudapp.azure.com/agilitywiki/index.php?title=String_Expressions&oldid=578"