CASE

In this section:

How to:

Reference:

The CASE command allows you to define a Maintain function. (Maintain functions are sometimes also called cases.) The CASE keyword defines the beginning of the function, and the ENDCASE keyword defines its end.

You can pass values to a Maintain function using its parameters, and you can pass values from a Maintain function using its parameters and its return value.

You can call a Maintain function in one of the following ways:

Once control has branched to the function, it proceeds to execute the commands within it. If control reached the end of the function (that is, the ENDCASE command), it returns or exits depending on how the function was called:

A CASE command that is encountered in the sequential flow of a procedure is not executed.

You assign a unique name to each function using the CASE command.


Top of page

x
Syntax: How to Use the CASE Command

The syntax for the CASE command is:

CASE functionname [TAKES p1/t1[,..., pn/tn]] [RETURNS result/t] [;] 
   [declarations]
   commands 
   .
   .
   .
ENDCASE

where:

functionname

Is the name you give to the function, and it can be up to 66 characters long. The name must begin with a letter, and can include any combination of letters, digits, and underscores ( _ ).

TAKES p1/t1

Specifies that the function takes parameters. p1/t1...pn/tn defines the parameters of the function (p) and the data type of each parameter (t). When you call the function, you pass it variables or constants to substitute for these parameters. Parameters must be scalar; they cannot be stacks.

If the function is the Top function or is being used as an event handler, it cannot take parameters.

RETURNS result/t

Specifies that the function returns a value. result is the name of the variable being returned, and t is the data type of the variable. The return value must be scalar. It cannot be a stack.

If the function is the Top function or is being used as an event handler, it cannot return a value.

declarations

Is an optional DECLARE command to declare any variables that are local to the function. These declarations must precede all other commands in the function.

commands

Is one or more commands, except for CASE, DESCRIBE, END, MAINTAIN, and MODULE.

;

Terminates the parameter and return variable definitions of the CASE command. Although the semicolon is optional, it is recommended that you include it to allow for flexible syntax and better processing. For more information about the benefits of including the semicolon, see Terminating Command Syntax.


Top of page

x
Reference: Usage Notes for CASE

Top of page

x
Reference: Commands Related to CASE

Top of page

x
Calling a Function: Flow of Control

When a function is called, and control in the function is complete, control returns to the next command after the call.

When the Increase function in the following example is complete, processing resumes with the line after the PERFORM command, the TYPE command:

PERFORM Increase;
TYPE "Returned from Increase";
.
.
.
CASE Increase
COMPUTE Salary = Salary * 1.05;
.
.
.
ENDCASE

Top of page

x
Passing Parameters to a Function

In general, the parameters of a Maintain function are both input and output parameters:

If the called function changes the values of any of its parameters, when it returns control to the calling function, the parameter variables in the calling function are set to those new values. The parameters are global to the calling and called functions.

This method of passing parameters is known as a call by reference, because the calling function passes a reference to the parameter variable (specifically, its address), not a copy of its value.

Note: There is one exception to this behavior. If you declare a function parameter (in the Function Editor or a CASE command) with one data type, but at run time you pass the function a value of a different data type, the value of the parameter is converted to the new data type. Data types, in this context, refer to basic data types such as fixed-length character (An where n is greater than zero), variable-length character (A0), text, date, date-time, integer, single-precision floating point, double-precision floating point, 8-byte packed decimal, and 16-byte packed decimal. Other data attributes, such as length, precision, MISSING, and display options, can differ without causing a conversion. Any changes that the called function makes to the value of the parameter will not get passed back to the calling function. The parameter is local to the called function.

This method of passing parameters is known as a call by value, because the calling function passes a copy of the value of the parameter variable, not a pointer to the actual parameter variable itself.

Note that you should not pass a constant as a function parameter if the function may change the value of that parameter.


Top of page

x
Using the Return Value of a Function

If a function returns a value using the RETURNS phrase, you can call that function anywhere you can use an expression. For example:

MAINTAIN FILE HousePlan
  .
  .
  .
COMPUTE ConferenceRoom/D6.2 = FindArea(CRlength,CRwidth);
  .
  .
  .
CASE FindArea TAKES Length/D6.2, Width/D6.2 RETURNS Area/D6.2;
Area = Length * Width;
ENDCASE
  .
  .
  .
END

Top of page

x
Using the Top Function

When you run a Maintain procedure, the procedure begins by executing its Top function. Every Maintain procedure has a Top function. Top does not take or return parameters. You can choose to define the Top function, beginning it with a CASE command and ending it with an ENDCASE command, as all other Maintain functions are defined. This is the recommended method for defining Top, and is how the Maintain Development Environment generates Top when creating a new procedure.

For example:

CASE Top
.
.
.
ENDCASE

WebFOCUS