19.3.8 Example - Define a BIF as an RDML Function
These are the steps involved in creating an RDML Built-In Function as a function. The example shown is very simple, but should give an insight into how an RDML Built-In Function is plugged into a LANSA system.
SCENARIO: This is a User Defined RDML Built-In Function. The Built-In Function is passed two arguments: a working list of packed 11,2 numbers and optionally whether to return those that are above or below the average of the numbers, defaulting to be above. The Built-In Function will return a working list of the packed 11,2 numbers as per the criteria and optionally the average value as a packed 30,9 number. The RDML BIF will be used extensively in a new application, so will be coded not to terminate between USEs.
The BIF name will be UD_GET_HI_LO_AVGE.
The BIF description will be 'Return numbers over or under the average'.
The RDML Built-In Function is generated from template BBRDMLBIF.
The argument and return value working lists are then customized from the prototype generated by the template.
The actual evaluation logic is then added.
********** Beginning of RDML commands **********
********** =======================================================
********** Copyright .....: (C) The LANSA Group , 19
98
********** Process .......: CR4587SMPL
********** Function ......: CR4587S
********** Type ..........: Built_In Function
********** Created by ....: KEVIN
********** Created on ....: 02/09/98 at 19:46:50
********** Description ...: Sample RDML BIF Function
********** =======================================================
FUNCTION OPTIONS(*DIRECT *NOMESSAGES *HEAVYUSAGE *MLOPTIMISE *BU
ILTIN)
********** =======================================================
********** Special field to name the Built-In Function
********** =======================================================
DEFINE FIELD(#BIF_NAME) TYPE(*CHAR) LENGTH(20) DESC('Return nu
mbers over or under the average') DEFAULT('UD_GET_HI_LO
_AVG')
********** =======================================================
********** Built-In Function Arguments
********** =======================================================
********** Argument 01, Supplied numbers list
DEFINE FIELD(#BIF_ALC01) TYPE(*DEC) LENGTH(7) DECIMALS(0) DESC
('Supplied numbers list')
DEFINE FIELD(#NUMBER) TYPE(*DEC) LENGTH(11) DECIMALS(2) DESC('
Number')
DEF_LIST NAME(#BIF_ARG01) FIELDS((#NUMBER)) COUNTER(#BIF_ALC01)
TYPE(*WORKING) ENTRYS(9999)
********** Argument 02, Over or under numbers required (O or U)
DEFINE FIELD(#BIF_ARG02) TYPE(*CHAR) LENGTH(1) DESC('Over or u
nder numbers required (O or U)') DEFAULT('O')
********** =======================================================
********** Working fields, lists and groups
********** =======================================================
DEFINE FIELD(#TOTAL) TYPE(*DEC) LENGTH(30) DECIMALS(2) DESC('T
otal')
********** =======================================================
********** Built-In Function Return Values
********** =======================================================
********** Return Value 01, Over or under average numbers list
DEFINE FIELD(#BIF_RLC01) TYPE(*DEC) LENGTH(7) DECIMALS(0) DESC
('Over or under average numbers list')
DEF_LIST NAME(#BIF_RET01) FIELDS((#NUMBER)) COUNTER(#BIF_RLC01)
TYPE(*WORKING) ENTRYS(9998)
********** Return Value 02, Average of supplied numbers
DEFINE FIELD(#BIF_RET02) TYPE(*DEC) LENGTH(30) DECIMALS(9) DES
C('Average of supplied numbers') DEFAULT(*ZERO)
********** =======================================================
********** Function Mainline : CR4587S
********** =======================================================
********** This is an evaluation call
**********
**********
IF COND('*BIF_SHUTDOWN *NE Y')
********** calculate the average
CHANGE FIELD(#TOTAL) TO(0)
SELECTLIST NAMED(#BIF_ARG01)
CHANGE FIELD(#TOTAL) TO('#TOTAL + #NUMBER')
ENDSELECT
CHANGE FIELD(#BIF_RET02) TO('#TOTAL / #BIF_ALC01') ROUND_UP(*Y
ES)
********** go through the list again and add the overs or unders
********** to the return list
CLR_LIST NAMED(#BIF_RET01)
SELECTLIST NAMED(#BIF_ARG01) WHERE('((#BIF_ARG02 *EQ O) *AND (#NUM
BER *GT #BIF_RET02)) *OR ((#BIF_ARG02 *EQ U) *AND
(#NUMBER *LT #BIF_RET02))')
ADD_ENTRY TO_LIST(#BIF_RET01)
ENDSELECT
********** This is a shutdown call
**********
ELSE
********** No shutdown logic
ENDIF
********** Return control to the invoker
RETURN
********** End of RDML commands **********
Note that:
- The return value list is explicitly cleared prior to any entries being added.
- The optional argument and return value can be referred to even though they may not have been coded in the USE statement. It would be more usual to condition references to any optional arguments or return values by testing the value of *BIF_ARGCOUNT and *BIF_RETCOUNT respectively. There is no extra processing to derive the optional return value. It saves defining another work field.
- Because the function is heavyusage, its evaluation logic is conditioned by ensuring that it is not a shutdown call. Also the accumulation field is reset to 0 every time. For this RDML BIF there is no special shutdown logic.