$IF 0
    OPT_PARM.TIP                                        OPT_PARM.TIP
                  PowerBASIC 3.2 Parameter Demonstration
                     Written by Jamshid  Khoshrangi
    RELEASED 11 SEP 95
    This example is released to the public domain.  PB Inc. -- please
    include it as a .FAQ or .TIP file in your next disk release of
    PowerBASIC, in order to help some programmers who find optional
    parameters a bit confusing.
    PURPOSE:
    This code demonstrates two features of PowerBASIC version 3.2,
    namely:
        1.  The use of optional parameters,
        2.  The use of pointers and null-pointer errors
            in identifying which params were actually passed
            at run-time.
    I've found a few "features" with version 3.1's implementation
    of optional parameters that have been fixed with version 3.2.  The
    first problem with version 3.1 optional parameters was that they
    could only be passed by value, which means that optional parameters
    could not be passed back with changes made to them.  Version 3.2
    allows parameters to be passed by reference, as well as by value using
    BYVAL.
    The second problem I found with optional parameters as implemented in
    version 3.1 was that one could not have a SUB with only one parameter,
    if that parameter was optional.  For some reason, this would not
    compile:
        SUB MySub CDECL ([BYVAL TheOneParam AS INTEGER])
    This, however, would:
        SUB MySub CDECL (TheRealParam AS BYTE [,BYVAL OptParam AS INTEGER])
    This has been fixed in version 3.2, allowing:
        SUB MySub CDECL ([TheOneAndOnlyParam AS INTEGER])
    Finally, version 3.1 did not allow the programmer any way of knowing
    whether or not a given parameter had actually been passed.  This
    required flags to be passed, like this:
        SUB MySub CDECL (NumParams%, Parm1% [,BYVAL Parm2%])
    This required calls like:
        MySub 1, 55
        MySub 2, 55, 10
    To me, at least, this seemed an odd way to pass parameters.
    Using ERROR trapping, with $ERROR BOUNDS ON, however, one can
    trap PB error #211 (Un-Initialized Pointer Error).  The ON LOCAL
    ERROR RESUME NEXT statement can precede a dummy use of the
    variable within the SUB, and then ERR can be read for a value of
    211.  If the value of ERR is not 211, one can then go on and
    safely assume that the optional parameter in question was passed.
    Otherwise, use of the variable in active code may lead to disaster.
    Remember to immediately follow the dummy reference with an ON
    LOCAL ERROR GOTO 0, and all is well.  This example code demonstrates
    exactly what I'm talking about.
    This code, then, shows how to use PowerBASIC's new pointers and the
    added functionality of Optional Parameters in version 3.2 to
    accomplish something never before seen in any BASIC I've ever
    programmed in!  Suppose we have a "PrintToFile" routine.  If we just
    want to print an empty line to the file, we call it thus:
        PrintToFile
    If we want to print some text, we call it:
        PrintToFile "The text to print"
    If we want to suppress a carriage return at the end, we call it:
        PrintToFile "The text to print", %TRUE
    The SUB declaration for this would read:
        DECLARE SUB PrintToFile CDECL ([Text$, SuppressCR%])
    The actual skeleton of the logic used within the PrintToFile SUB
    follows....
    I hope this clears up some of the confusion.  I've purposely
    over coded the routine just to show the logic you need to use
    when using optional parameters.
    Jamshid (aka "Quinn Tyler Jackson")
$ENDIF
'   Without BOUNDS checking on, this code could possibly send the
'   computer into the Twilight Zone....  Under QEMM it will, at the
'   very least, generate a pretty Exception 13 error on my system.
$ERROR BOUNDS ON
DEFINT A-Z
%TRUE = -1
%FALSE = NOT %TRUE
CLS
TheString$ = "This is a test!"
TheOtherString$ = "This is on its own line...."
PrintToFile
PrintToFile TheString$, %TRUE
PrintToFile TheString$
PrintToFile TheOtherString$
SUB PrintToFile CDECL  ([Text$, SuppressCR%])
    '   The following code simply determines which parameters were
    '   ACTUALLY passed to the SUB....
    '   By the way, even C's optional parameters are not THIS easy
    '   to work with... Kudos to PowerBASIC!
    ON LOCAL ERROR RESUME NEXT
        Text$ = Text$   '   Dummy code to generate error 211 if the
                        '   param wasn't passed to the SUB
        IF ERR  211 THEN
            CanUseTextString = %TRUE
        END IF
        SuppressCR% = SuppressCR%   '   More dummy code (see above)
        IF ERR  211 THEN
            CanUseSuppressCR = %TRUE
        END IF
    ON LOCAL ERROR GOTO 0
>>> Continued to next message
--- Maximus/2 2.01wb
---------------