NetXMS Wiki - User contributions [en]

NXSL Class Reference

2020-10-05T14:21:35Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/#_class_reference NXSL Class Reference]''' for current version of the documentation.
|}

===NetObj and its sub-classes===
[[NXSL:NetObj|NetObj]]

- [[NXSL:Cluster|Cluster]]

- [[NXSL:Interface|Interface]]

- [[NXSL:Node|Node]]

- [[NXSL:Zone|Zone]]

===SNMP related classes===
[[NXSL:SNMP_Transport|SNMP_Transport]]

[[NXSL:SNMP_VarBind|SNMP_VarBind]]

===Other classes===
[[NXSL:Alarm|Alarm]]

[[NXSL:Component|Component]]

[[NXSL:DCI|DCI]]

[[NXSL:Event|Event]]

[[NXSL:FILE|FILE]]

[[NXSL:GeoLocation|GeoLocation]]

[[NXSL:InetAddress|InetAddress]]

[[NXSL:NewNode|NewNode]]

[[NXSL:Situation|Situation]]

[[NXSL:Table|Table]]

[[NXSL:TableColumn|TableColumn]]

[[NXSL:TIME|TIME]]

[[NXSL:UserDBObject|UserDBObject]]

-[[NXSL:User|User]]

-[[NXSL:UserGroup|UserGroup]]

[[Category:Scripting Guide]]

NXSL Function Reference

2020-10-05T14:20:59Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/#_function_reference NXSL Function Reference] for current version of the documentation.
|}

= Function tables =
{| {border="1" cellpadding="4" cellspacing="2" style="border:\#c9c9c9 1px solid; margin: 1em 1em 1em 0; border-collapse: collapse;"}
| align="center" style="background:#f0f0f0;"|'''Generic'''
| align="center" style="background:#f0f0f0;"|'''Math'''
| align="center" style="background:#f0f0f0;"|'''String-related'''
| align="center" style="background:#f0f0f0;"|'''Data Collection'''
| align="center" style="background:#f0f0f0;"|'''Object search'''
| align="center" style="background:#f0f0f0;"|'''Object management'''
| align="center" style="background:#f0f0f0;"|'''Network'''
|-
| [[NXSL:CountScheduledTasksByKey|CountScheduledTasksByKey]]||[[NXSL:abs|abs]]||[[NXSL:ArrayToString|ArrayToString]]||[[NXSL:CreateDCI|CreateDCI]]||[[NXSL:FindNodeObject|FindNodeObject]]||[[NXSL:BindObject|BindObject]]||[[NXSL:AddrInRange|AddrInRange]]
|-
| [[NXSL:classof|classof]]||[[NXSL:ceil|ceil]]||[[NXSL:chr|chr]]||[[NXSL:FindAllDCIs|FindAllDCIs]]||[[NXSL:FindObject|FindObject]]||[[NXSL:CreateContainer|CreateContainer]]||[[NXSL:AddrInSubnet|AddrInSubnet]]
|-
| [[NXSL:d2x|d2x]]||[[NXSL:exp|exp]]||[[NXSL:format|format]]||[[NXSL:FindDCIByDescription|FindDCIByDescription]]||[[NXSL:GetInterfaceName|GetInterfaceName]]||[[NXSL:CreateNode|CreateNode]]||[[NXSL:gethostbyaddr|gethostbyaddr]]
|-
| [[NXSL:exit|exit]]||[[NXSL:floor|floor]]||[[NXSL:index|index]]||[[NXSL:FindDCIByName|FindDCIByName]]||[[NXSL:GetInterfaceObject|GetInterfaceObject]]||[[NXSL:DeleteCustomAttribute|DeleteCustomAttribute]]||[[NXSL:gethostbyname|gethostbyname]]
|-
| [[NXSL:GetConfigurationVariable|GetConfigurationVariable]]||[[NXSL:log|log]]||[[NXSL:left|left]]||[[NXSL:GetAvgDCIValue|GetAvgDCIValue]]||[[NXSL:GetNodeInterfaces|GetNodeInterfaces]]||[[NXSL:DeleteObject|DeleteObject]]||
|-
| [[NXSL:inList|inList]]||[[NXSL:log10|log10]]||[[NXSL:length|length]]||[[NXSL:GetDCIObject|GetDCIObject]]||[[NXSL:GetNodeParents|GetNodeParents]]||[[NXSL:EnterMaintenance|EnterMaintenance]]||
|-
| [[NXSL:map|map]]||[[NXSL:pow|pow]]||[[NXSL:lower|lower]]||[[NXSL:GetDCIRawValue|GetDCIRawValue]]||[[NXSL:GetNodeTemplates|GetNodeTemplates]]||[[NXSL:GetCustomAttribute|GetCustomAttribute]]||
|-
| [[NXSL:mapList|mapList]]||[[NXSL:round|round]]||[[NXSL:ltrim|ltrim]]||[[NXSL:GetDCIValue|GetDCIValue]]||[[NXSL:GetObjectChildren|GetObjectChildren]]||[[NXSL:LeaveMaintenance|LeaveMaintenance]]||
|-
| [[NXSL:max|max]]||||[[NXSL:ord|ord]]||[[NXSL:GetDCIValues|GetDCIValues]]||[[NXSL:GetObjectParents|GetObjectParents]]||[[NXSL:ManageObject|ManageObject]]||
|-
| [[NXSL:min|min]]||||[[NXSL:right|right]]||[[NXSL:GetDCIValueByDescription|GetDCIValueByDescription]]||[[NXSL:GetAllNodes|GetAllNodes]]||[[NXSL:RenameObject|RenameObject]]||
|-
| [[NXSL:random|random]]||||[[NXSL:rindex|rindex]]||[[NXSL:GetDCIValueByName|GetDCIValueByName]]||||[[NXSL:SetCustomAttribute|SetCustomAttribute]]||
|-
| [[NXSL:sleep|sleep]]||||[[NXSL:rtrim|rtrim]]||[[NXSL:GetMaxDCIValue|GetMaxDCIValue]]||||[[NXSL:SetInterfaceExpectedState|SetInterfaceExpectedState]]||
|-
| [[NXSL:trace|trace]]||||[[NXSL:SplitString|SplitString]]||[[NXSL:GetMinDCIValue|GetMinDCIValue]]||||[[NXSL:UnbindObject|UnbindObject]]||
|-
| [[NXSL:typeof|typeof]]||||[[NXSL:substr|substr]]||[[NXSL:GetSumDCIValue|GetSumDCIValue]]||||[[NXSL:UnmanageObject|UnmanageObject]]||
|-
| [[NXSL:x2d|x2d]]||||[[NXSL:trim|trim]]||[[NXSL:PushDCIData|PushDCIData]]||||||
|-
| ||||[[NXSL:upper|upper]]||||||||
|}
<hr>

{| {border="1" cellpadding="4" cellspacing="2" style="border:\#c9c9c9 1px solid; margin: 1em 1em 1em 0; border-collapse: collapse;"}
| align="center" style="background:#f0f0f0;"|'''Time-related'''
| align="center" style="background:#f0f0f0;"|'''Cryptography'''
| align="center" style="background:#f0f0f0;"|'''SNMP'''
| align="center" style="background:#f0f0f0;"|'''Agent'''
| align="center" style="background:#f0f0f0;"|'''Event Processing'''
| align="center" style="background:#f0f0f0;"|'''Persistent Storage'''
| align="center" style="background:#f0f0f0;"|'''File I/O'''
|-
| [[NXSL:gmtime|gmtime]]||[[NXSL:md5|md5]]||[[NXSL:CreateSNMPTransport|CreateSNMPTransport]]||[[NXSL:AgentReadList|AgentReadList]]||[[NXSL:FindAlarmById|FindAlarmById]]||[[NXSL:ReadPersistentStorage|ReadPersistentStorage]]||[[NXSL:CopyFile|CopyFile]]||
|-
| [[NXSL:localtime|localtime]]||[[NXSL:sha1|sha1]]||[[NXSL:SNMPGet|SNMPGet]]||[[NXSL:AgentReadParameter|AgentReadParameter]]||[[NXSL:FindAlarmByKey|FindAlarmByKey]]||[[NXSL:WritePersistentStorage|WritePersistentStorage]]||[[NXSL:CreateDirectory|CreateDirectory]]||
|-
| [[NXSL:SecondsToUptime|SecondsToUptime]]||[[NXSL:sha256|sha256]]||[[NXSL:SNMPGetValue|SNMPGetValue]]||[[NXSL:AgentReadTable|AgentReadTable]]||[[NXSL:FindAlarmByKeyRegex|FindAlarmByKeyRegex]]||||[[NXSL:DeleteFile|DeleteFile]]||
|-
| [[NXSL:strftime|strftime]]||||[[NXSL:SNMPSet|SNMPSet]]||||[[NXSL:GetEventParameter|GetEventParameter]]||||[[NXSL:FileAccess|FileAccess]]
|-
| [[NXSL:time|time]]||||[[NXSL:SNMPWalk|SNMPWalk]]||||[[NXSL:PostEvent|PostEvent]]||||[[NXSL:OpenFile|OpenFile]]
|-
| [[NXSL:mktime|mktime]]||||||||[[NXSL:SetEventParameter|SetEventParameter]]||||[[NXSL:RemoveDirectory|RemoveDirectory]]||
|-
| ||||||||||||[[NXSL:RenameFile|RenameFile]]||
|}

NXSL Formal Grammar

2020-10-05T14:20:22Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/#_formal_grammar NXSL Formal Grammar]''' for current version of the documentation.
|}

<pre>
script ::=
module |
expression

module ::=
module_component { module_component }

module_component ::=
function |
statement_or_block |
use_statement

use_statement ::=
use any_identifier ";"

any_identifier ::=
IDENTIFIER |
COMPOUND_IDENTFIER

function ::=
sub IDENTIFIER "(" [ identifier_list ] ")" block

identifier_list ::=
IDENTIFIER { "," IDENTIFIER }

block ::=
"{" { statement_or_block } "}"

statement_or_block ::=
statement |
block

statement ::=
expression ";" |
builtin_statement |
";"

builtin_statement ::=
simple_statement ";" |
if_statement |
do_statement |
while_statement |
for_statement |
foreach_statement |
switch_statement |
array_statement |
global_statement |
break ";"
continue ";"

simple_statement ::=
keyword [ expression ]

keyword ::=
exit |
print |
println |
return

if_statement ::=
if "(" expression ")" statement_or_block [ else statement_or_block ]

