Java Temenos Connector Server

Installation & Administration Guide

Release 1.4.0

Date of issue Version Changes By

May 2005 1.0 New template. New chapter on TCSConfig pgodot
tools. Link to TC Security Service.
OFS.CONNECTION.MANAGER replace by
tSS. Chapter Tracing updated(new log4j
appender).
July 2005 1.0.1 Added the Log4j Event Service Appender mlinari
description
Nov. 2005 1.0.2 Amended the JDBC Appender definition mlinari
Nov. 2005 1.0.3 Amended the JDBC Appender definition mlinari
Feb. 2007 1.0.4 Amended the SMTP Appender definition mlinari

Information in this document is subject to change without notice.

No part of this document may be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without the express written permission of TEMENOS Holdings NV.

Copyright 2002-2003 TEMENOS Holdings NV. All rights reserved.

Temenos Connector Installation and Administration Guide

1.1 Introduction ............................................................................................................................... 3

1.2 What’s new................................................................................................................................ 3
1.3 Prerequisites ............................................................................................................................. 3
1.4 Setup OFS ................................................................................................................................ 4
1.5 Testing OFS .............................................................................................................................. 5
1.6 Installing TCServer.jar and dependencies................................................................................ 6
1.7 Environment variables .............................................................................................................. 7
1.7.1 File : environment.vars ...................................................................................................... 7
1.7.2 The safest way : run .profile............................................................................................... 9
1.8 Configuration : tcserver.xml .................................................................................................... 10
1.9 Configuration with TCSConfig................................................................................................. 13
1.10 HeartBeat ............................................................................................................................ 14
1.11 Message Formatters ........................................................................................................... 15
1.12 TCMonitor............................................................................................................................ 19
1.13 Telnet Deamon .................................................................................................................... 20
1.14 Tracing Functionality ........................................................................................................... 21
1.14.1 Log4j SMTP Appender .................................................................................................... 21
1.14.2 Log4j JDBC Appender ..................................................................................................... 22
1.14.3 Log4j JMX Notification Appender .................................................................................... 23
1.14.4 Log4j Event Service Appender ........................................................................................ 23
1.14.5 MDC fields ....................................................................................................................... 23
1.15 Migrating from 1.3 to 1.4 Version ........................................................................................ 24
1.16 Technical errors from T24 ................................................................................................... 24
1.16.1 OFSERROR_PROCESS................................................................................................. 24
1.16.2 OFSERROR_TIMEOUT .................................................................................................. 24
1.16.3 General considerations.................................................................................................... 25
1.17 Troubleshooting................................................................................................................... 25

TEMENOS Page 2 of 28 May 2005

Temenos Connector Installation and Administration Guide

