Copy qualifier for subroutine parameters
Leaving out the Janus SOAP ULI, there are two types of parameters to 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 standard User Language 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:
- It is often useful to be able to update an Input parameter as if it were a local variable.
- 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, the Janus SOAP ULI 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 Janus SOAP 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.