for_statement ::=
for "(" expression ";" expression ";" expression ")" statement_or_block

foreach_statement ::=
foreach "(" IDENTIFIER ":" expression ")" statement_or_block

while_statement ::=
while "(" expression ")" statement_or_block

do_statement ::=
do statement_or_block while "(" expression ")" ";"

switch_statement ::=
switch "(" expression ")" "{" case { case } [ default ] "}"

case ::=
case constant ":" { statement_or_block }

default ::=
default ":" { statement_or_block }

array_statement ::=
[ global ] array identifier_list ";"

global_statement ::=
global global_variable_declaration { "," global_variable_declaration } ";"

global_variable_declaration ::=
IDENTIFIER [ "=" expression ]

expression ::=
"(" expression ")" |
IDENTIFIER "=" expression |
expression "->" IDENTIFIER |
"-" expression |
"!" expression |
"~" expression |
inc IDENTIFIER |
dec IDENTIFIER |
IDENTIFIER inc |
IDENTIFIER dec |
expression "+" expression |
expression "-" expression |
expression "*" expression |
expression "/" expression |
expression "%" expression |
expression like expression |
expression ilike expression |
expression "~=" expression |
expression match expression |
expression imatch expression |
expression "==" expression |
expression "!=" expression |
expression "<" expression |
expression "<=" expression |
expression ">" expression |
expression ">=" expression |
expression "&" expression |
expression "|" expression |
expression "^" expression |
expression "&&" expression |
expression "||" expression |
expression "<<" expression |
expression ">>" expression |
expression "." expression |
expression "?" expression ":" expression |
operand

operand ::=
function_call |
type_cast |
constant |
IDENTIFIER

type_cast ::=
builtin_type "(" expression ")"

builtin_type ::=
int32 |
int64 |
uint32 |
uint64 |
real |
string

function_call ::=
IDENTIFIER "(" [ expression { "," expression } ] ")"

constant ::=
STRING |
INT32 |
INT64 |
UINT32 |
UINT64 |
REAL |
NULL
</pre>

'''Terminal symbols'''

<pre>
IDENTIFIER ::= [A-Za-z_\$][A-Za-z_\$0-9]*
COMPOUND_IDENTIFIER ::= { IDENTIFIER}(::{ IDENTIFIER})+
INTEGER ::= \-?(0x)?[0-9]+
INT32 ::= INTEGER
INT64 ::= {INTEGER}L
UINT32 ::= {INTEGER}U
UINT64 ::= {INTEGER}(UL|LU)
REAL ::= \-?[0-9]+\.[0-9]+
</pre>

[[Category:Scripting Guide]]

Script Example: Setting node geolocation from SNMP

2020-10-05T14:19:44Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/#_examples_2 NetXMS Script examples]''' for current version of the documentation.
|}

Adjust the OIDs in ''SNMPGetValue'' as required.

<syntaxhighlight lang="c">
transport = CreateSNMPTransport($node);
if (transport == null) {
return null;
}

lat = SNMPGetValue(transport, ".1.2.3.4.1");
lon = SNMPGetValue(transport, ".1.2.3.4.2");

if (lat == null || lon == null) {
return null;
}

geoLoc = new GeoLocation(lat, lon);
$node->setGeoLocation(geoLoc);

return 0;
</syntaxhighlight>

Script Example: Recursively Collect Values from Custom Attributes

2020-10-05T14:19:35Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/#_examples_2 NetXMS Script examples]''' for current version of the documentation.
|}

This script recursively collects values of custom attribute '''contacts''' from all node parents. Collected values concatenated into single string and separated by semicolons. Duplicate values added only once.

<syntaxhighlight lang="c">
global contacts = ""; // concatenated values will be stored here
global presence = %{ }; // value presence indicator (hash map)

// walk through each parent object for current node
foreach(o : GetObjectParents($node))
{
add_contacts(o);
}

// Concatenated result is in "contacts" global variable
println "Contacts: " . contacts;

/**
* Recursively add contacts from object and it's parents
*/
sub add_contacts(curr)
{
c = GetCustomAttribute(curr, "contacts");
if ((c != null) && (presence[c] == null))
{
if (length(contacts) > 0)
contacts = contacts . ";" . c;
else
contacts = c;
presence[c] = true;
}

foreach(o : GetObjectParents(curr))
{
add_contacts(o);
}
}
</syntaxhighlight>

Script Example: Read Table From Agent

2020-10-05T14:19:23Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/#_examples_2 NetXMS Script examples]''' for current version of the documentation.
|}

This script can be put into Script Library and run from server's debug console. It accepts node object name or ID as first parameter, table name as second parameter, and prints content of given table to console.

<syntaxhighlight lang="c">
// Find node object
node = FindObject($1);
if (node == null)
{
println "ERROR: Node not found";
return;
}

// REad table data from agent
table = AgentReadTable(node, $2);
if (table == null)
{
println "ERROR: Cannot read table from agent";
return;
}

// Print column names
for(i = 0; i < table->columnCount; i++)
print "| " . left(table->getColumnName(i), 20);
println "|";
for(i = 0; i < table->columnCount; i++)
print "+" . left("-", 21, "-");
println "+";

// Print data
for(i = 0; i < table->rowCount; i++)
{
for(j = 0; j < table->columnCount; j++)
{
print "| " . left(table->get(i, j), 20);
}
println "|";
}
</syntaxhighlight>

Script Example: Read SNMP Value From Node

2020-10-05T14:19:13Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/#_examples_2 NetXMS Script examples]''' for current version of the documentation.
|}

This script can be put into Script Library and run from server's debug console. It accepts node object name or ID as parameter and prints value of SNMP sysDescription to console.

<syntaxhighlight lang="c">
if ($1 == null)
{
println "Please specify node name as parameter";
return 3;
}

transport = CreateSNMPTransport(FindObject($1)); // Create SNMP transport for node
if (transport == null)
{
println "Failed to create SNMP transport, exit";
return 1;
}

value = SNMPGetValue(transport, ".1.3.6.1.2.1.1.1.0");
if (value == null)
{
println "Failed to issue SNMP GET request";
return 2;
}
else
{
println "System description: " . value;
return 0;
}
</syntaxhighlight>

Example of script output:

<pre>
C:\Source\NetXMS\x64\debug>nxadm -c "exec GetSysDescr cisco-2600-central"
System description: Cisco IOS Software, C2600 Software (C2600-ADVSECURITYK9-M), Version 12.4(1a), RELEASE SOFTWARE (fc2)
Technical Support: http://www.cisco.com/techsupport
Copyright (c) 1986-2005 by Cisco Systems, Inc.
Compiled Fri 27-May-05 15:09 by hqluong
INFO: Script finished with rc=0

C:\Source\NetXMS\x64\debug>
</pre>

Script Example: Aggregation of DCI values and applying the 95% percentile average

2020-10-05T14:19:05Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/#_examples_2 NetXMS Script examples]''' for current version of the documentation.
|}

The example is based around a template which configures ICMP Packet Loss probes. This script will loop around the nodes, collect the required DCI values. The values are then ordered and the top 5 percent discarded, the remaining entries are averaged to give the required value;

<syntaxhighlight lang="c">
sub main()
{

trace(1, "Global Ping Loss 95");
array pValue;
arrayI = 0;

foreach(parent : GetNodeParents($node))
{
trace(3, "Parent object: name='" . parent->name ."' id=" . parent->id);
if (parent->name == "all voice")
{
foreach(vNode : GetObjectChildren(parent))
{
dciName = "ICMP: Packet loss to ".vNode->name;
dciId = FindDCIByDescription(vNode, dciName);
if (dciId > 0)
{
tmpValue = GetDCIValue(vNode,dciId);
if (tmpValue != null)
{
pValue[arrayI++] = tmpValue;
}
}
}
}
}

// Sort the Array
bubbleSort(pValue);

// Apply the 95 percent rule
upTo = arrayI * 0.95;
pLoss = 0;
pCount = 0;
for(ia = 0; ia < upTo; ia++)
{
pLoss += pValue[ia];
pCount = ia;
}
p95AvgLoss = pLoss / pCount;

trace(1, "Global Ping Loss 95 Summary: arrayI=".arrayI." upTo=".upTo." p95AvgLoss=".p95AvgLoss );

return p95AvgLoss;
}

sub bubbleSort(arr)
{
swapped = true;
while (swapped == true){
swapped = false;
for(ia = 1; arr[ia] != null; ia++)
{
ib = ia - 1;

if (arr[ib] > arr[ia]){
trace(3,"swap: ".ib.":".arr[ib]." with ".ia.":".arr[ia]);
swapped=true;
t = arr[ib];
arr[ib] = arr[ia];
arr[ia] = t;
swapped = true;
}
}
}
}

sub printArray(arr)
{
for(ia = 0; arr[ia] != null; ia++)
{
trace(1,"printArray: ".ia.":".arr[ia]);
}
}
</syntaxhighlight>

Script Example: Enumerate All Custom Attributes for Node

2020-10-05T14:18:56Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/#_examples_2 NetXMS Script examples]''' for current version of the documentation.
|}

'''Requirements'''

Enumerate all custom attributes on a node.

'''Solution'''

Note: this script requires NetXMS version 2.0.2 or higher.

<syntaxhighlight lang="c">
attributes = $node->customAttributes;
foreach(a : attributes->keys)
{
println a . "=" . attributes[a];
}
</syntaxhighlight>

Script Example: Enumerate All Nodes

2020-10-05T14:18:45Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/#_examples_2 NetXMS Script examples]''' for current version of the documentation.
|}

'''Requirements'''

Enumerate all nodes in NetXMS database.

'''Solution'''

Create script in script library which will find "Entire Networks" object and walk down the tree. This script can be executes as an action from event processing policy, or directly from server debug console via '''exec''' command.

In order to be able to access info about all nodes, the '''CheckTrustedNodes''' server configuration variable needs to be set to 0.

<syntaxhighlight lang="c">
// Find "Entire Network" object and start enumeration from it
EnumerateNodes(FindObject(1));

// This function walks object tree recursively starting from given root
sub EnumerateNodes(rootObject)
{
// Walk all child objects
foreach(o : GetObjectChildren(rootObject))
{
if (classof(o) == "Node")
{
// Process node object
trace(1, " + " . o->name);
}
else if (classof(o) == "NetObj")
{
// For all other objects, go down the tree
// There can be additional checks for object class, like
// if (o->type == 5)
EnumerateNodes(o);
}
}
}
</syntaxhighlight>

Script Example: Additional Information About Connected Node

