GET_VAR

Script Function: It returns the value of a Variable object.

Syntax

GET_VAR (Variable[, Key [, Column [,XPath/XQuery]]])

Syntax

Description/Format

Variable

The name of a Variable object whose value should be retrieved.
Format: AE name, script literal or script variable

Key

The variable line for the value retrieval (entry of the Key / first value column).
Format: AE name, script literal or script variable

Column

The number of the column whose value should be used.
Format: script literal, script variable or number without inverted commas

Allowed values:
Static variables: KEY (Key column), 1 to 5 (Value column 1 to 5)
Dynamic variables: RESULT (result column), 1 to n (Value column 1 to n) 

XPath/XQuery

Use an XPath or XQuery expression to access and read out the nodes or content of XML data.
If you do not enter an expression, the full-column content will be returned.

This function may be used with the static Variable object XML only.

The use of XPath expressions with the Variable object XML is possible, but depending on the database the Automation Engine system is being used with, individual XPath expressions may work differently. In such cases please check with the database's vendor.


Return Codes

Variable's value(s)
" " -The entry does not exist or does not include a value.

Comments

You can use this script function in order to read the values of static and dynamic Variable objects. Accessing a dynamic variable has the effect that the value will be resolved. This means that the value is directly retrieved from the data source (database, variable, directory).

An error that occurs while dynamic Variable objects are being resolved results in a runtime error.

The first line is used if the parameter Key is not specified. Note that you must always specify the key in static Variable objects in which the validity area "Freely selected" is selected.
If the
Column is also missing, the system will automatically use the Value 1 column (for static Variable objects), the result column (variable source: SQL, SQL-internally, multi) or the Filelist column (variable source: Filelist).

In variables that use the source "Filelist", you can either skip the column or use the value 1. The specified key complies with the returned value because there is only one column.

The area between 1 (first value column) and the last column number can be used as the value for the Column . You can use the value RESULT for the Column in order to read the result column (dynamic variables except "Filelist"). Note that static variables have only 5 value columns. Using this script function in combination with :FILL has the effect that all values of a line will be written to a script array.

The value's format corresponds to the output format that has been defined in the Attributes tab.

This script function can also be used to read agent variables.

  To access a key that begins with a "&" character, you must use this character twice. Otherwise, this term will be interpreted as a script variable and the system will try to resolve it.

For example: Access the key "&key" in the Variable object VARA.TEST
:SET &TEST#GET_VAR(VARA.TEST,"&&key")

A blank will be returned when you use GET_VAR for a key that does not exist.

In dynamic variables, you must specify the value of the result column (parameter Line ) in the format that it shows in the data source (SQL - database, MULTI - Variable object). The variable's output format is irrelevant in this case.

In static variables, you can also use the specific value "KEY" for the column. You can use it in order to check whether a certain key exists in this Variable object. It does not exist when the script function returns an empty value and there is an entry when it returns the key.

In the following example, the script function returns "Test" when there is a key and " " when there is no key:

:SET &KEY# = GET_VAR(VARA.TEST, "Test","KEY")

When using this script function with the static Variable object XML, the values for XML data type will be beautified automatically. That means, you may use XML in a single script line for example, but in the resulting script output the value will be rearranged according to the XML standard.

Examples

The following example retrieves the value of a variable and stores the result in a script variable:

:SET &TEST# = GET_VAR(MM.END.PROCESSING, "BookingDate")

Script variables can also be used in functions:

:SET &VAR# = "MM.END.PROCESSING"
:
SET &VAL# = "BookingDate"
:
SET &TEST# = GET_VAR(&VAR#, &VAL#)

In the following example, the script function GET_VAR is used to define a condition:

:IF GET_VAR(MM.END.PROCESSING, "BookingDate") = SYS_DATE("DDMMYY")  
!...
 
:
ENDIF

See also:

Script element Description

:DELETE_VAR

Deletes one or all values of a static Variable object.
:PUT_VAR Stores a value in a static Variable object.
:SET_SCRIPT_VAR Sets the values of script variables by indirect access.
GET_SCRIPT_VAR Returns the values of script variables by indirect access.

RESOLVE_VAR

Resolves any kind of variable (prompt values, system variables, script variables, variable objects) in text.

PREP_PROCESS_VAR and PREP_PROCESS_VAR_XML

Prepares the processing of a data sequence (values of a Variable object).

Script Elements - Read or Modify Objects

Agent Variables

Sample Collection:
Database Maintenance with Options

Calling an MBean

About Scripts
Script Elements - Alphabetical Listing

Script Elements - Ordered by Function