.TOPIC:                                            
Virtual Script Language (VScript)

                                            VBBS 6.12 Documentation --  10-1


         ÉÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ»
         º CHAPTER TEN        VIRTUAL SCRIPT LANGUAGE <VSCRIPT>           º
         ÈÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍͼ

         SCRIPT LANGUAGE INTRODUCTION
         ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ

                One of the features that makes VBBS unique is its script
         language compiler - VCOM.EXE.  Along with the built-in command
         interpreter in VBBS, it allows you to make changes to your BBS
         quickly and easily.  The scripts are nothing more than a series
         of commands listed in a plain ASCII text file, and you don't
         even need to be a programmer to write one.  All you need to cre-
         ate scripts are a text editor or word processor that allows you
         to save in ASCII format (see your word processor documentation
         for more info) and a little patience.  In no time, you will be
         writing up scripts and swapping them with other VBBS sysops like
         a pro.  Scripts are generic to both the DOS and OS/2 versions.


         GENERAL RESTRICTIONS
         ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ

                The VBBS script language has only one major restriction;
         there can only be a total of 7 'tokens' on a line.  A token is
         defined as either a single unspaced series of characters (for
         example, a command or a number) or any group of characters and
         spaces surrounded by single or double quotes (also called a
         "string".)  The script language is NOT case-sensitive; any
         capitalization used in this text is not required and is done
         only for clarity.

                All the scripts that you create should be placed into your
         scripts directory as defined in VCONFIG - PATHS Configuration;
         see Chapter 2 for more information on setting your paths.

                The only other restrictions pertain to names.  All of your
         script files MUST have the extension .V and all of your names
         for variables must begin with a '$', e.g., $variable.


         SCRIPT COMPILER (VCOM.EXE)
         ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ

                The program VCOM.EXE is the compiler that prepares your
         script file for use by VBBS's interpreter.  It takes the script
         file that you have created and builds the two files that VBBS
         actually uses from it.  These two files have the same name as
         the script file but have .LIT and .COD as their extensions.

                Compilation of a script is accomplished by changing to
         your scripts directory and executing the command line:

                VCOM <script name>



                                            VBBS 6.12 Documentation --  10-2


         You do not need to use the extension to compile the script.
         The compiler can detect some errors in the script file during
         the compilation.  These errors are predominantly related to the
         commands that 'jump' around within a script.  These commands
         are GO, TEST, TESTVAL, CALL, and BREAK.  If an error is found
         the compiler will abort and you will need to go into your
         script to correct the error.


         COMMAND FORMAT
         ÍÍÍÍÍÍÍÍÍÍÍÍÍÍ

                All commands will be listed in the form:

                    Command Name ->  Command Syntax.
                             <description of command here>

         The following conventions will be used in all command syntax
         in this document:

           COMMAND     - All commands will be in capitals and must be
                         typed in the format shown (see the note below.)
           <label>     - A single word, no quotes or spaces.
           <variable#> - Any variable name (only).
           <number#>   - Any numeric value (only).
           <string#>   - A string value ("aBc 123") or any variable name.
           <value#>    - A numeric value or any variable name that is
                         used to store numeric values.
           <pathfile#> - A legal DOS filename including path information.
                         If the path is excluded it will default to the
                         BBS' main directory.  A variable that stores the
                         correct path/filename info may also be used.
           <filename#> - A legal DOS filename excluding path information.
                         Commands that use this have the path info set
                         automatically.  A variable that has the filename
                         stored in it may also be used.
           <prompt>    - Either a text string or a variable name.  Most
                         of these are optional, so use them only if you
                         want them.
           <relation>  - Any of the following, but see the specific com-
                         mand for verification:

                           = Equal to         <> Not equal to
                           > Greater than     >= Greater than or equal to
                           < Less than        <= Less than or equal to

           <option>    - The value of this item is command-specific.
           <token#>    - Any single item; see section 1.2 for a complete
                         definition of a token.

           Note: If the command name is followed by a '<---' then the
                 syntax for the command is just the command name.



                                            VBBS 6.12 Documentation --  10-3


         SPECIAL VARIABLES/CONSTANTS
         ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ

                The script language contains the following restricted
         variables, which are read-only:

           $AGE       - Age of user.
           $ANSI      - Stores the user's current graphics setting.  Set
                        to OFF if using ASCII, ON if using ANSI, and ENH
                        if using PDM's.
           $AVAILABLE - Stores the sysop availability flag. Y if sysop is
                        available, N if not.
           $BAUD      - Stores the user's connect speed.
                        Returns "" if logged into node 0 (or other local
                        node) and returns "CONSOLE" if logged in locally
                        from the WFC screen.
           $BBSNAME   - Stores the BBS' name, as shown in VCONFIG.
           $BELL      - Stores ASCII code 7, causes a beep when printed.
           $BIRTHDATE - User birthdate in same format as $DATE.
           $BS        - Stores ASCII code 8, causes the cursor to back up
                        1 space on current line when printed.  It is not
                        a destructive backspace.
           $CLEAR     - Stores <CTRL>-<L> for ASCII users, stores the ANSI
                        clear screen code for others when printed.
           $<color>   - These nine variables are reserved as color codes:
                        $RED, $BLUE, $CYAN, $GREEN, $YELLOW, $MAGENTA,
                        $WHITE, $BLACK, and $NORM.  See section 3.3 for
                        more information.
           $CR        - Stores ASCII code 13, causes a carriage return
                        when printed (moves to column 1, current line.)
           $CREDITS   - Number of credits user has.
           $CRLF      - Causes both a $CR & $LF when printed (moves to
                        column 1 of the next line.)
           $DATE      - Stores the current system date as MM-DD-YYYY.
           $EXTRAx    - The users extra variables values are stored in
                        $EXTRA1 thru $EXTRA8.  They can be changed with
                        the SETEXTRA command.  See section 8.2 for info.
           $FLAGS     - This contains the list of all active general
                        flags of the current user.  Use the INSTR command
                        with $FLAG and you will know if a particular flag
                        is on if the result is non-zero.  You can change
                        the value of a flag with the SETFLAG command.  See
                        section 8.2 for info.
           $HANDLE    - User's handle.
           $LF        - Stores ASCII code 10, causes a linefeed when it's
                        printed (same column position, next line.)
           $MAXTIME   - Maximum minutes per day.
           $NAME      - User's real name.
           $NODE      - Stores your VirtualNET node # as set in VCONFIG.
                        Default is 0 if you are not in VirtualNET.
           $PAGE      - Number of lines to print before pause.
           $PORT      - Returns present channel # of user (not COM port!)
           $SECURITY  - User's security level, 250 and up is considered
                        Co-sysop/Sysop access.  Use TESTVAL and this
                        variable to implement your own security.


                                            VBBS 6.12 Documentation --  10-4


           $SYSOP     - Stores the sysop's name as set in VCONFIG.
           $TEXTPATH  - Stores the path to your TXT directory.
           $TIME      - Stores the current system time.
           $TIMELEFT  - Number of minutes left for this session.
           $TIMEON    - Number of minutes on for this session.
           $TIMESON   - Total number of logons for the user.
           $TOTALMIN  - Total number of minutes on since first logon.
           $USER      - User's account number.
           $VIDEOMODE - This stores values similar to $ANSI, only they are
                        #'s instead of words.  Set to 0 if using ASCII, 1
                        if using ANSI, 2 if using PDM's, and 3 if using
                        VGIX.


         INTERFACING WITH VBBS
         ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ

               There are only two ways that you can run a script. You can
         either run the script from a function block or LINK to it from
         another script.  The former is covered here and the latter is
         covered in section 7.3 - Passing Control.

                Go into the function block you wish to have run the script
         and add the following line on any but the first two lines in the
         .FB file:

           Z 001 2 Scripter
           |  |  |   ^------This is the script name, NO extension.
           |  |  ^----------This is the command type that tells VBBS it is
           |  |             running a script. See section 7.3
           |  ^-------------This is the SL to be able to use the key (and
           |                run the script.)
           ^----------------This is the key to press at the menu to load
                            and run the script.


         PREPACKAGED SCRIPTS
         ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ

         --> IMPORTANT NOTE:  This section is best read after reading
                              through the entire file but is included here
                              to maintain the structure of this document.
                              Do not let the unknown terms interfere with
                              your reading, as they will all be explained
                              elsewhere.

                There are many script authors out in the BBSing community
         that have written all sorts of scripted programs to perform prac-
         tically everything you could ever want.  The most difficult part
         of using a script is knowing how to install it.  What you should
         do first is pull up the script and look for comments that explain
         the script.  Some will contain complete sets of instructions,
         while others will contain no comments at all.  If the script con-
         tains few or no comments, then what you will need to do is:


                                            VBBS 6.12 Documentation --  10-5

                1> Make sure that all EXIT and LINK statements point to
                   FB's or scripts that you actually have. If all else
                   fails you can set all of these statements to EXIT
                   to your main FB file.
                2> Look for any statements that use file commands.  Be
                   sure to change these to valid paths on your system.
                3> See if the script has any RET lines.  If it does,
                   try to find the CALL statements to the labels that
                   appear a few lines before the RET.

         After you have done these steps you will then have the info you
         need to determine how the script should be used.  If the script
         has no EXIT or LINK statements, or the script has a RET line with
         no CALL statement, then you must make the script part of an exis-
         ting one.  The easiest way to do this is to just block-copy the
         entire script in before your final EXIT or LINK statement in your
         script if it has no unmatched RET statements.

                If there is an unmatched RET statement, then installing
         the new script is even easier.  Somewhere in your script you need
         to add a CALL <label> statement with <label> being the label at
         the start of the new script.  Then just add as the last line of
         your script the line '& <script name>'.  You should be able to
         compile and run it at this point.  Just remember, 'Nothing is
         Guaranteed!', so if you have a problem with a script and you
         can't get it to work try to either pick the code apart (if you
         can) or hop onto any VirtualNet BBS that carries a script dis-
         cussion sub and ask a few questions (or a few hundred, as
         needed).  One of the script gurus may be able to help you out,
         and you might even be able to get in touch with the author.