Monster Media 1994 #1/monster.zip/monster/BBS_UTIL/BFE3100P.ZIP/BFE3100P.EXE/DOCS/SCRIPT.DOC

Text File | 1994-03-12 | 22KB | 691 lines

─────────────────────────────────────────────────────────────────────────────
     ▄   ▄▄▄ ▄▄▄     ▄▄▄ ▄▄▄ ▄▄▄ ▄ ▄▄▄  ▄      ▄▄▄ ▄ ▄ ▄▄▄  ▄  ▄▄▄ ▄▄▄
     █▄▄ █▄  █▄█     █▄▄ █   █ ▀ █ █▄█ ▀█▀     █▄▄ ▐▄▌ █▄▄ ▀█▀ █▄█ ▌█▐
     █▄█ █   █▄▄     ▄▄█ █▄▄ █   █ █    █▄     ▄▄█  █  ▄▄█  █▄ █▄▄ ▌ ▐

─────────────────────────────────────────────────────────────────────────────

                        INTRODUCTION AND OVERVIEW

BFE/Script is the name of the internal script processor in BFE.  Through the
use of this system, users are able to "code" their own BFE scripts, and call
them from their BFE menus.  Most users will not have a need for BFE/Script,
as BFE alone provides quite an arsenal of tools to construct your frontend
system.  However, for those who like to tinker with internals and the like,
BFE/Script will prove to be a tremendous addition to your system.

In appearance, BFE/Script code is remarkably similar to the C language,
although C is a much more powerful platform.  In fact, the entire BFE system
was authored in C, while BFE/Script is but a user interface to the BFE
internals.  If you are a C programmer, or have dabbled in C, then you should
have no problems at all with BFE/Script.  Non-programmers should be sure to
read over this section in its entirety, and study the sample scripts which
are included in the BFE distribution archive.

Current features and constructs of BFE/Script include:

         - Access to internal BFE functions such as sysop paging, etc.
         - Parameterized functions with local variables
         - Function Recursion
         - Global variables
         - Keywords: if, do-while, while, for, and return.
         - Numeric and character variable types
         - Operators: +, -, *, /, %, <, >, <=, >=, ==, !=, unary +/-
         - Functions which return integers
         - BFE/Script is completely case-insensitive (unlike C!)

More BFE/Script functions and procedures will be added in future releases.
Should you have any suggestions on possible additions to this unique feature
of BFE, please contact us!


                SCRIPT SYNTAX RULES AND CODING BASICS

As we mentioned earlier, BFE/Script is very similar to C, at least in the
general appearance of its code.  While this section is not meant to teach C,
many of the rules will apply to both C and BFE/Script.  You may find it
helpful to pick up an introductory C programming book in order to hone your
BFE/Script skills.

All of your scripts should be edited with your favorite ASCII text editor,
such as Q-Edit, TED, DOS-Edit, etc.

Your BFE/Scripts are composed of functions, and calls to these functions.
Each of your functions must be completed enclosed in a "code-block".  For
example:

         printmessage()
         {
           putsnl("Welcome to my first BFE script!");
         }

In the above example, the function "printmessage" is a user-defined function,
consisting of nothing more than a call to "putsnl" (put string with a CR/LF
pair).  There are two very essential concepts about the above.  The first
being the two curly braces which separate the function name, in this case,
putmessage(), and the actual function contents, the call to putsnl().

The second item of interest is the semi-colon following the call to putsnl().
This signifies the end of the current function call.  Let's take a look at
another small example:

         /* My first BFE Script! */

         main() {
           clearscreen();
           printmessage();
         }

         printmessage()
         {
           putsnl("Welcome to my first BFE script!");
           putsnl("Press any key to return to BFE!");
           getkey();
         }

In this example, we have expanded on our original printmessage() example.
In actuality, the original example we discussed is not complete!  Each of
your BFE scripts *must* contain a function called "main".  This function is
used as the starting point of the script.

In the above example, you will also notice the placement of the two curly
braces in the function main(), is a bit different from that of the function
printmessage().  Like C, BFE/Script is a free-format language, to an extent.
Spacing and line order doesn't matter.  As long as the constructs are
present.

In the above example, BFE/Script would start processing in the function
main(), with consists of nothing more than a call to printmessage().  When
printmessage() is executed, the two calls to putsnl() would display the text
to the user.  The call to getkey() would simply wait for a keypress from the
user.  At that point, control is returned to main().  Since main() has no
more processing left, BFE/Script in turn returns control back to BFE.

Let's take a look at the use of user-defined variables, as these will play an
important role in even the most primitive of scripts.  Currently, BFE
supports two types of variables, character and numeric.  Additional, more
advanced data types (such as floating point and string), will be introduced
in a later release of the package.

