Errata for BML User Guide

The following sections either missed the printing of the BML User Guide, or
have been added to the BML system since the manual was printed.

------------------------------------------------------------------------------

                                  Inside BML

The BML          The first time you execute BML, it will create a private file
Configuration    that it will use to maintain information specific to its
File             execution and that of its scripts.  This file is called
                 BML.CFG, and will be created in the directory from
                 where BML is executed.  Since BML is hosted Modeler, that
                 usually means the same directory where Modeler and Layout
                 maintain their configuration files (NewTek/Programs).

                 BML scripts will use this file (albiet, indirectly) to house
                 variable values that are saved using the store() and recall()
                 functions.  Along with these script-owned values, BML
                 maintains two of its own variables.  The first, ScriptPath,
                 is maintained by BML to help it remember where you keep your
                 scripts.  The second, DefaultLib, is discussed next.


Specifying       By employing the library command directly in your BML script,
Default          you can import pre-built or commonly-used BML user-defined
Libraries        procedures.

                 However, instead of having to duplicate often-used library
                 directives in each script, BML allows you to specify default
                 BML libraries to be loaded each time a script is executed.
                 This is accomplished by adding a new entry in the BML
                 configuration file (BML.CFG) called DefaultLib.

                 The contents of this variable are arranged much like an
                 MS-DOS PATH variable.  Each library entry you add to this
                 variable needs to be separated from others using a semi-colon
                 (;) character.  Library file names can contain a path
                 specification--and should if BML cannot locate the file at
                 execution-time.

                 The DefaultLib entry needs to be added to the [BML] area of
                 the configuration file.

                     [BML]
                     ScriptPath=C:\LW\BML
                     DefaultLib=C:\LW\BMLLIB\LIB1.BML;C:\LW\BMLLIB\LIB2.BML
                     ...

------------------------------------------------------------------------------

                            BML Language Structure


The              BML provides script programmers a means of cleaning up their
ONERROR          execution environment when a run-time error occurs.  This is
Procedure        accomplished through the use of the ONERROR() command.  If
                 BML detects that you have defined a procedure with this name,
                 it will be automatically executed if a run-time error occurs.

                 If the 'autoerror' pragma has been omitted from your script,
                 run-time errors are defined as those that occur within the
                 script itself (such as attempts to access uninitialized
                 variables).  However, errors that occur in Modeler-specific
                 commands and functions during run-time will also qualify for
                 this automatic cleanup if 'autoerror' is selected.

                 The "batch.bml" example script contains an illustration of
                 the use of this command.  The following code snippet is taken
                 from that script:

                     ONERROR
                     {
                         commandFile.close();
                         replyFile.close();
                         batchFile.close();

                         filedelete(tmp,"\\snii.job");
                         filedelete(tmp,"\\snii.rpl");

                         terminate(snID);    // shut down ScreamerNet
                     }

                 Because the ONERROR() command does not accept parameters,
                 variables that you need to process at script shutdown need to
                 be declared with global scope (outside any user-defined
                 procedure or main()).


The              ONEXIT() is identical to ONERROR() in that it is an automatic
ONEXIT           command.  However, ONEXIT(), if defined, will be called at
Procedure        script termination if NO run-time errors occur.

                 As with ONERROR(), this command does not accept parameters.
                 Variables that you need to process at script exit need to be
                 declared with global scope.


Disabling        The 'nonrandom' pragma directive will disable the random
Random           access to ASCII text file lines that BML affords to script
File Access      programmers through the use of its line() File Object method.
                 When specified, BML will not pre-process text files (those
                 opened in ASCII mode) to determine line offsets.  Attempts to
                 access the line() method in a script where this pragma is
                 employed will result in a run-time error.

                 If your script tends to deal with large text files without
                 the need to randomly access lines, utilizing this pragma will
                 greatly increase the overall execution speed of your script.

                     #pragma nonrandom


Detecting        During script development, it's possible to clutter your
Unused           creation with unused variables.  In large scripts, it can
Variables        take a great deal of time to locate and purge these "dead"
                 variables.

                 The 'unused' pragma directive causes BML to detect and report
                 on declared variables that are never used (i.e., assigned a
                 value).  When your script has completed execution, BML will
                 display a dialog window for each variable that it determined
                 to be unused.

                 This pragma directive is intended only as a cleanup measure
                 when script development is nearing completion.  It is not
                 supported in the run-time environment.

                     #pragma unused

------------------------------------------------------------------------------

                              Built-In Features


matchfiles       The matchfiles() function returns an array of file names
                 (including path) that match a specific MS-DOS file mask in
                 the specified directory.

                     var files[10];  // max of ten names
                     ...
                     files = matchfiles("\\","*.bat");  // get names of batch
                                                        // files in root
                                                        // directory

chdir            chdir() is one of three directory management functions BML
                 provides to the script programmer.  Using this function, the
                 "working" directory of a BML script can be altered from the
                 directory in which the script was started. This command also
                 returns a character string representing the current "working"
                 directory of the script as a full path.

                 This command can be handy for launching external processes
                 that require a specific directory in which to execute.
                 ScreamerNet is a perfect example of such a process.  For
                 ScreamerNet to properly locate support files--such as
                 configuration files and images--it must be launched from the
                 NewTek/Programs directory.  However, it is entirely possible
                 that your BML script will have begun execution in an entirely
                 different location.  The following code snippet, illustrating
                 the use of chdir(), solves this particular situation:

                     // change the "working" directory to one required
                     //  by ScreamerNet

                     var snDir;
                     var oldDir;

                     // is it (properly) in the environment?

                     if((snDir = getenv("LW3D")) == nil)  
                         oldDir = chdir("\\windows\\apps\\newtek\\programs");
                     else
                         oldDir = chdir(snDir);

                     snID = spawn("lwsn -2 ",
                                  getenv("TMP"),"\\snii.job ",
                                  getenv("TMP"),"\\snii.rpl");

                     chdir(olddir);      // move back to our start-up directory

                 If the chdir() function fails to set the working directory to
                 the one specified, a value of nil will be returned.


mkdir            mkdir() is another directory management function.  With it, a
                 BML script can create a new file system directory.  It
                 accepts a string specifying the directory (with optional
                 path), and returns a result code (0 means no error).


rmdir            rmdir() can be used to remove an existing directory.  The
                 directory to be removed must be completely empty for this
                 command to succeed.

                 As with mkdir(), this command accepts a string specifying the
                 directory (with optional path) to be removed, and returns a
                 result code.


cross3d          cross3d() is used to calculate the cross product of two 3D
                 vectors.


dot3d            dot3d() is used to calculate the dot product of two 3D
                 vectors.


cross2d          cross2d() is used to calculate the cross product of two
                 floating-point values.


dot2d            dot2d() is used to calculate the dot product of two
                 floating-point values.

------------------------------------------------------------------------------
Copyright 1996 Virtual Visions, Inc.