2020-10-05T14:18:36Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/#_examples_2 NetXMS Script examples]''' for current version of the documentation.
|}

'''Requirements'''

Add information about name, IP address, and MAC address about connected node to notification about switch port being down.

'''Solution'''

Use named event attribute ''additionalInfo'' to pass information into e-mail body (using %<additionalInfo> macro). To populate this attribute the following script can be used:
<syntaxhighlight lang="c">
// only for interface up and down events
if (($event->name != "SYS_IF_DOWN") && ($event->name != "SYS_IF_UP"))
return true;

// get interface object from interface index
iface = GetInterfaceObject($node, $5);
if (iface == null)
return true;

// get peer node (node connected to this interface) object
peer = iface->peerNode;
if (peer == null)
return true;

// get peer interface object (needed to obtain MAC address)
peerIface = iface->peerInterface;
if (peerIface != null)
{
macAddr = peerIface->macAddr;
}
else
{
macAddr = "<MAC unknown>";
}

// set event's named parameter
SetEventParameter($event, "additionalInfo",
"Peer: " . peer->name . " " . peer->ipAddr . " " . macAddr);

return true;
</syntaxhighlight>

SG:Script Examples

2020-10-05T14:18:23Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/#_examples_2 NetXMS Script examples]''' for current version of the documentation.
|}

[[Script Example: Additional Information About Connected Node|Additional Information About Connected Node]]

[[Script Example: Enumerate All Nodes|Enumerate All Nodes]]

[[Script Example: Enumerate All Custom Attributes for Node|Enumerate All Custom Attributes for Node]]

[[Script Example: Aggregation of DCI values and applying the 95% percentile average|Aggregation of DCI values and applying the 95% percentile average]]

[[Script Example: Read SNMP Value From Node|Read SNMP Value From Node]]

[[Script Example: Read Table From Agent|Read Table From Agent]]

[[Script Example: Recursively Collect Values from Custom Attributes|Recursively Collect Values from Custom Attributes]]

[[Script Example: Setting node geolocation from SNMP|Setting node geolocation from SNMP]]

[[Category:Scripting Guide]]

SG:Security Issues

2020-10-05T14:17:30Z

Phil:

{{DISPLAYTITLE:Security Issues}}

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/#security Script security]''' for current version of the documentation.
|}

Because NXSL provides functions for searching objects, and because all scripts are executed on management server, user with write access to only one node can potentially acquire information about nodes to which he normally does not have access. For example, without additional security checks user with write access to node A and no access to node B can create transformation script for DCI on node A and use [[NXSL:FindNodeObject|FindNodeObject]] function to access node B and get information about it, thus breaking security settings.

To prevent such scenario, all NXSL functions capable of accessing NetXMS objects requires "current node" object to be provided. Reference to object being searched will only be returned if node object supplied as "current node" is in trusted nodes list of target object. For example, if variable '''$node''' in script refers to NODE1, and [[NXSL:FindNodeObject|FindNodeObject]]($node, "NODE2") called, NODE1 must be added to list of trusted nodes for NODE2. In most places (transformation script, event processing policy, etc.) predefined variable '''$node''' exists, which refers to node object on behalf of which script is being executed. It will be event source for event processing policy script, DCI owner for transformation script, and so on.

