EXEC VARA Objects

User-defined VARA objects are powerful dynamic execution tools. They are placeholders for values that they retrieve from different sources, depending on the type of VARA object. You assign VARAs to executable objects. When those executable objects are processed, the VARAs are replaced by their values. As a developer and object designer you create and use VARA objects in the attributes and scripts of executable objects. As an administrator user, you create VARA objects in Client 0 that can be used by other users in other Clients.

Use EXEC VARA objects as intermediaries that read and pass on the values returned by other executable objects. These values may affect the subsequent execution of objects or trigger the execution of objects. You store the readouts in the script variables that are defined in the EXEC VARA object. The VARA object itself has no input parameters.

The names of the parameters in the EXEC VARA object and in the PromptSet of the executable object that supplies the return codes must be identical.

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.

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

To Define an EXEC VARA Object

  1. In the Variable Settings section, specify how the VARA object is going to access the target system from which it retrieves the values.

    • Type is a read-only field. You determine the variable type when you create the object and cannot change it once the variable is defined.

    • In Executable object select the name of the executable object from which this EXEC VARA object reads the values. Type it or click the icon to open a dialog and search for it.

      Note: Schedule objects should not be used with EXEC VARA objects.

    • In Result variable enter the name of the script variable that will be used for the return value of the executable object

  2. In the Parameters section specify the list of parameters and variables that are available in the executable object. Their values can be either:

    • Direct values, such as 5342

    • Reference variables, such as &reftext#

      Trailing spaces at the end of values are removed when saving EXEC Variables

      You can include PromptSet variables here when using the dynamic reload feature for combo box prompts. When you use PromptSet variables in a dynamic VARA object, the Preview feature returns an error. This is because the PromptSet variables do not exist in the dynamic VARA object. However, the PromptSet variables will be resolved when objects including the PromptSet are executed.

    Treat these parameters as though they were PromptSet/read buffer values. When a VARA object calls the executable object, it uses :PUT_PROMPT_BUFFER to set the specified parameters. To read and use these values in the called executable object, you must use the :READ command. This command reads in the values of variables of the same names. The values depend on the parameters that are set in the calling EXEC Variable object.

    Important! It is not sufficient merely to define the variables on the Variables page under Variables & Prompts for the called executable object.

    For more information, see :PUT_READ_BUFFER, :PUT_PROMPT_BUFFER.

  3. In the Data & Formatting section you specify the data format of the value that is rendered by the VARA object. Do the following:

    • Data Type

      • For Text

        • Select Limit Text Length to set a limit to the length of the character string.

        • In Max. text length specify the maximum length. Possible values: 1 to 1024.

        • Select Force upper case if you want to convert the text of the first value column to upper case.

      • For Number

        Singed integer, possible values: any number from 0 to 2147483647.

        Default format: 16 digits

      • For Time

        The following formats are possible:

        • HHMMSS
        • HH:MM:SS
        • HHMM
        • HH:MM
        • MMSS
        • MM:SS

        Default format: HHMMSS

        The value for this data type must be a four or a six digit number. Decimal places are removed. Four-digit numbers are converted to hours and minutes.

        Example:

        Output Format: HH:MM:SS

        Value of the user or the data source: 1234, 1234.5, 123400, 12:34, 12:34:00

        Resulting variable value: 12:34:00

      • For Date

        The following formats are possible:

        • DD-MON-YYYY
        • DD-MON-RR
        • MM-DD-YYYY
        • YYYYMMDD
        • MMDDRR
        • DDMMRR
        • MM-DD-RR
        • MM/DD/RR
        • YYMMDD
        • YY.MM.DD
        • YY-MM-DD
        • YYYYMMDD
        • YYYY.MM.DD
        • YYYY-MM-DD
        • DDMMYY
        • DD.MM.YY
        • DD-MM-YY
        • DDMMYYYY
        • DD.MM.YYYY
        • DD-MM-YYYY
        • MMDDYY
        • MMDDYYYY
        • MM/DD/YY
        • MM/DD/YYYY

        Default format: YYMMDD

        Note: Some date formats include RR as a placeholder for the abbreviated year. Having both YY and RR accommodates different century-counting conventions, which are based on the two digits of the abbreviated year value.

        • YY - The current century applies for numbers from 00 to 80. The previous century applies for 81 - 99. 
        • RR - The current century applies for numbers from 00 to 49. The previous century applies for 50 - 99.

        Examples:

        • Date format DDMMYY and the resulting complete dates:

          010305 - corresponds to 01 March 2005
          010365 - corresponds to 01 March 2065
          010380 - corresponds to 01 March 2080
          010385 - corresponds to 01 March 1985

        • Date format DDMMRR and the resulting complete dates:

          010305 - corresponds to 01 March 2005
          010365 - corresponds to 01 March 1965
          010380 - corresponds to 01 March 1980
          010385 - corresponds to 01 March 1985

      • For Timestamp

        Possible formats:

          YYYYMMDDHH24MISS

          YYYY-MM-DD HH:MM:SS

        Default format: YYYY-MM-DD HH:MM:SS

        The value for this data type must be a four or a six digit number. Decimal places are removed. Four-digit numbers are converted to hours and minutes.

        Example:

        Output Format: YYYY-MM-DD HH:MM:SS
        Value of the user or the data source: 20110325 2201, 20110325 2201.5, 20110325 220100
        Resulting variable value: 2011-03-25 22:01:00

    • Set Min. value / Min. value and Set max. value / Max. value (All VARA types)

      Enforces a minimum/maximum value.

      Possible values for Number: max. 16 digits before and 16 digits after the decimal point

  4. 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.

  5. Click the Preview button to see a preview of the result values stored or transferred is displayed.

  6. To export the content of the preview table to a CSV file, click Export Table. All rows and column are exported. Use this function if you need to further process the content of the CSV file (paste it to a different application for further processing and so on).

  7. To copy one or more rows in the Preview table, select the Copy button. The selected rows are copied to the clipboard and you can paste them to a third party tool (Google, Sheets, Excel, text editor, and so on).

    Note: This function is available only if https is used on the Automic Web Interface .

  8. Save your changes.

