|
|
|
|
|
- Lesson 6 - Procedures
- Overview
- My first procedure
- Procedure parameters
- What is a parameter?
- Managing parameters: pass by reference or by value
- Return a value
- Mandatory or optional parameters?
- To sum up
Tutorial - WLanguage basicsWe will cover the following topics: - Creating and calling a procedure.
- Procedure parameters.
- Result of a procedure.
20 mn A procedure is used to associate an identifier (a name) with a section of code in order to reuse it. In this lesson, we are going to present the different types of procedures available in WLanguage, how to create them and call them, and how to pass parameters and retrieve a result. To view WLanguage events of the project: - Right-click the "P" button next to the open element tabs. The context menu appears.
- Select "Element code".
- The code editor displays the different events associated with the project.
- If you have completed the previous lessons, delete the code in the "Initialization" event of the project (press Ctrl + A to select all and then press "Delete").
A procedure is a set of instructions with a name. For example, we will write a procedure that simply displays a message. Create a procedure
We're going to create a global procedure in the WLanguage project's procedure collection. This set will contain server procedures. Remember A set of procedures allows you to group all the global procedures of a project. These procedures can be called from any code in the project. - On the "Code" tab, in the "Procedures" group, expand "New" and select "New global procedure (Server)".
- In the window that appears, a default name is displayed for the set of global procedures. Keep this name and validate (click "OK").
- A new window is displayed, allowing you to enter the name of the procedure and its characteristics: Let's take a look at this window for a moment. You can:
- specify the name of the procedure. A default name is displayed, but it can be modified.
- generate a header comment. This comment contains the different characteristics of the procedure. By default, the content of this comment is generated as you write the procedure code. It can also be modified directly.
- define the "scope" of the procedure. By default, a global procedure is public: it can be accessed from any piece of code. In some cases, it is necessary to restrict access to a global procedure. It can be:
- "Restricted". In this case, the global procedure can be accessed by another global procedure in the same or in a different set of procedures in the project.
- "Private". In this case, the global procedure can only be accessed by another global procedure in the set of procedures.
- indicate the role of the procedure. This role is necessary for developing applications that distinguish between Business logic and UI (e.g. with an MV or MVP development method). For more details on this topic, see Splitting Business logic / UI code. By default, this role is "Undefined".
- For our example, we will only change the name of the procedure and keep the default options. Name the procedure "Welcome" and validate.
- The "Welcome" global procedure appears in the code editor. This procedure consists of:
- automatically generated comments.
- of the code:
This code corresponds to the prototype of the procedure.
Remember The key elements of a procedure are the PROCEDURE keyword followed by the name of the procedure and brackets.
- We can write the contents of our procedure. We will simply display a message. Enter the following line of code:
Info("Welcome to my program written in WLanguage")
- And that's it! We now have a procedure. but to see the result of this function, we have to call it. That's our next step.
Calling a procedure To call a procedure, just write its name directly in the code. We will call our procedure from the project initialization code: - Right-click the "P" button next to the open element tabs. The context menu appears.
- Select "Element code".
- The code editor displays the different events associated with the project.
- Clear the initialization process and write the following code:
- Let's test this code right away: click on among the quick access buttons.
- The web browser opens and shows an information window. Our procedure was executed successfully. You can validate the information window.
We created a global procedure in this example. WLanguage supports 3 types of procedures: - Global procedure This type of procedure can be called in all project events and processes (procedure declared in a collection of procedures). For more details, see Global procedure.
- Local procedure to a Window, Page or Mobile Window: this type of procedure can be called in all events and processes dependent on the object in which this procedure has been declared. For more details, see Local procedure.
It is also possible to create procedures that are local to a control. These procedures can be used in all WLanguage events associated with the control. - Internal procedure to a process or event: this type of procedure can only be called in the process or event in which it has been declared. For more details, see Internal procedure.
What is a parameter? A parameter is a value sent to a procedure when the procedure is called. Hands-on example To understand how a procedure with parameters works, we will create a new procedure for removing spaces from a string. To create the new procedure: - On the "Code" tab, in the "Procedures" group, expand "New" and select "New global procedure (Server)".
- If necessary, select the "ServerProcedures" set of procedures and validate.
- In the window that appears, name the procedure to be created. For this example, name the procedure "RemoveSpaces".
- Validate. The "RemoveSpaces" global procedure appears in the code editor.
- Write the following code:
PROCEDURE RemoveSpaces(StringToProcess is string)
StringToProcess = StringToProcess.Replace(" ", "")
Trace("The string without spaces is: [%StringATraiter%]")
In this code, the procedure manipulates the string passed as a parameter. Spaces are removed (replaced with an empty string). Let's analyze several points: - This procedure takes the StringToProcess parameter. You can pass multiple values as parameters to a procedure, or no values at all. These values can be of any type (as with variables).
- StringToProcess is a typed parameter. In the procedure declaration, it is specified that "StringATreater is a string": it will not be possible to use this procedure by passing a numerical value as a parameter, for example.
- In the project initialization code, replace the code with the call to the procedure:
MyString is string
MyString = "Welcome to my program written in WLanguage"
RemoveSpaces(MyString)
- Let's test this code right away: click on among the quick access buttons.
- If necessary, display the "Debugger trace" pane to see the result: under the "Home" pane, in the "Environment" group, pull down "Panes" and select "Panes" then "Debugger trace".
- The following result will appear in the trace window:
The string without spaces is: Welcome to my program written in WLanguage
Managing parameters: pass by reference or by value In WLanguage, parameters are passed by reference (or by address). The parameter in the procedure represents (references) the variable passed during the call. Therefore, when a statement of the procedure modifies the value of the parameter, the value of the corresponding variable is modified in the calling code. Let's go back to our example: - In our example, the MyString variable is modified. To check this, simply add the following line of code after the call to the procedure:
Trace("MyString: " + MyString)
- After the test, the "Debugger trace" pane will display:
The string without spaces is WelcometomyprogramwritteninWLanguage MaChaîne: Welcome to my program written in WLanguage
To avoid modifying the value of the variable corresponding to the parameter, the parameters must be passed by value. Passing parameters by value allows you to manipulate a copy of the actual parameter's value. If the procedure code modifies the variable value, the value of the variable corresponding to the parameter is not modified. To pass a parameter to a procedure by value, you must use the LOCAL keyword before the parameter name in the procedure declaration. This keyword indicates that the following parameter will not be modified by the procedure. Let's try this functionality in our example: - Move the cursor to the name of the "RemoveSpaces" procedure.
- Press F2. The WLanguage code of the "RemoveSpaces" procedure is displayed.
- Modify the procedure declaration code as follows:
PROCEDURE RemoveSpaces(LOCAL StringToProcess is string)
- Let's test this code right away: click on among the quick access buttons.
- After the test, the "Debugger trace" pane will display:
The string without spaces is WelcometomyprogramwritteninWLanguage MaChaîne: Welcome to my program written in WLanguage The MyString variable is no longer modified.
In the same procedure, some parameters can be passed by reference while other parameters can be passed by value. Simply use the LOCAL keyword before each parameter passed by value. Return a value A procedure can return a value. Some examples: - A procedure can return a boolean (True/False) depending on whether the process was executed correctly,
- A procedure can return the result of a calculation, etc.
To try this functionality, we will create a new procedure to calculate the amount of a purchase including tax. - In the code editor, press Shift + F4.
- The procedure creation window appears.
- Enter the procedure name: CalculTTC
- Validate.
- Enter the code of the procedure:
PROCEDURE CalculTTC(LOCAL MontantHT is TO monetary Value, LOCAL TauxTVA is TO real Value): monetary Value
InclTax is currency
InclTax = AmountExclTax * (1 + VATRate/100)
RETURN InclTax
Let's take a closer look at the code of this procedure: - In the procedure declaration code (also called "prototype of the procedure"), we see that this procedure expects 2 parameters (the amount excluding tax and VAT).
- There are 2 particular features in this code:
- The ": monetary" at the end indicates that the value returned is of monetary type.
- The procedure calculates the amount including tax and returns it via the RETURN keyword.
- Modify the project initialization code to call the procedure:
AmountInclTax is currency
AmountInclTax = CalculateInclTax(500, 20)
Trace("Amount incl. tax: " + AmountInclTax)
- Let's test this code right away: click on among the quick access buttons.
- After the test, the "Debugger trace" pane will display:
Mandatory or optional parameters? The parameters received in the procedure can be mandatory or optional parameters. A mandatory parameter must be filled during the call to the procedure while an optional parameter can be omitted: in this case, it will take the default value defined when declaring the procedure parameters. Remember
When declaring a procedure, the optional parameters are specified at the end (they are always specified after all mandatory parameters). To test this functionality, let's go back to the procedure for calculating the amount of a purchase including tax. We will make the second parameter optional. The VAT can correspond to 20 by default (other possible rates are 10, 5.5 or 2.1). - Move the cursor to the name of the "CalculateInclTax" procedure.
- Press F2. The WLanguage code of the "CalculateInclTax" procedure is displayed.
- Modify the procedure declaration code as follows:
PROCEDURE CalculTTC(LOCAL MontantHT is TO monetary Value, LOCAL TauxTVA is TO real Value=20): monetary Value
- Press Ctrl + F2 to return to the calling code (the project initialization code).
- Modify the call to the procedure by deleting the second parameter:
AmountInclTax is currency
AmountInclTax = CalculateInclTax(500)
Trace("Amount incl. tax: " + AmountInclTax)
- Let's test this code right away: click on among the quick access buttons.
- After the test, the "Debugger trace" pane will display:
The result did not change because we used the default value.
In this lesson, you have discovered: - How to create and call a WLanguage procedure,
- How to pass parameters to a WLanguage procedure,
- How to return a value, etc.
In the next lesson, we will see how to use the debugger to track the code being executed.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|