Finally diving into Subroutines - Is this how it works?

[alltiagocom]

I'm finally seeing how subroutines can improve some macros I have so I decided to sit and do some tests. I gotta be honest: it was a bit confusing (unfortunately the Wiki pages don't help a lot of the times without real examples and images...), but here's what I got so far (I will be as clear as possible, and include images, in case other people in the future struggle with the same thing). If you see something wrong with my post, please feel free to share it.

How can subroutines be used and some of their benefits?

For those new to subroutines such as myself, what subroutines can help with is to create a "template" that can be used by 1 or more macros (I would say that more macros is when it actually makes more sense, even though I know it's not limited to that scenario, of course), similar to how we use variables to avoid editing multiple things when we can just update a single variable value and everything else that depends on that variable is now updated.

So in the case of subroutines, here's an example:
I have the calculation a+b=c
I can set that as a subroutine, so all I'm creating is a "template" that uses that formula.
Now I can have several macros that use that same calculation, but where I can just set different values to a and b on each macro. For example:
Macro 1
variable a = 2
variable b = 3

Macro 2
variable a = 34
variable b = 20

Macro 1 and Macro 2 both run the same subroutine (e.g. SUB Calculation) and perform the same calculation a+b=c, but each macro returns a different c, which then can be saved as a variable Local__calcSum, for example.

How to create and use a subroutine?

1. Create the subroutine (e.g. SUB Calculation) and set the trigger to Subroutine Trigger when clicking the green + button.
   

2. Define what comes from the main macro (e.g. Main Macro) to be processed in the subroutine. For example, this subroutine will perform a simple calculation and uses 3 variables that use values coming from my Main Macro:
   

3. Add the calculation itself using those variables:
   

4. Then use the Return Result action to send the result from the calculation back to Main Macro
   

5. The full subroutine SUB Calculation will look like this:
   

That's done and whatever value I get from that calculation is now automatically being sent to Main Macro

Now let's create the Main Macro:

1. Add the Execute Subroutine action, pick the subroutine (the list will only be populated with macros that are set to be triggered by "Subroutine Trigger" - the first step I mention at the top)
   

The value that comes from the subroutine, in the Return Result action, will be sent to the Save result to field (le'ts say the result of that calculation is 26, because of the values I set to 2, 20, and 4) and it will be saved to the variable Local__calc.

2. Do whatever needs to be done with that value, in this case I'm just displaying it in a window:
   

And when I run Main Macro I get this:

So the full Main Macro is this:

NOTE: Subroutines don't always need to return a result. They can just receive values/info/parameters from the main macros and just process that, without the main macros depending on a result. I just used it that way in this post, because it seems easier to understand how they can both interact with each other.

---

I hope this is all correct and if so, I hope it helps others who struggle with the same thing as I did.
If you see something that's not correct, please let me know so I can learn more about it and also update this topic with accurate information.

[kevinb]

@alltiagocom

unfortunately the Wiki pages don't help a lot of the times without real examples and images...),

I found the Wiki's page on subroutines quite confusing but the concept is very simple.

To tie together some posts, here are a couple of mine on the subject of subroutines. I've added some headers so you can see at a glance what they are about.

Q: What does a subroutine offer that you can't do just by having one macro call another?

A: A subroutine is a type of macro that provides an easy way to receive and return values with another macro directly, without always needing to use variables.

I also touch upon the general concept of subroutines beyond KM.

Execute next macro in group

Before V. 10 of KM, there were no subroutines, but you could call one macro from another macro, using the Execute a Macro action. And of course you can still do this, and it may often be all you need. So what does a subroutine offer that you can't do just by having one macro call another? The KM Wiki explains that when one macro calls (executes) another macro, there is a limitation: The Execute Macro action allows you to execute another macro... though without any ability to pass parameters …

Q: Could you give a simple example of a subroutine in use with a macro?

A: Yes....

Problems with getting a macro to repeat itself

So here is the start of a super-advanced (hmm) calculator macro called my_calculator: [1 calc] my_calculator executes a subroutine called my_doubler, and passes it the number 10. Here is the subroutine my_doubler, which expects to receive a parameter value, which will be used for the local variable "number". [2 doubler] my_doubler performs the complex calculation, and returns the result to my_calculator. my_calculator brings up an alert with the answer. I'm sure it's obvio…

[kevinb]

@kevinb

I found the Wiki's page on subroutines quite confusing but the concept is very simple.

The pages for Subroutines, the Execute a Subroutine Action and the Execute a Macro Action do of course have a lot of useful information but the dense presentation forming a reference work does not make the Wiki an easy introduction to what is in fact a very simple concept. Also, I believe that the shorthand term "sub-macro" adds to the jargon unnecessarily!

The Wiki's information does become clear once one has a handle on the simple core idea of subroutines and their implementation in KM. They are actually easy to use!

[Nige_S]

@alltiagocom

If you see something that's not correct...

Picture for step 4 is wrong (you've repeated the one for step 3). I know -- a bit nit-picky

[alltiagocom]

@Nige_S

a bit nit-picky

Not at all. Thanks for pointing that out. Fixed

[alltiagocom]

Thank you for the extra info and links.

Here's something I would like to know:
When you use Execute a Macro with parameter, that's the same as when you use a subroutine, where the subroutine doesn't have the "Return a value" selected OR when that option is selected but there's no "Return Result" action, right?

So basically we are sending a certain parameter from the main macro to the "sub macro", the same way we do when we use a subroutine with 2 exceptions:
a) Using Execute a Macro seems to be limited to just sending 1 parameter (unless I'm missing something?)
b) We can only send one parameter, we can't receive the result from the "sub-macro"

Is this true?

[alltiagocom]

Ok so I was testing the "Execute Macro" with parameter, but it seems I haven't understood it yet... I thought I could use a variable as a parameter, but it doesn't seem to work?

Then what is a "parameter"? Unfortunately, the wiki page is not very clear about this... again.

[griffman]

You can, but the variable is passed in as becomes the %TriggerValue% token:

-rob.

[alltiagocom]

I think I'm still a bit confused, because if you check this page, you can see that the parameter being used was %ExecutingMacro% and then in the sub-macro, %Trigger% was indeed used, like you did, but so was %ExecutingMacro%

In your image you have the Execute Subroutine, but I guess that's just because it's part of the group, not really necessary for this particular case? Just trying to understand if there's something else there?

[griffman]

@alltiagocom

In you image you have the Execute Subroutine, but I guess that's just because it's part of the group, not really necessary for this particular case? Just trying to understand if there's something else there?

Yea, not related, that's just the sub I run after the execute macro action—lazy screenshotting :).

-rob.

[alltiagocom]

@griffman

Yea, not related, that's just the sub I run after the execute macro action—lazy screenshotting :).

Ok great! Fewer things to be added to the confusion... haha

[alltiagocom]

@griffman I'm gonna start a new topic just for this subject to make this "subroutine" topic focused on just that. If you don't mind continuing the conversation there?

[Nige_S]

@alltiagocom

I think I'm still a bit confused...

I think what it is trying to show is that

• You can pass a single parameter to the sub-macro
• That parameter is accessed via the sub-macro's %TriggerValue% token
• When you execute it in this way, the sub-macro's %ExecutingMacro% token evaluates to the name of calling macro, not that of the sub

It's a bit more obvious if you reproduce the macros on that page, then run "Execute Macro with Parameter" which gives:

But if you execute "Who Call Me?" on its own, via the Editor's "Run" button:

[alltiagocom]

Check my new topic on this:

How does "Execute a Macro with parameter" work?

I never used "With Parameter" before, or Instance variables, but it seems to me that they behave "kinda" the same way? So I am able to set a value to the "With Parameter" field in "Execute a Macro" and then in the sub-macro I just set the %TriggerValue% to use that value, for example my main macro: [image] My sub-macro: [image] My notification when I run the main macro: [image] But according to what I read about Instance variables, it seems that this can be done as well. The only "disadva…