home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 2 BBS
/
02-BBS.zip
/
v611docs.zip
/
VMAIN611.ZIP
/
VC10
< prev
next >
Wrap
Text File
|
1993-10-08
|
14KB
|
273 lines
VBBS 6.11 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.11 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.11 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.11 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 code to tell VBBS it is running a
| | script
| ^-------------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.11 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 (see VBBS.DOC for information.)
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.
