Automic Workload Automation

 View Only
  • 1.  &VARIABLE#-style variables in the AE

    Posted Jan 30, 2018 04:55 AM
    I have been trying to learn a bit more about the different types of &VARIABLE#-style variables in the AE, and in particular, where and how they can be set, and where they are inherited.

    As anyone who has worked with the Automation Engine for a while will already know, the product and its documentation use the term variable to refer to multiple quite different things. (I have discussed the ambiguous terminology at length elsewhere.) For the purposes of this discussion, I am focusing only on the types of variables that take the form &VARIABLE#. These include several different types:
    • Script variables: Variables not defined in the Variablesof an object, but set using the :SET script command. This includes alsoarraysdefined using the :DEFINE script command.
    • Object variables: Variables defined in the Variablesof an object.
    • Prompt set variables: Variables defined in aPrompt Setof an object.
    In addition, variables can be defined at different levels. The level at which a variable is defined determines where the values of these variables can be read. (The Inherit from parent option in workflows and schedules also affects variable inheritance.)

    My main question today concerns the level at which a variable is set.

    When a script command is run to set the value of a variables, what determines at what level the variable is set?

    From recent experience, I surmise that the following two actions are equivalent:
    • Running :PSET in a workflow or its immediate child tasks, regardless of whether the variable is defined in the workflow’s Variables.
    • Running :SET in the workflow or its immediate child tasks, only if the variable is defined in the workflow’s Variables.
    Is this correct?


  • 2.  &VARIABLE#-style variables in the AE

    Posted Feb 01, 2018 11:42 AM

    The documentation page on object and prompt set variables includes more details about this process, as well as a few examples. See this statement under Example 3, Task 4:

    The script element :PSET is used to pass the object variable &VAR3#  on to the workflow. It is then available for subsequent workflow tasks.

    Based on this statement and some quick tests, I believe the answer to my question above is no. Running :PSET in a child task of a workflow sets the variable in the parent workflow, and this value will be available to other tasks in the workflow that run later. However, running :SET in the child task sets the variable only in that task, regardless of whether the variable is also defined in the parent workflow, and regardless of whether the variable has been set in the parent workflow.



  • 3.  &VARIABLE#-style variables in the AE

    Posted Feb 01, 2018 12:14 PM
    We only started using this product in 2013, and we decided to not use PSET unless there was a compelling reason to.  It seemed like overkill to expose variables to a wider audience than necessary, and we have not used it.

    There are three script phases; pre-process, process, and post-process.  The first two (pre-process and process) share script variables, so you can SET one in the pre-process and reference it in process.  But if you want either of the first two to expose a variable to the post-process phase, you must define it as an object variable. 

    If you want script data to be exposed to the workflow, then define it as an object variable to that workflow.

    I suspect that when one uses PSET, you would not need to define the object variables.  Consequently someone reviewing the solution would not know which PSET variables were being used by later steps and which PSET variables were not being used by later steps.


  • 4.  &VARIABLE#-style variables in the AE

    Posted Feb 01, 2018 12:25 PM
    I don't have many real life examples for RSET but from what I remember and initial testing it looks like this can be used to set a script variable in the pre-process or process that can be referenced in the post process.

    edit - Looks like it actually does create an object variable for that specific task. Appears the documentation might be a bit off for that.


  • 5.  &VARIABLE#-style variables in the AE

    Posted Feb 02, 2018 04:42 AM
    From a few quick tests, I surmise that :RSET is intended for situations where you want to make a variable that is set in either the pre-process or process tab available in the post-process tab, without having to set the value at the workflow level (using :PSET).


  • 6.  &VARIABLE#-style variables in the AE

    Posted Feb 02, 2018 05:42 AM

    Here’s an overview, based on my understanding.

    In the example below, if you run the :SET, :RSET, or :PSET command in the pre-process or process tab of UC0.JOB1, the level at which the variable/value will be accessible depends on the command used.
    hdg7lqj7rwo2.png

    • :SET— The variable is accessibleonly from the pre-process and process tab ofUC0.JOB1.
    • :RSET— The variable is accessible from thewhole job UC0.JOB1, including the post-process tab.
    • :PSET— The variable is accessible from thewhole workflow UC0.WF1, including any other child tasks that run afterUC0.JOB1has completed (contingent upon inheritance settings).


  • 7.  &VARIABLE#-style variables in the AE

    Posted Feb 02, 2018 08:45 AM

    Next, I’d like to tackle the topic of the custom of terminating variable names with a symbol like ‘#’. This is a topic that often confuses new users, and it is not fully explained in the documentation.

    In the Automation Engine documentation, virtually all variable names mentioned in examples are terminated with a hash symbol (#). E.g., &CLIENT# or &HOST#. Pre-defined variables for system and object attributes are also all terminated with a # symbol. E.g., &$SYSTEM# or &$RUNID#.

    At Automic, and among customers too, it is standard practice to terminate AE variable names with a single # character. This is not a hard and fast requirement, but it is a recommended convention. Why? A basic limitation of the Automation Engine:

    Variable names may not be substrings of other variable names.

    This means that if you define the variable called &APP, you cannot also define a variable called &APP_ID. This is because the former is a substring of the latter. If you try to save an object wherein two such variables are defined, message U01001312 will appear:

    U01001312 Variable name 'APP_ID' is not allowed. A variable with the name 'APP' already exists.

    Terminating the variable names with a symbol such as # gets around this limitation. A termination character at the end of variable names ensures that the names do not overlap¹. E.g., &APP# is not a substring of &APP_ID#. If you do not terminate variable names, you must do more work name them in such a way as to ensure that the names do not overlap. Terminating variable names makes scripting easier, because you do not have to work to prevent variable name overlaps; you must simply ensure name uniqueness.

    Any character that is allowed in variable names² may be used as a termination character. It is merely convention to use the # character. For this convention to be most effective, you must follow two rules:

    • Use the same termination character consistently, in all variable names. Again, it is a common convention to terminate variable names with the#character.
    • Do not use the termination character in the middle of variable names. Use it only at the end.


    Notes:
    1. If you examine the AE scripts used internally in the Automation Engine, you will find many variables names that are not terminated. For example, here is an excerpt from the UNIX header include object from client 0 (HEADER.UNIX):

    :set &UC_EXVER      = get_var(UC_EX_VERSION)
    :set &UC_MANDANT    = SYS_ACT_CLIENT
    :set &UC_REALNR     = SYS_ACT_RESTART_ME_NR
    :set &UC_NAME       = SYS_ACT_JOBNAME
    :set &UC_JOBMD      = get_var(UC_EX_JOB_MD)
    :set &UC_IP_ADDR    = get_var(UC_EX_IP_ADDR)
    :set &UC_IP_PORT    = get_var(UC_EX_IP_PORT)
    :set &UC_UNIX_SHELL = get_att(UNIX_SHELL)

    Note that although these variable names are not terminated, none of them is a substring of any other.
    2. The characters allowed in variable names are A-Z, a-z, 0-9, _, $, @, §, and #. (See this thread for details.)



  • 8.  Re: &VARIABLE#-style variables in the AE

    Posted Mar 13, 2019 09:33 AM

    additional comment about PSET.  It is useful in a sense to make a variable pseudo-global in a workflow.  However, use caution as the "P" in "PSET" means "Parent" object.  We discovered that this includes other containers such as "SCHEDULES", and we learned the hard way when tasks in our main schedule used PSET (in a PROCESS tab of a workflow, for example) and propogated a value into a variable used independently by other objects run from the schedule.  It took a bit of detective work to track that down -- worth knowing.