TRM System Admin Guide

User Manual:

Open the PDF directly: View PDF .
Page Count: 256

Download
Open PDF In Browser	View PDF

www.wallstreetsystems.com

Wall Street Systems – Empowering Treasury Trade and Settlement

Wallstreet Suite
TRM
System Administration Guide
Version 7.3.14

Information in this document is subject to change without notice and does not represent a commitment on the part
of Wall Street Systems. The software and documentation, which includes information contained in any databases,
described in this document is furnished under a license agreement or nondisclosure agreement and may only be
used or copied in accordance with the terms of the agreement. It is against the law to copy the software or
documentation except as specially allowed in the license or nondisclosure agreement. No part of this publication
may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical,
photocopying, recording, or otherwise, without the prior written permission of Wall Street Systems.
Although Wall Street Systems has tested the software and reviewed the documentation, Wall Street Systems
makes herein no warranty or representation, either expressed or implied, with respect to software or
documentation, its quality, performance, marketability, or fitness for a particular purpose. As a result, this
software is provided "as is", and in no event will Wall Street Systems be liable for direct, indirect, special,
incidental, or consequential damages from any defect in the software or by virtue of providing this
documentation, even if advised of the possibility of such damages. The documentation may contain technical
inaccuracies and omissions.
The mention of an activity or instrument in this publication does not imply that all matters relating to that activity or
instrument are supported by Wallstreet Suite, nor does it imply that processing of or by that activity or instrument is
carried out in any particular way, even if such processing is customary in some or all parts of the industry.
The windows and screen images shown herein were obtained from prototypes during software development. The
actual windows and screen images in the software may differ.
© Copyright 2011 Wall Street Systems IPH AB. All rights reserved.
Second Edition (May 2011)
This edition applies to Wallstreet Suite version 7.3.14 and to all later releases and versions until indicated in new
editions or Wall Street Systems communications. Make sure you are using the latest edition for the release level of
the Wall Street Systems product.

Wall Street Systems, WSS, WALLSTREET, WALLSTREET SUITE and the Wall Street Systems logos are
trademarks of Wall Street Systems Delaware, Inc.
Finance KIT, Trema and Trema logo are trademarks of Wall Street Systems Sweden AB.
Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States
and/or other countries.
Adobe, Acrobat, and Acrobat Reader are either registered trademarks or trademarks of Adobe Systems
Incorporated in the United States and/or other countries.
All other products mentioned in this book may be trademarks or service marks of their respective companies or
organizations.
Company names, people names, and data used in examples are fictitious unless otherwise noted.

2

Contents

Preface ...........................................................................................................................15
Associated documents ................................................................................................................ 15

1 System processes .....................................................................................................17
1.1 TRM clients ............................................................................................................................ 17
1.1.1 Server processes ............................................................................................................ 17
1.1.2 Onyx ................................................................................................................................ 19
1.1.2.1 Starting Onyx ........................................................................................................ 19
1.1.2.2 Configuring property files ...................................................................................... 19
1.1.2.3 Configuring number of service instances ............................................................. 19
1.1.2.4 Onyx log files ........................................................................................................ 19
1.1.3 User processes ............................................................................................................... 19
1.2 Network bandwidth ............................................................................................................... 20

2 Managing server processes .....................................................................................21
2.1
2.2
2.3
2.4
2.5
2.6
2.7
2.8

omniNames ............................................................................................................................ 21
Onyx rate interface ................................................................................................................ 21
Automatic start of server processes ................................................................................... 21
mdsd ....................................................................................................................................... 22
transd ..................................................................................................................................... 22
micd ........................................................................................................................................ 23
reportd .................................................................................................................................... 23
Limit Server ........................................................................................................................... 23
2.8.1 Start-up script .................................................................................................................. 24
2.8.2 Applying periodic stop/loss limits .................................................................................... 24
2.8.3 Setting up the limit daemon ............................................................................................ 25
2.8.3.1 Standard setup ..................................................................................................... 28
2.8.3.2 Setup with frozen rates ......................................................................................... 28
2.8.4 Checking the limit daemon .............................................................................................. 28
2.9 activityd .................................................................................................................................. 28
2.10 tmd ........................................................................................................................................ 29
2.10.1 Configuring views and books for Treasury Monitor ....................................................... 29
2.11 Configuring Monitor page templates ................................................................................ 31
2.12 Deal mirroring module (DMM) ............................................................................................ 31

TRM System Administration Guide

3

3 Interfaces with other tools .......................................................................................33
3.1 Bloomberg Interface ............................................................................................................. 33
3.1.1 Environment variables .................................................................................................... 33
3.1.2 CSD possibility ................................................................................................................ 35
3.1.2.1 Entity script ........................................................................................................... 35
3.1.2.2 Value Mapping Editor script .................................................................................. 36
3.1.2.3 Security Mapping Set Editor ................................................................................. 36
3.1.3 Data License Prices activity process .............................................................................. 37
3.1.4 Two step activity processing ........................................................................................... 37
3.2 Reuters Dealing 3000 Link ................................................................................................... 38
3.2.1 Overview ......................................................................................................................... 38
3.2.2 Scripts ............................................................................................................................. 39
3.2.3 Log file ............................................................................................................................ 39
3.2.4 Implementation ............................................................................................................... 39
3.3 Value-at-Risk Interface ......................................................................................................... 39
3.3.1 Default VaR scenario ...................................................................................................... 39
3.3.2 VaR Mapping Types ....................................................................................................... 39
3.3.3 Default mapping .............................................................................................................. 40
3.3.4 Importing RiskMetrics data to TRM ................................................................................. 40
3.3.4.1 Fetching the risk files ............................................................................................ 40
3.3.4.2 Running the import script ...................................................................................... 40
3.3.5 Importing FEA data to TRM ............................................................................................ 41
3.3.6 VaR horizon .................................................................................................................... 42
3.3.7 Other scripts .................................................................................................................... 42
3.3.7.1 Fetching RM data via FTP .................................................................................... 42
3.3.7.2 Importing volatility and correlations routine .......................................................... 43
3.4 Prices import - Import Market Information Activity ........................................................... 44
3.4.1 Import process ................................................................................................................ 44
3.4.1.1 Import files list ....................................................................................................... 44
3.4.1.2 Validating the files ................................................................................................ 45
3.4.1.3 Parsing the files .................................................................................................... 45
3.4.2 Environment variables .................................................................................................... 46
3.4.3 Format of the import file .................................................................................................. 47
3.4.3.1 Query properties ................................................................................................... 47
3.4.3.2 Price data properties ............................................................................................ 47
3.4.3.3 Example imports ................................................................................................... 47
3.4.4 Permissions .................................................................................................................... 48
3.4.5 CSD possibilities ............................................................................................................. 48
3.4.6 Validation of Imported Prices .......................................................................................... 49
3.4.6.1 CSD validation ...................................................................................................... 49
3.5 Using comKIT ........................................................................................................................ 50
3.5.1 Overview ......................................................................................................................... 50
3.5.2 comKIT services ............................................................................................................. 50

4 Using Import Export tool ..........................................................................................53
4.1 Introduction ........................................................................................................................... 53
4

© Wall Street Systems IPH AB - Confidential

4.2 Features ................................................................................................................................. 53
4.3 Structure of the Import Export tool ..................................................................................... 53
4.3.1 File organization and inheritance .................................................................................... 54
4.4 Importing data ....................................................................................................................... 54
4.5 Definition file (.def) ................................................................................................................ 55
4.5.1 Templates ....................................................................................................................... 55
4.5.2 Layout syntax of the template ......................................................................................... 55
4.5.2.1 Header .................................................................................................................. 56
4.5.2.2 Body ..................................................................................................................... 56
4.5.2.3 Trailer ................................................................................................................... 56
4.5.2.4 Body template ....................................................................................................... 57
4.5.3 Variables ......................................................................................................................... 57
4.5.3.1 Definition of variables ........................................................................................... 58
4.5.3.2 Command line variables ....................................................................................... 58
4.5.3.3 Variables section in .def file .................................................................................. 58
4.5.3.4 Syntax of environment variables .......................................................................... 58
4.5.3.5 Built-in variables ................................................................................................... 59
4.5.4 Format ............................................................................................................................. 59
4.5.4.1 Data type definitions ............................................................................................. 60
4.5.4.2 Predefined data types ........................................................................................... 60
4.5.4.3 Format options of data types ................................................................................ 60
4.6 Perl functions (the Interface class) ..................................................................................... 62
4.6.1 Export hook functions ..................................................................................................... 62
4.6.1.1 Start functions ....................................................................................................... 62
4.6.1.2 Finish functions ..................................................................................................... 63
4.6.2 Import hook functions ...................................................................................................... 63
4.6.2.1 Start functions ....................................................................................................... 63
4.6.2.2 Finish functions ..................................................................................................... 63
4.6.3 Overriding default functions ............................................................................................ 63
4.7 External packages: predefined modules ............................................................................ 63
4.8 Running Import Export tool ................................................................................................. 64
4.8.1 Running from the command line ..................................................................................... 64
4.8.2 Methods of script execution ............................................................................................ 65
4.9 Debugging ............................................................................................................................. 65
4.10 Interface class ..................................................................................................................... 65
4.10.1 Interface class functions ............................................................................................... 66
4.10.2 Interface member functions .......................................................................................... 66
4.11 TemplateInterface class ..................................................................................................... 67
4.11.1 TemplateInterface class functions ................................................................................ 68
4.11.2 TemplateInterface member functions ........................................................................... 68
4.12 Empty sample files .............................................................................................................. 71
4.12.1 Definition file ................................................................................................................. 71
4.12.2 Empty Perl module ........................................................................................................ 72

5 Setting up message management ...........................................................................75
TRM System Administration Guide

5

5.1
5.2
5.3
5.4
5.5
5.6
5.7

Overview ................................................................................................................................ 75
Transaction and Entity flow ................................................................................................. 76
Message Manager and Message flow ................................................................................. 76
Examples of messages ......................................................................................................... 77
Setting up Message Manager ............................................................................................... 77
Previews ................................................................................................................................. 77
Extracting data ...................................................................................................................... 78
5.7.1 Expressions .................................................................................................................... 78
5.7.1.1 Single Field ........................................................................................................... 78
5.7.1.2 Result set (multiple fields) .................................................................................... 80
5.7.1.3 System functions .................................................................................................. 82
5.7.2 SQL code in stored procedures ...................................................................................... 83
5.7.3 Filters .............................................................................................................................. 83
5.8 Setting up Document Formatter .......................................................................................... 83
5.8.1 Prerequisites ................................................................................................................... 83
5.8.2 Settings ........................................................................................................................... 84
5.8.3 Authoring template documents ....................................................................................... 84
5.8.4 Saving Word 2007 XML files ........................................................................................... 86
5.8.5 Authoring common placeholders .................................................................................... 86
5.8.6 Including reusable text (subdocuments) ......................................................................... 86
5.8.6.1 Writing and uploading templates .......................................................................... 86
5.8.6.2 Defining the expressions ...................................................................................... 88
5.8.7 Customizing the e-mail body ........................................................................................... 88
5.8.8 Customizing rounding numbers and amounts ................................................................ 89
5.9 Message transfer ................................................................................................................... 89
5.9.1 E-mail example ............................................................................................................... 90
5.9.2 Fax example 1 ................................................................................................................ 90
5.9.3 Fax example 2 ................................................................................................................ 91
5.9.4 Printer example ............................................................................................................... 91
5.10 Possible problems and solutions ...................................................................................... 92
5.10.1 Developing test cases ................................................................................................... 92
5.10.2 Previewing transactions ................................................................................................ 92
5.10.3 Test script for previewing transactions .......................................................................... 93
5.10.4 CORBA error when previewing ..................................................................................... 93
5.10.5 E-mail problems on windows ........................................................................................ 93
5.10.6 Error evaluating 'Source.field' ....................................................................................... 93
5.10.7 Checking the generated messages .............................................................................. 94
5.10.8 Filters do not work ......................................................................................................... 94

6 Managing static data .................................................................................................97
6.1 Introduction ........................................................................................................................... 97
6.1.1 Static data workflow ........................................................................................................ 97
6.1.2 Static data workflow with 4-eyes verification ................................................................... 99
6.1.3 Static data workflow: CMM and TRM .............................................................................. 99
6.2 Setting up static data management ................................................................................... 100
6

© Wall Street Systems IPH AB - Confidential

6.2.1 State and state flow setup ............................................................................................. 101
6.2.1.1 Next state after an Accept action ........................................................................ 102
6.2.1.2 Creating and deleting states ............................................................................... 103
6.2.2 Mode setup ................................................................................................................... 103
6.2.2.1 The four system modes ...................................................................................... 104
6.2.2.2 Creating and deleting modes .............................................................................. 104
6.3 TRM with CMM - static data changes ................................................................................ 104
6.3.1 Dependencies between entities .................................................................................... 105
6.4 Using SDM-managed entities ............................................................................................. 107
6.4.1 Using static data editors ................................................................................................ 107
6.4.2 Using SDM Manager applications ................................................................................. 107
6.4.2.1 SDM Query application ....................................................................................... 107
6.4.2.2 SDM Verify application ....................................................................................... 107
6.4.2.3 SDM Admin application ...................................................................................... 108
6.5 Tables and processes used ............................................................................................... 108

7 Setting up transaction and entity flow ..................................................................111
7.1 Transaction flow and entity flow ....................................................................................... 111
7.2 Loading default transaction flow ....................................................................................... 111
7.3 Setting up transaction flow ................................................................................................ 112
7.3.1 Setting permissions ....................................................................................................... 112
7.3.2 Setting Transaction Status ............................................................................................ 113
7.3.3 Setting transaction tags ................................................................................................ 113
7.3.4 Setting Transaction States ............................................................................................ 114
7.3.4.1 Transaction State flags ....................................................................................... 114
7.3.4.2 Transaction State contexts ................................................................................. 116
7.3.5 Setting up flow operations ............................................................................................. 116
7.3.5.1 Setting condition Calls ........................................................................................ 117
7.3.5.2 Setting up agents ................................................................................................ 120
7.3.5.3 Using masks in agent setup ............................................................................... 125
7.3.5.4 Setting up service queues .................................................................................. 126
7.3.5.5 Testing transaction flow ...................................................................................... 127
7.3.5.6 Converting flow.py to CSV format ...................................................................... 128
7.3.5.7 Migrating a transaction flow from a pre-7.2 version ............................................ 128
7.3.6 Setting up a COMMIT operation ................................................................................... 129
7.3.7 Setting up status operations ......................................................................................... 129
7.3.8 Setting up limit operations ............................................................................................. 129
7.4 Using Transaction Manager modes .................................................................................. 130
7.4.1 Loading default modes .................................................................................................. 130
7.4.2 Setting up modes ......................................................................................................... 131
7.4.3 Example of mode setup ................................................................................................ 145
7.5 Database objects for transaction flow and modes .......................................................... 146
7.6 Loading default entity flows ............................................................................................... 147
7.6.1 Entity broker-based flow ............................................................................................... 147
7.6.2 CLM loan action-based flow .......................................................................................... 149

TRM System Administration Guide

7

7.7 Setting up entity broker-based flow .................................................................................. 149
7.7.1 Entity States .................................................................................................................. 149
7.7.2 Cashflow actions for Call Money / Account ................................................................... 150
7.7.3 Entity Rules ................................................................................................................... 151
7.7.4 Entity broker operations ................................................................................................ 152
7.7.4.1 Condition calls .................................................................................................... 152
7.7.4.2 Agents ................................................................................................................ 154
7.7.4.3 Service queues ................................................................................................... 158
7.7.5 Entity Manager Modes .................................................................................................. 159
7.7.5.1 Loading default modes ....................................................................................... 160
7.7.5.2 Setting up modes ................................................................................................ 160
7.7.6 Setup scripts and database objects .............................................................................. 161
7.8 Setting up loan entity action-based flow .......................................................................... 163
7.8.1 Loan Entity States ......................................................................................................... 163
7.8.2 Loan Entity Rules .......................................................................................................... 164
7.8.3 Loan Entity Actions ....................................................................................................... 164
7.8.4 Setup scripts and database objects .............................................................................. 166
7.9 Setting up transaction and settlement comments ........................................................... 166

8 Controlling user access .........................................................................................169
8.1 Managing TRM users .......................................................................................................... 169
8.1.1 Creating TRM user accounts ........................................................................................ 169
8.1.2 Deleting a TRM user account ....................................................................................... 169
8.1.3 Locking a TRM user account ........................................................................................ 170
8.1.4 Setting the System Security Officer role ....................................................................... 170
8.2 User groups ......................................................................................................................... 170
8.2.1 Default user groups in TRM .......................................................................................... 170
8.2.2 Assigning users to a group ........................................................................................... 171
8.3 Password expiry .................................................................................................................. 171
8.4 Domains ............................................................................................................................... 171
8.5 Permissions ......................................................................................................................... 171
8.5.1 Setting up the object permissions ................................................................................. 171
8.5.2 Domain permission ....................................................................................................... 172
8.5.3 Portfolio access ............................................................................................................. 172
8.5.4 Mode permissions ......................................................................................................... 172
8.5.5 Payment mode permissions .......................................................................................... 172
8.6 Limiting access to activity types ....................................................................................... 172
8.7 Using Security Center ......................................................................................................... 173
8.7.1 User Administration Editor ............................................................................................ 174
8.7.1.1 Creating a new group ......................................................................................... 174
8.7.1.2 Modifying an existing group ................................................................................ 175
8.7.1.3 Deleting an existing group .................................................................................. 175
8.7.1.4 Creating a new user ........................................................................................... 175
8.7.1.5 Modifying an existing user .................................................................................. 176
8.7.1.6 Deleting an existing user .................................................................................... 176

8

© Wall Street Systems IPH AB - Confidential

