The BasicLib object provides the following methods and properties.
Methods
Call(sub As String, parameters() As String) : Executes the specified Sub in the script passing it the parameters provided returning its return value. If the Sub takes no parameters Null may be passed for the parameters value. It is only valid to call this after the Ended event has been raised at the end of execution of the initial code block of the script.
CanCall(sub As String) : Returns True if the specified Sub exists in the script otherwise returns False. It is only valid to call this after the Ended event has been raised at the end of execution of the initial code block of the script.
GetArray(var As String) : Returns a copy of the global array named var.
GetArrayItem(var As String, index As Int32) : Returns the contents of the item, index, of the global array named var.
GetArrayLength(var As Int32) : Returns the size of the global array named var.
GetGlobal(var As String) : Returns the contents of the global variable named var.
GetLocal(var As String) : Returns the contents of the local variable named var. The local variable returned is that of the present execution context. i.e. that belonging to the current Sub. If called while execution is in the main code block a global variable is returned if one with the name var exists.
Halt : Stops the program when it reaches the end of the next statement. The Ended event will fire. The line number of the last statement executed may be found in the LineNumber property. The program cannot be resumed once halted but must be restarted if required to run again. This method may be used stop a program if it gets stuck in an endless loop for some reason. If this is called within a Break or Stepped event the program will halt as soon as the event code returns.
LoadCodeAsArray(program As String() ) : Loads the program presented as an array of strings with one line of the program in each string. Returns true if the program loaded properly otherwise returns false. The reason for failure will be in the ErrorString property.
LoadCodeAsString(program As String) : Loads the program presented as a a single string with individual program lines separated by newlines within the string. Returns true if the program loaded properly otherwise returns false. The reason for failure will be in the ErrorString property.
New1(mainform As Form) : Creates a new BasicLib object. mainform must be the main Form of the application and is required in order to give access to the main thread of the application for CallHostSub.
ProgramLine(linenumber As Int32) : Returns the source code of the program for the line number specified.
Run(args As String()) : Runs the presently loaded program again and returns true if the program ran and ended properly otherwise returns false. The reason for failure will be in the ErrorString property. args is an array that may be used to pass arguments to the program to be run as described in Overview.
SetArray(var As String, vals As String[]) : Sets the global array named var to a copy of the array vals.
SetArrayItem(var As String,index As Int32, val As String) : Sets the contents of the item index, of the global array named var to val.
SetGlobal(var As Int32, val As String) : Sets the contents of the global variable named var to val.
SetLocal(var As Int32, val As String) : Sets the contents of the local variable named var to val. The local variable assigned is that of the present execution context. i.e. that belonging to the current Sub. If called while execution is in the main code block a global variable is assigned if one with the name var exists.
ShareArray(var As String, vals As String[]) : Sets the global array named var to the array vals. Unlike GetArray and SetArray which make a copy the specified array is now shared by the main program and the script and changes made by one will be seen by the other.
The following methods are provided for debugging the tokeniser and execution engine and additional technical information about the implemention of both is needed to use this information.
decGlobal(id As Int32) : Returns the name of a global variable given its numeric ID.
decLiteral(id As Int32) : Returns the name of a program literal value given its numeric ID.
decLocal(subname AS String, id As Int32) : Returns the name of a local variable given the Sub name in which it is used and its numeric ID.
decTokenName(tokenvalue As Int32) : Returns the name of a token given its numeric value.
decTokenNameAt(index As Int32) : Returns the token name at position index in the compiled program.
decTokenValue(tokenname As Int32) : Returns the numeric value of a token given its name as a string.
decTokenValueAt(tokenname As Int32) : Returns the token value at position index in the compiled program.
Properties
I signifies readable, O signifies settable.
BreakAtLine : Int32 [I/O] : Gets or sets the line number at which execution will cause the Break event to be raised. A value of 0 disables Break.
DllVersion : Double : Returns the version number of the library.
ErrorString : String : Gets a description of any error that occurred while the program was executing or an empty string if there was no error.
Finished : Boolean : Returns True if the program has finished executing. This is of little use in a single threaded situation but might be of use if the program is being run on a thread.
LineNumber : Int32 : Returns the line number of the next program line to be executed.
MessageString : String : Gets the the content of the last Msgbox statement or the result of the last Print statement.
Program : String() : Returns an array of strings containing the program with one program line in each array element.
ProgramLines : Int32 : Gets the number of lines in the program.
StackDepth : Int32 [I/O] : Gets or sets the size of the call and loop stacks. This determines how many sub-routine calls, For/Do loops or IF statements can be nested. The default is five.
Step : Boolean [I/O] : Gets or sets the state of the Step flag. If set true then the program executes one line at a time raising the Stepped event at the end of each line.
SubjectString : String : Gets the the subject of the last Msgbox statement or "Print" if the last statement was a Print statement.
The following properties are provided for debugging the tokeniser and execution engine and additional technical information about the implemention of both is needed to use this information.
decTokenCount : Int32 : Returns the total numbers of token in the compiled program.
decTokens : String : Returns a string that contains the tokenised version of the program which is what the BasicLib execution engine interprets
Events
Break(linenumber As Int) : Occurs when the program reaches the line specified by BreakLine. The linenumber parameter contains the line that will be executed next.
Ended(error As String) : Occurs when the program terminates. Within this event the GetXXX methods could be used to retrieve the contents of variables if required. If an error occurred it is described in the error parameter which otherwise is an empty string.
Loaded(error As String) : Occurs once the program has finished loading and tokenising. If an error occurred it is described in the error parameter which otherwise is an empty string.
Message(message As String, subject As String) : Occurs when Msgbox or Print are executed. For the message parameter and the property MessageString contains the first parameter of the Msgbox statement and the subject parameter and SubjectString the second, optional, parameter. For Print message and MessageString contain the first parameter of the Msgbox statement and subject and SubjectString contain "Print".
Starting : Occurs once program initialisation is complete and the program is about to start. Within this event the SetXXX methods could be used to initialise global variables if the facility provided by Args() is not sufficient.
Stepped(linenumber As Int) : Occurs after the program has executed one line and the Step property is set to True. The linenumber parameter contains the line that will be executed next.
. The reason will appear in the "Basic4android Share Your Creations" forum tomorrow.
