GET_VAR

Use the GET_VAR script function to retrieve 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 automatically. The value is retrieved directly from the data source (a database, variable, or directory).

More Information:

• User-Defined VARA Objects
• List of Agent Variables

Syntax

The syntax for this script function depends on the type of VARA object from which you want to retrieve the value. For Static and XML VARA objects, the scope defined for the VARA object also affects the syntax. For more information, see STATIC VARA Objects.

Static VARA Object

• Freely selected scope:
  

  GET_VAR (VARA, Key [, Column])

• Any other scope:
  

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

XML VARA Object

• Freely selected scope:
  

  GET_VAR (VARA, Key [, XPath|XQuery])

• Any other scope:
  

  GET_VAR (VARA [, Key] [, XPath|XQuery])

Dynamic VARA Object

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

Parameters

Parameter	Description	Format
VARA	Name of the VARA object from which to retrieve the value.	AE name, script literal, or script variable
Key	Variable line from which to retrieve the value. Note: Write the ampersand character twice when you want to access a key that begins with & (for example: &&key). Otherwise, the system interprets the term as a script variable and does not attempt to resolve it.	AE name, script literal, or script variable
Column or XPath or XQuery	(Optional) Specifies the content to retrieve, depending on the VARA object type: Static or Dynamic VARA: Number of the column from which to retrieve the value. XML VARA: XPath or XQuery expression to select a specific subset of XML content. Allowed values: Static VARA: KEY (Key column) or 1 to 5 (Value column 1 to 5). Dynamic VARA: RESULT (Result column, except for FILELIST VARA objects) or 1 to n (Value column 1 to n). For FILELIST VARA objects, omit the column or use the value 1. XML VARA: An XPath or XQuery expression. If you do not specify an expression, the full content of the column is returned.	Script literal, script variable, or number enclosed in quotation marks

Return Codes

This script function returns the following values:

• 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 configured on the Attributes page of the object definition. For more information, see Defining the Attributes Page.

Important Considerations

• Runtime Errors: Any error that occurs while dynamic VARA objects are being resolved will result in a runtime error.

• Array Filling: Use the GET_VAR script function in combination with the :FILL statement to write all values of a line directly into a script array.

• Checking for Keys: You can use GET_VAR to check whether a particular key exists in a static VARA object by specifying the key you want to check as the column. If the key exists, the function returns the key; otherwise, it returns an empty value.

• Case-Insensitive Keys: You can use the FORCE_VARA_KEY_CI key of the UC_SYSTEM_SETTINGS variable to force context-insensitive read/write actions on STATIC VARA objects while defining the key. When this setting is Y, the key is converted to and remains in uppercase. See FORCE_VARA_KEY_CI.

• Static VARA Default Behavior:

  • If the scope is freely selected, you must define the key in the script function, and GET_VAR returns the value based on that key.

  • For any other scope, the scope automatically determines which key is used to return the value.

  • If you do not specify a column, GET_VAR returns the first column.

• Dynamic VARA Default Behavior:

  • 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 (Result column for SQL, SQLI, and MULTI VARA objects; FILE LIST column for FILELIST VARA objects).

• XML VARA Default Behavior:

  • If the scope is freely selected, you must define the key in the script function. For other scopes, the scope determines the key.

  • If you do not specify an XPath or XQuery expression, GET_VAR returns the entire XML document (the complete content of the Value field for the chosen key).

  • When you use this script function with a static XML VARA object, the XML values are automatically beautified. You may use XML in a single script line, but in the resulting script output, the value is rearranged according to the standard XML format.

  • XPath expressions may work differently depending on the specific database vendor. Always consult the documentation provided by your database vendor.

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 as parameters 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 to define a condition:

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

!... 

: ENDIF

The following example checks whether a particular key exists. It 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")

The following script line accesses a key called &key in a VARA object named VARA.TEST by properly escaping the ampersand:

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

See also: