GET_VAR

Use the GET_VAR script function to return a value from a static or dynamic VARA object, or from an Agent variable. When you use this function to access a dynamic VARA object, the value is resolved. The value is retrieved directly from the data source (a database, variable, or directory).

Tips:

• Use the GET_VAR script function in combination with the :FILL statement to write all values of a line to a script array. For more information, see :FILL.
• You can use the GET_VAR function to check whether a particular key exists in a static VARA object. Specify the key you want to check as the column. If the key does not exist, then the script function returns an empty value. If the key exists, the function returns the key.
  Example: The following script line returns the value Test when the key exists, and returns a blank when there is no key.
  :SET &KEY# = GET_VAR(VARA.TEST, "Test","KEY")

More Information:

• User-Defined VARA Objects
• List of Agent Variables

Syntax

The syntax for this script function depends on the type of VARA object you want to retrieve the value from. For Static VARA objects and XML VARA objects, the scope defined for the VARA object also has an effect. For more information, see Defining the Attributes Page.

Static VARA object

• Scope: freely selected
  GET_VAR (VARA, Key [, Column])
  
• Any other scope
  GET_VAR (VARA [, Key] [, Column])

XML VARA object

• Scope: freely selected
  GET_VAR (VARA, Key [, XPath|XQuery])
• Any other scope
  GET_VAR (VARA [, Key] [, XPath|XQuery])

Dynamic VARA object

• GET_VAR (VARA [, Key] [, Column])

Parameters

• GET_VAR
  Retrieves the value from a VARA object

• VARA
  Name of the VARA object from which you want to retrieve the value
  Format: AE name, script literal or script variable

• Key
  Variable line to retrieve the value from
  Format: AE name, script literal or script variable
  Note: Write the ampersand character twice when you want to access a key that begins with &. Otherwise, the system interprets the term as a script variable and does not try to resolve it.
  Example: The following script line accesses a key called &key in a VARA object named VARA.TEST.
  :SET &TEST# = GET_VAR(VARA.TEST,"&&key")

• Column or XPath or XQuery
  (Optional) Specifies the content to retrieve, depending on the type of VARA object

  • (Static or Dynamic VARA object) Number of the column to retrieve the value from
  • (XML VARA object) XPath or XQuery expression to select a subset of XML content
  Format: script literal, script variable, or number enclosed in quotation marks
  Allowed values:
  • Static VARA object:
    • KEY (Key column)
    • 1 to 5 (Value column 1 to 5)
  • Dynamic VARA object:
    • RESULT (result column, except for FILELIST VARA objects)
    • 1 to n (Value column 1 to n)
    • FILELIST VARA objects: Omit the column, or use the value 1
  • XML VARA object:
    • XPath expression
    • XQuery expression
    Note: If you do not enter an expression, the full content of the column is returned.
    Important: You can use XPath expressions with the XML VARA object, but XPath expressions may work differently depending on the database. See the documentation provided by the database vendor.

Important! An error that occurs while dynamic VARA objects are being resolved results in a runtime error.

Return Codes

The script function has the following possible return codes:

• The value retrieved from the VARA object
• A single blank space if the entry does not exist, or does not include a value
  Tip: Use the script access setting of the VARA object to define what happens if the specified key is not available. For more information, see Script Access.

The format of the returned value corresponds to the output format set on the Attributes page in the object definition. For more information, see Attributes Page.

The following behaviors apply depending on the type of VARA object, and scope if applicable.

Static VARA object

• Freely selected scope: You must define the key in the script function, and GET_VAR returns the value based on that key.
• Other scope: the scope determines which key is used to return the value.
• If you do not specify a column, GET_VAR returns the first column.

Dynamic VARA object

• If you do not specify a key, GET_VAR returns the first row.
• If you do not specify a column, GET_VAR returns the first column:
  • SQL, SQLI, and MULTI VARA objects: Result column
  • FILELIST VARA objects: FILE LIST column
    

XML VARA object

• Freely selected scope: You must define the key in the script function, and GET_VAR returns the value based on that key.
• Other scope: the scope determines which key is used to return the value.
• If you do not specify the XPath or XQuery, GET_VAR returns the entire XML document (the content of the Value field for the chosen key).
• When you use this script function with a static XML VARA object, the values for XML data type are automatically beautified. You may use XML in a single script line, but in the resulting script output, the value will be rearranged according to the XML standard.
  

Examples

The following example retrieves a value from a VARA object and stores the result in a script variable:

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

The following example uses script variables in the GET_VAR function:

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

The following example uses the GET_VAR script function in a condition:

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

See also: