Do Statement

From Pengower
Jump to: navigation, search

All the script actions accessible via the ‘Do’ command follow these basic syntactic patterns. A full list of the currently available script actions is provided below. Note, as the platform has been developed to allow addition of more script actions over time the list below should not be considered definitive. Regular updates to this manual will be provided showing new script actions as the library is extended.

Contents

Do Commands (A-Z)

A

Add Attribute

Paramaters:
Item, Name / returns; an attribute item

Purpose: Allows a given attribute to be added to an item. The ‘Item’ parameter provides the item variable to which the attribute will be added. The ‘Name’ parameter provides the name of the attribute to be added. If successful the attribute will be returned, if not NULL will be returned. WARNING; Do NOT add an attribute to an item that has yet to be stored in the database – the necessary item inter-connections will not be established correctly.

Example; Set ped = Do Add Attribute Params Item = fido, Name = “Pedigree” Set ped[“Value”] = 400 Set ped[“Kennel Club Name”] = “King Fido the 5th” Do Store Item Params Item = ped Do Store Item Params Item = fido Output = fido Return_Ok

Add File

Purpose: Adds a file to an element (of type Attachment).

Paramaters:

  • Object - object
  • Element - element name
  • File - file

Returns:

  • "Ok"

Example:
The following example shows how Do Add File is used to add a converted file (from .Rtf file to .Doc) to the element Referral Form on the object ohaCase.

Set filename = "ManagementReferralForm_" + caseID +".doc"
Set rtfFile = Do Create File Params Name = filename, Type = "RTF"
Do Write Params File = rtfFile, Content = docStr<br>
Set docFile = Do Convert File Params File = rtfFile, Type = "DOC"

Do Add File Params Object = ohaCase, Element = "Referral Form", File = docFile

Do Store Item Params Item = ohaCase, Force = 1


Amend User

Update username

Parameters:

  • Username* – String – username of the user to be amended
  • New Username – String – new username
  • New Password – String – new password
  • New User Type – String – new user type
  • New Expiry Date – Date – new expiry date
  • New Linked Object – Object – new underling user record to associate with this user

Output:

• String – “Ok”


Application ID

Purpose:

  • Returns the id of the application.

Returns:

  • String

Example:

Set rtn = Do Run Module Params Name = "Utils_GetAppID"
Set repStr = "" + rtn
Set tmpStr = Do Replace String Params String = html, Replace = "#APPID#", With = repStr
Set html = tmpStr


C

Changes

Purpose:

  • Identifies if an object has been updated and what elements have been updated.</li>

Parameters:

  • Item

Returns:

  • Array- one sub-array for each change


Example:

Set acc = Current_Item
Set chnges = Do Changes Params Item = acc
Set repStr = ""
If chnges.Count = 0
//--no changes--.
Set repStr = repStr + "Nothing has changed"
Else
For i = 1 To chnges.Count
Set chnge = chnges[i]
//--the name of the element that has been updated--
Set eleNme = chnge.ElementName
//--the value of the in memory object - ie Current_Item--
Set memVal = chnge.MemoryValue
//--the valus stored on disk--
Set diskVal = chnge.DiskValue
Set repStr = repStr + eleNme + memVal + diskVal
Next
EndIf


The element types supported are as follows;

  • Text = get the text value
  • Number = get the numeric value
  • True_False = get 1 or 0
  • Selectable = get string
  • Relationship = get array of objects
  • Date_Time = get date time value
  • Time_Period = get time period value
  • Embedded Type = NOT SUPPORTED
  • Attachment = NOT SUPPORTED - will always return current list of files
  • Content = string
  • Calculated = Number or Date or Period (depending on calc)
  • Multi-Select = array of strings
  • Action Button = n/a
  • Information = n/a
  • Auto_generated = string
  • Linked Data = NOT SUPPORTED and not relevant
  • Group = NOT SUPPORTED
  • Linked Copy = string


Close Email Account

Purpose:

  • Logs out the open email account that was opend using the "Do Open Email Account" Do statement.


Parameters:

  • Server, Account, Password


Returns:

  • "Ok" When successful, and a message if otherwise


Example: Set email = Do Close Email Params Server = "example.server.com", Account = "account@server.com", Password = "Password123!"


Convert File

Purpose:

  • Converts a file from one type to another.

Returns:

  • File

Example:
The following example shows how Do Convert File is used to convert an .Rtf file to a .Doc

Set filename = "ManagementReferralForm_" + caseID +".doc"
Set rtfFile = Do Create File Params Name = filename, Type = "RTF"
Do Write Params File = rtfFile, Content = docStr
Set docFile = Do Convert File Params File = rtfFile, Type = "DOC"

Do Add File Params Object = ohaCase, Element = "Referral Form", File = docFile
Do Store Item Params Item = ohaCase, Force = 1



