Difference between revisions of "Functions"

From PresenceWiki
Jump to: navigation, search
(&lookupMimeByExtention)
(Eval)
 
(44 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
=== About Presence Functions ===
 
=== About Presence Functions ===
  
Functions can be used almost anywhere a [[Presence Text Area]] is Used, you know if you are in a Presence Text Area by Pressing CTRL+Space. Almost all Presence Functions will accept Presence Variables in the form of ${variable_name}, you can also embed other functions into functions e.g &round{"&random{"${maxval}"}"} would return a rounded integer rather than a double/float based on the value of the ${maxval} variable.
+
Functions can be used almost anywhere a [[Presence Text Area]] is used, you know if you are in a Presence Text Area by Pressing CTRL+Space. Almost all Presence Functions will accept Presence Variables in the form of ${variable_name}, you can also embed other functions into functions e.g &round{"&random{"${maxval}"}"} would return a rounded integer rather than a double/float based on the value of the ${maxval} variable.
  
 
It is always a good idea to place quotes around any parameters within the function unless it is a numeric function that only accepts whole numbers, doing this helps to ensure the parser can recognise the start and end of the data.  
 
It is always a good idea to place quotes around any parameters within the function unless it is a numeric function that only accepts whole numbers, doing this helps to ensure the parser can recognise the start and end of the data.  
  
Anybody can create their own Presence Functions, for more information see [[Function Call]].  
+
Anybody can create their own Presence Functions, for more information see [[Function Call]].
 +
 
 +
=== Testing Presence Functions ===
 +
 
 +
You can test functions using the [[Function Test Console]]
  
 
=== Index of Functions ===
 
=== Index of Functions ===
Line 20: Line 24:
  
 
<pre>&equalsString{"ABC","ABC"}</pre> Returns true <pre>&equalsString{"ABC","BC"}</pre> Returns false
 
<pre>&equalsString{"ABC","ABC"}</pre> Returns true <pre>&equalsString{"ABC","BC"}</pre> Returns false
 +
<hr>
  
 
===== If Boolean Test =====
 
===== If Boolean Test =====
Line 28: Line 33:
  
 
<pre>&if{"true", "I AM TRUE", "I AM FALSE"}</pre> Returns "I AM TRUE" <pre>&if{"0", "I AM TRUE", "I AM FALSE"}</pre> Returns "I AM FALSE"
 
<pre>&if{"true", "I AM TRUE", "I AM FALSE"}</pre> Returns "I AM TRUE" <pre>&if{"0", "I AM TRUE", "I AM FALSE"}</pre> Returns "I AM FALSE"
 
+
<hr/>
 
==== Data Functions ====
 
==== Data Functions ====
  
Line 49: Line 54:
  
 
If the task returns a magic ${response} variable that value will be populated in the variable or space you are calling the function from.
 
If the task returns a magic ${response} variable that value will be populated in the variable or space you are calling the function from.
 +
<hr/>
  
 
===== Does Column Exist On Data Table =====
 
===== Does Column Exist On Data Table =====
Line 57: Line 63:
  
 
Parameter 1: The column name to test
 
Parameter 1: The column name to test
 +
<hr/>
  
 
==== Date Functions ====
 
==== Date Functions ====
Line 110: Line 117:
  
 
<pre>&currentDate{"MMM/yyyy"}</pre> Returns Aug/2015 <pre>&currentDate{"dd/MM/yyyy"}</pre> Returns 13/08/2015 or whatever the current date is. <pre>&currentDate{"dd/MM/yyyy",-5}</pre> Returns 08/08/2015 (minus 5 days from the current date) <pre>&currentDate{"dd/MM/yyyy",-3M}</pre> Returns 13/05/2015 (minus 3 months from the current date) <pre>&currentDate{"dd/MM/YYYY",5}</pre> Returns 18/08/2015 (plus 5 days from the current date)
 
<pre>&currentDate{"MMM/yyyy"}</pre> Returns Aug/2015 <pre>&currentDate{"dd/MM/yyyy"}</pre> Returns 13/08/2015 or whatever the current date is. <pre>&currentDate{"dd/MM/yyyy",-5}</pre> Returns 08/08/2015 (minus 5 days from the current date) <pre>&currentDate{"dd/MM/yyyy",-3M}</pre> Returns 13/05/2015 (minus 3 months from the current date) <pre>&currentDate{"dd/MM/YYYY",5}</pre> Returns 18/08/2015 (plus 5 days from the current date)
 +
<hr/>
  
 
===== Format Date =====
 
===== Format Date =====
Line 118: Line 126:
  
 
<pre>&formatDate{"2015-08-13","yyyy-MM-dd","dd/MM/yyyy"}</pre> Returns 13/08/2015 <pre>&formatDate{"2015-08-13","yyyy-MM-dd","E dd MMM YYYY"}</pre> Returns Thu 13 Aug 2015 <pre>&formatDate{"2015-08-13","yyyy-MM-dd","dd/MM/yyyy",5}</pre> Returns 13/08/2015 (adds 5 days to the date on parameter 1) <pre>&formatDate{"2015-08-13","yyyy-MM-dd","EEEE dd MMM YYYY"}</pre> Returns Thursday 13 Aug 2015
 
<pre>&formatDate{"2015-08-13","yyyy-MM-dd","dd/MM/yyyy"}</pre> Returns 13/08/2015 <pre>&formatDate{"2015-08-13","yyyy-MM-dd","E dd MMM YYYY"}</pre> Returns Thu 13 Aug 2015 <pre>&formatDate{"2015-08-13","yyyy-MM-dd","dd/MM/yyyy",5}</pre> Returns 13/08/2015 (adds 5 days to the date on parameter 1) <pre>&formatDate{"2015-08-13","yyyy-MM-dd","EEEE dd MMM YYYY"}</pre> Returns Thursday 13 Aug 2015
 +
<hr/>
  
 
===== Adjust Time Zone =====
 
===== Adjust Time Zone =====
Line 127: Line 136:
  
 
There is an optional 5th parameter which is the format to be used when creating the string that is returned. If it is omitted then the format specified in the 2nd parameter is used.
 
There is an optional 5th parameter which is the format to be used when creating the string that is returned. If it is omitted then the format specified in the 2nd parameter is used.
 +
<hr/>
  
 
===== Calculate Date Ignoring Weekends  =====
 
===== Calculate Date Ignoring Weekends  =====
Line 150: Line 160:
  
 
Note that for months and years the IGNOREWEEKENDS attribute will be discarded - weekends will never be taken into account.
 
Note that for months and years the IGNOREWEEKENDS attribute will be discarded - weekends will never be taken into account.
 +
<hr/>
  
 
===== Calculate Runtime Basic =====
 
===== Calculate Runtime Basic =====
Line 164: Line 175:
  
 
<pre>&calcNextRuntimeFromBasic{"true", "false", "0", "09:00"}</pre> Returns 1441094400000
 
<pre>&calcNextRuntimeFromBasic{"true", "false", "0", "09:00"}</pre> Returns 1441094400000
 +
<hr/>
  
 
===== Calulate Runtime From Day =====
 
===== Calulate Runtime From Day =====
Line 179: Line 191:
 
String "STARTTIME" eg 09:00
 
String "STARTTIME" eg 09:00
 
String "ENDTIME" eg 13:00
 
String "ENDTIME" eg 13:00
 +
<hr/>
  
 
===== Calculate Timezone Difference Hours =====
 
===== Calculate Timezone Difference Hours =====
Line 189: Line 202:
  
 
Will return -5 (ie GMT-5).
 
Will return -5 (ie GMT-5).
 +
<hr/>
  
 
===== Current Time =====
 
===== Current Time =====
Line 203: Line 217:
 
<pre>&currentTime{"HH:mm", -60}</pre> Returns "14:30" (60 minutes in the past)
 
<pre>&currentTime{"HH:mm", -60}</pre> Returns "14:30" (60 minutes in the past)
 
<pre>&currentTime{"h.mm a", 30}</pre> Returns "4.00 PM" (half an hour in the future)
 
<pre>&currentTime{"h.mm a", 30}</pre> Returns "4.00 PM" (half an hour in the future)
 +
<hr/>
  
 
===== Current Time Stamp =====
 
===== Current Time Stamp =====
Line 208: Line 223:
  
 
Returns: the current time in milliseconds, offset by the number of minutes in the parameter (default is zero).
 
Returns: the current time in milliseconds, offset by the number of minutes in the parameter (default is zero).
 +
<hr/>
  
 
===== Date In Milliseconds =====
 
===== Date In Milliseconds =====
Line 215: Line 231:
  
 
<pre>&dateInMillis{"01/01/2001", "dd/MM/yyyy"}</pre> Returns 978307200000
 
<pre>&dateInMillis{"01/01/2001", "dd/MM/yyyy"}</pre> Returns 978307200000
 +
<hr/>
  
 
===== Format Milliseconds =====
 
===== Format Milliseconds =====
Line 223: Line 240:
 
<pre>&formatMilliseconds{"978307200000", "dd/MM/yyyy"}</pre> Returns 01/01/2001
 
<pre>&formatMilliseconds{"978307200000", "dd/MM/yyyy"}</pre> Returns 01/01/2001
 
<pre>&formatMilliseconds{"0", "dd MMM yyyy"}</pre> Returns the epoch date "01 Jan 1970"
 
<pre>&formatMilliseconds{"0", "dd MMM yyyy"}</pre> Returns the epoch date "01 Jan 1970"
 +
<hr/>
  
 
===== Format TF400 Date =====
 
===== Format TF400 Date =====
Line 238: Line 256:
  
 
<pre>&formatTF400Date{"9342220130325", "dd MMM yyyy 'at' HH:mm:ss"}</pre> Returns 25 Mar 2013 at 09:34:22
 
<pre>&formatTF400Date{"9342220130325", "dd MMM yyyy 'at' HH:mm:ss"}</pre> Returns 25 Mar 2013 at 09:34:22
 +
<hr/>
  
 
===== Milliseconds To Date =====
 
===== Milliseconds To Date =====
Line 246: Line 265:
  
 
<pre>&millisToDate{"978307200000", "yyyy-MM-dd'T'HH:mm:ss.SSSZ"}</pre> Returns 2001-01-01T00:00:00.000+0000
 
<pre>&millisToDate{"978307200000", "yyyy-MM-dd'T'HH:mm:ss.SSSZ"}</pre> Returns 2001-01-01T00:00:00.000+0000
 +
<hr/>
  
 
===== Parse Seven Digit Date=====
 
===== Parse Seven Digit Date=====
Line 256: Line 276:
 
- Parameter 2: The Java date format to use for formatting. Eg "dd-MM-yyyy".
 
- Parameter 2: The Java date format to use for formatting. Eg "dd-MM-yyyy".
 
<pre>&parseSevenDigitDate{"1150101", "dd-MM-yyyy"}</pre> Returns 01-01-2015
 
<pre>&parseSevenDigitDate{"1150101", "dd-MM-yyyy"}</pre> Returns 01-01-2015
 +
<hr/>
  
 
=====Seven Digit Date=====
 
=====Seven Digit Date=====
Line 267: Line 288:
 
Parameter 2: The date format to use in parsing the input date.
 
Parameter 2: The date format to use in parsing the input date.
 
<pre> &sevenDigitFormat{"23 Mar 2003", "dd MMM yyyy"}</pre> Returns "1030323"
 
<pre> &sevenDigitFormat{"23 Mar 2003", "dd MMM yyyy"}</pre> Returns "1030323"
 +
<hr/>
  
 
=====Validate Date=====
 
=====Validate Date=====
Line 275: Line 297:
  
 
Can also pass it a true to check that the date is not in the future.
 
Can also pass it a true to check that the date is not in the future.
 +
<hr/>
  
 
====Excel Functions====
 
====Excel Functions====
Line 291: Line 314:
  
 
Returns the old value.
 
Returns the old value.
 +
<hr/>
  
 
==== File Operations ====
 
==== File Operations ====
Line 302: Line 326:
  
 
Files are added recursively, ie subdirectory contents are also added. If the target zip file already exists it will be renamed to [old_file_name].yyyymmdd
 
Files are added recursively, ie subdirectory contents are also added. If the target zip file already exists it will be renamed to [old_file_name].yyyymmdd
 +
<hr/>
  
 
=====Extract Text from PDF File=====
 
=====Extract Text from PDF File=====
Line 309: Line 334:
  
 
Useage: &extractTextFromPdf {"FILE_LOCATION"}
 
Useage: &extractTextFromPdf {"FILE_LOCATION"}
 +
<hr/>
  
 
=====Does File Exist=====
 
=====Does File Exist=====
Line 315: Line 341:
  
 
Tests whether the specified file exists. If the file exists the function returns "TRUE", otherwise returns "FALSE".
 
Tests whether the specified file exists. If the file exists the function returns "TRUE", otherwise returns "FALSE".
 +
<hr/>
  
 
=====File Length=====
 
=====File Length=====
Line 320: Line 347:
  
 
Returns the length of the specified file, or -1 if it doesn't exist or if the path specified is a folder.
 
Returns the length of the specified file, or -1 if it doesn't exist or if the path specified is a folder.
 +
<hr/>
  
 
=====Get File Value=====
 
=====Get File Value=====
Line 330: Line 358:
  
 
Example: &getFileValue{"c:\myfile.ini","MYKEY"}
 
Example: &getFileValue{"c:\myfile.ini","MYKEY"}
 +
 +
See also : [[#Set File Value]]
 +
<hr/>
  
 
=====Lookup MIME Type By Extension =====
 
=====Lookup MIME Type By Extension =====
Line 337: Line 368:
  
 
<pre>&lookupMimeByExtension{".pdf"}</pre> Returns application/octet-stream
 
<pre>&lookupMimeByExtension{".pdf"}</pre> Returns application/octet-stream
 +
<hr/>
 +
 +
=====Measure Image=====
 +
Format: &measureImage{IMAGE_FILE}
  
=====&measureImage{IMAGE FILE}=====
 
 
Measures the width and height of image file specified in arg 1.
 
Measures the width and height of image file specified in arg 1.
  
Line 344: Line 378:
  
 
width=n,height=n
 
width=n,height=n
 +
<hr/>
 +
 +
=====Set File Value=====
 +
Format: &setFileValue{FILE,KEY,VALUE}
  
=====&setFileValue{FILE,KEY,VALUE}=====
 
 
Sets a value in a INI or Properties type file.
 
Sets a value in a INI or Properties type file.
  
Line 352: Line 389:
 
Example: &setFileValue{"c:\myfile.ini","MYKEY", "MYVALUE"}
 
Example: &setFileValue{"c:\myfile.ini","MYKEY", "MYVALUE"}
  
=====&touchFile{FILE}=====
+
See also : [[#Get File Value]]
 +
<hr/>
 +
 
 +
=====Touch File=====
 +
Format: &touchFile{FILE}
 +
 
 
Sets the last modified date of the file in parameter 1 to be the current system time.
 
Sets the last modified date of the file in parameter 1 to be the current system time.
 +
<hr/>
 +
 +
=====Unzip File=====
 +
Format: &unzip{ZIP,TO FOLDER}
  
=====&unzip{ZIP,TO FOLDER}=====
 
 
Unzips the archive specified in argument #1 into the directory specified in argument #2.
 
Unzips the archive specified in argument #1 into the directory specified in argument #2.
  
Line 361: Line 406:
  
 
Extracts the archive "/archive.zip" into the directory "/extracted". If the directory does not already exist it will be created at runtime.
 
Extracts the archive "/archive.zip" into the directory "/extracted". If the directory does not already exist it will be created at runtime.
 +
<hr/>
 +
 +
=====Encrypt File=====
 +
Format: &fileEncrypt{"/path/file.ext","/path/new_encrypted_file.enc","algorithm","key"}
 +
 +
The file encrypt function provides simple accessibility to common cryptography requirements. The supported algorithms are as follows:
 +
 +
Parameter 1: the location of the file to be encrypted
 +
 +
Parameter 2: the location of the newly created encrypted file.
 +
 +
Parameter 3: the Algorithm:
 +
 +
*AES (from 16 to 32 chars key length)
 +
*ARCFOUR (from 8 to 32 chars key length)
 +
*BLOWFISH (from 4 to 56 chars key length)
 +
*DES (8 chars key length)
 +
*DESEDE (8, 16 24 chars key length)
 +
*RC2 (variable upto 128 chars key length)
 +
 +
Parameter 4: the key to use for encryption see above for valid key lengths
 +
<hr/>
 +
 +
=====Decrypt File=====
 +
Format: &fileDecrypt{"/path/encrypted_file.enc","/path/decrypted_file.ext","algorithm","key"}
 +
 +
The file decrypt function provides simple accessibility to common cryptography requirements. The supported algorithms are as follows:
 +
 +
Parameter 1: the location of the file to be encrypted
 +
 +
Parameter 2: the location of the newly created encrypted file.
 +
 +
Parameter 3: the Algorithm:
 +
 +
*AES (from 16 to 32 chars key length)
 +
*ARCFOUR (from 8 to 32 chars key length)
 +
*BLOWFISH (from 4 to 56 chars key length)
 +
*DES (8 chars key length)
 +
*DESEDE (8, 16 or 24 chars key length)
 +
*RC2 (variable upto 128 chars key length)
 +
 +
Parameter 4: the key to use for decryption see above for valid key lengths
 +
<hr/>
  
 
====HTML Utitlity Functions====
 
====HTML Utitlity Functions====
=====&htmlEncode{HTML STRING}=====
+
=====HTML Encode=====
 +
Format: &htmlEncode{HTML STRING}
 +
 
 
Encodes a string of HTML, replacing any non-alphanumerics with their entity reference equivalent.
 
Encodes a string of HTML, replacing any non-alphanumerics with their entity reference equivalent.
 
<pre>&htmlEncode{"I was wondering & found a £1 coin!"}</pre> Returns  
 
<pre>&htmlEncode{"I was wondering & found a £1 coin!"}</pre> Returns  
  <nowiki>I was wondering &-a-m-p-; found a &-p-o-u-n-d-;1 coin&-#-3-3-; Dashes inserted to explain, actual function does not insert dashes</nowiki>
+
  <nowiki>I was wondering &-a-m-p-; found a &-p-o-u-n-d-;1 coin&-#-3-3-; *Dashes inserted to explain, actual function does not insert dashes</nowiki>
 +
<hr/>
 +
 
 +
=====URL Decode=====
 +
Format: &urlDecode{URLEncodedText}
  
=====&urlDecode{URLEncodedText}=====
 
 
Utility function for HTML form decoding. Decodes a String from the application/x-www-form-urlencoded MIME format.
 
Utility function for HTML form decoding. Decodes a String from the application/x-www-form-urlencoded MIME format.
  
 
To conversion process is the reverse of that used by the urlEncode{} function. It is assumed that all characters in the encoded string are one of the following: "a" through "z", "A" through "Z", "0" through "9", and "-", "_", ".", and "*". The character "%" is allowed but is interpreted as the start of a special escaped sequence.
 
To conversion process is the reverse of that used by the urlEncode{} function. It is assumed that all characters in the encoded string are one of the following: "a" through "z", "A" through "Z", "0" through "9", and "-", "_", ".", and "*". The character "%" is allowed but is interpreted as the start of a special escaped sequence.
 +
<hr/>
 +
 +
=====URL Encode=====
 +
Format: &urlEncode{STING_TO_ENCODE}
  
=====&urlEncode{STING TO ENCODE}=====
 
 
Utility function for HTML form encoding. Converts a String to the application/x-www-form-urlencoded MIME format.
 
Utility function for HTML form encoding. Converts a String to the application/x-www-form-urlencoded MIME format.
  
Line 387: Line 483:
  
 
The recommended encoding scheme to use is UTF-8. However, for compatibility reasons, if an encoding is not specified, then the default encoding of the platform is used.
 
The recommended encoding scheme to use is UTF-8. However, for compatibility reasons, if an encoding is not specified, then the default encoding of the platform is used.
 +
<hr/>
  
 
====JSON Functions====
 
====JSON Functions====
 +
The following functions do basic operations on JSON formats, to parse a JSON format into a data table use the [[JSON Node]] to create JSON formats then you would use the [[Custom Data Formatter Standard Option]].
 +
=====JSON To XML=====
 +
Format: &JSONToXML{JSON_STRING}
  
=====&JSONToXML{JSON STRING}=====
 
 
Converts a JSON format document into XML.
 
Converts a JSON format document into XML.
'''Place the JSON into a variable first, this will place it into an effective CDATA section'''
+
'''Place the JSON string into a variable first, this will place it into an effective CDATA section'''
 
Create a Varible called ${jsondata} and populated the JSON data into it.
 
Create a Varible called ${jsondata} and populated the JSON data into it.
 
e.g. ${jsondata} would contain <pre>{"menu": {
 
e.g. ${jsondata} would contain <pre>{"menu": {
Line 409: Line 508:
 
<menuitem><value>Close</value><onclick>CloseDoc()</onclick></menuitem></popup><value>File</value></menu>
 
<menuitem><value>Close</value><onclick>CloseDoc()</onclick></menuitem></popup><value>File</value></menu>
 
</pre>
 
</pre>
=====&XMLToJSON{XML STING}=====
+
<hr/>
 +
 
 +
=====XML To JSON=====
 +
Format: &XMLToJSON{XML_STRING}
 +
 
 
Converts an XML document into JSON format.
 
Converts an XML document into JSON format.
  
Line 433: Line 536:
 
  "value": "File"
 
  "value": "File"
 
}}</pre>
 
}}</pre>
 +
<hr/>
 +
 
====Miscellaneous Functions====
 
====Miscellaneous Functions====
=====&inspectContext{CONTEXT VALUE}=====
+
=====Inspect Context=====
 +
Format: &inspectContext{CONTEXT_VALUE}
 +
 
 
Inspects the current Presence Context and returns the value of the property specified in the first parameter. The property can be a dot separated list of objects and properties, for example, some common usages may be:
 
Inspects the current Presence Context and returns the value of the property specified in the first parameter. The property can be a dot separated list of objects and properties, for example, some common usages may be:
  
Line 441: Line 548:
 
data.rowCount - returns the number of rows in the current data table
 
data.rowCount - returns the number of rows in the current data table
  
taskMode - returns the current mode of the task as a number (see PresenceContext API)
+
taskMode - returns the current mode of the task as a number (see [[Presence Context]])
  
 
container.topLeveltask.taskName - the name of the currently running (top level) task
 
container.topLeveltask.taskName - the name of the currently running (top level) task
  
container.nestedTask.taskName - the name of the currently runnign (nested) task
+
container.nestedTask.taskName - the name of the currently running (nested) task
  
 
If an asterisk is specified instead of a property name, all of the available properties will be returned as a comma-separated list. For example:
 
If an asterisk is specified instead of a property name, all of the available properties will be returned as a comma-separated list. For example:
Line 453: Line 560:
 
<pre>userContext,timeZone,data,taskMode,container,executionPath,localVariables,currentRunner,universalVariables,replaceNullColumns,
 
<pre>userContext,timeZone,data,taskMode,container,executionPath,localVariables,currentRunner,universalVariables,replaceNullColumns,
 
replaceNonNullColumns,globalVariablePassword,currentTaskElement,threadNumber,variables,class,</pre>
 
replaceNonNullColumns,globalVariablePassword,currentTaskElement,threadNumber,variables,class,</pre>
 +
<hr/>
 +
 +
=====Is Null=====
 +
Format: &isNull{TEST_VALUE, RETURN_VAL_IF_TRUE}
  
=====&isNull{VALUE, RETURN VAL IF TRUE}=====
 
 
Tests if first parameter is null (empty) and returns second parameter if it is. Otherwise returns first parameter.
 
Tests if first parameter is null (empty) and returns second parameter if it is. Otherwise returns first parameter.
  
 
<pre>&isNull{"", "it was null"}</pre> Returns "it was null"  
 
<pre>&isNull{"", "it was null"}</pre> Returns "it was null"  
 
<pre>&isNull{"i'm here!", "it was null"}</pre> Returns "i'm here!".
 
<pre>&isNull{"i'm here!", "it was null"}</pre> Returns "i'm here!".
 +
<hr/>
 +
 +
=====Read AS400 Data Area=====
 +
Format: &ReadAS400DataArea{SERVER, USERNAME, PASSWORD, LIBRARY, DATAAREA}
 +
 +
Reads a data area on the IBM Midrange iSeries/AS400 and Returns the value.
 +
<hr/>
 +
 +
=====Tiff Page Count=====
 +
Format: &TiffPageCount{TIFFBYTES}
 +
 +
Determines the number of pages in the tiff image passed to the function.
 +
 +
Parameter 1: The Tiff image '''ByteArray'''
 +
 +
Returns: the number of pages in the TIFF supplied.
 +
<hr/>
 +
 +
===== Contains =====
 +
Format: &contains{FIND_STING, SEARCH_STRING}
 +
 +
Check to see if a string contains another string. both are converted to lowercase. if the string is found then the starting position of that string is returned otherwise false is returned.
 +
<hr/>
 +
 +
===== Convert TIFF to PNG =====
 +
Format: &convertTiffToPng{TIFFBYTES,SCALE,PAGE_NUMBER}
 +
 +
Converts a TIFF stream into a PNG stream.
 +
 +
Parameter 1: The '''byte array''' variable of the entire TIFF
 +
Parameter 2: Scale (1 = full size)
 +
Parameter 3: Page number
 +
<hr/>
 +
 +
===== Format Duration =====
 +
Format: &formatDuration{DURATION}
 +
 +
Formats a duration (specified in seconds or minutes) as hours, minutes and seconds.
 +
 +
Duration Examples:
 +
 +
8273s = 02:17:53
 +
 +
149s = 00:02:29
 +
 +
228m = 03:48:00
 +
 +
60m = 01:00:00
 +
<hr/>
 +
 +
===== Format Excel Date=====
 +
Format: &formatXlsDate{DATE, CENT}
 +
 +
Formats a date from a non standard date string to dd/MM/yyyy
 +
 +
First parameter is the date
 +
 +
Second parameter is the century
 +
 +
e.g. 12/2/07 becomes 12/02/2007
 +
 +
Also if the year is first it will swap it around.
 +
<hr/>
 +
 +
===== FTP Delete =====
 +
Format: ftpDelete{RESOURCEID,PATH}
 +
 +
Deletes a file from an FTP server
 +
 +
Param 1: The Unique ID of the FTP resource
 +
 +
Param 2: The Path of the file to be deleted
 +
 +
You can find out the resource ID of the FPT server resource by using a SQL on the Presence Internal Database.
 +
<hr/>
 +
 +
===== JAMES SMTP SERVER COMMAND =====
 +
Format: &jamesAdmin{SERVER, PORT, USERNAME, PASSWORD, COMMAND}
 +
 +
Logs on to James admin server, sends a command and returns the response.
 +
<hr/>
 +
 +
===== MD5 =====
 +
Format: &md5{STRING}
 +
 +
Creates a MD5 Hash from a string
 +
 +
<pre>&md5{"my string here but it will be much longer than the hash, this type of hash is widely used for sending secrete keys"}</pre> Returns "292be0ab57c86dea40d449d0a5f504de"
 +
 +
=====iSeries/AS400 Command=====
 +
Format: &AS400CMD{SERVER, USERNAME, PASSWORD, COMMAND, IGNORE ERRORS, PARM+}
 +
 +
Calls a program on an AS400 / iSeries as it is now known.
 +
 +
Parameters
 +
 +
parm 1 = System Host Name or IP address
 +
 +
parm 2 = User ID
 +
 +
parm 3 = Password
 +
 +
parm 4 = Cmd to call e.g call pgm(qgpl/myclpgm)
 +
 +
parm 5 = Ignore program errors ("true" or "false")
 +
 +
parm 6-99 string values for the parmeters.
 +
 +
e.g. &AS400CMD{"MYAS400","userid","password","call pgm(QGPL/MYCL)","false"}
 +
will call the program without passing any parameters
 +
 +
&AS400CMD{"MYAS400","userid","password","call pgm(QGPL/MYCL)","false",":VAR{ORDERID}",":VAR{QUANTITY}",":VAR{PRODUCT}"}
 +
will call the program for each row in the data table, with values from a previous presence query.
 +
<hr/>
  
 
====Numeric Functions====
 
====Numeric Functions====
=====&byteString{BYTE}=====
+
=====Byte String=====
 +
Format: &byteString{BYTE}
 +
 
 
This converts Presence's internal byte storage mechanism into the correct format for external applications.
 
This converts Presence's internal byte storage mechanism into the correct format for external applications.
 
Specifically, 128 is subtracted from the value of each byte.
 
Specifically, 128 is subtracted from the value of each byte.
'''Function cannot be tested'''
+
'''Function cannot be tested, will only work during runtime'''
=====&divide{VAL1,VAL2}=====
+
<hr/>
 +
 
 +
=====Divide=====
 +
Format: &divide{VAL1,VAL2}
 +
 
 
Divides 1st parameter by 2nd parameter and returns the result.
 
Divides 1st parameter by 2nd parameter and returns the result.
  
 
<pre>&divide{10,5}</pre> Returns 2.
 
<pre>&divide{10,5}</pre> Returns 2.
 +
<hr/>
 +
 +
=====Eval=====
 +
Format: &eval{EXPRESSION}
  
=====&eval{EXPRESSION}=====
 
 
Evaluates the expression in argument 1 and returns the logical result.
 
Evaluates the expression in argument 1 and returns the logical result.
  
Line 477: Line 710:
 
<pre>&eval{"6/2"}</pre> Returns 3
 
<pre>&eval{"6/2"}</pre> Returns 3
  
eval also supports the following constants and functions  
+
The following Operators are supported:
 +
*||
 +
*xor
 +
*or
 +
*mod
 +
*and
 +
*^
 +
*>>>
 +
*>>
 +
*>=
 +
*>
 +
*==
 +
*<>
 +
*<=
 +
*<<
 +
*<
 +
*/
 +
*-
 +
*+
 +
*<nowiki>**</nowiki>
 +
*<nowiki>*</nowiki>
 +
*&&
 +
*%
 +
*!=
 +
 
 +
eval also supports the following functions:
 +
*varr
 +
*var
 +
*trunc
 +
*tanh
 +
*tan
 +
*sum
 +
*stddev
 +
*sqrt
 +
*sinh
 +
*sin
 +
*sign
 +
*sech
 +
*sec
 +
*round
 +
*random
 +
*rad
 +
*pow
 +
*permr
 +
*perm
 +
*min
 +
*max
 +
*log2
 +
*log10
 +
*log
 +
*hypot
 +
*frac
 +
*floor
 +
*fact
 +
*exp2
 +
*exp10
 +
*exp
 +
*deg
 +
*cur
 +
*csch
 +
*csc
 +
*count
 +
*coth
 +
*cot
 
*cos
 
*cos
*sin
+
*combr
 +
*comb
 
*ceil
 
*ceil
*floor
+
*avg
*PI
+
*atanh
*E
+
*atan2
*sqrt
+
*atan
 +
*asinh
 +
*asin
 +
*asech
 +
*asec
 +
*acsch
 +
*acoth
 +
*acot
 +
*acosh
 +
*acos
 +
*abs
 +
 
 +
The following constants are supported:
 +
 
 +
*TB = 1099511627776L
 +
*STEFAN_BOLTZMANN = 5.6704E-8
 +
*SPEED_OF_LIGHT = 299792458
 +
*RYDBERG = 10973731.568549
 +
*PYTHAGORAS = Math.sqrt(2)
 +
*PROTON_MASS =1.67262158E-27
 +
*PROTON_ELECTRON_MASS_RATIO = 1836.1526675
 +
*PLANCK = 6.62606876E-34
 +
*PI = Math.PI
 +
*NEWTON =6.673E-11
 +
*MOLAR_GAS = 8.314472
 +
*MIN_INT = Integer.MIN_VALUE
 +
*MIN_DEC = Double.MAX_VALUE
 +
*MB = 1048576
 +
*MAX_INT = Integer.MAX_VALUE
 +
*MAX_DEC = Double.MAX_VALUE
 +
*MAGNETIC_FLUX = 2.067833636E-15
 +
*MAGNETIC = 4E-7 * Math.PI
 +
*MADELUNG = 2.0531987328
 +
*KHINTCHINE = 2.685452001
 +
*KB = 1024
 +
*INVERSE_FINE_STRUCTURE = 137.03599976
 +
*IMAGINARY_UNIT = Math.sqrt(-1)
 +
*GRAVITY = 9.80665
 +
*GB = 1073741824
 +
*FINE_STRUCTURE = 7.297352533E-3
 +
*FEIGENBAUM = 2.50290787509589282228390287272909
 +
*FARADAY = 96485.3415
 +
*EULER = 0.57721566490153286060651209008240243104215933593992
 +
*ELEMENTARY_CHARGE = 1.602176462E-19
 +
*ELECTRON_VOLT = 1.602176462E-19
 +
*ELECTRON_MASS = 9.10938188E-31
 +
*ELECTRIC_CONSTANT = 8.854187817E-12
 +
*E = Math.E
 +
*CONDUCTANCE_QUANTUM = 7.748091696E-5
 +
*CATALAN = 0.915965594
 +
*BOLTZMANN = 1.3806503E-23
 +
*AVOGADRO = 6.02214199E+23
 +
*ATOMIC_MASS = 1.66053873E-27
 +
*APERY = 1.20205690315959428539973816151144999076498629234049
 +
<hr/>
 +
 
 +
=====Hex Value=====
 +
Format: &hexVal{NUMBER}
  
=====&heVal{NUMBER}=====
 
 
Returns the hexidecimal value of the number passed in parameter 1.  
 
Returns the hexidecimal value of the number passed in parameter 1.  
 
<pre>&hexVal(255)</pre> Returns FF
 
<pre>&hexVal(255)</pre> Returns FF
 +
<hr/>
 +
 +
=====Multiply=====
 +
Format: &multiply{VAL+}
  
=====&multiply{VAL+}=====
 
 
Multiplies all parameters and returns the result.
 
Multiplies all parameters and returns the result.
 
<pre>&multiply{1,5,8}</pre> Returns 40
 
<pre>&multiply{1,5,8}</pre> Returns 40
 +
<hr/>
 +
 +
=====Percent=====
 +
Format: &percent{PERCENTAGE,VALUE}
  
=====&percent{PERCENTAGE,VALUE}=====
 
 
Returns the first argument expressed as a percentage of the second.
 
Returns the first argument expressed as a percentage of the second.
  
 
<pre>&percent{10,20}</pre> Returns 50
 
<pre>&percent{10,20}</pre> Returns 50
 +
<hr/>
 +
 +
=====Random=====
 +
Format: &random{MAX}
  
=====&random{MAX}=====
 
 
Returns a random number between zero and the argument specified
 
Returns a random number between zero and the argument specified
 
<pre>&random{50}</pre> Could Return 49.21655577700601
 
<pre>&random{50}</pre> Could Return 49.21655577700601
 +
<hr/>
 +
 +
=====Round=====
 +
Format: &round{NUMBER}
  
=====&round{NUMBER}=====
 
 
Round the parameter to the nearest whole number. See java.lang.Math.round(double) for contract.
 
Round the parameter to the nearest whole number. See java.lang.Math.round(double) for contract.
  
Line 509: Line 874:
  
 
<pre>&round{5.791}</pre> Returns 6
 
<pre>&round{5.791}</pre> Returns 6
 +
<hr/>
 +
 +
=====Subtract=====
 +
Format: &subtract{VAL1,VAL2}
  
=====&subtract{VAL1,VAL2}=====
 
 
Subtracts argument 2 from argument 1 and returns the result.
 
Subtracts argument 2 from argument 1 and returns the result.
  
 
<pre>&subtract{30,5}</pre> Returns 25
 
<pre>&subtract{30,5}</pre> Returns 25
 +
<hr/>
 +
 +
=====Sum=====
 +
Format: &sum{VAL+}
  
=====&sum{VAL+}=====
 
 
Adds all the parameters and returns the result.
 
Adds all the parameters and returns the result.
  
 
<pre>&sum{1,5,8,9,1225,1551,998,1005}</pre> Returns 4802
 
<pre>&sum{1,5,8,9,1225,1551,998,1005}</pre> Returns 4802
 +
<hr/>
  
 
====Presence Internal Functions====
 
====Presence Internal Functions====
=====&currentTaskName{}=====
+
=====Current Task Name=====
 +
Format: &currentTaskName{}
 +
 
 
Returns the current task name. No parameters required.
 
Returns the current task name. No parameters required.
 +
 
====Print Functions====
 
====Print Functions====
=====&pdfprintfunction{PDF FILE, PRINTER UNC, COPIES, FROM PAGE, TO PAGE, THROW ERROR, DUPLEX, SHORT EDGE BINDING}=====
+
=====PDF Print=====
 +
Format: &pdfprintfunction{PDF FILE, PRINTER UNC, COPIES, FROM PAGE, TO PAGE, THROW ERROR, DUPLEX, SHORT EDGE BINDING}
 +
 
 
Returns either Printed,Failed to print or throws an error
 
Returns either Printed,Failed to print or throws an error
  
Line 544: Line 921:
  
 
8:Short Edge Binding 'True' or 'False' (optional,default is false) applies with duplex printing
 
8:Short Edge Binding 'True' or 'False' (optional,default is false) applies with duplex printing
 +
<hr/>
 +
 
====Security Functions====
 
====Security Functions====
=====&ValidateWindowsUserAndPassword{DOMAIN/USER, PASSWORD, AD SERVER PORT, CLASS FACTORY}=====
+
=====Validate Windows User And Password=====
 +
Format: &ValidateWindowsUserAndPassword{DOMAIN/USER, PASSWORD, AD SERVER PORT, CLASS FACTORY}
 +
 
 
Validates windows user and password details are valid
 
Validates windows user and password details are valid
 
using Windows Acitve Directory and Fast Binding.
 
using Windows Acitve Directory and Fast Binding.
Line 558: Line 939:
 
4:Factory class
 
4:Factory class
 
<pre>&ValidateWindowsUserAndPassword{"mydomain\robert", "password", "ldap://adserver:389", "com.sun.jndi.ldap.LdapCtxFactory"}</pre> Returns false as this is not the correct password.
 
<pre>&ValidateWindowsUserAndPassword{"mydomain\robert", "password", "ldap://adserver:389", "com.sun.jndi.ldap.LdapCtxFactory"}</pre> Returns false as this is not the correct password.
 +
<hr/>
 +
 +
=====Create SHA Hash=====
 +
Format: &createSHAHash{VALUE,ITERATIONS}
  
=====&createSHAHash{VALUE,ITERATIONS}=====
 
 
A secure one-way hash function that converts the input value into a fixed length hash value, using an SHA (secure hash algorithm) digest.
 
A secure one-way hash function that converts the input value into a fixed length hash value, using an SHA (secure hash algorithm) digest.
  
Line 569: Line 953:
 
<pre>&createSHAHash{"Input Value"}</pre> Returns a4c9cbd6e25fd7ae420dbe02ecf40785fb89099c
 
<pre>&createSHAHash{"Input Value"}</pre> Returns a4c9cbd6e25fd7ae420dbe02ecf40785fb89099c
 
<pre>&createSHAHash{"Input Value",3}</pre> Returns a9676f44e0ae8b65c393a1463e97d20552b93d33
 
<pre>&createSHAHash{"Input Value",3}</pre> Returns a9676f44e0ae8b65c393a1463e97d20552b93d33
 +
<hr/>
 +
 +
=====Decrypt=====
 +
Format: &decrypt{ENCRYPTED TEXT, KEY(optional)}
  
=====&decrypt{ENCRYPTED TEXT, KEY(optional)}=====
 
 
Decrypts the encrypted value specified to provide the original text value. Uses the Triple DES algorithm and a key that is unique to your Presence installation.
 
Decrypts the encrypted value specified to provide the original text value. Uses the Triple DES algorithm and a key that is unique to your Presence installation.
  
Line 576: Line 963:
 
Parameter 2 (optional): Encryption key
 
Parameter 2 (optional): Encryption key
 
Result: A decrypted value
 
Result: A decrypted value
=====&encrypt{TEXT TO ENCRYPT, KEY(optional)}=====
+
<hr/>
 +
 
 +
=====Encrypt=====
 +
Format: &encrypt{TEXT TO ENCRYPT, KEY(optional)}
 +
 
 
Encrypts the specified value using a triple DES cipher algorithm. The key used is unique to each Presence installation. The resulting value can be decrypted using the decrypt{String} function.
 
Encrypts the specified value using a triple DES cipher algorithm. The key used is unique to each Presence installation. The resulting value can be decrypted using the decrypt{String} function.
  
Line 583: Line 974:
  
 
Parameter 2 (optional): A string to use as an encryption key.
 
Parameter 2 (optional): A string to use as an encryption key.
 +
<hr/>
  
 
====String Functions====
 
====String Functions====
 +
=====Chop Text=====
 +
Format: &ChopText{TEXT, MAXLENGTH, DELIMITER, POPINTOVAR1, POPINTOVAR2}
 +
 +
This function splits a long string of text into two parts, looking for a delimiter near the middle of the string.
 +
 +
The first and second half are placed into variables named in parameters 4 and 5.
 +
 +
<pre>&ChopText{"10 Coppergate Mews, 109-111 Brighton Road, Surbiton, Surrey, United Kingdom KT6 5NE", 60, ",", ${test1}, ${test2}}</pre>
 +
 +
Returns 41 (chop position), populates ${test1} with "10 Coppergate Mews, 109-111 Brighton Road" and populates ${test2} with "Surbiton, Surrey, United Kingdom KT6" 5NE
 +
<hr/>
 +
 +
=====Base 64 Decode=====
 +
 +
Format: &base64decode{BASE64STRING}
 +
 +
Decodes a Base64 String and converts it into a byte array.
 +
 +
<pre>&base64decode{"dGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2c="}</pre> Returns "74686520717569636b2062726f776e20666f78206a756d706564206f76657220746865206c617a7920646f67"
 +
<hr/>
 +
 +
=====Base 64 Encode=====
 +
Format: &base64encode{BASE64STRING}
 +
 +
Converts the specified byte array (hex) into BASE64, returns the output.
 +
 +
<pre>&base64encode{"74686520717569636b2062726f776e20666f78206a756d706564206f76657220746865206c617a7920646f67"}</pre> Returns "dGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2c="
 +
<hr/>
 +
 +
=====Capitalises Words=====
 +
Format: &capitaliseWords{STRING}
 +
 +
Capitalises the first letter of each word, where words are expected to be separated by space (" ") characters.
 +
 +
<pre>&capitaliseWords{"mr smith"}</pre> Returns "Mr Smith"
 +
<hr/>
 +
 +
===== Concatenate=====
 +
Format: &concat{VALS+}
 +
 +
Concatinates any strings passed to the function.
 +
Accepts unlimited parameters.
 +
Returns a concatinated string.
 +
<pre>&concat{"hello ", "how ", "are you","?"}</pre> Returns "hello, how are you?"
 +
<hr/>
 +
 +
=====Find Text In Line=====
 +
Format: &findTextInLine{Multiline_Input_String, Regexp_Search, Return Type}
 +
 +
Locates specified text in a line of text in the first parameter.
 +
 +
<pre>
 +
&findTextInLine{"This is line 1
 +
This is line 2
 +
This is line 3", ".*3", "WHOLE_LINE"}</pre> Returns: "This is line 3"
 +
 +
<pre>
 +
&findTextInLine{"This is line 1
 +
This is line 2
 +
This is line 3", ".*1", "WHOLE_LINE"}</pre> Returns: "This is line 1"
 +
 +
Third parameter controls what's returned if a match is found:
 +
 +
WHOLE_LINE
 +
FROM_START_OF_MATCH
 +
FROM_END_OF_MATCH
 +
<hr/>
 +
 +
=====Fix File Name=====
 +
Format: &fixFileName{FILENAME}
 +
 +
Converts a filename into something sensible. Any characters other than a-z, A-Z and 0-9 are converted to an underscore (_) except for the last period (i.e. the extension)
 +
 +
<pre> &fixFileName{"a file *&%name.png"}</pre> Returns "a_file____name.png"
 +
<hr/>
 +
 +
=====Format Number=====
 +
Format: &formatNumber{NUMBER, FORMAT}
 +
 +
Formats a number specified by parameter 1 in the format specified by parameter 2. Returns the formatted number.
 +
 +
<pre>&formatNumber{123456.789, "###,###.###"}</pre> Returns "123,456.789" The hash sign (#) denotes a digit, the comma is a placeholder for the grouping separator, and the period is a placeholder for the decimal separator.
 +
 +
<pre>&formatNumber{123456.789, "###.##"}</pre> Returns "123456.79" The value has three digits to the right of the decimal point, but the pattern has only two. The format method handles this by rounding up.
 +
 +
<pre>&formatNumber{123.78, "000000.000"}</pre> Returns "000123.780" The pattern specifies leading and trailing zeros, because the 0 character is used instead of the hash sign (#).
 +
 +
<pre>&formatNumber{12345.67, "£###,###.###"}</pre> Returns "£12,345.67" The first character in the pattern is the dollar sign ($). Note that it immediately precedes the leftmost digit in the formatted output.
 +
<hr/>
 +
 +
=====Get Text From HTML(Mark-Up)=====
 +
Format: &getTExtFromHTML{MARKUP}
 +
 +
Function to remove html tags from a string.
 +
 +
Will also replace <-b-r-> <-p-> <-h1-> etc with a new line *dashes not in real example, used to stop formatting errors
 +
 +
Also replaces:-
 +
 +
&-l-t-; with a <
 +
&-g-t-; with a >
 +
&-q-u-o-t-; with a "
 +
&-a-m-p-; with a &
 +
&-n-b-s-p-; with a space *dashes not in real example, used to stop formatting errors
 +
 +
<pre>&getTextFromHTML{"<!DOCTYPE html>
 +
<html>
 +
<body>
 +
<h1>My First Heading</h1>
 +
<p>My first paragraph.</p>
 +
</body>
 +
</html>"}</pre> Returns<pre>My First Heading
 +
 +
 +
My first paragraph.</pre>
 +
<hr/>
 +
 +
===== Index Of =====
 +
Format: &indexOf{TEXT_TO_SEARCH,SEARCH_FOR_TEXT}
 +
 +
Given the string specified in the first parameter, returns the index (position) of the string specified in the second parameter. The first character is at position zero and so on. Return value is zero based.
 +
 +
If the string cannot be found -1 is returned.
 +
<pre>&indexOf{"text.to.search", "."}</pre> Returns 4
 +
<hr/>
 +
 +
=====Lower Case=====
 +
Format: &lowerCase{STRING}
 +
 +
Converts the string entered to lower case.
 +
 +
<pre>&lowerCase{"Hello R2D2!"}</pre> Returns "hello r2d2".
 +
<hr/>
 +
 +
=====Pad Left=====
 +
Format: &padLeft{STRING}
 +
 +
Left-pads the specified string with the string specified to the length specified.
 +
 +
Parameter 1: The string to pad and measure the length of.
 +
 +
Parameter 2: The string to use for padding.
 +
 +
Parameter 3: The width of the returned string.
 +
 +
<pre>&padLeft ("string", ".", 9)</pre> Returns "...string"
 +
<hr/>
 +
 +
=====&padRight=====
 +
Format: &padRight{STRING}
 +
 +
Right-pads the specified string with the string specified to the length specified.
 +
 +
Parameter 1: The string to pad and measure the length of.
 +
 +
Parameter 2: The string to use for padding.
 +
 +
Parameter 3: The width of the returned string.
 +
 +
<pre>&padRight ("string", ".", 9)</pre> Returns "string..."
 +
<hr/>
 +
 +
=====Process String=====
 +
Format: &processString{STRING}
 +
 +
Parses the string in argument one for function calls, etc. Returns the result.
 +
<hr/>
 +
 +
=====Replace=====
 +
Format: &replace{TEXT,TEXT_TO_REPLACE,REPLACE_WITH}
 +
 +
Replaces occurrence of parameter 2 with parameter 3 in string parameter 1.
 +
 +
<pre>&replace{"The quick brown fox jumps over the lazy dog", "fox", "camel"}</pre> Returns "The quick brown camel jumps over the lazy dog"
 +
<hr/>
 +
 +
=====Replace Pattern=====
 +
Format: &replacePattern{TEXT,PATTERN,REPLACEMENT_PATTERN}
 +
 +
Given the input string in Parameter 1, replaces any occurrences of the pattern specified in parameter 2 with the string in parameter 3.
 +
Input patterns follow Java Regular Expression rules - see http://www.regexr.com/ for more information on regex patterns.
 +
 +
<pre>&replacePattern{"That costs £15.00", "[a-zA-Z\s£]+", ""}</pre> Returns: "15.00". Replaces any words and the pound sign as well as white spaces.
 +
<hr/>
 +
 +
=====Split Text In Columns (Actually Rows)=====
 +
Format:&splitTextIntoColumns{TEXT, DELIMITER, COLNAME, POSITION_COL_NAME}
 +
 +
Splits the text specified in argument 1, based on the delimiter specified in argument 2. A new data column is created with the column name specified in argument 3, and the data table is appended with the new column.
 +
 +
Optional parameter 4 specifies the column name to store the position of the item. If omitted, the position is not stored.
 +
 +
<pre>&splitTextIntoColumns{"word1;word2;word3", ";", "WORDS", "POSITION"}</pre> Returns "3 new rows created" and the data table at runtime would contain 3 rows and two Columns accessed via :var{WORDS} & :var{POSITION}. A very useful function for dealing with arrays returned from http requests, etc.
 +
<hr/>
 +
 +
=====Multi Column Text Split=====
 +
Format: &multiColumnTextSplit{TEXT, DELIMITER, COLNAME1, TEXT, DELIMITER, COLNAME2, [textToSplit, delim, colname] ...}
 +
 +
Splits text in parameter one according to delimiter specified in parameter two and creates a data table column named parameter three. The three paramaters can be repeated indefinitely to create a larger data table.
 +
 +
<pre>&multiColumnTextSplit{"word1;word2;word3", ";", "WORDS", "anotherword,anotherword,anotherword",",","COL2"}</pre> Returns "3 new rows created" and the data table at runtime would contain 3 rows and two Columns accessed via :var{WORDS} & :var{COL2}. A very useful function for dealing with arrays returned from http requests, etc.
 +
<hr/>
 +
 +
=====SQL String=====
 +
Format: &sqlString{SQL_STRING_TO_CORRECT}
 +
 +
Parses the String to find any single quotes that would upset the database
 +
and replaces them with two single quotes as per SQL 92 standard
 +
 +
<pre>&sqlString{"Don't do that"}</pre> Returns "Don''t do that"
 +
<hr/>
 +
 +
=====Starts With=====
 +
Format: &stratsWith{TEXT,CHARS_TO_CHECK}
 +
 +
Tests to see if the string supplied by the first parameter begins with the string specified in the second parameter.
 +
 +
Example:
 +
 +
<pre>&startsWith{"Foobar", "Foo"}</pre> Returns "true".
 +
<pre>&startsWith{"Foobar", "Bar"}</pre> Returns "false".
 +
<hr/>
 +
 +
=====String Length=====
 +
Format: &stringLength{STRING}
 +
 +
Returns the number of characters in the specified string.
 +
 +
Parameter 1: The string to measure the length of.
 +
<pre>&stringLength{"foobar"}</pre> Returns "6".
 +
<hr/>
 +
 +
=====Sub String=====
 +
Format: &substring{STRING,START,END}
 +
 +
Returns a substring of the specified string.
 +
 +
Parameter 1: The string to get the substring of.
 +
 +
Parameter 2: The start character (first character being 1)
 +
 +
Parameter 3: The number of characters to retrieve.
 +
<pre>&substring{"foobar",1,3}</pre> Returns "foo".
 +
<hr/>
 +
 +
=====Text To Binary=====
 +
Format: &textToBinary{STRING}
 +
 +
Converts the text specified into a byte array, for inserting into a blob etc.
 +
 +
<pre>&textToBinary{"The quick brown dog"}</pre> Returns a Byte array with 19 elements.
 +
<hr/>
 +
 +
=====Trim=====
 +
Format: &trim{STRING}
 +
 +
Trims the string specified by parameter 1, removing any leading or trailing spaces and line breaks.
 +
<pre>&trim{"  spaced      "}</pre> Returns "spaced".
 +
<hr/>
 +
 +
=====Upper Case=====
 +
Format: &upperCase{STRING}
 +
 +
Converts the string entered to upper case.
 +
 +
<pre>&upperCase{"Hello R2D2!"}</pre> Returns "HELLO R2D2!".
 +
<hr/>
 +
 +
=====Wrap=====
 +
Format: &wrap{STRING,WRAP_ON_WORD,CHARS_FOR_LINE}
 +
 +
Wraps text at a specified position
 +
 +
Usage:
 +
 +
Parameter 1 = The text to wrap
 +
Parameter 2=  true or false for wrap on word
 +
Parameter 3=  Max number of Chars for a single line
 +
 +
<pre>&wrap{"The quick brown fox jumps over the lazy dog, he doesn't stop to say hello.", "false", "30"}</pre> Returns <pre>The quick brown fox jumps over
 +
the lazy dog, he doesn't stop
 +
to say hello.</pre>
 +
<hr/>
 +
 +
====Data Table Functions====
 +
=====Add Running Total=====
 +
Format: &addRunningTotal{IN_COLUMN, OUT_COLUMN}
 +
 +
Keeps a running total of a column of numbers and sets an additional column to be the current total. eg:
 +
0
 +
1
 +
2
 +
0
 +
1
 +
2
 +
3
 +
 +
Becomes:
 +
 +
0
 +
1
 +
2
 +
2
 +
3
 +
4
 +
5
 +
<hr/>
 +
 +
=====Create Pivot Table=====
 +
 +
Format: &createPivotTable {ROWFIELD, COLUMNFIELD, FACTFIELD, AGGREGATION_METHOD [, VARIABLE_NAME]}
 +
 +
Creates a pivot table (see http://en.wikipedia.org/wiki/Pivot_table) based on the current Data Table.
 +
 +
ROWFIELD: This is the field which is used as the first column.
 +
COLUMNFIELD: Additional columns are created for each value of this field.
 +
FACTFIELD: The values of the columns are setting according to this field's values.
 +
AGGREGATION_METHOD: Where multiple values exist, this is the method that should be used to generate one unique value. Possible options are:
 +
 +
- SUM - the total sum of the values
 +
- COUNT - the count of values
 +
- MEAN - the arithmetic mean of the values
 +
- STD_DEV - the standard deviation of the values
 +
- RETAIN - only uses the first value found
 +
- REPLACE - uses the last value found
 +
 +
VARIABLE_NAME: (Optional) - if specified, the resulting data table will be stored in this variable rather than replacing the existing data table.
 +
<hr/>
 +
 +
=====Append Row IDs=====
 +
 +
Format: &appendRowIds{COL_NAME(Optional)}
 +
 +
Appends a new column to the data table with a unique ID for each row of data, numbered from 1 to n where n is the number of records.
 +
 +
An optional argument can be provided to identify the column name to use. If this is ommitted a default column name of "PRESENCE_ROW_ID" is used.
 +
 +
If the column already exists it will be updated to reflect the current record positions.

Latest revision as of 11:05, 7 September 2015

Contents

About Presence Functions

Functions can be used almost anywhere a Presence Text Area is used, you know if you are in a Presence Text Area by Pressing CTRL+Space. Almost all Presence Functions will accept Presence Variables in the form of ${variable_name}, you can also embed other functions into functions e.g &round{"&random{"${maxval}"}"} would return a rounded integer rather than a double/float based on the value of the ${maxval} variable.

It is always a good idea to place quotes around any parameters within the function unless it is a numeric function that only accepts whole numbers, doing this helps to ensure the parser can recognise the start and end of the data.

Anybody can create their own Presence Functions, for more information see Function Call.

Testing Presence Functions

You can test functions using the Function Test Console

Index of Functions

This list aims to be a comprehensive list of default functions available with Presence. Please note that it is always a work in progress.

Boolean Functions

Equals String

Format: &equalsString{Paramter,Parameter}

This function compares String1 and String2. If they are equal it will return the value "true". Otherwise it will return "false".

&equalsString{"ABC","ABC"}
Returns true
&equalsString{"ABC","BC"}
Returns false
If Boolean Test

Format: &if{Boolean Param To Test, True Result, False Result}

This function performs a test on a string. If it equals "true" or "1" the value of Parameter 2 will be returned. Otherwise, value of Parameter 3 will be returned.

&if{"true", "I AM TRUE", "I AM FALSE"}
Returns "I AM TRUE"
&if{"0", "I AM TRUE", "I AM FALSE"}
Returns "I AM FALSE"

Data Functions

On Demand Task Call

Format: &onDemand{taskAlias, parameter+,parameter+,param...}

Calls an On Demand Task that is on the Live Task Queue.

taskAlias: The alias of the Task to be called, the task should be on the Live Tasks Queue #On Demand Processes

parameter+ : The Parameters to be passed (zero or more).

&onDemand{"myTask","id=5", "now=true"}

Calls the Task referenced by the alias "myTask" and sets the following variables in the target task:

${id} = 5 ${now} = true

If the task returns a magic ${response} variable that value will be populated in the variable or space you are calling the function from.


Does Column Exist On Data Table

Format: &doesColumnExist{"COL_NAME"}

Tests to see if the specified column name exists in the current Data table - returns "true" if it does or "false" if not.

Parameter 1: The column name to test


Date Functions

All date functions use format patterns defined below, these date/time format patterns are based on Java Simple Date Format, for more information see http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html

Date and Time Patterns

G Era designator e.g. "AD"

y Year e.g. yyyy="2015"; yy="15"

M Month in year e.g. M="8" (August); MM="08"; MMM="Aug" MMMM="August"

w Week in year e.g. w="33" (13/August/2015)

W Week in month e.g. W="2" (13/August/2015)

D Day in year e.g. D="225" (13/August/2015)

d Day in month e.g d="13" (13/August/2015)

F Day of week in month

E Day in week e.g. E="Thu"

a Am/pm marker

H Hour in day (0-23)

h Hour in day (1-12)

m Minute in hour

s Second in minute

S Millisecond

z Time zone e.g. z="BST"; zzzz="British Summer Time"

Z Time zone (RFC 822 time zone) e.g Z="+0100"

X Time zone (ISO 8601 time zone) e.g X="+01"; XX="+0100"; XXX="+01:00"

Get Current Date

Format: &currentDate{format, offset}

Returns: the current date in the format specified by the first parameter.

format=The date format to use to format the current date (e.g. "dd/MM/yyyy"). See #Date and Time Patterns

offset=(Optional) The offset in days (e.g. -1, 1, 2, -5)

&currentDate{"MMM/yyyy"}
Returns Aug/2015
&currentDate{"dd/MM/yyyy"}
Returns 13/08/2015 or whatever the current date is.
&currentDate{"dd/MM/yyyy",-5}
Returns 08/08/2015 (minus 5 days from the current date)
&currentDate{"dd/MM/yyyy",-3M}
Returns 13/05/2015 (minus 3 months from the current date)
&currentDate{"dd/MM/YYYY",5}
Returns 18/08/2015 (plus 5 days from the current date)
Format Date

Format: &formatDate{DATE_VALUE, input_format, output_format}

Returns: a new format for a date passed into the function on parameter 1

&formatDate{"2015-08-13","yyyy-MM-dd","dd/MM/yyyy"}
Returns 13/08/2015
&formatDate{"2015-08-13","yyyy-MM-dd","E dd MMM YYYY"}
Returns Thu 13 Aug 2015
&formatDate{"2015-08-13","yyyy-MM-dd","dd/MM/yyyy",5}
Returns 13/08/2015 (adds 5 days to the date on parameter 1)
&formatDate{"2015-08-13","yyyy-MM-dd","EEEE dd MMM YYYY"}
Returns Thursday 13 Aug 2015
Adjust Time Zone

Format: &adjustTimeZone{Date_in_originating_timezone,Format_of_date_in_param_1, Originating_timezone, Resulting_timezone, Resulting_date_format (OPTIONAL)}

This function adjusts a given date from the source timezone to another timezone. For example, an event happens in San Fransisco at 03:00 AM but the time needs to be displayed in London, which would be 11:00 AM.

&adjustTimeZone{"2013-08-02 03:00", "yyyy-MM-dd HH:mm", "US/Pacific", "Europe/London"}
Returns 2013-08-02 11:00

There is an optional 5th parameter which is the format to be used when creating the string that is returned. If it is omitted then the format specified in the 2nd parameter is used.


Calculate Date Ignoring Weekends

Format :&calcDateIgnoreWeekends{DATE, FORMAT, TIMEADJUST, IGNOREWEEKENDS}

Using the start date DATE, formatted according to rules specified in FORMAT, add the number of days* specified in TIMEADJUST. IGNOREWEEKENDS should be set to "true" if weekends are ignored - in which case, if weekend days are encountered while adding minutes, skip to Monday.

Therefore if IGNOREWEEKENDS = true: Wednesday 22nd June 2011 @ 12:00 + 5 days = Wednesday 29th June 2011 @ 12:00

TIMEADJUST defaults to days, however other time periods can be specified by appending a letter, e.g.:

5000S = 5000 milliseconds

60s = 60 seconds

60m = 60 minutes

24H = 24 hours

1M = 1 month

1y = 1 year

Note that for months and years the IGNOREWEEKENDS attribute will be discarded - weekends will never be taken into account.


Calculate Runtime Basic

Format: &calcNextRuntimeFromBasic{Run_on_First_of_Month, Run_on_Last_of_Month, Run_On_Date, Run_Time(HH:mm)}

Gets Next Runtime From Date in milliseconds, only valid in a running task - can't be tested

The parameters for this are retrieved from the top info of the schedule info page. ie, Run on First of Month string (true/false) Run on Last of Month string (true/false) Run On Date string (1-31) Run Time (HH:MM) string

&calcNextRuntimeFromBasic{"true", "false", "0", "09:00"}
Returns 1441094400000
Calulate Runtime From Day

Format: &calcNextRuntimeFromDay{Run_on_First_of_Month, Run_on_Last_of_Month, Run_On_Date, Run_Time(HH:mm)}

Get Next Runtime From Day(s)

The parameters for this are retrieved from the bottom of the schedule info page.

This uses the context, so the data table should contain the following:-

Integer "DAYOFWEEK" 1-Sunday 2=Monday etc Integer "FREQUENCY" 0=Every, 1=First, 2=Last Integer "INTERVALMINUTES" eg 30 String "STARTTIME" eg 09:00 String "ENDTIME" eg 13:00


Calculate Timezone Difference Hours

Format: &calcTimezoneDifferenceHours{TIMEZONE}

Calculates the time difference between the system timezone and the specified timezone, returns difference in hours.

Example, if system running in GMT:

&calcTimezoneDifferenceHours{"EST"}

Will return -5 (ie GMT-5).


Current Time

Format: &currentTime{TIMEFORMAT}

Returns: the current time in the format specified by the first parameter, offset by the number of minutes in the second parameter (default is zero).

Parameter 1: The time format to use to format the current time (eg "HH:mm:ss" for 24 hour, "h:mm:ss a" for 12 hour + am/pm). Parameter 2: (Optional) The offset in minutes.

Examples assume current time is 15:30:00 PM

&currentTime{"HH:mm:ss"}
Returns (eg) "15:30:00"
&currentTime{"HH:mm", -60}
Returns "14:30" (60 minutes in the past)
&currentTime{"h.mm a", 30}
Returns "4.00 PM" (half an hour in the future)
Current Time Stamp

Format: &currentTimeStamp{"OPTIONAL"}

Returns: the current time in milliseconds, offset by the number of minutes in the parameter (default is zero).


Date In Milliseconds

Format: &dateInMillis{DATE,FORMAT}

Converts a given date into milliseconds from the 1970s epoch.

&dateInMillis{"01/01/2001", "dd/MM/yyyy"}
Returns 978307200000
Format Milliseconds

Format: &formatMilliseconds{MILLISECONDS,FORMAT}

Returns a millisecond date in a readable format specified.

&formatMilliseconds{"978307200000", "dd/MM/yyyy"}
Returns 01/01/2001
&formatMilliseconds{"0", "dd MMM yyyy"}
Returns the epoch date "01 Jan 1970"
Format TF400 Date

Format: &formatTF400Date{DATE, RETURN_FORMAT}

Formats a TF400 date numeric in the format specified.

TF400 dates are a LONG type in the following format:

HHmmssyyyyMMdd

They may be 13 or 14 digits depending on whether the hour part is before 12 PM.

This function prepends a trailing zero if necessary and returns the date as a String in the format specified.

&formatTF400Date{"9342220130325", "dd MMM yyyy 'at' HH:mm:ss"}
Returns 25 Mar 2013 at 09:34:22
Milliseconds To Date

Format: &millisToDate{MILLISECONDS,DATE FORMAT}

Coverts the milliseconds parameter to a formatted date string, same as #Format Milliseconds, retained for backwards compatibility

&millisToDate{"978307200000", "yyyy-MM-dd'T'HH:mm:ss.SSSZ"}
Returns 2001-01-01T00:00:00.000+0000
Parse Seven Digit Date

Format: &parseSevenDigitDate{DATE,NEW FORMAT}

Attempts to parse the seven digit date set in parameter 1. If this is successful, the function will then reformat the date in the date specified by parameter 2.

- Parameter 1: The seven-digit date to parse (eg "1032403") - Parameter 2: The Java date format to use for formatting. Eg "dd-MM-yyyy".

&parseSevenDigitDate{"1150101", "dd-MM-yyyy"}
Returns 01-01-2015
Seven Digit Date

Format: &sevenDigitFormat{DATE,FORMAT OF DATE}

Creates a seven digit string representation of the specified date, where the first character represents the century, ie 0 for years ending in 47-99 and 1 for years ending in 00-46.

Complete format is CYYMMDD.

Parameter 1: The date string to be parsed and reformatted Parameter 2: The date format to use in parsing the input date.

 &sevenDigitFormat{"23 Mar 2003", "dd MMM yyyy"}
Returns "1030323"
Validate Date

Format: &validatedate{DATE,FORMAT OF DATE, CHECK FUTURE} Pass it a date string and a date format.

Returns 1 if valid, else 0.

Can also pass it a true to check that the date is not in the future.


Excel Functions

Update Excel Cell

Format: &updateXLCell{PATH,SHEET INDEX,ROW,CELL,VALUE}

Updates a specified cell in an Excel worksheet.

Parameters:

1: Path of Excel file 2: Sheet index (zero based) 3: Row number (zero based) 4: Cell number (zero based) 5: New value

Returns the old value.


File Operations

Add files To Zip

Format: &addfilesToZip{DIR,ZIP FILE}

Creates a zip archive.

Argument #1: The directory containing files to be added to the archive Argument #2: The target zip file name.

Files are added recursively, ie subdirectory contents are also added. If the target zip file already exists it will be renamed to [old_file_name].yyyymmdd


Extract Text from PDF File

Format: &extractTextFromPdf{FILE}

Extracts text from a searchable PDF file. Some PDF files may not actually contain text even though it looks that way, instead you may get an embedded scanned image and this function will not be able to read a scanned image as text.

Useage: &extractTextFromPdf {"FILE_LOCATION"}


Does File Exist

Format: &fileExists{FILE LOCATION}

Tests whether the specified file exists. If the file exists the function returns "TRUE", otherwise returns "FALSE".


File Length

Format: &fileLength{"FILE_LOCATION"}

Returns the length of the specified file, or -1 if it doesn't exist or if the path specified is a folder.


Get File Value

Format: &getFileValue{FILE,KEY}

Gets a value from a INI or Properties type file.

Returns a String for the Key value specified in Parmeter2

Example: &getFileValue{"c:\myfile.ini","MYKEY"}

See also : #Set File Value


Lookup MIME Type By Extension

Format: &lookupMimeByExtention{"FILENAME_OR_EXTENSION"}

Attempts to retrieve the MIME type for the file name specifies. Uses the Java MimetypesFileTypeMap so is incomplete.

&lookupMimeByExtension{".pdf"}
Returns application/octet-stream
Measure Image

Format: &measureImage{IMAGE_FILE}

Measures the width and height of image file specified in arg 1.

Returns a string of the format:

width=n,height=n


Set File Value

Format: &setFileValue{FILE,KEY,VALUE}

Sets a value in a INI or Properties type file.

Returns success string

Example: &setFileValue{"c:\myfile.ini","MYKEY", "MYVALUE"}

See also : #Get File Value


Touch File

Format: &touchFile{FILE}

Sets the last modified date of the file in parameter 1 to be the current system time.


Unzip File

Format: &unzip{ZIP,TO FOLDER}

Unzips the archive specified in argument #1 into the directory specified in argument #2.

Example: unzip{"/archive.zip", "/extracted/"}

Extracts the archive "/archive.zip" into the directory "/extracted". If the directory does not already exist it will be created at runtime.


Encrypt File

Format: &fileEncrypt{"/path/file.ext","/path/new_encrypted_file.enc","algorithm","key"}

The file encrypt function provides simple accessibility to common cryptography requirements. The supported algorithms are as follows:

Parameter 1: the location of the file to be encrypted

Parameter 2: the location of the newly created encrypted file.

Parameter 3: the Algorithm:

  • AES (from 16 to 32 chars key length)
  • ARCFOUR (from 8 to 32 chars key length)
  • BLOWFISH (from 4 to 56 chars key length)
  • DES (8 chars key length)
  • DESEDE (8, 16 24 chars key length)
  • RC2 (variable upto 128 chars key length)

Parameter 4: the key to use for encryption see above for valid key lengths


Decrypt File

Format: &fileDecrypt{"/path/encrypted_file.enc","/path/decrypted_file.ext","algorithm","key"}

The file decrypt function provides simple accessibility to common cryptography requirements. The supported algorithms are as follows:

Parameter 1: the location of the file to be encrypted

Parameter 2: the location of the newly created encrypted file.

Parameter 3: the Algorithm:

  • AES (from 16 to 32 chars key length)
  • ARCFOUR (from 8 to 32 chars key length)
  • BLOWFISH (from 4 to 56 chars key length)
  • DES (8 chars key length)
  • DESEDE (8, 16 or 24 chars key length)
  • RC2 (variable upto 128 chars key length)

Parameter 4: the key to use for decryption see above for valid key lengths


HTML Utitlity Functions

HTML Encode

Format: &htmlEncode{HTML STRING}

Encodes a string of HTML, replacing any non-alphanumerics with their entity reference equivalent.

&htmlEncode{"I was wondering & found a £1 coin!"}
Returns
I was wondering &-a-m-p-; found a &-p-o-u-n-d-;1 coin&-#-3-3-; *Dashes inserted to explain, actual function does not insert dashes

URL Decode

Format: &urlDecode{URLEncodedText}

Utility function for HTML form decoding. Decodes a String from the application/x-www-form-urlencoded MIME format.

To conversion process is the reverse of that used by the urlEncode{} function. It is assumed that all characters in the encoded string are one of the following: "a" through "z", "A" through "Z", "0" through "9", and "-", "_", ".", and "*". The character "%" is allowed but is interpreted as the start of a special escaped sequence.


URL Encode

Format: &urlEncode{STING_TO_ENCODE}

Utility function for HTML form encoding. Converts a String to the application/x-www-form-urlencoded MIME format.

When encoding a String, the following rules apply:

The alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain the same.

The special characters ".", "-", "*", and "_" remain the same.

The space character " " is converted into a plus sign "+".

All other characters are unsafe and are first converted into one or more bytes using some encoding scheme. Then each byte is represented by the 3-character string "%xy", where xy is the two-digit hexadecimal representation of the byte.

The recommended encoding scheme to use is UTF-8. However, for compatibility reasons, if an encoding is not specified, then the default encoding of the platform is used.


JSON Functions

The following functions do basic operations on JSON formats, to parse a JSON format into a data table use the JSON Node to create JSON formats then you would use the Custom Data Formatter Standard Option.

JSON To XML

Format: &JSONToXML{JSON_STRING}

Converts a JSON format document into XML. Place the JSON string into a variable first, this will place it into an effective CDATA section Create a Varible called ${jsondata} and populated the JSON data into it.

e.g. ${jsondata} would contain
{"menu": {
  "id": "file",
  "value": "File",
  "popup": {
    "menuitem": [
      {"value": "New", "onclick": "CreateNewDoc()"},
      {"value": "Open", "onclick": "OpenDoc()"},
      {"value": "Close", "onclick": "CloseDoc()"}
    ]
  }
}}

So you then call the function:

&JSONToXML{"${jsondata}"}
Returns
<menu><id>file</id><popup><menuitem><value>New</value><onclick>CreateNewDoc()</onclick></menuitem><menuitem><value>Open</value><onclick>OpenDoc()</onclick></menuitem>

<menuitem><value>Close</value><onclick>CloseDoc()</onclick></menuitem></popup><value>File</value></menu>


XML To JSON

Format: &XMLToJSON{XML_STRING}

Converts an XML document into JSON format.

Parameter 1: XML document

&xmlToJSON{"<menu><id>file</id><popup><menuitem><value>New</value><onclick>CreateNewDoc()</onclick></menuitem><menuitem><value>Open</value><onclick>OpenDoc()</onclick></menuitem>
<menuitem><value>Close</value><onclick>CloseDoc()</onclick></menuitem></popup><value>File</value></menu>"}
Returns
{"menu": {
"id": "file",
"popup": {"menuitem": [
 {
  "value": "New",
  "onclick": "CreateNewDoc()"
 },
 {
  "value": "Open",
  "onclick": "OpenDoc()"
 },
 {
  "value": "Close",
  "onclick": "CloseDoc()"
 }
]},
"value": "File"
}}

Miscellaneous Functions

Inspect Context

Format: &inspectContext{CONTEXT_VALUE}

Inspects the current Presence Context and returns the value of the property specified in the first parameter. The property can be a dot separated list of objects and properties, for example, some common usages may be:

data.empty - returns true if the data table is empty, or false otherwise

data.rowCount - returns the number of rows in the current data table

taskMode - returns the current mode of the task as a number (see Presence Context)

container.topLeveltask.taskName - the name of the currently running (top level) task

container.nestedTask.taskName - the name of the currently running (nested) task

If an asterisk is specified instead of a property name, all of the available properties will be returned as a comma-separated list. For example:

&inspectContext{"data.*"}
Returns all available properties for the context data table
empty,rows,rowCount,columnNames,firstRow,class,
&inspectContext{"*"}
Returns all available properties for the context (includes data and container).
userContext,timeZone,data,taskMode,container,executionPath,localVariables,currentRunner,universalVariables,replaceNullColumns,
replaceNonNullColumns,globalVariablePassword,currentTaskElement,threadNumber,variables,class,

Is Null

Format: &isNull{TEST_VALUE, RETURN_VAL_IF_TRUE}

Tests if first parameter is null (empty) and returns second parameter if it is. Otherwise returns first parameter.

&isNull{"", "it was null"}
Returns "it was null"
&isNull{"i'm here!", "it was null"}
Returns "i'm here!".
Read AS400 Data Area

Format: &ReadAS400DataArea{SERVER, USERNAME, PASSWORD, LIBRARY, DATAAREA}

Reads a data area on the IBM Midrange iSeries/AS400 and Returns the value.


Tiff Page Count

Format: &TiffPageCount{TIFFBYTES}

Determines the number of pages in the tiff image passed to the function.

Parameter 1: The Tiff image ByteArray

Returns: the number of pages in the TIFF supplied.


Contains

Format: &contains{FIND_STING, SEARCH_STRING}

Check to see if a string contains another string. both are converted to lowercase. if the string is found then the starting position of that string is returned otherwise false is returned.


Convert TIFF to PNG

Format: &convertTiffToPng{TIFFBYTES,SCALE,PAGE_NUMBER}

Converts a TIFF stream into a PNG stream.

Parameter 1: The byte array variable of the entire TIFF Parameter 2: Scale (1 = full size) Parameter 3: Page number


Format Duration

Format: &formatDuration{DURATION}

Formats a duration (specified in seconds or minutes) as hours, minutes and seconds.

Duration Examples:

8273s = 02:17:53

149s = 00:02:29

228m = 03:48:00

60m = 01:00:00


Format Excel Date

Format: &formatXlsDate{DATE, CENT}

Formats a date from a non standard date string to dd/MM/yyyy

First parameter is the date

Second parameter is the century

e.g. 12/2/07 becomes 12/02/2007

Also if the year is first it will swap it around.


FTP Delete

Format: ftpDelete{RESOURCEID,PATH}

Deletes a file from an FTP server

Param 1: The Unique ID of the FTP resource

Param 2: The Path of the file to be deleted

You can find out the resource ID of the FPT server resource by using a SQL on the Presence Internal Database.


JAMES SMTP SERVER COMMAND

Format: &jamesAdmin{SERVER, PORT, USERNAME, PASSWORD, COMMAND}

Logs on to James admin server, sends a command and returns the response.


MD5

Format: &md5{STRING}

Creates a MD5 Hash from a string

&md5{"my string here but it will be much longer than the hash, this type of hash is widely used for sending secrete keys"}
Returns "292be0ab57c86dea40d449d0a5f504de"
iSeries/AS400 Command

Format: &AS400CMD{SERVER, USERNAME, PASSWORD, COMMAND, IGNORE ERRORS, PARM+}

Calls a program on an AS400 / iSeries as it is now known.

Parameters

parm 1 = System Host Name or IP address

parm 2 = User ID

parm 3 = Password

parm 4 = Cmd to call e.g call pgm(qgpl/myclpgm)

parm 5 = Ignore program errors ("true" or "false")

parm 6-99 string values for the parmeters.

e.g. &AS400CMD{"MYAS400","userid","password","call pgm(QGPL/MYCL)","false"} will call the program without passing any parameters

&AS400CMD{"MYAS400","userid","password","call pgm(QGPL/MYCL)","false",":VAR{ORDERID}",":VAR{QUANTITY}",":VAR{PRODUCT}"} will call the program for each row in the data table, with values from a previous presence query.


Numeric Functions

Byte String

Format: &byteString{BYTE}

This converts Presence's internal byte storage mechanism into the correct format for external applications. Specifically, 128 is subtracted from the value of each byte. Function cannot be tested, will only work during runtime


Divide

Format: &divide{VAL1,VAL2}

Divides 1st parameter by 2nd parameter and returns the result.

&divide{10,5}
Returns 2.
Eval

Format: &eval{EXPRESSION}

Evaluates the expression in argument 1 and returns the logical result.

&eval{"10*(2+5)"}
Returns 70
&eval{"5+(3*3)"}
Returns 45
&eval{"6/2"}
Returns 3

The following Operators are supported:

  • ||
  • xor
  • or
  • mod
  • and
  • ^
  • >>>
  • >>
  • >=
  • >
  • ==
  • <>
  • <=
  • <<
  • <
  • /
  • -
  • +
  • **
  • *
  • &&
  • %
  • !=

eval also supports the following functions:

  • varr
  • var
  • trunc
  • tanh
  • tan
  • sum
  • stddev
  • sqrt
  • sinh
  • sin
  • sign
  • sech
  • sec
  • round
  • random
  • rad
  • pow
  • permr
  • perm
  • min
  • max
  • log2
  • log10
  • log
  • hypot
  • frac
  • floor
  • fact
  • exp2
  • exp10
  • exp
  • deg
  • cur
  • csch
  • csc
  • count
  • coth
  • cot
  • cos
  • combr
  • comb
  • ceil
  • avg
  • atanh
  • atan2
  • atan
  • asinh
  • asin
  • asech
  • asec
  • acsch
  • acoth
  • acot
  • acosh
  • acos
  • abs

The following constants are supported:

  • TB = 1099511627776L
  • STEFAN_BOLTZMANN = 5.6704E-8
  • SPEED_OF_LIGHT = 299792458
  • RYDBERG = 10973731.568549
  • PYTHAGORAS = Math.sqrt(2)
  • PROTON_MASS =1.67262158E-27
  • PROTON_ELECTRON_MASS_RATIO = 1836.1526675
  • PLANCK = 6.62606876E-34
  • PI = Math.PI
  • NEWTON =6.673E-11
  • MOLAR_GAS = 8.314472
  • MIN_INT = Integer.MIN_VALUE
  • MIN_DEC = Double.MAX_VALUE
  • MB = 1048576
  • MAX_INT = Integer.MAX_VALUE
  • MAX_DEC = Double.MAX_VALUE
  • MAGNETIC_FLUX = 2.067833636E-15
  • MAGNETIC = 4E-7 * Math.PI
  • MADELUNG = 2.0531987328
  • KHINTCHINE = 2.685452001
  • KB = 1024
  • INVERSE_FINE_STRUCTURE = 137.03599976
  • IMAGINARY_UNIT = Math.sqrt(-1)
  • GRAVITY = 9.80665
  • GB = 1073741824
  • FINE_STRUCTURE = 7.297352533E-3
  • FEIGENBAUM = 2.50290787509589282228390287272909
  • FARADAY = 96485.3415
  • EULER = 0.57721566490153286060651209008240243104215933593992
  • ELEMENTARY_CHARGE = 1.602176462E-19
  • ELECTRON_VOLT = 1.602176462E-19
  • ELECTRON_MASS = 9.10938188E-31
  • ELECTRIC_CONSTANT = 8.854187817E-12
  • E = Math.E
  • CONDUCTANCE_QUANTUM = 7.748091696E-5
  • CATALAN = 0.915965594
  • BOLTZMANN = 1.3806503E-23
  • AVOGADRO = 6.02214199E+23
  • ATOMIC_MASS = 1.66053873E-27
  • APERY = 1.20205690315959428539973816151144999076498629234049

Hex Value

Format: &hexVal{NUMBER}

Returns the hexidecimal value of the number passed in parameter 1.

&hexVal(255)
Returns FF
Multiply

Format: &multiply{VAL+}

Multiplies all parameters and returns the result.

&multiply{1,5,8}
Returns 40
Percent

Format: &percent{PERCENTAGE,VALUE}

Returns the first argument expressed as a percentage of the second.

&percent{10,20}
Returns 50
Random

Format: &random{MAX}

Returns a random number between zero and the argument specified

&random{50}
Could Return 49.21655577700601
Round

Format: &round{NUMBER}

Round the parameter to the nearest whole number. See java.lang.Math.round(double) for contract.

Returns an integer representing the rounded value.

&round{5.791}
Returns 6
Subtract

Format: &subtract{VAL1,VAL2}

Subtracts argument 2 from argument 1 and returns the result.

&subtract{30,5}
Returns 25
Sum

Format: &sum{VAL+}

Adds all the parameters and returns the result.

&sum{1,5,8,9,1225,1551,998,1005}
Returns 4802

Presence Internal Functions

Current Task Name

Format: &currentTaskName{}

Returns the current task name. No parameters required.

Print Functions

PDF Print

Format: &pdfprintfunction{PDF FILE, PRINTER UNC, COPIES, FROM PAGE, TO PAGE, THROW ERROR, DUPLEX, SHORT EDGE BINDING}

Returns either Printed,Failed to print or throws an error

Parameters:-

1:PDF File

2:Printer UNC

3:Copies

4:Page-From:- 1 = first page

5:Page-To:- -1 = all

6:Throw Errors:-'True'=On failure, errors will be thrown back to the task 'False'=On failure the result will be 'Failed', but the task will continue

7:Duplex printing 'True' or 'False' (optional,default is false)

8:Short Edge Binding 'True' or 'False' (optional,default is false) applies with duplex printing


Security Functions

Validate Windows User And Password

Format: &ValidateWindowsUserAndPassword{DOMAIN/USER, PASSWORD, AD SERVER PORT, CLASS FACTORY}

Validates windows user and password details are valid using Windows Acitve Directory and Fast Binding.

returns string 'true' or 'false', throws an error on failure.

Parameters:-

1:Username domain\User 2:Password 3:LDAP url 4:Factory class

&ValidateWindowsUserAndPassword{"mydomain\robert", "password", "ldap://adserver:389", "com.sun.jndi.ldap.LdapCtxFactory"}
Returns false as this is not the correct password.
Create SHA Hash

Format: &createSHAHash{VALUE,ITERATIONS}

A secure one-way hash function that converts the input value into a fixed length hash value, using an SHA (secure hash algorithm) digest.

The original input value can never be retrieved from the hash value. This is useful for storing passwords etc, where the original value never needs to be known but the hashed value can be compared for correctness.

Parameter 1: Input value Parameter 2: Number of iterations to use (optional, default 1)

&createSHAHash{"Input Value"}
Returns a4c9cbd6e25fd7ae420dbe02ecf40785fb89099c
&createSHAHash{"Input Value",3}
Returns a9676f44e0ae8b65c393a1463e97d20552b93d33
Decrypt

Format: &decrypt{ENCRYPTED TEXT, KEY(optional)}

Decrypts the encrypted value specified to provide the original text value. Uses the Triple DES algorithm and a key that is unique to your Presence installation.

Parameter 1: An encrypted value Parameter 2 (optional): Encryption key Result: A decrypted value


Encrypt

Format: &encrypt{TEXT TO ENCRYPT, KEY(optional)}

Encrypts the specified value using a triple DES cipher algorithm. The key used is unique to each Presence installation. The resulting value can be decrypted using the decrypt{String} function.

Parameter 1: The string value to be encrypted. Result: An encrypted string, which can only be decrypted on the same Presence installation.

Parameter 2 (optional): A string to use as an encryption key.


String Functions

Chop Text

Format: &ChopText{TEXT, MAXLENGTH, DELIMITER, POPINTOVAR1, POPINTOVAR2}

This function splits a long string of text into two parts, looking for a delimiter near the middle of the string.

The first and second half are placed into variables named in parameters 4 and 5.

&ChopText{"10 Coppergate Mews, 109-111 Brighton Road, Surbiton, Surrey, United Kingdom KT6 5NE", 60, ",", ${test1}, ${test2}}

Returns 41 (chop position), populates ${test1} with "10 Coppergate Mews, 109-111 Brighton Road" and populates ${test2} with "Surbiton, Surrey, United Kingdom KT6" 5NE


Base 64 Decode

Format: &base64decode{BASE64STRING}

Decodes a Base64 String and converts it into a byte array.

&base64decode{"dGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2c="}
Returns "74686520717569636b2062726f776e20666f78206a756d706564206f76657220746865206c617a7920646f67"
Base 64 Encode

Format: &base64encode{BASE64STRING}

Converts the specified byte array (hex) into BASE64, returns the output.

&base64encode{"74686520717569636b2062726f776e20666f78206a756d706564206f76657220746865206c617a7920646f67"}
Returns "dGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2c="
Capitalises Words

Format: &capitaliseWords{STRING}

Capitalises the first letter of each word, where words are expected to be separated by space (" ") characters.

&capitaliseWords{"mr smith"}
Returns "Mr Smith"
Concatenate

Format: &concat{VALS+}

Concatinates any strings passed to the function. Accepts unlimited parameters. Returns a concatinated string.

&concat{"hello ", "how ", "are you","?"}
Returns "hello, how are you?"
Find Text In Line

Format: &findTextInLine{Multiline_Input_String, Regexp_Search, Return Type}

Locates specified text in a line of text in the first parameter.

&findTextInLine{"This is line 1
This is line 2
This is line 3", ".*3", "WHOLE_LINE"}
Returns: "This is line 3"
&findTextInLine{"This is line 1
This is line 2
This is line 3", ".*1", "WHOLE_LINE"}
Returns: "This is line 1"

Third parameter controls what's returned if a match is found:

WHOLE_LINE FROM_START_OF_MATCH FROM_END_OF_MATCH


Fix File Name

Format: &fixFileName{FILENAME}

Converts a filename into something sensible. Any characters other than a-z, A-Z and 0-9 are converted to an underscore (_) except for the last period (i.e. the extension)

 &fixFileName{"a file *&%name.png"}
Returns "a_file____name.png"
Format Number

Format: &formatNumber{NUMBER, FORMAT}

Formats a number specified by parameter 1 in the format specified by parameter 2. Returns the formatted number.

&formatNumber{123456.789, "###,###.###"}
Returns "123,456.789" The hash sign (#) denotes a digit, the comma is a placeholder for the grouping separator, and the period is a placeholder for the decimal separator.
&formatNumber{123456.789, "###.##"}
Returns "123456.79" The value has three digits to the right of the decimal point, but the pattern has only two. The format method handles this by rounding up.
&formatNumber{123.78, "000000.000"}
Returns "000123.780" The pattern specifies leading and trailing zeros, because the 0 character is used instead of the hash sign (#).
&formatNumber{12345.67, "£###,###.###"}
Returns "£12,345.67" The first character in the pattern is the dollar sign ($). Note that it immediately precedes the leftmost digit in the formatted output.
Get Text From HTML(Mark-Up)

Format: &getTExtFromHTML{MARKUP}

Function to remove html tags from a string.

Will also replace <-b-r-> <-p-> <-h1-> etc with a new line *dashes not in real example, used to stop formatting errors

Also replaces:-

&-l-t-; with a < &-g-t-; with a > &-q-u-o-t-; with a " &-a-m-p-; with a & &-n-b-s-p-; with a space *dashes not in real example, used to stop formatting errors

&getTextFromHTML{"<!DOCTYPE html>
<html>
<body>
<h1>My First Heading</h1>
<p>My first paragraph.</p>
</body>
</html>"}
Returns
My First Heading


My first paragraph.

Index Of

Format: &indexOf{TEXT_TO_SEARCH,SEARCH_FOR_TEXT}

Given the string specified in the first parameter, returns the index (position) of the string specified in the second parameter. The first character is at position zero and so on. Return value is zero based.

If the string cannot be found -1 is returned.

&indexOf{"text.to.search", "."}
Returns 4
Lower Case

Format: &lowerCase{STRING}

Converts the string entered to lower case.

&lowerCase{"Hello R2D2!"}
Returns "hello r2d2".
Pad Left

Format: &padLeft{STRING}

Left-pads the specified string with the string specified to the length specified.

Parameter 1: The string to pad and measure the length of.

Parameter 2: The string to use for padding.

Parameter 3: The width of the returned string.

&padLeft ("string", ".", 9)
Returns "...string"
&padRight

Format: &padRight{STRING}

Right-pads the specified string with the string specified to the length specified.

Parameter 1: The string to pad and measure the length of.

Parameter 2: The string to use for padding.

Parameter 3: The width of the returned string.

&padRight ("string", ".", 9)
Returns "string..."
Process String

Format: &processString{STRING}

Parses the string in argument one for function calls, etc. Returns the result.


Replace

Format: &replace{TEXT,TEXT_TO_REPLACE,REPLACE_WITH}

Replaces occurrence of parameter 2 with parameter 3 in string parameter 1.

&replace{"The quick brown fox jumps over the lazy dog", "fox", "camel"}
Returns "The quick brown camel jumps over the lazy dog"
Replace Pattern

Format: &replacePattern{TEXT,PATTERN,REPLACEMENT_PATTERN}

Given the input string in Parameter 1, replaces any occurrences of the pattern specified in parameter 2 with the string in parameter 3. Input patterns follow Java Regular Expression rules - see http://www.regexr.com/ for more information on regex patterns.

&replacePattern{"That costs £15.00", "[a-zA-Z\s£]+", ""}
Returns: "15.00". Replaces any words and the pound sign as well as white spaces.
Split Text In Columns (Actually Rows)

Format:&splitTextIntoColumns{TEXT, DELIMITER, COLNAME, POSITION_COL_NAME}

Splits the text specified in argument 1, based on the delimiter specified in argument 2. A new data column is created with the column name specified in argument 3, and the data table is appended with the new column.

Optional parameter 4 specifies the column name to store the position of the item. If omitted, the position is not stored.

&splitTextIntoColumns{"word1;word2;word3", ";", "WORDS", "POSITION"}
Returns "3 new rows created" and the data table at runtime would contain 3 rows and two Columns accessed via :var{WORDS} & :var{POSITION}. A very useful function for dealing with arrays returned from http requests, etc.
Multi Column Text Split

Format: &multiColumnTextSplit{TEXT, DELIMITER, COLNAME1, TEXT, DELIMITER, COLNAME2, [textToSplit, delim, colname] ...}

Splits text in parameter one according to delimiter specified in parameter two and creates a data table column named parameter three. The three paramaters can be repeated indefinitely to create a larger data table.

&multiColumnTextSplit{"word1;word2;word3", ";", "WORDS", "anotherword,anotherword,anotherword",",","COL2"}
Returns "3 new rows created" and the data table at runtime would contain 3 rows and two Columns accessed via :var{WORDS} & :var{COL2}. A very useful function for dealing with arrays returned from http requests, etc.
SQL String

Format: &sqlString{SQL_STRING_TO_CORRECT}

Parses the String to find any single quotes that would upset the database and replaces them with two single quotes as per SQL 92 standard

&sqlString{"Don't do that"}
Returns "Dont do that"
Starts With

Format: &stratsWith{TEXT,CHARS_TO_CHECK}

Tests to see if the string supplied by the first parameter begins with the string specified in the second parameter.

Example:

&startsWith{"Foobar", "Foo"}
Returns "true".
&startsWith{"Foobar", "Bar"}
Returns "false".
String Length

Format: &stringLength{STRING}

Returns the number of characters in the specified string.

Parameter 1: The string to measure the length of.

&stringLength{"foobar"}
Returns "6".
Sub String

Format: &substring{STRING,START,END}

Returns a substring of the specified string.

Parameter 1: The string to get the substring of.

Parameter 2: The start character (first character being 1)

Parameter 3: The number of characters to retrieve.

&substring{"foobar",1,3}
Returns "foo".
Text To Binary

Format: &textToBinary{STRING}

Converts the text specified into a byte array, for inserting into a blob etc.

&textToBinary{"The quick brown dog"}
Returns a Byte array with 19 elements.
Trim

Format: &trim{STRING}

Trims the string specified by parameter 1, removing any leading or trailing spaces and line breaks.

&trim{"   spaced       "}
Returns "spaced".
Upper Case

Format: &upperCase{STRING}

Converts the string entered to upper case.

&upperCase{"Hello R2D2!"}
Returns "HELLO R2D2!".
Wrap

Format: &wrap{STRING,WRAP_ON_WORD,CHARS_FOR_LINE}

Wraps text at a specified position

Usage:

Parameter 1 = The text to wrap Parameter 2= true or false for wrap on word Parameter 3= Max number of Chars for a single line

&wrap{"The quick brown fox jumps over the lazy dog, he doesn't stop to say hello.", "false", "30"}
Returns
The quick brown fox jumps over

the lazy dog, he doesn't stop

to say hello.

Data Table Functions

Add Running Total

Format: &addRunningTotal{IN_COLUMN, OUT_COLUMN}

Keeps a running total of a column of numbers and sets an additional column to be the current total. eg: 0 1 2 0 1 2 3

Becomes:

0 1 2 2 3 4 5


Create Pivot Table

Format: &createPivotTable {ROWFIELD, COLUMNFIELD, FACTFIELD, AGGREGATION_METHOD [, VARIABLE_NAME]}

Creates a pivot table (see http://en.wikipedia.org/wiki/Pivot_table) based on the current Data Table.

ROWFIELD: This is the field which is used as the first column. COLUMNFIELD: Additional columns are created for each value of this field. FACTFIELD: The values of the columns are setting according to this field's values. AGGREGATION_METHOD: Where multiple values exist, this is the method that should be used to generate one unique value. Possible options are:

- SUM - the total sum of the values - COUNT - the count of values - MEAN - the arithmetic mean of the values - STD_DEV - the standard deviation of the values - RETAIN - only uses the first value found - REPLACE - uses the last value found

VARIABLE_NAME: (Optional) - if specified, the resulting data table will be stored in this variable rather than replacing the existing data table.


Append Row IDs

Format: &appendRowIds{COL_NAME(Optional)}

Appends a new column to the data table with a unique ID for each row of data, numbered from 1 to n where n is the number of records.

An optional argument can be provided to identify the column name to use. If this is ommitted a default column name of "PRESENCE_ROW_ID" is used.

If the column already exists it will be updated to reflect the current record positions.