Druck vom 24. 01.2001 17:00.14 umschlag
GINA V4.0
General Interface for Network Applications
System Administrator Guide
Comments
Suggestions
Corrections
The User Documentation
Department would like to know
your opinion on this manual.
Your feedback helps us to
optimize our documentation to
suit your individual needs.
Fax forms for sending us your
comments are included at the
back of the manual.
Order number of this manual:
GINA V4.0 System Administrator Guide – September 2000
Druck vom 24. 01.2001 17:00.15 titel
GINA V4.0
General Interface for Network Applications
System Administrator Guide
Edition September 2000
Copyright and Trademarks
GINA is a registered trademark of Siemens Business Services GmbH & Co OHG.
®
Copyright © Siemens Nixdorf Informationssysteme AG 1990.
SINIX
SINIX is the UNIX
®
Reliant
is a registered trademark of Pyramid Technology Corporation.
UNIX is a registered trademark in the United States and other countries, licensed exlusively through
X/Open Company Limited.
Base: OSF/Motif™, Copyright © Open Software Foundation, Inc.
X Window System™, Copyright © Massachusetts Institute of Technology.
OSF/Motif is a registered trademark of Open Software Foundation, Inc.
X Window System is a registered trademark of Massachusetts Institute of Technology.
Copyright © Siemens Business Services GmbH & Co OHG 2000.
All rights reserved.
Delivery subject to availability; right of technical modifications reserved.
All hardware and software names used are trademarks of their respective manufacturers.
®
System derivative of Siemens Nixdorf Informationssysteme AG.
Introduction
Changes since Version 3
Installation and deinstallation
Creating GINA applications
Configuring the Persistency Service
Configuring T-ORB for
Configuring T-ORB for BEATUXEDO
Operating GINA applications
Glossary
Abbreviations
open
UTM
Continued
Related publications
Index
Druck vom 24. 01.2001 17:00.16 verwivz.doc
Contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2 Changes since Version 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1 Interface cancelations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3 Installation and deinstallation . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.2 Scope of supply and structure of GINA . . . . . . . . . . . . . . . . . . . . . . 11
3.2.1 Delivery package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2.2 Licensing of GINA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.2.3 Directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.3.1 UNIX (Solaris, SINIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.3.2 UNIX / HP-UX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.3.3 Windows NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.3.4 BS2000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
3.3.5 Environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.4 Deinstallation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.4.1 UNIX (Solaris, SINIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.4.2 UNIX / HP-UX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.4.3 Windows NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.5 Availability, restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4 Creating GINA applications . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.1 Application variants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.2 Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.3 The generators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.4 Makefiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5 Configuring the Persistency Service . . . . . . . . . . . . . . . . . . . . . . 31
5.1 Setting up the database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
GINA V4.0 System Administrator Guide – September 2000
5.2 Customizing the database layout . . . . . . . . . . . . . . . . . . . . . . . . . . 33
5.2.1 The pfx file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.2.2 The tbl file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
5.2.3 Further options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
6 Configuring T-ORB for
open
UTM . . . . . . . . . . . . . . . . . . . . . . . . . 43
6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
6.2 Configuration language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
6.2.1 Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
6.2.2 Lexical structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.2.3 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
6.3 Revision generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6.4 Sample configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
6.5 Call and options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
6.6 Generated files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
6.6.1 Generated files for UNIX hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
6.6.1.1 Development option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
6.6.1.2 Runtime option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
6.6.2 Generated files for WindowsNT hosts . . . . . . . . . . . . . . . . . . . . . . . 99
6.6.2.1 Development option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
6.6.2.2 Runtime option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
6.6.3 Generated files for BS2000/OSD hosts . . . . . . . . . . . . . . . . . . . . . . . 101
6.6.3.1 Development option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
6.6.3.2 Runtime option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
6.6.4 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
6.7 Creating a configuration file using WinConfig . . . . . . . . . . . . . . . . . . . 103
6.7.1 Calling WinConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
6.7.2 Elements of the graphical user interface . . . . . . . . . . . . . . . . . . . . . . 105
6.7.2.1 Host edit window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
6.7.2.2 Application edit window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
6.7.2.3 WinConfig menu bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
6.7.3 Mouse key assignments and mouse actions . . . . . . . . . . . . . . . . . . . . 153
7 Configuring T-ORB for BEA T
UXEDO . . . . . . . . . . . . . . . . . . . . . . . 155
7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
7.2 Configuration language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
7.2.1 Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
7.2.2 Lexical structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
7.2.3 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
7.3 Revision generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
7.4 Sample configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
7.5 Call and options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
GINA V4.0 System Administrator Guide – September 2000
Druck vom 24. 01.2001 17:00.17 verwivz.doc
7.6 Generated files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
7.6.1 Generated files for UNIX hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
7.6.2 Generated files for WindowsNT hosts . . . . . . . . . . . . . . . . . . . . . . . 181
7.6.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
7.7 BEA TUXEDO domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
7.7.1 Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
7.7.2 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
7.7.3 Example of a configuration file with domains . . . . . . . . . . . . . . . . . . . . 188
7.7.4 Generated files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
7.7.5 Special points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
8 Operating GINA applications . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
8.1 Communication administration . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
8.1.1 Communication structure of a server application . . . . . . . . . . . . . . . . . . 193
8.1.2 Communication structure of a client application . . . . . . . . . . . . . . . . . . 193
8.2 DB administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
8.2.1 Security management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
8.2.2 Data backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
8.2.3 Logging database errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
8.3 Starting and stopping GINA applications . . . . . . . . . . . . . . . . . . . . . . 196
8.3.1 Environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
8.3.2 Transaction-monitored applications . . . . . . . . . . . . . . . . . . . . . . . . 196
8.3.3 Non-transaction-monitored applications . . . . . . . . . . . . . . . . . . . . . . 196
8.4 Administering GINA applications . . . . . . . . . . . . . . . . . . . . . . . . . . 199
8.4.1 TP monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
8.4.2 Cyclical timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
8.4.3 Monitoring alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
8.4.4 Cyclical tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
GINA V4.0 System Administrator Guide – September 2000
GINA V4.0 System Administrator Guide – September 2000
Druck vom 24. 01.2001 17:00.18 einleit
1 Introduction
GINA (General Interfacefor Network Applications) provides a framework for the implementation and operation of object-oriented, transaction-oriented client/server applications. The
GINA-API is an object-oriented solution forthe mixed,distributed applicationswhich are encountered everywhere in modern business life.
GINA is suitable for use in many types of client/server environment– for systems which
place high demands on the criteria of data consistency and reliability (business-critical applications) as well as for the rightsizing of mainframe-based systems for decentralized online transaction processing (OLTP).
GINAis based onstandardsand can adaptto individual circumstances.Theobject-oriented
paradigmsavesprogrammingtime andmakessystem structures clearer.Modifications and
corrections are easier. GINA is a high-performance development environment for distributed and persistent objects.
GINA is an open system and provides connectivity to external OLTP systems in a variety of
environments such as the BS2000 or MVS environments.
About this manual
This manual is intended for system administrators who need to install GINA or applications
used by GINA. It describes how the communications system and GINA applications are
configured.
This manual also deals with the operation of GINA applications in client/server environments.
Developers and programmers of GINA applications may also want to refer to this manual
on occasions.
For more information, please contact us at the address below:
Siemens Nixdorf Informationssysteme AG
SBS MPM CPI
Otto-Hahn-Ring 6
81739 München
Fax (089) 636-48 303
E-Mail gina.service@mch20.sbs.de
GINA V4.0 System Administrator Guide – September 2000 1
Structure of this manual
Chapter 1 describes the structure and contents of this manual as well as other docu-
mentation on GINA.
Chapter 2 contains a listing of the essential changes since the last version of this man-
ual as well as a brief description of each.
Chapter 3 Installation and deinstallation
describes the installation of GINA, including prerequisites.
Chapter 4 Creating GINA applications
describes the necessary steps in creating GINA applications.
Chapters 5 ... 8
describe the configuration and administration of GINA applications:
Chapter 5 Configuring the Persistency Service
Chapter 6 Configuring T-ORB for openUTM
Chapter 7 Configuring T-ORB for BEA TUXEDO
Chapter 8 Operating GINA applications
The Glossary and Abbreviations chapters explain important technical terms and abbreviations.
The Related publications section contains a list of manuals and secondary literature.
The table of contents and index simplify the task of finding information.
Documentation on GINA
GINA Introductory Guide
This manual provides a brief summary of the performance characteristics and underlying philosophy of GINA. It also presents the various
components which make up GINA.
GINA
Introductory Guide
It is aimed at decision-makers who want to assess the possible usefulness of GINA or users who intend to work with GINA and want to become familiar with its structure.
2 GINA V4.0 System Administrator Guide – September 2000
Druck vom 24. 01.2001 17:00.18 einleit
G
G
GINA
Developer
Manual
GINA
Reference
Manual
Persist. Service
GINA Developer Manual
This manual is intended for developersof GINA applications. It provides
a detailed description of GINA concepts and gives practical instructions
and assistance for use.You should read this manual first as it describes
the theory and principles on which GINA is based.
Application developers should be familiar with the fundamentals of the
object-oriented paradigm; knowledge of C++ is essential.
INA Reference Manual Persistency Service
This is the manualfor GINA application programmers.It contains formal
descriptions of Persistency Service interfaces set out in alphabetical
order.
It also contains descriptions of the associated tools.
Programmers must be familiar with object-oriented programming and
must be able to program in C++.
They must be familiar with the concepts of the PersistencyService and
Support components which are described in the Developer Manual
INA Reference Manual T-ORB
This is the manualfor GINA application programmers.It contains formal
descriptions of T-ORB interfaces set out in alphabetical order.
GINA
Reference
Manual
T-ORB
It also contains descriptions of the associated tools.
Programmers must be familiar with object-oriented programming and
must be able to program in C++.
They must be familiar with the concepts of the T-ORB and Support
components which are described in the Developer Manual.
The Related publications sections of the manuals listed above also provide references to
related topics.
Ordering manuals
If you would like to order these manuals please contact your local Siemens office.
GINA V4.0 System Administrator Guide – September 2000 3
Notational conventions used in this manual
Thischaracter drawsyourattention to special features orpoints ofinterest; youwill also find
useful or secondary information there. ❍❍●
Particular attention must be paid to the information indicated by this symbol. ❍❍●
Terms that are explained in the text are highlighted in bold.
Program code, messages, keywords or class names are indicated by typewriter text.
Italic typewriter text
Text parts that are to be emphasized are represented by italics.
[1] Numbers in square brackets refer to the Related publications section.
◊ Rhombuses introduce processing statements.
indicates variables for parameters that you must enter.
4 GINA V4.0 System Administrator Guide – September 2000
Druck vom 24. 01.2001 17:00.19 aender
2 Changes since Version 3
2.1 Interface cancelations
The interfaceslisted in the following section werechanged in Version 4.0 of GINA. This version contains the new variant. Each section indicates the GINA version as of which the relevant interface or its old variant is no longer supported.
G_Exception eliminated
In earlier versions, GINA used the exception handling simulation of the Generic++ class
library [11] on some platforms. To facilitate this, the GINA exception classes were derived
internally from the Generic class G_Exception. This derivation process has had to be
eliminated because of a compiler problem.
The message and name methods derivedfrom G_Exception described in the Reference
Manual are omitted from GINA Version 4.0 and later.
OQL
Version 3.0 of GINA sees the introduction ofa new,improvedinterface for databasequeries
which is a subset of ODMG-OQL. Up to this version, the new OQL existed in parallel to the
old one and the user can decide the variant to be used.
Access via the old OQL will be eliminated as of GINA Version 4.0.
Entering special options in the mgen2 and mdiff generators
As of Version 3.3, special options (e.g. noansi, nohinfo) for the mgen2 and mdiff generators can be defined in a file, i.e. you no longer need to specify them individually in the
call. Instead, you reference an existing file using the -k option when you call a generator.
All of the special options can be specified in this file.
As of Version 3.3, special options were supported both as call options and via a special option file. As of Version 4, however, special options will only be read from a file.
GINA V4.0 System Administrator Guide – September 2000 5
Interface cancelations
Changing the names of the iterator methods max/min to maxValue/minValue
The methods max and min in the iterator classes PMibs::MibsFilterIt,
P
Mibs::MibsSeqIt, and VIEWITERATOR(P) were renamed maxValue and minValue
respectively in Version 3.0 of GINA in order to prevent conflicts with the max and min
macros defined in some environments.
The old API containing the method names max and min was supported as a transitional
aid. These methods are inline methods which call the methods maxValue and minValue
respectively. You can suppress these methods explicitly using the GINA_WITHOUT_MINMAX
compiler switch in order to prevent conflicts with macros of the same name.
The method names max and min will be omitted from GINA Version 4.0 and later.
mgen2: Column aliases (mnemonics for SQL) and PS-DB-API
The algorithm for defining the names of the column aliases as well as the parameters for
the functions in the PS-DB-API will be changed as of GINA V5.0.
To avoid name clashes, underscores contained in the names of the specialist attributes will
be doubled. In terms of the PS-DB-API, this change will not affect the GINA user as it is the
datatype of the individual attributes that is the decisive factor there. In terms of column
aliases, this change will affect all SQL queries where a search is to be performed for attributeswith an underscore in theirnames. Theunderscores in the relevantattribute names
must then simply be doubled.
C runtime libraries under WindowsNT
Version 4.0 and above will be shipped with multithreaded libraries only.
6 GINA V4.0 System Administrator Guide – September 2000
2.2 Revisions
Revisions
Druck vom 24. 01.2001 17:00.19 aender
Replacement of idlgen by idlgen1
The idlgen1 generates two definitions from an interface definition (x.idl) specified in
CORBA-IDL (Revision 2.2): x.hi which defines the data members to be encoded and
decoded and x.hd which defines the methods to be exported. The interim format x.hi
serves as input for the MIO generator miogen2. The interim format x.hd serves as input
for the T-ORB generator dogen2.
GINA V4.0 System Administrator Guide – September 2000 7
Revisions
8 GINA V4.0 System Administrator Guide – September 2000
Druck vom 24. 01.2001 17:00.19 install
3 Installation and deinstallation
This chapter describes how to install and deinstall GINA. Some of the technical information
given here is for the purposes of example only, e.g. it may vary partially depending on the
details of the operating system.
The current version of GINA can run under:
– UNIX-SVR4
– BS2000/OSD (under special release)
– WindowsNT
– Windows95/98
Further information on your respective system base can be found in the Release Notice
supplied with GINA. Please read this Release Notice carefully. ❍❍●
GINA V4.0 System Administrator Guide – September 2000 9
Requirements
3.1 Requirements
The following third-party products are required to implement the GINA components.
Please note that the products listed may be based on other products, which must then likewise be installed. Up-to-date information on the products required can be found in the Release Notice included in the delivery. ❍❍●
● Generic++ V2.5 [11]
GINA requires the class library Generic++ V2.5, which is contained in the GINA scope
of supply and is installed under the name libsupport2.
●
open
For communication and transaction monitoring, the T-ORB server uses the TP monitor
UTM. GINA Version 4.0 requires UTM Version
V5.0 or later [29].
To connect non-transaction-monitored applications (T-ORB client) to a transactionmonitored server, the CPIC interface is used.
This requires the product
UTM V5.0 and
open
UTM-Client V5.0
open
open
UTM (UNIX, NT, BS2000/OSD)
UTM-Client (UNIX, NT) V5.0A or later [36].
The software component UTM-D is also required when using GINA with BS2000.
● INFORMIX Dynamic Server 2000 (IDS.2000) V9.2
The Persistency Service in GINA V3.3 uses INFORMIX as the data storage system.
INFORMIXDynamic Server2000 [19] (UNIX & NT)and Client SDK 2.40 (UNIXand NT)
are required.
The XA interface[5] is required forthe integrated useof T-ORB and the PersistencyService. This interface is only integrated under UNIX in V9.2. Detailed information on coupling T-ORB and the Persistency Service under WindowsNT can be found in chapter 6,
Compiling and linking, of the Developer Manual [13].
10 GINA V4.0 System Administrator Guide – September 2000
Scope of supply and structure of GINA
3.2 Scope of supply and structure of GINA
Druck vom 24. 01.2001 17:00.20 install
This section describes the delivery packages and the general delivery structure of GINA
Version 4.0.
3.2.1 Delivery package
GINAV4.0 is supplied as a full-feature version (UNIX, NT) and as a partial version (WindowsNT only). The full-feature version contains the following GINA components:
● Persistency Service development, runtime system and PS browser
The development system of the PersistencyService comprises the generators mgen1,
mgen2, mgendb, mspgen2 and mdiff, the runtime system comprises the libraries of
the Persistency Service and the Persistency Service/client.
The PS browser comprises the components bruno and cuno.
● T-ORB development and runtime system
The development system of T-ORB comprises the generators config, miogen1,
miogen2, dogen1, dogen2 and idlgen, the runtime system comprises the libraries
of T-ORB and T-ORB/client.
● Support runtime system
The runtime system of the Support component comprises two libraries, one of which
contains support functions for T-ORB and the Persistency Service and the other of
which makes available the valid Generic++ class library.
The partial version under WindowsNT contains only the runtime environment (RT version)
for a T-ORB client. It is also prepared for use under Windows95 and Windows98. More detailed information can be found in the Release Notice included with the relevant version of
GINA.
The delivery medium is a CD.
GINA V4.0 System Administrator Guide – September 2000 11
Scope of supply and structure of GINA
3.2.2 Licensing of GINA
The tool FLEXlm from the company GLOBE
erators and the GINA runtime system are protected by licenses.
Before GINA can be used, the GINA Competence Center must generate the licenses for
the machine you require (processor ID) and convey them to you.
If you require an evaluation license, refer to the Release Notice for a template which you
must return completed to the GINA Competence Center.
Installing licenses
Store the license entries received from the Competence Center in the file
GinaLicense.dat. This file isa textfile. All machines where GINA is installedmust be able
to access this file. The environment variable LM_LICENSE_FILE must be set on each of
these machines. This variable contains the path and the name of the license file.
trotter
is used to license GINA. Both the gen-
Example (UNIX, csh)
setenv LM_LICENSE_FILE /home/usr/license/Ginalicense.dat
If the file already existson your machine, insert in file license.dat the lines of relevance
to GINA.
You can also specify several license files:
Example (UNIX, csh)
setenv LM_LICENSE_FILE /home0/GinaLicense.dat:/home1/GinaLicense.dat
12 GINA V4.0 System Administrator Guide – September 2000
Structure of the license file
Scope of supply and structure of GINA
Druck vom 24. 01.2001 17:00.20 install
The license file has the following structure:
Keyword License DaemonVer- Valid N License Proces- License-
sion code sor ID name
Example
FEATURE GinaDEV ginad 1.000 1-jan-0 0 C2348347 2387823 "Gina license"
Keyword Keyword for FLEX
License Type of license used
(GinaDEV, GinaRTS, TorbDEV, TorbRTS, PsDEV, PsRTS,
TorbClient, PsClient)
Daemon Name of the license daemon
Version Version number
Valid Date until which the license is valid
N Number of licenses (0 = unrestricted license)
License code 20-digit license code
Processor ID Processor ID which is assigned to the license code
License name Name of the license
lm
GINA V4.0 System Administrator Guide – September 2000 13
Scope of supply and structure of GINA
3.2.3 Directory structure
bin
doc
include
java
lib
template
Generators of the PS development system
Generators of the T-ORB development system
text
psbrowser
Release notice
Online documentation of the PS browser
doms
mibs
psc
support
support2
trace
usr
directory for the PS browser
Libraries of the PSund PS /client runtime system and PS browser
Libraries of the T-ORB runtime system
Libraries of the Support runtime system
comment
scr
Note
comment is a directory containing code templates
used by the generators dogen2 and idlgen1.
src contains code templates for the user outputs of
the T-ORB
The illustration shows the GINA default directory structure. The actual structure may differ
from that shown above.
You should thereforestudy the Release Notice, whichcan also be found under the file name
readme.
Version
in the doc directory. ❍❍●
14 GINA V4.0 System Administrator Guide – September 2000
Druck vom 24. 01.2001 17:00.21 install
Installation
3.3 Installation
The installation procedures depend on the system base. The variants described here are
examples only.
You must always perform installation and deinstallation in accordance with the description
of your system base or the information in the Release Notice. ❍❍●
GINA is shipped as a package which is created using a system-specific packet assembly
procedure (package under UNIX, setup under NT). The full-feature version of GINA V4.0
under UNIX is divided up into subpackages so that you do not have to install the entire product folder. The functional scope of a full-feature version can only be achieved by installing
all of the subpackages.
The names and contents of the subpackages as well as the order in which they must be
installed can be found in the Release Notice.
Depending on the selected variant, GINA builds on standard products (
open
UTM, INFORMIX).These mustbe installed usingtheir owninstallation procedures andare notdescribed
here.
If the GINA package is stored on the delivery CD as a file in compressed format, it must be
copied to an intermediate directory and unpacked prior to installation (refer to the description for the relevant platform).
Thefollowingactions, for example, must be carried out to install GINA itself on theplatforms
listed below.
GINA V4.0 System Administrator Guide – September 2000 15
Installation
3.3.1 UNIX (Solaris, SINIX)
Start the installation under UNIX using the command pkgadd.
The installation directory in which GINA is to be installed may not exist before the pkgadd
command is called. ❍❍●
1. Log in as root.
2. Set up a new user group
3. Set up a new user
4. Create a new directory e.g. /opt/gina for GINA:
mkdir -p /opt/gina
chmod 775 /opt/gina
chown gina:tmns /opt/gina
5a. Insert the GINA delivery CD in the CD drive and install the uncompressed GINA pack-
age using the following command:
pkgadd -d <
You are then prompted to do the following:
◊ Select the GINA subpackage to be installed.
◊ Specify the directory in which GINA is to be installed,
e.g. /opt/gina/
◊ Define users for this and the directories below:
e.g.
e.g.
◊ Specify the source directory from which GINA is installed.
<
CD drive directory
CD drive directory
gina
tmns
as userid (default: root)
as groupid (default: root)
gina
GINA
tmns
.
>
.
>/<
gina package file name
>
The GINA package is then installed under /opt/gina/
created and the structure filled with the files.
16 GINA V4.0 System Administrator Guide – September 2000
GINA
, the directory structure
Druck vom 24. 01.2001 17:00.21 install
Installation
5b. The following steps are required if the GINA package is stored on the delivery CD in
compressed format:
◊ Copy the GINA package from the CD to an intermediate directory
cp <
CD drive directory
directory name
>
◊ Unpack the file in the intermediate directory using gunzip.
◊ Install the unpacked GINA package
>/<
gina package file name
>.gz <
intermediate
pkgadd -d <
You are then prompted to do the following:
◊ Select the GINA package to be installed.
◊ Specify the directory in which GINA is to be installed,
e.g. /opt/gina/
◊ Define users for this and the directories below:
e.g.
gina
e.g.
tmns
◊ Specify the source directory from which GINA is installed.
<
intermediate directory name
The GINA package is then installed under /opt/gina/
created and the structure filled with the files.
3.3.2 UNIX / HP-UX
See UNIX (Solaris, SINIX) on page 16 for steps 1 through 4.
5. Insert the GINA delivery CD into the CD drive and install the uncompressed GINA pack-
age using the following command:
intermediate directory name
GINA
as userid (default: root)
as groupid (default: root)
>/<
gina package file name
>/<
gina package file name
>
GINA
, the directory structure
>
swinstall
The swinstall command opens a menu interface via which the aforementioned information is queried.
The GINA package is then installed, the directory structure created and the structure
filled with the files.
GINA V4.0 System Administrator Guide – September 2000 17
Installation
3.3.3 Windows NT
Installationof the full-featureorpartialversion(RTversion) under WindowsNTis performed
using the setup command, the installation tool is included in the GINA package on the
delivery CD.
1. Log in as administrator.
2. Create a new directory for GINA.
3. Insert the GINA delivery CD in the CD drive andstart thegraphical installation interface
using the command
<
drive
The dialog box which is displayed queries the path of the installation directory and the
components to be installed.
The GINA package is then installed, the directory structure created and the structure
filled with the files.
If, during installation, you selected GINA packages containing the services
DomsEventHandler and DomsDynConnectHandler, they will be automatically activated
the next time the system starts (under WindowsNT only).
Further information on this can be foundin the DeveloperManual [13] in thesection entitled
Compiling and linking, Special features under Windows NT. ❍❍●
>:\setup
If you intend to run GINA on a machine without a network link, you must set the
LM_NO_NETWORK environment variable in order to avoid the wait times resulting from futile
attempts to access a license server. ❍❍●
Special points in relation to the operation of the GINA PS browser
Beforethe GINA PS browseris called (on UNIX platforms), the directory in which the GINA
phases were installed must be included in the PATH environment variable.
Example for csh
sentenev PATH <gina_install_dir>/:$PATH
Furthermore, the environment variable LD_LIBRARY_PATH (for Solaris, SINIX) or
SHLIB_PATH (for HP-UX) must contain the file in which the GINA library is located.
18 GINA V4.0 System Administrator Guide – September 2000
Druck vom 24. 01.2001 17:00.22 install
Installation
Example for csh
– Solaris, SINIX
setenv LD_LIBRARY_PATH <gina_install_dir>/lib:$LD_LIBRARY_PATH
– HP-UX
setenv SHLIB_PATH <gina_install_dir>/lib:$LD_LIBRARY_PATH
On Windows NT all information necessary to the operation of the PS browser is entered
during installation by the setup routine.
That is, the environment variable GINADIR points to the file <gina_install_dir>,
<%GINADIR%\bin> is added to the PATH variable.
The PS browser is started using the Start > Programs menu. ❍❍●
Removing TPStartShut.o
If a T-ORB application which is to run on a WindowsNT machine uses custom startup and
shutdown exits, the dummy implementation of TPStartShut.o shipped with GINA must
be removed from the libraries
.../lib/doms.lib and .../lib/domsmt.lib
before this application is linked.
The two scripts extpss.bat and extpssmt.bat are made available for this.
extpss.bat removes the object TPStartShut.o from the library .../lib/doms.lib
and stores it in the library .../lib/domstpss.lib.
extpssmt.bat
removes the object TPStartShut.o from the library
.../lib/domsmt.lib and stores it in the library
.../lib/domstpssmt.lib.
The scripts must be executed in the lib directory of the GINA installation directory. One
prerequisite is that the %MSVCBIN% variable must be set. It must point to the bin directory
of the Microsoft Developer Studio.
Once TPStartShut.o has been removed, the library domstpss.lib or
domstpssmt.lib must be specified when linking T-ORBapplications whichdo notuse custom startup or shutdown exits.
Further information on special points to be noted when creating a GINA application under
NT can be found in the section entitled Compiling and linking, Special features under Win-
dows NT
GINA V4.0 System Administrator Guide – September 2000 19
in the Developer Manual [13]. ❍❍●
Installation
3.3.4 BS2000
The following steps are required when installing under BS2000:
1. Log in to BS2000/OSD under the name $GINA
2. Read in the tape using ARCHIVE, IMPORT ..., DEVICE=TAPE-C4
The following DVS files are created under the $GINA account:
GINA.PAX pax archive containing the POSIX files of the transfer
LIBxxx libraries of the GINA runtime system in PLAM format
3. Copy GINA.PAX as a POSIX file and unpack it within a POSIX shell:
/START-POSIX-SHELL
$ cd <gina_install_dir>
$ bs2cp ’bs2:gina.pax’ gina.pax
$ pax -r -f gina.pax
A directory GINA which contains the subdirectories and files described aboveis created in
<gina_install_dir>.
For further information please see the Release Notice.
The compiler C/C++ V3.0B requires the CRTE 2.1 runtime system. Refer to the Release
Notice for the C/C++ compiler V3.0A for information on dependencies with other BS2000
system components.
The GINA T-ORB component requires the XDR functionality from the POSIX-NSL 010
softwareunit.Thishasbeenavailableas aspecialreleasesincetheendofMay1998. ❍❍●
20 GINA V4.0 System Administrator Guide – September 2000
3.3.5 Environment variables
Installation
Druck vom 24. 01.2001 17:00.22 install
Certain environment variables must be set when implementing the various components of
GINA. Depending on the components implemented, these variables are:
Using the T-ORB on basis of
UTMPATH This environment variable contains the path of the installed
open
UTM
open
UTM envi-
ronment.
UPICPATH This environment variable contains the name of the directory with the
upicfile file. upicfile is created using the configuration generator
config (see chapter 6 on page 43).
This variable need only be set if you are starting a client application in a directory other than that containing the upicfile file.
GINACONFIG This variable is used to select a directory other than the actual directory for
the servernames file generated by config for the execution of a client
application.
Using the T-ORB on basis of BEA TUXEDO
TUXDIR This environment variable contains the path to the BEATUXEDO installation
directory.
TUXCONFIG Thisenvironment variable contains the name of the TUXCONFIG configura-
tion file.The absolute path name must be specified here.
Thisfile iscreated using the crbincf script generated bythe config-tux
configuration generator.
BDMCONFIG Thisenvironment variable contains the name of the BDMCONFIG configura-
tion file. The absolute path name must be specified here.
This file is created using the crbincf script.
This variable need only be set if you are using the Domains component
from BEATUXEDO.
GINACONFIG This variable is used to select a directory other than the actual directory for
the servernames file generated by config-tux for the execution of a client application.
GINA V4.0 System Administrator Guide – September 2000 21
Installation
Implementation of the Persistency Service
INFORMIXDIR This environment variable contains the name of the directory for the in-
stalled INFORMIX environment. The environment variable PATH must contain an $INFORMIXDIR/bin entry.
INFORMIXSERVER
This environment variable identifies the current instance of the database
server processed by the application database.
Following installation, you should inform the users of the correct values for the variables
UTMPATH, INFORMIXDIR and INFORMIXSERVER, or configure their environmentaccordingly.
When using NLS/GLS functionality, the following variables must also be set:
DB_LOCALE Ifthisenvironment variable is set, then the new databaseswill begenerated
on the database server using the locale specified by the variable
DB_LOCALE instead of the standard locale.
CLIENT_LOCALE
This environment variable is needed for the database client and the database server. It must also be set before an application that works with an
NLS/ GLS-capable database is started.
No further actions are required for BS2000/OSD.
Refer to the section Compiling and linking in the Developer Manual [13] for information on
special points to note when configuring the environment under Windows NT. ❍❍●
22 GINA V4.0 System Administrator Guide – September 2000
Druck vom 24. 01.2001 17:00.23 install
Deinstallation
3.4 Deinstallation
The installation procedures used depend onthe systembase; the variants described below
are examples only.
Installation and deinstallation should, therfore, always be carried out as described for your
system base or in accordance with the information contained in the Release Notice. ❍❍●
System-specific commands are used to deinstall GINA.
3.4.1 UNIX (Solaris, SINIX)
1. Log in as root.
2. Switch to the GINA directory:
cd /opt/gina/
3. Delete all GINA subdirectories and files using the system command:
pkgrm
4. Delete the GINA root directory:
cd /
rmdir /opt/gina/
5. Remove the
6. Remove the
gina
3.4.2 UNIX / HP-UX
Deinstallation of GINA under HP-UX is performed using the swremove command.
The swremove command opens a menu interface via which the information required for
deinstallation is queried.
The GINA package is then deinstalled, and the subdirectories and files are deleted.
GINA
gina
tmns
GINA
user set up at installation.
user group set up at installation.
GINA V4.0 System Administrator Guide – September 2000 23
Deinstallation
3.4.3 Windows NT
Deinstallation of GINA under Windows NT, Windows95 and Windows98 is performed byselecting the Software icon (Start > Settings > System Controls).
Then select GINA, and start the graphical deinstallation interface. The necessary information is queried in the dialog box.
The GINA package is then deinstalled, and the subdirectories and files are deleted.
24 GINA V4.0 System Administrator Guide – September 2000
3.5 Availability, restrictions
Availability, restrictions
Druck vom 24. 01.2001 17:00.23 install
This section provides information on platform-related restrictions, the availability of the
GINA components as well as libraries which are missing.
UNIX with CFront compilers
The GINA component PS/client is not available on UNIX systems with CFront compilers
(e.g. HP-UX).
WindowsNT
● The configuration generator for T-ORB with the graphical interface (WinConfig) is not
available.
● INFORMIX V9.2 does not contain an implementation of the XA interface. For that rea-
son, GINA offersa simulation. This means that INFORMIX cannot currently be used to
its full potential with
open
UTM and BEATUXEDO. For further information please see the
enclosed Release Notice.
Further information on this can be foundin the DeveloperManual [13] in thesection entitled
Compiling and linking, Special features under Windows NT.
Windows95/98
● Only the GINA runtime system for T-ORB/client applications (type 4) is available on
Windows95/98. This means that a T-ORB/client application can only be run on
Windows95.The applicationmust becreated in full on WindowsNT,i.e. execution of the
GINA generators, compilation, linking, and creation of the configuration.
● Installing GINA
An RT version for WindowsNT must be used for the GINA installation under
Windows95/98.
● C runtime system DLLs required (multithreaded)
msvcrt.dll
msvcirt.dll
GINA V4.0 System Administrator Guide – September 2000 25
Availability, restrictions
● Configuration file
The configuration file (the file that reads the config) must contain the line
OPERATING_SYSTEM("OS_WINNT")
for both WindowsNT and Windows95.
● Environment variable
The COMPUTERNAME environment variable is automatically set on WindowsNT, it must
be set by the user on Windows95.
BS2000/OSD
The PS/client (client part) as well as the direct database system connection are not available in the runtime system of T-ORB/client under BS2000/OSD.
The mgendb, WinConfig, mspgen2 and idlgen1 as well as the PS browser (bruno and
cuno) generators of the development system are not supplied.
26 GINA V4.0 System Administrator Guide – September 2000
Druck vom 24. 01.2001 17:00.23 inbtrieb
4 Creating GINA applications
GINA applications comprise a range of modules which must be linked as a program before
executiontime,at the latest. Since GINA represents a framework whichoffersdifferent functionality in different variants, special activities must be carried out to create an application,
depending on its specific type. Further details are provided in the following sections.
4.1 Application variants
The modular structure of GINA results in the following application types:
Type 1 Transaction-monitored communication with integrated local data store
This corresponds to using the full functionality of GINA.Both T-ORB and the Persistency Service are used; object-oriented transactions are supported.
Type 2 Transaction-monitored local data store
This corresponds to using the Persistency Service for applications which do not
require transaction-monitored communication in the network and which do not use
T-ORB. Transaction-monitored local data storage means that the transaction system of the database is used.
Type 3 Transaction-monitored communication
This corresponds to using T-ORB for applications which do not require transactionmonitored data storage or which do not implement the Persistency Service. Important fields of application for this type involve pure message queuing or connectivity
to mainframe applications.
Type 4 Linking applications of types 1 and 3 without transaction monitoring
These are client applications which establish the connection between the user and
GINA server applications, e.g. via a GUI.
Type 5 Persistency Service/client applications
In addition to T-ORB/client, these non-transaction monitored applications also use
the Persistency Service in the form of the Persistency Service/client.
GINA V4.0 System Administrator Guide – September 2000 27
Environment
Type 6 GINA applications associated with a Persistency Service/client application
Type 7 Dynamic client without a PS/client component
Type 8 Dynamic Persistency Service/client applications
Depending on the type of your application, you may have to specify different libraries when
linking.
4.2 Environment
If your system administrator has not already done so,you must at leastset the environment
variables INFORMIXDIR and UTMPATH. Please refer to section 3.3.5 on page 21.
You must also know the directory in which GINA has been installed on your system. It is
also advisable to read through the Release Notice, as this may also contain information on
creating GINA applications. The Release Notice can be found in the subdirectory doc of
the GINA directory (see section 3.2.3 on page 14).
These use T-ORB and the Persistency Service of GINA jointly.
Application of the type 5 as a dynamic client with a PS/client component.
28 GINA V4.0 System Administrator Guide – September 2000
4.3 The generators
The generators
Druck vom 24. 01.2001 17:00.24 inbtrieb
The generators of GINA can be found in the bin directory of the GINA installation (see
section 3.2 on page 11). These are listed below:
● The generator of the Persistency Service
mgen1 for analyzing C++ header files
mgen2 for generating the database schema and access methods
mgendb for creating the database
mdiff replaces mgen2 in the context of schema evolution
● The T-ORB generator
config for configuring T-ORB with the WinConfig graphical user interface for creat-
ing config input files.
WinConfig is only available on UNIX platforms. ❍❍●
● The T-ORB generator
dogen1 for analyzing C++ header files
dogen2 for creating global interface, stub, and export interface classes
● The MIO generator
miogen1 for analyzing C++ header files
miogen2 for creating encryption and decryption methods
● The IDL compiler
idlgen for creating global interface, stub and export interface classes, as well as
creating encryption and decryption methods.
The generators of the Persistency Service are described in the DeveloperManual [13] and
the Reference Manuals [14]. A description of the configuration options can be found in
chapter 5 on page 31 of the present manual.
The T-ORB generator config is described in chapter 6 on page 43.
GINA V4.0 System Administrator Guide – September 2000 29
Makefiles
4.4 Makefiles
Software development for larger systems, in particular, is much easier to handle with the
UNIX program make.
The Developer Manual [13] contains a detailed example of a possible makefile configuration.
30 GINA V4.0 System Administrator Guide – September 2000
Druck vom 24. 01.2001 17:00.24 per-konf
5 Configuring the Persistency Service
When examining the configuration of the Persistency Service, it is generally a good idea to
consult the documentation relating to the underlying database management system. All
explanations in this chapter relate to the database management system INFORMIX on the
UNIX platform. The environment can be differentfor other database management systems
or on other operating systems.
5.1 Setting up the database
The database is set up in several stages. First of all the system software of the database
management system used must be installed as prescribed by the manufacturer [19]. In
addition, IDs must be created for the administration of the database system. In this context,
it is also important to consider the definition of roles (IDs) in the area of administration and
security. Both the database server environment, for example INFORMIX Dynamic Server
2000,and that ofthe developmentenvironment, forexampleESQL(in the clientSDK), must
be installed.
In the nextphase, the resources assignedto the database system must be configured. This
particularly includes system resources such as
– the number of needed semaphores,
– size and number of shared memory segments,
– configuration of disk memory (raw devices, RAID controller), and the
– definition of connections (connectivity) to the database server.
When using the INFORMIX database system, for example, the entries in the files
/etc/hosts and /etc/services must match those in the sqlhosts file. In general,
these global activities must be performed under the root administrator ID.
The next step is for the database administrator to structure the assigned disk resources
(dividing into chunks), applying a structure (dbspaces, blobspaces) which can be used in
the definition of the database schema and in the backup and recovery concept. The aim of
this activity is to achieve an optimum solution under the aspects of fault tolerance, performance and availability. These activities are supported by appropriate tools, which are supplied with the database system. For example, here INFORMIX offers the onmode tool.
GINA V4.0 System Administrator Guide – September 2000 31
Setting up the database
To enablethese aims tobe achieved,knowledgeisrequired on datasets and theirdynamics
(static,low frequency of change, high rate of change), as well as the access behavior to the
data (navigating, value-based). This information is supplied to the Persistency Service generator as customizing[14] input in an optimization process. From this input, the Persistency
Service generator produces the optimized definition of the database schema (table layout,
indexing,constraints)and theaccess functions to database tables(see section 5.2 on page
33).
A further task of the database administrator is to configure the database server. Here, the
parameters for the operation of the database are defined in the appropriate configuration
files and runtime procedures(specific tothe selected database system). These parameters
include maximum values such as
– the number of transactions permitted in parallel
– the wait time for a response from a remote database server
– name spaces for the current session like DBSERVERNAME or SERVERNUM
– parameters that affect the executionof the session, e. g. the time interval between two
checkpoints.
If the database and transaction monitor are linked via the XA interface, the information
required by the participating systems must be configured in appropriate generation and
start procedures.
The initialization of the database is particularly important. This includes the initialization of
tables from a file which contains the data in ASCII notation, or the transfer of binaryencoded data as an excerpt from a secondary database of the same type. Migration tools
which are specific to the database system are available for transferring data from existing
databases or files.
32 GINA V4.0 System Administrator Guide – September 2000
5.2 Customizing the database layout
Customizing the database layout
Druck vom 24. 01.2001 17:00.24 per-konf
GINA offers you the option of customizing the database layout and the access privileges.
One aspect of this relates to the assignment of names of database tables for persistent
classes, whereby the default is that the class names of the specialist models are also used
to designate the database tables. However, this may cause problems if the maximum permitted length for identifiers is subject to specific restrictions.
For example, table names are limited to 18 characters in the INFORMIX version used.
Since GINA itself requiresa character as a prefix, class names thatare longer than 17 characters must be mapped to a shorter table name. ❍❍●
Another aspect is the definition of the actual storage space for tables in the physical database structures, i.e.the dbspaces.Performancerequirements can be considered here, and
the optimization functions of the database system can be used.
In terms of access privileges, requirements with regard to access protection are defined at
database or table level. The functionality also depends on the concrete database server.
The specifications for this customization are defined in description files. These are made
known to the mgen2 generator using the -r and -t options [14]. The generator then
creates an appropriately modified database schema. The following description files exist:
– the pfx file and
– the tbl file
GINA V4.0 System Administrator Guide – September 2000 33
Customizing the database layout
5.2.1 The pfx file
The description file that is called using the -r option, the so-called pfx file, handles the
specification of class-wide attribute names.
The attribute names used for the mapping to the database consist of the following components:
classPrefix_attributCounter_extension
classPrefix
is the part of the field name that is common to all fields in a class. Neither does
inheritance change it, i.e. it has the same valuein thesubclass asin thesuperclass.
It can be specified by the user with the help of the description file specified below.
When using identical views, this prefix is used to generate the attribute names of
both the table and also the view belonging to the class.
attributCounter
are always created by mgen2.
Layout of the description file
The description file consists of formatted lines with the following line format.
and
extension
classname prefix
Classname
represents a valid C++ identifier.
prefix
represents a valid SQL identifier. The prefix entries must differ for all classes and
can be a maximum of 6 characters in length.
Please note that all entries in the description file are case-sensitive.
If no prefix is found for a specific class, it is automatically generated by the mgen2 gener-
ator. The created prefixes have the following format:
X
dddd
or X
ddddd
The generation starts at X
value for
description file, the generation starts at X10201.
Once prefixes have been specified by the mgen2 for all classes, both those found in the
description file and the newly generated prefixes are output to the specified description file.
The old version of the pfx file is first backed up to a file with the extension .bak. An empty
or non-existent description file can be specified foruse in the creation of thefirst description
file.
dddd
withd=0,1,2,..,9
dddd
=X1024 or X
+1 found in the description file. That means that if X10200 was found in the
mmmm
, where
mmmm
represents the highest
34 GINA V4.0 System Administrator Guide – September 2000
5.2.2 The tbl file
Customizing the database layout
Druck vom 24. 01.2001 17:00.25 per-konf
The description file that is called using the -t option, the so-called tbl file, contains the
customizing functions:
– name mapping ofdatabase tablesand definition ofthe concretestorage space required
by tables (section 1 on page 35),
– fragmentation of a database table (section 2 on page 37),
– name mapping of views (section 3 on page 37),
– versioning of the database (section 4 on page 38) and
– access privileges for tables and views (section 5 on page 38).
The specification of this file, and of all entries in it, is optional.
The structure of the tbl files follows the general structure of the intermediate format files
(see the chapter entitled
Tools in the Reference Manuals [14]). The followingline types are
supported:
# for identifying a comment line
#|
comment text
t for identifying a definition line for the mapping of database table names or for defin-
ing the concrete storage space required by tables
fr for identifying a definition line for fragmenting a database table
v for identifying the version control
s for identifying a definition line for access privileges
vw for identifying a definition line for the mapping of database view names
The meaning of the individual lines as well as the necessary columns are now described
for each customizing function.
1. Name mapping of database tables and definition of the concrete storage space
required by tables
A table line contains the following fields:
t |
ident |name |resource |firstExtent |nextExtent
|
Only one definition line of this type is permitted per class.
Note that all “|” separators must be set.
ident
Name of the class in the specialist model.
Mandatory entry
GINA V4.0 System Administrator Guide – September 2000 35
Customizing the database layout
name
Name of the table to which the specialist model classes are to be mapped.
The default value is the class name.
Optional entry
resource
Entry to identify a dbspace in which the tables are to be stored. Such a
dbspace is a storage area which is based on the physical storage media.
Additional storage instructions are enteredusing the “fr definition lines” and
result in the fragmentation of the table.
Assigning tables to storage structures allows for the implementation of optimizationstrategiesforbacking up dataand foraccess functions.Thedefault
value for storing a table is the dbspace in which the database is generated
(-d
Optional entry
firstExtent
Entry for defining settings for the size of physically related storage areas,
which are reserved with the first entry in the table. Like
function serves to optimize the storage layout and enables it to be adapted
to the volumeof data involved.The minimum, maximum and defaultvalues
depend on the database system and on the layout of the storage media.
They are specified as integer multiples of pages (generally 2 Kb).
Optional entry
dbspace
option for the mgendb generator [14]).
resource,
this
nextExtent
Optional entry for defining settings for the size of physically related storage
areas, which are reserved with each extension to a table. As with the
firstExtent
entry, this function serves to optimize the storage layout.
Example
t |
myClassname1 |myNewTableName1 |dbspaceName
t |
myClassname2 |myNewTableName2
36 GINA V4.0 System Administrator Guide – September 2000
| | | |
| 4 | 4 |
2. Fragmentation of a database table
Customizing the database layout
Druck vom 24. 01.2001 17:00.25 per-konf
fr |
ident |resource
|
Anumber of definition lines of this type are permitted perclass, at leasttwo resources
must be defined for the purpose of fragmenting.
Note that a partitioning of storage space which is taken into account during the fragmentation can also be specified in the t definition line.
A fragmentation line contains the following fields:
ident
Name of the class in the specialist model.
Mandatory entry
resource
Entry to identify a dbspace in which the tables are to be stored. Such a
dbspace is a storage area which is based on the physical storage media.
The dbspace must exist and can only be assigned once per table. Optimization strategies for access functions can be realized through the fragmentation of tables across several storage structures.
Mandatory entry
Example
fr|
myClassname1 |Dbspace_1
fr|
myClassname1 |Dbspace_2
|
|
3. Name mapping of database views
A view line contains the following entries:
ident |name
vw |
Only one definition line of this type is permitted per class.
ident
Name of the class in the specialist model
Mandatory entry
name
Name of the viewto which the class of the specialist model is to be mapped.
Example
vw |
myClassname |myNewViewName
GINA V4.0 System Administrator Guide – September 2000 37
|
Customizing the database layout
4. Versioning of the database
A version line contains the following entries:
v |
indent
Only one version line is permitted per database.
|
ident
Version of the database schema (string with a maximum of 30 characters)
Mandatory entry
Example
v | 1.0 |
5. Access privileges for tables and identical views
A privilege line contains the following entries:
s |
ident |name |resource
A number of definition lines of this type are permitted per class.
ident
name
resource
Name of the class in the specialist model
Mandatory entry
Name of the userthat is assigned the privilege definedin the
umn
Mandatory entry
Mandatory entry in a definition line for privileges. It names the privilege
assigned to the user.
Value range:
|
resource
col-
INSERT allows you to make an object persistent.
DELETE allows you to delete a persistent object.
UPDATE allows you to modify a persistent object.
SELECT allows you to instance a persistent object.
Only privileges are permitted at table and view level and only those that do
not change the schema (ALTER TABLE, CREATE TABLE).
If the
ident
Only the CONNECT TO PUBLIC privilege is generated at database level.
38 GINA V4.0 System Administrator Guide – September 2000
class is a view class, only the privilege SELECT is permitted.
Customizing the database layout
Example
s |
Druck vom 24. 01.2001 17:00.26 per-konf
myClassname |hubert
If a user is assigned the DELETE privilege,he/she also needs the SELECT privilege for
the purpose of internal consistency checks. ❍❍●
| INSERT |
GINA V4.0 System Administrator Guide – September 2000 39
Customizing the database layout
5.2.3 Further options
The mgendb tool can also be used to influence the configuration of the database. In additiontospecificationsconcerning thedefaultdatabaseuserandNLS/GLS specifications, the
-d option can be used to determine a dbspace in which the database tables to be created
are to be set up. The mgendb supports the following options:
-d
dbspace
The named
the database to be generated. If this option is not set, the database is generated in the
root dbspace of the instance. See also [19].
dbspace
of the database instance is used as the default storage area of
Example
mgendb ... -d gina ...
-l
ltype
Specifying this option generates the database in such a way that it is NLS-/GLS-compatible (native language support/global language support), assuming the database
server supports this functionality.The concretelanguage variant (locale) is specified by
ltype
.The syntax of
system used. It is described in the database reference manual or the NLS documentation of the operating system. If the -l option is not set, the database is generated without NLS/GLS.
Thefollowingenvironmentvariablesare set inthe mgendb foranNLS-/GLS-compatible
database:
CLIENT_LOCALE=
DB_LOCALE=
The DB_LOCALE environmentvariableis needed forthe database server.Ifthis variable
is set, then the new databases will be generated using the locale specified by the variable DB_LOCALE instead of the standard locale.
The CLIENT_LOCALE environment variable is needed for the database client and the
database server.It must also be set beforean application that works with an NLS-/GLScapable database is started.
ltype
ltype
ltype
dependson thecurrent database serverand theoperating
Example
for INFORMIX V9.2 for creating a database with the German character set:
on SunOS mgendb -l de_de.8859-1 myDB (LANG=de)
on SINIX mgendb -l de_de.8859-1 myDB (LANG="De_DE.88591@TE")
on HP-UX mgendb -l de_de.8859-1 myDB (LANG=de_DE.iso88591)
40 GINA V4.0 System Administrator Guide – September 2000
Customizing the database layout
Note
ltype
Druck vom 24. 01.2001 17:00.26 per-konf
anotheroperating system environment,errorscan occursince
as a valid localeidentifier. Therefore mgendb shouldbe called on the same platform as
the one on which the database server is running.
-u
userName
A default database user can be entered if this option is specified. The default DB user
is identified by
no public user has access to the database. If no defaultuser is specified, all users have
access to the database.
must be a valid locale on the database server platform. If mgendb is called in
userName
ltype
and must be a valid UNIX user. If a default user is specified,
isnot recognized
Example
mgendb ... -u ginauser ...
GINA V4.0 System Administrator Guide – September 2000 41
Customizing the database layout
42 GINA V4.0 System Administrator Guide – September 2000
Druck vom 24. 01.2001 17:00.26 torb-kon
6 Configuring T-ORB for
This chapter describes how to configure communication between GINA applications. The
configuration does not require any modifications to the source program. However, it cannot
take place while the application is running; rather it must be performed before the application starts.
The configuration of T-ORB is based on the configuration of
Client [31]. Knowledge of the respective manuals will therefore aid comprehension. These
manuals are listed under Related publications at the back of this manual.
6.1 Overview
To operate a distributed system on the basis of GINA, certain information must be known
on the desired system structure, the current parameter settings of the host, and the characteristics of the GINA applications.
The configuration tool described here records this information in the form of a general system description, from which it generates the data required by GINA.
The information you must enter can be divided into the following parts (see Figure 1 on
page 44):
– specifications on system-wide settings, such as the participating systems
open
UTM
open
UTM [29] and
open
UTM-
– specifications on host-specific parameters, such as operating system resources
– specifications on application-specific parameters, such as the number of work pro-
cesses
– specifications on the connections between applications
Practically speaking, some of the parameters can be specified in more than one of these
areas. In such cases, the values set higher up in the hierarchy must be taken as default settings.These values are then overwrittenby the settings in more specific areas. The desired
settings can thus be specified separately for each application if required (customizing).
A connection between two applications is defined by the number of parallel communication
channels and the definition of the controlling application of each communication channel.
Even if all communication channels are controlled by one application, messages can be
GINA V4.0 System Administrator Guide – September 2000 43
Overview
transmitted by both sides. The controlling application simply has priority over the passive
application. From a performance point of view,the controllingapplication should be the one
which generally (or more frequently) opens the communication.
The definition of the type and number of all connections between the applications is equivalent to the definition of the communication structure for the entire system.
Figure 1 on page 44 is a symbolic representation of the hierarchies in the definition of this
communication structure. It is not drawn to scale to reflect the scope of the individual subdescriptions. Depending on the particular network structure, the definition of the connections between the applications can be much larger than the definition of the applications.
System-wide settings
Parameters valid throughout the system
Participating host: H1, H2, etc.
Host-specific parameters
R1
R2
etc.
Applications in R1, R2 etc.
Application-specific parameters
A1
A2
etc.
Connection parameters
V1
Figure 1 The logical hierarchy when defining the communication structure of a system
V2 V3 V4
etc.
44 GINA V4.0 System Administrator Guide – September 2000
Overview
The communication structure of a system can be depicted by a graph with nodes and
edges. The nodes correspond to the applications, while the edges represent the communi-
Druck vom 24. 01.2001 17:00.26 torb-kon
cation channels. The first three blocks in the diagram define the nodes of the graph with
respect to the specific system, host or application; the last block describes the edges of the
graph.
From the input data (which has already been explained), the configuration generator
config creates the following output data for each application of each host:
– for each application:
a GINA-specific address file containing all addressable server applications
– for each application:
a configuration file for the transaction monitor used by GINA
– for each host:
a list of the necessary TNSX entries
The configuration can be performed on a central computer for the entire system. The files
created in the process can then be distributed to the target computers and installed there.
The final tasks which mustbe performed locally are carried out during this installation. Moving the final tasksto the target computers eliminates the need toinstall the transaction monitor on the generation computer.Because the output data for the generation comprises only
textfiles, the hardware and operating system independence of the configuration process is
also guaranteed.
In the first version of the configuration tool, the procedure is that change requests are sent
to a central location and that a new configuration process will be implemented from there
only. The configuration generator makes it easier to configure the runtime environment for
T-ORB and T-ORB/Client. Revision generation is described in section 6.3 on page 88.
A central configuration is recommended for the following reasons:
– It does not make sense to change the configuration on the local target computers
because these modifications will be overwritten with the next global update process.
– Another argument against changing the settings locally is that modifications to the hier-
archy of the system often affect more than one host. It is precisely changes of this type
that require consistency checks, which are not possible on the local level.
GINA V4.0 System Administrator Guide – September 2000 45
Configuration language
6.2 Configuration language
The configuration generator config reads a text file which describes the configuration of
the entire system in a T-ORB-specific language. This file contains the necessary information on the network protocol, the transaction monitor, T-ORB, and the specialist application.
Theelements of thelanguageinclude keywords,literals,separatorsand comments. Blanks,
tabs, line feeds, form feeds and white spaces are ignored. The characters // introduce a
comment, the line feed character terminates it.
6.2.1 Statements
The configuration language contains a range of statements which are introduced by keywords;these are explained below. The statements include numerous UTM parameters [31].
Thestatements maycontain two differentstyles: uppercase letters only or lowercase letters
only. ❍❍●
ADMIN
The ADMIN statements onthe systemlevel apply toall hosts, ifthere is no ADMIN statement
with the same user ID in the HOST statement.
The ADMIN statements on the host level apply accordingly to all applications, if there is no
ADMIN statement in the application.
The optional ADMIN statement has the following parameters:
– user ID (LETTER)
– password (LETTER)
Example ADMIN ( "srv1", "srv1" )
ADDRESS
The ADDRESS statement describes how the foreign
addressed by the GINA application.
It has the following parameters:
– name of the transaction code (LETTER)
– name of the subroutine (LETTER)
open
UTM application is to be
Example ADDRESS ( "VSVONREB", "MV1VON" )
46 GINA V4.0 System Administrator Guide – September 2000
Configuration language
The ADDRESS statement describes how the GINA application is to be addressed by the foreign
open
UTM application. It has the following parameters:
Druck vom 24. 01.2001 17:00.27 torb-kon
– local name of the GINA application (LETTER)
– name of the local transaction code (LETTER)
APPLICATION
The APPLICATION statement describes a client which is connected via T-ORB/Client. It
comprises the following components:
– OsId of the application (NUMBER, 1 ... 32767)
– LayerId of the application (NUMBER, 1 ... 32767)
– User-friendly name of the application (LETTER)
– The REMOTE flagcan be specified as an option fora client connected via T-ORB/Client.
The REMOTE flag classifies a client as a remote client [31].
If the REMOTE flag is not specified as the last parameter, a client is generated locally if
it only has local connections to servers; otherwise, a remote generation is created.
– A user ID and password can be specified. This information is generated automatically
if it is not specified explicitly.
Example APPLICATION ( 131, 1, "CmdTrm1" )
AREA
The AREA statements on the system level apply to all hosts, if there is no AREA statement
with the same data area name in the HOST statement.
The AREA statements on the host level apply accordingly to all applications, if there is no
AREA statement in the application.
The optional AREA statement has one mandatory parameter
– Data area name (LETTER)
and the following optional parameters
– "ACCESS" = "DIRECT" | "INDIRECT" (OS_UNIX, OS_WINNT)
– "LOAD-MODULE" = "lmodname" (OS_BS2000)
– "LOAD" = "STATIC" (OS_BS2000)
– "LOAD" = "(POOL,poolname)" (OS_BS2000)
– "LIB" = "omlname" (OS_BS2000)
Example AREA ( "area1", "ACCESS" = "DIRECT" )
GINA V4.0 System Administrator Guide – September 2000 47
Configuration language
ASYN_PRIORITY
The ASYN_PRIORITY statement defines the priority classesfor the processing of asynchronous requests (see also the description of the PRIORITIES keyword). The statement has
the following format:
ASYN_PRIORITY(RELATIVE | ABSOLUTE | EQUAL)
{
PRIO(1 [,TIMER] [,EVENT] [,CYCLIC] [,PGWT] )
PRIO(2 [,TIMER] [,EVENT] [,CYCLIC] [,PGWT] )
PRIO(3 [,TIMER] [,EVENT] [,CYCLIC] [,PGWT] )
PRIO(4 [,TIMER] [,EVENT] [,CYCLIC] [,PGWT] )
PRIO(5 [,TIMER] [,EVENT] [,CYCLIC] [,PGWT] )
PRIO(6 [,TIMER] [,EVENT] [,CYCLIC] [,PGWT] )
PRIO(7 [,TIMER] [,EVENT] [,CYCLIC] [,PGWT] )
}
The ASYN_PRIORITY statement canbe used to define up to seven classes (PRIO1 through
PRIO7). As part of this process, PRIO1 is mapped to TAC class 10, PRIO2 to TAC class
11,etc. of
TAC class 9 with the highest priority is reserved for the T-ORB.
The RELATIVE, ABSOLUTE and EQUAL attributes of the ASYN_PRIORITY statementwere
transferred 1:1 from the
open
UTM.TACclass 10 has the second highest priority,TAC class 16 the lowest.
open
UTM generation.
These attributes are used to determine the priority with which processes will be distributed
to the asynchronous TAC classes containing executable asynchronous requests or interrupted asynchronous requests.
No new pending asynchronous requests willbe started once the maximum numberof asynchronous operations that can be open simultaneously is reached (set in MAX
ASYNTASKS=(...,service_number)), instead an interrupted outstanding asynchronous
operation will be selected on the basis of priority and continued.
ABSOLUTE attribute: Absolute priority
A free process will always be assigned to the class with the highest priority, i.e. Class 9,
provided that there are pending asynchronous requests or interrupted asynchronous
requests for this class. Processes that become free will only process requests from a
class with a lower priority if the message queues of all classes with a higher priority do
not contain any pending or interrupted asynchronous requests.
48 GINA V4.0 System Administrator Guide – September 2000
RELATIVE attribute: Relative priority
Configuration language
Druck vom 24. 01.2001 17:00.27 torb-kon
classes provided that there are pending or interrupted requests for these higher priority
classes. If there are requests present for all classes, a free process will be assigned to
TAC class 9 twice as often as to TAC class 10, and twice as often to TACclass 10 as to
TAC class 11, etc.
EQUAL attribute: Equal priority
All classes will be serviced equally if there are requests present. This equal distribution
can be disrupted if a class does not contain any pending requests at times or subprogram runs with blocking calls (e.g. KDCS call PGWT) frequently occur in that class.
Further information on the RELATIVE, ABSOLUTE and EQUAL attributes can be found in
Freeprocesses will be assigned to higher priority classes more often than lower priority
the
open
UTM documentation V5.0A, Generating and Handling Applications [26] in the
section entitled TAC-PRIORITIES – specify priorities of the TAC classes.
The following TIMER, EVENT, CONTROL and PGWT attributes are optional and can be spec-
ified in any order.
TIMER attribute
The T-ORB runtime system has an internal cyclical timer. This is a cyclical order (controlled by means of the CYCLETIME statement of the config generator) that takes
overvarioustasks withinT-ORB, e. g. initiation of the EventControlmechanism (seethe
EVENT attribute).
The TIMER attribute can be used to determine which priority class is to be assigned to
the internal cyclical timer. TIMER can only be specified for one priority class. If the TI-
MER attribute is not specified, the class with the average priority (rounded up to the next
highest priority) will be assigned to the cyclical timer. If, for example, PRIO1 through
PRIO4 is specified, PRIO2 will be assigned to the timer.
EVENT attribute
TheT-ORB runtime system maintains the so-calledEventControl mechanism internally.
This mechanism is responsible for ensuring that requests to T-ORB/client applications
that are buffered in the T-ORB application for technical reasons are actually delivered.
The EVENT attribute can be used to determine the priority class in which the
EventControl mechanism is to run. EVENT can only be specified for one priority class.
Ifthe EVENT attributeis not specified, the class with the average priority (rounded down
to the next lowest priority) will be assigned to the EventControl mechanism. If, for example,PRIO3 through PRIO7 is specified, PRIO5 will be assigned to the EventControl
mechanism.
This attribute is only needed if T-ORB/client applications are connected to the T-ORB
application.
GINA V4.0 System Administrator Guide – September 2000 49
Configuration language
CYCLIC attribute
A so-called administration order is created for each cyclical timed request
(DomsClient::cyclicOrder). This administration order makes sure that the cyclical
timed request is executed in the selected timeframe.
The CYCLIC attribute can be used to determine the priority class in which these administration orders are torun. CYCLIC can only be specified for one priority class. If the
CYCLIC attributeis not specified, the class with the average priority (rounded up to the
next highest priority) will be assigned to the administration orders. If, for example,
PRIO1 through PRIO6 is specified, PRIO3 will be assigned to the administration orders.
PGWT attribute
If a priority class is assigned requests that need to execute callAndWait and
execChainAndWait calls, the class must have the appropriate authorization.
The PGWT attribute can be used to grant this authorization to the priority class. PGWT
can be specified for each priority class.
BCAMAPPL
The optional BCAMAPPL statement permits the specification of BCAM application names
for a TA application. The number of application names required depends on the configuration and is checkedby config. If too fewapplicationnames are specified, config outputs
an appropriate error message. A BCAMAPPL statement is only permitted within a
TA_APPLICATION statement.
The application names are generated without the BCAMAPPL statement.
Example BCAMAPPL ( "GINA1", "GINA2" )
BEST_BCAMAPPL
The keyword BEST_BCAMAPPPL results in a separate BCAMAPPL statement being generated for each connection.
CANCEL
The CANCEL statement of the EVENTCONTROL block defines the interval after which an
event on a client expires, i.e. the event has exceeded its delivery time since the CANCEL
time, in relation to its start time. The interval is specified by four values for days, hours, minutes, and seconds.
The default value is CANCEL(2,0,0,0).
50 GINA V4.0 System Administrator Guide – September 2000
Configuration language
The CANCEL statementon system level applies to all hosts if there is no CANCEL statement
in the HOST statement.
Druck vom 24. 01.2001 17:00.28 torb-kon
The CANCEL statementon host level applies accordingly to all TAapplications if there is no
CANCEL statement in the TA_APPLICATION statement.
CHECK
The CHECK statement ofthe EVENTCONTROL block definesthe intervalafter which an event
on a client is overdue,i.e. incorporated into the checking mechanism, in relation to its start
time. The interval is specified by four values for days, hours, minutes and seconds.
The default value is CHECK(0,1,0,0).
The CHECK statement on system level applies to all hosts if there is no CHECK statement
in the HOST statement.
The CYCLICTIME statement on the host level applies accordingly to all TA applications if
there is no CHECK statement in the TA_APPLICATION statement.
CONNECT
The CONNECT entry describes a connection between a T-ORB/Client and a T-ORB-Server.
The statement has the following parameters:
– OsId of the first partner (e.g. client)
– LayerId of the first partner
– OsId of the second partner (e.g. server)
– LayerId of the second partner
Example CONNECT ( 221, 1, 204, 1 )
CYCLE
The CYCLE statement of the EVENTCONTROL block defines the interval in which the events
on the client that have not yet been delivered are checked. The interval is specified by four
values for days, hours, minutes and seconds.
The default value is CYCLE(0,0,10,0).
The CYCLE statement on system level applies to all hosts if there is no CYCLE statement
in the HOST statement.
The CYCLE statement on host level applies accordingly to all TA applications if there is no
CYCLE statement in the TA_APPLICATION statement.
GINA V4.0 System Administrator Guide – September 2000 51
Configuration language
CYCLICORDER
The CYCLICORDER statementdefines the maximum number of cyclical tasks permitted per
TA_APPLICATION.
The default value is CYCLICORDER(10).
The CYCLICORDER statement on system level applies to all hosts if there is no
CYCLICORDER statement in the HOST statement.
The CYCLICORDER statementon host levelapplies accordinglyto all TA applicationsif there
is no CYCLICORDER statement in the TA_APPLICATION statement.
CYCLICTIME
The CYCLICTIME statement defines the interval for activation of the application-specific
timer. The interval is specified by four values for days, hours, minutes and seconds.
The default value is CYCLICTIME(0,0,0,0).
The CYCLICTIME statement on system level applies to all hosts if there is no CYCLICTIME
statement in the HOST statement.
The CYCLICTIME statement on host level applies accordingly to all TA applications if there
is no CYCLICTIME statement in the TA_APPLICATION statement.
DYNAMIC_CONNECT
A DYNAMIC_CONNECT statementon system level and on host level permits the definition of
connections which are used by non-transaction-monitored clients to communicate with
transaction-monitored T-ORB applications.
This statement can be used to define connections to several different T-ORB applications.
DYNAMIC_CONNECT((os,layer,number), ...)
The parameters os and layer referto the OsLayerId in the TA_APPLICATION statement
of the transaction-monitored T-ORB application to which connections are to be generated.
The parameter number defines the number of connections.
If there is no DYNAMIC_CONNECT statement for a host, then this host inherits the connec-
tions specified at
If this list is empty, this means that this host does not inherit any connections from the sys-
tem level
.
system level.
52 GINA V4.0 System Administrator Guide – September 2000
EVENTCONTROL
Configuration language
Druck vom 24. 01.2001 17:00.28 torb-kon
The EVENTCONTROL statement comprises the following components:
– CYCLE
– CHECK
– CANCEL
Each component is optional.
Example EVENTCONTROL
{
CYCLE ( 0, 0, 20, 0 )
CHECK ( 0, 2, 0, 0 )
CANCEL ( 3, 0, 0, 0 )
}
FOREIGN_APPLICATION
open
The FOREIGN_APPLICATION statement describes a foreign
UTM application. It com-
prises the following components:
– OsId of the application (NUMBER, 1 ... 32767)
– LayerId of the application (NUMBER, 1 ... 32767)
– optional: a foreign application number
– user-friendly name of the application (LETTER))
Example FOREIGN_APPLICATION ( 1, 4, "FA1" )
FOREIGN_APPLICATION_NUMBER
The FOREIGN_APPLICATION_NUMBER statement summarizes a list of ADDRESS statements: this list is referenced by means of a number. An ADDRESS statement defines the
following components:
– FunctionId of the converter function (NUMBER)
– TransactionCode of the application (LETTER)
– TransactionType of the application (LETTER)
– optional: ConverterId of the application (NUMBER).
GINA V4.0 System Administrator Guide – September 2000 53
Configuration language
FOREIGN_SESSION
The FOREIGN_SESSION statement describes connections between aGINA applicationand
a foreign
– session type (LETTER); the generator currently supports LU6.1
– mapping (optional MAP_SYSTEM parameter)
MAP=
controls ASCII/EBCDIC conversion when exchanging unformatted messages with
other applications.
SYSTEM
open
patch or from EBCDIC to ASCII following receipt. The message may only contain printable characters.
See the KDCDEF control statement SESCHA in [26].
–a SESSIONPOINT statement for the GINA application
–a SESSIONPOINT statement for the foreign
HOST
The HOST statement describes the configurationof ahost. The HOST statement comprises
the following components:
open
UTM application. It comprises the following components:
UTM converts the data in the message area from ASCII to EBCDIC prior to dis-
open
UTM application
– host name
– optional: the CMX version of the host (default CMX040)
– optional: the UTM version of the host (default UTM040)
– optional: the flag RESERVE
– Internet address of the host (INTERNETADDRESS)
– shared memory and semaphore key (KEYVECTOR) (not OS_BS2000)
– available port numbers (PORTADDRESS) (not OS_BS2000)
– host-specific customizing statements
(ADMIN, CYCLICTIME, EVENTCONTROL, MAX, RMXA, START and START_RM)
– description of existing applications
Example HOST ( "Host2" )
{
INTERNETADDRESS ( 127.0.0.2 )
KEYVECTOR ( 5005, 5040 )
PORTADDRESSES ( 2000, 2100 )
...
}
54 GINA V4.0 System Administrator Guide – September 2000
IMPORT
Configuration language
Druck vom 24. 01.2001 17:00.28 torb-kon
The IMPORT statements on the system level apply to all hosts, if there is no IMPORT statement with the same file name in the HOST statement.
The IMPORT statements on the host level apply accordingly to all applications, if there is
no IMPORT statement with the same parameters in the application.
The optional IMPORT statement has one parameter:
– filename
The IMPORT statement is transformed into the KDCDEF control statement OPTION DATA.
IN_CONVERTER
The IN_CONVERTER statement describes a converter function or converter class method
that is called if there is a message from a foreign
open
UTM application.
The IN_CONVERTER statement has the following parameters:
– FunctionId of the converter function or
– ClassId and ClassMethodId of the converter class method
INTERNETADDRESS
The INTERNETADRESS statement isused tospecify thecurrent Internet addressof thehost.
KEYVECTOR
The KEYVECTOR statement contains the keys for the following UTM areas:
– the global application semaphore (SEMKEY)
– the access key for the KAA shared memory segment (KAASHMKEY)
– the access key for communication (IPCSHMKEY)
– the access key for file accesses (CACHESHMKEY)
The KEYVECTOR statement has the following parameters:
– start key
– end key
For the areas of importance, see the CMX documentation [7].
The differencebetween the start key and end key must be large enough for all applications
on the host to have their own key. ❍❍●
GINA V4.0 System Administrator Guide – September 2000 55
Configuration language
The following number of keys must be defined for each application:
– 1 key each for CACHESHMKEY, IPCSHMKEY and KAASHMKEY
– (6 + n + m)/10 semaphore keys for SEMKEY
n = maximum number of work processes
m = maximum number of communication partners connected simultaneously
When calculated, the value must be rounded off to a whole number.
MAX
The MAX statement allows you to customize TP applications.
On system level, the MAX statementapplies to all hosts if there is no MAX statement of the
same name in the HOST statement.
MAX statements on host level apply accordingly to all applications.
The optional MAX statement has the following parameters:
– name of the statement (LETTER)
– value of the statement as a string
The statement names APPLINAME, CACHESHMKEY, CONRTIME, DPUTLIMIT1, DPUTLIMIT2,
IPCSHMKEY, KAASHMKEY, NB, SEMARRAY and TRMSGLTH must not be specified, as these
statements are generated automatically.
If the KDCFILE statement is not specified or ifthe file name is omitted from the valuestring,
a MAX statement with the name KDCFILE is generated.
MPOOL
The MPOOL statement is onlysupported for TAapplicationson a host using the OS_BS2000
operating system. The MPOOL statements on the system level apply to all hosts, if there is
no MPOOL statement with the same pool name in the HOST statement.
The MPOOL statements on the host level apply accordingly to all applications, if there is no
MPOOL statement in the application.
The optional MPOOL statement has two mandatory parameters
– Poolname
– LSIZE = poolsize
and the following optional parameters
– ACCESS = READ | WRITE
– LIB = omlname
– PAGE = X'xxxxxxxx'
– SCOPE = GROUP | GLOBAL
– SHARETAB = csectname
56 GINA V4.0 System Administrator Guide – September 2000
NET_ACCESS
Configuration language
Druck vom 24. 01.2001 17:00.29 torb-kon
The NET_ACCESS statement describes the manner in which the application is linked to the
network.
The NET_ACCESS statements on system level apply to all hosts if there is no NET_ACCESS
statement with the same name in the HOST statement.
The NET_ACCESS statements on host level apply accordingly to all applications.
The optional NET_ACCESS statement has the following parameters:
– SINGLE-THREADED
Each network connection is administered in a separate network process.
– MULTI-THREADED
A number of network connections are administered in a single process. Network connections are assigned to network processes via listener IDs thatyou assign to the application name (BCAMAPPL statement) of your application.
– If you specify MULTI-THREADED, ALL,a LISTENER-ID is specifiedforeach BCAMAPPL
statement.
– If you specify MULTI-THREADED, number, number LISTENER-IDs are specified for
each BCAMAPPL statement.
The default value is SINGLE-THREADED.
OPERATING_SYSTEM
The optional OPERATING_SYSTEM statement defines the operating system of the host. Possible values are OS_UNIX, OS_WINNT and "OS_BS2000"
The default value is OPERATING_SYSTEM(OS_UNIX).
The OPERATING_SYSTEM statement on
system level applies to all hosts if there is no
OPERATING_SYSTEM statement in the HOST statement.
OUT_CONVERTER
The OUT_CONVERTER statement describes a converter function that is called beforea message from a foreign
open
UTM application is delivered.
The optional OUT_CONVERTER statement has the following parameter:
– converter ID of the converter function
GINA V4.0 System Administrator Guide – September 2000 57
Configuration language
PORTADDRESSES
The PORTADDRESSES statement contains the port numbers for the TNSX entries. The statement has the following parameters:
– first port number
– last port number
See the CMX documentation [7] for information on value ranges.
The difference between the start address and end address must be large enough for each
BCAMAPPL entry on the host to have its own port number. The following rules apply when
calculating the number of BCAMAPPL entries of an application:
– Each CONNECT statement creates two BCAMAPPL entries.
– If the BEST_BCAMAPPL flag is set in the APPLICATION statement, a separate
BCAMAPPL entry is generated for each SESSION statement of the application.
– Without the BEST_BCAMAPPL flag, the number of BCAMAPPL entries generated corre-
sponds to the maximum number of SESSION entries specified between the current
server application and one of its partners.
PRIORITIES
❍❍●
The PRIORITIES statement has the following format:
PRIORITIES
{
SYNC_PRIORITY(RELATIVE | ABSOLUTE | EQUAL [,free_sync] )
{
PRIO(1 [,PGWT] )
PRIO(2 [,PGWT] )
PRIO(3 [,PGWT] )
PRIO(4 [,PGWT] )
PRIO(5 [,PGWT] )
PRIO(6 [,PGWT] )
PRIO(7 [,PGWT] )
}
ASYN_PRIORITY(RELATIVE | ABSOLUTE | EQUAL)
{
PRIO(1 [,TIMER] [,EVENT] [,CYCLIC] [,PGWT] )
PRIO(2 [,TIMER] [,EVENT] [,CYCLIC] [,PGWT] )
PRIO(3 [,TIMER] [,EVENT] [,CYCLIC] [,PGWT] )
PRIO(4 [,TIMER] [,EVENT] [,CYCLIC] [,PGWT] )
PRIO(5 [,TIMER] [,EVENT] [,CYCLIC] [,PGWT] )
PRIO(6 [,TIMER] [,EVENT] [,CYCLIC] [,PGWT] )
58 GINA V4.0 System Administrator Guide – September 2000
Configuration language
PRIO(7 [,TIMER] [,EVENT] [,CYCLIC] [,PGWT] )
}
Druck vom 24. 01.2001 17:00.29 torb-kon
SCHEDULE
{
FUNCTION(<FunctionId>,<SyncPriority>,<AsyncPriority>,<Infostring>)
INSTMETHOD(<ClassId>,<InstMethodIdd>,<SyncPriority>,
<AsyncPriority>,<Infostring>)
CLASSMETHOD(<ClassId>,<ClassMethodId>,<SyncPriority>,
<AsyncPriority>,<Infostring>)
CLASS(<ClassId>,<Syncpriority>,<AsyncPriority>,<Infostring>)
}
}
The individual SYNC_PRIORITY, ASYN_PRIORITY and SCHEDULE blocks are described
under the relevant keywords.
– The new PRIORITIES statement and the old PRIORITY and SCHEDULE statements
are mutually exclusive, i. e. you can only assign one type of priority control to a
TA_APPLICATION.
– If you do not specify the PRIORITIES statement, priority control will be effected by
means of the function for controlling processing of orders by restricting processes.
– You can specify the PRIORITIES statement at system, host and TA application level.
The statement will be passed on from SYSTEM to HOST and from HOST to
TA_APPLICATION.
– Both the old priority control and the priority control described here can be used within
a T-ORB configuration.
PRIORITY
TAC classes are controlled at the level of the specialist class, class method, instance
method and function.
The PRIORITY statement defines three TAC classes with the priorities HIGH, MEDIUM and
LOW . This statement summarizes a list of three entries:
HIGH ( tasks [, SYNC_WAIT] )
MEDIUM ( tasks [, SYNC_WAIT] )
LOW ( tasks [, SYNC_WAIT] )
The parameter tasks specifies the maximum number of processes in the application
whichwork concurrently with this TACclass. It depends on the statements MAX TASKS and
MAX TASKS-IN-PGWT.
GINA V4.0 System Administrator Guide – September 2000 59
Configuration language
The attribute SYNC_WAIT specifies whether synchronous calls (callAndWait,
addToChain and execChainAndWait) are permitted in this TAC class. This attribute can
only be assigned to one of the three TAC classes.
The PRIORITY statement may only be used once on system, host or TA application level.
The PRIORITY statement on the system level applies to all hosts, if there is no PRIORITY
statement in the HOST statement.
The PRIORITY statement on the host level applies accordingly to all TA applications.
REMOTE
The REMOTE keywordclassifies a client as a remote client. If the REMOTE flag is not specified as the last parameter, a client is generated locally if it only has local connections to
servers; otherwise, a remote generation is created.
REPOSITORY
The REPOSITORY statement defines the file name of a repository in the current directory.
This repository contains the generation number and the associated port numbers and keys
for each of the OsId and LayerId pair.
If the file exists, these values are read, saved internally,and used during generation. If the
file does not exist, the values are generated automatically. The repository is written once
generation of these values is concluded.
The repository supports generation for a modified configuration. If an application is
removed,thesame identifiers are used in the kdcdf file fortheremaining applications.The
same port numbers are also used for the TNSX entries.
The REPOSITORY statement is optional. If this statement is not specified, no memory is
used in the generation.
REREADTIME
The REREADTIME statement has one parameter that defines a time interval in minutes.
REREADTIME(minutes)
The status of the gina.config fileof a TA_APPLICATION will be checkedevery minutes
minutes. The file will be read in once more if there has been a change in the status.
The REREADTIME statements at system level apply for all hosts unless the HOST statement
contains a REREADTIME statement.
The REREADTIME statements at host level apply accordingly for all TA applications.
60 GINA V4.0 System Administrator Guide – September 2000
RMXA
Configuration language
Druck vom 24. 01.2001 17:00.30 torb-kon
The RMXA statement describes a Resource Manager.
The RMXA statements on system level apply to all hosts if there is no RMXA statement of
the same name in the HOST statement.
The RMXA statements on host level apply accordingly to all applications.
The optional RMXA statement has the following parameters:
– manufacturer name of the Resource Manager
– form of the XA interface
– name of the OML with connection module (OS_BS2000 only)
SCHEDULE
The SCHEDULE statementis used to explicitlyassign the specialist classes, class methods,
instance methods and functions to the TAC classes with the priorities HIGH, MEDIUM and
LOW . This statement summarizes a list of entries:
CLASS ( ClassId, Priority )
CLASSMETHOD ( ClassId, ClassMethodId, Priority )
INSTMETHOD ( ClassId, InstMethodId, Priority )
FUNCTION ( FunctionId, Priority )
The parameter Priority has the values HIGH, MEDIUM or LOW .
The SCHEDULE statement may only be used once on system, host or TA application level.
The SCHEDULE statement on the system level applies to all hosts, if there is no SCHEDULE
statement in the HOST statement.
The SCHEDULE statement on the host level applies accordingly to all TA applications.
SCHEDULE (PRIORITIES)
The SCHEDULE statement defines the priority assigned to the specialist (synchronous/
asynchronous) processing mechanism (see also the description of the PRIORITIES keyword). The statement has the following format:
SCHEDULE
{
FUNCTION(<FunctionId>,<SyncPriority>,<AsyncPriority>,<Infostring>)
INSTMETHOD(<ClassId>,<InstMethodIdd>,<SyncPriority>,
<AsyncPriority>,<Infostring>)
CLASSMETHOD(<ClassId>,<ClassMethodId>,<SyncPriority>,
<AsyncPriority>,<Infostring>)
CLASS(<ClassId>,<Syncpriority>,<AsyncPriority>,<Infostring>)
}
GINA V4.0 System Administrator Guide – September 2000 61
Configuration language
The SCHEDULE statement can be used to assign functions, instance methods, class methods or all methods of a class to a specific priority.
Classes, class methods, instance methods and functions that are not explicitlyassigned to
a specific category using the SCHEDULE statement will be automatically assigned to the
second highest priority class.
The following minimum and maximum values apply to the individual parameters of the
SCHEDULE statement::
Parameter Minimum value Maximum value
ClassId 1025 SHRT_MAX
ClassMethodId 1 SHRT_MAX
InstMethodId 1 SHRT_MAX
Function 1025 LONG_MAX
SyncPriority 1 7
AsyncPriority 1 7x
SESSION
The SESSION statement describes connections between server applications. The SESSION statement comprises the following components:
– session type (LETTER); at present, the generator supports LU6.1
– mapping (optional MAP_SYSTEM parameter)
MAP=
controls ASCII/EBCDIC conversion when exchanging unformatted messages with
other applications.
SYSTEM
open
UTM converts the data in the message area from ASCII to EBCDIC prior to dispatch or from EBCDIC to ASCII following receipt. The message may only contain printable characters.
See the
– one SESSIONPOINT statement for each accessible application
KDCDEF
control statement
SESCHA
in [26].
62 GINA V4.0 System Administrator Guide – September 2000
SESSIONPOINT
Configuration language
Druck vom 24. 01.2001 17:00.30 torb-kon
The SESSIONPOINT statement specifies the number of connections that can be controlled
by an application.
The SESSIONPOINT statement has the following parameters:
– OsId of the current application (NUMBER)
– LayerId of the current application (NUMBER)
– number of connections controlled by this application
A SESSIONPOINT statement that describes the connections from a GINA application to a
foreign
open
UTM application has the following additional components:
–An ADDRESS statement
This statement describes the parameters used to specify how the foreign
open
UTM
application is to be addressed.
– An optional OUT_CONVERTER statement
This statement describes a converter function that is called before a message from a
foreign
A SESSIONPOINT statementthat describes the connections from aforeign
open
UTM application is delivered.
open
UTM appli-
cation to a GINA application has the following additional components:
–An ADDRESS statement
This statement describes the parameters used to specify how the GINA application is
to be addressed.
–An IN_CONVERTER statement
This statement describes a converter function or converter class method that is called
if there is a message from a foreign
open
UTM application.
START
The START statement allows you to customize TP statements.
The START statements on system level apply to all hosts if there is no START statement of
the same name in the HOST statement.
The START statements on host level apply accordingly to all applications.
The optional START statement has the following parameters:
– name of the statement
– value of the statement as a string
Permissible statement names are TASKS, ASYNTASKS and TASKS-IN-PGWT.
GINA V4.0 System Administrator Guide – September 2000 63
Configuration language
START_RM
The START_RM statements on system level apply to all hosts if there is no START_RM statement with the same manufacturer name in the HOST statement.
The START_RM statements on host level apply accordingly to all applications.
The optional START_RM statement has the following parameters:
– manufacturer name of the database
– Openstring OS
If the keyword APPLICATION is written instead of the Openstring parameter, the
TA_application name is used as the Openstring.
START_VALUE
The START_VALUE statement defines the first generation number that is used in the generation of identifiers in statements for the kdcdef program. This results in unique reproductions of the OsId and LayerId pair in these identifiers. By specifying different start
values, different subsystems that can be combined can be generated. The subsystem connections, however, must still be completed.
The START_VALUE statement is optional. If this statement is not specified, generation of
the identifiers starts with the value 1.
If a repository exists,it is used to ascertain the generation numbers, i.e. the START_VALUE
statement is ignored.
SYNC_PRIORITY
The SYNC_PRIORITY statement defines the priority classes for the processing of dialog requests (see also the description of the PRIORITIES keyword). The statement has the following format:
SYNC_PRIORITY(RELATIVE | ABSOLUTE | EQUAL [,free_sync] )
{
PRIO(1 [,PGWT] )
PRIO(2 [,PGWT] )
PRIO(3 [,PGWT] )
PRIO(4 [,PGWT] )
PRIO(5 [,PGWT] )
PRIO(6 [,PGWT] )
PRIO(7 [,PGWT] )
}
64 GINA V4.0 System Administrator Guide – September 2000
Configuration language
The SYNC_PRIORITY statement canbe used to define up to seven classes (PRIO1 through
PRIO7). As part of this process, PRIO1 is mapped to TAC class 2, PRIO2 to TAC class 3
etc. of
open
Druck vom 24. 01.2001 17:00.31 torb-kon
UTM. TAC class 2 has the second highest priority, TAC class 8 the lowest. TAC
class 1 with the highest priority is reserved for the T-ORB.
The RELATIVE, ABSOLUTE, EQUAL attributes of the SYNC_PRIORITY statement and the
free_sync parameter were transferred 1:1 from the
open
UTM generation.
These attributesare used to specify the strategy by which free processes will be distributed
to the dialog TAC classes containing pending requests. Pendingdialog requests only arise
if the number of requests retrievedfrom the request exchangeat any one time exceeds the
number of processes available for the dialog TAC classes. These pending requests will be
written to the request queues of the transaction codes from which theywill be read and processed in accordance with their priority by the processes that become free.
ABSOLUTE attribute: Absolute priority
A free process will always be assigned to the class with the highest priority (TAC class
1)provided that thereare pending requestsforthis class. Lowerpriority classes willonly
be serviced if there are no pending requests in any of the higher priority classes.
RELATIVE attribute: Relative priority
Freeprocesses will be assigned to higher priority classes more often than lower priority
classes provided that there are pending requests for these higher priority classes. If
there are requests present for all dialog classes, a free process will be assigned to TAC
class 1 twice as often as to TAC class 2, and twice as often to TAC class 2 as to TAC
class 3, etc.
EQUAL attribute: Equal priority
All classes will be serviced equally if there are requests present. This equal distribution
can be disrupted if a class does not contain any pending requests at times or subprogram runs with blocking calls (e.g. KDCS call PGWT) frequently occur in that class.
free_sync parameter
This parameter allows you to restrict the total number of processes that may process
requests to dialog TAC classes relative to the number of processes in the application.
In free_sync specify the number of processes in the application that are to be kept
free for processing requests and that do not belong to any dialog TAC class.
Minimum value: 0 (no restriction)
Maximum value: TASKS - 1 (TASKS from MAX statement)
Default: 1
GINA V4.0 System Administrator Guide – September 2000 65
Configuration language
PGWT attribute
If a priority class is assigned requests that need to execute callAndWait and
execChainAndWait calls, the class must have the appropriate authorization.
The PGWT attribute can be used to grant this authorization to the priority class. PGWT
can be specified for each priority class.
Further information on the RELATIVE, ABSOLUTE and EQUAL attributes as well as on the
free_sync parameter can be found in the
Handling Applications
the TAC classes
SYSTEM
The SYSTEM keyword must always be the first keyword in the description. The current
description is enclosed in braces, i.e. SYSTEM {...}.
Example SYSTEM {...}.
The SYSTEM statement can be written with a flag in rounded brackets.
Example SYSTEM (TNS_LESS_SESSION){...}
The flag TNS_LESS_SESSION means:
Noentries will be generated in the files tnsxin and tnsxdel forthe statements SESSION
and FOREIGN_SESSION.
open
UTM documentation V5.0, Generating and
[26] in the section entitled TAC-PRIORITIES – specify priorities of
.
TA_APPLICATION
The TA_APPLICATION statement describes atransaction-monitored applicationon the current host (HOST). It comprises the following components:
– TP application name (LETTER)
– OsId of the application (NUMBER, 1 ... 32767)
– LayerId of the application (NUMBER, 1 ... 32767)
– User-friendly name of the application (LETTER)
– optional: BCAMAPPL name can be assigned exclusively to a GINA application
(BEST_BCAMAPPL)
A further form describes a future application with the following parameters:
– OsId of the application (NUMBER, 1 .. 32767)
– LayerId of the application (NUMBER, 1 .. 32767)
– Flag RESERVE
66 GINA V4.0 System Administrator Guide – September 2000
Configuration language
This statement acts as a wildcard so that a GINA-SESSION between a T-ORB application
without the flag RESERVE and a T-ORB application with the flag RESERVE can be defined
Druck vom 24. 01.2001 17:00.31 torb-kon
(see SESSION). A T-ORB application can then be generated from this session in the event
ofa revisiongeneration.The normal syntax of this statementmust thenbe used. OsId and
LayerId may not then be changed.
Customizing statements (ADMIN, CYCLICTIME, EVENTCONTROL, MAX, RMXA, START and
START_RM) are permitted after the TA_APPLICATION description of a server.
Example TA_APPLICATION ( "OS1", 1, 1, "OS1" )
{
...
}
GINA V4.0 System Administrator Guide – September 2000 67
Configuration language
6.2.2 Lexical structure
This section describes how the configuration generator combines the contents of the configuration file into symbols (like the keywords) for syntax analysis. The description is in the
notation used by the UNIX command lex.
%{
%}
letter [a-zA-Z_]
DGS [0-9]+
letter_or_digit [a-zA-Z_0-9]
%%
[ \t\n\v\r\f]+ ;
\/\/.*\n ;
\{ {return(BBOPEN);}
\} {return(BBCLOSE);}
\( {return(SBOPEN);}
\) {return(SBCLOSE);}
\, {return(COMMA);}
\= {return(EQUAL);}
{DGS} {yylval.number=atol(yytext);
return(NUMBER);}
{DGS}\.{DGS}\.{DGS}\.{DGS} {strcpy(yylval.string,yytext);
return(INADDRESS);};
\"[^"\n]* {yytext[yyleng++] = yyinput();
yytext[yyleng] = '\0';
lettercpy(yylval.string,yytext);
return(LETTER);};
{letter}{letter_or_digit}* {return(rwlookup());};
. {return(ERROR);};
%%
68 GINA V4.0 System Administrator Guide – September 2000
6.2.3 Syntax
Configuration language
Druck vom 24. 01.2001 17:00.31 torb-kon
This section describes the syntax of the configuration language in the notation used by the
UNIX command yacc.
%{
%}
%start sysblock
%union
{
SessPoint *sessPt;
long number;
char string[80];
}
%token <number> NUMBER /* positive integer */
%token ADDRESS /* statement */
%token ADMIN /* statement */
%token APPLICATION /* statement */
%token AREA /* statement */
%token ASYN_PRIORITY /* statement */
%token BCAMAPPL /* statement */
%token CANCEL /* statement */
%token CHECK /* statement */
%token CLASS /* statement */
%token CLASSMETHOD /* statement */
%token CONNECT /* statement */
%token CYCLE /* statement */
%token CYCLICORDER /* statement */
%token CYCLICTIME /* statement */
%token DYNAMIC_CONNECT /* statement */
%token EVENTCONTROL /* statement */
%token FOREIGN_APPLICATION /* statement */
%token FOREIGN_APPLICATION_NUMBER /* statement */
%token FOREIGN_SESSION /* statement */
%token FUNCTION /* statement */
%token HOST /* statement */
%token IMPORT /* statement */
%token INSTMETHOD /* statement */
%token INTERNETADDRESS /* statement */
GINA V4.0 System Administrator Guide – September 2000 69
Configuration language
%token IN_CONVERTER /* statement */
%token KEY_VECTOR /* statement */
%token MAX_STMT /* statement */
%token MPOOL /* statement */
%token NET_ACCESS /* statement */
%token OPERATING_SYSTEM /* statement */
%token OUT_CONVERTER /* statement */
%token PORTADDRESSES /* statement */
%token PRIO /* statement */
%token PRIORITIES /* statement */
%token PRIORITY /* statement */
%token REPOSITORY /* statement */
%token REREADTIME /* statement */
%token RMXA /* statement */
%token SCHEDULE /* statement */
%token SESSION /* statement */
%token SESSIONPOINT /* statement */
%token START /* statement */
%token START_RM /* statement */
%token START_VALUE /* statement */
%token SYNC_PRIORITY /* statement */
%token SYSTEM /* statement */
%token TA_APPLICATION /* statement */
%token ABSOLUTE /* flag */
%token BEST_BCAMAPPL /* flag */
%token CYCLIC /* flag */
%token EVENT /* flag */
%token EQUAL /* flag */
%token HIGH /* flag */
%token LOW /* flag */
%token MAP_SYSTEM /* flag */
%token MEDIUM /* flag */
%token PGWT /* flag */
%token RELATIVE /* flag */
%token REMOTE /* flag */
%token RESERVE /* flag */
%token SYNC_WAIT /* flag */
%token TIMER /* flag */
%token TNS_LESS_SESSION /* flag */
%token <string> INADDRESS /* Internet address */
%token <string> LETTER /* string */
%token BBOPEN /* { */
%token BBCLOSE /* } */
%token SBOPEN /* ( */
70 GINA V4.0 System Administrator Guide – September 2000
Configuration language
%token SBCLOSE /* ) */
%token COMMA /* , */
Druck vom 24. 01.2001 17:00.32 torb-kon
%token EQUALS /* = */
%token CONFIG_ERROR /* error code (internal) */
%%
sysblock : system
BBOPEN
sys_statement_list_opt
multi_host
multi_link_opt
BBCLOSE
;
system : SYSTEM
| SYSTEM
SBOPEN
TNS_LESS_SESSION
SBCLOSE
;
sys_statement_list_opt
: /* empty */
| sys_statement_list
;
sys_statement_list
: org_statement_list s_statement_list_opt
| s_statement_list
;
org_statement_list
: org_statement
| org_statement_list org_statement
;
s_statement_list_opt
: /* empty */
| s_statement_list
;
s_statement_list
: s_statement
| s_statement_list s_statement
;
GINA V4.0 System Administrator Guide – September 2000 71
Configuration language
s_statement : statement
| foreign_app_number
| dynamic_connect
;
org_statement : start_value
| repository
| operating_system
;
start_value : START_VALUE SBOPEN NUMBER SBCLOSE
;
repository : REPOSITORY SBOPEN LETTER SBCLOSE
;
foreign_app_number
: foreig_app_number_header
BBOPEN address_list BBCLOSE
;
foreign_app_number_header
: FOREIGN_APPLICATION_NUMBER
SBOPEN NUMBER SBCLOSE
;
address_list : address_elm
| address_list address_elm
;
address_elm : ADDRESS SBOPEN
NUMBER COMMA LETTER COMMA LETTER SBCLOSE
| ADDRESS SBOPEN
NUMBER COMMA LETTER COMMA LETTER COMMA NUMBER SBCLOSE
;
operating_system
: OPERATING_SYSTEM SBOPEN LETTER SBCLOSE
;
72 GINA V4.0 System Administrator Guide – September 2000
Configuration language
statement : max
| rm
Druck vom 24. 01.2001 17:00.32 torb-kon
| admin
| start
| start_rm
| cyclictime
| cyclicorder
| eventcontrol
| net_access
| area
| mpool
| import
| priorities
| priority
| schedule
| rereadtime
;
cyclictime : CYCLICTIME SBOPEN
NUMBER COMMA
NUMBER COMMA
NUMBER COMMA
NUMBER SBCLOSE
;
cyclicorder : CYCLICORDER SBOPEN NUMBER SBCLOSE
;
eventcontrol : EVENTCONTROL BBOPEN
eventcontrol_body
BBCLOSE
;
eventcontrol_body
: cycle cyclic_rest
| check check_rest
| cancel
;
cyclic_rest : check check_rest
| check_rest
;
GINA V4.0 System Administrator Guide – September 2000 73
Configuration language
check_rest : cancel
| /* empty */
;
cycle : CYCLE SBOPEN
NUMBER COMMA
NUMBER COMMA
NUMBER COMMA
NUMBER SBCLOSE
;
check : CHECK SBOPEN
NUMBER COMMA
NUMBER COMMA
NUMBER COMMA
NUMBER SBCLOSE
;
cancel : CANCEL SBOPEN
NUMBER COMMA
NUMBER COMMA
NUMBER COMMA
NUMBER SBCLOSE
;
net_access : NET_ACCESS SBOPEN LETTER COMMA LETTER SBCLOSE
| NET_ACCESS SBOPEN LETTER SBCLOSE
| NET_ACCESS SBOPEN NUMBER SBCLOSE
;
area : AREA SBOPEN LETTER area_parameter_list_opt SBCLOSE
;
area_parameter_list_opt
: /* empty */
| COMMA area_parameter_list
;
area_parameter_list
: area_parameter
| area_paramter_list area_parameter
;
74 GINA V4.0 System Administrator Guide – September 2000
Configuration language
area_parameter : LETTER EQUAL LETTER
;
Druck vom 24. 01.2001 17:00.32 torb-kon
mpool : MPOOL SBOPEN LETTER COMMA mpool_parameter_list SBCLOSE
;
mpool_parameter_list
: mpool_parameter
| mpool_parameter_list COMMA mpool_parameter
;
mpool_parameter: LETTER EQUAL LETTER
;
import : IMPORT SBOPEN LETTER SBCLOSE
;
priorities : PRIORITIES BBOPEN priorities_body BBCLOSE
;
priorities_body: sync_priority asyn_priority p_schedule
;
sync_priority : SYNC_PRIORITY SBOPEN r_a_e free_sync SBCLOSE
BBOPEN prio_list BBCLOSE
;
r_a_e : RELATIVE
| ABSOLUTE
| EQUAL
;
free_sync : /* empty */
| COMMA NUMBER
;
prio_list : prio_element
| prio_list prio_element
;
prio_element : PRIO SBOPEN NUMBER prio_rest
;
GINA V4.0 System Administrator Guide – September 2000 75
Configuration language
prio_rest : SBCLOSE
| COMMA PGWT SBCLOSE
;
asyn_priority : ASYN_PRIORITY SBOPEN r_a_e SBCLOSE
BBOPEN aprio_list BBCLOSE
;
aprio_list : i aprio_element
| aprio_list aprio_element
;
aprio_element : PRIO SBOPEN NUMBER aprio_rest
;
aprio_rest : SBCLOSE
| COMMA tecp_list SBCLOSE
;
tecp_list : tecp_element
| tecp_list COMMA tecp_element
;
tecp_element : TIMER
| EVENT
| CYCLIC
| PGWT
;
p_schedule : SCHEDULE BBOPEN p_schedule_list BBCLOSE
;
p_schedule_list: p_schedule_element
| p_schedule_list p_schedule_element
;
76 GINA V4.0 System Administrator Guide – September 2000
Configuration language
p_schedule_element
: FUNCTION SBOPEN NUMBER COMMA NUMBER COMMA
Druck vom 24. 01.2001 17:00.33 torb-kon
NUMBER COMMA LETTER SBCLOSE
| INSTMETHOD SBOPEN NUMBER COMMA NUMBER COMMA
NUMBER COMMA NUMBER COMMA LETTER SBCLOSE
| CLASSMETHOD SBOPEN NUMBER COMMA NUMBER COMMA
NUMBER COMMA NUMBER COMMA LETTER SBCLOSE
| CLASS SBOPEN NUMBER COMMA NUMBER COMMA
NUMBER COMMA LETTER SBCLOSE
;
priority : PRIORITY BBOPEN priority_body BBCLOSE
;
priority_body : low_task low_task_rest
| medium_task medium_task_rest
| high_task high_task_rest
;
low_task : LOW SBOPEN NUMBER opt_sync_wait SBCLOSE
;
medium_task : MEDIUM SBOPEN NUMBER opt_sync_wait SBCLOSE
;
high_task : HIGH SBOPEN NUMBER opt_sync_wait SBCLOSE
;
low_task_rest : medium_task high_task
| high_task medium_task
;
medium_task_rest
: low_task high_task
| high_task low_task
;
high_task_task : low_task medium_task
| medium_task low_task
;
opt_sync_wait : /* empty */
| COMMA SYNC_WAIT
;
GINA V4.0 System Administrator Guide – September 2000 77
Configuration language
rereadtime : REREADTIME SBOPEN NUMBER SBCLOSE
;
schedule : SCHEDULE BBOPEN schedule_list BBCLOSE
;
schedule_list : schedule_element
| schedule_list schedule_element
;
schedule_element
: CLASS SBOPEN NUMBER COMMA prio SBCLOSE
| CLASSMETHOD SBOPEN NUMBER COMMA NUMBER COMMA prio
SBCLOSE
| INSTMETHOD SBOPEN NUMBER COMMA NUMBER COMMA prio
SBCLOSE
| FUNCTION SBOPEN NUMBER COMMA prio SBCLOSE
;
prio : LOW
| MEDIUM
| HIGH
;
ta_attrib : /* empty */
| BBOPEN
ta_appl_statement_list_opt
BBCLOSE
;
non_ta_attrib : /* empty */
| BBOPEN
non_ta_appl_statement_list_opt
BBCLOSE
;
foreign_attrib : /* empty */
| BBOPEN
foreign_appl_statement_list_opt
BBCLOSE
;
78 GINA V4.0 System Administrator Guide – September 2000
Configuration language
ta_appl_statement_list_opt
: /* empty */
Druck vom 24. 01.2001 17:00.33 torb-kon
| ta_appl_statement_list
;
non_ta_appl_statement_list_opt
: /* empty */
| non_ta_appl_statement_list
;
ta_appl_statement_list
: ta_appl_statement
| ta_appl_statement_list ta_appl_statement
;
non_ta_appl_statement_list
: non_ta_appl_statement
| non_ta_appl_statement_list non_ta_appl_statement
;
ta_appl_statement
: statement
| bcamappl_statement
;
bcamappl_statement
: BCAMAPPL SBOPEN bcam_list SBCLOSE
;
bcam_list : bcam_element
| bcam_list COMMA bcam_element
;
bcam_element : LETTER
;
non_ta_appl_statement
: authentication
;
foreign_appl_statement_list_opt
: /* empty */
| foreign_appl_statement_list
;
GINA V4.0 System Administrator Guide – September 2000 79
Configuration language
foreign_appl_statement_list
: foreign_appl_statement
| foreign_appl_statement_list foreign_appl_statement
;
foreign_appl_statement
: authentication
| bcamppl_statement
;
rm : RMXA SBOPEN LETTER COMMA LETTER SBCLOSE
;
admin : ADMIN SBOPEN LETTER COMMA LETTER SBCLOSE
;
max : MAX SBOPEN LETTER COMMA LETTER SBCLOSE
| max_header max_list_opt SBCLOSE
;
max_header : MAX SBOPEN LETTER EQUAL LETTER
;
max_list_opt : /* empty *?
| COMMA max_list
;
max_list : max_element
| max_list COMMA max_element
;
max_element : LETTER EQUAL LETTER
;
start : START SBOPEN LETTER COMMA LETTER SBCLOSE
;
start_rm : START_RM SBOPEN LETTER COMMA LETTER SBCLOSE
| START_RM SBOPEN LETTER COMMA APPLICATION
SBCLOSE
;
80 GINA V4.0 System Administrator Guide – September 2000
Configuration language
multi_host : hostblock
| multi_host hostblock
Druck vom 24. 01.2001 17:00.33 torb-kon
;
hostblock : HOST SBOPEN LETTER SBCLOSE hostbody
/* Hostname */
| HOST SBOPEN LETTER COMMA RESERVE SBCLOSE hostbody
/* Hostname, CMX-Version oder UTM-Version */
| HOST SBOPEN LETTER COMMA LETTER
SBCLOSE hostbody
/* Hostname, CMX-Version oder UTM-Version */
| HOST SBOPEN LETTER COMMA LETTER COMMA RESERVE
SBCLOSE hostbody
/* Hostname, CMX-Version oder UTM-Version */
| HOST SBOPEN LETTER COMMA LETTER COMMA LETTER
SBCLOSE hostbody
/* Hostname, CMX-Version, UTM-Version */
| HOST SBOPEN LETTER COMMA LETTER COMMA LETTER
COMMA RESERVE SBCLOSE hostbody
/* Hostname, CMX-Version, UTM-Version */
;
hostbody : BBOPEN
i_v_a
vector_aaddress_opt
host_statements
multi_applicat_opt
BBCLOSE
;
i_v_a : internet internet_rest
| vector vector_rest
| address adress_rest
;
address_rest : internet vector_opt
| vector internet_opt
;
internet_rest : /* empty */
| vector address_opt
| adress vector_opt
;
GINA V4.0 System Administrator Guide – September 2000 81
Configuration language
vector_rest : internet address_opt
| address internet_opt
;
internet : INTERNETADDRESS SBOPEN INADDRESS SBCLOSE
; ;
internet_opt : /* empty */
| internet
;
vector_opt : /* empty */
| vector
;
host_statements
: /* empty */
| operating_system host_statement_list_opt
| host_statement_list
;
host_statement_list_opt
: /* empty */
| host_statement_list
;
host_statement_list
: host_statement
| host_statement_list host_statement
;
host_statement : statement
| dynamic_connect_host
;
dynamic_conect_host
: dynamic_connect opt_dyn_block
| dynamic_connect_empty
;
dynamic_connect_empty
: DYNAMIC_CONNECT SBOPEN SBCLOSE
;
82 GINA V4.0 System Administrator Guide – September 2000
Configuration language
dynamic_connect: DYNAMIC_CONNECT SBOPEN dyn_conn_list SBCLOSE
;
Druck vom 24. 01.2001 17:00.34 torb-kon
dyn_conn_list : /* empty */
| dyn_conn_list
;
dyn_conn_list : dyn_conn_element
| dyn_conn_list COMMA dyn_conn_element
;
dyn_conn_element
: SBOPEN NUMBER COMMA NUMBER COMMA NUMBER SBCLOSE
;
opt_dyn_block : /* empty */
| dyn_block
;
dyn_block : BBOPEN authentication BBCLOSE
;
multi_applicat_opt
: /* empty */
| multi_applicat
;
multi_applicat : applicat
| multi_applicat applicat
;
applicat : ta_appl ta_attrib /* server */
| non_ta_appl /* client */
| foreign_appl foreign_attrib
;
ta_appl : ta_appl_1
| ta_appl_2
;
ta_appl_1 : ta_appl_best
| ta_appl_max
;
GINA V4.0 System Administrator Guide – September 2000 83
Configuration language
non_ta_appl : nonta_appl_remote
| nonta_appl_1
;
ta_appl_best : TA_APPLICATION
SBOPEN
LETTER COMMA
NUMBER COMMA
NUMBER COMMA
LETTER COMMA
BEST_BCAMAPPL
SBCLOSE
;
ta_appl_max : TA_APPLICATION
SBOPEN
LETTER COMMA
NUMBER COMMA
NUMBER COMMA
LETTER
SBCLOSE
;
ta_appl_2 : TA_APPLICATION
SBOPEN
NUMBER COMMA
NUMBER COMMA
RESERVE
SBCLOSE
;
nonta_appl_1 : APPLICATION
SBOPEN
NUMBER COMMA
NUMBER COMMA
LETTER
SBCLOSE
| APPLICATION
SBOPEN
NUMBER COMMA
NUMBER COMMA
84 GINA V4.0 System Administrator Guide – September 2000
Configuration language
LETTER COMMA
LETTER COMMA /* userid */
Druck vom 24. 01.2001 17:00.34 torb-kon
LETTER /* passwd */
SBCLOSE
;
nonta_appl_remote
: APPLICATION
SBOPEN
NUMBER COMMA
NUMBER COMMA
LETTER COMMA
REMOTE
SBCLOSE
| APPLICATION
SBOPEN
NUMBER COMMA
NUMBER COMMA
LETTER COMMA
REMOTE COMMA
LETTER COMMA /* userid */
LETTER /* passwd */
SBCLOSE
;
foreign_appl : FOREIGN_APPLICATION
SBOPEN
NUMBER COMMA
NUMBER COMMA
LETTER SBCLOSE
| FOREIGN_APPLICATION
SBOPEN
NUMBER COMMA
NUMBER COMMA
LETTER COMMA LETTER SBCLOSE
| FOREIGN_APPLICATION
SBOPEN
NUMBER COMMA
NUMBER COMMA
NUMBER COMMA /* foreign application number */
LETTER SBCLOSE
| FOREIGN_APPLICATION
SBOPEN
GINA V4.0 System Administrator Guide – September 2000 85
Configuration language
NUMBER COMMA
NUMBER COMMA
NUMBER COMMA /* foreign application number */
LETTER COMMA LETTER SBCLOSE
;
vector : KEYVECTOR SBOPEN NUMBER COMMA NUMBER
SBCLOSE
;
address : PORTADDRESSES SBOPEN NUMBER COMMA
NUMBER SBCLOSE
;
multi_link_opt : multi_link
| /* empty */
;
multi_link : link
| multi_link link
;
link : sessblock
| connect
;
connect : CONNECT
SBOPEN
NUMBER COMMA NUMBER COMMA NUMBER COMMA
NUMBER
SBCLOSE
;
sessblock : session_header
BBOPEN sesspoint sesspoint BBCLOSE
| foreign_session_header
BBOPEN foreign_sesspoint
foreign_sesspoint BBCLOSE
;
foreign_session_header
: FOREIGN_SESSION SBOPEN LETTER SBCLOSE
| FOREIGN_SESSION SBOPEN LETTER COMMA MAP_SYSTEM SBCLOSE
;
86 GINA V4.0 System Administrator Guide – September 2000
Configuration language
session_header : SESSION SBOPEN LETTER SBCLOSE
Druck vom 24. 01.2001 17:00.34 torb-kon
| SESSION SBOPEN LETTER COMMA MAP_SYSTEM SBCLOSE
;
foreign_sesspoint
: foreign_sesspoint_header
BBOPEN address_converter BBCLOSE
| foreign_sesspoint_header
;
foreign_sesspoint_header
: SESSIONPOINT
SBOPEN
NUMBER COMMA NUMBER COMMA NUMBER
SBCLOSE
;
address_converter
: foreign_address converter_opt
;
foreign_address
: ADDRESS SBOPEN LETTER COMMA LETTER SBCLOSE
;
converter_opt : /* empty */
| converter
;
converter : IN_CONVERTER SBOPEN NUMBER SBCLOSE
| IN_CONVERTER SBOPEN NUMBER COMMA NUMBER SBCLOSE
| OUT_CONVERTER SBOPEN NUMBER SBCLOSE
;
sesspoint : SESSIONPOINT
SBOPEN
NUMBER COMMA NUMBER COMMA NUMBER
SBCLOSE
;
%%
GINA V4.0 System Administrator Guide – September 2000 87
Revision generation
6.3 Revision generation
The purpose of the revision generation is as follows: when the configuration is revised, the
generation for the applications not affected by the revision remain the same.
Prerequisites
The use of a repository is an absolute must for this revision generation (see the statement
REPOSITORY
version or updated to the new status.
The applications use host resources such as authorization keys (KEYVECTOR) and port num-
bers (PORTADDRESSES). The applications not affected by a revision must use the same
resources. The authorization keys and port numbers are stored in the repository for each
application.
When creating the kdcdf script, the generator config must generate unique identifiers
foreach application. The same identifiersmust then be used ina revisiongeneration. In the
case of a first generation with an empty repository, a generation number is written to the
repository for each application so that this number will be used to generate the identifiers
(see the statement
The followingfurther characteristics or values are entered in the repository for each server
application:
on page 60). The repository must be created when generating the previous
START_VALUE
on page 64).
– KDCFILE, DOUBLE
If the KDCFILE is maintained in duplicate for security reasons, the characteristic
DOUBLE is stored and can then be taken into account during the next generation.
– PGPOOLFS
The PGPOOLFS parameter defines the number of files across which the page pool is
distributed. This number is entered in the repository and can thus be evaluated during
the next generation.
– RECBUFFS
RECBUFFS defines the number of files across which the restart area is to be distributed.
This number is stored in the repository and read during the next generation.
88 GINA V4.0 System Administrator Guide – September 2000
Loading...