1.1 Introduction
The TCServer (java version) is a product which lets an external client program to link to the standard
TEMENOS GLOBUS module OFS (Open Financial Services). The TCServer offers different way to
connect to TEMENOS GLOBUS and T24, like MQSeries ,TCP, SSL,... Used in conjunction with the
TCClient API (Available in java and C++, and offering a COM (Component Object Modeling) layout, it
has never been easier to connect to TEMENOS GLOBUS and T24. This document will explain how to
install the TCServer (java) and will details how to configure it.

1.2 What’s new

The TCServer has been updated in version 1.4:

– to support new TC Security Service. TC Security Service offers the possibility to authenticate and
impersonate T24 user with Corporate user. This service could be configure to integrate an access
to the corporate Directory Server(LDAP). OFS Adapter used tSS INFO BASIC program to call T24
backend.
– Logging facility has been touch to facilitate integration with new release 1.3 log4j release in beta
version today. We developed some new log4j appender.
– Some improvement on JMX plugins management
For bug fixing please, check the release notes.
To deploy and configure TC Security Service please refer to TC14-install-security-service-guide.

1.3 Prerequisites
The java TCServer has been developed on top of TEMENOS GLOBUS & T24 for jBASE. The java
TCServer supports TEMENOS GLOBUS 12.1 onwards and T24.
TEMENOS GLOBUS releases prior than the 13.1, need the installation of some additional subroutines
in order for the TCServer to run correctly.
These subroutines are:
- GLOBUS.INITIALISE
- GET.ENV.JBASE
- OFS.INITIALISE.SOURCE
- tSS

If you are not sure whether these subroutine are already deployed or not, type:
$ jshow <subroutine name>
If the result is a full path to a library, this means that your jBase can find this subroutine, otherwise,
contact your Temenos Representative to get the latest versions.

A java Virtual Machine (JRE) version 1.4.1 or above should be installed. To test it, type:
$ java –version. Note that some problems can occur depending the java VM and the platform.
Please refer to the Temenos HelpDesk in order to be sure that there is no known problems with some
specific VM.

TEMENOS Page 3 of 28 May 2005

Temenos Connector Installation and Administration Guide

The TCServer has been deployed and tested on the following platforms:

Windows 32, AIX, HP-UX, Solaris, Linux, OS390, AS400, True64.

As far as your server has a java VM, the TCServer should run properly.

1.4 Setup OFS

The module OFS Online (OO) needs to be installed in your TEMENOS GLOBUS account. Ask your
project manager if you are not sure this module is installed. Once sure, create an OFS.SOURCE
record as presented here :

SOURCE.NAME....... TCS
-------------------------------------------------------
1 DESCRIPTION....... OFS ONLINE MODE
2 SOURCE.TYPE....... TELNET
3. 1 LOGIN.ID....... any
4. 1 EB.PHANT.ID....
5 MAX.CONNECTIONS... 11
6 RESTRICT.LINK.....
7 INITIAL.ROUTINE...
8 CLOSE.ROUTINE.....
9 IN.MSG.RTN........
10 OUT.MSG.RTN.......
11 MSG.PRE.RTN.......
12 MSG.POST.RTN......
13 LOG.FILE.DIR......
14 LOG.DETAIL.LEVEL.. NONE
15 OFFLINE.QUEUE.....
16 MAINT.MSG.DETS....
17 DET.PREFIX........
18 IN.QUEUE.DIR......
19 IN.QUEUE.NAME.....
20 OUT.QUEUE.DIR.....
21 OUT.QUEUE.NAME....
22 QUEUE.INIT.RTN....
23 QUEUE.CLOSE.RTN...
24 SYNTAX.TYPE....... OFS
25. 1 LOCAL.REF......
26 GENERIC.USER...... INPUTTER
27 IN.DIR.RTN........
28 VERSION...........
29 IB.USER.CHECK.....
30 EOD.VALIDATE......
31 FIELD.VAL.........
32. 1 ATTRIBUTES.....
33 RESERVED1.........
34. 1 OVERRIDE.......
35 RECORD.STATUS.....
36 CURR.NO........... 16

TEMENOS Page 4 of 28 May 2005

Temenos Connector Installation and Administration Guide

37. 1 INPUTTER....... 0_AUBERT1

38. 1 DATE.TIME...... 07 NOV 02 07:29
39 AUTHORISER........ 0_AUBERT1
40 CO.CODE........... GB-001-0001
41 DEPT.CODE......... 1
42 AUDITOR.CODE......
43 AUDIT.DATE.TIME...

To have more details about setting up OFS, please refer to the Chapter 43 of the TEMENOS
GLOBUS Help. The field 2 (SOURCE.TYPE) is set to “TELNET”. However, the TCServer is not using
telnet at all ! This is to specify that we will have online (and not batch) data coming.

1.5 Testing OFS

You can now test if GLOBUS is ready to be accessed by the TCServer.

To do so, just type:

$ tSS TCS

“TCS” is the Record ID of the table OFS.SOURCE.

An alternative way is to make sure you have an environment variable called OFS_SOURCE set up to
the value of the Record ID of the table OFS.SOURCE (in our example : “TCS”)

$ export OFS_SOURCE=TCS

(or “set OFS_SOURCE=TCS” for windows …)

then type:
$ tSS

you should see something like this :

<tSS version="1.0"><t24version>G15.0.02</t24version><t24ofssource>TCS</t24ofssource></tSS>

Type anything at the prompt: e.g. “hello world”

The answer should be:
NO SIGN ON NAME SUPPLIED DURING SIGN ON PROCESS
You also can type a real enquiry like this :
ENQUIRY.SELECT,,<globus_user_id>/<password>,<enquiry_name>

So far, so good, you are ready to deploy the TCServer. To quit the test type: “exit”

TEMENOS Page 5 of 28 May 2005

Temenos Connector Installation and Administration Guide

1.6 Installing TCServer.jar and dependencies

If you received a jar File and a Setup.sh (or Setup.bat), just copy these files wherever you want, and
execute the script. You will be prompted to enter the path where you want to install the TCServer, the
Path where TEMENOS GLOBUS is (xxx.run), the Path where you version of jBASE is and the
OFS.SOURCE record ID you want to use. Note that this setup is only deploying files in the install
directory. This means that you don’t need any special privileges to install it apart from write access to
this directory. For Windows, there is NOTHING going in the registry. If you want to uninstall, just
delete the whole directory !
However, if you wish to install the NT Service (in the ./bin path), you will need to have write access to
the Registry. The removeService.bat will remove any entry.

========================================================
. Welcome to the Installation program of the .
. TEMENOS Connector Server. .
. To successfully install your program, you will need .
. to provide 3 informations : .
. - The Path where you want to install it. .
. - The Path where your GLOBUS/T24 is (xxx.run) .
. - The Path where your jBASE is. .
. - An OFS.SOURCE Record ID .
========================================================

Press ENTER to continue.

Please enter the install Directory. (C:\Data\Installation\GCServer/gcserver)

C:\InstallTCS
'C:\InstallTCS' doesn't exist. Create ? y/n
y
Please enter the GLOBUS Directory (eg. /globus/demo/fbnk.run).
C:\globus\13101\mbdemo.run
Please enter the jBASE directory. (C:\jBase4.0.4.3)

Please enter the OFS.SOURCE record ID to use. (GCS)

. . .

Once installed, you will find 2 files (TCServer.bat and TCServer.sh) in your /bin directory. Just execute
it (.bat for windows, .sh for Unix/Linux) to start your server. On unix, you maybe wish to change the
right of this file.

TEMENOS Page 6 of 28 May 2005

 Temenos Connector Installation and Administration Guide

1.7 Environment variables

Environment Variables are no more set up in a script since version 1.2.0.04.

This simplify the deployment and avoid most of the issues.
If you look at the TCServer.sh (or TCServer.bat), you will see that there is nothing anymore.

java -jar ../lib/tcserver.jar

#
# To run it as a deamon, uncomment this line :
#
# nohup java -jar ../lib/tcserver.jar -d&

This doesn’t mean that we don’t have to care about the environment variables anymore. The fact is
that since we can connect to multiple TEMENOS GLOBUS, each of them running on the same or
different versions of jBASE, the environment variables are listed in the format VARNAME=VALUE in a
separate file.

1.7.1 File : environment.vars

This file is located in the /conf Directory. The file name is environment.vars. There is 2 different
supported format for this file. The default one has the tags <unix></unix><win32></win32>.
Depending the platform you are running on, the values listed in <unix> or <win32> will be used. The
second format contains only the “name-values” pair. This means that you can, if necessary, pipe the
result of an “env” (unix) or “set” (win32) to this file. Environment variables is the biggest cause of
trouble in the deployment. A safe (but not recommended) way is to make sure OFS is running (see
previous section), and then, from the same session, “piping” all environment in the “environment.vars”
file. Thus, you ensure that the GC will start OFS sessions exactly the same way you tested it.

Eg : env > ./conf/environment.vars

By default, this file contains “tags” like “<GLOBUSPATH>, <JBASEPATH>, … These tags are
substituted on the fly by the values specified in the tcserver.xml file. Even if you choose to “pipe” your
environment, you can always edit this file and add these special tags instead of having “hardcoded”
path.

TEMENOS Page 7 of 28 May 2005

Temenos Connector Installation and Administration Guide

By default, this file looks like this (environment.vars) :

#
# Please DO NOT edit this file !
# ********************************
# <JBASEPATH> : path where jBASE is installed
# <GLOBUSPATH> : path where GLOBUS is installed (.... \demo.run)
# <GCPATH> : path where the GC is installed
# <OFSSOURCE> : The record ID of the OFS.SOURCE table.

<unix>
JBCRELEASEDIR=<JBASEPATH>
JBCGLOBALDIR=<JBASEPATH>
JBCOBJECTLIST=<GLOBUSPATH>/globuspatchlib:<GLOBUSPATH>/globuslib:<GLOBUSPATH>/lib
LD_LIBRARY_PATH=<JBASEPATH>/lib:/usr/ccs/lib:/usr/lib
LIBPATH=<JBASEPATH>/lib:/usr/ccs/lib:/usr/lib
SHLIB_PATH=<JBASEPATH>/lib:/usr/ccs/lib:/usr/lib
JEDIFILEPATH=<GLOBUSPATH>
JBCLISTFILE=<GLOBUSPATH>/&SAVEDLISTS&
JBCSPOOLERDIR=/usr/jspooler
JEDIFILENAME_MD=VOC
JEDIFILENAME_SYSTEM=<GLOBUSPATH>/SYSTEM
PATH=<JBASEPATH>/bin:/usr/local/bin:<GLOBUSPATH>/globuspatchbin:
<GLOBUSPATH>/globusbin:<GLOBUSPATH>/bin
JBCBASETMP=<GLOBUSPATH>/workfile/tmp_$$
JBCEMULATE=prime
JBASE_WARNLEVEL=30
JBASE_INHIBIT_ZERO_USED=1
JEDIENABLEQ2Q=1
JBASE_CODEPAGE=utf8
JBASE_I18N=1
OFS_SOURCE=<OFSSOURCE>
</unix>

<win32>
JBCRELEASEDIR=<JBASEPATH>
JBCGLOBALDIR=<JBASEPATH>
JBCOBJECTLIST=<GLOBUSPATH>\globuspatchlib;<GLOBUSPATH>\globuslib;<GLOBUSPATH>\lib
JEDIFILEPATH=<GLOBUSPATH>\
JBCLISTFILE=<GLOBUSPATH>\&SAVEDLISTS&
JBCSPOOLERDIR=<JBASEPATH>\jspooler
JEDIFILENAME_MD=VOC
JEDIFILENAME_SYSTEM=<JBASEPATH>\src\SYSTEM
PATH=<JBASEPATH>\bin;<GLOBUSPATH>\globuspatchbin;<GLOBUSPATH>\globusbin;
<GLOBUSPATH>\bin
JBCBASETMP=<GLOBUSPATH>\tmp_workfile
JBCEMULATE=prime
JBASE_WARNLEVEL=30
JBASE_INHIBIT_ZERO_USED=1
JEDIENABLEQ2Q=1
JBASE_CODEPAGE=utf8
JBASE_I18N=1
OFS_SOURCE=<OFSSOURCE>
</win32>

TEMENOS Page 8 of 28 May 2005

Temenos Connector Installation and Administration Guide

1.7.2 The safest way : run .profile

If you are running only one instance of T24/jBASE per TCServer, the safest way is to not use
environment.vars, but to start the TCServer AFTER having set the different environment variables
(running . ./.profile in xxx.run). The procedure is quite simple :
a) Rename (or remove the file environment.vars)
b) Go to your T24 run directory (xxx.run) and start .profile (. ./.profile)
c) Do not start Globus, and DO NOT start jShell (jsh). You maybe will need to prompt “START
JSH Y/N”
d) Cd to the bin directory of the TCServer
e) Run TCServer.sh (. TCServer.sh)

