The core idea of revising / expanding the Script (AKA Questionaire)
Langauge is to make QuickBBS more expandable, and versatile, while
making it even more user friendly.

The new Script language is *EXTREMELY* versatile, and the new commands
are even "more" user friendly (IE more "English" language than a typical
programming language).

This is a quick example of something you can do.

(One note, I intend to make the ^X text file command, also use scripts.
 This means ANSITEST.SCR could (in theory) be placed in the WELCOME.*
 text file)

ANSITEST.SCR is a start, I may sit down and make a script that actually
allows the user to test the SSR function (but most programs that are
broken *IGNORE* the reset command) but there are problems with that.

If anyone has a suggestion on how to expand this script to test for
ASCII only, 7Bit, 8Bit, or other terminal settings, I'd appreciate it.
If I get some feedback about that, then I'd be able to accelerate the
User File changes and add those Terminal modes....(or others)


Start of  ------------- ANSITEST.SCR ----------------


ClearScreen
Display "||Welcome to QuickBBS!!|||"

Display "Test  "
ChangeColor 7 1
Display "Test  "
ChangeColor 9 2
Display "Test  "
ChangeColor 10 3
Display "Test||"
ChangeColor 7 0
Display "Do you see word 'Test' in different colors?"
GetChoice YN 1
If 1 = "Y"
        SETANSI ON
        Display "||Your Terminal has been configured for ANSI Color Mode|"
        PressEnter
 ELSE
        SETANSI OFF
        Display "||Your Terminal has been configured for ASCII Text Mode|"
        PressEnter
 ENDIF
