TAFJ-Lo c k M a n a g e r

R20
 TAFJ-Lo c k M a n a g e r

Amendment History:

Revisio
Date Amended Name Description
n

1 1st April 2011 TAFJ team Initial version

7st February
2 H. Aubert R12GA review
2012

16th January
3 R. Vincent R13GA review
2013

4 18th Feb. 2014 R. Vincent R14GA review

5 11th April 2014 R. Vincent Add MSQL Locking

6 15th April 2014 H. Aubert R14GA review

10th March
7 H. Aubert R15 AMR review
2015

8 4th June 2015 R. Vincent Add TAFJ DATABASE Lock Manager

Add urls for Oracle and SQL Server locking return

9 29th Feb 2016 R. Vincent
codes.

10 15th March 2016 R. Vincent R16 AMR review

11 2nd August 2016 R. Vincent Update database locking

12 21st Oct. 2016 R. Vincent Add resilient tLockManager

13 21st Nov. 2016 H.Aubert Review Resilient tLockManager

Page 2
TAFJ-Lo c k M a n a g e r

Update table name from LOCK_RECORDS to

14 7th April 2017 R. Vincent
TAFJ_LOCKS.

15 7th Feb 2018 M.Kumar Database locking mode to show blocking locks only

Include TAFJ_HASHLOCKS mode for DATABASE

16 20th Sep 2018 M.Kumar
locking

Muthukrishnan
17 22nd Mar 2019 R19 AMR review
P

Basheer
18 6th Jun 2019 ORCL locking changes, related to hash generation
Ahamed

Cleanup mechanism for non existing rows in mode

19 11th Nov 2019 M.Kumar
1.

20 24th March 2020 Puja M R20 AMR review

Page 3
TAFJ-Lo c k M a n a g e r

Copyri g h t

Copyright © Temenos Headquarters SA 2009-2020.

All rights reserved.
This document contains proprietary information that is protected by copyright. No part of this document may
be reproduced, transmitted, or made available directly or indirectly to a third party without the express
written agreement of TEMENOS UK Limited. Receipt of this material directly TEMENOS UK Limited
constitutes its express permission to copy. Permission to use or copy this document expressly excludes
modifying it for any purpose, or using it to create a derivative therefrom.

Errat a and Com m e n t s

If you have any comments regarding this manual or wish to report any errors in the
documentation, please document them and send them to the address below:
Technology Department

Temenos Headquarters SA
2 Rue de l’Ecole-de-Chimie,
CH - 1205 Geneva,
Switzerland

Tel SB: +41 (0) 22 708 1150

Fax: +41 (0) 22 708 1160

Please include your name, company, address, and telephone and fax numbers, and email
address if applicable. [email protected]

Page 4
TAFJ-Lo c k M a n a g e r

Table of Contents
Copyright................................................................................................................................................ 4
Errata and Comments............................................................................................................................ 4
TAFJ tLockManager............................................................................................................................... 6
Introduction............................................................................................................................ 6
Syntax................................................................................................................................... 6
TAFJ tLockManager.............................................................................................................. 7
TAFJ tLockManager (Resilient)............................................................................................. 9
TAFJ JDBC Lock Manager................................................................................................................... 10
TAFJ DATABASE Lock Manager......................................................................................................... 11
TAFJ Oracle Lock Manager.................................................................................................................. 16
TAFJ MSQL Lock Manager.................................................................................................................. 17
Monitoring............................................................................................................................................. 19
In Verbose Mode: (PROC).................................................................................................. 19
In DBTools:.......................................................................................................................... 20
In Java Mission Control with --jmx options:......................................................................... 20
With the TAFJTrace.properties........................................................................................... 21
WARNING !.......................................................................................................................................... 23

Page 5
TAFJ-Lo c k M a n a g e r

TAFJ tLoc k M a n a g e r

Intr o d u c t i o n

Pessimistic locking is needed within T24. Pessimistic locking assumes that the lock is not
taken and a specific request is needed to take the lock. This can be accomplished in TAFJ
by either using tLockManager (a process outside of the database) or one of the mechanisms
for database locking.

tLockManager is a Lock Manager designed for TAFJ needs.