To use an EXEC VARA Object in a precondition

  1. In an executable object, include code like the following:

    2. :SET &RET# = "Y"

  2. Create an EXEC variable and point it the executable object.
  3. Access the EXEC variable in either a:
    • Script with the following code, :SET &TEST# = GET_VAR(VARA.EXEC)
    • Prompt or precondition with, {VARA.EXEC}

To Use an EXEC VARA Object as a Data Sequence

If you want to use an EXEC variable to pass a list of values (e.g. for using the result in a PromptSet dropdown), do the following:

  • You can use data sequences for this purpose (:CREATE_PROCESS, ....).
  • The first line is always a header line.
  • You have to return the saved data sequence with SAVE_PROCESS().
  • The process must be saved directly in the object that is used for EXEC variable (Workflows with JOBS and JOBS created that saved and published the data sequence do not work).

In an executable object, in order to return a list of values, include something like the following:

:SET &HND# = CREATE_PROCESS(NEW)

! add the header line

:SET &CHECK# = PUT_PROCESS_LINE(&HND#, "Header A;Header B; Header C", ";")

!fill the process with another one!

:PROCESS &HND_SOURCE#

:   SET &CHECK# = PUT_PROCESS_LINE(&HND#, "Value1;Value 2; Value 3", ";")

:ENDPROCESS

! save process

:SET &RET# = SAVE_PROCESS(&HND#)

:PUBLISH &RET#,,TOP

:CLOSE_PROCESS(&HND#)

In the VARA.EXEC the executable object, point to the object with the content about. The return value would be set to &RET#.

See also: