NetXMS Wiki

Difference between revisions of "UM:NetXMS Scripting Language (NXSL)"

UM:NetXMS Scripting Language (NXSL) (view source)

Revision as of 16:13, 13 September 2022

5,186 bytes added ,  16:13, 13 September 2022
m
Text replacement - "^" to "{{deprecated}}"
m (Text replacement - "^" to "{{deprecated}}")
 
(9 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:NetXMS Scripting Language (NXSL)}}
{{deprecated}}{{DISPLAYTITLE:NetXMS Scripting Language (NXSL)}}
 
 
{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/#_language_syntax Language syntax]''' for current version of the documentation.
|}
 
 
 
 
= NXSL Overview =
= NXSL Overview =
In many parts of the system, fine tuning can be done by using NetXMS built-in scripting language called NXSL (stands for NetXMS Scripting Language). NXSL was designed specifically to be used as embedded scripting language within NetXMS, and because of this has some specific features and limitations. Most notable is very limited access to data outside script boundaries – for example, from NXSL script you cannot access files on server, nor call external programs, nor even access data of the node object other than script is running for without explicit permission. NXSL is interpreted language – scripts first compiled into internal representation (similar to byte code in Java), which than executed inside NXSL VM.
In many parts of the system, fine tuning can be done by using NetXMS built-in scripting language called NXSL (stands for NetXMS Scripting Language). NXSL was designed specifically to be used as embedded scripting language within NetXMS, and because of this has some specific features and limitations. Most notable is very limited access to data outside script boundaries – for example, from NXSL script you cannot access files on server, nor call external programs, nor even access data of the node object other than script is running for without explicit permission. NXSL is interpreted language – scripts first compiled into internal representation (similar to byte code in Java), which than executed inside NXSL VM.
Line 32: Line 42:
Everything inside /* */ is considered a comment and will be ignored by interpreter. You can enclose comments, like below:
Everything inside /* */ is considered a comment and will be ignored by interpreter. You can enclose comments, like below:


<syntaxhighlight>
<syntaxhighlight lang="c">
/* comment /* another comment */ still comment */
/* comment /* another comment */ still comment */
</syntaxhighlight>
</syntaxhighlight>
Line 76: Line 86:


return is another built-in operator which exits the function and sets it's return value.
return is another built-in operator which exits the function and sets it's return value.
= Script entry point =
NXSL handles script entry in 2 ways:<br>
* Explicit main() function
* Implicit $main() fucntion
If an explicitelly defined main() exists, it will be called.
If an explicit main() doesnt exist, an implicit $main() fucntion will be created by the script interpreter and the script will enter at the $main() function.<br>
The $main() fucntion is constructed from code that is not a part of any other functions.




Line 204: Line 225:
A ''key'' must be a non-negative integer. When an array is created, its size is not specified and its map can have empty spots in it. For example, an array can have a element with a ''0'' key and an element with ''4'' key and no keys in-between. Attempting to access an array key which has not been defined is the same as accessing any other undefined variable: the result will be <tt>NULL</tt>.
A ''key'' must be a non-negative integer. When an array is created, its size is not specified and its map can have empty spots in it. For example, an array can have a element with a ''0'' key and an element with ''4'' key and no keys in-between. Attempting to access an array key which has not been defined is the same as accessing any other undefined variable: the result will be <tt>NULL</tt>.


Array elements can be accessed using [''index''] operator. For example, to access element with index 3 of array ''a'' you should use
<syntaxhighlight lang="c">
a[3];
</syntaxhighlight>
== Array Initialization ==
New array can be created in two ways. First is to use '''array''' operator. <br>
This statement will create empty array and assign reference to it to variable ''a''.
<syntaxhighlight lang="c">
array a;
</syntaxhighlight>
You can then assign values to the array like this.<br>
Please note arrays in NXSL are sparse, so you can have elements with nothing in between.
<syntaxhighlight lang="c">
array a;
a[1] = 1;
a[2] = 2;
a[260] = 260;
println(a[1]); // will print 1
</syntaxhighlight>
Second way is to use %( ) construct to create array already populated with values.<br>
This statement will create array with four elements at positions 0, 1, 2, and 3, and assign reference to this array to variable ''a''.
<syntaxhighlight lang="c">
// no need to use "array a;" here, since we are creating it dirrectly
a = %(1, 2, 3, 4);
println(a[0]); // will actually print 1, since 1 is the 0th member
</syntaxhighlight>
Array initialization can also be used directly in expressions, like this:
<syntaxhighlight lang="c">
sub f()
{
  return %(2, "text", %(1, 2, 3));
}
</syntaxhighlight>
In this example function ''f'' returns array of 3 elements - number, text, and another array of 3 numeric elements.