Syn t a x

To launch the tLockManager, use this syntax:

tLockManager [-p<port>][-m1|2][-i | -jvm= "<jvm_args>" ] [--jmx] [--verbose] [--debug]

Options:

-p<port> : port on which to connect to

-i : run interactively (not in background)
-m : 1 for normal 2 for hash
--verbose : run in verbose mode
--debug : In verbose mode trace debug

The default port it will listen on is 7425.

Page 6
TAFJ-Lo c k M a n a g e r

TAFJ tLoc k M a n a g e r

Example

To launch it, go in the bin directory of your TAFJ installation and just type
> tLockManager -i (if you want to run in background mode then you can remove -i)
If you are using the LockManager in PROCHASH, start the lockManager with the option –m2
> tLockManager -i -m2
If you are running the Lockmanager in background, you can pass specific JMV argument
with the option –jvm
> tLockManager -i -jvm="-Xms256M –Xmx2048M -XX:MaxPermSize=256M"
If you are using the LockManager in interactive mode you can pass the options –verbose
then –debug. You will have all the information in the screen about what’s going on in the
tLockManager. The option –Verbose add an overhead of about 5% and the option –debug
add an overhead of about 11% on the performance.
> tLockManager -i -m2 --verbose
> tLockManager -i -m2 --verbose --debug
If you want to monitor JMX MBean of the tLockManager, you need to specify the option –jmx.
> tLockManager -i -m2 --jmx

The Output will be:

[1495013022605] [INFO ] Start tLockmanager PROCHASH (mode 2)

[1495013022605] [Pid=4600 Host=10.41.2.29 Port=7425 Mode=PROCHASH][INFO ] tLockManager started.
[1495013022605] [Pid=4600 Host=10.41.2.29 Port=7425 Mode=PROCHASH][INFO ] tLockManager JMX is set to true
[1495013022605] [Pid=4600 Host=10.41.2.29 Port=7425 Mode=PROCHASH][INFO ] tLockManager DEBUG is set to false
[1495013022605] [Pid=4600 Host=10.41.2.29 Port=7425 Mode=PROCHASH][INFO ] tLockManager VERBOSE is set to false
[1495013022616] [Pid=4600 Host=10.41.2.29 Port=7425 Mode=PROCHASH][INFO ] tLockManager HTTP Health Page on port : 7426

Page 7
TAFJ-Lo c k M a n a g e r

Once done, you can configure your instance by editing your <project>.properties file with
following fields:

Under TAFJ Locking mechanism setup:

#********************************************************************
#
# TAFJ Locking mechanism
#
#********************************************************************
# Tafj locking mode
# Could be : JDBC | ORCL | MSQL | PROC | PROCHASH | MEM | NONE
# JDBC : locks managed in database uses TAFJ_LOCKS table.
# ORCL : locks managed in database using DBMS_LOCK Oracle specific package. Recommended solution for
Oracle.
# MSQL : locks managed in database using DBMS_LOCK MS-SQL specific package. Recommended solution for MS-
SQL.
# PROC : TAFJ lock manager, external process, server accepting client connections on a port.
# PROCHASH : TAFJ lock manager, external process, server accepting client connections on a port (for
performance).
# MEM : Memory mode version of the TAFJ lock manager.

temn.tafj.locking.mode = PROCHASH

# Host name or IP of where is the tLockManager daemon

#
temn.tafj.locking.hostname = 127.0.0.1

# TCP port of the tLockManager daemon is listening on

#
temn.tafj.locking.port = 7425

# Bring the current call stack over to the LockManager?

#
temn.tafj.locking.callstack = false

# if we want to override the URL as unique key for the DBInstance

# we have to give a name here (eg myDatabase). This is usefull
# if the DBServer has multiple adapters. The URL's are different
# but this is still the same Database.
# only for PROC and PROCHASH
#
temn.tafj.locking.name =

Page 8
TAFJ-Lo c k M a n a g e r

TAFJ tLoc k M a n a g e r (Re s i l i e n t )