8.7.1.7 Searching for a user ........................................................................................... 177
8.7.1.8 Assigning portfolio permissions to users and user groups ................................. 177
8.7.1.9 Assigning domain permissions to users and user groups .................................. 178
8.7.1.10 Assigning multiple groups to users and user groups ........................................ 178
8.7.2 Password Change ......................................................................................................... 179
8.7.2.1 Password expiry and validation .......................................................................... 180
8.7.3 Permission Editor .......................................................................................................... 180
8.7.3.1 Navigating through Permission Editor ................................................................ 181
8.7.3.2 Granting a permission ........................................................................................ 181
8.7.3.3 Removing an existing permission ....................................................................... 182
8.7.3.4 Single-screen 4-eyes principle ........................................................................... 182
8.7.3.5 Granting Deal Mirroring permissions .................................................................. 182
8.7.4 Object Hierarchy Editor ................................................................................................. 183
8.7.4.1 Adding an object ................................................................................................. 183
8.7.4.2 Removing an object ............................................................................................ 183
8.7.4.3 Moving an object ................................................................................................ 184
8.7.4.4 Renaming an object ............................................................................................ 184
8.7.5 Reports ......................................................................................................................... 184
8.7.5.1 Portfolios Report ................................................................................................. 184
8.7.5.2 Domains Report .................................................................................................. 185
8.7.5.3 Objects Report .................................................................................................... 185
8.7.5.4 User Groups Report ........................................................................................... 185
8.7.5.5 Users Information Report ................................................................................... 185
8.8 Domain Editor ...................................................................................................................... 186
8.8.1 Creating a new domain ................................................................................................. 186
8.8.2 Modifying an existing domain ........................................................................................ 186
8.8.3 Deleting a domain ......................................................................................................... 187

9 Configuration Table Editor and Admin Center ....................................................189
9.1 Introduction ......................................................................................................................... 189
9.2 Configuration Table Editor ................................................................................................. 189
9.3 Admin Center ....................................................................................................................... 193
9.3.1 Renaming Tool .............................................................................................................. 194
9.3.1.1 Renaming a portfolio ID ...................................................................................... 194
9.3.1.2 Renaming a client ID .......................................................................................... 195

10 Customizing TRM user interfaces .......................................................................197
10.1
10.2
10.3
10.4

Setting up menus .............................................................................................................. 197
Setting up title bars ........................................................................................................... 197
Deactivating splash screen .............................................................................................. 197
Selecting a theme .............................................................................................................. 197

10.5 Customizing Transaction Manager ................................................................................. 198
10.5.1 Transaction Manager default configuration ................................................................. 198
10.5.2 Overriding the default configuration ............................................................................ 199
10.5.3 Adding custom parameters to Transaction Manager actions ...................................... 199
TRM System Administration Guide

9

10.5.4 Removing a toolbar button from the Transaction Manager ......................................... 200
10.6 Customizing Enter Board ................................................................................................. 200
10.6.1 Adding the entity definition .......................................................................................... 200
10.6.2 Making fields accessible ............................................................................................. 201
10.6.3 Making properties available ........................................................................................ 201

11 Managing activities ...............................................................................................203
11.1 Overview ............................................................................................................................ 203
11.2 ActivityType table ............................................................................................................. 203
11.3 Generating Windows NT Reports .................................................................................... 203
11.3.1 Starting the cron service ............................................................................................. 203
11.3.2 Scheduling NT Reports ............................................................................................... 204

12 Setting up comKIT ................................................................................................205
12.1 Introduction ....................................................................................................................... 205
12.2 comKIT Components ........................................................................................................ 205
12.3 comKIT Server ................................................................................................................... 205
12.3.1 Architecture ................................................................................................................. 205
12.3.1.1 Garbage collecting ............................................................................................ 206
12.3.1.2 TRM Naming Service ....................................................................................... 206
12.3.1.3 comKIT Server Parameters .............................................................................. 206
12.3.2 comKIT Server Configuration ...................................................................................... 206
12.3.2.1 Naming Service ................................................................................................ 206
12.3.2.2 Firewall ............................................................................................................. 206
12.3.2.3 SSL ................................................................................................................... 207
12.3.2.4 omniORB .......................................................................................................... 207
12.4 comKIT Client .................................................................................................................... 207
12.4.1 Python ......................................................................................................................... 207
12.4.2 Java ............................................................................................................................ 207
12.4.3 Exceptions .................................................................................................................. 208

13 Configuring and customizing reports .................................................................209
13.1 Report Generator components ........................................................................................ 209
13.1.1 Dataloader modules .................................................................................................... 209
13.1.2 Report engine ............................................................................................................. 210
13.1.3 Report Generator UI ................................................................................................... 210
13.1.4 ReportD ....................................................................................................................... 210
13.1.5 Cover pages, headers, and footers ............................................................................. 210
13.2 Applying report definitions .............................................................................................. 210
13.3 Sample report definition file ............................................................................................. 211
13.3.1 Main section ................................................................................................................ 212
13.3.2 Rename section .......................................................................................................... 212
13.3.3 Filter section ................................................................................................................ 213
13.4 Configuring New Report submenu .................................................................................. 213
10

© Wall Street Systems IPH AB - Confidential

13.5 Setting up layout files ....................................................................................................... 214
13.6 Running related reports ................................................................................................... 214
13.6.1 drilldown.ini files .......................................................................................................... 214
13.6.2 .frd report types ........................................................................................................... 214
13.7 Customizing reports in python ........................................................................................ 215
13.8 Customizing reports in perl ............................................................................................. 215
13.9 Printing reports from the command line (Windows only) ............................................. 215
13.9.1 Main section ................................................................................................................ 216
13.9.2 Parameters section ..................................................................................................... 216
13.10 Executing reports from the command line ................................................................... 216

14 Generating verification reports ............................................................................217
14.1 General System Auditing ................................................................................................. 217
14.1.1 Domain Map Verification report .................................................................................. 217
14.1.2 Market Info Map Verification report ............................................................................. 217
14.1.3 Property Map Verification report ................................................................................. 218
14.1.4 Price Verification report ............................................................................................... 218
14.2 Instrument auditing ........................................................................................................... 219
14.2.1 Instrument Feature Verification report ........................................................................ 219
14.2.2 Instrument Result Verification report ........................................................................... 219
14.3 Transaction Auditing ........................................................................................................ 219
14.3.1 Transaction Classification Verification report .............................................................. 219
14.4 Relationship auditing ........................................................................................................ 220
14.4.1 Entity Relationship Verification report ......................................................................... 220
14.5 Client auditing ................................................................................................................... 220
14.5.1 Client Accounts Verification Report ............................................................................ 220

15 Routine system admin operations ......................................................................223
15.1 Database administration using Admin Center ............................................................... 223
15.1.1 Database statistics (TRM tables) ................................................................................ 223
15.1.2 Connected Users ........................................................................................................ 224
15.1.3 Database consistency check (Microsoft SQL Server and Sybase only) ..................... 224
15.1.4 Log Truncation ............................................................................................................ 226
15.1.5 History Log .................................................................................................................. 227
15.1.6 Database Cleanup ...................................................................................................... 228
15.2 Setting Application Manager timeout .............................................................................. 228

16 FIX trading platform interface ..............................................................................229
16.1
16.2
16.3
16.4

Components ...................................................................................................................... 229
Component interactions ................................................................................................... 230
Workflow related to the trading platform ........................................................................ 231
Site customization ............................................................................................................ 231

TRM System Administration Guide

11

16.4.1 process_order ............................................................................................................. 231
16.4.2 process_execution_report ........................................................................................... 232
16.4.3 process_cancel_request ............................................................................................. 232

Appendix A: Utility programs and scripts ...........................................................................233
A.1 Scripts ................................................................................................................................. 233
A.2 Real-time diagnostic tools ................................................................................................. 234
A.2.1 Monitoring Message Bus status ................................................................................... 234
A.2.1.1 Troubleshooting destinations ............................................................................. 235
A.2.2 md-status ...................................................................................................................... 235
A.2.3 md-trace ....................................................................................................................... 236
A.3 psql (Microsoft SQL Server and Sybase only) ................................................................. 237
A.3.1 Options ......................................................................................................................... 237
A.3.2 Commands ................................................................................................................... 238
A.4 Debugging ........................................................................................................................... 238
A.4.1 Tracing accesses to the database ................................................................................ 238
A.4.1.1 Tracing an end-user application (Windows) ....................................................... 238
A.4.1.2 Tracing a real-time application (UNIX) ............................................................... 239
A.4.2 Tracing TRM messages (Windows) ............................................................................. 239
A.4.2.1 Setting the trace level and log file output ........................................................... 239
A.4.2.2 Trace prefixes .................................................................................................... 240

Appendix B: Object permissions..........................................................................................243
B.1 List of TRM permissions .................................................................................................... 243

Appendix C: Unix operations ................................................................................................245
C.1 Unix operations .................................................................................................................. 245
C.1.1 TRM Server Passwords ............................................................................................... 245
C.1.1.1 Passwords for server processes ....................................................................... 245
C.1.1.2 Sample .fk-login file ............................................................................................ 246
C.1.1.3 Checking shared memory .................................................................................. 247
C.1.2 Startup scripts .............................................................................................................. 247
C.1.3 Scheduled processes (crontab) .................................................................................... 247

Appendix D: Configuring Dashboard ...................................................................................249
D.1 Introduction ......................................................................................................................... 249
D.2 Data sources configuration ............................................................................................... 250
D.2.1 Treasury Position ......................................................................................................... 250
D.2.2 Cash Management Reports ......................................................................................... 250
D.2.3 Report Generator ......................................................................................................... 250
D.2.4 Limits ............................................................................................................................ 251
D.2.5 Dashboard client application ........................................................................................ 251

Appendix E: Adding valuation modes..................................................................................253
12

© Wall Street Systems IPH AB - Confidential

Appendix F: External valuation.............................................................................................255

TRM System Administration Guide

13

14

© Wall Street Systems IPH AB - Confidential

Preface

This guide describes the system administration tasks required for Transaction and Risk Module
(TRM).
The guide aims to:

•

Provide guidelines for the system administration of TRM

•

Provide documentation on scripts and procedures

This guide is intended for system administrators who maintain and administer TRM. Administrators
should have experience with the following:

•

Common Object Request Broker Architecture (CORBA)

•

Perl and Python scripts

The database used with TRM is a customer asset and its operation, maintenance, and administration
should be under the control of a qualified DBA. It is the DBA’s responsibility to ensure that the
maintenance of the database used with TRM reflects customer policies and procedures.

Associated documents
•

TRM User Guide

•

comKIT API Reference provided in TRM installation:
FK_HOME\support\comKIT\doc\idl\html\index.html (Windows platform only)

•

Wallstreet Suite Installation Guide

•

Wallstreet Suite System Admin Guide

•

Wallstreet Suite Database Setup Guide

TRM System Administration Guide

15

16

© Wall Street Systems IPH AB - Confidential

Chapter 1

System processes

1.1 TRM clients
The TRM clients can be divided into server processes that take care of the underlying information
flow between all TRM processes and user processes (for example monitors and editors).

1.1.1 Server processes
The server processes are as follows:
Process

Description

ActiveMQ

Message bus

omniNames

CORBA name server

mdsd

Message Delivery System daemon (central point for all real-time traffic)

transd

Deal transfer daemon for TRM

micd

Market Information Calculation daemon (produces derived rates)

limitd

Limit daemon

activityd

Activity-launching daemon

tmd

Treasury Monitor daemon

comkitd

comkit daemon

reportd

Generates reports on demand for TRMWeb.

serviced

Service deamons, load CORBA modules to process and deliver data through
particular business logic.

sessiond

Session deamons, deliver data to the end user through persistent connections
(sessions) that can be distributed among several instances.

TRM - Onyx Rate Interfaces

Rate Feeder, Rate Saver, MDSD Gateway and Rate Broadcaster

More details about these processes, see Chapter 2 Managing server processes on page 21.

TRM System Administration Guide

17

1 System processes
1.1 TRM clients

SaverQ

RateFeeder

RateSaver

Database

transd Q

transd

mdsd
Gateway

mdsd

Broadcaster Q

C++ apps

Broadcaster

Key:
Topic Tree

micd

Other C++
apps

Rate Monitor Q

micd Q

Topic Tree

Rate Monitor

Onyx
process

C++
applications

Queue

The server processes, which may run on their own dedicated server computers, use CORBA for
inter-operability. The name server connects to all the processes and allows the server processes as
well as the user processes to locate each other. The following is a summary of how this works:

•

The ORB (Object Request Broker) is configured with a naming service with a dedicated port for
requests.

•

When an application connects to the mdsd, it uses the naming server to locate it. It then registers
a callback-object with the server. The server connects to this object whenever it needs to send
updates to the client.

•

A timeout parameter to the server defines how long the connection is alive, and the connection
is restored on an as-needed basis if it has timed-out.

18

© Wall Street Systems IPH AB - Confidential

1 System processes
1.1 TRM clients

1.1.2 Onyx
Onyx is a simple Java application server. It is complementary to ServiceD, which is used to run
services written in Python or c++.

1.1.2.1 Starting Onyx
Onyx is started by the following command:
On Windows
> onyx.bat
On Unix
> rc.onyx
It takes a space-separated list of services as arguments. For example, to start Onyx with the
services trmstaticdata and esiadapter, enter:
> rc.onyx trmstaticdata esiadapter

1.1.2.2 Configuring property files
Configuration files for Onyx and Onyx services are located under
$FK_HOME/etc/onyx/configuration/context/properties. This directory contains files with the
extension '.properties'. Each service has a configuration file named
'.properties' (for example esiadapter.properties).
Some property files are used by all services (jdbc.properties, jms.properties,
ssl.properties, dbkit.properties, appserver.properties). You need to configure only the
property files required by the services you want to run. See the documentation of each service for
more information.

1.1.2.3 Configuring number of service instances
Each service in Onyx can be run in a specified number of instances. To change the number of
instances, edit the file
$FK_HOME/etc/onyx/configuration/services/-bootstrap.xml.
Do not change anything in the content of the file except of number of instances, as in this example:





1.1.2.4 Onyx log files
By default, Onyx and all its services create log files in the $FK_HOME/var/log structure
(onyx_trmswift.log in $FK_HOME/var/log/trmswift, onyx_basics.log in
$FK_HOME/var/log/trm). To change the level of logging detail, edit the file
$FK_HOME/etc/onyx/configuration/context/log4j.xml.
For logging, Onyx uses the Java open source library Log4J.

1.1.3 User processes
The main TRM user processes are:

•

Transaction Managers (for example Deal Capture)

•

Monitors (for example Treasury Monitor)

•

Editors (for example Instrument Editor)

•

Reports. Reports are generated on demand (TRMWeb only).

TRM System Administration Guide

19

1 System processes
1.2 Network bandwidth

They all connect to the database when they are started, to read in their configuration data.

1.2 Network bandwidth
The network bandwidth required for TRM depends totally on the usage of the system. Entering a
deal in Deal Capture, for example, initiates a stored procedure (SQL insert to the database server)
and a real-time update to the mdsd. The network traffic for this kind of operation would be very
limited. An entry made with one of the editors, for example Client Editor, would also cause very
limited traffic.
There are two main traffic types: traffic between TRM applications and the TRM server processes,
and traffic between TRM applications and the TRM database.
The network traffic that is generated by receiving market information (for example, Reuters or
Telerate) will basically depend on the instruments configured in the system and the rate that they
are receiving updates from the information source.
It is also highly dependent on how the system is used. For example, Limit Monitor generates
different network traffic depending on the data used when started. This makes it very difficult to
predict how much network traffic will be generated.
The factor that has the most impact on network traffic is the update rate on the market information.
The update rate may be different from various providers.
The network traffic generated when the users request reports will depend on the parameters that
are given as well as the size and contents of the database. Reports or Treasury Monitor can cause a
lot of network traffic.

20

© Wall Street Systems IPH AB - Confidential

Chapter 2

Managing server processes

The TRM server processes use a CORBA-based messaging technique for inter-process
communication. Two processes, mdsd and limitd, are contacted by other processes and
applications.

2.1 omniNames
The CORBA Names server must be running before any of the TRM server processes can function.

2.2 Onyx rate interface
The Onyx Rate Interface consists of the following Onyx processes:
Process

Description

Rate Feeder

Rate Feeder is responsible for retrieving the native rate format and converting it to
the standard message format used in Wallstreet Suite. Currently, the Reuters API
in version 7.3 is based on the Reuters Foundation API for Java (RFAJ) 6.3. It
Reuters’ latest and strategic API for connecting to RMDS servers. This API
introduces a new message format and a more efficient binary communication
protocol.

Rate Saver

Rate Saver is responsible for storing real time or calculated rates into the
database. Special filtering logic can be applied in order to tune the frequency of
stored real time and calculated rates.

MDSD Gateway

MDSD Gateway itransfers rate messages from the ActiveMQ platform to the
CORBA platform in order to distribute rates via MDSD.

Rate Broadcaster

Rate Broadcaster distributes rates over the system and it takes over this role from
mdsd. Applications subscribe to the Rate Broadcaster to obtain new rate
messages.

2.3 Automatic start of server processes
All server processes, including the market information links, can be automatically restarted during
boot by:

•

On UNIX: running the setup.fk script as follows:
cd $FK_HOME/etc
./setup.fk
Running the script puts the system passwords into memory.

TRM System Administration Guide

21

2 Managing server processes
2.4 mdsd

On Windows: In Start - Control Panel - Administrative Tools - Services, ensure that the Startup Type of all
Wallstreet Suite services is Automatic.

•

Note: When running Telerate, the tipd process should be started as the Telerate user aws. If not,
it will not start up properly.

Refer also to the description of Process Monitor daemons in the WSS System Admin Guide.

2.4 mdsd
The mdsd (Message Delivery System Daemon) is the hub of all real-time information flow. It is
essential for the real-time components of TRM. All activities requiring real-time updates must
indicate this by creating a connection with the mdsd.
The mdsd is a message exchange service. It allows for the arrival of correctly formatted messages
that are then broadcast to the processes that have indicated an interest in that particular message.
When a client (process) connects to mdsd, it requires a response to indicate that its request has
been accepted.
All applications (user and server processes) connect to mdsd. Some only receive information, like
Treasury Monitor and FX Forward Pricing; others send information, like Editors and Transaction
Manager.
Option/Argument

Description

--log-directory arg

Directory for log files

--service-name arg

Service name to register with CosNaming

--max-queue-size arg

Maximum allowed queue length for clients

--timeout-interval arg

