Open topic with navigation

BYREF Operator

InstallShield 2013 » InstallScript Language Reference

By default, the parameters of a user-defined function are passed by value; that is, a copy of the data specified by each parameter is passed to the function. Because the function operates on a copy, the original data cannot be changed by the function.

Note: There is one exception: By default, string variables passed to DLL functions are passed by reference, so the value of the variable can be changed by the function.

When you want a user-defined function to operate directly on a variable it receives in a parameter rather than on a copy of that variable, you must specify the BYREF operator with the parameter type declaration in the function prototype, as shown below:

   prototype StrInvert( BYREF STRING );

The BYREF operator indicates that the parameter is to be passed by reference—that is, the actual variable is to be passed to the function, and any changes made to that variable will be visible to the caller when the function returns. Parameters that are passed by reference are often referred to as variable parameters because they require a variable. Constants and literals cannot be passed by reference.

Using BYREF With Multiple Parameters

When a user-defined function has more than one parameter, the BYREF operator must be specified with each variable parameter. In the example below, the first and third parameters are passed by reference and the second parameter is passed by value:

   prototype StrChangeChar( BYREF STRING, CHAR, BYREF BOOL);

Limitations

User-defined structure members cannot be passed by reference. Attempting to do so results in a compiler error. Instead, you must pass a pointer to the entire structure by reference and then use the structure pointer operator (->) to access or modify the data elements of the structure.

An autosized string variable that is passed by reference to a function will not be autosized within the called function. If the function attempts to assign a value whose length is greater than the current size of that parameter, run-time error 401 occurs. To avoid this error, declare strings with a specific size when they are to be passed by reference to a function.

See Also

Declaring Functions

Returning a Value from a Function

String Size and Autosize