Rapid-Q Documentation by William Yu (c)1999 | Appendix C: Procedures

# Introduction to Procedures

  A procedure in BASIC is either a SUB or FUNCTION (or SUBI and FUNCTIONI). It's functionally the same as GOSUB and RETURN but introduces the concept of parameters and return values. Unlike QBasic, a FUNCTION can also be called as a SUB. Meaning you can ignore its return value.
  DECLARE SUB
  Use DECLARE SUB whenever you want to provide a "forward" declaration without actually writing the SUB yet.

          DECLARE SUB Test

          CALL Test

          SUB Test
            '' Do Stuff
          END SUB

  Using CALL to call your subroutine is strictly optional. As you can see, we're providing a forward declaration of the SUB Test. To avoid using DECLARE SUB, you could have written the SUB Test before CALLing it.

          SUB Test
          END SUB

          Test

  This way you don't need to use DECLARE SUB. Please note that your parameter names in the DECLARE SUB and your actual SUB declaration MUST MATCH exactly! If you're not sure what I mean, take this for example:

          DECLARE SUB Test (A AS INTEGER, B AS INTEGER)

          SUB Test (X AS INTEGER, Y AS INTEGER)
             PRINT X;" ";Y
          END SUB

  Don't change the variable names! This is because when you defined your DECLARE SUB, the parameter names have been fixed as A and B, which also means you can comfortably do this:

          DECLARE SUB Test (A AS INTEGER, B AS INTEGER)

          SUB Test
             PRINT A;" ";B
          END SUB

  This is perfectly valid, since you've already declared your subroutine to have an A and B parameter. You don't actually need to define parameters if you already have a forward declaration in place. Obviously this can become confusing so it's not recommended.
  Passing variables by reference
  There are 2 ways to pass variables by reference. Unlike other BASIC languages, Rapid-Q assumes that all parameters are passed by value unless explicitly specified. To do this explicitly, you can attach a BYREF keyword in front of your parameter list. Here's an example

          SUB StrCat (BYREF Source AS STRING, Text AS STRING)
              Source = Source + Text
          END SUB

          A$ = "Hello"
          StrCat A$, " world!"
          PRINT A$              '-- returns "Hello world!"

  Another way is to prepend an '@' symbol in front of the variable:

          SUB StrCat (Source AS STRING, Text AS STRING)
              Source = Source + Text
          END SUB

          A$ = "Hello"
          StrCat @A$, " world!"
          PRINT A$              '-- returns "Hello world!"

  FUNCTIONs versus SUBs
  The only difference between a FUNCTION and a SUB is that a FUNCTION returns a value.

         FUNCTION Test AS INTEGER
           Test = 123
           Result = 123
         END FUNCTION

         Rval% = Test

  Our FUNCTION Test returns an INTEGER, which we can clearly see returns 123. To return a value, you can use the FUNCTION's name or use the keyword Result. Just because you've attached a return value to the FUNCTION, it does not automatically terminate until it reaches your END FUNCTION. So you can really assign as many return values as you like without consequences. The last return value assigned will ultimately be the one bound to your FUNCTION. To exit a FUNCTION or SUB, just use EXIT FUNCTION, or EXIT SUB respectively. One special case in using SUBs or FUNCTIONs in Rapid-Q is that you can only pass at most 10 parameters. QObjects, Arrays, UDTs and Variants are passed by reference, everything else is passed by value. In order for Rapid-Q to recognize that you want to pass a variable by reference, you must attach an @ symbol in front of the variable, or use BYREF in your parameter list. See Chapter 3 section 5 for more information.
  SUBI and FUNCTIONI
  There's a whole chapter reserved for these two procedure methods. It's not really that complicated, but is very handy to use. They provide the programmer with infinite parameters without type checking. Only simple types like numbers and strings can be passed, no Arrays, UDTs or QObjects. See Chapter 9 for all the details.

  <- Methods | Contents | Internal Variables ->