Variables

From Pengower
Jump to: navigation, search

Here are the basic things you need to know about Pengower Script and how you can use it to create powerful applications.

Introduction

Variables are at the heart of any computer language and allow you to modify, store and analyse different values. Examples of simple variable declarations:

Set x = 1
Set string = "Hello  World"
Set per = Do New Object Params Type = "Person"
Set name = per["First Name"] + " " + per["Surname"]

Simple variables can capture a variety of ideas – strings, numbers, items etc. Array variables capture the idea of groups of items.

Examples of array variable declarations:

Set arr = {}
Set arr = {‘Jan’, ‘Feb’, ‘Mar’, ‘Apr’, ‘May’, ‘Jun’}
Set arr = Get "Person"

Basic How To's

The basic things you need to know in creating Variables for your application.

How to name a Variable

Variables must begin with a letter, a-z or A-Z followed by zero or more characters from the set {a-z, A-Z, 0-9, _}.

For example:

  • ‘i’,
  • ‘I’,
  • ‘i1’,
  • ‘i_i’,
  • ‘test’

... are all okay. However:

  • ‘9z’ (number first),
  • ‘test 2’ (a space character)
  • ‘test#’ (a special character)

... are not okay

How to assign a Variable

Values can be assigned to variables in the following ways:

In the case of strings:

Set out = "Hello World"

In the case of numbers:

Set val = 1.2

In the case of dates:

Set dob = "24/12/2002"
Set dob = "12/24/2002"

Note: Action Script supports both UK (dd/mm/yyyy) and US (mm/dd/yyyy) date formats, but UK format will be assumed unless it produces an invalid date. These strings are automatically interpreted as dates because they conform to the basic date structure.

In the case of time periods;

Set per = "0:0:60:0"

Note; The format for time periods is "<days>:<hours>:<mins>:<secs>".

In the case of arrays:

Set arr = {1, 2, 3}
Set arr = {‘Lauren’, ‘Imogen’, ‘Ben’}

When assigning variables to other variables the syntax is;

Set tmp = tmp1

Note; if no operation is performed on the r.h.s. variable then the allocation is done by reference rather than by value. This means that if ‘tmp1’ is modified the value of ‘tmp’ also changes. If however the expression had been ‘Set tmp = tmp1 * 1’ then modifications of ‘tmp1’ would result in no change to ‘tmp’.

Variable Operators

Variable operators are used to combine variables and / or literals to create or update other variables.

Examples:

Set x = y + 3
Set output = "Hello" + person["First Name"] + ", How are you today?"

Action Script supports a basic range of variable operators;

  • + = addition
  • - = subtraction
  • * = multiplication
  • / = division

There are some basic rules governing how these operators will behave when used in conjunction with variables of differing types (i.e. that contain information of different types):

Addition

  • numbers can be added to other numbers, e.g. Set x = 1 + 2
  • strings can be added to strings, e.g. Set out = "Hello " + "World"
  • any type can be added to a string, e.g. Set out = "Hello " + 2
  • time periods can be added to dates, e.g. Set date = "24/12/2002" + "365:0:0:0"
  • time periods can be added to other time periods, e.g. Set per = "0:30:0:0" + "0:30:0:0"
  • variables can be added to each other, e.g. Set out = x + y
  • a string variable can be added to a number variable to produce a new number variable if the string has a valid interpretation as a number, e.g. Set out = 7 + "23"


Subtraction

  • numbers can be subtracted from other numbers, e.g. Set x = 7 – 3
  • time periods can be subtracted from dates, e.g. Set date = "24/12/2002" – "365:0:0:0"
  • time periods can be subtracted from other time periods, so long as the resultant value is a positive time period, e.g. Set per = "0:60:0:0" - "0:30:0:0"
  • variables can be subtracted from other variables (when the underlying concept is numerical) e.g. Set out = x – y