For environments where such strict security checks are not required (for example, all users have read access to all nodes), they can be disabled to simplify configuration. Enforcement of trusted nodes checking controlled by server's configuration variable '''CheckTrustedNodes'''. By default it is set to '''0''' and check of trusted nodes is not enforced. To enable it, server's configuration variable '''CheckTrustedNodes''' must be set to '''1'''. The server restart is required to make this change effective.

[[Category:Scripting Guide]]

UM:NetXMS Scripting Language (NXSL)

2020-10-05T14:16:59Z

Phil:

{{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 =
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.

= "Hello, World!" Program =
Syntactically, NXSL looks similar to Perl or C. Here's simple NXSL program:

<syntaxhighlight lang="c">
/* sample program */
sub main()
{
println "Hello!";
return 0;
}
</syntaxhighlight>

This program will print word ''Hello'' on screen.

Also, keep in mind that you are free to choose your own formatting style. E.g. the above could have been written as:

<syntaxhighlight lang="c">
/* sample program */ sub main(){println "Hello!";return 0;}
</syntaxhighlight>

Now we'll analyze this program:

<syntaxhighlight lang="c">
/* sample program */
</syntaxhighlight>

Everything inside /* */ is considered a comment and will be ignored by interpreter. You can enclose comments, like below:

<syntaxhighlight lang="c">
/* comment /* another comment */ still comment */
</syntaxhighlight>

You can also use single line comments:

<syntaxhighlight lang="c">
x = 1; // everything between two slashes and end of line is a comment
</syntaxhighlight>

Now onto next line:

<syntaxhighlight lang="c">
sub main()
{
}
</syntaxhighlight>

This is a function definition. A function is a part of a program that can be called by other parts of the program. A function definition always has the following form:

'''sub''' ''name'''''('''''parameters''''')'''
{
/* the function code goes here */
}

The function can return a value to the caller and accept zero or more parameters.

The function name follows the rules for all names (formally: identifiers): it must consist entirely of letters (uppercase and lowercase are different!), digits, underscores (_) and dollar signs ($), but may not begin with a digit. Please note that most special identifiers starts with dollar sign ($), so it is recommended not to start your identifiers with it.

First line in function code looks like

<syntaxhighlight lang="c">
println "Hello!";
</syntaxhighlight>

In this line, println is an embedded operator which prints given string to standard output with carriage return, and "Hello!" is a string we want to print. Please note semicolon at the end of line – it's a separator between operators. Each operator should end with semicolon.

The next, and final, line of our small program is:

<syntaxhighlight lang="c">
return 0;
</syntaxhighlight>

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.

= Types =
NXSL is loose typed programming language. The system will automatically determine each variable type, assign a certain type to a variable and convert a variable type from one to another, if necessary. For example, a result for <tt>3 + "4"</tt> will be 7, because the system will automatically convert <tt>"4"</tt> string into an integer. In case if the system is not able to automatically convert a line into an appropriate integer, the operation will result in a runtime error.

NXSL supports the following variable types:

* integer (32 bit),
* unsigned integer (32 bit),
* integer (64 bit), unsigned integer (64 bit),
* floating-point number,
* string,
* array,
* object.

In addition to that, NXSL also supports a special variable type – NULL. This value represents a variable with no value. NULL is the only possible value of type NULL. An attempt to perform any type of arithmetical or string operations with NULL variable will result in system runtime error.

It is possible to manually convert variable to a certain type, using a special function, named depending on the variable type. For example, <tt>string(4)</tt>. That way it is also possible to convert NULL type variables. Therefore, to avoid runtime errors while processing NULL type variables, it is advised to use manual conversion.

NXSL does not require setting variable type beforehand. The only exception to this is arrays. In case if an array is required, operator <tt>array </tt>defines its subsequent variables as arrays. Accessing variable which was not previously assigned will return NULL value.

Although NXSL has object type variables, it is not an object-oriented language. It is not possible to define classes or create objects at script level – only in extensions written in C++. Object type variables are used to return information about complex NetXMS objects, like nodes or events, in a convenient way. Please note that assigning object type variables actually holds reference to an object, so assigning object value to another variable does not duplicate actual object, but just copy reference to it.

To get a human-readable representation of a variable or expression type for debugging, use the <tt>typeof()</tt> function, and to get a class name for object type variables, use <tt>classof()</tt> function.

= Variables =
Variables in NXSL behave the same way as variables in most popular programming languages (C, C++, etc.) do, but in NXSL you don't have to declare variables before you use them.

Scope of a variable can be either global (visible in any function in the script) or local (visible only in the function within which it was defined). Any variable is by default limited to the local function scope. Variable can be declared global using '''global''' operator.

For example:

<syntaxhighlight lang="c">
x = 1;
myFunction();

sub myFunction()
{
println "x=" . x;
}
</syntaxhighlight>

This script will cause run time error "Error 5 in line 6: Invalid operation with NULL value", because variable '''x''' is local (in implicit main function) and is not visible in function '''myFunction'''. The following script will produce expected result (prints x=1):

<syntaxhighlight lang="c">
global x = 1;
myFunction();

sub myFunction()
{
println "x=" . x;
}
</syntaxhighlight>

= Functions =
A function is a named code block that is generally intended to process specified input values into an output value, although this is not always the case. For example, the [[NXSL:trace|trace]] function takes variables and static text and prints the values into server log. Like many languages, NXSL provides for user-defined functions. These may be located anywhere in the main program or loaded in from other scripts via the use keywords.
To define a function, you can use the following form:

'''sub''' ''NAME'' '''(''' ''ARGUMENTS'' ''')''' '''BLOCK'''

where ''NAME'' is any valid identifier, ''ARGUMENTS'' is optional list of argument names, and ''BLOCK'' is code block.

To call a function you would use the following form:

''NAME'' '''(''' ''LIST'' ''')'''

where ''NAME'' is identifier used in function definition, and ''LIST'' is an optional list of expressions passed as function arguments.

To give a quick example of a simple subroutine:

<syntaxhighlight lang="c">
sub message()
{
println "Hello!";
}
</syntaxhighlight>

== Function Arguments ==

The first argument you pass to the function is available within the function as $1, the second argument is $2, and so on. For example, this simple function adds two numbers and prints the result:

<syntaxhighlight lang="c">
sub add()
{
result = $1 + $2;
println "The result was: " . result;
}
</syntaxhighlight>

To call the subroutine and get a result:

<syntaxhighlight lang="c">
add(1, 2);
</syntaxhighlight>

If you want named arguments, list of aliases for $1, $2, etc. can be provided in function declaration inside the brackets:

<syntaxhighlight lang="c">
sub add(numberA, numberB)
{
result = numberA + numberB;
println "The result was: " . result;
}
</syntaxhighlight>

If parameter was not provided at function call, value of appropriate variable will be '''null'''.

== Return Values from a Function ==

You can return a value from a function using the '''return''' keyword:

<syntaxhighlight lang="c">
sub pct(value, total)
{
return value / total * 100.0;
}
</syntaxhighlight>

When called, return immediately terminates the current function and returns the value to the caller. If you don't specify a value in '''return''' statement or function ends implicitly by reaching end of function's block, then the return value is '''null'''.

= Arrays =
An array in NXSL is actually an ordered map. A map is a type that associates ''values'' to ''keys''. This type is optimized for several different uses; it can be treated as an array, list (vector), hash table (an implementation of a map), dictionary, collection, stack, queue, and probably more. As array values can be other arrays.

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 =
An operator is something that you feed with one or more values, which yields another value.

== Arithmetic Operators ==

{| class="wikitable"
|-
! Example !! Name !! Result
|-
| -a || Negation || Opposite of ''a''.
|-
| a + b || Addition || Sum of ''a'' and ''b''.
|-
| a - b || Subtraction || Difference of ''a'' and ''b''.
|-
| a * b || Multiplication || Product of ''a'' and ''b''.
|-
| a / b || Division || Quotient of ''a'' and ''b''.
|-
| a % b || Modulus || Remainder of ''a'' divided by ''b''.
|}
The division operator ("/") returns a float value unless the two operands are integers (or strings that get converted to integers) and the numbers are evenly divisible, in which case an integer value will be returned.

Calling modulus on float operands will yield runtime error.

== Assignment Operator ==
The assignment operator is "=", which means that the left operand gets set to the value of the expression on the rights (that is, "gets set to").

== Bitwise Operators ==

{| style="border-spacing:0;"
! <center>Example</center>
! <center>Name</center>
! <center>Result</center>

|-
| 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
| 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;"| Not
| 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;"| Bits that are set in ''a'' are not set, and vice versa.

|-
| 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 & 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;"| And
| 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;"| Bits that are set in both operand are set.

|-
| 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 | 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;"| Or
| 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;"| Bits that are set in either operand are set.

|-
| 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 ^ 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;"| Xor
| 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;"| Bits that are set in only one operand are set.

|-
| 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;"| <nowiki>a << b</nowiki>
| 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;"| Shift left
| 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;"| Shift the bits of ''a'' ''b'' steps to the left (each step means "multiply by two").

|-
| 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 >> 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;"| Shift right
| 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;"| Shift the bits of ''a'' ''b'' steps to the right (each step means "divide by two").

|}
== Comparison Operators ==
Comparison operators allow you to compare two values.

''Table 3: Comparison Operators''

{| style="border-spacing:0;"
! <center>Example</center>
! <center>Name</center>
! <center>Result</center>

|-
| 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 == 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;"| Equal
| 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 equal to ''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;"| a != 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;"| Not equal
| 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 not equal to ''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;"| <nowiki>a < b</nowiki>
| 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;"| Less than
| 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 strictly less than ''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;"| a > 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;"| Greater than
| 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 strictly greater than ''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;"| <nowiki>a <= b</nowiki>
| 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;"| Less than or equal to
| 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 less than or equal to ''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;"| a >= 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;"| Greater than or equal to
| 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 greater than or equal to ''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;"| a ~= 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 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.

|}
== Incrementing/Decrementing Operators ==
NXSL supports C-style pre- and post-increment and decrement operators.

''Table 4: Incrementing/Decrementing Operators''

{| style="border-spacing:0;"
! <center>Example</center>
! <center>Name</center>
! <center>Effect</center>

|-
| 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
| 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;"| Pre-increment
| 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;"| Increments ''a'' by one, then returns ''a''.

|-
| 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++
| 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;"| Post-increment
| 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;"| Returns ''a'', then increments ''a'' by one.

|-
| 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
| 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;"| Pre-decrement
| 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;"| Decrements ''a'' by one, then returns ''a''.

|-
| 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--
| 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;"| Post-decrement
| 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;"| Returns ''a'', then decrements ''a'' by one.

|}
== Logical Operators ==
''Table 5: Logical Operators''

{| style="border-spacing:0;"
! <center>Example</center>
! <center>Name</center>
! <center>Result</center>

|-
| 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
| 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;"| Not
| 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 not <tt>TRUE</tt>.

|-
| 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 && 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;"| And
| 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 both ''a'' and ''b'' is <tt>TRUE</tt>.

|-
| 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 <nowiki>||</nowiki> 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;"| Or
| 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 either ''a'' or ''b'' is <tt>TRUE</tt>.

|}

== String Operators ==
There are two string operators. The first is the concatenation operator ('.'), which returns the concatenation of its right and left arguments. The second is the concatenating assignment operator ('''.='''), which appends the argument on the right side to the argument on the left side.

= Control structures =
Any NXSL script is built out of a series of statements. A statement can be an assignment, a function call, a loop, a conditional statement or even a statement that does nothing (an empty statement). Statements usually end with a semicolon. In addition, statements can be grouped into a statement-group by encapsulating a group of statements with curly braces. A statement-group is a statement by itself as well. The various statement types are supported:

* if

* else
* while
* do-while
* for
* break
* continue
* switch
* return
* exit

== if ==
The ''if'' construct is one of the most important features of many languages. It allows for conditional execution of code fragments. NXSL features an ''if'' structure that is similar to that of C:

if (expr)
statement

== else ==
Often you'd want to execute a statement if a certain condition is met, and a different statement if the condition is not met. This is what ''else'' is for. ''else'' extends an ''if'' statement to execute a statement in case the expression in the ''if'' statement evaluates to <tt>FALSE</tt>. The ''else'' statement is only executed if the ''if'' expression evaluated to <tt>FALSE</tt>.

== while ==
''while'' loops are the simplest type of loop in NXSL. They behave just like their C counterparts. The basic form of a ''while'' statement is:

while (expr)
statement

The meaning of a ''while'' statement is simple. It tells NXSL to execute the nested statement(s) repeatedly, as long as the ''while'' expression evaluates to <tt>TRUE</tt>. The value of the expression is checked each time at the beginning of the loop, so even if this value changes during the execution of the nested statement(s), execution will not stop until the end of the iteration.

== do-while ==
''do-while'' loops are very similar to ''while'' loops, except the truth expression is checked at the end of each iteration instead of in the beginning. The main difference from regular ''while'' loops is that the first iteration of a ''do-while'' loop is guaranteed to run (the truth expression is only checked at the end of the iteration), whereas it may not necessarily run with a regular ''while'' loop (the truth expression is checked at the beginning of each iteration, if it evaluates to FALSE right from the beginning, the loop execution would end immediately).

== for ==
''for'' loops are the most complex loops in NXSL. They behave like their C counterparts. The syntax of a ''for'' loop is:

for (expr1; expr2; expr3)
statement

The first expression (''expr1'') is evaluated (executed) once unconditionally at the beginning of the loop.

In the beginning of each iteration, ''expr2'' is evaluated. If it evaluates to <tt>TRUE</tt>, the loop continues and the nested statement(s) are executed. If it evaluates to <tt>FALSE</tt>, the execution of the loop ends.

At the end of each iteration, ''expr3'' is evaluated (executed).

== break ==
''break'' ends execution of the current ''for'', ''while'', ''do-while'' or ''switch'' structure.

== continue ==
''continue'' is used within looping structures to skip the rest of the current loop iteration and continue execution at the condition evaluation and then the beginning of the next iteration.

== switch ==
The ''switch'' statement is similar to a series of ''if'' statements on the same expression. In many occasions, you may want to compare the same variable (or expression) with many different values, and execute a different piece of code depending on which value it equals to. This is exactly what the ''switch'' statement is for.

Example:
<syntaxhighlight lang="c">
switch (input)
{
case "1":
trace(0,"Input is 1");
break;
case "2":
trace(0,"Input is 2");
break;
default:
trace(0, "Input is unknown");
}
</syntaxhighlight>

== return ==
If called from within a function, the <tt>return</tt> statement immediately ends execution of the current function, and returns its argument as the value of the function call. Calling <tt>return</tt> from main() function (either explicitly or implicitly defined) is equivalent of calling <tt>exit</tt>.

== exit ==
The <tt>exit</tt> statement immediately ends execution of the entire script, and returns its argument as script execution result.

= Expressions =
The simplest yet most accurate way to define an expression is "anything that has a value".

The most basic forms of expressions are constants and variables. When you type "''a'' = 5", you're assigning '5' into ''a''. '5', obviously, has the value 5, or in other words '5' is an expression with the value of 5 (in this case, '5' is an integer constant).

Slightly more complex examples for expressions are functions. Functions are expressions with the value of their return value.

NXSL supports the following value types: integer values, floating point values (float), string values and arrays. Each of these value types can be assigned into variables or returned from functions.

Another good example of expression orientation is pre- and post-increment and decrement. You be familiar with the notation of ''variable++'' and ''variable--''. These are increment and decrement operators. In NXSL, like in C, there are two types of increment - pre-increment and post-increment. Both pre-increment and post-increment essentially increment the variable, and the effect on the variable is identical. The difference is with the value of the increment expression. Pre-increment, which is written '++''variable''', evaluates to the incremented value. Post-increment, which is written '''variable''++' evaluates to the original value of variable, before it was incremented.

A very common type of expressions are comparison expressions. These expressions evaluate to either <tt>FALSE</tt> or <tt>TRUE</tt>.<nowiki> NXSL supports > (bigger than), >= (bigger than or equal to), = (equal), != (not equal), < (smaller than) and <= (smaller than or equal to). These expressions are most commonly used inside conditional execution, such as </nowiki>''if'' statements.

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]]

NXSL Syntax highlight and calltips

2020-10-05T13:55:31Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/ NetXMS Scripting Language]''' for current version of the documentation.
|}

= Overview =
If you want to edit your NXSL scripts in an external editor to make use of syntax highlighing and calltips, you can use Notepad++.

Notepad++ is a free source code editor, governed by the GPL License.

You can get Notepad++ here:<br>
http://notepad-plus-plus.org/download/

= Calltips =
[[File:NSXL - calltips.png]]

= Syntax highlight =
[[File:NXSL - syntax highlighting.png]]

= How to import into Notepad++ =
For syntax highlight, import the syntax file using:<br>
Language > Define your language... > Import

For calltips, copy and rename the calltips file into:<br>
C:\Program Files (x86)\Notepad++\plugins\APIs\NetXMS.xml

= Getting the files =

You can get more information and download the newest versions at:<br>
http://www.netxms.org/forum/general-support/netxms-notepad-syntax-highlight/

NXSL Class Reference

