You can check out anytime you like...
But you can never leave.
- Don Felder, Don Henley and Glenn Frey
The Aztec Engine system is a single Windows executable program which includes the Aztec Build system, Aztec Virtual Machine, Aztec Class Framework and several other run-time components which are described below. The Aztec Engine contains all the tools necessary to compile and execute programs written in the Aztec Programming Language.
From a user perspective, there are four primary applications (modes) available when running the Aztec Engine, and the components described below all work closely together to support these four operating modes.
♦ Execute mode - Executes an Aztec script/application (source or binary).
♦ Source files are compiled automatically if applicable.
♦ Compile mode - Compiles one or more Aztec source files and creates an Aztec bytecode executable (.azcode)
♦ Create a single Aztec executable ready for execution.
♦ Interpret mode - Runs the Ad Hoc Interpret UI along with an empty Aztec Virtual Machine session
♦ Provides a clean sheet to play with various Aztec features with immediate feedback
♦ UI Display Server mode - Runs in a special UI server mode that accepts connections from remote Aztec Scripts and displays the remote UIs on the Display Server
♦ All UI Events are sent back to client Aztec script for processing.
Aztec Engine Command Line Options
The following table lists the Aztec Engine command line options. The top five lines are italicized to indicate that those four option keywords represent the four separate Aztec applications mentioned above. The first line, with no option keyword, runs the Engine in Execute mode.
Aztec Engine command line options are all case sensitive. Each "flag" or option must begin with the '-' or '/' character, and must match one of the option names shown above. Some options take one or more values, some take exactly one, and some take none. In addition to the options specified directly on the command line, the Aztec Engine supports an OS environment variable named 'AztecArgs' which can also contain more Aztec Engine options. The options from both sources are combined together and processed as one. Options are provided to control if and when the AztecArgs options are processed, as described below.
Rules for command line option usage are shown below, and they apply to the command line and the AztecArgs variable.
♦ These flags accept multiple values after the option.
♦ -exec, -comp, -path, -arg, -use, -flag, -remove
♦ These flags accept one value after the option.
♦ -display, -main, -space, -log, -argmode
♦ These flags do not accept a value after the option
♦ -interpret, -menu, -fore, -back, -fullexpr, -implicit, -stdio, -logo, -debug, -help
♦ The following four flags are used to specify one of the four main applications (modes) that the Aztec Engine provides. Each of these options should be used only once.
♦ -comp, -exec, -interpret, -display
♦ As mentioned above in the table, the source or executable file(s) can be listed without an option if they are the first parameters entered on the command line. The '-exec' option is then assumed.
♦ All of the other Aztec command line options can be used multiple times, though this should be done with caution. All command line options are processed from left to right, and the AztecArgs parameters are processed before the OS command line options by default (options to change this are described below). The following rules apply to an option being used more than once.
♦ For options that accept multiple values, values from each usage get added to the cumulative list.
♦ For options that accept a single value, the new value will override the previous value.
♦ For options that do not accept a value, it does not do anything to repeat the option. There are two mutually exclusive flags, -fore and -back, which can be overridden by subsequent usages. If the "-fore" keyword is specified in the AztecArgs OS variable, using "-back" on the Engine command line option will override the original "-fore" setting.
♦ This allows generic/default values to be specified in the AztecArgs variable and then overridden on the Aztec Engine command line (-main, -log, -space, etc.).
♦ There are two levels of validation for the options specified in the AztecArgs environment variable. The Aztec Engine first parses the string and verifies that it conforms to standard command line syntax. The actual keywords/options are not analyzed at this level - just the fact that options and values were provided with valid syntax. The second level of validation is to process the options and values within the context of the Aztec Engine, per the rules above and the table of valid command line options.
♦ If the AztecArgs string fails the first/generic syntax test, the contents of the variable are simply ignored and the Aztec Engine continues execution with just the command line options.
♦ If the AztecArgs string passes the generic syntax test, but fails the second/Aztec syntax test, the Engine displays an error dialog just as if the error was entered on the command line.
♦ Some other useful, option specific information.
♦ The -arg option accepts one or more arguments to be passed to the Script's execution, and they are available at run-time using Script.Args().
♦ The -argmode option accepts a single value, which can be one, two or three. It controls if and when incoming arguments from the AztecArgs environment variable are processed versus the OS command line options. If argmode is 1 (which is the default), AztecArgs variable options are processed before the OS command line options, If 2, the OS command line options are processed before the AztecArgs options. If 3, the AztecArgs options are not used.
♦ The -flag option accepts one or more flag names for the Aztec Compiler and Virtual Machine. The CompilerIsFlag() method can be used in the compiler to determine if a specific flag name was used on the command line, and Script.IsFlag() can be used at run-time.
♦ The -log option allows the user to attach the specified filename to the Build log or the Virtual Machine log. All log records are written to this file. If running in '-comp' mode, or in 'exec' mode with Aztec source code (as opposed to .azcode), the -log option applies to the Build/Compiler session. If running in '-exec' mode with a binary bytecode file, the -log filename applies to the Virtual Machine log. The Script class provides a SystemLog reference to the VM log file, and SystemLog.SetFile() can also be used to atttach a file to the VM log.
♦ The -debug option turns on debugging in the compiler and the virtual machine. This feature will be expanded in the future, but currently does a single thing. For exception handling, the line number within the source code where exception occurred is tracked and made available to the user. During normal operation, this line number is only tracked to the start of the method where the error happened. The "-debug" option tells the compiler to insert special VM instructions in the binary code to allow this number to be tracked directly to the offending source code line. It increases the size of the executable slightly, and marginally decreases performance.
The following table shows some representative Aztec Engine command line options.
Main Aztec Engine Components
The main components of the Aztec Engine application are listed below, with a brief description of each, along with a list of command line options that are used in that component, if applicable. The Aztec Build System, Virtual Machine, UI Display Server and the Interpret UI are all described in more detail on separate pages.
Aztec Compiler and Build System
♦ Compiles source module(s) and creates a binary Aztec bytecode executable (-comp)
♦ Compiles source module(s) and immediately executes the code by sending the bytecode to the Virtual Machine (-exec)
♦ Compiles and executes source code dynamically at run-time on demand based on request from Class Framework and VM
♦ Integrates the new code at run-time into the Virtual Machine, Script Metadata and updates virtual method hierarchy tables
♦ Applicable command line options: -comp, -exec, -path, -flag, -use, -remove, -space, -fore, -back, -fullexpr, -implicit, -log, -logo, -debug
♦ The Engine also supports the names "-compiler" and "-execute" in place of the "-comp" and "-exec" shortcuts described above.
Aztec Virtual Machine
♦ Executes Aztec bytecode from a binary file previously created by the Aztec Compiler
♦ Executes Aztec bytecode from memory which was just created by the Aztec Compiler from Aztec source module(s)
♦ Manages execution of all Script Threads based on the bytecode and the definition of the Aztec VM Instruction set
♦ Manages Script Metadata with multi-threaded synchronization, and provides multi-threaded event handling infrastructure for Aztec Events
♦ Applicable command line options: -exec, -main, -menu, -arg, -fore, -back, -stdio, -interpret, -debug
Aztec Class Framework
♦ Family of classes in many categories, including Primitive, Compiler, Script and Thread, Thead Synchronization, Metadata, Events and Exceptions, Collections, Steam I/O, Time and Date, Sockets, Sorting and User Interface.
♦ Every method in the Primitive Class Framework is directly tied to a Virtual Machine Instruction to maximize the performance of using primitive classes
♦ UI class framework methods send messages directly to UI Display Server for local UI , and to remote UI Display Server via Sockets for remote UI
♦ Provides access to a remote message server using Aztec Sockets to receive Script messages from a remote Aztec Script
♦ Works together with serialization utilities to provide a simple mechanism for remote object transfer
♦ The entire Aztec Class Framework is documented in detail in the "Class Framework" section of the website
♦ Applicable command line options: N/A
Aztec Sockets Subsystem
♦ Provides TCP/IP socket functionality for the Socket family of classes in the Aztec Class Framework
♦ Provides server functionality and peer-peer client communications for Remote Messaging functionality
♦ Provides server functionality and peer-peer client communications for Remote UI Display Server functionality
♦ Applicable command line options: N/A
Aztec UI Display Server
♦ Provides "Local" UI services for an Aztec Script running in the Virtual Machine within the same instance of the Aztec Engine
♦ Provides "Remote" UI services on one machine for an Aztec Script running on a separate machine
♦ When running the Aztec Engine in "-display" mode, the TCP/IP sockets port number must be specified (e.g. Aztec -display 1081).
♦ Applicable command line option: -display
Aztec Engine System Menu
The Engine displays an Aztec "Z" icon in the Windows system tray, and the system menu is available by right-clicking on the icon. The system tray icon is not always displayed, and depends on the primary Engine application/mode as described above, and the "-menu" command line option.
♦ The system menu icon is also always displayed in "-interpret" mode and "-display" mode, and the user needs to manually shutdown the Aztec Engine using the system menu.
♦ For "-exec" mode, the system menu is always displayed while the Aztec Script is running, but is removed immediately and automatically when the Script terminates, unless the '-menu' option is used.
♦ For "-comp" mode, it is only displayed if the '-menu' option is used.
Care should be used with the '-menu' option, particularly in compile or execute mode. If a script is run repeatedly for testing or debugging with the menu option turned on, a large number of system tray icons could easily result.
The following two pictures show the two main system menus. The first menu is available for "-exec", "-comp" and "-interpret" modes, and the second is available for "-display" mode. The text for the bottom choice in the first system menu will change depending on the current mode and the state of the system. It may also be grayed out.
♦ If the Virtual Machine is still running, "Cancel Virtual Machine Execution" is displayed as shown below (or grayed). It changes to "Shutdown Aztec Engine" once the Aztec Script has terminated.
Aztec Interpret UI and the VM Ad-Hoc Thread
♦ Provides a UI to compile and execute ad-hoc Aztec Source Code within the context of an already executing Script
♦ The Interpret UI can also be used with no separately executing Aztec Script, providing an empty sandbox to play in (e.g. Aztec -interpret)
♦ The feature uses Aztec dynamic code generation to compile, integrate and execute the Aztec source code on the fly
♦ Ad-hoc source code can directly access objects and methods from within a running Script if visibility settings allow it
♦ Provides a useful debugging and unit test environment for running ad-hoc dynamic tests on a running Script
♦ Applicable command line option: -interpret
Aztec Console and Standard I/O
♦ Virtual Machine provides a Console Window to support Aztec Standard I/O read and write services for the framework (StdIO.Read(), StdIO.Write())
♦ If "-stdio" is used on Aztec Engine command line, Virtual Machine redirects StdIO.Read() and StdIO.Write() calls to automatically use Operating System standard I/O services
♦ The StdIO Console is displayed automatically when the first StdIO.Write() statement is performed
♦ Applicable command line option: -stdio
Aztec UI Display Server Statistics
♦ Dialog displays statistics about remote UI Display server processing, which is available in the system menu when running in "-display" mode
♦ For each Display connection, it shows the name, IP Address, connection status, number of UI requests from Cient and number of UI events to the Client
Aztec Message Server Statistics
♦ Though not shown on the menu above, a "Show Message Server Stats" option appears in the menu if the script successfully calls the "Script.StartMessageServer()" method
♦ The dialog is similar to the remote UI server statistics dialog, but the "Port" is a separate column for the Message Server Dialog, since multiple message servers can be used simultaneously
Aztec System Logs
♦ Dialog provides three separate Log File tabs - Initial Build Log, Run-Time Build Log and Virtual Machine Log
♦ Access to these logs is available to the Script using CompilerWriteLog() at compile-time, and Script.Log() at run-time
Aztec Engine Setup
A Zip file containing the Aztec Engine and associated Windows libraries is available for download for free here. Contents of the download Zip file "AztecEngine.zip".
♦ Aztec.exe (1.81 MB)
♦ Microsoft VC and MFC 12.0 Libraries (mfc120.dll, msvcp120.dll, msvcr120.dll)
The Aztec Engine requires no special installation, beyond extracting the binary engine file (named "Aztec.exe") and related VC/MFC libraries from the "AztecEngine.zip" file and placing them into an appropriate directory.
Aztec Engine Execution
There are several ways to execute the Aztec Engine.
♦ A Windows shortcut can be created to run the Aztec Engine with the appropriate command line options to execute an Aztec script.
♦ The "-path" command line option can be used to tell the Aztec Engine where to find the source file(s).
♦ Register the Aztec Engine executable as the default application for ".aztec" and ".azcode" files.
♦ Open one or more Aztec source files ("*.aztec") in Windows Explorer (or other tool) to automatically launch the Aztec Engine and execute the specified source files.
♦ The AztecArgs environmental variable is useful for specifying command line options when launching Aztec in this way.
♦ The Aztec Engine can also be launched from the Windows command line or "Run" dialog.
♦ If a Windows path is set to the directory containing the Aztec engine, it can be executed from any directory.
♦ If executed from the directory containing the Aztec source code, no "-path" is required on the command line.
♦ If the source code resides in a different directory, "-path" command line option should be used, or use the full/relative path to the file.
When the Aztec Engine is executed on a machine for the first time, the Engine displays a special dialog for the user to read and review the Aztec License Agreement. The user must accept the license agreement before the Aztec Engine application can be used on that machine.
When the Aztec Engine terminates, it sets the application exit code with the operating system. This exit code can be used to test the results of running the Engine from an OS command line or in an OS script or batch file. Note that for the Windows version of the Aztec Engine, the Windows "start /wait" command should be used if the Engine's exit code needs to be monitored (command line or batch file). This causes the command processor to wait while the Aztec Engine runs, including in Execute mode, and only returns controls back to the command prompt when the Engine terminates. The exit code is reliably transferred from the Aztec Engine to the operating system when run in this way (start /wait aztec -exec AztecSource).
The return code depends on the mode that the Engine is running in (Compile, Execute, etc.), and also whether the Aztec source code specifies an exit code when it terminates. The following table shows the standard system exit codes for the Aztec Engine based on the application mode and the termination condition. Error codes detected and returned by the Aztec Engine are all less than zero. If the Engine is running in Execute mode, and the Aztec Script terminates successfully, the script/application exit code can be set dynamically by the script using the 'exit' statement.
.
Aztec Engine Overview
