ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

New WINDEV 2024 feature!
Help / WINDEV Tutorial / Tutorial - WLanguage basics
  • 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 basics

Lesson 6 - Procedures
We will cover the following topics:
  • Creating and calling a procedure.
  • Procedure parameters.
  • Result of a procedure.
Durée de la leçon 20 mn
Overview
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.
If necessary, open the "WLanguage" project you created in the first lesson of this tutorial (see A project to discover WLanguage in lesson 1).
To view WLanguage events of the project:
  1. Right-click the "P" button next to the open element tabs. The context menu appears.
  2. Select "Element code".
  3. The code editor displays the different events associated with the project.
  4. 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").
My first procedure
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 will create a global procedure in the set of procedures of the "WLanguage" project.
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.
  1. On the "Code" tab, in the "Procedures" group, expand "New" and select "New global procedure".
    New global procedure
  2. In the window that appears, a default name is displayed for the set of global procedures.
    New global procedure
    Keep this name and validate (click "OK").
  3. A new window is displayed, allowing you to enter the name of the procedure and its characteristics:
    New global procedure
    Let's take a look at this window. 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. A global procedure is public by default: it is accessible from anywhere in the 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".
  4. For our example, we will only change the name of the procedure and keep the default options. Name the procedure "Welcome" and validate.
  5. The "Welcome" global procedure appears in the code editor.
    New global procedure
    This procedure consists of:
    • automatically generated comments.
    • the following code:
      PROCEDURE Welcome()

      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.
  6. 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")
  7. 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:
  1. Right-click the "P" button next to the open element tabs. The context menu appears.
  2. Select "Element code".
  3. The code editor displays the different events associated with the project.
  4. Clear the initialization process and write the following code:
    Welcome()
  5. Let's test this code: click Test project in the quick access buttons.
  6. An information window appears.
    New global procedure
    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 the events and processes of the project (procedure declared in a set of procedures). For more details, see Global procedure.
  • Local procedure in a Window, Page or Mobile Window: this type of procedure can be called in all events and processes, depending on the object in which it was 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 in a process or event: this type of procedure can only be called in the process or event in which it was declared. For more details, see Internal procedure.
Procedure parameters

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:
  1. On the "Code" tab, in the "Procedures" group, expand "New" and select "New global procedure".
  2. If necessary, select the "GlobalProcedures" set of procedures and validate.
  3. In the window that appears, name the procedure to be created. For this example, name the procedure "RemoveSpaces".
  4. Validate. The "RemoveSpaces" global procedure appears in the code editor.
  5. Type the following code:
    PROCEDURE RemoveSpaces(StringToProcess is string)
    StringToProcess = StringToProcess.Replace(" ", "")
    Trace("The string without spaces is: [%StringToProcess%]")

    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, we specified "StringToProcess is string": it will not be possible to use this procedure with numeric values as parameters, for example.
  6. 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)
  7. Let's test this code: click Test project in the quick access buttons.
  8. If necessary, open the "Debugger trace" pane to see the result: on the "Home" tab, in the "Environment" group, expand "Panes", select "Panes", and then select "Debugger trace".
  9. The following result will appear in the trace window:
    The string without spaces is: WelcometomyprogramwritteninWLanguage

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
    MyString: WelcometomyprogramwritteninWLanguage
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:
  1. Move the cursor to the name of the "RemoveSpaces" procedure.
  2. Press F2. The WLanguage code of the "RemoveSpaces" procedure is displayed.
  3. Modify the procedure declaration code as follows:
    PROCEDURE RemoveSpaces(LOCAL StringToProcess is string)
  4. Let's test this code: click Test project in the quick access buttons.
  5. After the test, the "Debugger trace" pane will display:
    The string without spaces is WelcometomyprogramwritteninWLanguage
    MyString: 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. For example:
  • 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.
  1. In the code editor, press Shift + F4.
  2. The procedure creation window appears.
    • Enter the name of the procedure: CalculateInclTax
    • Validate.
    • Type the code of the procedure:
      PROCEDURE CalculateInclTax(LOCAL AmountExclTax is currency, LOCAL VATRate is real): currency
      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 ": currency" at the end indicates that the value returned is currency.
        • The procedure calculates the amount including tax and returns it via the RETURN keyword.
  3. Modify the project initialization code to call the procedure:
    AmountInclTax is currency
    AmountInclTax = CalculateInclTax(500, 20)
    Trace("Amount incl. tax: " + AmountInclTax)
  4. Let's test this code: click Test project in the quick access buttons.
  5. After the test, the "Debugger trace" pane will display:
    Amount incl. tax: 600

Mandatory or optional parameters?

The parameters received in the procedure can be mandatory or optional parameters. A mandatory parameter must be specified when calling 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).
  1. Move the cursor to the name of the "CalculateInclTax" procedure.
  2. Press F2. The WLanguage code of the "CalculateInclTax" procedure is displayed.
  3. Modify the procedure declaration code as follows:
    PROCEDURE CalculateInclTax(LOCAL AmountExclTax is currency, LOCAL VATRate is real=20): currency
  4. Press Ctrl + F2 to return to the calling code (the project initialization code).
  5. Modify the call to the procedure by deleting the second parameter:
    AmountInclTax is currency
    AmountInclTax = CalculateInclTax(500)
    Trace("Amount incl. tax: " + AmountInclTax)
  6. Let's test this code: click Test project in the quick access buttons.
  7. After the test, the "Debugger trace" pane will display:
    Amount incl. tax: 600
    The result did not change because we used the default value.
To sum up
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.
Previous LessonTable of contentsNext Lesson
Minimum version required
  • Version 2024
Comments
Click [Add] to post a comment

Last update: 12/11/2023

Send a report | Local help