home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-387-Vol-3of3.iso / v / v56a6-2.zip / VSCRIPT.DOC < prev    next >
Text File  |  1993-01-30  |  104KB  |  2,448 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                        ██┐    ██┐ ████████┐ ████████┐ ███████┐
  8.                        ██│    ██│ └██┌──██│ └██┌──██│ ██┌────┘
  9.                         ██┐  ██┌┘  ███████│  ███████│ ███████┐
  10.                          ██┐██┌┘   ██┌──██│  ██┌──██│ └────██│
  11.                           ███┌┘   ████████│ ████████│ ███████│
  12.                           └──┘    └───────┘ └───────┘ └──────┘
  13.                                           *
  14.  
  15.                                  The Virtual BBS/NET
  16.                                     Version 5.60
  17.  
  18.                       (C) Roland De Graaf 1990, 1991, 1992, 1993
  19.  
  20.                                   4246 Elisabeth Ave.
  21.                                   Holland, MI 49424
  22.  
  23.                                           *
  24.  
  25.          ═════════════════════════════════════════════════════════════════
  26.                               VBBS VSCRIPT Documentation
  27.          ═════════════════════════════════════════════════════════════════
  28.          Written By:  Tom Hightower, aka "Baloo"
  29.                          1@8064 VirtualNET
  30.                       Kevin Klunk, aka "Lord Doomslayer"
  31.                          2@5081 VirtualNET
  32.          Format By:   Sam Fleming, aka "O. F."
  33.                          1@2056 VirtualNET
  34.          ═════════════════════════════════════════════════════════════════
  35.  
  36.  
  37.                                 TABLE OF CONTENTS
  38.  
  39.                          (1) General VSCRIPT Information
  40.                               1.1 - Script Language Introduction
  41.                               1.2 - General Restrictions
  42.                               1.3 - Script Compiler (VCOM.EXE)
  43.                               1.4 - Command Format
  44.                               1.5 - Special Variables/Constants
  45.                               1.6 - Interfacing with VBBS
  46.                               1.7 - Prepackaged Scripts
  47.  
  48.                          (2) Number and String Handling
  49.                               2.1 - Numeric Operators
  50.                               2.2 - Numeric Functions
  51.                               2.3 - String Operators
  52.                               2.4 - String Functions
  53.                               2.5 - String Alterations
  54.  
  55.                          (3) Display and I/O Commands
  56.                               3.1 - Reading Input
  57.                               3.2 - Showing Line Output
  58.                               3.3 - Colorization
  59.                               3.4 - Other Display Commands
  60.  
  61.                          (4) Database & Message Commands
  62.                               4.1 - Database Selection
  63.                               4.2 - LOAD Related Commands
  64.                               4.3 - Editing Commands
  65.                               4.4 - Viewing & Writing
  66.                               4.5 - E-mail Functions
  67.  
  68.                          (5) Buffer Operation & Use
  69.                               5.1 - Buffer Commands
  70.                               5.2 - Buffer Example
  71.  
  72.                          (6) File Commands
  73.                               6.1 - Information Commands
  74.                               6.2 - Transfer Commands
  75.                               6.3 - File Editing
  76.                               6.4 - File Edit Example
  77.  
  78.                          (7) Control Commands
  79.                               7.1 - General Redirection
  80.                               7.2 - Loops & Comparisons
  81.                                     7.21 - DO Loops
  82.                                     7.22 - IF/IFVAL Structures
  83.                                     7.23 - TEST/TESTVAL Commands
  84.                               7.3 - Passing Control
  85.                               7.4 - Control Example
  86.  
  87.                          (8) Miscellaneous Commands
  88.                               8.1 - Visual/Interactive
  89.                               8.2 - User Modifiers
  90.                               8.3 - Real Miscellany
  91.  
  92.                          APPENDIX A - Programmer's Reference Guide
  93.                          APPENDIX B - Common Script Examples
  94.                          APPENDIX C - VGIX Commands
  95.  
  96.                                              VSCRIPT Documentation --  1
  97.  
  98.  
  99.          ╔════════════════════════════════════════════════════════════════╗
  100.          ║  (1) GENERAL VSCRIPT INFORMATION                               ║
  101.          ╚════════════════════════════════════════════════════════════════╝
  102.  
  103.          1.1 - Script Language Introduction
  104.          ══════════════════════════════════
  105.  
  106.                 One of the features that makes VBBS unique is its script
  107.          language compiler - VCOM.EXE.  Along with the built-in command
  108.          interpreter in VBBS, it allows you to make changes to your BBS
  109.          quickly and easily.  The scripts are nothing more than a series
  110.          of commands listed in a plain ASCII text file, and you don't
  111.          even need to be a programmer to write one.  All you need to cre-
  112.          ate scripts are a text editor or word processor that allows you
  113.          to save in ASCII format (see your word processor documentation
  114.          for more info) and a little patience.  In no time, you will be
  115.          writing up scripts and swapping them with other VBBS sysops like
  116.          a pro.
  117.  
  118.  
  119.          1.2 - General Restrictions
  120.          ══════════════════════════
  121.  
  122.                 The VBBS script language has only one major restriction:
  123.          there can only be a total of 7 'tokens' on a line.  A token is
  124.          defined as either a single unspaced series of characters (for
  125.          example, a command or a number) or any group of characters and
  126.          spaces surrounded by single or double quotes (also called a
  127.          "string".)  The script language is NOT case-sensitive; any
  128.          capitalization used in this text is not required and is done
  129.          only for clarity.
  130.  
  131.                 All the scripts that you create should be placed into your
  132.          scripts directory as defined in VCONFIG - PATHS Configuration;
  133.          see VBBS560.DOC for more information on setting your paths.
  134.  
  135.                 The only other restrictions pertain to names.  All of your
  136.          script files MUST have the extension .V and all of your names
  137.          for variables must begin with a '$', e.g., $variable.
  138.  
  139.  
  140.          1.3 - Script Compiler (VCOM.EXE)
  141.          ════════════════════════════════
  142.  
  143.                 The program VCOM.EXE is the compiler that prepares your
  144.          script file for use by VBBS's interpreter.  It takes the script
  145.          file that you have created and builds the two files that VBBS
  146.          actually uses from it.  These two files have the same name as
  147.          the script file but have .LIT and .COD as their extensions.
  148.  
  149.                 Compilation of a script is accomplished by changing to
  150.          your scripts directory and executing the command line:
  151.  
  152.                 VCOM <script name>
  153.  
  154.                                              VSCRIPT Documentation --  2
  155.  
  156.  
  157.          You do not need to use the extension to compile the script.
  158.          The compiler can detect some errors in the script file during
  159.          the compilation.  These errors are predominantly related to the
  160.          commands that 'jump' around within a script.  These commands
  161.          are GO, TEST, TESTVAL, CALL, and BREAK.  If an error is found
  162.          the compiler will abort and you will need to go into your
  163.          script to correct the error.
  164.  
  165.  
  166.          1.4 - Command Format
  167.          ════════════════════
  168.  
  169.                 All commands will be listed in the form:
  170.  
  171.                     Command Name ->  Command Syntax.
  172.                              <description of command here>
  173.  
  174.          The following conventions will be used in all command syntax
  175.          in this document:
  176.  
  177.            COMMAND     - All commands will be in capitals and must be
  178.                          typed in the format shown (see the note below.)
  179.            <label>     - A single word, no quotes or spaces.
  180.            <variable#> - Any variable name (only).
  181.            <number#>   - Any numeric value (only).
  182.            <string#>   - A string value ("aBc 123") or any variable name.
  183.            <value#>    - A numeric value or any variable name that is
  184.                          used to store numeric values.
  185.            <pathfile#> - A legal DOS filename including path information.
  186.                          If the path is excluded it will default to the
  187.                          BBS' main directory.  A variable that stores the
  188.                          correct path/filename info may also be used.
  189.            <filename#> - A legal DOS filename excluding path information.
  190.                          Commands that use this have the path info set
  191.                          automatically.  A variable that has the filename
  192.                          stored in it may also be used.
  193.            <prompt>    - Either a text string or a variable name.  Most
  194.                          of these are optional, so use them only if you
  195.                          want them.
  196.            <relation>  - Any of the following, but see the specific com-
  197.                          mand for verification:
  198.  
  199.                            = Equal to         <> Not equal to
  200.                            > Greater than     >= Greater than or equal to
  201.                            < Less than        <= Less than or equal to
  202.  
  203.            <option>    - The value of this item is command-specific.
  204.            <token#>    - Any single item; see section 1.2 for a complete
  205.                          definition of a token.
  206.  
  207.            Note: If the command name is followed by a '<---' then the
  208.                  syntax for the command is just the command name.
  209.  
  210.                                              VSCRIPT Documentation --  3
  211.  
  212.  
  213.          1.5 - Special Variables/Constants
  214.          ═════════════════════════════════
  215.  
  216.                 The script language contains the following restricted
  217.          variables, which are read-only:
  218.  
  219.            $AGE       - Age of user.
  220.            $ANSI      - Stores the user's current graphics setting.  Set
  221.                         to OFF if using ASCII, ON if using ANSI, and ENH
  222.                         if using PDM's.
  223.            $AVAILABLE - Stores the sysop availability flag. Y if sysop is
  224.                         available, N if not.
  225.            $BAUD      - Stores the user's connect speed.
  226.                         Returns "" if logged into node 0 (or other local
  227.                         node) and returns "CONSOLE" if logged in locally
  228.                         from the WFC screen.
  229.            $BBSNAME   - Stores the BBS' name, as shown in VCONFIG.
  230.            $BELL      - Stores ASCII code 7, causes a beep when printed.
  231.            $BIRTHDATE - User birthdate in same format as $DATE.
  232.            $BS        - Stores ASCII code 8, causes the cursor to back up
  233.                         1 space on current line when printed.  It is not
  234.                         a destructive backspace.
  235.            $CLEAR     - Stores <CTRL>-<L> for ASCII users, stores the ANSI
  236.                         clear screen code for others when printed.
  237.            $<color>   - These nine variables are reserved as color codes:
  238.                         $RED, $BLUE, $CYAN, $GREEN, $YELLOW, $MAGENTA,
  239.                         $WHITE, $BLACK, and $NORM.  See section 3.3 for
  240.                         more info.
  241.            $CR        - Stores ASCII code 13, causes a carriage return
  242.                         when printed (moves to column 1, current line.)
  243.            $CREDITS   - Number of credits user has.
  244.            $CRLF      - Causes both a $CR & $LF when printed (moves to
  245.                         column 1 of the next line.)
  246.            $DATE      - Stores the current system date as MM-DD-YYYY.
  247.            $EXTRAx    - The users extra variables values are stored in
  248.                         $EXTRA1 thru $EXTRA8.  They can be changed with
  249.                         the SETEXTRA command (see section 8.2 for info.)
  250.            $FLAG      - This contains the list of all active general
  251.                         flags of the current user.  Use the INSTR command
  252.                         with $FLAG and you will know if a particular flag
  253.                         is on if the result is non-zero.  You can change
  254.                         the value of a flag with the SETFLAG command (see
  255.                         section 8.2 for info.)
  256.            $HANDLE    - User's handle.
  257.            $LF        - Stores ASCII code 10, causes a linefeed when it's
  258.                         printed (same column position, next line.)
  259.            $MAXTIME   - Maximum minutes per day.
  260.            $NAME      - User's real name.
  261.            $NODE      - Stores your VirtualNET node # as set in VCONFIG.
  262.                         Default is 0 if you are not in VirtualNET.
  263.            $PAGE      - Number of lines to print before pause.
  264.            $PORT      - Returns present channel # of user (not COM port!)
  265.            $SECURITY  - User's security level, 250 and up is considered
  266.                         Co-sysop/Sysop access.  Use TESTVAL and this
  267.                         variable to implement your own security.
  268.  
  269.                                              VSCRIPT Documentation --  4
  270.  
  271.  
  272.            $SYSOP     - Stores the sysop's name as set in VCONFIG.
  273.            $TEXTPATH  - Stores the path to your TXT directory.
  274.            $TIME      - Stores the current system time.
  275.            $TIMELEFT  - Number of minutes left for this session.
  276.            $TIMEON    - Number of minutes on for this session.
  277.            $TIMESON   - Total number of logons for the user.
  278.            $TOTALMIN  - Total number of minutes on since first logon.
  279.            $USER      - User's account number.
  280.            $VIDEOMODE - This stores values similar to $ANSI, only they are
  281.                         #'s instead of words.  Set to 0 if using ASCII, 1
  282.                         if using ANSI, 2 if using PDM's, and 3 if using
  283.                         VGIX.
  284.  
  285.  
  286.          1.6 - Interfacing with VBBS
  287.          ═══════════════════════════
  288.  
  289.                There are only two ways that you can run a script. You can
  290.          either run the script from a function block or LINK to it from
  291.          another script.  The former is covered here and the latter is
  292.          covered in section 7.3 - Passing Control.
  293.  
  294.                 Go into the function block you wish to have run the script
  295.          and add the following line on any but the first two lines in the
  296.          .FB file:
  297.  
  298.            Z 001 2 Scripter
  299.            |  |  |   ^------This is the script name, NO extension.
  300.            |  |  ^----------This is the code to tell VBBS it is running a
  301.            |  |             script
  302.            |  ^-------------This is the SL to be able to use the key (and
  303.            |                run the script.)
  304.            ^----------------This is the key to press at the menu to load
  305.                             and run the script.
  306.  
  307.  
  308.          1.7 - Prepackaged Scripts
  309.          ═════════════════════════
  310.  
  311.          --> IMPORTANT NOTE:  This section is best read after reading
  312.                               through the entire file but is included here
  313.                               to maintain the structure of this document.
  314.                               Do not let the unknown terms interfere with
  315.                               your reading, as they will all be explained
  316.                               elsewhere.
  317.  
  318.                 There are many script authors out in the BBSing community
  319.          that have written all sorts of scripted programs to perform prac-
  320.          tically everything you could ever want.  The most difficult part
  321.          of using a script is knowing how to install it.  What you should
  322.          do first is pull up the script and look for comments that explain
  323.          the script.  Some will contain complete sets of instructions,
  324.          while others will contain no comments at all.  If the script con-
  325.          tains few or no comments, then what you will need to do is:
  326.  
  327.  
  328.                                              VSCRIPT Documentation --  5
  329.  
  330.                 1> Make sure that all EXIT and LINK statements point to
  331.                    FB's or scripts that you actually have. If all else
  332.                    fails you can set all of these statements to EXIT
  333.                    to your main FB file (see VBBS560.DOC for info.)
  334.                 2> Look for any statements that use file commands.  Be
  335.                     sure to change these to valid paths on your system.
  336.                 3> See if the script has any RET lines.  If it does,
  337.                    try to find the CALL statements to the labels that
  338.                    appear a few lines before the RET.
  339.  
  340.          After you have done these steps you will then have the info you
  341.          need to determine how the script should be used.  If the script
  342.          has no EXIT or LINK statements, or the script has a RET line with
  343.          no CALL statement, then you must make the script part of an exis-
  344.          ting one.  The easiest way to do this is to just block-copy the
  345.          entire script in before your final EXIT or LINK statement in your
  346.          script if it has no unmatched RET statements.
  347.  
  348.                 If there is an unmatched RET statement, then installing
  349.          the new script is even easier.  Somewhere in your script you need
  350.          to add a CALL <label> statement with <label> being the label at
  351.          the start of the new script.  Then just add as the last line of
  352.          your script the line '& <script name>'.  You should be able to
  353.          compile and run it at this point.  Just remember, 'Nothing is
  354.          Guaranteed!', so if you have a problem with a script and you
  355.          can't get it to work try to either pick the code apart (if you
  356.          can) or hop onto any VirtualNet BBS that carries a script dis-
  357.          cussion sub and ask a few questions (or a few hundred, as
  358.          needed).  One of the script gurus may be able to help you out,
  359.          and you might even be able to get in touch with the author.
  360.  
  361.  
  362.                                              VSCRIPT Documentation --  6
  363.  
  364.  
  365.          ╔════════════════════════════════════════════════════════════════╗
  366.          ║  (2) NUMBER AND STRING HANDLING                                ║
  367.          ╚════════════════════════════════════════════════════════════════╝
  368.  
  369.  
  370.          2.1 - Numeric Operators
  371.          ═══════════════════════
  372.  
  373.                 VSCRIPT supports the following mathematical operators:
  374.  
  375.                        +  Addition           -  Subtraction
  376.                        *  Multiplication     /  Division
  377.                        ^  Exponentiation
  378.  
  379.          All math commands in the script language are performed from
  380.          left-to-right.  Parentheses can NOT be used in a formula, so
  381.          any math that needs to be done in a hierarchical format must be
  382.          done over more than one line.  Also, remember the restriction
  383.          on 'tokens' - a math symbol counts as a token, so only two math
  384.          operations can be performed on one line.
  385.  
  386.                    Example:                   Results:
  387.                    $a= 2 * 2 + 4              => 4 + 4       => 8
  388.                    $b = $a + 2 / 5            => 10 / 5      => 2
  389.                    $c = $b + 5 - 4            => 7 - 4       => 3
  390.                    $d = 4 / $b ^ 3            => 2 * 2 * 2   => 8
  391.  
  392.  
  393.          2.2 - Numeric Functions
  394.          ═══════════════════════
  395.  
  396.          INT 0 ->  <variable1> = <value2> INT 0
  397.  
  398.                This function takes the number stored in <value2> and
  399.            rounds down to the next lower whole number.  The resulting
  400.            integer is then stored in <variable1>.  Rememebr: negative
  401.            numbers also round down with this function as shown below:
  402.  
  403.                $total = -11.25 INT 0 returns a value of -12, not -11.
  404.  
  405.          SQR 0 ->  <variable1> = <value2> SQR 0
  406.  
  407.                This function returns the square root of the absolute
  408.            value of the number stored in <value2>.  The result is then
  409.            stored in <variable1>.  Note: The absolute value of a number
  410.            equals its positive value, ie absolute of -11 = 11.
  411.  
  412.          RND ->  <variable1> = <value1> RND <value2>
  413.  
  414.                This function generates a random number between the two
  415.            <value>'s.  If <value1> is smaller than <value2> then the
  416.            result will not include either number.  If <value1> is larger
  417.            than <value2> then the result can include either number.
  418.  
  419.                                              VSCRIPT Documentation -- 7
  420.  
  421.  
  422.              Example:                Results:
  423.              $a = 4.15 * 4 + .25     => 16.85
  424.              $b = $a INT 0           => 16
  425.              $c = $b SQR 0           => 4
  426.              $d = $a INT 0 SQR 0     => 4
  427.              $e = $b RND $c          => a random number from 4 to 16
  428.              $f = $c RND $b          => a random number from 5 to 15
  429.  
  430.  
  431.          2.3 - String Operators
  432.          ══════════════════════
  433.  
  434.            & ->  <variable1> = <token3> & <token5> & <token7>
  435.  
  436.                This allows you to link together many variables and strings
  437.            to print as a single variable, effectively adding many tokens
  438.            together. ex: $Junk = "This is" & " one big " & "statement!"
  439.  
  440.  
  441.          2.4 - String Functions
  442.          ══════════════════════
  443.  
  444.                In addition to the '&' operators there are some functions
  445.            for use with strings and variables that store strings.
  446.  
  447.          ASC 0 ->  <variable1> = <string2> ASC 0
  448.  
  449.                This function finds the ASCII code of the first character
  450.            in <string2> and stores it in <variable1>.
  451.  
  452.          CHR 0 ->  <variable1> = <value2> CHR 0
  453.  
  454.                This function takes <value2> and places the character with
  455.            the matching ASCII code into <variable1>.
  456.  
  457.          LEN 0 ->  <variable1> = <string2> LEN 0
  458.  
  459.                This function returns the number of characters within
  460.            <string2> and places the result in <variable1>.
  461.  
  462.          UPPER 0 ->  <variable1> = <string2> UPPER 0
  463.  
  464.                This function returns the upper case equivalent of what is
  465.            in <string2>.  It only changes the lower case letters, leaving
  466.            all numbers and symbols as they are in the original <string2>.
  467.  
  468.          INSTR ->  <variable1> = <string2> INSTR <string3>
  469.  
  470.                This function scans <string2> to see if <string3> exists
  471.            within it.  It returns a 0 to <variable1) if it is not found,
  472.            otherwise it returns the position of <string3>.
  473.  
  474.                                              VSCRIPT Documentation --  8
  475.  
  476.  
  477.          MID   ->  <variable1> = <string2> MID <value3>
  478.          LEFT  ->  <variable1> = <string2> LEFT <value3>
  479.  
  480.                These functions return portions of a string. MID starts
  481.            at the character <value3> and returns the rest of the string.
  482.            LEFT starts at the left-most character and returns a number
  483.            of characters equal to <value3>.
  484.  
  485.            Example:                      Results:
  486.            $a = "aBc2" & "05 D" & "e╫Fg" => "aBc205 De╫Fg"
  487.            $b = $a MID 10                => ╫Fg
  488.            $c = $b ASC 0                 => 215 - the ASCII code for ╫
  489.            $d = $a LEFT 6 MID 4          => 205
  490.            $e = $d CHR 0                 => ═   - the ASCII 205 character
  491.            $f = $a INSTR "205"           => 4   - the 205 is in the string
  492.                                                   and the 2 is located in
  493.                                                   the 4th position.
  494.            $g = $a LEN 0                 => 12
  495.            $h = $a UPPER 0               => "ABC205 DE╫FG"
  496.  
  497.            Note: The quotes in the strings are not an actual part of the
  498.                  strings.  They are there only to denote the beginning
  499.                  and end of a single token.
  500.  
  501.  
  502.          2.5 - String Alterations
  503.          ════════════════════════
  504.  
  505.                There are a few commands that actually allow you to alter
  506.            the format of a variable.  All of them use the same syntax and
  507.            are described below.
  508.  
  509.          JC ->  JC <variable1> <value2>
  510.          JL ->  JL <variable1> <value2>
  511.          JR ->  JR <variable1> <value2>
  512.  
  513.                These commands all take what is stored within <variable1>
  514.            and pad it with extra spaces.  JC centers the <variable1> in
  515.            a field of <value2> spaces.  JL places it along the left margin
  516.            and JR places it on the right margin in a similar field.
  517.  
  518.            Example:                     Results:
  519.            $size = 14
  520.            $a = "Greed!"                => $a now has the value:
  521.            JC $a $size                     "    Greed!    "
  522.            $b = "Green!"                => $b now has the value:
  523.            JL $b $size                     "Green!        "
  524.            $c = "Groan!"                => $c now has the value:
  525.            JR $c $size                     "        Groan!"
  526.  
  527.                                              VSCRIPT Documentation --  9
  528.  
  529.  
  530.          ╔════════════════════════════════════════════════════════════════╗
  531.          ║ (3) INPUT AND OUTPUT COMMANDS                                  ║
  532.          ╚════════════════════════════════════════════════════════════════╝
  533.  
  534.  
  535.          3.1 - Reading Input
  536.          ═══════════════════
  537.  
  538.                One of the most common uses of a script is to get some
  539.            information from a user and the script language contains many
  540.            commands to help implement this task.  All the commands allow
  541.            for a <prompt> string, but this is optional so you do NOT have
  542.            to use it if you do not want to.
  543.  
  544.          GETYN ->  GETYN <variable1> <prompt>
  545.          GETNY ->  GETNY <variable1> <prompt>
  546.  
  547.                These two commands show the user whatever is stored within
  548.            the <prompt> and ask for a response of Y, N, or <enter>.  The
  549.            GETYN command defaults to Y when then user presses <enter> and
  550.            GETNY defaults to N.
  551.            ex: GETYN $yesorno "Do you wish to continue ? "
  552.  
  553.          RS ->  RS <variable1> <prompt>
  554.  
  555.                This command prints the optional <prompt> and then accepts
  556.            a line of input.  The input can be no more than 81 characters
  557.            in length, and input is terminated by pressing <enter>.
  558.            ex: RS $yourname "What is your name ? "
  559.  
  560.          RX ->  RX <variable1> <prompt>
  561.  
  562.                This command works like the RS command but instead of it
  563.            echoing the keys that the user presses it prints X's.  This is
  564.            very useful for password systems.
  565.  
  566.          RW ->  RW <variable1> <prompt>
  567.  
  568.                This command works like the RS command with the only real
  569.            difference being that this command has a word-wrapping feature.
  570.            If a word passes the 80 character point it is word-wrapped over
  571.            to the next input line.  To prevent the extra characters from
  572.            being placed into the next input statement you will need to
  573.            place 'Buffer Clear' after the last RW input line.  See section
  574.            5.x for more info on buffer commands.
  575.  
  576.          RN ->  RN <variable1> <prompt>
  577.  
  578.                This command prints the optional prompt and then accepts
  579.            only numerical input.  It will not take any keys but the #'s
  580.            and input is terminated by pressing <enter>.
  581.            ex: RN $number "Enter your favorite number : "
  582.  
  583.                                              VSCRIPT Documentation -- 10
  584.  
  585.  
  586.          RC ->  RC <variable1> <prompt>
  587.  
  588.                This command prints the optional <prompt> and then waits
  589.            for a single character to be pressed.  The character is stored
  590.            in <variable1> but it is not shown on the screen.
  591.            ex: RC $onechar "Pick a key, any key : "
  592.  
  593.          RR ->  RR <variable1> <string2> <prompt>
  594.  
  595.                This command operates in the same way as the RC command
  596.            with only one difference.  It will only accept characters that
  597.            are listed in the <string2>, all others will be ignored.
  598.            ex: RR $thisone ARI "A>bort, R>etry, I>gnore ? "
  599.  
  600.          RL ->  RL <variable1> <string2> <value3> <prompt>
  601.  
  602.                This command operates similarly to the RR command.  It will
  603.            accept any character listed in <string2> and also will accept a
  604.            number between 1 and <value3>.  This is the most versatile form
  605.            for getting input, and is most commonly used for creating a
  606.            menu within a script.
  607.            ex: RL $thatone ABC 3 "Choose A, B, C, 1, 2, or 3 : "
  608.  
  609.          RF ->  RF <variable1> <prompt>
  610.  
  611.                This command is used to get a filename as input.  It will
  612.            only accept input in the format 'xxxxxxxx.xxx' with each 'x'
  613.            being a character.  It will only allow legal characters for the
  614.            name and it will not accept globals (* and ?.)  The complete
  615.            list of acceptable characters contains A thru Z (uppercase is
  616.            forced automatically) and the symbols => ! # $ _ - (the => is
  617.            not in the list, it is used only for emphasis.)
  618.            ex: RF $filename "Name of file to be uploaded : "
  619.  
  620.          RI ->  RI <variable1> <prompt>
  621.  
  622.                This command is nearly identical to the RF command.  The
  623.            one difference being that this command accepts the * and ?
  624.            globals in the filename.
  625.            ex: RI $filetoget "Name of file to find (* and ? allowed) : "
  626.  
  627.  
  628.  
  629.          3.2 - Showing Line Output
  630.          ═════════════════════════
  631.  
  632.                There are two different ways that you can show output one
  633.            line at a time.  While they are slightly different, both accept
  634.            the same formatting information for their output.
  635.  
  636.          TR ->  TR <token2> <token3> <token4> ... <token7>
  637.          TS ->  TS <token2> <token3> <token4> ... <token7>
  638.  
  639.                These commands can print out up to 6 different tokens using
  640.            a single line.  After the last token on the line is printed the
  641.  
  642.                                              VSCRIPT Documentation -- 11
  643.  
  644.  
  645.            TR command performs a carriage return/linefeed while the TS
  646.            command does not.
  647.  
  648.            The three formatting statements are listed below.
  649.  
  650.            %s ->  %s<number1> <variable2>
  651.  
  652.                Outputs <variable2> in a field of <number1> spaces and then
  653.            left justifies it.
  654.  
  655.            %i ->  %i<number1> <variable2>
  656.  
  657.                Outputs <variable2> in a field of <number1> spaces and then
  658.            right justifies it.
  659.  
  660.            %d ->  %d<number1>.<number2> <value3>
  661.  
  662.                Outputs <value3> with the format ###.## where <number1> and
  663.            <number2> are the ### and the .## respectively.  The left part
  664.            of the output is padded with spaces and the right is padded
  665.            with 0's.  This format uses the absolute value of <value3>, so
  666.            the output is always a positive number.
  667.  
  668.                You can use any numbers within the statements as long as
  669.            you follow the specified syntax.  If the field selected is too
  670.            small for the variable then the output will be chopped down to
  671.            fit it into the field.
  672.  
  673.            Example:                     Results:
  674.            $a = "Green"
  675.            $b = 16.2312
  676.            tr $b " : " %d3.3 $b         => "16.2312 :  16.231"
  677.            tr %s10 $a ":" %i10 $a       => "Green     :     Green"
  678.            ts $b " : "
  679.            tr $a " : The End"           => "162312 : Green : The End"
  680.  
  681.            Note: The quotes are not in the actual output, they are only
  682.                  supplied to emphasize the blank spaces.
  683.  
  684.  
  685.  
  686.          3.3 - Colorization
  687.          ══════════════════
  688.  
  689.                There are three different ways to change color in the
  690.            script language.  All are identical in output, but each has
  691.            a unique form of implementation.  Note: <color code> is the
  692.            number (0-9) or letter (capital A-Z) code that corresponds to
  693.            the colors as listed in the COLORS.TXT file.  Also, the input
  694.            commands from section 3.1 (RS, RW, RX, etc.) will all change
  695.            the color to yellow (color 2) unless the <prompt> has a color
  696.            code within it.
  697.  
  698.                                              VSCRIPT Documentation -- 12
  699.  
  700.  
  701.          ANSIC ->  ANSIC <color code>
  702.  
  703.                This command is executed on a line by itself and changes
  704.            the effective color to that of the selected <color code>.
  705.  
  706.          $<color> ->  Special
  707.  
  708.                The $color commands are actually individual tokens that
  709.            resemble variable names.  As such, they may be included into
  710.            other strings with the '&' command (section 2.3) or used on
  711.            their own in output statements (TR & TS.)
  712.  
  713.                 $<color>   color code      $<color>   color code
  714.                 --------   ----------      --------   ----------
  715.                 $RED           6           $YELLOW        2
  716.                 $BLUE          7           $MAGENTA       B
  717.                 $GREEN         5           $CYAN          1
  718.                 $WHITE         U           $NORM          0
  719.                 $BLACK        n/a
  720.                   
  721.                The command $BLACK makes very dark letters though they may
  722.            be visible, depending on your system configuration.  A common
  723.            use for this is to cover over ANSI music symbols.
  724.  
  725.          Hearts ->  Special
  726.  
  727.                The most frequently used way to change colors is to use
  728.            what has been coined 'Heart-code ANSI.'  The Heart code is the
  729.            ASCII code 3 and can be created in a couple of different ways.
  730.            If your ANSI driver supports the extended ASCII character set
  731.            you can create the 'heart' by pressing the <CTRL> key and the
  732.            <C> key or it can be made by holding down the <ALT> key, then
  733.            press 3 (or 003 or 259) on the number pad and then releasing
  734.            the <ALT> key.  You will have to test this for your particular
  735.            system to see which works for you.  You can also create the
  736.            codes by using the FSE to colorize although this can be a bit
  737.            of work.  Immediately after the 'heart' you place the desired
  738.            <color code> and when the script actually runs, VBBS will show
  739.            the correct color (you will not see the 'heart' or the next
  740.            character after it.)
  741.  
  742.              These -----\_______/ANSIC 6
  743.              three      |       \TR "Hello ! " $handle
  744.              pieces     |
  745.              of code    |_______/$stuff = $red & "Hello ! " & $handle
  746.              all do     |       \TR $stuff
  747.              the exact  |
  748.              same thing-+-------<TR "<heart>6Hello ! " & $handle
  749.  
  750.                                              VSCRIPT Documentation -- 13
  751.  
  752.  
  753.          3.4 - Other Display Commands
  754.          ════════════════════════════
  755.  
  756.          EF ->  EF <pathfile1>
  757.  
  758.                This command displays the contents of the specified file
  759.            in <pathfile1>.  It will pause whenever the users screen fills
  760.            and continue when a key is pressed.
  761.  
  762.          DRAWWAITBAR ->  DRAWWAITBAR <value1>
  763.  
  764.                This command draws a string of green o's surrounded by red
  765.            []'s. The number of o's is equal to <value1>.  The cursor is
  766.            then placed on the first 'o' so you can write over it with
  767.            another character.  See section 7.4 for an example.
  768.  
  769.          LOC ->  LOC <value1> <value2>
  770.  
  771.                This command places the cursor at the location equal to the
  772.            (x, y) coordinates that match (<value2>, <value1>).  Legitimate
  773.            values for <value1> are 1-25 and for <value2> are 1-80. This
  774.            only operates for users of ANSI, Enhanced ANSI, and VGIX.
  775.  
  776.          MENU ->  MENU <filename1>
  777.  
  778.                This command displays a menu file stored in your text
  779.            directory (as set in VCONFIG.)  VBBS first checks to see if
  780.            <filename>.MNU exists, and shows it if true.  Otherwise it
  781.            shows <filename>.ANS if the user has ANSI and <filename>.ASC
  782.            otherwise.
  783.  
  784.                The .MNU files are universal text files colorized with
  785.            VBBS' heart-code ANSI colors.  If the user has ANSI then the
  786.            file displays w/ the colors, but if the user does not have
  787.            ANSI then it is displayed without the colors.  You can still
  788.            use .ANS and .ASC menus if you like, however.
  789.  
  790.                If ! is the first character of a line in a menu then VBBS
  791.            will only show the line if the user's security level is greater
  792.            than or equal to the three-digit number that follows the '!'.
  793.  
  794.            Examples:
  795.            !255 S) SysOp Menu  <== Not shown unless the user has SL >= 255.
  796.            !100 F) Forward     <==  "    "     "     "   "    "   " >= 100.
  797.  
  798.          NEWPAGE <---
  799.          SUSPENDPAGEBREAK <---
  800.          RESUMEPAGEBREAK <---
  801.  
  802.                These three commands alter the user's page-break pointer.
  803.            This pointer determines how many lines of text have been viewed
  804.            and the user's screen length (as set in defaults) determines
  805.            when a pause should be used.  NEWPAGE resets the pointer to 0
  806.            so the output will scroll for a number of lines equal to the
  807.            value set in the user's defaults.  SUSPENDPAGEBREAK turns the
  808.  
  809.                                              VSCRIPT Documentation -- 14
  810.  
  811.  
  812.            use of the pointer off completely (no pauses at all), while
  813.            RESUMEPAGEBREAK turns the pointer back on.
  814.  
  815.          PAUSE ->  PAUSE <prompt>
  816.  
  817.                This displays the optional <prompt> or the default prompt
  818.            as set in VCONFIG.  It then waits for a keypress and erases
  819.            the prompt before continuing.
  820.  
  821.                                              VSCRIPT Documentation -- 15
  822.  
  823.  
  824.          ╔════════════════════════════════════════════════════════════════╗
  825.          ║ (4) DATABASE OPERATIONS                                        ║
  826.          ╚════════════════════════════════════════════════════════════════╝
  827.  
  828.  
  829.                Each database (DB) in VBBS can be used in many different
  830.            ways for storing info.  A DB can store normal messages, file
  831.            descriptions, or even messages with attached files. Also, there
  832.            is no reason why you can't redefine the fields and use them for
  833.            other types of data storage, like a special voting booth or
  834.            customized daily news section.
  835.  
  836.                Each DB entry is made up of two parts - The Header and the
  837.            Memo Section. The Header contains things like the subject, the
  838.            sender's name, addressee, etc. The Memo Section is the actual
  839.            body of the entry.  The body, while always text, may contain
  840.            either a standard message or a long file description, depending
  841.            on how you are using the database.
  842.  
  843.  
  844.          4.1 - Database Selection
  845.          ════════════════════════
  846.  
  847.                Before you can implement any database commands you must
  848.            first select the exact database you wish to use.  This is done
  849.            with the commands DBGROUP and DB.  You must use the commands
  850.            in the order shown for proper results.
  851.  
  852.           DBGROUP ->  DBGROUP <group identifier>
  853.  
  854.                This selects the database group that you will be using in
  855.            the script.  The <group identifier> is the letter representing
  856.            the DBG as it appears in VCONFIG.  See VBBS.DOC for more info.
  857.            ex: DBGROUP A     <-- This makes DBGroup A the active area.
  858.  
  859.                Before you can select a database to use, you must first
  860.            select a database group.  Grouping was implemented so that it
  861.            would be much easier to implement global functions and so that
  862.            databases may be added and deleted (using VCONFIG.EXE) without
  863.            the need to edit the scripts every time.  The <group identifier>
  864.            is a single alphabetic character (from A to Z) and you can set
  865.            your database groups up any way you like.  A common set of DB
  866.            Groups might be:
  867.            <A> Public message bases    <H> Hidden/restricted message bases
  868.            <F> Public file bases       <I> Hidden/restricted file bases
  869.            <O> Special bases like voting sections, daily news, etc.
  870.  
  871.            The following read-only variables are loaded when you execute
  872.            the DBGROUP command:
  873.            --------------------
  874.            $DBNUMBER - Stores the total number of databases in the selected
  875.                        group.  The lowest numbered DB in a group is always
  876.                        a 1, so this number supplies the upper limit for
  877.                        loop operations within a database group.
  878.  
  879.                                              VSCRIPT Documentation -- 16
  880.  
  881.  
  882.            $DBGROUP  - This stores the letter you selected on the DBGROUP
  883.                        command line. Note: This variable is not cleared
  884.                        when you LINK to another script (see section 7.3),
  885.                        so this can be used to keep track of your location.
  886.            --------------------
  887.  
  888.          DB ->  DB <database number>
  889.  
  890.                The DB commands sets the current database for use. You
  891.            must select a database using this command somewhere in your
  892.            script before any of the other database commands (except
  893.            DBGROUP) are used. Once you set the database, it stays set
  894.            until another DB command is executed. Also, the database must
  895.            have been defined previously using VCONFIG.EXE.
  896.  
  897.            The following read-only variables are loaded when you execute
  898.            the DB command:
  899.            --------------------
  900.            $DB       - This stores the database number you have selected.
  901.                        Like $DBGROUP it is not cleared when you LINK
  902.                        between scripts and so using the two variables you
  903.                        can maintain a constant position within your DBs.
  904.            $DBNAME   - The long name of the selected database.
  905.            $DBPATH   - The path (if any) in the 'File Path' section of the
  906.                        VCONFIG Database entry.
  907.            $DBFILE   - The filename of the actual database storage file.
  908.            $HIGHDB   - This is the pointer that stores the number of the
  909.                        user's highest-read entry in the database.
  910.            $NUMBERDB - This stores the total number of entries in the
  911.                        database.
  912.            $WRITESL  - This contains the minimum security level needed to
  913.                        write to the database.
  914.            --------------------
  915.  
  916.  
  917.          4.2 - LOAD Related Commands
  918.          ═══════════════════════════
  919.  
  920.                All of the commands in this section require the use of the
  921.            LOAD command before they can be implemented.  The LOAD command
  922.            will be described in this section to maintain clarity.
  923.  
  924.          LOAD ->  LOAD <value1> <option>
  925.  
  926.                This command loads the database entry <value1> and has
  927.            one command <option>. Adding /Q to the command line will set
  928.            it so the user's $HIGHDB pointer is not updated. The command
  929.            also loads the following variables:
  930.            --------------------
  931.            $ATTFILE  - Filename of a file that is attached to the message,
  932.                        if any.
  933.            $DBCOUNT  - This variable can be used to count replies, # of
  934.                        downloads, or any other desired purpose. The value
  935.                        starts at 0 and can be increased by using the
  936.                        ADDCOUNT command (see below)
  937.  
  938.                                              VSCRIPT Documentation -- 17
  939.  
  940.  
  941.            $DBDATE   - Creation date and time of the entry.
  942.            $DBFLAG   - This variable can be used as a message received flag
  943.                        or any other desired purpose.  The value can have a
  944.                        value of 0 or 1 and can be toggled with the DBFLAG
  945.                        command (see below)
  946.            $FROM     - The handle of the person who created the entry.
  947.            $FROMNO   - The user # of the person who created the entry.
  948.            $FROMNODE - VirtualNET node number of sender.
  949.            $SIZE     - Size of attached file, set to 0 if none.
  950.            $SUBJECT  - The subject of the message, or brief description for
  951.                        a file.
  952.            $TO       - The handle of the addressee, if any.
  953.            $TONO     - The user # of the addressee, 0 if to ALL.
  954.            $TONODE   - VirtualNET node number of addressee.
  955.            $RESULT   - This variable contains one of these items:
  956.                          DEL if <value1> is marked for deletion
  957.                          OUT if <value1> is greater than the number of
  958.                              available entries (listed in $NUMBERDB)
  959.                          PRI if the DB is private and the user is not
  960.                              the sender, addressee, or has an SL below
  961.                              250 (ie Sysop or CoSysop)
  962.                          OK  in all other cases
  963.            --------------------
  964.  
  965.          ADDCOUNT ->  ADDCOUNT <value1>
  966.  
  967.                This command increases the number stored in the $DBCOUNT
  968.            for the entry <value1>.
  969.  
  970.          DBFLAG ->  DBFLAG <value1> <switch>
  971.  
  972.                This command toggles the value stored in $DBFLAG for the
  973.            entry <value1>.  The valid switches are ON or OFF and the
  974.            matching $DBFLAG values are 1 and 0, respectively.
  975.  
  976.          DISPLAYMSG <---
  977.  
  978.                This command displays the message header info to the user.
  979.            It will clear the screen before showing this info if the user
  980.            is using enhanced ANSI (see VBBS560.DOC for more info.)
  981.  
  982.          DISPLAYTEXT <---
  983.  
  984.                This command displays the memo section of the message to
  985.            the user.  It clears the screen like DISPLAYMSG for enhanced
  986.            ANSI users.
  987.  
  988.                                              VSCRIPT Documentation -- 18
  989.  
  990.  
  991.          SEARCH ->  SEARCH <value1> <number2> <string3>
  992.  
  993.                This command searches the contents of the database for
  994.            <string3> starting at the entry <value1>. The <number2> can
  995.            be any of the following:
  996.                          1 - Search the TO field
  997.                          2 - Search the FROM field
  998.                          3 - Search the SUBJECT field
  999.                          4 - Search the FILENAME field (allows wildcards)
  1000.                          5 - Search the FILENAME field (no wildcards)
  1001.            This command also returns two variables:
  1002.            --------------------
  1003.            $RESULT = OUT if <string3> is not found, OK otherwise.
  1004.            $SEARCH = the entry number where <string3> was found.
  1005.            --------------------
  1006.  
  1007.  
  1008.          4.3 - Editing Commands
  1009.          ══════════════════════
  1010.  
  1011.                All of these commands operate independently of the LOAD
  1012.            command.  They do still require you to select a DBGROUP and DB
  1013.            before use, however.
  1014.  
  1015.          CLEANUP <---
  1016.  
  1017.                This performs the PACK function (below) on all databases.
  1018.  
  1019.          DEL ->  DEL <value1>
  1020.  
  1021.                This command marks the entry <value1> for deletion.  It
  1022.            also returns the $RESULT variable with the possible values
  1023.            being OUT, PRI, and OK (see LOAD entry above.)
  1024.  
  1025.          PACK <---
  1026.  
  1027.                This command deletes all messages within the selected DB
  1028.            that have been marked for deletion and then resequences the
  1029.            database.  All user and network pointers are automatically
  1030.            updated to show the change in message numbers.
  1031.  
  1032.          QS ->  QS <value1>
  1033.  
  1034.                Manually set the user's $HIGHDB pointer to <value1>. If
  1035.            <value1> exceeds the value in $NUMBERDB then $HIGHDB is set
  1036.            to equal $NUMBERDB.
  1037.  
  1038.  
  1039.                                              VSCRIPT Documentation -- 19
  1040.  
  1041.  
  1042.          SAVE -> (command on next line due to length)
  1043.          SAVE <value1> <value2> <string3> <value4> <filename5> <value6>
  1044.  
  1045.                This command makes a database entry and saves it in the
  1046.            current database.  The variables used are:
  1047.            --------------------
  1048.            <value1>    - This is the user # that the message is addressed
  1049.                          to, this should be set to 0 if to ALL.
  1050.            <value2>    - This is the network address of the addressee,
  1051.                          use $NODE if the addressee is local.
  1052.            <string3>   - This will be the $SUBJECT of the saved message.
  1053.            <value4>    - This contains the size of the attached file, use
  1054.                          0 if none.
  1055.            <filename5> - This is the name of the attached file, use "" if
  1056.                          none.
  1057.            <value6>    - This is the network ID of the addressee, use 1 if
  1058.                          the addressee is local.
  1059.            --------------------
  1060.  
  1061.                The message saved uses the above information to create the
  1062.            header and then takes the contents of the buffer and uses it as
  1063.            the main body of the message.  See section 5.x for information
  1064.            on how to use the buffer.
  1065.  
  1066.  
  1067.          4.4 - Viewing & Writing
  1068.          ═══════════════════════
  1069.  
  1070.                These commands allow the user to view messages and move
  1071.            around within your databases.
  1072.  
  1073.          LISTBASES <---
  1074.  
  1075.                This lists all the DB's in the current DBGroup.
  1076.  
  1077.          NEXTBASE <---
  1078.          PREVBASE <---
  1079.  
  1080.                These commands move to the next or previous database within
  1081.            the selected DBGroup, respectively.
  1082.  
  1083.          POST <---
  1084.  
  1085.                This lets the user to enter a message into the active DB.
  1086.  
  1087.          READSEQMSG <---
  1088.  
  1089.                This command allows the user to read the messages within
  1090.            the current database.  It also contains a search feature.
  1091.  
  1092.          READNEWMSG <---
  1093.  
  1094.                This starts the user's new message scan, showing all new
  1095.            messages in databases that are in the user's quick-scan list.
  1096.  
  1097.                                              VSCRIPT Documentation -- 20
  1098.  
  1099.  
  1100.          SELECTBASE <---
  1101.  
  1102.                This command lists all the bases and then allows the user
  1103.            to select a different DB as the current one.  The user can
  1104.            also switch to a different DBGroup with this command.
  1105.  
  1106.          SETQUICKSCAN <---
  1107.  
  1108.                This command allows the user to select what databases he or
  1109.            she would like to view during a new message scan.
  1110.  
  1111.  
  1112.          4.5 - E-mail Functions
  1113.          ══════════════════════
  1114.  
  1115.                The E-mail section of the database structure is a separate
  1116.            entity.  To make it the active database for using the SAVE
  1117.            and BUFFER commands you need to execute the following command:
  1118.  
  1119.          SETEMAIL <---
  1120.  
  1121.               This command is used instead of the DBGROUP & DB commands to
  1122.            make the e-mail section the active database for use with BUFFER
  1123.            and SAVE (see sections 5.x and 4.3, respectively.)
  1124.  
  1125.          FEEDBACK <---
  1126.  
  1127.                This brings up the multi-feedback list (see VBBS560.DOC)
  1128.            and prompts the user to send a message to the sysop.
  1129.  
  1130.          READALLEMAIL <---
  1131.  
  1132.                This is a sysop command that allows you to read ALL E-mail
  1133.            currently in the system.
  1134.  
  1135.          READEMAILFROM <---
  1136.          READEMAILTO <---
  1137.  
  1138.                These commands allow the user to read all the E-mail FROM
  1139.            them or addressed TO them, respectively.
  1140.  
  1141.          SENDEMAIL <---
  1142.  
  1143.                This command allows the user to send E-mail to other users.
  1144.  
  1145.                                              VSCRIPT Documentation -- 21
  1146.  
  1147.  
  1148.          ╔════════════════════════════════════════════════════════════════╗
  1149.          ║ (5) BUFFER OPERATION & USE                                     ║
  1150.          ╚════════════════════════════════════════════════════════════════╝
  1151.  
  1152.  
  1153.                In order to accommodate larger memo sizes VBBS uses a disk
  1154.            file buffer in the format Bx.TMP, where x is the channel number
  1155.            that the user is on.  This file is stored in the \VBBS dir.
  1156.  
  1157.          5.1 - Buffer Commands
  1158.          ═════════════════════
  1159.  
  1160.          BUFFER APPEND ->  BUFFER APPEND <string1>
  1161.  
  1162.                This adds <string1> to the present buffer.
  1163.  
  1164.          BUFFER CLEAR <---
  1165.  
  1166.                This erases the contents of the present buffer.
  1167.  
  1168.          BUFFER EDIT <---
  1169.  
  1170.                This command loads up the user's selected editor and puts
  1171.            the current contents of the buffer into it.  Note:  When using
  1172.            the full-screen editor the user can edit, add, or clear the
  1173.            buffer.  The line editor will only allow you to add lines to
  1174.            the current buffer or clear it.  The user can clear the buffer
  1175.            by aborting out of either editor with /A.
  1176.  
  1177.          BUFFER LIST <---
  1178.  
  1179.                This prints the current buffer contents to the screen. If
  1180.            the user is in ASCII mode then heart-code ANSI is stripped out
  1181.            of the buffer.
  1182.  
  1183.  
  1184.          5.2 - Buffer Example
  1185.          ════════════════════
  1186.  
  1187.            !==============================================================
  1188.            ! EMAIL.V   This sends an E-mail to the Sysop.  To do this we
  1189.            !           create a form letter in the buffer and then write
  1190.            !           the buffer contents to an E-mail addressed to the
  1191.            !           Sysop #1 account.  Note the '!' are comment lines.
  1192.            !
  1193.            !                     Create the form letter
  1194.            $Line1 = $Sysop & ","
  1195.            $Line2 = "  I'm a new user and would really appreciate it"
  1196.            $Line3 = "if you would validate my account."
  1197.            $Line4 = "  Thanks!"
  1198.            $Line5 = "     " & $Handle
  1199.            !                     Clear out any existing buffer contents
  1200.            Buffer Clear
  1201.            !                     Write the text lines to the Buffer
  1202.            Buffer Append $Line1
  1203.  
  1204.                                              VSCRIPT Documentation -- 22
  1205.  
  1206.  
  1207.            Buffer Append $Line2
  1208.            Buffer Append $Line3
  1209.            Buffer Append $Line4
  1210.            Buffer Append $Line5
  1211.            !                     Position to the E-mail database
  1212.            SetEmail
  1213.            !                     Save the buffer as E-mail to the sysop #1
  1214.            Save 1 $Node "Validation Request" 0 "" 1
  1215.            !                     Clear out the buffer again
  1216.            Buffer Clear
  1217.            !==============================================================
  1218.  
  1219.                                              VSCRIPT Documentation -- 23
  1220.  
  1221.  
  1222.          ╔════════════════════════════════════════════════════════════════╗
  1223.          ║ (6) FILE COMMANDS                                              ║
  1224.          ╚════════════════════════════════════════════════════════════════╝
  1225.  
  1226.          ╔════════════════════════════════════════════════════════════════╗
  1227.          ║** Note: The commands DLMASTERLIST, SEARCHALL, REVIEUPLOADS,  **║
  1228.          ║**       FINDFILES, and NEWFILES will only work properly if   **║
  1229.          ║**       implemented from within a script that is called from **║
  1230.          ║**       your FILES.FB (or equivalent).  They take the letter **║
  1231.          ║**       for the DBGroup to use from the second line of the   **║
  1232.          ║**       .FB the script was called from.  The DBGROUP and DB  **║
  1233.          ║**       commands have no effect on these five commands. <LD> **║
  1234.          ╚════════════════════════════════════════════════════════════════╝
  1235.  
  1236.          6.1 - Information Commands
  1237.          ══════════════════════════
  1238.  
  1239.          CHECKFILE ->  CHECKFILE <variable1> <pathfile2>
  1240.  
  1241.                This command checks to see if <pathfile2> exists on your
  1242.            system and places the file size into <variable1>.  It returns
  1243.            a 0 if the file does not exist.
  1244.  
  1245.          FINDFIRST ->  FINDFIRST <variable1> <pathfile2>
  1246.          FINDNEXT ->  FINDNEXT <variable1>
  1247.  
  1248.                These commands search for the file mask <patfile2>. It may
  1249.            include globals and will default to the \VBBS directory if no
  1250.            path is specified.  You must execute FINDFIRST once before you
  1251.            can use the FINDNEXT command.  Both commands will return the
  1252.            full filename to <variable1> or a "" if no match is found.
  1253.  
  1254.          FINDFILES <---
  1255.  
  1256.                This asks the user for search text and asks if the user
  1257.            would like to search all topic areas.  It then searches all the
  1258.            files in the selected DBGroup(s) and searches the descriptions
  1259.            for those that contain the search text.
  1260.  
  1261.          LISTFILES <---
  1262.  
  1263.                This prompts for a filename (wildcards accepted) and then
  1264.            lists all matching files in the current database.
  1265.  
  1266.          NEWFILES <---
  1267.  
  1268.                This command asks the user would like to scan all topic
  1269.            areas and then lists all new files in the selected DBGroup(s).
  1270.  
  1271.          RATIO <---
  1272.  
  1273.                This displays the user's upload/download ratio.
  1274.  
  1275.  
  1276.                                              VSCRIPT Documentation -- 24
  1277.  
  1278.  
  1279.          REVIEWFILE <---
  1280.  
  1281.                This command allows the user to review any of the files in
  1282.            the current database.  They can they be downloaded or tagged
  1283.            for a batch download later.
  1284.  
  1285.          REVIEWUPLOADS <---
  1286.  
  1287.                This command allows the sysop to review all new files that
  1288.            have been uploaded by users.
  1289.  
  1290.  
  1291.          SEARCHALL <---
  1292.  
  1293.                This works like LISTFILES, but also allows the user to
  1294.            search all topic areas.  It then lists the matching files in
  1295.            the selected DBGroup(s).
  1296.  
  1297.          TOPDOWNLOADS <---
  1298.  
  1299.                This lists the top downloads in the active file DBGroup.
  1300.  
  1301.          XFERTIME ->  XFERTIME <variable1> <pathfile2>
  1302.  
  1303.                This command will calculate how long it will take to
  1304.            download <pathfile2> and stores it in <variable1>.  It will
  1305.            return a 0 if the file is not found.
  1306.  
  1307.  
  1308.          6.2 - Transfer Commands
  1309.          ═══════════════════════
  1310.  
  1311.          ╔═══════════════════════════════════════════════════════════════╗
  1312.          ║**   Note: To use the file transfer commands, you must have  **║
  1313.          ║**         DSZ.COM, an external protocol driver. DSZ version **║
  1314.          ║**         04-11-90 or newer is recommended!                 **║
  1315.          ╚═══════════════════════════════════════════════════════════════╝
  1316.  
  1317.          BATCHDL <---
  1318.  
  1319.                This command brings up the batch transfer menu.
  1320.  
  1321.          DLMASTERLIST <---
  1322.  
  1323.                This command allows the user to download a zipped listing
  1324.            of your entire transfer section.
  1325.  
  1326.          DOWNLOAD ->  DOWNLOAD <pathfile1>
  1327.  
  1328.                This prompts the user to choose an xfer protocol and then
  1329.            sends the file <pathfile1>.
  1330.  
  1331.  
  1332.                                              VSCRIPT Documentation -- 25
  1333.  
  1334.  
  1335.          DOWNLOADFILE <---
  1336.  
  1337.                This command prompts for a filename (it accepts wildcards)
  1338.            and then show the user the file's review screen.  The user can
  1339.            then download directly or tag for a batch download.
  1340.  
  1341.          REMOTEUPLOAD <---
  1342.  
  1343.                This allows the user to upload files to the BBS.
  1344.  
  1345.          SYSOPUPLOAD <---
  1346.  
  1347.                This command allows the sysop to upload files locally.
  1348.  
  1349.          UPLOAD ->  UPLOAD <pathfile1>
  1350.  
  1351.                This command prompts the user to choose a protocol and
  1352.            then receives <pathfile1> from the user.  A full path may be
  1353.            used, but is not necessary.
  1354.  
  1355.  
  1356.          6.3 - File Editing
  1357.          ══════════════════
  1358.  
  1359.                VSCRIPT allows you to directly read and write from pure
  1360.            ASCII text files.  The commands to do so are listed here.
  1361.            Note: You must always OPEN a file before performing any of the
  1362.                  other commands and CLOSE it when done, except as noted.
  1363.  
  1364.          EDITFILE <---
  1365.  
  1366.                This allows the sysop to edit any text file with no more
  1367.            than 200 lines.  This is one exception to the OPEN and CLOSE
  1368.            rule, you should not use either with this command.
  1369.  
  1370.          CLOSE <---
  1371.  
  1372.                This closes a file previously opened with OPEN.
  1373.  
  1374.          KILL ->  KILL <pathfile1>
  1375.  
  1376.                This deletes <pathfile1> off of your system.  This is the
  1377.            other exception to the OPEN and CLOSE rule, you should not use
  1378.            either with this command.
  1379.  
  1380.          OPEN ->  OPEN <pathfile1> <option>
  1381.  
  1382.                This command opens a file for use.  One of the following
  1383.            three options must be selected on the command line:
  1384.  
  1385.                 INPUT -> This allows you to READ data in from a file
  1386.                 OUTPUT -> This allows you to create a file and begin
  1387.                           to WRITE new information into it.
  1388.                 APPEND -> This allows you to open an existing file and
  1389.                           WRITE information onto the end of it.
  1390.  
  1391.                                              VSCRIPT Documentation -- 26
  1392.  
  1393.  
  1394.          READ ->  READ <variable1>
  1395.  
  1396.                This will read in a single line from the file and place it
  1397.            into <variable1>.  Multiple READ statements will continue to
  1398.            read in the next line in the file and if the end of the file is
  1399.            reached it will return an !EOF!.  The only way to start at the
  1400.            top of a file again is to CLOSE it and then OPEN it again.
  1401.  
  1402.          WRITE ->  WRITE <token2> <token3> <token4> ... <token7>
  1403.  
  1404.                This command performs exactly like the TR command in
  1405.            section 3.2 with the only difference being that the output
  1406.            goes into a file instead of on screen.
  1407.  
  1408.          6.4 - File Editing Example
  1409.          ══════════════════════════
  1410.  
  1411.            !==============================================================
  1412.            !  READ.V - Some examples of writing and reading from the
  1413.            !           buffer file.
  1414.            !
  1415.            $Where = $port                        ! this selects the buffer
  1416.            $File = "c:\vbbs\b" & $where & ".tmp" ! for the node you're on
  1417.            !
  1418.            !  Check to see if the file is there; if so, delete it.
  1419.            CHECKFILE $Len $File
  1420.            IFVAL $Len > 0 Then
  1421.               KILL $File
  1422.            ENDIF
  1423.            !  Build an new one, add one line, then close it.
  1424.            OPEN $File OUTPUT
  1425.               WRITE "Your Handle : " $handle
  1426.            CLOSE
  1427.            !  Now open it, add data to the end of it, then close it again.
  1428.            OPEN $File APPEND
  1429.               WRITE "The BBSName : " $bbsname
  1430.               WRITE "Your Baud Rate : " $baud
  1431.               WRITE "The Sysop's Name : " $sysop "  and the time : " $time
  1432.            CLOSE
  1433.            !  Now re-open it, read the data back, print it, and close it.
  1434.            OPEN $File INPUT
  1435.            # Tag
  1436.               READ $Line
  1437.               TEST $Line = "!EOF!" End
  1438.               TR $Line
  1439.               GO Tag
  1440.            # End
  1441.            !  Now close and remove the file
  1442.            CLOSE
  1443.            KILL $File
  1444.            !==============================================================
  1445.  
  1446.                 With very little work you could actually write an editor
  1447.            using the combination of the BUFFER commands and the commands
  1448.            above.  The options are limitless once you set your mind to it.
  1449.  
  1450.                                              VSCRIPT Documentation -- 27
  1451.  
  1452.  
  1453.          ╔════════════════════════════════════════════════════════════════╗
  1454.          ║ (7) CONTROL COMMANDS                                           ║
  1455.          ╚════════════════════════════════════════════════════════════════╝
  1456.  
  1457.  
  1458.          7.1 - General Redirection
  1459.          ═════════════════════════
  1460.  
  1461.          # ->  # <label>
  1462.  
  1463.                This command allows you to set points up within your script
  1464.            that the various other control commands can use.
  1465.                    ex:  TR "Hello "
  1466.                         GO skipit
  1467.                         TR "You wont see this text..."
  1468.                         # skipit
  1469.                         TR "Because you just jumped down to here!!"
  1470.  
  1471.          CALL ->  CALL <label>
  1472.  
  1473.                This forces the script to go to <label> and continue to
  1474.            run from there.  When a RET is found the script will go back
  1475.            to the line after the CALL command.
  1476.  
  1477.          GO ->  GO <label>
  1478.  
  1479.                This forces the script to go to <label> just like the CALL
  1480.            command, with the only difference being that it will not return
  1481.            if it encounters an RET statement.
  1482.  
  1483.          RET <---
  1484.  
  1485.                This returns a script from a routine CALLed to the line
  1486.            after the CALL statement.  Note: RET is ignored if there was
  1487.            no CALL statement used.
  1488.  
  1489.  
  1490.          7.2 - Loops and Comparisons
  1491.          ═══════════════════════════
  1492.  
  1493.                VSCRIPT supports some of the more common forms of loops
  1494.            and comparison structures.  These are all covered here.
  1495.  
  1496.          7.21 - DO Loops
  1497.          ───────────────
  1498.  
  1499.          ->  DO <variable1> = <value2> <value3>
  1500.                   [body of the loop]
  1501.              LOOP
  1502.  
  1503.                This type of loop begins with <variable1> equal to
  1504.            <value2>.  Each time it reaches the LOOP it adds 1 to it
  1505.            and continues until <variable1> is greater than <value3>.
  1506.  
  1507.                                              VSCRIPT Documentation -- 28
  1508.  
  1509.  
  1510.          ->  DO WHILE <variable1>   {must store a numeric!}
  1511.                   [body of the loop]
  1512.              LOOP
  1513.  
  1514.                This type continues to loop until <variable1> = 0. You
  1515.            must have some way to either exit the loop, or have a place
  1516.            where <variable1> is set to 0 or the script will lock into an
  1517.            endless loop.
  1518.  
  1519.  
  1520.          7.22 - IF/IFVAL Structures
  1521.          ──────────────────────────
  1522.  
  1523.                IF stuctures allow you to compare 2 strings to see if they
  1524.            match, valid <relation> operators are = and <> ONLY! The IFVAL
  1525.            structures are identical to IF structures, but they are used to
  1526.            compare numeric variables.  Valid IFVAL <relations> are =, >,
  1527.            >=, <, <= and <>.
  1528.  
  1529.          ->  IF <variable1> <relation> <variable2> THEN
  1530.                   [then-code]
  1531.              ENDIF
  1532.  
  1533.                This performs the [then-code] if <relation> is true.
  1534.  
  1535.          ->  IF <variable1> <relation> <variable2> THEN
  1536.                   [then-code]
  1537.              ELSE
  1538.                   [else-code]
  1539.              ENDIF
  1540.  
  1541.                This performs similar to the IF structure, but if the
  1542.            <relation> is false it performs the [else-code].
  1543.  
  1544.  
  1545.          7.23 - TEST/TESTVAL Commands
  1546.          ────────────────────────────
  1547.  
  1548.          ->  TEST <variable1> <relation> <variable2> <label>
  1549.          ->  TESTVAL <variable1> <relation> <variable2> <label>
  1550.  
  1551.                The two TEST commands allow you to compare two variables,
  1552.            and if the comparison is true, to go to a separate part of the
  1553.            script (as if a GO <label> had been used.)  The only difference
  1554.            in the two commands is that TEST performs a non-case-sensitive
  1555.            string comparison and TESTVAL performs a mathematic comparison.
  1556.            Valid <relations> are =, <, <=, >, >= and <>.
  1557.  
  1558.  
  1559.          7.3 - Passing Control
  1560.          ═════════════════════
  1561.  
  1562.                There are a total of four ways that you can pass control
  1563.            from a script to something else.  These four ways each have
  1564.            special uses and are covered below.
  1565.  
  1566.                                              VSCRIPT Documentation -- 29
  1567.  
  1568.  
  1569.                Note: These commands will only accept one token following
  1570.                      the actual command.  If you wish to have more items
  1571.                      on the line then you must place them into a variable
  1572.                      and place the variable on the command line.
  1573.                      ex: $doscom = "dir " & $pathused & " /w"
  1574.                          SHELL $doscom
  1575.  
  1576.          LINK ->  LINK <filename>
  1577.  
  1578.                This command causes the present script to terminate and
  1579.             begin running a script called <filename> (do not use any
  1580.             extension or globals in the filename.)  All of your
  1581.             variables will be cleared before the new script begins
  1582.             operation.
  1583.  
  1584.          EXIT ->  EXIT <filename>
  1585.  
  1586.                This command causes the present script to terminate and
  1587.             then exits to the function block <filename> (as with LINK,
  1588.             do not use extensions or globals.)  If no <filename> is
  1589.             specified then the script will exit to the .FB file that
  1590.             it was called from UNLESS the script did a shrinkout (see
  1591.             DOOR, below) in which case it will always exit to START.FB.
  1592.  
  1593.          SHELL ->  SHELL <pathfile or DOS command line>
  1594.  
  1595.                This will drop to DOS while keeping the BBS in memory.
  1596.             It will then execute the command following SHELL and then
  1597.             return to the line after the SHELL command.  All of your
  1598.             variables are retained because the script is never taken
  1599.             from memory.
  1600.  
  1601.          DOOR ->  DOOR <pathfile or DOS command line>
  1602.  
  1603.                This will shrink the BBS out of memory and drop to DOS.
  1604.             Implementation of the DOOR command writes the dropfiles
  1605.             CHAIN.TXT, DOOR.SYS and DORINFOx.DEF to disk.  If nothing
  1606.             else is specified on the command line then the script will
  1607.             bring up your list of Doors as set in VCONFIG; otherwise it
  1608.             will execute the required command line.  When the door has
  1609.             finished running it will return to the first line of the
  1610.             script.  All of your variables will be cleared by the DOOR
  1611.             command.  See VBBSDOOR.DOC for more info on doors.
  1612.  
  1613.                                              VSCRIPT Documentation -- 30
  1614.  
  1615.  
  1616.          7.4 - Control Example
  1617.          ═════════════════════
  1618.  
  1619.             !=============================================================
  1620.             !  Waiting.V - This is a small script to force the user to
  1621.             !              do nothing for 30 seconds.  It is also an
  1622.             !              example of how to use the various control
  1623.             !              structures to accomplish the same goals.
  1624.             $x = 1
  1625.             $y = 0
  1626.             CALL drawit                      !----------------------------
  1627.             DO $a = 1 10                     !  These
  1628.                CALL slowit                   !    three
  1629.             LOOP                             !      lines
  1630.             CALL drawit                      !----------------------------
  1631.             # again                          !  And
  1632.             IFVAL $x < 11 THEN               !    \
  1633.                CALL slowit                   !    all
  1634.                $x = $x + 1                   !      \
  1635.                GO again                      !      nine
  1636.             ELSE                             !        \
  1637.                GO notagain                   !         of
  1638.             ENDIF                            !          \
  1639.             # notagain                       !           these
  1640.             CALL drawit                      !----------------------------
  1641.             # lastone                        !  And
  1642.                CALL slowit                   !    \
  1643.                $y = $y + 1                   !    these
  1644.                TESTVAL $y = 10 alldone       !       \
  1645.                go lastone                    !        five
  1646.             # alldone                        !----------------------------
  1647.                exit start                    !  do the same thing
  1648.             # drawit                         !----------------------------
  1649.                TR
  1650.                DRAWWAITBAR 10
  1651.             RET
  1652.             # slowit
  1653.                DELAY 1
  1654.                TS "*"
  1655.             RET
  1656.             !=============================================================
  1657.  
  1658.                                              VSCRIPT Documentation -- 31
  1659.  
  1660.  
  1661.          ╔════════════════════════════════════════════════════════════════╗
  1662.          ║ (8) MISCELLANEOUS COMMANDS                                     ║
  1663.          ╚════════════════════════════════════════════════════════════════╝
  1664.  
  1665.                This is the catchall category.  Many useful commands are
  1666.            located in this section that just can't be qualified by a
  1667.            major type.
  1668.  
  1669.          8.1 - Visual/Interactive
  1670.          ════════════════════════
  1671.  
  1672.          AUTOPOST <---
  1673.  
  1674.                This brings up the autopost listing.  See VBBS560.DOC for
  1675.            more info on autoposts.
  1676.  
  1677.          LOGOFF <---
  1678.          LOGOFFYN <---
  1679.  
  1680.                These two commands show the user the LOGOFF.MNU and then
  1681.            log the user off of the BBS. The only difference between the
  1682.            two is that LOGOFFYN prompts the user, while LOGOFF just does
  1683.            it.
  1684.  
  1685.          PAGESYSOP <---
  1686.  
  1687.                This pages the sysop for chat, if available.  See
  1688.            VBBS560.DOC for info on chat availability.
  1689.  
  1690.          RANDOM <---
  1691.  
  1692.                This command shows one of your random blurbs from your
  1693.            random blurbs file.  See VBBS560.DOC for more info on the ran-
  1694.            dom message setup (in VCONFIG).
  1695.  
  1696.          STACK ->  STACK <variable1>
  1697.  
  1698.                This command takes the string in <variable1> and places it
  1699.            into the next input section that the script enters.  This can
  1700.            help make automating multi-keypress functions like downloading
  1701.            a QWK packet easy.  It has been tested and can store at the
  1702.            LEAST 800 characters from 80 '&'ed variables with NO problems.
  1703.            To STACK more than one line of characters for this command just
  1704.            use the '&' operator to add multiple variables into the one
  1705.            <variable1> for use on the STACK line.
  1706.  
  1707.          SYSINFO <---
  1708.  
  1709.                This shows the user a listing of the BBS' activity during
  1710.            the current day and over the BBS' lifetime.
  1711.  
  1712.          VALIDATE <---
  1713.  
  1714.                This loads up the network message validation routine. All
  1715.            messages in 'Validate On' subs are located here.
  1716.  
  1717.                                              VSCRIPT Documentation -- 32
  1718.  
  1719.  
  1720.          WHO <---
  1721.  
  1722.                This command lists who is currently online and what they
  1723.            are doing.  This normally lists the last .FB command that was
  1724.            run, or the last ACTION command that was used.
  1725.  
  1726.  
  1727.          8.2 - User Modifiers
  1728.          ════════════════════
  1729.  
  1730.          ACCOUNT <---
  1731.  
  1732.                This brings up the user's default settings and allows the
  1733.            user to change them.
  1734.  
  1735.          ACTION ->  ACTION <string1>
  1736.  
  1737.                This command changes the setting in the <who> command's
  1738.            listing to <string1>.  <string1> can be a maximum of 22
  1739.            characters long.
  1740.  
  1741.          ADDCREDITS ->  ADDCREDITS <value1>
  1742.  
  1743.                This command adds a number of credits = to <value1> to the
  1744.            users account.  <value1> can be positive or negative.
  1745.  
  1746.          ADDTIME ->  ADDTIME <value1>
  1747.  
  1748.                This command adds a number of minutes = to <value1> to the
  1749.            users time left for the day.  <value1> can be positive or
  1750.            negative.  Note: The change is for the current call ONLY,
  1751.            the bonus time will be lost if the user logs off.
  1752.  
  1753.          SETACCFLAGS ->  SETACCFLAGS <variable1> <option>
  1754.  
  1755.                These are the flags used in VConfig to set up restrictions
  1756.            on your subs.  They are the (h) flags in the user editor and
  1757.            more information on their uses can be found in VBBS.DOC.  The
  1758.            <variable1> can be any letter from A to Z and <option> is either
  1759.            ON or OFF (remember it is case insensitive).
  1760.  
  1761.          SETEXTRA ->  SETEXTRA <value1> <string2>
  1762.  
  1763.                There are 8 user-specific variables available for use.
  1764.            Each variable can contain a <string2> of up to 16 characters.
  1765.            The <value1> determines which $EXTRAx will be set.  This is one
  1766.            of the ways you can have info pass between scripts and kept
  1767.            track of during the 'DOOR' command.  See VDOOR.DOC for a full
  1768.            explaination on how this is done.
  1769.  
  1770.                                              VSCRIPT Documentation -- 33
  1771.  
  1772.  
  1773.          SETFLAGS ->  SETFLAGS <variable1> <option>
  1774.  
  1775.                There are 26 user-specific flags available for use, these
  1776.            are also called general (i) flags.  Each flag is a letter from
  1777.            A to Z and they are toggled with the <option> ON or OFF.  This
  1778.            is another way info can be passed between scripts or saved for
  1779.            use after a 'DOOR' command.  See VDOOR.DOC for an integrated
  1780.            example on how this is done.
  1781.  
  1782.            Special Note - three of the flags have a preset use for VBBS:
  1783.                  A -->  This flag is toggled on/off with the defaults
  1784.                         A>utopost command.
  1785.                  F -->  When this flag is ON the user will use the
  1786.                         built-in Full-Screen Editor.
  1787.                  X -->  When this flag is ON the user will only see
  1788.                         a menu by pressing <?>. Also called expert mode.
  1789.  
  1790.          SETSL -> SETSL <value1>
  1791.  
  1792.                Use this command to alter a users security level as shown
  1793.           by the $security variable.  The <value1> can be any integer value
  1794.           from 0 to 250.  The limit of 250 was set for security reasons.
  1795.  
  1796.          SETTIMELIMIT -> SETTIMELIMIT <value1>
  1797.  
  1798.                This command can be used to increase or decrease a user's
  1799.           maximum time per day as shown by the $maxtime variable.  It will
  1800.           accept any integer from 0 to 240 for <value1> and this value is
  1801.           in minutes per day. The limit of 240 was set for security reasons.
  1802.  
  1803.          USEREDIT <---
  1804.  
  1805.                This command loads the user editor, mostly for sysop use.
  1806.            Only accounts with an SL of 255 can access this feature.
  1807.  
  1808.  
  1809.          8.3 - Real Miscellany
  1810.          ═════════════════════
  1811.  
  1812.          ! ->  ! <put your comments here>
  1813.  
  1814.                Comment line. All text after a '!' is ignored by the
  1815.            script compiler.
  1816.  
  1817.          & ->  & <filename>
  1818.  
  1819.                This is an include directive for the VSCRIPT compiler to
  1820.            add in the contents of another script onto the end of the
  1821.            existing code during compilation.  This allows you to write
  1822.            up modular scripts and use them in more than one main script
  1823.            without having to type or block-copy the section in.  Just
  1824.            remember that it adds the code onto the END of the original
  1825.            script, so you must include the GO or CALL statements to get
  1826.            access to the extra sections.  You can also use this function
  1827.  
  1828.                                              VSCRIPT Documentation -- 34
  1829.  
  1830.  
  1831.            to reduce the size of a single script, as a very long START.V
  1832.            can cause problems when it is run (yet you will have none
  1833.            of the problems if you break into into pieces and include
  1834.            them in.)
  1835.  
  1836.          BEEP <---
  1837.  
  1838.                This sends a beep through the computer speaker.
  1839.  
  1840.          DELAY ->  DELAY <value1>
  1841.  
  1842.                This command pauses the script for <value1> seconds.
  1843.  
  1844.          LOG ->  LOG <token2> <token3> <token4> ... <token7>
  1845.  
  1846.                This command writes up to 6 tokens into the daily log
  1847.            file BBS.LOG, located in your \DATA directory.
  1848.  
  1849.  
  1850.                                              VSCRIPT Documentation -- 35
  1851.  
  1852.  
  1853.          ╔════════════════════════════════════════════════════════════════╗
  1854.          ║  APPENDIX A -- PROGRAMMER'S REFERENCE GUIDE                    ║
  1855.          ╚════════════════════════════════════════════════════════════════╝
  1856.  
  1857.                 This guide is a collection of the command formats for all
  1858.          the commands contained in the Virtual Script Language.  If you
  1859.          need more detail on a command all you need to do is look in the
  1860.          corresponding section in the VSCRIPT.DOC.  All the commands are
  1861.          listed in the exact same format in both places so you may also
  1862.          do a text search for the command line.  Make sure that you read
  1863.          sections 1.4 and 1.5 for a listing of the format definitions and
  1864.          the list of restricted variables.
  1865.  
  1866.          ═════════════════════════════════════════════════════════════════
  1867.  
  1868.          Section 2.1 - Numeric Operators
  1869.          ═══════════════════════════════
  1870.  
  1871.                +   -   *   /   ^
  1872.  
  1873.  
  1874.          Section 2.2 - Numeric Functions
  1875.          ═══════════════════════════════
  1876.  
  1877.                  INT 0 ->  <variable1> = <value2> INT 0
  1878.                  SQR 0 ->  <variable1> = <value2> SQR 0
  1879.                    RND ->  <variable1> = <value1> RND <value2>
  1880.  
  1881.  
  1882.          Section 2.3 - String Operators
  1883.          ══════════════════════════════
  1884.  
  1885.                      & ->  <variable1> = <token3> & <token5> & <token7>
  1886.  
  1887.  
  1888.          Section 2.4 - String Functions
  1889.          ══════════════════════════════
  1890.  
  1891.                  ASC 0 ->  <variable1> = <string2> ASC 0
  1892.                  CHR 0 ->  <variable1> = <value2> CHR 0
  1893.                  LEN 0 ->  <variable1> = <string2> LEN 0
  1894.                UPPER 0 ->  <variable1> = <string2> UPPER 0
  1895.                  INSTR ->  <variable1> = <string2> INSTR <string3>
  1896.                    MID ->  <variable1> = <string2> MID <value3>
  1897.                   LEFT ->  <variable1> = <string2> LEFT <value3>
  1898.  
  1899.  
  1900.          Section 2.5 - String Alterations
  1901.          ════════════════════════════════
  1902.  
  1903.                     JC ->  JC <variable1> <value2>
  1904.                     JL ->  JL <variable1> <value2>
  1905.                     JR ->  JR <variable1> <value2>
  1906.  
  1907.                                              VSCRIPT Documentation -- 36
  1908.  
  1909.  
  1910.          Section 3.1 - Reading Input
  1911.          ═══════════════════════════
  1912.  
  1913.                  GETYN ->  GETYN <variable1> <prompt>
  1914.                  GETNY ->  GETNY <variable1> <prompt>
  1915.                     RS ->  RS <variable1> <prompt>
  1916.                     RX ->  RX <variable1> <prompt>
  1917.                     RW ->  RW <variable1> <prompt>
  1918.                     RN ->  RN <variable1> <prompt>
  1919.                     RC ->  RC <variable1> <prompt>
  1920.                     RR ->  RR <variable1> <string2> <prompt>
  1921.                     RL ->  RL <variable1> <string2> <value3> <prompt>
  1922.                     RF ->  RF <variable1> <prompt>
  1923.                     RI ->  RI <variable1> <prompt>
  1924.  
  1925.  
  1926.          Section 3.2 - Showing Line Output
  1927.          ═════════════════════════════════
  1928.  
  1929.                     TR ->  TR <token2> <token3> <token4> ... <token7>
  1930.                     TS ->  TS <token2> <token3> <token4> ... <token7>
  1931.                     %s ->  %s<number1> <variable2>
  1932.                     %i ->  %i<number1> <variable2>
  1933.                     %d ->  %d<number1>.<number2> <value3>
  1934.  
  1935.  
  1936.          Section 3.3 - Colorization
  1937.          ══════════════════════════
  1938.  
  1939.                  ANSIC ->  ANSIC <color code>
  1940.               $<color> ->  $RED, $BLUE, $GREEN, $YELLOW, $MAGENTA,
  1941.                            $CYAN, $WHITE, $NORM, $BLACK
  1942.                 Hearts ->  See description in main section.
  1943.  
  1944.  
  1945.          Section 3.4 - Other Display Commands
  1946.          ════════════════════════════════════
  1947.  
  1948.                         EF ->  EF <pathfile1>
  1949.                DRAWWAITBAR ->  DRAWWAITBAR <value1>
  1950.                        LOC ->  LOC <value1> <value2>
  1951.                       MENU ->  MENU <filename1>
  1952.                    NEWPAGE <---
  1953.           SUSPENDPAGEBREAK <---
  1954.            RESUMEPAGEBREAK <---
  1955.                      PAUSE ->  PAUSE <prompt>
  1956.  
  1957.  
  1958.  
  1959.  
  1960.          Section 4.1 - Database Selection
  1961.          ════════════════════════════════
  1962.  
  1963.                DBGROUP ->  DBGROUP <group identifier>
  1964.                     DB ->  DB <database number>
  1965.  
  1966.                                              VSCRIPT Documentation -- 37
  1967.  
  1968.  
  1969.          Section 4.2 - LOAD Related Commands
  1970.          ═══════════════════════════════════
  1971.  
  1972.                   LOAD ->  LOAD <value1> <option>
  1973.               ADDCOUNT ->  ADDCOUNT <value1>
  1974.                 DBFLAG ->  DBFLAG <value1> <switch>
  1975.             DISPLAYMSG <---
  1976.            DISPLAYTEXT <---
  1977.                 SEARCH ->  SEARCH <value1> <number2> <string3>
  1978.  
  1979.  
  1980.          Section 4.3 - Editing Commands
  1981.          ══════════════════════════════
  1982.  
  1983.               CLEANUP <---
  1984.                   DEL ->  DEL <value1>
  1985.                  PACK <---
  1986.                    QS ->  QS <value1>
  1987.                  SAVE ->  See description in main section.
  1988.  
  1989.  
  1990.          Section 4.4 - Viewing & Writing
  1991.          ═══════════════════════════════
  1992.  
  1993.              LISTBASES <---
  1994.               NEXTBASE <---
  1995.               PREVBASE <---
  1996.                   POST <---
  1997.             READSEQMSG <---
  1998.             READNEWMSG <---
  1999.             SELECTBASE <---
  2000.           SETQUICKSCAN <---
  2001.  
  2002.  
  2003.          Section 4.5 - E-Mail Functions
  2004.          ══════════════════════════════
  2005.  
  2006.                SETEMAIL <---
  2007.                FEEDBACK <---
  2008.            READALLEMAIL <---
  2009.           READEMAILFROM <---
  2010.             READEMAILTO <---
  2011.               SENDEMAIL <---
  2012.  
  2013.  
  2014.  
  2015.  
  2016.          Section 5.1 - Buffer Commands
  2017.          ═════════════════════════════
  2018.  
  2019.           BUFFER APPEND ->  BUFFER APPEND <string1>
  2020.            BUFFER CLEAR <---
  2021.             BUFFER EDIT <---
  2022.             BUFFER LIST <---
  2023.  
  2024.                                              VSCRIPT Documentation -- 38
  2025.  
  2026.  
  2027.          Section 6.1 - Information Commands
  2028.          ══════════════════════════════════
  2029.  
  2030.               CHECKFILE ->  CHECKFILE <variable1> <pathfile2>
  2031.               FINDFIRST ->  FINDFIRST <variable1> <pathfile2>
  2032.                FINDNEXT ->  FINDNEXT <variable1>
  2033.               FINDFILES <---
  2034.               LISTFILES <---
  2035.                NEWFILES <---
  2036.                   RATIO <---
  2037.              REVIEWFILE <---
  2038.           REVIEWUPLOADS <---
  2039.               SEARCHALL <---
  2040.            TOPDOWNLOADS <---
  2041.                XFERTIME ->  XFERTIME <variable1> <pathfile2>
  2042.  
  2043.  
  2044.          Section 6.2 - Transfer Commands
  2045.          ═══════════════════════════════
  2046.  
  2047.                BATCHDL <---
  2048.           DLMASTERLIST <---
  2049.               DOWNLOAD ->  DOWNLOAD <pathfile1>
  2050.           DOWNLOADFILE <---
  2051.           REMOTEUPLOAD <---
  2052.            SYSOPUPLOAD <---
  2053.                 UPLOAD ->  UPLOAD <pathfile1>
  2054.  
  2055.  
  2056.          Section 6.3 - File Editing
  2057.          ══════════════════════════
  2058.  
  2059.               EDITFILE <---
  2060.                  CLOSE <---
  2061.                   KILL ->  KILL <pathfile1>
  2062.                   OPEN ->  OPEN <pathfile1> <option>
  2063.                            <option> = INPUT, OUTPUT, APPEND
  2064.                   READ ->  READ <variable1>
  2065.                  WRITE ->  WRITE <token2> <token3> <token4> ... <token7>
  2066.  
  2067.  
  2068.  
  2069.  
  2070.          Section 7.1 - General Redirection
  2071.          ═════════════════════════════════
  2072.  
  2073.                      # ->  # <label>
  2074.                   CALL ->  CALL <label>
  2075.                     GO ->  GO <label>
  2076.                    RET <---
  2077.  
  2078.                                              VSCRIPT Documentation -- 39
  2079.  
  2080.  
  2081.          Section 7.2 - Loops and Comparisons
  2082.          ═══════════════════════════════════
  2083.  
  2084.            Section 7.21 - DO Loops
  2085.            ───────────────────────
  2086.  
  2087.              ->  DO <variable1> = <value2> <value3>
  2088.                     [body of the loop]
  2089.                  LOOP
  2090.  
  2091.              ->  DO WHILE <variable1>   {must store a numeric!}
  2092.                     [body of the loop]
  2093.                  LOOP
  2094.  
  2095.            Section 7.22 - IF/IFVAL Structures
  2096.            ──────────────────────────────────
  2097.  
  2098.              ->  IF <variable1> <relation> <variable2> THEN
  2099.                     [then-code]
  2100.                  ENDIF
  2101.  
  2102.              ->  IF <variable1> <relation> <variable2> THEN
  2103.                     [then-code]
  2104.                  ELSE
  2105.                   [else-code]
  2106.                  ENDIF
  2107.  
  2108.  
  2109.          Section 7.23 - TEST/TESTVAL Commands
  2110.          ════════════════════════════════════
  2111.  
  2112.          ->  TEST <variable1> <relation> <variable2> <label>
  2113.          ->  TESTVAL <variable1> <relation> <variable2> <label>
  2114.  
  2115.  
  2116.          Section 7.3 - Passing Control
  2117.          ═════════════════════════════
  2118.  
  2119.                   LINK ->  LINK <filename>
  2120.                   EXIT ->  EXIT <filename>
  2121.                  SHELL ->  SHELL <pathfile or DOS command line>
  2122.                   DOOR ->  DOOR <pathfile or DOS command line>
  2123.  
  2124.                                              VSCRIPT Documentation -- 40
  2125.  
  2126.  
  2127.          Section 8.1 - Visual/Interactive
  2128.          ════════════════════════════════
  2129.  
  2130.               AUTOPOST <---
  2131.                 LOGOFF <---
  2132.               LOGOFFYN <---
  2133.              PAGESYSOP <---
  2134.                 RANDOM <---
  2135.                  STACK ->  STACK <variable1>
  2136.                SYSINFO <---
  2137.               VALIDATE <---
  2138.                    WHO <---
  2139.  
  2140.  
  2141.          Section 8.2 - User Modifiers
  2142.          ════════════════════════════
  2143.  
  2144.                ACCOUNT <---
  2145.                 ACTION ->  ACTION <string1>
  2146.             ADDCREDITS ->  ADDCREDITS <value1>
  2147.                ADDTIME ->  ADDTIME <value1>
  2148.             SETACCFLAG ->  SETACCFLAG <value1> <option>
  2149.                            <option> = ON, OFF
  2150.               SETEXTRA ->  SETEXTRA <value1> <string2>
  2151.               SETFLAGS ->  SETFLAGS <variable1> <option>
  2152.                            <option> = ON, OFF
  2153.                  SETSL ->  SETSL <value1>
  2154.           SETTIMELIMIT ->  SETTIMELIMIT <value1>
  2155.               USEREDIT <---
  2156.  
  2157.  
  2158.          Section 8.3 - Real Miscellany
  2159.          ═════════════════════════════
  2160.  
  2161.                      ! ->  ! <put your comments here>
  2162.                      & ->  & <filename>
  2163.                   BEEP <---
  2164.                  DELAY ->  DELAY <value1>
  2165.                    LOG ->  LOG <token2> <token3> <token4> ... <token7>
  2166.  
  2167.  
  2168.                                              VSCRIPT Documentation -- 41
  2169.  
  2170.  
  2171.          ╔════════════════════════════════════════════════════════════════╗
  2172.          ║  APPENDIX B -- COMMON SCRIPT EXAMPLES & EXPLAINATIONS          ║
  2173.          ╚════════════════════════════════════════════════════════════════╝
  2174.  
  2175.          ╔════════════════════════════════════════════════════════════════╗
  2176.          ║ Note:  While all the following scripts were written by other   ║
  2177.          ║        authors they have all undergone modification to improve ║
  2178.          ║        their clarity and/or add in new features found in 5.60. ║
  2179.          ╚════════════════════════════════════════════════════════════════╝
  2180.  
  2181.           Question: How do I figure out if it is a user's birtday?
  2182.           Answer: Place this section of code into the script that you
  2183.                   wish to have show the birthday greeting.
  2184.  
  2185.             !=============================================================
  2186.             !                       Unknown Author
  2187.             !=============================================================
  2188.             $bmonth = $birthdate LEFT 2
  2189.             $month = $date LEFT 2
  2190.             $bday = $birthdate MID 4 LEFT 2
  2191.             $day = $date MID 4 LEFT 2
  2192.             TESTVAL $bmonth = $month NOTNOW
  2193.             IFVAL $bday = $day THEN
  2194.                <place your birthday message here>
  2195.             ENDIF
  2196.             # NOTNOW
  2197.             !=============================================================
  2198.  
  2199.  
  2200.           Question: I would like to know when I have new messages to be
  2201.                     validated for my networked subs when I log on.
  2202.           Answer: Place this section of code into your START.V file
  2203.                   anywhere before you exit.
  2204.  
  2205.             !=============================================================
  2206.             !          Originally written by Ken 1@8051 VirtualNET
  2207.             !=============================================================
  2208.             testval $security < 254 nothere
  2209.             $found = "VALIDATE.0"
  2210.             findfirst $validmsg "c:\vbbs\data\validate.0"
  2211.             test $validmsg <> $found nothere
  2212.             # again
  2213.             tr
  2214.             getny $choice "5New messages to VALIDATE.6 Validate Now? "
  2215.             if $choice = "Y" then
  2216.                validate
  2217.             endif
  2218.             # NOTHERE
  2219.             !=============================================================
  2220.             !    Note:  This ONLY works for VirtualNET message bases.
  2221.             !=============================================================
  2222.  
  2223.  
  2224.                                              VSCRIPT Documentation -- 42
  2225.  
  2226.  
  2227.           Question: How do I set up a simple downloads area for special
  2228.                     files like virus scanners and compression utilities?
  2229.           Answer: Just edit the following script to show the correct paths
  2230.                   and filenames for the files, add in the command to run
  2231.                   the script from a function block (ex: G 001 2 SHOPPING).
  2232.                   Then all you need to do is create a .MNU file (or a .ANS
  2233.                   and .ASC pair) listing the user's choices and place it
  2234.                   into your \TXT directory and away you go.
  2235.  
  2236.             !=============================================================
  2237.             !        Originally written by O. F. 1@2056 VirtualNET
  2238.             !=============================================================
  2239.             Example SHOP.MNU file:
  2240.  
  2241.              Available files for quick download are:
  2242.                A> ARJ230.EXE    - Newest ARJ Compression Utility
  2243.                C> CLEAN100.ZIP  - McAfee Virus Cleaning Utility
  2244.                F> FRIES.GIF     - GIF of the lovable '-fries'
  2245.                G> GREMLIN.GIF   - GIF of 'The (verbose tagline) Gremlin'
  2246.                P> PKZIP204E.EXE - Newest PKZip Compression Utility
  2247.                S> SCAN100.ZIP   - McAfee Virus Scanning Utility
  2248.  
  2249.             !=============================================================
  2250.             tr $crlf
  2251.             menu shop
  2252.             tr $crlf
  2253.             rr $selection acfgpsq "Which file would you like ? <Q to quit>"
  2254.             IF $selection = a THEN
  2255.                DOWNLOAD d:\dloads\compress\arj230.exe
  2256.             ELSE
  2257.             IF $selection = c THEN
  2258.                DOWNLOAD d:\dloads\virus\clean100.zip
  2259.             ELSE
  2260.             IF $selection = f THEN
  2261.                DOWNLOAD d:\dloads\gifs\fries.gif
  2262.             ELSE
  2263.             IF $selection = g THEN
  2264.                DOWNLOAD d:\dloads\gifs\gremlin.gif
  2265.             ELSE
  2266.             IF $selection = p THEN
  2267.                DOWNLOAD d:\dloads\compress\pkz204e.exe
  2268.             ELSE
  2269.             IF $selection = s THEN
  2270.                DOWNLOAD d:\dloads\virus\scan100.zip
  2271.             ENDIF
  2272.             tr $crlf
  2273.             exit start
  2274.             ! Make sure the EXIT command above is to a .FB you have !!
  2275.             !=============================================================
  2276.  
  2277.  
  2278.                                              VSCRIPT Documentation -- 43
  2279.  
  2280.  
  2281.           Question: How can I enhance the chat call from my users?  I like
  2282.                     to know WHY they chatted me, even if I am not around.
  2283.           Answer: All you have to do is compile the following script as
  2284.                   CHAT.V and then and change the line in your START.FB from
  2285.                   'l 001 1 ^pagesysop' to 'l 001 2 chat'.
  2286.  
  2287.             !=============================================================
  2288.             !     Originally written by B. B. Woof 1@5096 VirtualNET
  2289.             !=============================================================
  2290.             tr "Why do you wish to page " $sysop
  2291.             tr
  2292.             tr "   >----------------------------------------------------<"
  2293.             rs $reason "=> "
  2294.             tr "   >----------------------------------------------------<"
  2295.             test $reason = "" end
  2296.             $tst = $reason LEFT 5
  2297.             test $tst = "     " end
  2298.             test $available = Y imhere
  2299.             tr
  2300.             tr $sysop " is not currently available, "
  2301.             go feed
  2302.             # imhere
  2303.             tr
  2304.             tr "Paging " $sysop
  2305.             do $count = 1 10
  2306.                 ts "2<6<2<6*2>6>2> " $bell
  2307.             loop
  2308.             tr
  2309.             tr "7Please wait 10 seconds for " $sysop " to respond, "
  2310.             tr
  2311.             drawwaitbar 10
  2312.             do $a = 1 10
  2313.                ts "*"
  2314.                delay 1
  2315.             loop
  2316.             tr
  2317.             tr $sysop " doesn't seem to be answering..."
  2318.             # feed
  2319.             getyn $yn "Would you like to leave feedback? (Y/N/enter=yes)"
  2320.             tr
  2321.             if $yn = Y then
  2322.                $s = "     and left feedback as well!"
  2323.                feedback
  2324.             else
  2325.                $s = "     and did not leave feedback!"
  2326.             endif
  2327.             log $handle ", paged you at " $time " on " $date
  2328.             log "Chat reason: " $reason
  2329.             log $s
  2330.             tr
  2331.             # end
  2332.             exit start
  2333.             ! Make sure the EXIT command above is to a .FB you have !!
  2334.             !=============================================================
  2335.  
  2336.  
  2337.                                              VSCRIPT Documentation -- 44
  2338.  
  2339.          ╔════════════════════════════════════════════════════════════════╗
  2340.          ║  APPENDIX C -- VGIX COMMANDS                                   ║
  2341.          ╚════════════════════════════════════════════════════════════════╝
  2342.  
  2343.          ╔════════════════════════════════════════════════════════════════╗
  2344.          ║ Note:  VGIX Commands have no effect when the user is not in    ║
  2345.          ║        VGIX mode.                                              ║
  2346.          ╚════════════════════════════════════════════════════════════════╝
  2347.  
  2348.          CLS <---
  2349.                
  2350.                This command clears the user's screen.
  2351.  
  2352.          COLOR ->  COLOR <color> 
  2353.  
  2354.               Set the current color for text and graphics.
  2355.          
  2356.          LINE ->  LINE <x> <y> <x2> <y2> <color> <boxflag>
  2357.  
  2358.                This command draws a line or box on the user's screen,
  2359.            starting at point <x>,<y> to point <x2>,<y2> using the
  2360.            <color> specified. If <boxflag> = 0 a line is drawn,
  2361.            if <boxflag> = 1, a box is drawn.
  2362.            
  2363.          ╔════════════════════════════════════════════════════════════════╗
  2364.          ║ Note:  <x> and <x2> have an allowable range of 0 to 639.       ║
  2365.          ║        <y> and <y2> have an allowable range of 0 to 479.       ║
  2366.          ║        <color> is one of the following:                        ║
  2367.          ║  0=Black      1=Blue           2=Green        3=Cyan           ║
  2368.          ║  4=Red        5=Magenta        6=Brown        7=Grey           ║
  2369.          ║  8=Dark Grey  9=Light Blue     10=Light Green 11=Light Cyan    ║
  2370.          ║  12=Light Red 13=Light Magenta 14=Yellow      15=Bright White  ║
  2371.          ╚════════════════════════════════════════════════════════════════╝
  2372.          
  2373.          PLOT ->  PLOT <x> <y> <color>
  2374.  
  2375.                Set the pixel at <x>,<y> using the <color> specified.
  2376.  
  2377.          CIRCLE ->  CIRCLE <x> <y> <radius> <color>
  2378.  
  2379.                Draw a circle, with an origin at <x>,<y>, using
  2380.            the <radius> and <color> given. Allowable ranges for
  2381.            <radius> are 1 to  639.
  2382.  
  2383.                                              VSCRIPT Documentation -- 45
  2384.  
  2385.          PAINT ->  PAINT <x> <y> <color> <bordercolor>
  2386.                
  2387.                This command paints an area starting at point <x> <y>
  2388.            using <color>. <Bordercolor> specifies the color at which
  2389.            painting should stop. You would typically use CIRCLE,
  2390.            LINE (in box mode), or PLOT to 'outline' the shape you 
  2391.            wanted paint to paint, and then you would use PAINT 
  2392.            to fill your shape with color.
  2393.  
  2394.          DRAW ->  DRAW <actionstring>
  2395.  
  2396.                <Actionstring> refers to a string of characters:
  2397.            An example might be "U4RU2R5D10L20"
  2398.            This would draw moving the "pen" UP 4, RIGHT 1, UP 2, 
  2399.            RIGHT 5, DOWN 10, LEFT 20.
  2400.            
  2401.            <actionstring> commands:
  2402.                U Up
  2403.                D Down
  2404.                R Right
  2405.                L Left
  2406.  
  2407.          PLAY -> PLAY <musicstring>
  2408.            
  2409.                This command plays music on the remote user's computer.
  2410.            When used with high (fast) tempos, it can also be used to
  2411.            make sound effects. No special sound/music hardware is
  2412.            required.
  2413.            
  2414.            <Musicstring> refers to a string of text such as:
  2415.            "ABCDEFGO4L4T100" = Notes A thru G, go to Octave 4, 
  2416.            note Length 1/4, Tempo 100.
  2417.            
  2418.            <musicstring> commands:
  2419.                A-G Notes A thru G
  2420.                O   Set Octave (1 to 5)
  2421.                L   Set Length (1 to 255 representing 1/1 to 1/255)
  2422.                T   Tempo (1 to 255, 1=Slow, 255=Extremely Fast)
  2423.                +   Sharp (Eg "A+" would play A sharp)
  2424.                -   Flat  (Eg "A-" would play A flat)
  2425.  
  2426.                                              VSCRIPT Documentation -- 46
  2427.  
  2428.          ICONIFY  <---               
  2429.          
  2430.                This command resets the VGIX ICON "counter."
  2431.  
  2432.          ICON ->  ICON <iconname> <x> <y> <orflag> <key> <caption>
  2433.  
  2434.                This command displays a VGIX Icon on the user's screen.
  2435.            <Iconname> is a 12 character icon name.
  2436.            <X> and <y> are coordinates on the screen where icon is
  2437.            to be displayed.
  2438.            <Orflag>: 0 = SET ICON, 1 = OVERLAY ICON (over a background)
  2439.            <Key> refers to the keystroke to return if this icon is 
  2440.            selected by the user via the mouse.
  2441.            <Caption> refers to the text to be printed under the icon.
  2442.            Captions are automatically centerd beneath the icon.
  2443.  
  2444.            Note: If key and caption are absent, the icon is NOT "counted" 
  2445.            and is not mouseable. Both key and caption must be present for 
  2446.            the icon to be mousable.
  2447.  
  2448.