home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 2 BBS
/
02-BBS.zip
/
v612docs.zip
/
VC7
< prev
next >
Wrap
Text File
|
1993-12-16
|
33KB
|
643 lines
.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.