Timeout for non-responsive clients

2.5 transd
The transd real-time process is used to send information to the real-time server about updates of
prices and transactions that are imported or changed in a way that is not otherwise notified to the
mdsd.

Note: This is a required process for the Limit Monitor.
The PushPendingPrices and PushPendingTransactions procedures are used to update the
PendingPrices and PendingTransactions tables which are being read by the transd process.
Option/Argument

Description

-I arg
--interval arg

Interval in milliseconds to check (default 70000)

-T arg
--topic arg

Topic to listen to

22

© Wall Street Systems IPH AB - Confidential

2 Managing server processes
2.6 micd

2.6 micd
The micd real-time process calculates yield curves and derived rates. This process logs in to the
database as user batch.
Option/Argument

Description

-i arg
--include arg

Include given rates (default all)

-e arg
--exclude arg

Exclude given rates

-s arg
--init-scenario arg

List of scenarios to initialize by default

-d arg
--init-date arg

List of dates to initialize by default

-n
--dont-send

Inhibit sending of quotes, useful for debugging

-b
--batch

Batch mode, finish immediately after startup

--interval arg

Interval in milliseconds to check.

--source-name arg

Source name (default MICD)

2.7 reportd
The reportd program generate reports on demand. It is launched by TRMWeb, retrieves the report
data, supplies them to TRMWeb and terminates.
Option/Argument

Description

-l arg
--layout arg

Report layout

-t arg
--type arg

Report type

-f arg
--format arg (=bin)

Output format (bin|xml|xml3|html|txt|csv)

-p arg
--param arg

Report list of report parameters (-p name1=value1 -p name2=value2
etc.)

2.8 Limit Server
The TRM limit deamon monitors updates of transactions and market information changes. It accepts
connections from TRM applications and sends out information about the usage of current limits. The
limit servers watch the limits that are set up.
The limit deamon exists in two versions:

•

limitd: the CORBA service, which only computes limits and serves data to applications

TRM System Administration Guide

23

2 Managing server processes
2.8 Limit Server

sessiond: the distributed limit service, which monitors limits, processes limit violations, and
serves data to the end user using persistent connections via the message bus.

•

2.8.1 Start-up script
On Unix systems, the script $FK_HOME/etc/rc/rc.limitd -e  starts the limit
daemon for the specified environment.
The limit daemon can be run in a periodic mode in the same way as Treasury Monitor, for example,
is run (both Start Date and End Date are used as a selection criteria when starting up the server).

2.8.2 Applying periodic stop/loss limits
The period against which the limit daemon is run is critical in applying periodic stop/loss limits. The
Period End Date is currently always the current date. The generation of Period Start Date is made
based on three start-up options for the limit daemon described in the following tables:
Option/Argument

Sessiond option

Description

--use-business-days arg

-s "use-business-days=arg"

Use business days, affects how
period-method operates.

--start-date-value arg

-s "start-date-value=arg"

The number of days offset from
end-date (start-date = end-date offset)

--period-method arg

-s "period-method=arg"

Specify period method,
NUMBER-OF-DAYS, CURRENT-WEEK, or
CURRENT-MONTH

•

Period Method = NUMBER-OF-DAYS
This method can be used as a default if no Period Method has been given and the server is run
in a periodic mode.
If --use-businessdays is set to No
(Default)

If NUMBER-OF-DAYS is used as Period Method and the parameter
--use-business-days is set to No, the preferred length of the period has to be
given as the number of days in parameter --start-date-value. The Start Date
for the limit daemon is then selected as:
Current Date - Start Date Value +1
where:
"1" in Start Date Value would result in the limit daemon being run with Start Date
= End Date (i.e. the current method). If nothing is given in
--Start-date-value, "1" should be used as default.

If --use-businessdays is set to Yes

If the parameter --use-business- days is set to Yes, the preferred length of
the period has to be given as number of business days in parameter
--start-date-value. The Start Date for the limit daemon is then selected as:
Current Date - Start Date Value +1
where:
Start Date Value is interpreted as business days validated against the calendar of
the base currency of the Portfolio ID used as a start up criteria for the limit
daemon.
"1" in Start Date Value would result in the limit daemon being run with Start Date
= End Date unless the previous day was a non-banking day. In this case, the
Start Date would be selected as one day after the previous business day.

24

© Wall Street Systems IPH AB - Confidential

2 Managing server processes
2.8 Limit Server

•

Period Method = CURRENT-WEEK
If --use-businessdays is set to No
(Default)

If CURRENT-WEEK is used as Period Method and the parameter
--use-business-days is set to No, the Start Date for the limit daemon is
selected as:
The closest past date for which the number of weekday was the same as the value
given in the parameter --start-date-value (1-7).
End Date is used as Start Date if the number of weekday of End Date (i.e. current
date) is the same as the value given in the parameter --start-date-value.

If --use-businessdays is set to Yes

If CURRENT-WEEK is used as Period Method and the parameter
--use-business-days is set to Yes, the Start Date for the limit daemon is
selected by:
Adding one day to the last business day preceding the closest past date for which
the number of weekday was the same as the value given in the parameter
--start-date-value (1-7).
For example, "1" (referring to Monday) is given as --start-date-value and the
server is started up on Wednesday.
The Start Date is selected by first going back to the previous Monday, then further
to last business day preceding Monday (normally Friday) and by adding one day to
it (i.e. ending up with Saturday).
End Date is used as a preliminary Start Date (i.e. before business day adjustment)
if the number of weekday of End Date (i.e. current date) is the same as the value
given in the parameter --start-date-value.
For example, in the previous example, the previous Saturday would be selected as
Start Date even when the server was started up on Monday.

•

Period Method = CURRENT-MONTH
If --use-businessdays is set to No
(Default)

If CURRENT-MONTH is used as Period Method and the parameter
--use-business-days is set to No, the Start Date for the limit daemon is
selected as:
The closest past date for which the number of day of month was the same as the
value given in the parameter --start-date-value (1-31).
End Date is used as Start Date if the number of day of month of End Date (i.e.
current date) is the same as the value given in the parameter
--start-date-value.

If --use-businessdays is set to Yes

If CURRENT-MONTH is used as Period Method and the parameter
--use-business-days is set to Yes, the Start Date for the limit daemon is
selected by:
Adding one day to the last business day preceding the closest past date for which
the number of day of month was the same as the value given in the parameter
--start-date-value (1-31).
For example, "1" is given as Start Date Value and the server is started up on 10th.
The Start Date is selected by first going back to first of month, then further back
to the last business day preceding the 1st day and then by adding one day to it.
End Date is used as a preliminary Start Date (i.e. before the business day
adjustment) if the number of day of month of End Date (i.e. current date) is the
same as the value given in the parameter --start-date-value.

2.8.3 Setting up the limit daemon
The environment variable $FK_LIMITD_SETUP is used to supply options to the rc.limitd script. On
UNIX, run $FK_HOME/sbin/limitd --help to list the available options; on Windows, run
%FK_HOME%\bin\limitd --help.

TRM System Administration Guide

25

2 Managing server processes
2.8 Limit Server

The following table outlines some of the typical definitions:
Option/Argument

Description

--batch limits

Run only once to compute and log the limits.

--category-warning-thresholds arg

To generate a warning message when the threshold level,
expressed as a percentage, is reached for the corresponding
category. For example, if the categories CREDIT and
SETTLEMENT have been specified with the
--limit-categories parameter, then
--category-warning-threshold 75 80 specifies a
threshold of 75% for CREDIT and 80% for SETTLEMENT.
(Available categories are shown in the Limit Editor.)

--contexts arg

The result contexts to include.

--end-date arg

Period end-date, defaults to today.

--exclude-limit-categories arg

Do not update specified limit categories.

--exclude-limits arg

Do not update specified limits.

--exclude-limits-match arg

Do not update limits matching.

--interval arg

The update interval in milliseconds.

--limit-categories arg

Update only specified limit categories.

--limits arg

Update only specified limits.

--limits-match arg

Update only limits matching.

--log-interval arg

The logging interval in milliseconds.

--mark-all

Pass all transactions through no-violation-action even if no
limit rule matches.

--min-log-interval arg

The minimum logging interval.

--mode arg

the valuation mode (default=0).

--no-violation-action arg

This start-up parameter can be given the following values
and behavior:

--no-violation-action 0
When a transaction update results in a new limit violation, or
an old limit violation worsens, the server calls the transaction
action LIMIT VIOLATION that, by default, sets the status
LIMIT VIOLATION for the transaction. Any other types of
transaction actions can also be configured under the
action_id LIMIT VIOLATION.

--no-violation-action 1
The server behaves the same way as “0.” In addition, the
server calls the transaction action LIMIT VIOLATION CLEAR
that, by default, clears the LIMIT VIOLATION status when no
limits are violated as a result of a transaction update. (In
other words, the server automatically clears the previously
set LIMIT VIOLATION status when, following a new update,
no limits are violated by that transaction anymore.) Any
other type of transaction action can also be configured under
the action_id LIMIT VIOLATION CLEAR.

--no-violation-action 2
When value "2" is assigned, the server calls either the LIMIT
VIOLATION or NO LIMIT VIOLATION transaction action once
for the entire transaction, regardless of the number of limits
that might be affected.

26

© Wall Street Systems IPH AB - Confidential

2 Managing server processes
2.8 Limit Server

Option/Argument

Description

--only-outstanding

Include only outstanding transactions.

--pending-on-value-date

Pre-Settlement Expression is used when value date = start
date.

--period-method arg

Period method, NUMBER-OF-DAYS, CURRENT-WEEK, or
CURRENT-MONTH.
See 2.8.2 Applying periodic stop/loss limits on page 24.

--portfolio-id arg

The top portfolio to start up.

--realized-end

Period behavior Realized End.

--scenario-id arg

The scenario to use.

--server-type arg

Specify server type, either FINAL (default) or SIMULATION

--service-name arg

The limit server name in Naming Service. Default is
limit-monitor.

--start-by-transaction

When the limit server starts up, read transactions into limitd
by transaction number order, calculate limit utilizations and
call limit operations separately for every transaction.

--start-date-value arg

The number of days offset from end-date (start-date =
end-date - offset).
See 2.8.2 Applying periodic stop/loss limits on page 24.

--state-context arg

The state contexts to include.

--state-id arg

The initial state to use.

--use-business-days

Use business days, affects how period-method operates.
See 2.8.2 Applying periodic stop/loss limits on page 24.

--use-todays-fx-rate

--valuation-method arg

Limit daemon command line option --use-todays-fx-rate
now accepts optional arguments to support the calculation of
FX rates using the same methods as in the valuation.
•

If the option is not used, FX rates are calculated using the
FX method 'Spot Rate'.

•

If the option is used with no arguments or with argument
'=1', FX rates are calculated using the FX method 'Today's
Rate (Forward points)'.

•

If the option is used with argument '=2', FX rates are
calculated using the FX method 'Today's Rate (IR
Difference)'.

Valuation method:
0 = Portfolio (default)
1 = Normal
2 = Zero Coupon
3 = Benchmark
4 = Zero Spot

--var-confidence-level arg

The Value-at-Risk confidence level to use

--var-horizon-id arg

The Value-at-Risk horizon id to use.

--var-scenario-id arg

The Value-at-Risk scenario to use

TRM System Administration Guide

27

2 Managing server processes
2.9 activityd

Option/Argument

Description

--warning-threshold arg

To generate a warning message when the threshold level n,
expressed as a percentage, is reached. This parameter can
provide the means for generating a global warning level for
all limits.

2.8.3.1 Standard setup
$ENV{FK_LIMITD_SETUP} = "
--contexts 3
--portfolio-id LIMIT
--state-id OPEN
--interval 300000
--min-log-interval 300000
--log-interval 3600000
";
This limit daemon will recalculate the limits every five minutes for all limits defined for the portfolio
tree where the LIMIT is the top portfolio. It will log the usage every 60 minutes.

2.8.3.2 Setup with frozen rates
$ENV{FK_LIMITD_SETUP} = "
--contexts 3
--portfolio-id LIMIT
--state-id OPEN
--interval 300000
--min-log-interval 300000
--log-interval 3600000
--scenario-id FREEZE
";
This limit daemon will work just like the previous one, but it will use frozen rather than default rates
to calculate the limits.

2.8.4 Checking the limit daemon
The program lm-status will show the id’s of the limits for the limit daemon. If limit users are
defined the switch -limit-user  should be used.
Sample output from lm-status:
ID
Name
---------------------------------------------------------FX-LIMIT
Forex Limit
IR-LIMIT
Limits on Interest Rate products
IR-LIMIT-2
Second Limit on Interest Rate products
VAR LIMIT
VaR Limit

2.9 activityd
The activityd process launches activities as soon as they are submitted from Activity Manager.
Option/Argument

Description

-n arg
--pool-size arg

The number of parallel handlers (default from database)

28

© Wall Street Systems IPH AB - Confidential

2 Managing server processes
2.10 tmd

Option/Argument

Description

-t arg
--poll-time arg

The maximum time to recheck (default from database)

-l arg
--log-program arg

The program to run at the end

-e arg
--external-program arg

The program to handle external commands.

--hostname arg

The name activityd will use as hostname to filter activity types.
Note: To use the hostname parameter you need to set the Check
activity host name parameter to true in the configuration
table.

2.10 tmd
The Treasury Monitor daemon provides position monitoring on the server and is used by comKIT’s
Position service. It can also be be used to take CPU and memory usage from the client machines
running Treasury Monitor.
tmd takes the following command line options:
Option/Argument

Description

-s arg
--service-name arg

Service name in Naming Service: default is treasury-monitor

-c arg
--tmd-config-file arg

XML configuration file

-p arg
--param arg

List of xml parameters

To use tmd from Treasury Monitor give it a service name:
tmd.exe --tmd-config-file tmpos.xml -–service-name tmdtest
and set Treasury Monitor to connect to the specified service name:
FKTreasuryMonitor.exe -–service tmdtest

2.10.1 Configuring views and books for Treasury Monitor
To limit CPU and memory usage, run tmd in preconfigured mode by providing a configuration file.
You must configure the position and portfolio views you want in the configuration file, create the
books based on that configuration, then launch Treasury Monitor to re-use those books. To do this:
1. Open Treasury Monitor from Application Manager with the startup parameters you would like to
see.
2. Configure the columns and pages you would like to see in the application.
3. Select File - Save Position and Pages as XML. This saves all data to a single XML file.
If you want to save the position and perhaps a particular page or pages then:
a. Select File - Save Position as XML (this will save the startup parameters), e.g. tmpos.xml.
b. For each Page in TM, select Page - Save Page as XML, e.g tmpage1.xml, tmpage2.xml etc.
c. In an XML editor, open the above files (the position file as well as the page files).

TRM System Administration Guide

29

2 Managing server processes
2.10 tmd

d. Insert the page information in the position file after the 



























































30

© Wall Street Systems IPH AB - Confidential

2 Managing server processes
2.11 Configuring Monitor page templates

4. By default, tmd goes to the $FK_HOME/etc directory to find this configuration file. If you wish to
place it somewhere else, then ensure that $FK_CONFIG_HOME is set, and that its value is the path
to this configuration file.
5. This XML configuration file must be placed in the $FK_HOME/etc folder. Otherwise its location
must be explicitly defined as FK_CONFIG_HOME.
Unix:
export FK_CONFIG_HOME=/home/user/xml
Windows:
set FK_CONFIG_HOME=c:\home\user\xml
6. Start the tmd (from shell, from script…)
tmd.exe --tmd-config-file tmpos.xml –service-name tmdtest
7. Start the Treasury Monitor (from shell, from script…) on Windows
FKTreasuryMonitor.exe -–service tmdtest
8. Select the position in the Position startup parameter (tmpos), and click OK.
9. Select Page - New Grid Page. Check that you can select the pages that you saved in the XML Page
files mentioned above. Click OK, and open the next Page, and so on.
From this point, you can rename the pages to something more meaningful, and then select Save

Book As...

2.11 Configuring Monitor page templates
The Monitor page template is a file that contains preconfigured axis information for use as a starting
point in creating a new Monitor page. The Monitor application comes with a number of page
templates, each of which contains a different selection of axes (or same axes set up differently).
A Monitor configuration file contains information about the page templates available for a particular
mode of operation. Currently there are two configuration files, RM.XML and CM.XML, that
correspond to the two supported modes of operation (Rate Monitor and Calibration Monitor). The
toolbar button configuration is defined in external page template files (*.page) and cannot be
modified from Rate Monitor.
Monitor application must be launched with an appropriate configuration file specified on the
command line using the -c switch. The application uses page template information found in the
configuration file to build a hierarchical menu, allowing users to create a new page based on a
certain template simply by clicking on the appropriate menu item.

2.12 Deal mirroring module (DMM)
Deal mirroring is provided by the Mirror Loop real-time process, which uses comKIT to access TRM.
You can set DMM related variables including user name and password, and location of logs in this
script: %FK_HOME%\share\environments\mirror_config.bat (Windows) or
$FK_HOME/share/environments/mirror_config.sh (Unix).

Hint:

Under Unix, instead of keeping the password in the mirror_config.sh file, you can have
the password written into shared memory. See C.1.1 TRM Server Passwords on page 245

TRM System Administration Guide

31

2 Managing server processes
2.12 Deal mirroring module (DMM)

which describes how do this. DMM first checks the value of the environment variable
DMM_SERVER_PASSWORD and if it finds nothing, it tries to read it from shared memory.
The configuration file is evaluated under Unix by running the eval command.
Under Windows, before launching DMM, open an evaluated shell and enter:
set DMM_CONFIG=%FK_HOME%\share\environments\mirror_config.bat
Deal mirroring can be launched by %FK_HOME%\mirror_loop.bat (process under Windows) or
$FK_HOME/bin/rc.mirror (Unix). Otherwise, see the section on Process Monitor in the WSS System
Administration Guide.

32

© Wall Street Systems IPH AB - Confidential

Chapter 3

Interfaces with other tools