Create Date

Purpose:

  • Returns a date type when provided with day, month and year integer values.

Parameters:

  • Day - integer
  • Month - integer
  • Year - integer

Returns:

  • Date

Example:
The following example converts a date from a string (in yyyy-mm-dd format) into a date type and then calculates the previous week's date.

Set yr =  0 + dateArr[1]
Set mth = 0 + dateArr[2]
Set day = 0 + dateArr[3]

Set tmpDate = Do Create Date Params Year = yr, Month = mth, Day = day


Create File

Purpose:

  • There exists a file script variable type which is a wrapper around a file saved onto the hard disk of the server where the Pengower Platform is implemented. The association between the file variable and the physical file is masked from the developer and they need not concern themselves with the exact physical representation of the file – they manipulate the file through a sequence of Do Actions incorporating the file variable as a parameter. Do Create File provides the ability to create a file.

Parameters:

  • Name - filename
  • Type - TXT/HTM/RTF/DOC/PDF/XML/BIN
  • Encoding - ASCII (default), UTF8 or UNICODE

Returns:

  • File

Example:

Set file = Do Create File Params Name = "people.csv", Type = "TXT", Encoding = "UTF8"


Please Note: It is recommended to set encoding for export files to UTF8 to get proper special characters like "£" to show correctly on Windows. If you are trying to show £ correctly on screen, don't look a the file encoding, use Do HTML Encode instead.


Create User

Parameters:

Type, Password, Entity* / returns; new username

  • creates a new user of a specified type and links it to the underlying entity if it is provided and is appropriate
  • parameter ‘Type’ represents the User Type to create
  • parameter ‘Password’ indicates the password to assign to the newly created user
  • parameter ‘Entity’ is a non essential parameter and represents the underlying item to link the user to if appropriate
  • the command returns the username of the newly created user or an empty string if the call failed. Note the username will be a combination of letter and numbers to create a unique username.

Example:

Set pwd = "fido"
Set un = Do Create User Params Type="Pet", Password=pwd, Entity=fido
If (un = "")
     Report = "Create user failed"
     Output = fido
     Return_Ok
EndIf
Output = un
Return_Ok


CSV Interpret

Purpose:
* Takes a string of comma-separated values and returns an array where each array element contains a value.


(This is generally used when importing CSV files into the application - see example below.)

Parameters:

  • String - string

Returns:

  • Array

Example:

//Figure out the total number of lines in the import file
Set totalLines = 0
Loop
	Set line = Do Read Line Params File = file
	Set totalLines = totalLines + 1

	If (("Organisation Unit" = frm["Import Type"]) AND (totalLines > 1) AND (line != "#EOF")) 
		Set fieldArr = Do CSV Interpret Params String = line
		Set tmp = "" + fieldArr[1]
		Set tmpStr = tmp.ToUpper
		Add tmpStr To referenceArr
	EndIf	
Until (line = "#EOF")
Set totalLines = totalLines - 2  //Subtracting the header and EOF lines<

Current Culture

Purpose:

  • Provides the developer with the ability to determine the culture being used by this user, e.g. EN-GB (English Great Britain) EN-US (English American) JP-JP (Japanese) etc


Returns:

  • Culture Code


Example:
Set culture = Do Current Culture


Current Section

Purpose:

  • Obtains the name of the current section on type.

Returns:

  • String

Example:

The following code is taken from the Save event of a type with many sections. It ensures that whatever section the user was on when they clicked 'Save', this is the section that they will be returned to once the save processing has completed (using Do Set Section).

Set itm = Current_Item<

Set section = Do Current Section

Set args = {}
Set Job = itm
Add Job To args
Set rtn = Do Run Script Params Script Name = "tm Job Save", Args = args
If (0 = rtn[1])
	Set error = "An unhandled error occurred in tm Job Save"
Else
	Set tmpStr = Cache Get Key = "Error"
	Set error	 = "" + tmpStr
EndIf

If ("" = error)
	Set itm = rtn[3]
	Do Set Section Params Item = itm, Name = section
	Report = "Record saved successfully" + calledFrom
	Output = itm

Else
	Do Set Section Params Item = itm, Name = section
        Report = "<span style='color: red;'>" + error + "</span>"
	Output = itm
EndIf

Return_Ok


Current User

Parameters:

  • NONE

Returns the Username and Password for the Current User in the form of an array of string variables (username, password).

Example:

Set arr = Do Current User
Set username = arr[1]
Set password = arr[2]

Current User Type

Purpose:

  • Gets the current users license type


Returns:

  • User Type


Example:
"Set licenseType = Do Current User Type If (licenseType != ""Administrator"") // do not permit action EndIf"


D

Decrypt String

Purpose:

  • Decrypts a string that has been encrypted using Do Encrypt String.

