0001 Migrating from Oracle Tuxedo to Enduro/X
0002 ========================================
0003 :doctype: book
0004
0005 == About the guide
0006
0007 This document describes different aspects which needs to be accounted for
0008 when performing migration from Oracle Tuxedo to Enduro/X middleware.
0009 The document describes common elements which Enduro/X covers from Tuxedo
0010 functionality, how functionality and configuration differs.
0011
0012 Lastly document describes standard approach for performing configuration
0013 migration for Tuxedo UBB Config to Enduro/X based configuration
0014
0015 Document shall be read by anybody which is involved into migration project
0016 from Oracle Tuxedo to Enduro/X middleware.
0017
0018 == Overview
0019
0020 Both systems are build on X/Open *XATMI*, *XA*, *TX* standards. Each of the systems
0021 implement extensions over theses APIs. For example Tuxedo have *FML* key-value
0022 structure format handling API. Enduro/X counterpart for this functionality is
0023 *UBF* buffers which even provide emulation for *FML* via *fml.h* and *fml32.h*
0024 headers shipped with Enduro/X.
0025
0026 Enduro/X tends to implement most majority of the C APIs which are typically used in
0027 Tuxedo application. To verify your application compatibility with Enduro/X,
0028 perform manual scan over your code base and check each Tuxedo API in Enduro/X
0029 documentation.
0030
0031 Enduro/X uses different configuration file formats than Tuxedo, however majority
0032 of the configuration concepts are the same.
0033
0034 Enduro/X provides tool *ubb2ex(8)* which allows to automatically convert Tuxedo
0035 UBB configuration to Enduro/X configuration files.
0036
0037
0038 == API compatibility aspects
0039
0040 Mostly all XATMI/FML calls are supported by Enduro/X with the same logic and
0041 parameters. This section lists some (but not all) known differences:
0042
0043 - *tpgetctxt(3)* Enduro/X version after the call puts current thread outside
0044 of any context association.
0045
0046 - When using *tpnotify(3)* or *tpbroadcast(3)* in multi-machine mode, to
0047 allow remote nodes to process the notifications, *tpbrdcstsv(8)* process
0048 shall be started on the remote nodes.
0049
0050 - In case if duplicate field IDs are used for UBF/FML, default logic
0051 of *mkfldhdr(8)* would generate error. In case if for some reason duplicate
0052 field IDs are OK, flag *ubf_dupfidok* shall be set in *NDRX_APIFLAGS* (see *ex_env(5)*).
0053 Note that for runtime this flag is not required i.e. only needed for build time.
0054
0055 - *Bnext(3)* / Fnext() / Fnext32() Enduro/X version keeps the iteration state
0056 within thread local storage, however Tuxedo stores the state in the FML buffer
0057 (or uses some other mapped association of the iteration states of multiple buffers).
0058 This means that if iterating multiple buffers at the same time by the same thread,
0059 Enduro/X version will corrupt the iteration state for previous buffer iterations.
0060 However Enduro/X offers *Bnext2(3)* API call which allow to store the iteration
0061 state in reentrant way.
0062
0063 === Tuxedo API bindings
0064
0065 - *endurox-java* package serves as direct counterpart of the *Oracle Tuxedo Java*. Some
0066 of the APIs are different, but majority conforms to the *TJATMI*. Enduro/X implementation
0067 is based on JNI binding code. Each java instance is started as separate binary.
0068
0069
0070 == Enduro/X installation process
0071
0072 Before starting the migration, necessary package shall be installed. The binary
0073 versions can be downloaded from https://www.mavimax.com/downloads where installers
0074 for desired platforms can be found. For example, if installing for
0075 Red-Hat Enterprise Linux 8, following procedure applies:
0076
0077 --------------------------------------------------------------------------------
0078
0079 $ wget https://www.endurox.org/attachments/download/1393/endurox-7.5.34-5.oracleserver8_0_GNU_epoll.x86_64.rpm
0080 $ wget https://www.endurox.org/attachments/download/1089/endurox-connect-2.5.0-1.oracleserver8_0.x86_64.rpm
0081
0082 $ su - root
0083
0084 # rpm -i endurox-7.5.34-5.oracleserver8_0_GNU_epoll.x86_64.rpm
0085 # rpm -i endurox-connect-2.5.0-1.oracleserver8_0.x86_64.rpm
0086
0087 --------------------------------------------------------------------------------
0088
0089 Once packages are installed, system limits must be configured
0090 see ex_adminman(guides)(Enduro/X Administration Manual, Setup System) section,
0091 particularly:
0092
0093 . 2.2. Linux setup / Increase OS limits
0094
0095 . 2.2. Linux setup / Setting Posix queue limits
0096
0097 For other Operating systems, other chapters applies from the administration manual.
0098
0099
0100 == Migration process
0101
0102 Migration from Oracle Tuxedo to Enduro/X typically is accomplished by following steps:
0103
0104 image:migration_tuxedo_process.png[caption="Figure 1: ", title="Migration from Tuxedo to Enduro/X steps",width=440]
0105
0106 . *Code analysis:* User application source code analysis for API compatibility. This can be done by
0107 manually checking each of the Tuxedo calls and their counterparts in the Enduro/X
0108 documentation.
0109
0110 . *Build:* The first step may be skipped, and migration may be started with the build, to
0111 let the compiler to analyze the source code compatibility. Enduro/X has the
0112 same build tools as Tuxedo: *buildserver(8)*,
0113 *buildclient(8)* and *buildtms(8)*. In case if some of the APIs are missing,
0114 developer needs to figure out how user code can be changed to avoid such API
0115 use. Or the other option is to contact Mavimax SIA company for change request
0116 to introduce such new API.
0117
0118 . *Configuration migration:* Migrate the configuration either by
0119 automatic tool *ubb2ex(8)* or convert configuration manually according to next chapters.
0120
0121 . *Testing:* Perform extensive system testing.
0122
0123 . *Go live*.
0124
0125
0126 == Automatic configuration migration
0127
0128 Enduro/X ships with the configuration migration tool *ubb2ex(8)*. Tool accepts valid
0129 Tuxedo UBBConfig text format file. It is able to process multi-machine configuration
0130 and it produces following set of configuration files for each of the *LMID* found
0131 in UBBconfig:
0132
0133 . set<lmid_lowercase> - environment source bash script
0134
0135 . ndrxconfig.<lmid_lowercase>.xml - *ndrxd(8)* and *cpmsrv(8)* configuration file.
0136
0137 . app.<lmid_lowercase>.ini - per binary configuration file.
0138
0139
0140 ==== Automatic configuration migration, by example
0141
0142 In the following example prefix directory -P ./test_dir is used. This basically
0143 adds prefix to all paths found in the *ubb_config1*.
0144
0145 --------------------------------------------------------------------------------
0146
0147 $ ubb2ex ubb_config1 -P ./test_dir
0148 UBB2EX Tool
0149
0150 Enduro/X 7.5.36, build Dec 17 2021 22:33:46, using epoll for LINUX (64 bits)
0151
0152 Enduro/X Middleware Platform for Distributed Transaction Processing
0153 Copyright (C) 2009-2016 ATR Baltic Ltd.
0154 Copyright (C) 2017-2021 Mavimax Ltd. All Rights Reserved.
0155
0156 This software is released under one of the following licenses:
0157 AGPLv3 (with Java and Go exceptions) or Mavimax license for commercial use.
0158
0159
0160 $ cd test_dir/user90/conf
0161
0162 $ ls -1
0163
0164 app.test1.ini
0165 ndrxconfig.test1.xml
0166 settest1
0167
0168 $ source settest1
0169
0170 $ xadmin start -y
0171 Enduro/X 7.5.36, build Dec 17 2021 22:33:46, using epoll for LINUX (64 bits)
0172
0173 Enduro/X Middleware Platform for Distributed Transaction Processing
0174 Copyright (C) 2009-2016 ATR Baltic Ltd.
0175 Copyright (C) 2017-2021 Mavimax Ltd. All Rights Reserved.
0176
0177 This software is released under one of the following licenses:
0178 AGPLv3 (with Java and Go exceptions) or Mavimax license for commercial use.
0179
0180 * Shared resources opened...
0181 * Enduro/X back-end (ndrxd) is not running
0182 * ndrxd PID (from PID file): 57479
0183 * ndrxd idle instance started.
0184 exec cconfsrv -k C4Lwt7G4 -i 1 -e /tmp/test_dir/user90/log/cconfsrv.1.log -r -- :
0185 process id=57481 ... Started.
0186 exec cconfsrv -k C4Lwt7G4 -i 2 -e /tmp/test_dir/user90/log/cconfsrv.2.log -r -- :
0187 process id=57482 ... Started.
0188 exec tpadmsv -k C4Lwt7G4 -i 3 -e /tmp/test_dir/user90/log/tpadmsv.3.log -r -- :
0189 process id=57483 ... Started.
0190 exec tpadmsv -k C4Lwt7G4 -i 4 -e /tmp/test_dir/user90/log/tpadmsv.4.log -r -- :
0191 process id=57484 ... Started.
0192 exec tpevsrv -k C4Lwt7G4 -i 5 -e /tmp/test_dir/user90/log/tpevsrv.5.log -r -- :
0193 process id=57485 ... Started.
0194 exec tmsrv -k C4Lwt7G4 -i 8 -e /tmp/test_dir/user90/log/tmsrv.8.log -r -- -t1 -l /tmp/test_dir/user90/tmlogs/rm8 :
0195 process id=57491 ... Started.
0196 exec tmsrv -k C4Lwt7G4 -i 9 -e /tmp/test_dir/user90/log/tmsrv.9.log -r -- -t1 -l /tmp/test_dir/user90/tmlogs/rm8 :
0197 process id=57503 ... Started.
0198 exec tmqueue -k C4Lwt7G4 -i 40 -e /tmp/test_dir/user90/log/tmqueue.40.log -r -- -s1 -p10 -f10 :
0199
0200 ...
0201 --------------------------------------------------------------------------------
0202
0203
0204 == Manual configuration migration
0205
0206 Even if configuration is being migrated by automatic approach, it is worth to
0207 read this section. This allows get solid understand of the Enduro/X concepts by using
0208 existing Tuxedo knowledge.
0209
0210 === How to read this manual
0211
0212 The following section lists only similar Oracle Tuxedo items which
0213 can be mapped to Enduro/X configuration files. Any Tuxedo configuration sections
0214 or settings that are not mentioned in bellow sections, does not map directly to
0215 Enduro/X or Enduro/X have different concepts or approach for the functionality.
0216
0217 === High level configuration and binaries mappings
0218
0219 If looking on Tuxedo UBBCONFIG and Enduro/X ndrxconfig.xml/app.ini, then following
0220 similarities can be found:
0221
0222 .UBBConfig - Enduro/X section mapping
0223 [width="80%", options="header"]
0224 |=========================================================
0225 |Ubb config section|Enduro/X ndrxconfig.xml|Enduro/X app.ini|Comments
0226 |*RESOURCES|-|[@global] section|Approximate mapping
0227 |*MACHINES|-|[@global], [@debug] path related infos|Approximate mapping
0228 |*GROUPS|-|[@global/<CCTAG>] - global settings per tag, [@queue/<CCTAG>] - persistent
0229 queue configuration per tag.|Approximate mapping
0230 |*NETWORK|Bridge is established as *tpbridge(8)* XATMI server
0231 processes in <servers> section|-|Approximate mapping
0232 |*SERVERS|<endurox>/<servers> tag |-|-
0233 |*SERVERS server|<endurox>/<servers>/<server name="server"> tag |-|-
0234 |*SERVERS DEFAULT:|<endurox>/<defaults> tag |-|-
0235 |*SERVICES|<endurox>/<services>|-|Service settings are global per instance, i.e.
0236 cannot be configured per cctag.
0237 |*SERVICES service|<endurox>/<services>/<service svcnm="service">|-|-
0238 |*SERVICES DEFAULT:|<endurox>/<services>/<defaults>|-|-
0239 |*ROUTING|<endurox>/<routing>|-|Defaults are not supported for this section.
0240 |*ROUTING route|<endurox>/<routing>/<route routing="route">|-|-
0241 |=========================================================
0242
0243 .Tuxedo - Enduro/X key binaries mapping
0244 [width="80%", options="header"]
0245 |=========================================================
0246 |Tuxedo binary|Enduro/X equivalent|Comments
0247 |tmadmin|xadmin|There are set of common commands, like psc, start, etc.
0248 |BBL, DBBL|ndrxd|
0249 |tlisten|tpbridge|Enduro/X binary is booted as a normal XATMI binary, i.e.
0250 it is not required to start it before application boots
0251 |TMSYSEVT,TMUSEREV|tpevsrv|Also Enduro/X event server is booted as a normal
0252 XATMI binary.
0253 |TMS|tmsrv|Enduro/X version of *tmsrv* supports loading XA switches via shared
0254 libraries. So it is possible to configure *tmsrv* instances for different resources
0255 without need to perform *buildtms(8)*. Enduro/X supports Tuxedo mode too, when
0256 transaction manager is built for particular resource manager.
0257 |=========================================================
0258
0259 === Creating base configuration for Enduro/X
0260
0261 It is recommended to create base configuration for Enduro/X which is then amended
0262 to match the migrated system setup.
0263
0264 In order to create a working instance of the Enduro/X application, you may use
0265 following command:
0266
0267 --------------------------------------------------------------------------------
0268
0269 $ xadmin provision
0270
0271 --------------------------------------------------------------------------------
0272
0273 This will create base system layout, including directories and configuration files
0274 such as:
0275
0276 - ndrxconfig.xml
0277 - app.ini
0278 - settest1 (environment loader)
0279
0280 For further document we assume that system code "test1" is used.
0281
0282 === UBB Configuration vs Enduro/X ini/xml format
0283
0284 *Tuxedo* use UBB configuration file, which is kind of extended ini file. This
0285 describes majority of information used for Tuxedo application instance.
0286
0287 On the other hand *Enduro/X* uses two separate files for the configuration. One is
0288 XML configuration file (*ndrxconfig.xml(5)* typically) which describes the XATMI
0289 server and client processes, services and DDR info. The other file is standard
0290 *ini* file (typically *app.ini*) which include per binary configuration.
0291
0292 Usually, Enduro/X applications are configured with third configuration file
0293 which loads the env variables in the shell session. File name typically
0294 starts with *set* prefix.
0295
0296 === Converting "*RESOURCES" section
0297
0298 Enduro/X resources shall be configured according to the *ex_env(5)* manpage. ThisF
0299 section lists elements with the same or close meaning. Enduro/X setting
0300 is written in *app.ini* in *[@global]* or *[@global/<CCTAG>]* section.
0301
0302 .Tuxedo - Enduro/X RESOURCES mapping
0303 [options="header"]
0304 |=========================================================
0305 |Tuxedo setting|Enduro/X equivalent|Comments
0306 |IPCKEY|NDRX_IPCKEY|System wide IPC (shm, msg, sem) identifier offset.
0307 This is hex value. For Enduro/X *0x* or *0X* prefix must not be present in value.
0308 | MAXSERVERS | NDRX_SRVMAX | Max number of servers instance can handle
0309 | MAXSERVICES | NDRX_SVCMAX | Max number of services instance can handle.
0310 For Enduro/X bigger number (something like x2) is recommended, so that linear
0311 hashing/service lookup would work faster.
0312 |SCANUNIT, BLOCKTIME | NDRX_TOUT | In Enduro/X timeouts are configured in single
0313 variable, set in seconds. Can be converted as NDRX_TOUT=(Tux SCANUNIT) * (Tux BLOCKTIME).
0314 |SCANUNIT| NDRX_SCANUNIT| In case if using *SystemV* release (AIX pre 7.3, Solaris),
0315 Enduro/X binaries internally by additional thread scan for timeouts in the local
0316 process. The scanning is done by *NDRX_SCANUNIT* setting (in milliseconds), which
0317 by default is *1000*. For Linux, FreeBSD, MacOS release this is not applicable.
0318 |MAXRTDATA|NDRX_RTCRTMAX|Number of bytes available for routing criterion storage.
0319 |=========================================================
0320
0321 === Converting "*MACHINES" section
0322
0323 In Enduro/X normally it each configuration set applies only to one machine/instance.
0324 So in Enduro/X there is no such direct equivalent to this section. However, some
0325 useful information is encoded in Tuxedo counterpart.
0326
0327 When converting multi-server UBBConfig file, it is needed to split all the resources
0328 in UBBConfig by *LMID*. For following UBB sections that could be done via *GROUP*
0329 setting.
0330
0331 If converting single machine (or multiple machines and working in different directories
0332 for each set of the files), then output files may be named as:
0333
0334 . set<lmid_lowercase>
0335
0336 . ndrxconfig.xml
0337
0338 . app.ini
0339
0340 In case if converting multiple machines in the same configuration directories,
0341 following configuration naming strategy shall be used:
0342
0343 . set<lmid_lowercase>
0344
0345 . ndrxconfig.<lmid_lowercase>.xml
0346
0347 . app.<lmid_lowercase>.ini
0348
0349 Following information from "*MACHINES" section projects to Enduro/X:
0350
0351 *settest1*:
0352
0353 --------------------------------------------------------------------------------
0354
0355 #/bin/bash
0356 #
0357 # @(#) Load this script in environment before Enduro/X start
0358 #
0359
0360 # update to correspond actual Enduro/X installation path
0361 export NDRX_HOME=/usr
0362 export NDRX_APPHOME=<Common part between APPDIR and TUXCONFIG, if no common part found, just use APPDIR >
0363 export NDRX_CCONFIG=<Directory name of TUXCONFIG>/app.ini
0364 export CDPATH=$CDPATH:.:${NDRX_APPHOME}
0365 export PATH=$PATH:<APPDIR>
0366
0367 --------------------------------------------------------------------------------
0368
0369 Additionally dirname of UBB *ULOGPFX* can be used as *[@global]/NDRX_ULOG*. Where
0370 later *NDRX_ULOG* by it self means a directory where ULOG files are written by
0371 mask 'ULOG.YYYYMMDD' and process debug logging is written.
0372
0373 Data from UBB *ENVFILE* setting may be copied to *app.ini* [@global] section.
0374
0375 The above is just recommended way how to setup runtime environment. Other
0376 approaches may be used too, according to *ex_env(5)* and
0377 *getting_started_tutorial(guides)(Getting Started Tutorial)*.
0378
0379 So if having Tuxedo configuration like:
0380
0381 --------------------------------------------------------------------------------
0382
0383 *MACHINES
0384 "SOME-MACHINE" LMID=TEST1
0385 TUXDIR="/some/folder/tuxedo12"
0386 APPDIR="/user90/bin"
0387 TUXCONFIG="/user90/conf/tuxconfig"
0388 ULOGPFX="/user90/log/ULOG"
0389 TLOGDEVICE="/user90/conf/TLOG"
0390 ENVFILE="./env_common.txt"
0391
0392 --------------------------------------------------------------------------------
0393
0394 That would be projected as following Enduro/X *set* file (*settest1*):
0395
0396 --------------------------------------------------------------------------------
0397
0398 # update to correspond actual Enduro/X installation path
0399 export NDRX_HOME=/usr
0400 export NDRX_APPHOME=/user90
0401 export NDRX_CCONFIG=${NDRX_APPHOME}/conf/app.ini
0402 export CDPATH=$CDPATH:.:${NDRX_APPHOME}
0403 export PATH=$PATH:${NDRX_APPHOME}/bin
0404
0405 --------------------------------------------------------------------------------
0406
0407 Additionally, *app.ini* would get:
0408
0409 --------------------------------------------------------------------------------
0410
0411 [@global]
0412 ...
0413 NDRX_ULOG=${NDRX_APPHOME}/log
0414
0415 # + any data from ENVFILE, directly copied here, as syntax basically is the same
0416
0417 --------------------------------------------------------------------------------
0418
0419 === Converting "*NETWORK" section
0420
0421 In Tuxedo, on each server *tlisten* binary shall be started which listens for
0422 any other node to connect. In Tuxedo this binary must be started before Tuxedo
0423 is booted.
0424
0425 In Enduro/X each cluster link (between this and other node) must be defined in
0426 *<servers>* section as a normal XATMI server. The XATMI server process name
0427 for link establishment between two nodes is *tpbridge(8)*.
0428 On one of the nodes listening/binding address/port must be configured together
0429 with passive mode, and on other node socket client mode shall be configured
0430 to connect to first node.
0431
0432 For example, if node *1* shall be connected to nodes *2* and *3*, then on node *1*, two
0433 *tpbridge* process shall be configured, to establish links to nodes *2* and *3*.
0434
0435 In Enduro/X cluster each server is identified with unique number in range for
0436 1..32, set in *NDRX_NODEID* parameter. This similar to Tuxedo's *LMID*, but
0437 value is strictly limited to numbers only. (Actually during automatic
0438 conversion by *ubb2ex(8)*, UBB keyword *LMID* is used for each instance,
0439 and tool assigns *NDRX_NODEID* just by counting from *1* upwards
0440 for each of the machines).
0441
0442 ==== Establishing links between nodes, by example
0443
0444 This assumes the scenario, when cluster is established by three nodes with LMIDs:
0445 SITE1, SITE2, SITE3. Each node establishes link with each.
0446
0447 *UBB configuration:*
0448
0449 This assumes that *tlisten* is started correctly prior Tuxedo boot.
0450
0451 --------------------------------------------------------------------------------
0452
0453 *NETWORK
0454 SITE1 NADDR="//localhost:999"
0455 NLSADDR="server1"
0456
0457 SITE2 NADDR="//127.0.0.1:999"
0458 NLSADDR="server2"
0459
0460 # hex format, first variant
0461 SITE3 NADDR="\\X00020AFF7F000001"
0462 NLSADDR="server3"
0463
0464 --------------------------------------------------------------------------------
0465
0466 *Enduro/X Configuration:*
0467
0468
0469 Enduro/X to have equivalent network setup, following connections needs to be defined:
0470
0471 image:migration_tuxedo_network.png[caption="Figure 2: ", title="Network connections between nodes"]
0472
0473
0474 *Note:* Port numbers shall be assigned manually for each of the links. *ubb2ex* uses
0475 following strategy: each listening socket derives the port number as:
0476 21000+NDRX_NODEID(currnet) * O_flag(default 100) + NDRX_NODEID(remote), e.g.
0477 If node *3* is listening for node 1 incoming connection, then for particular
0478 connection listening port would be: 21000+3*100+1 = 21301. This algorithm ensures
0479 that all migrated instances can be booted on localhost. If all booting on localhost
0480 is not needed, then when converting with *ubb2ex*, the flag -O may be set to *0*,
0481 which would prepare listening socket ports as number of 21000 + NDRX_NODEID(remote).
0482
0483
0484 *ndrxconfig.site1.xml*
0485
0486 --------------------------------------------------------------------------------
0487 <endurox>
0488 ...
0489 <servers>
0490 ...
0491 <!-- bi-directional link to site2, we are socket clients -->
0492 <server name="tpbridge">
0493 <min>1</min>
0494 <max>1</max>
0495 <srvid>6</srvid>
0496 <sysopt>-e ${NDRX_ULOG}/tpbridge.${NDRX_SVSRVID}.log</sysopt>
0497 <appopt>-n2 -r -i 127.0.0.1 -p 21201 -tA -z30</appopt>
0498 </server>
0499 <!-- bi-directional link to site3, we are socket clients -->
0500 <server name="tpbridge">
0501 <min>1</min>
0502 <max>1</max>
0503 <srvid>7</srvid>
0504 <sysopt>-e ${NDRX_ULOG}/tpbridge.${NDRX_SVSRVID}.log</sysopt>
0505 <appopt>-n3 -r -i 127.0.0.1 -p 21301 -tA -z30</appopt>
0506 </server>
0507
0508 --------------------------------------------------------------------------------
0509
0510 *NOTE:* Each connection either server or client fined by *tpbridge(8)*, contains
0511 other node id in parameter *-n*.
0512
0513 *NOTE:* These examples assumes that machine architectures are the same, if different
0514 architecture machines are being clustered (e.g. x86, PowerPC), then between these
0515 machines protocol mode must be enabled by *-f* cli flag for *tpbridge* on both ends.
0516
0517 *ndrxconfig.site2.xml*
0518
0519 --------------------------------------------------------------------------------
0520 <endurox>
0521 ...
0522 <servers>
0523 ...
0524 <!-- This is listening socket, for node1 to connect to us -->
0525 <server name="tpbridge">
0526 <min>1</min>
0527 <max>1</max>
0528 <srvid>5</srvid>
0529 <sysopt>-e ${NDRX_ULOG}/tpbridge.${NDRX_SVSRVID}.log</sysopt>
0530 <appopt>-n1 -r -i 0.0.0.0 -p 21201 -tP -z30</appopt>
0531 </server>
0532 <!-- This is client socket connecting to node 3 -->
0533 <server name="tpbridge">
0534 <min>1</min>
0535 <max>1</max>
0536 <srvid>7</srvid>
0537 <sysopt>-e ${NDRX_ULOG}/tpbridge.${NDRX_SVSRVID}.log</sysopt>
0538 <appopt>-n3 -r -i 127.0.0.1 -p 21302 -tA -z30</appopt>
0539 </server>
0540
0541 --------------------------------------------------------------------------------
0542
0543 *ndrxconfig.site3.xml*
0544
0545 --------------------------------------------------------------------------------
0546 <endurox>
0547 ...
0548 <servers>
0549 ...
0550 <!-- incoming socket for node1 -->
0551 <server name="tpbridge">
0552 <min>1</min>
0553 <max>1</max>
0554 <srvid>5</srvid>
0555 <sysopt>-e ${NDRX_ULOG}/tpbridge.${NDRX_SVSRVID}.log</sysopt>
0556 <appopt>-n1 -r -i 0.0.0.0 -p 21301 -tP -z30</appopt>
0557 </server>
0558 <!-- incoming socket for node2 -->
0559 <server name="tpbridge">
0560 <min>1</min>
0561 <max>1</max>
0562 <srvid>6</srvid>
0563 <sysopt>-e ${NDRX_ULOG}/tpbridge.${NDRX_SVSRVID}.log</sysopt>
0564 <appopt>-n2 -r -i 0.0.0.0 -p 21302 -tP -z30</appopt>
0565 </server>
0566
0567
0568 --------------------------------------------------------------------------------
0569
0570
0571 === Converting "*GROUPS" section
0572
0573 Tuxedo groups can be replaced with Enduro/X CCTAGs. CCTAG basically instructs
0574 processes that during XATMI initialization, library shall read specific parts
0575 from the *app.ini* configuration file. Mainly data encoded in Tuxedo "\*GROUPS"
0576 entry matches to the *[@global/<CCTAG>]* subsection.
0577
0578 Few more differences:
0579
0580 . Tuxedo's *SRVID* shall be unique within group, in Enduro/X *<srvid />* setting
0581 must be unique at instance level.
0582
0583 . In Enduro/X CCTAGs cannot be used to encode two or more instances in one configuration
0584 file. If several cluster instances must be configured, then configuration must
0585 be split and separate set/ini/xml files according to *LMIDs* used in Tuxedo configuration.
0586
0587 . Enduro/X CCTAGs may not be used to put processes in backup groups. The migration
0588 tool when processing such groups uses only first *LMID* value specified for the group.
0589
0590 . In case if XA processing and DDR is not performed by the group, the CCTAG
0591 is not needed to be assigned to the process. The process may be removed from
0592 CCTAG (if default was used) the empty *<cctag />* setting may be used under the *<server />* tag.
0593
0594 .Tuxedo - Enduro/X GROUPS mapping
0595 [options="header"]
0596 |=========================================================
0597 |Tuxedo setting|Enduro/X equivalent|Comments
0598 |GRPNO| app.ini: [@global/<CCTAG>]/NDRX_XA_RES_ID=__GRPNO__| Shall be set only if group fines XA resource
0599
0600 |TMSNAME| ndrxconfig.xml: <endurox>/<servers>/<server name="'TMSNAME'">| If 'TMSNAME' name is *TMS*, then *tmsrv*
0601 name shall be used. For null XA switch groups *app.ini*
0602 *[@global/CCTAG]/NDRX_XA_DRIVERLIB* shall be set to *libndrxxanulls.so*.
0603
0604 For /Q queues, *[@global/CCTAG]/NDRX_XA_DRIVERLIB* shall be set to *libndrxxaqdisks.so*
0605 and *[@global/CCTAG]/NDRX_XA_RMLIB* shall be set to *libndrxxaqdisk.so*.
0606
0607 For all other XA groups, *[@global/CCTAG]/NDRX_XA_DRIVERLIB* shall be set to
0608 *libndrxxatmsx.so* to use built-in xa switch.
0609
0610 |TMSCOUNT|ndrxconfig.xml:
0611 <endurox>/<servers>/<server name="_TMSNAME_">/<min>__TMSCOUNT__</min>
0612 and
0613 <endurox>/<servers>/<server name="_TMSNAME_">/<max>__TMSCOUNT__</max>|
0614 Configures TMSRV number of copies. In Enduro/X
0615 this is configured in the same way as all other XA servers.
0616
0617 |OPENINFO| app.ini: [@global/<CCTAG>]/NDRX_XA_OPEN_STR=__OPENINFO__|When converting from
0618 Tuxedo, the XA vendors interface name with colon (:) must be stripped from the value
0619 copied to app.ini.
0620
0621 |CLOSEINFO|app.ini: [@global/<CCTAG>]/NDRX_XA_CLOSE_STR=__CLOSEINFO__|When converting from
0622 Tuxedo, the XA vendors interface name with colon (:) must be stripped from the value
0623 copied to app.ini. If not info is required by XA switch vendor, value "-" shall be used.
0624
0625 |ENVFILE|Copy the data from __ENVFILE__ file to the [@global/<CCTAG>] ini sub-section |As basically
0626 [@globa] section loads the environment variables for the process, to match environment
0627 setup for each of the groups, the contents from the __ENVFILE__ file may be
0628 copied to the *app.ini*.
0629
0630 |Group participates in DDR|app.ini: [@global/<CCTAG>]/NDRX_RTGRP=_GROUP_NAME_|
0631 *Note:* The routing group name with any service name in the grouting group, must not
0632 exceed *29* symbols.
0633 |=========================================================
0634
0635 ==== Converting XA NULL group, participates in DDR, by example
0636
0637 *UBB configuration:*
0638
0639 --------------------------------------------------------------------------------
0640
0641 *GROUPS
0642 ...
0643
0644 DDR1 GRPNO=5 OPENINFO="NONE" TMSNAME="TMS" TMSCOUNT=3
0645
0646 *SERVERS
0647 ...
0648
0649 "atmi.sv90_3" SRVID=400 MIN=2 MAX=4 SRVGRP=DDR1 CLOPT="-s TESTSV_DDR:TESTSV -- "
0650 "atmi.sv90_4" SRVID=420 MIN=2 MAX=4 SRVGRP=DDR1 CLOPT="-A -- "
0651
0652 --------------------------------------------------------------------------------
0653
0654 *Enduro/X configuration:*
0655
0656 *app.ini:*
0657
0658 --------------------------------------------------------------------------------
0659
0660 [@global/DDR1]
0661 NDRX_XA_RES_ID=5
0662 NDRX_XA_OPEN_STR=-
0663 NDRX_XA_CLOSE_STR=-
0664 NDRX_XA_DRIVERLIB=libndrxxanulls.so
0665 NDRX_XA_RMLIB=-
0666 NDRX_XA_LAZY_INIT=0
0667 #NDRX_XA_FLAGS=FDATASYNC;DSYNC
0668 NDRX_RTGRP=DDR1
0669
0670 --------------------------------------------------------------------------------
0671
0672 *NB:* To protect transactions against OS crash or HW crash, *FDATASYNC*, *DSYNC*
0673 flags shall be enabled. The downside of this is, that performance would be
0674 reduced significantly.
0675
0676 *ndrxconfig.xml:*
0677
0678 --------------------------------------------------------------------------------
0679 <endurox>
0680 ...
0681 <servers>
0682 ...
0683 <!-- tmsrv or custom tms only once defined per first CCTAG/XA configuration usage -->
0684 <server name="tmsrv">
0685 <cctag>DDR1</cctag>
0686 <min>3</min>
0687 <max>3</max>
0688 <srvid>10</srvid>
0689 <sysopt>-e ${NDRX_ULOG}/tmsrv.${NDRX_SVSRVID}.log -r</sysopt>
0690 <appopt>-t1 -l ${NDRX_APPHOME}/tmlogs/rm5</appopt>
0691 </server>
0692 <server name="atmi.sv90_3">
0693 <cctag>DDR1</cctag>
0694 <min>2</min>
0695 <max>4</max>
0696 <srvid>400</srvid>
0697 <sysopt>-N -e ${NDRX_ULOG}/atmi.sv90_3.${NDRX_SVSRVID}.log -s TESTSV_DDR:TESTSV</sysopt>
0698 </server>
0699 <server name="atmi.sv90_4">
0700 <cctag>DDR1</cctag>
0701 <min>2</min>
0702 <max>4</max>
0703 <srvid>420</srvid>
0704 <sysopt>-e ${NDRX_ULOG}/atmi.sv90_4.${NDRX_SVSRVID}.log</sysopt>
0705 </server>
0706 ...
0707 --------------------------------------------------------------------------------
0708
0709 When XA related CCTAG is firstly used, the *tmsrv(5)* instance shall be defined.
0710 For each *tmsrv* or custom built *TMS* instance used, machine readable log directory shall be defined.
0711 In this example directory *$\{NDRX_APPHOME\}/tmlogs/rm5* is used.
0712
0713 ==== Converting /Q XA group, by example
0714
0715 In case if converting Tuxedo /Q queue groups additional mapping is used, i.e.
0716 Tuxedo's *TMQUEUE* and *TMQFORWARD* processes are merged under single *tmqueue(8)* instance.
0717 Also all persistent queue setup is performed in *app.ini*, no need for any special script
0718 execution, as it is in case of Tuxedo.
0719
0720 *UBB configuration:*
0721
0722 --------------------------------------------------------------------------------
0723
0724 *GROUPS
0725 ...
0726 QGRP1 LMID=TEST1 GRPNO=8 TMSNAME=TMS_QM TMSCOUNT=2 OPENINFO="TUXEDO/QM:/user90/conf/QUEUEA:QSPA"
0727
0728 *SERVERS
0729 ...
0730
0731 DEFAULT: SRVGRP=QGRP1
0732 RESTART=N
0733 REPLYQ=N
0734 CLOPT="-A"
0735
0736 TMQUEUE SRVID=40 CLOPT="-A -s QSPA:TMQUEUE -- "
0737
0738 ...
0739
0740 DEFAULT: SRVGRP=QGRP1
0741
0742 TMQFORWARD SRVID=1100 MIN=1 MAX=1 CLOPT="-A -- -i 2 -qQGRP1_1"
0743 TMQFORWARD SRVID=1120 MIN=1 MAX=1 CLOPT="-A -- -i 2 -qQGRP1_2 -t60"
0744 TMQFORWARD SRVID=1130 MIN=2 MAX=3 CLOPT="-A -- -i 2 -qQGRP1_3 "
0745
0746 --------------------------------------------------------------------------------
0747
0748 *Enduro/X configuration:*
0749
0750 *app.ini:*
0751
0752 --------------------------------------------------------------------------------
0753
0754 [@global/QGRP1]
0755 NDRX_XA_RES_ID=8
0756 NDRX_XA_OPEN_STR=datadir="${NDRX_APPHOME}/qdata/QSPA",qspace="QSPA"
0757 NDRX_XA_CLOSE_STR=${NDRX_XA_OPEN_STR}
0758 NDRX_XA_DRIVERLIB=libndrxxaqdisks.so
0759 NDRX_XA_RMLIB=libndrxxaqdisk.so
0760 NDRX_XA_LAZY_INIT=0
0761 NDRX_XA_FLAGS=FDATASYNC;DSYNC
0762
0763 # Queue definitions:
0764 [@queue/QGRP1]
0765 # Review as necessary, see q.conf man page for details
0766 @=svcnm=@,autoq=n,tries=3,waitinit=0,waitretry=30,waitretrymax=90,memonly=n,mode=fifo,workers=1
0767 QGRP1_1=autoq=y
0768 QGRP1_3=autoq=y,workers=2
0769 QGRP1_2=autoq=y,txtout=60
0770
0771 --------------------------------------------------------------------------------
0772
0773 Section *[@queue]* shall be reviewed according to *q.conf(5)* instructions. Non-automatic
0774 queues Enduro/X will instantiate automatically. The queue defaults are encoded in line
0775 starting with *@*. If *svcnm* is set to *@*, this means that automatic queue will send
0776 message to service whose name matches the queue name.
0777
0778 Enduro/X persistent queues stores data in the directory on the disk, the path corresponds
0779 to the *datadir* setting in *NDRX_XA_OPEN_STR*. The queue space name is encoded in *qspace*
0780 parameter.
0781
0782 *ndrxconfig.xml:*
0783
0784 --------------------------------------------------------------------------------
0785 <endurox>
0786 ...
0787 <defaults>
0788 <cctag>QGRP1</cctag>
0789 <respawn>N</respawn>
0790 </defaults>
0791 <servers>
0792 <server name="tmsrv">
0793 <min>2</min>
0794 <max>2</max>
0795 <srvid>8</srvid>
0796 <sysopt>-e ${NDRX_ULOG}/tmsrv.${NDRX_SVSRVID}.log -r</sysopt>
0797 <appopt>-t1 -l ${NDRX_APPHOME}/tmlogs/rm8</appopt>
0798 </server>
0799 <server name="tmqueue">
0800 <min>1</min>
0801 <max>1</max>
0802 <srvid>40</srvid>
0803 <sysopt>-e ${NDRX_ULOG}/tmqueue.${NDRX_SVSRVID}.log -r</sysopt>
0804 <appopt>-s1 -p10 -f10</appopt>
0805 </server>
0806 </servers>
0807 ...
0808
0809 --------------------------------------------------------------------------------
0810
0811 *NOTE*: No instance of *TMQFORWARD* is required. All forward handling is done
0812 by *tmqueue(8)* process. Number of forward threads are set in *-f* parameter,
0813 to avoid any waiting on senders, the number of forward threads shall match
0814 the total number of workers (*workers* setting in queue definition)
0815 configured for automatic queues.
0816
0817 ==== Converting normal XA group, by example
0818
0819
0820 *UBB configuration:*
0821
0822 --------------------------------------------------------------------------------
0823
0824 *GROUPS
0825 ...
0826
0827 ORAGRP2 LMID=TEST1
0828 GRPNO=6
0829 TMSNAME=TMS_ORA_2
0830 TMSCOUNT=2
0831 OPENINFO="Oracle_XA:ORACLE_XA+DB=ROCKY+SqlNet=SID1+ACC=P/username/password+SesTM=10+LogDir=/user90/xalog+Threads=true"
0832 CLOSEINFO="Oracle_XA:CLOSE_STR"
0833
0834 *SERVERS
0835 ...
0836 orabin2 SRVID=2000 SRVGRP=ORAGRP2
0837
0838 --------------------------------------------------------------------------------
0839
0840 *Enduro/X configuration:*
0841
0842 *app.ini:*
0843
0844 --------------------------------------------------------------------------------
0845
0846 [@global/ORAGRP2]
0847 NDRX_XA_RES_ID=6
0848 NDRX_XA_OPEN_STR=ORACLE_XA+DB=ROCKY+SqlNet=SID1+ACC=P/username/password+SesTM=10+LogDir=/user90/xalog+Threads=true
0849 NDRX_XA_CLOSE_STR=CLOSE_STR
0850 # use built in switch resolver
0851 NDRX_XA_DRIVERLIB=libndrxxatmsx.so
0852 NDRX_XA_RMLIB=-
0853 NDRX_XA_LAZY_INIT=1
0854 NDRX_XA_FLAGS=RECON:*:3:100;FDATASYNC;DSYNC
0855
0856 --------------------------------------------------------------------------------
0857
0858 *ndrxconfig.xml:*
0859
0860 --------------------------------------------------------------------------------
0861
0862 <endurox>
0863 ...
0864 <servers>
0865 ...
0866 <server name="TMS_ORA_2">
0867 <cctag>ORAGRP2</cctag>
0868 <min>2</min>
0869 <max>2</max>
0870 <srvid>19</srvid>
0871 <sysopt>-e ${NDRX_ULOG}/TMS_ORA_2.${NDRX_SVSRVID}.log -r</sysopt>
0872 <appopt>-t1 -l ${NDRX_APPHOME}/tmlogs/rm6</appopt>
0873 </server>
0874 <server name="orabin2">
0875 <cctag>ORAGRP2</cctag>
0876 <srvid>2100</srvid>
0877 <sysopt>-e ${NDRX_ULOG}/orabin2.${NDRX_SVSRVID}.log</sysopt>
0878 </server>
0879 ...
0880 --------------------------------------------------------------------------------
0881
0882 In this case transaction manager used is custom built from *buildtms(8)* output.
0883 This is one of the modes that may be used. The other option Enduro/X offer is to
0884 use generic *tmsrv* process and use one of the our XA switch loader shared
0885 libraries:
0886
0887 . *libndrxxaecpg(8)*: PostgreSQL PQ/ECPG XA switch emulator and loader.
0888 Use *NDRX_XA_DRIVERLIB=libndrxxaecpg.so*, *NDRX_XA_RMLIB=-*.
0889
0890 . *libndrxxapq(8)*: PostgreSQL PQ XA switch emulator and loader.
0891 Use *NDRX_XA_DRIVERLIB=libndrxxapq.so*, *NDRX_XA_RMLIB=-*.
0892
0893 . *libndrxxaoras(8)*: Oracle DB XA Switch loader. Use *NDRX_XA_DRIVERLIB=libndrxxaoras.so*
0894 for static registration switch (*xaosw*), use *NDRX_XA_DRIVERLIB=libndrxxaorad.so*
0895 for dynamic registration switch (*xaoswd*). Set *NDRX_XA_RMLIB* to the DB specific shared
0896 library which provides XA switches, e.g. *NDRX_XA_RMLIB=libclntsh.so*, by assuming that correct
0897 shared library path is configured in the environment. *NOTE:* As *tmsrv* in Enduro/X is multi-threaded,
0898 remember to set *+Threads=true* in *NDRX_XA_OPEN_STR* for Oracle DB connections.
0899
0900 . *libndrxxawsmqs(8)*: IBM WebSphere MQ XA Driver loader. Use *NDRX_XA_DRIVERLIB=libndrxxawsmqs.so*
0901 for static registration switch (*MQRMIXASwitch*), use *NDRX_XA_DRIVERLIB=libndrxxawsmqd.so*
0902 for dynamic registration switch (*MQRMIXASwitchDynamic*). Set *NDRX_XA_RMLIB* to the MQ specific shared
0903 library which provides XA switches, e.g. *NDRX_XA_RMLIB=libmqmxa64_r.so*, by assuming that correct
0904 shared library path is configured in the environment. The multi-threaded library version shall
0905 be used.
0906
0907 . *libndrxxadb2s*: IBM DB2 XA Switch loader. Use *NDRX_XA_DRIVERLIB=libndrxxadb2s.so*
0908 for static registration switch (*db2xacicst_std*), use *NDRX_XA_DRIVERLIB=libndrxxadb2d.so*
0909 for dynamic registration switch (*db2xacic_std*). Set *NDRX_XA_RMLIB* to the DB specific shared
0910 library which provides XA switches, e.g. *NDRX_XA_RMLIB=libdb2.so*, by assuming that correct
0911 shared library path is configured in the environment.
0912
0913 The above *TMS_ORA_2* usage example may be configured as:
0914
0915
0916 *app.ini:*
0917
0918 --------------------------------------------------------------------------------
0919
0920 [@global/ORAGRP2]
0921 NDRX_XA_RES_ID=6
0922 NDRX_XA_OPEN_STR=ORACLE_XA+DB=ROCKY+SqlNet=SID1+ACC=P/username/password+SesTM=10+LogDir=/user90/xalog+Threads=true
0923 NDRX_XA_CLOSE_STR=CLOSE_STR
0924 NDRX_XA_DRIVERLIB=libndrxxaoras.so
0925 NDRX_XA_RMLIB=libclntsh.so
0926 NDRX_XA_LAZY_INIT=1
0927 NDRX_XA_FLAGS=RECON:*:3:100;FDATASYNC;DSYNC
0928
0929 --------------------------------------------------------------------------------
0930
0931 *ndrxconfig.xml:*
0932
0933 --------------------------------------------------------------------------------
0934
0935 <endurox>
0936 ...
0937 <servers>
0938 ...
0939 <server name="tmsrv">
0940 <cctag>ORAGRP2</cctag>
0941 <min>2</min>
0942 <max>2</max>
0943 <srvid>19</srvid>
0944 <sysopt>-e ${NDRX_ULOG}/tmsrv.${NDRX_SVSRVID}.log -r</sysopt>
0945 <appopt>-t1 -l ${NDRX_APPHOME}/tmlogs/rm6</appopt>
0946 </server>
0947 <server name="orabin2">
0948 <cctag>ORAGRP2</cctag>
0949 <srvid>2100</srvid>
0950 <sysopt>-e ${NDRX_ULOG}/orabin2.${NDRX_SVSRVID}.log</sysopt>
0951 </server>
0952 ...
0953
0954 --------------------------------------------------------------------------------
0955
0956 ==== Additional notes for XA processing
0957
0958 When XA groups are used and for some reason there is chance that *tmsrv* logs
0959 are lost (for example, FSYNC flags were not used), additional process *tmrecoversv(5)*
0960 is recommended to be started at the and of application boot, which would collect the orphaned
0961 prepared transactions from all resource managers, and would perform the rollback of them.
0962 The rollbacks are not performed by resource managers automatically, due to fact that
0963 prepared transactions (from two phase commit protocol) are stuck in the database waiting
0964 for further commands from transaction managers.
0965
0966 *Enduro/X configuration:*
0967
0968 --------------------------------------------------------------------------------
0969
0970 <endurox>
0971 ..
0972 <defaults>
0973 <cctag/>
0974 <min>1</min>
0975 <max>1</max>
0976 </defaults>
0977 <servers>
0978 <server name="tmrecoversv">
0979 <srvid>6</srvid>
0980 <sysopt>-e ${NDRX_ULOG}/tmrecoversv.${NDRX_SVSRVID}.log -r</sysopt>
0981 <appopt>-p -s10</appopt>
0982 </server>
0983
0984 --------------------------------------------------------------------------------
0985
0986
0987 === Converting "*SERVERS" section
0988
0989 Servers and their defaults migrates to Enduro/X XML configuration relatively straight
0990 forward. Following section summarizes the server entry mapping
0991
0992 .Tuxedo - Enduro/X SERVERS mapping
0993 [options="header"]
0994 |=========================================================
0995 |Tuxedo setting|Enduro/X equivalent in <server> or <defaults> tags|Comments
0996 |SRVGRP|<cctag>|
0997 |SRVID|<srvid>|In Enduro/X must be unique across the instance configuration.
0998 |CLOPT|<sysopt>, <appopt>|In Enduro/X clopt may split by the -- in two parts
0999 server options goes to *<sysopt>* and all other options to *<appopt>*,
1000 but it is possible to leave all to the *<sysopt>*. Setting is not available for
1001 <defaults>.
1002 |MIN|<min>|
1003 |MAX|<max>|
1004 |ENVFILE|<env>|
1005 |CONV|N/A|For conversational servers at Enduro/X no special settings required.
1006 Conversational servers builds and configures in the same way as normal XATMI
1007 servers.
1008 |RQADDR|<rqaddr>|Used only for *SystemV* polling mode (Solaris, pre AIX 7.3).
1009 For all other modes, it is ignored.
1010 |RESTART|<respawn>|For Enduro/X default is *Y*.
1011 |MINDISPATCHTHREADS|<mindispatchthreads>|For Enduro/X minimum and default is 1.
1012 |MAXDISPATCHTHREADS|<maxdispatchthreads>|For Enduro/X minimum and default is 1.
1013 |THREADSTACKSIZE|NDRX_THREADSTACKSIZE in app.ini, or configured in <envs> tag as:
1014
1015 <envs><env name="NDRX_THREADSTACKSIZE">__THREADSTACKSIZE__/__1024__</env></envs>
1016 | Enduro/X value is in KB, thus UBB config value needs to be divided by 1024.
1017
1018 |=========================================================
1019
1020 ==== Converting server command line options
1021
1022 The Server command line options mostly matches between Tuxedo and Enduro/X XATMI
1023 servers, with few exceptions. Following table lists the details:
1024
1025 .Tuxedo - Enduro/X Server CLOPT mapping
1026 [options="header"]
1027 |=========================================================
1028 |Tuxedo CLOPT|Enduro/X <sysopt>|Comments
1029 |-A|-B|Cross mapping applies. In Enduro/X all servers are advertised by default.
1030 In case if in Tuxedo configuration *-A* is used, no flag must be used for Enduro/X.
1031 In case if *-A* is not used in Tuxedo configuration, in Enduro/X *-B* shall be used,
1032 to suppress advertise of built-in services.
1033 |-s|-S|Enduro/X does not support @filename syntax (advertise from file). All other
1034 work modes matches. The lower case *-s* parameter in Enduro/X provides functionality
1035 to alias services to other services instead of functions.
1036 |-e|-e|If not configured, Enduro/X logs all *stderr* and *stdout* to the parent process *stderr*,
1037 effectively *ndrxd(8)*.
1038 |-o|-o|Enduro/X redirect all *stdout* to specified file output. If not configured,
1039 output will be sent to configured *stderr* (set by *-e*) or
1040 parent process *stderr* (if *-e* is not configured), effectively *ndrxd(8)*.
1041 |-r|-r|Enduro/X ignores this flag.
1042 |=========================================================
1043
1044 ==== Converting server, by example
1045
1046 *UBB Configuration:*
1047
1048 --------------------------------------------------------------------------------
1049
1050 DEFAULT: SRVGRP=DFLTGRP
1051 MIN=1
1052 MAX=5
1053 REPLYQ=Y
1054 MAXGEN=10
1055 RESTART=N
1056 CLOPT="-A"
1057
1058 "atmi.sv90" SRVID=100 MIN=2 MAX=4 CLOPT="-A --"
1059 "atmi.sv90_2" SRVID=200 MIN=1 MAX=4 CLOPT="-A -e /tmp/err.out -- -c \"HELLO \\\"WORLD\""
1060
1061 DEFAULT: MAX=11
1062
1063 orabin3 SRVID=2200 SRVGRP=ORAGRP3 THREADSTACKSIZE=6500000
1064
1065 --------------------------------------------------------------------------------
1066
1067 *ndrxconfig.xml:*
1068
1069 --------------------------------------------------------------------------------
1070
1071 <endurox>
1072 ...
1073 <defaults>
1074 <cctag>DFLTGRP</cctag>
1075 <min>1</min>
1076 <max>5</max>
1077 <respawn>N</respawn>
1078 </defaults>
1079 <servers>
1080 <server name="atmi.sv90">
1081 <min>2</min>
1082 <max>4</max>
1083 <srvid>100</srvid>
1084 <sysopt />
1085 </server>
1086 <server name="atmi.sv90_2">
1087 <min>1</min>
1088 <max>4</max>
1089 <srvid>200</srvid>
1090 <sysopt>-e /tmp/err.out</sysopt>
1091 <appopt>-c "HELLO \"WORLD"</appopt>
1092 </server>
1093 ...
1094 <defaults>
1095 <max>11</max>
1096 </defaults>
1097 <servers>
1098 <server name="orabin3">
1099 <cctag>ORAGRP3</cctag>
1100 <srvid>2200</srvid>
1101 <envs><env name="NDRX_THREADSTACKSIZE">6347</env></envs>
1102 </server>
1103 ...
1104
1105 --------------------------------------------------------------------------------
1106
1107 ==== Converting Event servers: TMSYSEVT, TMUSREVT, by example
1108
1109 In case if application uses eventing (i.e. *tppost(3)* or *tpsubscribe(3)*, etc.)
1110 event server needs to be configured. Existing *TMSYSEVT* or *TMUSREVT* servers shall be replaced
1111 with single (*min/max=1*) instance of *tpevsrv(8)*.
1112
1113 *UBB configuration:*
1114
1115 --------------------------------------------------------------------------------
1116
1117 *SERVERS
1118 TMUSREVT SRVGRP=ADMINGRP SRVID=10 CLOPT="-A -- -f /user90/conf/TMUSREVT"
1119 TMSYSEVT SRVGRP=ADMINGRP SRVID=11 CLOPT="-A -- -f /user90/conf/TMSYSEVT"
1120
1121 --------------------------------------------------------------------------------
1122
1123 *ndrxconfig.xml:*
1124
1125 Enduro/X event server does not use control file, so when converting *-f* flag for
1126 these servers may be ignored. For performance reasons it is recommended to set
1127 thread dispatch threads to larger number than default *1*.
1128
1129 --------------------------------------------------------------------------------
1130
1131 <endurox>
1132 ...
1133 <servers>
1134 ...
1135 <server name="tpevsrv">
1136 <min>1</min>
1137 <max>1</max>
1138 <srvid>10</srvid>
1139 <mindispatchthreads>5</mindispatchthreads>
1140 <maxdispatchthreads>5</maxdispatchthreads>
1141 <sysopt>-e ${NDRX_ULOG}/tpevsrv.${NDRX_SVSRVID}.log -r</sysopt>
1142 </server>
1143
1144 --------------------------------------------------------------------------------
1145
1146 For any server, if no special requirement is needed, *-e* shall be configured
1147 and normally expected to be put to *NDRX_ULOG* directory with file name reflecting
1148 the binary name and it's server id.
1149
1150 ==== Adding admin server (for MIB interface)
1151
1152 In order to enable admin interface API via *.TMIB* service, *tpadmsv(8)* shall be
1153 configured:
1154
1155 --------------------------------------------------------------------------------
1156
1157 <endurox>
1158 ...
1159 <servers>
1160 ...
1161 <server name="tpadmsv">
1162 <min>2</min>
1163 <max>2</max>
1164 <srvid>3</srvid>
1165 <sysopt>-e ${NDRX_ULOG}/tpadmsv.${NDRX_SVSRVID}.log -r</sysopt>
1166 </server>
1167
1168
1169 --------------------------------------------------------------------------------
1170
1171 It is optional and only and only used by *xadmin mibget* command or *.TMIB* service calls.
1172
1173
1174 ==== Debug logging configuration per binary
1175
1176 Enduro/X allow to configure debug log levels per binary. If no debug is configured, Enduro/X writes
1177 logs for the processes at highest debug level (*5*), meaning that for normal use debug configuration
1178 shall be configured.
1179
1180 Enduro/X logging is split across following topics:
1181
1182 . *ubf* - this is UBF/FML library logging. Normally shall be disabled (set to level *0*).
1183
1184 . *ndrx* - this is XATMI internals logging, normally logging may be leaved at level *2* (error) or *3* (warning).
1185
1186 . *tp* - user logs, wrote by *TP_LOG()* and related macros. Also applies to *tplog(3)* XATMI call. This log
1187 level does not affect *ULOG* output.
1188
1189 Debug is configured according to *ndrxdebug.conf(5)* description. Sample section would look like:
1190
1191 *app.ini:*
1192
1193 --------------------------------------------------------------------------------
1194
1195 [@debug]
1196 #* - goes for all binaries not listed bellow
1197 *= ndrx=3 ubf=1 tp=3 threaded=l file=${NDRX_ULOG}/endurox.log
1198 xadmin=file=${NDRX_ULOG}/xadmin.log
1199 ndrxd=file=${NDRX_ULOG}/ndrxd.log
1200 cconfsrv=file=${NDRX_ULOG}/cconfsrv.${NDRX_SVSRVID}.log
1201 atmi.sv90=file=${NDRX_ULOG}/atmi.sv90.${NDRX_SVSRVID}.log
1202
1203 # this logs to stderr, except, if *-e* for server is set, then all logging
1204 # is redirected to that particular file.
1205 atmi.sv90_2= file=
1206
1207 --------------------------------------------------------------------------------
1208
1209 Debug settings are matched by the binary name. If binary is not found in the section, default * applies.
1210 Logging applies to all XATMI related processes, clients and servers, and stand-alone binaries which
1211 are just using UBF library, for example.
1212
1213
1214 ==== External connectivity replacements
1215
1216 Enduro/X does not have *WebLogic Tuxedo Connector* or *Jolt* libraries
1217 for Java. But Enduro/X provides Web Services interface module *endurox-connect*,
1218 particularly *restincl(8)* from which XATMI services can be exposed as JSONS
1219 web services. With this Enduro/X services may be called from any language which supports web
1220 services. Web services API provides capability for managing global transactions
1221 and associating the calls with the global transactions (this applies only for *restincl* incoming
1222 web service call layer).
1223
1224 If your software uses any of these following Tuxedo binaries: *WSL/WSH*, *JSL/JSH*, *WSH*, *GWWS*
1225 then consider to use *endurox-connect* package. If using *ubb2ex(8)* tool, when it sees any
1226 of these binaries, it omits them and provides sample *restincl(8)* configuration, for accepting
1227 incoming web service calls.
1228
1229 Sample configuration:
1230
1231 *app.ini:*
1232
1233 --------------------------------------------------------------------------------
1234
1235 [@restin]
1236 defaults={"errors":"json2ubf", "conv":"json2ubf"}
1237
1238 # Instance 1, see restincl manpage for the web service formats
1239 [@restin/RIN1]
1240 port=8080
1241 ip=0.0.0.0
1242 # invoke by: http://this.host:8080/SOME_SERVICE1
1243 /SOME_SERVICE1={"svc":"SOME_SERVICE1"}
1244 /SOME_SERVICE2={"svc":"SOME_SERVICE2"}
1245
1246 --------------------------------------------------------------------------------
1247
1248 *ndrxconfig.xml:*
1249
1250 --------------------------------------------------------------------------------
1251
1252 <endurox>
1253 ...
1254 <server name="cpmsrv">
1255 <srvid>7</srvid>
1256 <sysopt>-e ${NDRX_ULOG}/cpmsrv.${NDRX_SVSRVID}.log -r</sysopt>
1257 <appopt>-k3 -i1</appopt>
1258 </server>
1259 </servers>
1260 <clients>
1261 <client cmdline="restincl">
1262 <exec tag="RESTIN" autostart="Y" subsect="RIN1" cctag="RIN1" log="${NDRX_ULOG}/restincl.rin1.log"/>
1263 </client>
1264 </clients>
1265 ...
1266
1267 --------------------------------------------------------------------------------
1268
1269 As *restincl* purely is stand-alone XATMI client, Enduro/X offer such process monitoring
1270 via Client Process Monitor server - *cpmsrv(8)* this server starts any programs registered
1271 in the *<clients>* section. Basic management of the clients includes following commands:
1272
1273 . $ xadmin pc - print client processes and their statuses
1274
1275 . $ xadmin bc - boot client
1276
1277 . $ xadmin sc - stop client
1278
1279
1280 Once *restincl* is booted, check by:
1281
1282 --------------------------------------------------------------------------------
1283
1284 $ xadmin pc
1285 ...
1286 RESTIN/RIN1 - running pid 27014 (Fri Dec 17 11:46:52 2021)
1287
1288 --------------------------------------------------------------------------------
1289
1290 In case if process is not string, check the *${NDRX_ULOG}/restincl.rin1.log* log file,
1291 the port *8080* maybe busy already on host where migration is done.
1292
1293 The *FML/UBF* service may be called in following way:
1294
1295 --------------------------------------------------------------------------------
1296
1297 $ curl -s -i -H "Content-Type: application/json" -X POST \
1298 -d "{\"T_STRING_FLD\":\"HELLO POST\"}" http://localhost:8080/SOME_SERVICE2
1299
1300 HTTP/1.1 200 OK
1301 Content-Length: 238
1302 Content-Type: application/json
1303 Date: Fri, 17 Dec 2021 09:46:54 GMT
1304
1305 {
1306 "EX_IF_ECODE":0
1307 ,"T_LONG_FLD":9991
1308 ,"EX_IF_EMSG":"SUCCEED"
1309 ,"T_STRING_FLD":"HELLO POST"
1310 ,"T_STRING_2_FLD":["Hello World from XATMI server","Hello World from XATMI server, other"]
1311 ,"T_UBF_FLD":{
1312 "T_SHORT_FLD":[9991,9991]
1313 "T_CARRAY_FLD":"AAECAQAABAUGQUI="
1314 }
1315 }
1316
1317 --------------------------------------------------------------------------------
1318
1319 === Converting "*SERVICES" section
1320
1321 Enduro/X services settings applies to whole application instance. Enduro/X does
1322 not support different services settings according to different groups. Automatic
1323 configuration translation tool *ubb2exp* uses SRVGRP only to decide to which
1324 configuration set service shall be added. If for the same LMID the same service
1325 is used for several groups, only first service entry and it's settings are
1326 translated to new configuration, and other same service entries are ignored.
1327
1328 .Tuxedo - Enduro/X SERVICES mapping
1329 [options="header"]
1330 |=========================================================
1331 |Tuxedo setting|Enduro/X equivalent in <services>/<service> and <services>/<defaults>|Comments
1332 |__SVCNM__|xml attr "svcnm"|Not available for <defaults>
1333 |PRIO|xml attr "prio"|
1334 |ROUTING|xml attr "routing"|
1335 |AUTOTRAN|xml attr "autotran"|
1336 |TRANTIME|xml attr "trantime"|
1337 |=========================================================
1338
1339 ==== Converting SERVICES, by example
1340
1341 *UBB configuration:*
1342
1343 --------------------------------------------------------------------------------
1344
1345 *SERVICES
1346
1347 DEFAULT: AUTOTRAN=Y
1348 TRANTIME=60
1349 ROUTING=ROUT1
1350 PRIO=15
1351
1352 TESTSV_DDR ROUTING=ROUT1
1353 EXBENCH AUTOTRAN=Y ROUTING=ROUT2 PRIO=10 TRANTIME=40
1354
1355 --------------------------------------------------------------------------------
1356
1357 *ndrxconfig.xml:*
1358
1359 Enduro/X event server does not use control file, so when converting *-f* flag for
1360 these servers may be ignored. For performance reasons it is recommended to set
1361 thread dispatch threads to larger number than default *1*.
1362
1363 --------------------------------------------------------------------------------
1364 <endurox>
1365 ...
1366 <services>
1367 <defaults prio="15" routing="ROUT1" autotran="Y" trantime="60"/>
1368 <service svcnm="TESTSV_DDR" routing="ROUT1"/>
1369 <service svcnm="EXBENCH" prio="10" routing="ROUT2" autotran="Y" trantime="40"/>
1370 </services>
1371
1372 --------------------------------------------------------------------------------
1373
1374
1375 === Converting "*ROUTING" section
1376
1377 .Tuxedo - Enduro/X ROUTING mapping
1378 [options="header"]
1379 |=========================================================
1380 |Tuxedo setting|Enduro/X equivalent in <routing>/<route>|Comments
1381 |__CRITERION_NAME__|xml attr "routing"|
1382 |FIELD|<field>|
1383 |FIELDTYPE|<fieldtype>|
1384 |RANGES|<ranges>|
1385 |BUFTYPE|<buftype>|Only supported routing type is *UBF*. This means
1386 that if in Tuxedo configuration constants *FML* or *FML32* are used,
1387 in Enduro/X equivalent is *UBF*.
1388 |=========================================================
1389
1390
1391 *UBB configuration:*
1392
1393 --------------------------------------------------------------------------------
1394
1395 *ROUTING
1396
1397 ROUT1 FIELD=T_STRING_10_FLD BUFTYPE="FML32" FIELDTYPE=STRING
1398 RANGES="'0':DDR1,'2':DDR2,*:*"
1399
1400 ROUT2 FIELD=T_STRING_10_FLD BUFTYPE="FML32" FIELDTYPE=STRING
1401 RANGES="'0':DDR1,'2':DDR2,*:*"
1402
1403 --------------------------------------------------------------------------------
1404
1405 *ndrxconfig.xml:*
1406
1407 Enduro/X event server does not use control file, so when converting *-f* flag for
1408 these servers may be ignored. For performance reasons it is recommended to set
1409 thread dispatch threads to larger number than default *1*.
1410
1411 --------------------------------------------------------------------------------
1412
1413 <endurox>
1414 ...
1415 <routing>
1416 <route routing="ROUT1">
1417 <field>T_STRING_10_FLD</field>
1418 <ranges>'0':DDR1,'2':DDR2,*:*</ranges>
1419 <buftype>UBF</buftype>
1420 </route>
1421 <route routing="ROUT2">
1422 <field>T_STRING_10_FLD</field>
1423 <ranges>'0':DDR1,'2':DDR2,*:*</ranges>
1424 <buftype>UBF</buftype>
1425 </route>
1426 </routing>
1427
1428 --------------------------------------------------------------------------------
1429
1430 == System administration
1431
1432 This section lists common tasks that administrator needs to performed with the system
1433 and maps the similarities between the two middlewares.
1434
1435 .Tuxedo - Enduro/X Administrative tasks.
1436 [options="header"]
1437 |=========================================================
1438 |Task|Tuxedo command|Enduro/X command|Comments
1439 |Load configuration|$ tmloadcf|N/A|Enduro/X does not require configuration loading.
1440 Enduro/X uses actual text configuration to perform the system boot.
1441 |Starting the application instance|$ tmboot|$ xadmin start|For Enduro/X
1442 arguments *-y*, *-i* and *-s* works in the same way as in Tuxedo.
1443 Enduro/X provides wrapper *tmboot* over the *xadmin start*.
1444 |Stopping the application instance|$ tmshutdown|$ xadmin stop|For Enduro/X
1445 arguments *-y*, *-i* and *-s* works in the same way as in Tuxedo.
1446 Enduro/X provides wrapper *tmshutdown* over the *xadmin stop*.
1447 |Administrative CLI utility|$ tmadmin| $ xadmin|Enduro/X *xadmin* accepts commands
1448 from *stdin*, *as cli arguments* and *interactive shell mode*. Enduro/X ships
1449 with wrapper script named *tmadmin*.
1450 |List services|$ echo psc \| tmadmin|$ xadmin psc|
1451 |Print queues|$ echo pq \| tmadmin|$ xadmin pq|
1452 |List transactions| $ echo printtrans \| tmadmin|$ xadmin printtrans|
1453 |Dynamic configuration update|$ tmconfig|$ xadmin reload|Enduro/X command requests
1454 *ndrxd* to reload the configuration files from the disk, this does not require any
1455 interactive editing. In case if remove any server processes or making the <srvid>
1456 tags to be different for running XATMI servers, these servers must be stopped before
1457 executing *reload* command. In case if *ndrxconfig.xml* is invalid, the error
1458 is printed and existing configuration for the processes not changed.
1459 |Cleanup IPC resources|$ tmipcrm|$ xadmin down|Enduro/X xadmin's down command cleans
1460 all the IPC resources and also it kills all the server processes and as much
1461 as possible client processes.
1462 |Server process reloading (start/stop) one by one for high availability|N/A, manually write script for sequence of tmshutdown -i/tmboot -i|$ xadmin sreload -s <servernm>|
1463 |=========================================================
1464
1465 == Conclusions
1466
1467 This document shall provide enough information to successfully complete the migration
1468 from Oracle Tuxedo to Mavimax Enduro/X middleware. In case if support is necessary,
1469 the questions may be asked in:
1470
1471 . Forums: https://www.endurox.org/projects/endurox/boards
1472
1473 . Contact support@mavimax.com
1474
1475 . In case if some APIs are missing or other functionality of the Enduro/X shall be
1476 amended, change request may be ordered from Mavimax SIA.
1477
1478 . In case if providing patches by your self, prior making pull request to Github
1479 https://github.com/endurox-dev/endurox repository, do not forget to sign and send us
1480 a Mavimax Contribution Agreement, found at
1481 https://www.endurox.org/attachments/download/1211/MCA-20210513.pdf
1482
1483
1484
1485 ////////////////////////////////////////////////////////////////
1486 The index is normally left completely empty, it's contents being
1487 generated automatically by the DocBook toolchain.
1488 ////////////////////////////////////////////////////////////////
