.TOPIC:                                            
Customizing VBBS

                                            VBBS 6.12 Documentation --  7-1

         ͻ
          CHAPTER SEVEN     CUSTOMIZING VBBS                             
         ͼ

                The configurability of VBBS can not be overstated.
                
                Because of the way VBBS is structured, it's possible to
         configure the program to look and feel like some other BBS soft-
         ware; you can borrow features from several different BBS soft-
         wares to create your own design.  You might just take a vacation
         from reality one night and decide to make VBBS look just like
         GEnie or some other CIS.  Aside from the obvious limitations on
         actual storage space, you could accomplish the "look-alike" to
         the point where a user could not tell the difference!  By using
         scripts (and the source code, if you've registered for it), you
         can do many things that simply aren't possible with other BBS
         softwares.
                Unlike source code, which normally contains strict rules
         on code segment distribution (VBBS included), VSCRIPT-based ap-
         lications, function blocks, and menus may be distributed freely
         in full, or even in entire configuration sets.


         Menus, Function Blocks, Scripts, and Mods
         

                Customization and modification of VBBS comes in several
         forms: changing the menus to suit your personal tastes and set-
         up, rearranging function-block commands, installing scripts for
         special applications, and even modifying the source code (if
         you've registered at the source level).
                Menus and function blocks are closely interrelated, so
         if you find yourself flipping back and forth between the sec-
         tions on the two, don't worry; it's normal.
                For the remainder of this manual, the term "script" will
         apply exclusively to programs utilizing the VSCRIPT script lan-
         guage; the term "mod" will refer exclusively to modifications
         made at the source-code level.  It should be pointed out here
         that you do not need to register VBBS to write scripts or ex-
         change scripts with other sysops via VirtualNET; registration
         and an additional fee ARE, however, required to obtain the VBBS
         source code.  
                There are other good reasons to register VBBS; we'll get
         to those presently.

        
         "Heart-Code ANSI"
         

                If you've read this far, you've run across the term
         "heart-code ANSI" a time or two.  Since customization often in-
         volves changing colors and menus and adding system taglines,
         this is probably a good place to explain what "heart-code ANSI"
         is.

                                             VBBS 6.12 Documentation -- 7-2


                If you've ever used the DOS "type" command to look at a
         file you've created using TheDraw or some other ANSI drawing
         program, you know it consists mainly of "garbage" resembling
         Chinese.

         This is the ANSI (American National Standards Institute) code
         for introducing color changes into text files so that the colors
         will show up onscreen; in order to display these color changes,
         you need to have the statement

                DEVICE=ANSI.SYS

         somewhere in your CONFIG.SYS file (remember, though, about the
         ANSI bomb -- see "First-Time Startup" for details on alternate
         ANSI drivers).
                A while back, a good number of BBS programs  began
         using a method of color changing called "heart-code ANSI",
         in which color changes were represented by a heart character
         followed by an alphanumeric character.  The heart-code system
         has the benefit of taking only two bytes to accomplish what
         takes 4-6 bytes in "raw" ANSI, thereby reducing the size of
         network transfers, especially where large numbers of color
         changes are involved.
                In an effort to maintain compatibility other bulletin
         board networks, VBBS was designed to handle heart-code
         ANSI.  The heart-code colorization system has become the stan-
         dard for these BBS softwares.
                When you're starting out with heart-code ANSI, it's a
         good idea to go into the VBBS FSE and press [Ctrl-P][?], and
         look at the color combinations that appear at the bottom of
         the screen.  The same set of color combinations can be seen
         when you go into your [D]efaults setup and start changing
         your screen display colors; you might consider printing out
         that screen using [Shift-Print Screen].

         --> IMPORTANT NOTE:  If you print-screen the default-menu
                              color change information, be aware that
                              all the codes are "off" by one; for exam-
                              ple, the screen code for gray on black is
                              1, but the heart-code for gray on black
                              is 0 (zero).  Likewise, the bright-red on
                              black is screen code 7, but heart-code 6.

         ͻ    Using heart-code ANSI takes some getting used to, but       
         ͼ    with practice, it's not terribly more difficult than
                the "raw" ANSI produced by TheDraw or other ANSI draw
                programs.  Heart-code ANSI is best for menus, taglines,
                and other features that have patterned or infrequent
                color changes.
                
                                             VBBS 6.12 Documentation -- 7-3


                The easiest way to produce a heart-code menu or tagline 
         is to first use an ANSI drawing program to make the menu/tag-
         line, then save it as a straight ASCII text file.  Then, pull
         it into the VBBS FSE and use [Ctrl-P] codes to change the co-
         lors (see Appendix C for details).
                To introduce a heart-code color change into an ASCII
         text file, turn Num Lock ON; while holding down the [Alt] key, 
         type in either "3" or "259" (whichever works) FROM THE NUMERIC 
         KEYPAD.  A heart character should appear on your screen.  The 
         second keystroke should be a number from 0-9 or a letter from
         A-Z, depending on what color you want to produce.


         Customizing Menus
         

                The VBBS archive includes a default set of function blocks
         (see below) and their accompanying menus.  After running the de-
         faults for a while, however, most sysops want to customize their
         menus to more accurately reflect their personal tastes and give
         their BBS a distinctive look.
                Default VBBS has four different types of menu files:

                        .MNU files (the default)
                        .ANS and .ASC files
                        .PDM files

         We'll take a moment to explain each one in detail (there is one
         more menufile type if your BBS is set up to use the R.I.P.
         (Remote Imaging Protocol).

         On startup, VBBS looks for menu files with the .MNU ex-
         tension.  The .MNU files included with VBBS are done in heart-
         code ANSI, and serve "double duty".  If the user's video display
         will support ANSI graphics, the color changes will be included,
         but if it won't (user's defaults set to ASCII), VBBS will strip
         out the color changes for display to that user.  The main bene-
         fit of this system is that by using the heart-code .MNU files, 
         only one set of menu files is needed for both ANSI and ASCII 
         users.  Another point in favor of the .MNU files is that they
         seem to display a little bit faster -- this is probably due to
         the fact that it takes only two bytes to make a color change.

                The second set of menu formats -- .ANS and .ASC files --
         is what VBBS will look for if it doesn't find .MNU files.  The
         .ANS format is "raw" ANSI, such as that produced by TheDraw;
         an .ASC extension represents an ASCII (text) menu.  The advan-
         tages to having these files in lieu of .MNU files is that they

                                             VBBS 6.12 Documentation -- 7-4


           1) are a little bit quicker to produce, i.e., you draw a 
              menu directly in ANSI, save it twice (in .ANS format 
              and in .ASC format), and you're done.
           2) are easier to make, especially if you have very com-
              plex menus and color changes; the heart-code system 
              can be a little daunting if your menus are ornate.

         The downside of this method is that you must have two copies of
         each menu, one for ANSI users and one for ASCII users; if a user
         with ASCII defaults gets an .ANS menu, he/she will receive gar-
         bage characters (as shown above) and probably won't call back.

                The final set of files are VBBS' "pull-down" menus, which
         have a .PDM extension.  These are for users who have selected
         "Enhanced ANSI" as their screen display default.  These are ac-
         tually ASCII text files that VBBS colorizes as part of the de-
         fault color selection.  A user may opt to use .PDMs at any sys-
         tem prompt by pressing the [Esc] key -- and you should try it
         to see how they work.  The default FILES.PDM file is shown
         below:

                Directory
                 C Change Directory [C]
                 L List Files       [L]
                 S Search All Dirs  [S]
                 N New Files List   [N]
                 F Find Description [F]
                Transfer
                 D Download Files  [D]
                 U Upload Files    [U]
                 B Batch Functions [B]
                 R Review Files    [R]
                 Y Your Stats      [Y]
                Other
                 J New File Scandate       [J]
                 P Popular Downloads       [P]
                 M Download Master List    [M]
                 Q Quit to Main Menu       [Q]
                 G Log Off                 [G]

         These files are preconfigured, but easily changed using any text
         editor.  They don't need to be changed, though, unless you re-
         group or add commands within the function blocks.  But --

         --> IMPORTANT NOTE:  Any changes you make in your .MNU or
                              .ANS/.ASC menus should also be made in
                              your .PDM files.

         
                                             VBBS 6.12 Documentation -- 7-5



                Creating your own .MNU menus is simple enough: after 
         making backups of the original menu files (just in case), use 
         your favorite drawing program (or even a text editor capable of 
         handling "extended ASCII" characters, although this is a LOT 
         more work) to make an ASCII menu file.  To add the color 
         changes you want, pull the file into the VBBS FSE and use 
         heart codes to add color (as described earlier).

         ͻ    Menus are a great means of customizing your BBS.  They're
         ͼ    also the primary method by which a user interacts with
                your BBS, so you want to design menus that are as func-
                tional as possible.  Please note that complete script/
                function block/menu/pdm packages emulating the look and
                feel of several other bbs softwares have been developed.
                The most notable of these is MVMEN by David Bell with
                emulations of WWIV, Remote Access, WildCat, Renegade, and
                others, in addition to multi-language VBBS modules.


         Function Blocks
         

                At the heart of VBBS' command structure is the FUNCTION
         BLOCK, which is in turn represented by a menu.  A function block
         is an easy-to-modify ASCII file which allows the sysop to define 
         every single function of any menu -- what each key does, whether 
         it is calling an internal function, an external VSCRIPT, external
         .EXE file (shrinking or not shrinking VBBS out of memory as de-
         sired), or calling another function block.
                Creating and editing function blocks may be done with any
         ASCII text editor; the resulting files should be placed in the 
         VBBS \V or \VSCRIPT directory you have set up in VCONFIG.  

         For example, for your FILES.FB, the first line of the function
         block might now read FILE1.  This would instruct VBBS to display 
         a menu file called FILE1.MNU, FILE1.ANS, FILE1.ASC, or FILE1.PDM
         (depending on which menuing scheme you're using and the user's 
         default display setting).  Similarly, your START.FB might call
         up the MAIN.xxx menu file, while your SYSOP.FB might call up the
         SYSOP1.xxx menu file.
                The second line holds the letter designators of any topic
         areas that "go with" the function block.  For example, if you

                                             VBBS 6.12 Documentation -- 7-6

         have message topic areas A, B, C, and D, the second line of your
         START.FB should read

                ABCD

         Otherwise, your users would only see ONE topic area; the "A"
         topic that came preconfigured as a default.  Many new sysops for-
         get to add these other topic designators in; it's not difficult
         to overlook this, even though it IS crucial.

                Each subsequent line of a function block enables a "hot-
         key" to perform a particular command or function.  Lines in the
         "body" of a function block MUST follow this particular format
         and appear in strict columns:

                k xxx y cccccccccccc

         An explanation is given below.

         Part   Column(s)  Explanation
             
         k          1      The letter or symbol serving as the hot-key
         xxx       3-5     The minimum SL needed to access the function 
                             (must be three digits, like "050" or "007")
         y          7      The command type (a digit 0-5; more on that 
                             below)
         cccccc     9+     The name of the routine/script/.EXE command 
                             line, etc.; this section is of variable 
                             length, depending on what you're trying to 
                             do.

                The "y" in the command line represents a digit from 0
         through 5 that tells VBBS how to execute the command, according
         to the following list:

         Digit  Command-type Description                               
           
           0    Null (no operation)
           1    Internal command (like SENDEMAIL)
           2    Script
           3    DOS function (don't shrink VBBS out of memory)
           4    DOS function (shrink VBBS out of memory)
           5    Transfer control to a different function block

                A sample function block to handle E-mail might look some-
         thing like this (without the parts inside angle-brackets):

                EMAIL           <name of menu file>
                                <no database attached; E-mail's automatic>
                e 001 1 sendemail
                m 001 1 reademailto
                f 001 1 feedback
                s 001 1 reademailsent
                q 000 5 start   <on quitting, return to START.FB>

                                             VBBS 6.12 Documentation -- 7-7


         The Default START.FB
         

                VBBS could easily have been distributed with a blank menu;
         instead, a default START.FB is included which reflects the con-
         figuration of the software on the author's BBS, "Virtual Techno-
         logies".  Note the columnation at the beginning of each line and
         the topic-area designator on the second line.  Other points of
         interest include:  1) the 255 SL required to transfer control to 
         the SYSOP.FB function block; 2) the VBBS-AUX commands that shrink
         the BBS out of memory to execute the associated program; and 3)
         the nonalphabetic characters used as hot-keys.

                MAIN
                A
                $ 001 1 choosetopic
                > 001 1 nextbase
                < 001 1 prevbase
                c 001 1 selectbase
                j 001 1 setquickscan
                s 001 1 scanmsg
                n 001 1 readnewmsg
                r 001 1 readseqmsg
                p 001 1 post
                e 001 1 sendemail
                y 001 1 reademailfrom
                m 001 1 reademailto
                q 001 1 quickmail
                f 001 1 feedback
                o 001 1 door
                z 001 4 vbbs-aux %1 telecon
                d 001 1 account
                l 001 1 pagesysop
                t 001 5 files
                b 001 4 vbbs-aux %1 textfiles
                k 001 1 listcallers
                u 001 4 vbbs-aux %1 listusers
                a 001 1 autopost
                v 001 4 vbbs-aux %1 vote
                i 001 1 sysinfo
                w 001 1 who
                x 001 4 vbbs-aux %1 listnet
                * 255 5 sysop
                g 000 1 logoffyn

                Making changes is as simple as pulling the START.FB file
         into a text editor (even the VBBS FSE, from WITHIN the board!)
         and adding in the desired function(s).  For example, you might
         add in the following line to invoke a script that shows a user
         his/her credit total:

                # 001 2 crcheck

         Notice that all this is presented in lower-case; function blocks
         are NOT case-sensitive, so the number of commands you may have

                                             VBBS 6.12 Documentation -- 7-8


         is limited to 26 letters + 10 digits + however many punctuation
         and nonalphabetic characters you can come up with (of course, if
         any FB ever gets that big, you'll probably want to split it into
         smaller chunks anyway).

         ͻ    If you start breaking your function blocks into smaller
         ͼ    pieces, it's important to choose letter commands -- "hot
                keys" -- in such a way that commands will be consistent
                across menus.  For example, if you have the [M] key set
                to jump to the Message Menu in one function block, try
                to make it do the same thing in ALL function blocks.
                This may not be easy, but your users will appreciate not
                having to learn a different set of hotkeys at each menu.


         The Default FILES.FB and SYSOP.FB
         

                There are two other default function blocks: FILES.FB,
         which governs the file transfer section(s), and SYSOP.FB, which
         contains the commands for the sysop function block.  These func-
         tion blocks are shown below:

         FILE1                          SYSOP1
         F
         g 000 1 logoffyn               m 255 1 readallemail
         m 001 1 dlmasterlist           e 255 1 editfile
         u 001 1 remoteupload           u 255 1 useredit
         d 001 1 downloadfile           s 255 4 vbbs-aux %1 security
         r 001 1 reviewfile             v 255 1 validate
         c 001 1 selectbase             c 255 1 cleanup
         j 001 1 setnewfilesscan        q 000 5 start
         l 001 1 listfiles
         n 001 1 newfiles
         s 001 1 searchall
         b 001 1 batchdl
         f 001 1 findfiles
         > 001 1 nextbase
         < 001 1 prevbase
         p 001 1 topdownloads
         y 001 1 ratio
         z 255 1 sysopupload
         x 255 1 reviewuploads
         q 000 5 start


         One change to FILES.FB you might want to try right off the bat
         -- if you have more than one files area and want to fiddle with
         the function blocks (and if Roland hasn't added it in as a de-
         fault command yet) -- is to add in this line:

                $ 001 1 choosetopic

         No compilation is necessary ... just save it, and the the [$]
         command to move between files topic areas is enabled, just like

                                             VBBS 6.12 Documentation -- 7-9


         in the message bases!  Make sure, though, that you add the com-
         mand in your menus so your users can take advantage of it.

                Rearranging the commands in function blocks isn't that
         difficult -- it's just a matter of making sure you don't leave
         out any commands.  For example, I have separate function blocks
         for the Main Menu (12 whole commands!), E-mail, transfers, and
         subsystems, coupled with the ability to jump between FBs with
         one keystroke.  Of course, my menu structure is quite different
         from the default setup -- but that's the beauty of VBBS.  It
         didn't blink an eye when I installed the changes!
                One caveat, however: your main function block MUST be
         called START.FB.  It is the function block that takes over when
         the START.V script finishes running.


         Scripts and Mods
         

                As stated earlier, the term "scripts" refers to programs
         written using VSCRIPT and compiled using the program VCOM.EXE;
         "mods" refers to source-code modifications (just a reminder).

                The VSCRIPT language is one of the most powerful features
         of VBBS (if not THE most powerful).  It's a small programming
         language, somewhat similar to the REXX script language, that 
         incorporates many of VBBS' functions into single command state-
         ments (with or without command-line arguments).  All it takes 
         is your favorite ASCII text editor or word processor and some 
         familiarity with the VSCRIPT language (that's a separate part 
         of the documentation; see Chapter 10  for details), and you can
         be customizing your BBS via scripts in no time.
                As an example, let's take the script mentioned earlier
         that allows users to check their credits.  It consists of only
         three lines:

                tr
                tr "You currently have " $credits " credits."
                tr

         Save this file in your \V or \VSCRIPT directory (as you have it
         configured in VCONFIG) under the name CRCHECK.V (to maximize
         efficiency, you might want to keep a copy of VCOM.EXE in this 
         directory as well).  Compile the script:

                VCOM CRCHECK.V

         and you will see two NEW files in the directory:  CRCHECK.COD
         and CRCHECK.LIT.  These are the files VBBS will look for when
         you execute the script from the function block in which it's
         placed.
                There are literally dozens, if not hundreds, of VSCRIPT-
         based applications available through VirtualNET (more about that
         later).  Some enterprising programmers have created casino games,
         alternate mail and voting routines, scripts to welcome new users

                                             VBBS 6.12 Documentation -- 7-10
         

         and take them on a tour of the BBS, show user information ... 
         it's difficult to describe the variety of scripts that have been 
         written by sysops and users alike!  

                VBBS may also be modified through direct changes to the
         source code, a process known as "source modding" or simply "mod-
         ding".  This DOES require that you have a copy of either Micro-
         soft's QuickBASIC compiler (version 4.5 or later). The "QBASIC"
         that comes with MS-DOS is NOT sufficient for this purpose.
                
                VBBS employs a mixed programming environment using assem-
         bly-language routines for fast COM port and program I/O, while
         using QuickBASIC as an affordable and easy-to-modify environment.  
         This is in sharp contrast to many other BBS softwares, which re-
         quire a knowledge of Pascal or C and their associated compilers.
         It should be noted here, however, that in order to keep the 
         source-code files from being too large, there are very few com-
         ments in the default program; this can make for an -- <ahem!> -- 
         INTERESTING time when you're looking for a particular routine or 
         section of the code.  Just thought we'd let you know in ad-
         vance ...!  :-)

         ͻ    Some helpful hints to make your source modding easier:
         ͼ
                1) Make backup copies of the existing source code.  It
                   might save you truckloads of grief later.
                2) Print out the source code (make a pot of coffee or
                   something while you do ... it takes a while) and read
                   through it BEFORE you start modding.  The files are
                   simply too complex to try to keep up with on a screen-
                   by-screen basis.  Highlighting's much easier, too; my
                   source-code printout has so much red ink on it that it
                   looks like a bad high-school English paper.
                3) Make sure you're thoroughly familiar with the functions
                   and commands of VBBS; this will make it easier to spot
                   their associated source routines.
                   
         --> IMPORTANT NOTE:  Access to the QB4.5 DOS source code is
                              governed by a specific licensing agreement.
                              You may not possess any portion of the source
                              without having obtained a license to do so 
                              from the VBBS author, and in no case shall 
                              more than 100 lines of VBBS code be con-
                              tained within a published modification at
                              any time.

          OS/2 Version   :  Please note that source code is not made
                              available for source modding. Full scripting
                              is possible.

                                             VBBS 6.12 Documentation -- 7-11


         Scripts and Mods on VirtualNET
         

                Once your BBS is a VirtualNET node (more on that in a
         bit), there are many message subs dedicated to VBBS scripts
         and mods.  Two main subs are:

                       VBBS Script Technical Support
                       VBBS Source Technical Support

         The "VBBS Script Technical Support" sub is for the discus-
         sion of scripts and mods -- questions, troubleshooting, and the
         like.  The "Virtual ModNET" is EXCLUSIVELY for the posting of
         script/mod code -- no discussion.

         System Taglines
         

                Many sysops whose BBSs are part of VirtualNET like to
         "personalize" posts originating from their system by adding a
         system tagline to the posts.
                System taglines are optional; if they are used, however,
         they must follow several guidelines:

                1) They must include the name of the BBS, its geo-
                   graphic location, VirtualNET node number, and
                   version of VBBS being used;
                2) They must be 3 lines or less AND 300 bytes or
                   less (i.e., a 3-line, 350-byte tagline is NOT
                   acceptable);
                3) They must be colorized using ONLY heart-code 
                   ANSI (no "raw" ANSI allowed).

                Creating a system tagline is similar to creating a new
         menu; you make and save an ASCII version of the tagline, then
         bring it into the VBBS FSE to colorize it with heart codes.
         Since any experimental color changes are also saved with the
         tagline, it's usually a good idea to use your ASCII text edi-
         tor to delete any unnecessary color changes after you've got
         your tagline looking the way you want it.
                Taglines reside in your \TXT directory under the name(s)
         TAGLINE.xxx, where "xxx" is a number from 1 to 999.  It should
         be noted that single- or double-digit extensions to these files
         should be just that, i.e., TAGLINE.1 or TAGLINE.22, and not
         TAGLINE.001 or TAGLINE.022.

         ͻ    A word or two on system taglines:  they should be as dis-
         ͼ    tinctive as possible without being gaudy or distracting
                from the body of the message.  "Eyesore" taglines are 
                sometimes the butt of jokes on VirtualNET.  In addition, 
                some sysops try to cram every bit of information they

                                             VBBS 6.12 Documentation -- 7-12


                can about their systems into their taglines; this is 
                frequently viewed as being distracting, and in general, 
                a "less-is-more" approach is best advised.  If you want 
                to advertise your huge file base or the 42 game doors
                your system currently has, it's usually better to make 
                a BBS ad for the "BBS Advertisements" sub instead
                of trying to cram this information into your tagline.


         R.I.P. Remote Imaging Protocol GUI Interface
         

                VBBS is now compatible with R.I.P. graphic standards.
         RipTerm is an optional mouse-driven terminal program which
         interfaces with VBBS.  R.I.P. supports user's-end VGA graphics
         (sorry, no VGA locally -- the "overhead" local VGA would intro-
         duce would be of truly epic proportions) and is icon-driven.  As
         of this writing, a number of communication programs now
         support R.I.P. graphics.
                Details on R.I.P.may be found in the documentation that ac-
         companies the RipTerm Program. Adding R.I.P screens is yet
         another way you can customize your VBBS installation, and the
         early reviews are enthusiastic, to say the least!

                As you can see, there are quite a few ways you can cus-
         tomize your VBBS to get exactly the "look-and-feel" you want.
         It's pretty much a case of you being limited only by your imagi-
         nation.  You can make the graphics, menus, and command structure
         as simple or complex as you want them.  Just keep in mind that
         when you make changes to your user interface, it should be to
         make your users' lives easier, NOT to push everything to the
         max for the sake of doing it.