Parameters:

  • String - string

Returns:

  • Decrypted String

Example:
The following example uses Do Decrypt String to decrypt an encrypted string hidden on a HTML form with a name of returnValue3.

Set currentDate = Do Request Field Params Name = "returnValue3"

Set tmpStr = Do Decrypt String Params String = currentDate 

Set currentDate = "" + tmpStr


Delete Objects

Parameters:

  • Objects, Force / returns
  • enables the deletion of items from within scripts. The ‘Objects’ parameter can be either an array of item variables or a single item variable
  • ‘Force’ indicates if the call should be committed to the database now under its own transaction, or whether it should be left until script completion and stored under an overarching transaction capturing all database updates that occur within the script. A value of 1 forces the update now, whilst a value of 0 allows it to operate under the main script transaction (see below for more detailed notes on forcing and when to use it)
  • Note if ‘Force’ is excluded as it is an optional parameter a value of 0 will be assumed (i.e. do not force update now)

Example:
Note how, in the following example, referential integrity is enforced by not permitting the deletion if it will result in orphans being created.

Set itm = Current_Item

Set section = Do Current Section

Set error = ""
Set tmpArr = itm["Customers_"]
If (tmpArr.Count > 0)
	Set error = "Cannot delete an Agent that has Customers"
EndIf

If ("" != error)
	Report	= "<span style='color: red;'>" + error + "</span>"
	Do Set Section Params Item = itm, Name = section
	Output	= itm
	Return_Ok
EndIf

        Set msg	= "<span style='font-weight: bold;'>Agent " + itm["Name"] + " was deleted successfully</span>
Do Delete Objects Params Objects = itm, Force = 1

Output	= msg
Return_Ok


E

Edit User Item

Purpose:

  • Gets the current users associated record


Returns:

  • Record


Example:
Set userRecord = Do Edit User Item

Email

Parameters:

  • From - String
  • To - String
  • Subject - String
  • Body - String
  • CC - String - email address of person to be CC'd (Optional)
  • BCC - String - email address of person to be BCC'd (Optional)
  • Attachment - File (Optional)
  • Format - String - text/html (Optional)
  • sends an email via the IIS SMTP server. This construct allows for the auto-generation of emails in response to other actions in the system. Parameter ‘To’ is the email address of the recipient or recipients; parameter ‘From’ is the email address of the sender; parameter ‘Subject’ provides the subject of the email; parameter ‘CC’ is the email address or addresses of people to whom the email should be copied; parameter ‘Body’ is the main body of the email, note the emails are sent as html emails allowing for more flexible formatting of the body; and parameter ‘Attachment’ allows for attachments to be added to the email.
  • attachments are added by assigning an attachment/document element of an item to the ‘Attachment’ parameter
  • the return string will be ‘Ok’ if the send operation succeeded or ‘Failed’ if it failed.

Example:

Set to = Current_Form["To"]
Set body = Current_Form["Body"]
Set subject = Current_Form["Subject"]
Set from = Current_User["Email"]
Set rep = Do Email Params To=to, From=from, Subject=subject, Body=body
If (rep = "Ok")
     Output = "Email sent okay"
Else
     Output = "Emailed send failed"
EndIf
Return_Ok

Note: this action demonstrates that not all parameters are essential.

Set rtn	= Do Email Params To = mailTo, From = mailFrom, Subject = mailSubject, Body = mailBody
If ("Ok" != rtn)
	Set message = "Your password has been reset  but an email could not be sent - please contact your system administrator."
Else
	Set message = "Your password has been reset  and the details emailed to you."
EndIf


You can pass an alias via the From argument as follows "My Alias <myemail@mydomain.com>"


Encrypt String

Purpose:

  • Encrypts a string. To decrypt a string use Do Decrypt String.

Parameters:

  • String - string

Return:

  • Encrypted String

Example:

The following example uses Do Encrypt String as a way to hide data on a HTML form.

Set encryptedStartDateStr = Do Encrypt String Params String = sheetStartDateStr
Set h = "<input type='hidden' id='returnValue3' name='returnValue3' value='" + encryptedStartDateStr + "'>"
Do Write Params File = hFile, Content = h


Export Type

Purpose:

  • Exports a type including meta data and data to XML


F

File Url

Purpose:

  • Gets the file url path


File Name

Purpose:

  • Get the filename of the attached file


Parameters:

  • Params File


Returns:

  • Filename of the attached file


Example:
"Set doc = Obj[""Attachment""] Set fileName = Do File Name Params File = doc"


Filter Array

Purpose:

  • Filters a set of data by a particular element value

