VAR
Examples
Function
Declare local variables. Enables you to create variables to use within a script. The VAR command is often used with the ASSIGN command to store the variable's value.
Syntax
For declaring a string or numeric variable:
VAR VarName = Value
For declaring a variable relative to today's date:
VAR VarName nDays +d
Parameters
VarName |
The name of the variable. Maximum 50 characters. VarName must be unique within the script. |
= |
Required for numeric variables. Optional for strings. |
Value |
The initial value of the field. Required for numeric. Optional for strings. |
nDays |
Only used with the +d option. |
+d |
Creates a date string. |
Operations |
+ - * / |
About fields and field types
The ASSIGN command requires you indicate a field type (0, 6, 7, 14). The server is unaware of what fields exist on any form so you can define any field ID and type you wish. There's no need to update your forms just because you want to store field data.
The fields you create in Designer have pre-determined fields types.
Strings Can contains alpha or numeric values. In Designer, guide text, editable text, and an editable selection list all store strings. All string fields have a field type of 0.
Numbers There are 3 types of number fields.
Short numbers are stored when you create a static selection list, number icon, or radio button. These fields will store a field type of 7.
Long numbers are stored for date fields. Long numbers have a field type of 14. In FirstClass reserved forms 7 and 14 are often used interchangeably.
Checkboxes have a field type of 6. By default a checkbox has 3 values 0, 1 & 2, but the Designer supports up to 10 different states for a checkbox. If you are going to store numbers above 3 in a checkbox, you need to make sure your form is set up to display the optional states.
Examples
Numeric variables
To set a numeric variable to 42, enter:
//Initialize a numeric variable named RegionCode
VAR RegionCode = 42
Get the variable value from a numeric field on a form. The numeric field ID is 8067 and the Region Codes form located within the Projects Application folder.
//Initialize a numeric variable named RegionCode
VAR RegionCode = 0
//Set the RegionCode variable to the current value of field 8067
RegionCode = FORMFIELD "FirstClass applications:projects application:region codes" 8067
When executing a script from and advance from the FIELD keyword is used. You have a rule that executes a script contained in a document within the Project Applications folder. The document is named "Close Project".
//Initialize a numeric variable named Region
VAR RegionCode = 0
//Set the RegionCode variable to the current value of field 8067
RegionCode = field "FirstClass applications:projects application:close project" 8067
String variables
//Declare a string variable, the string has no initial content
VAR RegionName
//Declare a string variable, where the initial value is Sheffield
VAR RegionName = "Sheffield"
With IF
If you have a long and complicated application install script the VAR can be used as a convenient way of changing the behavior of the your script just by adjusting the variables. Your script would be written so that each major section would check for the value of the variables and run commands based on the results.
//If this variable is equal to 1 install the Projects application
VAR Project = 1
//If this variable is equal to 1 install the CRM application
VAR management = 1
IF Project == 1
//a small or large set of commands to perform
write Install the Projects application
ENDIF
IF CRM == 1
//a small or large set of commands to perform
write Install CRM application
ENDIF
If you only wanted to install the Project application you would change:
IF management == 1 to IF management == 0
then run the script.
The VAR value can also be set by using the IF command. For example, if an object exists then set the VAR value to 1, if it is missing set the VAR value to 0.
IF OBJECT "FirstClass applications:projects application" MISSING
VAR Project = 0
Write +c Installing Projects Application
ELSE
VAR Project = 1
Write +c Upgrading Projects Application
ENDIF
With ASSIGN and ENABLEFIELDSUBSTITUTION
To set the region code to 42 and put the value of the variable into the Region Codes document, enter:
//Initialize a numeric variable named RegionCode
VAR RegionCode = 42
ASSIGN RegionCode FORMFIELD "FirstClass Applications:Projects Application:Region Codes" 8067 7
To set the RegionCode to 42 and store the value in field 1001 of the message sent to Batch Admin, enter the commands below. ENABLEFIELDSUBSTITUTION is used to write the contents of field 1001 to server console.
//Initialize a numeric variable named RegionCode
VAR RegionCode = 42
ASSIGN RegionCode FIELD 1001 7
ENABLEFIELDSUBSTITUTION
WRITE +c #1001
After the message is sent to Batch Admin, the message form will have a 1001 field with a value of 42. The server is unaware of what fields exist on a form, so the FIELD parameter can be used to populate fields even if they do not exist on the form. Once you assign the value to the local form any valide command can be used.
Get the variable value from a numeric field on a form. The numeric field ID is 8067 and the Region Codes document located within the Projects Application folder. When creating or troubleshooting a script you may find it useful to have the value displayed on the server console. Adding a REPLY command to the script will send a message that will contain the variable value.
//Initialize a numeric variable named RegionCode
VAR RegionCode = 0
//Set the RegionCode variable to the current value of field 8067
RegionCode = FORMFIELD "FirstClass applications:projects application:region codes" 8067
ASSIGN RegionCode FIELD 1001 7
ENABLEFIELDSUBSTITUTION
WRITE #1001
 NoteYou cannot assign the contents of a string fields to another field, as this function is not supported.
