.TOPIC:                                            
Control Commands

                                            VBBS 6.12 Documentation -- 10-F-1


         ͻ
          CHAPTER TEN ANNEX F      CONTROL COMMANDS                      
         ͼ


         GENERAL REDIRECTION
         

         # ->  # <label>

                This command allows you to set points up within your script
           that the various other control commands can use.
                   ex:  TR "Hello "
                        GO skipit
                        TR "You wont see this text..."
                        # skipit
                        TR "Because you just jumped down to here!!"

         CALL ->  CALL <label>

                This forces the script to go to <label> and continue to
           run from there.  When a RET is found the script will go back
           to the line after the CALL command.

         GO ->  GO <label>

                This forces the script to go to <label> just like the CALL
           command, with the only difference being that it will not return
           if it encounters an RET statement.

         RET <---

                This returns a script from a routine CALLed to the line
           after the CALL statement.  Note: RET is ignored if there was
           no CALL statement used.


         LOOPS AND COMPARISONS
         

                VSCRIPT supports some of the more common forms of loops
           and comparison structures.  These are all covered below but
           note that the script language can not generally handle nested
           loops easily, so some testing must be done before you create
           any scripts using such combinations.

         DO LOOPS
         

         ->  DO <variable1> = <value2> <value3>
                  [body of the loop]
             LOOP

                This type of loop begins with <variable1> equal to


                                            VBBS 6.12 Documentation -- 10-F-2


           <value2>.  Each time it reaches the LOOP it adds 1 to it
           and continues until <variable1> is greater than <value3>.

         ->  DO WHILE <variable1>   {must store a numeric!}
                  [body of the loop]
             LOOP

                This type continues to loop until <variable1> = 0. You
           must have some way to either exit the loop, or have a place
           where <variable1> is set to 0 or the script will lock into an
           endless loop.


         IF/IFVAL STRUCTURES
         

                IF structures allow you to compare 2 strings to see if they
           match, valid <relation> operators are = and <> ONLY! The IFVAL
           structures are identical to IF structures, but they are used to
           compare numeric variables.  Valid IFVAL <relations> are =, >,
           >=, <, <= and <>.

         ->  IF <variable1> <relation> <variable2> THEN
                  [then-code]
             ENDIF

                This performs the [then-code] if <relation> is true.

         ->  IF <variable1> <relation> <variable2> THEN
                  [then-code]
             ELSE
                  [else-code]
             ENDIF

                This performs similar to the IF structure, but if the
           <relation> is false it performs the [else-code].


         TEST/TESTVAL COMMANDS
         

         ->  TEST <variable1> <relation> <variable2> <label>
         ->  TESTVAL <variable1> <relation> <variable2> <label>

                The two TEST commands allow you to compare two variables,
           and if the comparison is true, to go to a separate part of the
           script (as if a GO <label> had been used).  The only difference
           in the two commands is that TEST performs a non-case-sensitive
           string comparison and TESTVAL performs a mathematic comparison.
           Valid <relations> are =, <, <=, >, >= and <>.


                                            VBBS 6.12 Documentation -- 10-F-3


         PASSING CONTROL
         

                There are a total of four ways that you can pass control
           from a script to something else.  These four ways each have
           special uses and are covered below.

               Note: These commands will only accept one token following
                     the actual command.  If you wish to have more items
                     on the line then you must place them into a variable
                     and place the variable on the command line.
                     ex: $doscom = "dir " & $pathused & " /w"
                         SHELL $doscom

         LINK ->  LINK <filename>

                This command causes the present script to terminate and
            begin running a script called <filename> (do not use any
            extension or globals in the filename.)  All of your
            variables will be cleared before the new script begins
            operation.

         EXIT ->  EXIT <filename>

                This command causes the present script to terminate and
            then exits to the function block <filename> (as with LINK,
            do not use extensions or globals.)  If no <filename> is
            specified then the script will exit to the .FB file that
            it was called from UNLESS the script did a shrinkout (see
            DOOR, below) in which case it will always exit to START.FB.

         SHELL ->  SHELL <pathfile or DOS command line>

                This will drop to DOS while keeping the BBS in memory.
            It will then execute the command following SHELL and then
            return to the line after the SHELL command.  All of your
            variables are retained because the script is never taken
            from memory.

         DOOR ->  DOOR <pathfile or DOS command line>

                This will shrink the BBS out of memory and drop to DOS.
            Implementation of the DOOR command writes the dropfiles
            CHAIN.TXT, DOOR.SYS and DORINFOx.DEF to disk.  If nothing
            else is specified on the command line then the script will
            bring up your list of Doors as set in VCONFIG, otherwise it
            will execute the required command line.  All of the script
            variables will be cleared by the DOOR command.  After the
            DOOR has been exited the user will return to the function
            block that the script was called from unless one of the
            following two commands are used just before the line that
            contains the DOOR command:


                                            VBBS 6.12 Documentation -- 10-F-4


         RETURNFB -> RETURNFB <function block name>
         RETURNSCRIPT -> RETURNSCRIPT <script name>

                If either of these two commands precedes the DOOR command
            the user will be returned to the function block selected OR
            the beginning of the selected script.  If an invalid function
            block name or script name is given it will restore the user to
            the START.FB function block. If you do not have a START.FB then
            the BBS will shut down.