In that situation, you GARANTY that the sessions spawned by the TCServer are running exactelly as if
you where typing yourself the TSS command. (See chapter “Testing OFS”)

TEMENOS Page 9 of 28 May 2005

Temenos Connector Installation and Administration Guide

1.8 Configuration : tcserver.xml

In this chapter, we will concentrate on one file: tcserver.xml. This file contains all the configuration
parameters of the TCServer. This is certainly the only file you will have to concentrate on. So read this
chapter carefully ! This file is located in the ./conf directory. Since the version 1.2.04, this file changed
completely to be compliant with a schema definition allowing a pre-validation and the auto-defaulting
for some specific tags.

The structure of this file looks like this :

<TCSERVER>

<MESSAGEFORMATTERS>
. . . MESSAGEFORMATTERS are used to format
</MESSAGEFORMATTERS> (change) the requests and / or the responses.

<ADAPTERS>
. . . ADAPTERS are defining how to connect to
. . . T24 / TEMENOS GLOBUS. You can specify
</ADAPTERS> the link to the message formatters here.

<LISTENERS>
. . . The LISTENERS are defining how the External
</LISTENERS> world will connect to the TCServer (W.
MQSeries, TCP, SSL, …..).
</TCSERVER>

As LISTENERS and FORMATTERS are “plug-ins” (see “Guide for writing a plugin.pdf”), we will not
give the details of these 2 blocks here. Instead, you will find documents called “PI-<plugin_name>.pdf”
in the /doc directory explaining separately how to configure the different plug-ins.

To add configuration about TC Security Service please refer to TC14-installation-SecurityService-

guide.

TEMENOS Page 10 of 28 May 2005

Temenos Connector Installation and Administration Guide

The following section shows a complete tcserver.xml :

<TCSERVER>

