RDML Built-In Function Tips and Techniques

Initial Creation of an RDML Built-In Function

It is recommended that the RDML commands of an RDML Built-In Function be in the following sequence:

...

It would be extremely unusual to code DISPLAY, POP_UP or REQUEST commands in an RDML BIF function, unless it was documented that the RDML BIF is to run only in an interactive environment and appropriate checking for such an environment were coded on entry to the RDML BIF. This would affect the portability of the RDML BIF.

Termination of RDML Built-In Function

An RDML Built-In Function that is *LIGHTUSAGE will terminate after every USE of it.

...

These last three points are important. The execution of the shutdown logic is dependent not just on whether the RDML Built-In Function is marked as light or heavy usage. It also depends on whether the USEing function is light or heavy usage. The recommendation is to specify *LIGHTUSAGE in the RDML Built-In Function and to not have any logic in the shutdown logic. This means that the whole function becomes conditioned on *BIF_SHUTDOWN being 'N'. If the RDML Built-In Function is then changed to *HEAVYUSAGE, the USEing functions do not need to be re-compiled. Note that the impact of field values retaining their value between invocations would need to be investigated. The best solution to this is to always use explicit CHANGE/ASSIGN commands to set the initial value of all fields used in the function.

Platform Differences when Shutting down *HEAVYUSAGE Built-In Functions

There are differences when RPG functions as opposed to C/C++ functions shutdown *HEAVYUSAGE functions. (RPG is generated for RDML functions on IBM i. C/C++ is generated for RDMLX functions on IBM i, and both RDML and RDMLX functions on non-IBM i.)

...

A C/C++ Function that is *HEAVYUSAGE will get called to shutdown even when the application is terminating.

State Retention in *HEAVYUSAGE Built-In Functions

The state of fields used in *HEAVYUSAGE functions should not be relied upon due to the termination behaviour described above. For example, incrementing a value each time the RDML Built-In Function is executed. A *HEAVYUSAGE RDML Built-In Function can be called by *HEAVYUSAGE Functions and accumulate state. But as soon as a *LIGHTUSAGE Function is used, the *HEAVYUSAGE RDML Built-In Function will be shutdown and thus lose its state.

If you need to retain state, use a data area or system variable.

Optional Arguments and Return Values

It would be usual to condition references to optional return values and their derivation by testing the value of the system variable *BIF_RETCOUNT. In particular where deriving an optional return value is expensive in terms of machine resources, this would be more efficient.

...

Optional arguments and return values can be referred to in the RDML Built-In Function whether or not they have been coded in the USE command of the USEing function.

Access to an RDML BIF Function

Functions are partition specific. Built-In Function definitions are LANSA system wide. If an RDML Built-In Function has to be made available to a partition other than that where it has been compiled, it must be accessible in the library list for that other job. As with 3GL BIFS, this is the responsibility of the LANSA administrator or provider of the BIF.

Replacing 3GL BIFs with RDML BIFS

If, in the interests of portability, a 3GL BIF is replaced by an RDML BIF, all functions that USE that BIF will need to be recompiled, because of differences in the underlying architecture between 3GL and RDML BIFs

Adding Optional Arguments and Return Values

New optional arguments and return values can be added to RDML Built-In Functions without having to recompile all functions that already USE the RDML BIF. To do this the new optional arguments or return values are added after all other arguments and return values. Obviously functions that take advantage of the new optional arguments or return values will need to be recompiled. However, if the Built-In Function is enabled for RDMLX and it is used from any RDML function, then you cannot add an extra parameter, or in fact change anything to do with the number and order of arguments and return values, unless you recompile the RDML functions that USE this RDMLX BIF.

...

• RDMLX functions to RDMLX Built-In Functions

• RDMLX functions to RDML Built-In Functions

• RDML functions to RDML Built-In Functions.

RDML BIFS in a Client / Server Environment

An RDML BIF can be used to redirect execution from the client to the server without the remainder of the application being concerned with the 'mechanics' of it.