Parameters:

  • Array* – Array – Array of Objects to be filtered
  • Element* – String – Element to Filter By
  • Operator* – String – Operator to be applied
   o Accepts values: EQ, NE, GT, LT, LE, GE, =, !=, >, <, >=, <=
  • Value* – String or Number or Date (Depending on Element) – Value to use in filtering
  • Null – String – “OMIT” or “INCLUDE” to indicate behaviour on filtration for null elements. Default is omit.

Output:

  • Array – Array filtered by your specified parameters


Returns:

  • Subset


Example:
Do Filter Array Params Array = contacts, Element = Surname, Operator = "=", Value = "Johnson", Null = ""


Format Date

Purpose:

  • Use to format date e.g (from 01/12/2016 to 2016-01-12)


Parameters:

  • Date Format
  • Format* – String – Format to use
   o Options are based on standard C# Format options and custom format options


Returns:

  • Formatted date


Example:
"Set date = TODAY Set formatDate= Do Format Date Params Date = TimeNow, Format = ""yyyy-MM-dd"""


Format Number

Parameters:

  • Value, Dps
  • Formats the string display of a numeric value to have a set number of decimal places (including trailing zeros if required).
  • ‘Value’ is the number to be formatted.
  • ‘Dps’ is the number of decimal points to display.
  • Used to format numbers to display in html output, primarily when displaying monetary values.

Example:

Set cost = 1.5
Set costStr = Do Format Number Params Value = cost, Dps = 2
Set Output = "Cost = £" + costStr
Return_Ok
Will output "Cost = £1.50".


G

Get Attribute

Parameters:

  • Item/Name

Returns:

  • An attribute item

Purpose:

  • Provides access to a given attribute on a specific item. This is used when information on the attribute is required, but only the underlying item has been accessed. Parameter ‘Item’ indicates the specific item from which the attribute should be retrieved, and parameter ‘Name’ provides the name of the attribute to retrieve. If the attribute exists on the provided item the attribute item will be returned otherwise NULL will be returned.

Example:

Set ped = Do Get Attribute Params Item = fido, Name = "Pedigree"
Set value = ped["Value"]


Get Item

Parameters:

  • Attributes

Returns:

  • An Item Variable

Purpose:

  • Provides mechanism to access the underlying item for a given attribute. If an attribute item is obtained through searching, i.e. use of a Get statement or other query mechanism, it may be necessary to access the underlying item to which the attribute is attached. This command will return the underlying item for the attribute provided or NULL if the item provided is not an attribute.


Example:

Set man = Get "Manager" Where Department = "Legal"
Set person = Do Get Item Params Attribute = man

Get Emails

Purpose:

  • Retrieves all the emails from the main inbox of an email account.


Parameters:

  • Server, Account, Password


Returns:

  • Array of emails/error message if unsuccessful


Example:
Set emails = Do Get Emails Params Server = "example.server.com", Account = "account@server.com", Password = "Password123!"


H

HTML Encode

Parameters:

  • String / returns; new string
  • takes the input string (‘String’) and encodes it to HTML so that it will display correctly when rendered as HTML. This will modify special characters and carriage returns.
  • parameter ‘String’ is the string to be encoded.
  • the newly encoded string is returned.

Example:

Set html = Do HTML Encode Params String = addr


I

Import Data

Purpose:

  • Import the data exported by 'Export Data'



L

Lock Item

Parameters:

  • Item

Returns:

  • Report string
  • Applies an edit lock to an item in script. This is used when during the course of executing a script you wish to modify an already existing object. It is necessary to ensure data consistency. Consider the case where two users are trying to update the balance on a customer account – if exclusive control cannot be gained then the final value of the balance could be inaccurate.
  • Parameter ‘Item’ is the item on which an edit lock is required
  • The return value is a string variable indicating if the lock was obtained. If the lock was obtained the return will be ‘Ok’- otherwise it will be ‘Fail’

Example:

Set lck = Do Lock Item Params Item = fido
If (lck != ‘Ok’)
     Report = "Could not obtain an edit lock on fido"
     Output = fido
     Return_Ok
EndIf
  • It may be necessary to use Release Lock after locking, to avoid unnecessarily stopping other users editing the object
  • Update Element allows you to edit a single element on an object without obtaining a lock


Log Event

Purpose:

  • Allows creating a log entry in the application's event log which can then be reviewed through the builder. Useful for when trying to debug and checking values of certain variables during a script's runtime.


Parameters:

  • "Params Type = WARN / ERROR

String = Event Msg/ Error Message"


Example:
Do Log Event Params Type = "ERROR", String = logString


Logout

Purpose:

  • Logs out the current user from the applciation


Example:
Do Logout


M

Manage Users

Purpose:

  • Opens a form to select the list of current users filtered by user types


N

New Object

Parameters:

  • Type / returns; an Item
  • Creates a new instance of a given type

Example:

Set fido = Do New Object Params Type = "Pet"


New String Builder

Parameters:

  • Size (Optional)

