Automic Workload Automation

  • Private Community
 View Only
Back to Library

GET_VAR syntax 

Jan 14, 2019 11:32 AM

The documentation for GET_VAR includes the following syntax description:

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

This syntax description is incorrect. The correct syntax descriptions follow.

 

Update 2019.01.31: The documentation has been updated and now correctly describes the syntax for GET_VAR.

 

Syntax descriptions for GET_VAR

The type and scope of the VARA determine the syntax description:

Static or XML VARA with scope Freely selectedAll other VARAs
GET_VAR(VARA, Key [, Column|XPath|XQuery])GET_VAR(VARA [, Key] [, Column|XPath|XQuery])

 

Parameters

VARA

The name of the VARA object. Always required.

 

Key

The name of the key or row to access. Required for Static and XML VARA objects with scope Freely selected.

  • Static or XML VARA with scope Freely selected

    If the key is not specified, runtime error U00003712 is generated.

  • Static or XML VARA with any other scope

    If the key is not specified, the scope determines the key that is read.

  • Dynamic VARA (SQL, EXEC, FILELIST, etc.)

    If the key is not specified, the first row from the results will be read.

 

Column | Xpath | XQuery

  • Static VARA
    The Value column to read
    If the column is not specified, the first column (Value 1) will be read.
  • Dynamic VARA (except FILELIST)
    The result column to read
    • RESULT: the first result column will be read.
    • 1 to n (where n is the number of columns returned): The referenced column will be read.

      If the column is not specified, the first column is read.

  • FILELIST VARA
    The column to read. FILELIST VARAs always return exactly one column.
    Can be 1 or any string except RESULT. Integers other than 1 and the string RESULT will generate a runtime error.
  • XML VARA
    An Xpath or XQuery string to extract specific subset of information from the XML content

    If Xpath/XQuery is not specified, the entire XML document (the content of the Value field for the chosen key) is read.

 

The fourth argument

Contrary to the syntax description in the documentation, the Xpath/XQuery argument should be the third argument, not the fourth. If you try to save a script containing a string as the fourth parameter, the following error results:

U04006586 Error found in object 'UC0.XML_TEST.SCRI(Process)', line '14'.

U01001321 Expecting 'Number(int)/Variable' as function parameter '4'.

This error message suggests that GET_VAR can take a fourth (integer) argument, but this behavior is not publicly documented.

 

See also: Reference dynamic VARA columns by name.

Statistics
0 Favorited
23 Views
0 Files
0 Shares
0 Downloads

Tags and Keywords

Comments

Michael A. Lowry
Jan 31, 2019 09:23 AM

CA/Automic have updated the documentation. It now correctly describes the syntax for GET_VAR.

 

For what it’s worth, I did a couple more tests and discovered that GET_VAR actually has two undocumented arguments. A script containing this command can be saved and run without problems:

:SET &String# = GET_VAR(&VARA_Name#, &VARA_Key#, &VARA_Selector#, &GET_VAR_arg4#, &GET_VAR_arg5#)

 

However, if you add a sixth argument, a syntax error will be generated when you attempt to save the object.
U01001319 Too many parameters are defined for function 'GET_VAR'.

 

I have no idea what arguments 4 and 5 are, but the Automation Engine expects them to be integers.

U01001321 Expecting 'Number(int)/Variable' as function parameter '5'.

Michael A. Lowry
Jan 15, 2019 05:04 AM

It occurs to me that it would be possible to put more control in the user’s hands by adding another Scope option, Initial values.

 

The Scope determines the key that will be used to access the VARA if no key is specified. (The Scope setting should therefore ideally be renamed to Default key.) My idea is that there should be an additional option in this list: Initial values. Here’s a quick mock-up.

 

I created a new idea for this: Rename VARA Scope to ‘Default key’ & add options. If you like the idea, please vote for it!

Michael A. Lowry
Jan 15, 2019 04:53 AM

There’s a setting on the Attributes tab of each VARA object that in principle ought to allow the user to specify how the VARA behaves if it is accessed using a non-existent key.

 

Java User Interface

  

Automic Web Interface

 

The Script access setting determines the behavior when accessing a VARA using a non-existent key. For example, here is the error that results when a script attempts to read a non-existent result row from an SQLI VARA.

U00020331 Runtime error in object 'UC0.TEST_1.SCRI', line '00014':

U00003708 No value found for variable 'VARA.SQLI.NEW.1' with validity 'abc2134'.

 

I did some quick tests, and discovered that if you set this option to initial values, the behavior will depend on the type of VARA being accessed. And once again, static and XML VARA objects are treated differently for some reason.

VARA type

Result if specified key not found

& setting is “Return initial values”

Result if specified key not found & setting is “Return error”

Result if no key specified, regardless of key-not-found setting.

StaticA single blank space character.Error U00003708Error U00003712
XMLA single blank space character.Error U00003708Error U00003712
DynamicThe first result row.Error U00003708The first result row.

 

I do not know why static and XML VARA objects are singled-out for special treatment.

Michael A. Lowry
Jan 15, 2019 03:52 AM

The GET_VAR documentation states:

If you do not specify a Key parameter, the first line is used.

 

Unfortunately, this is not correct. There are two situations wherein GET_VAR returns a runtime error if no key is specified:

  • Static VARA with scope Freely selected
  • XML VARA with scope Freely selected

 

Here’s an example of the error:

U00020331 Runtime error in object 'UC0.TEST_1.SCRI', line '00014':

U00003712 Missing key for accessing variable 'UC0.XML_TEST.VARA_XML'.

 

If the script function truly worked as described, the Key argument would be optional in all cases. Then the syntax description could be simplified to just this:

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

Michael A. Lowry
Jan 15, 2019 03:38 AM

Two observations:

  • The Key argument is required only when accessing a static or XML VARA whose scope is set to Freely selected. In all other cases, it is optional.
  • The Column argument and XPath/XQuery argument are not two separate arguments; they're different mutually exclusive options for the third argument.

 

Given the above, it might make sense to summarize the syntax descriptions like this:

Static or XML VARA with scope “Freely selected”All other VARAs
GET_VAR(VARA, Key [, Column|XPath|XQuery])GET_VAR(VARA [, Key] [, Column|XPath|XQuery])

 

Would it be possible to get feedback and confirmation from CA on my findings?

Related Entries and Links

No Related Resource entered.