- Pete Townshend
Script
IScript
Script Methods
| Script() | Constructor for the Script class |
| Name() | Returns the full name of the file associated with the running script |
| NumArgs() | Returns number of commmand line arguments on the Aztec VM command line (-arg xxx) |
| GetArg() | Returns a single command line argument from Aztec command line given one based index |
| GetArgs() | Returns an array of strings corresponding to the Aztec command line arguments |
| IsFlag() | Returns true if the specified flag was used on the Aztec VM command line (-flag xxx) |
| OSVar() | Returns the value of the operating system environmental variable as a string |
| SetOSVar() | Sets the value of the OS environmental variable |
| OSName() | Returns the OS name and version in a string |
| OSExec() | Executes the OS command or launches application |
| CPUName() | Returns the name of the CPU as a string |
| VMVersion() | Returns the Aztec Virtual Machine version as a string (e.g. "1.1 Alpha 2") |
| EnableCancel() | Enables or disables the ability of the user to cancel the VM during execution |
| Thread() | Returns reference to currently executing thread |
| MainThread() | Returns reference to the main thread of the script |
| Display() | Returns reference to the local Display object |
| DefaultFolder() | Returns the current default folder used by the system when opening data files |
| SetDefaultFolder() | Sets a new value for the default folder using a string |
| SetDefaultFolder() | Sets a new value for the default folder using a Folder object |
| GetUnits() | Returns an array of Unit metadata objects associated with the script |
| GetModules() | Returns an array of Module metadata objects associated with the script |
| GetClasses() | Returns an array of Class metadata objects associated with the script |
| Log() | Returns a reference to the script's default SystemLog object |
| WriteLog() | Writes a text string to the script's default SystemLog object |
| LoadModule() | Dynamically compiles a source module (string or file) and integrates code into running program |
| LoadModule() | Dynamically compiles a source module (File object) and integrates code into running program |
| CompileMethod() | Dynamically recompiles source (string or file) for method (base method ref) and integrates code into running program |
| CompileMethod() | Dynamically recompiles source (File object) for method (base method ref) and integrates code into running program |
| CompileMethod() | Dynamically recompiles source (string or file) for method (Method metadata) and integrates code into running program |
| CompileMethod() | Dynamically recompiles source (File object) for method (Method metadata) and integrates code into running program |
| Interpret() | Dynamically compiles and executes source code within context of method in which it is called |
| InterpretInt() | Dynamically compiles and executes source code within context of calling method and returns an integer |
| InterpretFloat() | Dynamically compiles and executes source code within context of calling method and returns a floating point number |
| InterpretStr() | Dynamically compiles and executes source code within context of calling method and returns a string |
| InterpretBool() | Dynamically compiles and executes source code within context of calling method and returns a bool |
| InterpretRef() | Dynamically compiles and executes source code within context of calling method and returns an Aztec object reference |
| SendTextMessage() | Sends a text message to the script |
| SendBinaryMessage() | Sends a binary message to the script |
| SendObjectMessage() | Sends an object message to the script |
| StartMessageServer() | Starts a Message Server thread to receive and process incoming Aztec messages from other Aztec scripts/applications |
| StopMessageServer() | Stops one or more message server threads |
| GetMessageClients() | Returns an array of client names that have connected to the Message Server |
| AddTextMessageHandler() | Registers an event handler for receiving a text message using a method reference |
| AddTextMessageHandler() | Registers an event handler for receiving a text message using an IScript reference |
| AddBinaryMessageHandler() | Registers an event handler for receiving a binary message using a method reference |
| AddBinaryMessageHandler() | Registers an event handler for receiving a binary message using an IScript reference |
| AddObjectMessageHandler() | Registers an event handler for receiving an object message using a method reference |
| AddObjectMessageHandler() | Registers an event handler for receiving an object message using an IScript reference |
| OnTextMessage() | Method to handle TextMessage events |
| OnBinaryMessage() | Method to handle BinaryMessage events |
| OnObjectMessage() | Method to handle ObjectMessage events |
IScript Methods
| OnTextMessage() | Virtual method to handle TextMessage events |
| OnBinaryMessage() | Virtual method to handle BinaryMessage events |
| OnObjectMessage() | Virtual method to handle ObjectMessage events |
Derived Classes
None
See Also
Class Hierarchy, Thread, Display, TextMessageEvent, ObjectMessageEvent, DynamicCodeException, Global Methods
public method Script()
Parameters
None
Return Value
None
Description
Constructor for the Script class. The one and only Script object is created internally by the VM and is available using "GetScript()" and "Thread.Script()".
Script Class
public method<string> Name()
Parameters
None
Return Value
Name of the script's main file
Description
This method returns the name of the script. This is the name of the Aztec source or binary file which is listed first on the Aztec command line.
Script Class
public method<int> NumArgs()
Parameters
None
Return Value
Number of command line arguments
Description
This method returns the number of "-arg" arguments specified on the Aztec commmand line. Each instance of "-arg" can contain one or more values, and there can be multiple instances of "-arg". This method returns the total.
Script Class
public method<string> GetArg(int Index)
Parameters
Index
One based index of the argument
Return Value
Argument from command line for specified index
Description
This method returns the "-arg" argument on the Aztec command line for the specified one based index. If the index is not within the range of 1 to "NumArgs()", the method returns an empty string.
Script Class
public method<string [ ] > GetArgs()
Parameters
None
Return Value
Reference to array containing all command line arguments (null if none)
Description
This method returns an array of strings representing the Aztec command line arguments (e.g. "-arg A1 B1 C1"). If there are no command line arguments specified, this method will return null.
Script Class
public method<bool> IsFlag(string Flag)
Parameters
Flag
Name of flag from command line
Return Value
Returns true if the flag is used on command line
Description
This method returns true if the specified Flag was specified on the Aztec command line using the "-flag" option and returns false if not.
Script Class
public method<string> OSVar(string Variable)
Parameters
Variable
Name of OS environment variable
Return Value
Returns the value of the environment variable
Description
This method returns the value of the operating system environment variable specified by 'Variable'. If it doesn't exist, the method returns an empty string.
Script Class
public method SetOSVar(string Variable, string Value)
Parameters
Variable
Name of OS environment variable
Value
New value for OS environment variable
Return Value
NONE
Description
This method sets a new value for the environment variable. If the variable doesn't exist, it creates it and sets the value. This method only sets the environment variable within the scope of the running application, and any OS applications subsequently launched from it.
Script Class
public method<string> OSName()
Parameters
None
Return Value
Returns the name of the operating system
Description
This method returns the name of the operating system which the Aztec Virtual Machine is running in. This is an OS dependent value, and may or may not include a version number embedded within the string.
Script Class
public method<int> OSExec(string CommandLine)
Parameters
CommandLine
Command to be passed to the OS for execution
Return Value
Returns the error code from the OS
Description
This method executes the specified command with the operating system. The CommandLine string represents the entire command line, which includes the OS command or application name/path together with command line arguments. If the command is executed successfully, the return value is based on the command or application that is executed. Typically, an OS level command returns zero if successful, which is then returned by this method. If an application is executed, the exit code from that application is returned from this methoid. If an error occurs executing the command/application, an OS dependent non-zero value is returned.
Script Class
public method<string> CPUName()
Parameters
None
Return Value
Returns the name of the processor
Description
This method returns the name of the processor running the Aztec VM.The format of the name is processor dependent.
Script Class
public method<string> VMVersion()
Parameters
None
Return Value
Returns the version of Aztec VM
Description
This method returns the version of the Aztec Virtual Machine which is executing this script. This will be in the form "1.0" with an optional "alpha" or "beta" designator, such as "1.0 Alpha".
Script Class
public method EnableCancel(bool EnableFlag = true)
Parameters
EnableFlag
true to allow the user to cancel the VM and false to not allow (true by default)
Return Value
NONE
Description
This method sets the internal flag to indicate whether the user can cancel the Virtual Machine execution while it is running. For the Windows implementation, this means the "Cancel Virtual Machine Execution" item in the system menu is enabled or disabled accordingly based on this setting. The default setting for the flag argument is true, to be consistent with the name of the method. However, the internal setting for the Aztec Engine is false by default, so the user cannot cancel the script/application unless the script specifically allows it by calling this method. The method takes a flag so that it can be dynamically turned on or off as needed based on the application and the sensitivity to being interrupted partway through a specific task.
Script Class
public method<Thread> Thread()
Parameters
None
Return Value
Reference to the current Aztec Thread
Description
This method returns a reference to the currently executing Thread object.
Script Class
public method<Thread> MainThread()
Parameters
None
Return Value
Reference to the main Aztec Thread
Description
This method returns a reference to the main Thread object in the script
Script Class
public method<Display> Display()
Parameters
None
Return Value
Reference to the local Display object
Description
This method returns a reference to the local Display object. This represents the physical workstation running the VM script, and is used as the default parent for top-level windows.
Script Class
public method<Folder> DefaultFolder()
Parameters
None
Return Value
Reference to the current default Folder object
Description
This method returns a reference to the default Folder for the Aztec Script. This folder is used throughout the system as a default when trying to open up data files, in classes such as FileStream, File, Folder and SystemLog, and when the system needs to open up temporary files.
The value of the default directory at startup is determined by stripping the path out of the first Aztec source/executable file and using that. The user can then change it anytime using either of the Script.SetDefaultFolder() methods.
Script Class
public method<bool> SetDefaultFolder(string DefaultFolderName)
Parameters
DefaultFolderName
Name of the folder to be used as default
Return Value
Returns true if the folder was found and it is now the default folder, and returns false if an error occurred
Description
This method sets a new value for the default Folder for the Aztec Script. This implementation takes a string a the input parameter for the new folder.
If the new folder exists and is valid, the system will return true and false if the folder could not be found or accessed.
This folder is used throughout the system as a default when trying to open up data files, in classes such as FileStream, File, Folder and SystemLog, and when the system needs to open up temporary files
The value of the default directory at startup is determined by stripping the path out of the first Aztec source/executable file and using that.
Script Class
public method<bool> SetDefaultFolder(Folder DefaultFolderObject)
Parameters
DefaultFolderObject
Folder to be used as default
Return Value
Returns true if the folder object is valid and the actual folder name still exists, and returns false if an error occurred
Description
This method sets a new value for the default Folder for the Aztec Script. This implementation takes a Folder object as the input parameter for the new folder.
If the new folder exists and is valid, the system will return true and false if the folder could not be found or accessed.
This folder is used throughout the system as a default when trying to open up data files, in classes such as FileStream, File, Folder and SystemLog, and when the system needs to open up temporary files
The value of the default directory at startup is determined by stripping the path out of the first Aztec source/executable file and using that.
Script Class
public method<Unit[]> GetUnits()
Parameters
None
Return Value
Returns an array of Unit objects for the script
Description
This method returns an array of Unit metadata objects associated with the entire script. A "Unit" represents the code and metadata associated a single Aztec compile/build execution. The Aztec framework is built using several Units, and there is at least one more for the executing Script. The Unit class contains methods to retrieve arrays of classes, methods and other items within each Unit.
Script Class
public method<Module[]> GetModules()
Parameters
None
Return Value
Returns an array of Module objects for the script
Description
This method returns an array of Module metadata objects associated with the entire script. A "Module" represents the code and metadata associated a single Aztec source file or string. The Aztec framework is built using several Modules, and there is at least one more for the executing Script. The Module class contains methods to retrieve arrays of classes, methods and data items within each Module.
Script Class
public method<Class[]> GetClasses()
Parameters
None
Return Value
Returns an array of Class objects for the script
Description
This method returns an array of Class metadata objects associated with the entire script. This list represents all classes, regardless of the Unit or Module. The Class class contains metadata associated with a single Aztec class.
Script Class
public method<SystemLog> Log()
Parameters
None
Return Value
Returns a reference to the internal (default) SystemLog object
Description
This method returns a reference to the default VM SystemLog object for the entire script. The default system log object is created automatically by the VM system at startup. The contents of this system log are available via the "Show Virtual Machine Log" option in the tray menu (available using the "-menu" command line option). The SystemLog object is created with no underlying text file by default, but a file can be attached to the SystemLog object by calling "GetScript().Log().SetFile("Name.log")". In addition, if the Aztec "-log XXX" command line option was used, and the file being executed was already compiled by Aztec at a previous time (.azcode), the file name specified will automatically be attached to the default SystemLog object at startup.
Script Class
public method<string> WriteLog(string Record)
Parameters
Record
Text record to be written to the default SystemLog object for the Virtual Machine
Return Value
Returns a copy of the record just written to the internal (default) SystemLog object
Description
This convenience method writes a record into the default VM SystemLog object for the entire script. The system log object is created automatically by the VM system at startup. The contents of this system log are available via the "Show Build and VM Logs" option in the tray menu (available using the "-menu" command line option) and the reference to the underlying SystemLog object is available using the "Script.Log()" method.
Calling this method is equivalent to calling "GetScript().Log().Write(Record)".
Script Class
public method LoadModule(string SourceCode, bool IsFile = false, bool WriteToLog = false)
Parameters
SourceCode
Source code to be compiled and integrated into the running program - string can be a filename or the actual source code
IsFile
If true, first argument is the name of a file which contains source code, and if false, first argument contains the source code itself (false by default)
WriteToLog
If true, normal compiler output will be written to the compiler log (false by default)
Return Value
None
Description
This method allows the user to dynamically compile Aztec source code while the program is running and have that code become part of the running program. If the compile process is successful, the code which is generated is integrated into the running program and then can be immediately executed by the running program after this method call is finished. The source code can reside in a file, in which case the filename is passed into this method (if IsFile is true). The source code can also reside in the string itself, if the IsFile flag is false.
The source code (module) can contain new classes, new global data and methods, and it can also contain satellite classes, which adds methods and shared data to classes which already exist. This allows the generated code to dynamically modify existing classes at run-time. The Aztec Engine rebuilds class hierarchy and virtual method hierarchy tables after the code is built, so it is possible to modify the meaning of existing code by inserting a virtual method into the mix dynamically. If a new class defined within the module contains a shared constructor, or if a satellite class within the module contains a shared constructor, that constructor will be executed before the LoadModule() call completes. Likewise, if a global data item is defined with an initialization expression, that initialization code will be executed before the LoadModule() call completes.
The source code can also include other source modules by calling "CompilerLoadModule()" inside it (using either filename or dynamic source code). The multiple levels of compilation which occur during an initial compilation process also occur within the LoadModule() compilation process.
If the source code compilation process fails (compiler error, file not found, etc.), a "DynamicCodeException" object will be created and fired. Therefore, an "exceptions/handle" block should always be used to contain the LoadModule() call. Currently, the LoadModule() method can only be used when the starting code for the Script was source code which was compiled and passed to the VM (using "-exec"). If the Script was started with a binary executable (.azcode), this LoadModule() method cannot currently be used. Support for using dynamic code generation within binary executables is planned for the future.
In order to work with a new class or method which was added during the LoadModule() call, one option is to use the Script.Interpret() family of methods to dynamically compile and execute code on the fly, which can include the use of new classes and methods.
Script Class
public method LoadModule(File SourceFile, bool WriteToLog = false)
Parameters
SourceFile
Source code to be compiled and integrated into the running program - (filename comes from File object)
WriteToLog
If true, normal compiler output will be written to the compiler log (false by default)
Return Value
None
Description
This method allows the user to dynamically compile Aztec source code while the program is running and have that code become part of the running program. If the compile process is successful, the code which is generated is integrated into the running program and then can be immediately executed by the running program after this method call is finished.
Except for the input arguments, the processing for this method is identical to that for the other Script.LoadModule() method. Please refer to that method for more details.
Script Class
public method CompileMethod(base method MethodRef, string SourceCode, bool IsFile = false, bool WriteToLog = false)
Parameters
MethodRef
Base method reference for the dynamic method that will be recompiled
SourceCode
New method source code to be compiled and integrated into the running program - string can be a filename or the actual source code
IsFile
If true, first argument is the name of a file which contains source code, and if false, first argument contains the source code itself (false by default)
WriteToLog
If true, normal compiler output will be written to the compiler log (false by default)
Return Value
None
Description
This method allows the user to dynamically compile new Aztec source code for a single method (which must be marked as 'dynamic'). The source code can reside in a file, in which case the filename is passed into this method (if IsFile is true). The source code can also reside in the string itself, if the IsFile flag is false. This implementation of the method takes a "base method reference" as an input argument to identify the method to be recompiled.
This recompile process occurs while the program is running and this new code becomes part of the running program. If the method that is being recompiled is actually running when this method is called, the system will wait until that method is done and then the method will be recompiled and updated. This is achieved using standard language facilities. When a method is marked as dynamic, internally it is also marked as 'sync'. So this recompilation will wait its turn to claim ownership of the method, and once it begins compilation, any other calls to this method (from within other running threads), will wait until the compilation and integration of the code is complete. So a "queued up" method call to this method being recompiled will automatically execute the new code once this process is complete.
This new source code completely replaces the current code for the method, but it does not affect the signature of the method, only the body. As such, the new source code must not include the method definitiion statement. The first line of source code in the file/string is the first line of source code WITHIN the method.
If the compile process is successful, the code which is generated is integrated into the running program and then can be immediately executed by the running program after this method call is finished.
Since the code replaces a single method, the source code must conform to valid Aztec source that resides inside a method (e.g. classes and methods cannot be defined inside a method). There is also an extra rule applied to dynamic replacement of method source code. If templates are used within the method, the combination of template class and "embedded" classes must have already been created at the time of the recompile process. This could be achieved during the original compilation of the entire script, or using a dynamic Script.LoadModule() call, both of which allow the creation of new template data types. An example would be to use the data definition statement "data<List<Thread>> MyThreadList" in the new dynamic source code, if the "List<Thread>" combination had not already been built during the original Script compilation or in a LoadModule() call. The compiler will prevent this from happening and flag an error if that occurs. If this is too limiting, consider using one of the more general purpose "LoadModule()" methods which support new classes, new templates, new methods, etc.
If the source code compilation process fails (compiler error, file not found, invalid template usage, etc.), a "DynamicCodeException" object will be created and fired. Therefore, an "exceptions/handle" block should always be used to contain the CompileMethod() call. Currently, the CompileMethod() method can only be used when the starting code for the Script was source code which was compiled and passed to the VM (using "-exec"). If the Script was started with a binary executable (.azcode), this CompileMethod() method cannot currently be used. Support for using dynamic code generation within binary executables is planned for the future.
Script Class
public method CompileMethod(base method MethodRef, File SourceFile, bool WriteToLog = false)
Parameters
MethodRef
Base method reference for the dynamic method that will be recompiled
SourceFile
New method source code file to be compiled and integrated into the running program
WriteToLog
If true, normal compiler output will be written to the compiler log (false by default)
Return Value
None
Description
This method allows the user to dynamically compile new Aztec source code for a single method (which must be marked as 'dynamic'). The source code resides in the file reference by the SourceFile object. This implementation of the method takes a "base method reference" as an input argument to identify the method to be recompiled.
Except for the input arguments, the processing for this method is identical to that for the other three versions of Script.CompileMethod(). Please refer to the method referenced in the link for more details.
Script Class
public method CompileMethod(Method MethodMetadata, string SourceCode, bool IsFile = false, bool WriteToLog = false)
Parameters
MethodMetadata
Method metadata object for the dynamic method that will be recompiled
SourceCode
New method source code to be compiled and integrated into the running program - string can be a filename or the actual source code
IsFile
If true, first argument is the name of a file which contains source code, and if false, first argument contains the source code itself (false by default)
WriteToLog
If true, normal compiler output will be written to the compiler log (false by default)
Return Value
None
Description
This method allows the user to dynamically compile new Aztec source code for a single method (which must be marked as 'dynamic'). The source code can reside in a file, in which case the filename is passed into this method (if IsFile is true). The source code can also reside in the string itself, if the IsFile flag is false. This implementation of the method takes a Method metadata object as an input argument to identify the method to be recompiled.
Except for the input arguments, the processing for this method is identical to that for the other three versions of Script.CompileMethod(). Please refer to the method referenced in the link for more details.
Script Class
public method CompileMethod(Method MethodMetadata, File SourceFile, bool WriteToLog = false)
Parameters
MethodMetadata
Method metadata object for the dynamic method that will be recompiled
SourceFile
New method source code file to be compiled and integrated into the running program
WriteToLog
If true, normal compiler output will be written to the compiler log (false by default)
Return Value
None
Description
This method allows the user to dynamically compile new Aztec source code for a single method (which must be marked as 'dynamic'). The source code resides in the file reference by the SourceFile object. This implementation of the method takes a Method metadata object as an input argument to identify the method to be recompiled.
Except for the input arguments, the processing for this method is identical to that for the other three versions of Script.CompileMethod(). Please refer to the method referenced in the link for more details.
Script Class
public method Interpret(string SourceCode, bool WriteToLog = false)
Parameters
SourceCode
Source code to be compiled and executed on the fly
WriteToLog
If true, normal compiler output will be written to the compiler log (false by default)
Return Value
None
Description
This method allows the user to dynamically compile Aztec source code while the program is running and have that code executed directly on the fly. It is executed within the context of the method in which the Interpret() method is called. It must contain one or more valid Aztec statements. It can only be called from within a method, so unlike Script.LoadModule(), it cannot create new classes, new data, or new methods. However, since it is compiled within the context of a method, the dynamic source code can access local data items within the method, and global data items or global methods within the module or the entire program (depending on the visibility keywords specified for the data or method). If the method which contains the Interpret() call is an instance method within a class, the dynamic source code can access instance data and methods within the class just like any other code in the class.
The dynamic source code contained in the Interpret() call can contain any number of separate valid Aztec statements, including using braces to define blocks of statements, as long as all of the statements are valid within the context of the method which called it.
If the source code compilation process fails (compiler error, file not found, etc.), a "DynamicCodeException" object will be created and fired. Therefore, an "exceptions/handle" block should always be used to contain the Interpret() call. Currently, the Interpret() method can only be used when the starting code for the Script was source code which was compiled and passed to the VM (using "-exec"). If the Script was started with a binary executable (.azcode), this Interpret() method cannot currently be used. Support for using dynamic code generation within binary executables is planned for the future.
Script Class
public method<int> InterpretInt(string SourceCode, bool WriteToLog = false)
Parameters
SourceCode
Source code to be compiled and executed on the fly
WriteToLog
If true, normal compiler output will be written to the compiler log (false by default)
Return Value
int
Description
This method allows the user to dynamically compile Aztec source code which represents an integer expression while the program is running, execute that code directly on the fly, and then return the value of the intgeger expression. It is compiled and executed within the context of the method in which the InterpretInt() method is called. The source code must contain a valid Aztec integer expression. The expression can be as complex as needed as long as it returns an integer. If the method which contains the InterpretInt() call is an instance method within a class, the dynamic source code can access instance data and methods within the class just like any other code in the class.
If the source code compilation process fails due to a compiler error, a "DynamicCodeException" object will be created and fired. Therefore, an "exceptions/handle" block should always be used to contain the InterpretInt() call. Currently, the InterpretInt() method can only be used when the starting code for the Script was source code which was compiled and passed to the VM (using "-exec"). If the Script was started with a binary executable (.azcode), this InterpretInt() method cannot currently be used. Support for using dynamic code generation with binary executables is planned for the future.
Script Class
public method<float> InterpretFloat(string SourceCode, bool WriteToLog = false)
Parameters
SourceCode
Source code to be compiled and executed on the fly
WriteToLog
If true, normal compiler output will be written to the compiler log (false by default)
Return Value
float
Description
This method allows the user to dynamically compile Aztec source code which represents a floating point expression while the program is running, execute that code directly on the fly, and then return the value of the float expression. It is compiled and executed within the context of the method in which the InterpretFloat() method is called. The source code must contain a valid Aztec floating point expression. The expression can be as complex as needed as long as it returns a float. If the method which contains the InterpretFloat() call is an instance method within a class, the dynamic source code can access instance data and methods within the class just like any other code in the class.
If the source code compilation process fails due to a compiler error, a "DynamicCodeException" object will be created and fired. Therefore, an "exceptions/handle" block should always be used to contain the InterpretFloat() call. Currently, the InterpretFloat() method can only be used when the starting code for the Script was source code which was compiled and passed to the VM (using "-exec"). If the Script was started with a binary executable (.azcode), this InterpretFloat() method cannot currently be used. Support for using dynamic code generation with binary executables is planned for the future.
Script Class
public method<string> InterpretStr(string SourceCode, bool WriteToLog = false)
Parameters
SourceCode
Source code to be compiled and executed on the fly
WriteToLog
If true, normal compiler output will be written to the compiler log (false by default)
Return Value
string
Description
This method allows the user to dynamically compile Aztec source code which represents a string expression while the program is running, execute that code directly on the fly, and then return the value of the string expression. It is compiled and executed within the context of the method in which the InterpretStr() method is called. The source code must contain a valid Aztec string expression. The expression can be as complex as needed as long as it returns a string. If the method which contains the InterpretStr() call is an instance method within a class, the dynamic source code can access instance data and methods within the class just like any other code in the class.
If the source code compilation process fails due to a compiler error, a "DynamicCodeException" object will be created and fired. Therefore, an "exceptions/handle" block should always be used to contain the InterpretStr() call. Currently, the InterpretStr() method can only be used when the starting code for the Script was source code which was compiled and passed to the VM (using "-exec"). If the Script was started with a binary executable (.azcode), this InterpretStr() method cannot currently be used. Support for using dynamic code generation with binary executables is planned for the future.
Script Class
public method<bool> InterpretBool(string SourceCode, bool WriteToLog = false)
Parameters
SourceCode
Source code to be compiled and executed on the fly
WriteToLog
If true, normal compiler output will be written to the compiler log (false by default)
Return Value
bool
Description
This method allows the user to dynamically compile Aztec source code which represents a bool expression while the program is running, execute that code directly on the fly, and then return the value of the bool expression. It is compiled and executed within the context of the method in which the InterpretBool() method is called. The source code must contain a valid Aztec bool expression. The expression can be as complex as needed as long as it returns a bool. If the method which contains the InterpretBool() call is an instance method within a class, the dynamic source code can access instance data and methods within the class just like any other code in the class.
If the source code compilation process fails due to a compiler error, a "DynamicCodeException" object will be created and fired. Therefore, an "exceptions/handle" block should always be used to contain the InterpretBool() call. Currently, the InterpretBool() method can only be used when the starting code for the Script was source code which was compiled and passed to the VM (using "-exec"). If the Script was started with a binary executable (.azcode), this InterpretBool() method cannot currently be used. Support for using dynamic code generation with binary executables is planned for the future.
Script Class
public method<Base> InterpretRef(string SourceCode, bool WriteToLog = false)
Parameters
SourceCode
Source code to be compiled and executed on the fly
WriteToLog
If true, normal compiler output will be written to the compiler log (false by default)
Return Value
Base
Description
This method allows the user to dynamically compile Aztec source code while the program is running. The source code represents an expression which returns a reference to any valid Aztec object, execute that code directly on the fly, and then return the value of the expression (as a 'Base' reference). It is compiled and executed within the context of the method in which the InterpretRef() method is called. The source code must contain a valid Aztec expression returning a reference. The expression can be as complex as needed as long as it returns a valid reference to an Aztec object. If the method which contains the InterpretRef() call is an instance method within a class, the dynamic source code can access instance data and methods within the class just like any other code in the class.
If the source code compilation process fails due to a compiler error, a "DynamicCodeException" object will be created and fired. Therefore, an "exceptions/handle" block should always be used to contain the InterpretRef() call. Currently, the InterpretRef() method can only be used when the starting code for the Script was source code which was compiled and passed to the VM (using "-exec"). If the Script was started with a binary executable (.azcode), this InterpretRef() method cannot currently be used. Support for using dynamic code generation with binary executables is planned for the future.
Script Class
public method SendTextMessage(string TextMessage, int ApplicationSpecifiedId = 0)
Parameters
TextMessage
String to be sent as message to event handlers
ApplicationSpecificId
Can be any integer for the application to use any way it wants. Default value of zero.
Return Value
NONE
Description
This method sends the specified text string to the script as a message, resulting in all registered text message event handlers to be executed.
The application specified Id argument has no effect on the "send" process. It is simply an extra piece of data that the application (the "sender" of the message AND the "receiver(s)" of the message (event handlers)) can use in any way it wants.
Script Class
public method SendBinaryMessage(MemoryStream BinaryMessageBuffer, int NumberOfBytes = 0, int ApplicationSpecifiedId = 0)
Parameters
MemoryStream
Reference to the MemoryStream object that contains the binary data
NumberOfBytes
Specifies a max number of bytes to write, otherwise uses all data from current I/O position to end of the stream
ApplicationSpecificId
Can be any integer for the application to use any way it wants. Default value of zero.
Return Value
NONE
Description
This method sends a "binary" message to this script. The data to be sent in the message is extracted from the MemoryStream object and sent to this script as a message (could be from the same script or from a remote script). The amount of data to be sent depends on the current I/O position within the stream, the total amount data in the stream, and value of the "NumberOfBytes" argument. If "NumberOfBytes" is zero (which is the default), the message will consist of all data from the current I/O position to the end of the stream. If "NumberOfBytes" is greater than zero, then the amount of data sent will be limited by that amount. If the total amount of data left in the stream exceeds this specified limit, then the message size is truncated at the limit. If the amount of data left in the stream is less than or equal to the limit specified (unless zero), then the remainder of the data in the stream is sent.
It is important to set the current position in the memory stream prior to sending the message. After data is written into the memory buffer, the stream position will be after the last write operation, by default. If the memory buffer is sent in that state, the system will try to read from it, and will fire an exception if there is no data to read. After the memory stream is filled, the stream position should be manually set to the correct position before the message is sent.
This results in all registered binary message event handlers (for this script) to be executed. When a handler is executed, each handler gets its OWN copy of a MemoryStream object containing that data that was sent from the original incoming MemoryStream object. Each handler's MemoryStream object (and the data within the stream) is unique and independent of each other, as well as independent from the original stream. All changes made to the receiver's copy of the MemoryStream object affect only that object.
The application specified Id argument has no effect on the "send" process. It is simply an extra piece of data that the application (the "sender" of the message AND the "receiver(s)" of the message (event handlers)) can use in any way it wants.
Script Class
public method SendObjectMessage(Base ObjectMessage, int ApplicationSpecifiedId = 0)
Parameters
ObjectMessage
Object to be sent as message to event handlers
ApplicationSpecificId
Can be any integer for the application to use any way it wants. Default value of zero.
Return Value
NONE
Description
This method sends the specified Aztec object to the script as a message, resulting in all registered object event handlers to be executed. This can be any type of object, but the handlers can be registered on a class by class basis, so only those handlers which are applicable (based on the ObjectMessage class) will be executed.
The application specified Id argument has no effect on the "send" process. It is simply an extra piece of data that the application (the "sender" of the message AND the "receiver(s)" of the message (event handlers)) can use in any way it wants.
Script Class
public method<bool> StartMessageServer(int PortId)
Parameters
PortId
Port number used to listen for incoming Aztec messages
Return Value
true if successful and false if not
Description
This method starts an Aztec message server thread which listens on the specified TCP/IP port for incoming Aztec messages. These messages can come from other Aztec scripts/applications executing on either the same machine or a remote machine. Text and Binary messages can be sent this way.
The Aztec server script/application executes this StartMessageServer() method, and then one or more Aztec client scripts/applications create a MessageClient object. This client object is then used to connect to the message server in this script, at which point the client can send text or binary messages to this script.
In order to receive the messages, the Aztec server code needs to register a method to receive that type of message (text or binary) at the Script level (using Script.AddTextMessageHandler() or Script.AddBinaryMessageHandler()). This same event handler method will receive Script messages sent from inside this script, or from outside scripts using the MessageClient and connecting to this message server.
Note that more than one message server can be running at the same time, but they must each use a unique TCP/IP port number..
Script Class
public method StopMessageServer(int PortId = 0)
Parameters
PortId
Port number associated with the Message Server to be shut down
Return Value
NONE
Description
This method stops one or more Aztec message servers, based on the PortId passed in. If a value of zero is passed in (default), all current message servers are shut down. If a non-zero PortId is passed in, only the message server associated with that port will be shut down. The message server will distribute any queued up incoming messages to the appropriiate message handlers within this script before shutting down.
Script Class
public method<string [ ] > GetMessageClients()
Parameters
None
Return Value
Array of strings for client names/addresses that have connected via message servers
Description
This method returns an array of strings representing the names of each of the message clients that have connected to any of the message servers. The client names are entered in the order in which they connected to the Message Servers. The client side code uses the MessageClient.Connect() method to connect to the message server. This array can be useful to determine who has connected in case the "server" code wants to try to connect back to the client.
This method returns null if no client connections have occurred.
Script Class
public method AddTextMessageHandler(TextMessageHandler Handler, Base ExtraObject = null)
Parameters
Handler
Method reference to be executed when the event occurs
ExtraObject
Optional object which will be sent along to each event handler when it is executed
Return Value
NONE
Description
This method registers a method reference to be executed when a text message is sent to the script. An optional object can also be registered which will be sent to each event handler as it is executed.
Note that this text message can come from within the same running script, or it can also come from an independent script running on either the same machine or on a remote machine. The TextMessageEvent object contains information about the sender of the message.
The TextMessageHandler data type represents a method reference specific to a handler for TextMessageEvent. TextMessageHandler is defined as follows:
public type<method<TextMessageEvent,Base>> TextMessageHandler
Given this definition, the method handler must be defined with the following signature (name can be anything):
public method TextMessageMethod(TextMessageEvent event, Base Extra) { }.
Script Class
public method AddTextMessageHandler(IScript Interface, Base ExtraObject = null)
Parameters
Interface
Reference to an IScript object
ExtraObject
Optional object which will be sent along to each event handler when it is executed
Return Value
NONE
Description
This method registers an IScript interface object to be executed when a text message is sent to the script. An optional object can also be registered which will be sent to each event handler as it is executed.
Note that this text message can come from within the same running script, or it can also come from an independent script running on either the same machine or on a remote machine. The TextMessageEvent object contains information about the sender of the message.
When a TextMessage is sent to the script, the OnTextMessage() method within the IScript object will be executed.
Script Class
public method AddBinaryMessageHandler(BinaryMessageHandler Handler, Base ExtraObject = null)
Parameters
Handler
Method reference to be executed when the event occurs
ExtraObject
Optional object which will be sent along to each event handler when it is executed
Return Value
NONE
Description
This method registers a method reference to be executed when a binary message is sent to the script. An optional object can also be registered which will be sent to each event handler as it is executed.
Note that this binary message can come from within the same running script, or it can also come from an independent script running on either the same machine or on a remote machine. The BinaryMessageEvent object contains information about the sender of the message.
The BinaryMessageHandler data type represents a method reference specific to a handler for BinaryMessageEvent. BinaryMessageHandler is defined as follows:
public type<method<BinaryMessageEvent,Base>> BinaryMessageHandler
Given this definition, the method handler must be defined with the following signature (name can be anything):
public method BinaryMessageMethod(BinaryMessageEvent event, Base Extra) { }.
Script Class
public method AddBinaryMessageHandler(IScript Interface, Base ExtraObject = null)
Parameters
Interface
Reference to an IScript object
ExtraObject
Optional object which will be sent along to each event handler when it is executed
Return Value
NONE
Description
This method registers an IScript interface object to be executed when a binary message is sent to the script. An optional object can also be registered which will be sent to each event handler as it is executed.
Note that this binary message can come from within the same running script, or it can also come from an independent script running on either the same machine or on a remote machine. The BinaryMessageEvent object contains information about the sender of the message.
When a BinaryMessage is sent to the script, the OnBinaryMessage() method within the IScript object will be executed.
Script Class
public method AddObjectMessageHandler(ObjectMessageHandler Handler, Base ExtraObject = null)
Parameters
Handler
Method reference to be executed when the event occurs
ExtraObject
Optional object which will be sent along to each event handler when it is executed
Return Value
NONE
Description
This method registers a method reference to be executed when an object message is sent to the script. An optional object can also be registered which will be sent to each event handler as it is executed.
The ObjectMessageHandler data type represents a method reference specific to a handler for ObjectMessageEvent. ObjectMessageHandler is defined as follows:
public type<method<ObjectMessageEvent,Base>> ObjectMessageHandler
Given this definition, the method handler must be defined with the following signature (name can be anything):
public method ObjectMessageMethod(ObjectMessageEvent event, Base Extra) { }.
Script Class
public method AddObjectMessageHandler(IScript Interface, Base ExtraObject = null)
Parameters
Interface
Reference to an IScript object
ExtraObject
Optional object which will be sent along to each event handler when it is executed
Return Value
NONE
Description
This method registers an IScript interface object to be executed when an object message is sent to the script. An optional object can also be registered which will be sent to each event handler as it is executed.
When an ObjectMessage is sent to the script, the OnObjectMessage() method within the IScript object will be executed.
Script Class
public method OnTextMessage(TextMessageEvent MsgEvent, Base ExtraObject)
Parameters
MsgEvent
TextMessageEvent object associated with the event
ExtraObject
Optional object sent along from when it was registered
Return Value
NONE
Description
This method is the event handler for TextMessageEvent. It is invoked internally as a result of the Script.SendTextMessage() method being executed. This method in turn executes every registered handler with the same argument list which comes in. Both implementations of the Script.AddTextMessageHandler() method register the event handlers which get invoked by this method.
Script Class
public method OnBinaryMessage(BinaryMessageEvent MsgEvent, Base ExtraObject)
Parameters
MsgEvent
BinaryMessageEvent object associated with the event
ExtraObject
Optional object sent along from when it was registered
Return Value
NONE
Description
This method is the event handler for BinaryMessageEvent within the script. It is invoked internally as a result of the Script.SendBinaryMessage() method being executed. This method in turn executes every registered handler with the same argument list which comes in. Both implementations of the Script.AddBinaryMessageHandler() method register the event handlers which get invoked by this method.
Note that this binary message can come from within the same running script, or it can also come from an independent script running on either the same machine or on a remote machine. The BinaryMessageEvent object contains information about the sender of the message.
.
Each instance of an event handler being executed based on a single message being sent will receive its own copy of the MemoryStream object. The contents will be the same for all instances, but each instance has its own copy, so modifications to any instance of the MemoryStream object will not affect the contents of the MemoryStream objects in other event handler instances.
Script Class
public method OnObjectMessage(ObjectMessageEvent MsgEvent, Base ExtraObject)
Parameters
MsgEvent
ObjectMessageEvent object associated with the event
ExtraObject
Optional object sent along from when it was registered
Return Value
NONE
Description
This method is the event handler for ObjectMessageEvent. It is invoked internally as a result of the Script.SendObjectMessage() method being executed. This method in turn executes every registered handler with the same argument list which comes in. Both implementations of the Script.AddObjectMessageHandler() method register the event handlers which get invoked by this method.
Script Class
public method virtual OnTextMessage(TextMessageEvent MsgEvent, Base ExtraObject)
Parameters
MsgEvent
TextMessageEvent object associated with the event
ExtraObject
Optional object sent along from when it was registered
Return Value
NONE
Description
This virtual method is the event handler for TextMessageEvent within the IScript interface class. The method which overrides it is invoked for TextMessageEvent within the Script object when the interface object is registered with the Script.AddTextMessageHandler() method.
IScript Class
public method virtual OnBinaryMessage(BinaryMessageEvent MsgEvent, Base ExtraObject)
Parameters
MsgEvent
BinaryMessageEvent object associated with the event
ExtraObject
Optional object sent along from when it was registered
Return Value
NONE
Description
This virtual method is the event handler for BinaryMessageEvent within the IScript interface class. The method which overrides it is invoked for BinaryMessageEvent within the Script object when the interface object is registered with the Script.AddBinaryMessageHandler() method.
IScript Class
public method virtual OnObjectMessage(ObjectMessageEvent MsgEvent, Base ExtraObject)
Parameters
MsgEvent
ObjectMessageEvent object associated with the event
ExtraObject
Optional object sent along from when it was registered
Return Value
NONE
Description
This virtual method is the event handler for ObjectMessageEvent within the IScript interface class. The method which overrides it is invoked for ObjectMessageEvent within the Script object when the interface object is registered with the Script.AddObjectMessageHandler() method.
IScript Class