<!-- JMXRmiPort is the port the TCServer will use to comunicate with the JMX TCManager.
Optional -->
<JMXRmiPort>1099</JMXRmiPort>
<!-- MONITOR_PORT is the port the TCServer will listen on for the TCMonitor. Optional, but
recommended. -->
<MONITOR_PORT> 9500 </MONITOR_PORT>
<!-- TELNETD_PORT is the port the TCServer will listener on for the telnet deamon. Optional --
>
<TELNETD_PORT> 9501 </TELNETD_PORT>
<!-- DEBUGGER_PORT is the port the TCServer will listener on for the remote debugger. If you
telnet on that port, and you send a request FROM THE SAME CLIENT and you basic program enter
the debugger, any debugger input / output will be redirected to your telnet session. -->
<DEBUGGER_PORT> 9502 </DEBUGGER_PORT>
<!-- SPY_PORT is the same principal than the DEBUGGER, but for ALL Input / Output. -->
<SPY_PORT> 9503 </SPY_PORT>
<!-- The STACKEXPIRATION defines how long the TCServer will keep a response in the stack
before removing it. It can happen in an asynchronous communication, if the client don’t come
to fetch the response. -->
<STACKEXPIRATION>120</STACKEXPIRATION>
<!-- SCALEDOWNSPEED defines the speed the TCServer will scale down the Sessions. For example,
if there is suddenly a lot of requests to be processed, the TCServer will scale up to a
maximum of session (See Adapter definition). Then, once there is no more request, it will
slowly remove session after session. This value defines the frequence for removing the session
(in secondes) -->
<SCALEDOWNSPEED>30</SCALEDOWNSPEED>
<!-- If a message is encrypted with the library encryption.jar (DES III), the TCServer can
detect it an decrypt / encrypt the message on the fly. This tag defines where the encryption
key is. -->
<ENCRYPTION_KEY>key</ENCRYPTION_KEY>

