Topic group Related topics Example

Assigns data passed from a calling routine to private variables.

Syntax

PARAMETERS <parameter list>

<parameter list>

The memory variable names to assign, separated by commas.

Description

There are three ways to access values passed to program or function:

  1. Variable names may be declared on the FUNCTION (or PROCEDURE) line in parentheses. These variables are local to that routine.

Passed values may be assigned to variables only once in a routine. You may either create local variables on the FUNCTION line or use the PARAMETERS statement, and you may only use the PARAMETERS statement once.

The ARGVECTOR( ) function returns copies of the passed values. It has no effect on, nor is it affected by, the other two techniques.

Parameters passed to the main procedure of a dBASE Plus application .exe, such as from a DOS command line, will be received as character strings.

For example:

someApp abcd efgh 

In someApp.prg,

PARAMETERS var1, var2 

var1 will be received as, "abcd", and var2 as, "efgh".

To pass a string containing an embedded space, use quotes around the string. Such as:

someApp "abcd efgh" ijk 

var1 will be received as, "abcd efgh", and var2 as, "ijk".

In general, local variables are preferred because they cannot be accidentally overwritten by a lower-level routine. Reasons to use PARAMETERS instead include:

Using values passed to a program file: a program file may contain statements that are not part of a function or class, like the statements in the Header of a WFM file. Because there is no FUNCTION or PROCEDURE line, there is no place to declare local parameters. A PARAMETERS statement must be used instead.

You specifically want the parameters to be private, so they can for example be modified by a lower-level routine, or be used in a macro substitution.

For more information on the difference between local and private variable scope, see LOCAL.

If you specify more variables in the <parameter list> than values passed to the routine, the extra variables assume a value of false. If you specify fewer variables, the extra values do not get assigned.

The PARAMETERS statement should be at or near the top of the routine. This is good programming style; there is no rule requiring this.

Passing mechanisms

There are two ways to pass parameters, by reference or by value. This section uses the term "variable" to refer to both memory variables and properties.

If you pass variables by reference, the called function has direct access to the variable. Its actions can change (overwrite) the value in that variable. Pass variables by reference if you want the called function to manipulate the values stored in the variables it receives as parameters.

If you pass variables by value, the called function gets a copy of the value contained in the variable. Its actions can't change the contents of the variable itself. Pass variables by value if you want the called function to use the values in the variables without changing their values—on purpose or by accident—in the calling subroutine.

The following rules apply to parameter passing mechanisms:

Literal values (like 7) and calculated expression values (like xVar + 3) must be passed by value—there is no reference for the called function to manipulate, nor is there any way to tell that the parameter has been changed.

Memory variables and properties may be passed by reference or by value. The default is pass-by-reference.

The scope declaration of a variable (local, private, etc.) does not have any effect on whether the variable is passed by reference or by value. The scope declaration protects the name of the variable. That name is used inside the calling routine; the called function assigns its own name (which is often different but sometimes happens to be the same) to the parameter, making the scope declaration irrelevant.

To pass a variable or property by value, enclose it in parentheses when you pass it.

Passing objects

Because an object reference is itself a reference, passing one as a parameter is a bit more complicated:

Passing a variable (or property) that contains an object reference by reference means that you can change the contents of that variable, so that it points to another object, or contains any other value.

Even if you pass an object reference by value, you can access that object, and change any of its properties. This is because the value of a object reference is still a reference to that object.

Passing this and form

When passing the special object references this and form as parameters to the method of another object, they must be enclosed in parentheses to be passed by value. If not, the value of the this and form parameters take on the corresponding values for the target object, and no longer refer to the calling objects.

Passing fields in XBase DML

With the XBase DML, fields are accessed directly by name (instead of a Field object’s value property). When used as parameters, they are always passed by value, so the called function can't change their contents.

There are two ways to alter the contents of an XBase field with a function:

Store its contents to a memory variable and call the function with that variable. When control returns to the calling routine, REPLACE the field contents with the memory variable contents.

Design the function to accept a field name. Pass the name of the field, and have the function REPLACE the contents of the named field, using macro substitution to convert the field name to a field reference.

Protecting parameters from change

Because the decision whether to pass by reference or by value is made by the caller, the called function doesn’t know whether it’s safe to modify the parameter. It’s a good idea to copy parameters to work variables and to use those variables instead if their values are going to be changed, unless the intent of the function is specifically to modify the parameters.