Multiplication

  • numbers can be multiplied by other numbers e.g. Set x = 7 * 3
  • time periods can be multiplied by numbers, e.g. Set per = "0:60:0:0" * 24
  • variables can be multiplied by other variables (when the underlying concept is numeric), e.g. Set out = x * y


Division

  • numbers can be divided by other numbers e.g. Set x = 7 / 3
  • time periods can be divided by numbers, e.g. Set per = "0:60:0:0" / 2
  • variables can be divided by other variables (when the underlying concept is numeric), e.g. Set out = x / y

Attempts to use operators outside of this permissible range of cases may result in script errors and will certainly result in incorrect values being assigned to the output variable.

The general order of precedence when dealing with operators is strict left to right. But the order of calculation can be influenced through the use of brackets. For example

Set x = 7 – 3 * 2

evaluates to 8, where as

Set x = 7 – (3 * 2)

evaluates to 1.

WARNING: Currently ActionScript does not handle negative numbers particularly elegantly. To create a negative number subtract the required value from 0, e.g. Set neg = 0 – (x * 5).

Special Variables

A number of special variables are defined within ActionScript to make some key concepts available to the developer. These variables are TODAY, NOW, AUTOGEN, NULL, Current_Item, Current_Form, Current_Selection, and Current_User.

How to use TODAY

TODAY variable is used to access a date variable equal to today’s date.

Example:

Set tdy = TODAY
Set tomrw = tdy + "1:0:0:0"


How to use NOW

NOW variable is used to access a date variable equal to the current date and time

Example:

Set person["Created At"] = "NOW"


How to use AUTOGEN

AUTOGEN variable is used to create a unique string that can be used to populate items or forms. The composition of the string is a combination of date and time and current user identity.

Set uid = AUTOGEN


How to use NULL

NULL variable is used to encapsulate the idea of ‘no data present’. Some elements on items may not be set and thus attempting to utilise the value of the element may prove erroneous, thus checking against NULL can alleviate that possible source of error

Example:

Set dob = person["Date of Birth"]
If (NULL = dob)
     Set dob = "01/01/1970"
EndIf


How to use Current_Item

Current_item variable is a special variable used to access the item currently being edited by the user. Current_Item is used in conjunction with save override actions and other special processing actions, e.g. sending emails, to gain access to information about the currently open item.

Example:

// assume the current item is a person
Set firstNme = Current_Item["First Name"]
Set surNme = Current_Item["Surname"]
Set nme = firstNme + " " + surNme


How to use Current_Form

Current_form variable is used in conjunction with custom forms to gain access to the currently open form and through that to data input by the user. It is generally used in actions that are processing the current form.

Set frm = Current_Form
Set name = frm["Name"]
If (name  = "")
     Report = " – Please input a name"
     Output = Current_Form
     Return_Ok
EndIf
Set dept = frm["Department"]…


How to use Current_Selection

Current Selection variable is used when the action containing the script may come from a listing page and we are interested in analysing/processing the items selected by the user.

Example:

Set items = Get "Current_Selection"
For j = 1 To items.Count
     Set itm = items[j]
     Set outStr = outStr + itm["Name"] + ", "
Next


How to use Current_User

This is used when wanting to gain access to the identity of the current user of the system, normally to stamp an item as having been created or updated by them. Note, ActionScript actually access and utilises the underlying item associated with the current user, in some cases no such item exists and the Current_User will be NULL.

Example:

Set person["Created By"] = Current_User

Item Variables

In the previous section the idea of a variable representing an application item was introduced via the Current_User concept. The idea that a variable can represent one of the items in the application and can easily be updated and saved is key to the operation of Action Script. A variable can easily be assigned to any item from the application and the elements of that item easily accessed and updated. The following paragraphs work through the key constructs available when handling item variables.

How to create Item variables

Item variables are created through the use of a specific ‘Do’ command (see later for explanation of the ‘Do’ command). The ‘New Object’ script action is utilised to create an instance of a specific type.

Example;

Set person = Do New Object Params Type = "Person"


