Evaluation Method ByReference or ByValue

[LDBM]

In the Stimulus Profile Editor  (VS2011), Parameters can be either selected with Evaluation Method being "ByReference" or "byValue". What does this mean and where is there any documentation relative to this?  

L.

[Jarrod_S. · Accepted solution]

I am looking into the documentation side of your question, but for now I can talk about what those terms mean.

If a parameter has the byValue evaluation method selected, then when the sequence sequence gets called as a subsequence, it will get a copy of the variable value mapped to that parameter. This means that if the calling sequence updates the mapped variable value while the subsequence is running (say from another task in a MultiTask structure), the parameter value in the subsequence will not be affected, because it is just a copy of the original variable value. Similarly, if the subsequence modifies the parameter value while the subsequence is running, this does not affect the value of the mapped variable in the calling sequence.

If a parameter has the byReference evaluation method selected, then it will directly operate on the mapped variable value that is passed in from the calling sequence. So if the subsequence updates the parameter value, the mapped variable in the calling sequence also gets updated. Conversely if the calling sequence updates the the mapped variable value while the subsequence is running from another task, the parameter value in the subsequence will change as well.

Because of this, if you have a parameter that you want to map to a system definition channel, it should probably always be byReference. This means that as the system definition channel value changes, the parameter value changes as well, and when the sequence updates the parameter, the system definition channel is updated too. For instance, the Ramp sequence and the SineWave sequence specify that both the RampOut and SineWaveOut parameters are byReference, so that as the sequence runs and plays back data onto these variables, any channel mapped to these variables will also get updated.

In general, you can probably almost always just leave a parameter as byReference and not think about it. Most of the time that will naturally fit with what you would expect would happen. The only caveat with byReference parameters is that in order to map a variable to it from the calling sequence, the variable in the calling sequence must be the exact same data type as the parameter. So you can't map an I32 variable in a sequence to a double byReference parameter in a subsequence being called. You can do this with a byValue parameter. Because the subsequence in that case is just getting a copy of the value anyway, it is okay for it to coerce this copy to the parameter's own data type.

We can take a look at a simple example. Imagine you have a sequence Foo that has a double parameter x. All Foo does is increment x 10 times.

• Foo
• Setup
• Main
• For i in [0, 10)
• x = x + 1
• CleanUp

Imagine you have a calling sequence Bar with a local variable z that calls Foo.

• Bar
• Setup
•  z = 0
• Main
• Foo(z)
• CleanUp

If the x parameter in Foo is byReference, then after calling Foo, the value of z in Bar is 10, because Foo was operating directly on the value of z. If on the other hand the parameter x in Foo was byValue, then the value of z after calling Foo is still 0, because Foo was just incrementing a copy of the value of z, not z itself.

[LDBM]

Haaa... I see. Ok, Thanks Jarrod.

One general  issue we are having at the moment, is that the Help File is really not in depth enough, just describing how to open this and that... So really understanding how all this fits together is very time consuming.

[Jarrod_S.]

I filed CAR 317950 regarding the documentation of this issue. We will look into it. Thanks for reporting this.

Please post any questions you have and we'll do our best to help out!