<!-- The HEARTBEAT block contains information for the TCServer to send a specific message to
the T24 Session on a Regular basis. The message to send can be defined, same for the expected
response. If the response received doesn’t match the expected one (following the pattern :
“does the response START with the expected answer”, an error is logged. The FREQUENCY tag
indicates (in secs) how often each adapter thread should send a Heartbeat message. Note that
this functionality has absolutally no priority on any messages. This means that if there are
messages to process, even if the periode for sending a Heartbeat message has been reached, it
wont. -->
<HEARTBEAT>
<FREQUENCY>30</FREQUENCY>
<MESSAGE>XXX</MESSAGE>
<EXPECTED_ANSWER>EB.RTN.APP.MISS.2</EXPECTED_ANSWER>
</HEARTBEAT>

TEMENOS Page 11 of 28 May 2005

Temenos Connector Installation and Administration Guide

<!-- This session lists all the formatters. -->

<MESSAGEFORMATTERS>
<MESSAGEFORMATTER id="PrefixAppender">
<CLASS>com.temenos.formatter.PrefixAppender</CLASS>
<PREFIX>SWIFT.PROCESS.INCOMING,,SWIFTINCOMING/123456,,</PREFIX>
</MESSAGEFORMATTER>

<MESSAGEFORMATTER id="PrefixAppender.2">
<CLASS>com.temenos.formatter.PrefixAppender</CLASS>
<PREFIX>This is the response :</PREFIX>
</MESSAGEFORMATTER>
</MESSAGEFORMATTERS>

<!-- This session lists all the Adapter. Each adapter is a plug-in, thus described in it’s own
documents. However, all adapters have few common tags. There are described here.-->
<ADAPTERS>
<!-- Each adapter must have a unique id. This id will be defined in the listener to know how
to process the incoming message. The type must be compliant with the type of the plugin (see
specific documentation). The default value of the tape is “OFS” -->
<ADAPTER id="T24" type=”OFS”>

<!-- This tag lists all the formatters the message must go through before beeing send to the
adapter itself. Each formatter (if many) must be separated by a coma (“,”) eg : “Cp838toUTF8,
OFSML, UTF8ToCp838”. UTF( is a “build-in” formatter, and there is no need to specify it (the
TCServer will detect if the message is in OFSML) unless you want the formatting to occurs in a
specific sequence. -->
<REQUEST_FORMATTER>PrefixAppender</REQUEST_FORMATTER>
<!-- Same formatter processing for the response. -->
<RESPONSE_FORMATTER>PrefixAppender.2</RESPONSE_FORMATTER>
<!-- Maximum of session to “spawn” -->
<MAX_SESSION> 5 </MAX_SESSION>
<!-- Minimum of session to “spawn”. This is the initial value when you start your TCServer. -
->
<MIN_SESSION> 1 </MIN_SESSION>
<!-- The remaining is dependent of the adapter definition. Please refer to the specific
document (Starting with “PI-“ -->
<TIMEOUT>30</TIMEOUT>
<STARTIN>C:\globus\14000\mbdemo.run</STARTIN>
<JBASEPATH>C:\jbase4.1.3</JBASEPATH>
<PROGRAM>T24</PROGRAM>
<PARAMETER>GCS</PARAMETER>
</ADAPTER>
</ADAPTERS>

<LISTENERS>
<!-- Each listener have a unique id (can be “name”). The type must match the type of the plug-
in (see specific documentation). Active = “true or false” indicates if this listener must be
activated at startup or not. -->
<LISTENER id="Browser.1" type="tcp" active="true">
<!-- Must be an existing adapter (defined in the previous section). Note that is an adapter
has no listener associated, it will simply not start. -->
<ADAPTERID>T24</ADAPTERID>
<!-- The remaining is dependent of the listener definition. Please refer to the specific
document (Starting with “PI-“ -->
<PORT> 7001 </PORT>
</LISTENER>
</LISTENERS>
</TCSERVER>

TEMENOS Page 12 of 28 May 2005

Temenos Connector Installation and Administration Guide

1.9 Configuration with TCSConfig

The tcserver.xml file can also be edited with a graphical utility. With this utility, you can edit a local
tcserver.xml file or a distant one. In the case of a distant file, you must have the TC Server running on
the distant machine and the JMX-RMI enabled. All you need to provide is a host name or address and
the "JMXRmiPort" of the distant machine.
The image below, show the TCSConfig main window. With this utility you can edit, delete, copy paste
all the TC Server configuration objects without manipulating an XML tag.

TEMENOS Page 13 of 28 May 2005

Temenos Connector Installation and Administration Guide

1.10 HeartBeat
As described in the previous chapter, there is the possibility to set a Heartbeat facility for the
TCServer. This function will send on a regular basis a request to the adapter (only if inactive) and will
evt. Log an error if the result doesn’t match the expected one. By making a Heartbeat request which
uses the T24 Database (like a simple enquiry), it will allow the TCServer to log an exception if the
database becomes unavailable …
There is also the possibility to query the TCServer to get all the Heartbeat informations.
By sending the request “HEARTBEAT” (upper case), the TCServer will interrupt it and send the actual
result of all the heartbeat messages, grouped by adapters, like this :

<HeartBeat>
<Adapter name="T24">
<Session nb="1">
<StartTime>2004-12-07 15:08:50.818</StartTime>
<LastHitTime>2004-12-07 15:16:40.934</LastHitTime>
<NbHit>2</NbHit>
<TotalUsage>220</TotalUsage>
<LastHeartBeatHost>2004-12-07 15:16:36.137</LastHeartBeatHost>
<HeartBeatHost>OK</HeartBeatHost>
</Session>
</Adapter>
</HeartBeat>

The request “HEARTBEAT” is not compliant with OFS, so the TCServer will also recognize such a
request :
“HEARTBEAT,,./.,,” which is compliant with the OFS specifications.
If you want to ask for the Heartbeat via OFSML, the request will look like this :
<?xml version="1.0" encoding="UTF-8"?>
<Globus xmlns="http://www.temenos.com/GLOBUS/OFSML/120"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.temenos.com/GLOBUS/OFSML/120 ../../xsd/ofsml.xsd">
<ofsmlHeader>
<correlationId>001100110011</correlationId>
</ofsmlHeader>
<serviceRequest>
<securityContext>
<userName>.</userName>
<password>.</password>
</securityContext>
<ofsXMLRoutine name="HEARTBEAT">
<HEARTBEAT xmlns = "http://www.temenos.com/GLOBUS/OFSML/120/heartbeat"
xsi:schemaLocation = "http://www.temenos.com/GLOBUS/OFSML/120/heartbeat
../xsd/heartbeat.xsd"/>
</ofsXMLRoutine>
</serviceRequest>
</Globus>

TEMENOS Page 14 of 28 May 2005

Temenos Connector Installation and Administration Guide

1.11 Message Formatters

Message Formatters are classes you can write on your own which will format any Request/Response
before/after having send it to T24. A message formatter can be very useful in charset conversion or
interfaces. For example, this would be very useful to write a custom Listener, and 2 message
formatters (on for requests and one for responses) to make ANY type of online interface (ATM) !
A “MessageFormatter” is a class extending com.temenos.formatter.Formatter.
This class is in the jar “messageformatter.jar”
Formatter has one abstract method:

public abstract byte[] format(byte[] request, byte[] response);

If your formatter is a REQUEST formatter, response will be null. Whatever you will return back will
replace the request.
If your class is a RESPONSE formatter, both the original request and the response will be passed.
The response will be replaced by whatever you will return back.

Here is a sample class which is supposed to convert CRLF to VM (253):

package com.temenos.formatter;

import com.temenos.messageformatter.*;
import java.io.*;

public class CRLFtoVM extends Formatter {

private static final byte CR = 13;

private static final byte LF = 10;
private static final byte VM = (byte) 253;

public byte[] format(byte[] request, byte[] response) {

if (request != null) {
ByteArrayOutputStream baos = new ByteArrayOutputStream();
int nRealLength = request.length;
int nFakeLength = nRealLength - 1;
int i = 0;
while(i < nRealLength){
if ((request[i] == CR) && ((i < nFakeLength) && (request[i + 1] == LF))) {

baos.write(VM);
i++;
} else {

baos.write(request[i]);
}

TEMENOS Page 15 of 28 May 2005

Temenos Connector Installation and Administration Guide

In addition, you can know, from your formatter, where the request is coming from, and what adapter is
calling you. This can be done using the class Formatter (super…) like this :

String sAdapter = super.getAdapterID();

String sListener = super.getListenerID();

You also can get any custom parameter (Tags) like this :

If your definition looks like this :

<MESSAGEFORMATTER id="MY_FORMATTER">
<CLASS>com.temenos.formatter.TestFormatter</CLASS>
<MYPARAM>Hello World</MYPARAM>
</MESSAGEFORMATTER>

You can retrieve the value of the tag <MYPARAM> like this :
String sParam = super.getParam(“MYPARAM”);

You also can decide to cancel this call. This means that the request will not (!) be sent to
T24/GLOBUS. In that scenario, if you defined a RESPONSE formatter, it will be invoked with a null
response …. Remember that you can override this response by just returning anything you want from
the method format().
super.setCancelCall(true);

In order that the TCServer finds your classes, they need to be deployed in the directory “ext”. For
example, our previous sample (CRLFtoVM.class) needs to be located in
<tcserver_install_path>/ext/com/temenos/formatter (“com/temenos/formatter” is the package name).

If you don’t want to deploy it in that directory, or if you made a jar file, you will need to add this jar in
the classpath.

This is possible to specify multiple formatters. In that case, you just separate them with a coma (“,”) in
the specific ADAPTER like this :

<ADAPTER id="13101">
<REQUEST_FORMATTER> CP838_TO_UTF8, OFSML, UTF8_TO_CP838 </REQUEST_FORMATTER>
<RESPONSE_FORMATTER> CP838_TO_UTF8, OFSML, UTF8_TO_CP838</RESPONSE_FORMATTER>
<MAX_SESSION> 1 </MAX_SESSION>
<MIN_SESSION> 1 </MIN_SESSION>
<OFSTIMEOUT>30</OFSTIMEOUT>
<GLOBUSPATH>c:\globus\13101\mbdemo.run</GLOBUSPATH>
<JBASEPATH>C:\jBase4.0.4.3</JBASEPATH>
<OFSENTRY>TSS</OFSENTRY>
<OFSSOURCE>GCS</OFSSOURCE>
</ADAPTER>

TEMENOS Page 16 of 28 May 2005

Temenos Connector Installation and Administration Guide

As you can see in the above example, we are “chaining” different formatters. The formatter “OFSML”
is a special one, and doesn’t need any definition in the <MESSAGEFORMATTERS> tag. This
formatter will convert OFSML to OFS for the request, and OFS to OFSML for the answer.

Here is the MESSAGEFORMATTERS block for the given example :

<MESSAGEFORMATTERS>
<MESSAGEFORMATTER id="CP838_TO_UTF8">
<CLASS>com.temenos.formatter.CP838TOUTF8</CLASS>
</MESSAGEFORMATTER>
<MESSAGEFORMATTER id="UTF8_TO_CP838">
<CLASS>com.temenos.formatter.UTF8TOCP838</CLASS>
</MESSAGEFORMATTER>
</MESSAGEFORMATTERS>

Of course, this is assuming that the class CP838TOUTF8.class and UTF8TOCP838.class are in the
directory <tcserver>/ext/com/temenos/formatter/.
This example assume that the incoming message is encoded in CP838. Because the OFSML parser
doesn’t support this charset, we say to the ADAPTER to :
1) Convert the message in UTF8
2) Parse the message (assuming this is OFSML)
3) Convert it back in Cp838 before sending it to T24.

On the way back (the answer), we do the same.

Here is the code (as example) for CP838TOUTF8.class :
package com.temenos.formatter;

import com.temenos.messageformatter.*;

public class CP838TOUTF8 extends Formatter{

public byte[] format(byte[] request, byte[] response) {

if (response == null){
return format(request);
}else{
return format(response);
}
}

private byte[] format(byte[] orig){

try{
return new String(orig, "Cp838").getBytes("UTF-8");
}catch(Exception e){
e.printStackTrace();
return null;
}
}
}

TEMENOS Page 17 of 28 May 2005

Temenos Connector Installation and Administration Guide

This would be much more convenient to use the getParam() method for this situation. Here is another
sample MessageFormatter which format the message from any charset to another :
package com.temenos.formatter;

import com.temenos.messageformatter.*;

public class CharsetConverter extends Formatter{

public byte[] format(byte[] request, byte[] response) {
if (response == null){
return format(request);
}else{
return format(response);
}
}
private byte[] format(byte[] orig){
String sFrom = null;
String sTo = null;
byte[] bResult = null;
try{
sFrom = super.getParam("CHARSET_IN");
sTo = super.getParam("CHARSET_OUT");

if (sFrom != null && !sFrom.equalsIgnoreCase("")){

if (sTo != null && !sTo.equalsIgnoreCase("")){
bResult = new String(orig, sFrom).getBytes(sTo);
}else{
bResult = new String(orig, sFrom).getBytes();
}
}else{
if (sTo != null && !sTo.equalsIgnoreCase("")){
bResult = new String(orig).getBytes(sTo);
}else{
bResult = orig;
}
}
return bResult;
}catch(Exception e){
System.out.println("Failed to convert from '" + sFrom + "' to '" + sTo + "'");
return null;
}
}
}

The definition of this formatter would look like this :

<MESSAGEFORMATTER id="KSC5601TOUTF8">
<CLASS>com.temenos.formatter.CharsetConverter</CLASS>
<CHARSET_IN>KSC5601</CHARSET_IN>
<CHARSET_OUT>UTF-8</CHARSET_OUT>
</MESSAGEFORMATTER>

TEMENOS Page 18 of 28 May 2005

Temenos Connector Installation and Administration Guide

1.12 TCMonitor

The TC Monitor is a monitoring tool allowing to remotely connect to any TCServer.

You can have multiple monitors. You also can stop the server, check the actives channels, reset the
statistics data, ... There is no installation required. Just copy the tcmonitor.jar anywhere, and start it
with the script in your install directory or by just typing “java -jar tcmonitor.jar”.
The tcmonitor.jar file is in the lib directory of your installation path.
By default, the TCMonitor will try to connect to a server on « localhost », on port 9500.
To connect to another server, just use the menu “File”, “Connect to …”. You specify a server by
<ip_address_or_machine_name>:<tcp_port>. The tcp_port is optional. The default value is 9500. You
can change the port the TCServer is listening on by changing the tag <MONITOR_PORT> in the
tcserver.xml file (check the previous chapter). If you choose to not specify anything in the
<MONITOR_PORT>, the TCServer will simply not listen on any port.

TEMENOS Page 19 of 28 May 2005

 Temenos Connector Installation and Administration Guide

1.13 Telnet Deamon

You have the possibility to manage your server via telnet. To do so, just telnet your machine with the
correct port number. You can change the port the TCServer is listening on by changing the tag
<TELNETD_PORT> in the jTCServer.xml file (check the previous chapter). If you choosed to not
specify anything in the <TELNETD_PORT>, the TCServer will simply not start the telnet Deamon.

Eg : telnet localhost 9501

The result will look like this :

------------------------------------------------------------------------
GCServer Telnet Deamon V. 1.0
------------------------------------------------------------------------

Avg. response Time : 125 ms.

Nb Session in Use : 0
Total Transaction : 4
Last : Wed Jan 22 13:14:22 CET 2003

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

1) stop server Close all Session and Stop Server.

2) reset Stop all Listeners, reload the config, restart
3) adapter list Return the List of Adapters
4) listener list Return the List of Listeners
5) stop listener... Stop a listener
6) start listener... Start a listener
7) reload config Reload the configuration file jgcserver.xml
8) reset data Reset the statistices data.
x) disconnect Quit this telnet Session

