Defining Methods
You're the best I ever had.
- J.J. Cale
The Method Definition statement creates a single method within the context of where it is defined. If the statement is defined at the module level, the method stands alone, and is not tied to any class. If defined inside a class, it becomes a member of that class. A method is a convenient and practical approach to grouping multiple statements together to perform a specific task. Any number of arguments can be passed into a method, and a method can optionally return a value to be used by the caller in an expression. There can be any number of valid Aztec statements inside the curly brackets of the method statement. Valid statements are defined below.
The following table shows four separate permutations of the method definition statement.
♦ The first usage applies to a method being defined that returns an object of data type 'Type', and it takes no arguments.
♦ The second usage applies to a method being defined that returns an array of 'Type' objects, and it takes three arguments. The parentheses are required since one or more arguments are used.
♦ The third usage applies to a method being defined that returns an object of data type 'Type', and it takes two arguments. The last argument is optional. If the caller does not provide the last argument, the system will send a null argument in its place. One or all arguments can specify a default value like this, with one simple rule. As you go from the first argument (left) to the last argument (right), once a default value is used for a particular argument, all subsequent arguments in the method definition must also use a default argument.
♦ The fourth usage applies to a method being defined that does not return anything. It takes two arguments.
A method can define any number of separate arguments. Parentheses on the method name are optional if the method has no arguments.
Note that method names can be overloaded within a specific context. The Aztec compiler uses the combination of method name and its arguments to determine uniqueness of a method. This means that the same method name can be used multiple times within the same context, as long as each of the methods has a different argument list. Note that default arguments also play into this analysis.
♦ If defined inside a class, the name and signature must be unique within that class (and base classes depending on visibility and other settings).
♦ If defined outside a class, the name and signature must be unique within the module/global scope, depending on visibility settings.
♦ The ‘Type’ returned by a method must be a valid data type and it is optional. If provided, the method must contain a corresponding return statement that returns a value that is consistent with 'Type'. The compiler will give an error if this is not done.
♦ The examples above refer to many different data types, 'Type', 'Type1', 'Type2', etc. Each of these must be a valid Aztec data type, which can be a primitive data type, value or reference, a Class reference or a method reference. A data type created with the "type" statement is also valid. The following table shows the reserved keywords which are valid for all of the data types, along with user defined identifiers, such as classes, enumerations and types.
♦ The "ref" keyword is used only with primitive data types, including int, float, string and bool (e.g. data<string ref>).
♦ Array references for any data type are also allowed, as shown in one of the examples above. Refer to the Aztec Array web page for more details.
♦ The "base" keyword can be used to specify generic method reference data types and generic array references. The "base method" combination is a generic method reference and "base[]" is a generic array reference. These are discussed in more detail in the method reference and array web pages.
♦ The following table shows the keywords that are supported within the method definition statement. The 'method' keyword is the only one that is required.
♦ Methods can be defined at the following scope levels
♦ Module – defined outside of a class. The visibility keywords (public, module, space and unit) can be used to control who can access the global method. Default visibility is ‘unit’ and default space is ‘aztec.script’.
♦ Class – defined within a class. Can be an instance method (access to instance data for each instance of the class), or can be shared (no access to instance data, but has access to shared data for the class). The visibility keywords (public, private, family, module, space and unit) can be used to control who can access the class level method, with a default visibility of ‘unit’.
♦ The 'virtual', 'abstract' and 'final' keywords are used for class methods, and they are described in more detail in the "Inheritance and Polymorphism" web page.
♦ The 'sync' keyword is used to specify the entire method as a "critical section". The Virtual Machine will only allow one Aztec Thread to execute the method at one time. An internal mutex is used to control access to execution of the method. When one VM thread gets control of the mutex, it executes the entire method before releasing the mutex. If one or more other threads try to execute the method while another thread is already executing the method, each thread will wait in a FIFO queue for its turn to execute the method.
♦ If the 'unique' keyword is used, the method name cannot be overloaded within the scope where it is defined. The name itself must be unique amongst all methods within that scope, regardless of argument list contents.
♦ If a method is marked as 'unique', it can be passed as a "method reference" argument directly in a method call. This is useful for registering event handlers.
♦ The 'dynamic' keyword tells the Virtual Machine that the source code for the method can be dynamically recompiled at run-time using the Script.CompileMethod() family of methods.
♦ If the method is recompiled at run-time, existing calls to the method automatically reference the new code once the recompile process is successfully completed.
♦ When a method is marked as 'dynamic', it is also automatically marked as 'sync'. This allows the VM to control and synchronize access to the method while dynamically modifying its executable code.
♦ The 'method' keyword does not have to be the first keyword in the statement, but all keywords (including 'method<>') must come before "MethodName".
♦ The method can contain any number of valid Aztec statements, and they are executed one at a time from top to bottom, except as redirected by control flow statements. The following types of statements are valid inside a method.
♦ Data definition statement for "local" variables
♦ If a data definition statement is defined inside a nested statement block inside the method, the initialization expression for that data definition statement will be executed every time the block is executed.
♦ Assignment statement
♦ Method call statement
♦ Flow control statements
