|
|
|
|
|
|
A function is a discrete unit of MDL code, which returns a single value for a given set of parameters. It is effectively an extension to the MDL language, reducing the need to duplicate sections of code in mapping or entity definitions.
The definition of a function can include other functions (either built-in or user-defined) as necessary. For example, the definition of a function to extract the century digits from a date would almost certainly make use of the built-in function YEAR(), which extracts all of the year digits from a date value.
A function has only two possible outputs: it can return a single value to the calling statement, or write a message to an error report. A function cannot include calls to report commands (such as PRINT). Otherwise, a function may contain any normal MDL statements. There are no restrictions on the size of a function definition except those imposed by availability of system resources (but see also the sections on Limits in this manual and in the MDL Reference Manual).
Functions can be used in two ways: to perform standard, repetitive calculations, or to provide a simplified interface to callable routines. An example of the first kind of use would be the depreciation calculation mentioned in the Overview. To illustrate the second kind of use, consider the e5 General Ledger. It provides many multi-purpose facilities as "callable routines"; these might be regarded as "super-functions", because they can require twenty or more parameters to be passed to them when they are used. Depending on the reason for calling one of these routines, many of those parameters might be left blank (so that default values are used) or they might require specific entries relevant to the task in hand. To make these routines easier to use, you can define functions which accept only a small number of parameters, and which then call the GL routines themselves, with the full complement of parameters including blanks and literal values. The colour coding below shows the relationship between a user-defined function accepting three parameter values, and a GL routine which actually requires ten parameter values. The user-defined function has the extra parameters "hard-coded" into it.
User_GLfunc(parm_1,parm_2,parm_3)
GL_routine(parm_1,123,'ABC', ,parm_2, ,456,789,'DEF',parm_3)
(You should note that parameters are actually passed to callable routines via named commareas, not in calling statements. See MDL Commands for more information on the COMMAREA statement.)
As usual in QED, a function defined within one company will not be available to other companies unless it is copied to them (using the screen Function - Copy, MQFC). When entities and mappings are being copied between companies, they should be checked for references to user-defined functions, and any required functions should also be copied across otherwise they will fail.
A function consists of three parts. The first part, an ACCEPTS statement to get any parameter values, is optional; the third part must be a RETURN statement (which returns the value of a variable - usually a calculation result - to the calling routine). The second part, the body of the function, contains all the MDL code necessary to achieve the production of the result being returned.
A function may contain multiple RETURN statements, but the first one encountered during processing will cause the function to terminate immediately and return the current value of the nominated variable to the calling routine.
Variables declared within a function are local - that is, they exist only whilst the function is executing. The only value which is preserved after a function terminates is the nominated return variable, which is passed back to the calling routine.
The following function definition illustrates the general principles of function construction. The function performs a simple depreciation calculation, based on three parameters: current value, residual value, and number of periods.
ACCEPT (Current_Value(Decimal(15,2)),
Residual_Value(Decimal(15,2)),
Life_in_Periods(integer)
)
LET Rate = 100*(1-(Residual_Value/Current_Value)
**
(1/Life_In_Periods )
)
RETURN (Rate)
The ACCEPT statement determines the number, order and data type (class) of the parameters required; the LET statement actually performs the calculation; the RETURN statement passes back the result and stops the function.
The following segment of code illustrates a function with multiple RETURN statements (one of two possible values is returned depending on the magnitude of the result of a calculation):
IF result LE 0
THEN
RETURN (val_a)
ELSE
RETURN (val_b)
END_IF
The normal Syntax Check and Syntax Compile actions are available when defining functions (screen Function - Edit, MQFB). Use these before attempting to compile a function.
If a function definition includes a call to another function, the parameters passed must be the correct number and class; the compilation will fail if there is a mismatch. Similarly, when the new function is called from a mapping, the mapping will not compile if the syntax of the call is incorrect or there is a parameter mismatch.
Note that these checks cannot catch mistakes in the order of parameters of the same class. Using the example of the depreciation function above, reversal of the order of the Current_Value and Residual_Value parameters in the calling statement would not be detected, although reversal of the order of the Residual_Value and Life_in_Periods parameters would be. A call using the first two parameters in the wrong order would succeed because the classes of the passed parameters match, although the result of the calculation would actually be incorrect. Switching the order of the last two parameters would cause a type mismatch error; this would prevent a compilation from starting, because it would be detected by the syntax checking.
User-defined error handling during execution is limited to returning special "flag" values to the routine which called the function, or putting a message in an error log. If a function fails during execution, it can write a message in the QED run time error report (RQZZ02). The following piece of code is from a function which calls another function; the called function performs some processing, but only returns a message if the processing is not completed (if processing is completed, it returns a message which consists of spaces). The calling function checks to see if the called function returns any message; if it does, then that message is added to the error report.
IF msg NE spaces
THEN
DISPLAY_ERROR msg
END_IF
See also
QED System Administration Home Page
|
© Advanced, Jan 2021 |
|