Please choose a value : [ ]

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

TEMENOS Page 20 of 28 May 2005

Temenos Connector Installation and Administration Guide

1.14 Tracing Functionality

The TCServer uses the log4j tracing API. This API is well described on the log4j website
(http://jakarta.apache.org/log4j).
The configuration file we are using for the tracing is tcslog.properties (in the conf directory). The
tracing level should be set to “ERROR” once everything’s up and running. During the deployment
phase, the “DEBUG” or “ALL” level are the suggested one. (see the “troubleshooting chapter”).

Remarks: With the TCServer 1.4 version, Category is replaced by Logger in properties files.

In TC 1.4 distribution, you will find tlog4jappenders jars with three new Temenos log4j appender.

1.14.1 Log4j SMTP Appender

This appender offer the functionality to send the message by mail. The example enclosed in the
"tcslog.properties" show the specific properties for this appender. Theses properties are:

SeverityFilter Overrides the tracing level of the main section

SMTPHost Mail server host name or ip address
SMTPPort The SMTP server port (default is 25)
SMTPTimeout The SMTP communication timeout in milliseconds
(default is 180000)
UseSSL Use SSL encryption to communicate with the SMTP server
(true or false default is false)
To List of recipient mail addresses separated by semi-colons.
From Sender mail address
Subject The mail subject (optional)
Header The mail header (optional)
SMTPLogin The mail server login (if required by the mail server)
SMTPPassword The mail server password (if required by the mail server)
DropIfError Drop the message in case of error (server unreachable) if set to true
or persist the message and send it when the server is available again
if set to false. The default value is true.

TEMENOS Page 21 of 28 May 2005

Temenos Connector Installation and Administration Guide

1.14.2 Log4j JDBC Appender

With this appender you can store the message in a SQL database. This appender does not require a
layout information, because the structure of the table is pre-defined (this allows to generate the table if
the table does not exist). The properties for this appender are :

SeverityFilter Overrides the tracing level of the main section

ConnectionString The connection to access the database
Driver The driver used to connect the database
DriverPath The path to the driver file
TypeINT The name of the integer type for this database. Default is the
database type defined for the java.sql.Types.INTEGER.
TypeBIGINT The name of the "big integer" type for this database. Default is the
database type defined for the java.sql.Types.BIGINT.
TypeVARCHAR The name of the varchar type for this database. Default is the
database type defined for the java.sql.Types.VARCHAR.
TypeTIMESTAMP The name of the time stamp type for this database. Default is the
database type defined for the java.sql.Types.TIMESTAMP.
TypeBLOB The name of the blob type for this database. Default is the database
type defined for the java.sql.Types.BLOB.

User The database user name

Password The database password
Table The table name
OverwriteTable true or false. If set to true, the table is created if it does not exist.
DropIfError Drop the message in case of error (database unreachable) if set to
true or persist the message and send it when the database is
available again if set to false. The default value is true.

TEMENOS Page 22 of 28 May 2005

Temenos Connector Installation and Administration Guide

1.14.3 Log4j JMX Notification Appender

This appender sends the message to a registred MBean server (as a JMX notification). This appender
does not require a layout information because the structure of the message is pre-defined. The
properties for this appender are :

SeverityFilter Overrides the tracing level of the main section

TypePrefix Prefix to use as a "message type" (if not provided, the class name is
used)
AppendSeverityToType Append the log4j severity code to the message type (true/false)
DropIfError Drop the message in case of error (database unreachable) if set to
true or persist the message and send it when the database is
available again if set to false. The default value is true.

1.14.4 Log4j Event Service Appender

This appender acts as an event service publisher ( send the message to an event server ). This
appender does not require a layout information because the structure of the message is pre-defined.
The properties for this appender are :

SeverityFilter Overrides the tracing level of the main section.

ServerName The event service server name or IP address.
CmdPortNo The event server command port number.
PortNo The event server communication port number.
AppID The application ID (numeric).
DropIfError Drop the message in case of error (event server unreachable) if set to true or
persist the message and send it when the event server is available again if
set to false. The default value is true.

1.14.5 MDC fields

The TCServer will use some specific log4j fields for the Tracing. These fields are:
“CorrelationID”, “ErrorCode” and “ErrorDescription”
Of course, ErrorCode and ErrorDescription are set for Errors only. The CorrelationID is set
whenever available (Always apart on startup and termination). For Special HeartBeat messages,
the CorrelationID is hardcoded to "00000000hb"

TEMENOS Page 23 of 28 May 2005

Temenos Connector Installation and Administration Guide

1.15 Migrating from 1.3 to 1.4 Version

We recommend to install The TCServer 1.4 in a new directory and copy your TCServer 1.3
configuration file (TCServer.xml by default) in the new conf directory.

Remark: log.properties file must not copied to 1.4 version from 1.3. We don’t support old Category
Log4j object.

1.16 Technical errors from T24

Recall that the TCServer is designed to ALWAYS return an answer. Whatever goes wrong down the
line, each request will have an answer.
There can be 2 types of technical errors coming from T24, and shown in the TCServer.

1) An OFSERROR_PROCESS.
2) An OFSERROR_TIMEOUT.