:END
------------- ANSITEST.SCR ----------------

                            Script Command Language

             The script command language is based off the v2.85 (and lower)
        QuickBBS questionaire language.  In both cases these languages are
        a form of programming that QuickBBS will be able to understand, and
        thus that allows *YOU* the sysop to interact with the user, record
        answers, and even perform functions based on the answers.

             The script file  must have a  1-8 character filename  with
        the extension  SCR.  Blank lines and indentations are permitted for
        clarity, with commands as the first non-space characters on the line.
        The answers will  be stored in a file with the same filename but the
        extension ASW.  New answers will be appended to the ASW file as they are
        received.

        *NOTE* : The script command (Menu Type 12 - Execute Script File), will
               automatically check for a *.SCR file, and then if that is not
               found it will check for a *.Q-A file.  This allows you to keep
               using your *OLD* questionaire files, without modification.

             These are the commands available for Script files.

             ASK <Len> <Var  Num> {Min}: Reads a  user's response of  at least
                  {Min}  characters up  to <Len>  characters and stores  it in
                  variable number <Var Num>.  <Len> can be from 1 to  255. The
                  {Min} parameter is optional.

                       Display "Question #1: What is your real name? "
                       Ask 60 1 10
                       OutputAnswer "NAME: " 1

             CHANGECOLOR  <Foreground> <Background>: Changes the current color
                  if the user has ANSI selected, the <Foreground> can be from 0
                  to 15 and the <Background> can be from 0 to 7.  See page 47
                  for a list of available color codes.

                       ChangeColor 15 1

             CLEAREOL   : Clears from the cursors position to the end of the
                  line via the ANSI "Clear to End of Line" command.

             CLEARSCREEN: Clears the callers screen, but only if the caller has
                  selected screen clearing.

             DISPLAY "<String>": Displays the character string <String>, which
                  must be encased in quotes.

                       Display "Question #1: What is your real name? |"

             DOWNLOAD "<FileName>"  [/proto=xx]
                  See Also: TRANSFER.SCR

                  This command is equivalent to using a Menu Type 55 (Download
                  Any File), and has the same security "risks".  The Major risk
                  is that a user maybe able to download your "userfile", and
                  "steal" information from it.  This is possible, doubtful,
                  but for safety you should be very careful with scripts that
                  allow downloading.

                  The protocol choice menu is shown, and then "<Filename>" is
                  automatically started to download.  Please note <FILENAME>
                  has to be contained within QUOTES (").

                  The protocol choice menu can be bypassed by using the
                  /proto=xx, where xx is the # of the protocol entry
                  (Qconfig -> Protocol), which you wish to use.
                  (See transfer.scr for working examples)

                  This could be useful for allowing users to download your
                  BBS rules of conduct, or any other material.
                      ------------------------------------------
                             For example:
                      ------------------------------------------
                  Display "Would you like to download QuickBBS? |"
                  GetChoice YN 1
                  If 1 = "Y"
                       SetFlag C7 ON
                       Display "Good for you!|"
                       DOWNLOAD "E:\FILES\QKREL\QB285P4A.ZIP"
                  Else
                       SetFlag C8 ON
                  EndIf



             ELSE: Used with IF and ENDIF to perform an alternate action.

                      ------------------------------------------
                             For example:
                      ------------------------------------------
                  Display "Do you operate a BBS? |"
                  GetChoice YN 1
                  If 1 = "Y"
                       SetFlag C7 ON
                       Display "Good for you!|"
                  Else
                       SetFlag C8 ON
                       Display "Too Bad!  Have you thought about QuickBBS?|"
                  EndIf
                      ------------------------------------------
                             For example:
                      ------------------------------------------
                             If 1 = "YES"
                                Display "|You Entered YES|"
                              ENDIF
                      ------------------------------------------
                             IF 1 = "YES"
                                Display "|You Entered YES|"
                              ELSE
                                Display "|You did NOT Enter YES|"
                              ENDIF
                      ------------------------------------------


             ENDIF: Terminates the If statement (see IF and ELSE).

             GETCHOICE <Choices>  <Var Num>:  Inputs one character  which will
                  consist of an item in the <Choices>. The result is stored in
                  variable number <Var Num>.

                       Display "Is your modem: | 1: 300 baud |"
                       Display "2: 1200 baud | 3: 2400 baud | 4: Over 2400 |"
                       GetChoice 1234 9

             GOSUB <LABEL> : Gosub will cause the script to "jump" to <LABEL>
                  when it hits "RETURN", it will return to the next statement
                  after GOSUB.

                  (Labels are indentical to DOS's batch labels)
                   ie -    :GOSUB_TO_HERE

                  The ":" (Colons) are very important, and tell the system
                  it is a label.  And SPACES are not supported.

             GOTO <LABEL> : Will cause the Script to "jump" to <LABEL>,
                  unlike GOSUB, this will *NOT* remember your last place,
                  and RETURN will *NOT* return you to your last processing
                  point.

             GOTOXY <xx> <yy> : Will use the ANSI goto command to reposition the
                  cursor to xx, yy.  One caution, if you exceed the users screen
                  size you will get erratic results depending on the ANSI
                  driver they are using.

             IF <Var Num> = "<Test String>": Compares a variable number to the
                  Test String. The test is not case sensitive. If the compari-
                  son  is  true then  the  following  questionnaire lines are
                  processed  until an  Endif or Else is  reached, otherwise
                  all lines through the  Endif are skipped.  A space is
                  required before and  after  the equals  sign (=),  and the
                  arguments  to be processed if the test is true must end
                  with an EndIf statement.

                       If 3 = "Adam"
                       SetSecurity 3000
                       EndIf


             LISTANSWER <Var Num>: Displays  the contents of <Var Num>  to the
                  user's screen.  This makes  it possible  to list  the user's
                  answers so far and ask if they are correct.

                       ListAnswer 4

             LOCKOUT <Yes/No/True/False> : Will set the user's security level to
                  Zero (0), and effectively lockout the User (This is the same
                  as hitting ALT-L from the keyboard).

             LOGENTRY "<String>": Writes "String" to SYSTEM.LOG.

                       LogEntry "Security level upgraded"

             MENUCOMMAND <Menu Type #> <Rest of optional command>
                  See Also: TRANSFER.SCR

                  This command allows you to run any Menu Command except for:

                        1    - Goto
                        2    - Gosub
                        3    - Return from Gosub
                        4    - Clear GOSUB Stack & Goto
                        40   - Display *.A?? file w/Hotkey
                        62   - Change Language
                        64   - Multiple Command Option
                        66   - Internode Command Menu

                  These 8 Menu Commands would require rewrites to allow
                  them to work inside the script engine.

                  Other than that restriction, to our knowledge their should be
                  no other limitations at this time.

             OUTPUTANSWER  "<Descriptor>" <Var Num>:  Outputs the  contents of
                  <Var  Num> to the answer file and  labels it with the string
                  <Descriptor>.

                       OutputAnswer "NAME: " 2

             PAGESYSOP "<Page Prompt>" : Will Page the sysop, equivalent to
                  Menu type 11.

             PRESSENTER - Will display Language Entry #6 ('Press Enter :') and
                  wait for a Return (CHR(#13)) before proceeding.

             POSTINFO: Posts  the user's name,  city, state,  and the current
                  date and time in the  answer file. You may wish to  put this
                  command  at  the top  of your  questionnaire so you  have a
                  header for each entry in the answer file.

             QUIT: Ends  the questionnaire  immediately and closes  the answer
                  file.

             SAVE <filename> <PersistantVariableName>
                  See Also: SET, USES, TRANSFER.SCR

                  Save will save the persistant variable into the <FILENAME>.INI
                  file as well as the default file.

                  This allows you to store persistant variables in "common"
                  files, so that you can share them between different scripts.

                  *NOTE* The <filename> will always have a forced extension of
                        *.INI.

                  *CAUTION* This save command does not "persist" through out the
                        script file, you must resave it every time it changes.
                        Instead of having SAVE's after each change, it maybe
                        easier to place the SAVE command at the END of the
                        script file.  This way whatever the value is, the
                        changes are saved before you "end" the script.

                  Example:

                        SAVE PROTOCOL PREFERREDDOWNLOAD
                        SAVE PROTOCOL PREFERREDUPLOAD
                        SAVE NEWS     READ_AT_LOGON
                        SAVE USERSPEC BAD_LOGON

             SET <PersistantVariable> "<Data>"
                  See Also: SET, USES, TRANSFER.SCR

                  Will set the persistant variable with the data in the quotes.

                  Example:

                        SET Download_Me "C:\quickbbs\release\qb285gac.zip"

             SETANSI <Yes/No/True/False/Flip> - Will Set the User's Ansi
                  Setting

             SETFLAG <Flag Set><Flag Number> <ON|OFF>: Sets the user's flag on
                  or  off.  <Flag Set>  is  A through  D.  <Flag Number> is 1
                  through 8, counting  left to right through the flagset. The
                  changed flag setting is valid immediately on flags in menus,
                  but does  not take  effect on  flag settings  in QCONFIG.EXE
                  until the user's next call.

                       SetFlag D5 ON

             SETNOKILL <Yes/No/True/False/Flip>

                  Will set the Users "NoKill" Flag.

             SETSECURITY <Level>:  Changes the user's security  level to
                  <Level>.  This can be any valid security level, from 0 to
                  32000.  If set to  0, the user will be disconnected on
                  completion of the questionnaire file.

             SETSSR <Yes/No/True/False/Flip> - Will set the User's SSR Setting.

             SHOWFILE [<FullPathName>] [<filename>]

                  This command will first check for the filename in the textfile
                  path, but if it is not found, it will check to see if you have
                  specified the full pathname.  If it finds the file, it will
                  display the text file, no matter where it is.

                  Example:

                        SHOWFILE C:\bbs\txtfiles\macross\macross.1

                        SHOWFILE BBSRULES

             SUBSCRIPT "<FileName>" : ill Cause <FileName> to be *APPENDED*
                  to the currently *RUNNING* script.  Once loaded the script
                  will be GOSUB'd to, and "Returned" once finished...

                  This could be used to create small little scripts that are
                  used THROUGHOUT your "major" scripts.  For example, Turbo
                  Pascal Units, or C/C++ OBJ files, etc.

             UPDATEBOARDS: Updates the user's access to message areas based on
                  changes in security levels and flag settings.

             USES <filename> - The uses command tells the script to check
                  additional *.INI files for the persistant variable.
                  See Also: SAVE, TRANSFER.SCR

                  *NOTE* - You can only have up to 4 uses commands in any one
                        script.  It is *NEVER* necessary to include the default
                        ini file (<scriptname>.ini), that is always included.

                  *NOTE* - The search will end at the *FIRST* occurance of the
                        variable the script engine is searching for.

                  For example :

                        USES PROTOCOL
                        USES NEWS
                        USES USERSPEC

             WAITENTER - QuickBBS will pause, and wait for a return (CHR(#13),
                  but will *NOT* display any prompt.


                               Special Characters

             '|' (aka the "Pipe" aka "The vertical bar") is used inside a text
        string will be replaced with a carriage return.

             All Metacharacters should be able to be used in the text strings as
        well.

             A ';' (Semicomma) when used in the first character of a line, will
        cause the script engine to ignore the line, in otherwords, it's the
        comment "command".

                                    Variables

             The old style variables (i.e. 1..20), only allow up to twenty
        variables, each which can be up to 255 characters long.

             The new style "persistant" variables, also have the same length
        limitation (255 characters), but have a (effectively) unlimited number
        of variables.  All persistant variable data is stored in a file called
        "<scriptname>.INI".  This INI file is a typical Windows text based ini
        file, and is in plain text.  If there is enough demand, I may add a
        method to store variables in an ENCRYPTED form.
