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 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 ellipsis button 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 obtain Help on any Maintain language keyword by selecting the keyword and pressing F1 key.

  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 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 obtain Help on any Maintain language keyword by selecting the keyword or placing your insertion point in the keyword and pressing F1 key.


Top of page

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

Top of page

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

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, as shown in the following image.

Edit Function dialog box

This dialog box includes the following options:

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. You cannot use a function with arguments as an event handler.

New 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.

Move Up button

Moves a selected argument up in the list of arguments.

Moves a sMove Down buttonelected 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.

ellipsis button

Opens the Function Return dialog box, where you can define the return value.


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, as shown in the following image.

You can 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, as shown in the following image.

    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, as shown in the following image.

    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

  13. Close the Events dialog box.

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


WebFOCUS