Returns:

  • N/A
  • Initialises a String Builder variable,
  • Optional parameter ‘Size’ is the character length of the final string- including this if possible will give some improvement to speed

For detailed information about the String Builder, please see Using The String Builder

Example:

   Set string1 = "The quick brown fox"
   Set stringBuilder = New String Builder
   AddTo stringBuilder = string1
   Output = "" + stringBuilder
   Return_Ok

The output of the code above will be:

   The quick brown fox


If we add more text to the string builder we can have something like this:

   Set string1 = "The quick brown fox"
   Set stringBuilder = Do New String Builder
   AddTo stringBuilder = string1
   Set string2 = " jumped over the lazy dog."
   Set string3 = " And that's how the cookie crumbles."
   AddTo stringBuilder = string2
   AddTo stringBuilder = string3
   Output = "" + stringBuilder
   Return_Ok

The output will now be:

  The quick brown fox jumped over the lazy dog. And that's how the cookie crumbles.

O

Open Custom Form

Parameters:

  • Custom Form / returns; the form

Creates and returns an instance of a custom form. The instance then be populated as per a standard item prior to being returned as the main item in the work region. The parameter ‘Custom Form’ provides the name of the form to be opened/created

Example:

Set frm = Do Open Custom Form Params Custom Form = "New Pet Form"
Set frm["Type"] = "Dog"
Set frm["Name"] = "Fido"
Output = frm
Return_Ok

Open Email Account

Purpose:

  • Opens an email account which allows for accessing emails in the said email account.


Parameters:

  • Server, Account, Password


Returns:

  • "Ok" when successful / an error message if otherwise


Example:
Set email = Do Open Email Params Server = "example.server.com", Account = "account@server.com", Password = "Password123!"


Open HTML Page

Purpose:

  • Used to open an HTML Snippet via an action script.


Parameters:

  • Page: HTML Snippet Name


Returns:

  • HTML snippet page


Example:
"Set html = Do Open HTML Page Params Page = ""HTMLSnippet"" Output = html Return_Ok"


Pad String

Purpose:

  • Adds a character to a string

Parameters:

  • String* – String – String to pad
  • Side* – String – Side of the string to be padded, Left, Right or Both
  • Pad With – String – String to pad with, defaults to a space
  • Size*– Number – Number of times to use ‘Pad With’


Returns:

  • "1000"


Example:
Do Pad String Params String = "1", Side = "right", Size = "3", Pad With = "0"


P

PDF Generator

Populate File Content

Purpose:

  • Populates element with content of file


Example:
Do Populate File Content = content, Content Type = "htm", Name = "variable name", Save Type = "htm"Set email = Do Close Email Params Server = "example.server.com", Account = "account@server.com", Password = "Password123!"

Q

Query String Element

Purpose

  • Returns the specified part of the query string that the client came in with; parameters are after the "?" in the URL.

Parameters

  • Key specifies the name of the parameter

Example

Set tmp = Do Query String Element Params Key = "ClientID"
Set id = "" + tmp
If (id = "")
	Output = "System Error: No ClientID specified"
	Return_Ok
EndIf

Set clientID = Do Decrypt String Params String = id
Set clientArr = Get "Client" Where (ID = clientID)
If (clientArr.Count != 1)

Output = "System Error: Invalid ClientID specified"
Return_Ok

	Output = "System Error: Invalid ClientID specified"
	Return_Ok
EndIf


R

Read

Purpose

  • Transfers the entire content of a specified file to a string.

Parameters

  • File - a file

Return

  • String


Read Line

Purpose

  • Reads a line (ie. string of characters terminated by carridge control line feed characters) from a specified file

Parameters

  • File - a file

Return

  • String

Example

Note the detection of the end of the file by comparing the result of this call with "#EOF".

Set totalLines = 0
Loop
	Set line = Do Read Line Params File = file
	Set totalLines = totalLines + 1

	If (("Organisation Unit" = frm["Import Type"]) AND (totalLines > 1) AND (line != "#EOF")) 
		Set fieldArr  = Do CSV Interpret Params String = line
		Set tmp	      = "" + fieldArr[1]
		Set tmpStr   = tmp.ToUpper
		Add tmpStr To referenceArr
	EndIf	
Until (line = "#EOF")
Set totalLines = totalLines - 2  //Subtracting the header and EOF lines


Regular Expression

Purpose

  • Finds a regular expression [1] within a string. Returns -1 if nothing was found.

Regular Expressions are very useful for validating strings, for example checking that a string conforms to a certain pattern; Do Regular Expression will return -1 if the pattern is not matched, 0 or a positive number otherwise.

Parameters

  • String - the string to search in
  • Find - the regular expression

Example