3.1 Bloomberg Interface
The Bloomberg interface consists of several activities. You can import and update instruments,
import corporate actions, update information in the Client Editor, or request new prices based on
information sent by Bloomberg. Each item is implemented by a dedicated activity which is described
in the TRM User Guide. Technical communication is the same for all of these activities. First, the
request is created, then it is sent via FTP communication to the Bloomberg site, the response file is
retrieved after a preset interval, and obtained data are processed based on their nature in the
Wallstreet Suite structures, instruments, clients or prices.

3.1.1 Environment variables
The following environment variables affect the behavior of all Bloomberg activities:
Name

Comment

Default

FK_BLOOMBERG_FTP
_REMOTE_DIR

This environment variable should point to the directory
where the request and reply files should be stored,
otherwise the default will be /tmp.

/tmp

FK_BLOOMBERG_FTP
_HOST

IP address of the primary FTP server, delivered by
Bloomberg.

bfmdr.bloomberg.com

FK_BLOOMBERG_FTP
_SEC_HOST

IP address of the secondary FTP server, delivered by
Bloomberg.

FK_BLOOMBERG_FTP
_USER

Login ID (user ID) for the Bloomberg FTP server, delivered
by Bloomberg.

FK_BLOOMBERG_FTP
_PASS

Login Password (user Password) for the Bloomberg FTP
server, delivered by Bloomberg.

FK_BLOOMBERG_FTP
_DES_PASS

Password that is used to decrypt the incoming file from
Bloomberg. The encryption/decryption method used is
DES.

FK_BLOOMBERG_FTP
_TRIES

Maximum number of attempts to download the response
file.

10

FK_BLOOMBERG_FTP
_POLL_TIME

Specifies the number of seconds in total to wait for the
reply file to appear on the FTP server.

15

FK_BLOOMBERG_FTP
_SERIALNUMBER

Serial number setup, delivered by Bloomberg.

FK_BLOOMBERG_FTP
_USERNUMBER

User number setup, delivered by Bloomberg.

FK_BLOOMBERG_FTP
_WORKSTATION

Workstation setup, delivered by Bloomberg.

FK_BLOOMBERG_FTP
_LOCAL_DIR

Local directory used for FTP communication - generated
request files are stored here.

FK_BLOOMBERG_FTP
_SCRIPT

Shell script that will take care of FTP communication with
Bloomberg instead of the built-in implementation.

TRM System Administration Guide

TS_ENV_HOME/var/tmp/

33

3 Interfaces with other tools
3.1 Bloomberg Interface

Name

Comment

Default

FK_BLOOMBERG_RE
QUEST_SYSTEM

Specifies how request files are processed. Possible values:
FTP or DATA. DATA should be used only if the request files
will be communicated as Send File via the BLOOMBERG
PROFESSIONAL service.

FK_BLOOMBERG_CO
MPRESS

Specifies whether the request file should be compressed.

FK_BLOOMBERG_EN
CRYPTION_UTILITY

Utility to be used to encrypt and decrypt request and
response files. Possible values: OPENSSL and DES.

Possible values: YES or NO.

OPENSSL means that the openssl utility delivered with WSS
is used.
If DES is used, then it is necessary to specify a path to the
DES utility provided.
FK_MDI_BLOOMBER
G_PROVIDER_NAME

Name of the provider.

FK_MDI_FILE_IMPOR
T_DIR

Directory where the output files for the Data License
Output Processing activity are searched.

TS_ENV_HOME/var/impo
rt/

FK_MDI_FILE_ARCHI
VE

Archive response files if successfully processed.

true

FK_MDI_FILE_ARCHI
VE_DIR

Dir where response files are archived.

TS_ENV_HOME/var/archi
ve/

FK_MDI_FILE_ARCHI
VE_DIR

Pattern used to search file in FK_MDI_FILE_IMPORT_DIR

'*.*'

FK_MDI_CHECK_INS
TRUMENT_EXISTS

Specifies whether duplicity instruments can be created.
Possible values: True, False
If set to true, then before each import of a specific security
(for example ISIN) a check is made to establish whether an
instrument with the same security ID already exists. If yes,
an error is reported and the security is skipped.
If set to false, no validation of whether the security id
exists is performed and the security is always imported. If
the name that should be used for the new instrument
already exists, then the counter is added at the end.

FK_MDI_UPDATE_CLI
ENT_TO_STATE

The maximum state to which the client will be accepted
after an update (valid only if SDM is installed)

FINAL

Example: The client is in state FINAL before update. If the
value of the property is FINAL, the client is accepted to
state FINAL. If the value of the property is VERIFY, the
client is accepted only to state VERIFY.

FK_MDI_SCRIPT_P
ACKAGE

FK_MDI_SCRIPT_DIR

34

The default package to be used when searching for the
scripts. The package should contain the following
subdirectories:
•

field_mapping

•

entity

•

mapped_value

The location of the scripts root if it is different from the
default location.

tasks.instrument.imp.scri
pt

© Wall Street Systems IPH AB - Confidential

3 Interfaces with other tools
3.1 Bloomberg Interface

3.1.2 CSD possibility
You can adjust the behavior of the majority of Bloomberg actions according to your specific needs.
You can attach specific python scripts at various points (i.e. when inserting new instruments or
updating individual entities) to implement any necessary changes.
You need to store this python script as a python module with the extension .py in the folder
FK_MDI_SCRIPT_DIR/ FK_MDI_SCRIPT_PACKAGE/entity. Then, the name of this script (without the
.py extension) is attached to the appropriate Request or Mapping Rule Editor. Pre-save scripts are
executed before the entity is saved; Post-save scripts are executed after the entity is saved.

3.1.2.1 Entity script
You need to store the python entity script as a python module with the .py extension in the folder
FK_MDI_SCRIPT_DIR/ FK_MDI_SCRIPT_PACKAGE/entity. Then, the name of this script (without the
.py extension) is attached to the appropriate Request Editor (Instrument, Security, Corporate Action
or Client). Pre-save scripts are executed before the entity is saved; Post-save scripts are executed
after the entity is saved.
This script adjusts the entity that is supplied as the starting parameter. The ’process’ function then
returns the modified entity, which will be used in further processing.
The following provides an example of the script that is used to adjust the name of the Client entity.
def process(entity, providerData):
"""
This is a sample script to show how the entity (mapping for Client in this
case) can be processed and updated
"""
entity.setFieldValue('name', providerData['LONG_COMP_NAME'] + '__' +
providerData['ID_BB_COMPANY'])
return entity
The following provides an example of the script that is used to adjust the id of the Instrument entity.
import re
def process(entity, providerData):
"""
use pattern ${COUNTRY}G${MATURITY}_${CPN}
but take only YYYYMM of MATURITY and remove trailing zeros from coupon rate
"""
newID = providerData['COUNTRY'] + 'G'
# take only year and month from maturity date
newID = newID +

providerData['MATURITY'][:-2]

# remove trailing zeros from coupon rate
newID = newID + '_' + re.sub('\.{0,1}0*$','',providerData['CPN'])
entity.setFieldValue('id',newID)
return entity

TRM System Administration Guide

35

3 Interfaces with other tools
3.1 Bloomberg Interface

3.1.2.2 Value Mapping Editor script
You need to store the python script that is used in the Value Mapping Editor as a python module with
the .py extension in the folder FK_MDI_SCRIPT_DIR/ FK_MDI_SCRIPT_PACKAGE/ mapped_value.
Then, the name of this script (without the .py extension) will be populated in the Script field in the
Value Mapping Editor.
This script will adjust the value in the Destination field. This value is copied to the sourceValue
parameter. The ’process’ function will then return the modified value of the Destination field, which
will then be used in further processing.

Note: In general, all values from the 'process' function can be returned as strings except the
'date' fields. These fields should be returned after conversion by the DateTranslator.

3.1.2.3 Security Mapping Set Editor
You need to store the python script used in the Security Mapping Set Editor as a python module with
the .py extension in the folder FK_MDI_SCRIPT_DIR/ FK_MDI_SCRIPT_PACKAGE/ field_mapping.
Then, the name of this script (without the .py extension) will be populated in the Script field in the
Security Mapping Set Editor.
This script will adjust the value in the Provider Field. This value is copied to the sourceValue
parameter. The process function will then return the modified value, which will be used in further
processing and inserted in the defined field in the Instrument Editor.
Please note, that Script in this editor has a higher priority than Value Mapping, and only Script will be
used if Script is populated. This means that Script in the Value Mapping Editor will not be used if Script
is populated in the Security Mapping Editor.

Note: In general, all values from the 'process' function can be returned as strings except the
'date' fields. These fields should be returned after conversion by the DateTranslator.

The following provides an example of the script that is used to add a defined number of days to the
maturity date.
from tasks.instrument.imp.datatype import DateTranslator
import datetime
def process(sourceValue, localParsedEntity, localMapping):
year =
month =

int(localParsedEntity['FUT_LAST_TRADE_DT'][0:4])
int(localParsedEntity['FUT_LAST_TRADE_DT'][4:6])

days = int(localParsedEntity['FUT_LAST_TRADE_DT'][6:8])
print year, month, days
FUT_LAST_TRADE_DT = datetime.date(year, month, days)
print FUT_LAST_TRADE_DT
print localParsedEntity['DAYS_TDY_TO_NOTNL_MTY']
print int(localParsedEntity['DAYS_TDY_TO_NOTNL_MTY'])
DAYS_TDY_TO_NOTNL_MTY =
datetime.timedelta(int(localParsedEntity['DAYS_TDY_TO_NOTNL_MTY']))
print DAYS_TDY_TO_NOTNL_MTY
t = FUT_LAST_TRADE_DT + DAYS_TDY_TO_NOTNL_MTY

36

© Wall Street Systems IPH AB - Confidential

3 Interfaces with other tools
3.1 Bloomberg Interface

print t
maturity_date_1 = t.strftime("%Y%m%d")
return

DateTranslator().translate(maturity_date_1)

Note: In general, all values from the 'process' function can be returned as strings except the
'date' fields. These fields should be returned after conversion by the DateTranslator.

3.1.3 Data License Prices activity process
The following steps are performed during the Data License Prices activity process:
1. According to the query parameters in the activity, the appropriate Market Info definitions are
searched and a list of required quotations (represented by a unique identification item) is
evaluated.
2. A request for the file (in format bb-date-numberX.req) is generated and stored in the specified
folder FK_BLOOMBERG_FTP_REMOTE_DIR. If the value of the variable is not specified, the request
file will be stored in the tmp folder in the root directory (/tmp on UNIX, drive:\tmp on Windows
where the drive is the drive letter of the Wallstreet Suite installation).
3. A connection to the Data License FTP server is established based on the activity's connection
parameters.
4. The activity waits for a reply file (in format bb-date-numberX.out) from Data License, to be
stored in FK_BLOOMBERG_FTP_REMOTE_DIR.
5. The reply file is decrypted and unzipped.
6. For every quotation (represented by a unique identification item), the market info definition
valid for the date in question (either the current date or the historical rate, based on the
transaction parameters) is searched.
7. The price message containing all the necessary data such as price, scenario, and subscenario is
created. Typically, a price message consists of:
type_id

Type of instrument, for example IR-RATE, FX-RATE as defined in the
MarketInfoSource table.

period_id

Price periods, as defined in the MarketInfoSource table.

period_1_id
period_2_id
source

Source name, as defined in the MarketInfoSource table.

scenario

Specified in the activity parameters or Market Info.

subscenario

Specified in the activity parameters or Market Info.

8. The price is stored in the database by calling the PushMarketInfo stored procedure.
9. The price is propagated to the message delivery system by marking the price as pending using
the PushPendingPrice stored procedure.

3.1.4 Two step activity processing
Bloomberg activities can be run either in one go, when the whole interface process is complete
(request generation, FTP communication and output processing), or you can split the process into
two executions:
1. Request generation
2. Output processing

TRM System Administration Guide

37

3 Interfaces with other tools
3.2 Reuters Dealing 3000 Link

FTP processing is defined by user specific needs in a dedicated custom script. FTP communication
can be done asynchronously. This approach should be used in cases where there are security
limitations and direct FTP communication from the Wallstreet Suite servers is not allowed.
Both ways (all in one go and or two separate executions) are managed by the Bloomberg activities
Processing Type parameter. You need to select one of the following values:

•

All,

•

Generate Request, or

•

Process Output.

3.2 Reuters Dealing 3000 Link
3.2.1 Overview
The Dealing 3000 Link is used to convey foreign exchange and money market deals from the
Reuters Dealing 3000 system and its ticket output feed to TRM.
The link is run as a background process and is transparent to the user. It consists of a
communications module and a data conversion and storage module.

•

The communications module monitors the Dealing 3000 port and when new deals become
available it requests the deal details and passes them on to the data conversion and storage
module.

•

The data conversion and storage module maps the Dealing 3000 deal details into TRM
transaction fields and stores the transactions into the database.

38

© Wall Street Systems IPH AB - Confidential

3 Interfaces with other tools
3.3 Value-at-Risk Interface

Transaction details that are required by TRM but cannot be extracted from Dealing 3000 output can
be defined in a special configuration file. Such transaction details are for example the portfolio and
initial state of the transaction.
All deal conversions, errors and other events in either module are logged in a file.

3.2.2 Scripts
The executable Python scripts are config.py, D3000.py and CreateTransactions.py (which is
called by D3000.py).
1. Configure config.py
2. Evaluate your environment (this requires access to FK.Cache and Corba)
3. Use a command like the following:
python D3000.py > D3000.log 2>&1

3.2.3 Log file
Debug mode is enabled by default. All the received data from D3000 server is by default saved in
.\D3000Response.dat with datetime. The debug is verbose, so the file size should be monitored.
By default, the interface ignores real-time messages and polls the server every 30 seconds.

3.2.4 Implementation
D3000.py can be used standalone for testing purposes. Just comment out the transaction_maker
call in _processDeal, line 297. If configured, it saves the received data into a file which can be used
with CreateTransactions standalone. CreateTransactions.py can also be called standalone with a
file as parameter. This file will be read line by line to create transactions.
If the feed still needs to be serial, the old read-feed perl version can be used with
CreateTransactions.py. but the python main script needs to be adapted slightly to read from
STDIN instead of a file.
In addition, in Client Editor, a property DEALING-3000-ID should be defined for all Dealing 3000
counterparts. This property is the Dealing 3000 tcid.

3.3 Value-at-Risk Interface
This section describes how to install the Value-at-Risk (VaR) data in TRM via the VaR interface.
The aim of the VaR interface is to update the TRM database with the volatility and correlation data
from RiskMetrics for the currencies, yield curves and equities defined in the system. These variables
are used in VaR analysis within Treasury Monitor and also in performance calculations and risk
reports.

3.3.1 Default VaR scenario
The default VaR scenario is created at the first installation of TRM. VaR configuration is part of the
standard build procedure. The default VaR scenario does not have any mapping or data set
associated at initiation, and is the default scenario used by the import scripts.

3.3.2 VaR Mapping Types
The standard configuration has two mapping types, GOVT and SWAP. These are in the table
VaRMappingType, where they can be modified and new types added.

TRM System Administration Guide

39

3 Interfaces with other tools
3.3 Value-at-Risk Interface

3.3.3 Default mapping
A default mapping between TRM data (currencies and interest rates) and the corresponding
RiskMetrics variables is built automatically. You may need to make some changes to this default
mapping. To view or edit the default mapping, open VaR Mapping Editor and choose mapping
RISKMETRICS.
The following changes may be required:
1. TRM currencies are mapped to their RiskMetrics counterparts. Not all TRM currencies are
provided by RiskMetrics.
2. All TRM yield curves are mapped to the corresponding RiskMetrics swap curves. Re-mapping
TRM yield curves to different RiskMetrics curves (for example zero-coupon GBond curves may
need to be mapped to the RiskMetrics equivalent) must be carried out manually. For more
information on using different RiskMetrics IR mappings, see the TRM User Guide.

3.3.4 Importing RiskMetrics data to TRM
The RiskMetrics Group publishes their data on the Web (and ftp) in the form of compressed files (zip
or tar) for both the UNIX and Windows environments. The RiskMetrics data files for correlation and
volatility are as follows:
RiskMetrics Data Files

Description

.dvf

Volatility data for 1 day horizon

.dcf

Correlation data for 1 day horizon

.mvf

Volatility data for 30 day horizon

.mcf

Correlation data for 30 day horizon

More information about these data sets is in the RiskMetrics Technical Document, available from the
RiskMetrics Web site http://www.riskmetrics.com.

3.3.4.1 Fetching the risk files
There are two ways of getting the risk files:

•

From their Web site, http://www.riskmetrics.com: Choose regular risk files, monthly and daily,
and copy them to the directory $FK_HOME/com/risk-metrics

•

From their FTP site. TRM provides a script to get the files from their ftp site:
$FK_HOME/share/risk-metrics/fetch-from-riskmetrics

Note: Getting the risk files is a step that can be run automatically by the import script. See below
for additional details.

3.3.4.2 Running the import script
The program $FK_HOME/share/risk-metrics/import-from-riskmetrics is the main tool to import
RiskMetrics data in TRM. It first fetches data from the RiskMetrics FTP site, evaluates the TRM
environment and then imports the volatility and correlation data in the corresponding VaR scenario
(by default, the default VaR scenario).
The following options are recognized by the program:
Option

Description

-h 

TRM home directory

-i, I, e, f <>

Usual TRM environment arguments

-s

Skips fetching of data via FTP

40

© Wall Street Systems IPH AB - Confidential

3 Interfaces with other tools
3.3 Value-at-Risk Interface

Option

Description

-u,p,l,d <>

Arguments for connection to FTP site (see below)

-y

Imports yield volatility for IR market (default is price volatility for all market data)

-U 

Database login

-P 

Database password

-c 

Scenario name

-z 

Data file type:
•

""tarZ" : use RMD.tar.Z and RMM.tar.Z

•

""zip" : uses RMD.zip and RMM.zip

•

"If -z is not used, then it imports from *.dvf, *.dcf, *.mvf, and *.mcf.

-r

Removes all data files after the import process

-v

Verbose