Get the variable value from a numeric field on a form and assign it to a second document. The field IDs can be different. You must initiate a field type. The numeric field ID is 8067 and its field type is 7. The Region Codes form located within the Projects Application folder. The variable value is then assigned to another document named Target.
//Initialize a numeric variable named RegionCode
VAR RegionCode = 0
//Set the RegionCode variable to the current value of field 8067
RegionCode = FORMFIELD "FirstClass applications:projects application:region codes" 8067
ASSIGN RegionCode FORMFIELD "FirstClass applications:projects application:target" 8066 7
The following commands will also accomplish the same task, but use the ENABLEFIELDSUBSTITUTION and the PUT command:
//Initialize a numeric variable named RegionCode
VAR RegionCode = 0
//Set the RegionCode variable to the current value of field 8067
RegionCode = FORMFIELD "FirstClass applications:projects application:region codes" 8067
ASSIGN RegionCode FIELD 1001 7
ENABLEFIELDSUBSTITUTION
PUT "FirstClass applications:projects application:target" 8066 7 #1001
Once you assign the value to the local form any command can be used.
Creating a counter
When new a Project is created, it is assigned a project code. Within the Projects Applications is a Project Code document that has custom field that stores numeric value. The application designer has chosen fieldID 12215. The field currently has a value of 1000. The first time this script is run a folder named 1001 will be created. The second time this script is run a folder named 1002 is created.
//Create and set the initial value for a variable named ProjectCode
VAR ProjectCode = 0
//get current value COUNTER from the form
ProjectCode = ProjectCode + FORMFIELD "FirstClass applications:projects application:project code" 12215
//increase the ProjectCode variable by 1
ProjectCode = ProjectCode + 1
//put the new value into the Project Code document
ASSIGN ProjectCode FORMFIELD "FirstClass applications:projects application:project code" 12215 7
ENABLEFIELDSUBSTITUTION
ASSIGN ProjectCode FIELD 1001 0
//Create new folder based on the project code
NEW "FirstClass applications:projects application" "#1001" "" FOLDER 24043 -1 -1
Reusing an icon
In this example, Susan has a Project Preferences document within her My Projects folder. Susan has used this document to choose an icon for her new Project folders. To create a new project, Susan executes an application rule that runs a script. This portion of the script looks up the value of the icon ID and uses it for the icon of new project folders.
ENABLEFIELDSUBSTITUTION
//sets the path from the desktop of the user that runs the rule
SETBASE +USER
//this command enables you to use the keyword RELATIVE in place of DESKTOP <userID>
SETRELATIVE FROMBASE ""
//define a numeric variable
VAR ProjectIcon = 0
//get value of icon field from the Project Preferences form, the field ID for the icon field is 12209
//in this case RELATIVE is equivilent to DESKTOP sbram
ProjectIcon = ProjectIcon + FORMFIELD RELATIVE "My Projects:Project Preferences" 12209
//assign the ProjectIcon to a local field, icon field are field type 7
ASSIGN ProjectIcon FIELD 1009 7
//uncomment the next line to see the value of field 1009 on the server console
//write +c The folder will be created with icon number #1009
//Create a new project folder, use the ProjectIcon
NEW RELATIVE "My Projects" "Project Highland" "" FOLDER #1009 -1 -1 +p
Dates
The VAR command has an option to capture a date string relative to today's date.
In this example, an application installation script records the date of installation:
// create the string variable to hold today's date
VAR Today +D
//put today's date in a form's field 8021
ASSIGN Today FORMFIELD "FirstClass applications:projects application:Project Preferences" 8021 0
If you wanted to capture a date string for 7 days in the future, enter:
// create the string variable to hold date one week from today.
VAR NxtWeek 7 +D
/
/put next week's date in a form's field 8021
ASSIGN NxtWeek FORMFIELD "FirstClass applications:projects application:Project Preferences" 8021 0
If you wanted to capture a date string for 7 days in the past, enter:
// create the string variable to hold date one week ago.
VAR LstWeek -7 +D
//put last week's date in a form's field 8021
ASSIGN LstWeek FORMFIELD "FirstClass applications:projects application:Project Preferences" 8021 0
Mathematical operations
To add two variable and display the results on the server console, enter:
VAR PRICE = 100
VAR SHIPPING = 10
VAR TOTAL = 0
TOTAL = PRICE + SHIPPING
ASSIGN PRICE FIELD 1000 7
ASSIGN SHIPPING FIELD 1001 7
ASSIGN TOTAL FIELD 1002 7
ENABLEFIELDSUBSTITUTION
WRITE
WRITE PRICE IS SET TO #1000
WRITE
WRITE SHIPPING IS SET TO #1001
WRITE
WRITE TOTAL IS SET TO #1002
WRITE
Concatenating strings
To concatenate 2 strings, enter:
VAR Greeting = Dear
VAR Name = " Ms Bram
Greeting = Greeting + Name
ASSIGN Greeting FIELD 1001 0
ENABLEFIELDSUBSTITUTION
WRITE The greeting is #1001
If the user runs a manual application rule that executes a script, session data is available. The ENABLEFIELDSUBSTITUTION command has been placed before the first field substitution - #7100. This script uses the fully formatted name variable to create a greeting, in this script the variable greeting would be Dear Susan Bram:
ENABLEFIELDSUBSTITUTION
VAR Greeting = Dear
Greeting = Greeting + " #7100:"
ASSIGN Greeting FIELD 1001 0
WRITE The greeting is #1001
With SETBASE
If an application has been registered in the Application Configuration form within FirstClass Applications, the SETBASE +APP appNumber command can be used. For example if the Projects Applications is registered as application number 4001 then this command:
ASSIGN ProjectCode FORMFIELD "FirstClass applications:projects application:project code" 12215 14
could be written as:
SETBASE +APP 4001
ASSIGN ProjectCode FORMFIELD RELATIVE "project code" 12215 7
When Application Rule's Run Batch Admin Script action the the SETBASE +USER command can be used work with from the current user's Desktop:
//define a numeric variable
VAR ProjectIcon = 0
//get value of icon field from the Project Preferences form, the field ID for the icon field is 12209
ProjectIcon = ProjectIcon + FORMFIELD desktop sbram "My Projects:Project Preferences" 12209
could be written as:
//sets the path from the desktop of the user that runs the rule
SETBASE +USER
//this command enables you to use the keyword RELATIVE in place of DESKTOP <user>
SETRELATIVE FROMBASE ""
//define a numeric variable
VAR ProjectIcon = 0
//get value of icon field from the Project Preferences form, the field ID for the icon field is 12209
ProjectIcon = ProjectIcon + FORMFIELD RELATIVE "My Projects:Project Preferences" 12209
Related commands and rule actions
The VAR and ASSIGN commands complement other methods of capturing field values. You can create custom forms and reference the field number within your script using field substitution.
The Application Rule's Run Batch Admin Script gives you access to session data, enabling you to include pre-defined variables for the current user's name, ClientID, UserID, primary organization group, current date and current time.
The Application Rule's Get Confirmation action retains the field data entered in to the confirmation form. Though the default confirmation form only contains a name field, application developers can create custom forms that contain fields required for the application.
See ENABLEFIELDSUBSTITUTION for more information.
|