1.16.1 OFSERROR_PROCESS
This error is due to the process being spawned by the TCServer (tSS) to terminate unexpectedly. In
that situation, the TCServer will detect it and return the message “OFSERROR_PROCESS”. This error
will also being return if the process enter the debugger. However, if you have a debugger session
attached to your request, the pipes will be redirected to your debugger client. If you make a “continue”
(“C”) on the debugger, the process will continue as normal. If you make a “quit” (“Q”), then the process
will die, and the TCServer will return an “OFSERROR_PROCESS”. On platforms having a TTY (UNIX,
LINUX but not Win32, AS400), this is important to set the environment variable JBASE_DEBUG_PIPE
to “1”. Otherwise, if a process enters the debugger, the debugger will be redirected to the TTY instead
of STDOUT. In that case, the TCServer will never detect it and will timeout.

1.16.2 OFSERROR_TIMEOUT
In the settings of your adapter (tcserver.xml), you specified a timeout value. This tells to the TCServer
after how many seconds it should stop waiting for an answer, and return an “OFSERROR_TIMEOUT”
message. This error can be found in many situation. This could be a “real” timeout. This means that
everything is fine, but too slow. The TCServer will give up waiting and kill the process and restart one
“fresh”.
This also could be that the process (tSS) got a problem (dead lock, entered accidentally to an
interactive mode (waiting for a user input, …).

TEMENOS Page 24 of 28 May 2005

Temenos Connector Installation and Administration Guide

1.16.3 General considerations

When running against a external database (Oracle, DB2, …), each process spawned by the TCServer
has one connection on the Database. If, for any reason, these connections are closed, this could
cause an OFSERROR_PROCESS message. However, the tcserver will detect it only when sending a
message to T24. The TSS process is still alive, even when the DB connection is dropped. This
situation can also occur if the jBase deamons (JPML, …) are stopped and restarted.

1.17 Troubleshooting

The only problems in the deployment of the java TC Server are due to
a) A bad configuration of OFS.
b) A bad starting Script (TCServer.sh or .bat)