How to access Item Elements

Accessing elements of an item is done through a simple syntax utilising the name of the element required.

Set fname = person["First Name"]

where ‘First Name’ is the name of the specifically required element.


How to assign Item variables to Item Elements

Assigning to item elements uses the same basic syntax as accessing.

Example;

Set person["First Name"] = "John"


How to access Item Relationships

Relationships are a special element type as the bind the item in question to other items in the application as governed by the element and relationship definitions. The same basic syntax is utilised as when accessing other elements, but the returned variable is ALWAYS an array. Even when the relationship cardinality dictates that the returned array can contain only one item, an array is returned.

Example;

Set dadArray = person["Father"]
Set dad = dadArray[1]
Set dadName = dad["First Name"] + " " + dad["Surname"]


How to assign Relationships to Items

Assigning to relationship elements is no different from basic element assignment, except that the assignment variable should be an item variable or an array of item variables.

Example:

Set siblingArr = {}
Add broth1 To siblingArr
Add sis1 To siblingArr
Set person["Mother"] = moth
Set person["Brothers and Sisters"] = siblingArr


How to store Items

Storing (saving) of the item associated with an item variable is done through another script action. Until the item and its changes have been stored it persists only in memory and has no permanent storage in the underlying database. The script action is ‘Store Item’.

Example:

Do Store Item Params Item = person


How to delete Items

The deletion of item variables is also completed via a script action accessed through a ‘Do’ command. The script action is ‘Delete Objects’.

Example:

Do Delete Objects Params Objects = person
Do Delete Objects Params Objects = siblingArr

Note, that the deletion routine can handle both individual item variables and arrays of item variables.

WARNING: There is one particular area when working with item variables that needs careful attention if errors are not to occur. This comes when adding new related objects to the current item.

The potential for problems occurs when adding new related items to an item previously saved and loaded from the database, such as the current item. The reason for the problem is that when a relationship element is requested from an item all the relationship data are populated from the database and will not be refreshed until the item is re-loaded again from the database. The easiest way to demonstrate the problem is through the following simple example…

Set john = Current_Item
Set pet = Do New Object Params Type = "Pet"
Set pet["Type"] = "Dog"
Set pet["Name"] = "Fido"
Set pet["Owner"] = "john"
Do Store Item Params Item = "pet"
Do Store Item Params Item = "john"
Output = john
Return_Ok

This script will NOT work correctly. ‘Fido’ will be created and associated with ‘john’ correctly, so at the point that ‘Fido’ is stored everything is correct. However, ‘john’ is a fully populated item with all relationship data loaded and thus when ‘john’ is stored the link to ‘Fido’ is broken as ‘john’s existing pet information is re-committed to the database. To make this script work correctly use the following approach;

Set john = Current_Item
Set pets = john["Pets"]
Set pet = Do New Object Params Type = "Pet"
Set pet["Type"] = "Dog"
Set pet["Name"] = "Fido"
Do Store Item Params Item = "pet"
Add pet To pets
Set john["Pets"] = pets
Do Store Item Params Item = john
Output = john
Return_Ok

This script will work correctly and link ‘Fido’ to ‘john’ and make the relationship persist correctly in the database.


How to use Set Statements to assign and declare variables

The Set statement allows for the declaration of and assignment to variables. There are four possible syntactic variations;

Set [va] = [expression]
Set [var] = [do_command]
Set [var] = [get_command]
Set [var] = {[var], [var] … }

where [var] represents a variable being declared and assigned to or simply assigned to. Examples of valid Set statements are;

Set x = 2 + 3 + y
Set y = y + 1
Set arr = {1, 2, 3}
Set outStr = "Hello World. The answer is " + ans

Variables in called scripts

In some versions of the platform, when you call a script with Do Run Script the called script may not correctly deal with all the passed variables. This can lead to problems with saving items in called scripts.

Add Set varname = varname for each param at the top of the script.


See Also

You might find the following topics useful:

Arrays