STUBFILE Conversion

This section provides a guide for the conversion of Temenos Transact RDBMS STUBFILE files from an existing Temenos Transact RDBMS implementation into the VOC table as VOC TABLE entries.

Although STUBFILE files have been deployed as the mechanism to access RDBMS database tables and other types of databases successfully, they cause a complication to the configuration, maintenance and various deployments of Temenos Transact and the associated RDBMS database.

The STUBFILE files must reside on a physical file partition, which is shared usually over the Multiple Application Servers executing the Temenos Transact processes. The information contained within the STUBFILE files must be preserved and maintained over and above the actual data in the database. The STUBFILE files must always be aligned correctly with the database so that they correctly reflect the tables and their types, which are created or deleted in the database.

It is possible to configure VOC as a RDBMS table and hold STUBFILE information directly in the VOC. The VOC as an RDBMS table means that the STUBFILE information is now preserved directly in the associated RDBMS database. In addition, the application lock mechanisms are enhanced to be independent of the physical STUBFILE files.

The above modifications indicate that the STUBFILE files are no longer necessary and can be removed. Similarly, the procedures required to ensure that the STUBFILE files are correctly aligned and maintained with the RDBMS database are no longer necessary.

The format of the previous STUBFILE information as represented in a VOC TABLE entry is described in Appendix A.

After the VOC entries have been converted from STUBFILE file references to TABLE entries, any subsequent tables created using Temenos Transact (EBS.CREATE.FILE) will automatically generate a VOC TABLE entry rather than a STUBFILE F pointer reference.

Data Comparison

The STUBFILE files were used Temenos Transact RDBMS implementations as a mechanism to redirect the file and/or table open request to the required database driver. The STUBFILE contains specific information relevant to both the Shared Object Library Loader and JEDI Database Driver.

For example, Description of a STUBFILE for ../bnk.data/ac/FBNK.ACCOUNT is as follows.

          FBNK.ACCOUNT
JBC__SOB XMLORACLEInit acFBNK_ACCOUNT

In the above example, JBC__SOB and XMLORACLEInit strings indicates that the runtime needs to locate a Shared OBject library containing the library initialisation function, XMLORACLEInit.

The runtime searches the file paths in the JBCOBJECTLIST and configured OS Library Path to locate the export file containing the required function. The library is then loaded and initialisation function is invoked. Subsequently, the driver open function is invoked with the rest of the arguments specified in the STUBFILE. The additional arguments in the STUBFILE can be specific to each database driver and are used to describe the name and type of the target file or RDBMS table.

In this example, the XMLORACLE database driver will try to access the RDBMS table name of acFBNK_ACCOUNT as type XML in the default database schema of the configured ORACLE database.

The STUBFILE can contain several additional arguments, which further define the table configuration to the database driver. The STUBFILE contents should never be modified manually. For the conversion process, the STUBFILE information is extracted and placed directly in VOC as VOC TABLE entries.

The STUBFILE conversion process is one of a suite of conversions that is provided by the RBDMS Conversion package, which must be installed and configured in the environment run directory.

Conversion Process

The aim of the full conversion process is to create a clean copy of the existing VOC as a RDBMS table in the database and convert the existing VOC F pointers usually used to refer the STUBFILE files, to VOC TABLE entries, which will contain the STUBFILE information directly.

The STUBFILE conversion process does not move or delete any actual tables. Only the STUBFILE files are removed from the directory structure after the conversion is complete.

The first phase of the conversion process will scan and analyse VOC, creating a new copy of the VOC (./rdbmsVOC) in the run directory. If the stub file conversion is selected, the rdbmsVOC will be created as a TABLE in the target RDBMS.

The conversion process will also create several work files in the ./rdbmsConversion conversion directory. These work files are used to control the conversion process and report details regarding the VOC analysis and conversion problems.

Each entry in VOC is processed as one of the following types.

Deprecated

A deprecated entry is a VOC entry type, which is no longer required. These entries will not be copied to the new VOC.

Invalid File

An invalid file indicates that the files specified in the F pointer do not exist and cannot be referenced. These entries will be reported in the InvalidFiles work file but will not be copied to the new VOC. These entries need to be reviewed prior to the final conversion to determine if they are still required.

Duplicate File

A duplicate file indicates that a reference to the file is found in one or more VOC entries. These entries will be reported in the DuplicateFiles work file and they will not be copied to the new VOC. These entries must be resolved prior to the conversion process.

VOC Vocabulary

The VOC vocabulary entries will be copied to the new VOC (./rdbmsVOC).

File Pointer