To make tLockManager resilient, you need to install a load balancer on top of two or more
tLockmanager. The policy of the LoadBalancer to switch to a different tLockmanager is by
query the http health page of the tLockManagers on the port number + 1. If the
LockManager dies, the loadbancer will switch to a other one and all T24 connections will be
restart/reset.

T24 /T24

Load Balancer
Server 1,server2
Port 7526

HTTP Page Health HTTP Page Health

tLockManager tLockManager

Server 1 Server 1
Port 7526 Port 7526
Http 7527 Http 7527

Page 9
TAFJ-Lo c k M a n a g e r

TAFJ JDBC Lock Man a g e r

TAFJ can take locks by using an underlying database table. This table has the format:
SQL> desc TAFJ_LOCKS;

Name Null? Type

----------------------------------------- -------- -------------------------

RECID NOT NULL VARCHAR2(255)

SESSIONID VARCHAR2(50)

This method works well within an application server context where a separate datasource
can be set up for locking. However, it performs worse than tLockManager and ORCL
locking. Edit properties file and set:

temn.tafj.locking.mode = JDBC

Page 10
TAFJ-Lo c k M a n a g e r

TAFJ DATABASE Lock Man a g e r

To set the lock manager to database locking mode, set the property:

temn.tafj.locking.mode = DATABASE

The database-locking mode has two different algorithms

Mode 1: using TAFJ_NONEXISTING_ROWS table

Mode 2: using TAFJ_HASHLOCKS table

The default is Mode 1.

The mode can be switched to Mode 2 by adding the below property with false in properties
file.

temn.tafj.jdbc.db.locking.insert.rows.on.demand = false

 Savepoint stored procedure has to be executed inside the DB from

TAFJ_HOME/dbscripts/<DB flavour>/createSavePointStoredProc.sql for T24
service architecture support.

Mode 1:

This mode makes use of an internal technical table TAFJ_NONEXISTING_ROWS for

handling the locks of non-existing records from the application. This table is created on fly in
the environment by the runtime when the locking mode set appropriately.

This mode handles the inserts and deletes in the technical table
TAFJ_NONEXISTING_ROWS on demand as a part of transaction boundary.

In cases of JVM going down suddenly there is a clean up mechanism in place for application
server which execute the JBC routine CLEANUP.STALE.ENTRIES which is shipped along
with TAFJ in TAFJBasic.jar.

Page 11
TAFJ-Lo c k M a n a g e r

The cleanup mechanism for standalone TAFJ is not in place out of box, alternatively the
above routine CLEAUP.STALE.ENTRIES should be executed from a shell prompt to perform
the cleanup.

Ex: from TAFJ_HOME/bin.

tRun CLEANUP.STALE.ENTRIES

Before:

sql> SELECT * FROM TAFJ_NONEXISTING_ROWS;

RECID | CREATEDTIME

FBNK_CURRENCY*YYY | 2019-11-11 15:53:58.64

FBNK_CURRENCY*YZY | 2019-11-11 15:54:07.634

FBNK_CURRENCY*GGG | 2019-11-11 15:54:12.037

FBNK_CURRENCY*UUU | 2019-11-11 15:54:16.015

After executing the cleanup routine.

[ERROR] 2019-11-11 16:05:13,803 [CLEANUP_STALE_ENTRIES_723715090] BASIC
{command=CLEANUP_STALE_ENTRIES, sessionId=723715090} - DATE : 18943 > 18943 or TIME : 675 > 600 for the entry :
FBNK_CURRENCY*YYY

[ERROR] 2019-11-11 16:05:13,806 [CLEANUP_STALE_ENTRIES_723715090] BASIC

{command=CLEANUP_STALE_ENTRIES, sessionId=723715090} - Deleting : FBNK_CURRENCY*YYY

[ERROR] 2019-11-11 16:05:13,845 [CLEANUP_STALE_ENTRIES_723715090] BASIC

{command=CLEANUP_STALE_ENTRIES, sessionId=723715090} - DATE : 18943 > 18943 or TIME : 666 > 600 for the entry :
FBNK_CURRENCY*YZY

[ERROR] 2019-11-11 16:05:13,846 [CLEANUP_STALE_ENTRIES_723715090] BASIC

{command=CLEANUP_STALE_ENTRIES, sessionId=723715090} - Deleting : FBNK_CURRENCY*YZY