Examples:
Importing data (from RMM.zip and RMD.zip) in the default VaR scenario:
$FK_HOME/share/risk-metrics/import-from-riskmetrics -h /usr/wss/v7 -e fk7_1_env
-s -v -z zip
Importing data (from .dvf, etc…) in the default VaR scenario:
$FK_HOME/share/risk-metrics/import-from-riskmetrics -h /usr/wss/v7 -e dev1 -s -v
Importing data (from RMM.tar.Z and RMD.tar.Z) in a user specific scenario:
$FK_HOME/share/risk-metrics/import-from-riskmetrics -h /usr/wss/v7 -e dev1 -s -v
-U user -P passwd -c "TEST SCENARIO" -z tarZ
Notes:

•

The import of RiskMetrics data in TRM is a lengthy process: about 20-30 minutes for a typical
data set (volatility and correlation, 1-day and 1-month horizon).

•

Once ran, check that the correlation and volatility date exist in VaR Data Board.

3.3.5 Importing FEA data to TRM
The FEA (Financial Engineering associates) http://www.fea.com/ publishes data on the Web in the
form of compressed files (zip or tar) for both UNIX and Windows environments.
Program ‘import-from-fea’ is the main tool to import FEA data in TRM. It expects data to be present
either as *.zip or *.txt, and then imports the data in TRM. The program takes the following
arguments:
Option

Description

-h 

TRM home directory

-i,I,e,f <>

Usual TRM environment arguments

-y

imports yield volatility (default is price vol.)

-U 

Database login

-P 

Database password

-c 

Scenario name

-z 

Datafile type ("zip"). If -z is not used then it imports from *.txt

TRM System Administration Guide

41

3 Interfaces with other tools
3.3 Value-at-Risk Interface

Option

Description

-r

removes all data files after import process

-R

removes data files and compressed file after import process

-m

only import data for which a mapping exists in given scenario

-v

Verbose

Examples:
Importing data from text file in the default scenario:
$FK_HOME/share/risk-metrics/import-from-fea –h /usr/wss/v7 -e test -r -y -v
Importing data from a zip file in a user specific scenario:
$FK_HOME/share/risk-metrics/import-from-fea -h /usr/wss/v7 -e test -r -y -v -c "TEST
SCENARIO"

3.3.6 VaR horizon
To set up a horizon other than the default horizons (1 day and 1 month), use the procedure
CommitVaRHorizon. For example, to set up a horizon of 10 days which interpolates between 1 and
30 days, run:
CommitVaRHorizon @id = 10,
@scenario_id=1,
@id_1 = 1,
@id_2 = 30,
@name = "10 Day VaR Horizon"

3.3.7 Other scripts
The scripts described in this section are mainly for illustration purposes. They should not be run if
the main import script was run:
$FK_HOME/share/risk-metrics/import-from-riskmetrics.
These scripts are actually called by the main import script.

3.3.7.1 Fetching RM data via FTP
The program $FK_HOME/share/risk-metrics/fetch-from-riskmetrics fetches the RiskMetrics
data via FTP. The arguments of this program are as follows:
Option

Description

-h 

FTP site (ftp.riskmetrics.com by default)

-u 

FTP site user login

-p 

FTP site user password

-l 

Remote directory on FTP site

-a

Passive mode

-d

Debug mode

-v

Verbose



List of files to fetch

Example:

42

© Wall Street Systems IPH AB - Confidential

3 Interfaces with other tools
3.3 Value-at-Risk Interface

$FK_HOME/share/risk-metrics/fetch-from-riskmetrics -h datomatic.com -u trema -p
pass12 RMD.zip RMM.zip

3.3.7.2 Importing volatility and correlations routine
The programs $FK_HOME/share/risk-metrics/import-volatilities and
$FK_HOME/share/risk-metrics/import-correlation are used by the main import script. These
programs can be run separately and both programs have the following arguments:
Option

Description

-u 

Owner of scenario

-h 

The time horizon, '1' for the daily data and '30' for the monthly data.

-y

Imports daily volatility (price vol by default)

-d 

Date, if different from what is in the file.

-s


Scenario ID.

-r

Fetches data for mapped variables only.

-v

Gives some feedback of the process.



RiskMetrics data file to import.

The data is read from the files in command line, or from the standard input.
Note: If no scenario is specified, data are imported in the default VaR scenario. When a scenario is
specified, only the owner of the scenario can import data.
Examples:
Importing 1-day volatility data in default VaR scenario:
$FK_HOME/share/risk-metrics/import-volatilities -h 1 -v 20011231.dvf
Importing 1-month volatility data (yield volatility) in user "trema" specific VaR scenario, "TEST
SCENARIO":
$FK_HOME/share/risk-metrics/import-volatilities -u trema -y -h 30 -s "TEST
SCENARIO" -v 20011231.mvf

TRM System Administration Guide

43

3 Interfaces with other tools
3.4 Prices import - Import Market Information Activity

3.4 Prices import - Import Market Information Activity
The TRM activity Import Market Information allows you to import rates from generic CSV files. This
section describes how to set it up.
You access the Import Market Information activity from the Activity Manager application (from TRM
Application Manager) as shown below:

The fields are explained in the TRM User Guide (search on Activity Parameters).

3.4.1 Import process
Consists of:
1. Identifying the list of files to be imported
2. Validating the files
3. Parsing the files.

3.4.1.1 Import files list
The list of import files is based on the contents of the Source Subdirectory field and the environment
variables FK_IMPORT_PRICES_DIR and FK_IMPORT_PRICES_PATTERN. The final path is constructed as
follows:
[FK_IMPORT_PRICES_DIR] Source Subdirectory [FK_IMPORT_PRICES_PATTERN]
If the Source Subdirectory field contains the full path from the root, then FK_IMPORT_PRICES_DIR is
ignored.

44

© Wall Street Systems IPH AB - Confidential

3 Interfaces with other tools
3.4 Prices import - Import Market Information Activity

If the path ends with name of a file (with or without wildcards), then FK_IMPORT_PRICES_PATTERN is
ignored.

Examples
V:\WSS\var\import\prices\examples contains three files: a.csv, aa.csv, and b.csv.
FK_IMPORT_PRICES_DIR=V:\ WSS\var\import\prices
FK_IMPORT_PRICES_PATTERN=*
If Source Subdirectory=

then files processed are:

V:\ WSS\var\import\prices\examples\a.csv

a.csv

examples

a.csv
aa.csv
b.csv

examples\

a.csv
aa.csv
b.csv

examples\a*

a.csv
aa.csv

3.4.1.2 Validating the files
Before the files are parsed, they are first validated. If errors are found then the activity fails.

