Automic Workload Automation

 View Only
Expand all | Collapse all

:RSET scripting command

  • 1.  :RSET scripting command

    Posted Sep 02, 2024 12:22 PM
    Edited by Michael A. Lowry 29 days ago

    Today I learned the actual purpose of the :RSET scripting command.

    In restarts of a task, any variable set with :RSET will be set to the original value of that variable that was set in the initial run of the task. An example follows.

    Script

    :SET  &TIMESTAMP_SET#  = SYS_TIMESTAMP_PHYSICAL()
    :RSET &TIMESTAMP_RSET# = SYS_TIMESTAMP_PHYSICAL()
    :P "&&TIMESTAMP_SET#  : &TIMESTAMP_SET#"
    :P "&&TIMESTAMP_RSET# : &TIMESTAMP_RSET#"

     

    Original execution

    2024-09-02 14:25:32 - U00020237 The object variable '&TIMESTAMP_RSET#' in object: 'UC0.MAL.RSET_TESTING.SCRI', line: '00002' (RunID: '0006745735') has been created with the value '2024-09-02 14:25:32' by  using the command :RSET.
    2024-09-02 14:25:32 - U00020206 Variable '&TIMESTAMP_RSET#' was stored with value '2024-09-02 14:25:32'.
    2024-09-02 14:25:32 - U00020408 &TIMESTAMP_SET#  : 2024-09-02 14:25:32
    2024-09-02 14:25:32 - U00020408 &TIMESTAMP_RSET# : 2024-09-02 14:25:32

     

    Restart

    2024-09-02 14:26:23 - U00020206 Variable '&TIMESTAMP_RSET#' was stored with value '2024-09-02 14:25:32'.
    2024-09-02 14:26:23 - U00020206 Variable '&TIMESTAMP_RSET#' was stored with value '2024-09-02 14:25:32'.
    2024-09-02 14:26:23 - U00020408 &TIMESTAMP_SET#  : 2024-09-02 14:26:23
    2024-09-02 14:26:23 - U00020408 &TIMESTAMP_RSET# : 2024-09-02 14:25:32

    The documentation page for :RSET does not make this behavior very clear. Given that this behavior appears to be the raison d'être of the command, it should probably be spelled out more explicitly in the documentation.

    I also have ahttps://docs.automic.com/documentation/webhelp/english/ALL/components/AE/LATEST/DB%20Schema/db/_structure/HTML/MELD.html few questions.

    1. Does the R in :RSET stand for report, restart, or something else?
    2. The documentation states that :RSET writes the variable value to the activation report, and that in restarts, the original value is actually read from the report of the first run. Is this accurate? Does the AE read values set with :RSET from the RT table instead of from EV?
    3. The documentation states that :RSET can be used in the Process page of a workflow to generate an object variable. What does this mean? How does the variable differ from a script variable in this context? How does the behavior of :RSET differ from the behavior of :SET in this situation?
    4. How is :RSET intended to behave in restarts in situations wherein the original variable value is not available - for instance, when the original execution of the task was cancelled before it had a chance to run?

    If and when I get clear answers to these questions, I will update the document Variables in the Automation Engine.



  • 2.  RE: :RSET scripting command

    Posted Sep 04, 2024 05:28 AM
    Edited by Roney.Uba Sep 04, 2024 05:28 AM

    Hi Michael,

    about 3.

    With a script variable (SET), the scope is only the script, so the following does not work:

    Process: :SET &test# = 'A'
    Post Process: :PRINT &test#
    U00021719 Syntax error in object 'JOBS.WIN.NEW.2(2)', line '00004'. 'U01001308 Variable 'test#' has not yet been defined.'.
    U00011150 Post process of 'JOBS.WIN.NEW.2' ('0001361086') (Agent 'WINHOST') has ended abnormally. See next message

    With an object variable (RSET), the scope is the object, so the print in Post Process works:

    Process: :RSET &test# = 'A'
    Post Process: :PRINT &test#
    U00011002 Job 'JOBS.WIN.NEW.2' (RunID '0001361087') on Host 'WINHOST' ended normally. Remote ID=8468 

    This is similar to define an object variable under "Variables & Prompts"->"Variables". It can be used anywhere in the object.

    LG,
    Roney




  • 3.  RE: :RSET scripting command

    Posted Sep 04, 2024 06:46 AM
    Edited by Antony Beeston Sep 04, 2024 08:37 AM

    @Roney.Uba:

    I think I understand now. I made a diagram to explain this concept for my document Variables in the Automation Engine.

    hdg7lqj7rwo2.png

    When I created this document, I did not know that variables set with :RSET are equivalent to object variables set in the Variables page of the object. If I understand you correctly, then I will amend my description of the different variable types as follows:

    • Script variables: Variables not defined in the Variables page of an object, but set using the :SET command. This includes also arrays defined using the :DEFINE script command. Script variables may contain only text, and cannot span multiple lines. (Variables declared as arrays can contain multiple values.)
    • Object variables: Variables defined in the Variables page of an object, or via the :RSET, or :PSET command. Object variables defined in the Variables page can contain multi-line text.
    • Prompt set variables: Variables defined in a Prompt Set attached to an object, or in a :READ statement in the process page. The type of data they can contain depends on the prompt set element type. Once a prompt set variable has been set, its value is read-only and can no longer be changed.

    Is this correct?

    Next, a few comments about the documentation.

    The :RSET documentation states:

    Use :RSET to pass the value of a script variable from the Process page to the Post Process page of a Job

    This is correct but not complete, because :RSET can also be used in the pre-process page.

    Later, the :RSET documentation states:

    Use :RSET in the script of a Workflow object to generate an object variable. 

    The :PSET documentation similarly states:

    Use the :PSET statement to assign a value to an object variable. 

    However, the documentation page on Variables and VARA objects contradicts the :RSET and :PSET documentation, stating [emphasis mine]:

    You use script statements such as :SET, :PSET, or :RSET to set and declare script variables, and assign values to a script variable. 

    If :RSET and :PSET create object variables (as opposed to script variables), then the above statement is misleading.

    The documentation would be clearer if it consistently described the types of variables, the scope of each type, and the ways each type can be defined and set.

    A diagram like mine above would be a welcome addition too.

    Ping @Gabi Oberreiter, @Gabi Oberreiter



  • 4.  RE: :RSET scripting command

    Posted 22 days ago

    Hi Michael,

    yes, I believe the diagram summarizes it quite well.

    About "... :RSET are equivalent to object variables set in the Variables page" this is my personal interpretation when the Docu says "Use :RSET in the script of a Workflow object to generate an object variable.".
    If WPs and/or DB handles both the exactly same way, this only the developers know.

    Even if there are some "counter intuitive" situations, I like to think that the AE is just a big file with code inside and there is some logic trying to produce the desired result of the program functions we use.
    Each function (:SET, :RSET, :PSET, Object Variable, PromptSet, etc.) could be on some different place of the code, so yeah, it's not always intuitive and documenting all the logic details would not be the best thing.

    But it would be better to have a more consistent and intuitive behavior.

    With trace db=4 you would be able to see the inserts and updates when using these SET functions, and re-engineer what the WP is doing, but not sure if time invested would payoff.

    LG,
    Roney




  • 5.  RE: :RSET scripting command

    Posted 29 days ago
    Edited by Michael A. Lowry 29 days ago

    I opened a case with Broadcom about this. Hopefully they'll clear up some of the confusion in a future revision to the documentation.



  • 6.  RE: :RSET scripting command

    Posted 29 days ago

    Hi @Michael A. Lowry

    Seems like RSET is more complex than I tought. Well... possibly I need to take a nap to get a use-case for this. 

    Example:
    :RSET &TEST# = "Initial"
    :PRINT &TEST#
    :SET &TEST# = SYS_TIMESTAMP_PHYSICAL()
    :PRINT &TEST#
    First execution:
    Initial
    2024-09-11 13:40:41    <= This value is stored as RSET value, even tough the value-change caused by :SET does not show up in the report

    First restart:
    2024-09-11 13:40:41    <= RSET of "initial" is ignored, instead, &TEST# receives the stored value 
    2024-09-11 13:40:50   <= SET overwrites &TEST#, but only for the current execution
    Second restart:
    2024-09-11 13:40:41    <= Here we go again with the timestamp from the first execution
    2024-09-11 13:41:01     <= SET overwrites again, with no sustainable success


    ------------------------------
    ☎️ Swisscom Automation Engineer & 🧙 PE Membership Creator

    Automic Kurse, Tutorials, Tools und mehr auf:
    https://membership.philippelmer.com/
    Zwei Wochen kostenlos testen!
    ------------------------------



  • 7.  RE: :RSET scripting command

    Posted 29 days ago
    Edited by Michael A. Lowry 29 days ago

    Wow, that's probably not how it's supposed to work.

    Update 2024.09.12 9:54 CEST:

    @Joel Wiesmann, I did some more thinking about it. 

    It seems :RSET is not just setting the value, but also permanently declaring the variable as a special :RSET-variable. I don't see a flag for this in the schema description for the EV table, so maybe the AE truly reads this information from RT.

    The logic appears to be:

    If :RSET is used to set a variable anywhere in the pre-process or process page, then the final value of this variable at the end of the first execution of the object is stored and used in any subsequent restarts, even if the value was altered after the initial :RSET, e.g., by :SET or :PSET.



  • 8.  RE: :RSET scripting command

    Posted 29 days ago
    Edited by Juergen Lechner 29 days ago

    Hi,

    define "supposed"! ;-)

    Let's look at the example

    Example:
    :RSET &TEST# = "Initial"
    :PRINT &TEST#
    :SET &TEST# = SYS_TIMESTAMP_PHYSICAL()
    :PRINT &TEST#
    First execution:
    Initial
    --> No value found. Set to "initial".
    2024-09-11 13:40:41    <= This value is stored as RSET value, even tough the value-change caused by :SET does not show up in the report
    --> Last value counts AND is stored.
    First restart:
    2024-09-11 13:40:41    <= RSET of "initial" is ignored, instead, &TEST# receives the stored value 
    --> Stored value found. Assignment is ignored.
    2024-09-11 13:40:50   <= SET overwrites &TEST#, but only for the current execution
    --> Value changed. But nothing is stored since we are in a rerunning task.
    Second restart:
    2024-09-11 13:40:41    <= Here we go again with the timestamp from the first execution
    --> Stored value found. Assignment is ignored.
    2024-09-11 13:41:01     <= SET overwrites again, with no sustainable success
    --> Value changed. But nothing is stored since we are in a rerunning task.
    So IMHO a conistent behaviour. The documentation shows three purposes of the command. The first one of them is

    "Use stored values from the activation report"

    So I assume that this is the top priority in the execution of code behind the command itself. This explains why it does not matter wether you restart the original task or a restarted one. It will always end in the "stored values from the ORIGINAL activation report".
    This is not obvious from the documentation. And I would not dare to write an explanation that does not automatically scare away half of the readers... :-D

    And the example is rather... How do we say "verkopft" in English??? ;-) Why should you put a SET behind a RSET? I would have persisted the variable with a RSET at the end of the code.

    Edit: BTW. Nice diagram!

    Regards,
    Juergen


    ------------------------------
    Juergen Lechner
    Managing Consultant
    setis GmbH
    Germany
    ------------------------------



  • 9.  RE: :RSET scripting command

    Posted 29 days ago
    Edited by Michael A. Lowry 29 days ago

    Yeah, I guess it's the intended behavior. It's just a bit counterintuitive. See my updated comment above.



  • 10.  RE: :RSET scripting command

    Posted 29 days ago

    counterintuitive???

    Yessss! :-D



    ------------------------------
    Juergen Lechner
    Managing Consultant
    setis GmbH
    Germany
    ------------------------------



  • 11.  RE: :RSET scripting command

    Posted 27 days ago

    "Use stored values from the activation report"

    Activation report of first run:

    2024-09-13 15:50:11 - U00020237 The object variable '&TEST#' in object: 'SCRI.NEW.1', line: '00001' (RunID: '0002453868') has been created with the value 'Initial' by  using the command :RSET.
    2024-09-13 15:50:12 - U00020206 Variable '&TEST#' was stored with value 'Initial'.
    2024-09-13 15:50:12 - U00020408 Initial
    2024-09-13 15:50:12 - U00020408 2024-09-13 14:50:12

    The RSET command does show up in the activation report, but not the SET - value change.

    So if the documentation would be correct, the value after a restart would be "initial", because that's the value assignment that shows up in the report.

    Activation report of restart:

    2024-09-13 15:51:44 - U00020206 Variable '&TEST#' was stored with value '2024-09-13 14:50:12'.
    2024-09-13 15:51:44 - U00020206 Variable '&TEST#' was stored with value '2024-09-13 14:50:12'.
    2024-09-13 15:51:44 - U00020408 2024-09-13 14:50:12
    2024-09-13 15:51:44 - U00020408 2024-09-13 14:51:44
    2024-09-13 15:51:44 - U00020206 Variable '&TEST#' was stored with value '2024-09-13 14:51:44'.

    ... or am I missing something?



    ------------------------------
    ☎️ Swisscom Automation Engineer & 🧙 PE Membership Creator

    Automic Kurse, Tutorials, Tools und mehr auf:
    https://membership.philippelmer.com/
    Zwei Wochen kostenlos testen!
    ------------------------------



  • 12.  RE: :RSET scripting command

    Posted 27 days ago

    Hi,

    yes and no. By using the SET command after the RSET the system gets a little bit confused. Nevertheless the last assigned value in the first run defines the stored and furthermore used value. One could discuss if this is correct. But the test testifies my assumption. :-D

    Regards,
    Juergen



    ------------------------------
    Juergen Lechner
    Managing Consultant
    setis GmbH
    Germany
    ------------------------------



  • 13.  RE: :RSET scripting command

    Posted 25 days ago
    Edited by Michael A. Lowry 24 days ago

    @Joel Wiesmann & @Juergen Lechner:

    With the following SQL query (Oracle), you can list all of the RT lines pertaining to :RSET scripting commands.

    WITH RT_MESSAGE_INSERTS AS (
    SELECT RT_AH_IDNR, RT_TYPE, RT_LNR, RT_TIMESTAMP, RT_MSGNR, RT_CONTENT,
    SUBSTR(RT_MSGINSERT, 1, INSTR(RT_MSGINSERT, '|', 1, 1) - 1) MSG_INSERT_1,
    SUBSTR(RT_MSGINSERT,INSTR(RT_MSGINSERT,'|', 1,1) +1, INSTR(RT_MSGINSERT,'|', 1,2) - INSTR(RT_MSGINSERT,'|', 1,1) -1) MSG_INSERT_2,
    SUBSTR(RT_MSGINSERT,INSTR(RT_MSGINSERT,'|', 1,2) +1, INSTR(RT_MSGINSERT,'|', 1,3) - INSTR(RT_MSGINSERT,'|', 1,2) -1) MSG_INSERT_3,
    SUBSTR(RT_MSGINSERT,INSTR(RT_MSGINSERT,'|', 1,3) +1, INSTR(RT_MSGINSERT,'|', 1,4) - INSTR(RT_MSGINSERT,'|', 1,3) -1) MSG_INSERT_4,
    SUBSTR(RT_MSGINSERT,INSTR(RT_MSGINSERT,'|', 1,4) +1, INSTR(RT_MSGINSERT,'|', 1,5) - INSTR(RT_MSGINSERT,'|', 1,4) -1) MSG_INSERT_5,
    SUBSTR(RT_MSGINSERT,INSTR(RT_MSGINSERT,'|', 1,5) +1, INSTR(RT_MSGINSERT,'|', 1,6) - INSTR(RT_MSGINSERT,'|', 1,5) -1) MSG_INSERT_6,
    SUBSTR(RT_MSGINSERT,INSTR(RT_MSGINSERT,'|', 1,6) +1) MSG_INSERT_7
    FROM RT
    )
    SELECT * FROM RT_MESSAGE_INSERTS
    WHERE RT_TYPE = 'ACT'
    AND RT_MSGNR = 00020237
    AND MSG_INSERT_7 = 'RSET'

    You can identify all of the :RSET-variables associated with a particular task using a query like the one below.

    SELECT SUBSTR(RT_MSGINSERT,INSTR(RT_MSGINSERT,'|', 1,4) +1, INSTR(RT_MSGINSERT,'|', 1,5) - INSTR(RT_MSGINSERT,'|', 1,4) -1)
    FROM RT
    WHERE SUBSTR(RT_MSGINSERT,INSTR(RT_MSGINSERT,'|', 1,6) +1) = 'RSET'
    AND RT_AH_IDNR = original_run_ID

    I do not believe the AE looks at RT records pertaining to the original run though. This is unnecessary and inconsistent with observed behavior. I also do not believe :RSET-variables are stored differently in the DB. The difference in behavior arises solely from how the AE interprets :RSET commands during task activation.

    My guess is that it works like this:

    When the Automation Engine evaluates an :RSET statement, if the task is a restart, the AE ignores the value after the equals sign, and looks up the value set in the original run.

    SELECT EV_VALUE value
    FROM EV
    WHERE EV_VNAME = variable_name
    AND EV_AH_IDNR = original_run_ID
    UNION ALL
    SELECT AV_VALUE value
    FROM AV
    WHERE AV_VNAME = variable_name
    AND AV_AH_IDNR = original_run_ID

    The final value set in the task may not be the initial value set by :RSET, because it can have been modified subsequent to the :RSET.

    The above is at least consistent with observed behavior.



  • 14.  RE: :RSET scripting command

    Posted 24 days ago

    Hi,

    that's also my assumption. As I have written above

    --> Stored value found. Assignment is ignored.

    Thanks for the SQL!

    Regards,
    Juergen



    ------------------------------
    Juergen Lechner
    Managing Consultant
    setis GmbH
    Germany
    ------------------------------