9.38 DEFINE_OVERRIDE_FILE
Þ Note: Built-In Function Rules.
Use this Built-In Function to override the Database Table Owner Name and/or the Database Table Name.
Typically this Built-In Function will be used when the library (schema name) associated with a file (table) is modified during the application installation. In this case the table is created in the database with the installation schema name but the supplied OAM has embedded in it the LANSA Library of when the OAM was generated. To access the file when executing the application, the application must redirect the OAM to the appropriate LANSA Library for the current installation using the DEFINE_FILE_OVERRIDE. Refer to Why are File Overrides required? and Use of Define_Override_File with SuperServer and LANSA Open.Net for details.
The database overrides remain only during the current session.
The DEFINE_OVERRIDE_FILE's functionality is not available to the SELECT_SQL Free Format command.
For use with
|
Arguments
|
Return Values
|
Why are File Overrides required?
When installing an application only one OAM will be installed which has embedded in it the LANSA Library of when the OAM was generated. If an application file is installed into a library which is different to the library embedded in the OAM, the OAM must be redirected to the appropriate LANSA Library at runtime. The LANSA Library is mapped into the database equivalent, which has a different name in different database managers: it is variously called Schema, Owner and Collection.
A summary of the process:
1. The Function/Component is generated with the BUILT library and passes this to the common database execution layer.
2. The OAM is located. If this is in the or then the library is no longer the BUILT library. It is an EXECUTE Library.
A file OAM refers to the library it is BUILT with. When overriding, you would specify this BUILT library in OVERRIDE_TABLE_OWNER.
3. The EXECUTE is looked up to see if there is an OVERRIDE. If the EXECUTE library is still the BUILT library then the file will be overridden with the new library.
If you need to override a file that has been installed in the , then the system variable needs to be assigned to a and this passed to the OVERRIDE_TABLE_OWNER so that the library can be overridden at runtime.
An application has files installed into the . Typically the is NOT the same name as the BUILT library. If it were the same, then OVERRIDE of BUILT would also override the files. This would not achieve the desired outcome, as the files should always access the same library.
Use of Define_Override_File with SuperServer and LANSA Open.Net
The DEFINE_OVERRIDE_FILE operates on the database local to the RDML that is executing. When database IO is performed, the OAM checks the file overrides on the machine/process where the OAM is executing. Therefore, an OAM executing on a server requires that the file overrides have been set up on the server by using CALL_SERVER_FUNCTION and calling the DEFINE_OVERRIDE_FILE appropriately. This is true for both SuperServer and LANSA Open .Net.
How to set up an override
1. A valid File Library name and optionally a File Name must be provided to indicate the file(s) that overrides should be applied to.
2. A valid Override Database Table Owner name and/or Override Database Table name must also be provided. The below table illustrates all valid cases:
|
How to remove an override of group of overrides
1. Execute DEFINE_OVERRIDE_FILE with no arguments values supplied to remove all overrides on database files.
2. Execute DEFINE_OVERRIDE_FILE with only the File Library Name argument to remove overrides from all files in a library.
3. Execute DEFINE_OVERRIDE_FILE with the File Library Name and File Name arguments to remove overrides from a specific file.
|
Examples
Example 1: Override all Files under a specific File Library name to a different Database Table Owner ABC
Use BIF(Define_Override_File) ('DC@DEMOLIB' *Default 'ABC') To_Get(#retcode)
Example 2: Override a specific File to a different Database Table Owner ABC
Use BIF(Define_Override_File) ('DC@DEMOLIB' 'PSLMST' 'ABC') To_Get(#retcode)
Example 3: Override a specific File to a different Database Table with the same Database Table Owner
Use BIF(Define_Override_File) ('DC@DEMOLIB' 'PSLMST' *Default 'XYZ') To_Get(#retcode)
Example 4: Override a specific File to a different Database Table
Use BIF(Define_Override_File) ('DC@DEMOLIB' 'PSLMST' 'ABC' 'XYZ') To_Get(#retcode)
Example 5: Remove all defined overrides
Use BIF(Define_Override_File) To_Get(#retcode)
Example 6: Remove a File Library override
Use BIF(Define_Override_File) ('DC@DEMOLIB') To_Get(#retcode)
Example 7: Remove a specific File override
Use BIF(Define_Override_File) ('DC@DEMOLIB' 'PSLMST') To_Get(#retcode)