technical reference sheet - highqsoft · 2020. 6. 30. · technical reference sheet avalon version...

472
HighQSoft GmbH

Upload: others

Post on 27-Jan-2021

7 views

Category:

Documents


1 download

TRANSCRIPT

  • Technical Reference Sheet

    Avalon

    version 4.9a

    HighQSoft GmbH Karst Schaap 2020/06/30

  • Contents

    1 Introduction 1

    1.1 Introduction Athos Runtime System . . . . . . . . . . . . . . . . . . . . . . . . . . 1

    1.2 Introduction ASAM-ODS API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

    1.3 Introduction Avalon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

    1.4 Introduction Avalon Distributor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

    1.5 Introduction Translator MME1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

    2 Requirements 5

    2.1 Requirements Athos Runtime System . . . . . . . . . . . . . . . . . . . . . . . . . 5

    2.2 requirements ASAM-ODS API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

    2.3 Requirements Avalon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

    2.4 Requirements Avalon Distributor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

    2.5 Requirements Translator MME1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

    3 Installation 7

    3.1 Installation of license manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

    3.2 Installation Translator MME1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

    4 Con�guration 9

    4.1 Con�guration Athos Runtime System . . . . . . . . . . . . . . . . . . . . . . . . . 9

    4.2 Con�guration of the Athos Runtime System on Linux . . . . . . . . . . . . . . . . 10

    4.3 Con�guration of the security in the Athos Runtime System . . . . . . . . . . . . . 10

    4.4 Con�guration of the Windows event viewer . . . . . . . . . . . . . . . . . . . . . . 10

    4.5 Memoryhandling and loading values of Localcolumns . . . . . . . . . . . . . . . . . 10

    4.6 Load the translator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

    4.7 Con�guration ASAM-ODS API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

    4.8 ODS Session data source connect handling. . . . . . . . . . . . . . . . . . . . . . . 12

    4.9 Con�guration license manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

    4.10 Usage ODS API Wildcard characters . . . . . . . . . . . . . . . . . . . . . . . . . . 14

  • ii CONTENTS

    4.11 ODS API handling Con�guration Variables . . . . . . . . . . . . . . . . . . . . . . 15

    4.12 Store encrypted password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

    4.13 Open transaction at session close. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

    4.14 Con�guration Avalon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

    4.15 Avalon using a LDAP-Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

    4.16 Avalon using a new session-Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

    4.17 Firewall Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

    4.18 UTF-8 as character set for the Avalon. . . . . . . . . . . . . . . . . . . . . . . . . . 25

    4.19 Session watchdog in Avalon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

    4.20 Worker mode in Avalon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

    4.21 Avalon con�guration �le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

    4.22 Con�guration Avalon Distributor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

    4.23 Con�guration Translator MME1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

    4.24 Con�guration of Oracle Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

    4.25 The convert�le in Translator MME1 . . . . . . . . . . . . . . . . . . . . . . . . . . 31

    4.26 Directory handling for the external component �les of the translator MME1. . . . 32

    4.27 Memory usage of the translator MME1 . . . . . . . . . . . . . . . . . . . . . . . . . 35

    4.28 Usage of di�erent schemas in an oracle database . . . . . . . . . . . . . . . . . . . 36

    5 Initialization File Format 37

    5.1 Initialization File Format Athos Runtime System . . . . . . . . . . . . . . . . . . . 37

    5.2 Tool AthosCon�g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

    5.3 Password Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

    5.4 Athos ASAM-ODS API Initialization File Example . . . . . . . . . . . . . . . . . . 40

    6 Usage 41

    6.1 Usage Athos Runtime System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

    6.2 Noti�cation with Athos Runtime System . . . . . . . . . . . . . . . . . . . . . . . . 41

    6.3 Datatype of Id's in Athos Runtime System. . . . . . . . . . . . . . . . . . . . . . . 43

    6.4 Usage of the security tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

    6.5 Usage of the data manipulation tools. . . . . . . . . . . . . . . . . . . . . . . . . . 55

    6.6 Usage tool CreateUnitScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

    6.7 Usage tool DeleteAttribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

    6.8 How to setup security at an ASAM ODS Server. . . . . . . . . . . . . . . . . . . . 56

    6.9 Usage Avalon / Avalon Distributor . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

    6.10 orbd - The Object Request Broker Daemon . . . . . . . . . . . . . . . . . . . . . . 61

    6.11 Client programming. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • CONTENTS iii

    6.12 Java properties for Avalon / Avalon Distributor . . . . . . . . . . . . . . . . . . . . 64

    6.13 Using JacORB with Avalon / Avalon Distributor . . . . . . . . . . . . . . . . . . . 65

    6.14 Noti�cation with Avalon / Avalon Distributor . . . . . . . . . . . . . . . . . . . . . 74

    6.15 Usage of AvalonControlService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

    6.16 Usage tool CheckAoFiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

    6.17 Usage tool CheckExternalReferences . . . . . . . . . . . . . . . . . . . . . . . . . . 91

    6.18 Usage tool NameServiceCleaner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

    6.19 Usage tool ASAM ODS Ping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

    6.20 Usage Translator MME1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

    6.21 Usage the physical storage of the translator MME1. . . . . . . . . . . . . . . . . . 97

    6.22 Usage the di�erent storage for the measurement values. . . . . . . . . . . . . . . . 105

    6.23 Usage of database constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

    6.24 Usage of global temporary table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

    6.25 Usage of context variables in the translator . . . . . . . . . . . . . . . . . . . . . . 107

    6.26 Usage tool CheckNumberOfRows . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

    6.27 Usage tool Check_SVCVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

    6.28 Usage tool CheckTableInstances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

    6.29 Usage tool CopyLocalColumnValues . . . . . . . . . . . . . . . . . . . . . . . . . . 113

    6.30 Usage tool CorrectExternalReferences . . . . . . . . . . . . . . . . . . . . . . . . . 118

    6.31 Usage tool Correct_SVCVAL_String . . . . . . . . . . . . . . . . . . . . . . . . . 119

    6.32 Usage tool DBPing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

    6.33 Usage tool DistinctSVCREF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

    6.34 Usage tool Dump_SVCVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

    6.35 Usage tool ExtendModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

    6.36 Usage tool ListConstraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

    6.37 Usage tool LoadExtComp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

    6.38 Usage tool MME1Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

    6.39 Usage tool UpdateStorage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

    6.40 Usage tool lcCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

    7 Error reporting and Logging 155

    7.1 Error reporting Athos Runtime System . . . . . . . . . . . . . . . . . . . . . . . . . 155

    7.2 How to use the event log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

    7.3 LogViewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

    7.4 LogPro�leViewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

    7.5 LogPro�ler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

    7.6 LogSplitter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • iv CONTENTS

    7.7 Error reporting and logging ASAM-ODS API . . . . . . . . . . . . . . . . . . . . . 168

    7.8 LogArchiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

    7.9 Error reporting and logging Avalon . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

    7.10 Setting the DEBUGLEVEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

    7.11 Java error logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

    7.12 Error reporting and logging Translator MME1 . . . . . . . . . . . . . . . . . . . . 173

    7.13 Translator MME1 connection lost to Oracle . . . . . . . . . . . . . . . . . . . . . . 175

    8 Con�guration Variables 177

    8.1 Athos Runtime System Con�guration variables . . . . . . . . . . . . . . . . . . . . 177

    8.2 ASAM-ODS API Con�guration variables . . . . . . . . . . . . . . . . . . . . . . . 191

    8.3 Translator MME1 Con�guration variables . . . . . . . . . . . . . . . . . . . . . . . 205

    9 Properties of Avalon and Avalon Distributor 219

    10 Athos version 229

    10.1 How to determine the Athos version . . . . . . . . . . . . . . . . . . . . . . . . . . 229

    11 Know how 231

    11.1 Error: Unable to load driver (AO_UNABLE_LOAD_DRIVER) . . . . . . . . . . 231

    11.2 Datamodel and Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

    11.3 Avalon error com.sun.corba.se.impl.encoding.CodeSetConversion$JavaCTBConverter233

    11.4 Alive checks for Avalon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

    11.5 CORBA Communication failure IOP00410215 . . . . . . . . . . . . . . . . . . . . . 247

    11.6 Connecting problems from java to database on x64-systems . . . . . . . . . . . . . 249

    11.7 Change the IP-adres of the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

    11.8 Problem CORBA character converting . . . . . . . . . . . . . . . . . . . . . . . . . 249

    11.9 Avalon and the Client FAMOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

    11.10Memory consumption of Avalon process . . . . . . . . . . . . . . . . . . . . . . . . 250

    11.11Update a storage to ASAM ODS 5.3.0 . . . . . . . . . . . . . . . . . . . . . . . . . 251

    11.12NI DIAdem cache mode for Bulk data . . . . . . . . . . . . . . . . . . . . . . . . . 252

    11.13Optimize the oracle database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

    11.14Oracle errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

    11.15Rename the �les in the external component table. . . . . . . . . . . . . . . . . . . 255

    11.16Error: Unable to open �le (mapview) (AO_UNABLE_OPEN_FILE) . . . . . . . 255

    11.17Name of new sequence to long . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

    11.18Not all instances are loaded. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

    11.19The translator reports the oracle message "ORA-01012: not logged on" . . . . . . 256

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • CONTENTS v

    11.20The translator reports the oracle message "SQL-02113: Unable to open message �le"257

    11.21Informations about Oracle 12c (Release 1) . . . . . . . . . . . . . . . . . . . . . . . 257

    11.22Using case sensitive table and coloumn names . . . . . . . . . . . . . . . . . . . . . 258

    11.23Using extended data types in oracle 12c . . . . . . . . . . . . . . . . . . . . . . . . 258

    11.24Oracle Bug 17846528 CONNECTIONS THROUGH LISTENER HANG AFTER2049 ATTEMPTS ON NON-ENGLISH SERVERS . . . . . . . . . . . . . . . . . . 258

    11.25Treatment of NaN (Not a Number) as Double or Float Value . . . . . . . . . . . . 259

    12 Appendices 261

    12.1 Athos Error Link List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

    12.2 Athos Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

    12.3 CORBA Interface de�nition of the AvalonControlService . . . . . . . . . . . . . . . 329

    12.4 Interface of the variables of the AvalonControlService . . . . . . . . . . . . . . . . . 334

    12.5 SRVANY application as services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

    12.6 The debuglevel de�nitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

    13 Releasenotes 345

    13.1 Scheduled for next Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

    13.2 Release 4.9a . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

    13.3 Internal optimization, some bug �xes. . . . . . . . . . . . . . . . . . . . . . . . . . 347

    13.4 Release 4.8b . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

    13.5 Release 4.8a . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

    13.6 Release 4.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

    13.7 Release 4.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

    13.8 Release 4.6d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

    13.9 2017-08-15 Release 4.6c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

    13.102017-02-21 Release 4.6a . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362

    13.11Athos 4.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

    13.122016-02-15 Release 4.5b . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

    13.132015-11-09 Release 4.5a . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

    13.142015-07-10 Release 4.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373

    13.152015-04-28 Release 4.4c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

    13.162014-10-30 Release 4.4a . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

    13.172014-05-20 Release 4.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

    13.182013-12-04 Release 4.3b . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

    13.192013.08.27 Release 4.3a . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388

    13.202013.02.22 Release 4.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392

    13.212012.11.23 Release 4.2e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • vi CONTENTS

    13.222012.09.07 Release 4.2d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

    13.232012.06.24 Release 4.2c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

    13.242012-05-10 Release 4.2b . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400

    13.252012.02.24 Release 4.2a . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

    13.262012.01.06 Release 4.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403

    13.272011.11.08 Release 4.1h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404

    13.282011.10.21 Release 4.1g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

    13.292011.08.16 Release 4.1f . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

    13.302011.07.21 Release 4.1e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

    13.312011.06.30 Release 4.1d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408

    13.322011.04.15 Release 4.1c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409

    13.332011.03.04 Release 4.1b . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

    13.342011.02.25 Release 4.1a . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411

    13.352011.01.05 Release 4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412

    13.362010.11.03 Release 4.0k . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413

    13.372010.11.03 Release 4.0j . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414

    13.382010.10.08 Release 4.0i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415

    13.392010.07.22 Release 4.0g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

    13.402010.07.08 Release 4.0f . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418

    13.412010.05.11 Release 4.0e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

    13.422010.05.03 Release 4.0d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421

    13.432010.03.26 Release 4.0c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423

    13.442010.02.25 Release 4.0b . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424

    13.452010.02.17 Release 4.0a . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

    13.462010.20.01 Release 4.0 Initial version ODS 5.2.0 . . . . . . . . . . . . . . . . . . . . 427

    13.472009.15.12 Release 3.7k . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428

    13.482009.17.11 Release 3.7j . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429

    13.492009.11.10 Release 3.7i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430

    13.502009.10.05 Release 3.7h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432

    13.512009.08.25 Release 3.7g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

    13.522009.06.23 Release 3.7f . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437

    13.532009.05.13 Release 3.7e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

    13.542009.04.03 Release 3.7d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441

    13.552009.03.12 Release 3.7c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442

    13.562009.02.25 Release 3.7b . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

    13.572009.02.10 Release 3.7a . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • CONTENTS vii

    13.582009.01.01 Release 3.7 Initial Release 2009 . . . . . . . . . . . . . . . . . . . . . . . 445

    14 Glossary 447

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • Chapter 1

    Introduction

    Athos is a toolkit to build ASAM-ODS products from basic components. Today the name Athosis also very often used to refer to our ASAM-ODS Server (Athos Server) or even our entire ASAM-ODS product line (Athos System).

    Based on our �exible Athos Toolkit HighQSoft has developed a wide variety of products formanaging your test data on Linux, MS-Windows based operating systems 64-Bit.

    Higher e�ciency

    By using our software products you have the possibility to work with all the data storedanywhere within your enterprise. Even old data, possibly no longer accessible due to migrationto new hard- and/or software, may now be used and do not have to be recreated with greate�ort.

    Distinct saving of time

    The products of HighQSoft GmbH are based on standards and make development of oftenvery time-consuming and risky individual solutions unnecessary.

    Reduced costs

    Due to many years of experience and close co-operation with our customers, we achieve saferesults within a short time. These results are "on the point" and assure reduced costs in thefuture.

    1.1 Introduction Athos Runtime System

    The Athos Runtime System is the backbone and the working engine of all Athos based products.The runtime system provides basic ASAM ODS functionality, which is the same on all supported

  • 2 Introduction

    operating systems (single source). The Athos Runtime System is written in plain ANSI-C formaximum portability. The provided functionality is utilized within Athos-based client and serverapplications.

    Figure 1.1: The Athos Runtime System

    1.2 Introduction ASAM-ODS API

    The ASAM-ODS Application Programmers Interface (API) is an object oriented interface de�ni-tion to access ASAM-ODS compliant data sources. The Athos implementation of the ASAM-ODSAPI is based on the Athos Runtime System. It is written in plain ANSI-C for maximum portabil-ity. Therefore, the ANSI-C interface is the default programming language binding which is alwaysavailable. Language Bindings for other languages like C++, Java, Tcl, Perl, Python, Visual Basicand others are available as separate products.

    The Athos implementation of the ASAM-ODS API strictly follows the ASAM-ODS de�nitions.The ASAM-ODS Interface De�nition (ods.idl) as well as the o�cial ASAM-ODS documentationmay be used as a reference. Any other information on how to use the Athos implementation isfound in this document. The main objects of the ASAM-ODS_API are given below.

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 1.2 Introduction ASAM-ODS API 3

    AoSession

    BaseStructure

    BaseRelation

    BaseElement

    AoFactory

    ApplicationRelation

    ApplicationAttribute

    Measurement

    ValueMatrix Column

    ApplicationStructure

    ApplicationElement

    BaseAttribute

    SubMatrix

    InstanceElement

    ApplElemAccess

    Figure 1.2: Main objects of the ASAM-ODS-API.

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 4 Introduction

    1.3 Introduction Avalon

    Avalon is an ASAM-ODS Corba OO-API Server, which full�lls the current ASAM ODS speci�ca-tion. Avalon is a standalone application based on the Athos Runtime System. The source code ofthis application is the same on all supported operating systems (single source). Avalon is writtenin Java for maximum portability.

    1.4 Introduction Avalon Distributor

    Avalon Distributor is an Server for load balancing, when using multiple Avalon Server. It distributethe client requests for new session, across the available Avalon Servers. The source code of thisapplication is the same on all supported operating systems (single source). Distributor is writtenin Java for maximum portability.

    1.5 Introduction Translator MME1

    The Athos Toolkit design pattern follows a driver concept to access di�erent data sources likerelational databases, ASAM Transport Format �les (ATF), ASAM-ODS servers or other existingdata storage and retrieval systems (mostly proprietary, �le-based).

    The drivers are also referred to as translators which describes their purpose very well. Driverstranslate the information from the data sources to ASAM-ODS compliant objects and vice versa.Depending on the data source, the translation process may be a simple mapping task or a sophis-ticated data conversion process.

    The translator implementation is based on the Athos Runtime System. This translator is writtenin plain ANSI-C for maximum portability.

    This translator support the ASAM ODS mixed mode physical storage, with relational base de-scriptive data and �le oriented mass store data. The database must be Oracle, the access to thedatabase is done by Oracle Embedded SQL

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • Chapter 2

    Requirements

    No special software products are required. About 50 MB of free disk space is needed for a normalAthos installation. Volatile memory consumption of the Athos Runtime System depends on theapplication data volume plus approx. 1MB for the runtime system code. The required disk spacefor compilation and linking of the complete Athos System is 400 MB for all source, temporary andoutput �les.

    2.1 Requirements Athos Runtime System

    There are no special requirements for the Athos Runtime System.

    If the Athos Runtime System should run in multithreaded mode, only Microsoft Windows NT,Microsoft Windows 2000, Microsoft Windows XP, Microsoft Windows 2003, Microsoft Windows2008, Microsoft Windows 2012, Microsoft Windows vista, Microsoft Windows 7 and Linux aresupported.

    2.2 requirements ASAM-ODS API

    No special software products besides the Athos Runtime System and the appropriate translator(driver) are required. The disk space and volatile memory requirements of the Athos-based ASAM-ODS API do not add a signi�cant amount to the Athos Runtime System (some 100 kByte only).

    2.3 Requirements Avalon

    The Java Runtime Environment besides the Athos Runtime System and the appropriate translators(drivers) are required. The disk space and volatile memory requirements of Avalon are about 1MB for the Avalon and ASAM-ODS JAR �les. Additionally the memory requirements of the ORBimplementation must be added.

    There is a known problem when the server runs under the JAVA versoin 1.5.x and the Client usesthe JAVA release 1.4.x. Sometimes the CORBA communication fails. This problem is not solvedby the latest Tiger (JAVA 1.5) release Sun's bug 5067940.

    Therefore we require a JAVA Virtual Machine of the verion 1.5 for Clients, if the server is runningin a 1.5 environment. The following table shows the result of test between di�erent java versionof client and server.

    http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=5067940

  • 6 Requirements

    Server / Client Sun Java 1.4 Sun Java 1.5 Sun Java 1.6Sun Java 1.4 OK Error Not TestedSun Java 1.5 Error OK OKSun Java 1.6 Not tested OK OK

    We have not found any di�erence between the di�erent releases of the java versions for our appli-cation.

    The java version must match with the versin of Athos, when Athos is delivered as win32 the javaversion must be a 32-Bit version. When Athos is delivered as win64 the java version must be a64-Bit version. When the version don't match error messages like Can't load IA 32-bit .dll ona AMD 64-bit platform are reported at the standard error of avalon.

    2.4 Requirements Avalon Distributor

    There are no additional requirements to the described requirements of Avalon.

    2.5 Requirements Translator MME1

    In addition to the Athos Runtime System an oracle client software or oracle database system ofthe proper version for the actual operating system and compilation of the translator (32-Bit or64-Bit) are required.

    The disk space and volatile memory requirements of this translator do not add a signi�cant amountto the Athos Runtime System (appr. 600 kByte).

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • Chapter 3

    Installation

    The installation of the ASAM ODS Server Avalon is described in the seperate document: Instal-lation Guide.

    3.1 Installation of license manager

    When a �oating license is used, the license manager must be installed. For the license managerthe programs rlm(.exe) and highqsoft(.exe) are required. These programs are available in thebinary directory, which is $ATHOS_ROOT\bin\$OSTYPE. For more details about the installation seethe Reprise documentation.

    The program rlm(.exe) must be started, the license server is available on the default port 5053.A WEB-GUI is available on the port 5054. The licence �le must be copied in the directory wherethe license server ist started or the directory con�gured by the option -c.

    3.1.1 rlm startup options

    The rlm command is:

    % rlm [-c license_file] [-dat] [-dlog [+]logfile]

    [-nows] [-ws port] [-x [rlmdown|rlmremove]]

    [-install_service] [-service_name sname]

    [-isv_startup_delay seconds] [-v] [-info]

    [-noudp]

    The -c license_�le option speci�es which license �le to use. This option overrides the settingof the RLM_LICENSE environment variable. The license_�le parameter can be a directorycontaining license �les, all of which will be processed.

    The -dat option speci�es that license �les should have the extension ".dat", rather than ".lic".If -dat is speci�ed, the rlm server will search for all �les ending in ".dat" instead of ".lic" asdocumented elsewhere.

    The -dlog log�le speci�es the pathname for the server debug log. If log�le is preceded by the '+'character, the log�le will be appended, otherwise it is overwritten.

    The -info option causes RLM to print information about all copies of rlm that are running onthis computer, including copies which have run in the prior 24 hours, then exit.

  • 8 Installation

    The -install_service and -service_name sname options are used to run the rlm server as aservice under windows.

    The -isv_startup_delay seconds option speci�es that when running as a Windows service,rlm should delay seconds seconds before starting up the ISV servers. If not speci�ed, there is nodelay. This is useful if a license �le speci�es a hostid of type rlmid1 or rlmid2 (hardware keys),the server is started at system boot time, and the key driver is not yet started at the time the ISVserver needs to read it.

    The -nows and -ws port options control the operation of the embedded Web Server. The -nowsoption instructs the rlm server to not start the embedded web server. The -ws port optioninstructs the rlm server to use port as the port number for the web serverThe -noudp option tellsRLM to not bind the UDP port (5053) used for replying to broadcast messages from clients inRLM v10.0 and later.

    The -v option causes RLM to print it's version and exit.

    The -x [rlmdown | rlmremove] option controls whether the rlmdown and/or rlmremove com-mands will be processed by the server. Specifying only -x will disable both commands. Specifyingeither command name after the -x will disable just that command. These options can appearin any order on the command line. If you want to generate a report log �le, specify this on anISV-by-ISV basis in the individual ISV's options �le.

    Additional information about the Reprise License Manager contains the sup-plied manual RLM_License_Administration.pdf or the rlm homepage at:http://www.reprisesoftware.com/RLM_License_Administration.pdf.

    3.2 Installation Translator MME1

    The installation of this translator is an integral part of the Athos Runtime System installation. Dueto the compact size of this translator we decided not to set up a separate installation procedure.All required components are available when the Athos Runtime System has been installed. Thisis valid for all supported operating systems.

    Concerning the installation of the oracle database client on the operating system of your choiceplease refer to the documentation of your database vendor or ask your database administrator.Oracle SQL∗Net client is required and the TNS for the database server must be installed correctly.

    The MME∗ translator depends strongly from the Oracle client version. For the moment there areone version of the MME translator available.

    Name of translator Oracle client version Oracle server versionMME1 8.1.6 8.1.7MME92 9.2. 9.2.MME102 10.2. 10.2.MME102 10.g XE 10.g XEMME112 11.2. 11.2.MME121 12.1. 12.1.

    The combination of these versions are tested, if there are other combination working please letus known. The combination of the wrong client/server version can produce unpredicable results.Most time the reported errors have no relation to the problem of version con�ct.

    The translator uses the oracle client software for the connection to the oracle server. Add theoracle client software to the PATH or LD_LIBRARY_PATH so the oracle client software can beloaded by the system when the translator is loaded.

    Take also care the system is able to solve the TNSName.

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • Chapter 4

    Con�guration

    The con�guration of the components of the Athos toolkit is generally done by setting environmentvariables and usage of an INI-File. Before the components are con�gured, the con�guration ofthe Athos Runtime System must be done �rst. See: Con�guration Athos Runtime System(p. 9).

    4.1 Con�guration Athos Runtime System

    The Athos Runtime System is highly con�gurable and adaptable for a multitude of di�erentrequirements. The con�guration may be done via environment variables and via de�nitions ininitialization �les. For most cases the built-in defaults of the Athos Runtime System will besu�cient. However, for special cases it may be necessary to con�gure some options for yourrequirements.

    The environment variable ATHOS_ROOT is used to de�ne the root directory of the Athos system. Ifthis environment variable is not de�ned, the de�nition of ATHOS_ROOT in the INI-File is used asdefault. See: Athos Runtime System Con�guration variables (p. 177).

    The name of the INI-File or the name of the environment variable containing the INI-File namemay be passed to the Athos Runtime System at time of initialization. This allows Athos-basedapplications to specify their own application initialization �lename environment variable (e.g.MYAPP_INI instead of ATHOS_INI) to avoid collisions with other applications environment variables.

    If no ATHOS_ROOT is de�ned, no INI-File name and no environment variable containing an INI-Filename can be found, the Athos Runtime System tries to open the �le athos.ini in the currentworking directory as default. If this also fails, a corresponding message is written to the EventLog on Win32 or the default log �le ATHOS_ROOT/log/asam_err.log. If the log directory can notbe located (e.g. because of missing ATHOS_ROOT de�nition) the log �le asam_err.log is written tothe current working directory. If the log �le cannot be opened for any reason, the Athos messagesare lost.

    The table in this document shows all supported con�guration variables including their names,descriptions, default values and source. The source of a con�guration variable may be the systemenvironment or the Athos INI-File. The global keyword denotes variables that may be de�ned inthe global section of the Athos INI-File. The global section in the INI-File is marked by the string[ATHOS].

    The con�guration variables of the Athos Runtime System are given in Athos Runtime SystemCon�guration variables (p. 177).

  • 10 Con�guration

    AthosCon�g is a tool which helps you to edit the INI-File. See Tool AthosCon�g (p. 39).

    4.2 Con�guration of the Athos Runtime System on Linux

    The Athos Runtime System switch automatically into mutilthreaded mode on Windows system.On Linux system there is no automatic switch into the multithreaded mode, so the con�gurationof the Athos Runtime System must explicit force the multithreaded mode.

    The global INI-File variable MULTITHREADABLE = yes must be used to force the multithreadedmode and do the required initialization. The Athos Runtime System will probably crashes whenmultithreaded access is done without the initialization.

    4.3 Con�guration of the security in the Athos Runtime Sys-tem

    There are two con�guration variables available for the security con�guration. The two variables,IGNORE_SECURITY and NOSECURITYACTIVE, have the same meaning, but IGNORE_SECURITY tellsthe 'server' (AVALON or Aop3Server) to ignore the security and NOSECURITYACTIVE tells theAthos Runtime System not to check the objects added from the translators.

    Disabling security is done by setting both variables to YES in the INI-File. Normally a server isavailable for the security, so the variable NOSECURTYACTIVE = YES will not change andthe security will be activated by comment out of the variable IGNORE_SECURTY.

    4.4 Con�guration of the Windows event viewer

    The Windows event viewer is able to show a textual explanation of the error message. The eventviewer need a �le with the text of the messages. This �le is registered during setup or installationof the Athos Runtime System. However when the messages don't occur you ca register athos atthe event viewer also afterwards with the following commands executed in the Windows console.

    cd %ATHOS_ROOT%

    bin\Win32\instsrc" Athos "%ATHOS_ROOT%\bin\win32\athos.dll" 2

    This command is part of the batch �le setupathos.bat

    4.5 Memoryhandling and loading values of Localcolumns

    4.5.1 Memoryhandling values of Localcolumns

    Athos Runtime System loads the values of the localcolumn into the memory on request. Loadingthe values of the localcolumn cost a lot of performance, so there is a cache for the these values.When a client request the values of the localcolumn twice the values are loaded only once. Thememory required for the values of teh localcolumns can be high, so there is a restriction of theused memory for the values of the localcolumns. This restriction is given by the global INI-Filevariable MAX_LC_MEMORY. The localcolumns are unloaded until enough memory is free to allocatethe memory for the values of the actual requested localcolumn. When there is a strong di�erencebetween the number of values of the localcolumn the number of localcolumns in the cache increase

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 4.6 Load the translator 11

    also without the memory usage increase strongly. When the number of localcolumn is high theperformance go down, you can restrict the number of localcolumn in the cache with the global INI-File variable MAX_NUMBER_LC With the global INI-File variable FREE_NUMBER_LC you can speci�ythe number of localcolumns which will be deleted from the cache when the number of localcolumnsis to high.

    There are two futher INI-�le variables which de�ned the capacity and way of working of thetranslator. The INI-File variable DRIVER_FACTOR de�ned taht the translator needs a copy of thedata in memory independent of the memory in the Athos Runtime System. The variable LOAD_-SUBMATRIX de�nes the translator is only able to load the complete submatrix, which increase tehmemory requirements.

    4.5.2 Loading values of Localcolumns

    Depending on the request of the client Athos Runtime System tries to load only the required valuesof the localcolumn. When the client ask for only a part of the values this part is only loaded whenthe translator is able to load only these parts. When the values of one localcolumn is requestedonly the values of this localcolumn is loaded.

    Some implementations can improve the performance of loading the values when the values of alllocalcolumn of a submatrix are loaded at once. This will reduce the database query for the externalcomponent description. But the used memory increase rapidly and the localcolumn cache can beto small to load the values of all localcolumn of a submatrix. There is a INI-File variable TRY_-LOAD_SUBMATRIX which will force the Athos Runtime System to load the values of all localcolumnof a submatrix at once. When there is not enough memory in the localcolumn cache, the valuesof the localcolumn is loaded seperate and the performance will be less.

    This variable is also used to load the localcolumns of the submatrix when the application elementof AoLocalColumn is a virtual application element (E.g. Translator avl3).

    The translators MME1 or MMD3 are able to load the values of submatrix even faster, dependingof the the sequence_representation of the localcolumn. When the values are stored in externalcomponent �les and the INI-File variable LOAD_COMPLETE_SUBMAT is set the translators load thevalues of the all localcolumn at once with only one read at the database for the measurement_-quantities, the localcolumn and the external component instances, which reduce the overhead inthe translator to load the values. When the values are not stored in external component �les theINI-File variable will reduce the performance a little bit.

    This variables has also in�uenece loading the values from the table SVCVAL_SPS, the single pointstorage. When these variables are set to 'YES' the translator MME1 will load the values of thesubmatrix and not of the localcolumn which will reduce the numner of interqactions with thedatabase and increase the performance when the values of many localcolumns of a submatrix arerequested.

    4.6 Load the translator

    A translator used by the Athos Runtime System by simply specifying its name and directory inthe [SERVICE] section of an INI-File as follows:

    DRIVER = mme1

    DIRECTORY = "///$(ATHOS_ROOT)/bin/$(OSTYPE)/"

    The translators are designed as dynamic link libraries, shared objects, shared libraries or sharedimages, depending on the actual operating system, loaded at runtime. The Athos Runtime Systemknows for all supported operating systems how to load translators on request at runtime. Except

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 12 Con�guration

    the INI-File entry, no additional user interaction is required. The loading process is very e�cient(operating system feature), fully automated and transparent to the users of the Athos Toolkit.

    The supported OSTYPE are

    WIN32 for windows with 32-bit application (x86)

    WIN64 for windows with 64-bit application.

    Linux for linux systems.

    4.7 Con�guration ASAM-ODS API

    The Athos-based ASAM-ODS API is highly con�gurable and adaptable to a multitude of di�erentrequirements. The con�guration may be done via an initialization �le as described in the AthosRuntime System Technical Reference Sheet.

    The table in this document shows all supported con�guration variables including their names,descriptions, default values and source. All Athos Runtime System con�guration variables arealso considered since this API implementation is written on top of the Athos Runtime System.

    4.8 ODS Session data source connect handling.

    When a new ODS session is created, the �rst time the connection of the data storage is created, allother sessions use these connection to the data storage also. Depending on the translator, the datastorage can be an ATF(XML) �le or a database. There are two ways to for the implementationnot to use the connection created the �rst time but to create a new connection.

    1. REOPEN_VARIABLE, in the INI-File the reopen variable is de�ned and in the auth-stringof the method newSession of the interface AoFactory this variable is used. This is normallyused to open a new ATF(XML) �le. The REOPEN_VALRIABLE = FILENAME and inthe auth-String the parameter "FILENANE=.." is given will force the implementation tothe connection to the data storage, the values in the auth-string will be stored as INI-�levariable prior the data storage is opened, when the variable is not found in the auth-stringthe existing connection to the data storage is used.

    2. REOPEN_ALWAYS=YES, in the INI-File forces the implementation to create every time anew connection to the data storage when the method newSession of the interface AoFactoryor the method createCoSession of the interface AoSession is called. In case the datastorage is a database and the translator is able to update direct in the data storage theimplementation can use the transaction handling of the database. Because every ODS sessionhas his own connection to the database, the number of parallel connection to the databasewithin one connection is not required (NUMBER_DB_CONNECTION). Modi�cation ofthe model is also possible when each ODS session has his own database connection, so oneclient can modify the application model without in�uence on the other sessions.

    4.9 Con�guration license manager

    The con�guration to �nd the license manager is done with the global INI-File variable LICENSE_-LOCATION. The default of this variable is the �le avalon.lic in the directory ATHOS_ROOT\etc.When a license server is running, the port@host.

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 4.9 Con�guration license manager 13

    The license needs a host Id, the program rlmutil with the argument rlmhostid shows the host idof the system where the program runs, this is the system where the license manager runs. Whenthe license is a nodelock license the system where rlmutil must run is the same system as theavalon runs. With this host Id the license can be generated. For more details about the licensemanaging see the Reprise documentation.

    Built into every client of the license software is the ability to output environmental informationabout the application's use of RLM. To enable this, simply sets the environment variable RLM_-DIAGNOSTICS to the name of a �le, then runs the application. Once you call the �rst method,RLM will write diagnostic information to the �le name speci�ed.

    Note

    If you simply set RLM_DIAGNOSTICS without a value, the output will be sent to standardout - which may not be what you want.

    The resulting output will give the following information:

    time the program was run

    working directory

    relevant environment variables

    list of RLM's idea of the hostids on the machine where the application was run (includinghighqsoft ISV-de�ned hostids)

    the license �les in use, in the order RLM will use them (can be re-ordered from your normallist if RLM_PATH_RANDOMIZE is set).

    the parameters you used in your call to rlm_init()

    a list of all local licenses which can be checked out. This list will have any roaming licenseslisted �rst if RLM_ROAM is set, otherwise roaming licenses will be at the end of the list.In other words, the list will be in the order which RLM attempts to check them out. Eachlicense �le will also have an indication of what license server would be contacted if no locallicenses can satisfy the request.

    Note

    That for client-cached licenses, only the highest-numbered version will appear, even if thereare lower-version licenses available. And only licenses cached by the same RLM version willappear in this output.

    4.9.1 RLM Error code -130

    RLM reports the error -130, RLM is detecting clock-windback and not honoring expiring licenses.

    RLM detects windback by looking for future-dated �les (access and modi�ed times) in systemdirectories. In many cases just running the system for a little while with the correct date willaccess the future-dated �les and the problem will clear itself. Often a reboot helps too.

    If it doesn't clear itself, you will have to go into those directories and look for the o�ending �les,and set them to the current time by accessing them.

    On Windows, RLM is looking in or , and examining the accessed and modi�ed timestamps on allthe �les there. You can �nd the o�ending �le(s) in a command window with the commands

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 14 Con�guration

    dir /od /ta (displays and sorts on last access time) and dir /od /tw (displays and sorts on lastwrite time)

    On Unix/Linux systems, RLM is looking in /etc, /var/adm, and /var/log 'ls -ult' shows and sortsby access time; 'ls -clt' shows and sorts by modify time.

    4.9.2 User in license manager

    When a license is requested from the license manager and an ASAM ODS user is known, thelicense is requested for that ASAM ODS user. At most installation it is not allowed to show theuser in any log �le at all. In other cases the user or services must be shown in the log �le foraccounting purposes. The INI-File variable RLM_USERNAME de�ned the format of the user for whichthe license is requested. The default is a code username. The variable have keywords USER,PLAIN or / and SERVICE.

    USER

    the name of the ODS user in coded. E.g. 123456

    PLAIN

    the name of the ODS user in plain text. E.g. karst

    SERVICE

    the name of the service and the host where the avalon runs separated wit a dot, always plaintext. E.g. TestModel/DB.testserver

    The keywords USER, PLAIN can be combined they keyword SERVICE by any charac-ter. USER overwrite PLAIN when both are given the coded user will be used. Com-pibed value of the variable USER_SERIVCE which is identical with USER_PLAIN_SERIVCE,means the coded user name and service in plain text. E.g. 123456@TestModel/DB.testserverValue of the variable PLAIN_SERIVCE, means the user name and service in plain text. E.g.karst@TestModel/DB.testserver The length of the username is restricted to 32 characters.

    4.10 Usage ODS API Wildcard characters

    There are entries in the INI-File to de�ne the wildcard characters for the server. There are twosets of entries de�ned in the service part of the INI-File, the wildcard characters used by the clientand the wildcard characters used by the translator for the datastorage.

    The wildcard characters used by the client for the access to the server are the entriesWILDCARD_ONE. WILDCARD_ALL and WILDCARD_ESC. The default values are de�nedin the ASAM ODS documentation. The defaults are listed below and given in the ASAM-ODSAPI Con�guration variables (p. 191).

    WILDCARD_ONE = ?

    WILDCARD_ALL = *

    WILDCARD_ESC = \

    The client which supports the ASAM ODS version ODS API can set the parameters the way theyneed with the method setContext of the interface AoSession.

    The wildcard characters used by the translator for the access to the datastorage are documentedin the technical reference sheet of the used translator. The most common wildcard characterhandling of the translators are given below, but check the translator speci�c documentation for

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 4.11 ODS API handling Con�guration Variables 15

    detailed and correct information. The most translator use the de�nitions WILDONE, WILDALLand WILDESC. The default values of these parameter are the ASAM ODS defaults and givenbelow.

    WILDONE = ?

    WILDALL = *

    WILDESC = \

    For a database oriented storage the following parameters are required.

    WILDONE = _

    WILDALL = %

    WILDESC = [

    There are some ORACLE installations which required the following parameters for the aod1 andaod2 translator.

    WILDONE = _

    WILDALL = %

    WILDESC = \

    USE_ORACLE_ESCAPE = YES

    In ASAM-ODS API Con�guration variables (p. 191) is the explanation of all ODS APIcon�guration variables given.

    4.11 ODS API handling Con�guration Variables

    The con�guration variables are normally de�ned in the INI-File or the system environment. Atstartuptime, the ODS API reads the system environment variables and the INI-File, so all con�gu-ration variables stay constant for the run of the ODS API. There are some con�guration variableswhich can be changed at runtime. Some variables change only the con�guration of the currentsession other variables will change the behaviour of the ODS API. The variables are case sensitive.

    The following variables change the current session:

    USER and PASSWORD

    WILDCARD_ALL

    WILDCARD_ESC

    WILDCARD_ONE

    The following variables change the behaviour of the ODS API:

    ODS_LOGFILE

    DEBUGLEVEL

    The client can set the parameters the way they need with the method setContext of the interfaceAoSession.

    For more details see ASAM-ODS API Con�guration variables (p. 191).

    4.12 Store encrypted password

    The value of the base attribue password at the element of AoUser is initial an plain text password.With the method setPassword() of the interface AoSession is it possible to store the passwordMD5 encrypted. The ODS API stores default the password as plain text password. Use theINI-File variable USE_CRYPTED_PASSWORD to switch the ODS API to store an encrypted password.For more details see ASAM-ODS API Con�guration variables (p. 191).

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 16 Con�guration

    4.13 Open transaction at session close.

    When the session is closed (method close() of interface AoSession) and a transaction is stillopen an error is occured at the client. The client must commit (method commitTransaction() ofinterface AoSession) or abort (method abortTransaction() of interface AoSession) the trans-action properly. Depending on the con�guration variable SESSION_CLOSE_COMMIT in the INI-Fileof the ODS API, implementation knows what to do with the open transaction.

    SESSION_CLOSE_COMMIT = NO

    If the variable is set to 'NO' the transaction will be abort. Default or 'YES' means the transactionis commited. More details about the con�guration varables are given in ASAM-ODS APICon�guration variables (p. 191).

    4.14 Con�guration Avalon

    Before starting Avalon, the CORBA Name Service has to be started. Therefore access to the "bin"directory of the Java Runtime Environment (JRE) is required to start the name server daemon.

    A Naming Service is a CORBA service that allows CORBA objects to be named by means ofbinding a name to an object reference. The name binding may be stored in the naming service,and a client may supply the name to obtain the desired object reference.

    Prior to running client or a server, you will start ORBD. ORBD includes a persistent NamingService and a transient Naming Service, both of which are an implementation of the COS NamingService. This daemon is part of the JRE distribution. The Persistent Naming Service providespersistence for naming contexts. This means that this information is persistent across serviceshutdowns and startups, and is recoverable in the event of a service failure. If ORBD is restarted,the Persistent Naming Service will restore the naming context graph, so that the binding of allclients' and servers' names remains intact (persistent).

    The -ORBInitialPort Argument is a required command-line argument for orbd, and is used to setport number an which the Naming Service will run. The following instructions assume you canuse port 2809 for the Java IDL Request Broker Daemon.

    From a MS-Windows system prompt, enter:

    start orbd -ORBInitialPort 2809

    After starting the Name Service, Avalon may be start with the following command:

    avalon -NameServicePort 2809 -ServiceName "TestModel/DB"

    Speci�ng NameServicePort 2809 is optional, because this is the default. If the ServiceName isnot speci�ed, Avalon automatically uses the �rst service de�ned in the �le pointed to by theenvironment variable ATHOS_INI.

    Avalon may run on any service de�ned in the INI �le.

    In addition to the parameters NameServicePort and ServiceName Avalon supports the parameterNameServiceHost. Thus the NameService may run on any computer. The local host is the default.Example:

    avalon -NameServicePort 2809 -NameServiceHost localhost

    -ServiceName "TestModel/DB"

    The order of the parameters is not important. In case a parameter is given multiple times, thelast entry will be used.

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 4.15 Avalon using a LDAP-Plugin 17

    4.14.1 Avalon at the NameService

    Avalon publish the AoFactory object at the CORBA NameService. The client program shouldload the reference of the AoFactory at this CORBA NameService. The AoFactory will be pub-lished with two di�erent paths, the �rst one according the ASAM ODS de�niton with the path'org/asam/ods/ServiceName', the second with in the root with the name 'ServiceName.ASAM-ODS'.

    When the ServiceName contain a slash ("/"), like in the example "TestModel/DB", pub-lish this object in the root of the CORBA NameService is in con�ict with naming conver-tions of OMG CORBA. Avalon does this already from the beginning, publishing the AoFac-tory in the tree 'org/asam/ods' was later de�ned. The Avalon property Avalon.PublishInRootfalse will suppress the publish in the root of the CORBA NameService. With the propertyAvalon.NameServiceContext will overwrite the default 'org/asam/ods/' to the context tree inthe CORBANameService, when no argument is given to this property AoFactory will be publishedin the root of the CORBA NameService and the slashes in the name will be used as seperator forthe context tree. With the property Avalon.NameServiceContextKind ASAM-ODS the kind of theobject pubished in the CORBA NameService can be set for the object in the context tree.

    The example

    avalon -NameServicePort 2809 -NameServiceHost localhost

    -ServiceName "TestModel/DB"

    will publish the following objects in the CORBA NameService

    TESTMODEL\DB.ASAM-ODS

    org

    asam

    ods

    TestModel

    DB

    The example

    avalon -NameServicePort 2809 -NameServiceHost localhost

    -ServiceName "TestModel/DB" -Avalon.PublishInRoot false

    -Avalon.NameServiceContext

    -Avalon.NameServiceContextKind ASAM-ODS

    will publish one following object in the CORBA NameService

    TESTMODEL

    DB.ASAM-ODS

    Which will reduce the entries in teh CORBA NameService and allows project speci�c trees at theCORBA NameService.

    4.15 Avalon using a LDAP-Plugin

    Avalon supports the connection to a LDAP-server or another authentication server. Avalon willcall, when con�gured, the methods of the plugin at every invocation of the method newSessionor newSessionNameValue of the interface AoFactory.

    The LDAP-plugin checks the authentication with the LDAP-server, when the LDAP-server grantaccess rights, the plugin has to create an authentication string for ASAM ODS. This authenticationstring depends on the ASAM ODS security used in the customer application model.

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 18 Con�guration

    E.g. The username is loaded from the LDAP-server and all users have the same password in theASAM ODS storage, the authentication sting can be "USER=me, PASSWORD=all_the_same"

    E.g. The LDAP-server knows which role the user has in the ASAM ODS storage and foreach role is an user de�ned in ASAM ODS the authentication can be "USER=role_engeneer,PASSWORD=engeneer". A same pattern can be used for the project or role in a project.

    E.g. The plugin knows the superuser login to the ASAM ODS storage, loads the username fromthe LDAP-server and use the FOR_USER keyword in the authentication string USER=superuser,PASSWORD=very_secret, FOR_USER=me" The FOR_USER is a feature available in ASAM ODS 5.3which has a prototype implementation in Avalon 4.1 and later. The plugin can also check if theuser exist in the ASAM ODS storage and when the user don't exist creates an instance of theuser, so the connect will succeed. The user has in this case no access to any element / instanceswhich is protected by security and the ASAM ODS storage administrator has to create a relationto the required usergroups.

    The method NameValue[] checkAuthNameValue(NameValue[] nvauth, String factory) willbe called in case the method newSessionNameValue of interface AoFactory is called by the client.Each item in the array represent a variable. The name of the variable is stored in the �eld valName,the value is stored in the �eld value, with type org.asam.ods.TS_Value. To read the value youneed the �eld u of the �eld value which is of the type org.asam.ods.TS_Union. In case the TS_-Union has the discriminator DT_STRING the real value is return with the method stringVal().See NameValue of the ASAM ODS OO API. An example is given in pseudo code below.

    NameValue[] nvAuth = new NameValue[]

    {

    new NameValue(valName="USER" value.u.stringVal("me")),

    new NameValue(valName="PASSWORD" value.u.stringVal("all_the_same"))

    }

    The main advandage of the LDAP-plugin is that there is only on place the rules of the passwordhandling of the company is de�ned. Even using the LDAP-plugin, the ASAM ODS security mustbe de�ned, the LDAP-plugin can ony protect against unauthorized access. When the Avalon iscon�gured to start with an LDAP-plugin any other access the the Avalon is not possible.

    Client Avalon ODSAPI LDAPPluginnewSession(LDAP-auth)

    checkAuth(LDAP-auth)

    auth

    newSession(auth)

    aoSession

    aoSession

    newSession Request with LDAP Plugin

    The implementation of the class is customer dependent but there is a prototype implementationavailable.

    The interface which the plugin-class has to ful�ll is com.highqsoft.avalon.LDAPCheckInterface.

    /* @(#) $Id: LDAPCheckInterface.java,v 1.16 2017/04/06 13:28:33 adil Exp $

    ****************************************************************************

    * COPYRIGHT (c), HighQSoft GmbH, All Rights reserved. *

    ****************************************************************************

    * HighQSoft GmbH *

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 4.15 Avalon using a LDAP-Plugin 19

    * Black-und-Decker-Strasse 17c, D-65510 Idstein, Germany *

    * www.highqsoft.de *

    ****************************************************************************

    * *

    * This software is the confidential and proprietary information of *

    * HighQSoft GmbH. *

    * *

    * All brand names and product names used in this software are trademarks, *

    * registered trademarks, or trade names of their respective holders. *

    * The authors of this software are not associated with any product or *

    * vendor mentioned in the code or documentation. *

    * *

    ****************************************************************************

    */

    package com.highqsoft.avalon;

    import org.asam.ods.AoException;

    import org.asam.ods.NameValue;

    /**

    * The LDAPCheck interface.

    * Implementors can use RuntimeException at every point to signal internal problems.

    * If the implementation allows a default constructor, AoFactory will use it to get an instance.

    * If the implementation doesn't allow the default constructor, AoFactory tries to get the instance

    * by passing an options string to the constructor.

    * Once an instance is created by the AoFactory, it will be used before a session is created to convert

    * the options string of session.

    *

    * @author karst

    * @version $Revision: 1.16 $

    * @see com.highqsoft.avalon.AoFactory

    * @see com.highqsoft.avalon.LDAPCheckImpl

    * @since $Date: 2017/04/06 13:28:33 $

    */

    /*

    Modification History:

    $Log: LDAPCheckInterface.java,v $

    Revision 1.16 2017/04/06 13:28:33 adil

    update copyright.

    Revision 1.15 2015/08/03 15:51:47 karst

    Add some comment.

    Revision 1.14 2015/05/20 13:06:24 karst

    Update Copyrights to current.

    Revision 1.13 2013/01/03 09:07:01 karst

    Update copyright to 2013.

    Revision 1.12 2012/09/12 14:27:56 elke

    interface checkAuthNameValue added

    Revision 1.11 2012/01/04 08:13:51 karst

    Update copyright to 2012.

    Revision 1.10 2011/01/05 09:02:34 karst

    Update copyright header to 2011

    Revision 1.9 2010/01/11 07:56:11 karst

    Update header comment to current

    Revision 1.8 2009/04/03 09:44:32 karst

    Add the AoException to the checkAuth method.

    Revision 1.7 2009/01/05 09:25:56 karst

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 20 Con�guration

    Modify copyright to 2009

    Revision 1.6 2008/10/21 06:59:40 karst

    Correct typing error.

    Revision 1.5 2008/01/10 09:24:08 karst

    Change copyright to current.

    Revision 1.4 2006/11/28 12:15:24 karst

    Reorganize the comment.

    Revision 1.3 2005/09/13 13:49:29 andy

    Comment added.

    Revision 1.2 2005/09/13 11:53:07 andy

    Change Exception handling.

    Add/Change comment.

    Revision 1.1 2005/09/12 12:43:40 karst

    Initial version

    */

    public interface LDAPCheckInterface {

    /**

    * Initialize the LDAP communication.

    * This method is called once directly after the instance was created.

    *

    * @param factory the name of the factory or service

    */

    public void init(String factory);

    /**

    * Check the authentication string at the LDAP Server. This method is called by AoFactory

    * at every time a new session should be created. The implementation can use the authentication

    * string coming from client and the name of the factory to return an authentication string

    * that will be used to create a new session.

    *

    * @param auth the authentication string

    * @param factory the name of the factory or service

    * @return the new authentication string from the LDAP server

    * @throws the ASAM ODS Exception whit the error code AO_CONNECT_REFUSED.

    */

    public String checkAuth(String auth, String factory) throws AoException;

    /**

    * Check the authentication namevalue array at the LDAP Server. This method is called by AoFactory

    * at every time a new session should be created. The implementation can use the authentication

    * name value array coming from client and the name of the factory to return an authentication

    * name value array that will be used to create a new session.

    *

    * @param nvauth the authentication namevalue array

    * @param factory the name of the factory or service

    * @return the new authentication name value array from the LDAP server

    * @throws the ASAM ODS Exception whit the error code AO_CONNECT_REFUSED.

    */

    public NameValue[] checkAuthNameValue(NameValue[] nvauth, String factory) throws AoException;

    /**

    * Close the connections that are necessary to made the checks.

    * This method will be called when the AoFactory finalize method is started.

    */

    public void close();

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 4.16 Avalon using a new session-Plugin 21

    }

    A prototype implementation is given in the class com.highqsoft.avalon.LDAPCheckImpl.

    Avalon have two properties to control the LDAP-Plugin:

    Avalon.LDAPClass.Name

    The name of the class for the LDAP access to check the authentication with an LDAP server.

    Avalon.LDAPClass.Options

    The option string for the constructor for the LDAP access to check the authentication withan LDAP server.

    The following command starts the avalon with the prototype plugin and gives an option string tothe constructor:

    avalon -ServiceName TestModel/DB

    -Avalon.LDAPClass.Name com.highqsoft.avalon.LDAPCheckImpl

    -Avalon.LDAPClass.Options "My personal LDAP constructor options"

    The following command starts the avalon with the customer plugin with the classnamecom.mycompany.avalon.LDAPCheckImpl and compiled in the jar �le LDAPImpl.jar and givesan option string to the constructor:

    java -classpath Avalon.jar;LDAPImpl.jar com.highqsoft.avalon.Avalon

    -ServiceName TestModel/DB

    -Avalon.LDAPClass.Name com.mycompany.avalon.LDAPCheckImpl

    -Avalon.LDAPClass.Options "My company LDAP constructor options"

    For more information see the documentation of the interface or in the properties.

    4.16 Avalon using a new session-Plugin

    Avalon has a plugin which will be called when a new session is created or closed or when thesession will be closed at the next check for the inactive sessions.

    This plugin can be used for statistic when the user logins. Checks the user is not disabled. Checksthe user is only allowed to loggin in a certain time frame. Check the user is logged on only once.

    Two di�ernt plugin's can be con�gured, one when a new session is created andone when the session is closed. The con�guration of the plugin is done withthe properties Avalon.NewSessionClass.Name and Avalon.NewSessionClass.Optionsor Avalon.SessionCloseClass.Name and Avalon.SessionCloseClass.Options orAvalon.SessionWillCloseClass.Name and Avalon.SessionWillCloseClass.Options.

    The plugin of the new session is called after the methods newSession of the interface AoFactoryand the method createCoSession of the interface AoSession. The plugin of the close session iscalled before the method close of the interface AoSession. The plugin of the "will close session"is called when the session watchdog recognize the next checks will close this session. When sucha plugin is con�gured and the plugin accesses the session, E.g. to read the Id of the ssesion, thesession will never close and the plugin is reponsable to close the session. Each access to the sessionwill tell Avalon there is activity and the session will not be closed at next check, the activity isnot from the user but only of the plugin which normally should force the session to close.

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 22 Con�guration

    Client Avalon ODSAPI NewSessionPluginnewSession(auth)

    newSession(auth)

    aoSession

    checkSession(aoSession)

    aoSession

    NewSession request with Session Plugin

    Client Avalon ODSAPI CloseSessionPluginclose()

    checkSession(aoSession)

    close()

    Close request with Session Plugin

    Client Avalon ODSAPI WillCloseSessionPlugincheckSession(aoSession)

    WillClose sequence with Session Plugin

    All plugins must implement the same interface com.highqsoft.avalon.SessionCheckInterfaceor com.highqsoft.avalon.SessionCheckInterfaceEnhanced , the method checkSession iscalled and the plugin can use the complete ASAM ODS API to check the session. The plugin canthrow an AoException when the access is denied.

    Because the plugin is running inside the server some extra CORBA methods are required. Thefollowing code will not work:

    InstanceElement user = aoSession.getUser();

    The object must be converted from an CORBA-Oject to an ODS-Object so the following code isneed

    org.asam.ods.InstanceElement user = InstanceElementHelper.narrow(aoSession.getUse

    r());

    Note

    Access to the session in the CloseSessionPlugin will cause an AoException, because thesession is already closed and further access is not allowed.

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 4.16 Avalon using a new session-Plugin 23

    /* @(#) $Id: SessionCheckInterface.java,v 1.9 2017/04/06 13:28:35 adil Exp $

    ****************************************************************************

    * COPYRIGHT (c), HighQSoft GmbH, All Rights reserved. *

    ****************************************************************************

    * HighQSoft GmbH *

    * Black-und-Decker-Strasse 17c, D-65510 Idstein, Germany *

    * www.highqsoft.de *

    ****************************************************************************

    * *

    * This software is the confidential and proprietary information of *

    * HighQSoft GmbH. *

    * *

    * All brand names and product names used in this software are trademarks, *

    * registered trademarks, or trade names of their respective holders. *

    * The authors of this software are not associated with any product or *

    * vendor mentioned in the code or documentation. *

    * *

    ****************************************************************************

    */

    package com.highqsoft.avalon;

    /**

    * The NewSessionCheck interface.

    *

    * The interface methods are called each time a new session is created or before the session is closed.

    *

    * @author karst

    * @version $Revision: 1.9 $

    * @since $Date: 2017/04/06 13:28:35 $

    */

    /*

    Modification History:

    $Log: SessionCheckInterface.java,v $

    Revision 1.9 2017/04/06 13:28:35 adil

    update copyright.

    Revision 1.8 2016/09/05 13:17:21 karst

    Update comment.

    Revision 1.7 2015/05/20 13:06:24 karst

    Update Copyrights to current.

    Revision 1.6 2013/01/03 09:07:01 karst

    Update copyright to 2013.

    Revision 1.5 2012/01/04 08:13:51 karst

    Update copyright to 2012.

    Revision 1.4 2011/01/05 09:02:34 karst

    Update copyright header to 2011

    Revision 1.3 2010/01/11 07:56:11 karst

    Update header comment to current

    Revision 1.2 2009/01/05 09:25:56 karst

    Modify copyright to 2009

    Revision 1.1 2008/02/20 09:23:36 karst

    Initial version

    */

    public interface SessionCheckInterface {

    /**

    * Initialize the session communication.

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 24 Con�guration

    * This method is called once directly after the instance was created.

    *

    * @param factory the name of the factory

    */

    public void init(String factory);

    /**

    * Method called every time the new session is created or before the session is closed.

    *

    * @param aoSess the new created session.

    * @throws org.asam.ods.AoException any occurring ASAM ODS exception.

    */

    public void checkSession(org.asam.ods.AoSession aoSess) throws org.asam.ods.AoException;

    /**

    * Close the connections that are necessary to made the checks.

    * This method will be called when the AoFactory finalize method is started.

    */

    public void close();

    }

    The following command starts the avalon with the customer plugin with the classnamecom.mycompany.avalon.NewSessionImpl and compiled in the jar �le NewSesisonImpl.jar andgives an option string to the constructor:

    java -classpath Avalon.jar;NewSessionImpl.jar com.highqsoft.avalon.Avalon

    -ServiceName TestModel/DB

    -Avalon.NewSessionClass.Name com.mycompany.avalon.NewSessionImpl

    -Avalon.NewSessionClass.Options "My company NewSession constructor options"

    For more information see the documentation of the interface or in the properties.

    Note

    SessionWillClose Every method call from on the session object results in resetting of theinternal �ags number of access and not used �ag . This has the consequence that the nextwatchdog cycle is not closed. SessionClose The session is closed, so the plugin can't performany method calls on the session object.

    4.17 Firewall Settings

    There are some network dependencies to start and connect Avalon. This section explains theenvironment for the CORBA name service (ORB - Object Request Broker), Avalon and the ASAMODS client.

    First of all we have to con�gure and start the CORBA name service. The ORB must know theportnumber for the communication with Avalon and the ASAM ODS client. If we want to startthe ORB coming with Java (1.6) the default port is 900 and we are able to con�gure the portusing a startup parameter:

    orbd -ORBInitialPort 2809

    This example starts the ORB listening on port 2809. This must be done on Linux systems.

    The next step is to start Avalon. It must known the port number that is used by ORB.

    avalon -NameServicePort 2809 [-NameServiceHost -ServiceName]

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 4.18 UTF-8 as character set for the Avalon. 25

    Avalon creates then a CORBA reference and registers this reference at the ORB. The port 1049is used to communicate with the ORB. This port is the default for SUN's implementation andwe don't known how to change this setting. For a Linux system the localhost must referencethe network address (!! not the loopback !!), because the Java ORB uses the localhost alias forbuilding the IOR information.

    If you want to verify the IOR you can do the following. Start Avalon by passing the propertyAvalon.PrintNameServiceIOR:

    avalon -NameServicePort 2809 [-NameServiceHost -ServiceName] -AvalonPrintNameServiceIOR

    Now Avalon prints the IOR registered at the ORB. Start an internet browser and go to the page

    http://www2.parc.com/istl/projects/ILU/parseIOR/

    Here you can enter (cut/copy/paste) the IOR string. Use the buttons to analyze the string andyou can see the coded settings of the reference.

    The ASAM ODS client tries to �nd the CORBA name service by the same way. Using the port2809 to �nd the service and using 1049 as communication port. Then the ORB returns theCORBA reference of the ASAM ODS service and assigns the port 1128 for communication withthat service. This port depends on the implementation of the ORB and we don't known how tochange this setting.

    This was tested under Linux (SuSE 10.0) and Java ORB (1.4.2_09). Avalon and the ORB run onthe same machine. If a �rewall was started on the server machine and the client should be startedon another machine, it is necessary to enable the ports in the �rewall con�guration. If you are notsure what ports are used by this game, take a look into the log �le of your �rewall.

    Port 2809/tcp

    �nd ORB

    Port 1049/tcp

    communicate with ORB

    Port 1128/tcp

    communicate with ASAM ODS service

    4.18 UTF-8 as character set for the Avalon.

    Using UTF-8 as character set for the Avalon there are di�erent settings to be done, the database,ATHOS Runtime System and the Avalon Java Native Interface and CORBA.

    Note

    The oracle characterset or language setting must be done in the environment. ATHOS_-CHARACTERSET must be set in the environment also. The settings are required before theINI-File is read. The FILENAME_CHARACTERSET is a global INI-File variable which shouldcome in the section [ATHOS] and not set at any services.

    First of all the characterset of the database must be set to UTF-8. This depends on the useddatabase for oracle the you can use the environment variable

    NLS_CHARACTERSET=AL32UTF8

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 26 Con�guration

    or do the settings in the Windows registry. See the oracle documentation. On some Linux systemssetting of NLS_CHARACTERSET seems to be without any in�uence. To switch the character set onUTF-8 the NLS_LANG must be set.

    NLS_LANG=AMERICAN_AMERICA.AL32UTF8

    You can use also the INI-File variable ORACLE_NLS_LANG in case of the translator mme∗.At some system NLS_CHARACTERSET is not enough and NLS_LANG must be set also, E.g.for ISO 8859-1 use:

    NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1

    ATHOS Runtime System uses as default the characterset ISO-8859-1, there are several characternot available in this characterset, with the environment varaible

    ATHOS_CHARACTERSET=UTF-8

    ATHOS Runtime System will use UTF-8 characterset. This characterset is also used in the AvalonJava Native interface. For more detail see Athos Runtime System Con�guration variables(p. 177). The client can read this variable as a context variable in the session. This variable is notpart of the list of context variables.

    The CORBA implementation of Sun, the SunORB, the default implementation used by the Avalon,uses also for the transport of String the characterset ISO-8859-1. The implementation can be forceto use also UTF-8 with the following startup arguments

    -ORBProperty[com.sun.CORBA.codeset.charsets] "0x05010001, 0x00010109"

    -ORBProperty[com.sun.CORBA.codeset.wcharsets] "0x00010109, 0x05010001"

    The number are de�ned in the registry and part of the CORBA speci�cation. Better is to setthese value direct as JAVA properties with the -D option. Use the follwing con�guration in theAvalonService.cfg when Avalon is running as Windows service.

    -Dcom.sun.CORBA.codeset.charsets=0x05010001,0x00010109

    -Dcom.sun.CORBA.codeset.wcharsets=0x00010109,0x05010001

    When all settings are correct CORBA, ATHOS Runtime System and the database characterset ofAvalon will handle UTF-8 characters. ATHOS Runtime System will set the ODS de�ned contextvariable SERVER_CHARSET according the setting of the environment variable ATHOS_CHARACTERSET.

    When JacORB is used as CORBA implementation set the following properties in the property �lefor JacORB.

    jacorb.codeset=ON

    jacorb.native_char_codeset=UTF8

    jacorb.native_wchar_codeset=UTF8

    The property jacorb.codeset have the default value ON, but please check it with your JacORBimplementation.

    Note

    Athos use for the conversion the library iconv, this library have a de�ned list of names whichcan be converted. On Windows the name of the characterset for UTF-8 is only "UTF-8" onlinux is also "UTF8" allowed. JacORB have also de�ned strings, for UTF-8 the string is only"UTF8", so theres is a di�erence between the setting for iconv and JacORB, so there is adi�erence for the environment variable ATHOS_CHARACTERSET and the JacORB properties.

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 4.19 Session watchdog in Avalon 27

    When the characterset of the system is not ISO 8859-1, the global INI-File variable FILENAME_-CHARACTERSET must be set for the �lenames handled by the ATHOS Runtime System which havecharacters above the ASCII 128 range. The �lenames will be internally converted to FILENAME_-CHARACTERSET, when this characterset do not match with the characterset of the system wherethe Avalon is running there will be problems to open the �les.

    Note

    Most CORBA-implementations are able to exchange the used characterset and they will usedthe characterset with the widest range (UTF-8 and not ISO 8859-1). So it is enough to setthe properties for CORBA only on Avalon and the client will communicate also with UTF-8.In some cases it is also required to set the properties also on the client.

    4.19 Session watchdog in Avalon

    Avalon has a session watchdog implemented, this watchdog will close sessions which are not usedfor a longer time. The watchdog runs every 10 Minutes, �xed in avalon code, but it is con�gurablewhen Avalon will close the session. The value of the propery Avalon.SessionWatchdogCountis the number of counts before the session is closed. Each time when the watchdog runs it willincrease the counter, each access to the session or any object from the session the counter will beset to 0. When the watchdog �nd a session with a value of the counter bigger the then the value ofthe propery, the session will be closed. The default value of the property is 3, so default a sessioncan be inactive between 30 until 40 minutes before the session is closed.

    As long as a session is opened, the session uses memory in Avalon, so the Avalon has to killsometimes an inactive session, otherwise avalon runs out of memory. You can increase the numberof watchdog counts but this will increase also the memory usage of Avalon for a longer time whena session is inactive. When a client exits without closing the session, this session will becomeinactive and only the wactdog can close such a session.

    4.20 Worker mode in Avalon

    When Avalon is used with Avalon Distributor, this �ag must be set to true. In this mode, Avalondo not register in name service, instead Avalon is looking for Avalon Distributor entry in nameservice and tries to register itself by Avalon Distributor. All new session requests from clients aresend to Avalon Distributor, which distribute the request to one of the registered Avalon server.

    4.21 Avalon con�guration �le

    At starttime, avaon tries to read the con�guration �le. At �rst, avalon looks for the startupparameter: Avalon.ConfigurationFile . When the parameter is not passed, avalontries to extract the name from the environment variable AVALON_INI. At least Avalon search the�le Avalon.xml in the current directory.

    The con�guration �le contains access rights for the functions and variables of the avalon controlinterface. The following example shows the parts of the �le.

    Technical Reference Sheet Avalon

    © 2020/06/30 version 4.9a

    HighQSoft Karst Schaap

    http://www.highqsoft.com

  • 28 Con�guration

    ListSession

    username1, username2

    admin, development

    Get

    admin, development

    Set

    admin

    ...

    ...

    Debuglevel

    username1, username4

    admin, all

    [

    admin

    ...

    ...

    The access right de�nitions for avalon control interface are divided into separate parts for functionsand variables. For each function it is possible to de�ne the execution for groups and or users (entries'user' and 'group'). Every control variable contains to access de�ntion. One for read access andone for write access.

    When no access de�nition for a speci�c function or variable exist, the access is only for super userallowed.

    In the Avalon Documents folder there is a directory template with an Avalon con�guration sample�le. This �le contains all possible control functions and control variables.

    Hint: It is possible, that athos.ini contains additional restrictions on some variables.

    4.22 Con�guration Avalon Distributor

    Before starting Avalon Distributor or any Avalon's in worker mode (Avalon Worker), the CORBAName Service has to