Set fea = feaArr[i]
Set ID = "" + fea["Feature ID"]
Set find = "FEATURE"
Set mtch = Do Regular Expression Params String = ID, Find = find
If mtch < 0
Output = frm
Report = "ERROR: Unable to find feature to delete"
Return_Ok
EndIf



Release Lock

Parameters:

  • Item

Returns:

  • Report string
  • Releases a previously applied lock, making sure it will be free to edit after changes are stored
  • Parameter ‘Item’ is the item on which an edit lock is required
  • The return value is a string variable indicating if the lock was released. If the lock was released the return will be ‘Ok’

Example:

Set lck = Do Lock Item Params Item = fido
If (lck != ‘Ok’)
     Report = "- could not obtain an edit lock on fido"
     Output = fido
     Return_Ok
Else
     Do Store Item Params Item = fido, Force = 1
     Do Release Lock Params Item = fido
EndIf


Remove Attribute Form

Parameters:

  • Item & Name

Purpose:

  • Allows an attribute to be removed from an item if it is no longer required. Note all the data associated with the attribute will be deleted. Parameter ‘Item’ indicates the item from which the attribute will be removed and parameter ‘Name’ provides the name of the attribute to be removed.

Example:

Do Remove Attribute Params Item = fido, Name = "Pedigree"

Remove File

Purpose:

  • Removes a file from a given Attachment element from a given Object


Parameters:

  • Object = Object

Element = Attachment Element File = Filename / All File


Example:
"Set Object = Current_Item Do Remove File Params Object = Object, Element = ""Files"", File = ""ALL"""

Replace String

Parameters:

  • String, Replace, With / returns; new string
  • replaces all occurrences of ‘Replace’ with ‘With’ in ‘String’ and returns the new string.
  • parameter ‘String’ is the original string.
  • parameter ‘Replace’ is the string that will be replaced in ‘String’
  • parameter ‘With’ is the string with which ‘Replace’ will be replaced.
  • the command returns the new string after replacement has been completed.

Example:

Set newString = Do Replace String Params String=temp, Replace="#NAME", With=nme


Request Field

Parameters:

  • Name / returns; string value of html control (v4.0)
  • used to extract the value of a specific html control on a form, i.e. it provides access to the underlying html form in the Request.
  • this is used in conjunction with HTML Pages to give more flexible control over interface design. The platform will now allow bespoke forms/interfaces designed through html pages and still allow scripts to extract and process data.
  • parameter ‘Name’ is the name of the html control on the page whose value is required.
  • the call returns the value of the element requested. The returned variable will either be a string or a number depending on the form of the input.
  • if no element is present matching the given name a string variable "NOT_PRESENT" will be returned.

Example:

Set nameStr = Do Request Field Params Name = "fullName"
If nameStr = "NOT_PRESENT"
     Output = "Error extracting the form data"
     Return_Ok
EndIf


Round

Parameters:

  • Value, Dps / returns; rounded number
  • rounds input value to the specified number of decimal places. This is generally used when handling calculations involving money to restrict calculated values to 2 decimal places.
  • parameter ‘Value’ represents the number to be rounded.
  • parameter ‘Dps’ represents the number of decimal places to round the number to.

Example:

Set tmp = nett * rate / 100
Set vat = Do Round Params Value = tmp, Dps = 2

WARNING: The ‘Round’ command cannot work in a self-referential fashion. Trying to write the script in this way will cause the platform to fall over, i.e. do NOT write Set tmp = Do Round Params Value = tmp, Dps = 2 – this will FAIL AND CAUSE A SERIOUS PLATFORM CRASH!


Run Module

Parameters:

  • Name & Args

Returns:

  • Variable

Purpose:

  • runs a routine that has been specifically written in C# (or any other .NET language) and appropriately incorporated into the main body of the platform (i.e. within PengowerCompiledModules.dll)
  • the main purpose of the compiled modules option is to improve performance and flexibility without extending the script engine to become a complete programming environment usable only by technical staff. The aim has always been to keep the scripting simple so that non-IT specialists can cope with basic scripts
  • where the requirements go beyond the platform capability or performance is critical and difficult to attain via script compiled modules can be utilised
  • to obtain a compile module contact Pengower
  • parameter ‘Name’ provides the name of the compiled module – this will be available from Pengower
  • parameter ‘Args’ contains any variable that should be passed to the module to allow correct execution
  • the call will return a variable – it could be of any valid variable type dependent on the operation of the compiled module and its required functionality


Example:

Set args = {}
Add per To args
Add dob To args
Set family = Do Run Module Params Name = "Find Family", Args = args
Output = family
Return_Ok

Run Script