Each file pointer will be processed to determine the file paths of the file references. If the data file path references the data, dict, then a conversion entry will be generated in the respective DataFiles, DictTables work files of the conversion directory (./rdbmsConversion). If the file pointer references a file in another user directory then the file pointer is simply copied to the new VOC (./rdbmsVOC) but is not considered for conversion.

All current VOC entries are also preserved in a work file (eldVOC) in the rdbmsConversion directory. After analysis of the VOC is complete, the operator will be prompted to continue with the conversion. The next phase of the conversion process will then process each of the entries generated in the DataFiles and DictFiles work files.

The background processes working on behalf of the main conversion process handles the work of the Company Schema conversion. These background processes are started for each phase of the conversion, which are monitored, summarised and controlled by the main conversion process. The number of processes required for background processing can be specified before the conversion process begins.

The background process locks an entry in the work file (DataFiles, DictFiles or OtherFiles) depending upon the current conversion processing point. The background process then analyses the entry, creates the table in the normal way, retrieves the STUBFILE file information and updates the new VOC (./rdbmsVOC) accordingly.

All converted VOC entries will be recorded in the ConvertedVoc work file in the rdbmsConversion directory along with the associated STUBFILE file information in the StubFiles work file.

After all required sections of the conversion are completed, the main conversion process will either prompt the operator to continue in case of errors or continue the process and remove the original STUBFILE files from the original directory structure. VOC errors are reported in the VocErrors work file in the rdbmsConversion directory. If this step is not selected at the time of conversion, it can be performed later separately.

Finally, the new VOC (./rdbmsVOC) can be enabled by the rdbmsConversion/rdbmsMove.ksh script. This script moves the original VOC to ./eldVOC and new VOC (./rdbmsVOC) to VOC.

Before attempting to use the converted VOC, exit the process and re-login.

To revert to the original VOC, you can use the rdbmsConversion/rdbmsRevert.ksh script, which does the following.

1. Moves the new VOC back to ./rdbmsVOC

2. Moves the ./eldVOC back to VOC

The rdbmsRestoreStubs program can be used to reconstruct the original STUBFILE files, if required.

Execute StubFile Conversion

Run the rdbmsConvertStub.ksh company schema conversion script or rdbmsConvertStub.bat file

Override Options

RDBMS_PRESERVE_STUBS

This environment variable can be set to suppress the automated removal of the original STUBFILE files, prior to the execution of the conversion program.

RDBMS_ONLY_VOC_CONVERSION

This environment variable is pre-configured in the rdbmsConvertVoc script for the RDBMS conversion process to perform only a STUBFILE to VOC TABLE entry conversion.

Points to Remember

The RDBMS Conversion package logs output details for the main conversion process as well as the background processes in the &COMO& directory. If the RDBMS conversion procedure is re-executed, the process may prompt to rescan the VOC. If this option is chosen, it will reprocess the original VOC file but the ./rdbmsVOC file will not be recreated.

The initial creation of./rdbmsVOC will be of the data type configured already for the F.PGM.TABLE table. The RDBMS conversion can be quit at any time by depressing the Q key. If the original VOC is rendered unusable, a copy of the original VOC is held in the rdbmsConversion directory as eldVOC.

The RDBMS conversion can be reset by executing the rdbmsReset.ksh or rdbmsReset.bat script. The rdbmsMove.ksh script will cause reversion of any toggles of VOC and removes all related files and directories related to the RDBMS conversion. However, any STUBFILE files already removed will not be reinstated.

After the conversion is determined to be complete and new VOC tested, the RDBMS conversion work areas can be removed using rdbmsRemove.ksh or rdbmsRemove.bat.

Lock Considerations

The physical STUBFILE files were also used to take and propagate application level record locks. The unique Inode and device numbers from the physical STUBFILE files were used as unique identification of the associated table.

The removal of the STUBFILE files indicates that that the Inode and device number are now no longer available to be used with the relevant lock mechanism. The VOC TABLE definitions are used in place of the STUBFILE file to create pseudo Inode and device numbers for use by the lock mechanisms.

The pseudo Inode is generated using the Hash value of the table name specified in the VOC TABLE definition. The device number is derived from either the Hash value of the Driver Initialisation Function (XMLORACLEInit) or string value of the JBASE_DATABASE environment variable, if configured.

In case of deployment using the OS lock mechanism, the OS locks will be taken on abstracted files created specifically for record locks. The abstracted files will be created by default in a /tmp/jbase directory, which can be overridden by setting JBASE_UNIX_LOCKDIR. The entries in the directory take are in the jlock_IIIIIIII_DDDDDDDD format, in which IIIIIIII and DDDDDDDD are the hexadecimal representation of the Inode and device, respectively.

In case of a Multiple Application Server configuration using OS locks, the lock directory (/tmp/jbase) should be shared over a networked file system to propagate the OS locks correctly among servers.