= Operators =
= Operators =
Line 318: Line 387:
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding-top:0.0236in;padding-bottom:0.0236in;padding-left:0.075in;padding-right:0.075in;"| Match
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding-top:0.0236in;padding-bottom:0.0236in;padding-left:0.075in;padding-right:0.075in;"| Match
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding-top:0.0236in;padding-bottom:0.0236in;padding-left:0.075in;padding-right:0.075in;"| <tt>TRUE</tt> if ''a'' is matched to regular expression ''b''. As a side effect, assigns values to special variables $1, $2, $3, etc. See ''Regular Expressions'' for details.
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding-top:0.0236in;padding-bottom:0.0236in;padding-left:0.075in;padding-right:0.075in;"| <tt>TRUE</tt> if ''a'' is matched to regular expression ''b''. As a side effect, assigns values to special variables $1, $2, $3, etc. See ''Regular Expressions'' for details.
|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding-top:0.0236in;padding-bottom:0.0236in;padding-left:0.075in;padding-right:0.075in;"| a match b
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding-top:0.0236in;padding-bottom:0.0236in;padding-left:0.075in;padding-right:0.075in;"| Match
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding-top:0.0236in;padding-bottom:0.0236in;padding-left:0.075in;padding-right:0.075in;"| <tt>TRUE</tt> if ''a'' is matched to regular expression ''b''. As a side effect, assigns values to special variables $1, $2, $3, etc. See ''Regular Expressions'' for details.
|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding-top:0.0236in;padding-bottom:0.0236in;padding-left:0.075in;padding-right:0.075in;"| a imatch b
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding-top:0.0236in;padding-bottom:0.0236in;padding-left:0.075in;padding-right:0.075in;"| Match (case insensitive)
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding-top:0.0236in;padding-bottom:0.0236in;padding-left:0.075in;padding-right:0.075in;"| <tt>TRUE</tt> if ''a'' is matched to regular expression ''b'' (case insensitive). As a side effect, assigns values to special variables $1, $2, $3, etc. See ''Regular Expressions'' for details.


|}
|}
Line 460: Line 539:
   }
   }
</syntaxhighlight>
</syntaxhighlight>


== return ==
== return ==
Line 485: Line 565:


The last example of expressions is combined operator-assignment expressions. You already know that if you want to increment ''a'' by 1, you can simply write '''a''++' or '++''a'''. But what if you want to add more than one to it, for instance 3? In NXSL, adding 3 to the current value of ''a'' can be written '''a'' += 3'. This means exactly "take the value of ''a'', add 3 to it, and assign it back into ''a''". In addition to being shorter and clearer, this also results in faster execution. The value of '''a'' += 3', like the value of a regular assignment, is the assigned value. Notice that it is NOT 3, but the combined value of ''a'' plus 3 (this is the value that's assigned into ''a''). Any two-place operator can be used in this operator-assignment mode.
The last example of expressions is combined operator-assignment expressions. You already know that if you want to increment ''a'' by 1, you can simply write '''a''++' or '++''a'''. But what if you want to add more than one to it, for instance 3? In NXSL, adding 3 to the current value of ''a'' can be written '''a'' += 3'. This means exactly "take the value of ''a'', add 3 to it, and assign it back into ''a''". In addition to being shorter and clearer, this also results in faster execution. The value of '''a'' += 3', like the value of a regular assignment, is the assigned value. Notice that it is NOT 3, but the combined value of ''a'' plus 3 (this is the value that's assigned into ''a''). Any two-place operator can be used in this operator-assignment mode.
== Short-circuit evaluation ==
[http://en.wikipedia.org/wiki/Short-circuit_evaluation Short-circuit evaluation] denotes the semantics of some Boolean operators in which the second argument is only executed or evaluated if the first argument does not suffice to determine the value of the expression: when the first argument of the AND function evaluates to false, the overall value must be false; and when the first argument of the OR function evaluates to true, the overall value must be true. NXSL uses short-circuit evaluation for && and || boolean operators. This feature permits two useful programming constructs. Firstly, if the first sub-expression checks whether an expensive computation is needed and the check evaluates to false, one can eliminate expensive computation in the second argument. Secondly, it permits a construct where the first expression guarantees a condition without which the second expression may cause a run-time error. Both are illustrated in the following example:
<syntaxhighlight lang="c">
if ((x != null) && ((trim(x) == "abc") || (long_running_test(x))) 
  do_something();
</syntaxhighlight>
Without short-circuit evaluation, trim(x) would cause run-time error if x is null. Also, long running function will only be called if condition (trim(x) == "abc") will be false.
[[Category:Scripting Guide]]
Retrieved from "https://wiki.netxms.org/wiki/Special:MobileDiff/783...2023"