PC SOFT

ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

Home | Sign in | English EN
This page concerns the 270056D version of WINDEV Mobile 27. Update your version.
  • In this lesson you will learn the following concepts
  • Overview
  • My first procedure
  • Procedure parameters
  • What is a parameter?
  • How to use the parameters?
  • Return a value
  • Mandatory or optional parameters?
  • Conclusion
Lesson 3.7. Procedures
In this lesson you will learn the following concepts
  • Creating and calling a procedure.
  • Procedure parameters.
  • Procedure result.
Lesson duration

Estimated time: 30 mn
Previous LessonTable of contentsNext Lesson
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, their creation mode, how to call them, pass parameters and retrieve a result.
  • 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.
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.
  • 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 closer 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 may be useful to restrict the access to a global procedure by making it "Private". In this case, the global procedure cab 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, 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.
  • 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.
  • 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.

      Note

      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.

  • We will create a new procedure to remove spaces from a character string.
    1. On the "Code" tab, in the "Procedures" group, expand "New" and select "New global procedure".
    2. If necessary, select the "COL_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. This parameter is specified as a variable. You can pass 0 or multiple values as parameters to a procedure. 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, 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" and select "Debugger trace".
    9. The following result will appear in the trace window:
      The string without spaces is: WelcometomyprogramwritteninWLanguage

How to use the parameters?

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 as well.
  • 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.

Note

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. Select the set of procedures to which the procedure is to be added (COL_GlobalProcedures) and validate.
    3. 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 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.
    4. Modify the project initialization code to call the procedure:
      AmountInclTax is currency
      AmountInclTax = CalculateInclTax(500, 20)
      Trace("Amount including tax: " + AmountInclTax)
    5. Let's test this code: click Test project in the quick access buttons.
    6. 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 including 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.
Conclusion
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'll see how to use the debugger to track the code being executed.
Previous LessonTable of contentsNext Lesson
Minimum version required
  • Version 27
Comments
Click [Add] to post a comment