WD: Passing Parameters "By Reference" and "By Value"

ID: Q94374

The information in this article applies to:

Microsoft Word for Windows, versions 1.0, 1.1, 1.1a, 2.0, 2.0a, 2.0a-CD, 2.0b, 2.0c, 6.0, 6.0a, 6.0c
Microsoft Word for Windows 95, versions 7.0, 7.0a
Microsoft Word 97 for Windows
Word for the Macintosh, versions 6.0, 6.0.1, 6.0.1a
Microsoft Word 98 Macintosh Edition

SUMMARY

By default, Word passes parameters to subroutines or functions "by reference." To pass a variable "by value," enclose the variable in parentheses when you make the call to the subroutine or function.

MORE INFORMATION

Word 97 for Windows or Word 98 Macintosh Edition

For more information about passing a variable "by value," while in the Visual Basic for Applications Editor, click the Office Assistant, type "Passing Arguments Efficiently" (without the quotation marks), click Search, and then click to view "Passing Arguments Efficiently."

NOTE: If the Assistant is hidden, click the Office Assistant button on the Standard toolbar. If Microsoft Visual Basic Help is not installed on your computer, please see the following article in the Microsoft Knowledge Base:

   ARTICLE-ID: Q120802
   TITLE     : Office: How to Add/Remove a Single Office
               Program or Component

Passing a Variable "By Reference"

When you pass a variable "by reference," the subroutine or function can change the value of that variable. This change affects the value in the subroutine as well as the variable in the calling routine.

Consider the following example:

   Sub MAIN
      a$ = "By Value!"
      TestSub a$
      MsgBox a$
   End Sub

   Sub TestSub(b$)
      b$ = "By Reference!"
   End Sub

When you run this macro, the message box displays "By Reference!".

The variable a$ is passed to the subroutine TestSub where the variable is referenced by b$. Since the value of a$ is being passed "by reference," a$ and b$ actually point to, or share, the same data information. When b$ is assigned a new value, a$ will change as well.

Passing a Variable "By Value"

When a variable is passed "by value," the subroutine or function gets a copy of the information. If the subroutine or function assigns a new value to the variable, the change affects only the copy of the information and not the original that was passed to the subroutine or function.

Consider the following example:

   Sub MAIN
      a$ = "By Value!"
      TestSub (a$)
      MsgBox a$
   End Sub

   Sub TestSub(b$)
      b$ = "By Reference!"
   End Sub

The only difference from the previous example is that parentheses appear around the argument a$, which is being passed to the subroutine TestSub. However, when the macro runs, the message box displays "By Value!". In TestSub, b$ gets a copy of what was in a$. a$ and b$ do not share the same value; instead they have identical copies of the data.

NOTE: There is only one case in which the macro passes parameters "by reference" when they are enclosed in parentheses. If you run a subroutine and precede the subroutine name with the WordBasic Call statement, the macro passes all parameters "by reference," even though the parameters are enclosed in parentheses.

For example, if you call the TestSub subroutine in the above macro with the following syntax, the message box displays "By Reference!", even though you enclosed the variable in parentheses:

   Call TestSub(a$)

Examples: Passing Values "By Reference" And "By Value"

Consider the following function:

   Function TestFunct(x$, y$)
      x$ = "New X Value!"
      y$ = "New Y Value!"
   End Function

Below is a table of calls to the TestFunct function that indicates whether the macro passes the values "by reference" or "by value."

                             a$        b$

z = TestFunct(a$, b$)        by ref    by ref
z = TestFunct((a$), (b$))    by val    by val
z = TestFunct((a$), b$)      by val    by ref
z = TestFunct(a$, (b$))      by ref    by val

How WordBasic Differs from Other Microsoft Basic Languages

WordBasic passes variables "by reference" and "by value" in a different manner than most Microsoft Basic programming language applications (such as Microsoft Visual Basic, Microsoft QuickBasic, and Microsoft Professional Basic).

In WordBasic, the caller is responsible for using parentheses to determine whether information passes "by reference" or "by value." By contrast, other Microsoft Basic languages make this distinction in subroutines and functions using the BYVAL keyword in the parameter list of the declaration.

By default, other Microsoft Basic languages pass variables "by reference" (this is the same as WordBasic). If you precede the variable with "BYVAL" (without the quotation marks) in the subroutine or function declaration, the values pass "by value."

Consider the following Visual Basic subroutine:

   Sub TestSub(a$, BYVAL b$)
      a$ = "New a$ value!"
      b$ = "New b$ value!"
   End Sub

If you use the following syntax to call this subroutine, the first message box displays "Old a$", and the second displays "New b$ value!":

   a$ = "Old a$"
   b$ = "Old b$"
   TestSub a$, b$
   MsgBox a$
   MsgBox b$

Additional query words: winword2 VB QB winword 7.0 word95 Word98 macword word7 word6 word8 word97 8.0

Keywords          : kbmacro
Version           : 2.x 6.0 6.0a 6.0c 7.0 7.0a 97 98
Platform          : MACINTOSH WINDOWS

Last Reviewed: February 4, 1998