To define a user-defined variable, use the following construct:

                 <type> <identifier>

Here are a few examples:

                               int x,y,z;

The above example creates three (3) numeric variables (integers) called x, y,
and z.  (Note the ability to separate variable definitions of the same type
with a comma!  You cannot mix more than one type like this).

                               char key;
                               char a,b,c;

Similarly, the above examples generate character variables, called "key", a,
b, and c.

All variables (unlike C) are automatically initialized to zero.  To set a
variable's value, simply use the "=" operator:

         x = 10;
         y=1;
         key = 'A';

Variables declared inside of a function block are "local" to that function,
and are not available in any other function!  These "local" variables are
also re-initialized on each call to the owning function.  Similarly, any
variables declared outside of any function are declared as "global" variables
and are available anywhere in the script, in any function.  Global variables
retain their values unless explicitly changed.

Another extremely powerful feature of BFE/Script is the ability to pass
values to and from functions.  This is known as "parameterized functions".
Perhaps another example is in order:

         main()
         {
           int x,y,z;
           char t;
           clearscreen();
           puts("Enter a number: ");
           x = getnum();

           ShowNumber(x);
         }

         ShowNumber(int z)
         {
           puts("X is equal to: ");
           print(z);
           putsnl("Press any key to exit!");
           getkey();
         }

In this particular example, starting in the main() function, the user is
prompted to enter a number.  This number is then passed to the ShowNumber()
function, where the number is displayed.  This is also a great example of
local variables, as the variable "z" is local to the ShowNumber() function,
even though it will end up with the same value as the main() function's local
variable "x".

Easy, isn't it?  Great!  Now that we have variables under our belt, let's
discuss some of the conditional keywords which BFE/Script makes use of.

         dumb_function() {
            int x;

            x = getnum();

            if(x < 10) {
              putsnl("Number is less than 10!");
            }

            if(x == 10) {
              putsnl("Number is equal to 10!");
            }

            if(x > 10) {
              putsnl("Number is greater than 10!");
            }
         }

In the above function, we declare a local variable called "x".  We then set
this variable equal to the value returned by the getnum() function (the
getnum() function simply queries the user for a numeric value).  We then put
the contents of "x" through a series of tests, using the "if" keyword.
Simple, eh?

         dumb_function2() {
           int x;

           for(x=1; x<11; x=x+1) {
             print(x);
           }
         }

The above example uses a "for" loop to display the numbers 1 through 10.

         dumb_function3() {
           int x;
           x = 1;
           while(x <= 10) {
             print(x);
             x = x + 1;
           }
         }

This example does the same thing, only instead of the "if" loop, we use a
"while" loop.

         dumb_function4() {
           int x;

           do {
              print(x);
           } while(x <= 10);
         }

In the above example, we use a modified version of the "while" loop, known as
the "do-while" loop.  Simple, isn't it?

Ah, but what would code be without comments?  BFE/Script implements the C-
style "slash-asterisk" comment.

         /* This is my first script! */

Anything which falls in between the /* and the */ is ignored by BFE/Script
and treated as a comment.  Comments may span several lines:

         /* This is my first script!
                 Enjoy!
         */

or how about:

         /* This is my first script!

                 Enjoy it! */

On a final note, all items contained in a BFE script are case-insensitive. In
other words GETKEY() is the same as getkey() or GeTkEy().

That's about all of the help I can provide at this point.  As this feature
expands to new horizons as BFE progresses, the documentation on it will
inherently get better.  Trust me!  Feel free to post your scripts in the
SPHINX echo should you require assistance.  Now, let's move on to the actual
function calls contained with the scripting system.


                        SCRIPT FUNCTION REFERENCE

ADDTIME();

         Adds the passed numeric value to the user's total remaining time
         online.

         Example: /* This adds 5 minutes to the user's time */
                  addtime(5);


CENTERMSG();

         Centers the passed text string on the current line.

         Example: centermsg("Welcome to this script!");


CHANGEEXITSCRIPT();

         Changes the global exit script to the passed script file name.

         Example: ChangeExitScript("NEWEXIT.SCR");


CHECKANSI();

         Returns TRUE if the user is in ANSI graphics mode, or FALSE if
         the user is in standard ASCII/TTY mode.

         Example:
                  ShowGraphicsMode() {
                      int ansi;

                      ansi = checkansi();

                      if(ansi) {
                        centermsg("Graphics Mode: ANSI");
                      } else {
                        centermsg("Graphics Mode: ASCII");
                      }
                  }

