Sub
From Xojo Documentation
Declares the name, parameters, and code that form the body of a subroutine (method).
Usage
For use in XojoScript code:
Sub name [(parameterList)]
[local variable declarations]
[statements]
[ Return ]
[statements]
[exception handlers]
[ Finally ]
End [sub]
| Part | Description |
|---|---|
| name | The name of the subroutine (method); it follows standard variable naming conventions. You cannot use Reserved Words words in naming a method or function. |
| parameterList | Optional list of values representing parameters that are passed to the Subroutine when it is called. Multiple parameters are separated by commas.
You can optionally assign a default value to a parameter. The default value can be a literal, a constant, or an enum. |
Notes
The Sub statement is used to define a method that does not return a value. Methods are usually associated with an object (exceptions are global methods or functions that are part of a module). All executable code must be in a Sub or Function statement. A Sub cannot be defined inside another Sub or Function. A Sub executes each line of code from the top down, assuming that you have not used the GoTo statement. Once the last line of code is executed, control returns to the line following the statement that called the Sub.
Declaring Parameters
When you declare parameters, you declare the name of each parameter and its data type in the form:
If you declare more than one parameter, separate each declaration with a comma. You can optionally set a default value for the parameter using the syntax:
For example, if you want to declare the parameter "StartValue" as an Integer and give it value of 1, you would write
You can provide default values for more than one parameter. For example, the following is valid:
When you pass a default value, you can use either a literal (as shown here), a constant, or an enum. If you don't provide a default value, the parameter takes the default value for the data type, e.g., 0 for numbers, a null string ("") for strings.
You use the same syntax to use a constant as the default value. For example, suppose you define a global constant in a module, InitialValue. You can use it as a default value for a parameter like this:
Similarly, you can use an enum as a default value. Suppose you have created an enum in a module called SecurityLevel, with values None, Minimum, Maximum, and Forced. You can then assign the default value of a parameter using one of the enum values:
When a method is called, you have the option of passing a value to a parameter using the assignment operator. For example, you can pass the value of 10 to an Integer parameter of the method myMethod using the syntax:
You can also make a parameter optional. If you need to specify that one of the parameters in the method is optional without giving it a default value, use the Optional keyword. This modifier precedes the parameter name. An optional parameter does no take on a default value in the called method. If the caller omits this parameter, it will receive the standard default value for its data type.
When you pass a value to a method, you have the option of using the assignment operator. For example, you can pass the value of 10 to a method using the statement:
However, the assignment operator can be used only if you use the Assigns keyword when you declare the method. For example, if the method "myMethod" takes one parameter and the Assigns keyword is used, the declaration would be:
You could then call myMethod and provide the default value for StartValue with the statement:
You can use the Assigns keyword with methods that take more than one parameter, but only the last parameter can use Assigns. For example, the following declaration is valid:
With this declaration, the method can be called like this:
When you use the Assigns keyword, you cannot use the 'normal' syntax shown below:
An array can be passed as a parameter. To specify that a parameter is an array, place empty parentheses after the name of the array in the declaration. You can pass multi-dimensional arrays without specifying the number of elements in each dimension, but you need to indicate the number of dimensions. Do this by placing one fewer commas in the parentheses than dimensions.
See the Function statement for more information.
By default, parameter passing is done by value and the value cannot be modified by the method. You can also pass a parameter by reference. When you pass a parameter by reference, a pointer to the object is passed. This allows you to return a value using the parameter.
If you want to pass a parameter by reference, precede it by the keyword ByRef in the parameter list, e.g., ByRef MyInt as Integer).
You call a Sub by using its name followed by any parameters in parentheses.
Variables
Variables used in a Sub can be global, public, protected, private, or local in scope. Global variables can be accessed from within any Sub or Function. They exist from the moment the application runs to the time it quits. Global variables are created by creating properties of a module and declaring their scope Global. Public variables (a.k.a. properties) work like global properties except that the name of the owning window, class, or module must be used when referring to them, e.g., "module1.publicProperty". Private and protected properties are available only within the owning object and are called using the name of the owning window, class, or module.
Local variables are variables that are created each time the Sub is run and destroyed when the Sub finishes. Consequently, they can only be accessed by the statements within the Sub. They are created by using the Var statement from within a Sub or Function. A Var statement can appear anywhere within the Sub.
The Return statement can be used to immediately return control to the statement that called the Sub.
Exception handlers are statements that handle runtime errors. See the RuntimeException class and the Exception and Try statements for more information.
Sometimes a method needs to do some cleanup work whether it is finishing normally or aborting early because of an exception. The optional Finally statement at the end of the method runs after the exception handlers, if it has any. Code in this block will be executed even if an exception has occured, whether the exception was handled or not.
Constants
The built-in metaconstant CurrentMethodName is available in all methods and events. It automatically contains the fully qualified name of the method or event. It is the same as if the user had declared the constant manually:
For example, if you create a method, MyNewMethod, belonging to Window1 that has the code:
A call to this method will display the name "Window1.MyNewMethod".
Functions
If you need your method to return a value, you will want to declare it as a Function. A Function is a method that can return a value. The value can be a one-dimensional array. A Sub method can call itself resulting in recursion. Too much recursion can lead to StackOverFlowException errors.
See Also
Break, Catch, Exit, Finally, Function, Return statements; RuntimeException class; Exception, Try statements; CurrentMethodName constant.