2020-10-05T13:55:05Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/ NetXMS Scripting Language]''' for current version of the documentation.
|}

===NetObj and its sub-classes===
[[NXSL:NetObj|NetObj]]

- [[NXSL:Cluster|Cluster]]

- [[NXSL:Interface|Interface]]

- [[NXSL:Node|Node]]

- [[NXSL:Zone|Zone]]

===SNMP related classes===
[[NXSL:SNMP_Transport|SNMP_Transport]]

[[NXSL:SNMP_VarBind|SNMP_VarBind]]

===Other classes===
[[NXSL:Alarm|Alarm]]

[[NXSL:Component|Component]]

[[NXSL:DCI|DCI]]

[[NXSL:Event|Event]]

[[NXSL:FILE|FILE]]

[[NXSL:GeoLocation|GeoLocation]]

[[NXSL:InetAddress|InetAddress]]

[[NXSL:NewNode|NewNode]]

[[NXSL:Situation|Situation]]

[[NXSL:Table|Table]]

[[NXSL:TableColumn|TableColumn]]

[[NXSL:TIME|TIME]]

[[NXSL:UserDBObject|UserDBObject]]

-[[NXSL:User|User]]

-[[NXSL:UserGroup|UserGroup]]

[[Category:Scripting Guide]]

NXSL Function Reference

2020-10-05T13:54:17Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/ NetXMS Scripting Language]''' for current version of the documentation.
|}

= Function tables =
{| {border="1" cellpadding="4" cellspacing="2" style="border:\#c9c9c9 1px solid; margin: 1em 1em 1em 0; border-collapse: collapse;"}
| align="center" style="background:#f0f0f0;"|'''Generic'''
| align="center" style="background:#f0f0f0;"|'''Math'''
| align="center" style="background:#f0f0f0;"|'''String-related'''
| align="center" style="background:#f0f0f0;"|'''Data Collection'''
| align="center" style="background:#f0f0f0;"|'''Object search'''
| align="center" style="background:#f0f0f0;"|'''Object management'''
| align="center" style="background:#f0f0f0;"|'''Network'''
|-
| [[NXSL:CountScheduledTasksByKey|CountScheduledTasksByKey]]||[[NXSL:abs|abs]]||[[NXSL:ArrayToString|ArrayToString]]||[[NXSL:CreateDCI|CreateDCI]]||[[NXSL:FindNodeObject|FindNodeObject]]||[[NXSL:BindObject|BindObject]]||[[NXSL:AddrInRange|AddrInRange]]
|-
| [[NXSL:classof|classof]]||[[NXSL:ceil|ceil]]||[[NXSL:chr|chr]]||[[NXSL:FindAllDCIs|FindAllDCIs]]||[[NXSL:FindObject|FindObject]]||[[NXSL:CreateContainer|CreateContainer]]||[[NXSL:AddrInSubnet|AddrInSubnet]]
|-
| [[NXSL:d2x|d2x]]||[[NXSL:exp|exp]]||[[NXSL:format|format]]||[[NXSL:FindDCIByDescription|FindDCIByDescription]]||[[NXSL:GetInterfaceName|GetInterfaceName]]||[[NXSL:CreateNode|CreateNode]]||[[NXSL:gethostbyaddr|gethostbyaddr]]
|-
| [[NXSL:exit|exit]]||[[NXSL:floor|floor]]||[[NXSL:index|index]]||[[NXSL:FindDCIByName|FindDCIByName]]||[[NXSL:GetInterfaceObject|GetInterfaceObject]]||[[NXSL:DeleteCustomAttribute|DeleteCustomAttribute]]||[[NXSL:gethostbyname|gethostbyname]]
|-
| [[NXSL:GetConfigurationVariable|GetConfigurationVariable]]||[[NXSL:log|log]]||[[NXSL:left|left]]||[[NXSL:GetAvgDCIValue|GetAvgDCIValue]]||[[NXSL:GetNodeInterfaces|GetNodeInterfaces]]||[[NXSL:DeleteObject|DeleteObject]]||
|-
| [[NXSL:inList|inList]]||[[NXSL:log10|log10]]||[[NXSL:length|length]]||[[NXSL:GetDCIObject|GetDCIObject]]||[[NXSL:GetNodeParents|GetNodeParents]]||[[NXSL:EnterMaintenance|EnterMaintenance]]||
|-
| [[NXSL:map|map]]||[[NXSL:pow|pow]]||[[NXSL:lower|lower]]||[[NXSL:GetDCIRawValue|GetDCIRawValue]]||[[NXSL:GetNodeTemplates|GetNodeTemplates]]||[[NXSL:GetCustomAttribute|GetCustomAttribute]]||
|-
| [[NXSL:mapList|mapList]]||[[NXSL:round|round]]||[[NXSL:ltrim|ltrim]]||[[NXSL:GetDCIValue|GetDCIValue]]||[[NXSL:GetObjectChildren|GetObjectChildren]]||[[NXSL:LeaveMaintenance|LeaveMaintenance]]||
|-
| [[NXSL:max|max]]||||[[NXSL:ord|ord]]||[[NXSL:GetDCIValues|GetDCIValues]]||[[NXSL:GetObjectParents|GetObjectParents]]||[[NXSL:ManageObject|ManageObject]]||
|-
| [[NXSL:min|min]]||||[[NXSL:right|right]]||[[NXSL:GetDCIValueByDescription|GetDCIValueByDescription]]||[[NXSL:GetAllNodes|GetAllNodes]]||[[NXSL:RenameObject|RenameObject]]||
|-
| [[NXSL:random|random]]||||[[NXSL:rindex|rindex]]||[[NXSL:GetDCIValueByName|GetDCIValueByName]]||||[[NXSL:SetCustomAttribute|SetCustomAttribute]]||
|-
| [[NXSL:sleep|sleep]]||||[[NXSL:rtrim|rtrim]]||[[NXSL:GetMaxDCIValue|GetMaxDCIValue]]||||[[NXSL:SetInterfaceExpectedState|SetInterfaceExpectedState]]||
|-
| [[NXSL:trace|trace]]||||[[NXSL:SplitString|SplitString]]||[[NXSL:GetMinDCIValue|GetMinDCIValue]]||||[[NXSL:UnbindObject|UnbindObject]]||
|-
| [[NXSL:typeof|typeof]]||||[[NXSL:substr|substr]]||[[NXSL:GetSumDCIValue|GetSumDCIValue]]||||[[NXSL:UnmanageObject|UnmanageObject]]||
|-
| [[NXSL:x2d|x2d]]||||[[NXSL:trim|trim]]||[[NXSL:PushDCIData|PushDCIData]]||||||
|-
| ||||[[NXSL:upper|upper]]||||||||
|}
<hr>

{| {border="1" cellpadding="4" cellspacing="2" style="border:\#c9c9c9 1px solid; margin: 1em 1em 1em 0; border-collapse: collapse;"}
| align="center" style="background:#f0f0f0;"|'''Time-related'''
| align="center" style="background:#f0f0f0;"|'''Cryptography'''
| align="center" style="background:#f0f0f0;"|'''SNMP'''
| align="center" style="background:#f0f0f0;"|'''Agent'''
| align="center" style="background:#f0f0f0;"|'''Event Processing'''
| align="center" style="background:#f0f0f0;"|'''Persistent Storage'''
| align="center" style="background:#f0f0f0;"|'''File I/O'''
|-
| [[NXSL:gmtime|gmtime]]||[[NXSL:md5|md5]]||[[NXSL:CreateSNMPTransport|CreateSNMPTransport]]||[[NXSL:AgentReadList|AgentReadList]]||[[NXSL:FindAlarmById|FindAlarmById]]||[[NXSL:ReadPersistentStorage|ReadPersistentStorage]]||[[NXSL:CopyFile|CopyFile]]||
|-
| [[NXSL:localtime|localtime]]||[[NXSL:sha1|sha1]]||[[NXSL:SNMPGet|SNMPGet]]||[[NXSL:AgentReadParameter|AgentReadParameter]]||[[NXSL:FindAlarmByKey|FindAlarmByKey]]||[[NXSL:WritePersistentStorage|WritePersistentStorage]]||[[NXSL:CreateDirectory|CreateDirectory]]||
|-
| [[NXSL:SecondsToUptime|SecondsToUptime]]||[[NXSL:sha256|sha256]]||[[NXSL:SNMPGetValue|SNMPGetValue]]||[[NXSL:AgentReadTable|AgentReadTable]]||[[NXSL:FindAlarmByKeyRegex|FindAlarmByKeyRegex]]||||[[NXSL:DeleteFile|DeleteFile]]||
|-
| [[NXSL:strftime|strftime]]||||[[NXSL:SNMPSet|SNMPSet]]||||[[NXSL:GetEventParameter|GetEventParameter]]||||[[NXSL:FileAccess|FileAccess]]
|-
| [[NXSL:time|time]]||||[[NXSL:SNMPWalk|SNMPWalk]]||||[[NXSL:PostEvent|PostEvent]]||||[[NXSL:OpenFile|OpenFile]]
|-
| [[NXSL:mktime|mktime]]||||||||[[NXSL:SetEventParameter|SetEventParameter]]||||[[NXSL:RemoveDirectory|RemoveDirectory]]||
|-
| ||||||||||||[[NXSL:RenameFile|RenameFile]]||
|}

NXSL Formal Grammar

