Module overriding

Deploying different versions of a given .42m module to implement hook functions.

When a FUNCTION is called at runtime, the .42m module implementing the function will be loaded dynamically, if it is not yet in memory.

Modules are found at runtime according to a package directory structure, and by using the FGLLDPATH environment variable.

If you implement the same modules and functions (with the same parameters and return types), it is possible to implement customized code in application programs, in a dedicated "plugin" module containing these "hook functions".

Depending on the FGLLDPATH directory search list, you can control which .42m module will be loaded at runtime:
Directories content FGLLDPATH plugin loaded from
./dir_a/plugin.42m
./dir_b/plugin.42m
./dir_a ./dir_a
./dir_a/plugin.42m
./dir_b/plugin.42m
./dir_b ./dir_b
./dir_a/plugin.42m
./dir_b/plugin.42m
./dir_a:./dir_b ./dir_a
./dir_b/plugin.42m
./dir_a:./dir_b ./dir_b
./dir_a/plugin.42m
./dir_a:./dir_b ./dir_a
./dir_a/plugin.42m
./dir_b Runtime error -6206.

A good practice is to have FGLLDPATH only contain the directory paths to the wanted .42m modules, that must be located in the specified directories.

The concept of "hook function" is a user-defined function, that is called at specific places by programs, in oder to customize the application behavior.

A good practice is to return at least a status value from the hook functions, to indicate the caller if the custome code execution succeeded (0), failed (<0) or succeed with warnings (>0)

By default, the application must provide a default module implementing the hook functions with an empty body (doing nothing), and returning success (0)

The standard application code typically passes data to the hook function, to be modified or checked.

In the next example, the module implementing the MAIN block imports a "plugin" module, that implements two hook functions, to control the SQL transaction with custom code:

Directory structure (no packages):
hook_functions
├── common
│   ├── mytypes.42m
│   └── mytypes.4gl
├── custom_code
│   ├── plugin.42m
│   └── plugin.4gl
├── default_code
│   ├── plugin.42m
│   └── plugin.4gl
├── main.42m
└── main.4gl
Module main.4gl:
IMPORT FGL mytypes
IMPORT FGL plugin

MAIN

    DEFINE rec mytypes.t_customer
    DEFINE s INTEGER, m STRING

    CONNECT TO ":memory:+driver='dbmsqt'"

    CREATE TABLE customer (
       customer_id INTEGER NOT NULL PRIMARY KEY,
       cust_name VARCHAR(50) NOT NULL,
       cust_address VARCHAR(100)
    )

    TRY
        BEGIN WORK
        LET rec.customer_id = 938
        LET rec.cust_name = "Peter Silverstone"
        LET rec.cust_address = "5 Quantom St."
        CALL plugin.customer_before_insert(rec)
          RETURNING s, m
        IF s<0 THEN
           DISPLAY SFMT("ERROR %1: %2",s,m)
           GOTO l_rollback
        END IF
        INSERT INTO customer VALUES (rec.*)
        CALL plugin.customer_after_insert(rec)
          RETURNING s, m
        IF s<0 THEN
           DISPLAY SFMT("ERROR %1: %2",s,m)
           GOTO l_rollback
        END IF
        COMMIT WORK
        DISPLAY "OK: New row was inserted"
    CATCH
LABEL l_rollback:
        ROLLBACK WORK
    END TRY

END MAIN
Module common/mytypes.4gl:
PUBLIC TYPE t_customer RECORD
       customer_id INTEGER,
       cust_name VARCHAR(50),
       cust_address VARCHAR(100)
   END RECORD
Module default_code/plugin.4gl:
IMPORT FGL mytypes

PUBLIC FUNCTION customer_before_insert(
    rec mytypes.t_customer INOUT
) RETURNS (INTEGER,STRING)
    RETURN 0, NULL
END FUNCTION

PUBLIC FUNCTION customer_after_insert(
    rec mytypes.t_customer INOUT
) RETURNS (INTEGER,STRING)
    RETURN 0, NULL
END FUNCTION
Module custom_code/plugin.4gl:
IMPORT FGL mytypes

PUBLIC FUNCTION customer_before_insert(
    rec mytypes.t_customer INOUT
) RETURNS (INTEGER,STRING)
    IF upshift(rec.cust_name) <> rec.cust_name THEN
        RETURN -1, "Customer name must be uppercase"
    END IF
    RETURN 0, NULL
END FUNCTION

PUBLIC FUNCTION customer_after_insert(
    rec mytypes.t_customer INOUT
) RETURNS (INTEGER,STRING)
    RETURN 0, NULL
END FUNCTION
At runtome (after compiling the modules), FGLLDPATH settings control which module is used by the main program:
$ export FGLLDPATH=$PWD/common:$PWD/default_code
$ fglrun main.42m
OK: New row was inserted

$ export FGLLDPATH=$PWD/common:$PWD/custom_code
$ fglrun main.42m
ERROR -1: Customer name must be uppercase