Functions

PeopleCode supports the following types of functions:

• Built-in: The standard set of PeopleCode functions. These can be called without being declared.

• Internal: Functions that are defined (using the Function statement) within the PeopleCode program in which they are called.

• External PeopleCode: PeopleCode functions defined outside the calling program. These are generally contained in record definitions that serve as function libraries.

• External non-PeopleCode: Functions stored in external (C-callable) libraries.

See Understanding the Analytic Model Definition Creation Process.

In addition, PeopleCode supports methods. The main differences between a built-in function and a method are:

• A built-in function, in your code, is on a line by itself, and it does not (generally) have any dependencies.

  You do not have to instantiate an object before you can use the function.

• A method can only be executed by an object (using dot notation).

  You must instantiate the object first.

PeopleCode functions can be defined in any PeopleCode program. Function definitions must be placed at the top of the program, along with any variable and external function declarations. The syntax for a PeopleCode function definition is as follows:

Function name[(paramlist)] [Returns data_type]
    [statements] 
End-function

By convention, PeopleCode programs are stored in records whose names begin in FUNCLIB_, and they are always attached to the FieldFormula event.

If you call an external function from a PeopleCode program, you must declare the function at the top of the program. The syntax of the function declaration varies, depending on whether the external function is written in PeopleCode or compiled in a dynamic link library.

The following is an example of a function declaration of a function that is in another FUNCLIB record definition:

Declare Function UpdatePSLOCK PeopleCode FUNCLIB_NODES.MSGNODENAME FieldFormula;

Functions are called with this syntax:

function_name([param_list]);

The optional parameter list (param_list) is a list of expressions, separated by commas, that the function expects you to supply. If a parameter is listed in the function definition, then it is required when the function is called.

You can check the values of parameters that get passed to functions at runtime in the Parameter window of the PeopleCode debugger.

If the return value is required, then the function must be called as an expression, for example:

&RESULT = Product(&RAISE_PERCENT, .01, EMPL_SALARY);

If the function has an optional return value, it can be called as a subroutine. If the function has no return value, it must be called as a subroutine:

WinMessage(64, "I can't do that, " | &OPER_NICKNAME | ".");

Parameters are always passed to internal and external PeopleCode functions by reference. If the function is supposed to change the data the caller passes, you must also pass in a variable.

Built-in function parameters can be passed by reference or by value, depending on the function. External C function parameters can be passed by value or by reference, depending on the declaration and type.

Functions can return values of any supported data type; some functions do not return any value.

Optional return values occur only in built-in functions. You cannot define a function that optionally returns a value. Optional return values are typical in functions that return a Boolean value indicating whether execution was successful. For example, the following call to DeleteRow ignores the Boolean return value and deletes a row:

DeleteRow(RECORD.BUS_EXPENSE_PER, &L1_ROW, RECORD.BUS_EXPENSE_DTL, &L2_ROW);

The following example checks the return value and returns a message saying whether it succeeded:

if DeleteRow(RECORD.BUS_EXPENSE_PER, &L1_ROW, RECORD.BUS_EXPENSE_DTL, &L2_ROW) then
   WinMessage("Row deleted.");
else
   WinMessage("Sorry -- couldn't delete that row.");
end-if;

If you define a function with the same name as a built-in function, the function that you defined takes precedence over the built-in function.

Anytime you compile the PeopleCode in the PeopleCode Editor, a warning message appears in the Validate tab, indicating that a user-defined function has the same name as an existing built-in function.

In addition, if you select Compile All PeopleCode, an error message is generated in the log file for every user-defined function that has the same name as a built-in function.

The following is an example error message: User-defined function IsNumber is overriding the built-in function of the same name. (2,98)

If you notice that you named a function the same as a built-in function, and that the built-in function does what you're trying to achieve, replace your function with a reference to the built-in function. The built-in function is probably more efficient. In addition, using the built-in function reduces confusion for people who maintain your code, because if they miss the warning message in the Validate tab, they might assume the built-in function is being called when it is not.