2020-10-05T13:54:01Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/ NetXMS Scripting Language]''' for current version of the documentation.
|}

<pre>
script ::=
module |
expression

module ::=
module_component { module_component }

module_component ::=
function |
statement_or_block |
use_statement

use_statement ::=
use any_identifier ";"

any_identifier ::=
IDENTIFIER |
COMPOUND_IDENTFIER

function ::=
sub IDENTIFIER "(" [ identifier_list ] ")" block

identifier_list ::=
IDENTIFIER { "," IDENTIFIER }

block ::=
"{" { statement_or_block } "}"

statement_or_block ::=
statement |
block

statement ::=
expression ";" |
builtin_statement |
";"

builtin_statement ::=
simple_statement ";" |
if_statement |
do_statement |
while_statement |
for_statement |
foreach_statement |
switch_statement |
array_statement |
global_statement |
break ";"
continue ";"

simple_statement ::=
keyword [ expression ]

keyword ::=
exit |
print |
println |
return

if_statement ::=
if "(" expression ")" statement_or_block [ else statement_or_block ]

for_statement ::=
for "(" expression ";" expression ";" expression ")" statement_or_block

foreach_statement ::=
foreach "(" IDENTIFIER ":" expression ")" statement_or_block

while_statement ::=
while "(" expression ")" statement_or_block

do_statement ::=
do statement_or_block while "(" expression ")" ";"

switch_statement ::=
switch "(" expression ")" "{" case { case } [ default ] "}"

case ::=
case constant ":" { statement_or_block }

default ::=
default ":" { statement_or_block }

array_statement ::=
[ global ] array identifier_list ";"

global_statement ::=
global global_variable_declaration { "," global_variable_declaration } ";"

global_variable_declaration ::=
IDENTIFIER [ "=" expression ]

expression ::=
"(" expression ")" |
IDENTIFIER "=" expression |
expression "->" IDENTIFIER |
"-" expression |
"!" expression |
"~" expression |
inc IDENTIFIER |
dec IDENTIFIER |
IDENTIFIER inc |
IDENTIFIER dec |
expression "+" expression |
expression "-" expression |
expression "*" expression |
expression "/" expression |
expression "%" expression |
expression like expression |
expression ilike expression |
expression "~=" expression |
expression match expression |
expression imatch expression |
expression "==" expression |
expression "!=" expression |
expression "<" expression |
expression "<=" expression |
expression ">" expression |
expression ">=" expression |
expression "&" expression |
expression "|" expression |
expression "^" expression |
expression "&&" expression |
expression "||" expression |
expression "<<" expression |
expression ">>" expression |
expression "." expression |
expression "?" expression ":" expression |
operand

operand ::=
function_call |
type_cast |
constant |
IDENTIFIER

type_cast ::=
builtin_type "(" expression ")"

builtin_type ::=
int32 |
int64 |
uint32 |
uint64 |
real |
string

function_call ::=
IDENTIFIER "(" [ expression { "," expression } ] ")"

constant ::=
STRING |
INT32 |
INT64 |
UINT32 |
UINT64 |
REAL |
NULL
</pre>

'''Terminal symbols'''

<pre>
IDENTIFIER ::= [A-Za-z_\$][A-Za-z_\$0-9]*
COMPOUND_IDENTIFIER ::= { IDENTIFIER}(::{ IDENTIFIER})+
INTEGER ::= \-?(0x)?[0-9]+
INT32 ::= INTEGER
INT64 ::= {INTEGER}L
UINT32 ::= {INTEGER}U
UINT64 ::= {INTEGER}(UL|LU)
REAL ::= \-?[0-9]+\.[0-9]+
</pre>

[[Category:Scripting Guide]]

Script Example: Setting node geolocation from SNMP

2020-10-05T13:53:42Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/ NetXMS Scripting Language]''' for current version of the documentation.
|}

Adjust the OIDs in ''SNMPGetValue'' as required.

<syntaxhighlight lang="c">
transport = CreateSNMPTransport($node);
if (transport == null) {
return null;
}

lat = SNMPGetValue(transport, ".1.2.3.4.1");
lon = SNMPGetValue(transport, ".1.2.3.4.2");

if (lat == null || lon == null) {
return null;
}

geoLoc = new GeoLocation(lat, lon);
$node->setGeoLocation(geoLoc);

return 0;
</syntaxhighlight>

Script Example: Recursively Collect Values from Custom Attributes

2020-10-05T13:53:29Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/ NetXMS Scripting Language]''' for current version of the documentation.
|}

This script recursively collects values of custom attribute '''contacts''' from all node parents. Collected values concatenated into single string and separated by semicolons. Duplicate values added only once.

<syntaxhighlight lang="c">
global contacts = ""; // concatenated values will be stored here
global presence = %{ }; // value presence indicator (hash map)

// walk through each parent object for current node
foreach(o : GetObjectParents($node))
{
add_contacts(o);
}

// Concatenated result is in "contacts" global variable
println "Contacts: " . contacts;

/**
* Recursively add contacts from object and it's parents
*/
sub add_contacts(curr)
{
c = GetCustomAttribute(curr, "contacts");
if ((c != null) && (presence[c] == null))
{
if (length(contacts) > 0)
contacts = contacts . ";" . c;
else
contacts = c;
presence[c] = true;
}

foreach(o : GetObjectParents(curr))
{
add_contacts(o);
}
}
</syntaxhighlight>

Script Example: Read Table From Agent

2020-10-05T13:53:05Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/ NetXMS Scripting Language]''' for current version of the documentation.
|}

This script can be put into Script Library and run from server's debug console. It accepts node object name or ID as first parameter, table name as second parameter, and prints content of given table to console.

<syntaxhighlight lang="c">
// Find node object
node = FindObject($1);
if (node == null)
{
println "ERROR: Node not found";
return;
}

// REad table data from agent
table = AgentReadTable(node, $2);
if (table == null)
{
println "ERROR: Cannot read table from agent";
return;
}

// Print column names
for(i = 0; i < table->columnCount; i++)
print "| " . left(table->getColumnName(i), 20);
println "|";
for(i = 0; i < table->columnCount; i++)
print "+" . left("-", 21, "-");
println "+";

// Print data
for(i = 0; i < table->rowCount; i++)
{
for(j = 0; j < table->columnCount; j++)
{
print "| " . left(table->get(i, j), 20);
}
println "|";
}
</syntaxhighlight>

Script Example: Read SNMP Value From Node

2020-10-05T13:52:51Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/ NetXMS Scripting Language]''' for current version of the documentation.
|}

This script can be put into Script Library and run from server's debug console. It accepts node object name or ID as parameter and prints value of SNMP sysDescription to console.

<syntaxhighlight lang="c">
if ($1 == null)
{
println "Please specify node name as parameter";
return 3;
}

transport = CreateSNMPTransport(FindObject($1)); // Create SNMP transport for node
if (transport == null)
{
println "Failed to create SNMP transport, exit";
return 1;
}

value = SNMPGetValue(transport, ".1.3.6.1.2.1.1.1.0");
if (value == null)
{
println "Failed to issue SNMP GET request";
return 2;
}
else
{
println "System description: " . value;
return 0;
}
</syntaxhighlight>

Example of script output:

<pre>
C:\Source\NetXMS\x64\debug>nxadm -c "exec GetSysDescr cisco-2600-central"
System description: Cisco IOS Software, C2600 Software (C2600-ADVSECURITYK9-M), Version 12.4(1a), RELEASE SOFTWARE (fc2)
Technical Support: http://www.cisco.com/techsupport
Copyright (c) 1986-2005 by Cisco Systems, Inc.
Compiled Fri 27-May-05 15:09 by hqluong
INFO: Script finished with rc=0

C:\Source\NetXMS\x64\debug>
</pre>

Script Example: Aggregation of DCI values and applying the 95% percentile average

2020-10-05T13:52:34Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/ NetXMS Scripting Language]''' for current version of the documentation.
|}

The example is based around a template which configures ICMP Packet Loss probes. This script will loop around the nodes, collect the required DCI values. The values are then ordered and the top 5 percent discarded, the remaining entries are averaged to give the required value;

<syntaxhighlight lang="c">
sub main()
{

trace(1, "Global Ping Loss 95");
array pValue;
arrayI = 0;

foreach(parent : GetNodeParents($node))
{
trace(3, "Parent object: name='" . parent->name ."' id=" . parent->id);
if (parent->name == "all voice")
{
foreach(vNode : GetObjectChildren(parent))
{
dciName = "ICMP: Packet loss to ".vNode->name;
dciId = FindDCIByDescription(vNode, dciName);
if (dciId > 0)
{
tmpValue = GetDCIValue(vNode,dciId);
if (tmpValue != null)
{
pValue[arrayI++] = tmpValue;
}
}
}
}
}

// Sort the Array
bubbleSort(pValue);

// Apply the 95 percent rule
upTo = arrayI * 0.95;
pLoss = 0;
pCount = 0;
for(ia = 0; ia < upTo; ia++)
{
pLoss += pValue[ia];
pCount = ia;
}
p95AvgLoss = pLoss / pCount;

trace(1, "Global Ping Loss 95 Summary: arrayI=".arrayI." upTo=".upTo." p95AvgLoss=".p95AvgLoss );

return p95AvgLoss;
}

sub bubbleSort(arr)
{
swapped = true;
while (swapped == true){
swapped = false;
for(ia = 1; arr[ia] != null; ia++)
{
ib = ia - 1;

if (arr[ib] > arr[ia]){
trace(3,"swap: ".ib.":".arr[ib]." with ".ia.":".arr[ia]);
swapped=true;
t = arr[ib];
arr[ib] = arr[ia];
arr[ia] = t;
swapped = true;
}
}
}
}

sub printArray(arr)
{
for(ia = 0; arr[ia] != null; ia++)
{
trace(1,"printArray: ".ia.":".arr[ia]);
}
}
</syntaxhighlight>

Script Example: Enumerate All Custom Attributes for Node

2020-10-05T13:52:13Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/ NetXMS Scripting Language]''' for current version of the documentation.
|}

'''Requirements'''

Enumerate all custom attributes on a node.

'''Solution'''

Note: this script requires NetXMS version 2.0.2 or higher.

<syntaxhighlight lang="c">
attributes = $node->customAttributes;
foreach(a : attributes->keys)
{
println a . "=" . attributes[a];
}
</syntaxhighlight>

Script Example: Enumerate All Nodes

2020-10-05T13:51:58Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/ NetXMS Scripting Language]''' for current version of the documentation.
|}

'''Requirements'''

Enumerate all nodes in NetXMS database.

'''Solution'''

Create script in script library which will find "Entire Networks" object and walk down the tree. This script can be executes as an action from event processing policy, or directly from server debug console via '''exec''' command.

In order to be able to access info about all nodes, the '''CheckTrustedNodes''' server configuration variable needs to be set to 0.

<syntaxhighlight lang="c">
// Find "Entire Network" object and start enumeration from it
EnumerateNodes(FindObject(1));

// This function walks object tree recursively starting from given root
sub EnumerateNodes(rootObject)
{
// Walk all child objects
foreach(o : GetObjectChildren(rootObject))
{
if (classof(o) == "Node")
{
// Process node object
trace(1, " + " . o->name);
}
else if (classof(o) == "NetObj")
{
// For all other objects, go down the tree
// There can be additional checks for object class, like
// if (o->type == 5)
EnumerateNodes(o);
}
}
}
</syntaxhighlight>

Script Example: Additional Information About Connected Node

2020-10-05T13:51:48Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/ NetXMS Scripting Language]''' for current version of the documentation.
|}

'''Requirements'''

Add information about name, IP address, and MAC address about connected node to notification about switch port being down.

'''Solution'''

Use named event attribute ''additionalInfo'' to pass information into e-mail body (using %<additionalInfo> macro). To populate this attribute the following script can be used:
<syntaxhighlight lang="c">
// only for interface up and down events
if (($event->name != "SYS_IF_DOWN") && ($event->name != "SYS_IF_UP"))
return true;

// get interface object from interface index
iface = GetInterfaceObject($node, $5);
if (iface == null)
return true;

// get peer node (node connected to this interface) object
peer = iface->peerNode;
if (peer == null)
return true;

// get peer interface object (needed to obtain MAC address)
peerIface = iface->peerInterface;
if (peerIface != null)
{
macAddr = peerIface->macAddr;
}
else
{
macAddr = "<MAC unknown>";
}

// set event's named parameter
SetEventParameter($event, "additionalInfo",
"Peer: " . peer->name . " " . peer->ipAddr . " " . macAddr);

return true;
</syntaxhighlight>

SG:Script Examples

2020-10-05T13:51:34Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/ NetXMS Scripting Language]''' for current version of the documentation.
|}

