BYREF keyword

Purpose: BYREF indicates that the following parameter is passing the argument by reference in the SUB or FUNCTION declaration. Note well, in BCX versions 4.29 and up, that in the FUNCTION or SUB calling statement, the variable being passed by reference to the procedure must be prepended by an ampersand.


 Syntax 1:

 SUB | FUNCTION MySubOrFunc(BYREF var1%, BYREF var2#, ...)

 Syntax 2:

 SUB | FUNCTION MySubOrFunc(BYREF var1 AS INTEGER, BYREF var2 AS DOUBLE, ...)

 Parameters:

  • BYREF var1 The integer variable var1 is being passed by reference.
  • BYREF var2 The double variable var2 is being passed by reference.

Anytime you want to be able to modify the contents of an argument, you must pass the argument BYREF. Otherwise, a copy of the value is normally passed to the SUB or FUNCTION.

Strings are automatically passed by reference, so BYREF is not needed when passing string arguments. Do not use BYREF within SUB or FUNCTION parameter lists when referencing arrays.

Here is an example using BYREF to modify the passed argument.


 CALL Test1 : KEYPRESS

 SUB Test1
   LOCAL i
   CALL Test2(&i)  ' this LOCAL variable will be modified by SUB test2!
   PRINT i
 END SUB

 SUB Test2(BYREF Q AS INTEGER)
   Q = Q + 2
   PRINT Q
 END SUB

Here is another example that uses BYREF to access a RECT structure from a subroutine(SUB rectProc1). Note carefully the use of parentheses. Also included is an example of an alternate syntax(SUB rectProc2) to accomplish the same access.


 DIM rct AS RECT

 rct.left = 1
 rct.top = 2
 rct.right = 100
 rct.bottom = 100

 rectProc1(&rct) ' The argument being passed by reference
 rectProc2(&rct) ' must be preceded by an ampersand.
 getchar()

 SUB rectProc1(BYREF rct AS RECT)
  ?(rct).left
  ?(rct).top
  ?(rct).right
  ?(rct).bottom
 END SUB

 SUB rectProc2(rct AS RECT PTR)
  ? rct->left
  ? rct->top
  ? rct->right
  ? rct->bottom
 END SUB