Parameters:

  • Script Name, Args, Async / returns; array (see below)
  • runs/calls another script action from within a script. This allows the script construction to be split into functional units where appropriate. This approach should be used with caution as excessive nesting could impact performance.
  • the parameter ‘Script Name’ is the name of the script that should be called.
  • the parameter ‘Args’ represents any arguments that should be passed to the inner function. The ‘Args’ array is an array of variables from the calling script. Note, the variables are passed by name, that is, the function script will access the arguments based on the name they are given (see example below).
  • The ‘Async’ parameter indicates if the script routine should be run synchronously, i.e. the current script will wait whilst the called script function executes and then returns, or asynchronously, in which case the calling script will continue to process once it has initiated the call to the script function, possibly completing and returning to the user prior to the called script function completing its execution. This functionality is used to reduce latency and improve usability of applications e.g. a check that is run every morning when a user logs on to update some parameters (such as last login time etc) – this can be called on application start up but the bulk of the functionality removed to an asynchronous function – so not delaying the start up from the users perspective
  • the return array contains information about the success of the function call, any report information and any output. The array has three elements; element 1 indicates the success or failure of the function call – a value of 0 indicates failure and a value of 1 indicates success; element 2 contains a string variable that holds the report generated in the function script (i.e. the string that was allocated to Report); element 3 contains any output from the function (i.e. it contains the variable or expression that was allocated to Output in the function script).

Example:

// calling script
Set x = 1
Set y = 2
Set args = {}
Add x To args
Add y To args
Set out = Do Run Script Params Script Name = "Simple Addition", Args = args
Set ans = out[3]
Output = ans
Return_Ok
-----------------------
Script: Simple Addition
-----------------------
// function script
Set a = x + y
Report = " – okay "
Output = a
Return_Ok


S

Send SMS Message

Purpose:

  • Used for sending a message via SMS.


Parameters:

  • "Number = Mobile Number

Message = Actual Message Sender = Sender Name Country = Country Name"


Returns:

  • SMS Message


Example:
"Set to = ""07712345678"" Set message = ""Hello World"" Set sender = ""John Doe"" Set country = ""UK"" EndIf

