12.4.1 RDML Functions

Consider the following function to evaluate the system variable *SYDN as an example of the simplest form of a system evaluation function:

FUNCTION  OPTIONS(*DIRECT *ALP_SYSTEM_VARIABLE *NOMESSAGES)

CHANGE     FIELD(#SYSVAR$AV) TO('SYD0386')

• This function can be very easily expanded to return the values for 2 system variables named *SYDN and *MELB because they are both of type alphanumeric:

FUNCTION  OPTIONS(*DIRECT *ALP_SYSTEM_VARIABLE *NOMESSAGES)

IF         COND(#SYSVAR$NM *EQ '''*SYDN''')

CHANGE     FIELD(#SYSVAR$AV) TO('SYD0386')

ELSE

CHANGE     FIELD(#SYSVAR$AV) TO('MEB2307')

ENDIF

• In addition this function could return values for system variables that have different lengths like *SYDN, *MELB, *COMPANY ...

FUNCTION  OPTIONS(*DIRECT *ALP_SYSTEM_VARIABLE *NOMESSAGES)

CASE      OF_FIELD(#SYSVAR$NM)

WHEN      VALUE_IS('= ''*SYDN''')

CHANGE    FIELD(#SYSVAR$AV) TO('SYD0386')

WHEN      VALUE_IS('= ''*MELB''')

CHANGE     FIELD(#SYSVAR$AV) TO('MEB2307')

WHEN      VALUE_IS('= ''*COMPANY''')

CHANGE     FIELD(#SYSVAR$AV) TO('C05')

ENDCASE

In these examples the returned values are generated from moves of numeric or alphanumeric literals that are "hard-coded" into the system variable evaluation function. In reality this is not usually the case. The returned values are most often derived from data areas or database files. The extension of the logic demonstrated above to access data areas or database files is fairly easy to imagine.

Technical Notes

System variable evaluation functions can handle system variables of different lengths and decimal precision but not of different types. The option *ALP_SYSTEM_VARIABLE is used to indicate that this is a function to evaluate an alphanumeric value. The option *NUM_SYSTEM_VARIABLE is used to indicate that this is a function to evaluate a numeric value.

It is necessary to define the following fields in the data dictionary, in order to access the system variable name and the system variable value within the evaluation function:

	SYSVAR$NM A(20)	System Variable Name
	SYSVAR$AV A(256)	System Variable Alphanumeric Return Value
	SYSVAR$NV P(30,9)	System Variable Numeric Return Value

Note that this implementation effectively prohibits evaluating numeric fields with more than 21 significant digits of precision.

If option *ALP_SYSTEM_VARIABLE is used within the function, return the evaluated value in field SYSVAR$AV, otherwise return the value in field SYSVAR$NV if option *NUM_SYSTEM_VARIABLE has been used.

If either *ALP_SYSTEM_VARIABLE or *NUM_SYSTEM_VARIABLE have been entered as a function option, the following design constraints (rather than technical constraints) exist to ensure the correct use of the system variable facility:

• No DISPLAY, REQUEST or POP_UP command can be used.

• No CALL can exist to another process/function within a complex logic validation function. However, a call to a 3GL program can exist.

• System variable evaluation functions cannot exist within an action bar process. This is not to say that they cannot be referenced by an action bar process, just not defined as part of a process of action bar type.

• System variable evaluation functions cannot have options of RCV_DS or RCV_LIST.

• The associated process must not have parameters.

• The exchange list may not be used. This restriction ensures insulated modularity in the evaluation function. System variables can be referenced almost anywhere in LANSA and requiring information in an exchange list at the time of reference would require very strange implementations.

• Recursive implementations may be defined, but will fail to execute correctly. For instance: system variable *TEST is defined and its evaluation function FUNC01 defined. If FUNC01 makes a reference to *TEST directly, or indirectly (through a validation rule or default value) it will attempt to invoke itself recursively and fail.
  
  The trap to watch out for here is in default values. Say field #TEST is defined in the data dictionary with a default of *TEST. If FUNC01 makes any reference at all to field #TEST then it will be implemented with initialization logic to set up the default value of #TEST, which means of course a call to function FUNC01, which is not only recursive, but endless.

• Use of options *DBOPTIMIZE and *NOMESSAGES are recommended for system variable evaluation functions. The use of *HEAVYUSAGE may also be considered in heavily used evaluation functions.

• The use of option *MLOPTIMIZE is strongly recommended in all multilingual applications of this facility.