VBossAPI.DLL v1.02.00 (Ver 1.0 Rev 2.00)
Copyright  1995, Greg Truesdell


See VBossAPI.HLP section History of Changes for information on this release.

------------------------------------------------------------------------------------
CHANGES TO SWEETPEA DEMO APPLICATION in Ver 1.0 Rev 2.0
------------------------------------------------------------------------------------

SweetPEA has been augmented to demonstrate a two-pass execution process.  The
first pass collects LABEL information.  The second pass executes the script
normally.

During the first pass, all script instructions and data are parsed as they
would be is the program was executed normally.  The difference is that each
procedure has been modified to skip actual execution.  This allows a number
of syntax error, data type error and forward reference information to be
gathered about the program before it executes.

In this version, I am only parsing for labels.  Once all labels have been
located, the program uses ZapVariables() to clear the variable database; then
the labels are pre-defined.  Now the program can locate labels defined after
the code that needs them.

This opens the door to developing other processes during the first pass.  For
example, you might define procedures and functions which appear after the
final END statement in your script.  Since their location is known, you can
execute their code.

GOSUB ... RETURN has been added to the demo application.

More improvements will come later.  Planned additions are:

    Do .. Loops
    For .. Next
    On Error Goto
    Include Files

Have fun!

------------------------------------------------------------------------------------
EXAMPLE PROGRAM - COMPILABLE VERSION
------------------------------------------------------------------------------------

I have been asked to provide a version of the new VBossAPI.DLL example program
in a from that is compilable by standard Visual Basic v3.0 installations.  This
archive contains a version of SweetPEA that you can modify, compile and run
without anything extra.

If you require the complete shareware release of VBossAPI.DLL (which includes
a comprehensive Windows Help file) please download VBOS61.ZIP from the 
Programming Issues forum in MSBASIC.

In this version I have included more programming examples including:

	Variable Equate Logic
	If .. Then Goto .. Logic
	Relational Expression Logic
	Comment handling
	Source Code Error Marking

plus all the other usual examples.

------------------------------------------------------------------------------------
SOURCE CODE NOTES
------------------------------------------------------------------------------------

All of the functions and procedures needed to implement the interpreter are kept
in ACTIONS.BAS. Windows and VB API constants are kept in IMAGES.BAS.  The main
form file, OSSMAIN.FRM, contains the declarations and procedures to support the
user interface (as well as file I/O).

The interpreter is started after the SetDefaultKeywords() procedure is called. I
have implemented the interpreter in such a way as to support syntax error 
highlighting, so you must pass the TextBox control to most of the supporting
functions and procedures.  In the sample application, the main editor window is
called 'Editor', so starting the interpreter would be:

	Interpret Editor

Once the interpreter is started, I use a Select Case ... End Select construct to
define the command interpreter level. That is the 'outer' or primary command
syntax definition.  The example implements the following language definition:

	DIM variable_identifier AS data_type_identifier

	MSGBOX string_expression[, numeric_expression[,string_expression]

	variable_identifier = expression

	label_identifier:

	INPUT string_expression, variable_identifier

	CHR numeric_expression (usually as Chr(nn))

	IF <relational_expression> THEN GOTO <label>

	END

where
	variable_identifier
	label_identifier

		Up to 16 character string where the first character is not
		a number and all other characters are in 0..9, A..Z, a..z, _

	string expression

		An expression made up of one or more of the following items
		where the + or & character is used for concatenation:

		constant_strings as 'text' or "text"
		string_variables
		numeric_variables
		Chr(nn) character function

	ie: 
		Spain = "in Spain"		
		"The Rain " + Spain + " lies mainly on the plain."

		Note that the + and & characters can be used interchangebly.

	numeric_expression

		A valid infix numeric expression which includes the following
		built-in function:

			PI, ABS, ARCTAN, COS, EXP, LN, SQR and SQRT

		The arithmetic text is evaluated using the correct order
		of precedence and includes (,),*,/,+,- operators as well
		as the unary minus (ie: -1) operator.

------------------------------------------------------------------------------------
SOURCE CODE WRAPPER FUNCTIONS AND PROCEDURES
------------------------------------------------------------------------------------

I have used a number of 'wrapper' functions and procedures in the ACTIONS.BAS
module to simplify the code presentation, as well as to provide single locations
for certain text and error messages, and to implement the 'monitor' list.  The
GetToken() wrapper, for example, wraps up the NextToken() call with the Monitor()
call.  This allows every call to NextToken() to be reported in the 'monitor' 
list window on the right of the source window.

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

Thank you for your interest.  I hope this moderately detailed example helps you to
understand and create scripts and formatters of your own.  I also hope that it will
help you form an informed opinion of VBossAPI.DLL, and that you will pass your
ideas, problems and suggestions along to me.

I will respond promptly, and where necessary, will quickly provide registered
users with an update.  New versions of the Help file will contain a "Thank's To"
section containing the list of individuals who have had a substantial influence
in changes to the library.

Greg Truesdell
CIS: 74131,2175