If (to != """")

  Set sms = Do Send SMS Message Params Number = to, Message = message, Sender = sender, Country = country
  Set status = """" + sms

Else

   Set status = ""Failed: Mobile Phone Number not defined""

EndIf"


Set Relationship Options

Purpose:

  • Used to set the available options of related Objects for a given Relationship element either of an Object or a Custom form.


Parameters:

  • Entity - the object/or form variable; Element - the name of the elemen in the Object or Custom Form; Options - an array of objects that fits the related objects for that element


Example:
"Set Object = Current_Item Set persons = Get ""Person"" Do Set Relationship Options Params Entity = Object, Element = ""Person"", Options = persons"


Sort Array

Purpose:

  • Use to sort the array of object


Parameters:

  • "Array = Array of Objects to be sorted
  • Element = Sorting Element
  • Order = ASC/DESC"
  • Array* – Array –
  • Element* – String – Element to Filter By
  • Order – String – Order to be used: Ascending or Descending, Asc or Desc. Defaults to Ascending.
  • Null – String – “FIRST”, “LAST” or “ZERO” to indicate behaviour on orderingof null elements. Default is first.


Returns:

  • Sorted Array


Example:
"Set arrObj = Get ""Person"" Set sortedObj = Do Sort Array Params Array = arrObj , Element = ""First Name"", Order = ""ASC""

For i = 1 to sortedObj.Count

  // statement here

Next"

Split String

Purpose:

  • Allows string to be split into seperate parts

Paramaters:

  • String - the string to be split.
  • Divider - optional parameter to specify the divider (if not used, divider will be space).
  • Max Items - optional paramter indicateing the maximum number of parts to return. (if not used, all parts are returned).

Returns:

  • Array of string variables representing each of the parts in the original string.

Example

Set string = "Hello World, It is a sunny day"
Set arr = Do Split String Params String = string
Output = arr.Count
Return_Ok

Output would be 7 arr would be {"Hello","World,","It","is","a","sunny","day"}

Example

Set string = "Hello World, It is a sunny day"
Set divider = ","
Set arr = Do Split String Params String = string, Divider = divider
Output = arr.Count
Return_Ok

Output would be 2 arr would be {"Hello World"," It is a sunny day"}


Store Item

Parameters:

  • Item, Force / returns
  • stores the given item to the database. This will persistently store an newly created item or update an already existing item
  • ‘Item’ is the item to be stored
  • ‘Force’ indicates if the call should be committed to the database now under its own transaction, or whether it should be left until script completion and stored under an overarching transaction capturing all database updates that occur within the script. A value of 1 forces the update now, whilst a value of 0 allows it to operate under the main script transaction (see below for more detailed notes on forcing and when to use it)
  • Note if ‘Force’ is excluded as it is an optional parameter a value of 0 will be assumed (i.e. do not force update now)

Example:

Do Store Item Params Item = fido


Sub String

Purpose:

  • Used to return a part of a string


Parameters:

  • String = Specifies the string to return a part of
  • Search* – String – String to look for
  • From = Integer value that defines where to start in the string
  • Length = The length of the substring to be returned starting from the ""From"" parameter

Returns:

  • Part of string


Example:
"Set Object = Current_Item Set summary = Object[""Summary""] Set desc = Do Sub String Params String = summary, From = 0, Length = 90"

T

Trim String

Purpose:

  • Removes characters at the left, right or both sides of the string

Parameters:

  • String* – String – String to trim
  • Side* – String – Side of the string to trim, Left, Right or Both
  • Remove – String – String to remove, defaults to a space


U

Update Element

Parameters:

  • Object, Element, Value, Force (Optional)

Returns:

  • String
  • Updates the value stored against a specific element on a specific item
  • Is used to improve script efficiency when updating an element on an item, but not making significant modifications to that item, e.g. updating a stock level object for a specific stock item – simply update the current level and leave the remainder of the object untouched
  • Once an element has been updated there is no need to store the associated item. The update element call will ensure that the new value is stored in the database- this has the advantage that it can be used even if the object is locked
  • ‘Object’ parameter is an object variable holding the entity whose element is to be updated
  • ‘Element’ is a string containing the name of the element to be updated
  • ‘Value’ is the new value of the element
  • ‘Force’ indicates if the call should be committed to the database now under its own transaction, or whether it should be left until script completion and stored under an overarching transaction capturing all database updates that occur within the script. A value of 1 forces the update now, whilst a value of 0 allows it to operate under the main script transaction (see below for more detailed notes on forcing and when to use it)
  • Note if ‘Force’ is excluded as it is an optional parameter a value of 0 will be assumed (i.e. do not force update now)
  • The call will return ‘Ok’ if successful

Example:

Set per = Current_Form["Person"]
Set maritalStatus = Current_Form["Status"]
Set ok = Do Update Element Params Object = per, Element = "Marital Status", Value = maritalStatus, Force = 1
If ok != "Ok"
     Output = Current_Form
     Report = "Update Failed"
     Return_Ok
EndIf


Update User

Parameters:

  • Username, Password
  • updates the current User password and username.
  • can be used in conjunction with custom forms to given custom control over usernames and password.
  • returns ‘Ok’ if successful otherwise it returns a string with an error description.

Example:

Set uNme = Current_Form["New Username"]
Set uPwd = Current_Form["New Password"]
Set ans = Do Update User Params Username = uNme, Password = uPwd
If (and != "Ok")
      Report = ans
      Output = Current_Form
      Return_Ok
EndIf

Username List

Parameters:

  • Type* – String – Name of User Type

Output:

  • Array – Array of Strings containing usernames


User Management

Purpose:

  • Set a Password and/or Expiry Date for a user based on their username.

Parameters:

  • Username (essential), New Password – text, Expiry Date – date

Example:

Set expDate = Do Create Date Params Day = 13, Month = 7, Year = 2018 Set res = Do Store User Params Username="user.name ", Password="newPwd123", Expiry Date = expDate Output = res Return_Ok


User Type List

Output:

  • Array – Array of Strings containing user types



V

View Login

Parameters:

  • View, Username, Password / returns; report string variable

Allows scripted transfer between views. This is generally used in conjunction with a custom form in a public view to collect username and password from a user and then log them into a secure view. Parameter ‘View’ provides the name of the view into which the user will be logged in; parameter ‘Username’ is the username of a valid user for the view; and parameter ‘Password’ is the password for the provided username. If the login process is a success then the returned string variable = "Ok", otherwise it will contain a report of the reason for the login failure – such as an incorrect password etc.

Example:

Set un = Current_Form["Username"]
Set pwd = Current_Form["Password"]
Set rep = Do View Login Params View="Pets View", Username=un, Password=pwd
If (rep != "Ok")
     Report = rep
     Output = Current_Form
     Return_Ok
EndIf
Return_Ok


View URL

Returns the URL used to launch a specified View. In the builder, the equivalent would be clicking "Views", selecting a view and clicking "Launch".

Parameters

  • Name: Title of View to generate launch URL for

Example:

Set viewURL = Do View URL Params Name = "Administration"
Output = viewURL
Return_Ok

View Transfer

Parameters:

  • View – String – Name of View to open

Output:

  • String – “Ok”


W

Write Line

Purpose:

  • Used to write a string to a file - .txt .csv .doc


Parameters:

  • "File = Specifies the file to write to

Content = Specifies the string to write to the file"


Returns:

  • File


Example:
"Set persons = Get ""Persons"" Set txtfile = Do Create File Params Name = ""filename"", Type = ""TXT"", Encoding = ""UTF8"" Set content = ""Hello Word"" Do Write Line Params File = txtfile, Content = "content"