Using Functions in Procedures

How to:

Reference:

A function, also known as a case, is a series of commands in a procedure grouped together as a unit of control. A function accomplishes some small task, such as calculating values, extracting data from a data source to place in a data source stack, or writing information to a data source.

All executable code must be in a function. The only types of logic allowed outside of a function are variable declarations, object declarations, and class definitions (CASE, DECLARE, DESCRIBE, END, MAINTAIN, and MODULE statements).

Some functions have arguments, meaning when you invoke the function, you must supply information that the function needs to complete its task.

Some functions also have a return value, meaning they calculate a value and return this value to whatever called the function. Functions that are event handlers (that is, that are invoked by some action in a form) cannot have return values.

Notice that local variables (defined in a function using the DECLARE command) are available only within that function. As soon as the function completes processing, these values are no longer available. Global variables (defined using the DECLARE command outside of a function or using the COMPUTE command anywhere) are available for the entire procedure. For more information on local and global variables, see the WebFOCUS Maintain Language Reference manual.

You can also call one function from within another function.

The combination of the arguments and return value of a function is known as its signature.


Top of page

x
Procedure: How to Create a Function
  1. Select the procedure that you want the function to be part of.
  2. Right-click the procedure, click New in the shortcut menu, and click Function (Case) in the submenu.

    or

    Click the New function button New Function button on the Maintain Objects toolbar.

  3. In the New Function dialog box, type a name for your function in the Name field (up to 66 characters with no spaces).
  4. If your function requires any arguments, use the New button New button to open the Function Parameter dialog box to add them (not all functions require arguments).
  5. If your function requires a return value, enter its name and format in the Returns field, or click the ellipsis button Return to open the Function Return dialog box. This is where you can define the function.
  6. If you wish, click the Description tab and type a description.
  7. Click OK.
  8. Right-click the function and select Edit Source from the shortcut menu.

    WebFOCUS Maintain opens the procedure containing your function in the Procedure Editor at the code for the function.

  9. Locate your cursor just before the ENDCASE keyword and enter the Maintain language commands that determine what this function does.

    Note: The following Maintain language commands are not valid within the context of a function: CASE, ENDCASE, MAINTAIN, END, MODULE, and DESCRIBE.

    Tip: You can add Maintain language code to your function using the Language Wizard. Place your insertion point where you want your code to go, right-click in the Procedure Editor window, and in the shortcut menu, click Language Wizard.

    You can easily obtain help on any Maintain language keyword by selecting the keyword and pressing F1.

  10. Close the Procedure Editor.

Top of page

x
Procedure: How to Edit the Name, Arguments, Return Value, and Description of a Function
  1. Right-click the function in the Project Explorer.
  2. In the shortcut menu, click Edit.
  3. Make your desired changes in the Edit Function dialog box.
  4. Click OK.

Top of page

x
Procedure: How to Edit a Function
  1. Right-click the function in the Project Explorer.
  2. In the shortcut menu, click Edit Source.
  3. Make your desired changes to the code between the CASE functionname and ENDCASE keywords.

    For more information, see the WebFOCUS Maintain Language Reference manual.

  4. Close the Procedure Editor.

Tip: You can add Maintain language code to your function using the Language Wizard. Place your insertion point where you want your code to go, right-click in the Procedure Editor window, and in the shortcut menu, click Language Wizard.

You can easily obtain help on any Maintain language keyword by selecting the keyword or placing your insertion point in the keyword and pressing F1.


Top of page

x
Procedure: How to Move a Function to Another Procedure
  1. In the Project Explorer, ensure you can see both the function and the procedure you want to move it to.
  2. Select the function and drag it to the procedure you want to move it to.

Top of page

x
Procedure: How to Copy a Function to Another Procedure
  1. In the Project Explorer, ensure you can see both the function and the procedure you want to move it to.
  2. Select the function, hold down the Ctrl key, and drag the function to the procedure you want to move it to.

Top of page

x
Reference: Function Editor: Signature Tab

When you create or edit a function, WebFOCUS Maintain opens the New Function, Edit Function, or Member Function dialog box.

Edit Function dialog box

This dialog box contains the following elements:

Name

The name you assign to your case. This name can be up to 66 characters long. It must begin with a letter and can include any combination of letters, digits, and underscores (_).

Takes: (Name/Type)

Lists the arguments that the function requires. When you invoke the function, you pass to it variable names or values to substitute for these arguments.

To edit an existing argument, double-click its name. You can also edit an existing argument directly by clicking it twice or pressing F2.

To create a new argument, double-click the gray rectangle.

Note: Not all functions require arguments. In fact, you cannot use a function with arguments as an event handler.

Opens the Funtion Parameter  button

Opens the Function Parameter dialog box where you can define a new argument.

Delete button

Deletes a selected argument from the list of arguments.

Moves selected argument up button

Moves a selected argument up in the list of arguments.

Moves selected argument down button

Moves a selected argument down in the list of arguments.

Returns: (Name/Type)

Contains the name and data type of the return value that the function calculates. You can type this in if you wish.

Opens the Function Return dialog box, where you can define the return value if you do not want to type it in.


Top of page

x
Reference: Function Editor: Description Tab

When you click the Description tab in the New Function or Edit Function dialog box, WebFOCUS Maintain opens a dialog box where you can enter a description for your function.

You can easily view the description of a function in the Project Explorer with the Show description command. For more information, see How to View the Description of a Procedure Component.

Edit Function description dialog box



Example: Creating a Function

Suppose you create a project that enables end users to update a list of fan club members. Part of this project is a form where end users can enter information for a new fan club member and then insert this information into the data source. This example demonstrates how you create a function that updates the data source and how you trigger it from the form.

  1. In the Project Explorer, right-click the procedure you want the function to be part of.
  2. In the shortcut menu, click New, then click Function (Case).
  3. In the New Function dialog box, give your function the name AddFan.

    New Function dialog box

  4. Click OK.

    Your new function appears in the list of components of the procedure.

  5. Double-click AddFan.

    WebFOCUS Maintain opens the source code for your function in the Procedure Editor.

  6. Between Case AddFan and EndCase, enter the following Maintain language code:
    For all include Fannames.CUSTOMER.SSN from AddFanStack ;
    Stack clear AddFanStack ;

    Tip: You can use the Language Wizard to enter this code instead of typing it. Place your insertion point between Case AddFan and EndCase, right-click in the Procedure Editor window, and in the shortcut menu, click Language Wizard.

  7. Open the form from which you will execute this function.
  8. Create a button named AddButton with the text Add.

    Add button

  9. Double-click the Add button to open the Events dialog box.
  10. Select Click from the list of events.
  11. Ensure you can see both the Events dialog box and the Project Explorer.
  12. Click and drag the AddFan function from the Project Explorer into the Events dialog box.

    The Events dialog box looks similar to the following example:

    Events dialog box image

  13. Close the Events dialog box.

When you execute the project, clicking Add executes the function AddFan.


WebFOCUS