Statements

The following elements can be used in statements.

Assignment

The assignment operation is declared with an equal sign (=). It loads the value from the expression evaluated on the right into a field on the left.

Example 1. Field Assignment

This statement sets the $EventReceivedTime field to the value returned by the now() function.

$EventReceivedTime = now();

Block

A block consists of one or more statements within curly braces ({}). This is typically used with conditional statements as in the example below.

Example 2. Conditional Statement Block

If the expression matches, both log messages will be generated.

if now() > 2000-01-01 00:00:00
{
   log_info("we are in the");
   log_info("21st century");
}

Procedures

A procedure is a statement that performs a set of actions. Procedures can accept arguments. Unlike a function, a procedure modifies its arguments, the state of the NXLog Agent engine, the state of a module, or the current event. Procedures can be polymorphic, meaning that the same procedure can take different argument types.

Many NXLog language features are provided through procedures. See the list of available core procedures. Modules can provide additional procedures for use with the NXLog language.

Example 3. Calling a procedure

This example uses the parse_syslog() procedure, provided by the xm_syslog module, to parse syslog records received via UDP.

nxlog.conf

<Input in>
    Module  im_udp
    Host    0.0.0.0
    Port    514
    Exec    parse_syslog();
</Input>

Example 4. Calling a procedure of a specific module instance

Procedures for a specific module instance can be called using the -> operator. This statement calls the rotate_to() procedure of an om_file instance named out to rotate the current output file.

out->rotate_to("output_logs");

Calling procedures of a specific instance is especially useful when the configuration contains more than one instance of the same module. These statements call the parse_xml() procedure of two xm_xml instances, one named xml_a and the other named xml_b.

xml_a->parse_xml();
xml_b->parse_xml();

If-Else

A conditional statement starts with the if keyword followed by a boolean expression and a statement. The else keyword, followed by another statement, is optional. Brackets around the expression are also optional.

Example 5. Conditional Statements

A log message will be generated if the expression matches.

if now() > 2000-01-01 00:00:00 log_info("we are in the 21st century");

This statement is the same as the previous one but uses brackets.

if ( now() > 2000-01-01 00:00:00 ) log_info("we are in the 21st century");

This is a conditional statement block.

if now() > 2000-01-01 00:00:00
{
   log_info("we are in the 21st century");
}

This conditional statement block includes an else branch.

if now() > 2000-01-01 00:00:00
{
   log_info("we are in the 21st century");
}
else log_info("we are not yet in the 21st century");

Like Perl, the NXLog language does not have a switch statement. Instead, this can be accomplished by using conditional if-else statements.

Example 6. Emulating "switch" With "if-else"

The generated log message varies based on the value of the $value field.

if ( $value == 1 )
   log_info("1");
else if ( $value == 2 )
   log_info("2");
else if ( $value == 3 )
   log_info("3");
else
   log_info("default");

The Perl elsif and unless keywords are not supported.

While

A basic looping construct in NXLog language. The syntax is:

while ( cond_expression )
{
   statement;
   statement;
   ...
   statement;
}

Where cond_expression is any valid NXLog language expression which evaluates to a boolean value. The statements will be executed repeatedly as long as the cond_expression evaluates to TRUE.

It is important to note that currently nothing prevents infinite loops therefore it is the responsibility of the user to not create such loops.

An example:

$$i = 0;
while ( $$i < 5 )
{
   log_info("Repeated message");
   $$i = $$i + 1;
}

while loops can be nested without limitations but the best practice is to limit the nesting level in order to avoid long-running exec blocks.

Foreach

A looping construct in NXLog language designed to work on containers. The syntax is:

foreach (expression, module-variable)
{
   statement;
   statement;
   ...
   statement;
}

Where expression is any valid NXLog language expression which evaluates to a container type of value like array or hash. But if one wants to change the values in that container then the expression must "address" a container or a sub-container already assigned to a field or to a module variable. Any temporary container, which can be a container literal or a function’s return value, will be disposed outside the loop.

The module-variable is a $$ notation for a module variable.

The statements will be executed as many times as many elements the container has (expression) and for each repetition, the module-variable will be updated with the access key for a container element. In case of arrays the module-variable will hold the index values, while in the case of hash containers, this will hold the keys for the stored values.

An example:

$$array = [1, 2, 3];
foreach ($$array, $$idx)
{
   $$array[$$idx] = $$array[$$idx] * 10;
}

$$hash = ( '1' => 100, '2' => 500);
foreach($$hash, $$key)
{
   $$hash($$key) = $$hash($$key) - 5;
}

foreach loops can be nested without limitations but the best practice is to limit the nesting level in order to avoid long-running exec blocks.

Break, Continue

Like programming or scripting languages NXLog Agent loops also have these statements and the effects are the same. In loop body break; causes immediate leaving of the loop while continue; causes skipping the rest of the statements after the continue;. In the case of nested loops, these statements affect the loop in which the break or the continue resides.

E.g.:

$ar = [9,8,7,6,5,4,3,2,1];
foreach($ar, $$i)
{
  if ( $ar[$$i] == 4 )
  {
    continue;
  }
  if ( $ar[$$i] == 2 )
  {
    break;
  }
  if ( $ar[$$i] % 2 == 0 )  $ar[$$i] = "xxx";
}