CHECKRIP();

         Returns TRUE if the user is in RIP graphics mode, or FALSE if
         the user is not.

CHECKACCESS();

         Returns the current user's security level.

         Example:  int access;
                   access = CheckAccess();
                   puts("Current security level is: ");
                   print(access);
                   putsnl(" ");

CHECKBAUD();

         Returns user's current baud rate.

CHECKNODE();

         Returns the current BFE node number.

CLEARSCREEN();

         Clears the screen both remotely and locally.

         Example: clearscreen();


DISPLAYFILE();

         Displays an ANSI/ASCII/AVATAR/RIP file to the user.  See the section
         on the type "D" menu option for more details on how BFE displays
         external files!

         Examples: Displayfile("WELCOME");
                   Displayfile("WELCOME.TXT");

DOWNLOADFILE();

         Initiates a download session for the passed file.

         Examples: Downloadfile("MASTER.ZIP");
                   Downloadfile("C:\FILES\MASTER.ZIP");


DOWNLOADLIST();

         Allows the user to browse a BFE-style FILES.BBS file, and download
         files from the list.  Functions exactly as its menu type counterpart.
         Simply pass the path that the FILES.BBS resides in.  The filename
         FILES.BBS is assumed at this time.

         Examples: DownloadList("C:\BFE\NEWFILES");
                   DownloadList("C:\SUPPORT\BETAFILE");

ERROR();

         Displays a BFE-style error message.

         Example: Error("Your error message goes here!");


ERRORLEVELLOW();

         Exits the current script and BFE with an errorlevel.  DTR is lowered.
         (Hangs up on user!)

         Example: errorlevellow("100");

