' Rapid-Q by William Yu (c)1999-2000                                             .
' ================================================================================
' Upload_il_tuo_script_su_Rapidq.it

' 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. SeeChapter_9for all the
details.



' ===============================================================================
'                      2003 Holyguard.net - 2007_Abruzzoweb