Declare Function function

Syntax

PeopleCode Function Syntax

Declare Function function_name PeopleCode record_name.field_name event_type

External Library Function Syntax

Declare Function function_name Library lib_name
    [Alias module_name]
    [paramlist]
    [Returns ext_return_type [As pc_type]]

In which paramlist is: 

([ext_param1 [, ext_param2] . . .)

And in which ext_param1, ext_param2, and so on is: 

ext_datatype [{Ref|Value}] [As pc_return_type]

Description

PeopleCode can call PeopleCode functions defined in any field on any record definition. You can create special record definitions whose sole purpose is to serve as function libraries. By convention, PeopleCode functions are stored in FieldFormula PeopleCode, in record definitions with names beginning in FUNCLIB_.

PeopleCode can also call external programs that reside in dynamic link libraries. You must declare either of these types of functions at the top of the calling program using the Declare Function statement.

To support processes running on an application server, you can declare and call functions compiled in dynamic link libraries on windows (*.DLL files) and shared libraries on UNIX (lib*.so files.) The PeopleCode declaration and function call syntax is the same regardless of platform, but UNIX libraries must be compiled with an interface function.

See PeopleCode Developer’s Guide: Calling DLL Functions on the Application Server.

Parameters

The following are the parameters for the PeopleCode function syntax:

Parameter Description

function_name

Name of the function.

PeopleCode

Reserved word that identifies the function as a PeopleCode function.

recordname.fieldname

Specifies the record and field where the function is located.

event_type

Component Processor event with which the function is associated.

Note:

event_type can be used to specify record field events only. You can’t specify a component record field event, a component record event, and so on.

The following are the parameters for the external library function syntax:

Parameter Description

function_name

Name of the function.

Library

Reserved word that identifies the function as an external library function.

lib_name

A string representing the name of the external library. The external routine must be located in a DLL named lib_name accessible by Windows, or an equivalent shared library in a UNIX system.

Alias   module_name

Optionally specifies the name of the function’s entry point within the shared library. This is needed only if the C function name differs from function_name in the PeopleCode external function declaration. The external module is invoked using the __stdcall calling convention on Windows.

paramlist

List of parameters expected by the function, each in the form:

ext_datatype [{Ref | Value}] [As  pc_type]

ext_datatype

The data type of the parameter expected by the function. To specify the type you can use any of the following:

  • BOOLEAN

  • INTEGER

  • LONG

  • UINTEGER

  • ULONG

  • STRING

  • STRING

  • FLOAT

  • DOUBLE

Ref | Value

Optionally use one of these two reserved words to specify whether the parameter is passed by reference or by value. If Ref is specified, it is passed by pushing a reference (pointer) on the stack. If Value is specified the value is pushed on the stack (for integers, and so on.) If neither is specified, Ref is assumed.

As  pc_type

Specifies PeopleCode data type of the value passed to the function. You can choose between PeopleCode data types String, Number, Integer, Float, Date, Boolean, and Any.

Returns  ext_return_type

Specifies the data type of any value returned by the function. The Returns clause is omitted if the function is void (returns no value.) To specify the return type you can use any of the following:

  • BOOLEAN

  • INTEGER

  • LONG

  • UINTEGER

  • ULONG

  • FLOAT

  • DOUBLE

The types String and LString are not allowed for the result type of a function.

As  pc_return_type

Specifies the PeopleCode data type of the variable or field into which to read the returned value. You can choose between PeopleCode data types String, Number, Integer, Float, Date, Boolean, and Any. If the As clause is omitted, PeopleTools selects an appropriate type based on the type of value returned by the external function (for example, all integer and floating point types are converted to Number).

Example

Assume you have defined a PeopleCode function called VerifyZip. The function definition is located in the record definition FUNCLIB_MYUTILS, in the record field ZIP_EDITS, attached to the FieldFormula event. You would declare the function using the following statement:

Declare Function verifyzip PeopleCode FUNCLIB_MYUTILS.ZIP_EDITS FieldFormula;

Now assume you want to declare a function called PCTest in PSUSER.DLL. It takes an integer and returns an integer. You would write this declare statement: 

Declare Function pctest Library "psuser.dll"
      (integer Value As number) Returns integer As number;

PeopleCode Functions

You can call a PeopleCode function defined on any record definition, provided you declare it at the top of the calling program. The declaration identifies the function name, as well as the record, field, and event type where the function definition resides. The function parameters and return type are not declared; they are determined from the function definition.

Note:

You can define functions only in record field PeopleCode. You can’t define functions in component PeopleCode, component record Field PeopleCode, and so on.

External Library Functions

Function declarations define routines in an external (C-callable) library. The function declaration provides the name of the library, an optional alias module_name, a list of parameters to pass to the function, an optional Returns clause specifying the type of any value returned by the external function, and the PeopleCode data type into which to convert the returned value. The library must be a DLL accessible by Windows or a shared library accessible by UNIX.

After you have declared an external library function, you can call it the same way as an external PeopleCode function. Like PeopleCode functions, you must pass the number of parameters the library function expects. Calls to external functions suspend processing: this means that you should exercise caution to avoid “think-time” errors when calling the function in the following PeopleCode events:

  • SavePreChange.

  • SavePostChange.

  • Workflow.

  • RowSelect.

  • Any PeopleCode event that fires as a result of a ScrollSelect (or one of its relatives) function calls, or a Select (or one of its relatives) Rowset class method.

See PeopleCode Developer’s Guide: Think-Time Functions.

Related Topics