[[Script Example: Additional Information About Connected Node|Additional Information About Connected Node]]

[[Script Example: Enumerate All Nodes|Enumerate All Nodes]]

[[Script Example: Enumerate All Custom Attributes for Node|Enumerate All Custom Attributes for Node]]

[[Script Example: Aggregation of DCI values and applying the 95% percentile average|Aggregation of DCI values and applying the 95% percentile average]]

[[Script Example: Read SNMP Value From Node|Read SNMP Value From Node]]

[[Script Example: Read Table From Agent|Read Table From Agent]]

[[Script Example: Recursively Collect Values from Custom Attributes|Recursively Collect Values from Custom Attributes]]

[[Script Example: Setting node geolocation from SNMP|Setting node geolocation from SNMP]]

[[Category:Scripting Guide]]

SG:Security Issues

2020-10-05T13:51:20Z

Phil:

{{DISPLAYTITLE:Security Issues}}

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/ NetXMS Scripting Language]''' for current version of the documentation.
|}

Because NXSL provides functions for searching objects, and because all scripts are executed on management server, user with write access to only one node can potentially acquire information about nodes to which he normally does not have access. For example, without additional security checks user with write access to node A and no access to node B can create transformation script for DCI on node A and use [[NXSL:FindNodeObject|FindNodeObject]] function to access node B and get information about it, thus breaking security settings.

To prevent such scenario, all NXSL functions capable of accessing NetXMS objects requires "current node" object to be provided. Reference to object being searched will only be returned if node object supplied as "current node" is in trusted nodes list of target object. For example, if variable '''$node''' in script refers to NODE1, and [[NXSL:FindNodeObject|FindNodeObject]]($node, "NODE2") called, NODE1 must be added to list of trusted nodes for NODE2. In most places (transformation script, event processing policy, etc.) predefined variable '''$node''' exists, which refers to node object on behalf of which script is being executed. It will be event source for event processing policy script, DCI owner for transformation script, and so on.

For environments where such strict security checks are not required (for example, all users have read access to all nodes), they can be disabled to simplify configuration. Enforcement of trusted nodes checking controlled by server's configuration variable '''CheckTrustedNodes'''. By default it is set to '''0''' and check of trusted nodes is not enforced. To enable it, server's configuration variable '''CheckTrustedNodes''' must be set to '''1'''. The server restart is required to make this change effective.

[[Category:Scripting Guide]]

UM:NetXMS Scripting Language (NXSL)

2020-10-05T13:51:05Z

Phil:

{{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/ NetXMS Scripting Language]''' for current version of the documentation.
|}

= 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.

= "Hello, World!" Program =
Syntactically, NXSL looks similar to Perl or C. Here's simple NXSL program:

<syntaxhighlight lang="c">
/* sample program */
sub main()
{
println "Hello!";
return 0;
}
</syntaxhighlight>

This program will print word ''Hello'' on screen.

Also, keep in mind that you are free to choose your own formatting style. E.g. the above could have been written as:

<syntaxhighlight lang="c">
/* sample program */ sub main(){println "Hello!";return 0;}
</syntaxhighlight>

Now we'll analyze this program:

<syntaxhighlight lang="c">
/* sample program */
</syntaxhighlight>

Everything inside /* */ is considered a comment and will be ignored by interpreter. You can enclose comments, like below:

<syntaxhighlight lang="c">
/* comment /* another comment */ still comment */
</syntaxhighlight>

You can also use single line comments:

<syntaxhighlight lang="c">
x = 1; // everything between two slashes and end of line is a comment
</syntaxhighlight>

Now onto next line:

<syntaxhighlight lang="c">
sub main()
{
}
</syntaxhighlight>

This is a function definition. A function is a part of a program that can be called by other parts of the program. A function definition always has the following form:

'''sub''' ''name'''''('''''parameters''''')'''
{
/* the function code goes here */
}

The function can return a value to the caller and accept zero or more parameters.

The function name follows the rules for all names (formally: identifiers): it must consist entirely of letters (uppercase and lowercase are different!), digits, underscores (_) and dollar signs ($), but may not begin with a digit. Please note that most special identifiers starts with dollar sign ($), so it is recommended not to start your identifiers with it.

First line in function code looks like

<syntaxhighlight lang="c">
println "Hello!";
</syntaxhighlight>

In this line, println is an embedded operator which prints given string to standard output with carriage return, and "Hello!" is a string we want to print. Please note semicolon at the end of line – it's a separator between operators. Each operator should end with semicolon.

The next, and final, line of our small program is:

<syntaxhighlight lang="c">
return 0;
</syntaxhighlight>

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.

= Types =
NXSL is loose typed programming language. The system will automatically determine each variable type, assign a certain type to a variable and convert a variable type from one to another, if necessary. For example, a result for <tt>3 + "4"</tt> will be 7, because the system will automatically convert <tt>"4"</tt> string into an integer. In case if the system is not able to automatically convert a line into an appropriate integer, the operation will result in a runtime error.

NXSL supports the following variable types:

* integer (32 bit),
* unsigned integer (32 bit),
* integer (64 bit), unsigned integer (64 bit),
* floating-point number,
* string,
* array,
* object.

In addition to that, NXSL also supports a special variable type – NULL. This value represents a variable with no value. NULL is the only possible value of type NULL. An attempt to perform any type of arithmetical or string operations with NULL variable will result in system runtime error.

It is possible to manually convert variable to a certain type, using a special function, named depending on the variable type. For example, <tt>string(4)</tt>. That way it is also possible to convert NULL type variables. Therefore, to avoid runtime errors while processing NULL type variables, it is advised to use manual conversion.

NXSL does not require setting variable type beforehand. The only exception to this is arrays. In case if an array is required, operator <tt>array </tt>defines its subsequent variables as arrays. Accessing variable which was not previously assigned will return NULL value.

Although NXSL has object type variables, it is not an object-oriented language. It is not possible to define classes or create objects at script level – only in extensions written in C++. Object type variables are used to return information about complex NetXMS objects, like nodes or events, in a convenient way. Please note that assigning object type variables actually holds reference to an object, so assigning object value to another variable does not duplicate actual object, but just copy reference to it.

To get a human-readable representation of a variable or expression type for debugging, use the <tt>typeof()</tt> function, and to get a class name for object type variables, use <tt>classof()</tt> function.

= Variables =
Variables in NXSL behave the same way as variables in most popular programming languages (C, C++, etc.) do, but in NXSL you don't have to declare variables before you use them.

Scope of a variable can be either global (visible in any function in the script) or local (visible only in the function within which it was defined). Any variable is by default limited to the local function scope. Variable can be declared global using '''global''' operator.

For example:

<syntaxhighlight lang="c">
x = 1;
myFunction();

sub myFunction()
{
println "x=" . x;
}
</syntaxhighlight>

This script will cause run time error "Error 5 in line 6: Invalid operation with NULL value", because variable '''x''' is local (in implicit main function) and is not visible in function '''myFunction'''. The following script will produce expected result (prints x=1):

<syntaxhighlight lang="c">
global x = 1;
myFunction();

sub myFunction()
{
println "x=" . x;
}
</syntaxhighlight>

= Functions =
A function is a named code block that is generally intended to process specified input values into an output value, although this is not always the case. For example, the [[NXSL:trace|trace]] function takes variables and static text and prints the values into server log. Like many languages, NXSL provides for user-defined functions. These may be located anywhere in the main program or loaded in from other scripts via the use keywords.
To define a function, you can use the following form:

'''sub''' ''NAME'' '''(''' ''ARGUMENTS'' ''')''' '''BLOCK'''

where ''NAME'' is any valid identifier, ''ARGUMENTS'' is optional list of argument names, and ''BLOCK'' is code block.

To call a function you would use the following form:

''NAME'' '''(''' ''LIST'' ''')'''

where ''NAME'' is identifier used in function definition, and ''LIST'' is an optional list of expressions passed as function arguments.

To give a quick example of a simple subroutine:

<syntaxhighlight lang="c">
sub message()
{
println "Hello!";
}
</syntaxhighlight>

== Function Arguments ==

The first argument you pass to the function is available within the function as $1, the second argument is $2, and so on. For example, this simple function adds two numbers and prints the result:

<syntaxhighlight lang="c">
sub add()
{
result = $1 + $2;
println "The result was: " . result;
}
</syntaxhighlight>

To call the subroutine and get a result:

<syntaxhighlight lang="c">
add(1, 2);
</syntaxhighlight>

If you want named arguments, list of aliases for $1, $2, etc. can be provided in function declaration inside the brackets:

<syntaxhighlight lang="c">
sub add(numberA, numberB)
{
result = numberA + numberB;
println "The result was: " . result;
}
</syntaxhighlight>

If parameter was not provided at function call, value of appropriate variable will be '''null'''.

== Return Values from a Function ==

You can return a value from a function using the '''return''' keyword:

<syntaxhighlight lang="c">
sub pct(value, total)
{
return value / total * 100.0;
}
</syntaxhighlight>