This is important to verify if OFS is running correctly. Log on to your server, at the prompt Start
GLOBUS Y/N answer NO, and then just type “tSS GCS”. Note that “GCS” is the OFS.SOURCE record
ID you whish to use.
If you receive a message like :
<tSS verrsion="1.0"> <t24version>G15.0.02</t24version> <t24ofssource>GCS</t24ofssource> </tSS>
this means OFS is running. Type an enquiry in the OFS Format :

ENQUIRY.SELECT,,INPUTT7123456,CURRENCY-LIST

If you receive the result, everything’s fine.

TEMENOS Page 25 of 28 May 2005

Temenos Connector Installation and Administration Guide

Another way to verify that everything’s fine is to change the tcslog.properties file (in your conf
directory) to redirect the tracing to the console (instead of a file) and to activate all tracing.

Like this :
#####################################
# Technology & Research Dep.
# Log file configuration
#
# TEMENOS (c) 2003
#
# This file contains configuration
# parameters for the log4j logger.
#
# Log Level = OFF, FATAL, ERROR, WARN, INFO, DEBUG
#
# Note :The 'File' must have only slashes '/' and never backslashes '\'
#
#####################################

log4j.rootLogger=FALSE
log4j.logger.common=ALL, file,console
log4j.logger.tcs=ALL, file,console
log4j.logger.ofs=ALL, console
log4j.logger.tcp=ALL, file,console

By doing so, restart your server, and you will have plenty of messages …

TEMENOS Page 26 of 28 May 2005

Temenos Connector Installation and Administration Guide

===========================================================
java GCServer version 1.1.1

java VM Version : 1.4.0_02

user.dir : C:\testSetup11\Server
Current directory : /C:/testSetup11/Server/
For running it as a deamon (Unix) pass parameter -d
Type '?' for getting functions list.
===========================================================
log4j:WARN No such property [file] in org.apache.log4j.ConsoleAppender.
log4j:WARN No such property [maxFileSize] in org.apache.log4j.ConsoleAppender.
log4j:WARN No such property [maxBackupIndex] in org.apache.log4j.ConsoleAppender
.
log4j:WARN No such property [maxFileSize] in org.apache.log4j.ConsoleAppender.
log4j:WARN No such property [file] in org.apache.log4j.ConsoleAppender.
log4j:WARN No such property [maxBackupIndex] in org.apache.log4j.ConsoleAppender
.
Tracing Level : ALL
[2003-01-31 07:55:58,828] INFO gcs - javaVM : 1.4.0_02
[2003-01-31 07:55:58,828] INFO gcs - GCSServer started.
[2003-01-31 07:55:58,908] INFO gcs - GCServer : Authentication library loaded ?
: false
[2003-01-31 07:55:58,918] INFO gcs - GCServer : Starting Monitor Listener on po

First of all, don’t worry about the log4j warnings …. We should have remed-out all the line concerning
the FileAppender in the jgcslog.properties file.

Then concentrate on the highlighted lines : If you have it, you can be 100% sure your TCServer can
connect to GLOBUS and is up and running!
If you don’t have these lines, but you can make the precedent test (Typing TSS), this means that the
environment variables are wrong in the environment.vars.

If this is still not working, there is one more known cause : The version of your VM. Type java –
version. If your version is less than 1.3.1, this means that java cannot execute a binary in another
directory than the current one. In that situation you should upgrade your java VM. However, there is
the possibility to copy your entire install directory (the one where TCServer.sh is in your xxx.run
directory. Then, you duplicate (and rename) the script .profile (jProfile.bat), and add the java –jar
<currdir>\lib\TCServer.jar.

On OS390, you MUST be in the xxx.run directory when starting the tcserver. One way of doing is to
copy the TCServer.sh file in the xxx.run directory, and edit it to change the path to the tcserver.jar like
this :

TEMENOS Page 27 of 28 May 2005

Temenos Connector Installation and Administration Guide

“ java -jar <full_path_to_tcserver_lib_dir>/tcserver.jar”

TEMENOS Page 28 of 28 May 2005