var

Overview

The var statement is used to create or update a variable which can subsequently be referenced by name in the USE script.

Syntax

[public] varname [ = value]

[public] varname operator number

[public] encrypt varname = value

For details on encrypted variables please refer to the encrypt article.

Details

Variables are created in one of two ways:

1. Manually via the var command

2. Automatically, as a consequence of other statements in the script

If the word public precedes a variable declaration then the variable will be shown in, and its value can be updated from, the Exivity GUI. Only variables prefixed with the word public appear in the GUI (all others are only visible in the script itself). To make an automatic variable public, re-declare it with a value of itself as shown below:

# Convert the automatic NEWLINE variable to be public
public var NEWLINE = ${NEWLINE}

Manually defined variables

A variable is a named value. Once defined, the name can be used in place of the value for the rest of the script. Amongst other things this permits the configuration of various parameters at the top of a script, making configuration changes easier.

The = value portion of the statement is optional, but if used there must be white space on each side of the = character. To use spaces in a variable value it should be quoted with double quotes.

Once a variable has been defined it can be referenced by prefixing its name with ${ and post-fixing it with a }. For example, a variable called outputFile can be referenced using ${outputFile}. If no value is specified, then the variable will be empty, eg:

var empty_var
print Variable value: "${empty_var}"

will result in the output:

Variable value:

Variable names are case sensitive, therefore ${variableName} and ${VariableName} are different variables.

If there is already a variable called name then the var statement will update the value.

There is no limit to the number of variables that can be created, but any given variable may not have a value longer than 8095 characters.

Arithmetic

Variables that contain a numeric value can have the arithmetic operations performed on them in one of two ways.

Method 1

The first, and recommended way is to use an expression, as demonstrated in the example code below:

var cpu_total = 5
var cpu_total = (${cpu_total} + 2)   # Add 2 to cpu_total

var ram = 8
var ram_uplift = 4
var ram = (${ram} + ${ram_uplift})  # Add ram_uplift to ram

When using expressions in this manner after a var statement it is necessary to enclose the expression in parentheses as shown above but both integer and floating point arithmetic can be performed.

Method 2

If working with integer arithmetic then one of the operators += , -= , *= , /= or %= can be used which will perform addition, subtraction, multiplication, (integer) division or modulo operations respectively.

For example the statement var x += 10 will add 10 to the value of x. Note that both the value in the variable and the value following the operator must be integers.

When performing arithmetic operations on a variable using this second method, any leading zeros in the value of that variable will be respected:

var x = 000
var x += 5    # Result is 005
var x += 10   # Result is 015
var x += 100  # Result is 115
var x += 1000 # Result is 1115

Currently, only integer arithmetic is supported by the += , -= , *= , /= and %= operators.

Automatic variables

Automatic variables are referenced in exactly the same way as manually created ones; the only difference is in the manner of creation.

The following variables are automatically created during the execution of a USE script:

Variable	Details
${ARGC}	The number of parameters passed to the script
${ARG_N}	For each parameter passed to the script a variable called ${ARG_N}, where N is a number greater than or equal to 1, will be created whose value is the argument value associated with that parameter
${DAY}	The day of the current local date, padded to 2 digits if necessary
${DAY_NAME}	The full English name of the current day of the week
${DAY_UTC}	The day of the current date in UTC, padded to 2 digits if necessary
${DAY_NAME_UTC}	The full English name of the current day o fthe week in UTC
${GET_TIME}	The current local time in 'friendly' format, eg Tue Jan 16 14:04:32 2018
${loop_label.COUNT}	A foreach loop creates this variable (where loop_name is the name of the loop). The value of the variable is updated every time the loop executes, with a value of 1 on the first loop. If no loops are performed, then the variable will have a value of 0
${loop_label.NAME} ${loop_label.VALUE}	When iterating over the children of a JSON object (not an array) using foreach, these variables are updated with the name and value respectively of the current child every time the loop is executed (either may be blank if the child has no name or value respectively)
${loop_label.TYPE}	When iterating over the children of a JSON object (not an array) using foreach, this variable is updated to reflect the type of the current child every time the loop is executed. The type will be one of boolean, number, string, array, object or null.
${HOUR}	The hour of the current local time, padded to 2 digits if necessary
${HOUR_UTC}	The hour of the current time in UTC, padded to 2 digits if necessary
${HTTP_STATUS_CODE}	The HTTP status code returned by the server in response to the most recent http request executed. In case of transport-level failure contains value -1, HTTP_STATUS_TEXT variable contains error message
${HTTP_STATUS_TEXT}	In case of transport-level failures, this variable will contain an error message intended to assist in identifying the issue
${MINUTE}	The minute of the current local time, padded to 2 digits if necessary
${MINUTE_UTC}	The minute of the current time in UTC, padded to 2 digits if necessary
${MONTH}	The month of the current local date, padded to 2 digits if necessary
${MONTH_NAME}	The full English name of the current month of the year
${MONTH_UTC}	The month of the current date in UTC, padded to 2 digits if necessary
${MONTH_NAME_UTC}	The full English name of the current month of the year in UTC
${NEWLINE}	A newline (0x0A) character. Example use: var twolines = "This string${NEWLINE}contains two lines of text"
${SECOND}	The second of the current local time, padded to 2 digits if necessary
${SECOND_UTC}	The second of the current time in UTC, padded to 2 digits if necessary
${MSEC}	The milliseconds of the current local time, padded to 3 digits if necessary
${MSEC_UTC}	The milliseconds of the current time in UTC, padded to 3 digits if necessary
${SCRIPTNAME}	The filename of the script being executed
${OSI_TIME_UTC}	The current UTC time in YYYYMMDD'T'HHMMSS'Z' format, eg: 20180116T140432Z
${YEAR}	The year of the current local date as a 4 digit number
${YEAR_UTC}	The year of the current date in UTC as a 4 digit number
${UNIX_UTC}	Current UNIX time (seconds since 1 January 1970 00:00:00 UTC)

To derive the short versions of the day and month names, use a match statement to extract the first 3 characters as follows:

match day "(...)" ${DAY_NAME_UTC}

var short_day = ${day.RESULT}

The .LENGTH suffix

On occasion it may be useful to determine the length (in characters) of the value of a variable. This can be done by appending the suffix .LENGTH to the variable name when referencing it. For example, if a variable called result has a value of success then ${result.LENGTH} will be replaced with 7 (this being the number of characters in the word 'success').

A variable with no value will have a length of 0, therefore using the .LENGTH suffix can also be used to check for empty variables as follows:

    var myvar
    if (${myvar.LENGTH} == 0) {
        print The variable 'myvar' is empty
    } else {
        print The variable 'myvar' has a value of ${myvar}
    }

myvar.LENGTH is not a variable in its own right. The .LENGTH suffix merely modifies the manner in which the myvar variable is used.

Examples

Basic variable creation and use

    # Declare a variable
    var name = value

    # If the value contains whitespace then it must be quoted or escaped
    var sentence = "This sentence is contained in a variable"

    # Pathnames should be quoted to avoid any incidences of '\t' being expanded to tabs
    var exportfile = "C:\exivity\collected\Azure\customers.csv"

Creating encrypted variables

    # ---- Start Config ----
    encrypt var username = admin
    encrypt var password = topsecret
    var server = "http://localhost"
    var port = 8080
    var api_method = getdetails
    # ---- End Config ----

    set http_authtype basic
    set http_username ${username}
    set http_password ${password}

    buffer {response} = http GET ${server}:${port}/rest/v2/${api_method}