[ERROR] 2019-11-11 16:05:13,884 [CLEANUP_STALE_ENTRIES_723715090] BASIC

{command=CLEANUP_STALE_ENTRIES, sessionId=723715090} - DATE : 18943 > 18943 or TIME : 661 > 600 for the entry :
FBNK_CURRENCY*GGG

[ERROR] 2019-11-11 16:05:13,886 [CLEANUP_STALE_ENTRIES_723715090] BASIC

{command=CLEANUP_STALE_ENTRIES, sessionId=723715090} - Deleting : FBNK_CURRENCY*GGG

Page 12
TAFJ-Lo c k M a n a g e r

[ERROR] 2019-11-11 16:05:13,924 [CLEANUP_STALE_ENTRIES_723715090] BASIC

{command=CLEANUP_STALE_ENTRIES, sessionId=723715090} - DATE : 18943 > 18943 or TIME : 657 > 600 for the entry :
FBNK_CURRENCY*UUU

[ERROR] 2019-11-11 16:05:13,926 [CLEANUP_STALE_ENTRIES_723715090] BASIC

{command=CLEANUP_STALE_ENTRIES, sessionId=723715090} - Deleting : FBNK_CURRENCY*UUU

Mode 2:

This mode makes use of an internal technical number table TAFJ_HASHLOCKS containing
values ranging from 0 – 2147483647 (Integer. MAX)

To populate this table, a procedure is in place under TAFJ_HOME/dbscripts/<DB

flavour>/tafj_hashlock_tab_prepare.sql.

The procedure runs for around 1 ~ 2 hrs depending on the hardware of the database server.

For oracle database, the procedure need to run in SYSDBA login as it involves creation of
index/primary key/Altering user data files/altering temp table spaces to accommodate the
huge table inside the DB.

Behind the scenes (in runtime):

TAFJ can take locks by using the underlying database locks. For READU and other locking
commands where records exists, the lock manager will issue a SELECT FOR UPDATE
(either blocking or non-blocking depending on the READU clause also has a LOCKED
clause) to the database to lock the record before an anticipated write. This means that a
JBC statement RELEASE will have no effect until a commit or rollback is performed. T24 is
wrapped inside transactional boundaries where the RELEASE statement is ignored until the
transactional boundary ends. Any L2/L3 code must conform to the same to use DATABASE
locking mode.

When a lock on a non-existent row is requested from T24 application the

TABLENAME*RECID is hashed to an integer value and a lock is obtained on
TAFJ_HASHLOCKS table using the same.

TAFJ can take locks by using the underlying database locks. For READU and other locking
commands where records exists, the lock manager will issue a SELECT FOR UPDATE
(either blocking or non-blocking depending on the READU clause also has a LOCKED
clause) to the database to lock the record before an anticipated write. This means that a
JBC statement RELEASE will have no effect until a commit or rollback is performed. T24 is

Page 13
TAFJ-Lo c k M a n a g e r

wrapped inside transactional boundaries where the RELEASE statement is ignored until the
transactional boundary ends. Any L2/L3 code must conform to the same to use DATABASE
locking mode.

READU without LOCKED clause for a nonexistent record.

We can clearly see the second session is waiting on lock for the first one to commit or roll
back.

Once the rollback from first session, the other one grabs the lock.

Page 14
TAFJ-Lo c k M a n a g e r

READU with LOCKED clause for a nonexistent record.

When both the sessions ask for a READU LOCKED clause on nonexistent record, the first
one acquiring the lock will end up in ELSE clause and the second thread enters LOCKED
clause and continues.

Page 15
TAFJ-Lo c k M a n a g e r

Reporting locks with DBTools (with the LOCKS command) will appear a bit different when
using this. When issuing the LOCKS command, the only blocking locks can be viewed under
this mode.

i.e example :

Session A takes a lock on FBNK.CURRENCY CHF without a LOCKED clause and session B
does the same, the session B hangs till it manages to obtain the lock to continue further. In
this case an entry in LOCKS command will show up as blocking lock along with the time in
seconds from which this is blocked.

Page 16
TAFJ-Lo c k M a n a g e r