When called, return immediately terminates the current function and returns the value to the caller. If you don't specify a value in '''return''' statement or function ends implicitly by reaching end of function's block, then the return value is '''null'''.

= Arrays =
An array in NXSL is actually an ordered map. A map is a type that associates ''values'' to ''keys''. This type is optimized for several different uses; it can be treated as an array, list (vector), hash table (an implementation of a map), dictionary, collection, stack, queue, and probably more. As array values can be other arrays.

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 =
An operator is something that you feed with one or more values, which yields another value.

== Arithmetic Operators ==

{| class="wikitable"
|-
! Example !! Name !! Result
|-
| -a || Negation || Opposite of ''a''.
|-
| a + b || Addition || Sum of ''a'' and ''b''.
|-
| a - b || Subtraction || Difference of ''a'' and ''b''.
|-
| a * b || Multiplication || Product of ''a'' and ''b''.
|-
| a / b || Division || Quotient of ''a'' and ''b''.
|-
| a % b || Modulus || Remainder of ''a'' divided by ''b''.
|}
The division operator ("/") returns a float value unless the two operands are integers (or strings that get converted to integers) and the numbers are evenly divisible, in which case an integer value will be returned.

Calling modulus on float operands will yield runtime error.

== Assignment Operator ==
The assignment operator is "=", which means that the left operand gets set to the value of the expression on the rights (that is, "gets set to").

== Bitwise Operators ==

{| style="border-spacing:0;"
! <center>Example</center>
! <center>Name</center>
! <center>Result</center>

|-
| 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
| 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;"| Not
| 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;"| Bits that are set in ''a'' are not set, and vice versa.

|-
| 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 & 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;"| And
| 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;"| Bits that are set in both operand are set.

|-
| 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 | 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;"| Or
| 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;"| Bits that are set in either operand are set.

|-
| 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 ^ 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;"| Xor
| 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;"| Bits that are set in only one operand are set.

|-
| 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;"| <nowiki>a << b</nowiki>
| 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;"| Shift left
| 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;"| Shift the bits of ''a'' ''b'' steps to the left (each step means "multiply by two").

|-
| 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 >> 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;"| Shift right
| 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;"| Shift the bits of ''a'' ''b'' steps to the right (each step means "divide by two").

|}
== Comparison Operators ==
Comparison operators allow you to compare two values.

''Table 3: Comparison Operators''

{| style="border-spacing:0;"
! <center>Example</center>
! <center>Name</center>
! <center>Result</center>

|-
| 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 == 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;"| Equal
| 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 equal to ''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;"| a != 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;"| Not equal
| 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 not equal to ''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;"| <nowiki>a < b</nowiki>
| 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;"| Less than
| 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 strictly less than ''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;"| a > 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;"| Greater than
| 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 strictly greater than ''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;"| <nowiki>a <= b</nowiki>
| 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;"| Less than or equal to
| 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 less than or equal to ''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;"| a >= 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;"| Greater than or equal to
| 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 greater than or equal to ''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;"| a ~= 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 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.

|}
== Incrementing/Decrementing Operators ==
NXSL supports C-style pre- and post-increment and decrement operators.

''Table 4: Incrementing/Decrementing Operators''

{| style="border-spacing:0;"
! <center>Example</center>
! <center>Name</center>
! <center>Effect</center>

|-
| 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
| 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;"| Pre-increment
| 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;"| Increments ''a'' by one, then returns ''a''.

|-
| 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++
| 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;"| Post-increment
| 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;"| Returns ''a'', then increments ''a'' by one.

|-
| 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
| 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;"| Pre-decrement
| 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;"| Decrements ''a'' by one, then returns ''a''.

|-
| 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--
| 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;"| Post-decrement
| 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;"| Returns ''a'', then decrements ''a'' by one.

|}
== Logical Operators ==
''Table 5: Logical Operators''

{| style="border-spacing:0;"
! <center>Example</center>
! <center>Name</center>
! <center>Result</center>

|-
| 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
| 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;"| Not
| 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 not <tt>TRUE</tt>.

|-
| 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 && 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;"| And
| 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 both ''a'' and ''b'' is <tt>TRUE</tt>.

|-
| 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 <nowiki>||</nowiki> 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;"| Or
| 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 either ''a'' or ''b'' is <tt>TRUE</tt>.

|}

== String Operators ==
There are two string operators. The first is the concatenation operator ('.'), which returns the concatenation of its right and left arguments. The second is the concatenating assignment operator ('''.='''), which appends the argument on the right side to the argument on the left side.

= Control structures =
Any NXSL script is built out of a series of statements. A statement can be an assignment, a function call, a loop, a conditional statement or even a statement that does nothing (an empty statement). Statements usually end with a semicolon. In addition, statements can be grouped into a statement-group by encapsulating a group of statements with curly braces. A statement-group is a statement by itself as well. The various statement types are supported:

* if

* else
* while
* do-while
* for
* break
* continue
* switch
* return
* exit

== if ==
The ''if'' construct is one of the most important features of many languages. It allows for conditional execution of code fragments. NXSL features an ''if'' structure that is similar to that of C:

if (expr)
statement

== else ==
Often you'd want to execute a statement if a certain condition is met, and a different statement if the condition is not met. This is what ''else'' is for. ''else'' extends an ''if'' statement to execute a statement in case the expression in the ''if'' statement evaluates to <tt>FALSE</tt>. The ''else'' statement is only executed if the ''if'' expression evaluated to <tt>FALSE</tt>.

== while ==
''while'' loops are the simplest type of loop in NXSL. They behave just like their C counterparts. The basic form of a ''while'' statement is:

while (expr)
statement

The meaning of a ''while'' statement is simple. It tells NXSL to execute the nested statement(s) repeatedly, as long as the ''while'' expression evaluates to <tt>TRUE</tt>. The value of the expression is checked each time at the beginning of the loop, so even if this value changes during the execution of the nested statement(s), execution will not stop until the end of the iteration.

== do-while ==
''do-while'' loops are very similar to ''while'' loops, except the truth expression is checked at the end of each iteration instead of in the beginning. The main difference from regular ''while'' loops is that the first iteration of a ''do-while'' loop is guaranteed to run (the truth expression is only checked at the end of the iteration), whereas it may not necessarily run with a regular ''while'' loop (the truth expression is checked at the beginning of each iteration, if it evaluates to FALSE right from the beginning, the loop execution would end immediately).

== for ==
''for'' loops are the most complex loops in NXSL. They behave like their C counterparts. The syntax of a ''for'' loop is:

for (expr1; expr2; expr3)
statement

The first expression (''expr1'') is evaluated (executed) once unconditionally at the beginning of the loop.

In the beginning of each iteration, ''expr2'' is evaluated. If it evaluates to <tt>TRUE</tt>, the loop continues and the nested statement(s) are executed. If it evaluates to <tt>FALSE</tt>, the execution of the loop ends.

At the end of each iteration, ''expr3'' is evaluated (executed).

== break ==
''break'' ends execution of the current ''for'', ''while'', ''do-while'' or ''switch'' structure.

== continue ==
''continue'' is used within looping structures to skip the rest of the current loop iteration and continue execution at the condition evaluation and then the beginning of the next iteration.

== switch ==
The ''switch'' statement is similar to a series of ''if'' statements on the same expression. In many occasions, you may want to compare the same variable (or expression) with many different values, and execute a different piece of code depending on which value it equals to. This is exactly what the ''switch'' statement is for.

Example:
<syntaxhighlight lang="c">
switch (input)
{
case "1":
trace(0,"Input is 1");
break;
case "2":
trace(0,"Input is 2");
break;
default:
trace(0, "Input is unknown");
}
</syntaxhighlight>

== return ==
If called from within a function, the <tt>return</tt> statement immediately ends execution of the current function, and returns its argument as the value of the function call. Calling <tt>return</tt> from main() function (either explicitly or implicitly defined) is equivalent of calling <tt>exit</tt>.

== exit ==
The <tt>exit</tt> statement immediately ends execution of the entire script, and returns its argument as script execution result.

= Expressions =
The simplest yet most accurate way to define an expression is "anything that has a value".

The most basic forms of expressions are constants and variables. When you type "''a'' = 5", you're assigning '5' into ''a''. '5', obviously, has the value 5, or in other words '5' is an expression with the value of 5 (in this case, '5' is an integer constant).

Slightly more complex examples for expressions are functions. Functions are expressions with the value of their return value.

NXSL supports the following value types: integer values, floating point values (float), string values and arrays. Each of these value types can be assigned into variables or returned from functions.

Another good example of expression orientation is pre- and post-increment and decrement. You be familiar with the notation of ''variable++'' and ''variable--''. These are increment and decrement operators. In NXSL, like in C, there are two types of increment - pre-increment and post-increment. Both pre-increment and post-increment essentially increment the variable, and the effect on the variable is identical. The difference is with the value of the increment expression. Pre-increment, which is written '++''variable''', evaluates to the incremented value. Post-increment, which is written '''variable''++' evaluates to the original value of variable, before it was incremented.

A very common type of expressions are comparison expressions. These expressions evaluate to either <tt>FALSE</tt> or <tt>TRUE</tt>.<nowiki> NXSL supports > (bigger than), >= (bigger than or equal to), = (equal), != (not equal), < (smaller than) and <= (smaller than or equal to). These expressions are most commonly used inside conditional execution, such as </nowiki>''if'' statements.

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]]

Scripting Guide

2020-10-05T13:50:49Z

Phil:

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/ NetXMS Scripting Language]''' for current version of the documentation.
|}

[[SG:Introduction|Introduction]]

[[UM:NetXMS Scripting Language (NXSL)|Language Description]]

[[SG:Security Issues|Security Issues]]

[[SG:Script Examples|Script Examples]]

[[NXSL Formal Grammar]]

[[NXSL Function Reference]]

[[NXSL Class Reference]]

[[NXSL Syntax highlight and calltips]]

SG:Introduction

2020-10-05T13:49:51Z

Phil:

{{DISPLAYTITLE:Introduction}}

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/ NetXMS Scripting Language]''' for current version of the documentation.
|}

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.

[[Category:Scripting Guide]]

SG:Introduction

2020-10-05T10:32:11Z

Phil:

{{DISPLAYTITLE:Introduction}}

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please visit '''[https://www.netxms.org/documentation/nxsl-latest/ NetXMS Scripting Language]''' documentation.
|}

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.

[[Category:Scripting Guide]]

SG:Introduction

2020-10-05T10:31:57Z

Phil:

{{DISPLAYTITLE:Introduction}}

{| style="border-spacing: 20px; border: 20px solid red;"
|
'''WARNING''': This page is no longer updated. Please wisit '''[https://www.netxms.org/documentation/nxsl-latest/ NetXMS Scripting Language]''' documentation.
|}

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.

[[Category:Scripting Guide]]

SG:Introduction

2020-10-05T10:31:49Z

Phil:

NXSL:FindDCIByName

2020-08-12T10:49:17Z

Phil:

__NOTOC__
Find DCI by name (search is case-insensetive).

== Syntax ==

FindDCIByName(''node'', ''parameter name'');

== Parameters ==

:{|
|-
| ''node'' || [[NXSL:Node|Node]] object. Predefined variable '''$node''' can be used to refer to current node in transformation script or event processing policy rule.
|-
| ''name'' || DCI parameter name.
|}

== Return Value ==

DCI ID on success or 0 if DCI with matching name was not found.

== Examples ==

FindDCIByName($node, "Agent.Uptime") -> 5 /* perhaps */
FindDCIByName($node, "bad") -> 0