XML VARA Objects

You store complex data as XML structures in XML VARA objects. Through the XML VARA object, you can then reference and use this data in PromptSet objects, in Script objects, and other script contexts system-wide. XML VARA objects can have any number of keys. The value of each key is a structured XML.

XML VARA objects allow you to retrieve a list of Variable object values. Use the PREP_PROCESS_VAR and PREP_PROCESS_VAR_XML script function to access all or several particular entries of a variable. This prepares the processing of a data sequence.

You can use XPath expressions with XML VARA objects. Depending on your database, individual XPath expressions can work differently. If you experience such situations, check with the database vendor.

Use PromptSet variables here when you use the Dynamic Reload feature for combo box prompts. The PromptSet variables are resolved when the object that includes the PromptSet is executed.

Script Elements for XML VARA Objects

You can use the following script elements to store values in the VARA object:

• :PUT_VAR stores values
• :PUT_VAR_COL stores a value in a specific column
• :DELETE_VAR deletes one or all values

XML VARA Restrictions

• With an Oracle database, the attribute values of XML data should not contain more than 4000 characters.

• XML data can use only character encoding that is compatible with the character encoding in the database connection.

Like any other objects XML VARAs have various definition pages. General, Version Management and Documentation are common to all objects. Here we describe the Variables and Commands pages that are specific to XML VARAs.

To Define an XML VARA Object

1. On theVariables page, add the Keys and values of the XML VARA object.

   1. Use the buttons on the toolbar to add, edit, duplicate and remove keys.

   2. On the editor, enter the XML structure for that key in the pane on the right handside.

      Example:

      An XML VARA object called SRV.VARA.XML has a key called SERVER NAMES with the following value:

      <SERVERS>

          <SERVER NAME="TestServer1">

              <IP>192.168.0.1</IP>

          </SERVER>

          <SERVER NAME="TestServer2">

              <IP>192.168.0.2</IP>

          </SERVER>

      </SERVERS>

      To read the single values from the XML, you use the GET_VAR script function with XQUERY expressions:

      :set &name# = GET_VAR('HAM.VARA.XML','TESTSERVER','/SERVERS/SERVER[1]/@NAME')

      :set &ip# = GET_VAR('HAM.VARA.XML','TESTSERVER','/SERVERS/SERVER[1]/IP/text()')

      :p &name# &ip#

      The output is as follows:

      U00020408 TestServer1 192.168.0.1

2. On the Attributes page define the following:

   1. In Variable Setting select the Scope of the variable.

      Usually, the key must be specified as a parameter in the script element :PUT_VAR or GET_VAR. However, this makes it difficult to ensure that values are stored with unique keys. Specify a scope to simplify the design of scripts that write to or read from the VARA object.

      The key is optional for all values of scope except Freely selected. The default key used to access the VARA object if no key is specified depends on the characteristics of the task that is accessing the object.

      The following options are available:

      • No Scope

        Specifying a key is optional.

        Default key if none is specified: *

      • Freely selected

        Specifying a key is mandatory. Runtime error U00003712 occurs if the key is missing.

        Default key if none is specified: N/A.

        Example:

        :SET&VARA_NAME# = "UC0.MAL.TEST#1_1.VARA_STATIC_USERNAME"

        :PUT_VAR&VARA_NAME#, &$USER#, "Mercury", "Venus", "Earth", "Mars", "Jupiter"

        :SET&VALUE# = GET_VAR(&VARA_NAME#, &$USER# ,1)

        :PRINT"Value: &Value#"

      • Host - each host name

        Specifying a key is optional.

        Default key if none is specified: The name of the Agent where the task is running.

      • Task - each task name

        Specifying a key is optional.

        Default key if none is specified: The name of the running executable object.

      • Workflow name - each workflow name

        Specifying a key is optional.

        Default key if none is specified: The name of the parent Workflow in which the task is running.

      • Workflow session - each workflow session

        Specifying a key is optional.

        Default key if none is specified: The RunID of the parent Workflow in which the task is running.

      • User - each user name

        Specifying a key is optional.

        Default key if none is specified: The name of the executing user.

        Example:

        :SET&VARA_NAME# = "UC0.MAL.TEST#1_1.VARA_STATIC_USERNAME"

        :PUT_VAR&VARA_NAME#, , "Mercury", "Venus", "Earth", "Mars", "Jupiter"

        :SET&VALUE# = GET_VAR(&VARA_NAME#, &$USER# ,1)

        :PRINT"Value: &Value#"

      • User session - each user session

        Specifying a key is optional

        Default key if none is specified: The RunID of the user session. The entry (row) corresponding to the user session will be deleted when the user session ends.

      Tip:

      The two scopes that are more useful are User session - each user session and Workflow session - each workflow session. With these two scopes, the default key that is used if none is specified is user session ID or the workflow run ID, respectively. And importantly, with these two scopes, the rows are deleted when the corresponding run ID is deactivated.

      Example:

      You want to store some information in a VARA object as long as a user is logged in, but remove the information when the user logs out. You can set the scope of the VARA object to User session - each user session, and put values into the VARA object without specifying a key as shown here:

      :SET&VARA_NAME# = "UC0.MAL.TEST#1_1.VARA_STATIC_USERSESSION"

      :PUT_VAR&VARA_NAME#, , "Mercury", "Venus", "Earth", "Mars", "Jupiter"

      :SET&VALUE# = GET_VAR(&VARA_NAME#, &$USER# ,1)

      :PRINT"Value: &Value#"

      The key used to write the values will be the session ID of the user who runs the script. In this example, running the script caused the following row to be added to the VARA object:

      • Key 1168010
      • Value 1 Mercury
      • Value 2 Venus
      • Value 3 Earth
      • Value 4 Mars
      • Value 5 Jupiter

      1168010 is the ID of the user session. These IDs are visible under Users in the Administration perspective. When the user logs out, this row is removed from the VARA object.

      The scope Workflow session - each workflow session works in a similar way. Any row written to such a VARA object (without a key specified) will be automatically removed as soon as the executing workflow is deactivated.

   2. All VARA objects have a Script Access section on their definition pages that determines the error handling when scripts read the VARA object. In this section you decide what happens if scripts access the VARA object and the key to which they refer is not available.

      You have the following options:

      • Return error

        The script ends abnormally and a runtime error message is displayed in the Messages console

      • Return initial values (Default)

        The script continues executing although the key is not available. No runtime error is displayed. The report contains an empty string indicating that no key has been found.

        Tip: Ensure that the keys of VARA objects always return a value if you want to use this option.

   3. Save the object.