ERRORLEVELHI();

         Exits the current script and BFE with an errorlevel.  DTR is left
         high.  (Doesn't hang up on user!)

         Example: errorlevelhi("100");

ESTABLISHGATEWAY();

         This function will establish a gateway session, without the user
         having to actually log in.  This is *extremely* handy if you wish
         to shield the user from the UNIX login prompts, or if you wish to
         write BFE script files which perform automated logins and tasks.
         The only argument you need to pass is the gateway port.  To see this
         function in action, see the SENDFILE.SCR script file in the sample
         SCRIPTS subdirectory included with the BFE distribution archive.
         This script performs an automated login, and simple file transfer.

         Example: EstablishGateway(1);

FLASHFILE();

          Displays a ANS/ASC/AVT/RIP file with no page pausing.

GATEWAY();

         Initiates a BFE "gateway" from one serial port to another.  This is
         used primarily to pass a BFE caller from a DOS environment to a
         UNIX environment, with BFE's gateway feature acting as the mediator.
         See the GATEWAY.DOC file for more information on this feature.

         Example: gateway(1, 1);

GETKEY();

         Gets a keystroke from the keyboard and returns the value.

         Example:  char key;
                   key = getkey();

GETNUM();

         Gets and returns a numeric value from the user.

         Example: int x;
                  x = getnum();


GETRANDOM();

         Returns a random number from 0 to the passed numeric value.

         Example:  /* Get a number from 1 to 100 */
                   int x;
                   x = getrandom(100);
                   x = x + 1

GETSCRBUF();

         Loads the internal script input buffer with a line of user input.
         This value may be substituted in some function calls via a special
         "%B" macro.  Returns 0 is no input, 1 otherwise.

         Example: /* Simple example with no error checking! */
                  puts("Enter a filename: ");
                  GetScrBuf();
                  RunExternal("dsz sz %B");

GOODBYE();

         Hangs up on the user and exits BFE with an errorlevel of 255.

         Example: Goodbye();

IFEXIST();

         Returns TRUE if the passed filename exists (no wildcards allowed!)

         Example:
                 main() {
                   int x;

                   x = ifexist("C:\AUTOEXEC.BAT");

                   if(x) {
                     putsnl("AUTOEXEC.BAT exists!");
                   }
                   if(x==0) {
                     putsnl("Error locating AUTOEXEC.BAT!");
                   }
                 }

LEAVEMSGSDM();

         Places the user in BFE/Edit using the passed message area number.
         The message area templates are configurable in BFE/Setup.
         The "SDM" portion of this command stands for "Star-dot-MSG", or
         "*.MSG", which is the fidonet standard.

         Examples: leavemsgsdm(1);
                   leavemsgsdm(8);


LEAVEMSGSQ();

         Places the user in BFE/Edit using the passed message area number.
         The "SQ" portion of this command stands for "Squish", as this
         function utilizes Scott Dudley's Squish message base format.

         Examples: leavemsgsq(1);
                   leavemsgsq(8);

MAKEDORINFO();

         Creates a DORINFO?.DEF dropfile in the passed directory.

         Example: makedorinfo("C:\BBS\MYDOOR");


MAKEDOORSYS();

         Creates a DOOR.SYS dropfile in the passed directory.

         Example: makedoorsys("C:\BBS\MYDOOR");


MAKESFDOORS();

         Creates a SFDOORS.DAT dropfile in the passed directory.

         Example: makesfdoors("C:\BBS\MYDOOR");

MENU();

         Queries the user for a response.  All valid keystrokes are passed as
         a parameter.  MENU() returns the first valid keystroke.

         Example: char key;

                  putsnl("1 - Option 1");
                  putsnl("2 - Option 2");
                  putsnl("Q - Quit this script");
                  key = menu("12Qq");

MENULINE();

         Displays line of text and hotkey, similar to the way BFE handles
         its default internal menus.  (Text mode only, no RIP!)

         Example:
                 clearscreen();
                 centermsg("Welcome to BFE!");
                 menuline("Go to WildCAT!", "1");
                 menuline("Go to Maximus", "2");
                 menuline("Goodbye", "G");
                 menu("12PG");

OS_SHELL();

         Performs a remote (or local) shell to the contents of COMPSEC.

         Example: os_shell();


PAGE();

         Initiates a page to the sysop.  All hour restrictions are valid!

         Example: page();

PAGENOW();

         Initiates a page to the sysop.  All hour restrictions are IGNORED!

         Example: pagenow();

PASSWORD();

         Accepts a password from the user, and compares it to the password
         which is passed to the function.  Returns TRUE on success, or FALSE
         if the passwords did not match.

         Example:
                 secret_page() {
                   int x;
                   x = password("SECRET");
                   if(x) {
                     pagenow();
                   }
                 }


PLAYMUSIC();

         Plays an ANSI music string on the remote speaker only.

         Example: PlayMusic("MBT120L4MFMNO4");


PRINT();

         Used to display numeric values.

         Example: int x;
                  x = getnum();
                  print(x);

PUTCH();

         Puts a single character to the display.

         Example: putch('*');


PUTS();

         Puts a string to the display (no carriage return/linefeed!).

         Examples: puts("Testing!");
                   puts("!|*|");         /* Clear RIP screen! */


PUTSNL();

         Puts a string to the display, and appends a carriage return/linefeed.
         PUTSNL is short for "put string with a CR/LF pair".

         Example: putsnl("Testing again!");


RUNEXTERNAL();

         Runs an external process.  All "process" macros (%p, %s, %t, %n)
         are available.

         Examples: runexternal("DOOR.EXE -p%p -s19200 -t%t -n%n");
                   runexternal("COMMAND.COM /C del dorinfo1.def");


SETCOLOR();

         Sets the current text attribute.  The following color codes format
         table is used:

            {Bright} {Flashing} [Foreground Color] on [Background Color]

         Where foreground and background colors are one of:

           Black
           Blue
           Green
           Cyan
           Red
           Magenta
           Yellow / Brown
           White / Grey

         Examples: setcolor("bright white on black");
                   setcolor("flashing bright yellow on blue");

SUBTIME();

         Subtracts the passed numeric value to the user's total remaining
         time online.

         Example: /* This subtracts 5 minutes to the user's time */
                  subtime(5);


TOGGLEANSI();

         Toggles ANSI graphics on and off.

         Example: toggleansi();


TRANSMIT2GATEWAY();

         Transmits a command string through an enabled serial gateway port.
         This will be used most prevalently during UNIX gateway sessions.
         This function can be run in one of two methods:  PASSIVE mode or
         ACTIVE mode (similar to the two corresponding menu types).  The
         first argument to the function is the actual command string, and
         the second argument is the "mode" to run in (0=PASSIVE, 1=ACTIVE).
         PASSIVE mode will simply gate the command to the server through
         the gateway port, and will *immediately* return to the calling
         script.  In ACTIVE mode, the user will remain in the gateway
         session, until the RETURN2BFE server command is returned to BFE
         by your application.

         Examples:  /* Run the mail command ACTIVELY */
                    Transmit2Gateway("mail", 1);

                    /* Write a message to the console PASSIVELY */
                    Transmit2Gateway("write root tty01 < /etc/motd", 0);

UPLOADFILE();

         Initiates an upload from the user.

         Example: Uploadfile();


WAIT();

         Forces BFE to "pause" for the passed number of milliseconds.

         Example: /* Pause for 5 seconds */
                  wait(5000);


WRITELOG();

         Used for logging information from BFE/Script.

         Example: writelog("This is a test!");