Page 17
TAFJ-Lo c k M a n a g e r

TAFJ Oracl e Lock Man a g e r

This method of locking works only with the Oracle database and leverages the DBMS_LOCK
package within Oracle to take TAFJ application locks. It is the preferred method when using
Oracle database and performs slightly faster than tLockManager. Edit properties file and set:

temn.tafj.locking.mode = ORCL

For return values of DBMS_LOCK for locking and releasing, please see the following URL.

http://docs.oracle.com/cd/B19306_01/appdev.102/b14258/d_lock.htm#i997159

The ORCL Lock mechanism make use of oracle’s API (DBMS_LOCK.ALLOCATE_UNIQUE)

to allocate a unique INT to handle the lock.

The DBMS_LOCK.ALLOCATE_UNIQUE stores the locks in a table called

DBMS_LOCKS_ALLOCATED. The entries in this table are maintained by default for 10 days
(default from oracle). This expiration of entries in this table can be overridden by adding the
below property to the properties file.

temn.tafj.locking.orcl.allocate.unique.exp.secs=<value>

If the property is disabled/ removed from properties file a default value of 2 days (172800
seconds) will be added by runtime.

ORCL locking architecture has been changed such that only the tables defined in the
property 'temn.tafj.orcl.table.list.for.unqiue.locking' would use dbms_lock.allocate_unique to
generate unique hash for lock/release. For other tables, internal processing will be applied to
generate the hash for lock/release of tables.

To use this feature, add the tables to the below property in tafj.properties file

temn.tafj.orcl.table.list.for.unqiue.locking =

Default value for the property is null and tables should be added to the property, as advised
by PACS team.

Note: Table names should be Oracle table names, not J4file names. Multiple table names
can be added to this property, separated by semi-colon (;)

Whenever this property is modified, a server restart is required, for the changes to take
effect.

Page 18
TAFJ-Lo c k M a n a g e r

By setting this parameter, tables defined in the parameter will make use of Oracle unique
lock mechanism, which will resolve the 'waiting for lock' scenario during COB services.

TAFJ MSQL Lock Man a g e r

This method of locking works only with the MS Sql Server database and leverages packages
within Sql Server to take TAFJ application locks. It is the preferred method when using Sql
Server database and performs slower than tLockManager but keeps all locking within the
database. Edit properties file and set:

temn.tafj.locking.mode = MSQL

For return values for locking and releasing, please see the following URL.

https://msdn.microsoft.com/en-us/library/ms189823.aspx

Note that MSQL LockManager will crash Eclipse with sqljdbc_4.1 drivers and will not
produce the right results (DBTools LOCKS command). It should also be noted that sp_lock
command truncates data. Version sqljdbc_1.2 of drivers have been tested and work.

Page 19
TAFJ-Lo c k M a n a g e r

Mon i t o r i n g
The lock manager offers several ways to monitor locks. One easy way of seeing what is
going on is to run the EX Basic File using tRun
Example:
tRun EX
The output will be:

If you’re running tLockManager in verbose mode (ie tLockManager --verbose -i ) then, you
will get some information while running EX basic.

Page 20
TAFJ-Lo c k M a n a g e r

In Verb o s e Mod e : (PROC)

In DBT o o l s :

Page 21
TAFJ-Lo c k M a n a g e r

In Java Mis s i o n Contr o l with --jmx opti o n s :

With th e TAFJTrac e . p r o p e r t i e s

In <TAFJ_HOME>/conf/TAFJTrace.properties there is a log4j logger setup for LOCKING. To

set maximum level of debugging, set the below line:

log4j.logger.LOCKING=DEBUG, locking
The log file is <TAFJ_HOME>/log/locking.log

log4j.logger.LOCKING_SERVER=DEBUG, locking_server
The log file is <TAFJ_HOME>/log/locking_server.log

Page 22
TAFJ-Lo c k M a n a g e r

Page 23
TAFJ-Lo c k M a n a g e r

WARNI N G !
The verbose mode and DEBUG mode degrade the performance.

The option --verbose add an overhead of about 5% and the option --debug add an
overhead of about 11% on the performance.

The output --verbose

Page 24