About free variables that are globally available in a Polybench project, or within a namespace

Free Global and Namespace Variables

Overview

Free variables contain values that are not bound to any object in your project. Polybench knows two different kinds of free variables: Global Variables that can be accessed anywhere in your project, and Namespace Variables that are only available in the namespace ("Namespaces in a project") they were defined in.

Free variables can either be defined by a SET_PARAMETER action ("SET_PARAMETER"), or by specifying them in the arguments of Polybench executables ("Polybench Designer" and "Polybench Scientific Runtime"). There is a number of pre-defined global variables that are specified below.

Items

??????

Unknown address, or Variable has not been set.
If in a display that should have shown a value in place of an address the text '??????' is shown, then the address is not correct. Please check if the address exists. If the address points to a global variable, then the variable has not (yet) been set to a value. For example:

$Constant1.Valuw is shown as ??????: The variable parameter cannot be found (mis-spelling!)
$var$ is shown as ??????: The global variable $var$ has not yet been given a value.

xxxxxx

Value cannot be displayed, or Wrong format.
If in a display that should have shown a value in place of an address the text 'xxxxxx' is shown, then the address is correct, but the value cannot be shown in the text. Please check if the address refers to something that can be displayed as text. For example:

$Constant1 is shown as xxxxxx: An object with the addres $Constant1 has been found, but the address refers to an operator, and not a value. $Constant1.Value may be correct in stead.

$NL$

New line character
Use $NL$ to get the a carriage return/line feed (New Line) character. You may use this for building strings out of variables, if you need your text output to be on multiple lines.

$startupfolder$

Use '$startupfolder$' to get the folder where Polybench is installed (probably a sub-folder of C:\Program Files\).

$doc$

Use '$doc$' to get the standard Documents folder (My Documents in Windows XP) of the current Windows account. On different computers and user accounts this path may be different.
Example: $doc$\Polybench\ is the folder 'Polybench' in your Documents folder.

$appdata$

Use '$appdata$' to get the standard Application Data folder path of the roaming user of the current Windows account. In this folder software programs typically store their settings.

$desktop$

Use '$desktop$' to get the Desktop folder path on the current Windows account.

$applicationfolder$

Use $applicationfolder$ to get the path of the folder in which this project is located.
You could use this, for example, to load a data file that is located in the same folder as this project. You would then use a path like: $applicationfolder$\Sample.DataFile.csv.

$applicationfilename$

Use $applicationfilename$ to get the file name (without folder) of this project.

$year$

Use $year$ to get the current year, for example '1975'.

$month$

Use $month$ to get the number of the current month in two digits, for example '07'.

$day$

Use $day$ to get the number of the current day of the month in two digits, for example '03'.

$hour$

Use $hour$ to get the number of the current hour in two digits, for example '09'.

$minute$

Use $minute$ to get the number of the current minute in two digits, for example '45'.

$second$

Use $second$ to get the number of the current second in two digits, for example '05'.

$dayname$

Use $dayname$ to get the name of the current week day in the language of the culture that has been set for the operating system.
For example on a US computer: 'Monday'; on a German computer: 'Montag'.

$universalms$

Use $universalms$ to get a practically indefinite millisecond counter. This value counts the milliseconds passed since 12:00:00 midnight, January 1, 0001.

$polybenchversion$

Use $polybenchversion$ to get a version number of the Polybench engine that is currently used.
The version number consists of four numbers separated by dots. This number could be handy for support calls.

$ext$

The variable $ext$ does not have a value by default. It is only used in a specific context, for example for setting file storage settings. This variable however is reserved and cannot be used for other purposes.

$alias$

The variable $alias$ does not have a value by default. It is only used in a specific context, for example for setting file storage settings. This variable however is reserved and cannot be used for other purposes.

$applicationname$

Use $applicationname$ to display the name of the project. See the Caption property of the project ("Project").

$applicationversion$

Use $applicationversion$ to display the version of the project. See the Version property of the project ("Project").

$applicationdescription$

Use $applicationdescription$ to display the description of the project. See the Description property of the project ("Project").

$applicationauthor$

Use $applicationauthor$ to display the author of the project. See the Author property of the project ("Project").

$applicationcopyright$

Use $applicationcopyright$ to display the copyright information of the project. See the Copyright property of the project ("Project").

$applicationhelpurl$

Use $applicationhelpurl$ to display or use the Help URL for this project, which is a URL to a website containing information about the project (or the application that is the result of this project). See the HelpURL property of the project ("Project").

$applicationlicense$

Use $applicationlicense$ to get the identifier of the license that is used to run this application.

$computername$

Use $computername$ to get the name of your computer. This is the NetBIOS name.

$operatingsystemversion$

Use $operatingsystemversion$ to get the version of the OS of the computer Polybench runs on.

$computerusername$

Use $computerusername$ to get the user name of the user that is currently logged in into Windows.

$screenheight$

Use $screenheight$ to get the height of the current screen in pixels. You may also want to use $screenwidth$.

$screenwidth$

Use $screenwidth$ to get the width of the current screen in pixels. You may also want to use $screenheight$.

$PI$

Use $PI$ to get the mathematical constant π (approximately 3.141592). This constant contains an estimate of π that has the maximum precision representable in a 64-bit floating point value.
The value is only set after Polybench has started up. You can overwrite the variable at any time.

$E$

Use $E$ to get the mathematical constant that is the base of the natural logarithm e (approximately 2.71828). This constant contains an estimate of e that has the maximum precision representable in a 64-bit floating point value.
The value is only set after Polybench has started up. You can overwrite the variable at any time.

Details

Syntax

A free variable is always written like:

$[variable name]$

So, a free variable is always enclosed by two '$'-signs. The variable name may contain spaces, numbers and some other characters, but it must not contain dots '.', nor '@' signs.

Use a pre-defined global variable

To demonstrate the use of pre-defined global variables, follow the next steps:
- Get a Variable Viewer ("Variable Viewer") from the toolbox and open its properties.
- In the property Addresses and Text fill in any of the listed global variables, for example:

The time is $hour$:$minute$:$second$

The Variable Viewer will now show a continuously updating time.

Add a free variable from within the project

A new free variable is created as soon as you try to write a value to a new variable name. Writing values to a variable is done using the SET_PARAMETER action ("SET_PARAMETER"). The variable is only available in the namespace of the component that called the SET_PARAMETER action.
For example, the following action will create a new global variable $var$, if that variable did not already exist:
action: SET_PARAMETER
address: $var$
value: Some text or a numerical value

After executing that action (for example using an Action Button), $var$ contains "Some text or a numerical value", but only on pages in the same namespace as the defining object had. On pages in other namespaces, the same variable name can be used for different values.

If a free variable is defined by the project start-up action (see properties of the project, "Project"), the variable is defined in the default namespace 'Main'.

Add a free global variable at start-up

When starting Polybench.exe ("Polybench Designer") or PolybenchRun.exe ("Polybench Scientific Runtime"), you may specify arguments. A couple of standard arguments have been defined, but any other argument names are translated to free global variables in the Main namespace.

For example, if you start Polybench Designer like this:

Polybench.exe /program:"MyApp.xmc" /MyVariable:12.3

then if MyApp.xmc is loaded, it will contain a free variable called $MyVariable$ and its value is 12.3.
The variable is only available in the default Main namespace!

Polybench Manager allows to specify custom arguments for apps that are started from the application quick-start panel in the Application Start dialog ("Application Start Buttons").