Copy qualifier for subroutine parameters

There are two types of parameters to SOUL methods and complex subroutines:

• Input parameters
• Output parameters (also called InOut)

The default parameter type is Input.

If Output is specified for a parameter, references to the parameter in a method or complex subroutine directly reference the corresponding parameter in the Call statement. As a result, changes to the output parameter are immediately reflected in the Call variable, and vice versa.

For example, if a Common variable is passed to a User Language Complex subroutine, all changes to the Common variable also affect the parameter:

%common is float common ... %common = 7 call unusual(%common) ... subroutine unusual(%parm is float output) ... %common is float common ... %common = 11 print %parm

In this example, when the indicated call is made to Unusual, the subroutine would print 11, because %parm is an output parameter and thus a reference to the Call argument (%common). As modifying the Call argument affects the output parameter, so does modifying the output parameter affect the Call argument:

%common is float common ... %common = 7 call unusual(%common) ... subroutine unusual(%parm is float output) ... %common is float common ... %parm = 13 print %common

The print output here is 13, because setting %parm directly sets %common.

Unlike Output parameters, the Input parameters in non-OO complex subroutines and in method input parameters that are Arrays are not allowed to be updated. This is one of the two main problems with these Input parameters:

1. It is often useful to be able to update an Input parameter as if it were a local variable.
2. Sometimes Model 204 passes Input parameters as references to the Call argument. This can cause strange behavior if the Call argument changes (because the Call argument is a Common variable, for example).

To circumvent these problems, SOUL provides the Copy qualifier for complex subroutine and method array parameters. The Copy qualifier indicates that:

• A copy of the input parameter is always made.
• The copy of the input parameter is updateable.

The following example demonstrates a use of the Copy qualifier on a method parameter:

subroutine log(%message is string len 255 copy) %message = $time with ' ' with %message %displayJournal(%message) end subroutine print %message

The Print of %message would contain the called message without the time.

Implicitly, all SOUL non-array method input parameters are treated as if Copy were specified for them. This includes the input value for a property Set method: a copy is always made of the input value, and the input value variable may be updated inside the Set method.