3.4.1.3 Parsing the files
The following steps are performed during the import prices process:
1. All scenarios and subscenarios are fetched in order to provide a means of translating names into
system ids.
2. Before parsing every file, processes are verified if the FK_IMPORT_PRICES_VERIFY_PROCESSES
environment variable is set (see 3.4.2 Environment variables on page 46.
3. For each price (equivalent to a line in an input file):
a. If any Market Info is cached for the specified name_id and date, then MarketInfos are loaded
using FetchMarketInfoData for the specified date and name_id.
b. If Market Info is not found, then possible reasons are searched and logged, using the stored
procedure FetchMarketInfoDetail.
c. Enrich the price with data from previously loaded MarketInfos:
period_id, period_1_id, and period_2_id
name_id, and type_id (e.g. EUR/USD, FX-RATE resp.)
price type
scenario_id, subscenario_id

d. Enrich the price with the Scenario/Subscenario specified in the Activity parameters, if supplied.
e. Set the period from/to, if not provided in the input file, to the date of the price.
f.

A CSD hook can be called to modify the price before storing it to database. See 3.4.5 CSD
possibilities on page 48.

g. Store the price by calling PushMarketInfo.
h. Mark the price as pending using PushPendingPrice.
4. Verify that none of the processes has been restarted meanwhile; if so, the activity fails.

TRM System Administration Guide

45

3 Interfaces with other tools
3.4 Prices import - Import Market Information Activity

5. Call CSD hooks if required.
6. File is archived, based on environment settings (see FK_IMPORT_PRICES_ARCHIVE below).
Archiving moves the file to a subfolder with the name batch_ and
renames the file to _.

3.4.2 Environment variables
The following environment variables affect the behavior of the Import Market Information activity.

•

FK_IMPORT_PRICES_VERIFY_PROCESSES
Certain processes must be running during the import to ensure that the derived prices are
automatically recomputed. The required processes are: mdsd, transd, and micd. The verification
logic uses the mdsd.get_status() service to obtain a list of processes connected to the mdsd
bus. If any of the mentioned processes is not connected to mdsd, the activity fails. Note that by
default, the FK_IMPORT_PRICES_VERIFY_PROCESSES variable is set to verify.
Default: verify

•

FK_IMPORT_PRICES_DIR
Defines the path to the root directory for source directory where import prices files are located.
Default: %FK_VAR_DIR%\import\prices

•

FK_IMPORT_PRICES_BATCH_SIZE
The number of records (batch size) to be processed before the import price activity is suspended
for a time interval equal to FK_IMPORT_PRICES_SLEEP_MSECS. Both values must be non-zero for
the suspend mechanism to work. This helps to avoid overloading the mdsd and micd processes
with huge amounts of direct and derived prices.
Default: 0

•

FK_IMPORT_PRICES_SLEEP_MSECS
Price import is suspended for a time interval in milliseconds after a certain number of records
(batch size) specified in FK_IMPORT_PRICES_BATCH_SIZE. Both values must be non-zero for the
suspend mechanism to work. This helps to avoid overloading the mdsd and micd processes with
huge amounts of direct and derived prices.
Default: 0

•

FK_IMPORT_PRICES_PATTERN
Defines which import files are processed, unless overridden by the contents of the Source

Subdirectory field. See 3.4.1 Import process on page 44.
Default: *.*

•

FK_IMPORT_PRICES_ARCHIVE
The import file is archived in a subdirectory after processing, and is deleted from the import
directory. If FK_IMPORT_PRICES_ARCHIVE is not set, then archiving does not happen, and the
import file is left in the source directory.
Default: True

•

FK_IMPORT_PRICES_ALLOW_ERROR _LINES
’False’ means that if there is an invalid datasource, no bid/ask quote, or no date of quote
specified on the particular line in the csv file, a message with severity ERROR will be logged, and
the file will not be archived.
’True’ means that in the case of an invalid datasource, no bid/ask quote, or no date of quote
specified, only WARNING messages are logged and the file is archived as processed. A message
with severity ERROR is logged and the file is not archived only in the case of 'technical' issues

46

© Wall Street Systems IPH AB - Confidential

3 Interfaces with other tools
3.4 Prices import - Import Market Information Activity

such as missing permissions, no connection/access to the database and other non-source data
related issues that prevent saving the data to the database.
Default: False

3.4.3 Format of the import file
The format of each file in the import directory must conform to the CSV specification: the first line of
the file must contain names of the properties and the remaining lines must contain the data. There
are two types of properties that can be specified:

•

Query properties

•

Price data properties

3.4.3.1 Query properties
These are used to identify the Market Info record - the values are used to search for the appropriate
MarketInfo record. One of item or name_id (or both) must be specified; other values are optional.
Each row in the import file must uniquely identify exactly one record in MarketInfo table.
item

Identifier of the Market Info record. Mandatory if name_id is not provided.

name_id

Name of the instrument, currency pair, etc. Mandatory if item is not provided.

type_id

Type of instrument, for example IR-RATE, FX-RATE.

period_id,
period_1_id,
period_2_id

Price periods

source

Source name, as defined in the MarketInfoSource table, e.g. FILE, ECB, REUTERS.

date

The date (in MMDDYYYY format) to which the price applies.

3.4.3.2 Price data properties
These are the price details which would be stored in the database:
date

The date (in MMDDYYYY format) to which the price applies.

period_from, period_to

The date period (in MMDDYYYY format) to which the price applies.

price_1 … price_10

Price data.

bid (ask) …

Synonym for price_1 (price_2 etc.).

Note: All query properties must be properly filled. For example, empty columns are not ignored,
but MarketInfo is searched for condition "column"="", which can then cause activity
failure, because no MarketInfo record is found.

3.4.3.3 Example imports
Using Item:
Item

Source

Date

Bid

Ask

SAMPLE-BOND-GOVT-CA

FILE

01012000

20

21

USD1YD=

REUTERS

12312005

4.7

4.8

EURON=

REUTERS

11012008

0.8

0.9

TRM System Administration Guide

47

3 Interfaces with other tools
3.4 Prices import - Import Market Information Activity

Using name_id
Type_id

Name_id

Period _id

Source

Date

Bid

Ask

UM-PRICE

SAMPLE-BOND-GOVT-CA

SPOT

FILE

01012000

20

21

IR-RATE

USD-DEPO/SWAP

SPOT

REUTERS

12312005

4.7

4.8

FX-RATE

EUR/USD

O/N

REUTERS

11012008

0.8

0.9

Using unsupported format of FILE
Type_id

Name_id

Period _id

UM-PRICE

SAMPLE-BOND-GOVT-CA

SPOT

IR-RATE

USD-DEPO/SWAP

FX-RATE

EUR/USD

Item

Source

Date

Bid

Ask

FILE

01012000

20

21

SPOT

12312005

4.7

4.8

O/N

11012008

0.8

0.9

The special source FILE is used for identifying Market Info definitions created for import via activity.
They can differ - for instance by scenario - from standard Market Info definition for source REUTERS.
If there are multiple definitions of Market Info for the same price that differs by source, then it is
necessary to distinguish between them using FILE, otherwise the activity could find two valid Market
Info definitions and it would fail.

3.4.4 Permissions
The process verifies permissions for the user that scheduled the activity. The permission checked is
for object=UpdatePrices and the permission verified is defined in the scenario or subscenario
relevant to the activity (Scenario Editor, Permission field).

3.4.5 CSD possibilities
Some CSD hooks exist in order to allow modification of prices prior to calling PushMarketInfo,
verification of processes, imported prices etc. All CSD hooks are located in csd.py. If an exception is
thrown, the importing process is terminated and the activity fails.

CSD Class
Name

Comment

__init__

One instance of this class is created at the beginning of import.
CSD logic can be implemented in either the constructor (initialization) or
in the methods.

preprocessPrice

Called for every price after the price has been enriched by market info
data. Price can be liberally modified in this hook.

postprocessPricess

Called at the end of importing of one file, after all prices has been
successfully imported.

verifyProcesses

This function should return True, if processes (micd, mdsd, transd)
should be verified (FK_IMPORT_PRICES_VERIFY_PROCESSES is set). If
processes should not be verified (environment variable
FK_IMPORT_PRICES_VERIFY_PROCESSES not set), it returns True
without checking the processes.
Business logic can be liberally changed here.

48

© Wall Street Systems IPH AB - Confidential

3 Interfaces with other tools
3.4 Prices import - Import Market Information Activity

Name

Comment

verifyProcessesBeforeImport

Called at the beginning of processing before any file is read.
The provided dictionary contains keys: transd, micd. The value under the
key contains result of the mdsd.get_status() call, that is, info usually
obtainable using the md-status utility, or None if no such process is
running.
The return value should be of type boolean:
•

Returning True means the processes are fine and default verification
should be omitted.

•

Returning False (default) means default verification should take
place.

Throw whatever exception to terminate the process and fail the activity if
the verification fails.

verifyProcessesAfterImport

Called at the end of processing after all files have been imported.
The provided dictionary contains keys: transd, micd. The value under the
key contains result of the mdsd.get_status() call, that is, info usually
obtainable using the md-status utility, or None if no such process is
running.
The return value should be of type boolean:
•

Returning True means the processes are fine and default verification
should be omitted.

•

Returning False (default) means default verification should take
place.

3.4.6 Validation of Imported Prices
In a market datastream like the Reuters interface, prices are updated continuously, which means
should a price be discarded for some reason, it is not critical since an update will soon be received.
In the price import activity, typically a price is only imported once it is critical that a price discard is
reported. The procedure FetchMarketInfoDetail is used to acquire additional information when:

•

There is no market information found for the name_id or item provided.

•

There is market information found for name_id or item but other fields in the imported line do
not match.

The activity then displays each candidate with the following additional information:

•

Disabled Market Info

•

Inactive Market Info

•

Inactive Instrument Quote

•

Inactive Currency Journal.

Also, the currently processed price and the import file line, along with the corresponding line
number, are printed out when the following errors occur:

•

Scheduling of price recalculation has failed.

•

Calling PushMarketInfo returns a non-zero code.

•

The user does not have object permission to UpdatePrices.

•

Calling GetMarketInfoId returns a non-zero code or does not fetch any data.

3.4.6.1 CSD validation
It is not possible to identify following problems and a CSD must be used where necessary:

TRM System Administration Guide

49

3 Interfaces with other tools
3.5 Using comKIT

Error message if the date is not between issue_date and maturity_date
This must be handled in the CSD hook preprocessPrice. The Import Market Information activity
detects this situation only if valid_ from and valid_to dates on the quote tab are properly set
based on the maturity date and issue date of the instrument.
However, when a price is imported for an instrument after its maturity or before its issue_date, it
does not cause any problems in the system and the price is not used.

Error message if the "Calculated price" related to imported price has not stored
There is no simple link between direct (imported) price and derived (calculated) price, and therefore
the activity cannot verify that all possible derived prices are correctly calculated and stored.
However, there are mechanisms in the activity to check running processes in several places, to slow
down the importing of prices so that subsequent processes are not overloaded and can handle all
recalculation and storing of prices. Also a user-specific check can be performed that specific prices
were recalculated in the CSD hook postprocessPricess.

3.5 Using comKIT
3.5.1 Overview
Note: You can find HTML comKIT documentation in FK_HOME\support\comKIT\doc.
comKIT enables TRM to be run using an API instead of the traditional GUI. More specifically, comKIT
is a programmable interface that hides the details of the implementation and offers support for high
level objects (Business Objects) that make sense on the business side of TRM. CORBA is used to
expose methods and data to the programmer via interfaces defined in IDL. JacORB is supported for
Java interfaces. The IDL interfaces are the starting point for comKIT. These IDL files describe what
can be done using comKIT. IDL compilers exist for the most common programming languages and
these are used to generate classes.
comKIT makes importing transactions easier, since comKIT uses the same underlying software as
the transaction manager GUI to enter transactions; the calls you make in comKIT map directly to
the operations you would do in the Transaction Manager to enter a deal.
So, if a user with financial knowledge shows an interface programmer how a deal is entered in
transaction manager, it is quite easy to program the same using comKIT. There are no workarounds
and mappings to be implemented as with the cvt procedures.
Information on setting up comKIT is available in Chapter 12 Setting up comKIT on page 205.

3.5.2 comKIT services
The comKIT toolkit is made up of the following services:

•

Settlement service

•

Position service

•

Static Data service

•

Transaction service

•

Performance service

Each service provides access to a area of TRM functionality. In most cases, each area corresponds to
a TRM application: for example, the Position service provides access to the features you find in
Treasury Monitor. There is a direct correspondence between the manner in which you work with a
TRM application and the way you make programming calls to the relevant comKIT service. For this

50

© Wall Street Systems IPH AB - Confidential

3 Interfaces with other tools
3.5 Using comKIT

reason, it is highly recommended that you become familiar with the TRM application and interface
for any service you plan to use.

TRM System Administration Guide

51

3 Interfaces with other tools
3.5 Using comKIT

52

© Wall Street Systems IPH AB - Confidential

Chapter 4

Using Import Export tool

4.1 Introduction
The Import Export Tool application aims to make a standard interface tool available which can be
used as a base for all types of data transfers.
This tool provides:

•

A consistent approach - making all interfaces look similar gives ease of use and maintenance.

•

Reduced development time - many small issues are supported automatically.

•

Ease of use - helps the developer to get at the available data more easily by having built-in
extensible functionality.

Import Export tool has been developed as a shell using the Perl language. The advantages of this
approach are:

•

Rapid prototyping

•

Inbuilt data conversions and pattern matching

•

Existing TRM interfaces for database access

•

Part of the standard TRM release

•

Object-oriented approach for hierarchical design and extensibility for newer methods

4.2 Features
The basic shell of Import Export tool provides the following features:

•

Formatting templates for data input (import) and output (export)

•

Database interface that allows the calling of stored procedures for either export or import

•

Data formatting including formats such as SWIFT Money

•

Callback hooks for pre-processing of data and post-processing of output for export and import

•

Automated unique file naming for file based output

4.3 Structure of the Import Export tool
When exporting data from TRM using Import Export tool, a stored procedure is used to extract the
data from the database. Each row returned from the stored procedure contains directly or indirectly
one data set for the output. This data set might contain all data to output, or it might be used for
input to routines in the perl package, which calculate the data to output.
When importing data, the stored procedure takes data from the input file and enters the data into
the TRM database.

TRM System Administration Guide

53

4 Using Import Export tool
4.4 Importing data

When setting up the Import Export Tool for your specific data requirements, it is recommended to
use additional stored procedures rather than modifying the Perl package (i.e., adding new Perl
classes) if possible, for performance reasons. Please refer to your SQL reference for details on how
to write stored procedures.

4.3.1 File organization and inheritance
Templates, formats, and variables are defined in a definition file with extension .def.
The Perl code is put into a Perl class file, a file with extension .pm. The base part of both file names
must be the same. This name is the name of the import/export function.
If the interface is derived from another interface, a new subdirectory must be created, whose name
is that of the parent interface. For example, an interface XYZ derived from an interface called
''Payment'', which itself is derived from an interface called MYINTERFACE must have the following
file and directory structure:
MYINTERFACE.def
MYINTERFACE.pm
MYINTERFACE/
MYINTERFACE/Payment.def
MYINTERFACE/Payment.pm
MYINTERFACE/Payment/
MYINTERFACE/Payment/XYZ.def
MYINTERFACE/Payment/XYZ.pm
The corresponding Perl classes would be:
MYINTERFACE
MYINTERFACE::Payment
MYINTERFACE::Payment::XYZ
The Perl class files are not mandatory; if it is possible to define everything within the
template/stored procedures framework then you can leave out some of the Perl files and only have
the definition file. Template files are provided in the TRM package in $FK_HOME/share/interface.

4.4 Importing data
The basic principle of importing data is that the input data are compared on a row-by-row basis to
the template (header, body, and trailer). When there is a match, the regular expression engine picks
up the provided fields and puts them into an array of records. After all the records have been
successfully read, stored procedure calls are constructed for each record. Finally, these stored
procedure calls are executed.
The types of all fields must be defined because, at import time, the data types are not available from
the database.
Regular expressions are generated automatically from the template and format definitions. It is
possible, though, to override the default regular expression. This may be useful if performance is
bad with the default expression.
Once the records have been parsed, the construction of the stored procedure calls is simple. For
example, if one record has the fields number and reference with the values 766 and 'TII'
respectively, and the import procedure has the value UpdateReference, the procedure call would
be:
For Microsoft SQL Server and Sybase:
exec UpdateReference
@number = 766,
@reference = ''TII''

54

© Wall Street Systems IPH AB - Confidential

4 Using Import Export tool
4.5 Definition file (.def)

For Oracle:
var r number
exec :r := HelpObjectPermission(pobject_id => 'aaa');
UpdateReference( Pnumber => 766,
Preference => 'TII');
Note that we must define the data type of the number field to be integer in the format section of
the .def definition file. (See 4.5.4 Format on page 59.) Otherwise, it will be interpreted as a string
and thus enclosed in quotes.

4.5 Definition file (.def)
Definition files define the layout of the imported/exported data files with templates (header, body,
and trailer) and the data structures used with formats and variables.

4.5.1 Templates
Templates are used to define the layout of the data file; the position of the actual data items relative
to one another and to other parts of the data file.
There are three sections in each template: header, body and trailer. There can be many different
definitions of each of these three types and it is possible to choose the correct one in the database
query or in the Perl hook functions.
The header and trailer definitions are each evaluated once only in each data transfer, at the
beginning and the end of the transfer, respectively. The body definition is evaluated for each row of
data that comes from the export query. When files are imported, the template is used to construct
regular expressions that will match into the input.
The header template sections are delimited by:
BEGIN HEADER []
....
END HEADER []
The body sections by:
BEGIN BODY []
....
END BODY []
The trailer sections:
BEGIN TRAILER []
....
END TRAILER []
where the optional  parameter specifies the name of the template if there are multiple
header, body or trailer template sections.

4.5.2 Layout syntax of the template
The layout of the header, body or trailer is described by 'example': the data is written as it will
appear in the imported/exported file, with all fill characters and line breaks, except that actual data
is replaced by variables. Variables are marked by a variable name surrounded with curly brackets
('{, }').
A sample header definition looks like this:
BEGIN HEADER
Risk metrics data from {date}
END HEADER

TRM System Administration Guide

55

4 Using Import Export tool
4.5 Definition file (.def)

where the header in the file looks like:
Risk metrics data from 1999-04-23
At import time, the header is parsed, and the variable date is matched to '1999-04-23'.

Note: Remove trailing white space everywhere in layout definitions for importing data. The

sensitive matching process tries to match every single character in the template to the
data in the file.

4.5.2.1 Header
If the data file has a header before the start of the actual data section, the layout of this header has
to be defined. The header section of the template file defines the layout of this header. It is parsed
and read/written once. If the data file has no header, the header part in the template file should be
omitted.
There may be several layout definitions for the header. The correct template is chosen according to
the value of the variable template. This variable can either be given on the command line, in the
stored procedure, or it may be set in the Perl package. In the Perl package, it is the variable
$row->{template} that is set accordingly. In the stored procedure, an additional column with the
name template has to be returned (e.g. select template = TemplateName).
In the definition file, each of the headers would be defined with a specific name; for example:
BEGIN HEADER TemplateName
....header layout definition ....
END HEADER TemplateName

4.5.2.2 Body
The body section defines the layout of the main data in the data file which is to be imported or
exported. It defines the layout of one data set, one row in the database. It will be parsed for every
row.
There may be several layout definitions for the body. The template used is chosen according to the
value of the variable template. As described for the header above, this variable can either be given
on the command line, in the stored procedure, or it may be set in the Perl package. In the Perl
package, it is the variable $row->{template} that is set accordingly. In the stored procedure, an
additional column with the name template has to be returned (e.g. select template =
TemplateName).
BEGIN BODY TemplateName
....body layout definition ....
END BODY TemplateName

4.5.2.3 Trailer
If the data file has a trailer after the actual data section, the layout of this trailer has to be defined.
The trailer part of the template file defines this layout of the trailer. It is parsed and read/written
once. If the data file has no trailer, the trailer section in the template file should be omitted.
As for both the header and body sections, there may be several layout definitions for the trailer. The
template used is chosen according to the value of the variable template. This variable can either be
given on the command line, in the stored procedure, or it may be set in the Perl package. In the Perl
package, it is the variable $row->{template} that is set accordingly. In the stored procedure, an
additional column with the name template has to be returned (e.g. select template =
TemplateName).
BEGIN TRAILER TemplateName
....trailer layout definition ....

56

© Wall Street Systems IPH AB - Confidential

4 Using Import Export tool
4.5 Definition file (.def)

END TRAILER TemplateName

4.5.2.4 Body template
The following is an example of a body template (SWIFT MT210):

BEGIN EXPORT VARIABLES
procedure=ListBatch
END EXPORT VARIABLES
BEGIN HEADER HEAD1
REC-01 Table Batch {rundate}
END HEADER HEAD1
BEGIN BODY
REC-02 {id};{date};{type};{user_id};{comment}
END BODY
BEGIN TRAILER TRAIL1
REC-09 total records {count}
END TRAILER TRAIL1
BEGIN FORMAT
id {
absolute:no
type:integer
length:10
leading_zeros:yes
}
type {
type:character
length:50
alignment:left
}
date.time_format:MM/DD/YYYY
user_id {
type:character
length:30
alignment:right
}
step.type:integer
END FORMATedure=ListBatch

4.5.3 Variables
Two types of variables can have values assigned to them:

•

Built-in variables like import/export file names and debug switches

•

Parameters of the stored procedure calls can have values assigned to them.

A full list of the built-in variables available is given in 4.5.3.5 Built-in variables on page 59.

TRM System Administration Guide

57

4 Using Import Export tool
4.5 Definition file (.def)

Variable names can contain characters, digits and '_' ([a-zA-Z0-9_]). Parameters to stored
procedure calls always start with an @ sign. There can be any amount of white space anywhere in
variable assignments. If a variable is assigned more than once, then the last assignment is used.

4.5.3.1 Definition of variables
Variables can be assigned in the definition file and also on the command line. In addition, certain of
these variables can have values stored in normal environment variables. If variables are defined in
several places, the order of evaluation is as follows (from most dominant to least dominant):

•

Command line variables

•

Export/import variables in .def files

•

Common variables in .def files (apply to both import and export)

•

Environment variables

Variables can be assigned for export only, import only, or for both (common variables).

4.5.3.2 Command line variables
On the command line, variables are appended to the stored procedure command, separated by
space, as the following example shows:
On UNIX:
./interface MYINTERFACE::Payment::XYZ export @flags=2 @portfolio_id=\'TOP\ '
On Windows:

perl Interface MYINTERFACE::Payment::XYZ export @flags=2
@portfolio_id=TOP
Note: On UNIX, quotation marks must be preceded with backslashes to prevent expansion by the
shell.

4.5.3.3 Variables section in .def file
Variables or stored procedure parameters that are defined in the .def files exist in their own
sections. Variables that apply for both import and export are delimited by
BEGIN VARIABLES
variable=value
variable=value ....
END VARIABLES
Variables that apply for import only:
BEGIN IMPORT VARIABLES
variable=value
variable=value ....
END IMPORT VARIABLES
Variables that apply for export only:
BEGIN EXPORT VARIABLES
variable=value
variable=value ....
END EXPORT VARIABLES

4.5.3.4 Syntax of environment variables
Environment variables are of the form $FK_IMPORT_variable and $FK_EXPORT_variable for
import and export respectively. For example:
On UNIX (Bourne shell):

58

© Wall Street Systems IPH AB - Confidential

4 Using Import Export tool
4.5 Definition file (.def)

set $FK_IMPORT_variable=value; \
export $FK_IMPORT_variable
On UNIX (C shell):

setenv $FK_IMPORT_variable value
On Windows:
set FK_IMPORT_variable=value
If environment variables are used, the most appropriate location to set these variables is in the TRM
system environments, which are defined in $FK_HOME/share/environments.

4.5.3.5 Built-in variables
There are several built-in variables, described in the following table:
Variable

Description

procedure

Name of the SQL stored procedure to use in export or import to extract or insert the data,
respectively.

@parameter1,
@parameter2

Possible default parameters for the stored procedure. They always start with @.

dir

Specifies the directory in which the export file is created or from which the import file is
read.

file

Specifies the name of the export or import file. If the name is undef (the default), the
filename is the current date plus a unique number 01..99 in the format: YYYYMMDDnn.
For example, 1999101702, would be the second file created on 1999/10/17.

ext

Extension of input/output file name. Default is .exp for export files and .imp for import
files. Can be with or without the dot, i.e. ".dat" and "dat" are both accepted and will
result in ".dat" being appended.

filter

Name of the program used to post process the export output. Could be a printer
command or xform, for example.

view_file

If set to 1, every row will be printed to STDOUT as well as to the file.

debug

If set to 1, every procedure call will be printed to STDOUT and nothing will be executed.
Default is 0.

line_terminator

Character or string used to separate lines in the exported file. A typical use is to set
line_terminator to CRLF (line_terminator = \r\n). To set line_terminator to an empty
string (or remove linefeeds) use line_terminator = ''.

empty_output

Output file is opened and header and trailer are written even if no data is returned from
the database query. Possible values yes and no.

my_own_variable

You can define your own command-line variables.

4.5.4 Format
The format part of the definition file defines the data types used in the Import Export Tool.

Note: It is very important to specify the data types of the variables used as exactly as possible.
Import Export Tool internally generates regular expressions for each data type and
matches these regular expressions to the imported and exported data respectively.

The format section is delimited by:
BEGIN FORMAT
....
END FORMAT

TRM System Administration Guide

59

4 Using Import Export tool
4.5 Definition file (.def)

4.5.4.1 Data type definitions
Every variable used in the body section of the template file has to have a data type associated with
it. This data type may be one of the pre-defined basic or built-in data types or may be defined by
the user in the format section of the template file.
There are two ways to write format definitions: by using curly brackets to group keywords for a
particular field/type or to use the field.keyword notation:
type_name {
type: value
format option: value
format_option: value
.....
}
or
variable_name.format_option: value
For example, to set the length and alignment of the field number, write:
number {
length: 16
alignment: left
}
or
number.length: 16
number.alignment: left
A user-defined data type may have any number of associated format options; user defined data
types build on existing data types and inherit all the format options of the type they are building on.
Any format option can however be overwritten by explicitly redefining it.

4.5.4.2 Predefined data types
There are a number of built-in and predefined data types. In the following table, these data types
are described and the regular expression which is internally created is shown.
Data type

Regular expression

integer

(\d*?)

float, money

([\+\-\d$decimal_separator$fill_character]*?)
(swift): ([\+\-\d,$fill_character]*?)

datetime
character

Any digit in the time_format string is matched with \d.
(.*?fill_character)

4.5.4.3 Format options of data types
The following format options can be used to describe the data types:
Formatting
keywords

Description

absolute

Converts integer, float or money values to their absolute value. Possible values are yes
and no.

alignment

Specifies whether the formatted value is shown in the left or right end of the field (left
or right aligned), if the maximum field length exceeds the length of the formatted
value. If omitted, no alignment occurs. Possible values are left and right.

60

© Wall Street Systems IPH AB - Confidential

4 Using Import Export tool
4.5 Definition file (.def)

Formatting
keywords

Description

fill_character

Character used to fill fixed-length fields, if the maximum field length exceeds the length
of the formatted value. To fill in spaces one has to enclose the space character in single
quotes, i.e. ' '.

decimal_separator

Specifies the character (sequence) used as decimal separator for float and money
types. To specify empty string one has to use single quotes, i.e. '', or use the undef
keyword. If the swift_format option is yes this option will be overridden.

thousand_separator

Specifies the character (typically point, comma, or space) to separate adjacent 3 digit
sequences in the integer part of a number, e.g. 1,000,000.00. To have spaces one has
to enclose the space character in single quotes, i.e. ' '.

precision

Specifies the decimal precision of money and float types. Possible values are
non-negative integers. If precision is zero, the decimal_separator will not be shown. If
the swift_format option is yes this option will be overridden.

leading_zeros

Specifies whether zeros will be prepended to a number value if the maximum field
length exceeds the length of the formatted value. This is equivalent to setting
fill_character to 0 and alignment to right, but for negative numbers the output is
different. For instance, -100 would be displayed as -0000100 using the leading_zeros
approach and as 0000-100 using the fill_character approach.

swift_format

Specifies whether the money or float value will be displayed according to the SWIFT
standard (numbers will be shown without sign, comma as the decimal separator and
without thousand separators). Possible values are yes and no.

time_format

Specifies the format of dates and times for datetime types. Possible values are:
YYYY - year in four digits
YY - year in two digits
MM - month in two digits (01, 02, 03, ... ,12)
M - month in one or two digits (1, 2, 3, ..., 12)
DD - day of the month in two digits (01, 02, 03, ..., 31)
D - day of the month in one or two digits (1, 2, 3, ..., 31)
hh - hours
mm - minutes
ss - seconds
For example, to get a date/time like 1998/12/24 13:30, write YYYY/MM/DD hh:mm.

length

Specifies the maximum length of the field. If the formatted value is longer then the
maximum field length, the value will be truncated. If it is shorter that the maximum
field length, it gets padded with the fill character.

case

Specifies whether character type values should be shown in upper, lower or mixed case.
Possible values are upper and lower. To get mixed case one must use undef.

type

Data type of the variable. This can be either one of the basic or built-in types (character,
integer, float, datetime, money) or a customized data type.

key_of

Specifies the name of the database table which the field is a key of. This enables the
use of the dot notation to access database table fields. Possible values are Client,
Portfolio, Instrument and Equity.

regexp (import)

With this option you can specify the regular expression to be used for internal parsing.
This option overrides the automatically created regexp. This option should be used as
an exception, only when the internal regexp generation does not work sufficiently. Do
not use, unless you know exactly what you are doing.

TRM System Administration Guide

61

4 Using Import Export tool
4.6 Perl functions (the Interface class)

4.6 Perl functions (the Interface class)
The Interface class allows complex logic to be included in the interface. If the templates and
formatting parameters are not expressive enough to create the specified output, additional logic
using Perl functions can be written (for instance, if some part of the template should not be
displayed depending on a certain condition in the input data).
The recommended approach to add this logic is to derive a new Perl class that inherits the
TemplateInterface class. (See 4.11 TemplateInterface class on page 67.) The TemplateInterface
class is a subclass of the Interface class.

Note: For performance reasons, it is generally recommended to use stored procedures as much
as possible rather than defining new classes.

The structure of a new subclass looks as follows:
package PACKAGENAME;
use TemplateInterface;
@ISA = qw (TemplateInterface);
sub new {
my ($class, @templates) = @_;
my $this = new TemplateInterface (@templates);
bless $this, $class;
return $this;
}
The new class can define so-called hook functions that can be called at certain stages in the process
of file creation to manipulate the incoming and outgoing data before and after parsing. Basically, the
hook functions can manipulate either the raw database input (start functions) or the formatted
output (finish functions).

4.6.1 Export hook functions
4.6.1.1 Start functions
export_header_start ($row)
export_body_start ($row)
export_trailer_start ($row)
These functions are called before the database query row is evaluated against the template. The
$row parameter is a reference to a hash containing name-value pairs that come from the query. It is
possible to change the existing row values and set new ones by using normal assignment.
A special feature is that one can specify the template to be used by setting $row->{template} to
the name of the required template. If, for some reason, the whole row should be excluded from
further processing, this can be achieved by returning the string ‘skip’ (return ‘‘skip’’;) from
the function export_body_start(). Other return values are ignored.
Here is an example of a start hook function that sets the template and some other fields and ignores
some rows.
sub export_body_start {
my ($this, $row) = @_;
if ($row->{layout} eq "MM") {
$row->{template} = "XYZ";
} elsif ($row->{layout} eq "FX") {
$row->{template} = "ABC";
} else {

62

© Wall Street Systems IPH AB - Confidential

4 Using Import Export tool
4.7 External packages: predefined modules

return "skip";
}
$row->{count} = $count++;
}

4.6.1.2 Finish functions
export_header_finish ($output)
export_body_finish ($output)
export_trailer_finish ($output)
These functions are called after the template has been evaluated. The $output parameter is a
reference to the resulting output string. For instance, to remove new lines from the output one
would write:
$output =~ s/\n//g;

4.6.2 Import hook functions
4.6.2.1 Start functions
import_header_start ($input)
import_body_start ($input)
import_trailer_start ($input)
These functions are called before the input is matched against the appropriate templates (header,
body, trailer). The templates are tried in such an order that the one with least number of lines is
first. Generally it is not possible to say how many times these functions are called, it might be only
once or it might be as many times as there are templates.
If, for some reason, the whole row should be excluded from further processing, this can be achieved
by returning the string ‘skip’ (return ‘‘skip’’;)from the function import_body_start(). Other
return values are ignored.

4.6.2.2 Finish functions
import_header_finish ($params)
import_body_finish ($params)
import_trailer_finish ($params)
These functions are called after the input has been matched against a template. If the match was
successful, the $params variable contains a reference to the resulting name-value pairs. If the
match was not successful, $params will be undef.

4.6.3 Overriding default functions
It is, of course, possible to override any of the functions defined in the Perl classes Interface and
TemplateInterface (see 4.10 Interface class on page 65 and 4.11 TemplateInterface class on page
67).

4.7 External packages: predefined modules
Four predefined Perl modules are available for Import Export Tool. Each of the modules corresponds
to a table in the TRM database with the same name.
First, the variable used in the body part of the template file contains an extra element, the name of
the key used to index the external table, in addition to the variable name in that table.

TRM System Administration Guide

63

4 Using Import Export tool
4.8 Running Import Export tool

BEGIN BODY
name_of_key.variable_name
END BODY
The first part is the name of the key used for indexing the respective table; the second part is the
field name from that table.
Secondly, in the format part of the definition (.def) file, the key is associated as a key of a table by
the following syntax:
BEGIN FORMAT
name_of_key.key_of: NameOfPredefinedModule
variable_name.type: type_name
END FORMAT
The variable itself must also be associated with a data type.

4.8 Running Import Export tool
4.8.1 Running from the command line
To run Import Export tool from the command line after an environment evaluation:
On UNIX:
cd $FK_HOME/share/interface/
interface  (import|export) [name=value ...] [@name=value ...]
On Windows:
cd %FK_HOME%\share\interface
perl Interface  (import|export) [name=value ...] [@name=value ...]
where:

•

 is the interface you have set up

•

(import|export) - choose the direction of the data transfer

•

[name=value ...] - to specify one of the built-in variables. (See 4.5.3 Variables on page 57.)

•

[@name=value ...] - to specify a stored procedure parameter variable.

For example, to export MYINTERFACE XYZ payments, use the following:
On UNIX:
./interface MYINTERFACE::Payment::XYZ export @portfolio_id='TOP'
On Windows:
perl Interface MYINTERFACE:Payment::XYZ export @portfolio_id=TOP
To import fx-match statements you could use:
On UNIX:
./interface FXMATCH import @file='/tmp/fxmatch.txt'
On Windows:
perl Interface FXMATCH import @file=/tmp/fxmatch.txt

64

© Wall Street Systems IPH AB - Confidential

4 Using Import Export tool
4.9 Debugging

4.8.2 Methods of script execution
Running Import Export tool can be achieved in several different ways with TRM:

•

Manually: on the command line as shown above.

•

Repeatedly: via crontab (UNIX). For example every hour:
10 * * * * ./interface FXMATCH import @file='/tmp/fxmatch.txt'

•

From Money Transfer Method Editor in TRM:

Define a new method in Money Transfer Method Editor: give a unique id and method name in the
ID and Method fields, and the required command in the Command field (for example the XYZ END
FORMAT payments example shown above). The method can now be used automatically for
exporting payments. The batch_id is appended as command-line variable and can thus be used in
Import Export Tool to export the payments to a file and/or to screen.

4.9 Debugging
To debug an interface, use the following command:

•

On UNIX: fk-perl -d ./interface  {import|export}

•

On Windows: perl -d Interface  {import|export}

and then
c 52
to continue to line 52. From here, it is possible to set breakpoints in your own .pm file. For example:
b MYINTERFACE::Payment::XYZ::export_body_start
sets a breakpoint in the subroutine export_body_start in the XYZ class, which is a subclass of the
MYINTERFACE class.

4.10 Interface class
An abstract class from which all import and export interfaces are derived. Defined in the file
Interface.pm.

TRM System Administration Guide

65

4 Using Import Export tool
4.10 Interface class

4.10.1 Interface class functions
Function

Description

init

Initialize.

find_package

Return the most specific class that is defined @param @packages list of packages.
•

package_split

Returns: the most specific one or undef if not found

Split package name to an array of package names.
For example, $this->package_split ("abc::def::ghi") would return
("abc::def::ghi" "abc::def" "abc").

package_to_file

file_exists

default_file_name

pad_right

pad_left

swift_amount

•

Parameters: package - name of the package

•

Returns: list of packages

Construct Perl .pm file name from a package name.
•

Parameters: package - name of package

•

Returns: file name

See if a file exists in the include path.
•

Parameters: name - name of the file

•

Returns: the full file name if found, otherwise undef

Return the default file name YYMMDDNN, where YY is the current year, MM is the current
month and DD is the current day. NN is an increasing sequence number for files with the
same date, 01 for the first file.
•

Parameters: dir - directory; ext - extension

•

Returns: file name (without directory and extension)

Add pad characters to the right of a string or truncate it.
•

Parameters: value - input string, width - width of the output string, pad - pad
character

•

Returns: result

Add pad characters to the left of a string or truncate it.
•

Parameters: value - input string, width - width of the output string, pad - pad
character

•

Returns: result

Format amount in SWIFT format.
•

Parameters: amount - unformatted amount

•

Returns: formatted amount

4.10.2 Interface member functions
Function

Description

new

Constructor.

process_args

Store command line arguments.
Arguments of the type foo=bar are stored in a hash, referenced by
$this->{cmdline_variables}. Arguments of the type @foo=bar are stored in an array,
referenced by $this->{cmdline_parameters}.

export_file

Fetch records from the database and write them to a file.

import_file

Read records from a file and insert them to the database.

66

© Wall Street Systems IPH AB - Confidential

4 Using Import Export tool
4.11 TemplateInterface class

Function

Description

read_database

Fetch records from the database and store them in a hash, referenced by
$this->{export_rows}. Store field types to the hash referenced by
$this->{export_types}.

write_database

Insert records to the database.

write_file

Write records to a file.

read_file

Read records from a file.

write_file_body

Loop through rows to write the body of the file. Calls pure virtual method write_row.

sql_value

sybase_type

Format a field value for the database.
•

Parameters: name - field name, value - field value

•

Returns: formatted value

Default function for getting Sybase type for a field
•

Parameters: name - field name

•

Returns: Sybase type

db

Return the database handle.

procedure_
parameters

Return the array of parameters to the export or import stored procedure.

line_terminator

Return the default line terminator.

•

Parameters: direction - import or export

The default line terminator is defined in the VARIABLES section of the .def file.
export_handle

Return the file handle to the export file.

import_handle

Return the file handle to the import file.

open_export_ file

Open the export file handle for writing. If file name is not defined, write to standard
output.

close_export_file

Close the export file.

open_import_file

Open the import file handle for reading. If file name is not defined, read from standard
input.

close_import_file

Close the import file.

file_name

Return the import or export file name.
Uses the dir, file and ext variables.

variable

•

Parameters: direction - import or export

•

Returns: filename or undef if export directory is undefined.

Return a variable.
Try in order: command line variable, import or export variable, common variable,
environment variable (e.g. FK_EXPORT_DIR).
•

Parameters: direction - import or export, variable - name of the variable

•

Returns: variable value or undef if not defined

4.11 TemplateInterface class
A class for importing and exporting files using templates. Defined in the file TemplateInterface.pm.

TRM System Administration Guide

67

4 Using Import Export tool
4.11 TemplateInterface class

4.11.1 TemplateInterface class functions
Function
get_fields

read_lines

line_count

Description
Get field names from a template.
•

Parameters: template - name of the template

•

Returns: reference to an array of fields

Read a specified number of lines from a file handle.
•

Parameters: handle - file handle, count- number of lines to read

•

Returns: the most specific one or undef if not found

Get the number of lines in a string.
For example, $this->package_split ("abc::def::ghi") would return
("abc::def::ghi" "abc::def" "abc").

escape_meta

align

add_thousand_
separators

•

Parameters: string - input string

•

Returns: number of lines

Escape regular expression metacharacters in a string.
•

Parameters: string - input string

•

Returns: result string

Do alignment, padding and truncation.
•

Parameters: value - input value, length - length, fill_character - fill character,
alignment - alignment ("left" or "right")

•

Returns: result

Add thousand separators to a number.
•

Parameters: value - input number, thousand_separator - thousand separator

•

Returns: result

4.11.2 TemplateInterface member functions
Function
new

Description
Constructor.
•

read_def

Parameters: templates - array of class names whose template files are read

Read templates and format definitions from the .def file.
•

Parameters: class - name of the class

write_file_header

Write file header.

write_row

Write one record to the export file.

write_file_trailer

Write file trailer.

read_file_header

Read file header.

read_file_body

Read file body and trailer.

template_parse

Parse input using template.

set_type

•

Parameters: type - template type (HEADER/BODY/TRAILER), start_hook - name of
the function that is executed before parsing, finish_hook - name of the function that
is executed after parsing, input - input lines

•

Returns: reference to the record hash

Set the type of a field.
•

68

Parameters: field - field name, type - field type

© Wall Street Systems IPH AB - Confidential

4 Using Import Export tool
4.11 TemplateInterface class

Function

Description

type

Get type of a field.

select_template

•

Parameters: field - field name

•

Returns: field type

Select current template.
•

template

Parameters: type - template type (HEADER/BODY/TRAILER), name - template name

Return a reference to the current or specified template.
•

Parameters: type - template type (HEADER/BODY/TRAILER), name - template name
or undef

•

Returns: reference to the current (name is undef) or specified template

template_name

Return current template name.

template_type

Return the file handle to the import file.

export_header_ start

•

Virtual method that is executed before the current header template is evaluated
with the current header record.

•

Parameters: row - reference to the header record hash (initially empty)

export_header_finish

Virtual method that is executed after the current header template has been evaluated
with the current header record.
•

export_body_start

Virtual method that is executed before the current body template is evaluated with the
current body record.
•

export_body_finish

expand_field

output

parse

Parameters: output - reference to the evaluated template

Evaluate a template
•

Parameters: row - reference to the input record hash

•

Returns: evaluated template

Expand a field of the form key1.key2. ... .field
•

Parameters: field - fully qualified field name, data - data record

•

Returns: base field name and field value

Output a string to the export file.
•

format

Parameters: row - reference to the trailer record hash (initally empty)

Virtual method that is executed after the current trailer template has been evaluated
with the current trailer record.
•

evaluate

Parameters: output - reference to the evaluated template

Virtual method that is executed before the current trailer template is evaluated with the
current trailer record.
•

export_trailer_finish

Parameters: row - reference to the body record hash

Virtual method that is executed after the current body template has been evaluated
with the current body record.
•

export_trailer_start

Parameters: output - reference to the evaluated template

Parameters: string - output string

Format a value according to its type.
•

Parameters: key - field name, value - field value, row - rest of the record (optional),
sybtype - Sybase type of the field (optional)

•

Returns: formatted value

Parse header/body/trailer record
•

Parameters: input - input lines, template - template to be used for matching

•

Returns: reference to a hash containing key/value pairs, undef if template does not
match with input

TRM System Administration Guide

69

4 Using Import Export tool
4.11 TemplateInterface class

Function

Description

regexp

Construct a regular expression from a field definition.

get_types

sql_type

get_format

cleanup

import_header_start

•

Parameters: key - field name

•

Returns: regular expression

Get the type array for a field. Elementary type (character, integer, etc.) is the first
element in the array, field name is the last one.
•

Parameters: key - field name, sybtype - Sybase type (optional )

•

Returns: reference to the array of types

Get SQL type for a field name.
•

Parameters: name - field name

•

Returns: SQL type

Get a formatting option for a type array.
•

Parameters: option - name of the formatting option, type_array - the type array

•

Returns: value of the formatting option

Clean up a parsed record.
•

Parameters: name - field name, value - field value

•

Returns: cleaned up value

Virtual method that is executed before the current header template has been evaluated
with the current header record.
•

import_header_finish

Virtual method that is executed after the current header template has been evaluated
with the current header record.
•

import_body_start

align

escape_meta

70

Parameters: input - reference to the trailer record hash

Virtual method that is executed after the current trailer template has been evaluated
with the current trailer record.
•

add_thousand_separ
ators

Parameters: params - reference to the evaluated template

Virtual method that is executed before the current trailer template has been evaluated
with the current trailer record.
•

import_trailer_finish

Parameters: input - reference to the body record hash

Virtual method that is executed after the current body template hasbeen evaluated
with the current body record.
•

import_trailer_start

Parameters: params - reference to the evaluated template

Virtual method that is executed before the current body template has been evaluated
with the current body record.
•

import_body_finish

Parameters: input - reference to the header record hash

Parameters: params - reference to the evaluated template

Add thousands separators to a number.
•

Parameters: value - input number, thousand_separator - thousands separator

•

Returns: result

Do alignment, padding and truncation.
•

Parameters: value - input number, length - length, fill_character - fill character,
alignment - left or right.

•

Returns: result

Escape regular expression metacharacters in a string.
•

Parameters: string - input string

•

Returns: result string

© Wall Street Systems IPH AB - Confidential

4 Using Import Export tool
4.12 Empty sample files

Function

Description

line_count

Get the number of lines in a string.

read_lines

•

Parameters: string - input string

•

Returns: number of lines

Read a specified number of lines from a file handle.
•

Parameters: handle - file handle, count - number of lines to read

•

Returns: lines read

4.12 Empty sample files
4.12.1 Definition file
BEGIN EXPORT VARIABLES
procedure =
@param =
dir =
file =
ext =
END EXPORT VARIABLES
BEGIN EXPORT HEADER
END EXPORT HEADER
BEGIN EXPORT BODY
END EXPORT BODY
BEGIN EXPORT TRAILER
END EXPORT TRAILER
BEGIN EXPORT FORMAT
END EXPORT FORMAT

BEGIN IMPORT VARIABLES
procedure =
@param =
dir =
file =
ext =
END IMPORT VARIABLES
BEGIN IMPORT HEADER
END IMPORT HEADER
BEGIN IMPORT BODY
END IMPORT BODY

BEGIN IMPORT TRAILER
END IMPORT TRAILER

TRM System Administration Guide

71

4 Using Import Export tool
4.12 Empty sample files

BEGIN IMPORT FORMAT
END IMPORT FORMAT

4.12.2 Empty Perl module
Template for empty import export Perl module
package Empty;
use TemplateInterface;

@ISA = qw (TemplateInterface);

sub new {
my ($class, @templates) = @_;

my $this = new TemplateInterface (@templates);

bless $this, $class;
return $this;
}
sub export_header_start{
my $this = shift;
my ($row) = @_;
}
sub export_body_start{
my $this = shift;
my ($row) = @_;
}
sub export_trailer_start{
my $this = shift;
my ($row) = @_;
}
sub export_header_finish{
my $this = shift;
my ($row) = @_;
}
sub export_body_finish{
my $this = shift;
my ($row) = @_;
}
sub export_trailer_finish{
my $this = shift;
my ($row) = @_;
}

72

© Wall Street Systems IPH AB - Confidential

4 Using Import Export tool
4.12 Empty sample files

#### The import part

sub import_header_start{
my $this = shift;
my ($row) = @_;
}
sub import_body_start{
my $this = shift;
my ($row) = @_;
}
sub import_trailer_start{
my $this = shift;
my ($row) = @_;
}
sub import_header_finish{
my $this = shift;
my ($row) = @_;
}
sub import_body_finish{
my $this = shift;
my ($row) = @_;
}
sub import_trailer_finish{
my $this = shift;
my ($row) = @_;

TRM System Administration Guide

73

4 Using Import Export tool
4.12 Empty sample files

74

© Wall Street Systems IPH AB - Confidential

Chapter 5

Setting up message management

5.1 Overview
Message Manager generates documents based on information in Wallstreet Suite (Transactions,
Schedule, Payment, Client). The documents can be printed, e-mailed or faxed. For information on
message management for business users, refer to the TRM User Guide.
The creation of a document is usually triggered by the fact that a transaction or other entity is
moved from one state to another in the process flow. If there are TransactionActions, a
MessageRequest is created. Also, EntityActions support the creation of MessageRequests. The
following entities are supported:

•

Payment Allocation Report

•

Payment Reminder

•

Late Payment Reminder

•

Drawdown Fixing

•

FX Rate Notification

•

Facility (using the flow in Facility Editor)

•

Amount Event

Message Manager uses the serviced daemon (replacing messaged used in TRM 7.1). This daemon is
usually started by Process Monitor, but for debugging purposes, it can also be started in a TRM
environment as follows:
serviced document/document.xml
In general, serviced supports the same command line options as the other real-time services such
as tracing. For details of serviced, see the WSS System Administration Guide.
The steps in producing a message are as follows (details are given in the rest of this chapter):
1. MessageRequest is created in the process flow and sent on the message bus. This step
determines the MessageType.
2. Given a MessageRule, a MessageSubType is assigned.
3. Each MessageRule defines which MessageRuleInstance(s) to use. For example, a
DRAWDOWN-NOTIFICATION implies that one document should be e-mailed to the counterparty
and one other document should be faxed to the bank. There is a one-to-one mapping between
the MessageRuleInstance and Message. In this case there will be two messages created since
there are two MessageRuleInstances attached to the matching MessageRule.
4. The combination of MessageType, MessageSubType and MessageGroup is used to determine a
ContactPerson (found in ClientEditor). A ContactPerson contains among other things the address
such as fax number, e-mail address, language of the document etc.,
5. The combination of MessageType, MessageSubType, Language and TransferType is used to
retrieve a MessageTemplate.
6. The serviced daemon loads the data associated with the underlying message object. The data to
load is defined by the MessageType and the MessageSubType in MessageTypeEditor, using the
tab MessageContent.
7. The document is created, based on the template to use.

TRM System Administration Guide

75

5 Setting up message management
5.2 Transaction and Entity flow

8. The command in the TransferMethod is used to transmit the message.
In Loan Drawdown Fixing Manager, Payment Allocation Manager and Payment Reminder Manager,
you can preview a message by right-clicking on the relevant line.

5.2 Transaction and Entity flow
MessageRequests can be created from both transaction flow and entity flow. An example of a
TransactionAction is as follows:
# Trade tickets for TRM transactions
(state ('OPEN'), mask (0),
rule ('TFLO-MESSAGE_TRADE-TICKET'),
send_full ('document.transaction', message_type='TRADE-TICKET',
state_id='TO-BE-TRANSMITTED')),
The message request gets the message type given by message_type. The parameter state_id
specifies the initial state_id in the message flow for the message request. By default, there are two
possible states:

•

TO-BE-VALIDATED: you are given the option to approve the message request in Message
Manager

•

TO-BE-TRANSMITTED: message transfer takes place immediately, without user intervention.

5.3 Message Manager and Message flow
The two main steps are creating messages (match rules and create message) and extracting data
(retrieving the fields defined in MessageContent for the given MessageType/MessageSubType).
To control and overview the process, use Message Manager. Message Manager is an entity board
application with a default message State ID flow is as follows:
1. TO-BE-VALIDATED typically allows the user to add comments. If the four-eyes principle is
applied, a message request is typically validated here.
2. EXECUTE is normally used just for previews. MessageRequests in this state now show in
Message Manager.
3. TO-BE-TRANSMITTED These message requests will be sent using the defined TransferMethod.
4. TRANSMITTED if external Message Manager successfully sends all subrequests, the message
request will be moved to this state.
Three thresholds are defined in the message flow (see the database setup folder):

•

If the MessageRequest is flagged Provisional, Message Manager will try to create messages and
extract the underlying data. For example, the first provisional state is TO-BE-VALIDATED, so
message creation and data extraction take place as soon as a MessageRequest is created.

•

If the MessageRequest is in a state flagged Intermediate, serviced tries to carry out the action
defined in the corresponding TransferMethod (e.g. send an e-mail, execute a script, fax or print).
By default, TO-BE-TRANSMITTED is an intermediate state.

•

If the MessageRequest is in a state flagged Final, no further processing takes place. For
example, if a MessageRequest consists of three messages and all are sent successfully, the
MessageRequest will be accepted into TRANSMITTED which is a state flagged as Final.

76

© Wall Street Systems IPH AB - Confidential

5 Setting up message management
5.4 Examples of messages

5.4 Examples of messages
A trade ticket should be printed immediately
The MessageRequest is created in a state which is defined as "to be transmitted immediately"
(TO-BE-TRANSMITTED). Since this MessageRequest does not have any messages yet and it is in an
intermediate state, the daemon instructs Message Manager to process the message. This processing
results in:

•

Rule matching, finding subtype since there is no structure yet

•

Data extraction

•

Upon successful data extraction the MessageRequest is accepted. If the next state is a
transmission-enabled state (intermediate) the execution will be continued. This means that the
document will be either printed immediately, or sent as an e-mail.

A MessageRequest is created in TO-BE-VALIDATED
Since the daemon discovers that this MessageRequest does not yet have any structure, serviced will
create a structure (find subtype, match rules, messages according to the MessageRuleInstances).
The user approving messages starts Message Manager and clicks ACCEPT on the MessageRequest.
The MessageRequest will now be moved to state EXTRA-VERIFICATION (not defined by default).
This allows another person to also accept the message into an intermediate state (where it will be
transmitted). Any number of states can be created to reflect the work process.

Messages that need comments as well as approval
In this case, Message Manager allows editing of these remark fields before the message reaches a
state that allows transmission. Initially this MessageRequest is created in a provisional state . The
daemon will discover the non-existence of structure (Message), therefore it will be processed and
Messages will be created. The user starts Message Manager and edits the MessageRequest remark
fields. Then the user ACCEPTS the MessageRequest into state TO-BE-TRANSMITTED and everything
proceeds as in the above cases.

5.5 Setting up Message Manager
Set up Message Manager as follows:
1. Edit the layouts using MS Word 2003 or 2007 and save them as XML.
2. Install the XML plugin described below. This is needed in order to mark the TRM specific fields to
be replaced by real data.
3. If other type and subtype combinations than provided by the best practice package is needed,
they need to be entered in Message Type Editor.
4. Upload the templates using the script upload_documents.py
5. Review the message rules in Message Rule Editor.
6. Check Transfer Type Editor and review transfer types.

5.6 Previews
There are two kinds of previews:

•

Transaction Manager
When the user selects preview action, the action scans all available TransactionActions for

TRM System Administration Guide

77

5 Setting up message management
5.7 Extracting data

possible MessageTypes and MessageSubTypes and presents a dialog box. When the user clicks
OK, a hidden MessageRequest and Message(s) created. Only the Message where the
corresponding MessageRuleInstace is flagged primary message will be displayed.

•

Message Manager
Right-click on a message. The message to preview is identified by its id.

5.7 Extracting data
Data extraction is based on the same modules as the GUI applications. For example, if a document
is based on a Transaction, the available fields are the same as in the corresponding Transaction
Manager view. If needed, additional static date fields can be included from static data editors.
For example, to display the name of a transaction currency:
1. Select Transaction.currency_id and Currency.name as fields in Message Type Editor. The
Currency source will not appear in the list until the transaction field is chosen).
2. Use the placeholder Transaction.currency_id.name in the document.
For cases when the built-in extraction capabilities are not enough, Message Manager provides
several ways to add and derive client-specific fields as follows:
1. Expressions (powered by python code)

•

•

Single field

–

Declaration in Message Type Editor (valid only in selected source and message type)

–

Declaration in document-config.xml (available for all message types)

Result set (many fields at a time)

In general, it is best to use expressions in Message Type Editor, because then the business user can
directly edit and review how a certain field is calculated or retrieved.
Making declarations directly in document-config.xml makes the expression available for all message
types. Expressions made in Message Type Editor are valid only in the selection message type.
Python code allows access to computed fields (same data as used by GUI applications) and is
database-independent. The python code to write depends on whether there is a need to process
only one field or many at a time.
2. SQL code in a stored procedure.
The stored procedure approach can be an easy method when migrating from earlier versions of
TRM. (database structure is relevant here). Processing SQL on the server side and returning many
fields in one call is normally efficient if performance is an issue.

5.7.1 Expressions
5.7.1.1 Single Field
Declare the expression directly in Message Type Editor. For each source, there is a special field
named Calculated. If this field is selected, the property fields become editable. Examples of
expressions that can be used in this field are:
logo='logo_wss.gif'
include_p=(cp_client_id != 'TP-CPTY')
transaction_sign_rev=if(sign_id == 'Buy','Sell','Buy')
sign_name=if(sign_id=='Buy', 'Receive', 'Pay')
date_basis1=if(type_subtype=='Netting',date_basis)
These expressions are driven by the same engine as in Transaction Manager. It is also possible to
call previously defined python functions from the expressions in the Message Type Editor.

78

© Wall Street Systems IPH AB - Confidential

5 Setting up message management
5.7 Extracting data

If you have a single field to compute, this will be coded in a python function: for example, code your
"my_function" function in the python file my_functions.py (Make sure this file is in your python
path):
def my_function (number):
# do some calculation here
...
return result
Declare the calculated field in document-config.xml:


my_function (number)


It is possible to select the name of the owner or counterparty using the functions provided:
seller = if (sign_id == 'Sell', get_field ('Client',owner_id,'name'), get_field
('Client',cp_client_id,'name'))
For this to work, the following piece of python code must be saved in the python path, for example
as:
C:\wss\v7\python\lib\Lib\site-packages\functions.py
This folder is usually used for python scripts. Save the following file as functions.py:
import FK.Core
from FK.ORB import from_value, to_value
import IDL.FK.Data_Context
from FK.Cache import Cache
cache = Cache ()
# Arguments are of type value
def get_field (o,k,f):
obj = FK.ORB.from_value(o)
# k should be of type value already
key = to_value(k)
field = FK.ORB.from_value(f)
# print "get_field",obj,key,field
holder = cache.context ()
try:
umi = holder.get (obj, [key])
(found, v) = umi.get_field (field, FK.ORB.to_value ())
if found:
return FK.ORB.from_value (v)
except:
return ""
return ""
The file functions.py must be linked to the source to be used in document-config.xml:

This makes the get_field function available to all Transaction sources. It is also possible to define the
field in document-config directly:


get_field('Client',cp_client_id,'name')



TRM System Administration Guide

79

5 Setting up message management
5.7 Extracting data

The field test_name is now available for selection in Message Type Editor and it will always contain
the name of the counterparty. It will be available for Transaction source only, but it will be available
across all Message types. If it is needed in yet other source, just add it again, but change the source
attribute.

5.7.1.2 Result set (multiple fields)
More complex processing may be required. There might be cases when the filter syntax is not
enough to get a certain cashflow. If there is a need to compute values based on several cashflows
and flags etc, the python code for this can be placed in the same python file as the above
expressions.
In general, if many parameters need to be computed at the same time, they are interdependent or
fetched altogether. Code a function called get_values in a python script, my_other_functions.py:
def get_values (ctx, values):
# compute some values
return values
The ctx parameter gives you the source you are considering (Transaction, Cashflow, UMI etc.),
values is a dictionary with fetched fields - from the source. You have to complement this list with
your own calculated information and return it. Finally link your script to Message Manager:













Pay attention to the module attribute where you setup your python script name:
module="data/python@my_other_functions"
A more detailed example of this:















The file myvalues.py must be in your python path. For example:
C:\wss\v7\python\lib\Lib\site-packages\myvalues.py
If above declaration is made in document-config.xml, the function get_values will be called for every
processed source (Transaction). A dictionary is passed as argument, so its contents can be changed
in the get_values function and then returned at the end. For example:

80

© Wall Street Systems IPH AB - Confidential

5 Setting up message management
5.7 Extracting data

import FK.Core
import FK.ORB
FK.ORB.use_idl ("Type")
from
from
from
from

FK.Cache import Cache
IDL.FK.Database import Action
FK.Module.Transaction_Manager import *
FK.Core import Money

cache = Cache ()

def get_receive_pay_flows (flows, category_id):
receive_principal = Money (0)
pay_principal = Money (0)
for flow in flows:
if flow.type_id == 1 and flow.category_id == category_id:
amount = Money (flow.amount)
if amount > 0:
receive_principal += amount
else:
pay_principal += amount
return (receive_principal, pay_principal)
def cmp (c1, c2):
if c1.value_date == c2.value_date:
return int ((c1.id - c2.id).as_long ())
return c1.value_date - c2.value_date
def get_values (ctx, values):
print "get_values"
if values.has_key ('number'):
number = FK.ORB.from_value (values['number'])
container = Container ()
action = cache.session ().create_action ()
t = container.retrieve (action, number, True)
if t != None:
if values.has_key ('receive_principal') or values.has_key ('pay_principal'):
(values['receive_principal'], values['pay_principal']) =
get_receive_pay_flows (t.cashflows(), 0) # category settlement
if values.has_key ('receive_redemption') or values.has_key ('pay_redemption'):
(values['receive_redemption'], values['pay_redemption']) =
get_receive_pay_flows (t.cashflows(), 1) # category payback
if values.has_key ('first_interest_amount'):
flows = t.cashflows ()
flows.sort (cmp)
for flow in flows:
if flow.type_id == 2 and flow.category_id == 1: # type interest, category
payback
print '*' * 8, flow.value_date
values['first_interest_amount'] = flow.amount
break
return values
Note that it is possible to call the already existing get_field (to avoid code duplication) function to
lookup needed field in the TRM object hierarchy, for example. In the example below, depending on
transaction sign, different bank names and swift codes are selected. For the moment, all functions
are called with Type::Value arguments.

TRM System Administration Guide

81

5 Setting up message management
5.7 Extracting data

def get_field (o,k,f):
obj = FK.ORB.from_value(o)
# k should be of type value already
key = k
field = FK.ORB.from_value(f)
print "get_field",obj,key,field
holder = cache.context ()
try:
umi = holder.get (obj, [key])
(found, v) = umi.get_field (field, FK.ORB.to_value ())
if found:
return FK.ORB.from_value (v)
except:
return ""
return ""
def get_bond_beneficiary(t):
flows = t.cashflows()
for flow in flows:
if flow.type_id == 1 and flow.sign != t.sign_id:
# Found cashflow to use
beneficiary_details = ()
client_v = FK.ORB.to_value("Client")
name_v = FK.ORB.to_value("name")
swift_v = FK.ORB.to_value("swift_code")
if t.sign_id > 0:
beneficiary_details =
(get_field(client_v,FK.ORB.to_value(flow.local_client_id),name_v),
get_field(client_v,FK.ORB.to_value(flow.local_bank_id),name_v),
flow.local_account_id,
get_field(client_v,FK.ORB.to_value(flow.local_bank_id),swift_v),
get_field(client_v,FK.ORB.to_value(flow.local_corr_bank_id),swift_v))
else:
beneficiary_details =
(get_field(client_v,FK.ORB.to_value(flow.other_client_id),name_v),
get_field(client_v,FK.ORB.to_value(flow.other_bank_id),name_v),
flow.other_account_id,
get_field(client_v,FK.ORB.to_value(flow.other_bank_id),swift_v),
get_field(client_v,FK.ORB.to_value(flow.other_corr_bank_id),swift_v))
return beneficiary_details

5.7.1.3 System functions
Message Manager also provides a set of predefined functions. Date handling is as follows:
Type

Parameter

Action

today

None

Gets the current date

year

Date

Extracts the year

month

Date

Extracts the month

day

Date

Extracts the date

82

© Wall Street Systems IPH AB - Confidential

5 Setting up message management
5.8 Setting up Document Formatter

Multiple entities manipulation is as follows. These functions operate on all entities of a source and
return a single value. This unique value is then available on any of the source entities.
Entity

Parameter

Action

min_value

Entity field

Gets the minimum value of the field in the set of entities

max_value

Entity field

Gets the maximum value

total

Amount field

Sums the amounts

average

Amount field

Averages the amounts

count

None

Counts the entities

5.7.2 SQL code in stored procedures
The stored procedure and the fields to use must be declared in document-config.xml as follows:








When fields are extracted from a transaction, the number is passed as key to GetMyInfo. This
procedure may return a lot of fields and record sets, but only myfield1 and myfield2 will be available
in Message Type Editor. In the document, the following placeholders Transaction.myfield1 and
Transaction.myfield2 can be used.

5.7.3 Filters
New sources can be configured in document-config.xml. The following example creates a new source
which is a subset of the cashflows:



1
6

hot



5.8 Setting up Document Formatter
5.8.1 Prerequisites
Wallstreet Suite installation must contain the latest version of Apache FOP. There is nothing to
install except to add into the path the folder where FOP is extracted to. Since FOP is Java-based, the
Java runtime environment should also be present.

TRM System Administration Guide

83

5 Setting up message management
5.8 Setting up Document Formatter

5.8.2 Settings
All document management settings are in this folder: /etc/document
which contains the following subfolders:

•

images - this is where reusable pictures are kept, for example logos and similar items.

•

interim - temporary folder for intermediate files and final results (PDF files). This folder location
can be customized during setup - if so, the directory to be used should be assigned to the
environment variable named FK_DOCUMENTS_INTERIM_DIRECTORY.

•

processor - contains XSLT code that translates WordML to FO (contains subfolders so that we
can use several input and output formats. Read-only.

The main activity is logically splitting message templates by type, subtype, media and language,
then uploading the document into the database. The name of the document is not the file name of
the Word XML document: it is the logical name that you give to this template document, and
defaults to "default".
For example, for type preview_type, subtype preview_subtype, medium email and language en-us,
and the name of the document is not specified, the following command line should be used:
python upload_documents.py --document