Syntax of CubePL

Syntax step by step

This chapter introduced the CubePL syntax of the most common programming structures.

Expressions

Constants

Any constant expression is an expression. eg. 123.0, "someString"

Arithmetical Expressions

Common mathematical notation of an arithmetical expression is valid in CubePL. Any arithmetical expression is an expression. eg. 123.0 + 23.6, sin(23)

Boolean Expressions

Common literal notation of a boolean expression is valid in CubePL. Any boolean expression is an expression.

[expression] or|and|xor [expression]

or

not [expression]

Any expression can be a term of a boolean expression. Non zero value is observed as TRUE, zero value is FALSE.

Function call expressions

Function calls have the following syntax:

name ( [expression ] )

Lambda function (In-place function definition)

To define a function in-place, one uses the following syntax:

{
  [statement];
  [statement];
  ...
  return [expression];
}

In-place definition of a function is an expression. It means, it can appear everywhere, where one can use an expression.

Control structures

Control structures like if-else or while are statements.

Condition IF-ELSE

One can execute series of statements under a condition using the short form of the if statement:

if ( condition )
{
 [statement];
 [statement];
 ...
}

or full form with else :

 if ( condition )
 {
  [statement];
  [statement];
  ...
 }
 else
{
  [statement];
  [statement];
  ...
 }

condition is a boolean expression

Loop WHILE

One can execute a series of statements as long as a condition is true using the while statement:

while ( condition )
{
 [statement];
 [statement];
 ...
}

Sequence of statements will be executed till condition is not fulfilled, max 1000000000 times.

Variables

CubePL allows to work with memory, by using variables. All variables are multi-typed:

• In string context value of a numeric variable is presented in string format.
• In numerical context a string variable is converted to its numerical representation, if possible. Otherwise it is 0.

All variables are arrays. Indexless access to the variable assummes mutually index value 0.

User defined Variables

The user can define a variable using the syntax:

${ name } = [expression];

or

${ name }[index] = [expression];

Currently its name is a fixed string of characters. In later versions of CubePL it will allow any expression.

Example of a string context :

${name} seq "STRING"

Example of a numeric context :

${name} >= 0.34

Example of an array access to the variable :

${name}[ ${i} ] >= 0.34

Access to the variable is an expression.

Index for the access to the value is also an expression.

Predefined Variables

Cube provides a set of predefined variables for every calculation, which values are independend. Following predefined variables do contain the general information about the cube:

Predefined variable	Explanation
cube::#mirrors	Number of mirrors in cube file
cube::#metrics	Number of metrics in cube file
cube::#root::metrics	Number of root metrics in cube file
cube::#regions	Number of regions in cube file
cube::#callpaths	Number of call paths in cube file
cube::#root::callpaths	Number of root call paths
cube::#locations	Number of locations in cube file
cube::#locations::void	Number of void locations in cube file
cube::#locations::nonvoid	Number of nonvoid locations in cube file
cube::#locationgroups	Number of location groups in cube file
cube::#locationgroups::void	Number of void location groups in cube file
cube::#locationgroups::nonvoid	Number of nonvoid location groups in cube file
cube::#stns	Number of system tree nodes in cube file
cube::#rootstns	Number of root system tree nodes in cube file
cube::filename	Name of the cube file

CubePL engine defines a set of variables, which do depend on an index, their "id". Using call sizeof(...) one can run over them and inspect within CubePL expression.

cube::metric::unit::name	Unique name of the metric
cube::metric::disp::name	Display name of the metric
cube::metric::url	URL of the documentation of the metric
cube::metric::description	Description of the metric
cube::metric::dtype	Data type of the metric
cube::metric::uom	Unit of measurement of the metric
cube::metric::expression	CubePL expression of the metric
cube::metric::initexpression	CubePL initialisation expression of the metric
cube::metric::parentd::id	ID of the parent of the metric
cube::metric::#children	Number of children in the metric

cube::callpath::mod	Module of the call path
cube::callpath::line	File line of the call path
cube::calleeid	ID of the callee region
cube::callpath::#children	Number of children in the call path
cube::callpath::parent::id	ID of the parent callpath

cube::region::name	Name of the region
cube::region::mangled::name	Mangled name of the region
cube::region::paradigm	Name of the paradigm of the region
cube::region::role	Name of the role the region is playing within the paradigm
cube::region::url	URL with the description of the region of the call path
cube::region::description	Description of the region of the call path
cube::region::mod	Module of the region of the call path
cube::region::begin::line	Begin line of the region of the call path
cube::region::end::line	End line of the region of the call path

cube::stn::name	Name of the system tree node
cube::stn::class	Class of the system tree node
cube::stn::description	Description of the system tree node
cube::stn::#children	Number of children (other system tree nodes) of the system tree node
cube::stn::#locationgroups	Number of location groups of the system tree node
cube::stn::parent::id	ID (among all system tree nodes) of the parent of the system tree node
cube::stn::parent::sysid	ID (global) of the parent of the system tree node

cube::locationgroup::name	Name of the location group
cube::locationgroup::rank	Rank of the location group
cube::locationgroup::type	Type of the location group
cube::locationgroup::void	Is the this location group void?
cube::locationgroup::#locations	Number of locations of the location group
cube::locationgroup::parent::id	ID (amoung all system tree nodes) of the parent system tree node
cube::locationgroup::parent::sysid	ID (global) of the parent system tree node

cube::location::name	Name of the location
cube::location::rank	Rank of the location
cube::location::type	Type of the location
cube::location::void	Is the this location void?
cube::location::parent::id	ID (among all location groups) of the parent location group
cube::location::parent::sysid	ID (global) of the parent location group

CubePL engine sets a series of context sensetive variables, which value depends on the paramaters, for which the derived metric is being calculated. Their value can be used to refer to the values of context insensitive variables described above:

calculation::metric::id	ID of the metric, being calculated
calculation::callpath::id	ID of the callpath, for what is the metric being calculated
calculation::callpath::state	State of the callpath (inclusive=0, exclusive=1, same=2), for what is the metric being calculated
calculation::callpath::#elements	Number of selected callpath, for which is metric being calculated. Usually bigger than 1 only for postderived metrics
calculation::region::id	ID of the region, for what is the metric being calculated
calculation::region::#elements	Number of selected regions, for which is metric being calculated. Usually bigger than 1 only for postderived metrics
calculation::sysres::id	ID (local within system resource type) if the sysem resource, for what is the metric being calculated
calculation::sysres::sysid	ID (global) if the sysem resource, for what is the metric being calculated
calculation::sysres::kind	Type of the system element: 0 = unknown 5 = system tree node 6 = location group 7 = location
calculation::sysres::#elements	Number of selected system tree elements, for which is metric being calculated. Usually bigger than 1 only for postderived metrics

Different ways to refer an another metric

Context sensitive reference to another metric

To use values of another metric in the same calculation context, one uses syntax:

metric::[uniq_name]( modificator, modificator )

or

metric::[uniq_name]( modificator)

or

metric::[uniq_name]()

There are three version of this call:

1. with two arguments (call path and system);
2. with one argument (call path);
3. with no argument(an arguments takes as '*').

modificator specifies flavor of the calculation: i - inclusive, e - exclusive, * - same like in calculation context.

Metric reference is an expression.

Context insensitive reference to another metric

To use values of another metric in the some fixed calculation context (e.g. aggregated over threads), one uses syntax:

metric::fixed::[uniq_name]( modificator, modificator )

or

metric::fixed::[uniq_name]( modificator)

or

metric::fixed::[uniq_name]()

There are three version of this call:

1. with two arguments (call path and system);
2. with one argument (call path);
3. with no argument(an arguments takes as '*').

modificator specifies flavor of the calculation: i - inclusive, e - exclusive, * - same like in calculation context.

Metric reference is an expression.

Direct reference to another metric

To use values of another metric with an specific call path id and system resource id (!), one uses syntax:

metric::call::[uniq_name]( callpath id, modificator, sysres id, modificator )

or

metric::call::[uniq_name]( callpath id, modificator )

There are two version of this call:

1. with four arguments (call path and system); - Only callculation of an inclusive or exclusive value is performed
2. with one argument (call path); - Aggragation over system tree is performed additionally to the calculation of the inclisive or exclusive value for the calltree id

modificator specifies flavor of the calculation: i - inclusive, e - exclusive.

Metric reference is an expression.

Note that "sysres id" is a global identificator and can be refered using ${calculation::sysres::id}.

Definition of an encapsulated calculation within CubePL expression using metrics of Cube.

One special mechanis of CubePL processing engine allows some level of calculation separation. A derived metric can be created within another CubePL expression. Such "ghost" metric gets its name and properties and exists inside of the cube object as a casual metric. Only difference to the casual metric is in the fact that ghost metric is not visible in GUI and tools and is not stored inside of the metric tree of the cube file.

One can refer such metric as a casual metric using metric references (see 'Context sensitive reference to another metric' , 'Context insensitive reference to another metric' and 'Direct reference to another metric' ).

Example for definition of such metric :

cube::metric::nvisitors(e)
<<
{
  ${return}=0;
  if ( ${cube::locationgroup::void}[${calculation::sysres::id}]  != 1)
  {
    if (metric::visits()>0 )
    {
      ${return} = 1;
    };
  };
  return ${return};
}
>>;
${visitors} = metric::fixed::nvisitors(e);

where

cube::metric::prederived::nvisitors(e)

gives a type (prederives, exclusive) and unique name (nvisitors) of this metric. Unique name is used then later to refer to this metric via

${visitors} = metric::fixed::nvisitors(e);

There are kinds of metrics, which can be defined on such manner:

1. cube::metric::prederived::name(e) - An exclusive prederived metric with the name name;
2. cube::metric::prederived::name(i) - An inclusive prederived metric with the name name;
3. cube::metric::postderived::name - A postderived metric with the name name.

Notice that once the metric with some unique name created it exists whole lifetime of the cube object. Therefore one can refer to some somewhere previously defined ghost metric from any following it CubePL expressions.

Ghost Metric definition is a statement.

Definition of an initialization expression for ghost metrics within CubePL expression.

One can specify within of a CubePL expression an initialisation phase for previously created ghost metric. For that purpose one uses expression cube::init::metric::[name]. Notice that named metric should be know by the moment of compilation of the CubePL expression.

Example for definition of such metric :

cube::init::metric::init::nvisitors
<<
{
  global(nvisitors);
}
>>;

where

cube::init::metric::nvisitors

uses an unique name (nvisitors) of the metric.

Definition of the initialisation phase of a metric is a statement.

Definition of an initialization expression for ghost metrics within CubePL expression.

One can specify within of a CubePL expression an aggregation operator "+" or "-" for previously created ghost metric. For that purpose one uses expression cube::metric::plus::[name] or cube::metric::minus::[name]. Notice that named metric should be know by the moment of compilation of the CubePL expression.

Example for definition of such metric :

cube::init::metric::plus::nvisitors
<<
max( arg1, arg2)
>>;

or

cube::init::metric::minus::nvisitors
<<
min( arg1, arg2)
>>;

where

cube::init::metric:plus::nvisitors

or

cube::init::metric:minus::nvisitors

uses an unique name (nvisitors) of the metric.

Definition of the initialisation phase of a metric is a statement.

Grammar of CubePL

Here will be a full grammar of CubePL expressions (later).