BeanConnect V2.1 - Fujitsu manual server

© Siemens Nixdorf Informationssysteme AG 1995
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\title_UTM.fm
BeanConnect V2.1
Edition December 2008
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.
Feel free to send us your comments by e-mail to:
manuals@ts.fujitsu.com
Certified documentation
according to DIN EN ISO 9001:2000
To ensure a consistently high quality standard and
user-friendliness, this documentation was created to
meet the regulations of a quality management system which
complies with the requirements of the standard
DIN EN ISO 9001:2000.
cognitas. Gesellschaft für Technik-Dokumentation mbH
www.cognitas.de
Copyright and Trademarks
Copyright © Fujitsu Technology Solutions GmbH 2008.
All rights reserved.
Delivery subject to availability; right of technical modifications reserved.
All hardware and software names used are trademarks of their respective manufacturers.
This manual is printed
on paper treated with
chlorine-free bleach.
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicsotoc.fm
Juni 8, 2009 7:06 pm
© cognitas GmbH 2001-2005
Dokuschablonen für DARB XML in FSC-Layout Version 1.0 für FrameMaker ab Version 7 vom 19.05.2005
Contents
1
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.1
Target group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.2
Structure of the BeanConnect documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.3
Structure of this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.4
Changes compared to the predecessor version . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
1.5
Notes on third-party products and literature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
1.6
Notational conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2
JCA adapter integration overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.1
2.1.1
2.1.2
2.1.3
2.1.4
The JCA adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JCA adapter integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JCA 1.5 contracts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SOA architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JCA adapter integration in Oracle AS / OC4J . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
24
24
24
26
26
2.2
2.2.1
2.2.1.1
2.2.1.2
2.2.1.3
2.2.1.4
2.2.2
2.2.3
2.2.4
BeanConnect architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BeanConnect components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BeanConnect resource adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BeanConnect proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BeanConnect Management Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BeanConnect tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Standard operation with one resource adapter and one proxy . . . . . . . . . . . . . . . . . . . .
Multiple resource adapter mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Platform support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
28
28
29
30
32
33
34
35
36
2.3
2.3.1
2.3.1.1
2.3.1.2
BeanConnect as a JCA-compliant resource adapter . . . . . . . . . . . . . . . . . . . . . . . .
Outbound and inbound communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Outbound communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inbound communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
37
37
38
38
BeanConnect V2.1
3
Contents
2.3.2
2.3.2.1
2.3.2.2
2.3.3
2.3.3.1
2.3.3.2
2.3.4
Dialog and asynchronous communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dialog communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Asynchronous communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transactional and non-transactional communication . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transactional communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Non-transactional communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4
BeanConnect in cluster operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3
Installing BeanConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
3.1
3.1.1
3.1.1.1
3.1.1.2
3.1.1.3
3.1.1.4
3.1.1.5
3.1.2
Installing BeanConnect under Solaris systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Master installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing PCMX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing openUTM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing the BeanConnect product files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing the openUTM-LU62 Gateway (for CICS partners) . . . . . . . . . . . . . . . . . .
Silent installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing the BeanConnect proxy container and the Management Console . . . . . . . . .
46
46
47
47
48
48
48
49
3.2
3.2.1
3.2.1.1
3.2.1.2
3.2.1.3
3.2.1.4
3.2.1.5
3.2.2
Installing BeanConnect under Linux systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Master installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing PCMX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing openUTM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing the BeanConnect product files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing the openUTM-LU62 Gateway (for CICS partners) . . . . . . . . . . . . . . . . . .
Silent installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing the BeanConnect proxy container and the Management Console . . . . . . . . .
53
53
54
54
55
55
55
55
3.3
3.3.1
3.3.1.1
3.3.1.2
3.3.1.3
3.3.1.4
3.3.2
Installing BeanConnect under Windows systems . . . . . . . . . . . . . . . . . . . . . . . . . . .
Master installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing PCMX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing openUTM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing BeanConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing the openUTM-LU62 Gateway (for CICS partners) . . . . . . . . . . . . . . . . . .
Installing the BeanConnect proxy container via the command line . . . . . . . . . . . . . . . .
60
60
61
61
62
66
67
3.4
Installing a BeanConnect resource adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
3.5
Installing the BeanConnect tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
4
40
40
40
40
40
41
41
BeanConnect V2.1
Dokuschablonen für DARB XML in FSC-Layout Version 1.0 für FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2005
Juni 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicsotoc.fm
Contents
3.6
3.6.1
3.6.2
3.6.3
Update installation for the BeanConnect proxy container and
Management Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Update installation under Solaris systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Update installation under Linux systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Update installation under Windows systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
73
73
74
76
3.7
3.7.1
3.7.2
3.7.3
Uninstalling BeanConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Uninstalling BeanConnect under Solaris systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Uninstalling BeanConnect under Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Uninstalling BeanConnect under Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
78
78
79
80
3.8
Uninstalling the BeanConnect resource adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
3.9
Uninstalling the BeanConnect tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
4
Configuration in the application server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
4.1
4.1.1
4.1.2
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Configuration files in the application server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Configuration steps for outbound and inbound communication . . . . . . . . . . . . . . . . . . . 87
4.2
4.2.1
4.2.2
4.2.2.1
4.2.2.2
4.2.3
Configuring global properties for the resource adapter (ra.xml) . . . . . . . . . . . . . . .
Defining global properties in ra.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deploying and undeploying the resource adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deploying the resource adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Undeploying the resource adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example of an ra.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3
4.3.1
4.3.1.1
4.3.1.2
4.3.1.3
4.3.1.4
4.3.1.5
4.3.2
Setting configuration properties for outbound communication via
OSI-TP / LU6.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Defining connection-specific properties for OSI-TP / LU6.2 in oc4j-ra.xml . . . . . . . . . . 98
Defining the JNDI name and resource type for OSI-TP / LU6.2 . . . . . . . . . . . . . . . . 99
Defining configuration properties for OSI-TP / LU6.2 . . . . . . . . . . . . . . . . . . . . . . . 100
Adapting connection pooling for OSI-TP / LU6.2 . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Defining security settings (managing sign-on) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Example of an oc4j-ra.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Deploying an Enterprise JavaBean for OSI-TP / LU6.2 . . . . . . . . . . . . . . . . . . . . . . . . 111
4.4
4.4.1
4.4.1.1
4.4.1.2
4.4.1.3
4.4.1.4
4.4.1.5
4.4.2
Configuring outbound communication via UPIC . . . . . . . . . . . . . . . . . . . . . . . . . . .
Defining connection-specific properties for UPIC in oc4j-ra.xml . . . . . . . . . . . . . . . . . .
Defining the JNDI name and resource type for UPIC . . . . . . . . . . . . . . . . . . . . . . .
Setting the configuration properties for UPIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adapting connection pooling for UPIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Defining security settings (managing sign-on) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example of an oc4j-ra.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deploying an Enterprise JavaBean for UPIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BeanConnect V2.1
89
89
94
94
96
96
114
114
115
115
120
121
122
124
5
Contents
4.5
4.5.1
4.5.2
Setting configuration properties for inbound communication . . . . . . . . . . . . . . . . 127
Configuration properties in the ejb-jar.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Examples for ejb-jar.xml and orion-ejb-jar.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
4.6
Preparing resource adapter logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
4.7
Special characteristics of multiple resource adapter mode . . . . . . . . . . . . . . . . . . 136
4.8
Special characteristics in cluster operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
5
BeanConnect Management Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
5.1
5.1.1
5.1.2
5.1.3
Starting and shutting down the Management Console . . . . . . . . . . . . . . . . . . . . . .
Starting the Management Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting the Management Console's online Help system . . . . . . . . . . . . . . . . . . . . . . .
Shutting down the Management Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
144
144
144
145
5.2
5.2.1
5.2.2
5.2.3
User interface - Management Console window . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Navigation area in the Management Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managed objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Additional functions and information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
146
147
148
150
5.3
5.3.1
5.3.2
5.3.3
5.3.4
5.3.5
5.3.6
5.3.7
5.3.8
Functions of the BeanConnect Management Console . . . . . . . . . . . . . . . . . . . . . .
Configuration functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuration wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting and stopping proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checking the availability of BeanConnect components and EIS partners . . . . . . . . . .
Diagnosis support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Todo topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Cluster support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Management Console as a JMX client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
151
151
152
154
155
156
156
157
158
5.4
Administrative data of the Management Console . . . . . . . . . . . . . . . . . . . . . . . . . . 160
6
Configuration of BeanConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
6.1
Configuration steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
6.2
6.2.1
6.2.2
Adding a BeanConnect proxy to the Management Console . . . . . . . . . . . . . . . . . 165
Adding a new proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Removing a proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
6.3
6.3.1
6.3.2
6.3.3
Configuring the BeanConnect proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
General information on the proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Proxy Components: CICS partners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Modifying the administration password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6
168
168
172
177
BeanConnect V2.1
Dokuschablonen für DARB XML in FSC-Layout Version 1.0 für FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2005
Juni 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicsotoc.fm
Contents
6.3.4
6.3.4.1
6.3.4.2
6.3.4.3
Configuration options in expert mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Timer Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Performance Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Program Interface Mode (API Mode) . . . . . . . . . . . . . . . . . . . . . . . . . .
178
178
178
179
6.4
6.4.1
6.4.2
6.4.3
Configuring a BeanConnect proxy cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generating a proxy cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a proxy to the proxy cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Removing a proxy from a cluster / removing a proxy cluster . . . . . . . . . . . . . . . . . . . .
180
180
182
183
6.5
6.5.1
6.5.2
6.5.3
Configuring the BeanConnect resource adapter . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a resource adapter (no cluster operation) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a resource adapter in cluster operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Resource adapter configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
184
184
188
191
6.6
6.6.1
6.6.1.1
6.6.1.2
6.6.2
6.6.2.1
6.6.2.2
6.6.3
6.6.4
Configuring the EIS partners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring EIS partners of type openUTM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding EIS partners of the type UTM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuration files for EIS partners of type openUTM . . . . . . . . . . . . . . . . . . . . . .
Configuring EIS partners of type CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding EIS partners of the type CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuration files for the EIS partners of the type CICS . . . . . . . . . . . . . . . . . . . .
Configuring EIS partners of type XATMI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Removing an EIS partner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
193
194
194
202
203
203
211
213
213
6.7
6.7.1
6.7.2
Configuring outbound communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Configuring outbound services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Configuring outbound communication endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
6.8
6.8.1
6.8.2
6.8.3
6.8.4
Configuring inbound communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring inbound message endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring inbound services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up users for access to inbound message endpoints . . . . . . . . . . . . . . . . . . . .
Configuring the error message prefix for inbound communication . . . . . . . . . . . . . . . .
6.9
Saving and activating the configuration of the BeanConnect proxy . . . . . . . . . . . 228
6.10
6.10.1
6.10.2
6.10.2.1
6.10.2.2
6.10.2.3
Configuring the Management Console command handler (MC-CmdHandler) . .
Security and privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Administering the MC-CmdHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting the MC-CmdHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Shutting down the MC-CmdHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring an MC-CmdHandler as a service . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BeanConnect V2.1
219
219
224
226
227
230
230
231
231
232
233
7
Contents
6.11
6.11.1
6.11.2
6.11.2.1
6.11.2.2
6.11.2.3
Configuring the Management Console as a JMX client . . . . . . . . . . . . . . . . . . . . .
Defined resource adapter MBeans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up the JMX client in the Management Console . . . . . . . . . . . . . . . . . . . . . . . .
Setting up a JMX client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Establishing and clearing a connection to the JMX server . . . . . . . . . . . . . . . . . . .
Removing a JMX client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7
Adapting the configuration in the EIS partner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
7.1
7.1.1
7.1.1.1
7.1.1.2
7.1.1.3
7.1.1.4
7.1.2
Adapting the configuration in EIS partners of type openUTM . . . . . . . . . . . . . . . .
Defining connections between BeanConnect and openUTM . . . . . . . . . . . . . . . . . . . .
Defining an OSI-TP connection between BeanConnect and openUTM . . . . . . . . .
Defining a UPIC connection for outbound communication between the
openUTM partner and BeanConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Defining a socket connection between the openUTM partner and BeanConnect .
Defining a BCMAP entry (only for BS2000/OSD partners) . . . . . . . . . . . . . . . . . . .
Defining connections between BeanConnect and other EIS partners . . . . . . . . . . . . .
7.2
7.2.1
7.2.2
Adapting the configuration in EIS partners of type CICS . . . . . . . . . . . . . . . . . . . . 244
Configuration in the CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Configuration of VTAM on an IBM mainframe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
8
Administering BeanConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
8.1
8.1.1
8.1.2
8.1.3
8.1.4
Administering a BeanConnect proxy via the Management Console . . . . . . . . . . .
Starting a proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Restarting a proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stopping a proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Special characteristics in cluster operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
248
249
251
251
252
8.2
8.2.1
8.2.1.1
8.2.1.2
8.2.1.3
8.2.1.4
8.2.2
8.2.2.1
8.2.2.2
8.2.3
8.2.3.1
8.2.3.2
8.2.3.3
Administering a BeanConnect proxy container on command level . . . . . . . . . . .
Starting a proxy container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting via a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting using the proxy container program group under Windows . . . . . . . . . . . .
Starting as a Windows service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting after abnormal termination of a proxy container run . . . . . . . . . . . . . . . . .
Restarting a proxy container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Restarting using a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Restarting using the proxy container program group under Windows . . . . . . . . . .
Stopping a proxy container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stopping using a local script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stopping using the proxy container program group under Windows . . . . . . . . . . .
Stopping as a Windows service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
254
254
254
254
255
255
256
256
256
257
257
257
257
8
234
234
235
236
238
238
240
240
240
241
242
242
243
BeanConnect V2.1
Dokuschablonen für DARB XML in FSC-Layout Version 1.0 für FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2005
Juni 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicsotoc.fm
Contents
8.3
Starting an MC-CmdHandler as a service on Windows systems . . . . . . . . . . . . . . 258
8.4
8.4.1
8.4.2
8.4.3
Administering the openUTM-LU62 Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting the openUTM-LU62 Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stopping the openUTM-LU62 Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying status information on the openUTM-LU62 . . . . . . . . . . . . . . . . . . . . . . . . .
8.5
8.5.1
8.5.2
Administering the communication service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Starting and stopping the SNA daemon (Linux and Solaris systems) . . . . . . . . . . . . . 261
Starting and stopping a communication service in a command line
(Linux and Solaris systems) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
8.6
8.6.1
8.6.2
8.6.3
8.6.4
8.6.4.1
8.6.4.2
8.6.5
Checking the availability of BeanConnect proxies . . . . . . . . . . . . . . . . . . . . . . . . .
Checking the availability of a proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checking the availability of a BeanConnect resource adapter . . . . . . . . . . . . . . . . . . .
Checking the availability of an openUTM-LU62 Gateway and a
communication service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checking the availability of an MC-CmdHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checking the availability of the MC-CmdHandler with the Management Console .
Checking the availability of the MC-CmdHandler in the command line . . . . . . . . .
Checking the availability of an EIS partner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
267
268
268
268
269
8.7
8.7.1
8.7.2
8.7.3
8.7.3.1
8.7.3.2
8.7.4
8.7.4.1
8.7.4.2
8.7.5
8.7.5.1
8.7.5.2
8.7.6
Monitoring the resource adapter with the Management Console . . . . . . . . . . . . .
Establishing a connection to the MBean server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying MBean object names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying and modifying MBean attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying MBean attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Modifying MBean attribute values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Collecting and displaying diagnostic values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring, displaying and modifying statistics collectors . . . . . . . . . . . . . . . . . . .
Displaying statistical values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Subscribing to and displaying MBean notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Subscribing to MBean notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying MBean notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying and executing MBean operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
271
272
273
274
274
275
276
276
277
278
279
280
281
9
Interfaces and programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
9.1
BeanConnect-specific interfaces and Common Client Interface (CCI) . . . . . . . . . 284
9.2
9.2.1
9.2.1.1
9.2.1.2
9.2.1.3
Programming outbound communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BeanConnect-specific interfaces for outbound communication . . . . . . . . . . . . . . . . . .
Connection factory interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Connection interfaces (overview) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Communication using the connection interfaces . . . . . . . . . . . . . . . . . . . . . . . . . .
BeanConnect V2.1
259
259
260
260
263
263
266
286
286
286
287
290
9
Contents
9.2.2
9.2.3
9.2.3.1
9.2.3.2
9.2.3.3
9.2.3.4
9.2.3.5
9.2.3.6
9.2.4
9.2.4.1
9.2.4.2
9.2.5
9.2.6
Common Client Interface (CCI) for outbound communication . . . . . . . . . . . . . . . . . . .
Programming information on outbound communication . . . . . . . . . . . . . . . . . . . . . . . .
Addressing an EIS application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Placing BeanConnect calls in an EJB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Authentication (user ID and password) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Querying information on the conversation with the EIS application . . . . . . . . . . . .
Programming hints with respect to CICS applications . . . . . . . . . . . . . . . . . . . . . .
Support of DPL (Distributed Program Link) programs . . . . . . . . . . . . . . . . . . . . . .
Program framework for outbound communication . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Program framework for BeanConnect-specific interfaces . . . . . . . . . . . . . . . . . . .
Program framework for Common Client Interface (CCI) . . . . . . . . . . . . . . . . . . . . .
Outbound communication with XATMI partners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Code samples for outbound communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
298
299
299
299
300
301
301
302
303
303
304
308
309
9.3
9.3.1
9.3.2
9.3.3
9.3.4
9.3.5
9.3.6
9.3.6.1
9.3.6.2
9.3.6.3
313
313
314
315
317
317
318
318
320
9.3.7
9.3.7.1
9.3.7.2
9.3.8
Programming inbound communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLTP message-driven beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inbound communication with openUTM partners . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inbound communication with CICS applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inbound communication with other EIS partners (openUTM) . . . . . . . . . . . . . . . . . . . .
Inbound communication with XATMI partners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BeanConnect-specific interfaces for inbound communication . . . . . . . . . . . . . . . . . . .
Programming information on OLTP message-driven beans . . . . . . . . . . . . . . . . . .
Determining sender contexts in the OLTP message-driven bean . . . . . . . . . . . . .
Program framework using the interfaces AsyncOltpMessageListener and
OltpMessageListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Common Client Interface (CCI) for inbound communication . . . . . . . . . . . . . . . . . . . .
Programming information on OLTP message-driven beans (CCI) . . . . . . . . . . . .
Program framework using the interface javax.resource.cci.MessageListener . . . .
Code samples for inbound communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10
Encoding and national language support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
10.1
10.1.1
10.1.3
10.1.4
10.1.5
Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Standard conversion between EBCDIC code and Unicode for EIS partners
of type openUTM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Standard conversion between EBCDIC code and Unicode for EIS partners
of type CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using other predefined code tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using custom charsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating and using legacy code tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2
National language support for message output . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
10.1.2
10
322
324
324
324
327
334
334
337
337
345
345
BeanConnect V2.1
Dokuschablonen für DARB XML in FSC-Layout Version 1.0 für FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2005
Juni 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicsotoc.fm
Contents
11
BPEL support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
11.1
Function scope of BeanConnect BPEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
11.2
Deploying the BeanConnect resource adapter in the BPEL environment . . . . . . 353
11.3
11.3.1
11.3.2
11.3.2.1
11.3.2.2
11.3.2.3
11.3.2.4
Creating a BPEL process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a BPEL project and modeling a BPEL process . . . . . . . . . . . . . . . . . . . . . . .
Deploying the BPEL process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example: Modeling a BPEL process for an openUTM service . . . . . . . . . . . . . . . .
Creating a WSDL file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generated schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
355
355
356
356
356
357
360
11.4
11.4.1
11.4.2
11.4.3
11.4.3.1
11.4.3.2
BPEL WSDL generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting and exiting the BPEL WSDL generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Online Help system for the BPEL WSDL generator . . . . . . . . . . . . . . . . . . . . . . . . . . .
Functions of the BPEL WSDL generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a WSDL file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing, modifying and removing WDSL instances . . . . . . . . . . . . . . . . . . . . . . . .
365
365
366
366
366
368
12
High availability and scalability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
12.1
12.1.1
Shared memory of the proxy container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Adapting the shared memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
12.2
12.2.1
12.2.2
Number of proxy container processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Displaying the workload of processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Setting the number of processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
12.3
Page pool area and cache of the proxy container . . . . . . . . . . . . . . . . . . . . . . . . . . 375
12.4
Number of parallel connections to the EIS partner . . . . . . . . . . . . . . . . . . . . . . . . . 376
12.5
12.5.1
12.5.2
Asynchronous processing in the proxy container . . . . . . . . . . . . . . . . . . . . . . . . . 378
Duration of asynchronous requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Inbound communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
12.6
OSI-SCRATCH-AREA in the proxy container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
12.7
Number of semaphores in the proxy container . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
BeanConnect V2.1
11
Contents
13
Logging, diagnostics and troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
13.1
13.1.1
13.1.1.1
13.1.1.2
13.1.1.3
Logging with Log4j . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Basic principles of Log4j . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Loggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Appenders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How the rolling file appender works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13.2
Logging with JDK logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
13.3
13.3.1
13.3.1.1
13.3.1.2
13.3.2
13.3.3
13.3.4
13.3.5
Configuring logging with Log4j . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring logging for BeanConnect resource adapter and proxy . . . . . . . . . . . . . . .
Configuring loggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring appenders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Editing the Log4j configuration file using the BeanConnect Management Console . . .
Configuring the BeanConnect Management Console as a Log4j socket reader . . . . .
Displaying the logging events in the BeanConnect Management Console . . . . . . . . .
Display the Log4j logging file using the BeanConnect Management Console . . . . . . .
13.4
LogWriter for connection factories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
13.5
13.5.1
13.5.2
13.5.3
Diagnosis of the BeanConnect resource adapter . . . . . . . . . . . . . . . . . . . . . . . . . .
Overview of logging in the BeanConnect resource adapter . . . . . . . . . . . . . . . . . . . . .
Predefined logging configuration of a resource adapter . . . . . . . . . . . . . . . . . . . . . . .
Logging of user interface calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
403
403
405
411
13.6
13.6.1
13.6.2
13.6.2.1
13.6.2.2
13.6.2.3
13.6.2.4
13.6.3
13.6.3.1
13.6.3.2
13.6.3.3
Diagnosis of the BeanConnect proxy container . . . . . . . . . . . . . . . . . . . . . . . . . . .
Predefined logging configuration of a proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Log files of the BeanConnect proxy container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
stdout/stderr log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
System log file SYSLOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dumps and diagnostic dumps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application log under Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Traces of the BeanConnect proxy container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OSS trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BCAM trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CMX trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
412
412
415
415
416
417
417
418
418
419
420
13.7
Diagnosis of the BeanConnect Management Console . . . . . . . . . . . . . . . . . . . . . . 422
13.8
Diagnosing the BeanConnect tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
13.9
13.9.1
13.9.1.1
13.9.1.2
13.9.2
Diagnosis of the openUTM-LU62 Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Traces and logs of the openUTM-LU62 Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Activate/deactivate traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Evaluating traces and logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Diagnosis information for the openUTM-LU62 Gateway . . . . . . . . . . . . . . . . . . . . . . .
12
384
384
384
386
387
390
390
391
392
393
394
396
399
424
424
424
425
427
BeanConnect V2.1
Dokuschablonen für DARB XML in FSC-Layout Version 1.0 für FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2005
Juni 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicsotoc.fm
Contents
13.10
13.10.1
Diagnosis of SNAP-IX for Solaris systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Diagnosis with the Management Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
13.11
13.11.1
Diagnosis of the IBM Communications Server for Linux . . . . . . . . . . . . . . . . . . . . 431
Diagnosis with the Management Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
13.12
13.12.1
Diagnosis of the IBM Communications Server for Windows systems . . . . . . . . . 433
Diagnosis with the Management Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
13.13
Collecting diagnostic information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
13.14
13.14.1
13.14.2
13.14.2.1
13.14.2.2
13.14.2.3
13.14.2.4
Error messages of the BeanConnect proxy container . . . . . . . . . . . . . . . . . . . . . .
Configuration error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Runtime error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Types of messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
K messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
P messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
U messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
435
435
436
436
438
457
463
13.15
13.15.1
13.15.2
13.15.3
13.15.4
13.15.5
Error messages of the openUTM-LU62 Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . .
openUTM-LU62 Gateway error messages on start-up . . . . . . . . . . . . . . . . . . . . . . . . .
openUTM-LU62 Gateway error messages at runtime . . . . . . . . . . . . . . . . . . . . . . . . .
openUTM-LU62 Gateway error messages on status queries . . . . . . . . . . . . . . . . . . . .
openUTM-LU62 Gateway error messages during administration . . . . . . . . . . . . . . . . .
openUTM-LU62 Gateway error messages during configuration . . . . . . . . . . . . . . . . .
467
467
468
477
478
479
13.16
13.16.1
13.16.2
Error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
Error codes during file processing (DMS error codes) . . . . . . . . . . . . . . . . . . . . . . . . . 480
System error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
14
Cobol2Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
14.1
14.1.1
14.1.2
Mapping COBOL data types to Java classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
14.2
14.2.1
14.2.1.1
14.2.1.2
14.2.1.3
14.2.1.4
14.2.1.5
14.2.1.6
Converting COBOL data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating an XML description for a COBOL program in BS2000 . . . . . . . . . . . . . . . . . .
Transferring the LMS library to BS2000/OSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Converting the data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
D.XMLPROG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
D.XMLCOPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generated files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BeanConnect V2.1
488
488
488
489
489
490
491
491
13
Contents
14.2.2
14.2.2.1
14.2.2.2
14.2.2.3
Generating Java classes on UNIX or Windows systems . . . . . . . . . . . . . . . . . . . . . . .
Generating Java classes with Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generating Java classes without Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Replacing the XSLT processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
492
492
496
497
14.3
14.3.1
14.3.2
14.3.3
14.3.3.1
14.3.3.2
14.3.3.3
14.3.3.4
14.3.4
14.3.5
Programming reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Type assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Naming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing COBOL fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Writing a data field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reading a data field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Replacement data type PicU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting and reading the data for the entire structure (for sending and receiving) . .
Java/EBCDIC conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Formatted mode support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
498
498
500
501
501
502
502
503
504
504
14.4
14.4.1
14.4.2
14.4.3
14.4.4
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
COBOL example program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating the XML description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generating the Java classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Use of the generated classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
505
505
506
507
508
14.5
Error messages and error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
List of Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
List of Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
14
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k01
June 8, 2009 7:06 pm
1 Preface
The BeanConnect adapter family is part of the openSEAS product range (open Suite for
Enterprise Application Server). The BeanConnect adapters implement the link between
classical transaction monitors and modern application servers, thus allowing legacy applications to be efficiently integrated into modern Java applications.
This manual describes the product BeanConnect. BeanConnect provides a JCA 1.5
compliant adapter connecting openUTM and CICS applications to applications based on
J2EE, e.g. the Oracle Application Server. In this document, the EIS (Enterprise Information
System) is understood to be the openUTM or CICS application.
BeanConnect supports different communication directions and models. BeanConnect
allows outbound and inbound communication, transactional and non-transactional communication as well as dialog and asynchronous communication.
Dokuschablonen Version 5.71 fкr FrameMaker ab Version 5.5.6 vom 23.03.2004
© cognitas GmbH 2001-20
BeanConnect components
BeanConnect consists of the following components:
●
The BeanConnect resource adapter implements the JCA 1.5 interfaces. Being a
compliant JCA adapter, it is deployed in the application server and hence runs within
the application server.
●
The BeanConnect proxy provides the functionality of a protocol converter as well as
functions for transaction control and transaction processing. It can be seen as an intelligent gateway. It communicates with the resource adapter running within the application server on the one hand and with the EIS on the other hand.
●
The BeanConnect Management Console (MC) is a Java GUI used for configuration
and administration of BeanConnect proxies. It can manage multiple proxies running on
the same system or on other systems.
●
The BeanConnect tools are tools which you require in many BeanConnect applications. They include Cobol2Java, the MC-CmdHandler and the BPEL WSDL Generator.
BeanConnect V2.1
15
Structure of the BeanConnect documentation
Preface
1.1 Target group
This manual is intended for the following target groups:
●
BeanConnect administrators
●
Administrators of an application server, such as Oracle Application Server/OC4J
●
Deployers
●
Developers of Enterprise Java Beans (EJB)
●
openUTM and CICS administrators
It is assumed that you are familiar with Java and with the JCA V1.5 specification from Sun
Microsystems.
1.2 Structure of the BeanConnect documentation
The documentation for BeanConnect comprises the following components:
●
The BeanConnect manual (this document).
●
The Help System for the Management Console, which provides quick and
context-sensitive support on screen when configuring and administering BeanConnect
proxies.
●
The Help System for the BPEL WSDL Generator tool component which provides quick
and context-sensitive support on screen when creating WSDL files.
●
The Javadoc of BeanConnect, which is supplied with the resource adapter JAR file
BC21A00_RA.jar and is available after the installation of the resource adapter.
Manual extension file
Last-minute changes and additions to this manual can be found in the product-specific
manual extension file (man file).
The man file is stored in the BeanConnect home directory
●
under Solaris and Linux in /docs/English/man01-en.pdf
●
under Windows in \docs\English\man01-en.pdf
I
For detailed information on openUTM, please refer to the relevant manuals.
For detailed information on the Oracle Application Server and other software
products mentioned in this manual, please refer to the relevant documentation.
16
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k01
Preface
Structure of this manual
1.3 Structure of this manual
Chapter 2, "JCA adapter integration overview" provides an overview of the Oracle concept
for the integration of adapters. It describes the features of BeanConnect and shows how
this product is embedded in the Oracle Application Server environment.
Chapter 3, "Installing BeanConnect" describes how to install, update and uninstall
BeanConnect.
Chapter 4, "Configuration in the application server" provides information for configuring
outbound and inbound communication via the OSI-TP / LU6.2 protocol and outbound
communication via the UPIC protocol. It describes deployment of the resource adapter,
deployment of an OLTP message-driven bean and deployment of Enterprise Java Beans.
Chapter 5, "BeanConnect Management Console" gives an overview of the BeanConnect
Management Console.The Management Console is used to configure and administer one
or more BeanConnect proxies.
Chapter 6, "Configuration of BeanConnect" describes the steps you must perform to
configure a BeanConnect proxy and its components using the Management Console.
Chapter 7, "Adapting the configuration in the EIS partner" describes the configuration activities that are necessary in the EIS (Enterprise Information System) to establish communication between the application server and the EIS.
Chapter 8, "Administering BeanConnect" describes the administration tasks involved in
operating the BeanConnect proxies.
Chapter 9, "Interfaces and programming" describes how to program communication
between the application server and the EIS.
Dokuschablonen Version 5.71 fкr FrameMaker ab Version 5.5.6 vom 23.03.2004
© cognitas GmbH 2001-20
Chapter 10, "Encoding and national language support" describes code conversion between
the encoding used in the EIS partner and Unicode. Additionally, this chapter provides information on national language support for message output.
Chapter 11, "BPEL support" describes how the BeanConnect Adapter can be used as a
partner link in a BPEL process within an Oracle BPEL environment and how the PBEL
WSDL Generator is used
Chapter 12, "High availability and scalability" describes the modifications which could be
necessary in the configuration of BeanConnect for heavy load operations.
Chapter 13, "Logging, diagnostics and troubleshooting" describes the variety of diagnosis
utilities and trace functions.
Chapter 14, "Cobol2Java" describes the integration of BS2000/OSD COBOL applications
and BeanConnect clients using Cobol2Java for mapping and converting COBOL data types
to Java classes.
BeanConnect V2.1
17
Changes compared to the predecessor version
Preface
1.4 Changes compared to the predecessor version
BeanConnect V2.1 contains extensive changes compared to BeanConnect V2.0. The most
important changes are listed below. For a complete description – in particular concerning
the software configuration – please refer to the Release Notice:
●
Fusion of the BeanConnect variants for openUTM and CICS.
There is a joint manual which applies to EIS partners of openUTM and CICS types. In
the manual, these two types are simply referred to as openUTM partners and CICS
partners.
There is now only one resource adapter and one BeanConnect proxy inclusive of the
Management Console which permit communications with EIS partners of openUTM
type and communications with EIS partners of CICS type. The two partner types are
configured using a common interface in the Management Console.
In addition, it is possible to configure a proxy for simultaneous communication with
openUTM partners and CICS partners.
In all cases, it is necessary to obtain the corresponding license.
●
Multiple resource adapter mode
A BeanConnect proxy is able to communicate with up to 32 resource adapters. These
resource adapters can run in different application servers. Multiple resource adapter
mode is possible for both outbound and inbound communications.
●
Cluster operation
BeanConnect makes it possible not only to operate multiple BeanConnect resource
adapters in an application server cluster but also to operate multiple BeanConnect
proxies as a proxy cluster. In this case, m:n relationships are possible between the
BeanConnect resource adapter instances in the application server cluster and the
proxy instances in the BeanConnect proxy cluster. All the variants are administered via
the Management Console.
●
BPEL support
BeanConnect provides an interface to the Oracle BPEL environment, i.e. the
BeanConnect adapter can be used in an Oracle BPEL environment as a partner link in
a BPEL process.
The BPEL WSDL Generator tool is also available. This provides an easy way of generating and administering WSDL files.
●
Management Console as a JMX client
The Management Console can be configured as a JMX client and is therefore able to
display output from a JMX server and evaluate this output on a statistical basis.
18
BeanConnect V2.1
Changes compared to the predecessor version
●
Logging in the resource adapter
In the resource adapter, it is possible to use JDK logging in addition to log4j which is
used by default.
The resource adapter can perform system logging which can be used to recover transactions.
In addition, the resource adapter can write logging output to the application server's
LogWriter.
●
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k01
Preface
Possibility of administering resource adapters via separate MC-CmdHandler
The resource adapter can be administered via a separately installed MC-CmdHandler.
It is no longer necessary to install the complete proxy there.
●
Communication Service (CICS partner) on a remote host
The communication services for communications with CICS partners can run on a host
other than the proxy host and can be administered via an MC-CmdHandler which is
installed there.
●
Extension for inbound communication
In the case of inbound communication, multiple inbound services can be specified per
message endpoint. In addition, a separate code conversion can be set for an inbound
service.
Moreover, the transaction timer and the reply timer can be set separately.
●
XATMI partners
It is also possible to communicate with EIS partners which use the XATMI interface and
its paradigms.
Configuration wizards
The Management Console provides configuration wizards to simplify the configuration
tasks.
●
Installation of resource adapters and tools
The resource adapter and the BeanConnect tools MC-CmdHandler, Cobol2Java and
BPEL WSDL Generator are supplied and installed separately. By default, installation is
performed using the IzPack tool.
Dokuschablonen Version 5.71 fкr FrameMaker ab Version 5.5.6 vom 23.03.2004
© cognitas GmbH 2001-20
●
BeanConnect V2.1
19
Changes compared to the predecessor version
●
20
Preface
Other changes
–
All error messages to the EIS partner during inbound communication start with the
prefix BCSYSEX.
–
Cobol2Java supports the National data type and offers improved handling of
numerical fields (the NumberFormatException has been removed) as well as of
identically named fields in substructures.
–
An availability check is possible for both EIS partners and resource adapters. When
running the check, different settings can be used for individual EIS partners and
individual resource adapters.
–
BeanConnect provides a "utmhostname" file which makes it possible, for example,
to use long host names (longer than 8 characters).
–
The stdout/stderr files are created independently of their generation time and can
be switched during operation.
–
The possible settings for the openUTM partner's ACCESS POINT and TSEL format
have been improved to facilitate communications with openUTM partners.
–
The possible settings for communications with CICS partners have been extended
and some of the default settings have been changed in order to ensure the unique
identification of proxies and CICS partners.
–
The redeployment of the proxy outbound connector bean can be activated manually
via the Management Console.
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k01
Preface
Notes on third-party products and literature
1.5 Notes on third-party products and literature
This manual refers to the following and other third-party products which can be used in
combination with BeanConnect:
●
Oracle Application Server and OC4J
●
Oracle JDeveloper
●
Oracle BPEL Process Manager
●
IBM Communications Server for Windows systems and IBM Communications Server
for Linux systems
●
SNAP-IX from Data Connection Ltd's for Solaris systems
●
IBM's CICS (Customer Information Control System)
Dokuschablonen Version 5.71 fкr FrameMaker ab Version 5.5.6 vom 23.03.2004
© cognitas GmbH 2001-20
In some cases, this manual makes concrete reference to parameters which have to be
specified in the Oracle Application Server. Oracle Application Server 10.1.3.3 is a prerequisite for the current description, i.e. the specifications apply to precisely this version. If
another version is used then different specifications may be required. For details, refer to
the relevant Oracle documentation.
BeanConnect V2.1
21
Notational conventions
Preface
1.6 Notational conventions
This documentation uses the following notational conventions:
Convention
.
.
.
Meaning
Vertical ellipsis points in an example mean that information not
directly related to the example has been omitted.
...
Horizontal ellipsis points in statements or commands mean that
parts of the statement or command not directly related to the
example have been omitted.
boldface text
Boldface type in text indicates all user interface items (menu items,
field names, options, etc.).
typewriter font
Typewriter font indicates input for the system, system output and file
names.
<>
Angle brackets enclose names which the user must supply.
Angle brackets indicate XML statements in the examples with XML.
22
[]
Square brackets enclose optional clauses from which you can
choose one or none.
{}
Braces enclose alternative clauses from which you must choose
exactly one.
|
A vertical line separates the alternatives or optional clauses.
I
This symbol indicates important notes and further information.
V
This symbol indicates a warning.
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k02
June 8, 2009 7:06 pm
2 JCA adapter integration overview
This document describes the product BeanConnect. BeanConnect provides a JCA 1.5
compliant adapter connecting openUTM applications (Universal Transaction Monitor) and
CICS applications (Customer Information Control System) to applications based on J2EE,
for example the Oracle Application Server.
I
For detailed information on the Oracle Application Server and
other software products mentioned in this manual, please refer
to the relevant documentation.
This chapter provides an overview of JCA adapter integration in a J2EE application server
environment. JCA is the 2EETM Connector Architecture specification from
Sun MicrosystemsTM.
●
The JCA adapter
●
BeanConnect architecture
●
BeanConnect as a JCA-compliant resource adapter
●
BeanConnect in cluster operation
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
The chapter describes the features of BeanConnect and shows how this product is
embedded in the Oracle Application Server environment. In detail this chapter contains the
following information:
BeanConnect V2.1
23
The JCA adapter
JCA adapter integration overview
2.1 The JCA adapter
JCA from Sun MicrosystemsTM defines standard Java interfaces for simplifying the
integration of applications with an EIS.
2.1.1 JCA adapter integration
A resource adapter is specific to the Enterprise Information System (EIS) for which it was
developed. It provides the system-level operations needed to communicate and operate
with the EIS. A resource adapter which supports the JCA interfaces can be used with any
application server which also supports these interfaces. The resource adapter reveals its
capabilities to the application server through a JCA-defined API. Using the defined API, the
application server can effectively incorporate the services of the resource adapter into its
operations while isolating the applications themselves from the underlying implementation
of the EIS. Important requirements for effective and scalable integration with EIS systems
are services such as.
●
connection management and pooling
●
transaction management to support global transactions, i.e. transactions which involve
both the application server and EIS.
●
logging and tracing
●
and a security framework enabling both container-managed and bean-managed
sign-on.
2.1.2 JCA 1.5 contracts
All contracts of the JCA 1.5 specification are supported:
●
Connection management contract
The connection management contract enables application components to connect to
an EIS and to exploit any connection pooling provided by the application server.
●
Transaction management contract
The transaction management contract enables an application server to use a transaction manager to manage transactions across multiple resource managers.
●
Security management contract
The security management contract provides authentication, authorization, and secure
communication between the J2EE server and the EIS.
24
BeanConnect V2.1
●
The JCA adapter
Lifecycle management contract
The lifecycle management contract enables the application server to manage the
lifecycle, i.e. the startup and shutdown functionality, of the resource adapter.
●
Work management contract
The work management contract enables the resource adapter to carry out work by
submitting it to an application server for execution. Since the application server does the
work for the resource adapter, the resource adapter need not worry about thread
management. Instead, the application server manages this aspect efficiently and can
use thread pooling if necessary. Although the work management contract is not
required (the resource adapter can choose to manage its own thread for work), it is
definitely recommended.
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k02
JCA adapter integration overview
●
Message inflow contract
The message inflow contract allows a resource adapter to synchronously or asynchronously deliver messages to endpoints in the application server, irrespective of message
style, semantics, and infrastructure.
●
Transaction inflow contract
The transaction inflow contract allows a resource adapter to propagate an imported
transaction to an application server. It also makes it possible to transfer the termination
of a transaction as well as calls initiated by an EIS.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
●
Common Client Interface (CCI)
The CCI describes a standard API client and is primarily intended to meet the requirements relating to the development of tools for application development and EAI frameworks (Enterprise Application Integration). The CCI possesses limited functionality
compared to the BeanConnect-specific API
Please refer to the Oracle Application Server – OC4J documentation for details on the
services provided by the OC4J container.
You can also find more detailed information in the JCA 1.5 specification.
BeanConnect V2.1
25
The JCA adapter
JCA adapter integration overview
2.1.3 SOA architecture
The JCA adapter supports the SOA concept (Service-Oriented Architecture).
SOA is a concept for a system architecture in which functions are implemented in the form
of reusable, technically independent, loosely coupled services. Services can be called
independently of the underlying implementations via interfaces whose specifications may
be public and therefore reliable. Service interaction is performed via a specially provided
communication infrastructure.
Using BeanConnect, it is possible to make components of openUTM and CICS applications
available as services. At the same time, openUTM and CICS applications are able to
address services in the application server. Furthermore, thanks to the Oracle SOA Suite
and BPEL Process Manager (PM), the tool-based development of complex SOA structures
is also possible.
I
Further information can be found, for example, at
http://en.wikipedia.org/wiki/Service-oriented_architecture
BPEL support
BeanConnect supports the Oracle BPEL Process Manager which is a component of the
Oracle Fusion Middleware family of products. The BPEL Process Manager allows enterprises to develop instrumentalized IT implementations of their business processes. This
means that existing services, which are usually present in the form of Web services, are
used as modules and can be combined with one another. This permits the very rapid,
standardized construction of the processes at the IT level where they are then implemented
– an optimum prerequisite for the development of a service-oriented architecture.
For further details on BPEL support in BeanConnect, see Chapter 11, "BPEL support".
2.1.4 JCA adapter integration in Oracle AS / OC4J
Oracle Containers for J2EE (OC4J) represent the core Oracle Application Server runtime
component. OC4J is compatible with J2EE-1.4 and runs on the standard J2SE distributions.
OC4J provides a complete J2EE 1.4-compliant environment. OC4J stand-alone is for use
in development environments and in small-to-medium scale production environments.
OC4J provides all the containers, APIs, and services that J2EE specifies.
OC4J is written entirely in Java and executes on the Java Virtual Machine (JVM) of the
standard Java Development Kit (JDK). OC4J can run on your operating system with the
standard JDK available.
26
BeanConnect V2.1
The JCA adapter
The JCA 1.5 resource adapters are easily deployed within the OC4J container or Oracle
Applications Server.
Figure 1: OC4J – J2EE Connection Architecture
OC4J
J2EE application
component
Application
contract
System contracts
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k02
JCA adapter integration overview
Resource
adapter
Network
Enterprise
Information
System
(Quality of service)
The application components and the resource adapter are deployed using deployment
descriptors which make it possible to integrate the resource adapter and the application
components in the application server:
●
Standard deployment descriptor ejb-jar.xml for application component in accordance with the J2EE specification.
●
Standard deployment descriptor ra.xml for the resource adapter.
●
Application server-specific deployment descriptors oc4j-ra.xml for the resource
adapter and orion-ejb-jar.xml for the application component.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
For a detailed description of these deployment descriptors, see Section 4.1.1, "Configuration files in the application server".
BeanConnect V2.1
27
BeanConnect architecture
JCA adapter integration overview
2.2 BeanConnect architecture
BeanConnect makes it possible to communicate with both openUTM and CICS Enterprise
Information Systems (abbreviated to EIS partners). This chapter describes the components
that are required for these partners as well as the functions that these components possess.
2.2.1 BeanConnect components
BeanConnect consists of the following components:
●
The BeanConnect resource adapter implements the JCA 1.5 interfaces. Being a
compliant JCA adapter, it is deployed in the application server and runs within the application server.
●
The BeanConnect proxy provides the functionality of a protocol converter as well as
functions for transaction control. It can be seen as an intelligent gateway. It communicates with the resource adapter running within the application server on the one hand
and with the EIS on the other hand. It can be located on the same machine as the
resource adapter or on a different one.
●
The BeanConnect Management Console (MC) is a Java -based GUI used, for
example, for the configuration and administration of proxies. It can manage multiple
proxies running on the same host as the Management Console or on remote hosts. The
Management Console is not required for the configuration of outbound connections
using the UPIC protocol
●
The BeanConnect tools can be installed and used independently of the proxy
container. These tools include the Management Console Command Handler
(MC-CmdHandler), Cobol2Java and the BPEL WSDL Generator.
Figure 2: BeanConnect components
Application server
OSI-TP
BeanConnect
resource adapter
BeanConnect proxy
LU6.2
Enterprise
Information
System
BeanConnect Management Console
28
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k02
JCA adapter integration overview
BeanConnect architecture
The BeanConnect proxy uses the appropriate protocol depending on the type of EIS
partner, i.e. OSI-TP for openUTM partners or LU6.2 for CICS partners.
Figure 3: BeanConnect components for outbound communication with openUTM partners via UPIC protocol
Application server
UPIC protocol
Enterprise
Information
System
June 8, 2009 7:06 pm
BeanConnect
resource adapter
In more complex scenarios it may be necessary to connect one or more application servers
with several EISs. In this case, notice the following rules:
BeanConnect may only be deployed once in an application server instance
●
One resource adapter communicates with exactly one proxy.
●
A proxy can communicate either with a single resource adapter (Section 2.2.2,
"Standard operation with one resource adapter and one proxy") or with multiple
resource adapters (Section 2.2.3, "Multiple resource adapter mode" or Section 2.4,
"BeanConnect in cluster operation")
●
One proxy can communicate with multiple EIS partners.
●
One Management Console can handle multiple proxies (configuration and administration).
In addition, when BeanConnect is used in a cluster configuration, it can be operated with
multiple resource adapters and multiple proxies, see Section 2.4, "BeanConnect in cluster
operation".
© cognitas GmbH 2001-2
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
●
2.2.1.1
BeanConnect resource adapter
BeanConnect is a connector resource adapter in compliance with the JCA 1.5 specification
from Sun MicrosystemsTM. It supplies standardized connectivity of openUTM and CICS
applications to applications running in an application server based on the J2EE architecture
and plays a fundamental role in the integration and connectivity between an EIS and an
application server. It serves as the point of contact between application components, application servers and Enterprise Information Systems.
The resource adapter is provided as a RAR archive. This archive must be deployed in the
application server by means of the application server.
Detailed information how to configure the resource adapter can be found in Chapter 4,
"Configuration in the application server".
BeanConnect V2.1
29
BeanConnect architecture
2.2.1.2
JCA adapter integration overview
BeanConnect proxy
The proxy is the connecting link between the resource adapter on one side and the EIS on
the other side.
It serves as container for configuration properties of the communication partners and holds
all information on services, communication endpoints and message endpoints.
The proxy is responsible for transporting the messages and ensures that they are assigned
to the corresponding partners and services. It provides functions for transactional security
and for verification of access rights (user ID and password) of openUTM or CICS application
requests. The proxy stores asynchronous messages (inbound and outbound) until they are
sent to the EIS partner or the message endpoint application.
The bulk of the BeanConnect configuration is done by configuring the proxy.
The proxy contains the proxy container which is based on the openUTM transaction monitor
openUTM. You can use the Management Console to configure the proxy in three different
ways
●
As an openUTM proxy which communicates exclusively with EIS partners of type
openUTM.
An openUTM proxy consists only of the proxy container.
●
As a CICS proxy which communicates exclusively with EIS partners of type CICS.
A CICS proxy requires additional components to communicate with CICS applications.
A separate license is required for CICS communication.
●
As a combined proxy
A combined proxy communicates both with EIS partners of type openUTM and with EIS
partners of type CICS. A further, separate license is required for CICS communication.
Components of a CICS proxy
For communications with CICS applications, the proxy additionally consists of the following
internal components:
●
the openUTM-LU62 Gateway, implementing the LU6.2 protocol stack for interconnection with EIS partners supporting the SNA protocol LU6.2. Both transactional and
non-transactional connections with CICS applications are supported.
●
Communication service:
This is a third-party product that implements the SNA stack
This is Data Connection's SNAP-IX for Solaris Systems or IBM's Communications
Server for Linux and Windows. These products are not included in the BeanConnect
scope of delivery.
30
BeanConnect V2.1
BeanConnect architecture
The following figure shows the components of the proxy for communications with CICS
applications:
Figure 4: BeanConnect proxy components of a CICS proxy
BeanConnect proxy
Communication
Service
SNAP-IX
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k02
JCA adapter integration overview
Proxy
container
openUTM
LU62
Gateway
Solaris systems
Communications
Server
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Linux, Windows
systems
The proxy and all the proxy components are managed and administered using the
Management Console. The openUTM-LU62 Gateway and communication service proxy
components may run either on the same computer as the proxy container or together on a
separate computer as required. In the latter case, at least one MC-CmdHandler handler
must be explicitly installed on the remote machine to permit the administration of the
openUTM-LU62 Gateway and the communication service, see also Section 2.2.1.4,
"BeanConnect tools". Please note that the communication service must be installed under
a user ID which has SNA authorization.
I
The BeanConnect proxy is used for outbound communication
via the OSI-TP and LU6.2 protocols as well as for inbound
communication.
In the case of outbound communication via the UPIC protocol.
(openUTM), the proxy is not used.
BeanConnect V2.1
31
BeanConnect architecture
2.2.1.3
JCA adapter integration overview
BeanConnect Management Console
The Management Console supports configuration and administration of the proxy and
proxy components. It offers a Java GUI that facilitates the necessary configuration steps.
The Management Console is able to work with more than one proxy, local or remote.
●
Local means that the proxy is located on the same computer as the Management
Console and that the proxy is installed under the same user ID, or that the access rights
to the user ID under which the proxy is installed have been set accordingly.
●
Remote means that the proxy is installed on a different computer from the Management
Console or that the proxy is installed on the same computer but under a different user
ID which the Management Console is not able to access.
Remote access is carried out with the Management Console Command Handler
(MC-CmdHandler). The MC-CmdHandler is a stand-alone Java program which allows the
Management Console to manage remote proxies.
The administrator provides the Management Console with all necessary information for the
proxy configuration. The following information can be specified:
●
General information on the proxy or the proxy cluster
●
Management of the properties of resource adapters and access to the resource
adapters' deployment descriptors
●
Description of the EIS partners
●
The services and the communication endpoints for outbound communication (see
"Outbound communication" on page 38)
●
The Services and the message endpoints for inbound communication (see "Inbound
communication" on page 38)
●
Connection to the JMX server for access to MBeans and the information and functions
which these provide
Additionally for CICS partners:
●
Connection to the openUTM-LU62 Gateway
●
Connection between the Communication Service and the EIS partner
The configuration data is stored by the Management Console so that it is available in subsequent Management Console sessions and can be modified or completed. The Management
Console creates the configuration files to be used by the proxy, the proxy components and
the EIS.
32
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k02
JCA adapter integration overview
2.2.1.4
BeanConnect architecture
BeanConnect tools
BeanConnect provides certain components in the form of tools which can be installed and
used independently of the proxy container. These tools are not dependent on the type of
EIS communication partner.
BeanConnect provides the following tools:
●
MC-CmdHandler (Management Console Command Handler)
Using separately installed MC-CmdHandlers, it is possible, for example, to administer
remote resource adapters or the proxy components required for CICS partners via the
Management Console without having to install the proxy container.
●
Cobol2Java
Cobol2Java permits the object-oriented mapping of COBOL data structures to Java
classes.
●
BPEL WSDL Generator
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
You use the BPEL WSDL Generator to create WSDL files and administer these in the
form of WSDL instances. The WSDL files are configuration files that are required to
provide BPEL support in BeanConnect.
BeanConnect V2.1
33
BeanConnect architecture
JCA adapter integration overview
2.2.2 Standard operation with one resource adapter and one proxy
During standard operation, one proxy works together with precisely one resource adapter.
However, it is possible to address multiple EIS partners.
Figure 5: Relationships between the BeanConnect components in standard operation and without a cluster
Application
server
instance
BeanConnect
Resource
adapter
1:1
Enterprise
Information
System
BeanConnect
proxy
1:n
1:1
1:1
BeanConnect Management Console
With BeanConnect V2.1, it is possible to deploy a BeanConnect in an application server
instance.
34
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k02
JCA adapter integration overview
BeanConnect architecture
2.2.3 Multiple resource adapter mode
In multiple resource adapter mode, one proxy works together with multiple resource
adapters which act independently of one another and run on different application server
instances. One and the same BeanConnect resource adapter cannot run multiple times on
the same application server instance.
I
Cluster operation and multiple resource adapter mode are
mutually exclusive.
Figure 6: BeanConnect components in multiple resource adapter mode with 2 resource adapters and one proxy
Application
server
instance B
BeanConnect
Resource
Adapter 2
Enterprise
Information
System
BeanConnect
proxy
1:n
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Application
server
instance A
BeanConnect
Resource
Adapter 1
BeanConnect Management Console
A proxy can handle up to 32 resource adapters on different application server instances.
Like standard operation, multiple resource adapter mode is configured and administered
via the Management Console.
BeanConnect V2.1
35
BeanConnect architecture
JCA adapter integration overview
2.2.4 Platform support
The following platforms are supported by the components of BeanConnect:
●
The BeanConnect resource adapter is available for the following operating systems:
Solaris systems / Linux systems / Windows systems / HP-UX / HP Tru64 / IBM AIX
●
The BeanConnect proxy is available for the following operating systems:
Solaris systems / Linux systems / Windows systems
●
The BeanConnect Management Console is available for the following operating
systems:
Solaris systems / Linux systems / Windows systems
For details please refer to the release notice delivered with the product.
Software prerequisites for CICS partners
The following software is required to allow SNA data flows to be transmitted over a TCP/IP
network:
I
●
On Solaris systems:
–
●
●
This software can run on the proxy host or on another computer
as required.
SNAP-IX from Data Connection Ltd.
On Linux systems:
–
IBM Communications Server
–
Linux Streams
On Windows systems:
–
IBM Communications Server
EIS support with openUTM partners
BeanConnect can communicate with openUTM applications on all openUTM platforms.
EIS support with CICS partners
BeanConnect can communicate with CICS applications on a z/OS mainframe.
BeanConnect does not change the EIS configuration itself. It only creates configuration files
to be used by the administrator for adapting the EIS configuration.
36
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k02
JCA adapter integration overview
BeanConnect as a JCA-compliant resource adapter
2.3 BeanConnect as a JCA-compliant resource adapter
BeanConnect supports different communication directions and models. BeanConnect
allows outbound and inbound communication, dialog and asynchronous communication as
well as transactional and non-transactional communication.
2.3.1 Outbound and inbound communication
During outbound communication, an EJB deployed in the application server communicates with a partner application on the EIS side of the connection.
During inbound communication, an EIS sends messages to a message-driven bean in a
J2EE application server.
With openUTM partners BeanConnect supports the following communication variants:
●
bidirectional (outbound and inbound) and transactional or non-transactional communication to OLTP applications (On-Line Transaction Processing) via the OSI-TP protocol.
●
unidirectional (outbound only) and non-transactional access to openUTM applications
via the UPIC protocol. This access is performed without the involvement of proxies.
●
Non-transactional, asynchronous inbound communication via openUTM-Socket and
the RFC1006 protocol (see Section 2.3.1.2, "Inbound communication").
With CICS partners BeanConnect supports the following communication variant:
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
●
bidirectional (outbound and inbound) and transactional or non-transactional access
to/from OLTP (On-Line Transaction Processing) applications via the LU6.2 protocol.
LU6.2 is a Systems Network Architecture (SNA) protocol that supports both
system-to-system communication and system-to-device communication.
In addition, BeanConnect supports non-transactional inbound communication via the proxy
with any application which supports one of the protocols: UPIC, openUTM-Socket or
RFC1006 (see Section 2.3.1.2, "Inbound communication").
BeanConnect V2.1
37
BeanConnect as a JCA-compliant resource adapter
2.3.1.1
JCA adapter integration overview
Outbound communication
With outbound communication, an EJB deployed in the application server initiates communication with a partner application on EIS side. Outbound communication can take place as
both dialog and asynchronous communication.
Figure 7: Outbound communication for openUTM partners
Application server
EJB
BeanConnect
Resource
Adapter
BeanConnect
proxy
OSI-TP
connection
UPIC
EJB
openUTM
OLTP
application
openUTM
application
connection
Figure 8: Outbound communication for CICS partners
Application server
EJB
BeanConnect
Resource
Adapter
BeanConnect
proxy
LU6.2
connection
CICS
application
EJB
2.3.1.2
Inbound communication
With inbound communication, an EIS sends messages to a message-driven bean application in a J2EE application server. The message-driven bean must implement a
resource-adapter-specific message listener interface. BeanConnect supports the Service
Endpoint Message Listener interface which forms part of the CCI (Common Client
Interface) defined in the JCA specification and, additionally, its own message listener
interface for dialog and asynchronous communication (see Section 2.3.4, "Interfaces" .
38
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k02
JCA adapter integration overview
BeanConnect as a JCA-compliant resource adapter
BeanConnect supports the following communication types for inbound communication:
●
●
EIS is an openUTM application
–
transactional and non-transactional communication via the OSI-TP protocol (dialog
and asynchronous)
–
non-transactional communication via the openUTM socket protocol or RFC1006
protocol (only asynchronous)
EIS is a CICS application
–
●
transactional and non-transactional communication via the LU6.2 protocol
(asynchronous and dialog communication)
EIS is another application
–
UPIC application: non-transactional communication via the UPIC protocol (dialog)
–
openUTM socket client or RFC1006 application: non-transactional communication
via the openUTM socket protocol or RFC1006 protocol (dialog and asynchronous)
Figure 9: Inbound communication for openUTM partners
Application server
MDB
UP
BeanConnect
Resource
Adapter
OSI-TP
BeanConnect
proxy
Soc
ket
MDB
connection
UPIC client
openUTM
OLTP application
open UTM socket/
RFC1006 client
Figure 10: Inbound communication for CICS partners
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
IC
Application server
MDB
BeanConnect
Resource
Adapter
BeanConnect
proxy
LU6.2
connection
CICS
application
MDB
BeanConnect V2.1
39
BeanConnect as a JCA-compliant resource adapter
JCA adapter integration overview
2.3.2 Dialog and asynchronous communication
BeanConnect supports dialog as well as asynchronous communication for both inbound
and outbound communication.
2.3.2.1
Dialog communication
In the case of dialog communication, one communication partner waits for a response from
the other partner before continuing processing, i.e.:
2.3.2.2
●
In the case of outbound dialog communication, the application (EJB) in the application
server waits for the response from the EIS partner.
●
In the case of inbound dialog communication, the EIS partner waits for the response
from the message-driven bean application.
Asynchronous communication
In the case of asynchronous communication, a communication partner does not wait for a
response from the other partner, i.e.:
●
In the case of outbound asynchronous communication, the application (EJB) in the
application server sends a message to the EIS partner without expecting a response,
●
In the case of inbound asynchronous communication, the EIS partner sends a message
to the message-driven bean application without expecting a response.
2.3.3 Transactional and non-transactional communication
BeanConnect supports transactional and non-transactional communication.
Transactional communication is only possible for communication with OLTP applications via
the OSI-TP and the LU6.2 protocol.
2.3.3.1
Transactional communication
In the case of dialog communication, the processing in the remote application is included in
the global transaction. This ensures that the distributed resources are consistent at all
times, even across applications.
In the case of asynchronous communication, only transmission of the message is included
in the transaction. Asynchronous jobs are transmitted exactly once in the case of transactional communication. This means that even in the event of network malfunctions or failure
of an application, the asynchronous job is not lost, neither is the message duplicated.
40
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k02
JCA adapter integration overview
2.3.3.2
BeanConnect as a JCA-compliant resource adapter
Non-transactional communication
In the case of non-transactional communication, the processing in the remote application is
independent of the local transaction. When two independent transactions interoperate,
each application commits or rolls back its own transaction independently. In the event of
communication failure, for instance, this can lead to inconsistent data in the different applications. This kind of communication does not ensure that asynchronous jobs are transmitted only once.
2.3.4 Interfaces
BeanConnect supports both BeanConnect-specific interfaces and standard interfaces in
accordance with the JCA specification. This section presents an overview of the interfaces
for outbound and inbound communication
Detailed information on the programming interfaces can be found in Chapter 9, "Interfaces
and programming". The interfaces for BPEL support are described in Chapter 11, "BPEL
support".
Interfaces for outbound communication
During outbound communication, an EJB deployed in the application server communicates
with a partner application in the EIS system. This EJB can communicate with EIS partners
via interfaces in the following packages.
net.fsc.jca.communication
The interfaces combined in the package net.fsc.jca.communication define proprietary BeanConnect-specific communication interfaces. These support different
programming modes (like send/receive and call) and provide access to the functions
supported by the underlying communication protocol.
●
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
●
net.fsc.jca.communication.cci
The Common Client Interface (CCI) is defined in the JCA specification. It describes a
standard client API and primarily addresses the requirements of developing application
development tools and EAI frameworks (Enterprise Application Integration). Compared
with the BeanConnect-specific API, the CCI provides a restricted functional range.
BeanConnect V2.1
41
BeanConnect as a JCA-compliant resource adapter
JCA adapter integration overview
Interfaces for inbound communication
With inbound communication, an EIS can send messages to a message-driven bean application in a J2EE application server.
The message-driven bean must implement a resource-adapter-specific message listener
interface.
BeanConnect supports the following message listener interfaces:
●
net.fsc.jca.communication.AsyncOltpMessageListener
BeanConnect-specific interface for asynchronous communication
●
net.fsc.jca.communication.OltpMessageListener
BeanConnect-specific interface for dialog communication
●
javax.resource.cci.MessageListener
Common Client Interface (CCI) for dialog communication
A message-driven bean which implements one of the first two message listener interfaces
is called an OLTP message-driven bean.
42
BeanConnect V2.1
BeanConnect in cluster operation
2.4 BeanConnect in cluster operation
BeanConnect supports both clusters in the application server and proxy clusters. This
means that n instances of the resource adapter can be assigned to m proxy instances.
Cluster operation is designed to increase reliability and balance the load between the
instances.
Figure 11: BeanConnect components in cluster operation
Application server cluster
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k02
JCA adapter integration overview
Application
server
instance
BeanConnect
resource
adapter instance
Proxy cluster
Enterprise
Information
System
BeanConnect
proxy
instance
1:n
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
BeanConnect Management Console
In the case of outbound communication, a resource adapter instance is always assigned to
precisely one proxy cluster instance at any one time. If this instance fails, the resource
adapter instance searches for a new proxy cluster instance. Load balancing is performed
using the mechanisms present in the application server.
In the case of inbound communication, all the application server instances are always
assigned to a single proxy instance. The proxy container is responsible for load balancing.
The proxy cluster is configured using the Management Console. One of the proxy instances
is identified as the master instance and is used to synchronize the other proxy instances,
for example when changes are made to the configuration data.
BeanConnect V2.1
43
BeanConnect in cluster operation
44
JCA adapter integration overview
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
June 8, 2009 7:06 pm
3 Installing BeanConnect
This chapter describes how to install, update and uninstall BeanConnect.
●
Installing BeanConnect under Solaris systems
●
Installing BeanConnect under Linux systems
●
Installing BeanConnect under Windows systems
●
Installing a BeanConnect resource adapter
●
Installing the BeanConnect tools
●
Update installation for the BeanConnect proxy container and Management Console
●
Uninstalling BeanConnect
●
Uninstalling the BeanConnect resource adapter
●
Uninstalling the BeanConnect tools
I
Additional information can be found in the manual extension file
man01-en.pdf (PDF format).
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
After installation, the manual extension file can be found in the
BeanConnect home directory:
Solaris and Linux systems: /Docs/English
Windows systems: \Docs\English
BeanConnect V2.1
45
Installing BeanConnect under Solaris systems
Installing BeanConnect
3.1 Installing BeanConnect under Solaris systems
BeanConnect supports the Sun Solaris operating system (SPARC).
BeanConnect contains the following product files:
●
BeanConnect proxy
●
openUTM
●
openUTM-LU62 gateway (only for CICS partners)
●
PCMX
Installing BeanConnect involves the following steps:
1. Master installation
2. Installing the BeanConnect proxy container and the Management Console
3.1.1 Master installation
Master installation must be performed under the root user ID.
You start master installation with the following command:
pkgadd -d MASTER_BC21A00.pkg
Master installation allows you to install the following packages:
●
PCMX (Communications Manager UNIX OS)
●
openUTM
●
BeanConnect
●
openUTM-LU62 gateway (for CICS partners)
Select the package(s) that you wish to install.
I
To use BeanConnect, you must have installed all the packages
of the master installation, but you should install only those
packages that are not yet installed on your system. Please make
sure that the versions of the package are identical.
If you want to install multiple packages, you do not always have to restart the master installation package. When you start the master package, the individual packages that you can
install are listed in numerical order.
46
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
Installing BeanConnect under Solaris systems
Example 1 Installing multiple packages
You want to install the BeanConnect (package 1) and openUTM (package 4) product files.
June 8, 2009 7:06 pm
The following packages are available:
1 BC21A00
BeanConnect
(sparc) 2.1A00
2 SMAWpcmx
Communications Manager Unix OS
(sparc) 6.0A60
3 SMAWutm6s
openUTM-LU62: openUTM LU6.2 comm. (using SNAP-IX)
(sparc) 5.1A00
4 UTM53A30
openUTM:Universal Transaction Monitor
(sparc) 5.3A30
Select package(s) you wish to process (or 'all' to process all packages).
(default: all) [?,??,q]: 1 4
Packages 1 and 4 will be installed one after the other.
V
The installation operation itself runs in the background. You
must therefore wait for a short time for the termination
messages after the shell prompt has been output to determine
whether installation has been performed successfully. You
should therefore start by logging off once the messages have
been output.
3.1.1.1
You must install PCMX before installing the BeanConnect proxy container. You must not
install PCMX if the kernel CMX has already been installed.
© cognitas GmbH 2001-2
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
Installing PCMX
1. Select the PCMX (Communications Manager UNIX OS) package from the master
installation.
2. PCMX (Communications Manager UNIX OS) is installed automatically.
3.1.1.2
Installing openUTM
You must install openUTM before installing the BeanConnect proxy container.
1. Select the openUTM package from the master installation.
2. Specify the home directory in which openUTM is to be installed. Default: /opt/lib
3. Specify the base directory <basedir>. To do this, you must once again select the
directory which you specified in step two.
BeanConnect V2.1
47
Installing BeanConnect under Solaris systems
3.1.1.3
Installing BeanConnect
Installing the BeanConnect product files
You must install the BeanConnect product files before installing the BeanConnect proxy
container.
1. Select the BeanConnect package from the master installation.
2. Specify the BeanConnect installation directory in which the BeanConnect product files
are to be installed. Default: /opt/lib
3.1.1.4
Installing the openUTM-LU62 Gateway (for CICS partners)
1. Select the openUTM-LU62 gateway package from the master installation.
2. The openUTM-LU62 gateway is installed automatically.
3.1.1.5
Silent installation
In the case of the openUTM and BeanConnect subpackages, you need a so-called
<response-file> in order to respond to the questions concerning location, owner and group.
In addition, for both products you need a modified
<installation-administration-file>, in order to deactivate the security query for
root authorization.
The default file is located under /var/sadm/install/admin/default.
1. Copy the default file.
2. Specify action= nocheck.
3. Specify the file as the <installation-administration-file>
On Solaris systems, you call silent installation as follows:
pkgadd -r <response-file> -a <installation-administration-file>
-d MASTER_BC21A00.pkg
<<EOF
<Space-separated subpackage number>
EOF
Example for <response-file>:
LOC="/opt/lib"
OWNER="root"
GROUP="root"
48
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
Installing BeanConnect under Solaris systems
3.1.2 Installing the BeanConnect proxy container and the Management
Console
I
Before you can install BeanConnect, you must first install JDK,
PCMX, openUTM, openUTM-LU62 gateway (for CICS partners)
and the BeanConnect product files from the master installation.
The BeanConnect installation program can perform the following operations:
●
Installing the BeanConnect proxy container and the MC-CmdHandler
●
Installing the BeanConnect Management Console
Starting the installation procedure
After you have installed the product files, the second step is to perform a user-specific
installation of the BeanConnect components.
Log in to the system using the user ID under which BeanConnect is to run. Root or administration authorization is not required for installation.
1. Switch to the directory in which you want to install the proxy container / Management
Console.
2. Start the installation using the following command:
<BC_home>/shsc/install.BeanConnect
3. The procedure displays a menu containing the components you can install.
●
1 BeanConnect Proxy Container
This installs a BeanConnect proxy container and the MC-CmdHandler.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
The default value for <BC_home> is /opt/lib/bc21a00.
●
2 Management Console (Administration Tool)
This installs the BeanConnect Management Console.
Specify the number of the component(s) that you want to install. If you want to install
both components, enter 1 2. If you enter q, the installation procedure is terminated.
BeanConnect V2.1
49
Installing BeanConnect under Solaris systems
Installing BeanConnect
Installing the BeanConnect proxy container
The installation procedure <BC_home>/shsc/install.BeanConnect requires the
following input:
1. User base directory in which the BeanConnect proxy is to be installed
The installation procedure sets the current directory (from which the procedure was
started) as the BeanConnect user base directory <user_base_dir> in which the proxy
container is to be installed.
If you accept this directory with y, the installation procedure continues.
If you specify n, the installation procedure is aborted.
To install the proxy container in another directory, switch to this directory and start the
installation again.
2. Name of the proxy container
Specify the name of the proxy container.
The name must be unique in your system.
The name can have a maximum length of eight characters.
The following characters are permitted: A,...,Z, a,...,z, 0,...,9
Lowercase letters are converted to uppercase letters.
The default is BCCONT.
I
A subdirectory with the name of the proxy container is created
in the BeanConnect user base directory. The files are installed
in this subdirectory. The proxy container home directory is
therefore
<user_base_dir>/<proxy_cont_name>
(e.g. <user_base_dir>/BCCONT).
If you specify the name of a proxy container that is already installed, you are asked
whether you want to overwrite the proxy container (new installation) or perform an
update installation (see "Update installation for the BeanConnect proxy container and
Management Console" on page 73).
3. openUTM home directory
Specify the openUTM home directory. This environment variable is pre-assigned the
value of the environment variable UTMPATH. The installation procedure also searches
for the openUTM versions that are installed on the computer and displays them in a list
from which you can select the desired home directory.
50
BeanConnect V2.1
Installing BeanConnect under Solaris systems
If openUTM is not installed in the specified directory, the following error message is
displayed:
openUTM not found!
In this case, check the specified home directory or the installation of openUTM (see
Section 3.1.1.2, "Installing openUTM").
4. JAVA home directory
Prerequisite: JDK must already be installed on your system before you can install the
proxy.
The installation procedure asks for the name of the JAVA home directory. You have to
specify the directory explicitly. No name is suggested. You have to specify a fully
qualified directory name. The procedure then checks your input.
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
If JDK is not installed in the specified directory, the following error message is displayed:
JDK not found!
Check the specified home directory or install JDK first.
5. Acceptance
The installation procedure displays the name of the archive from which the proxy is
installed. Installation must be performed from the archive
<BC_home>/CPIO.BCCont.
The default value for <BC_home> is /opt/lib/bc21a00.
Accept this archive.
6. Port number of the proxy container
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
BeanConnect needs a range of one hundred port numbers. You are asked to enter the
port number which specifies the beginning of this range.
The range of port numbers must not be used by other proxy containers or other applications. You have to specify a different port number here.
Start Value of the Port Number Range for BeanConnect
Specify the start value of the port number range. The next hundred port numbers are
reserved for BeanConnect. Values between 1025 and 32667 are permitted for the port
number. Default: 31000.
7. Password for administration of the proxy container
Specify the password. Default: admin
8. The proxy container is installed once this dialog has been completed.
I
BeanConnect V2.1
You can repeat the installation procedure several times if you
want to install multiple proxy containers.
51
Installing BeanConnect under Solaris systems
Installing BeanConnect
Installing the Management Console
The installation procedure requires you to make the following entries:
1. User base directory in which the Management Console is to be installed
The installation procedure sets the current directory (from which the procedure was
started) as the BeanConnect user base directory <user_base_dir>.
If you accept the directory with y, the installation procedure continues. If you specify n,
the installation procedure is aborted.
2. JAVA home directory
Prerequisite: JDK must already be installed on your system before you can install the
proxy.
The installation procedure asks for the name of the JAVA home directory. You have to
specify a fully qualified directory name. The procedure then checks your input.
If JDK is not installed in the specified directory, the following error message is displayed:
JDK not found!
Check the specified home directory or install JDK first.
3. Directory for the Management Console configuration files
The configuration files are stored in a subdirectory of the BeanConnect user base
directory <user_base_dir>.
Specify the subdirectory <console_name>. Default: console
The Management Console home directory is consequently
<user_base_dir>/<console_name>.
If you specify the name of a Management Console that is already installed, you are
asked whether you want to overwrite the Management Console (new installation) or
perform an update installation (see "Update installation for the BeanConnect proxy
container and Management Console" on page 73).
4. Acceptance
The installation procedure displays the name of the archive from which the
Management Console is installed. Installation must be performed from the archive
<BC_home>/CPIO.console.
The default value for <BC_home> is /opt/lib/bc21a00.
Accept this archive.
52
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
Installing BeanConnect under Linux systems
3.2 Installing BeanConnect under Linux systems
BeanConnect supports the Linux operating system.
BeanConnect contains the following product files:
●
BeanConnect proxy
●
openUTM
●
openUTM-LU62 gateway (for CICS partners)
●
CMX
Installation of BeanConnect involves the following steps:
1. Master installation
2. Installing the BeanConnect proxy container and the Management Console
3.2.1 Master installation
Master installation must be performed under the root user ID.
You start master installation with the following command:
rpm -i MASTER_BC21A00.rpm --ignorearch --prefix=<BC_install>
Specify the desired BeanConnect installation directory for prefix=<BC_install>. If
prefix is not specified, the default BeanConnect installation directory /opt/lib/ is used.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Master installation allows you to install the following packages:
●
CMX (Communications Manager UNIX OS)
●
openUTM
●
BeanConnect
●
openUTM-LU62 gateway (for CICS partners)
Select the package(s) that you wish to install.
I
BeanConnect V2.1
To use BeanConnect, you must have installed all the packages
of the master installation, but you should install only those
packages that are not yet installed on your system. Please make
sure that the versions of the package are identical.
53
Installing BeanConnect under Linux systems
Installing BeanConnect
If you want to install multiple packages, you do not always have to restart the master installation package. When you start the master package, the individual packages that you can
install are listed in numerical order.
Example 2 Installing multiple packages
You want to install the openUTM (package 3) and BeanConnect (package 4) product files:
The following packages are available:
1 PCMX
Communications Manager LINUX
6.0A70
2 UTMLU62
gw4 openUTM-LU62: openUTM LU6.2 communication
5.1A00-04
3 UTM53A30
openUTM:Universal Transaction Monitor
5.3A30
4 BC21A00
BeanConnect
2.1A00
Select package(s) you wish to process (or 'all' to process all packages).
(default: all) [?,??,q]: 3 4
Packages 3 and 4 will be installed one after the other.
V
3.2.1.1
The installation operation itself runs in the background. You
must therefore wait for a short time for the termination
messages after the shell prompt has been output to determine
whether installation has been performed successfully. You
should therefore start by logging off once the messages have
been output.
Installing PCMX
You must install PCMX before installing the BeanConnect proxy container.
1. Select the PCMX (Communications Manager UNIX OS) package from the master
installation.
2. PCMX is installed automatically in the directory /opt/lib/.
3.2.1.2
Installing openUTM
You must install openUTM before installing the BeanConnect proxy container.
1. Select the openUTM package from the master installation.
2. openUTM is installed automatically in the directory which you specified in prefix.
54
BeanConnect V2.1
3.2.1.3
Installing BeanConnect under Linux systems
Installing the BeanConnect product files
You must install the BeanConnect product files before installing the BeanConnect proxy
container.
1. Select the BeanConnect package from the master installation.
2. The product files are installed automatically in the directory which you specified in
prefix.
3.2.1.4
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
Installing the openUTM-LU62 Gateway (for CICS partners)
1. Select the openUTM-LU62 gateway package from the master installation.
2. openUTM-LU62 gateway is installed automatically in the directory /opt/lib/.
3.2.1.5
Silent installation
You call silent installation on Linux systems in exactly the same way as the master installation. In addition, you must enter the numbers of the subpackages – separated by spaces
– in the file /response.
Please note the following:
If you do not enter anything in the/response then all the subpackages are installed.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
3.2.2 Installing the BeanConnect proxy container and the Management
Console
I
Before you can install BeanConnect, you must first install JDK,
PCMX, openUTM, openUTM-LU62 gateway (for CICS partners)
and the BeanConnect product files from the master installation.
The BeanConnect installation program can perform the following functions:
●
Installing the BeanConnect proxy container and the MC-CmdHandler
●
Installing the BeanConnect Management Console
Starting the installation procedure
After you have installed the product files, the second step is to perform a user-specific
installation of the BeanConnect components.
BeanConnect V2.1
55
Installing BeanConnect under Linux systems
I
Installing BeanConnect
The Korn shell (ksh) must be used for installation.
Log in to the system using the user ID under which BeanConnect is to run. Root or administration authorization is not required for installation.
1. Switch to the directory in which you want to install the proxy container / Management
Console.
2. Start the installation using the following command:
<BC_home>/shsc/install.BeanConnect
The default value for <BC_home> is /opt/lib/bc21a00.
3. The procedure displays a menu containing the components you can install.
●
1 BeanConnect Proxy Container
This installs a BeanConnect proxy container and the MC-CmdHandler.
●
2 Management Console (Administration Tool)
This installs the BeanConnect Management Console.
Specify the number of the component(s) that you want to install. If you want to install
both components, enter 1 2. If you enter q, the installation procedure is terminated.
Installing the BeanConnect proxy container
The installation procedure <BC_home>/shsc/install.BeanConnect requires the
following input:
1. User base directory in which the BeanConnect proxy is to be installed
The installation procedure sets the current directory (from which the procedure was
started) as the BeanConnect user base directory <user_base_dir> in which the proxy
container is to be installed.
If you accept this directory with y, the installation procedure continues.
If you specify n, the installation procedure is aborted.
To install the proxy container in another directory, switch to this directory and start the
installation again.
56
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
Installing BeanConnect under Linux systems
2. Name of the proxy container
Specify the name of the proxy container.
The name must be unique in your system.
The name can have a maximum length of eight characters.
The following characters are permitted: A,...,Z, a,...,z, 0,...,9
Lowercase letters are converted to uppercase letters.
The default is BCCONT.
I
A subdirectory with the name of the proxy container is created
in the BeanConnect user base directory. The files are installed
in this subdirectory. The proxy container home directory is
therefore
<user_base_dir>/<proxy_cont_name>
(e.g. <user_base_dir>/BCCONT).
If you specify the name of a proxy container that is already installed, you are asked
whether you want to overwrite the proxy container (new installation) or perform an
update installation (see "Update installation for the BeanConnect proxy container and
Management Console" on page 73).
3. openUTM home directory
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Specify the openUTM home directory. This environment variable is pre-assigned the
value of the environment variable UTMPATH. The installation procedure also searches
for the openUTM versions that are installed on the computer and displays them in a list
from which you can select the desired home directory.
If openUTM is not installed in the specified directory, the following error message is
displayed:
openUTM not found!
In this case, check the specified home directory or the installation of openUTM (see
Installing openUTM on page 54).
4. Java home directory
Prerequisite: JDK must already be installed on your system before you can install the
proxy.
The installation procedure asks for the name of the JAVA home directory. You have to
specify the directory explicitly. No name is suggested. You have to specify a fully
qualified directory name. The procedure then checks your input.
BeanConnect V2.1
57
Installing BeanConnect under Linux systems
Installing BeanConnect
If JDK is not installed in the specified directory, the following error message is displayed:
JDK not found!
In this case, check the specified home directory or install JDK first.
Please note that on Linux systems, JDK must have the same bit characteristics as the
proxy!
5. Acceptance
The installation procedure displays the name of the archive from which the proxy is
installed. Installation must be performed from the archive
<BC_home>/CPIO.BCCont.
The default value for <BC_home> is /opt/lib/bc21a00.
Accept this archive.
6. Port number of the proxy container
BeanConnect needs a range of one hundred port numbers. You are asked to enter the
port number which specifies the beginning of this range.
The range of port numbers must not be used by other proxy containers or other applications. You have to specify a different port number here.
Start Value of the Port Number Range for BeanConnect
Specify the start value of the port number range. The next hundred port numbers are
reserved for BeanConnect. Values between 1025 and 32667 are permitted for the port
number. Default: 31000.
7. Password for the administration of the proxy container
Specify the password. Default: admin
8. The proxy container is installed once this dialog has been completed.
I
58
You can repeat the installation procedure several times if you
want to install multiple proxy containers.
BeanConnect V2.1
Installing BeanConnect under Linux systems
Installing the Management Console
The installation procedure requires you to make the following entries:
1. User base directory in which the Management Console is to be installed
The installation procedure sets the current directory (from which the procedure was
started) as the BeanConnect user base directory <user_base_dir>.
If you accept the directory with y, the installation procedure continues. If you specify n,
the installation procedure is aborted.
2. JAVA home directory
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
Prerequisite: JDK must already be installed on your system before you can install the
proxy.
The installation procedure asks for the name of the JAVA home directory. You have to
specify a fully qualified directory name. The procedure then checks your input.
If JDK is not installed in the specified directory, the following error message is displayed:
JDK not found!
Check the specified home directory or install JDK first.
3. Directory for the Management Console configuration files
The configuration files are stored in a subdirectory of the BeanConnect user base
directory <user_base_dir>.
Specify the subdirectory <console_name>. Default: console
The Management Console home directory is consequently
<user_base_dir>/<console_name>.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
If you specify the name of a Management Console that is already installed, you are
asked whether you want to overwrite the Management Console (new installation) or
perform an update installation (see "Update installation for the BeanConnect proxy
container and Management Console" on page 73).
4. Acceptance
The installation procedure displays the name of the archive from which the
Management Console is installed. Installation must be performed from the archive
<BC_home>/CPIO.console.
The default value for <BC_home> is /opt/lib/bc21a00.
Accept this archive.
BeanConnect V2.1
59
Installing BeanConnect under Windows systems
Installing BeanConnect
3.3 Installing BeanConnect under Windows systems
BeanConnect supports the Microsoft Windows operating system.
BeanConnect contains the following product files:
●
BeanConnect proxy
●
openUTM
●
openUTM-LU62 gateway (for CICS partners)
●
PCMX
To install BeanConnect, perform the steps described below:
1. Master installation
3.3.1 Master installation
You need administration authorization to perform master installation.
Insert the BeanConnect DVD in the drive. The DVD starts automatically and the setup menu
appears.
I
The file %WIN32SYS%\drivers\etc\hosts can be saved under the name
hosts.save and modified during installation. In this case, a message is
output. If network problems occur, you should copy the hosts.save file back.
You can install the following packages:
●
PCMX32
●
openUTM
●
BeanConnect
●
openUTM-LU62 gateway (for CICS partners)
Select the package(s) in the Choose Products dialog box that you wish to install.
I
To use BeanConnect, you must have installed all the packages of the master
installation, but you should install only those packages that are not yet
installed on your system. Please make sure that the versions of the package
are identical.
Click the Next button to start master installation.
60
BeanConnect V2.1
3.3.1.1
Installing BeanConnect under Windows systems
Installing PCMX
You must install PCMX before installing openUTM and BeanConnect.
1. Select PCMX-32 installation in the Choose Products dialog box which is described
above.
2. In the PCMX-32 Installation window, click Next > to open the following sequence of
dialog boxes:
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
3.3.1.2
–
In the Information dialog box, click Readme to open the readme file which contains
detailed information. Click License to display the license agreement.
–
In the ... choose your preferred Installation method dialog box, check the
Standard Installation box (default) and click Next >.
–
The Ready to install dialog box then lists the installation directories. Click Next >
to continue.
–
In the Installation completed dialog box, click Finish.
Installing openUTM
You must install openUTM before installing BeanConnect.
1. Select openUTM installation in the Choose Products dialog box which is described
above.
2. Follow the installation program instructions and select the appropriate options.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
openUTM checks the system requirements and makes sure that sufficient disk space
is available. If the system fails to meet the requirements, installation is rejected.
If an older version of openUTM exists on your PC and you decide to install openUTM in
the same directory, the older version is automatically overwritten.
If an older version of openUTM exists on your PC and you decide to install openUTM in
another directory, the valid version is the one that was most recently installed.
3. Reboot the system if you are requested to do so by the installation routine.
BeanConnect V2.1
61
Installing BeanConnect under Windows systems
3.3.1.3
Installing BeanConnect
Installing BeanConnect
I
Before you can install BeanConnect, you must first install JDK,
PCMX and openUTM.
The BeanConnect installation program performs the following tasks:
●
It installs the BeanConnect proxy container and the MC-CmdHandler
●
It installs the BeanConnect Management Console
I
If you want to update an existing installation, you find detailed
information in section "Update installation for the BeanConnect
proxy container and Management Console" on page 73.
Installation procedure
To install BeanConnect, perform the steps described below:
1. Select BeanConnect Proxy in the Choose Products dialog (see "Master installation"
on page 60).
The Installation dialog opens. You can navigate through the sequence of dialog boxes
that are now displayed by clicking Next > and < Back.
2. Welcome screen
Click Next to start the installation.
3. Information dialog box
Click Readme to view the BeanConnect readme file.
4. Choose Language dialog box
Select the language for the Management Console online help system.
5. Common Resources dialog box
Decide whether or not you want to install the common resources. These include
archives, libraries and documents etc. When performing a new installation, you must
always also install the common resources, see section "Installing common resources".
If you do not want to install the common resources, the Common Resources Directory
dialog box asks you to specify the directory containing the common resources that you
intend to use.
In the case of an update installation, you must ensure that the current common
resources are installed.
62
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
Installing BeanConnect under Windows systems
6. Installation Option dialog box
Select Normal installation to perform a new installation.
Select Update installation to update an existing BeanConnect installation. For information on update installations, see "Update installation for the BeanConnect proxy
container and Management Console" on page 73.
Select the entry Update installation without deinstallation to update an existing
BeanConnect installation without uninstalling the existing installation. For information
on update installations, see Section 3.6, "Update installation for the BeanConnect proxy
container and Management Console".
7. Proxy Components dialog box
Check the appropriate box(es) to specify the component(s) which you want to install.
You can select one or both of the components. The subsequent installation process
depends on the components that you have selected for installation.
●
BeanConnect Proxy Container
Installs and initiates a BeanConnect proxy container and the MC-CmdHandler.
It first opens the dialog box openUTM Directory and then the dialog box Java
Directory.
openUTM Directory dialog box
Specify the openUTM home directory which contains the ex\libwork.dll file.
JAVA Directory dialog box
Specify the JAVA home directory. This is the directory on your system that contains
the JDK lib\tools.jar and bin\java.exe files.
© cognitas GmbH 2001-2
●
Management Console (Administration Tool)
Installs the BeanConnect Management Console with which you can configure and
administer BeanConnect proxies.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
If you only activate the option Management Console (Administration Tool) then
the dialog box Java Directory is opened.
JAVA Directory dialog box
Specify the JAVA home directory. This is the directory on your system that contains
the JDK lib\tools.jar and bin\java.exe files.
BeanConnect V2.1
63
Installing BeanConnect under Windows systems
Installing BeanConnect
Installing common resources
If you have chosen to install the common resources in the Common Resources dialog box
then the following dialog boxes are displayed
1. Target BeanConnect Common Resources Directory to install dialog box
Enter the home directory in which the BeanConnect common resources are to be
installed. Default: C:\BeanConnect\BC21A00.
2. BeanConnect Common Resources Program Group dialog box
Select the program group in which you want the installation program to save the
BeanConnect icons for the common resources. You can either select an existing
program group or create a new one.
By default, the installation program creates the following program group:
BeanConnect V2.1A00
Installing the BeanConnect proxy container
If you select BeanConnect Proxy Container in the Proxy Components dialog box, the
following installation program dialog opens:
1. Proxy Container Options dialog box
Specify the name, the port number and the password of the proxy.
●
Name for Proxy Container
Name of the proxy container. Default: BCCont
The name must be unique in your system.
The name can have a maximum length of eight characters.
The following characters are permitted: A,...,Z, a,...,z, 0,...,9
●
Begin of port interval for Proxy Container
BeanConnect needs a range of 100 port numbers. You are asked to enter the port
number which specifies the beginning of this range.
The range of port numbers must not be used by other proxy containers or other
applications. You may specify a different port number here if necessary.
Start Value of the Port Number Range for BeanConnect
Specify the start value of the port number range. The next hundred port numbers
are reserved for BeanConnect. Values between 1025 and 32667 are permitted for
the port number. Default: 31000.
●
Password for Proxy Container
Specify the admin password. Default: admin
64
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
Installing BeanConnect under Windows systems
2. Target Proxy Container Directory to install dialog box
Specify the proxy container home directory in which the proxy container is to be
installed.
By default, the proxy container is installed in the BeanConnect home directory <BC_
home>\<proxy_cont_name>.
Click the Browse button to select a different directory.
3. Proxy Container Program Group dialog box
Select the program group in which you want the installation program to save the
BeanConnect icons for the proxy container. You can either select a program group that
is already present or create a new program group.
By default, the installation program creates the program group:
BeanConnect V2.1A00\<proxy_cont_name>
Installing the BeanConnect Management Console
If you select Management Console (Administration Tool) in the Proxy Components
dialog box, the following installation program dialog opens:
1. Target BeanConnect Management Console Directory to install dialog box
Specify the Management Console home directory in which the Management Console
is to be installed.
By default, the Management Console is installed in the Management Console home
directory <BC_home>\Console.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Click the Browse button to select a different directory.
2. BeanConnect Management Console Program Group dialog box
Select the program group in which you want the installation program to save the
BeanConnect icons for the Management Console. You can either select a program
group that is already present or create a new program group.
By default, the installation program creates the program group:
BeanConnect V2.1A00\Management Console
Installing the BeanConnect proxy container and Management Console
If you select both BeanConnect Proxy Container and Management Console (Administration Tool) in the Proxy Components dialog box, the proxy container and the
Management Console are installed in a single step.
See above for a detailed description of the dialog boxes.
BeanConnect V2.1
65
Installing BeanConnect under Windows systems
Installing BeanConnect
In this case, the following dialog boxes are displayed only once:
●
JAVA Directory
●
Target BeanConnect Common Resources Directory to install
●
BeanConnect Proxy Program Group
Concluding the installation
You have now made all the entries and settings required for installation.
1. Ready to Install! dialog box
Click the Install button to start the installation.
2. Installation Completed! dialog box
Click Finish to conclude installation.
Depending on the selected option(s), the installation program creates a proxy container
including the "internal" MC-CmdHandler or the Management Console.
I
3.3.1.4
The BeanConnect product files are installed automatically
during the installation process.
Installing the openUTM-LU62 Gateway (for CICS partners)
To install the openUTM-LU62 gateway:
1. Select openUTM-LU62 gateway installation in the Choose Products dialog box which
is described above.
2. Follow the installation program instructions and select the appropriate options.
3. Select the home directory in which openUTM-LU62 gateway is to be installed.
4. In the Installation completed dialog box, click Finish.
66
BeanConnect V2.1
Installing BeanConnect under Windows systems
3.3.2 Installing the BeanConnect proxy container via the command line
The BeanConnect installation program setup.exe also has a command line interface
which is described below.
To install the product via the command line, open a DOS prompt window. Switch to the
following directory:
<DVD_drive>\BEANCONNECT-PROXY\Windows
Then enter the following command:
Setup.exe [/S /M=paramfile] [/E=errorfile]
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
The /S option specifies that installation is to be performed without a GUI (Graphical User
Interface). In this case, you must also specify the /M=paramfile parameter. The installation parameters are then taken from the file paramfile in which you can set the installation parameters and directories yourself. The file paramfile must have the format
described below. If you want to use a parameter file, you should specify all the parameters
in the file. In this case, there is no guarantee that the default values will be used.
If /S is not specified, installation is started via the GUI.
With /E=errorfile, you can specify a log file which records the parameters used, the
progress of the installation process, and any error messages that occur. If you specify the
/S option, you are also advised to use the /E option.
If you do not specify /E, any error messages that occur may be lost. If it does not already
exist, the file errorfile is created by the installation program. If it does exist, the file is
overwritten.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Format of the parameter file
An example of a parameter file is shown below. This file
(BeanConnect_Install.ini) is provided. You can adapt it to suit your requirements.
;Online Help Language;
A: English;
B: German
OHELP_CFG=A
Language for the online help system
;Installation Option
UPDATEINSTALL=N
Update installation?
;BeanConnect Proxy directory to update UPDBEANCONNECTDIR=
INST_PROXY=Y
Create proxy container
INST_CONSOLE=Y
Create Management Console
; openUTM Directory
UTMPATH=c:\openUTM-Server
openUTM home directory
BeanConnect V2.1
67
Installing BeanConnect under Windows systems
; JAVA Home Directory
Installing BeanConnect
Java home directory
JAVA_HOME=C:\jdk1.5
; BeanConnect Common Resources Directory
ROOTDIR=C:\BeanConnect
BeanConnect home directory
; ------------------------------------------------------ ;
Proxy parameters. Only evaluated if INST_PROXY=Y and
UPDATEINSTALL=N
; ----------------------------------------------------PROXY_NAME=BCCont
Name of the proxy container
PORT_BEGIN=31000
Port for communication with the
BeanConnect proxy container
PROXY_PASSWORD=admin
Administration password of the proxy
container
; Target Proxy Directory
PROXYDIR=C:\BeanConnect\BCCont
Directory for installation of the proxy
container
; -----------------------------------------------------;Management Console. Only evaluated if INST_CONSOLE=Y
; -----------------------------------------------------; Only for Update installation.
; Existing Console directory to update
UPDCONSOLEDIR=C:\BeanConnect\Console
Directory of the existing
Management Console
; Target Console directory
CONSOLEDIR=C:\BeanConnect\Console
Directory for the installation of the
Management Console
68
BeanConnect V2.1
Installing a BeanConnect resource adapter
3.4 Installing a BeanConnect resource adapter
You install the BeanConnect resource adapter using the JAR file BC21A00_RA.jar.
This file contains the resources listed below:
●
the RAR file BC21A00.rar containing the resource adapter classes (for information on
using the RAR file see "Deploying and undeploying the resource adapter" on page 94)
●
the file BeanConnectDev.jar for compiling the EJBs
●
The file BeanConnectVerifyer.jar, which must be appended to the BeanConnect
RAR file if you want to use the Sun JEE Verifier (part of the Sun Glassfish V2 JEE5
Application Server).
●
The directory config: log4j configuration files for resource adapter logging
●
The directory Docs: Documents
●
The directory encoding: Encoding example
●
The directory JavaDoc: Javadoc for the user API.
●
The directory scid: Diagnostic tool
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
Installing a resource adapter in systems with a graphical user interface
In systems with a graphical user interface, proceed as follows:
1. In the relevant system, open a window for command entry, e.g. Shell or DOS prompt
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
2. Switch to the directory in which the JAR file is located
3. Unpack the JAR file using the command
java -jar BC21A00_RA.jar
4. Follow the instructions output by the graphical installation program and define the installation directory for the resource adapter
Installing a resource adapter in systems without a graphical user interface
The file RA-auto.xml is supplied to permit installation on systems without a graphical user
interface. Proceed as follows:
1. Open the file RA-auto.xml with a text editor and enter the required installation path for
the resource adapter in the <installpath> tag
2. In the relevant system, open a window for command entry, e.g. Shell or DOS prompt.
3. Switch to the directory in which the JAR file is located
BeanConnect V2.1
69
Installing a BeanConnect resource adapter
Installing BeanConnect
4. Unpack the JAR file using the command
java -jar BC21A00_RA.jar RA-auto.xml
This installs the resource adapter automatically. The files are unpacked in the current
directory without modifying RA-auto.xml .
70
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
Installing the BeanConnect tools
3.5 Installing the BeanConnect tools
BeanConnect provides a number of tools in addition to the proxy and the resource adapter.
These tools can be installed separately and are present in the form of JAR archives. The
tools are available in the following archives:
MC-CmdHandler
BC21A00_MCCmdHandler.jar
Cobol2Java
BC21A00_Cobol2Java.jar
BPEL WSDL Generator
BC21A00_BPELWsdlGen.jar
Installing the BeanConnect tools in systems with a graphical user interface
In systems with a graphical user interface, proceed as follows:
1. In the relevant system, open a window for command entry, e.g. Shell or DOS prompt.
2. Switch to the directory in which the JAR file is located.
3. Unpack the JAR file using the following command
java -jar <jar-archive>
<jar-archive> is the name of the relevant JAR archive displayed at the top of the list.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
4. Follow the instructions output by the graphical installation program and define the installation directory for the tool, possibly together with additional parameters.
Installing the BeanConnect tools in systems without a graphical user interface
An Auto.xml file is supplied for each tool to permit installation on systems without a
graphical user interface. This file has the name <tool>-auto.xml, where <tool> is the
name of the tool to be installed MC-CmdHandler, Cobol2Java, BPELWsdlgen).
Proceed as follows:
1. Open the Auto-xml- file with a text editor and enter the required installation path for the
tool in the <installpath> tag. In the case of some tools, you must also enter configuration data such as port number or password for additional tags that have been
commented out.
2. In the relevant system, open a window for command entry, e.g. Shell or DOS prompt.
3. Switch to the directory in which the JAR file is located.
4. Unpack the JAR file using the following command
java -jar <jar-archive> <tool>-auto.xml
This installs the tool automatically.
BeanConnect V2.1
71
Installing the BeanConnect tools
Installing BeanConnect
5. In the case of the tools MC-CmdHandler and BPEL WSDL Generator, you must enter
the path to JDK in the file javaenv.cmd (Windows systems) or javaenv.sh (Linux,
Solaris systems). You do this by editing the file with a text editor.
72
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
Update installation
3.6 Update installation for the BeanConnect proxy container and
Management Console
BeanConnect allows you to perform update installations. An update installation enables you
to install a new BeanConnect version or a new patch while retaining the configuration data
of the installed proxy container and Management Console.
This section provides an overview of:
●
Update installation under Solaris systems
●
Update installation under Linux systems
●
Update installation under Windows systems
3.6.1 Update installation under Solaris systems
This section describes how you can update the proxy container and Management Console
installation under Solaris systems. If you obtain new software, then start the master installation and install the new products (see Installing BeanConnect under Solaris systems on
page 46).
Starting the update installation
The update installation is performed in the same way as a new installation.
Start the installation procedure with the following command:
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
<BC_home>/shsc/install.BeanConnect
The default value for <BC_home> is /opt/lib/bc21a00.
As in a new installation, the procedure displays a menu listing the two components that can
be installed. You select the components for which you want to install an update:
Configuration Options
1 BeanConnect Proxy Container
2 Management Console (Administration Tool)
The installation procedure recognizes when you specify a home directory that already
contains one of the components and checks whether the version is updatable. If it is, you
are asked whether you want to perform an update installation or overwrite the existing
version (new installation).
An update installation is performed for the selected BeanConnect components.
BeanConnect V2.1
73
Update installation
Installing BeanConnect
BeanConnect proxy container
1. The proxy container home directory is copied and saved in the directory
<BC_home>/<proxy_cont_name>.save. This directory is not changed by the update
installation. All the old configuration data is retained.
2. The proxy container is uninstalled.
3. A new proxy container is installed in the proxy container home directory.
4. The old configuration is moved to the new proxy container.
Management Console
1. The Management Console home directory is copied and saved in the directory
<BC_home>/<console_name>.save. This directory is not changed by the update
installation. All the old configuration data is retained.
2. The Management Console is uninstalled.
3. The new Management Console is installed in the Management Console home directory.
4. The old configuration files are read from <console_name>.save and copied to the new
Management Console home directory.
3.6.2 Update installation under Linux systems
This section describes how you can update the proxy container and Management Console
installation under Linux. If you obtain new software then start the master installation and
install the new products (see Installing BeanConnect under Linux systems on page 53).
Starting the update installation
The update installation is performed in the same way as a new installation.
Start the installation procedure with the following command:
<BC_home>/shsc/install.BeanConnect
The default value for <BC_home> is /opt/lib/bc21a00.
As in a new installation, the procedure displays a menu listing the two components that can
be installed. You select the components for which you want to install an update:
Configuration Options
1 BeanConnect Proxy Container
2 Management Console (Administration Tool)
74
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
Update installation
The installation procedure recognizes when you specify a home directory that already
contains one of the components and checks whether the version is updatable. If it is, you
are asked whether you want to perform an update installation or overwrite the existing
version (new installation).
An update installation is performed for the selected BeanConnect components.
BeanConnect proxy container
1. The proxy container home directory is copied and saved in the directory
<BC_home>/<proxy_cont_name>.save. This directory is not changed by the update
installation. All the old configuration data is retained.
2. The proxy container is uninstalled.
3. A new proxy container is installed in the proxy container home directory.
4. The old configuration is moved to the new proxy container.
Management Console
1. The Management Console home directory is copied and saved in the directory
<BC_home>/<console_name>.save. This directory is not changed by the update
installation. All the old configuration data is retained.
2. The Management Console is uninstalled.
3. The new Management Console is installed in the Management Console home directory.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
4. The old configuration files are read from <console_name>.save and copied to the new
Management Console home directory.
BeanConnect V2.1
75
Update installation
Installing BeanConnect
3.6.3 Update installation under Windows systems
This section describes how you can update the proxy container and Management Console
installation under Windows. If you obtain new software then start the master installation and
install the new products (see Installing BeanConnect under Windows systems on page 60).
Starting the update installation
You start the installation in the usual way (see "Installing BeanConnect under Windows
systems" on page 60). You should then click the BeanConnect Proxy item in the setup
menu.
Only the dialog boxes that differ from those displayed during a new installation are
described here. You work with all the other dialog boxes in the same way as for a new installation (see "Installing BeanConnect under Windows systems" on page 60).
●
Installation Option dialog box
If you want to update an existing BeanConnect installation, select the option Update
installation.
If you want to update an existing BeanConnect installation without uninstalling the
existing installation, select Update installation without deinstallation.
●
Existing Proxy Container Directory to update dialog box
Specify the proxy coantainer home directory that is to be updated.
●
Existing BeanConnect Management Console directory to update dialog box
Specify the Management Console home directory that is to be updated.
For the subsequent procedure, see "Installing BeanConnect" on page 62.
The update installation is performed for the BeanConnect components selected in the
Configuration Options dialog box (see "Installation procedure" on page 62).
BeanConnect proxy container update installation
1. The proxy container home directory is copied and saved in the directory
<BC_home>\<proxy_cont_name>.save. This directory is not changed by the update
installation. All the old configuration data is retained.
2. The proxy container is uninstalled.
3. A new proxy container is installed in the proxy container home directory.
4. The old configuration is moved to the new proxy container.
76
BeanConnect V2.1
Update installation
Management Console update installation
1. The Management Console home directory is copied and saved in the directory
<BC_home>\<console_name>.save. This directory is not changed by the update
installation. All the old configuration data is retained.
2. The Management Console is uninstalled.
3. The new Management Console is installed in the Management Console home directory.
4. The old configuration files are read from <console_name>.save and copied to the new
Management Console home directory.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
BeanConnect V2.1
77
Uninstalling BeanConnect
Installing BeanConnect
3.7 Uninstalling BeanConnect
This section describes how to uninstall BeanConnect:
●
Uninstalling BeanConnect under Solaris systems
●
Uninstalling BeanConnect under Linux
●
Uninstalling BeanConnect under Windows
3.7.1 Uninstalling BeanConnect under Solaris systems
This section describes how to uninstall BeanConnect under Solaris systems.
Uninstalling the BeanConnect proxy container
To uninstall the proxy container you simply have to delete the home directory.
Uninstalling the BeanConnect Management Console
To uninstall the Management Console you simply have to delete the home directory.
Uninstalling the BeanConnect product files
You use the following command to uninstall the BeanConnect product files:
pkgrm BC21A00
Uninstalling PCMX
You use the following command to uninstall the supplied PCMX:
pkgrm SMAWpcmx
Uninstalling openUTM
You use the following command to uninstall openUTM:
pkgrm UTM<version>
Uninstalling openUTM-LU62 Gateway (for CICS partners)
You use the following command to uninstall the openUTM-LU62 gateway:
pkgrm SMAWutm62
78
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
Uninstalling BeanConnect
3.7.2 Uninstalling BeanConnect under Linux
This section describes how to uninstall BeanConnect under Linux.
Uninstalling the BeanConnect proxy container
To uninstall the proxy container you simply have to delete the home directory.
Uninstalling the BeanConnect Management Console
To uninstall the Management Console you simply have to delete the home directory.
Uninstalling the BeanConnect product files
You use the following command to uninstall the BeanConnect product files:
rpm -e BC21A00
Uninstalling PCMX
You use the following command to uninstall PCMX:
rpm -e PCMX-<version>
To obtain the exact package name, enter rpm -qa | grep PCMX .
Uninstalling openUTM
You use the following command to uninstall openUTM:
Uninstalling openUTM-LU62 Gateway
You use the following command to uninstall the openUTM-LU62 gateway:
rpm -e UTMLU62
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
rpm -e UTM<version>
BeanConnect V2.1
79
Uninstalling BeanConnect
Installing BeanConnect
3.7.3 Uninstalling BeanConnect under Windows
This section describes how to uninstall BeanConnect under Windows.
Uninstalling the BeanConnect proxy container
To uninstall the proxy container select:
Start - Programs - BeanConnect V2.1A00 - Proxy <proxy_cont_name> - Uninstall
Alternatively, you can use the following commands:
1. Start the uninstall program by clicking Start - Settings - Control Panel - Software.
2. Select BeanConnect V2.1A00 <proxy_cont_name> and click the Remove button.
The uninstallation of the proxy container comprises:
●
Deletion of the directories: <BC_home>\<proxy_cont_name>,
<BC_home>\<proxy_cont_name>.SAVE
●
Deletion of <BC_home>\MCINFO if the directory is empty
●
The product files will not be deleted (<BC_home>\lib, <BC_home>\Docs)
Uninstalling the BeanConnect Management Console
To uninstall the Management Console select:
Start - Programs - BeanConnect V2.1A00 - Management Console - Uninstall
Alternatively, you can use the following commands:
1. Start the uninstall program by clicking Start - Settings - Control Panel - Software.
2. Select BeanConnect V2.1A00 Management Console and click the Remove button.
The uninstallation of the Management Console comprises:
80
●
Deletion of the directories: <BC_home>\<console_name>,
<BC_home>\<console_name>.SAVE
●
The product files will not be deleted (<BC_home>\lib, <BC_home>\Docs)
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
Uninstalling BeanConnect
Uninstalling the BeanConnect common resources
To uninstall the BeanConnect common resources, select:
Start - Programs - BeanConnect V2.1A00 - Uninstall Common Resources
Alternatively, you can use the following commands:
1. Start the uninstall program by clicking Start - Settings - Control Panel - Software.
2. Select BeanConnect V2.1A00 Common Resources and click the Remove button.
The uninstallation of the product files comprises:
●
Deletion of the directories: <BC_home>\lib, <BC_home>\Docs
●
Deletion of <BC_home>\MCINFO if the directory is empty
V
If you uninstall the BeanConnect common resources, the proxy
container and the Management Console that are installed in the
same <BC_home> directory will no longer function.
Uninstalling PCMX
1. Start the uninstall program by clicking Start - Settings - Control Panel - Software.
2. Select PCMX-32 and click the Remove button.
Uninstalling openUTM
To uninstall openUTM, select:
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Start - Programs - openUTM-Server - Uninstall openUTM-Server
Alternatively, you can use the following commands:
1. Start the uninstall program by clicking Start - Settings - Control Panel - Software.
2. Select openUTM-Server <version> and click the Remove button.
Uninstalling openUTM-LU62 Gateway (for CICS partners)
To uninstall the openUTM-LU62 gateway, select:
Start - Programs - openUTM-LU62 - Uninstall openUTM-LU62
Alternatively, you can use the following commands:
1. Start the uninstall program by clicking Start - Settings - Control Panel - Software.
2. Select openUTM-LU62 <version> and click the Remove button.
BeanConnect V2.1
81
Uninstalling BeanConnect
Installing BeanConnect
3.8 Uninstalling the BeanConnect resource adapter
To uninstall the resource adapter you simply have to delete the copied or extracted files and
directories that you unpacked from the JAR file when installing the resource adapter.
82
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k03
Installing BeanConnect
Uninstalling the BeanConnect tools
3.9 Uninstalling the BeanConnect tools
You uninstall a BeanConnect tool by deleting the tool's installation directory.
The only special case is the MC-CmdHandler tool. If the MC-CmdHandler is configured as
a service (see Section 6.10.2.3, "Configuring an MC-CmdHandler as a service"), then you
must remove this first. To do this, proceed as follows:
●
Windows systems:
Call the script MCCmdHandler_UnInstSrv.cmd.
●
Linux and Solaris systems
If you want to uninstall an individual service, delete the corresponding line from the file
/etc/init.d/bcmccmdhandler.dat.
If you want to uninstall the entire service, then you must delete the files
/etc/init.d/bcmccmdhandler.sh (incl. symbolic links) and /etc/init.d/bcmccmdhandler.dat .
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
You need system administrator authorizations to perform these activities. You may
therefore need to ask the system administrator to perform this task.
BeanConnect V2.1
83
Uninstalling the BeanConnect tools
84
Installing BeanConnect
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
June 8, 2009 7:06 pm
4 Configuration in the application server
It is necessary to configure settings for BeanConnect both when deploying the
BeanConnect resource adapter in the application server and when deploying Enterprise
Java Beans (EJB) in the application server.
This chapter contains information on configuring outbound communication via the various
protocols (OSI-TP for openUTM partners, LU6.2 protocol for CICS partners, UPIC protocol
for openUTM partners) as well as on configuring inbound communication.
This chapter also describes how you prepare logging in the resource adapter and the issues
that you have to take into account when operating in multiple resource adapter or cluster
mode.
●
Deploying and undeploying the resource adapter
●
Configuring global properties for the resource adapter (ra.xml)
●
Deploying an Enterprise JavaBean for OSI-TP / LU6.2
●
Configuring outbound communication via UPIC
●
Setting configuration properties for inbound communication
●
Preparing resource adapter logging
●
Special characteristics of multiple resource adapter mode
●
Special characteristics in cluster operation
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
It contains information on the following topics:
BeanConnect V2.1
85
Overview
Configuration in the application server
4.1 Overview
The resource adapter is supplied as a so-called BeanConnect RAR archive.
V
Only one BeanConnect resource adapter may be deployed per
instance in the application server.
The deployment of more than one resource adapter may result
in unpredictable errors.
The BeanConnect RAR archive is named BC21A00.rar. It contains various items including
the deployment descriptor ra.xml.
4.1.1 Configuration files in the application server
The resource adapter and EJB configuration properties are defined in the following files:
●
ra.xml
Default deployment descriptor for the resource adapter.
This file is present in the BeanConnect RAR archive and defines the resource adapter's
global properties.
●
oc4j-ra.xml
OC4J-specific deployment descriptor for the resource adapter.
This file contains the connection-specific settings for outbound communication, i.e. the
properties of the connection factories. These include the configuration properties, the
pooling properties (if connection pooling is used) and the security settings for
container-managed authentication (user, password). The entries in oc4j-ra.xml refer
to entries in ra.xml.
●
ejb-jar.xml
Default deployment descriptor for EJBs.
This file describes various items including the EJB properties that are relevant for
communications. The entries refer to entries in orion-ejb-jar.xml and
oc4j-ra.xml.
86
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
●
Overview
orion-ejb-jar.xml
Application server-specific deployment descriptor for EJBs in OC4J.
This file is responsible for "name mapping" between EJB and the resource adapter. The
entries refer to entries in oc4j-ra.xml.
The section below describes the procedure you may adopt.
4.1.2 Configuration steps for outbound and inbound communication
The procedure depends on whether you want to operate outbound communication via
OSI-TP/ LU6.2, outbound communication via UPIC, or inbound communication. Each of
these possibilities is presented separately below. However, different rules apply for multiple
resource adapter and cluster operation.
In the case of outbound communication (OSI-TP / LU6.2 and UPIC), you must define
resource references in both ejb-jar.xml (resource references) and orion-ejb-jar.xml
(resource reference mapping).
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Procedure for outbound communication via OSI-TP / LU6.2
If you want to run BeanConnect for outbound communication via OSI-TP / LU6.2 in default
mode (one proxy, one resource adapter, no cluster) then you must perform the following
activities in the application server:
●
Defining global properties in ra.xml
●
If present, pack the file oc4j-ra.xml under the META-INF directory before deployment
to the RAR file.
This avoids having to start OC4J twice.
●
Deploying the resource adapter
●
Defining connection-specific properties for OSI-TP / LU6.2 in oc4j-ra.xml
●
Restart OC4J
●
Deploying an Enterprise JavaBean for OSI-TP / LU6.2
●
Preparing resource adapter logging
BeanConnect V2.1
87
Overview
Configuration in the application server
Procedure for outbound communication via UPIC
If you want to run BeanConnect for communications via UPIC then you must perform the
following activities at the application server:
●
Deploying the resource adapter
●
Defining connection-specific properties for UPIC in oc4j-ra.xml
●
Restart OC4J
●
Deploying an Enterprise JavaBean for UPIC
●
Preparing resource adapter logging
Procedure for inbound communication
If you want to run BeanConnect for inbound communication in default mode (one proxy, one
resource adapter, no cluster) then you must perform the following activities in the application server:
●
Defining global properties in ra.xml
●
Deploying the resource adapter
●
Configuration properties in the ejb-jar.xml
In ejb-jar.xml, define the activation-config-properties.
●
Specify the resource adapter for the message-driven bean in orion-ejb-jar.xml
●
Deploy the OLTP message-driven bean
●
Preparing resource adapter logging
Procedure with multiple resource adapters and in cluster operation
When working with multiple resource adapters or in cluster operation, additional settings
must be made in the file ra.xml. For further details, see:
88
●
Special characteristics of multiple resource adapter mode
●
Special characteristics in cluster operation
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
Global properties (ra.xml)
4.2 Configuring global properties for the resource adapter
(ra.xml)
The resource adapter's deployment descriptor ra.xml is present in the BeanConnect RAR
archive. The file ra.xml contains:
●
The global configuration properties for the connection between the resource adapter
and the proxy
●
The definition of the connection factories supported by BeanConnect
●
The properties supported by these connection factories together with their default
values
It can be thought of as a template for configuring the connection. Before deploying the
resource adapter, it is necessary to adapt the global configuration properties to the specific
circumstances applying to the application in question. This is done in the file ra.xml.
4.2.1 Defining global properties in ra.xml
The global configuration properties are relevant only for outbound communication via
OSI-TP / LU6.2 and for inbound communication.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Before you can deploy the BeanConnect RAR archive you must adapt the global configuration properties in the file ra.xml to suit your requirements. Different properties apply to
inbound and outbound communications.
Alternatively you can deploy the resource adapter with the predefined settings. Then
specify the values by using the application server's GUI. The settings can be lost while
undeploying.
Adapting the ra.xml file
You can adapt ra.xml in two ways
●
with the BeanConnect Management Console provided that the BeanConnect RAR
archive and the Management Console are located on the same host. If this is not the
case, then an MC-CmdHandler must be installed on the same computer as the
BeanConnect RAR archive and configured in the Management Console.
For more information, see Section 6.5, "Configuring the BeanConnect resource
adapter" on page 184).
●
Manually using a text editor.
1. Extract the file ra.xml from the BeanConnect RAR archive:
jar xf BC21A00.rar META-INF/ra.xml
BeanConnect V2.1
89
Global properties (ra.xml)
Configuration in the application server
2. Use a text editor of your choice to modify the following global configuration
properties in the file ra.xml:
proxyURL (outbound only)
transactionLogging (outbound only)
transactionLogDir (outbound only)
inboundListenerPort (inbound only)
RevisionNumber
3. Insert the file ra.xml in the BeanConnect RAR archive in the subdirectory
META-INF again:
jar uf BC21A00.rar META-INF/ra.xml
In multiple resource adapter mode or in cluster operation, it is necessary to make additional
settings, see Section 4.7, "Special characteristics of multiple resource adapter mode" and
Section 4.8, "Special characteristics in cluster operation".
proxyURL
The proxyURL defines the way the resource adapter assigns the proxy.
proxyURL is defined globally for all connections.
Definition:
oltp://<host>:<port>/<name>
Explanation: <host>
Host on which the proxy container is installed
<host> can be specified as a symbolic name or as an IPv4
address.
90
<port>
Port number of the proxy container
<name>
Application name of the proxy container (BC<port>)
Default:
oltp://localhost:31000/BC31000
Example:
<config-property>
<description>BeanConnect Proxy URL for OLTP outbound
communication</description>
<config-property-name>proxyURL</config-property-name>
<config-property-type>java.lang.String
</config-property-type>
<config-property-value>oltp://proxyhost:31000/BC31000
</config-property-value>
</config-property>
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
Global properties (ra.xml)
The value for <port> is specified during installation of the proxy. The value for <name> is
derived from the value for <port>. It is composed of the prefix BC and the port number.
The Management Console displays the proxy URL to be used in the properties dialog of the
resource adapter.
For information on configuration for cluster operation, see Section 4.8, "Special characteristics in cluster operation".
transactionLogging
This attribute defines whether or not BeanConnect is to write persistent transaction logs for
transactions with EIS partners during outbound communication.
Definition:
[NONE | FILE]
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Explanation: Activates or deactivates persistent transaction logging
NONE:
No persistent transaction logs are written.
FILE:
Persistent transaction logs are written. The directory to which the
logs are written is specified in the attribute transactionLogDir.
Default:
NONE
Example:
<config-property>
<description>BeanConnect transaction logging:
possible values are NONE | FILE
</description>
<config-property-name>transactionLogging
</config-property-name>
<config-property-type>java.lang.String
</config-property-type>
<config-property-value>FILE
</config-property-value>
</config-property>
During transaction recovery operations following a program or system crash, persistent
transaction logs make it possible for BeanConnect to provide information about the status
of the transactions that were being processed at the time of the crash. Activating this option
has an impact on performance since two file access operations are required for every transaction which is terminated with two-phase commit.
If FILE is specified then it is also necessary to enter a value for the attribute transactionLogDir.
If transaction logging is configured then the resource adapter writes a separate transaction
log for each transaction. The file name consists of the prefix tx. and a number.
BeanConnect V2.1
91
Global properties (ra.xml)
Configuration in the application server
A transaction log file is written on Prepare and deleted on Commit or Rollback, i.e. it is
normally temporary. However, situations exist in which it is retained:
●
If the resource adapter is terminated between Prepare and Rollback or Commit. This
type of log file is retained until the recovery has been completed for this transaction.
●
If a heuristic decision has been made for a transaction. This type of log file is retained
for an indefinite period.
All the transaction log files are read in when the resource adapter is started. New transaction log files are written for transactions which have the status Prepared after start-up or
for which a heuristic decision has been made.
I
For transactions associated with heuristic decisions, the transaction log files are
retained for an indefinite period. They should therefore be deleted from time to time.
The creation time of the log files may serve as a criterion when deciding which log
files are to be deleted. Files whose creation date and time correspond to the last
resource adapter start-up contain heuristic logs and the application server has not
called forget() for these transactions; these files can be deleted. To identify the
application start time, BeanConnect writes a file during the start phase after
processing the transaction log files. This file has the name
tx.startup-complete.<date>.<time> and is written in the transaction log
directory.
BeanConnect deletes old startup-complete files on the next start-up.
transactionLogDir
This attribute defines the directory to which BeanConnect is to write the persistent transaction logs. A value must be specified for this attribute if the attribute transactionLogging has been assigned the value FILE.
92
Definition:
Name of a directory
Default:
persistence\BeanConnect
Example:
<config-property>
<description>Directory where transaction log files are to be
stored (only needed if transactionLogging=FILE)
</description>
<config-property-name>transactionLogDir
</config-property-name>
<config-property-type>java.lang.String
</config-property-type>
<config-property-value>persistence/BeanConnect
</config-property-value>
</config-property>
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
Global properties (ra.xml)
The directory can be specified with an absolute or relative path name. Any relative path
specification is understood to be relative to the application server's home directory.
In the case of OC4J 10.1.3, the home directory is
<OC4J_install_dir>/j2ee/home/oc4j.
If the directory specified for transactionLogDir does not exist, BeanConnect creates it.
inboundListenerPort
For inbound communication, the resource adapter listens at a socket port for connection
requests initiated by the proxy. You must specify the port number of this socket port with the
global configuration property inboundListenerPort. This value must be adapted before
deploying the resource adapter.
Definition:
<port number>
Explanation:
Port number of the socket port on which the resource adapter listens for inbound
communication requests.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
0 means that no inbound communication is possible.
Default:
31099
Example:
<config-property>
<description>Resource Adapter Listener Port for Inbound
Communication
</description>
<config-property-name>inboundListenerPort
</config-property-name>
<config-property-type>java.lang.String
</config-property-type>
<config-property-value>31099
</config-property-value>
</config-property>
If no inbound functionality is to be used, you should set the value 0.
The port number specified with inboundListenerPort must be identical to the port
number specified during configuration of the proxy with the Management Console.
RevisionNumber
This attribute indicates the revision level of the file ra.xml. You should increase the value
of the attribute revisionNumber every time you modify the ra.xml file in order to make it
easier to identify possible inconsistencies in the configuration.
BeanConnect V2.1
93
Deploying and undeploying the resource adapter
Example:
Configuration in the application server
<config-property>
<description>Revision number of the ra.xml. This number
should be incremented with each change of the resource
adapter properties.
</description>
<config-property-name>revisionNumber
</config-property-name>
<config-property-type>java.lang.String
</config-property-type>
<config-property-value>2
</config-property-value>
</config-property>
4.2.2 Deploying and undeploying the resource adapter
You should not deploy the resource adapter until you have entered the global configuration
settings in the file ra.xml, see Section 4.2.1, "Defining global properties in ra.xml".
When the resource adapter is deployed in OC4J, a template is inserted in the file
oc4j-ra.xml. This contains the template definition for the connection factories and their
configuration properties in the form of comments. You must then adapt these configuration
properties, see Section 4.3, "Setting configuration properties for outbound communication
via OSI-TP / LU6.2" and Section 4.4.1.2, "Setting the configuration properties for UPIC".
4.2.2.1
Deploying the resource adapter
You deploy the BeanConnect RAR archive using the OC4J admin.jar utility. You can find
a detailed description of this utility, for example, in chapter "6. Using the admin_client.jar
Utility" in the manual "Oracle Containers for J2EE Configuration and Administration Guide".
admin.jar must be called from the <J2EE_HOME> directory of the application server.
Alternatively you can use the Web GUI provided at
http://<oc4j_host>:<port>/em.
<oc4j_host> identifies the host where OC4J is running. You can call the GUI from
anywhere in the network where you have access to the RAR file to be deployed. The default
value for <port> is 8888.
If you do not deploy the applications from the host on which OC4J is running, you may
instead use the Administrative Client Utility
(http://www.oracle.com/technology/software/products/ias/htdocs/
utilsoft.html).
94
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
Deploying and undeploying the resource adapter
Calling the OC4J admin.jar utility for deployment
java -jar <J2EE_HOME>/admin_client.jar
ormi://<oc4j_host>:<oc4j_RmiPort>
<user> <password>
-deploy <RA_HOME>/BC21A00.rar
-name <RA_name>
-grantAllPermissions
<J2EE_HOME> indicates the directory <oc4j_install_dir>/j2ee/home.
<oc4j_host> and <oc4j_RmiPort> specify host name and port number of OC4J. The
default value for <oc4j_RmiPort> is 23791.
<RA_HOME> specifies the directory to which the resource adapter's BeanConnect RAR
archive was unpacked during installation.
<RA_name> is the name of the resource adapter. The value for <RA_name> is arbitrary. The
BeanConnect RAR archive can be installed once for each application server.
Notes:
●
If a resource adapter already deployed in the application server is to be replaced, for
example because the file ra.xml has been provided with new configuration values,
only the new BeanConnect RAR archive must be deployed as described here. Before
a redeployment, it is necessary to stop all the OLTP message-driven bean applications
which reference the resource adapter. An explicit undeploy and deploy is not necessary,
this is done implicitly during deployment.
© cognitas GmbH 2001-2
●
If an existing resource adapter is redeployed, the existing oc4j-ra.xml file in <J2EE_
HOME>/application-deployments/default/<RA_name> is deleted. You should
therefore save oc4j-ra.xml before deployment and copy it back to this directory after
deployment.
You can also include oc4j-ra.xml in the BeanConnect RAR archive with
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
jar uf BC21A00.rar META-INF/oc4j-ra.xml.
It will then be included automatically by OC4J during deployment.
BeanConnect V2.1
95
Deploying and undeploying the resource adapter
4.2.2.2
Configuration in the application server
Undeploying the resource adapter
Before an undeployment, it is necessary to stop all the OLTP message-driven bean applications that reference the resource adapter.
The following example illustrates how to undeploy a BeanConnect RAR archive.
Calling the OC4J admin.jar utility for undeployment
java -jar <J2EE_HOME>/admin_client.jar
ormi://<oc4j_host>:<oc4j_RmiPort>
<user> <password>
-undeploy <RA_name>
-isConnector
You can also undeploy by using the Web GUI.
4.2.3 Example of an ra.xml File
Example 3 shows the definition of the global configuration properties in the file ra.xml.
Example 3 Configuration properties in the file ra.xml
The section with the global configuration properties in the file ra.xml has the following
layout:
...
<resourceadapter>
<resourceadapter-class>
net.fsc.jca.BeanConnect.ResourceAdapterJBImpl
</resourceadapter-class>
<config-property>
<description>Resource Adapter Listener Port for Inbound Communication
</description>
<config-property-name>inboundListenerPort
</config-property-name>
<config-property-type>java.lang.String</config-property-type>
<config-property-value>31099</config-property-value>
</config-property>
<config-property>
<description>BeanConnect Proxy URL for OLTP Outbound Communication</description>
<config-property-name>proxyURL</config-property-name>
<config-property-type>java.lang.String</config-property-type>
<config-property-value>oltp://localhost:31000/BC31000</config-property-value>
</config-property>
<config-property>
96
BeanConnect V2.1
Deploying and undeploying the resource adapter
<description>BeanConnect transaction logging: possible values are NONE |
FILE</description>
<!-- If NONE is set, no persistent transaction logging will be performed.
If FILE is set, transaction log files will be written to the directory specified in
property
transactionLogDir. -->
<config-property-name>transactionLogging</config-property-name>
<config-property-type>java.lang.String</config-property-type>
<config-property-value>FILE</config-property-value>
</config-property>
<config-property>
<description>Directory where transaction log files are to be stored (only needed if
transactionLogging=FILE)</description>
<!-- The path name of the dircetory may be specified as absolute or relative path.
A relative path is relative to the home directory of the application server. -->
<config-property-name>transactionLogDir</config-property-name>
<config-property-type>java.lang.String</config-property-type>
<config-property-value>persistence/BeanConnect</config-property-value>
</config-property>
<config-property>
<description>Revision number of the ra.xml. This number should be incremented with each
change of the resource adapter properties.
</description>
<config-property-name>revisionNumber
</config-property-name>
<config-property-type>java.lang.String
</config-property-type>
<config-property-value>2
</config-property-value>
</config-property>
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
BeanConnect V2.1
97
Outbound communication via OSI-TP / LU6.2
Configuration in the application server
4.3 Setting configuration properties for outbound
communication via OSI-TP / LU6.2
The following configuration properties must be set for outbound communication:
●
In the file ra.xml: The global configuration property proxyURL (see "Defining global
properties in ra.xml" on page 89).
●
In the file oc4j-ra.xml: The connection-specific configuration properties.
A new oc4j-ra.xml file is created when the resource adapter is deployed. During this
operation, the templates for the BeanConnect-specific properties (connection factories) are
entered in the file in the form of comments.
4.3.1 Defining connection-specific properties for OSI-TP / LU6.2 in
oc4j-ra.xml
The file oc4j-ra.xml is the OC4J-specific deployment descriptor for the resource adapter.
This deployment descriptor specifies the settings that are required for outbound communication with EIS partners. The communications are conducted via so-called connection
factories.
After deployment of the resource adapter, the directory
<J2EE_HOME>/application-deployments/default/<RA_name> contains a predefined
file oc4j-ra.xml with templates for the different types of connection factories.
<J2EE_HOME> stands for the directory <OC4J_install_dir>/j2ee/home.
Connection factories
You must configure at least one connection factory for each EIS partner. However, you may
also configure multiple connection factories with different properties for one and the same
EIS partner.
A connection factory's properties are defined in a <connector-factory> entry. In the
Management Console, an outbound communication endpoint is assigned to each
connection factory.
You make the following specifications for each connection factory:
98
●
JNDI name and resource type: These are also required when deploying the EJB and
make it possible to assign the connection factory to the EJB.
●
Configuration properties: These are the parameters that apply to the connection to the
EIS partners.
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
●
Connection pooling: Connection pooling is an application server functionality. It helps
improve performance on frequently used connections.
●
Security settings: This is the data required when signing on at the EIS partner, e.g. user
ID and password. If this data is encoded directly in the EJB then the corresponding
entry can be omitted in the deployment descriptor.
I
4.3.1.1
Outbound communication via OSI-TP / LU6.2
The changes in oc4j-ra.xml do not take effect until you restart OC4J.
Defining the JNDI name and resource type for OSI-TP / LU6.2
An EJB uses the JNDI name and resource type to address the connection factory.
JNDI name
An Enterprise Java Bean (EJB) in the application server addresses a connection factory via
JNDI (Java Naming and Directory Interface). Internally, the connection factory addresses
the managed connection factory assigned to it and assigns the configured properties to the
connection.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
The connection factory's JNDI name is defined in the <connector-factory> tag by
means of the location attribute. For the EJB that uses this connection factory, this JNDI
name must be mapped to the resource reference in the file orion-ejb-jar.xml using the
tag <res-ref-mapping>.
ResourceType
The connection factory's resource type is defined in the tag
<connectionfactory-interface>. After deployment, the file oc4j-ra.xml contains a
template for each resource type. Communication via OSI-TP / LU6.2 involves the following
resource types:
●
net.fsc.jca.communication.cci.BCOltpConnectionFactory
●
net.fsc.jca.communication.EISOltpConnectionFactory
●
net.fsc.jca.bpel.xml.BpelBCOltpConnectionFactory
Precisely this type must be specified for the EJB which uses this connection factory in the
deployment descriptor ejb-jar.xml, see Section 4.3.2, "Deploying an Enterprise
JavaBean for OSI-TP / LU6.2".
BeanConnect V2.1
99
Outbound communication via OSI-TP / LU6.2
4.3.1.2
Configuration in the application server
Defining configuration properties for OSI-TP / LU6.2
For outbound communication, BeanConnect supports the following connection-specific
configuration properties:
●
bufferedIO
●
connectionURL
●
displayName
●
encoding
●
encodingActive
●
logLevel
●
timeout
●
transactional
The connection which you obtain with a ConnectionFactory.getConnection() call is
preinitialized with these configuration properties.
Use a text editor to change the <config-property> values. Alternatively you can change
the configuration by using the Web GUI. You can save the created oc4j-ra.xml file for
future configurations.
bufferedIO
The bufferedIO configuration property is used to define whether I/O buffering is carried
out between the resource adapter and the proxy. If set, interaction between resource
adapter and proxy is minimized. To reach maximum performance within a production
environment you should set this property to true. During deployment or operation, you can
set this value to false by means of the connection factory MBean to detect user errors as
early as possible during the test.
Definition:
[true | false]
Explanation: Switches IO buffering between resource adapter and proxy on or off.
100
true:
IO buffering is used.
false:
IO buffering is not used.
Default:
true
Example:
<config-property name="bufferedIO" value="true"/>
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
Outbound communication via OSI-TP / LU6.2
connectionURL
For communication via OSI-TP or LU6.2, the connectionURL configuration property
specifies the name of the outbound communication endpoint which stands for a connection
to an EIS partner and was defined in the proxy using the Management Console. The name
begins with a prefix which describes the type of EIS partner, e.g. utm or cics. The name
used in BeanConnect V2.0 and earlier - oltp - continues to be supported for reasons of
compatibility and is used as a synonym for utm in BeanConnect V2.1.
The name of the outbound communication endpoints is a freely definable string. It must be
the same as the corresponding name of the outbound communication endpoint configured
in the proxy, see Section 6.7, "Configuring outbound communication".
Definition:
<type>://<name>
Explanation: <type> Type of the EIS partner, possible values:
utm
The EIS partner is of type openUTM.
cics
The EIS partner is of type CICS.
xatmi-rr The EIS partner is of type XATMI and communication is
conducted using the Request/Reply paradigm.
xatmi-cv The EIS partner is of type XATMI and communication is
conducted using the Conversational paradigm.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
<name> Name of an outbound communication endpoint as it was defined using
the Management Console
Default:
utm://outboundCommunicationEndpoint
Example:
<config-property name="connectionURL"
value="utm://HELLO"/>
displayName
This attribute allows you to define a name for a managed connection factory. This name is
then used by BeanConnect when outputting information about this managed connection
factory, e.g. during the output of MBeans and LogWriter records.
Definition:
[<name>]
Explanation: Freely definable name of a managed connection factory as it is to be used, for
example in MBean and LogWriter output.
Default:
No default value.
If you do not specify a name then the internal name of the managed connection
factory is used. This consists of the prefix "MCF" and a 5-digit number.
Example:
BeanConnect V2.1
<config-property name="displayName"
value="sample application/test"/>
101
Outbound communication via OSI-TP / LU6.2
Configuration in the application server
encoding
The encoding configuration property defines a code table for converting byte code (for
example EBCDIC) to Unicode. These code tables are used for converting byte streams to
strings and vice versa. These conversions are always called implicitly when interactions
(sndString(), rcvString() for example) are executed which contain strings as I/O
parameters.
The code table that is defined with the encoding configuration property is used as default
for the corresponding connection. The bean programmer may determine that a different
code table is to be used for the connection by explicitly calling the
setEncoding(Encoding) method of the EISConnection interface or of the OltpMessageContext interface (see the section "Encoding" on page 334).
Code conversion using this code table is only carried out if encodingActive is actually
activated. You can select this with the encodingActive configuration property or by calling
the method setEncodingActive(true).
There are different definitions for openUTM-P partners and CICS partners.
For UTM partners apply:
Definition:
[<builtin_encoding_table> |
builtin:<builtin_encoding_table> |
jdk:<jdk_encoding_table> |
custom:<encoding_table>]
Explanation: Name of a code table to be used for code conversion.
If no prefix is specified or if the prefix builtin: is specified, you must specify
the name of a built-in code table provided by BeanConnect.
The following built-in code tables are provided:
OSD_EBCDIC_DF03_IRV, OSD_EBCDIC_DF04_1, OSD_EBCDIC_DF04_15, OSD_
EBCDIC_DF04_DRV
Use the prefix jdk: to specify a code table contained in the JDK.
Use the prefix custom: to assign your own code table. Here you must specify
the fully qualified class name of the code table. For further details on using your
own code tables, refer to the Javadoc for BeanConnect.
102
Default:
For openUTM partners, this value is set to "OSD_EBCDIC_DF04_DRV".
Example:
<config-property name="encoding"
value="OSD_EBCDIC_DF03_IRV"/>
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
Outbound communication via OSI-TP / LU6.2
For CICS partners apply:
Definition:
[jdk:<jdk_encoding_table> |
custom:<encoding_table>]
Explanation: Name of a code table to be used for code conversion.
Use the prefix jdk: to specify a code table contained in the JDK.
Use the prefix custom: to assign your own code table. Here you must specify
the fully qualified class name of the code table. For further details on using your
own code tables, refer to the Javadoc for BeanConnect.
Default:
jdk:Cp1047
Example:
<config-property name="encoding"
value="jdk:Cp1250"/>
encodingActive
The encodingActive configuration property specifies whether code conversion is to be
activated.
Definition:
[true | false]
true:
Code conversion according to the settings of the encoding
configuration property is activated.
false:
The default code table of the JDK is used to convert byte streams to
strings.
Default:
false
Example:
<config-property name="encodingActive" value="true"/>
The deployment settings can be overwritten using the setEncodingActive() method
defined in the EISConnection or the OLTPMessageContext interface.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Explanation: Flag specifying whether code conversion is to be activated.
BeanConnect V2.1
103
Outbound communication via OSI-TP / LU6.2
Configuration in the application server
logLevel
This attribute can be used to set the level for the output of log records to a LogWriter for a
connection factory. LogWriters for connection factories are configured in different ways
depending on the employed application server. In the case of OC4J, a LogWriter for a
connection factory must be configured explicitly as otherwise it is not possible to perform
logging at the LogWriter irrespective of the level setting. For more detailed information on
LogWriter configuration and output, see Section 13.4, "LogWriter for connection factories".
Definition:
[NONE | ERROR | INFO | ALL]
Explanation: NONE
No output is written to the LogWriter.
ERROR
Only information relating to exceptions and transaction rollbacks is
written to the LogWriter.
INFO
In addition to the information listed for ERROR, all transaction-related
events are logged, e.g. the beginning or committing of transactions.
ALL
In addition to the information listed for INFO, all events relating to
connection lifecycles are logged. These include, for example, the
requesting or releasing of connection handles by the application or
events which affect pooling.
Default:
NONE
Example:
<config-property name="logLevel" value="INFO"/>
timeout
The timeout configuration property specifies the maximum time the resource adapter
waits for the proxy to answer.
The value specified here must be greater than the maximum time that the EIS system needs
to process a call. If the timer expires, an exception is thrown to the application and the
connection between the resource adapter and the proxy is reinitialized. This generally
causes the transaction to be reset at the EIS partner
Definition:
Time in millisecods.
Explanation: :> 0
:0
104
Maximum time in milliseconds the resource adapter waits.
The resource adapter waits indefinitely.
Default:
300000 (corresponds to 5 minutes)
Example:
<config-property name="timeout" value="300000"/>
BeanConnect V2.1
Outbound communication via OSI-TP / LU6.2
transactional
The transactional configuration property specifies whether the communication between
the application server and the EIS should be transactional. In this case the transaction of
the EIS is included in the transaction of the application server.
Definition:
[true | false]
Explanation: true:
false:
Participation in the application server transaction is activated.
Participation in the application server transaction is deactivated.
Default:
false
Example:
<config-property name="transactional" value="true"/>
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
BeanConnect V2.1
105
Outbound communication via OSI-TP / LU6.2
4.3.1.3
Configuration in the application server
Adapting connection pooling for OSI-TP / LU6.2
For each connection factory in the file oc4j-ra.xml, you can specify how connection
pooling is carried out.
Connection pooling is activated in order to increase the performance. Connections which
are used frequently and by many clients should be defined with large values for maxConnections. For rarely used connections you need not define connection pooling at all. For
more information on connection pooling, refer to the application server documentation.
A connection factory definition with sample settings is shown in Example 4:
Example 4 Connection pooling
<connector-factory location="my_EIS"
connector-name="BeanConnect V2.1 JCA1.5 Connector">
<connectionfactory-interface>net.fsc.jca.communication.EISOltpConnectionFactory
</connectionfactory-interface>
<config-property name="connectionURL" value="utm://HELLO"/> 1
<config-property name="encoding" value="OSD_EBCDIC_DF04_DRV"/> 2
<config-property name="encodingActive" value="true"/>
<<config-property name="timeout" value="300000"/
<config-property name="transactional" value="true"/>
<config-property name="bufferedIO" value="true"/>
<connection-pooling use="private">
<property name="scheme" value="dynamic" />
<property name="maxConnections" value="20" />
<property name="minConnections" value="0" />
<property name="inactivity-timeout-check" value="never" />
<property name="initial-capacity" value="0" />
<property name="inactivity-timeout" value="0" />
</connection-pooling>
<security-config use="none">
</security-config>
</connector-factory>
I
1
2
With connection pooling you should always specify
use=private.
For CICS partners: <config-property name="connectionURL" value="cics://HELLO" /
For CICS partners: <config-property name="encoding" value="jdk:Cp1047"/>
106
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
4.3.1.4
Outbound communication via OSI-TP / LU6.2
Defining security settings (managing sign-on)
If an EJB requests a connection to the EIS with a ConnectionFactory.getConnection() call, this connection is set up in the security context of BeanConnect. In
particular, the authentication data (user name and password) required for the EJB to access
the EIS is assigned when the connection is set up.
EJBs can authenticate themselves to the EIS in two ways:
●
Application-managed authentication
●
Container-managed authentication
It is recommended that container-managed authentication is used.
The basic procedure for application- and container-managed authentication is explained
below.
Application-managed authentication (application-managed sign-on)
In this case, the authentication data must be provided in the program code of the EJB (see
"Interfaces and programming" on page 283). For EJBs which perform authentication
themselves, the <res-auth> tag of the associated EJB deployment descriptor must be
specified as follows:
<res-auth>Application</res-auth>
Example of setting by EJB:
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
getConnection(new PasswordCredential(user, password));
Container-managed authentication (container-managed sign-on)
In this case, the application server regulates the transfer of authentication data. For EJBs
which allow the application server to perform authentication, the <res-auth> tag of the
associated EJB deployment descriptor must be specified as follows:
<res-auth>Container</res-auth>
With container-managed authentication, the authentication data must be specified within a
<security-config> section in the deployment descriptor (in this case: oc4j-ra.xml) for
the resource adapter.
BeanConnect V2.1
107
Outbound communication via OSI-TP / LU6.2
Configuration in the application server
Example 5 Security section in oc4j-ra.xml
The <security-config> section in the file oc4j-ra.xml has the following layout:
...
<connector-factory location="..." connector-name="...">
...
<security-config use="principal-mapping-entries">
<principal-mapping-entries>
<default-mapping>
<res-user>RESTRN</res-user>
<res-password></res-password>
</default-mapping>
<principal-mapping-entry>
<initiating-user>jazn.com/admin</initiating-user>
<res-user>ADMIN</res-user>
<res-password>ADMIN</res-password>
</principal-mapping-entry>
<principal-mapping-entry>
<initiating-user>jazn.com/user</initiating-user>
<res-user>USER</res-user>
<res-password>USERPW</res-password>
</principal-mapping-entry>
</principal-mapping-entries>
</security-config>
</connector-factory>
...
User names and passwords for authentication are highlighted.
108
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
4.3.1.5
Example of an oc4j-ra.xml file
Example 6 shows the definition of the connection-specific configuration properties in
oc4j-ra.xml.
Example 6 Configuration properties in the file oc4j-ra.xml
The section with the connection-specific configuration properties in the file oc4j-ra.xml
has the following layout:
June 8, 2009 7:06 pm
...
<oc4j-connector-factories xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/
oc4j-connector-factories-10_0.xsd" schema-major-version="10"
schema-minor-version="0">
<connector-factory location="my_BC_Factory"
connector-name="BeanConnect V2.1 JCA1.5 Connector">
<connectionfactory-interface>
net.fsc.jca.communication.EISOltpConnectionFactory
</connectionfactory-interface>
<config-property name="connectionURL" value="utm://accountEIS" /> 3
<config-property name="encoding" value="OSD_EBCDIC_DF04_DRV" /> 4
<config-property name="encodingActive" value="true" />
<config-property name="timeout" value="300000" />
<config-property name="transactional" value="true" />
<config-property name="bufferedIO" value="true" />
<connection-pooling use="private">
<config-property name="logLevel" value="INFO"/>
<config-property name="displayName" value="accountEIS"/>
<property name="waitTimeout" value="10" />
<property name="scheme" value="dynamic" />
<property name="maxConnections" value="20" />
<property name="inactivity-timeout-check" value="all" />
<property name="minConnections" value="0" />
<property name="initial-capacity" value="0" />
<property name="inactivity-timeout" value="300" />
</connection-pooling>
<security-config use="none" />
<log>
<file path="D:/temp/log/BeanConnect/accountEIS.log" />
</log>
</connector-factory>
<connector-factory location="my_CCI_factory"
connector-name="BeanConnect V2.1 JCA1.5 Connector">
<connectionfactory-interface>
net.fsc.jca.communication.cci.BCOltpConnectionFactory
© cognitas GmbH 2001-2
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
Outbound communication via OSI-TP / LU6.2
3
4
for CICS partners: <config-property name="connectionURL" value="cics://accountEIS" /
for CICS partners: <config-property name="encoding" value="jdk:Cp1047" />
BeanConnect V2.1
109
Outbound communication via OSI-TP / LU6.2
Configuration in the application server
</connectionfactory-interface>
<config-property name="connectionURL" value="utm://accountEIS" />
<config-property name="encoding" value="OSD_EBCDIC_DF04_DRV" /> 6
<config-property name="encodingActive" value="true" />
<config-property name="timeout" value="300000" />
<config-property name="transactional" value="true" />
<config-property name="bufferedIO" value="true" />
<config-property name="logLevel" value="INFO"/>
<config-property name="displayName" value="cci/accountEIS"/>
<connection-pooling use="private">
<property name="waitTimeout" value="10" />
<property name="scheme" value="dynamic" />
<property name="maxConnections" value="20" />
<property name="inactivity-timeout-check" value="all" />
<property name="minConnections" value="0" />
<property name="initial-capacity" value="0" />
<property name="inactivity-timeout" value="300" />
</connection-pooling>
<security-config use="none" />
</connector-factory>
<log>
<file path="D:/temp/log/BeanConnect/accountEIS.cci.log" />
</log>
</oc4j-connector-factories>
5
6
5
for CICS partners: <config-property name="connectionURL" value="cics://accountEIS" />
for CICS partners: <config-property name="encoding" value="jdk:Cp1047" />
110
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
Deploying an Enterprise JavaBean (EJB)
4.3.2 Deploying an Enterprise JavaBean for OSI-TP / LU6.2
When deploying an EJB which is designed to use BeanConnect for outbound communication, you must link the EJB to the BeanConnect deployment. In the case of OC4J, this is
done using the file orion-ejb-jar.xml. The following files are relevant for deploying an
EJB:
●
Code file of the EJB (.java or .class file)
●
Standardized deployment descriptor of the EJB (ejb-jar.xml)
●
Application server-specific deployment descriptor of the EJB
(with OC4J: orion-ejb-jar.xml)
●
Application server-specific deployment descriptor for the resource adapter
(with OC4J: oc4j-ra.xml)
When an EJB is deployed, the resource reference used by the Bean developer is made
known to the application server in the deployment descriptor of the EJB. In addition, a
resource type is assigned to the resource reference.
BeanConnect supports the following resource types, which represent the different types of
connections that can be used:
●
For OSI-TP or LU6.2 communication using the BeanConnect interface:
net.fsc.jca.communication.EISOltpConnectionFactory
●
For OSI-TP or LU6.2 communication using the CCI interface:
net.fsc.jca.communication.cci.BCOltpConnectionFactory
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
●
For OSI-TP or LU6.2 communication using the CCI interface:
net.fsc.jca.beannconnect.bpel.xml.BpelBCOltpConnectionFactory
You must specify the resource type in the following files:
●
oc4j-ra.xml with the <connectionfactory-interface> tag
●
ejb-jar.xml with the <res-type> tag
The sections of the code file of the EJB as well as of the files ejb-jar.xml,
orion-ejb-jar.xml and oc4j-ra.xml that are relevant for the deployment of the EJB
are described in detail below. The bold (partial) path names indicate the relationships
between the individual files.
BeanConnect V2.1
111
Deploying an Enterprise JavaBean (EJB)
●
Configuration in the application server
Code file of the EJB (.java or .class file)
The JNDI lookup for the ConnectionFactory object via a resource reference (coded
name) takes place here. In the following example, the resource reference used is
eis/Part1Dial.
...
cf=(EISConnectionFactory)
ic.lookup("java:comp/env/eis/Part1Dial")
...
●
Deployment descriptor of the EJB (ejb-jar.xml)
Here the resource reference (ConnectionFactory object) which the EJB accesses is
specified. In addition, a resource type is assigned to the resource reference. In the
following example net.fsc.jca.communication.EISOltpConnectionFactory
is used as the resource type.
Please note that for <res-sharing-scope> you must always specify
Unshareable.
<session>
<ejb-name>SimpleBeanConnect</ejb-name>
...
<resource-ref>
<res-ref-name>eis/Part1Dial</res-ref-name>
<res-type>
net.fsc.jca.communication.EISOltpConnectionFactory
</res-type>
<res-sharing-scope>Unshareable</res-sharing-scope>
...
</resource-ref>
</session>
●
Application server-specific deployment descriptor of the EJB (with OC4J:
orion-ejb-jar.xml)
Here the link (mapping) is defined between the coded name (logical reference (in the
following example: eis/Part1Dial) and the real JNDI name (in the following example:
partner1Dial).
<session-deployment name="SimpleBeanConnect">
<resource-ref-mapping name="eis/Part1Dial"
location="Part1Dial"/>
</session-deployment>
112
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
●
Deploying an Enterprise JavaBean (EJB)
Deployment descriptor for the resource adapter (with OC4J: oc4j-ra.xml):
Here the connection factory is configured for deployment in the application server
instance
(here: OC4J) is configured and linked to the resource reference via the JNDI name
(here: partner1Dial). Via the configuration of the connection factory in the application
server instance, the resource adapter receives the URL of the service (in the following
code fragment: utm://echo 7) and of the EIS partner.
June 8, 2009 7:06 pm
<oc4j-connector-factories>
<connector-factory location="partner1Dial"
connector-name="BeanConnect V2.1 JCA 1.5
Connector">
<connectionfactory-interface>
net.fsc.jca.communication.EISOltpConnectionFactory
</connectionfactory-interface>
<config-property name="connectionURL"
value="utm://echo"/> 8
...
</connector-factory>
</oc4j-connector-factories>
The value specified in <connectionfactory-interface> must be identical to the
value that is specified with the <res-type> tag in the file ejb-jar.xml.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
An additional configuration step is required on the proxy. For each outbound communication endpoint name that is specified in a connectionURL configuration property in
the file oc4j-ra.xml, you must configure a corresponding outbound communication
endpoint of the same name in the proxy. The outbound communication endpoint
definition maps the symbolic service name onto a real service name in the EIS partner
application. You can carry out configuration of an outbound communication endpoint
using the Management Console (see "Configuring outbound communication endpoints"
on page 217).
7
8
for CICS partners: cics://echo
for CICS partners: value="cics://echo" />
BeanConnect V2.1
113
Outbound communication via UPIC
Configuration in the application server
4.4 Configuring outbound communication via UPIC
When communications are performed via UPIC, you simply need to define the
connection-specific properties in the file oc4j-ra.xml. In this case, the file ra.xml is not
relevant.
4.4.1 Defining connection-specific properties for UPIC in oc4j-ra.xml
The file oc4j-ra.xml is the OC4J-specific deployment descriptor for the resource adapter.
This deployment descriptor specifies the settings that are required for outbound communication with EIS partners. The communications are conducted via so-called connection
factories.
After deployment of the resource adapter, the directory
<J2EE_HOME>/application-deployments/default/<RA_name> contains a predefined
file oc4j-ra.xml with templates for the different types of connection factories.
<J2EE_HOME> stands for the directory <OC4J_install_dir>/j2ee/home.
Connection factories
You must configure at least one connection factory for each EIS partner. However, you may
also configure multiple connection factories with different properties for one and the same
EIS partner.
A connection factory's properties are defined in a <connector-factory> entry.
You make the following specifications for each connection factory:
114
●
JNDI name and resource type: These are also required when deploying the EJB and
make it possible to assign the connection factory to the EJB.
●
Configuration properties: These are the parameters that apply to the connection to the
EIS partners.
●
Connection pooling: Connection pooling is an application server functionality. It helps
improve performance on frequently used connections.
●
Security settings: This is the data required when signing on at the EIS partner, e.g. user
ID and password. If this data is encoded directly in the EJB then the corresponding
entry can be omitted in the deployment descriptor.
BeanConnect V2.1
4.4.1.1
Outbound communication via UPIC
Defining the JNDI name and resource type for UPIC
An EJB uses the JNDI name and resource type to address its connection factory.
JNDI name
An Enterprise Java Bean (EJB) in the application server addresses a connection factory via
JNDI (Java Naming and Directory Interface). Internally, the connection factory addresses
the managed connection factory assigned to it and assigns the configured properties to the
connection.
The connection factory's JNDI name is defined in the <connector-factory> tag by
means of the location attribute. For the EJB that uses this connection factory, this JNDI
name must be mapped to the resource reference in the file orion-ejb-jar.xml using the
tag <res-ref-mapping>.
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Resource type
The connection factory's resource type is defined in the tag
<connectionfactory-interface>. After deployment, the file oc4j-ra.xml contains a
template for each resource type. The following resource types are relevant for communication via UPIC:
●
net.fsc.jca.communication.cci.BCUpicConnectionFactory
●
net.fsc.jca.communication.EISUpicConnectionFactory
●
net.fsc.jca.bpel.xml.BpelBCUpicConnectionFactory
Precisely this type must be specified for the EJB which uses this connection factory in the
deployment descriptor ejb-jar.xml, see Section 4.4.2, "Deploying an Enterprise
JavaBean for UPIC".
4.4.1.2
Setting the configuration properties for UPIC
BeanConnect supports the following connection-specific configuration properties for
outbound communication:
●
connectionURL
●
displayName
●
encoding
●
encodingActive
●
logLevel
●
timeout
BeanConnect V2.1
115
Outbound communication via UPIC
Configuration in the application server
The connection which you obtain with a ConnectionFactory.getConnection() call is
preinitialized with these configuration properties.
You can use a text editor to modify the values for the configuration properties
(<config-property>). You can also make these changes via the graphical user interface.
You can save the generated oc4j-ra.xml file for subsequent configurations.
connectionURL
connectionURL defines the EIS partner and, if required, the service that is to be
addressed.
The getConnection() method of a connection factory supplies a connection with the
appropriate configuration properties which can be used by both the EISConnection or the
EISUpicConnection interface.
Definition:
upic://<host>[:<port>]/[<local>:]<remote>[/<tac>]
[?tsel[;tsel]]
Explanation: host
Host on which the openUTM partner application is running.
port
Port number of the port at which the openUTM partner application
listens (optional). Default: 102
local
Local name of the client (PTERM). Default: UPIC
remote
Name of the openUTM partner application (BCAMAPPL or
APPLINAME).
tac
TAC (ServiceName) which is to be called in the openUTM partner
application (optional).
This value can be overwritten by methods which are defined in the
EISConnection or BCInteractionSpec interface.
tsel
TSEL format definition for the locale address (lt) or remote
addresses (rt) in the form:
[lt={a|e|t}]|[rt={a|e|t}]
a =ASCII, e = EBCDIC, t = TRANSDATA
Default:
upic://<host>:<port>/application/service
Example:
EIS partner in BS2000:
<config-property name="connectionURL"
value="upic://BS2HOST/UTMAPP/INFO"/>
EIS partner on Solaris/Linux/Windows systems:
<config-property name="connectionURL"
value="upic://unixhost:24000/UTMAPP/INFO?rt=a"/>
116
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
Outbound communication via UPIC
displayName
This attribute allows you to define a name for a managed connection factory. This name is
then used by BeanConnect when outputting information about this managed connection
factory, e.g. during the output of MBeans and LogWriter records.
Definition:
[<name>]
Explanation: Freely definable name of a managed connection factory as it is to be used, for
example, in MBean and LogWriter output.
Default:
No default value.
If you do not enter a name then the internal name of the managed connection
factory is used. This consists of the prefix "MCF" and a 5-digit number.
Example:
<config-property name="displayName"
value="sample application/test"/>
encoding
The encoding configuration property defines a code table for converting byte code (for
example EBCDIC) to Java Unicode. These code tables are used for converting byte
streams to strings and vice versa. These conversions are always called implicitly when
interactions (sndString(), rcvString() for example) are executed which contain strings
as I/O parameters.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
The code table that is defined with the encoding configuration property is used as default
for the corresponding connection. The Bean programmer may determine that a different
code table is to be used for the connection by explicitly calling the
setEncoding(Encoding) method of the EISConnection interface or of the
OltpMessageContext interface.
Code conversion using this code table is only carried out if encodingActive is actually
activated. You can select this with the encodingActive configuration property or by calling
the method setEncodingActive(true).
Definition:
BeanConnect V2.1
[<builtin_encoding_table> |
builtin:<builtin_encoding_table>|
jdk:<jdk_encoding_table>|
custom:<encoding_table>]
117
Outbound communication via UPIC
Configuration in the application server
Explanation: Name of a code table to be used for code conversion.
If no prefix is specified or if the prefix builtin: is specified, you must specify
the name of a built-in code table provided by BeanConnect.
The following built-in code tables are provided:
OSD_EBCDIC_DF03_IRV, OSD_EBCDIC_DF04_1, OSD_EBCDIC_DF04_15,
OSD_EBCDIC_DF04_DRV
Use the prefix jdk: to specify a code table contained in the JDK.
Use the prefix custom: to assign your own code table. Here you must specify
the fully qualified class name of the code table. For further details on using your
own code tables, refer to the Javadoc for BeanConnect
Default:
OSD_EBCDIC_DF04_DRV
Example:
<config-property name="encoding"
value="OSD_EBCDIC_DF03_IRV"/>
encodingActive
The encodingActive configuration property specifies whether code conversion is to be
activated. The encodingActive configuration property is mapped directly onto the setEncodingActive(boolean activate) method of the EISConnection interface.
Definition:
[true | false]
Explanation: Flag specifying whether code conversion is to be activated.
true
Code conversion according to the settings of the encoding
configuration property is activated.
false
The default code table of the JDK is used to convert byte streams to
strings.
Default:
false
Example:
<config-property name="encodingActive" value="true"/>
The deployment settings can be overwritten using the setEncodingActive() method
defined in the EISConnection interface. It is also possible to activate customer-defined
classes for code conversion (setEncoding(Encoding)) at this interface.
118
BeanConnect V2.1
Outbound communication via UPIC
logLevel
This attribute can be used to set the level for the output of log records to a LogWriter for a
connection factory. LogWriters for connection factories are configured in different ways
depending on the employed application server. In the case of OC4J, a LogWriter for a
connection factory must be configured explicitly as otherwise it is not possible to perform
logging at the LogWriter irrespective of the level setting. For more detailed information on
LogWriter configuration and output, see Section 13.4, "LogWriter for connection factories".
Definition:
[NONE | ERROR | INFO | ALL]
Explanation: NONE
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
No output is written to the LogWriter.
ERROR
Only information relating to exceptions is written to the LogWriter.
INFO
Same output as for ERROR.
ALL
In addition to the information listed for INFO/ERROR, all events
relating to the connection lifecycle are logged. These include, for
example, the requesting and releasing of connection handles by the
application or events relating to pooling.
Default:
NONE
Example:
<config-property name="logLevel" value="INFO"/>
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
timeout
The timeout configuration property defines the maximum wait time for receive() or
call() calls. This property is mapped directly onto the socket timeout of the Java socket
implementation.
The value specified here must be greater than the maximum time that the EIS system needs
to process a call. If the timer expires, an exception is thrown to the application and the
connection between the resource adapter and the proxy is reinitialized.
Definition:
Timeout value (in milliseconds)
Default:
30000 (corresponds to 30 seconds)
Example:
<config-property name="timeout" value="50000"/>
BeanConnect V2.1
119
Outbound communication via UPIC
4.4.1.3
Configuration in the application server
Adapting connection pooling for UPIC
For each connection factory in the file oc4j-ra.xml, you can specify how connection
pooling is carried out.
Connection pooling is activated in order to increase the performance. Connections which
are used frequently and by many clients should be defined with large values for maxConnections. For rarely used connections you need not define connection pooling at all.
A connection factory definition with sample settings is listed in Example 7:
Example 7 Connection pooling
<connector-factory location="my_EIS"
connector-name="BeanConnect V2.1 JCA1.5 Connector">
<connectionfactory-interface>net.fsc.jca.communication.EISUpicConnectionFactory
</connectionfactory-interface>
<config-property name="connectionURL" value="upic://HOST134/ACCOUNT/GETINF"/>
<config-property name="encoding" value="OSD_EBCDIC_DF04_DRV"/>
<config-property name="encodingActive" value="true"/>
<connection-pooling use="private">
<property name="scheme" value="dynamic" />
<property name="maxConnections" value="20" />
<property name="minConnections" value="0" />
<property name="inactivity-timeout-check" value="never" />
<property name="initial-capacity" value="0" />
<property name="inactivity-timeout" value="0" />
</connection-pooling>
<security-config use="none">
</security-config>
</connector-factory>
I
120
With connection pooling you should always specify
use=private.
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
4.4.1.4
Outbound communication via UPIC
Defining security settings (managing sign-on)
If an EJB requests a connection to the EIS with a ConnectionFactory.getConnection() call, this connection is set up in the security context of BeanConnect. In
particular, the authentication data (user name and password) required for the EJB to access
the EIS is defined when the connection is set up.
EJBs can authenticate themselves to the EIS in two ways:
●
Application-managed authentication
●
Container-managed authentication
It is recommended that container-managed authentication is used.
The basic procedure for defining application- and container-managed authentication is
explained below.
Application-managed authentication (application-managed sign-on)
In this case, the authentication data must be provided in the program code of the EJB (see
"Interfaces and programming" on page 283). For EJBs which perform authentication
themselves, the <res-auth> tag of the associated EJB deployment descriptor must be
specified as follows:
<res-auth>Application</res-auth>
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Container-managed authentication (container-managed sign-on)
In this case, the application server regulates the transfer of authentication data. For EJBs
which allow the application server to perform authentication, the <res-auth> tag of the
associated EJB deployment descriptor must be specified as follows:
<res-auth>Container</res-auth>
With container-managed authentication, the authentication data must be specified within a
<security-config> section in the deployment descriptor (in this case: oc4j-ra.xml) for
the resource adapter.
BeanConnect V2.1
121
Outbound communication via UPIC
Configuration in the application server
Example 8 Security section in oc4j-ra.xml
The <security-config> section in the file oc4j-ra.xml has the following layout:
...
<connector-factory location="..." connector-name="...">
...
<security-config use="principal-mapping-entries">
<principal-mapping-entries>
<default-mapping>
<res-user>RESTRN</res-user>
<res-password></res-password>
</default-mapping>
<principal-mapping-entry>
<initiating-user>jazn.com/admin</initiating-user>
<res-user>ADMIN</res-user>
<res-password>ADMIN</res-password>
</principal-mapping-entry>
<principal-mapping-entry>
<initiating-user>jazn.com/user</initiating-user>
<res-user>USER</res-user>
<res-password>USERPW</res-password>
</principal-mapping-entry>
</principal-mapping-entries>
</security-config>
</connector-factory>
...
User names and passwords for authentication are highlighted.
4.4.1.5
Example of an oc4j-ra.xml file
Example 9 shows the definition of the configuration properties in the file oc4j-ra.xml.
Example 9 Configuration properties in the file oc4j-ra.xml
The section with the configuration properties in oc4j-ra.xml has the following layout:
...
<oc4j-connector-factories xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/
oc4j-connector-factories-10_0.xsd" schema-major-version="10"
schema-minor-version="0">
<connector-factory location="my_BC_factory"
connector-name="BeanConnect V2.1 JCA1.5 Connector">
<connectionfactory-interface>
net.fsc.jca.communication.EISUpicConnectionFactory
</connectionfactory-interface>
<config-property name="connectionURL"
122
BeanConnect V2.1
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
Outbound communication via UPIC
value="upic://BS2HOST/UTMAPP/INFO"/>
<config-property name="encoding" value="OSD_EBCDIC_DF04_DRV" />
<config-property name="encodingActive" value="true" />
<config-property name="timeout" value="30000" />
<config-property name="logLevel" value="INFO"/>
<config-property name="displayName" value="upic/UTMAPP/INFO"/>
<connection-pooling use="private">
<property name="waitTimeout" value="10" />
<property name="scheme" value="dynamic" />
<property name="maxConnections" value="20" />
<property name="inactivity-timeout-check" value="all" />
<property name="minConnections" value="0" />
<property name="initial-capacity" value="0" />
<property name="inactivity-timeout" value="120" />
</connection-pooling>
<security-config use="none" />
<log>
<file path="D:/temp/log/BeanConnect/upic.UTMAPP.INFO.log" />
</log>
</connector-factory>
<connector-factory location="my_CCI_factory"
connector-name="BeanConnect V2.1 JCA1.5 Connector">
<connectionfactory-interface>net.fsc.jca.communication.cci.
BCUpicConnectionFactory</connectionfactory-interface>
<config-property name="connectionURL"
value="upic://BS2HOST/UTMAPP/INFO" />
<config-property name="encoding" value="OSD_EBCDIC_DF04_DRV" />
<config-property name="encodingActive" value="true" />
<config-property name="timeout" value="30000" />
<config-property name="logLevel" value="INFO"/>
<config-property name="displayName" value="upic/cci/UTMAPP/INFO"/>
<connection-pooling use="private">
<property name="waitTimeout" value="10" />
<property name="scheme" value="dynamic" />
<property name="maxConnections" value="20" />
<property name="inactivity-timeout-check" value="all" />
<property name="minConnections" value="0" />
<property name="initial-capacity" value="0" />
<property name="inactivity-timeout" value="300" />
</connection-pooling>
<security-config use="none" />
<log>
<file path="D:/temp/log/BeanConnect/upic.cci.UTMAPP.INFO.log" />
</log>
</connector-factory>
</oc4j-connector-factories>
BeanConnect V2.1
123
Outbound communication via UPIC
Configuration in the application server
4.4.2 Deploying an Enterprise JavaBean for UPIC
When deploying an EJB which is designed to use BeanConnect for outbound communication, you must link the EJB to the BeanConnect deployment. In the case of OC4J, this is
done using the file orion-ejb-jar.xml. The following files are relevant for deploying an
EJB:
●
Code file of the EJB (.java or .class file)
●
Standardized deployment descriptor of the EJB (ejb-jar.xml)
●
Application server-specific deployment descriptor of the EJB (with OC4J:
orion-ejb-jar.xml)
●
Application server-specific deployment descriptor for the resource adapter
(with OC4J: oc4j-ra.xml)
When an EJB is deployed, the resource reference used by the Bean developer is made
known to the application server in the deployment descriptor of the EJB. In addition, a
resource type is assigned to the resource reference.
BeanConnect supports the following resource types, which represent the different types of
connections that can be used:
●
For UPIC communication using the BeanConnect interface:
net.fsc.jca.communication.EISUpicConnectionFactory
●
For UPIC communication using the CCI interface:
net.fsc.jca.communication.cci.BCUpicConnectionFactory
●
For UPIC communication using the BPEL interface:
net.fsc.jca.BeanConnect.bpel.xml.BpelBCUpicConnectionFactory
You must specify the resource type in the following files:
●
oc4j-ra.xml with the <connectionfactory-interface> tag
●
ejb-jar.xml with the <res-type> tag
The sections of the code file of the EJB as well as of the files ejb-jar.xml,
orion-ejb-jar.xml and oc4j-ra.xml that are relevant for the deployment of the EJB
are described in detail below. The bold (partial) path names indicate the relationships
between the individual files.
124
BeanConnect V2.1
●
Outbound communication via UPIC
Code file of the EJB (.java or .class file)
The JNDI lookup for the ConnectionFactory object via a resource reference (coded
name) takes place here. In the following example, the resource reference used is
eis/Part1Dial.
...
cf=(EISConnectionFactory)
ic.lookup("java:comp/env/eis/Part1Dial")
...
●
Deployment descriptor of the EJB (ejb-jar.xml)
Here the resource reference (ConnectionFactory object) which the EJB accesses is
specified. In addition, a resource type is assigned to the resource reference. In the
following example net.fsc.jca.communication.EISUpicConnectionFactory
is used as the resource type. For <res-sharing-scope> you always specify
Unshareable.
<session>
<ejb-name>SimpleBeanConnect</ejb-name>
...
<resource-ref>
<res-ref-name>eis/Part1Dial</res-ref-name>
<res-type>
net.fsc.jca.communication.EISUpicConnectionFactory
</res-type>
<res-sharing-scope>Unshareable</res-sharing-scope>
...
</resource-ref>
</session>
●
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
Application server-specific deployment descriptor of the EJB (with OC4J:
orion-ejb-jar.xml)
Here the link (mapping) is implemented between the coded name (logical reference (in
the following example: eis/Part1Dial) and the real JNDI name (in the following
example: partner1Dial).
<session-deployment name="SimpleBeanConnect">
<resource-ref-mapping name="eis/Part1Dial"
location="partner1Dial"/>
</session-deployment>
BeanConnect V2.1
125
Outbound communication via UPIC
●
Configuration in the application server
Deployment descriptor for the resource adapter (with OC4J: oc4j-ra.xml):
Here the connection factory for deployment in the application server
(here: OC4J) is configured and linked to the resource reference via the JNDI name
(here: partner1Dial). The configuration of the connection factory in the application
server informs the resource adapter of the URL of the service (in the following code
fragment: upic://BS2HOST/UTMAPP/INFO) and the EIS partner.
<oc4j-connector-factories>
<connector-factory location="partner1Dial"
connector-name="BeanConnect V2.0 JCA 1.5 Connector">
<connectionfactory-interface>
net.fsc.jca.communication.EISUpicConnectionFactory
</connectionfactory-interface>
<config-property name="connectionURL"
value="upic://BS2HOST/UTMAPP/INFO"/>
...
</connector-factory>
</oc4j-connector-factories>
The value specified in <connectionfactory-interface> must be identical to the
value that is specified with the <res-type> tag in the file ejb-jar.xml.
126
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
Inbound communication
4.5 Setting configuration properties for inbound communication
At least one OLTP message-driven bean has to be deployed when using inbound communication. The OLTP message-driven bean must support the EJB specification V2.1 and
implement one of the following message listener interfaces:
●
net.fsc.jca.communication.AsyncOltpMessageListener
●
net.fsc.jca.communication.OltpMessageListener
●
javax.resource.cci.MessageListener
A deployment descriptor has to be created in the file ejb-jar.xml for deploying the OLTP
message-driven bean. If the file ejb-jar.xml is not created automatically by an IDE during
the bean development process, you must create this file manually. Additionally, in most
cases, the deployment of an OLTP message-driven bean requires an
application server-specific deployment descriptor. In the case of OC4J, the application
server-specific deployment descriptor is stored in the file orion-ejb-jar.xml. Examples
of an ejb-jar.xml and an orion-ejb-jar.xml file for an OLTP message-driven bean
are shown in Example 10 on page 131 and in Example 11 on page 134.
4.5.1 Configuration properties in the ejb-jar.xml
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
The following properties have to be set in the deployment descriptor (ejb-jar.xml) of the
OLTP message-driven bean:
●
The messaging-type property specifies the message listener interface used by the
OLTP message-driven bean.
●
The activation-config properties refer to the specified message listener interface.
Each of the properties are specified in a separate activation-config-property
element within the activation-config element of the file ejb-jar.xml.
The following activation-config properties are available:
encoding
encodingActive
messageEndpoint
redeliveryThreshold
The properties for the file ejb-jar.xml are described in detail below.
messaging-type
The messaging-type property specifies the message listener interface used by the OLTP
message-driven bean.
BeanConnect V2.1
127
Inbound communication
Configuration in the application server
Definition:
Message listener interface used by the OLTP message-driven bean
Default:
–
Example:
<messaging-type>
net.fsc.jca.communication.AsyncOltpMessageListener
</messaging-type>
messageEndpoint
The messageEndpoint activation-config property specifies the name of the message
endpoint. Note that the message endpoint name specified here must be identical to the
name of the inbound message endpoint specified when configuring the proxy using the
Management Console (see "Configuring inbound message endpoints" on page 219).
Definition:
Name of the message endpoint.
Default:
–
Example:
<activation-config-property>
<activation-config-property-name>messageEndpoint
</activation-config-property-name>
<activation-config-property-value>SampleAsynOltpMdb
</activation-config-property-value>
</activation-config-property>
encoding
The encoding activation-config property defines a code table for converting EIS-specific
byte code (for example EBCDIC) to Unicode.
The property specified here is overwritten if the message-driven bean is called by an
inbound service to which a Partner Encoding was assigned in the Management Console
during the configuration of the proxy.
Definition:
128
[<builtin_encoding_table> |
builtin:<builtin_encoding_table> |
jdk:<jdk_encoding_table> |
custom:<encoding_table>]
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
Inbound communication
Explanation: Name of a code table to be used for code conversion.
If no prefix is specified or if the prefix builtin: is specified, you must specify
the name of a built-in code table provided by BeanConnect.
The following code tables are provided:
OSD_EBCDIC_DF03_IRV, OSD_EBCDIC_DF04_1, OSD_EBCDIC_DF04_15,
OSD_EBCDIC_DF04_DRV
Use the prefix jdk: to specify a code table contained in the JDK.
Use the prefix custom: to assign your own code table. Here you must specify
the fully qualified class name of the code table. For further details on using your
own code tables, refer to the Javadoc for BeanConnect
Default:
OSD_EBCDIC_DF04_DRV
Example:
for openUTM partners:
<activation-config-property>
<activation-config-property-name>encoding
</activation-config-property-name>
<activation-config-property-value>OSD_EBCDIC_DF04_15
</activation-config-property-value>
</activation-config-property>
for CICS partners:
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
<activation-config-property>
<activation-config-property-name>encoding
</activation-config-property-name>
<activation-config-property-value>jdk:Cp1047
</activation-config-property-value>
</activation-config-property>
encodingActive
The encodingActive activation-config property specifies whether code conversion is to
be activated.
encodingActive is set to true irrespective of the value specified here if the
message-driven bean is called by an inbound service to which a Partner Encoding was
assigned in the Management Console during the configuration of the proxy
Definition:
[true | false]
Explanation: Flag specifying whether code conversion is to be activated.
Default:
BeanConnect V2.1
true:
Code conversion according to the settings of the encoding
activation-config property is activated.
false:
The default code table of the JDK is used to convert byte streams to
strings.
false
129
Inbound communication
Example:
Configuration in the application server
<activation-config-property>
<activation-config-property-name>encodingActive
</activation-config-property-name>
<activation-config-property-value>true
</activation-config-property-value>
</activation-config-property>
redeliveryThreshold
The redeliveryThreshold activation-config property defines the number of additional
attempts to deliver the message if the transaction is rolled back. This property can only be
set for asynchronous OLTP message-driven beans, i.e. for OLTP message-driven beans
which implement the message listener interface net.fsc.jca.communication.AsyncOltpMessageListener. The message listener interface is specified in the
messaging-type property.
The property only takes effect if the OLTP message-driven bean has been deployed with
the transaction attribute Required. In this case, the onMessage method is called inside a
transaction which has been started by the proxy (never by the EIS). If this transaction is
reset, the message is delivered again, unless the generated threshold has been exceeded.
Definition:
Number of additional redelivery attempts if an error occurs.
Minimum value = 0
Maximum value = 254
130
Default:
0, i.e. the message is not delivered again.
Example:
<activation-config-property>
<activation-config-property-name>redeliveryThreshold
</activation-config-property-name>
<activation-config-property-value>1
</activation-config-property-value>
</activation-config-property>
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
4.5.2 Examples for ejb-jar.xml and orion-ejb-jar.xml
Example 10 ejb-jar.xml file
The following code extract shows a deployment descriptor ejb-jar.xml for a JAR file that
describes three OLTP message-driven beans. The OLTP message-driven beans implement
three different message listener interfaces.
June 8, 2009 7:06 pm
<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd" version="2.1"
xmlns="http://java.sun.com/xml/ns/j2ee">
<description xml:lang="en">Code Samples for Inbound Communication</description>
<display-name xml:lang="en">SampleMessageDrivenBeans</display-name>
enterprise-beans>
<message-driven>
<description xml:lang="en">
Code Sample for Dialog Inbound Communication
</description>
<ejb-name>SampleDialogOltpMdbBean</ejb-name>
<ejb-class>net.fsc.jca.beanconnect.oltpmdb.SampleDialogOltpMdbBean
</ejb-class>
<messaging-type>net.fsc.jca.communication.OltpMessageListener
</messaging-type>
<transaction-type>Container</transaction-type>
<activation-config>
<activation-config-property>
<activation-config-property-name>messageEndpoint
</activation-config-property-name>
<activation-config-property-value>SampleDialogOltpMdb
</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>encodingActive
</activation-config-property-name>
<activation-config-property-value>true
</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>encoding
</activation-config-property-name>
<activation-config-property-value>OSD_EBCDIC_DF04_159
</activation-config-property-value>
</activation-config-property>
</activation-config>
© cognitas GmbH 2001-2
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
Inbound communication
9
For CICS partners: <activation-config-property-value>jdk:Cp1047
BeanConnect V2.1
131
Inbound communication
Configuration in the application server
</message-driven>
<message-driven>
<description xml:lang="en">
Code Sample for Asynchronous Inbound Communication
</description>
<ejb-name>SampleAsynOltpMdbBean</ejb-name>
<ejb-class>net.fsc.jca.beanconnect.oltpmdb.SampleAsynOltpMdbBean</ejb-class>
<messaging-type>net.fsc.jca.communication.AsyncOltpMessageListener
</messaging-type>
<transaction-type>Container</transaction-type>
<activation-config>
<activation-config-property>
<activation-config-property-name>messageEndpoint
</activation-config-property-name>
<activation-config-property-value>SampleAsynOltpMdb
</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>encodingActive
</activation-config-property-name>
<activation-config-property-value>true
</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>redeliveryThreshold
</activation-config-property-name>
<activation-config-property-value>1</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>encoding
</activation-config-property-name>
<activation-config-property-value>OSD_EBCDIC_DF04_1510
</activation-config-property-value>
</activation-config-property>
</activation-config>
</message-driven>
<message-driven>
<description xml:lang="en">
Code Sample for CCI Inbound Communication</description>
<ejb-name>SampleCciOltpMdbBean</ejb-name>
<ejb-class>net.fsc.jca.beanconnect.oltpmdb.SampleCciOltpMdbBean</ejb-class>
<messaging-type>javax.resource.cci.MessageListener</messaging-type>
<transaction-type>Bean</transaction-type>
<activation-config>
<activation-config-property>
<activation-config-property-name>messageEndpoint
10
For CICS partners: <activation-config-property-value>jdk:Cp1047
132
BeanConnect V2.1
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
Inbound communication
</activation-config-property-name>
<activation-config-property-value>SampleCciOltpMdbBean
</activation-config-property-value>
</activation-config-property>
</activation-config>
</message-driven>
</enterprise-beans>
<assembly-descriptor>
<container-transaction>
<method>
<ejb-name>SampleDialogOltpMdbBean</ejb-name>
<method-name>onMessage</method-name>
<method-params>
<method-param>net.fsc.jca.communication.OltpMessage</method-param>
</method-params>
</method>
<trans-attribute>Required</trans-attribute>
</container-transaction>
<container-transaction>
<method>
<ejb-name>SampleAsynOltpMdbBean</ejb-name>
<method-name>onMessage</method-name>
<method-params>
<method-param>net.fsc.jca.communication.OltpMessage</method-param>
</method-params>
</method>
<trans-attribute>Required</trans-attribute>
</container-transaction>
<container-transaction>
<method>
<ejb-name>SampleCciOltpMdbBean</ejb-name>
<method-name>onMessage</method-name>
<method-params>
<method-param>net.fsc.jca.communication.OltpMessage</method-param>
</method-params>
</method>
<trans-attribute>Required</trans-attribute>
</container-transaction>
</assembly-descriptor>
</ejb-jar>
BeanConnect V2.1
133
Inbound communication
Configuration in the application server
Example 11 orion-ejb-jar.xml file
In the application-specific deployment descriptor orion-ejb-jar.xml, the value of the
message-driven-deployment element's resource-adapter attribute must correspond
to the resource adapter name that was specified for -name when the resource adapter was
deployed using the OC4J admin.jar utility (see Section 4.2.2.1, "Deploying the resource
adapter").
The following code extract shows a deployment descriptor for the three OLTP
message-driven beans from the Example 10, "ejb-jar.xml file".
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE orion-ejb-jar PUBLIC
"-//Evermind//DTD Enterprise JavaBeans 1.1 runtime//EN"
"http://xmlns.oracle.com/ias/dtds/orion-ejb-jar.dtd">
<orion-ejb-jar deployment-version="10.1.3.3" deployment-time="ed17605434">
<enterprise-beans>
<message-driven-deployment name="SampleDialogOltpMdb"
resource-adapter="BeanConnect"></message-driven-deployment>
<message-driven-deployment name="SampleAsynOltpMdb"
resource-adapter="BeanConnect"></message-driven-deployment>
<message-driven-deployment name="SampleCciOltpMdb"
resource-adapter="BeanConnect"></message-driven-deployment>
</enterprise-beans>
<assembly-descriptor>
<default-method-access>
<security-role-mapping name="&lt;default-ejb-caller-role&gt;"
impliesAll="true"/>
</default-method-access>
</assembly-descriptor>
</orion-ejb-jar>
134
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
Preparing resource adapter logging
4.6 Preparing resource adapter logging
The file BeanConnect.log4j.properties.xml is shipped with the resource adapter. It is
contained in the file BC21A00_RA.jar (see Section 3.4, "Installing a BeanConnect
resource adapter"). In Version 2.1, the resource adapter is installed with the Java archive
BC21A00_RA.jar. The log4j property file is located in the config subdirectory of the
resource adapter's installation directory.
This directory contains the following four log4j property files:
1. BeanConnect.log4j.properties.xml
2. BeanConnect.log4j.properties_debug.xml
3. BeanConnect.log4j.properties_default.xml
4. BeanConnect.log4j.properties_error.xml
The first and third files are identical. In normal operation, you should use the first file.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Copy this file to the directory <J2EE_HOME>/config (OC4J specific). The file contains
settings for the logging of the resource adapter. You can subsequently extend or reduce the
scope of logging, see Section 13.5.1, "Overview of logging in the BeanConnect resource
adapter".
BeanConnect V2.1
135
Multiple resource adapter mode
Configuration in the application server
4.7 Special characteristics of multiple resource adapter mode
In a multiple resource adapter configuration, several resource adapters work together with
one proxy instance. A maximum of 32 resource adapter instances are possible for each
proxy instance. A unique index is assigned to each resource adapter instance. This index
must be entered in the file ra.xml, see below.
Multiple resource adapter mode is possible for both outbound communication via OSI-TP /
LU6.2 and for inbound communication.
In multiple resource adapter mode, you must perform the following configuration steps in
the application server for each resource adapter:
●
In the file ra.xml, define the index of the resource adapter using the additional configuration property resourceAdapterIndex. This may also be possible via the
Management Console as in standard operation providing that certain requirements are
fulfilled, see "Adapting the ra.xml file" on page 89.
If you assign the indices manually, you must make sure that each resource adapter is
given a unique index. In the case of inbound communication, you require this unique
index to configure the inbound message endpoints via the Management Console (see
Section 6.8.1, "Configuring inbound message endpoints").
●
Perform the other configuration steps at the application server in exactly the same way
as in default resource adapter mode, see Section 4.1.2, "Configuration steps for
outbound and inbound communication".
resourceAdapterIndex
resourceAdapterIndex defines the index of the associated resource adapter instance in
a multiple resource adapter configuration.
This property is only of any significance in a multiple resource adapter configuration with
several resource adapter instances and must not be specified at the same time as the
resourceAdapterAddresses property (see Section 4.8, "Special characteristics in cluster
operation").
Definition:
<index>
Explanation: <index> is a number between 1 and 32. It is defined by the Management
Console if the ra.xml is configured using the Management Console.
Default:
136
No default value
BeanConnect V2.1
Example:
Multiple resource adapter mode
<config-property>
<description>Index of this resource adapter instance in a
multi-resource-adapter configuration.
</description>
<config-property-name>resourceAdapterIndex
</config-property-name>
<config-property-type>java.lang.String
</config-property-type>
<config-property-value>5
</config-property-value>
</config-property>
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
BeanConnect V2.1
137
Cluster operation
Configuration in the application server
4.8 Special characteristics in cluster operation
Multiple resource adapter instances may run together with multiple proxy instances in a
cluster environment. The number of proxy instances does not have to be the same as the
number of resource adapter instances. A maximum of 32 resource adapter instances and
a maximum of 32 proxy instances are possible.
All the participating instances have an identical configuration, and in particular each
resource adapter instance is deployed with the same BeanConnect RAR archive and
therefore works with the same configuration values from ra.xml.
Cluster operation is possible for both outbound communication via OSI-TP / LU6.2 and for
inbound communication.
In the case of cluster operation, the following configuration steps are necessary at the application server:
●
Define the additional parameters and properties for cluster operation in the ra.xml file:
–
You must specify the addresses of all the proxy instances in the property proxyURL.
–
You must specify the addresses of all the resource adapter instances in the
additional property resourceAdapterAddresses.
–
You can modify the parameters for the reallocation of the resource adapters and
proxies in the properties proxyReconnectCount and proxyReconnectInterval.
This is also possible via the Management Console as in standard operation, see
"Adapting the ra.xml file" on page 89. However, you may also adapt the ra.xml file
manually.
●
Perform the other configuration steps at the application server in exactly the same way
as when using only one resource adapter, see Section 4.1.2, "Configuration steps for
outbound and inbound communication".
proxyURL
In cluster operation, the proxyURL defines the assignment of the resource adapter
instances to the proxy instances. If you are working with multiple proxy instances then you
must specify the addresses of all the proxies, each separated by a semicolon.
Definition:
oltp://<host>:<port>/<name>; ... ;oltp://<host>:<port>/<name>
Explanation: <host>
Host on which the associated proxy container is installed.
<host> can be specified as a symbolic name or as an IPv4 address.
<port>
138
Port number of the associated proxy container
BeanConnect V2.1
<name>
Cluster operation
Application name of the associated proxy container
The individual entries must be separated by semicolons.
Default:
oltp://localhost:31000/BC31000
Example:
<config-property>
<description>BeanConnect Proxy URLs for OLTP outbound
communication with 2 Proxies</description>
<config-property-name>proxyURL</config-property-name>
<config-property-type>java.lang.String
</config-property-type>
<config-property-value>oltp://proxyhost1:31000/BC31000;
oltp://proxyhost2:31010/BC31010
</config-property-value>
</config-property>
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
resourceAdapterAddresses
This property is only of any significance in a cluster configuration with several resource
adapter instances and must not be specified at the same time as the resourceAdapterIndex property (see Section 4.7, "Special characteristics of multiple resource adapter
mode").
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
This property enables you to specify the addresses of all the computers on which instances
of the BeanConnect resource adapter will be run. You can specify up to 32
semicolon-delimited addresses.
You specify addresses in the format host[:port]. If you do not specify a port number, the
port number specified under inboundListenerPort is used as the listener port for
inbound communication. This must be greater than 0. If you specify a port number, this is
used as the listener port for inbound communication. The specified value must be greater
than 0.
If multiple resource adapter instances are to run under one and the same host address,
then you must specify this host address the corresponding number of times in the list and
assign each address a different port number.
Definition:
<host>[:<port>]; ... ;<host>[:<port>]
Explanation: <host>
Host on which the associated resource adapter instance is running.
<host> can be specified as a symbolic name or as an IPv4 address.
<port>
Port number of the associated resource adapter instance for inbound
communication.
The individual entries must be separated by semicolons.
Default:
BeanConnect V2.1
There is no default value
139
Cluster operation
Example:
Configuration in the application server
<config-property>
<config-property-name>resourceAdapterAddresses
</config-property-name>
<config-property-type>java.lang.String
</config-property-type>
<config-property-value>
host1:31099;host2:31099;host3:31099
</config-property-value>
</config-property>
proxyReconnectCount
This property is only of any significance in a cluster configuration with multiple resource
adapter instances and multiple proxy instances. proxyReconnectCount controls the
usage-driven reassignment of a resource adapter instance to a proxy application. This
mechanism is activated as soon as multiple resource adapter instances are assigned to a
proxy application.
Definition:
<number>
Explanation: <number> specifies the number of connection requests (calls to
getConnection()) after which a reassignment between the resource adapter
instance and the proxy application is necessary.
If the value 0 is specified for <number> then usage-driven reassignment is
deactivated
Default:
100
Example:
<config-property>
<config-property-name>proxyReconnectCount
</config-property-name>
<config-property-type>java.lang.String
</config-property-type>
<config-property-value>200
</config-property-value>
</config-property>
proxyReconnectInterval
This property is only of any significance in a cluster configuration with multiple resource
adapter instances and multiple proxy instances. proxyReconnectInterval controls the
time-driven reassignment of a resource adapter instance to a proxy application. This
mechanism is activated as soon as multiple resource adapter instances are assigned to a
proxy application.
140
BeanConnect V2.1
Definition:
Cluster operation
<minutes>
Explanation: <minutes> specifies the time in minutes after which a reassignment between the
resource adapter instance and the proxy application is necessary
If the value 0 is specified for <minutes> then time-driven reassignment is
deactivated.
Default:
10
Example:
<config-property>
<config-property-name>proxyReconnectInterval
</config-property-name>
<config-property-type>java.lang.String
</config-property-type>
<config-property-value>5
</config-property-value>
</config-property>
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k04
Configuration in the application server
If a cluster configuration is operated with more resource adapter
instances than proxy instances (i.e. there is always at least one
proxy instance which is assigned more than one resource
adapter instance), then the usage-driven and time-driven
reassignment should be deactivated or, at the very least, values
larger than the defaults should be set in order to avoid performance losses.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
I
BeanConnect V2.1
141
Cluster operation
142
Configuration in the application server
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k05
June 8, 2009 7:06 pm
5 BeanConnect Management Console
The BeanConnect Management Console is used to configure and administer one or more
BeanConnect proxies. These proxies can run on the same host as the Management
Console (local proxies) or on a remote host (remote proxies).
Local proxies are proxies which run on the same host and under the same user ID as the
Management Console. All other proxies are referred to as remote proxies.
In addition, the Management Console is a JMX client. As a result, it is therefore possible,
for example, to modify the settings in the resource adapter via the BeanConnect MBeans,
query statistical values for connections via the BeanConnect MBeans or access the application server's MBeans.
In addition, you can also use the Management Console to set the logging properties in the
application server.
The Management Console is an administration tool with a graphical user interface (GUI).
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
I
You can find further detailed information about the Management
Console in the Management Console's online help system.
This chapter provides an overview of
●
Starting and shutting down the Management Console
●
User interface - Management Console window
●
Functions of the BeanConnect Management Console
●
Administrative data of the Management Console
BeanConnect V2.1
143
Starting/shutting down the Management Console
BeanConnect Management Console
5.1 Starting and shutting down the Management Console
This section provides information about:
●
Starting the Management Console
●
Starting the Management Console's online Help system
●
Shutting down the Management Console
5.1.1 Starting the Management Console
Starting the Management Console under Solaris and Linux systems
You start the Management Console using the shell script startconsole.sh:
1. Open a shell.
2. Change to the Management Console home directory.
3. Run the shell script startconsole.sh.
Starting the Management Console under Windows
To start the Management Console, select Management Console from the
BeanConnect V2.1A00- Management Console program group in the Start menu.
Select:
Start - Programs - BeanConnect V2.1A00 - Management Console - Management
Console
5.1.2 Starting the Management Console's online Help system
You can start the Management Console's online help system within the Management
Console window in the following ways:
144
●
Press the F1 key.
●
Choose the Content command from the Help menu.
●
Click the Help button in a dialog box or a panel in which you require assistance.
BeanConnect V2.1
Starting/shutting down the Management Console
Alternatively, you can start the online help system without starting the Management
Console:
●
On Solaris/Linux systems:
1. Open a shell.
2. Change to the Management Console home directory.
3. Call the script starthelp.sh.
●
On Windows systems:
Select the MC Help command from the
BeanConnect V2.1A00 - Management Console program group.
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k05
BeanConnect Management Console
Language of the online Help system
You can change the language of the Management Console's online help system:
●
On Solaris/Linux systems:
During the installation of the Management Console, both the English and the German
versions of the help system are installed. By default, the Management Console uses the
English version.
To change to the German language, move the file
ConsoleHelp_de.jar to ConsoleHelp.jar
to the lib subdirectory of the BeanConnect installation directory.
●
You can select the language for the Management Console's online help system during
the installation of BeanConnect (see Section 3.3, "Installing BeanConnect under
Windows systems" on page 60). By default, the English version is selected.
© cognitas GmbH 2001-2
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
On Windows systems:
5.1.3 Shutting down the Management Console
To shut down the Management Console, choose Exit from the File menu.
BeanConnect V2.1
145
Management Console window
BeanConnect Management Console
5.2 User interface - Management Console window
The Management Console window contains the components described below:
●
A menu bar is located at the top of the Management Console window.
The menu bar contains the File, View, Extras, Window and Help menus.
●
The central part of the window is divided into the following areas:
●
–
Navigation area (on the left)
This area displays a tree structure (the navigation tree) containing the administered
proxies together with the resources and settings they contain.
–
Work area (in the top right area of the window)
This area displays configuration data associated with the entries you have selected
in the navigation area.
–
Protocol (log) window (in the bottom right part of the window)
This area contains the messages of the current Management Console session. The
log window can be permanently displayed or hidden.
At the bottom of the window you will find the status bar.
The status bar displays the processing status of time-intensive jobs in the form of text
messages.
Figure 12: User interface of the Management Console
146
BeanConnect V2.1
Management Console window
5.2.1 Navigation area in the Management Console
The administered BeanConnect proxies are displayed in a tree structure in the navigation
area (in the same way as the drives and directories in Windows Explorer). There is a
separate subtree under the BeanConnect proxies node for every BeanConnect proxy that
is administered via the Management Console (Proxy1 in Figure 13). This subtree allows
you to display and edit the configuration data of the BeanConnect proxy. If you click an item
in the subtree, the configuration data associated with this component is displayed in a panel
in the work area. The context menu of the entry in question also contains commands which
allow you to modify the configuration data.
The figure below shows the navigation area of the Management Console:
Figure 13: Navigation area
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k05
BeanConnect Management Console
BeanConnect V2.1
147
Management Console window
BeanConnect Management Console
5.2.2 Managed objects
No proxy container needs to be running in order to administer objects.
A distinction is made between the following objects:
MC-CmdHandler Client Instances
One object for each administered MC-CmdHandler. An MC-CmdHandler enables you to
access the filesystem at the relevant host and execute scripts there.
Communication Services
One object for each administered communication service. A communication service is
required for communications with CICS partners. It can run either locally or on a remote
host.
openUTM-LU62 Gateways
One object for each managed openUTM-LU62 Gateway. An openUTM-LU62 Gateway is
required alongside the communication service for communications with CICS partners. In
each case, it runs on the same host as the associated communication service.
BeanConnect Proxy Clusters
One object for each administered BeanConnect proxy cluster. A proxy cluster consists of
one or more proxies which must be configured beforehand.
BeanConnect Proxies
One object for each administered BeanConnect proxy which is not located in a proxy
cluster.
Only "administrable" BeanConnect proxies can be managed using the Management
Console. A BeanConnect proxy is considered administrable if one of the following applies:
●
The proxy is a local proxy.
●
The proxy is a remote proxy and the MC-CmdHandler associated with the proxy is
available and can be accessed via the Management Console.
Resource Adapters
One or more resource adapters is assigned to each proxy. A resource adapter runs on an
application server instance.
148
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k05
BeanConnect Management Console
Management Console window
MBean Clients
An MBean client can be defined for each resource adapter. The Management Console can
use the MBean client to access the MBeans of the relevant JMX server (display attributes
and modify their values, run operations and receive notifications).
It is also possible to define "free" (stand-alone) MBean clients which are not assigned to any
resource adapter. Free MBean clients are displayed on the topmost level of the navigation
tree.
EIS Partners
One object for each administered EIS partner.
Inbound Users
The user information (user name and password) may be passed by the EIS partner on
inbound communication. This user information must be known to the proxy.
Inbound Message Endpoints
An inbound message endpoint represents a communication endpoint for inbound communication. A proxy can manage several inbound message endpoints.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Inbound Services
An inbound service is a service which an EIS partner addresses during inbound communication. A service is always assigned to precisely one inbound message endpoint. However,
it is possible to assign multiple services to an inbound message endpoint. You can also
define coding properties for a service.
Outbound Services
An outbound service represents a service (transaction code (TAC) or CICS transaction) that
is provided by the EIS partner.
Outbound Communication Endpoints
For each (symbolic) service that is specified in the connectionURL configuration property
in the application server, you must configure a corresponding outbound communication
endpoint of the same name in the proxy. The outbound communication endpoint definition
maps the symbolic service name onto a real service name in the EIS partner application.
Outbound communication endpoints are specific to the EIS partners. Several outbound
communication endpoints can be assigned to one EIS partner.
For detailed information see section "Configuring outbound communication endpoints" on
page 217.
BeanConnect V2.1
149
Management Console window
BeanConnect Management Console
5.2.3 Additional functions and information
You can find more functions and information in:
Advanced Functions
The advanced features provide statistical information and diagnosis control. You can find
detailed information in Chapter 13, "Logging, diagnostics and troubleshooting".
Todo Topics
The Management Console provides a list of todo topics. The todo list contains the most
important activities that need to be performed in order to activate modifications made to the
configuration data of the BeanConnect proxies. You can also use the todo topic list to add
your own todo topics. You will find further details in the section "Todo topics" on page 156.
150
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k05
BeanConnect Management Console
Functions of the Management Console
5.3 Functions of the BeanConnect Management Console
The Management Console supports you in tasks associated with:
●
Configuration functions
●
Configuration wizards
●
Starting and stopping proxies
●
Checking the availability of BeanConnect components and EIS partners
●
Diagnosis support
●
Todo topics
●
Cluster support
●
Management Console as a JMX client
I
You should avoid to concurrently configure or administrate a
BeanConnect proxy from multiple Management Console
sessions. Otherwise settings of one Management Console
session could be overwritten by another session and data may
be lost.
5.3.1 Configuration functions
© cognitas GmbH 2001-2
●
configuring the BeanConnect proxies
●
configuring the EIS partners
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
Configuration using the Management Console covers the following activities:
Configuring the BeanConnect proxies
When you configure a proxy, the following activities can be initiated from the Management
Console GUI:
1. define and modify the configuration
2. save the configuration
3. shut down the proxy
4. update the configuration of the proxy
5. start the proxy
BeanConnect V2.1
151
Functions of the Management Console
BeanConnect Management Console
If you want to integrate an EIS partner in the Management Console or if you want to modify
or remove an EIS partner, you must perform the above steps in the specified order. If you
want to generate, modify or delete an outbound communication endpoint or an inbound
message endpoint, you can update the configuration while the proxy is running. In this case,
only steps 1 and 2 have to be performed. You then have to restart the proxy.
When you configure a proxy, the Management Console assists you by displaying todo
topics (see "Todo topics" on page 156).
Further details on proxy configuration can be found in section "Configuring the
BeanConnect proxy" on page 168.
Configuring the EIS partners
The Management Console allows you to create configuration fragments for the generated
EIS partners. These configuration fragments are created and saved in files when the
BeanConnect proxy configuration is saved. However, it is your responsibility to perform the
following tasks:
●
Transfer the generated files containing the configuration statements for the EIS partner
applications to the host on which the EIS partner is running.
●
Integrate these files into the EIS partner's configuration.
You will find further details in Chapter 7, "Adapting the configuration in the EIS partner".
5.3.2 Configuration wizards
The Management Console provides wizards for the configuration of individual proxies and
their components. This means that even less experienced users can create a configuration
without forgetting parameters. You start the configuration wizards via the context menu, for
example by opening the wizard subtree under Configurations Wizards and choosing the
context menu command Start Configuration Wizard for the required wizard.
152
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k05
BeanConnect Management Console
Functions of the Management Console
Figure 14: Starting the configuration wizard
Alternatively, choose Configuration Wizards from the File menu.
The wizard itself runs in a window which consists of three sections.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Figure 15: Configuration wizard window
The top left section of the wizard (in the example, Configure EIS Partners) provides an
overview of all the individual tasks present in the configuration wizard in the form of a tree
structure.
BeanConnect V2.1
153
Functions of the Management Console
BeanConnect Management Console
The section to the right of this describes the individual task currently selected in the tree
structure.
The lower section provides a detailed description of the current individual task. You may be
able to choose from a selection of options in order to guide the configuration process. You
do this using the buttons at the lower edge of the screen, in this case Select EIS Partner
and Create Further EIS Partner.
The user can exit a configuration wizard at any time by clicking the cross at the top right of
the window to close it.
If configuration with the wizard has not been terminated in full, the user is informed of this
and is able to save the current state of the wizard. This means that it is possible to continue
the commenced configuration at a later date (possibly even in a subsequent program
session).
See the online Help system for further details about the wizard window.
5.3.3 Starting and stopping proxies
You can use the Management Console to start, stop and restart BeanConnect proxies and
proxy components on both local and remote hosts.
Starting and stopping a BeanConnect proxy
Select the command Start Proxy or Stop Proxy from the BeanConnect proxy's context
menu to start or stop the proxy.
In the case of proxies for CICS partners, a proxy consists of multiple components. The
Management Console allows you to start/stop individual proxy components or all the
components of a proxy. A special dialog box is displayed in which you can select the components that are to be started/stopped. You can select the following components:
●
proxy container
●
openUTM-LU62 Gateway (for CICS partners)
●
SNAP-IX or IBM Communications Server (for CICS partners)
I
For CICS partners:
You must not stop the openUTM-LU62 Gateway and SNAP-IX
or the IBM Communications Server as long as other applications that use these components are running (such as proxy
containers, for example).
154
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k05
BeanConnect Management Console
Functions of the Management Console
The Management Console only tries to start the proxy component if the proxy component
in question is not already running.
Restarting the BeanConnect proxy
Select the command Save/Restart - Restart Proxy from the BeanConnect proxy's context
menu.
In the case of proxies for CICS partners, when you perform a restart then, in the same way
as a normal start/shutdown, a dialog box is displayed in which you can select the components that are to be restarted.
When restarting a proxy container the individual processes are stopped one after the other
and are then restarted. The proxy container remains available during the restart.
5.3.4 Checking the availability of BeanConnect components and EIS
partners
You can use the Management Console to check the availability of a proxy and all the components that are assigned to this proxy. These also include the EIS partners. You can perform
the check for the proxy or individually for certain components.
To do this, choose the Check Availability command from the required object's context
menu. The command is available for the following objects.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
●
Proxy
Checks the availability of the proxy container and of all the components assigned to the
proxy: All resource adapters, all MC-CmdHandlers on remote hosts if these are used to
administer remote proxies as well as the openUTM-LU62 Gateway and SNAP-IX or IBM
Communications Server if the proxy is configured for CICS partners. The availability of
all assigned EIS partners is also checked.
●
Resource adapter
Only checks the availability of a specified resource adapter. The associated proxy
container must be running.
●
openUTM-LU62 Gateway / communication service
Checks the availability of an openUTM-LU62 Gateway or a communication service
(SNAP-IX, IBM communications service). The openUTM-LU62 Gateway and communication services objects can be accessed via the topmost level in the navigation tree.
If the components are installed on a remote host then the associated MC-CmdHandler
must be running.
BeanConnect V2.1
155
Functions of the Management Console
●
BeanConnect Management Console
EIS partner
Checks the availability of a specified EIS partner. The associated proxy container must
be running.
For further details, see Chapter 8.6.1, "Checking the availability of a proxy".
5.3.5 Diagnosis support
The Management Console helps you to diagnose problems that occur in the environment
of a BeanConnect proxy. The Management Console therefore provides a range of functions
that allow you to do the following:
●
configure traces and logging
●
collect and display traces and logs
For details see Chapter 13, "Logging, diagnostics and troubleshooting".
5.3.6 Todo topics
The Management Console displays a todo list containing an overview of the activities that
need to be performed (e.g. for update the configuration).
I
The todo list represents an overview of the actions that are to be
performed. It is important to note that the list also contains todo
topics relating to actions that have to be performed on remote
(application/EIS) servers. Those actions cannot be started from
the local host. They must be started manually on the remote
host.
Certain actions cause the Management Console to add todo topics to the list automatically.
Some of these topics refer to actions you can perform using the Management Console. In
such cases, the relevant items are removed from the list automatically once the associated
actions have been completed. You can also perform such actions directly from the topic list.
Todo topics may also involve actions that you cannot perform via the Management Console,
for instance adding the generation statements created by the Management Console to the
configuration of an EIS partner. In such cases, the Management Console cannot identify
whether or not you have performed the action. Consequently, when you have completed an
action of this type you must remove the corresponding topic from the list yourself.
You can also create your own todo topics and add them to the list to avoid having to note
them elsewhere.
156
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k05
BeanConnect Management Console
Functions of the Management Console
5.3.7 Cluster support
A proxy cluster consists of one or more proxies. You can configure and administer a proxy
cluster via the Management Console. The procedure is similar to that for configuring and
administering an individual proxy.
Many of the menu commands and activities are the same since, in most cases, the proxy
cluster behaves in the same way as an individual proxy.
Configuration wizards are not supported in a proxy cluster.
Configuring a BeanConnect proxy cluster
Perform the steps below to configure a proxy cluster consisting of multiple proxies:
1. Configure an individual proxy which will act as the basis for the proxy cluster.
2. Choose the command Define Proxy Cluster in this proxy's context menu. This defines
the proxy cluster and simultaneously enters the proxy in this cluster. This action
automatically makes this proxy the master proxy in the new cluster.
3. Enter further proxies in the Management Console. You do not have to configure these
since the configuration properties are overwritten when they are included in the cluster
and synchronized with the master proxy.
4. Add the new proxies to the cluster by choosing Add to Proxy Cluster in the context
menu.
5. Save the cluster configuration. This synchronizes the proxies' configuration data.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
You can modify the configuration properties of a proxy cluster in the cluster network, e.g.
modify or add EIS partners, inbound services or outbound services.
The Management Console also provides a manual synchronization function for the proxy
cluster (Synchronize Proxy Cluster command in the proxy cluster's context menu). This
function is needed, for example, if a proxy in a cluster could not be administered for a period
(for example because the corresponding host was not running) and the configuration of the
proxy cluster changed during this period. An explicit synchronization then harmonizes the
configuration of this specific proxy in the cluster with the configuration of the proxy cluster
as a whole.
For further information, see Chapter 6.4, "Configuring a BeanConnect proxy cluster".
BeanConnect V2.1
157
Functions of the Management Console
BeanConnect Management Console
Starting and stopping a BeanConnect proxy cluster
You start, stop and restart a proxy cluster in the same way as when starting, stopping and
restarting an individual proxy. Choose the corresponding command in the proxy cluster's
context menu.
Start Proxy Cluster to start
Stop Proxy Cluster to stop
Save/Restart - Restart Proxy Cluster to restart
Checking availability
You check the availability of a proxy cluster or its components in the same way as for an
individual proxy by choosing the Check Availability command in the associated context
menu.
In a proxy cluster, the command initiates a check of all the proxy containers and all the
associated components, i.e. resource adapters, EIS partners, MC-CmdHandlers on remote
hosts and the openUTM-LU62 Gateway and communication service in the case of connections to CICS partners.
At the level of the individual components, the command only checks these components.
The openUTM-LU62 Gateway and the communication service are checked at the topmost
level in the same way as for an individual proxy.
5.3.8 Management Console as a JMX client
The Management Console also contains a JMX client which permits you to monitor a
resource adapter. It is possible to configure multiple JMX clients.
A JMX client can either be assigned to a resource adapter or can be configured as a free
JMX client. To assign it to a resource adapter, you define the JMX client using the Define
MBean Client command in the resource adapter's context menu and then specify its
properties in the dialog which then follows, see Section 6.11.2, "Setting up the JMX client
in the Management Console".
A JMX client communicates with the JMX server. This runs on the application server and
makes the data available via so-called MBeans. The JMX client is therefore also known as
the MBean client. This allows you to monitor the following objects:
158
●
Resource adapters
●
Connection factories
●
Inbound connections
●
Message endpoints
BeanConnect V2.1
Functions of the Management Console
The MBean client can read the data and attributes made available by the MBeans. It also
has write access to certain attributes. The following monitoring functions are provided:
●
Display MBeans attributes
The attributes include, for example, the configuration properties or certain statistical
values of the corresponding MBean.
●
Read notifications output by the MBeans
Notifications must first be subscribed to via the MBeans.
Notifications are messages which the application server generates when certain events
occur. Notifications are also generated by the resource adapter and by the application
server components which supply the MBeans.
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k05
BeanConnect Management Console
●
Collect and display statistical values
Attribute values can be collected at fixed intervals and output in statistical form. These
include, for example, the number of active connections or the number of rolled back
transactions.
●
Run operations
Operations are specific functions that are implemented by the MBeans and accessible
via the interface; in the case of connection factories, these are, for example, the
functions cleanupPool and resetStatisticValues.
For more detailed information on defining and activating monitoring functions, see
Section 8.7, "Monitoring the resource adapter with the Management Console".
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
You can use the administration facilities to set the monitoring functions you want to use for
each MBean client (notifications, statistics etc.). For this to be possible, there must be a
connection between the Management Console and the JMX server on the application
server. You can also define favorites to permit simple access to frequently used MBeans.
BeanConnect V2.1
159
Administrative data of the Management Console
BeanConnect Management Console
5.4 Administrative data of the Management Console
The Management Console uses the files listed below:
●
console.properties.xml
●
log4j.properties.xml
console.properties.xml
This XML file is located in the Management Console's config subdirectory.
console.properties.xml contains the administrative data of all BeanConnect proxies
that are known to the Management Console. This file is also used to store additional
settings for the Management Console.
The console.properties.xml file is automatically updated or extended as necessary by
the Management Console. It is not necessary to save the updated data explicitly.
log4j.properties.xml
This XML file is located in the Management Console's config subdirectory. The
log4j.properties.xml file is the Log4j configuration file used by the Management
Console. You can update this file in the Management Console's Settings dialog box. Select
Extras - Settings... to open this dialog box.
160
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
June 8, 2009 7:06 pm
6 Configuration of BeanConnect
The BeanConnect proxy communicates with the BeanConnect resource adapter running
within the application server on the one hand and with the EIS partner on the other hand.
The proxy is not used for outbound communication via UPIC.
To ensure communication between an EJB deployed in the application server and a partner
application, the proxy and the proxy components must be configured properly.
The BeanConnect Management Console allows you to carry out the configuration tasks for
the BeanConnect proxy container and the proxy components. It is also possible to change
the configuration of the proxy clusters, EIS partners, the outbound services, the outbound
communication endpoints and the inbound message endpoints, inbound services and
Management Console command handlers (MC-CmdHandlers). The Management Console
can also be configured as a JMX client for the display of MBeans
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
You can add new objects and change or delete existing objects.
BeanConnect V2.1
161
Configuration of BeanConnect
This chapter provides information on the following topics:
●
Configuration steps
●
Adding a BeanConnect proxy to the Management Console
●
Configuring the BeanConnect proxy
●
Configuring a BeanConnect proxy cluster
●
Configuring the BeanConnect resource adapter
●
Configuring the EIS partners
●
Configuring outbound communication
●
Configuring inbound communication
●
Saving and activating the configuration of the BeanConnect proxy
●
Configuring the Management Console command handler (MC-CmdHandler)
●
Configuring the Management Console as a JMX client
Detailed information on using the BeanConnect Management Console can be found in
Chapter 5, "BeanConnect Management Console" and in the online help system.
162
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuration steps
6.1 Configuration steps
The following steps must be performed to configure a proxy using the Management
Console:
1. Adding the proxy to the configuration data of the Management Console
Before it can be administered, each proxy must be made known to the Management
Console. This procedure is described in the section "Adding a BeanConnect proxy to
the Management Console" on page 165.
2. Configuring the proxy and the proxy components
When configuring the proxy and the proxy components, you have to make all the specifications which allow the partners to communicate with each other. This includes:
–
the specifications for identifying the proxy (Section 6.3.1, "General information on
the proxy").
–
additionally for CICS partners, the settings for communication with the
openUTM-LU62 Gateway and the communication service, see Section 6.3.2,
"Proxy Components: CICS partners"), as well as specifications for the network
connections for CICS partners, see "CICS Partner tab" on page 208.
–
the settings for communication with the resource adapter assigned to the proxy (see
Section 6.5, "Configuring the BeanConnect resource adapter").
3. Configuring the EIS partners and communication objects
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
In this step of the configuration process, you define the communication relationships
between the proxy and the EIS partners for inbound and outbound communication. The
following objects must be created:
–
EIS parttners (see Section 6.6, "Configuring the EIS partners")
–
Outbound services and outbound communication endpoints (see Section 6.7,
"Configuring outbound communication")
–
Inbound users, inbound services and inbound message endpoints (see Section 6.8,
"Configuring inbound communication")
4. Saving and activating the configuration
After all the necessary information has been provided, you have to save the configuration. The properties of the configuration objects are stored by the Management
Console, so that they are available for subsequent Management Console sessions. The
Management Console then generates the configuration files to be used by the proxy,
the components of the proxy and the EIS partners. The last step is to activate the new
configuration.
BeanConnect V2.1
163
Configuration steps
Configuration of BeanConnect
These tasks are described in the section "Saving and activating the configuration of the
BeanConnect proxy" on page 228.
If you want to form a proxy cluster, you will find the relevant information on Section 6.4,
"Configuring a BeanConnect proxy cluster".
For information on configuring the Management Console as a JMX client, see
Section 6.11, "Configuring the Management Console as a JMX client".
164
BeanConnect V2.1
Adding a BeanConnect proxy to the Management Console
6.2 Adding a BeanConnect proxy to the Management Console
All proxies which are known to the Management Console and are not assigned to a proxy
cluster are shown together with the configured EIS partners and communication objects in
the navigation tree of the Management Console below the BeanConnect Proxies node.
One Management Console can be used to administer multiple proxies.
Figure 16: Proxies within the Management Console
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
To access the data of a proxy, you have to enter the administration password. By default,
this is admin. You can change the administration password, see Section 6.3.3, "Modifying
the administration password".
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
6.2.1 Adding a new proxy
To add a new proxy to the navigation tree:
●
Choose Add Local Proxy from the context menu of the BeanConnect Proxies node if
the proxy is located on the same host and under the same user ID as the Management
Console. It is not necessary to use the same user ID if the access permissions have
been set in such a way that the Management Console is able to access all the proxy's
required files under the user ID under which the proxy runs.
●
Choose Add Remote Proxy from the context menu of the BeanConnect Proxies node
if the proxy is located on another host. You must enter the name of the host the proxy
container is running on.
To add and manage a proxy on a remote host, the proxy's MC-CmdHandler must be
running on the proxy host (see Section 6.10, "Configuring the Management Console
command handler (MC-CmdHandler)". The password of the employed
MC-CmdHandler and the administration password of the added proxy must be
identical!
BeanConnect V2.1
165
Adding a BeanConnect proxy to the Management Console
Configuration of BeanConnect
Enter the name of the remote host under Host and the MC-CmdHandlers's listener port
on the remote host under MC-CmdHandler Listener Port.
Figure 17: Adding a new proxy
When adding a local proxy a container selection dialog box is opened. Choose the
container directory by browsing the file system.
Both menu entries can also be found in the File menu and can also be activated from there.
166
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
I
Adding a BeanConnect proxy to the Management Console
Adding proxies to the Management Console's configuration
data does not install new proxies. You only can add proxies
which have already been installed.
A proxy added to the Management Console can not be fully managed until all the necessary
parameters for the proxy and the proxy components are defined (see "Configuring the
BeanConnect proxy" on page 168). An appropriate message is created if you try to call a
function which is not available before having finished the necessary configuration.
A proxy, installed beneath the same BeanConnect home directory as the Management
Console, will be detected the next time the Management Console is started and will be
added to the configuration data automatically. This also applies if the proxy is installed on
the system after the Management Console has been installed.
6.2.2 Removing a proxy
To remove a proxy from the configuration data of the Management Console, select Remove
Proxy from the context menu of the proxy.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
After you have confirmed the prompt, the proxy is deleted from the configuration data. Apart
from that, the proxy itself will not be changed. In particular, it will not be deinstalled.
BeanConnect V2.1
167
Configuring the BeanConnect proxy
Configuration of BeanConnect
6.3 Configuring the BeanConnect proxy
When you add a new proxy to the Management Console, a property sheet is displayed
automatically to allow you to enter the configuration data for the proxy components. To
change the configuration data of an existing proxy, select the desired proxy in the navigation
tree and choose Edit Properties from the context menu.
The property sheet consists of several pages. These are described below.
6.3.1 General information on the proxy
The General page contains some general information to allow the Management Console
to identify the proxy and access it.
168
BeanConnect V2.1
Configuring the BeanConnect proxy
Figure 18: General information on a proxy
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Name
Proxy Name. This name is only used internally by the Management Console to distinguish
between the managed proxies.
ID
The Management Console assigns an ID to each proxy in the form ProxyID.<number>.
This ID is shown in the dialog box after a proxy is added for the first time and cannot be
changed. The Management Console uses this ID as a name component for the generated
configuration files.
BeanConnect V2.1
169
Configuring the BeanConnect proxy
Configuration of BeanConnect
Host
Name or IP address of the host on which the proxy is installed
Container Port / Container Directory
These fields indicate the proxy's port number and home directory. The port number is
specified during installation.
Container Run UserID
User ID under which the proxy container is started. The Management Console compares
the user ID specified here with the user ID under which the MC-CmdHandler used for
administering the proxy container is running. Only if both user IDs are identical does the
Management Console judge that the proxy container can be administered with the
MC-CmdHandler used.
In the case of local proxies, please note that in certain situations, e.g. if the proxy container's
MC-CmdHandler has not been started and this MC-CmdHandler's listener port has not
been assigned to the proxy then the system uses the "internal" MC-CmdHandler which runs
in the Management Console process and operates without communications. In this case,
the user ID specified here must match the user ID under which the Management Console
itself was started.
Possible EIS Partner Types
Specifies the EIS partner type for which the proxy is configured. If you choose Only UTM
Partners then the proxy can only communicate with openUTM partners. If you choose Only
CICS Partners then the proxy can only communicate with CICS partners. Choosing the
option UTM and CICS Partners enables communications with both partner types. An
additional tab – Proxy Components – is displayed in the case of communication with CICS
partners.
I
Separate licenses must be purchased to communicate with the
partner types UTM and CICS.
Management Console Access
Additionally, you must specify the administration password used by the Management
Console to access the proxy container and its MC-CmdHandler in the Admin User
Password field. Instead of specifying a password you can choose the option Prompt. In
this case the password is requested on the first access to any proxy container data within
a Management Console session.
The field MC-CmdHandler Listener Port defines the listener port of the MC-CmdHandler
used to administer the proxy. The default value is the value in Container Port + 2.
170
BeanConnect V2.1
Configuring the BeanConnect proxy
Windows Service for Proxy Container
Only if the proxy container is running on a Windows system: Proxies can also be started as
Windows services. To do this, select the option Start as Service. The name to be used to
start the proxy as a service is defined during installation and is shown in the field Service
Name. If the proxy is operated as a Windows service, it cannot be started in debug mode.
Automatic Availability Check
Finally, you can set the time interval for the automatic availability check in the Time Interval
(sec) field. The values you set should not be too small in order to avoid overburdening the
Management Console (and the proxies) with availability checks. Values of 180 seconds and
higher are recommended.
No automatic availability check is performed if you leave the field empty or enter the value 0.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
BeanConnect V2.1
171
Configuring the BeanConnect proxy
Configuration of BeanConnect
6.3.2 Proxy Components: CICS partners
In the Proxy Components tab in the property sheet
Edit Properties of Local/Remote Proxy, you define the settings for the proxy
components openUTM-LU62 Gateway and communication service.
These two proxy components are required for communication with CICS partners and must
always run on the same computer. This does not have to be the computer on which the
proxy is running.
The tab illustrated below already contains the necessary entries. When you perform initial
set-up, further dialog boxes are displayed for the entry of the openUTM-LU62 Gateway and
the communication server data.
Figure 19: Description of the proxy components for CICS partners
openUTM-LU62 Gateway/Communication Service Location
Displays the location, the name and the operating system of the computer on which the
proxy components openUTM-LU62-Gateway and communication service are running.
Location: On Proxy Host means: The same computer on which the proxy container is
running.
Location: On Separate Host means: A different computer.
172
BeanConnect V2.1
Configuring the BeanConnect proxy
openUTM-LU62 Gateway
Specifies the computer and the directory in which the openUTM-LU62 Gateway is installed.
To select a gateway, click the ... button to open the following sequence of dialog boxes:
Figure 20: Configuring the openUTM-LU62 Gateway
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
The gateway instances that have already been configured are displayed in Select an
openUTM-LU62 Gateway Instance. You can select an instance and click OK to assign this
instance. You can click Edit to modify the properties of a selected instance.
BeanConnect V2.1
173
Configuring the BeanConnect proxy
Configuration of BeanConnect
Proceed as follows if you want to configure a new instance:
●
Click the Add button.
●
In Add openUTM-LU62 Gateway Instance, click the ... button under Select
MC-CmdHandler to open the dialog Properties of MC-CmdHandler.
●
In Properties of MC-CmdHandler, enter the properties of the MC handler used to
administer the components and click OK.
●
In Add openUTM-LU62 Gateway Instance, enter the installation path of the
openUTM-LU62 Gateway and modify the traced properties if necessary. Click OK.
Communication Service
Specifies the computer, the type and the directory in which the communication service is
installed. To select a communication service, click the ... button to open the following
sequence of dialog boxes: Proceed in the same way as when entering an openUTM-LU62
Gateways:
174
BeanConnect V2.1
Configuring the BeanConnect proxy
Figure 21: Configuring a communication service
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
The communication service instances that have already been configured are displayed in
Select a Communication Service Instance. You can select an instance and click OK to
assign this instance. You can click Edit to modify the properties of a selected instance.
BeanConnect V2.1
175
Configuring the BeanConnect proxy
Configuration of BeanConnect
Proceed as follows if you want to configure a new communication service instance:
●
Click the Add button.
●
In Add Communication Service Instance, click the ... button under Select
MC-CmdHandler to open the dialog Properties of MC-CmdHandler.
●
In Properties of MC-CmdHandler, enter the properties of the MC handler used to
administer the components and click OK.
●
In Add Communication Service Instance, enter the installation path of the
communication service together with the configuration parameters (as described
below) and click OK.
Figure 22: Configuring the properties of a communication service
MAC Address
If LAN is used as the DLC type for at least one EIS partner then you must enter the
MAC address of the computer on which the communication service is running here. For
more detailed information, see Section 6.6.2.1, "Adding EIS partners of the type CICS".
176
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
June 8, 2009 7:06 pm
Control Point
The control point refers to a unique node in the SNA network. This name is used to
identify the instance of the communication service. BeanConnect generates a file
containing the necessary VTAM definitions which can then be entered at the z/OS
mainframe (see Section 7.2.2, "Configuration of VTAM on an IBM mainframe"). The
complete control point name must be unique in the network and consists of the following
two parts:
●
Control Point Network Name specifies the network and can be freely defined by
the user. It is, however, recommended that you use the EIS network name.
●
Control Point Name specifies the control point in this network. The name must
match the VTAM definition on z/OS.
IDBLK / IDNUM
These values form the XID (node ID) and are incorporated in the PU (physical unit)
definition for the VTAM generation.
●
IDBLK specifies the block ID (IDBLK value) for the CICS generation. It must be
specified as a 3-digit hexadecimal number. Alphabetic characters must be entered
in uppercase.
●
IDNUM specifies the Physical Unit ID (IDNUM value) for the CICS generation. It
must be specified as a 5-digit hexadecimal number. Alphabetic characters must be
entered in uppercase.
© cognitas GmbH 2001-2
I
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
Configuring the BeanConnect proxy
See the Glossary for an explanation of SNA-specific terms.
6.3.3 Modifying the administration password
You can change the administration password with the menu item Modify Admin Password
in the context menu of the proxy.
This also changes the password of the MC-CmdHandler that is used for proxy administration. For this reason, every proxy should have its own MC-CmdHandler rather than a
single MC-CmdHandler being used for a number of different proxies.
You can deposit your password by selecting the option Use for the property Admin User
Password within the property sheet of the proxy so that you don't have to enter it in further
sessions (see the section "General information on the proxy" on page 168).
When these actions are performed, the MC-CmdHandler must be started on the proxy host.
If it is not already running, start it first, see Section 6.10.2.1, "Starting the MC-CmdHandler".
BeanConnect V2.1
177
Configuring the BeanConnect proxy
Configuration of BeanConnect
6.3.4 Configuration options in expert mode
If you operate the Management Console in expert mode, the Edit Properties of
Local/Remote Proxy property sheet contains two more tabs: Timer Settings and Performance Settings. These tabs provide several additional configuration options which affect
the proxy behavior.
In expert mode, you are also able to modify the Application Program Interface Mode.
To enable expert mode, select the menu item Extras – Settings and from the General tab
in the Management Console Settings property sheet and choose the option Expert
Mode.
6.3.4.1
Timer Settings
The Timer Settings tab contains timers which affect connection surveillance within the
proxy.
6.3.4.2
Performance Settings
The Performance Settings tab allows you to make settings which affect the performance
of the proxy.
The Proxy Container Mode defines the behavior regarding asynchronous jobs when the
proxy is stopped. By default, asynchronous requests which are not yet started will be
deleted when the proxy is stopped (Performance Enhanced (Non-durable
Asynchronous Processing)). This applies both to asynchronous inbound jobs that have
not yet been sent to the application server or which must be redelivered to the application
server and to asynchronous outbound jobs that have not yet been sent to the EIS partner.
In particular, this includes asynchronous outbound jobs whose start time has not been
reached, see also Section 12.5.1, "Duration of asynchronous requests".
If asynchronous requests are to be retained after the proxy has been stopped, you can set
the property Proxy Container Mode to Durable Asynchronous Processing.
In the Number of Proxy Container Processes area, you can set the maximum number of
processes the proxy can handle at the same time for
178
●
all connections (inbound and outbound),
●
asynchronous jobs.
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring the BeanConnect proxy
In the Number of Parallel Connections area, you can set the maximum number of parallel
connections for
●
inbound connections via the UPIC protocol,
●
inbound connections via the openUTM socket protocol, and
●
inbound connections via the RFC1006 protocol.
Additionally, you can set the size of specific storage areas of the proxy container.
Please refer to the online help system for detailed information.
6.3.4.3
Application Program Interface Mode (API Mode)
The API Mode field is located on the General tab and is preset to the value Standard.
If you want to configure a new connection to an EIS partner which uses the XATMI program
interface as API then you must set the value XATMI for API Mode.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
You can also set the value All. This mode may be necessary during the migration phase,
for example if you change from a standard connection to an XATMI connection and vice
versa.
BeanConnect V2.1
179
Configuring a BeanConnect proxy cluster
Configuration of BeanConnect
6.4 Configuring a BeanConnect proxy cluster
One or more instances of the BeanConnect resource adapter and one or more
BeanConnect proxy instances may run in a BeanConnect cluster configuration. All the
instances in the cluster are configured identically. Three different scenarios result from this:
●
n:1 relation: Several resource adapter instances and one proxy instance.
An n:1 relationship is useful in cases where an application in an application server
cluster conducts only a low level of communication with EIS partners.
●
1:m relation: One resource adapter instance and several proxy instances
This option makes sense if communication is almost exclusively inbound.
●
n:m relation: Several resource adapter instances and several proxy instances
Even in the event of an n:1 relation, you must configure a proxy cluster to ensure that any
change is performed in all the instances of the resource adapter.
You always configure all the resource adapter instances in the Management Console if
multiple resource adapter instances are running in a cluster in the application server. This
is where you configure the cluster for the application server.
If there is more than one proxy in the proxy cluster then there is one special proxy known
as the master proxy. This proxy is the (first) point of contact for the Management Console
when fetching the configuration data for the cluster. If the currently defined master proxy
cannot be administered then the Management Console demands that another proxy, for
which administration is possible, is defined as the master proxy. The configuration data is
then fetched from this proxy. If any changes are made to the configuration, the Management
Console ensures that the administration data of all the proxies in the proxy cluster is
modified consistently.
6.4.1 Generating a proxy cluster
Before you can generate a proxy cluster, you must already have configured at least one
proxy, see Section 6.3, "Configuring the BeanConnect proxy".
To generate a new proxy cluster, select the required proxy under BeanConnect Proxies
and then choose the Define Proxy Cluster... command in the context menu. The proxy
must not be started when you do this.
180
BeanConnect V2.1
Configuring a BeanConnect proxy cluster
Figure 23: Generating a new proxy cluster
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Enter the name of the new proxy cluster in the Name field in the Define Proxy Cluster
dialog box. The values for the selected proxy are displayed in all the other fields. You can
change these values if required.
When you exit the dialog with OK, a new node named BeanConnect Proxy Clusters is
generated in the navigation tree. The cluster is entered here with the name defined above.
At the same time, the proxy is removed from the list of BeanConnect Proxies. By default,
the first proxy included in the proxy cluster becomes the master proxy.
Displaying the proxies in a cluster
To display the proxies in a proxy cluster, you can either click the proxy cluster node or
choose the Show Cluster Proxies command in the context menu. A list of all the proxies
is now displayed. The individual columns describe the properties of the proxies such as
their names and address data. For further details, consult the online Help.
BeanConnect V2.1
181
Configuring a BeanConnect proxy cluster
Configuration of BeanConnect
6.4.2 Adding a proxy to the proxy cluster
You can add further proxies to the proxy cluster. A maximum of 32 proxies per cluster is
permitted. The corresponding proxy must be installed and the general proxy data must have
been configured using the Management Console, see Section 6.3.1, "General information
on the proxy".
To add another proxy to the cluster:
●
Select the required proxy and choose the Add to Proxy Cluster command in the
context menu. This displays all the configured proxy clusters to which the selected proxy
can be added.
●
Click to select the required cluster and confirm the query with Add. The proxy is added
to this cluster and is removed from the list of proxies.
V
Caution!
When you add a proxy to a proxy cluster, the configuration of the proxy is lost since
it is overwritten by the configuration of the proxy cluster (the proxy cluster is
synchronized).
Figure 24: Adding a proxy to a proxy cluster
182
BeanConnect V2.1
Configuring a BeanConnect proxy cluster
6.4.3 Removing a proxy from a cluster / removing a proxy cluster
You can remove individual proxies from the proxy cluster or remove the proxy cluster itself.
●
To remove a proxy from the proxy cluster, select the required proxy on the list of cluster
proxies and choose the Remove Proxy From Cluster command from the context
menu. After you confirm the prompt, the proxy is removed from the cluster and listed in
the BeanConnect Proxies area again.
●
You remove a proxy cluster by choosing the Remove Proxy Cluster command from the
context menu of the proxy cluster. After this action, all the proxies present in the proxy
cluster are listed in the BeanConnect Proxies area again. The proxies are therefore
not uninstalled but are simply removed from the cluster.
V
Caution!
When you remove a proxy from a proxy cluster or remove the proxy cluster itself,
the proxy retains the configuration that it had in the cluster. In other words, it does
not return to the state it had before it was added to the proxy cluster.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
BeanConnect V2.1
183
Configuring the BeanConnect resource adapter
Configuration of BeanConnect
6.5 Configuring the BeanConnect resource adapter
The configuration data for the BeanConnect resource adapter is described in the resource
adapter's deployment descriptor ra.xml. This deployment descriptor is located in the
BeanConnect RAR archive.
For information on how to adapt the ra.xml file, see Section 4.2, "Configuring global
properties for the resource adapter (ra.xml)".
Alternatively, you can edit the ra.xml file via the BeanConnect Management Console. To
do this, you must configure the BeanConnect resource adapter in the BeanConnect
Management Console.
The configuration dialog differs depending on whether or not the proxy belongs to a cluster.
6.5.1 Adding a resource adapter (no cluster operation)
To add a resource adapter, open the context menu for the Resource Adapter node in the
navigation tree's proxy subtree and choose Add Resource Adapter... Alternatively, you
can click the required node and then run the Add command in the resource adapter list.
The proxy must not be running when it is added. You may therefore need to stop it, for
example using the Stop Proxy command in the proxy's context menu.
Enter the parameters for the resource adapter in the General tab:
184
BeanConnect V2.1
Configuring the BeanConnect resource adapter
Figure 25: Adding a resource adapter without cluster operation
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Name
Freely definable name of the resource adapter. This name is only relevant locally in the
Management Console.
BeanConnect V2.1
185
Configuring the BeanConnect resource adapter
Configuration of BeanConnect
ID / Index
ID is the ID of the resource adapter assigned by the Management Console. This is a number
between 1 and 256.
Index is the index of the resource adapter which is assigned by the Management Console.
The index is only relevant in multiple resource adapter mode This property corresponds to
the resourceAdapterIndex property in the resource adapter's deployment descriptor
ra.xml.
Description
You can enter a freely definable description of the resource adapter here.
Host
Name or IPv4 address of the computer running the application server on which the resource
adapter is deployed.
Listener Port
Number of the listener port of the resource adapter for inbound communication. This
property corresponds to the inboundListenerPort property in the resource adapter's
deployment descriptor ra.xml. If you enter 0 here (or leave the field blank), inbound
communication is not possible.
Proxy URL of OLTP Outbound Communication
URL used for outbound communication in the application server. This URL is defined when
the proxy is configured and cannot be changed. This property corresponds to the proxyURL
property in the resource adapter's deployment descriptor ra.xml.
Transaction Logging
Specifies whether persistent transaction logs are written in the resource adapter in the case
of outbound communication (FILE) or not (NONE). This property corresponds to the
transactionLogging property in the resource adapter's deployment descriptor ra.xml.
If transaction logging is configured then the resource adapter writes a separate log file for
each transaction. The file name consists of the prefix tx. and a number.
Transaction Logging Directory
Directory in which the transaction logs are created in the resource adapter. This property
corresponds to the transactionLogDir property in the resource adapter's deployment
descriptor ra.xml.
186
BeanConnect V2.1
Configuring the BeanConnect resource adapter
MC-CmdHandler of the Resource Adapter
This allows you to define an MC-CmdHandler that is available on the resource adapter
computer and that can be used to administer the resource adapter via the Management
Console. To do this, proceed as follows:
●
Click the ... button in Select MC-CmdHandler to display an additional dialog box
Properties of MC-CmdHandler in which you can enter the data for the
MC-CmdHandler (listener port, password):
Figure 26: Configuring the properties of an MC-CmdHandler
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
If the BeanConnect-RAR archive is also located on this computer, then you can use this
MC-CmdHandler to edit the entries in the resource adapter's deployment descriptor
ra.xml or update these entries in line with the entered parameters. You can do this
using the commands Edit ra.xml of BeanConnect Resource Adapter RAR or Update
ra.xml of BeanConnect Resource Adapter RAR in the resource adapter's context
menu, see Section 6.5.3, "Resource adapter configuration file".
You can also use this MC-CmdHandler to modify the Log4j diagnostic settings.
●
You can enter the fully qualified path name of the Log4j configuration file in Log4j
Configuration File Path (optional).
The Log4j configuration file is always located on the computer on which the application
server runs. This does not have to be the computer on which the BeanConnect
resource adapter is located since the resource adapter cannot be uploaded to the application server computer before deployment.
If you want to change the resource adapter's logging configuration then an
MC-CmdHandler must be running on the computer on which the application server
runs.
BeanConnect V2.1
187
Configuring the BeanConnect resource adapter
Configuration of BeanConnect
6.5.2 Adding a resource adapter in cluster operation
To add a resource adapter in cluster operation, open the context menu for the Resource
Adapter node in the navigation tree's cluster subtree and choose Add Resource
Adapter... Alternatively, you can click the required node and then run the Add command
in the resource adapter list.
Enter the parameters for the resource adapter in the two tabs General and Common
Properties. The parameters specified in Common Properties are the same for all the
resource adapters in a cluster. Any change to these properties therefore affects all the
resource adapters defined in the cluster, whereas the parameters specified in General are
specific to each resource adapter:
Figure 27: Adding a resource adapter in cluster operation
188
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring the BeanConnect resource adapter
Host (General)
Name or IPv4 address of the computer running the application server on which the resource
adapter is deployed. The host specified here must match the value of <host> in a
<host:port> entry of the resourceAdapterAddresses property of the deployment
descriptor ra.xml for the resource adapter.
Listener Port (General)
Number of the listener port of the resource adapter for inbound communication. The host
specified in Host and the listener port must match a <host:port> entry in the
resourceAdapterAddresses property of the deployment descriptor ra.xml for the
resource adapter. If no port is specified there, the specification must match the value in the
inboundListenerPort property.
I
Within a cluster, the Management Console does not permit a
value of 0 or no value to be entered. A port between 1025 and
65535 must be specified even if no inbound communication is
planned.
MC-CmdHandler of the Resource Adapter (General)
These fields allow you to define an MC-CmdHandler that is available on the resource
adapter computer and that can be adapted via the Management Console using the
resource adapter's deployment descriptor ra.xml.
●
If the BeanConnect-RAR archive is also located on this computer, then you can use this
MC-CmdHandler to edit the entries in the resource adapter's deployment descriptor
ra.xml or update these entries in line with the entered parameters. You can do this
using the commands Edit ra.xml of BeanConnect Resource Adapter RAR or Update
ra.xml of BeanConnect Resource Adapter RAR in the resource adapter's context
menu, see Section 6.5.3, "Resource adapter configuration file".
You can also use this MC-CmdHandler to modify the Log4j diagnostic settings.
© cognitas GmbH 2001-2
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
Click the ... button in Select MC-CmdHandler to display an additional dialog box in
which you can enter the data for the MC-CmdHandler (listener port, password):
●
You can enter the fully qualified path name of the Log4j configuration file in Log4j
Configuration File Path (optional).
The Log4j configuration file is always located on the computer on which the application
server runs. This does not have to be the computer on which the BeanConnect
resource adapter is located since the resource adapter cannot be uploaded to the application server computer before deployment.
If you want to change the resource adapter's logging configuration then an
MC-CmdHandler must be running on the computer on which the application server
runs.
BeanConnect V2.1
189
Configuring the BeanConnect resource adapter
Configuration of BeanConnect
Transaction Logging (Common Properties)
Specifies whether persistent transaction logs are written in the resource adapter in the case
of outbound communication (FILE) or not (NONE). This property corresponds to the
transactionLogging property in the resource adapter's deployment descriptor ra.xml.
If transaction logging is configured then the resource adapter writes a separate log file for
each transaction. The file name consists of the prefix tx. and a number.
Transaction Logging Directory (Common Properties)
Directory in which transaction logging is stored in the resource adapter. This property corresponds to the transactionLogDir property in the resource adapter's deployment
descriptor ra.xml.
Proxy Reconnect Count (Common Properties)
Specifies the number of connection requests (calls to getConnection()) after which the
assignment between the resource adapter instance and the proxy application must be
made again. This property controls the usage-driven reassignment of a resource adapter
instance to a proxy application. It corresponds to the proxyReconnectCount property in
the resource adapter's deployment descriptor ra.xml.
The default value is 100.
If a cluster is operated with more resource adapter instances than proxy instances then a
larger value or the value 0 should be entered for this parameter. The value 0 deactivates
the reconnect counter.
Proxy Reconnect Interval (min) (Common Properties)
Specifies the time in minutes after which the assignment between the resource adapter
instance and the proxy application must be made again. This property controls the
time-driven reassignment of a resource adapter instance to a proxy application. It corresponds to the proxyReconnectInterval property of the resource adapter's deployment
descriptor ra.xml.
The default value is 10 minutes.
If a cluster is operated with more resource adapter instances than proxy instances then a
larger value or the value 0 should be entered for this parameter. The value 0 deactivates
the reconnect timer.
190
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring the BeanConnect resource adapter
6.5.3 Resource adapter configuration file
The resource adapter's global configuration data is defined in the file ra.xml, see
Section 4.2, "Configuring global properties for the resource adapter (ra.xml)". ra.xml is
located in the BeanConnect-RAR archive. The Management Console can access this file
and modify the configuration properties if one of the following conditions is satisfied:
●
The BeanConnect RAR archive is located on the computer on which the Management
Console runs. In this case, it must be located under the user ID under which the
Management Console runs or the file access permissions must be set accordingly.
●
The BeanConnect RAR archive is located on a computer on which an MC-CmdHandler
runs. In this case, it must be located under the user ID under which the MC-CmdHandler
runs or the file access permissions must be set accordingly.
Updating the configuration file via the Management Console
To update the configuration file ra.xml, choose the command Update ra.xml of
BeanConnect Resource Adapter RAR from the resource adapter's context menu. In a
proxy cluster, you must open the context menu in the Resource Adapters node and not in
the resource adapter itself.
This overwrites the values in ra.xml with the values specified in the Management Console.
The dialog box Edit ra.xml of BeanConnect Resource Adapter RAR is now opened.
Here, you can modify all the properties of ra.xml, see also Section 4.2.1, "Defining global
properties in ra.xml" and the online Help.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Editing the configuration file via the Management Console
To edit the configuration file ra.xml, choose the command Edit ra.xml of BeanConnect
Resource Adapter RAR from the resource adapter's context menu. In a proxy cluster, you
must open the context menu in the Resource Adapters node and not in the resource
adapter itself.
BeanConnect V2.1
191
Configuring the BeanConnect resource adapter
Configuration of BeanConnect
Figure 28: Editing the configuration file ra.xml
After an update or following direct editing, the modified values do not take effect until the
BeanConnect RAR archive has been deployed (see Section 4.2.2.1, "Deploying the
resource adapter".
I
192
Please note that you must enter the required changes in the
Management Console of the corresponding resource
adapter(s) before using the Update ra.xml... command.
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring the EIS partners
6.6 Configuring the EIS partners
A proxy or proxy cluster can communicate with multiple EIS partners, i.e. with multiple
openUTM/CICS applications. When you configure the proxy/proxy cluster, you specify the
type of EIS partners it is to communicate with (only openUTM, only CICS, or both).
To allow an EIS partner to be managed, the partner must be added to the Management
Console's configuration data. As far as this operation is concerned, there are only slight
differences between proxies and proxy clusters.
Each partner application known by the Management Console is represented by an EIS
partner object in the navigation tree's proxy subtree beneath the EIS Partners node.
I
Here, you only have to configure EIS partners that are either of
type openUTM and are communicated with via the OSI-TP
protocol or are of type CICS.
Click on the EIS Partners node to display a list of the managed EIS partners of the proxy.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Figure 29: Displaying and configuring EIS partners
BeanConnect V2.1
193
Configuring the EIS partners
Configuration of BeanConnect
6.6.1 Configuring EIS partners of type openUTM
Before you can configure an EIS partner of type openUTM, the proxy or proxy cluster must
be configured accordingly in the General tab, see Figure 18, "General information on a
proxy" on page 169.
6.6.1.1
Adding EIS partners of the type UTM
To add a new EIS partner:
1. Click the Add button beneath the list of EIS partners or choose Add EIS Partner from
the context menu of an existing EIS partner object or the EIS Partner node.
If the proxy/proxy cluster is configured for the two partner types (UTM and CICS), then
the dialog box Choose EIS Partner Type is displayed during this operation. Here you
must choose UTM application.
2. Define the properties for the EIS partner. The property sheet is opened automatically
and contains the tabs General, UTM Partner and Availability Check.
The following properties are requested:
194
BeanConnect V2.1
Configuring the EIS partners
General tab (openUTM Partners)
Figure 30: General properties of an EIS partner of Type openUTM
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Name / Description
Name is the name of the EIS partner. This must be unique to the proxy. Additionally, you
can enter a Description for the EIS partner. For a created EIS partner, the EIS ID is shown
beneath the name. (cannot be changed).
Type
Displays the type of EIS partner: here UTM, cannot be changed.
Active
The option Active controls whether the EIS partner definition is active or not. Only active
EIS partners will be included in the configuration of the proxy and the EIS partner (Update
Configuration command in the proxy node or proxy cluster node).
BeanConnect V2.1
195
Configuring the EIS partners
Configuration of BeanConnect
Proxy Host Name
Computer name under which the proxy host is known in the openUTM partner application.
In the case of an EIS partner in the proxy cluster, there is an entry field for each cluster proxy
in which you must specify the computer name under which the corresponding proxy is
known to the EIS partner.
By default, this field is set to the computer name entered under General for Host in the Edit
Properties command.
Connections
Specifies the maximum number of concurrent connections allowed between proxy and the
EIS partner.
Proxy Contention Winners
Specifies the number of connections for which the proxy should be contention winner. The
number you should specify depends on the favored communication type (outbound or
inbound communication).
The following applies in principle:
●
Outbound communication: the proxy should be the contention winner.
●
Inbound communication: the EIS partner should be the contention winner.
Proxy Autoconnect
Defines the number of connections to be established when starting the proxy.
I
The specifications in the fields Proxy Contention Winners and
Proxy Autoconnect must not exceed the value for Connections.
Proxy Idletimer (sec)
Specifies the time in seconds after which the BeanConnect proxy container is to clear down
the connection to the EIS partner if no communication has taken place over the connection
during that time.
Possible values: 0 (default) through 32767.
0 means that the timer is not used.
196
BeanConnect V2.1
Configuring the EIS partners
Prefix
The prefix is included as a component in names which are used in configuration statements.
This prefix must be unique for all proxies running on the same host. The prefix must
comprise exactly three characters (uppercase letters or digits). The first character must be
an uppercase letter.
UTM Partner tab
Figure 31: Properties of the openUTM partner
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
If expert mode is enabled then additional fields are displayed. These are described later on,
see "UTM Partners - Additional Fields in Expert Mode" on page 200.
BeanConnect V2.1
197
Configuring the EIS partners
Configuration of BeanConnect
Host
The name of the computer on which the openUTM partner application is located, from 1 to
a maximum of 8 characters in length.
Partner LPAP
Specifies the LPAP name under which the openUTM partner application addresses the
BeanConnect proxy and therefore also the application server during inbound communication, 1 to a maximum of 8 characters in length. From this name, the Management Console
generates an OSI-LPAP statement for generating the openUTM partner application.
Partner Idletimer (sec)
Specifies the time in seconds after which the EIS partner is to clear down the connection to
the BeanConnect proxy container if no communication has taken place over the connection
during that time.
It is recommended that you choose a value for Partner Idletimer that is smaller than the
one specified for Proxy Idletimer.
0 means that the timer is not used.
Possible values: 0 (default) through 32767.
Is BS2000
This option specifies whether or not the openUTM partner application is located on a
BS2000 system. If this option is activated then the Management Console generates
KDCDEF and BCMAP statements for a BS2000 system.
Admin Permission
This option specifies whether the proxy, and, implicitly, the application server also, are to
possess administrative permissions in the openUTM partner application during outbound
communication.
Listener Port
Defines the port at which the openUTM partner application waits for requests to establish
a connection. Permitted values: 102 and 1025 through 32767
If you have not enabled Is BS2000 and you select the Use Existing option for Access
Point , you must enter the value generated in the openUTM partner application here
(ACCESS-POINT statement, LISTENER-PORT operand).
Application Entity Qualifier
The Application Entity Qualifier is an address component for the openUTM partner application's access point.
198
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring the EIS partners
If you select the Use Existing option for Access Point , you must enter the value generated
in the openUTM partner application here (ACCESS-POINT statement,
APPLICATION-ENTITY-QUALIFIER operand).
Application Process Title
The Application Process Title is an address component for the openUTM partner application's UTMD statement.
If you select the Use Existing option for Access Point , you must enter the value generated
in the openUTM partner application (UTMD statement, APPLICATION-PROCESS-TITLE
operand).
Access Point
Defines the properties of the access point used to address the openUTM partner application during outbound communication. The access point is generated in the openUTM
partner application using the KDCDEF statement ACCESS-POINT.
The three options Create New (Generic Names), Create New (Own Names) and Use
Existing are used to determine whether the Management Console generates KDCDEF
statements for the access point, or whether an access point that already exists in the
openUTM partner application is to be used.
Create New (Generic Names)
If you select this option, the Management Console generates an ACCESS-POINT
statement with generic values. The Management Console enters these values in the
Access Point Name, Transport Selector and Transport Selector Format fields.
They cannot be changed.
●
Create New (Own Names)
If you select this option, the Management Console generates an ACCESS-POINT
statement with specific values. The Management Console enters these values in the
fields Access Point Name, Transport Selector and Transport Selector Format. You
can modify the values.
●
Use Existing
If you select this option, the Management Console does not generate an
ACCESS-POINT statement. This option is designed for circumstances in which you
want to use an existing access point in the openUTM partner application. You must
enter the values for this access point in the Access Point Name, Transport Selector
and Transport Selector Format fields. Furthermore, the values you enter in the
Application Entity Qualifier and Listener Port fields must have been generated in the
openUTM partner application.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
●
BeanConnect V2.1
199
Configuring the EIS partners
●
Configuration of BeanConnect
Access Point Name
Name of the access point in the openUTM partner application.
If you select Create New (Generic Names), this contains the generated name (cannot
be changed).
If you select Create New (Own Names), you must enter a freely-definable name here
(1 through 8 characters in length).
If you select Use Existing, you must enter the name generated in the ACCESS-POINT
statement of the openUTM partner application.
●
Transport Selector
Transport selector of the access point in the openUTM partner application.
If you select Create New (Generic Names), this contains the generated name (cannot
be changed).
If you select Use Existing, you must enter the name generated with T-SEL= in the
ACCESS-POINT statement of the openUTM partner application.
If you select Create New (Own Names), you must enter a freely-definable name here.
This can be 1 through 8 characters in length, the first character must be an uppercase
alphabetic character, otherwise alphabetic characters, numeric characters and the
special characters #, $ and @ are permitted.
UTM Partners - Additional Fields in Expert Mode
If expert mode is active then the following additional fields are also displayed:
●
Application Program Interface Mode of EIS Partner
This field is only relevant for partners that use the XATMI interface, see Section 6.6.3,
"Configuring EIS partners of type XATMI". In the case of openUTM partner applications
that use the KDCS interface, the value Standard must always be set for API Mode.
●
Transport Selector Format
Format used to encode the transport selector.
If you select Create New (Generic Names), this contains the generated value (cannot
be changed).
If you select Create New (Own Names), you can choose between ASCII, EBCDIC and
TRANSDATA (default). If the EIS partner is running under BS2000, TRANSDATA must
be used as the transport selector format.
If you select Use Existing, you must enter the value generated with TSEL-FORMAT=
in the ACCESS-POINT statement of the openUTM partner application.
200
BeanConnect V2.1
Configuring the EIS partners
Availability Check tab (openUTM partners)
Figure 32: Properties of the EIS partner for the availability check
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
This dialog box allows you to select a dialog service in the partner application which is
called when checking the availability of an EIS partner. When this is done, the message
defined in Message is passed to the specified service in the EIS partner. As soon as the
response is received, the EIS partner is flagged as available. The response is output in the
Management Console.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
You cannot complete this dialog box properly unless you have defined at least one
outbound service for the EIS partner, see Section 6.7.1, "Configuring outbound services".
Check Service
This lists all the outbound services defined for this partner. Select a suitable service from
the list. The service is always of type Dialog.
Character Code
Character set used by the EIS partner:
Possible values: ASCII or EBCDIC.
Message
Message sent to the EIS partner when checking availability. The maximum length of the
message is 80 characters.
User
User ID if the service is to be called under a specific user ID.
BeanConnect V2.1
201
Configuring the EIS partners
Configuration of BeanConnect
Password
Password for the user ID if a password is required.
Perform Check
This option allows you to temporarily disable the availability check for this EIS partner
without losing the settings, such as the service to be called.
If the option is enabled, the availability check is performed with the specified parameters.
If you disable this option, the availability check for this EIS partner is disabled until the option
is enabled again. Both automatic availability checking and the availability check performed
by issuing a command in the proxy or proxy cluster's context menu are disabled. If the EIS
partner is checked "manually" (using its context menu), the check is performed irrespective
of this setting.
6.6.1.2
Configuration files for EIS partners of type openUTM
The Management Console creates configuration fragments for the EIS partners. The next
time you save the proxy configuration (see Section 6.9, "Saving and activating the configuration of the BeanConnect proxy"), the Management Console generates all the configuration statements for all the EIS partners. Before this is possible, you must have enabled
the Active option on the General tab.
Files with KDCDEF statements are created. In the case of openUTM partner applications
on BS2000 systems, files containing BCMAP statements are also generated.
The configuration files are located in the directory <MC_Home>/genfiles under the
following names:
●
Single proxy:
ProxyID.<p-id>.EISPartnerID.<e-id>.UTM.txt (KDCDEF statements)
ProxyID.<p-id>.EISPartnerID.<e-id>.BCMAP.txt (BCMAP statements)
●
Proxy cluster:
ClusterID.<c-id>.EISPartnerID.<e-id>.UTM.txt (KDCDEF statements)
ClusterID.<c-id>.EISPartnerID.<e-id>.BCMAP.txt (BCMAP statements)
<MC_Home> is the directory under which the Management Console is installed.
<p-id>, <e-id> and <c-id> designate the IDs for the proxy, EIS partner and proxy cluster
assigned by the Management Console.
The file containing the BCMAP statements is only generated for openUTM partners in
BS2000 systems (the Is BS2000 option is enabled).
For further details on the configuration tasks in EIS partners, see Chapter 7, "Adapting the
configuration in the EIS partner".
202
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring the EIS partners
6.6.2 Configuring EIS partners of type CICS
Before you can configure an EIS partner of type CICS, the proxy or proxy cluster must be
configured accordingly in the General tab, see, for example, "Possible EIS Partner Types"
on page 170.
Generally speaking, an EIS partner in the proxy cluster is configured in exactly the same
way as an individual proxy except for one small difference relating to the configuration of the
communication service.
6.6.2.1
Adding EIS partners of the type CICS
To add a new EIS partner:
1. Click the Add button beneath the list of EIS partners or choose Add EIS Partner from
the context menu of an existing EIS partner object or the EIS Partners node.
If the proxy/proxy cluster has been configured for the two partner types (UTM and
CICS), then the dialog box Choose EIS Partner Type is also displayed. Here, you
should select CICS application.
2. Define the properties for the EIS partner. The property sheet is opened automatically
and contains the tabs General, Communication Service, CICS Partner and Availability Check.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
The following properties are requested:
BeanConnect V2.1
203
Configuring the EIS partners
Configuration of BeanConnect
General tab (CICS partners)
Figure 33: General properties of an EIS partner of type CICS
Name / Description
The Name of the EIS partner. This must be unique to the proxy. Additionally, you can enter
a Description for the EIS partner. For a created EIS partner, the EIS ID is shown in the ID
field beneath the name (cannot be changed).
Type
Displays the type of EIS partner: here CICS, cannot be changed.
Active
The option Active controls whether the EIS partner definition is active or not. Only active
EIS partners will be included in the configuration of the proxy and the EIS partner. Inactive
EIS partners are struck through to identify them in the navigation tree.
204
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring the EIS partners
Partner Type
Specifies the type of outbound communication performed with the CICS partner:
●
Dialog: Communication over dialog services.
●
Asynchronous: Communication over asynchronous services.
In BeanConnect, a CICS partner may be configured either as a dialog partner only or as an
asynchronous partner only. If both communication types are to be permitted for a single real
CICS partner, the real CICS partner must be configured twice using the same address data
and different LU names: Once as a dialog partner and once as an asynchronous partner.
Connections
Specifies the maximum number of concurrent connections allowed between proxy and the
EIS partner.
Prefix
The prefix is included as a component in names which are used in configuration statements.
This prefix must be unique for all proxies running on the same host. The prefix must
comprise exactly three characters (uppercase letters or digits) to ensure that the generated
names are unique. The first character must be an uppercase letter.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
DLC Type
Specifies the communication type of the connection between the proxy and the EIS partner.
It can be LAN or IBM-EEDLC
BeanConnect V2.1
205
Configuring the EIS partners
Configuration of BeanConnect
Communication Service tab
This tab has a different layout for proxy clusters containing multiple proxies. Consequently,
both variants are displayed here.
Figure 34: Communication service properties of a CICS partner (single proxy)
Figure 35: Communication service properties of a CICS partner in a proxy cluster
206
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring the EIS partners
Mode Name
Specifies the name of an entry in the VTAM MODETAB on the z/OS mainframe. Such
entries describe the properties of sessions between the communication service and VTAM.
You must specify the name of an entry that is suitable for LU6.2 communication with CICS.
openUTM-LU62 Gateway Listener Port
Specifies the partner-specific number of the port where the openUTM-LU62 Gateway is
listening for messages. This number must not be used by another EIS partner communication service configuration or by another application.
In the case of a proxy cluster, one field is output for each proxy. In these fields, enter the
port number on which the openUTM-LU62 Gateway receives messages for the EIS partner
for each proxy. The port numbers must be different and must be uniquely assigned to an
"EIS partner <-> proxy" pair. In other words, the same port number must not be assigned
for different "EIS partner <-> proxy" pairs.
Logical Unit Name
Specifies the proxy's unique application name in the SNA network.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
In the case of a proxy cluster, one field is output for each proxy. Here, you can enter the
application name of the corresponding proxy.
BeanConnect V2.1
207
Configuring the EIS partners
Configuration of BeanConnect
CICS Partner tab
Figure 36: Properties of the CICS partner on a z/OS mainframe
The layout of this dialog box depends on the DLC type. Many of the fields are only displayed
for a specific setting. All the fields are described below.
EIS Platform
The EIS Platform the CICS partner is running on. Currently only z/OS is possible, cannot
be changed.
Logical Unit
Describes the CICS partner's logical unit.
208
●
Network Name is the NETID in the VTAM start options on the z/OS mainframe.
●
Name is the application name of the CICS region as specified in the VTAM statement
APPL at the z/OS mainframe.
●
For IP Address, enter the IP address of the z/OS mainframe on which CICS runs.
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring the EIS partners
Control Point
Specifies the VTAM control point on the z/OS mainframe.
●
Network Name is the NETID in the VTAM start options on the z/OS mainframe.
●
Name is the value specified in the SSCPNAME parameter in the VTAM start options on
the z/OS mainframe.
VTAM
Group Name specifies the VTAM group name. This is the name of the GROUP macro in
the VTAM major node definition for the Enterprise Extender.
MAC Address
MAC address of the z/OS mainframe on which the CICS partner runs if the DLC type is
LAN. Otherwise, this field is not displayed
Explanations of SNA-specific terms can be found in the
glossary.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
I
BeanConnect V2.1
209
Configuring the EIS partners
Configuration of BeanConnect
Availability Check tab (CICS partners)
Figure 37: Properties of the CICS type EIS partner for the availability check
This dialog box allows you to select a dialog service in the partner application which is
called when checking the availability of an EIS partner. When this is done, the message
defined in Message is passed to the specified service in the EIS partner application. As
soon as the response is received, the EIS partner is flagged as available. The response is
output in the Management Console.
You cannot complete this dialog box properly unless you have defined at least one
outbound service for the EIS partner, see Section 6.7.1, "Configuring outbound services".
Check Service
This lists all the outbound services defined for this partner. Select a suitable service from
the list. The service is always of type Dialog.
Character Code
Character set used by the EIS partner:
Possible values: ASCII or EBCDIC.
Message
Message sent to the EIS partner when checking availability. The maximum length of the
message is 80 characters.
Users
User ID if the service is to be called under a specific user ID.
210
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring the EIS partners
Password
Password for the user ID if a password is required.
Perform Check
This option allows you to temporarily disable the availability check for this EIS partner
without losing the settings, such as the service to be called.
If the option is enabled, the availability check is performed with the specified parameters.
June 8, 2009 7:06 pm
If you disable this option, the availability check for this EIS partner is disabled until the option
is enabled again. Both automatic availability checking and the availability check performed
by issuing a command in the proxy or proxy cluster's context menu are disabled. If the EIS
partner is checked "manually" (using its context menu), the check is performed irrespective
of this setting.
6.6.2.2
Configuration files for the EIS partners of the type CICS
The Management Console creates configuration fragments for the defined proxy and EIS
partners. Generation of all configuration files is performed automatically by the
Management Console the next time you save the proxy configuration (see "Saving and
activating the configuration of the BeanConnect proxy" on page 228). All configuration
statements for the proxy and all defined EIS partners are generated.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
The Management Console generates configuration statements for the following components:
●
BeanConnect proxy container
●
openUTM-LU62 Gateway of the proxy
●
all partner applications of the BeanConnect proxy
●
VTAM (for the connection)
●
Communications service, i.e. SNAP-IX or IBM Communications Server (for the proxy
side of the connection)
The configuration files are located in the directory <MC_Home>/genfiles under the
following names:
●
Single proxy:
ProxyID.<p-id>.EISPartnerID.<e-id>.CICS.txt
This file contains generation statements for the CICS partner application.
ProxyID.<p-id>.EISPartnerID.<e-id>.VTAM.txt
This file contains generation statements for the communication component at the EIS
partner's side of the connection (VTAM).
BeanConnect V2.1
211
Configuring the EIS partners
●
Configuration of BeanConnect
Proxy cluster:
ClusterID.<c-id>.ProxyID.<p-id>.EISPartnerID.<e-id>.CICS.txt
This file contains generation statements for the CICS partner application.
ClusterID.<c-id>.ProxyID.<p-id>.EISPartnerID.<e-id>.VTAM.txt
This file contains generation statements for the communication component at the EIS
partner's side of the connection (VTAM).
<MC_Home> is the directory under which the Management Console is installed.
<p-id>, <e-id> and <c-id> designate the IDs for the proxy, EIS partner and proxy cluster
assigned by the Management Console.
Information on configuration tasks in the EIS partner can be found in Chapter 7, "Adapting
the configuration in the EIS partner".
212
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring the EIS partners
6.6.3 Configuring EIS partners of type XATMI
You must enable expert mode before you can use this function.
If you want to configure an EIS partner of type XATMI, then the proxy must be configured
with API Mode XATMI or ALL, see Section 6.3.4.3, "Application Program Interface Mode
(API Mode)".
When configuring the proxy, you must specify either Only UTM Partners or UTM and CICS
Partners as the EIS partner type. You always configure an EIS partner of type XATMI in the
same way as a partner of type openUTM.
Proceed as follows to add a new XATMI partner:
1. Click the Add button below the list of EIS partners or open the context menu for an
existing EIS partner object or for the EIS Partners node and choose Add EIS Partner.
2. Define the properties for the EIS partner. The properties sheet opens automatically. It
contains the tabs General, UTM Partner and Availability Check.
Complete these fields in the same way as for an openUTM partner, see Section 6.6.1.1,
"Adding EIS partners of the type UTM". The only difference compared to an EIS partner
of type openUTM is that, when expert mode is enabled, the value XATMI is displayed
in the API Mode field.
The same configuration data is displayed as for an EIS partner of type openUTM, see also
Section 6.6.1.2, "Configuration files for EIS partners of type openUTM".
To remove an EIS partner, choose Remove EIS Partner from the context menu of the EIS
partner. Alternatively, you can select one or more EIS partners in the list and click the
Remove button beneath the list.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
6.6.4 Removing an EIS partner
BeanConnect V2.1
213
Configuring outbound communication
Configuration of BeanConnect
6.7 Configuring outbound communication
Outbound communication denotes communication from the application server to the EIS
partner. For outbound communication, you have to configure outbound services and
outbound communication endpoints.
An outbound service represents a service (e.g. transaction code) inside the EIS partner.
Each service of an EIS partner which is to be called from the application server, must be
configured as an outbound service. It can either be used implicitly if it is assigned as a
service to a communication endpoint or can be set explicitly in the EJB via the method
setServiceName.
Each outbound communication endpoint represents a communication endpoint inside the
EIS partner for outbound communication and is therefore EIS-specific. A connection factory
is assigned to a communication endpoint with the configuration property connectionURL
and is thus assigned to a specific EIS partner. An EIS partner can have multiple outbound
communication endpoints.
You can find examples of how to use the BeanConnect programming interfaces for developing EJBs in the section "Code samples for outbound communication" on page 309.
6.7.1 Configuring outbound services
To configure outbound services, click the Services node beneath the Outbound node in
the navigation tree of a proxy.
214
BeanConnect V2.1
Configuring outbound communication
Figure 38: Configuring outbound services
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
To display a list of the outbound services of a proxy, open the subtree beneath the
Outbound node and then click on Services or alternatively choose Show Outbound
Services from the context menu of the Services node.
To add a new outbound service, click the Add button below the list or choose Add
Outbound Service from the context menu of an existing service or the Services node. The
property sheet is opened.
BeanConnect V2.1
215
Configuring outbound communication
Configuration of BeanConnect
The following properties have to be specified for an outbound service:
Partner Service Name / Description
Specifies the name of the service inside the EIS partner that is represented by this
outbound service. Additionally you can enter a Description for the outbound service.
Type
Type specifies the communication type of the service. It can be Dialog or Asynchronous.
Reply Timer (sec)
The proxy monitors the responses of an outbound service. If no response is received within
the time defined here, the proxy rolls back the corresponding transaction. This parameter
can only be set or changed for services of the type Dialog.
Removing an outbound service
To remove an outbound service, choose Remove Outbound Service from the context
menu of the service. Alternatively you can select one or more services in the list and click
the Remove button beneath the list.
216
BeanConnect V2.1
Configuring outbound communication
6.7.2 Configuring outbound communication endpoints
To configure outbound communication endpoints, click the Communication Endpoints
node beneath the Outbound node in the navigation tree of a proxy.
Figure 39: Configuring outbound communication endpoints
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
To display a list of the outbound communication endpoints of a proxy, click on the
Communication Endpoints node or alternatively choose Show Outbound
Communication Endpoints from the context menu of the Communication Endpoints
node.
BeanConnect V2.1
217
Configuring outbound communication
Configuration of BeanConnect
To add a new outbound communication endpoint, click the Add button below the table.
Alternatively, you can choose Add Outbound Communication Endpoint from the context
menu of an existing endpoint or the Communication Endpoints node. The property sheet
is opened.
The following properties have to be specified for an outbound communication endpoint:
Name / Description
Name specifies the symbolic name of the outbound communication endpoint. Additionally,
you can enter a Description for the outbound communication endpoint.
The deployer of a bean uses this name when deploying a bean in the application server to
refer to the service inside the EIS partner. For detailed information on this topic please refer
to section "Deploying an Enterprise JavaBean for OSI-TP / LU6.2" on page 111.
EIS Partner
Name of the EIS partner the communication endpoint belongs to. This parameter can only
be selected when creating a new endpoint. The EIS partner must be specified before.
Partner Service
Specifies the real name of the service inside the EIS partner that is represented by this
outbound communication endpoint. This service must have been defined already as an
outbound service. All the defined services are shown in the drop-down list.
I
Each <connector-factory> entry contained in the
oc4j-ra.xml file, must point to a defined outbound communication endpoint (see Section 4.3, "Setting configuration
properties for outbound communication via OSI-TP / LU6.2").
To remove an outbound communication endpoint, choose Remove Outbound
Communication Endpoint from the context menu of the endpoint. Alternatively you can
select one or more endpoints in the list and click the Remove button beneath the list.
218
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring inbound communication
6.8 Configuring inbound communication
During inbound communication, an EIS partner sends messages to a message endpoint
application in a J2EE application server.
The name of the message endpoint, which is defined in the OLTP message-driven bean's
deployment descriptor, must be known to the proxy. You must therefore configure an
inbound message endpoint in the Management Console. The name of this inbound
message endpoint must match the OLTP message-driven bean's messageEndpoint
property which is defined in the file ejb-jar.xml.
You will find examples on using the BeanConnect programming interfaces for developing
OLTP message-driven beans for inbound communication in the section "Code samples for
inbound communication" on page 327.
6.8.1 Configuring inbound message endpoints
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
The inbound message endpoints are accessible from the Message Endpoints node
beneath the Inbound node in the navigation tree's proxy subtree.
BeanConnect V2.1
219
Configuring inbound communication
Configuration of BeanConnect
Figure 40: Configuring inbound message endpoints
To display the list of the inbound message endpoints of a proxy, click on the Message
Endpoints node or alternatively choose Show Inbound Message Endpoints from the
context menu of the Message Endpoints node.
220
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring inbound communication
To add a new inbound message endpoint, click the Add button below the list, choose Add
Inbound Message Endpoint from the context menu of an existing endpoint or from the
context menu of the Message Endpoints node. The property sheet is opened.
The following properties have to be specified for an inbound message endpoint:
Name / Description
Name specifies the symbolic name of the inbound message endpoint. This name must
correspond to the name used in the deployment descriptor of the OLTP message-driven
bean within the application server (property messageEndpoint defined in ejb-jar.xml)
(see Section 4.5, "Setting configuration properties for inbound communication").
Additionally, you can enter a Description for the inbound message endpoint.
Type
Type specifies the communication type of the connection. Depending on the message
listener interface implemented by the OLTP message-driven bean, the type can be Dialog
or Asynchronous.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
BeanConnect supports the following message listener interfaces (defined as
messaging-type in the ejb-jar.xml file):
●
net.fsc.jca.communication.AsyncOltpMessageListener (asynchronous
communication)
●
net.fsc.jca.communication.OltpMessageListener (dialog communication)
●
javax.resource.cci.MessageListener (dialog communication)
Service Names
Defines one or more inbound services that are assigned to the inbound message endpoint;
a service name may be up to eight characters in length. If you specify multiple services then
they must be separated by commas. However, exactly one inbound message endpoint must
be assigned to an inbound service.
In the case of inbound communication with an openUTM partner over OSI-TP, each of these
names must be explicitly generated in the EIS partner. To this end, the name is specified as
the value of the RTAC parameter in an LTAC statement.
In a CICS program, the service name is used to address the inbound message endpoint.
You can modify the properties of an inbound service, see Section 6.8.2, "Configuring
inbound services".
BeanConnect V2.1
221
Configuring inbound communication
Configuration of BeanConnect
Resource Adapter
In multiple resource adapter mode, you select the resource adapter assigned to the inbound
message endpoint here. If only one resource adapter has been defined then this is
displayed (cannot be changed). This field is not output in cluster operation.
Reply Timer (sec)
Monitors the response time of the resource adapters on calling the OLTP message-driven
bean.
If no response has been received from the resource adapter after this time has elapsed, the
proxy container clears the connection to the resource adapter and rolls back the transaction
if necessary.
If you specify 0, no monitoring is performed.
Transaction Timer (sec)
Monitors the transaction duration in the application server if a transaction is propagated to
the application server. If you specify 0, no monitoring is performed.
A transaction is propagated to the application server
●
if the onMessage() method of the OLTP message-driven bean was deployed with the
transaction attribute Required and Asynchronous was selected as the Type or
●
if the onMessage() method of the OLTP message-driven bean was deployed with the
transaction attribute Required and Dialog was selected as the Type and a transaction
was propagated from EIS to the proxy.
If the transaction is not completed in the specified period, it is rolled back.
Make sure you take account of the time the EIS partner requires for processing, e.g. for
accessing a database. Do not set this value too low.
If you activate both timers (both values > 0), you should set a value for the Transaction
Timer that is at least as great as that of the Reply Timer.
State
Displays the state of the inbound message endpoint. The inbound message endpoint can
have the state Unknown, Available or Not Available.
222
●
Unknown means that the state has not yet been checked.
●
Available means that an inbound message endpoint with this name exists in the
resource adapter. The proxy container must be available to obtain the state of an
inbound message endpoint.
●
Not Available means that an inbound message endpoint with this name does not exist
in the resource adapter.
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring inbound communication
You can update the state by clicking the Update State button beneath the list or by choosing
Update State from the context menu of the endpoint. Additionally, the names of other
inbound message endpoints available in the resource adapter which you have not defined
in the Management Console are displayed.
Waiting Messages
This field is only displayed in expert mode. The value specifies the number of messages
addressed to the services indicated in Service Names that are currently waiting in the
proxy container.
Unknown means that the status has not yet been checked. Values > 0 are only possible if
the type is Asynchronous.
Dead Letter Queue Messages
This field is only displayed in expert mode. The value specifies how many messages were
originally sent to this message endpoint and are currently in the dead letter queue of the
proxy container.
Unknown means that the status has not yet been checked. Values > 0 are only possible if
the type is Asynchronous.
If the proxy is not running at the time the inbound message endpoint is added then the
configuration must be updated before the proxy is started again (Update Configuration,
see Section 6.9, "Saving and activating the configuration of the BeanConnect proxy").
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
To remove an inbound message endpoint, choose the Remove Inbound Message
Endpoint command in the endpoint's context menu. Alternatively, you select one or more
endpoints in the list and then click the Remove button below the list.
BeanConnect V2.1
223
Configuring inbound communication
Configuration of BeanConnect
6.8.2 Configuring inbound services
An inbound service is a service which an EIS partner addresses during inbound communication. You specify the name of the service when configuring an inbound message
endpoint. You can also specify multiple service names for an inbound message endpoint.
However, exactly one inbound message endpoint must be assigned to any given service
name.
You can modify the coding properties of an inbound service. To do this, proceed as follows:
●
Click the Services node in the Inbound node and then click Show Inbound Services.
A list of all the inbound services is now displayed.
●
Select the required inbound service in the list and click the Edit button (alternatively:
double-click the service).
●
Configure the inbound service in the dialog box
Edit Properties of Inbound Service... .
Figure 41: Configuring an inbound service
The following inbound service properties are displayed or can be defined.
Service Name
Name of the inbound service as specified in the assigned message endpoint, cannot be
changed. This is the name used by the EIS partner to address the service.
224
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring inbound communication
Description
You can enter a description here.
Inbound Message Endpoint
Name of the inbound communication message endpoint, cannot be changed.
Type
Type of the inbound service (Dialog or Asynchronous cannot be changed).
Partner Character Code
Specifies the type of character set used in the EIS partner (possible choices: ASCII or
EBCDIC). This setting is used to send a correctly encoded message to the EIS partner if
an error occurs before the inbound message endpoint is called.
Partner Encoding
Name of a code table for converting byte code (e.g. EBCDIC) to Java Unicode. If you specify
a code table here, the following values are overwritten in the deployment descriptor of the
message-driven bean:
●
encoding is replaced by the value specified here
●
encodingActive is set to true
I
If the proxy is configured with API Mode: All then the XATMI
option is also displayed in expert mode. You must enable this
option if the service is to be used by an XATMI partner.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
The value <set by activation config property "encoding"> (default) or a blank
entry causes the setting in the deployment descriptor to be used.
BeanConnect V2.1
225
Configuring inbound communication
Configuration of BeanConnect
6.8.3 Setting up users for access to inbound message endpoints
If the EIS partner uses user IDs for inbound communication then you must define these in
the proxy as otherwise the job will be rejected. if the user ID needs a password then you
must also define this.
Otherwise, this operation is optional.
You access the user entries via the Users node which is located below the Inbound node
in the proxy subtree.
To display the list of users, click the Users node. Alternatively, open the context menu for
the Users node and choose Show Inbound Users.
Figure 42: Configuring users for inbound communication
To add a new user, click the Add button below the list or choose Add Inbound User from
the context menu of an existing user or the Users node.
226
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring inbound communication
Enter the Name. Additionally, you optionally can enter a Description and a Password for
the inbound user.
To remove a user from the Management Console, choose Remove Inbound User from the
context menu of the user. Alternatively you can select one or more users in the list and click
the Remove button beneath the list.
6.8.4 Configuring the error message prefix for inbound communication
If errors occur during inbound communication then an error message may be sent to the
affected EIS partner. By default, these error messages have the prefix BCSYSEX.
You can activate and deactivate this prefix as follows:
●
In the context menu of the Inbound node, choose the command Configure Inbound
Error Prefix... .
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Figure 43: Configuring the inbound error prefix
●
Select the appropriate options in the dialog box:
Don't use an inbound error prefix (deactivate prefix)
Use the inbound error prefix "BCSYSEX" (activate the prefix)
The affected proxy must not be running when you do this. The change takes effect when
you save the proxy.
BeanConnect V2.1
227
Saving and activating the proxy configuration
Configuration of BeanConnect
6.9 Saving and activating the configuration of the BeanConnect
proxy
After adding a new proxy or changing the configuration of an existing proxy in the
Management Console, you must save and activate the configuration to bring the configuration into effect. To obtain information on outstanding activities you can use the todo topics
feature (see the section "Todo topics" on page 156).
I
The following description also applies if you are running the
BeanConnect proxy in a cluster.
The necessary steps depend on the changes you have made.
If data such as the LU name or control point name has been modified for the
openUTM-LU62 Gateway and the communication service then the configuration must be
saved and the components must be restarted. Only then do the changes take effect.
The configuration must be saved and the proxy container must be restarted to bring the
changes into effect if you have
●
changed the settings for communication with the resource adapter (see "Configuring
the BeanConnect resource adapter" on page 184).
●
created, modified or deleted an inbound user, an inbound message endpoint, an
outbound service or an outbound communication endpoint.
Select one of the following commands from the context menu of the proxy:
●
If the proxy is running: Save/Restart – Save & Restart Proxy
●
If the proxy is not running: Save/Restart – Save and then start the proxy with Start
Proxy.
The steps listed below are necessary and sufficient if you have added or deleted an EIS
partner or changed its configuration. Activation of the new configuration cannot be carried
out while the proxy is running. Therefore, proceed as follows after you have finished the
configuration activities:
1. Select Save/Restart – Save from the context menu of the proxy.
The newly defined configuration is saved and new configuration files are generated for
all EIS partners of the proxy.
2. If the proxy is running, stop it by selecting Stop Proxy from the context menu of the
proxy. All proxy components are stopped.
3. Select Update Configuration from the context menu of the proxy to activate the new
configuration.
228
BeanConnect V2.1
Saving and activating the proxy configuration
4. Start the proxy by selecting Start Proxy from the context menu of the proxy. The proxy
and proxy components are started with the changed configuration.
5. It may be necessary to enter the new configuration data for the EIS partner in the EIS
partner
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
BeanConnect V2.1
229
Configuring the MC-CmdHandler
Configuration of BeanConnect
6.10 Configuring the Management Console command handler
(MC-CmdHandler)
The Management Console Command Handler (MC-CmdHandler) is a stand-alone Java
application that enables the Management Console to administer remote proxies, proxy
components, resource adapters or the Log4j configuration.
An MC-CmdHandler is installed for each BeanConnect proxy. In addition, you can also
install the MC-CmdHandler separately on computers other than the proxy computer. This is
necessary in the following cases:
●
If it is not possible to access required files such as the deployment descriptor ra.xml
in the BeanConnect RAR archive or the resource adapter's Log4j configuration
because they are present on different computers and/or under different IDs.
●
If it is not possible to access components such as openUTM-LU62 or communication
services because they are present on different computers and/or under different IDs.
The MC-CmdHandler is a socket listener that waits at a listener port for orders given by the
Management Console. The MC-CmdHandler is able to perform basic file transfer tasks
such as listing directories, supplying information about files, fetching and updating files.
Beyond this, it is also possible to execute scripts on a remote system.
The following conditions must be met before the above-mentioned components can be
administered on remote hosts:
●
The MC-CmdHandler must be started on the host on which the proxy or the components to be administered are running (resource adapter, openUTM-LU62 and communication service).
●
The Management Console must be able to access the MC-CmdHandler.
6.10.1 Security and privileges
The MC-CmdHandler checks user authorizations. This prevents unauthorized individuals
from using the MC-CmdHandler to manipulate file systems on remote hosts. Requests are
accepted only if the (encrypted) password that accompanies the request matches the
password of the MC-CmdHandler.
The privileges of the MC-CmdHandler are the same as the privileges of the system user ID
under which the MC-CmdHandler was started. This is relevant when the MC-CmdHandler
accesses files or executes scripts. It is therefore necessary to start each MC-CmdHandler
under the same user ID as the component(s) to be administered.
230
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring the MC-CmdHandler
Notes on using the MC-CmdHandler
The following points must be noted if an MC-CmdHandler is to be used to administer a
proxy:
●
When the proxy is entered in the Management Console's administration data, the
password of the employed MC-CmdHandler must correspond to the administration
password of the proxy that is to be included.
●
If the administration password for a proxy changes then the password of the
MC-CmdHandler that is used to administer the relevant proxy also changes.
June 8, 2009 7:06 pm
Therefore, if several proxies are installed on a computer, a separate MC-CmdHandler
should be used for each proxy.
6.10.2 Administering the MC-CmdHandler
You will find scripts for starting, checking and shutting down the MC-CmdHandler
undershsc in the proxy container's home directory or under shsc in the MC-CmdHandler's
installation directory if the MC-CmdHandler is installed separately.
6.10.2.1
Starting the MC-CmdHandler
Starting the MC-CmdHandler on UNIX systems
You start the MC-CmdHandler using the following script in the proxy container's home
directory or in the MC-CmdHandlers' installation directory
shsc/startmccmdhandler.sh
I
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
●
If you do not want the MC-CmdHandler to be shut down
automatically on the next logoff, you must either start it as a
service (see Section 6.10.2.3, "Configuring an
MC-CmdHandler as a service") or start it using the following
command:
nohup shsc/startmccmdhandler.sh &
BeanConnect V2.1
231
Configuring the MC-CmdHandler
Configuration of BeanConnect
Starting the MC-CmdHandler on Windows systems
You start the MC-CmdHandler using the following script in the proxy container's home
directory or in the MC-CmdHandlers' installation directory:
●
shsc\startmccmdhandler.cmd
If the MC-CmdHandler is located in the proxy container's home directory, you can also start
it via the program group. To do this, choose
Start - Programs - BeanConnect V2.1A00 - Proxy <container> - MC-CmdHandler
- MC-CmdHandler Startup
6.10.2.2
Shutting down the MC-CmdHandler
Shutting down the MC-CmdHandler in UNIX systems
You shut down the MC-CmdHandler with the following script in the proxy container's home
directory or in the MC-CmdHandler's installation directory:
●
shsc/shutmccmdhandler.sh
Shutting down the MC-CmdHandler in Windows systems
You shut down the MC-CmdHandler with the following script in the proxy container's home
directory or in the MC-CmdHandler's installation directory:
●
shsc\shutmccmdhandler.cmd
If the MC-CmdHandler is located in the proxy container's home directory, you can also shut
it down it via the program group. To do this, choose
Start - Programs - BeanConnect V2.1A00 - Proxy <container> - MC-CmdHandler
- MC-CmdHandler Shutdown
232
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
6.10.2.3
Configuring the MC-CmdHandler
Configuring an MC-CmdHandler as a service
Configuring an MC-CmdHandler as a service on UNIX systems
If the MC-CmdHandler is to be started as a service then it must be configured. To do this,
enter a line in the file /etc/init.d/bcmccmdhandler.dat for every service that is to be
started. This line contains the user ID under which the service is to be started as well as
the directory under which the MC-CmdHandler was installed, e.g.:
●
proxyuser
/home2/proxyuser/BCCONT
To start/stop the MC-CmdHandler as a service, call the following script:
●
/etc/init.d/bcmccmdhandler.sh start | stop
Alternatively, you may also call the script with the options restart or reload. restart
and reload are identical and each contain stop and start.
To remove a service from the UNIX system again, delete the corresponding line in the
above-mentioned configuration file.
To enter and delete the service and to call the script /etc/init.d/bcmccmdhandler.sh,
you require system administrator permissions. For further information on deleting a service,
see Section 3.9, "Uninstalling the BeanConnect tools".
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Configuring an MC-CmdHandler as a service on Windows systems
If the MC-CmdHandler is installed without a BeanConnect container, then the
MC-CmdHandler is entered as a service at installation time under the name
BeanConnect MC-CmdHandler <port-number> with autostart type Manual.
If the MC-CmdHandler is installed together with the BeanConnect container, then you must
subsequently explicitly enter the MC-CmdHandler as a service. You do this using the script
shsc/MCCmdHandler_InstallSrv.cmd in the container's home directory. Call the script
with administration authorization:
●
<Cont_Home>/shsc/MCCmdHandler_InstallSrv.cmd
This script enters the service with autostart type Manual.
You can use the script shsc/MCCmdHandler_UnInstSrv.cmd to remove the service
again.
BeanConnect V2.1
233
Configuring the Management Console as a JMX client
Configuration of BeanConnect
6.11 Configuring the Management Console as a JMX client
The Management Console contains a JMX client This allows the Management Console to
read current statistical and administrative data for the running resource adapter and to
modify certain attribute values, see Section 8.7, "Monitoring the resource adapter with the
Management Console".
The data is made available using MBeans. The JMX client is therefore also referred to as
the MBean client.
I
As JMX client, the Management Console can access all the
MBeans of the relevant application server instance. However,
this section describes only the MBeans which affect the
resource adapter.
6.11.1 Defined resource adapter MBeans
The resource adapter provides the following types of MBeans:
●
ResourceAdapter MBean
This MBean indicates the resource adapter configuration settings as defined in the file
ra.xml. There is one MBean of this type for each resource adapter.
●
ManagedConnectionFactory MBean
These MBeans indicate the configuration properties of the individual connection
factories (deployment data) and provide information about connection usage (statistical
data). Each connection factory has a corresponding MBean.
●
Inbound MBean
This MBean indicates the statistical data for all the inbound connections that cannot be
assigned to a message endpoint. There is only one MBean of this type.
●
MessageEndpoint MBean
These MBeans indicate the configuration properties of the individual message
endpoints (configuration properties in the file ejb-ra.xml) and provide information
about connection usage (statistical data). Each message endpoint has a corresponding
MBean.
●
Logging MBean
This MBean indicates the Log4j configuration settings. All the Log4j Loggers are
displayed together with their log levels. There is only one MBean of this type.
234
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring the Management Console as a JMX client
The following types of data are provided for each MBean:
●
Attributes
These are values, e.g. configuration values or statistical counters. Most of the attributes
of the MBeans are read-only. Some of them can also be modified via the MBean
interface.
●
Operations
These are operations (methods) that can be executed using MBeans, for example
resetting counters.
●
Notifications
Notifications sent to the MBean client when certain events occur (e.g. when a transaction is rolled back). Before it is possible to send notifications, the MBean client must
have explicitly subscribed to them.
For further details on the data supplied by the MBeans and the options available via the
administration functions, see Section 8.7, "Monitoring the resource adapter with the
Management Console".
6.11.2 Setting up the JMX client in the Management Console
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
The JMX client requires additional Java libraries to communicate with OC4J or the Oracle
Application Server. If the Management Console runs on a different computer from the application server then you must download these libraries from Oracle's official download page
and install them.
To declare these libraries, it is necessary to extend the Management Console's classpath.
The scripts mc.cmd (Windows systems) and mc.sh (Solaris, Linux systems) for starting the
Management Console already contain the associated statements under Enable Oracle
JMX client. To use these statements, you must set the variable ORACLEJMX to yes in the
corresponding script; yes must be written in lowercase. Otherwise, the statements under
Enable Oracle JMX client will not execute.
In Windows systems, the script mc.cmd is located under <MC_home>/bin
where <MC_home> is the Management Console's installation directory.
In Solaris/Linux systems, the script mc.sh is located in the installed BeanConnect's
Console/bin directory. You must adapt the script mc.sh for the JMX client. However, the
Management Console is started with the script startconsole.sh which is located in the
Management Console's installation directory.
BeanConnect V2.1
235
Configuring the Management Console as a JMX client
6.11.2.1
Configuration of BeanConnect
Setting up a JMX client
A JMX client is usually assigned to a resource adapter. However, you can also set up a free
"stand-alone" JMX client, see section "Setting up free JMX clients".
Setting up a JMX client for resource adapters
To set up a JMX client for a resource adapter, choose the Define MBean Client command
in the resource adapter's context menu and define the properties of the MBean client in the
MBean Client Properties dialog box
Figure 44: Setting up a JMX client for resource adapters
Name
Name of the resource adapter, cannot be changed.
236
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k06
Configuration of BeanConnect
Configuring the Management Console as a JMX client
Server Type
Select the type of application server.
Server URL
Specifies the URL that is to be used to establish the connection to the JMX server. The
format of the URL depends on the type of application server. The Management Console
proposes a default URL which you may need to modify. The default URL has the following
format:
●
service:jmx:rmi:///opmn:/<server-host>:6003/home
(Oracle AS)
●
service:jmx:rmi://<server-host>:23791
(OC4J)
<server-host> is the name of the JMX server. This is followed by the port number of the
relevant server. Here, the Management Console enters the name of the computer on which
the resource adapter is running and proposes a default port number for the JMX server. You
may need to adapt the port number and <home>.
Login
User ID required for login at the application server. The user ID usually possesses administration permissions.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Password
Password for the specified user ID.
The newly set up MBean client is represented by a separate node below the resource
adapter.
Setting up free JMX clients
A free JMX client is a client that is not assigned to any resource adapter. To set up this type
of client, open the File menu and choose the command Add MBean Client. Enter the
properties in the dialog box MBean Client Properties. You proceed in the same way as for
a client with a fixed resource adapter except that you must assign the name of the JMX
client and that the name of the JMX client computer is not predefined. The MBean clients
defined in this way are listed at the topmost level under the MBean Clients node. This node
only exists if you have set up at least one free MBean client.
BeanConnect V2.1
237
Configuring the Management Console as a JMX client
6.11.2.2
Configuration of BeanConnect
Establishing and clearing a connection to the JMX server
You must explicitly establish and clear the connection between the Management Console
and the JMX server.
Establishing a connection to the JMX server
In the MBean context menu, choose Connect to MBean Server. If it has been possible to
establish the connection, the icon for the MBean node changes and all the available MBean
domains are displayed below the MBean node. If the connection is not established, an error
message is output. This may provide information about the cause of the error.
Clearing a connection to the JMX server
To clear a connection to the JMX server, choose the command Disconnect From MBean
Server in the MBean client's context menu. When the connection is cleared, the contents
of the MBean domain nodes are removed from the navigation tree.
6.11.2.3
Removing a JMX client
To remove a JMX client, choose the command Remove MBean Client from the MBean
client's context menu and confirm the query. The Management Console removes the node
from the navigation tree, closes any windows that are open and deletes the configuration
data from its administration files
238
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k07
June 8, 2009 7:06 pm
7 Adapting the configuration in the EIS partner
In order to enable communication between the application server and an EIS partner, it is
not sufficient to configure the application server, the resource adapter and the proxy. Some
additional configuration activities are necessary in the EIS itself and on the platform that
hosts the EIS.
This chapter contains information on
●
Defining connections between BeanConnect and openUTM
●
Defining connections between BeanConnect and other EIS partners
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
For detailed information on configuring openUTM applications, please refer to the
openUTM documentation.
BeanConnect V2.1
239
Adapting the configuration in openUTM partners
Adapting the configuration in EIS partners
7.1 Adapting the configuration in EIS partners of type openUTM
An EIS partner of type openUTM is usually an openUTM application which communicates
with the application server via outbound or inbound communications. However, it is also
possible for an application from the openUTM environment, for example a UPIC application,
to perform inbound access to the application server.
7.1.1 Defining connections between BeanConnect and openUTM
openUTM partners can be connected to BeanConnect via the
●
OSI-TP protocol
●
UPIC protocol
●
Socket or RFC1006 protocol
The following sections indicate the parameters that have to be configured in the EIS partner.
In the case of connections to an openUTM partner running on BS2000/OSD, you may also
need to create BMAP entries.
7.1.1.1
Defining an OSI-TP connection between BeanConnect and openUTM
An OSI-TP connection can be used for both outbound communication and inbound communication. An OSI-TP connection enables both transactional and non-transactional communication.
An OSI-TP connection between BeanConnect and openUTM requires an OSI-LPAP and an
OSI-CON statement within the EIS partner's openUTM generation (KDCDEF).
On the proxy side the generation is processed as described in section "Configuring the EIS
partners" on page 193. On the EIS partner side the BeanConnect Management Console
generates these statements in a text file in the directory <MC_Home>/genfiles.
In the case of a single proxy, the name of the generated input file is:
ProxyID.<p-id>.EisPartnerID.<e-id>.UTM.txt
In the case of a proxy cluster, the name of the generated input file is:
ClusterID.<c-id>.EisPartnerID.<e-id>.UTM.txt
<p-id>, <e-id> and <c-id> designate the IDs for the proxy, EIS partner and proxy cluster
assigned by the Management Console.
240
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k07
Adapting the configuration in EIS partners
Adapting the configuration in openUTM partners
BeanConnect does not transfer this configuration file to the EIS platform. The generated
input file has to be transferred to the EIS partner host using common file transfer mechanisms. After that, the openUTM administrator can use the file to carry out the configuration
activities.
7.1.1.2
Defining a UPIC connection for outbound communication between the openUTM
partner and BeanConnect
From the openUTM partner point of view, the BeanConnect resource adapter is seen as a
UPIC client.
A UPIC connection from BeanConnect to an openUTM partner requires a TPOOL statement
within the KDCDEF generation of openUTM partner application. The Management Console
does not generate this statement.
The configuration enables non-transactional UPIC outbound communication.
The openUTM connection is configured as follows:
BCAMAPPL UTMSERV
,T-PROT=RFC1006
[,LISTENER-PORT = 11111] // only required for UNIX/Windows systems
[,TSEL-FORMAT=T|A|E]
// only required for UNIX/Windows systems
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
TPOOL NUMBER=99
,PTYPE=UPIC-R
,LTERM=UPIC#R
,BCAMAPPL=UTMSERV
,PRONAM=*ANY
,Connect-Mode=MULTI
Please note the following:
●
TSEL-FORMAT must match the configuration property connectionURL, parameter
TSEL, attribute rt (see "connectionURL" on page 116).
●
UTMSERV and the port number must match the values which are specified in the configuration property connectionURL parameters remote and port or in the program.
Example 12 Example of an URL
The openUTM partner application configured above can be addressed as follows with the
configuration property connectionURL:
<config-property name="connectionURL"
value="upic://host:11111/UTMSERV?rt=t"/>
(for UNIX/Windows systems)
BeanConnect V2.1
241
Adapting the configuration in openUTM partners
7.1.1.3
Adapting the configuration in EIS partners
Defining a socket connection between the openUTM partner and BeanConnect
A socket connection or RFC1006 connection from an openUTM partner to BeanConnect
requires a pair of PTERM/LTERM statements within the openUTM partner application's
KDCDEF generation either with PTYPE=SOCKET for the openUTM socket protocol or with
PTYPE=APPLI for the RFC1006 protocol. The Management Console does not generate
these statements.
The configuration enables non-transactional asynchronous inbound communication.
7.1.1.4
Defining a BCMAP entry (only for BS2000/OSD partners)
An additional configuration step has to be carried out on the BS2000/OSD partner system
in BCAM if a communication port number other than port 102 is used.
To assign another port than the default port 102 to the OSI-CON, PTERM or TPOOL statements in the openUTM configuration, you have to define a BCMAP entry.
When configuring a BS2000/OSD EIS partner with the Management Console the following
text file with the according BCMAP entry is generated in the directory
<MC_Home>/genfiles .
In the case of a single proxy, the name of the generated input file is:
ProxyID.<p-id>.EisPartnerID.<e-id>.BCMAP.txt
In the case of a proxy cluster, the name of the generated input file is:
ClusterID.<c-id>.EisPartnerID.<e-id>.BCMAP.txt
<p-id>, <e-id> and <c-id> designate the IDs for the proxy, EIS partner and proxy cluster
assigned by the Management Console.
BeanConnect does not transfer this configuration file to the EIS platform. The generated
input file has to be transferred to the EIS partner host using common file transfer mechanisms and can be used by the BCAM administrator to carry out the configuration activities.
For detailed information on configuring BCMAP entries, please refer to the BCAM
documentation.
242
BeanConnect V2.1
Adapting the configuration in openUTM partners
7.1.2 Defining connections between BeanConnect and other EIS partners
Each UPIC application and each application using transport-level protocols like RFC1006
or the openUTM socket protocol can be used as an EIS partner for non-transactional
inbound communication. A UPIC application may only use dialog communication.
For detailed information on communication between UPIC applications or applications
using transport-level protocols like RFC1006 or openUTM socket protocol and
BeanConnect please refer to the openUTM documentation.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k07
Adapting the configuration in EIS partners
BeanConnect V2.1
243
Adapting the configuration in CICS partners
Adapting the configuration in EIS partners
7.2 Adapting the configuration in EIS partners of type CICS
An EIS partner of type CICS is a CICS application which runs on an IBM mainframe.
7.2.1 Configuration in the CICS
The following configuration activities have to be carried out in the CICS itself:
●
Definition of a connection, used to specify the connection parameters. This definition
contains the name of the logical unit (NETNAME parameter) of the CICS partner application.
●
Definition of a session, used to specify the session parameters. This definition contains
the name of the connection (CONNECTION parameter) and the name of the session
mode (MODE parameter). The properties of a session are then defined via the mode.
The BeanConnect Management Console generates a text file that contains the definitions
of CONNECTION and SESSION (see Section 6.6.2, "Configuring EIS partners of type CICS" ).
In the case of a single proxy, the name of the generated input file is:
ProxyID.<p-id>.EisPartnerID.<e-id>.CICS.txt
In the case of a proxy in a cluster, the name of the generated input file is:
ClusterID.<c-id>.ProxyID.<p-id>.EisPartnerID.<e-id>.CICS.txt
<p-id>, <e-id> and <c-id> designate the IDs for the proxy, EIS partner and proxy cluster
assigned by the Management Console.
BeanConnect does not transfer the file to the EIS platform. This file has to be transferred to
the EIS partner host using common file transfer mechanisms and can be used by the CICS
administrator to carry out the configuration activities.
7.2.2 Configuration of VTAM on an IBM mainframe
The VTAM (Virtual Telecommunications Access Method) component has to be configured
for CICS partners running on the IBM mainframe (z/OS system). VTAM is an IBM product
that runs on the mainframe and enables access to a CICS region on that mainframe.
Requests from the proxy are passed to VTAM and then to CICS. Therefore, some VTAM
definitions are needed.
VTAM definitions are coded using macros. The Management Console generates an input
file for the VTAM configuration during the configuration run (see section Section 6.6.2,
"Configuring EIS partners of type CICS" ). This input file contains definitions for the Physical
Unit (PU) in VTAM.
244
BeanConnect V2.1
Adapting the configuration in CICS partners
In the case of a single proxy, the name of the generated input file is:
ProxyID.<p-id>.EisPartnerID.<e-id>.VTAM.txt
In the case of a proxy in a cluster, the name of the generated input file is:
ClusterID.<c-id>.ProxyID.<p-id>.EisPartnerID.<e-id>.VTAM.txt
<p-id>, <e-id> and <c-id> designate the IDs for the proxy, EIS partner and proxy cluster
assigned by the Management Console.
BeanConnect does not transfer the VTAM configuration file to the EIS platform. The
generated input file has to be transferred to the EIS partner host using common file transfer
mechanisms. After that, the VTAM administrator can use the file to carry out the configuration activities. Note that the VTAM administrator has to adapt some VTAM definitions to
the needs of the partner application. BeanConnect cannot guarantee the uniqueness of the
definitions when generating the file because it has no access to the complete VTAM definitions. Therefore, the configuration file contains some question marks which must be
replaced with the proper values.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k07
Adapting the configuration in EIS partners
BeanConnect V2.1
245
Adapting the configuration in CICS partners
246
Adapting the configuration in EIS partners
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k08
June 8, 2009 7:06 pm
8 Administering BeanConnect
This chapter describes the administration tasks involved in operating BeanConnect.
You can carry out all the necessary operations using the BeanConnect Management
Console. These operations include:
●
Starting and stopping the proxy container and the proxy components
●
Checking the availability of the proxy
To start and stop the proxy container there are also scripts available. On Windows systems,
these are available in the proxy container program group.
Administration of proxies running on a remote system is only possible using the
Management Console.
●
Administering a BeanConnect proxy via the Management Console
●
Administering a BeanConnect proxy container on command level
●
Starting an MC-CmdHandler as a service on Windows systems
●
Checking the availability of a proxy
●
Administering the openUTM-LU62 Gateway
●
Administering the communication service
●
Monitoring the resource adapter with the Management Console
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
This chapter deals with the following topics:
BeanConnect V2.1
247
Administering via the Management Console
Administering BeanConnect
8.1 Administering a BeanConnect proxy via the Management
Console
The Management Console is able to administer a number of installed proxies. These
proxies can be installed either on the same computer as the Management Console, in which
case they are referred to as local proxies, or they can be installed on a different computer,
in which case they are referred to as remote proxies.
Proxies can be administered via the Management Console if one of the following conditions
is met:
●
The proxy is local from the point of view of the Management Console. and runs under
the same user ID as the Management Console.
●
The proxy is a (possibly) remote proxy whose associated MC-CmdHandler is available
and can be accessed via the Management Console.
The Management Console offers the necessary administration functions in the context
menu of a proxy node.
Figure 45: Proxy context menu
248
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k08
Administering BeanConnect
Administering via the Management Console
8.1.1 Starting a proxy
The proxy container or proxy component must be configured before you can start it
successfully.
You start a proxy by selecting the menu item Start Proxy in the context menu of the relevant
proxy node in the navigation tree.
If the proxy is only configured for partners of type openUTM then it is started immediately.
If the proxy is (also) configured for partners of type CICS, a selection dialog box then
appears which allows you to select those components of the proxy which you want to be
started:
●
Proxy container
●
openUTM-LU62 Gateway
●
Communication Service
I
Before you start openUTM-LU62 and the communication
service, the associated MC-CmdHandler must already be
started.
If you are starting the openUTM-LU62 Gateway (CICS) you can also select the option Cold
Start. All restart information is lost during a cold start.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Before starting a proxy, the Management Console first checks whether the proxy container
or the proxy component is already available.
The proxy container or the proxy component must be configured before it can be started
successfully.
The openUTM-LU62 Gateway and the Communication Service cannot be started until at
least one EIS partner of type CICS has been defined for the proxy. For more information,
refer to the section "Configuring the BeanConnect proxy" on page 168.
I
For CICS partners:
To administer the Communication Service the administration
user must be member of the predefined SNA administrator
group sna. The user group sna is present after the installation
of the communication service. The administrator is the user
under whose user ID, the MC-CmdHandler was started.
The Management Console issues appropriate messages in an action dialog box in which
you can monitor the actions and results. You can
BeanConnect V2.1
249
Administering via the Management Console
Administering BeanConnect
●
identify what actions have already been carried out and control the results of the
completed actions,
●
display detailed information on the results if an error occurs,
●
if necessary, cancel the entire operation. In this case, only the execution of the subactions that have not yet been performed is canceled. Subactions that have already been
executed are not undone.
If an availability check has been performed, the status icons in front of the relevant node in
the navigation tree are colored depending on result (green if the proxy container or, in the
case of CICS partners, the proxy component is running or red if not running). In the case of
openUTM proxies, the icon consists of one part and describes the status of the proxy
container. In the case of CICS proxies, the icon consists of three parts.
The individual icons stand for the following components:
Left
Proxy container
Middle
openUTM-LU62 Gateway
Right
Communication Service
An availability check is performed automatically at predefined time intervals or can be
started manually (see "Checking the availability of a proxy" on page 263).
I
To permit communication between the application server and
the EIS partner, all the proxy components must be active
(green).
In the case of CICS partners, this is not always sufficient, i.e. the
communication may not function properly even though the icons
are green. In such cases, you must also check the established
connections and opened sessions, see Section 13.9.2,
"Diagnosis information for the openUTM-LU62 Gateway"
250
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k08
Administering BeanConnect
Administering via the Management Console
Starting the proxy container as a Windows service
On Windows systems, you can also start a proxy container as a Windows service using the
Management Console:
1. Select the proxy in the navigation area of the Management Console.
2. From the context menu, select the entry Edit Properties, open the General tab and
select the option Start as Service.
3. Save the configuration with Save/Restart - Save. The next time the proxy is started, it
is started as a Windows service. If the proxy is already running then this change does
not take effect with the proposed restart. Instead, it only becomes effective when the
proxy is shut down and then restarted
Further information can be found in section "Starting as a Windows service" on page 255.
8.1.2 Restarting a proxy
Restarting the proxy involves a combination of stopping (if necessary) and starting the
proxy or individual proxy components. This is necessary after certain configuration activities
(see "Saving and activating the configuration of the BeanConnect proxy" on page 228).
Restart a proxy by selecting the menu item Save/Restart – Restart Proxy in the context
menu of the relevant proxy node in the navigation tree.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
In the case of a proxy that is configured for CICS partners, a dialog box is displayed where
you can select the proxy components to be restarted. Again, the action dialog box is
available for monitoring the actions and results.
The proxy container is reloaded, i.e. the individual processes are stopped and restarted in
sequence. The proxy container as a whole remains available.
In the case of a proxy that is configured for CICS partners, the openUTM-LU62 Gateway
and communication service are first stopped and then restarted.
8.1.3 Stopping a proxy
Stop a proxy by selecting the menu item Stop Proxy in the context menu of the relevant
proxy node in the navigation tree.
In the case of a proxy that is configured for CICS partners, here again, in the same way as
when starting the proxy, you can select single proxy components. The Management
Console displays an action dialog box dialog box in which you can monitor the actions and
results.
BeanConnect V2.1
251
Administering via the Management Console
Administering BeanConnect
8.1.4 Special characteristics in cluster operation
The administration of a proxy cluster resembles that of an individual proxy. The
Management Console provides the necessary administration functions via the proxy
cluster's context menu. You can use the Show Cluster Proxies command to display all the
proxies in the cluster.
Figure 46: Administering a BeanConnect proxy cluster
Start, stop and save operations always apply to all the proxies in the proxy cluster.
If you want to start or stop an individual proxy, select it in the Cluster Proxies panel and
choose the corresponding command from the context menu.
You should use MBeans if you want to switch a running resource adapter to a different
proxy, see section "Switching a resource adapter in the cluster to another proxy".
The administration of a proxy cluster differs from that of an individual proxy in the following
ways:
●
252
If the proxy cluster is made up of a number of proxies, one proxy is always the master
proxy. This is indicated accordingly in the Master column of the Cluster Proxies list.
This proxy is the (first) point of contact for the Management Console when fetching the
configuration data for the cluster. If there are any changes, the Management Console
ensures that these are made in all the proxies.
BeanConnect V2.1
●
Administering via the Management Console
If it is not possible to administer one of the proxies for a period then it is possible that
this proxies data will not be consistent. In such cases, you can then use the
Synchronize Proxy Cluster command in the proxy cluster's context menu to
synchronize such proxies. When you do this, the other proxies take over the data from
the master proxy.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k08
Administering BeanConnect
BeanConnect V2.1
253
Administering on command level
Administering BeanConnect
8.2 Administering a BeanConnect proxy container on command
level
BeanConnect provides some scripts and programs for administering the proxy container
which you can use on command level or via the proxy container program group on Windows
systems.
8.2.1 Starting a proxy container
You can start a local proxy container using a script.
On Windows systems you can also use the proxy container program group or start the proxy
container as a Windows service.
8.2.1.1
Starting via a script
You can use the following scripts to start a local proxy container.
The procedure startcontainer in the subdirectory shsc of the proxy container home
directory is available for starting a local proxy container.
Proceed as follows:
1. Open a shell or a DOS command prompt window.
2. Change to the proxy container home directory.
3. Call the script as follows:
shsc/startcontainer.sh (under Solaris/Linux systems) or
shsc\startcontainer.cmd (under Windows systems)
8.2.1.2
Starting using the proxy container program group under Windows
You can also start a local proxy container on a Windows system using the proxy container
program group:
●
254
From the program group BeanConnect V2.1A00 - Proxy <proxy_cont_name>, select
the command Proxy Container Startup - <proxy_cont_name>.
BeanConnect V2.1
8.2.1.3
Administering on command level
Starting as a Windows service
If BeanConnect is installed under Windows, the proxy container is set up as a service with
the name BeanConnectV21A00 <proxy_cont_name>.
By default, the service has the startup type manual. If required, you can set the startup type
to automatic to ensure that the proxy container is always available.
To start a local proxy container as a service:
1. From the program group Start - Settings - Control Panel, select the entry Administrative Tools - Services.
2. Select the Start command from the context menu of the service
BeanConnect <version> <proxy_cont_name>.
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k08
Administering BeanConnect
You can also start a proxy container as a service using the Management Console (see
"Starting a proxy" on page 249).
When the proxy container executes as a service, its first output to stdout is written to the file
utmp.out and its first output to stderr is written to the file utmp.err.
If the log files are switched then the files are named utmp.err.<timestamp> and
utmp.out.<timestamp>. The log files for the last application run are automatically saved
in the directory out-err.
If you start the proxy container as a service, no DOS window is opened for output to stdout
or for error messages. You can, however, open windows specially for this purpose. Output
is written during operation and is updated automatically (see Chapter 13, "Logging,
diagnostics and troubleshooting" on page 383).
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
8.2.1.4
Starting after abnormal termination of a proxy container run
If the proxy container cannot be started, for instance because the previous proxy container
run was terminated abnormally, proceed as follows:
●
On Solaris/Linux systems, switch to the proxy container home directory and call the
script shsc/remove.sh.
●
On Windows systems, select Forced Clear from the program group
BeanConnect V2.1A00 - Proxy <proxy_cont_name>.
or
switch to the proxy container home directory and call the script
shsc/remove.cmd.
●
If you are operating the Management Console in expert mode (in Solaris, Linux or
Windows systems), choose Forced Clear from the proxy's context menu.
BeanConnect V2.1
255
Administering on command level
Administering BeanConnect
8.2.2 Restarting a proxy container
It may be necessary to restart the proxy container after certain configuration activities (see
"Saving and activating the configuration of the BeanConnect proxy" on page 228).
8.2.2.1
Restarting using a script
You can use the following scripts to restart a local proxy container.
The procedure change in the subdirectory shsc of the proxy container home directory is
available for restarting a local proxy container.
Proceed as follows:
1. Open a shell or a DOS command prompt window.
2. Switch to the proxy container home directory.
3. Call the script as follows:
shsc/change.sh (under Solaris/Linux) or
shsc\change.cmd (under Windows)
8.2.2.2
Restarting using the proxy container program group under Windows
You can restart a local proxy container on a Windows system using the proxy container
program group:
●
256
From the program group
BeanConnect V2.1A00 - Proxy <proxy_cont_name>, select the command Proxy
Container Restart.
BeanConnect V2.1
Administering on command level
8.2.3 Stopping a proxy container
You can stop a local proxy container using a script or using the proxy container program
group on a Windows system.
8.2.3.1
Stopping using a local script
You can use the following scripts for stopping the proxy container.
The procedure shutcontainer in the subdirectory shsc of the proxy container home
directory is available for stopping a local proxy container.
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k08
Administering BeanConnect
Proceed as follows:
1. Open a shell or a DOS command prompt window.
2. Switch to the proxy container home directory
3. Call the script as follows:
shsc/shutcontainer.sh (under Solaris/Linux) or
shsc\shutcontainer.cmd (under Windows)
8.2.3.2
Stopping using the proxy container program group under Windows
You can also stop a local proxy container on a Windows system using the proxy container
program group:
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
●
8.2.3.3
From the program group
BeanConnect V2.1A00 - Proxy <proxy_cont_name>, select the command Proxy
Container Shutdown.
Stopping as a Windows service
If a proxy container was started as a service on a Windows system, you can stop it in the
Services dialog box as follows.
1. From the program group Start - Settings - Control Panel, select the entry Administrative Tools - Services.
2. Select Stop from the context menu of the service
BeanConnect V2.1A00 <proxy_cont_name>.
I
BeanConnect V2.1
If the proxy container was started as service with the start type
automatic, it can only be stopped in this way.
257
Starting an MC-CmdHandler as a service (Windows)
Administering BeanConnect
8.3 Starting an MC-CmdHandler as a service on Windows
systems
If the MC-CmdHandler is to be started as a service on Windows systems then it must
always first be configured as a service, see "Configuring an MC-CmdHandler as a service
on Windows systems" on page 233. After this, the service has the autostart type Manual.
Use the Control Panel to set the autostart type to Automatic. This causes the service to
be started automatically when the Windows system is started.
258
BeanConnect V2.1
Administering the openUTM-LU62 Gateway
8.4 Administering the openUTM-LU62 Gateway
The openUTM-LU62 Gateway can be administered by the Management Console (see
"Administering a BeanConnect proxy via the Management Console" on page 248) or
directly using scripts. On Solaris and Linux systems you can call all administration
commands from a shell as described below.
I
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k08
Administering BeanConnect
After installation of the openUTM-LU62 Gateway on Solaris or
Linux systems, all users are authorized to administer it. If for
security reasons you want to restrict the administration rights to
certain users, proceed as follows:
In the openUTM-LU62 Gateway home directory (default:
/opt/lib/utmlu62), you will find the file u62_users. In this
file you can configure a list of users who are to have administration permission. User names must be separated by blank,
tab, comma or new line.
If the list defined in the u62_users file is not empty, administration access will be denied for all users not contained in the list
(except root, which always has administration permission).
Under Windows it is recommended that you open a DOS command prompt window with
Start - Programs - openUTM-LU62 - command prompt
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
From that DOS command prompt window, you can call the commands described below
without the prefix <LU62_home>/.
8.4.1 Starting the openUTM-LU62 Gateway
The following command starts openUTM-LU62 as a background process, where
<LU62_home> refers to the installation directory of the openUTM-LU62 Gateway:
<LU62_home>/u62_start
BeanConnect V2.1
259
Administering the openUTM-LU62 Gateway
Administering BeanConnect
8.4.2 Stopping the openUTM-LU62 Gateway
The following command stops the openUTM-LU62 Gateway, where <LU62_home> refers to
the installation directory of the openUTM-LU62 Gateway:
<LU62_home>/u62_adm -e
Under Windows you can select the following entry from the program group instead:
Start - Programs - openUTM-LU62 - Stop openUTM-LU62
8.4.3 Displaying status information on the openUTM-LU62
The following command displays information on the current status of the openUTM-LU62
Gateway:
<LU62_home>/u62_sta
Under Windows you can select the following entry from the program group instead:
Start - Programs - openUTM-LU62 - status information
260
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k08
Administering BeanConnect
Administering the communication service
8.5 Administering the communication service
This section describes how to start the SNA daemon and how you start the communication
service (SNAP-IX in Solaris systems or IBM Communications Server in Linux and Windows
systems) in a command line.
For further information on administering SNAP-IX or the IBM Communications Server
please refer to the manufacturer's documentation.
8.5.1 Starting and stopping the SNA daemon (Linux and Solaris systems)
The SNA daemon must be running to administer the Communication Service. If not, an
error message is output.
Starting the SNA daemon
●
Switch to the directory /opt/sna/bin (Solaris) systems or /opt/ibm/sna/bin
(Linux) systems in the system on which the communication service was installed.
●
Enter the command ./sna start.
Stopping the SNA daemon
●
Switch to the directory /opt/sna/bin (Solaris systems) or /opt/ibm/sna/bin (Linux
systems) in the system on which the communication service was installed.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
●
Enter the command./sna stop.
8.5.2 Starting and stopping a communication service in a command line
(Linux and Solaris systems)
In Linux and Solaris systems, the BeanConnect Management Console generates the
scripts cs-start-all.sh and cs-stop.sh for a BeanConnect proxy every time the
communication service's configuration changes. These scripts are generated on saving
and make it possible to start or stop the proxy component in a command line.
If all the proxy components are located on the same host then the scripts are located in the
directory <Proxy_Home>/shsc, where <Proxy_Home> is the proxy container's home
directory.
In contrast, if the openUTM-LU62 Gateway and communication service are running on
separate hosts then the script is made available in the MC-CmdHandler which the
Management Console uses for the administration of these proxy components. In this case,
the script is located in the directory <MC-CmdHandler_Home>/shsc, where
<MC-CmdHandler_Home> is the home directory of the MC-CmdHandler.
BeanConnect V2.1
261
Administering the communication service
Administering BeanConnect
Starting the communication service
Proceed as follows to start the communication service in a command line:
●
Open a shell on the host on which the communication service is installed.
●
Go to the proxy container's home directory (installation on proxy host) or to the
MC-CmdHandler's home directory (installation on separate host).
●
Call the script:
shsc/cs-start-all.sh
Stopping the communication service
Proceed as follows to stop the communication service in a command line:
●
Open a shell on the host on which the communication service is installed.
●
Go to the proxy container's home directory (installation on proxy host) or to the
MC-CmdHandler's home directory (installation on separate host).
●
Call the script:
shsc/cs-stop.sh
262
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k08
Administering BeanConnect
Checking availability
8.6 Checking the availability of BeanConnect proxies
The availability of BeanConnect proxies refers to the availability of the proxy containers
(including the components required for CICS) and their communication partners (EIS
partners, resource adapters, MC-CmdHandlers). The availability check can take the form
of a full check or an individual component or partner-specific check.
The following options are available:
●
Checking the availability of a proxy
●
Checking the availability of a BeanConnect resource adapter
●
Checking the availability of an openUTM-LU62 Gateway and a communication service
●
Checking the availability of an MC-CmdHandler
●
Checking the availability of an EIS partner
I
You can also check the availability of a proxy cluster. For details,
see Section , "Special characteristics of proxy clusters".
8.6.1 Checking the availability of a proxy
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
You can check the availability of a proxy (and its communication partners) in the
Management Console by selecting Check Availability from the context menu of the
relevant proxy node in the navigation tree.
You can also force an automatic availability check to be carried out at predefined time
intervals by setting the parameter Automatic Availability Check in the proxy's property
sheet.
The Management Console checks the availability of:
●
Proxy containers
●
All the resource adapters assigned to the proxy
●
All the MC-CmdHandlers
●
The openUTM-LU62 Gateway and communication service if the proxy is configured for
CICS partners
●
All EIS partners
The proxy container must be running to check the availability of the resource adapter and
the EIS partners. In the case of CICS partners, the openUTM-LU62 Gateway and the
communication service must also be running.
BeanConnect V2.1
263
Checking availability
Administering BeanConnect
The Management Console displays an action dialog box in which you can monitor the
actions and results.
Figure 47: Checking the availability of a BeanConnect proxy
If one of the components is unavailable, select the entry and click Result Details to output
detailed information on the results of the check. This information can be useful for
diagnosis.
When configuring a proxy, you can define an interval for regular availability checks.
264
BeanConnect V2.1
Checking availability
Special characteristics of proxy clusters
●
To check the availability of all the components in a cluster, choose the Check Availability command from the proxy cluster's context menu.
●
To check the availability of an individual proxy in the cluster, select the proxy in the
Cluster Proxies panel and choose the Check Availability command in the context
menu.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k08
Administering BeanConnect
BeanConnect V2.1
265
Checking availability
Administering BeanConnect
8.6.2 Checking the availability of a BeanConnect resource adapter
To check the availability of an individual resource adapter in the Management Console,
open the resource adapter's context menu in the navigation tree and choose the Check
Availability command. The associated proxy container must be running.
Figure 48: Checking the availability of a resource adapter
Select a line and click Result Details to obtain the detailed results of the check.
266
BeanConnect V2.1
Checking availability
8.6.3 Checking the availability of an openUTM-LU62 Gateway and a
communication service
To check the availability of an openUTM-LU62 Gateway and a communication service in the
Management Console, click the openUTM-LU62 Gateway or Communication Services
at the topmost level and choose the Check Availability command in the context menu. The
associated MC-CmdHandler must be running when you perform the check. This also
applies if the component is running on the same host as the proxy.
Figure 49: Checking the availability of an openUTM-LU62 Gateway
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k08
Administering BeanConnect
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Click Result Details to obtain the detailed results of the check as illustrated in the figure.
BeanConnect V2.1
267
Checking availability
Administering BeanConnect
8.6.4 Checking the availability of an MC-CmdHandler
8.6.4.1
Checking the availability of the MC-CmdHandler with the Management Console
You can use the Management Console to check the availability of an MC-CmdHandler client
instance. To do this, click the corresponding node at the topmost level and choose the Show
MC-CmdHandler Client Instances command in the context menu to open the
MC-CmdHandler Client Instances panel.
Figure 50: Availability of an MC-CmdHandler instance
The Availability column in this table indicates whether or not the MC-CmdHandler is
available.
To check the availability of a remote MC-CmdHandler, select the relevant line and choose
the Check Availability command in the context menu.
"Internal" MC-CmdHandlers are identified as <locally coupled> in the list. Their availability
cannot be checked since they are implicitly available.
8.6.4.2
Checking the availability of the MC-CmdHandler in the command line
Solaris and Linux systems
You use the following script in the proxy container's home directory to check whether the
MC-CmdHandler is running:
●
shsc/checkmccmdhandler.sh
In the case of a stand-alone MC-CmdHandler, the scripts are located in the directory shsc
below the MC-CmdHandler's installation directory.
268
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k08
Administering BeanConnect
Checking availability
Windows systems
Check whether the MC-CmdHandler is running by choosing the command by opening the
Start menu and choosing the command MC-CmdHandler Check
in the program group BeanConnect <version> - Proxy <container> - MC-CmdHandler.
You can also check the availability of the MC-CmdHandlers by running the following script
located in the proxy container's home directory:
●
shsc\checkmccmdhandler.cmd
8.6.5 Checking the availability of an EIS partner
You can only check the availability of an EIS partner if a service was specified in the EIS
when the EIS partner was configured. This service is called when the availability check is
performed and the service's output message is output by the Management Console when
you choose the Result Details command.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
To check the availability of an EIS partner in the Management Console, open the EIS
partner's context menu in the navigation tree and choose the Check Availability command.
The associated proxy container must be running. In the case of CICS partners, the
openUTM-LU62 Gateway and the communication service must also be running.
BeanConnect V2.1
269
Checking availability
Administering BeanConnect
Figure 51: Checking the availability of an EIS partner
Select a line and click Result Details to view the EIS output message. If an error occurs,
you will see diagnostic information as illustrated in the example.
270
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k08
Administering BeanConnect
Monitoring the resource adapter
8.7 Monitoring the resource adapter with the Management
Console
The resource adapter can be monitored via MBean clients. For this to be possible, an
MBean client must be configured in the Management Console, see Section 6.11, "Configuring the Management Console as a JMX client".
The MBean client has a fixed assignment to a resource adapter and is displayed in the
resource adapter's tree.
I
It is also possible to define a stand-alone MBean client which is
not assigned to any resource adapter.
For further information, see section "Setting up free JMX
clients" on page 237.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Figure 52: Navigation tree for an MBean
The following nodes are present below the MBean Client node:
Subscribed Notifications
Permits access to all subscribed notifications. You must perform subscription explicitly.
Received Notifications
Permits access to all received notifications. If notifications have been received then the
node is displayed in bold. It is followed by the number of received notifications in brackets.
BeanConnect V2.1
271
Monitoring the resource adapter
Administering BeanConnect
Statistics Collectors
Permits access to the statistics collectors. This node is only displayed if statistics collectors
have been configured, see Section 8.7.4, "Collecting and displaying diagnostic values".
Favorite MBeans
Indicates the MBeans that have been included in the list of favorites. The list of favorites
provides a clearer overview by providing a separate depiction of the frequently used
MBeans. You can define favorites by choosing Add to Favorites in the relevant context
menu.
All Beans
Permits access to all the MBeans including the MBeans listed under Favorite MBeans.
8.7.1 Establishing a connection to the MBean server
Most actions are only possible if there is a connection to the MBean server. If no such
connection has so far been established, choose Connect To MBean Server from the
context menu of the MBean client.
272
BeanConnect V2.1
Monitoring the resource adapter
8.7.2 Displaying MBean object names
When you open the All MBeans or Favorite MBeans nodes, all the defined MBean
domains or, alternatively, all the domains present in the favorites are displayed. You can
then open the individual MBean domains to see the MBean object names. Alternatively, you
can choose the Show MBeans command in the context menu.
Figure 53: MBean - object name subtree
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k08
Administering BeanConnect
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
For each MBean, you see a list containing the elements Attributes, Notifications and, if
operations are possible for the MBean, Operations.
BeanConnect V2.1
273
Monitoring the resource adapter
Administering BeanConnect
8.7.3 Displaying and modifying MBean attributes
MBeans usually possess extensive lists of attributes. You can output the current values of
these attributes via the Management Console. You can also modify some of these
attributes.
8.7.3.1
Displaying MBean attributes
To view an MBean's attributes, expand the MBean's node and click Attributes. Alternatively, you can choose Show MBean Attributes from the context menu.
Figure 54: MBean - attribute table
When you click an attribute in the table to select it, the details are displayed in the lower part
of the window. This detailed view is intended for extensive attributes that cannot be
displayed in full in the table.
The columns of the table have the following meanings:
Name / Description
Name and more detailed description of the attribute.
Type
Type of attribute value, e.g. string, integer, Boolean.
Value
Value of the attribute.
Exception
Specifies whether the JMX server delivered an exception when determining the value of the
attribute If this is the case, you can display the exception in the attribute's detailed view.
274
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k08
Administering BeanConnect
Monitoring the resource adapter
Read
Specifies whether the attribute can be queried at the JMX server. This is the case for the
majority of attributes.
Write
Specifies whether the attribute values can be modified.
June 8, 2009 7:06 pm
Writable
Specifies whether the attribute value can be modified via the Management Console.
Only attributes with "simple" value types (string, integer, Boolean) can be modified via the
Management Console. Attributes with complex (e.g. composite) values cannot usually be
modified via the Management Console. These attributes are then identified as Write but not
as Writable.
8.7.3.2
Modifying MBean attribute values
The Management Console allows you to modify all the attributes that are identified as
Writable in the table. To do this, proceed as follows:
●
In the attribute's context menu, choose Set MBean Attribute Value. Alternatively,
select the attribute and click the Set Value button.
●
You then edit the values in the following dialog.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
The Management Console outputs a message after performing the action. This contains
either a confirmation of the change or an error message if it was not possible to perform the
modification.
BeanConnect V2.1
275
Monitoring the resource adapter
Administering BeanConnect
8.7.4 Collecting and displaying diagnostic values
You can create statistics via the Management Console by configuring statistics collectors.
The statistics collectors poll the values of the MBean attributes at regular intervals;
8.7.4.1
Configuring, displaying and modifying statistics collectors
You can configure a statistics collector for every attribute of an MBean. The Management
Console then generates a node with the name Statistics Collectors below the MBean
client. All the statistics collectors for the MBean client are displayed below this node.
You set up a statistics collector as follows:
●
Display the attributes for the required MBean, see Section 8.7.3.1, "Displaying MBean
attributes".
●
Select the attribute in the table and choose the command Collect Attribute Values in
the attribute's context menu.
When you click the Statistics Collectors node, a table with all the statistics collectors
available for the MBean is output. Alternatively, you can choose Show Statistics
Collectors from the corresponding node's context menu. You will find more details on the
meaning of the table columns in the online Help system.
You can modify the data collection interval for each statistics collector. To do this, select the
required statistics collector in the table, choose Edit Properties in the context menu and
then modify the interval in the following dialog. Alternatively, you can click the Edit button
below the table.
To remove a statistics collector from the table, choose the command Remove MBean
Statistics Collector from the statistics collector's context menu (alternatively: Remove
button below the table). Removing a statistics collector also deletes all the data that has
been collected by this collector up to the time of deletion.
276
BeanConnect V2.1
8.7.4.2
Monitoring the resource adapter
Displaying statistical values
You can view the values for a statistics collector by displaying the table of statistics
collectors and choosing the command Show Statistic Values in the required collector's
context menu. Alternatively, you can select the collector and click the Show Values button
below the table.
Figure 55: MBean - statistical values
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k08
Administering BeanConnect
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
The table with the collected statistical values contains the three columns Time, Value and
Exception, see the online Help system. The Exception column outputs any exception
which the JMX server may have output when determining the statistical value. When you
click a statistical value with the mouse, details such as the complete text of an exception are
displayed in the lower part of the window.
BeanConnect V2.1
277
Monitoring the resource adapter
Administering BeanConnect
8.7.5 Subscribing to and displaying MBean notifications
The MBeans of type ResourceAdapter, ManagedConnectionFactory, Inbound and
MessageEndpoint issue notifications. These are messages which the resource adapter
generates when certain events occur and which can be displayed in the Management
Console. Before you can display notifications, you must have explicitly subscribed to these
in the Management Console (Subscribe procedure).
The following table indicates the notifications that you can subscribe to:
Type of MBean
Name and meaning of the notification
Resource adapter
BeanConnect.Started
The resource adapter has been started.
BeanConnect.Stopped
The resource adapter has been stopped.
ManagedConnectionFactory
BeanConnect.Connection.Error
The resource adapter has thrown an exception for a connection.
BeanConnect.Transaction.Rollback
The connection is involved in a transaction that has been rolled
back.
BeanConnect.Transaction.Heuristic
A heuristic decision has been made for the transaction branch in
which the connection is involved.
Inbound
BeanConnect.MessageEndpoint.Activation
The application server has activated a message endpoint in
BeanConnect.
BeanConnect.MessageEndpoint.Deactivation
The application server has deactivated a message endpoint in
BeanConnect.
BeanConnect.MessageEndpoint.Unknown
A message has arrived for an unknown message endpoint.
BeanConnect.Transaction.Rollback
A transaction has been rolled back during recovery.
BeanConnect.Transaction.Heuristic
A heuristic decision has been made for a transaction during
recovery.
278
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k08
Administering BeanConnect
Monitoring the resource adapter
Type of MBean
Name and meaning of the notification
MessageEndpoint
BeanConnect.MessageEndpoint.Error
An error occurred when calling the message endpoint.
BeanConnect.MessageEndpoint.Exception
An exception was thrown when calling the message endpoint.
BeanConnect.Transaction.Rollback
June 8, 2009 7:06 pm
The message endpoint is involved in a transaction that has been
rolled back.
BeanConnect.Transaction.Heuristic
A heuristic decision has been made for the transaction branch in
which the message endpoint is involved.
8.7.5.1
Subscribing to MBean notifications
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
You can subscribe to the MBean Notifications either all at once or individually:
●
If you want to subscribe to all an MBean's notifications at once, choose the command
Subscribe MBean Notifications in the MBean node's context menu.
●
If you want to subscribe to an individual notification, expand the Notifications node in
an MBean's subtree. All the notifications to which you can subscribe are then displayed.
You should now choose Subscribe MBean Notifications of this type in the context
menu of the required notification.
If you want to terminate your subscription to a notification, use the command Unsubscribe
MBean Notification in the context menu of an MBean's Notifications node or choose
Unsubscribe MBean Notifications of this type from the context menu of a specific notification type node.
The settings for the notifications are retained even after the Management Console is shut
down. As a result, it is not necessary to resubscribe to notifications for which you already
have a subscription each time the Management Console is started. Instead, these notifications are supplied automatically once the connection to the JMX server has been established. However, no notifications generated during the period when the Management
Console was not logged in at the MBean server are supplied.
BeanConnect V2.1
279
Monitoring the resource adapter
8.7.5.2
Administering BeanConnect
Displaying MBean notifications
The Management Console indicates that notifications have been received by displaying the
corresponding nodes in bold. The number of notifications is indicated in parentheses next
to the node. You can view the MBean notifications in the following ways.
●
To view all the notifications from all the MBean clients, click the Received Notifications
node below the MBean Client node or choose the command Show Received
Notifications in this node's context menu.
●
To view all the notifications for a specific MBean, expand the relevant MBean's subtree
and click the Notifications node. Alternatively: Choose the command Show Received
Notifications in this node's context menu.
●
To view all the notifications of a given type, click a notification type node or choose
Show Received Notifications in its context menu.
The notifications and associated attributes are listed in table form in a new window. To
display detailed information for a notification, click to select the notification or choose the
command Show MBean Attributes from the context menu. The details are displayed in the
lower window area. You will find more information on the meaning of the table columns in
the online Help system.
You can delete a notification using the command Remove MBean Notification from the
context menu. Alternatively, you can select the notification and click the Remove button
below the table.
I
280
Received notifications are not saved when the Management
Console is shut down and are therefore not displayed in the next
session.
BeanConnect V2.1
Monitoring the resource adapter
8.7.6 Displaying and executing MBean operations
The Management Console allows you to perform operations on MBeans. These are specific
actions that are performed in the resource adapter, e.g. resetting statistics counters or
checking availability.
Every MBean possesses an Operations node. Clicking this node or choosing Show
MBean Operations from the context menu outputs a table which lists all the operations for
the corresponding MBean.
Figure 56: MBean operations
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k08
Administering BeanConnect
When you click an operation, the detailed information is displayed in the window at the
bottom.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Operations that you can perform using the Management Console are identified accordingly
in the column Invocable. In a similar way to when modifying attribute values, the
Management Console can only execute operations which have no or only simple parameter
types. Proceed as follows to execute this type of operation:
●
In the operation's context menu, choose the command Invoke MBean Operation....
Alternatively, you can select the operation and click the Invoke button below the table.
●
Enter the call (invocation) parameters in the subsequent dialog (if necessary). The
dialog may consist of several sheets. The operation is not performed until you confirm
with OK.
The Management Console outputs a message after execution. This contains either the
result of the operation or an error message if it was not possible to perform the operation.
Switching a resource adapter in the cluster to another proxy
You can use the MBean operation selectProxyApplication to stop a proxy while the
cluster is running and simultaneously switch the resource adapter(s) to a different proxy
("soft" switchover). This has the advantage of minimizing negative impacts on operation. In
contrast, if you stop a running proxy in a proxy cluster directly via the context menu then the
connections administered by this proxy are immediately cleared, with the result, for
example, that open transactions are interrupted and may have to be rolled back.
BeanConnect V2.1
281
Monitoring the resource adapter
Administering BeanConnect
You can avoid this by performing a "soft" switchover. Proceed as follows:
●
Shut down the proxy using the openUTM tool kdcshut and specify a wait time.
To do this, open a shell or DOS command window and enter the following command
(with "\" in Windows systems):
<openUTM-Server_home>/ex/kdcshut
<Proxy_home>
time
Here, <openUTM-Server_home> is the openUTM installation directory, <Proxy_home>
is the fully qualified path name of the proxy and time is the wait time in minutes (recommended value: at least 10 minutes). On the one hand, this call prevents any new
connections from being established and, on the other, it stops the proxy from being shut
down immediately.
●
Immediately after this in the Management Console, call the resource adapter MBean in
a resource adapter instance that is operating with the proxy that you want to shut down.
In this MBean, call the operation selectProxyApplication in order to assign a
different proxy to the resource adapter instance. BeanConnect selects the new proxy
automatically using internal algorithms.
If the application server is configured as a cluster, you must perform this operation for
every resource adapter instance in the application server cluster that is assigned to the
proxy that you want to shut down. The resource adapter MBean's CurrentProxyUrl
attribute indicates the proxy to which a resource adapter instance is assigned.
●
Once you have switched the resource adapter to the new proxy, you can shut down the
earlier proxy by calling kdcshut again and specifying a short wait time (e.g. 5 minutes):
<openUTM-Server_home>/ex/kdcshut
<Proxy_home> 5 G
The parameters 5 and G cause the proxy to be shut down once all the connections have
been cleared but at the latest at the end of the 5 minute wait time.
282
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
June 8, 2009 7:06 pm
9 Interfaces and programming
This chapter provides information on the following topics:
●
BeanConnect-specific interfaces and Common Client Interface (CCI)
●
Programming outbound communication
●
Programming inbound communication
The interfaces in a BPEL environment are described in Chapter 11, "BPEL support".
Before any communication between an EJB and an EIS application can take place, both the
configuration data of BeanConnect and the configuration of the EIS application have to be
set up properly.
●
On outbound communication, an EJB that is deployed in a J2EE application server calls
a service in the EIS partner.
●
On inbound communication, an EIS partner sends messages to an OLTP
message-driven bean that is deployed in a J2EE application server.
© cognitas GmbH 2001-2
I
The Javadoc of BeanConnect, which is often referred to in the
course of this chapter is supplied with the resource adapter JAR
file BC21A00_RA.jar and is available after the installation of the
resource adapter.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
The JavaDoc is located in the resource adapter's installation
directory:
BeanConnect V2.1
■
In Windows systems, under JavaDoc\api\index.html
■
In UNIX/Linux systems under JavaDoc/api/index.html
283
BeanConnect-specific interfaces and CCI
Interfaces and programming
9.1 BeanConnect-specific interfaces and Common Client
Interface (CCI)
BeanConnect offers two different sets of interfaces:
●
BeanConnect-specific interfaces
●
Common Client Interface (CCI)
Recommendations: BeanConnect-specific interfaces or CCI
The Common Client Interface (CCI) is defined in the JCA 1.5 specification of
Sun MicrosystemsTM. The CCI defines a standard API and addresses primarily the needs
of application development tools and EAI Frameworks (Enterprise Application Integration).
If you are familiar with the CCI in the JCA specification, it makes sense to use the CCI.
In any other case it is advisable to use the BeanConnect-specific interfaces, because the
associated programming effort is considerably reduced.
Differences between the BeanConnect-specific interfaces and CCI
For outbound communication, BeanConnect-specific interfaces and the CCI offer virtually
the same functionality.
For OLTP communication with openUTM partners and for CICS partners, the
BeanConnect-specific EISOltpConnection interface and the CCI offer the identical
functionality.
The BeanConnect-specific EISUpicConnection interface merely provides additional
functionality for UPIC connections to openUTM partners (see "Additional functionality
provided by the EISUpicConnection interface" on page 289).
For inbound communication, the BeanConnect-specific OltpMessageListener interface
and the CCI offer the same functionality for dialog communication. Additionally,
BeanConnect provides the AsyncOltpMessageListener interface for asynchronous
communication.
284
BeanConnect V2.1
BeanConnect-specific interfaces and CCI
Selecting the interfaces to be used
For outbound communication, you specify the interface to be used as follows:
●
In the application server-specific deployment descriptor file oc4j-ra.xml of the
resource adapter, you specify the connection factory interface in the <connectionfactory-interface> entry:
●
For the BeanConnect-specific interfaces:
net.fsc.jca.communication.EISOltpConnectionFactory
or
net.fsc.jca.communication.EISUpicConnectionFactory (only if the EIS
partner is an openUTM application)
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
●
For CCI:
net.fsc.jca.communication.cci.BCOltpConnectionFactory
or
net.fsc.jca.communication.cci.BCUpicConnectionFactory (only if the
EIS partner is an openUTM application)
●
In the deployment descriptor file ejb-jar.xml of an EJB, you specify the connection
factory interface in the <res-type> entry:
●
For the BeanConnect-specific interfaces:
net.fsc.jca.communication.EISConnectionFactory
●
For CCI:
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
javax.resource.cci.ConnectionFactory
For inbound communication, you specify your favored interface in the deployment
descriptor file ejb-jar.xml of the message-driven bean.
You specify the interface in the <messaging-type> entry:
●
For the BeanConnect-specific interfaces:
net.fsc.jca.communication.AsyncOltpMessageListener or
net.fsc.jca.communication.OltpMessageListener
●
For CCI:
javax.resource.cci.MessageListener
BeanConnect V2.1
285
Programming outbound communication
Interfaces and programming
9.2 Programming outbound communication
For outbound communication with an openUTM partner application, BeanConnect
supports the communication protocol OSI-TP, which can be used for distributed transaction
processing as well as for non-transactional communication, and the proprietary, non-transactional protocol UPIC for access to openUTM applications.
For outbound communication with an CICS partner application, BeanConnect supports the
communication protocol LU6.2, which can be used for distributed transaction processing as
well as for non-transactional communication.
This section provides you with information on the following topics:
●
BeanConnect-specific interfaces for outbound communication
●
Common Client Interface (CCI) for outbound communication
●
Programming information on outbound communication
●
Program framework for outbound communication
●
Outbound communication with XATMI partners
●
Code samples for outbound communication
9.2.1 BeanConnect-specific interfaces for outbound communication
The BeanConnect-specific interfaces for outbound communication are contained in the
package net.fsc.jca.communication.
9.2.1.1
Connection factory interfaces
You use a connection factory to set up a connection. BeanConnect provides the following
connection factory interfaces:
●
EISConnectionFactory
●
EISOltpConnectionFactory
●
EISUpicConnectionFactory (only if the EIS partner is an openUTM application)
The EISOltpConnectionFactory interface and the EISUpicConnectionFactory
interface extend the EisConnectionFactory interface without providing additional
functionality.
286
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
Programming outbound communication
Using the EISOltpConnectionFactory or EISUpicConnectionFactory interface
makes sense if you want to make sure that communication is processed by means of the
OSI-TP protocol or the UPIC protocol, respectively.
The use of the EISConnectionFactory interface is recommended.
Example 13 Verifying that the OSI-TP protocol is used for communication (openUTM
partner)
To verify that communication with the EIS application is processed by means of the OSI TP
protocol specify the following code sequence:
June 8, 2009 7:06 pm
...
net.fsc.jca.communication.EISConnectionFactory cf =
(EISConnectionFactory)ic.lookup
("java:comp/env/<resourceRefName>");
...
if (! (cf instanceof EISOltpConnectionFactory))
throw new Exception("EISOltpConnectionFactory was
expected!");
...
An exception is thrown if not the OSI-TP protocol is used for communication.
9.2.1.2
Connection interfaces (overview)
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
BeanConnect provides the following connection interfaces:
●
EISConnection
●
EISOltpConnection
●
EISUpicConnection (only if the EIS partner is an openUTM application)
The EISOltpConnection interface extends the EISConnection interface by providing
additional features such as data structure characteristics, for details see "Additional
functionality provided by the EISOltpConnection interface" on page 289).
The EISUpicConnection interface extends the EISConnection interface by providing
additional features such as data structure features (for details see Additional functionality
provided by the EISUpicConnection interface on page 289).
It is recommended that you use the EISOltpConnection and EISUpicConnection interfaces only if you use the additional functionality offered by these interfaces.
BeanConnect V2.1
287
Programming outbound communication
Interfaces and programming
Communication methods provided by the EISConnection interface
The EISConnection interface is extended by a number of interfaces. Each of them
provides methods for outbound communication between the EJB and the EIS application.
For data exchange, these methods are snd(), rcv(), call() and a number of variants of
snd() and rcv() such as sndString() or rcvRecord().
The communication methods offered by these interfaces differ in the data format on which
the methods are based:
●
For byte-array-oriented access to EIS applications:
EISConnectionByteArray
●
For byte-container-oriented access to EIS applications:
EISConnectionByteContainer
An application may use the EISConnectionByteContainer interface and implement
the ByteContainer interface if it wants to exchange structured objects containing text
and binary information with a service in a partner application. Code conversion needs
to be performed for the text information of this object within the class that implements
the ByteContainer interface.
By providing an appropriate ByteContainer object, byte stream to string conversion is
handled while executing the sndRecord(), rcvRecord() or call() methods. The
objects you can obtain from Cobol2Java are objects that use this feature (see
Chapter 14, "Cobol2Java").
●
For OLTP message-oriented access to EIS applications:
EISConnectionOltpMessage
Objects of type OltpMessage are exchanged with the EIS application over this
interface. The OltpMessage object serves as a container for the message content,
which is assembled from one or more OltpMessageRecord objects and/or one or more
OltpMessagePart objects. While an OltpMessageRecord is of arbitrary length, an
OltpMessagePart may not exceed 32767 bytes. OltpMessagePart objects are
mapped to message parts by an openUTM partner application.
OltpMessageRecord objects and OltpMessagePart objects accept the following data
types:
288
●
byte[]
●
String
●
ByteContainer
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
●
Programming outbound communication
For string-oriented access to EIS applications:
EISConnectionString
For code conversion in the course of the communication process the EncodingDef
interface is available.
For detailed information concerning these interfaces, please refer to the Javadoc of
BeanConnect.
Additional functionality provided by the EISOltpConnection interface
The EISOltpConnection interface extends the EISConnection interface by providing the
following additional functionality:
●
Methods that are specific for asynchronous communication (see Asynchronous
communication on page 295): setDelayTime(), getDelayTime()
●
The method setEndConversation()
The method specifies whether the EIS partner application may or may not terminate the
current conversation with the next send...() call.
To make use of the additional functionality offered by the EISOltpConnection interface
you have to cast the EISConnection object, which you obtain when you call the object
EISConnectionFactory with getConnection(), as type
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
con = (EISOltpConnection)cf.getConnection(...);
Additional functionality provided by the EISUpicConnection interface
The EISUpicConnection interface is only relevant if the EIS partner is an openUTM application. It extends the EISConnection interface by providing the following additional
functionality:
●
"Emulation" of terminal functions
openUTM conversations which were programmed for terminals can also be addressed
with the aid of BeanConnect. “Emulation” of terminal functions is only possible with the
EISUpicConnection interface. Terminal functions such as function keys and cursor
positions can be handled using this interface.
●
Using format names (format identifiers) when sending or receiving data
When data is exchanged between the resource adapter and the openUTM partner
application, it is possible to also send format names (format identifiers). Thus the
resource adapter can send to or receive from the openUTM partner structure information about the data along with the user data itself. This function is only supported if
the requested service uses the KDCS interface.
BeanConnect V2.1
289
Programming outbound communication
●
Interfaces and programming
Restart functionality
The openUTM partner application performs an automatic service restart for user IDs
that have been defined with the USER control statement in conjunction with the
RESTART=YES operand.
●
The method isInTransaction() which is used to query the transaction status at the
EIS partner.
To make use of the additional functionality offered by the EISUpicConnection interface,
you have to cast the EISConnection object (which you get calling the getConnection()
method on the EISConnectionFactory object) to the type EISUpicConnection:
con = (EISUpicConnection)cf.getConnection(...);
9.2.1.3
Communication using the connection interfaces
The connection interfaces provide a variety of features which may be used by an EJB in a
communication with an EIS application. These may be used as alternatives or in combination:
●
Dialog communication (based on the EISConnection, EISOltpConnection and
EISUpicConnection interfaces)
●
Asynchronous communication (based on the EISConnection interface and on
additional methods of the interface EISOltpConnection)
●
Transactional communication
●
Connection groups
●
Code conversion
The following sections provide information concerning these topics. Examples of the most
common communication scenarios are given in the Javadoc of BeanConnect.
Dialog communication
The recommended way for an EJB to communicate with an EIS application is by using the
methods of the EISConnectionOltpMessage interface. Objects of type OltpMessage are
exchanged with the EIS application over this interface. The OltpMessage object serves as
a container for the message content, which is assembled from one or more OltpMessageRecord objects and/or one or more OltpMessagePart objects. While an OltpMessageRecord is of arbitrary length, the length of an OltpMessagePart may not exceed
32767 bytes.
At the time of a sndOltpMessage() call, the data to be sent is merely handed over to
BeanConnect but not yet transferred to the EIS application. The request to the EIS application is only actually sent when the first rcvOltpMessage() method is issued for this
connection.
290
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
Programming outbound communication
The easiest way to call a dialog service in an EIS application is with the call() method.
This method allows RPC-like communication with an EIS application.
The following sections outline the communication between an EJB and an openUTM/CICS
program by means of OltpMessage objects.
The options listed below are available for exchanging data between an EJB and an
openUTM/CICS program using OltpMessage objects:
●
Data exchange based on OltpMessagePart objects with openUTM partners
●
Data exchange based on OltpMessageRecord objects
You will find further examples of the most common communication scenarios as well as
code examples in the Javadoc of BeanConnect.
Data exchange based on OltpMessagePart objects with openUTM partners
With MGET and MPUT, an openUTM program can receive or send one or more message
parts each with a maximum length of 32 Kbytes. Here the individual MessagePart objects
correspond directly to the MGET and MPUT calls in the openUTM program.
Data is thus exchanged according to the following scheme:
Figure 57: Data exchange based on OltpMessagePart objects (openUTM partners)
EJB
openUTM partner application
create OLTP message ...
addMessagePart(...)
addMessagePart(...)
© cognitas GmbH 2001-2
call(...)
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
MGET
MGET
MPUT
MPUT
MPUT
getMessageParts(...)
read part 1
read part 2
read part 3
BeanConnect V2.1
291
Programming outbound communication
Interfaces and programming
Data exchange based on OltpMessagePart objects with CICS partners
With RECEIVE and SEND, a CICS program can receive or send one or more message parts
each with a maximum length of 32 Kbytes. Here the individual MessagePart objects correspond directly to the RECEIVE and SEND calls in the CICS program.
Data is thus exchanged according to the following scheme:
Figure 58: Data exchange based on OltpMessagePart objects (CICS partners)
EJB
CICS partner application
create OLTP message ...
addMessagePart(...)
addMessagePart(...)
call(...)
RECEIVE
RECEIVE
SEND
SEND
SEND
getMessageParts(...)
read part 1
read part 2
read part 3
Data exchange based on OltpMessageRecord objects
As an alternative to multiple MessagePart objects sent within an OltpMessage object, you
can use OltpMessageRecord objects sent within an OltpMessage object. In this case, you
can send and receive messages which are longer than 32 Kbytes without needing to break
it down into packets of 32 Kbytes as a Java programmer.
292
BeanConnect V2.1
Programming outbound communication
Figure 59: Data exchange based on OltpMessageRecord objects (OSI-TP protocol with openUTM partners)
EJB
openUTM partner application
create OLTP message ...
addMessageRecord(...)
call (...)
MGET in a loop until all message sections
have been received
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
MPUT
MPUT
MPUT
getMessageRecords(...)
read record
Figure 60: Data exchange based on OltpMessageRecord objects (CICS partners)
EJB
CICS partner application
create OLTP message ...
© cognitas GmbH 2001-2
addMessageRecord(...)
call (...)
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
RECEIVE in a loop until all message
sections have been received
SEND
SEND
SEND
getMessageRecords(...)
read record
BeanConnect V2.1
293
Programming outbound communication
Interfaces and programming
When communicating with an openUTM application via the UPIC protocol, you can use
OltpMessageRecord objects and OltpMessagePart objects if you are working with
different format names.
Figure 61: Data exchange based on OltpMessageRecord objects (UPIC protocol)
EJB
openUTM partner application
create OLTP message ...
addMessageRecord("FORMAT1",...)
addMessageRecord("FORMAT2",...)
call(...)
MGET in a loop until all message sections with
KCRMF/kcrfn="FORMAT1"have been received
MGET in a loop until all message sections with
KCRMF/kcrfn="FORMAT2" have been received
MPUT with KCFM/kcfn="*FORMATA"
MPUT with KCFM/kcfn="*FORMATA"
MPUT with KCFM/kcfn="*FORMATA"
MPUT with KCFM/kcfn="*FORMATB"
MPUT with KCFM/kcfn="*FORMATB"
getMessageRecords(...)
read record 1
All data of the 3 MPUT calls with *FORMATA has been received.
Format name can be read with getMapName() by OLTPMessageRecord.
read record 2
All data of the 2 MPUT calls with *FORMATB has been received.
Format name can be read with getMapName() by OLTPMessageRecord.
294
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
Programming outbound communication
Asynchronous communication
A service is called asynchronous when it does not send a reply message.
The sending of an asynchronous message has to be explicitly triggered by the EJB with the
methods snd() + flush(), sndLast() or sndLastString() of the EISConnection
interface, which finalize the message and initiate the send cycle.
An asynchronous message may be sent to the EIS partner either immediately or after a
delay. With a delayed sending, the EJB must specify the delay time prior to calling the snd()
method. You specify the delay time by means of the setDelayTime() method. A delayed
message is stored by the BeanConnect proxy until the time delay has elapsed. The
message is then forwarded to the EIS application.
I
An asynchronous message generated in a transaction is sent
only if and when the transaction is committed. If the transaction
is rolled back, the asynchronous request will not be sent. An
asynchronous request with time delay 0 generated outside of a
transaction is sent immediately.
If you want to ensure that an asynchronous service is currently being addressed, you can
check this using the getPartnerType() method or you can use the setDelayTime(0)
method, which throws an exception if a dialog service is addressed unexpectedly. However,
the use of this method results in certain performance impairments.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Examples of asynchronous communication with an EIS partner can be found in the Javadoc
of BeanConnect.
Transactional communication
During deployment of a connection factory, the configuration property transactional of
the connection factory has to be set (see "transactional" on page 105). A connection factory
may either support both transactional and non-transactional communication or it may be
limited to non-transactional communication only:
●
If the connection factory supports transactional communication, the runtime
environment decides at the time a transaction is started whether the communication
within a conversation of such a connection will be transactional or not. A conversation
which is started while a transaction is open is always included in the transaction.
A conversation which was already open at the start of the transaction but on which no
communication has yet occurred is also included in the transaction. In these cases a
transactional protocol will be used for communication; otherwise a non-transactional
protocol will be used.
BeanConnect V2.1
295
Programming outbound communication
●
Interfaces and programming
If the connection factory does not support transactional communication, the following
applies: For connections generated with this connection factory, a non-transactional
protocol is always used, no matter whether the communication takes place within or
outside an application server transaction. This allows the deployer of the resource
adapter to explicitly exclude an EIS service from a transaction that may be active in the
application server.
You can query the current status of a transaction using the
isInDistributedTransaction() method of the EISOltpConnection interface.
When a transactional protocol is used for communication, the application server transaction
and the transaction in the EIS partner are part of a single, distributed transaction which are
either committed or rolled back as a single unit. With transactional communication, a
conversation must not span more than one transaction. However, a conversation may
comprise more than one dialog step. This means that several snd()/rcv() pairs may be
exchanged with the EIS partner within a single transaction.
I
If an EJB uses more than one transactional connection within a
transactional EJB method, it is strongly recommended that
these connections are associated in a single EISConnectionGroup (see the following section "Connection groups"). Doing
so helps to avoid a resource bottleneck.
Connection groups
The concept of associated connections enables an EJB to simultaneously send several
messages via more than one connection. This allows the processing of several dialog
services of one or more EIS partner application at the same time, thereby avoiding the time
delay caused by the sequential processing of a number of RPC-like calls.
You can associate a connection with another connection by means of an EISConnectionGroup. You create the EISConnectionGroup using an EISConnectionGroupFactory.
You get an EISConnectionGroupFactory with the method getEISConnectionGroupFactory()from a ConnectionFactory. For example:
ConnectionFactory cf1 = (ConnectionFactory)ic.lookup(...);
ConnectionFactory cf2 = (ConnectionFactory)ic.lookup(...);
EISConnectionGroupFactory cgf =
cf1.getEISConnectionGroupFactory();
EISConnectionGroup cg = cgf.getConnectionGroup();
con1 = (EISOltpConnection)cf1.getConnection(cg);
con2 = (EISOltpConnection)cf2.getConnection(cg);
You will find a code sample for "Associated connections using the EISConnectionGroup
interface" on page 311.
296
BeanConnect V2.1
Programming outbound communication
The simultaneous dispatch of the messages to all connections of the connection group is
initiated by calling the execute() method on the EISConnectionGroup-object. Connections for transactional communication may be associated with connections for non-transactional communication. For details see the Javadoc of BeanConnect.
Code conversion
Whenever String or ByteContainer objects are used, BeanConnect can perform a code
conversion. The methods for setting up the proper environment for a code conversion are
contained in the interface net.fsc.beanta.encoding.EncodingDef. This interface is
extended by the EISConnection interfaces of BeanConnect. If code conversion has not
already been activated at deployment time using the encodingActive configuration
property (see "encodingActive" on page 103), you can switch on code conversion by calling
the method setEncodingActive(). The code table to be used for a code conversion is
assigned by defining the encoding configuration property (see "encoding" on page 102) at
deployment time or by using the method setEncoding() of the EISConnection interface.
For details about code conversion of messages and on how to supply your own encoding
tables see Chapter 10, "Encoding and national language support" on page 333) and the
Javadoc of package net.fsc.beanta.encoding.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
BeanConnect V2.1
297
Programming outbound communication
Interfaces and programming
9.2.2 Common Client Interface (CCI) for outbound communication
The CCI interfaces for outbound communication are contained in the packages
javax.resource.cci and net.fsc.jca.communication.cci. For outbound communication, the CCI offers virtually the same functionality as the BeanConnect-specific interfaces (with the exception of the additional functionality with openUTM partners offered by
the EISUpicConnection interface). You find information on the program framework using
the CCI interface in the section "Program framework for Common Client Interface (CCI)" on
page 304.
Connection factory interfaces
On deployment of the resource adapter, you can specify that you want to use outbound
communication via CCI. To do this, you specify one of the following connection factory interfaces (see "Selecting the interfaces to be used" on page 285) in the <connectionfactory-interface> element of the deployment descriptor file oc4j-ra.xml:
●
net.fsc.jca.communication.cci.BCOltpConnectionFactory
●
net.fsc.jca.communication.cci.BCUpicConnectionFactory
(only if the EIS partner is an openUTM application)
In your EJB code, you use a connection factory to set up a connection. CCI provides the
following connection factory interfaces:
●
javax.resource.cci.ConnectionFactory
●
net.fsc.jca.communication.cci.BCOltpConnectionFactory
●
net.fsc.jca.communication.cci.BCUpicConnectionFactory
(only if the EIS partner is an openUTM application)
The BCOltpConnectionFactory interface and the BCUpicConnectionFactory
interface extend the javax.resource.cci.ConnectionFactory interface without
providing additional functionality.
Using the BCOltpConnectionFactory or BCUpicConnectionFactory interface makes
sense if you want to verify that communication is processed via the OSI-TP or UPIC
protocol respectively. Example 13 on page 287 applies analogously. It is recommended
that you use the interface javax.resource.cci.ConnectionFactory.
Connection interface
The CCI interface for the outbound communication is
javax.resource.cci.Connection.
298
BeanConnect V2.1
Programming outbound communication
9.2.3 Programming information on outbound communication
This section provides programming information on outbound communication between an
EJB and an EIS partner application.
9.2.3.1
Addressing an EIS application
A service of an EIS application which is used by your J2EE application has to be configured
during deployment by defining the configuration property connectionURL (see
connectionURL on page 101 and on page 116). If the J2EE application utilizes multiple
services of the same EIS partner in an EIS you may use the setServiceName() method
of the connection object to address a specific service explicitly:
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
connection.setServiceName(<service_name>);
9.2.3.2
Placing BeanConnect calls in an EJB
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
In the JNDI service of the application server, you have to execute a lookup() for a preconfigured connection factory. A connection factory provides a getConnection() method that
returns a Connection object. During the deployment of the connection factory the
properties of this connection (EIS address, EIS service name, etc.) were configured. No
matter which type of connection factory has been deployed (EISUpicConnectionFactory
or EISOltpConnectionFactory), a Connection object that implements the EISConnection interface is always returned. When the application no longer needs a Connection
object, it must return it to the application server for pooling or destruction by issuing the
close() method for the Connection object.
The application must make sure that it also releases the requested connections with
close() when errors occur. Otherwise, secondary errors may occur in the application
server.
It is recommended that the JNDI lookup() for a connection factory is executed during
initialization. In an EJB this can, for example, take place within the ejbCreate() or
setSessionContext() method.
The getConnection() method and the associated close() method must be called
directly within the business methods.
BeanConnect V2.1
299
Programming outbound communication
9.2.3.3
Interfaces and programming
Authentication (user ID and password)
Authentication takes place by means of user name and password. A distinction is made
between
●
Container-managed authentication
●
Application-managed authentication
It is recommended that you use container-managed authentication.
Container-managed authentication
In the case of container-managed authentication, the access data is handled by the
container. The EJB deployer configures the container-managed authentication with the
following entry in the EJB deployment descriptor:
<res-auth>Container</res-auth>
When using container-managed authentication, you call the getConnection() method
without parameters.
With container-managed authentication, the authentication data itself must be specified in
the deployment descriptor for the BeanConnect resource adapter within a
<security-config> section in the application server-specific deployment file
(oc4j-ra.xml for OC4J).
Application-managed authentication
In the case of application-managed authentication, the access data is handled in the
program code of the EJB. The EJB deployer configures the application-managed authentication in the EJB deployment descriptor with the following entry:
<res-auth>Application</res-auth>
In the EJB source code, you use, for example, the following code sequence instead of the
getConnection() call without parameters:
javax.naming.InitialContext ic = new InitialContext();
String user = (String)ic.lookup("java:comp/env/User");
String password = (String)ic.lookup("java:comp/env/Password");
net.fsc.jca.communication.PasswordCredential pwc =
new net.fsc.jca.communication.PasswordCredential
(user, password);
con= (net.fsc.jca.communication.EISConnection)cf.getConnection(pwc);
Here, the user ID (user in the example) and the password (password in the example) are
defined as environment variables of the EJB. The deployer can adapt environment variables
as required. The environment variables can be accessed using the lookup() method.
300
BeanConnect V2.1
9.2.3.4
Programming outbound communication
Querying information on the conversation with the EIS application
The isInConversation() method of the connection object enables you to query the
status of the EIS application.
Example 14 Information on the conversation with the EIS application
You want to assure that the conversation with the EIS application will be terminated after
method execution has been completed:
...
String s = con.call("what will be the echo of this");
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
if (eis.isInConversation())
{
con.terminate();
con.close();
throw new EJBException
("EJB Exception: EIS Partner Service not yet terminated ... ");
}
9.2.3.5
Programming hints with respect to CICS applications
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
CICS transactions have to be designed and coded to comply with the Distributed Transaction Programming (DTP) paradigm. For a description of this programming paradigm, see
the IBM CICS documentation, for example the "CICS Distributed Transaction Programming
Guide".
The following restrictions and rules have to be considered to allow outbound communication by means of BeanConnect:
●
A CICS partner application may never use SYNCPOINT or ISSUE PREPARE itself.
Instead, it may only do so when requested to by the EJB in the J2EE application server.
●
Basic conversation is not possible. Basic conversation is programmed for CICS by using
commands that begin with GDS, such as
EXEC CICS GDS ALLOCATE, for example.
●
BeanConnect always establishes LU6.2 conversations with SYNCLEVEL 0 or 2 and
never with SYNCLEVEL 1. The SYNCLEVEL of an incoming conversation can be
queried in CICS-API using EXTRACT PROCESS.
●
The default value of the communication property endConversation is false for
CICS partners and true for openUTM partners.
BeanConnect V2.1
301
Programming outbound communication
9.2.3.6
Interfaces and programming
Support of DPL (Distributed Program Link) programs
CICS provides different programming interfaces to invoke another CICS program or to allow
a program to be invoked by another CICS program. Two of these facilities are important
here.
●
DTP (Distributed Transaction Processing) which enables a CICS transaction to communicate with a CICS application running in another system by exchanging messages.
DTP programs are coded using the APPC programming interface.
●
DPL (Distributed Program Link) which enables a CICS program to invoke a program in
another CICS system and wait for the called program to return. Data is exchanged
between the programs in a communication area (COMMAREA). DPL is similar to a remote
procedure call.
BeanConnect makes it possible to invoke outbound transactions via DTP. However, it is not
possible to call a DPL program directly. For this, a DTP program is needed in which the
program link is wrapped.
An example of such a COBOL program fragment with the name DPLSERVR.CCP can be
found in the directory <BC_home>/<proxy_cont_name>/src (Solaris/Linux) respectively
<BC_home>\<proxy_cont_name>\src (Windows). This source code contains hints on the
changes which must be carried out to build a new program.
The DPL program is called with the CICS LINK command, which has three important
parameters:
●
PROGRAM to specify the name of the program to which control is to be passed unconditionally
●
COMMAREA to specify the communication area that is made available to the linked
program
●
LENGTH which specifies the length in bytes of the communication area.
The input data for the distributed program call is received in a message. The input data must
be copied to the communication area. The required output data has to be sent as response
to the EJB when the linked program returns.
302
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
Programming outbound communication
9.2.4 Program framework for outbound communication
This section provides a program framework for outbound communication between an EJB
and an EIS application. The framework contains the principal communication steps.
9.2.4.1
Program framework for BeanConnect-specific interfaces
In BeanConnect you specify the EIS partner to be addressed when deploying a managed
connection factory. You use the lookup() method to search for the connection factory and
obtain a connectivity object by calling the getConnection() method.
The connectivity object provided implements the EISConnection interface for communication with the EIS application:
1. Set up the initial context:
javax.naming.InitialContext ic = new InitialContext();
2. Reference a connection factory:
net.fsc.jca.communication.EISConnectionFactory cf =
(EISConnectionFactory)ic.lookup
("java:comp/env/<resource_reference_name>");
3. Set up the connection:
net.fsc.jca.communication.EISConnection con = (EISConnection)
cf.getConnection();
4. If you use the EISConnection interface in order to specify the service name (TAC) or
the name of the EIS service, proceed as follows:
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
con.setServiceName(<name_of_the_service>);
However, you should note that for performance reasons, it is recommended that you
work with the preconfigured service names.
5. Create the message that you want to send
String requestMessage = "...";
6. Call the EIS application and receive the reply message:
String replyMessage = con.call(requestMessage);
7. Close the connection:
con.close();
Further information on how to program the EISConnection and EISOltpConnection
interfaces is provided in the Javadoc of the interface itself.
BeanConnect V2.1
303
Programming outbound communication
Interfaces and programming
You will find a sample Dialog communication using the EISConnection interface on
page 309.
9.2.4.2
Program framework for Common Client Interface (CCI)
When deploying a managed connection factory in BeanConnect you specify the EIS partner
to be addressed via this managed connection factory. You use the lookup() method to
search for the connection factory and obtain a connectivity object by calling the getConnection() method.
You can request an interaction object via the CCI connection which you obtain from the CCI
connection factory. This interaction object implements an execute() method for initiating
an interaction. The execute() method also knows a BCCciInteractionSpec object in
addition to the input record and output record. In this BCCciInteractionSpec you define
an interactionVerb (SYNC_SEND, SYNC_SEND_RECEIVE or SYNC_RECEIVE) and, at the
same time, the name of the EIS application. This enables you to control an interaction by
providing suitable data instead of calling methods. The default value of the interactionVerb
is SYNC_SEND_RECEIVE.
For details, see the Javadoc of BeanConnect.
Program framework for dialog communication (CCI)
For dialog communication with your server application over the CCI Interface in
BeanConnect, proceed as follows:
1. Set up the initial context:
javax.naming.InitialContext ic = new InitialContext();
2. Reference a connection factory:
javax.resource.cci.ConnectionFactory cf =
(ConnectionFactory)ic.lookup("java:comp/env/eis/myEIS");
A dialog service is assigned as the default service to the connection factory referenced
by eis/myEIS.
3. Set up the connection:
javax.resource.cci.Connection con =
(Connection)cf.getConnection();
Alternatively, an EJB may pass security-related information (user ID/password) to
BeanConnect in a BCCciConnectionSpec object. In this case you specify:
net.fsc.jca.communication.cci.BCCciConnectionSpec;
cred = new BCCciConnectionSpec("myuser", "mypass");
javax.resource.cci.Connection con =
(Connection)cf.getConnection(cred);
304
BeanConnect V2.1
Programming outbound communication
4. Create an Interaction object and an InteractionSpec object:
Interaction ix = (Interaction)con.createInteraction();
BCCciInteractionSpec is = new
BCCciInteractionSpec(InteractionSpec.SYNC_SEND_RECEIVE);
Whereas an Interaction object is created from the Connection object on which it is
to be used, the InteractionSpec object is created using a constructor of the implementation class.
An Interaction object enables an EJB to communicate with an EIS application. An
InteractionSpec object holds properties for driving an interaction with this EIS application. It is used by an interaction to execute the specified function in the EIS application.
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
5. Create a BCRecord object that serves as a container for the message to the EIS and
another BCRecord object that serves as a container for the reply message. This is done
by means of a BCRecordFactory object:
net.fsc.jca.communication.cci.BCRecordFactory rf =
(BCRecordFactory)cf.getRecordFactory();
net.fsc.jca.communication.cci.BCRecord reqrec = (BCRecord)
rf.createBCRecord("request");
net.fsc.jca.communication.cci.BCRecord replrec = (BCRecord)
rf.createBCRecord("reply");
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
After creation, a BCRecord object contains an empty OltpMessage object, which can
be retrieved from the BCRecord object. Subsequently, the BCRecord object can be
populated with OltpMessageRecord or OltpMessagePart objects.
6. Populate the OltpMessage object of the message which is destined for the EIS with
data (here: with two OltpMessagePart objects):
net.fsc.jca.communication.OltpMessage request = reqrec.getOltpMessage();
request.addMessagePart("request - message part1");
request.addMessagePart("request - message part2");
7. Execute the interaction:
ix.execute(is, reqrec, replrec);
The BCRecord object returned from this call again holds an OltpMessage object, which
in turn contains the reply sent by the EIS application in an OltpMessageRecord or
OltpMessagePart object.
BeanConnect V2.1
305
Programming outbound communication
Interfaces and programming
8. Receive the reply message:
net.fsc.jca.communication.OltpMessage reply = replrec.getOltpMessage();
java.util.Iterator it = reply.getMessageParts();
net.fsc.jca.communication.OltpMessagePart msgPart;
String msgText="";
while (it.hasNext()) {
msgPart = (OltpMessagePart) it.next();
msgText += msgPart.getText();
}
9. Close the connection:
con.close();
Further information on how to program the CCI interfaces is provided in the Javadoc of the
CCI.
You will find a code sample of Dialog communication using the CCI on page 310.
Program framework for asynchronous communication (CCI)
For asynchronous communication with your server application over the CCI Interface in
BeanConnect, proceed as follows:
1. Set up the initial context:
javax.naming.Context ic = new InitialContext();
2. Reference a ConnectionFactory:
javax.resource.cci.ConnectionFactory cf =
(ConnectionFactory)ic.lookup("java:comp/env/eis/myAsyncEIS");
3. Set up the connection:
javax.resource.cci.Connection con =
(Connection)cf.getConnection();
Alternatively, an EJB may pass security-related information (user ID/password) to
BeanConnect in a BCCciConnectionSpec object. In this case you specify:
net.fsc.jca.communication.cci.BCCciConnectionSpec cred =
new BCCciConnectionSpec("myuser", "mypass");
javax.resource.cci.Connection con =
(Connection)cf.getConnection(cred);
306
BeanConnect V2.1
Programming outbound communication
4. Create an Interaction object and an InteractionSpec object:
An Interaction object enables an EJB to communicate with a partner application. An
InteractionSpec object holds properties for driving an interaction with a partner
application. It is used by an interaction to execute the specified function in the EIS application.
Whereas an Interaction object is created from the connection object on which it is
to be used, the InteractionSpec is created using a constructor of the implementation
class:
Interaction ix = (Interaction)con.createInteraction();
net.fsc.jca.communication.cci.BCCciInteractionSpec is = new
BCCciInteractionSpec(InteractionSpec.SYNC_SEND,
"ASYNTAC");
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
The assignment of the asynchronous service ASYNTAC specifies that communication
will be asynchronous.
Here, the SYNC_SEND has the same effect as a flush() call when using the
BeanConnect-specific interfaces.
5. Create a BCRecord object that serves as a container for the request message. This is
done by means of a recordFactory:
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
net.fsc.jca.communication.cci.BCRecordFactory rf=
(BCRecordFactory)cf.getRecordFactory();
net.fsc.jca.communication.cci.BCRecord reqrec =
rf.createBCRecord("request");
After creation, a BCRecord object contains an empty OltpMessage object, which can
be retrieved from the BCRecord object and then can be assigned with OltpMessageRecord and/or OltpMessagePart objects.
6. Populate the OltpMessage object of the request record with data (here: with two
OltpMessagePart objects):
net.fsc.jca.communication.OltpMessage request = reqrec.getOltpMessage();
request.addMessagePart("request - message part1");
request.addMessagePart("request - message part2");
7. Execute the interaction:
ix.execute(is, reqrec);
8. Close the connection:
con.close();
BeanConnect V2.1
307
Programming outbound communication
Interfaces and programming
9.2.5 Outbound communication with XATMI partners
You need to take account of the following special characteristics if you program outbound
communication with XATMI partners:
●
Transaction management
The transaction environment in the user program and the transactional property of the
ConnectionFactory determines whether communication with the partner application
is performed with or without Commit FU (TRAN or NOTRAN in XATMI).
●
typed buffer
Only typed buffers of type X_OCTET are supported.
●
Message length and message segments
When the OLTP message interface is used, a message segment in a message sent to
an XATMI partner may be a maximum of 32,000 bytes in length. Longer message
segments are rejected by means of an OltpMessageException. The same restriction
to 32,000 bytes per message segment applies to all the EIS connection interface
methods for which the restriction for other partners is 32,767 bytes.
Messages to XATMI partners in request/reply mode may only consist of one message
segment and this may be a maximum of 32,000 bytes in length.
Messages to XATMI partners in conversational mode may consist of more than one
message segment. Each of these message segments may be up to 32,000 bytes in
length.
Messages passed to BeanConnect via interface methods for which there is no message
length restriction, e.g. sndRecord(String) are fragmented by BeanConnect into
message segments of a maximum of 32,000 bytes in length during communication with
XATMI partners in conversational mode. In the case of XATMI partners in request/reply
mode, messages with a length of more than 32,000 bytes are rejected with an
exception.
308
●
The reception of a FAILURE_RI is indicated to an application by means of an
EISConnectionException.
●
For XATMI partners, the default value of the communication property
endConversation is always false.
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
Programming outbound communication
9.2.6 Code samples for outbound communication
This section contains the following code samples:
●
Dialog communication using the EISConnection interface on page 309.
●
Dialog communication using the CCI on page 310.
●
Associated connections using the EISConnectionGroup interface on page 311.
Example 15 Dialog communication using the EISConnection interface
...
public String callService(String request) throws EJBException
{
net.fsc.jca.communication.EISConnectionFactory cf = null;
net.fsc.jca.communication.EISConnection con = null;
String reply = null;
try
{
javax.naming.InitialContext ic =
new javax.naming.InitialContext();
cf = (net.fsc.jca.communication.EISConnectionFactory)
ic.lookup("java:comp/env/eis/myEIS");
con= cf.getConnection();
reply = con.call(request);
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
con.close();
con = null;
return reply;
}
catch (Exception e)
{
if (con != null)
{
con.close();
}
throw new EJBException ("EJB Exception: " + e);
}
}
BeanConnect V2.1
309
Programming outbound communication
Interfaces and programming
To allow you to use this method, the deployment descriptor of the EJB must contain the
following information:
<resource-ref>
<res-ref-name>eis/myEIS</res-ref-name>
<res-type>net.fsc.jca.communication.EISConnectionFactory</
res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Unshareable</res-sharing-scope>
</resource-ref>
Example 16 Dialog communication using the CCI
...
public String sndRcvJavax(String user, String name, String data)
{
String retValue = "";
Connection connection = null;
try {
Context ic = new InitialContext();
ConnectionFactory cf =
(ConnectionFactory)ic.lookup("java:comp/env/eis/myEIS");
ConnectionSpec cred = new BCCciConnectionSpec (user, "");
connection = cf.getConnection(cred);
Interaction ix = connection.createInteraction();
InteractionSpec is =
new BCCciInteractionSpec(
InteractionSpec.SYNC_SEND_RECEIVE,"HELLO");
BCRecordFactory recordFactory =
(BCRecordFactory)cf.getRecordFactory();
BCRecord in = recordFactory.createBCRecord("SendRecord");
BCRecord out =
recordFactory.createBCRecord("ReceiveRecord");
OltpMessage inMsg = in.getOltpMessage();
inMsg.addMessagePart(data);
out = (BCRecord)ix.execute(is, in);
OltpMessage outMsg = out.getOltpMessage();
Iterator it = outMsg.getMessageParts();
OltpMessagePart msgPart;
310
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
Programming outbound communication
while (it.hasNext()) {
msgPart = (OltpMessagePart) it.next();
retValue += msgPart.getText();
}
} catch ( Throwable ex) {
// Todo: Error handling
}// tryCatch
try
{
if ( connection != null )
connection.close(); }
catch (ResourceException e)
{
retValue += "\n bei connection.close():\n"+getStackInfo(e);
}
return retValue;
} // sndRcvJavax
To allow you to use this method, the deployment descriptor of the EJB must contain the
following information:
<resource-ref>
<res-ref-name>eis/myEIS</res-ref-name>
<res-type>net.fsc.jca.communication.EISConnectionFactory</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Example 17 Associated connections using the EISConnectionGroup interface
...
EISOltpConnection con1 = null;
EISOltpConnection con2 = null;
try {
javax.naming.InitialContext ic =
new javax.naming.InitialContext();
cf = (net.fsc.jca.communication.EISConnectionFactory)
ic.lookup("java:comp/env/eis/myEIS");
EISConnectionGroupFactory cgf =
cf.getEISConnectionGroupFactory();
EISConnectionGroup cg = cgf.getConnectionGroup();
con1 = (EISOltpConnection)cf.getConnection(cg, new
PasswordCredential("upicusea", ""));
con2 = (EISOltpConnection)cf.getConnection(cg, new
PasswordCredential("upicuseb", ""));
OltpMessage om1 = con1.createMessage();
BeanConnect V2.1
311
Programming outbound communication
Interfaces and programming
om1.addMessagePart("STAT");
OltpMessage om2 = con2.createMessage();
om2.addMessagePart("osi-con,l=kdcall");
con1.sndOltpMessage(om1);
con2.sndOltpMessage(om2);
cg.execute();
String s;
om2 = con2.rcvOltpMessage();
Iterator iter = om2.getMessageRecords();
for (s = ""; iter.hasNext(); )
{ s+= ((OltpMessageRecord)iter.next()).getText(); }
String result_o = "";
result_o = result_o + "OltpConnection: KDCINF osi-con,
l=kdcall\n" + s + "\n";
om1 = con1.rcvOltpMessage();
iter = om1.getMessageRecords();
for (s = ""; iter.hasNext(); ) {
s+= ((OltpMessageRecord)iter.next()).getText(); }
result_o = addResult_o(result_o, "OltpConnection:
KDCINF STAT\n" + s + "\n");
s = cg.getGroupName();
result_o = result_o + "OltpConnection: KDCINF STAT\n" +s
+ "\n");
con1.close();
con2.close();
return result_o;
} catch(EISConnectionException ex) {
...
312
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
Programming inbound communication
9.3 Programming inbound communication
For inbound communication, an EIS application addresses an OLTP message-driven bean
which is deployed in the application server. Communication between the EIS application
and the OLTP message-driven bean requires that the OLTP message-driven bean has
been made known to BeanConnect using the Management Console.
This section provides you with information on the following topics:
●
OLTP message-driven beans
●
Inbound communication with openUTM partners
●
Inbound communication with CICS applications
●
Inbound communication with other EIS partners (openUTM)
●
Inbound communication with XATMI partners
●
BeanConnect-specific interfaces for inbound communication
●
Common Client Interface (CCI) for inbound communication
●
Code samples for inbound communication
9.3.1 OLTP message-driven beans
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
OLTP message-driven beans are the types of JCA-like message endpoint applications
supported by BeanConnect. An EIS application can call OLTP message-driven beans
deployed in an application server via BeanConnect.
In order to communicate with an OLTP message-driven bean, an EIS application sends a
message to a service known to BeanConnect. BeanConnect then passes the message to
an OLTP message-driven bean configured for the message endpoint name that is
associated with this service name. The connection between the service name and the
message endpoint name is established by the Management Console (see "Configuring
inbound message endpoints" on page 219).
BeanConnect supports two types of OLTP message-driven beans:
●
OLTP message-driven beans for dialog communication
●
OLTP message-driven beans for asynchronous communication
BeanConnect V2.1
313
Programming inbound communication
Interfaces and programming
OLTP message-driven beans for dialog communication
An OLTP message-driven bean for dialog communication receives messages from an
EIS application and returns messages. The related BeanConnect-specific interface is
net.fsc.jca.communication.OltpMessageListener. The CCI interface
javax.resource.cci.MessageListener also matches the requirements for dialog
communication.
These interfaces enable an OLTP message-driven bean to receive a message from and
send a reply message to the EIS application. The messages may contain one or more
message parts.
OLTP message-driven beans for asynchronous communication
An OLTP message-driven bean for asynchronous communication can receive a message
from an EIS application, but is not allowed to send a reply message. The associated
BeanConnect-specific interface is net.fsc.jca.communication.AsyncOltpMessageListener. The message from the EIS application may contain one or more message
segments.
9.3.2 Inbound communication with openUTM partners
For inbound communication with an openUTM partner, BeanConnect supports the communication protocol OSI-TP (transactional or non-transactional) as well as transport-level
protocols such as RFC1006 or the openUTM-socket protocol, all of which are non-transactional protocols.
The configuration of the openUTM partner application needs to be adapted properly in
order to be able to call an OLTP message-driven bean.
You can call an OLTP message-driven bean for asynchronous communication using the
OSI-TP protocol or a transport-level protocol. You can call OLTP message-driven beans for
dialog communication using the OSI-TP protocol.
314
●
Connections to BeanConnect for communication using the OSI-TP protocol can be
configured with the Management Console (see Chapter 6, "Configuration of
BeanConnect").
●
Connections to BeanConnect for communication using a transport-level protocol must
be configured in the EIS (see Chapter 7, "Adapting the configuration in the EIS
partner"). The Management Console does not support the configuration of these
connections.
●
An LTAC must be configured in the EIS for each OLTP message-driven bean to be
called using the OSI-TP protocol. The RTAC name assigned to this LTAC must be
identical to the inbound service name of the inbound message endpoint which has been
assigned to this EJB at the time of deployment.
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
●
Programming inbound communication
The encoding of the user messages is determined on deployment of the
OLTP message-driven bean (activation-config properties encodingActive and
encoding, see "Configuration properties in the ejb-jar.xml" on page 127) or on the
configuration of the inbound service, see Section 6.8.2, "Configuring inbound services".
The handshake functional unit of OSI-TP must not be used in communication with
OLTP message-driven beans.
The messages sent by an openUTM partner application to an OLTP message-driven bean
may consist of one or more message parts. Each message part can be read separately by
the OLTP message-driven bean (see "Program framework using the interfaces
AsyncOltpMessageListener and OltpMessageListener" on page 322). Likewise, the
OLTP message-driven bean may assemble the reply message from several message parts
which are to be read by the openUTM partner application with a sequence of MGET NT calls.
For details see Section "Program framework using the interfaces
AsyncOltpMessageListener and OltpMessageListener" on page 322.
If you use the transport-level protocol to call an OLTP message-driven bean, the first
message part sent to this bean must be prefixed with the service name that was assigned
to the message endpoint corresponding to this EJB at the time of deployment.
I
You can find further information in the openUTM documentation.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
9.3.3 Inbound communication with CICS applications
BeanConnect supports the communication protocol LU6.2 for inbound communication with
a CICS application. To allow communication to take place by means of BeanConnect, some
additional restrictions and rules apply:
●
Basic conversation is not supported. Basic conversation is programmed for CICS using
commands that begin with GDS.
●
PIP data cannot be used for the CONNECT PROCESS call. The data is lost.
●
It is not possible to use different mode names for different connections to the same
partner. For CICS/ESA V4.1 the mode name is set in the session definition and can then
be selected implicitly in the program interface using the SYSID parameter in the
ALLOCATE call.
●
If an LU6.2 conversation to the J2EE application server cannot be opened due to
internal connectivity problems in BeanConnect itself, CICS does not receive a detailed
rejection message. The detailed rejection messages can only be found in one of the
protocol files of BeanConnect.
BeanConnect V2.1
315
Programming inbound communication
●
BeanConnect supports SYNCLEVEL 0 (non-transactional conversation) and
SYNCLEVEL 2 (transactional conversation).The SYNCLEVEL is set in CICS-API using
the SYNCLEVEL parameter for CONNECT PROCESS.
●
If inbound communication uses SYNCLEVEL 2, the CICS program must call the proxy
for the end of the transaction with the commands SEND LAST and SYNCPOINT or ISSUE
PREPARE. Then the proxy terminates the transaction. CICS can request the end of the
transaction either when sending the user message or after receiving the answer.
●
Only one-step dialogs are possible (one SEND INVITE call in the CICS program).
However, message and reply may comprise several parts. A SEND and a RECEIVE call
must be executed for each message part. The last part is indicated by the sender with
a SEND INVITE call.
●
With SYNCLEVEL 0, the OLTP message-driven bean terminates communication. This
means that CICS may send a message using SEND INVITE and receive the corresponding reply message using RECEIVE. Subsequently, the dialog is terminated and
SEND LAST is no longer permissible. However, it is possible for CICS to submit SEND
LAST instead of submitting the SEND INVITE / RECEIVE pair. Here, CICS sends the
message to the OLTP message-driven bean without receiving a corresponding reply
message.
I
316
Interfaces and programming
A CICS program for inbound communication must be designed
and coded to comply with the Distributed Transaction
Programming (DTP) paradigm. For a description of this
programming paradigm, see the IBM CICS documentation, e.g.
the CICS Distributed Transaction Programming Guide.
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
Programming inbound communication
9.3.4 Inbound communication with other EIS partners (openUTM)
For inbound communication, BeanConnect supports the following EIS partners other than
openUTM or CICS:
●
UPIC partners
●
Transport-system partners such as RFC1006 partners or openUTM-socket partners
The following rules apply for communication using the UPIC protocol or transport-level
protocols (RFC1006 or the openUTM-socket protocol), all of which are non-transactional
protocols:
●
UPIC partners can only be used to call OLTP message-driven beans for dialog communication. UPIC message parts are mapped onto OltpMessagePart objects and vice
versa.
●
If you use the transport-level protocol to call an OLTP message-driven bean, the first
message part sent to this bean must be prefixed with the inbound service name that
was assigned to the message endpoint corresponding to this EJB at the time of
deployment.
●
The encoding of the user messages is determined on deployment of the
OLTP message-driven bean (activation-config properties encodingActive and
encoding, see Section 4.5.1, "Configuration properties in the ejb-jar.xml" ) or during
the configuration of the inbound service (see Section 6.8.2, "Configuring inbound
services" ).
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
9.3.5 Inbound communication with XATMI partners
During inbound communication, openUTM and UPIC partners that use the XATMI API are
also supported. In this case, communication with the openUTM partner is always performed
via the OSI-TP protocol.
The following applies to communication with XATMI partners:
●
Only typed buffers of type X_OCTET are supported.
●
An OLTP message-driven bean can use an OltpMessageContext object to determine
whether the calling EIS partner is an XATMI partner and - if it is - what paradigm it uses
(request/reply or conversational). For details, see Section 9.3.6.2, "Determining sender
contexts in the OLTP message-driven bean".
●
The length of a (coded) message segment must not exceed 32,000 bytes.
●
In the request/reply paradigm, only one message segment may be sent.
BeanConnect V2.1
317
Programming inbound communication
Interfaces and programming
9.3.6 BeanConnect-specific interfaces for inbound communication
The following BeanConnect-specific interfaces of the package net.fsc.jca.communication are supported for inbound communication:
●
AsyncOltpMessageListener for asynchronous communication
To receive an inbound message, the interface provides the onMessage() method,
which contains the inbound message as a parameter.
●
OltpMessageListener for dialog communication
To receive an inbound message and send a reply message, the interface provides the
onMessage() method, which contains the inbound message as a parameter and
returns a reply message to the EIS application.
9.3.6.1
Programming information on OLTP message-driven beans
●
●
An OLTP message-driven bean must implement exactly one of the following interfaces:
–
AsyncOltpMessageListener
–
OltpMessageListener
An OltpMessage object may consist of one or more OltpMessagePart objects and/or
one or more OltpMessageRecord objects. Whereas an OltpMessageRecord is of
arbitrary length, an OltpMessagePart object must not exceed a length of 32767 bytes.
You can retrieve the message content from OltpMessagePart and OltpMessageRecord objects as an object of one of the following types:
●
byte[]
●
String
●
ByteContainer
An OLTP message-driven bean may implement the ByteContainer interface if it wants
to exchange structured objects containing text and binary information with an EIS application. Here, code conversion needs to be performed for the text information of the
structured object. For objects of type String, code conversion is performed by
BeanConnect. For details, see the Javadoc of BeanConnect.
●
318
The sequence in which OltpMessagePart- and/or OlpMessageRecord objects are
added to an OltpMessage or are returned by an OltpMessage corresponds to the
sequence in which the message was sent or received.
BeanConnect V2.1
●
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
Programming inbound communication
The interface OltpMessageContext serves two purposes:
–
It provides a method for generating a reply message.
–
It allows status information to be retrieved.
An OLTP message-driven bean may call the methods of the interface OltpMessageContext only from within the onMessage() method.
●
When calling the method addMessagePart() or the method addMessageRecord()
within the method onMessage(), you must use the same OltpMessage that was used
to call one of the methods createMessagePart() or createMessageRecord()
respectively.
●
Asynchronous OLTP message-driven beans receive asynchronous messages, which
arrive independently of the initiator's availability. Therefore, neither a reply message nor
an exception thrown by an asynchronous OLTP message-driven bean can be returned
to the initiator of the asynchronous message.
●
If transactional communication via the OSI-TP protocol is used between the EIS application and BeanConnect, the method onMessage(OltpMessage) of a dialog based
OLTP message-driven bean participates in a distributed transaction, if the transaction
attribute Required has been assigned to this method.
●
Asynchronous OLTP message-driven beans can never be part of a transaction that is
distributed between the EIS application and the application server.
●
The method onMessage() of an asynchronous OLTP message-driven bean which has
been deployed with the transaction attribute Required is called in the transaction,
which has been started by the proxy (never by the EIS). If the transaction is rolled back,
the asynchronous message is redelivered to the OLTP message-driven bean if
necessary.
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
The OLTP message-driven bean can detect such a situation by evaluating the delivery
count value of an asynchronous OltpMessage object. The redeliveryThreshold
activation-config property, which is specified at deployment of the OLTP
message-driven bean, defines the number of additional attempts to deliver the
message if an error occurs (see "redeliveryThreshold" on page 130).
●
The support methods of the interface EncodingDef are available through the interface
OltpMessageContext for exchanging messages in codes other than ASCII.
For detailed information, refer to the Javadoc of BeanConnect.
BeanConnect V2.1
319
Programming inbound communication
9.3.6.2
Interfaces and programming
Determining sender contexts in the OLTP message-driven bean
An OLTP message-driven bean can obtain information about the sender via the object
OltpMessageContext. This includes, for example, the application name and host name of
the EIS partner and the inbound service with which the OLTP message-driven bean was
called in the proxy. It may, for example, be of interest to identify the inbound service, if
several different inbound services have been assigned to a message endpoint in the proxy
container.
The object OltpMessageContext provides the following methods for querying the sender
context:
●
String getBCProxyName()
Name of the proxy application, fixed length of 8 characters
●
String getBCProxyHost()
Name of the host on which the proxy is running, fixed length of 8 characters.
●
String getBCProxyInboundService()
Name of the called inbound service in the proxy, fixed length of 8 characters.
●
enum BCCommunicationProtocolType getBCCommunicationProtocol()
Identifier for the communication protocol via which the EIS partner called the inbound
service.
–
In the case of dialog communication, the type of communication protocol (or client
protocol) can be determined from the enumeration class
BCCommunicationProtocolType.
–
In the case of asynchronous communication, the protocol type of the logical access
point in the proxy is passed, see also getBCProxyLocalPartnerName().
BCCommunicationProtocolType returns the following values:
'2' corresponds to the protocol type OSI-TP
'3' corresponds to the protocol type UPIC
'5' corresponds to the protocol type RFC1006
'6' corresponds to the protocol type SOCKET
●
String getBCPartnerTransportSelector()
String with a fixed length of 8 characters. In the case of asynchronous communication,
blanks are passed.
320
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
Programming inbound communication
In the case of dialog communication, the following elements are passed depending on
the protocol type:
●
–
Protocol type UPIC, RFC1006 or SOCKET: Partner name of the client in the proxy
–
Protocol type OSI-TP and openUTM partner in BS2000: BCAM application name of
the remote host
–
Protocol type OSI-TP and openUTM partner on open platforms: The partner application's T selector
–
Protocol type OSI-TP and CICS partner: TRANSPORT-SELECTOR which is
assigned to the CICS partner in the openUTM-LU62 Gateway
String getBCPartnerNetworkSelector()
String with fixed length of 8 characters. In the case of asynchronous communication,
blanks are passed.
●
–
Protocol type UPIC, RFC1006 or SOCKET: Processor name of the client
–
Protocol type OSI-TP and openUTM partner in BS2000: BCAM processor name of
the host on which the partner application is located
–
Protocol type OSI-TP and openUTM partner on open platforms: Host name of the
partner computer
–
Protocol type OSI-TP and CICS partner: NETWORK-SELECTOR assigned to the
CICS partner in the openUTM-LU62 Gateway
String getBCProxyTransportSelector()
String with fixed length of 8 characters. In the case of asynchronous communication,
blanks are passed.
In the case of dialog communication, the following elements are passed depending on
the protocol type:
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
In the case of dialog communication, the following elements are passed depending on
the protocol type:
BeanConnect V2.1
–
Protocol type UPIC, RFC1006 or SOCKET: Application name in the proxy application (BCAMAPPL name)
–
Protocol type OSI-TP and openUTM partner: TRANSPORT-SELECTOR of the
ACCESS-POINT in the proxy application
–
Protocol type OSI-TP and CICS partner: TRANSPORT-SELECTOR of the
associated ACCESS-POINT in the openUTM-LU62 Gateway.
321
Programming inbound communication
●
Interfaces and programming
String getBCProxyUserId()
User ID in the proxy application or, if the protocol type is OSI-TP and the EIS partner
has not passed any user ID, the connection name
(ASSOCIATION name). Fixed length of 8 characters.
●
String getBCProxyLocalPartnerName()
Name of the logical access point in the proxy application. In the case of the protocol type
OSI-TP, this is the OSI-LPAP name; for all other protocol types, it is the LTERM name.
Fixed length of 8 characters.
●
String getBCRaMessageEndpointName()
Name of the called message endpoint.
●
boolean isBCPartnerXATMI()
true if the EIS partner communicates with the BeanConnect proxy via the XATMI
interface, otherwise false.
●
boolean isBCPartnerXATMIConversational()
true if the EIS partner communicates with the BeanConnect proxy via the XATMI
interface and has selected the conversational communication paradigm, otherwise
false (i.e. request/reply paradigm).
Strings which are returned with a fixed length of 8 may be padded with blanks at the end if
necessary.
9.3.6.3
Program framework using the interfaces AsyncOltpMessageListener and
OltpMessageListener
An OLTP message-driven bean receives the inbound message as the inMsg parameter of
the onMessage() method. The received object is an OltpMessage object. From the
OltpMessage object you can retrieve an OltpMessageContext object which in turn
contains attributes of the received message and serves dialog OLTP message-driven
beans as a factory for creating a response message:
1. Access to the message context:
OltpMessageContext oltpMsgCtx = inMsg.getMessageContext();
2. Access the message content:
The OltpMessage object allows access to the message content which may be
processed in the form of OltpMessageRecord or OltpMessagePart objects.
322
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
Programming inbound communication
In the case of OltpMessagePart objects you specify:
if (inMsg.countMessageParts() > 0) {
OltpMessagePart inMsgPart;
Iterator it = inMsg.getMessageParts();
for ( ; it.hasNext(); ) {
inMsgPart = (OltpMessagePart) it.next();
inMsgTxt += inMsgPart.getText();
}
June 8, 2009 7:06 pm
}
In the case of OltpMessageRecord objects you specify
String inMsgTxt = "";
if (inMsg.countMessageParts() > 0) {
OltpMessagePart inMsgPart;
Iterator it = inMsg.getMessageParts();
for ( ; it.hasNext(); ) {
inMsgRec = (OltpMessageRecord) it.next();
inMsgTxt += inMsgRec.getText();
}
}
3. Creating a reply message (only in the case of OLTP message-driven beans for dialog
communication):
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
An OLTP message-driven bean for dialog communication uses the OltpMessageContext interface to create an OltpMessage object for the reply message:
OltpMessage outMsg = oltpMsgCtx.createMessage();
4. The OltpMessage object needs to be populated with message content (only in the case
of OLTP message-driven beans for dialog communication). You can do this in different
ways using OltpMessageRecord and/or OltpMessagePart objects.
–
You should construct the response message using OltpMessagePart objects if the
message recipient is to be sent a response structured in message segments. If the
recipient is an openUTM application then it reads each message segment transferred with an OltpMessagePart object by means of a separate MGET call.
–
If it is not important for the response message to be structured in message
segments then it is more advantageous to use OltpMessageRecord objects.
You will find a code sample of an OLTP message-driven bean for dialog communication on
page 327 and a code sample of an OLTP message-driven bean for asynchronous communication on page 328.
BeanConnect V2.1
323
Programming inbound communication
Interfaces and programming
9.3.7 Common Client Interface (CCI) for inbound communication
The CCI interface for the inbound communication is
javax.resource.cci.MessageListener. This interface offers the same functionality as
the BeanConnect-specific OltpMessageListener interface.
In addition, the interfaces net.fsc.jca.communication.cci.BCRecord and
net.fsc.jca.communication.OltpMessage may be used for inbound communication.
9.3.7.1
Programming information on OLTP message-driven beans (CCI)
An OLTP message-driven bean (CCI) must implement the interface
javax.resource.cci.MessageListener. OLTP message-driven beans (CCI) meet the
requirements for dialog communication. The corresponding rules described in the section
"Programming information on OLTP message-driven beans" on page 318 apply.
9.3.7.2
Program framework using the interface javax.resource.cci.MessageListener
An OLTP message-driven bean (CCI) receives the inbound message as the record
parameter of the onMessage() method of the MessageListener interface. The received
object is of type BCRecord and contains an OltpMessage object. From the OltpMessage
object you can retrieve an OltpMessageContext object that in turn contains attributes of
the received message and also serves dialog OLTP message-driven beans as a factory for
creating a response message:
1. Extract the OltpMessage object from the BCRecord object:
OltpMessage inMsg = ((BCRecord)record).getOltpMessage();
2. Set up the message context:
String inMsgTxt;
OltpMessageContext oltpMsgCtx = inMsg.getMessageContext();
3. Access the message content:
The OltpMessage object allows access to the message content which may be
processed in the form of OltpMessageRecord or OltpMessagePart objects. From
these objects, you can retrieve the message content as an object of one of the following
types:
324
●
byte[]
●
String
●
ByteContainer
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
Programming inbound communication
In the case of OltpMessagePart objects you specify:
if (inMsg.countMessageParts() > 0) {
OltpMessagePart inMsgPart;
Iterator it = inMsg.getMessageParts();
for ( ; it.hasNext(); ) {
inMsgPart = (OltpMessagePart) it.next();
inMsgTxt = inMsgPart.getText();
}
June 8, 2009 7:06 pm
}
In the case of OltpMessageRecord objects you specify:
if (inMsg.countMessageRecords() > 0) {
OltpMessageRecord inMsgRec;
Iterator it = inMsg.getMessageRecords();
for ( ; it.hasNext(); ) {
inMsgRec = (OltpMessageRecord) it.next();
inMsgTxt = inMsgRec.getText();
}
}
4. Create an OLTPMessage object for the reply message:
An OLTP message-driven bean for dialog communication uses the OltpMessageContext interface to create an OltpMessage object for the reply message:
5. The OltpMessage object needs to be populated with the reply message content.
You can do this in different ways using OltpMessageRecord and/or OltpMessagePart objects.
In the case of OltpMessagePart objects you specify:
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
OltpMessage outMsg = oltpMsgCtx.createMessage();
OltpMessagePart outMsgPart = outMsg.createMessagePart();
outMsgPart.setText("reply");
outMsg.addMessagePart(outMsgPart);
In the case of OltpMessageRecord objects you specify:
OltpMessageRecord outMsgRec = outMsg.createMessageRecord("");
outMsgRec.setText("reply");
outMsg.addMessageRecord(outMsgRec);
BeanConnect V2.1
325
Programming inbound communication
Interfaces and programming
6. Before return, the reply message needs to be set in the BCRecord object which is
subsequently returned from this method:
((BCRecord)record).setOltpMessage(outMsg);
You will find a code sample of an OLTP message-driven bean (CCI) on page 330.
326
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
Programming inbound communication
9.3.8 Code samples for inbound communication
This section contains the following code samples:
●
OLTP message-driven bean for dialog communication
●
OLTP message-driven bean for asynchronous communication
●
OLTP message-driven bean (CCI)
Example 18 OLTP message-driven bean for dialog communication
package net.fsc.jca.beanconnect.oltpmdb;
import
import
import
import
import
javax.ejb.EJBException;
javax.ejb.MessageDrivenBean;
javax.ejb.MessageDrivenContext;
java.util.Iterator;
net.fsc.jca.communication.*;
public class SampleDialogOltpMdbBean
implements MessageDrivenBean, OltpMessageListener {
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
public void ejbCreate()
throws EJBException {
// @TODO: add code
}
public void setMessageDrivenContext(MessageDrivenContext ctx)
throws EJBException {
// @TODO: add code
}
public void ejbRemove()
throws EJBException {
// @TODO: add code
}
public OltpMessage onMessage(OltpMessage inMsg) {
String inMsgTxt;
OltpMessageContext oltpMsgCtx = inMsg.getMessageContext();
// read request
try {
if (inMsg.countMessageParts() > 0) {
OltpMessagePart inMsgPart;
BeanConnect V2.1
327
Programming inbound communication
Interfaces and programming
Iterator it = inMsg.getMessageParts();
for ( ; it.hasNext(); ) {
inMsgPart = (OltpMessagePart) it.next();
inMsgTxt = inMsgPart.getText();
// @TODO: process message part
}
// @TODO: process request
}
}
catch (Exception ex) {
// @TODO: handle exception
}
// setup reply
OltpMessage outMsg = oltpMsgCtx.createMessage();
OltpMessagePart outMsgPart = outMsg.createMessagePart();
try {
outMsgPart.setText("Reply from SampleDialogOltpMdbBean");
}
catch (OltpMessageException ex) {
// @TODO: add exception handling
}
outMsg.addMessagePart(outMsgPart);
return (outMsg);
}
}
Example 19 OLTP message-driven bean for asynchronous communication
package net.fsc.jca.beanconnect.oltpmdb;
import
import
import
import
import
javax.ejb.EJBException;
javax.ejb.MessageDrivenBean;
javax.ejb.MessageDrivenContext;
java.util.Iterator;
net.fsc.jca.communication.*;
public class SampleAsynOltpMdbBean
implements MessageDrivenBean,AsyncOltpMessageListener {
public void ejbCreate()
throws EJBException {
// @TODO: add code
328
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
Programming inbound communication
}
public void setMessageDrivenContext(MessageDrivenContext ctx)
throws EJBException {
// @TODO: add code
}
June 8, 2009 7:06 pm
public void ejbRemove()
throws EJBException {
// @TODO: add code
}
public void onMessage(OltpMessage inMsg) {
String inMsgTxt;
OltpMessageContext oltpMsgCtx = inMsg.getMessageContext();
// read request
try {
if (inMsg.countMessageParts() > 0) {
OltpMessagePart inMsgPart;
Iterator it = inMsg.getMessageParts();
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
for ( ; it.hasNext(); ) {
inMsgPart = (OltpMessagePart) it.next();
inMsgTxt = inMsgPart.getText();
// @TODO: process message part
}
// @TODO: process request
}
}
catch (Exception ex) {
// @TODO: handle exception
}
return;
}
}
BeanConnect V2.1
329
Programming inbound communication
Interfaces and programming
Example 20 OLTP message-driven bean (CCI)
package net.fsc.jca.beanconnect.oltpmdb;
import java.util.Iterator;
import
import
import
import
import
javax.ejb.EJBException;
javax.ejb.MessageDrivenBean;
javax.ejb.MessageDrivenContext;
javax.resource.cci.MessageListener;
javax.resource.cci.Record;
import
import
import
import
import
net.fsc.jca.communication.OltpMessage;
net.fsc.jca.communication.OltpMessageContext;
net.fsc.jca.communication.OltpMessageException;
net.fsc.jca.communication.OltpMessagePart;
net.fsc.jca.communication.cci.BCRecord;
public class SampleCciOltpMdbBean
implements MessageDrivenBean, MessageListener {
public Record onMessage(Record record) {
String inMsgTxt;
OltpMessage inMsg = ((BCRecord)record).getOltpMessage();
OltpMessageContext oltpMsgCtx = inMsg.getMessageContext();
// read request
try {
if (inMsg.countMessageParts() > 0) {
OltpMessagePart inMsgPart;
Iterator it = inMsg.getMessageParts();
for ( ; it.hasNext(); ) {
inMsgPart = (OltpMessagePart) it.next();
inMsgTxt = inMsgPart.getText();
// @TODO: process message part
}
// @TODO: process request
}
}
catch (Exception ex) {
// @TODO: handle exception
330
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k09
Interfaces and programming
Programming inbound communication
}
// setup reply
June 8, 2009 7:06 pm
OltpMessage outMsg = oltpMsgCtx.createMessage();
OltpMessagePart outMsgPart = outMsg.createMessagePart();
try {
outMsgPart.setText("Reply from SampleCciOltpMdbBean");
}
catch (OltpMessageException ex) {
// @TODO: add exception handling
}
outMsg.addMessagePart(outMsgPart);
((BCRecord)record).setOltpMessage(outMsg);
return record;
}
/**
* Method ejbCreate() as required by EJB spec.
*/
public void ejbCreate()
throws EJBException {
// @TODO: add code
}
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
/**
* Method setMessageDrivenContext() as required by interface
* javax.ejb.MessageDrivenBean.
* javax.ejb.MessageDrivenBean#setMessageDrivenContext(
*
MessageDrivenContext ctx)
*/
public void setMessageDrivenContext(MessageDrivenContext ctx)
throws EJBException {
// @TODO: add code
}
/**
* Method ejbRemove() as required by interface
* javax.ejb.MessageDrivenBean.
*
* @see javax.ejb.MessageDrivenBean#ejbRemove()
*/
BeanConnect V2.1
331
Programming inbound communication
Interfaces and programming
public void ejbRemove()
throws EJBException {
// @TODO: add code
}
}
332
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k10
This chapter provides the following information:
●
The section "Encoding" describes the code conversion between a Java program using
Unicode and the specific encoding used by the partner system.
●
The section "National language support for message output"describes the
BeanConnect National Language Support (NLS) feature for language- and
country-specific message display from the BeanConnect resource adapter, the
BeanConnect proxy and the BeanConnect Management Console.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
10 Encoding and national language support
BeanConnect V2.1
333
Encoding
Encoding and national language support
10.1 Encoding
If BeanConnect receives printable data from partners on BS2000/OSD or on an IBM
mainframe, the data stream encoded in 1-byte code (for example EBCDIC) must first be
converted into 2-byte Unicode so that a Java program can process it directly. Correspondingly, conversion from 2-byte Unicode to 1-byte code is required when a Java program with
BeanConnect sends data to the BS2000/OSD or CICS partner.
To convert 1-byte code to 2-byte Unicode and vice versa, you have the following options:
●
Standard conversion between EBCDIC code and Unicode for EIS partners of type
openUTM
●
Standard conversion between EBCDIC code and Unicode for EIS partners of type CICS
●
Using other predefined code tables
●
Using custom charsets
●
Creating and using legacy code tables
You can find further detailed information on the topics discussed in this chapter in the
Javadoc for BeanConnect concerning the package net.fsc.beanta.encoding.
All code tables used by the IBM systems can be found in
http://www-1.ibm.com/servers/eserver/iseries/software/
globalization/codepages.html
10.1.1 Standard conversion between EBCDIC code and Unicode for EIS
partners of type openUTM
In most cases you do not need to deal with conversion from EBCDIC code to Unicode and
vice versa as BeanConnect performs conversion automatically in accordance with the
standard code table OSD_EBCDIC_DF04_DRV.
Code conversion takes place automatically when the following requirements are met:
●
The value true is specified in the configuration property encodingActive.
●
Strings are used for communication.
I
334
If the Java program is to receive the 1-byte EBCDIC data stream
unconverted, byte arrays must be used instead of strings.
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k10
Encoding and national language support
Encoding
Code table OSD_EBCDIC_DF04_DRV
The table below shows the assignment of 1-byte EBCDIC code, printable Unicode
characters, and 2-byte Unicode defined in the code table OSD_EBCDIC_DF04_DRV.
In the following table
●
the x and y axes indicate the relevant 1-byte EBCDIC code
●
the first line in a field indicates the 2-byte Unicode
(leading non-significant bytes are not indicated)
●
the second line in a field indicates the Unicode printing character
Byte - character (Unicode) correspondence
Ļĺ
0_
1_
2_
3_
_A
_B
_C
_D
_E
_F
00
01
_2
02
_3
03
_4
85
…
_5
09
_6
86
†
_7
7F
_8
87 8D
‡
_9
8E
Ž
0B
0C
0D
0E
0F
10
11
12
13
8F
A
8
97
—
18
19
9C 9D
œ
1C
1D
1E
-
1F
80
€
81
82
‚
83
ƒ
84
„
92
’
17
1B
88
ˆ
89
‰
8A
Š
8B
‹
8C
Œ
5
6
7
90
91
‘
16
93
“
94
”
95
•
96
–
4
98
˜
99
™
9A
š
9B
›
14
15
9E 1A
ž
20 A0
E2
â
7C E0
|
à
E1
á
E3
ã
E5
å
E7
ç
F1
ñ
60
`
2E
.
3C
<
28
(
2B
+
0
21
!
24 2A
$
*
29
)
3B AF
;
¯
C7 D1
Ç Ñ
5E
^
2C
,
25
%
5F
_
3E
>
3F
?
CD CE CF CC A8
Í
Î
Ï
Ì
¨
3A
:
23 A7
#
§
27
'
3D
=
22
"
B1
±
F6
ö
5_
26
&
E9 EA EB E8
é
ê
ë
è
ED EE
í
î
EF EC
ï
ì
6_
2D
-
2F
/
C1 C3
Á Ã
C5
Å
© cognitas GmbH 2001-2
_1
7_
F8 C9 CA CB C8
ø
É
Ê
Ë
È
8_
D8
Ø
61
a
62
b
63
c
64
d
65
e
66
f
67
g
68
h
69 AB BB
i
«
»
F0 FD
ð
ý
FE
þ
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
4_
_0
9_
B0 6A
°
j
6B
k
6C 6D
l m
6E
n
6F
o
70
p
71
q
72 AA BA
r
ª
º
E6
æ
C6 A4
Æ
¤
A_
B5
µ
73
s
74
t
76
v
77
w
78
x
79 7A
y
z
B_
A2 A3 A5
¢
£
¥
B7 A9
· ©
40 B6 BC BD BE AC
@
¶ ¼ ½ ¾
¬
C4 D6 DC
Ä
Ö
Ü
B4 D7
´
×
C_
7B
{
41
A
42
B
43
C
44
D
45
E
46
F
47
G
48
H
49 AD
I
F4
ô
F3
ó
F5
õ
D_
7D 4A
}
J
4B
K
4C 4D
L M
4E
N
4F
O
50
P
51
Q
52
R
B9 FB 5D
¹
û
]
F9 FA
ù
ú
FF
ÿ
E_
5C
\
F7
÷
53
S
54
T
55
U
56
V
57
W
58
X
59 5A
Y
Z
B2 D4 DB
²
Ô
Û
D2
Ò
F_
30
0
31
1
32
2
33
3
34
4
35
5
36
6
37
7
38
8
B3
³
FC DA DF
ü
Ú
ß
BeanConnect V2.1
7E
~
C2 A6 C0
Â
¦ À
75
u
39
9
B8
¸
A1 BF D0 DD DE AE
¡
¿
Ð
Ý
Þ ®
5B
[
E4 D9
ä
Ù
F2
ò
D3 D5
Ó Õ
335
Encoding
Encoding and national language support
Character (Unicode) - byte correspondence
Substitute character: 6F
In the following table
●
the x and y axes indicate the relevant 2-byte Unicode
●
the relevant field indicates the associated 1-byte EBCDIC code
Ļĺ
_0
_1
_2
_3
_4
_5
_6
_7
_8
_9
_A _B _C _D _E _F
000_
00
01
02
03
37
2D 2E
2F
16
05
15
0B 0C 0D 0E
0F
001_
10
11
12
13
3C 3D
32
26
18
19
3F
27
1F
002_
40
5A 7F
7B 5B 6C
50
7D 4D 5D 5C 4E 6B
003_
F0
F1
F3
F6
F7
F2
F4
F5
F8
1C 1D 1E
60
4B
61
F9 7A 5E 4C 7E
6E
6F
004_ B5 C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6
336
005_ D7 D8 D9 E2
E3
E4
E5
E6
E7
E8
E9 CC E0 DC 6A 6D
006_ 4A
81
82
83
84
85
86
87
88
89
91
92
93
94
95
96
007_
97
98
99
A2 A3 A4 A5 A6 A7 A8 A9 C0
43
D0 A1
7
008_
20
21
22
23
24
4
6
8
28
29
2A 2B 2C
A
14
009_
30
31
25
33
34
35
36
17
38
39
3A 3B 1A 1B 3E
5F
00A_ 41 AA B0 B1
9F
B2
63
7C
79
B4 9A 8A BA CA AF 5F
9
00B_ 90
8F EA FA BE A0 B6 B3 9D DA 9B 8B B7 B8 B9 AB
00C_ 64
65
62
68
74
71
00D_ AC 69 ED EE EB EF BC BF
80
FC FE EC BD AD AE FF
00E_ 44
45
9C
48
54
51
00F_ 8C
49 CD CE CB CF 4F
E1
70 DD DE DB FD 8D 8E DF
42
66 BB 67
46
FB
47
9E
72
52
73
53
78
58
75
55
76
56
77
57
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k10
Encoding and national language support
Encoding
10.1.2 Standard conversion between EBCDIC code and Unicode for EIS
partners of type CICS
In most cases you do not need to deal with conversion from 1-byte code to Unicode and
vice versa as BeanConnect performs conversion automatically in accordance with the
standard JDK code table Cp1047.
Code conversion takes place automatically when the following requirements are met:
●
The value true is specified in the configuration property encodingActive.
●
Strings are used for communication.
●
The connection URL is of type cics://
I
If the Java program is to receive the 1-byte data stream unconverted, byte arrays must be used instead of strings.
10.1.3 Using other predefined code tables
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
In addition to the standard code table OSD_EBCDIC_DF04_DRV, the following code tables
are also supplied with the product BeanConnect:
●
OSD_EBCDIC_DF03_IRV (only openUTM partners)
●
OSD_EBCDIC_DF04_1 (only openUTM partners)
●
OSD_EBCDIC_DF04_15 (only openUTM partners)
●
code tables of the JVM (openUTM and CICS partners)
BeanConnect supports the code tables provided with the JVM. You will find a list of the JVM
code tables
●
for JDK 1.5 at
http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html
You select the required code table at deployment time as follows:
●
In the configuration property encoding specify the name of the required code table.
You specify a JMV code table with jdk:<jvm-code-table>.
●
Set the configuration property encodingActive to true to activate it.
You select the required code table at runtime as follows:
●
BeanConnect V2.1
In the Java program activate the required code table with the setEncoding() method
of the EISConnection interface or the OltpMessageContext interface.
337
Encoding
Encoding and national language support
I
You can use the Management Console to specify a code table
for an inbound service. This specification overwrites the value
for encoding and sets encodingActive to true, see
Section 6.8.2, "Configuring inbound services".
Example 21 Using predefined code tables
Code table OSD_EBCDIC_DF03_IRV is to be used:
connection.setEncoding(Encoding.getEncoding("OSD_EBCDIC_DF03_IRV"))
JVM code table CP1047 is to be used:
connection.setEncoding(Encoding.getEncoding("jdk:Cp1047"));
connection.setEncodingActive(true);
The other predefined code tables are shown on the following pages.
In all the following Byte - Character (Unicode) Correspondence tables
●
the x and y axes indicate the relevant 1-byte EBCDIC code
●
the first line in a field indicates the 2-byte Unicode
(leading non-significant bytes are not indicated)
●
the second line in a field indicates the Unicode printing character
In all the following Character (Unicode) - Byte Correspondence tables
338
●
the x and y axes indicate the relevant 2-byte Unicode
●
the relevant field indicates the associated 1-byte EBCDIC code
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k10
Encoding and national language support
Code table OSD_EBCDIC_DF03_IRV
The table below shows the assignment of 1-byte EBCDIC code, printable Unicode
characters, and 2-byte Unicode defined in the code table OSD_EBCDIC_DF03_IRV.
Byte - character (Unicode) correspondence
Ļĺ
0_
1_
2_
3_
_1
_2
_3
_4
_5
_6
00
01
02
03 FFFD
09 FFFD
10
11
12
13 FFFD
0A
FFFD FFFD FFFD FFFD FFFD FFFD
FFFD FFFD
_7
16 FFFD FFFD FFFD FFFD
_9
_A
_B
_C
_D
_E
_F
0B
0C
0D
0E
0F
19 FFFD FFFD
1C
1D
1E
-
1F
1B FFFD FFFD FFFD FFFD FFFD
05
06
07
04 FFFD FFFD FFFD FFFD
14
15 FFFD
1A
7C
|
08 FFFD
17
_8
7F FFFD FFFD FFFD
18
60
`
2E
.
3C
<
28
(
2B
+
5_
26 FFFD FFFD FFFD FFFD FFFD FFFD FFFD FFFD FFFD
&
21
!
24
$
2A
*
29
)
3B FFFD
;
6_
2D
-
2F FFFD FFFD FFFD FFFD FFFD FFFD FFFD FFFD
/
5E
^
2C
,
25
%
5F
_
3E
>
3F
?
FFFD FFFD FFFD FFFD FFFD FFFD FFFD FFFD FFFD FFFD
3A
:
23
#
40
@
27
'
3D
=
22
"
7_
8_
9_
A_
© cognitas GmbH 2001-2
_0
20 FFFD FFFD FFFD FFFD FFFD FFFD FFFD FFFD FFFD
4_
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
Encoding
B_
C_
D_
E_
F_
BeanConnect V2.1
FFFD
61
a
62
b
63
c
64
d
65
e
66
f
67
g
68
h
69 FFFD FFFD FFFD FFFD FFFD FFFD
i
FFFD
6A
j
6B
k
6C
l
6D
m
6E
n
6F
o
70
p
71
q
72 FFFD FFFD FFFD FFFD FFFD FFFD
r
FFFD FFFD
73
s
74
t
75
u
76
v
77
w
78
x
79
y
7A FFFD FFFD FFFD FFFD FFFD FFFD
z
FFFD FFFD FFFD FFFD FFFD FFFD FFFD FFFD FFFD FFFD FFFD
5B
[
5C
\
5D FFFD FFFD
]
FFFD
41
A
42
B
43
C
44
D
45
E
46
F
47
G
48
H
49 FFFD FFFD FFFD FFFD FFFD FFFD
I
FFFD
4A
J
4B
K
4C
L
4D
M
4E
N
4F
O
50
P
51
Q
52 FFFD FFFD FFFD FFFD FFFD FFFD
R
FFFD FFFD
53
S
54
T
55
U
56
V
57
W
58
X
59
Y
5A FFFD FFFD FFFD FFFD FFFD FFFD
Z
32
2
33
3
34
4
35
5
36
6
37
7
38
8
39 FFFD
9
30
0
31
1
7B FFFD
{
7D FFFD
}
7E
~
339
Encoding
Encoding and national language support
Character (Unicode) - byte correspondence
Substitute character: 6F
Ļ ĺ _0 _1 _2 _3 _4 _5 _6 _7 _8 _9 _A _B _C _D _E _F
000_ 00 01 02 03 37 2D 2E 2F 16 05 15 0B 0C 0D 0E 0F
001_ 10 11 12 13 3C 3D 32 26 18 19 3F 27 1C 1D 1E 1F
002_ 40 5A 7F 7B 5B 6C 50 7D 4D 5D 5C 4E 6B 60 4B 61
003_ F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 7A 5E 4C 7E 6E 6F
004_ 7C C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6
005_ D7 D8 D9 E2 E3 E4 E5 E6 E7 E8 E9 BB BC BD 6A 6D
006_ 4A 81 82 83 84 85 86 87 88 89 91 92 93 94 95 96
007_ 97 98 99 A2 A3 A4 A5 A6 A7 A8 A9 FB 4F FD FF 07
008_ 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F
009_ 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F
00A_ 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F
00B_ 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F
00C_ 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F
00D_ 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F
00E_ 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F
00F_ 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F 6F
340
BeanConnect V2.1
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k10
Encoding and national language support
Encoding
Code table OSD_EBCDIC_DF04_1
The table below shows the assignment of 1-byte EBCDIC code, printable Unicode
characters, and 2-byte Unicode defined in the code table OSD_EBCDIC_DF04_1.
Byte - character (Unicode) correspondence
Ļ ĺ _0
_A
_B
_C _D
_E
_F
0_
00
_1
01
02
03
85
…
09
86
†
7F
87 8D
‡
8E
Ž
0B
0C
0D
0E
0F
1_
10
11
12
13
8F
A
8
97
—
18
19
9C 9D
œ
1C
1D
1E
-
1F
2_
80
€
81
82
‚
83
ƒ
84
„
92
’
17 1B
88
ˆ
89
‰
8A
Š
8B
‹
8C
Œ
05
06
07
3_
90
91
‘
16
93
“
94
”
95
•
96
–
4
98
˜
99
™
9A
š
9B
›
14
15
9E 1A
ž
4_
20 A0
E2
â
E4 E0
ä
à
E1
á
E3
ã
E5
å
E7
ç
F1
ñ
60
`
2E
.
3C
<
28
(
2B 7C
+
|
5_
26
&
E9 EA EB E8
é
ê
ë
è
ED EE EF EC DF
í
î
ï
ì
ß
21
!
24 2A
$
*
29
)
3B
;
9F
Ÿ
6_
2D
-
2F
/
C1 C3 C5
Á Ã Å
C7 D1
Ç Ñ
5E
^
2C
,
25
%
5F
_
3E
>
3F
?
7_
F8 C9 CA CB C8
ø
É
Ê
Ë È
CD CE CF CC A8
Í
Î
Ï
Ì
¨
3A
:
23
#
40
@
27
'
3D
=
22
"
8_
D8
Ø
9_
_3
_4
C2 C4 C0
Â Ä À
_7
_8
_9
66
f
67
g
68
h
69 AB BB
i
«
»
F0 FD
ð
ý
FE B1
þ
±
B0 6A
°
j
6B 6C 6D
k
l m
6E
n
6F
o
70
p
71
q
72 AA BA
r
ª
º
E6
æ
C6 A4
Æ
¤
A_
B5 AF
µ
¯
73
s
76
v
77
w
78
x
79 7A
y
z
B_
A2 A3 A5 B7 A9
¢
£
¥
· ©
A7 B6 BC BD BE AC
§
¶ ¼ ½ ¾
¬
5B
[
5C
\
5D
]
B4 D7
´
×
C_
F9
ù
44
D
45
E
46
F
47
G
48
H
49 AD
I
F4
ô
F6
ö
F2
ò
F3
ó
F5
õ
D_
A6 4A
¦
J
4B 4C 4D
K
L M
4E
N
4F
O
50
P
51
Q
52
R
B9 FB FC DB FA
¹
û
ü
Û
ú
FF
ÿ
E_
D9
Ù
F7
÷
53
S
54
T
55
U
56
V
57
W
58
X
59 5A
Y
Z
B2 D4 D6
² Ô Ö
D2
Ò
F_
30
0
31
1
32
2
33
3
34
4
35
5
36
6
37
7
38
8
B3
³
7D DA
}
Ú
42
B
63
c
_6
65
e
41
A
62
b
_5
64
d
BeanConnect V2.1
61
a
_2
74
t
43
C
75
u
39
9
B8
¸
A1 BF D0 DD DE AE
¡
¿ Ð
Ý
Þ ®
7B DC
{ Ü
D3 D5
Ó Õ
7E
~
341
Encoding
Encoding and national language support
Character (Unicode) - byte correspondence
Substitute character: 6F
Ļ ĺ _0 _1 _2 _3 _4 _5 _6 _7 _8 _9 _A _B _C _D _E _F
000_
00 01 02 03 37 2D 2E 2F 16 05 15 0B 0C 0D 0E 0F
001_
10 11 12 13 3C 3D 32 26 18 19 3F 27 1C 1D 1E 1F
002_
40 5A 7F 7B 5B 6C 50 7D 4D 5D 5C 4E 6B 60 4B 61
003_
F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 7A 5E 4C 7E 6E 6F
004_ 7C C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6
005_ D7 D8 D9 E2 E3 E4 E5 E6 E7 E8 E9 BB BC BD 6A 6D
006_ 4A 81 82 83 84 85 86 87 88 89 91 92 93 94 95 96
007_
97 98 99 A2 A3 A4 A5 A6 A7 A8 A9 FB 4F FD FF
008_
20 21 22 23 24
009_
30 31 25 33 34 35 36 17 38 39 3A 3B 1A 1B 3E 5F
4
6
8 28 29 2A 2B 2C
9
7
A 14
00A_ 41 AA B0 B1 9F B2 D0 B5 79 B4 9A 8A BA CA AF A1
00B_ 90 8F EA FA BE A0 B6 B3 9D DA 9B 8B B7 B8 B9 AB
00C_ 64 65 62 66 63 67 9E 68 74 71 72 73 78 75 76 77
00D_ AC 69 ED EE EB EF EC BF 80 E0 FE DD FC AD AE 59
00E_ 44 45 42 46 43 47 9C 48 54 51 52 53 58 55 56 57
00F_ 8C 49 CD CE CB CF CC E1 70 C0 DE DB DC 8D 8E DF
342
BeanConnect V2.1
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k10
Encoding and national language support
Encoding
Code table OSD_EBCDIC_DF04_15
The table below shows the assignment of 1-byte EBCDIC code, printable Unicode
characters, and 2-byte Unicode defined in the code table OSD_EBCDIC_DF04_15.
Byte - character (Unicode) correspondence
Ļ ĺ _0
_1
_2
_3 _4
00 01
02
03 85
…
_5
09 86
†
_6
_7
7F
_8
87 8D
‡
_9
10 11
12
13 8F
A
8
97
—
2_
80 81
€
82
‚
83 84
ƒ
„
92 17
’
3_
90 91
‘
16
93 94
“
”
4_
_A _B _C _D
_E
_F
8E 0B 0C
Ž
0D
0E
0F
18
19 9C 9D 1C
œ
1D
1E
-
1F
1B
88
ˆ
89 8A 8B 8C
‰
Š
‹ Œ
5
6
7
95 96
• –
4
98
˜
99 9A 9B
™
š
›
14
15
9E
ž
1A
20 A0 E2 E4 E0
â
ä
à
E1 E3
á
ã
E5
å
E7
ç
F1
ñ
60 2E 3C
`
.
<
28
(
2B
+
7C
|
5_
26 E9 EA EB E8
&
é
ê
ë
è
ED EE EF EC DF
í
î
ï
ì
ß
21
!
29
)
3B
;
9F
Ÿ
6_
2D 2F C2 C4 C0
/ Â Ä À
C1 C3 C5
Á Ã Å
5E 2C
^
,
25
%
5F
_
3E
>
3F
?
7_
F8 C9 CA CB C8
ø É Ê Ë È
CD CE CF CC 161 3A
Í
Î
Ï
Ì
š
:
40
@
27
'
3D
=
22
"
8_
D8 61
Ø
a
63 64
c d
65 66
e
f
67
g
68
h
69 AB BB
i
«
»
F0 FD
ð
ý
FE
þ
B1
±
9_
B0 6A 6B 6C 6D
°
j
k
l m
6E 6F
n o
70
p
71
q
72 AA BA E6 17E
r
ª
º æ
ž
A_
B5 AF
µ ¯
76 77
v w
78
x
79 7A A1 BF D0 DD
y
z
¡
¿ Ð
Ý
B_
A2 A3 A5 B7 A9
¢ £
¥
· ©
C_
F9 41
ù A
0_
1_
62
b
C6 20AC
Æ
€
AE
®
A7 B6 152 153 178 AC 5B 5C
§
¶ Œ œ Ÿ
¬
[
\
5D 17D
]
Ž
D7
×
43 44
C D
45 46
E F
47
G
48
H
49 AD
I
F2
ò
F3
ó
F5
õ
D_
160 4A 4B 4C 4D
Š
J K L M
4E 4F
N O
50
P
51
Q
52 B9 FB FC DB
R
¹
û
ü
Û
FA
ú
FF
ÿ
E_
D9 F7
Ù ÷
53
S
54 55
T U
56 57
V W
58
X
59 5A B2 D4 D6
Y
Z
² Ô Ö
D2
Ò
D3
Ó
D5
Õ
F_
30 31
0 1
32
2
33 34
3 4
35 36
5 6
37
7
38
8
7D DA
}
Ú
7E
~
42
B
74 75
t u
23
#
DE
Þ
BeanConnect V2.1
73
s
C7 D1
Ç Ñ
24 2A
$
*
F4
ô
F6
ö
39 B3 7B DC
9
³
{ Ü
343
Encoding
Encoding and national language support
Character (Unicode) - byte correspondence
Substitute character: 6F
Ļĺ
_0
_1
_2
_3
000_
00
01
02
001_
10
11
12
002_
40
5A
7F
_4
_5
_6
_7
_8
_9
_A
_B
_C
_D
_E
_F
03
37
2D
2E
2F
16
13
3C
3D
32
26
18
05
15
0B
0C
0D
0E
0F
19
3F
27
1C
1D
1E
1F
7B
5B
6C
50
7D 4D 5D
5C
4E
6B
60
4B
61
003_
F0
F1
F2
F3
F4
F5
F6
F7
F8
F9
7A
5E
4C
7E
6E
6F
004_
7C
C1
C2
C3
C4
C5
C6
C7
C8
C9
D1
D2
D3
D4
D5
D6
005_ D7
D8
D9
E2
E3
E4
E5
E6
E7
E8
E9
BB BC BD 6A
6D
006_ 4A
81
82
83
84
85
86
87
88
89
91
92
96
007_
97
98
99
A2 A3 A4 A5 A6 A7 A8
A9
008_
20
21
22
23
24
4
6
8
28
29
2A
009_
30
31
25
33
34
35
36
17
38
39
00A_ 41
AA B0
B1
9F
B2
D0
B5
79
B4
00B_ 90
8F
EA FA BE A0
B6
B3 9D DA 9B
8B
B7
B8
B9 AB
00C_ 64
65
62
9E
68
74
71
72
73
78
75
76
77
00D_ AC
69
ED EE EB EF EC BF
80
E0
FE DD FC AD AE
59
52
66
46
63
43
67
47
9C
93
94
95
FB
4F
FD
FF
7
2B
2C
9
A
14
3A
3B
1A
1B
3E
5F
9A
8A BA CA AF A1
00E_ 44
45
42
48
54
51
55
56
57
00F_ 8C
49
CD CE CB CF CC E1
70
C0 DE DB DC 8D
53
58
8E
DF
Results for entries > 0x00FF
Zeichen (in) Byte (out)
344
152
Œ
B7
153
œ
B8
160
Š
D0
161
š
79
178
Ÿ
B9
17D
Ž
BE
17E
ž
9D
20AC
€
9F
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k10
Encoding and national language support
Encoding
10.1.4 Using custom charsets
This is the preferred method for using new custom charsets.
You can create your own code tables for use in the JVM and activate them by applying the
procedure described in section "Using other predefined code tables". Instead of a
predefined JDK code table name, use your own code table name with the syntax jdk:<my_
code_table>.
A detailed description on how to implement and deploy your own code tables in the Java
runtime environment can be found in the Java documentation at
http://java.sun.com/j2se/1.5.0/docs/api/java/nio/charset/
package-summary.html
and in the BeanConnect Javadoc for the package net.fsc.beanta.encoding.
A Java sample code is present in the BeanConnect delivery scope in the package
net.fsc.beanconnect.encoding.sample.
In order to use your own code tables, you have to place the classes in the directory
<JDK>/jre/lib/ext.
10.1.5 Creating and using legacy code tables
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Note: The preferred method for using custom charsets is described in the section "Using
custom charsets" above.
If the predefined code tables do not satisfy your requirements, you can create code tables
of your own. A Java sample source for a user-defined code table is supplied with the
product. You will find this example in the Javadoc for the package
net.fsc.beanta.encoding in the Encoding.CustomEncoder class.
To avoid problems with the class loaders when using the classes of these own code tables,
you should place these classes in the directory <J2EE_HOME>/applib of the application (in
case of the Oracle Application Server).
You select the required code table at deployment time as follows:
●
In the configuration property encoding, specify the name of the required code table
using custom:<my-code-table>.
●
Set the configuration property encodingActive to true to activate it.
BeanConnect V2.1
345
Encoding
Encoding and national language support
You select the required code table at runtime as follows:
●
In the Java program activate the required code table with the setEncoding() method
of the EISConnection or the OltpMessageContext interface as follows:
OwnTable myTable = new OwnTable();
connection.setEncoding(new Encoding.CustomEncoder(myTable));
connection.setEncodingActive(true);
I
For compatibility reasons, not only the procedure described for using
customer-defined code tables is supported, but also the following
procedure for utilizing user-defined code tables in which conversion
is implemented with two Java programs:
OwnTable_ByteToChar myTableByteToChar = new
OwnTable_ByteToChar();
OwnTable_CharToByte myTableCharToByte = new
OwnTable_CharToByte();
setEncoding(new Encoding.Custom(myTableByteToChar,
myTableCharToByte)
);
These code tables only support 1-byte encoding. This means that the encoding source and
destination for one char can only be one byte. If you need 2-byte code tables, we
recommend the use of a custom charset which provides all options of code conversion.
346
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k10
National language support and encoding
National language support
10.2 National language support for message output
BeanConnect permits internationalization and localization of the messages of the
BeanConnect resource adapter, the BeanConnect proxy and the BeanConnect
Management Console. Internationalization and localization means that the messages that
a component passes to the users or writes to log files are output correctly for the relevant
environment (country, language).
For this, Java offers classes which provide support for internationalization (such as the
class Locale). To determine the language in which messages are to be output, there are
two criteria in BeanConnect:
●
language (for example en)
●
region (for example US)
The language code is defined as per ISO-639. The possible values for the region are
described in ISO-3166.
By default, BeanConnect supplies messages for the language en and the region US. If the
user does not make any explicit selection, the default values apply as specified by the
current JVM (Default-Locale).
BeanConnect provides two methods of changing these default settings:
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
●
●
On starting a Java program, set the locale by defining the following two system
properties:
–
net.fsc.tpbasics.i18n.defaultCountry and
–
net.fsc.tpbasics.i18n.defaultLanguage
Store the required settings in the file beanconnect_i18n.properties, which must be
accessible in the class path of the relevant JVM.
BeanConnect first tries to determine the settings using the system properties. If no system
properties have been defined, the system searches for the property file and reads the
settings from there. The standard method should be to set the locale in
beanconnect_i18n.properties.
BeanConnect V2.1
347
National language support
National language support and encoding
Default configuration
A JAR file (BeanConnectI18N.jar) is deployed with the installation of the BeanConnect
resource adapter, the BeanConnect proxy or the BeanConnect Management Console. This
file must be entered in the class path of the JVM. By default, this file has the following
contents:
●
beanconnect_i18n.properties for setting the locale
●
the message files for the individual components (default language: en, US)
●
a number of Java classes (Msg…class) which must remain unchanged in the JAR file.
To allow access to the message files, their names must follow a certain pattern.
Several message files with the name <component>.properties are included. These files
act as a fallback and are used if you have given incorrect values for the language and
region. The currently used message files are:
Resource adapter
basics.properties
stub.properties
proxy.properties
ui.properties
oltpmsg.properties
jconnect.properties
encoding.properties
Proxy
proxy.properties
oltpmsg.properties
Management Console
mc.properties
tpbasics.properties
In addition, a file <component>_en_US.properties can be contained in the JAR file. This
is generally an identical copy of the file <component>.properties, since en_US is the
default value for BeanConnect message files.
Examples of file names:
348
●
proxy.properties
●
proxy_de.properties
●
proxy_en_US.properties
●
proxy_fr_FR.properties
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k10
National language support and encoding
National language support
Introducing a new language
You can provide support for other languages by adding message files to the JAR file
BeanConnectI18N.jar. These message files are text files and can be edited with a text
editor (such as notepad, vi).
The following example shows the steps necessary for support of German messages.
1. Extract the default message file (for example proxy.properties) from the JAR file
using the command jar or the program WinZip.
2. Translate the messages into German.
3. Store the new message file with the name proxy_de_DE.properties and add it to the
JAR file under the same path (net.fsc.tpbasic.i18n.r) as the default file.
4. Extract the file beanconnect_i18n.properties.
5. Enter de as the language and DE as the country:
net.fsc.tpbasics.i18n.defaultLanguage=de
net.fsc.tpbasics.i18n.defaultCountry=DE
6. Write the file beanconnect_i18n.properties back to the JAR file.
Apply step 1 to 3 to all the other message files (stub.properties, ui.properties, etc.).
For the BeanConnect proxy and the BeanConnect Management Console the
BeanConnectI18N.jar file must be edited in the BeanConnect home directory
<BC_home>/lib.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
When switching to a new language, note that BeanConnectI18N.jar must be edited for
the BeanConnect resource adapter in the file BeanConnect.rar if the connector is to be
redeployed. Otherwise, you can initialize the new language environment simply by means
of changing the file /j2ee/home/connectors/<connector_name>/
<connector_name>/BeanConnectI18N.jar.
BeanConnect V2.1
349
National language support
350
National language support and encoding
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k11
June 8, 2009 7:06 pm
11 BPEL support
The Business Process Execution Language (BPEL) is an XML-based language for the
description of business processes whose individual actions are implemented via web
services.
BeanConnect supports Oracle BPEL. As a result, the BeanConnect adapter can be used
as a partner link in a BPEL process.
This chapter contains information on the following topics:
●
Function scope of BeanConnect BPEL
●
Deploying the BeanConnect resource adapter in the BPEL environment
●
Creating a BPEL process
●
BPEL WSDL generator
The Oracle SOA Suite is based on BPEL V1.1, WSDL V1.1 (Web Service Definition
Language)) and WSIF (Web Service Invocation Framework).
Dokuschablonen fr DARB XML in FSC-Layout Version 1.0 fr FrameMaker ab Version 7 vom 19.05.2005
cognitas GmbH 2001-2005
In order to support BPEL, the Oracle SOA Suite uses the BPEL Designer as development
environment and the BPEL Process Manager as runtime environment.
BeanConnect V2.1
351
Function scope of BeanConnect BPEL
BPEL support
11.1 Function scope of BeanConnect BPEL
BeanConnect BPEL provides the following detailed functionality:
●
Outbound communication with openUTM partners via OSI-TP (synchronous and
asynchronous)
●
Outbound communication with CICS partners via LU6.2 (synchronous and
asynchronous)
●
Outbound communication with openUTM partners via the UPIC protocol
The present version supports only single-step conversations.
The BeanConnect resource adapter provides two additional resource types to implement
these functions:
●
net.fsc.jca.bpel.xml.BpelBCOltpConnectionFactory
This connection factory is used for communications with openUTM and CICS partners
via OSI-TP / LU6.2.
●
net.fsc.jca.bpel.xml.BpelBCUpicConnectionFactory
This connection factory is used for communications with openUTM partners via the
UPIC protocol. It corresponds to the connection factory
net.fsc.jca.communication.cci.BCUpicConnectionFactory
These connection factories correspond to the CCI interfaces for outbound communication
net.fsc.jca.communication.cci.BCOltpConnectionFactory (OSI-TP / LU6.2) and
net.fsc.jca.communication.cci.BCUpicConnectionFactory (UPIC protocol),
see also "Common Client Interface (CCI) for outbound communication".
352
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k11
BPEL support
Deploying resource adapter
11.2 Deploying the BeanConnect resource adapter in the BPEL
environment
A BPEL process run is controlled by the BPEL Process Manager. This is a Java Enterprise
Application which is deployed in an Oracle Application Server. For this reason, you must
deploy the BeanConnect resource adapter in the application server by adapting the
OC4J-specific descriptor for the resource adapter (oc4j-ra.xml).
June 8, 2009 7:06 pm
I
You configure the connection-specific properties in oc4j-ra.xml in the same way
as when operating without BPEL, see Chapter 4.3.1, "Defining connection-specific
properties for OSI-TP / LU6.2 in oc4j-ra.xml" and Chapter 4.4.1, "Defining
connection-specific properties for UPIC in oc4j-ra.xml".
Proceed as follows:
1. Exit the Oracle Application Server
2. Use an editor to insert the following lines in oc4j-ra.xml:
<imported-shared-libraries>
<import-shared-library name="oracle.bpel.common"/>
<import-shared-library name="oracle.xml"/>
</imported-shared-libraries>
The BPEL-specific connection factories are now available.
Dokuschablonen fr DARB XML in FSC-Layout Version 1.0 fr FrameMaker ab Version 7 vom 19.05.2005
cognitas GmbH 2001-2005
Below you will find two sample oc4j-ra.xml files for communication via both
OSI-TP / LU6.2 and UPIC.
Example 22 oc4j-ra.xml in the BPEL environment (OSI-TP / LU6.2)
<connector-factory location="eis/bpelOltpMCF" connector-name="BeanConnect V2.1 JCA1.5
Connector">
<config-property name="connectionURL" value="utm://COBSOA"/>1
<config-property name="encoding" value="default"/>
<config-property name="encodingActive" value="false"/>
<config-property name="transactional" value="true"/>
<config-property name="timeout" value="300000"/>
<config-property name="bufferedIO" value="true"/>
<config-property name="logLevel" value="NONE"/>
<config-property name="displayName" value="BPEL OLTP MCF"/>
<connection-pooling use="private">
<property name="waitTimeout" value="300" />
<property name="scheme" value="fixed_wait" />
1
For CICS partner: cics://COBSOA
BeanConnect V2.1
353
Deploying resource adapter
BPEL support
<property name="maxConnections" value="50" />
<property name="minConnections" value="0" />
</connection-pooling>
<security-config use="principal-mapping-entries">
<principal-mapping-entries>
<default-mapping>
<res-user>USERADM</res-user>
<res-password>USERADM</res-password>
</default-mapping>
</principal-mapping-entries>
</security-config>
<connectionfactoryinterface>
net.fsc.jca.beanconnect.bpel.xml.BpelBCOltpConnectionFactory
</connectionfactory-interface>
</connector-factory>
Example 23 oc4j-ra.xml in the BPEL environment (UPIC)
<connector-factory location="eis/bpelUpicMCF" connector-name="BeanConnect V2.1 JCA1.5
Connector">
<config-property name="connectionURL"value="upic://mch0001x:28001/maro53"/>
<config-property name="encoding" value="default"/>
<config-property name="encodingActive" value="false"/>
<config-property name="timeout" value="30000"/>
<config-property name="logLevel" value="NONE"/>
<config-property name="displayName" value="BPEL UPIC MCF for maro53"/>
<connection-pooling use="private">
<property name="waitTimeout" value="300" />
<property name="scheme" value="fixed_wait" />
<property name="maxConnections" value="50" />
<property name="minConnections" value="0" />
</connection-pooling>
<security-config use="principal-mapping-entries">
<principal-mapping-entries>
<default-mapping>
<res-user>USERADM</res-user>
<res-password>USERADM</res-password>
</default-mapping>
</principal-mapping-entries>
</security-config>
<connectionfactoryinterface>
net.fsc.jca.beanconnect.bpel.xml.BpelBCUpicConnectionFactory
</connectionfactory-interface>
</connector-factory>
354
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k11
BPEL support
Creating a BPEL process
11.3 Creating a BPEL process
You use the BPEL Designer to create BPEL processes. The BPEL Designer runs as a
plug-in in JDeveloper.
In JDeveloper, it is possible both to develop BPEL processes and deploy them directly in
the required BPEL Process Manager.
11.3.1 Configuring connections
You must use JDeveloper's graphical user interface to configure an application server
connection and an integration server connection.
Configuring an application server connection
To do this in the GUI, choose the New Application Server Connection... command from
the context menu under Application Server and proceed as follows:
1. Enter the Connection Name and Connection Type (Oracle Application Server
10g10.1.3).
2. Enter the user name and password. When you do this, make sure that Deploy
Password is active.
3. Enter the name and address data of the Oracle Application Server (Host Name, OC4J
Instance Name, OPMN Port).
Dokuschablonen fr DARB XML in FSC-Layout Version 1.0 fr FrameMaker ab Version 7 vom 19.05.2005
cognitas GmbH 2001-2005
4. Finally check whether the connection is established.
Configuring an integration server connection
To do this in the GUI, choose the New Integration Server Connection... command from
the context menu under Integration Server and proceed as follows:
1. Enter the Connection Name (freely definable name for the integration server
connection).
2. Under Application Server, enter the Connection Name that you specified for
Application Server Connection. Enter the host name of the computer on which the
Oracle Application Server is running as well as the HTTP port of the Oracle Application
Server.
3. Finally check whether the connection is established.
For more detailed information, see the manual "Oracle® BPEL Process Manager Installation Guide".
BeanConnect V2.1
355
Creating a BPEL process
BPEL support
11.3.2 Creating a BPEL project and modeling a BPEL process
In JDeveloper, define a new BPEL project (BPEL Process Project) and then proceed as
follows:
1. Specify the process name and the name space. At runtime, the BPEL Process Manager
calls the BPEL process under the name specified here. Choose whether the process
(i.e. the communication with the EIS partner) is to run synchronously or asynchronously.
2. Assign a schema for the input and output messages in Input Schema Element and
Output Schema Element respectively. These schemas describe the data format.
After this step, the BPEL Designer is opened.
3. Use the BPEL Designer to model the BPEL process, see example. When performing
modeling, you should also specify a partner link, see example. You must create a WSDL
file for this partner link, see Chapter 11.3.2.3, "Creating a WSDL file".
11.3.2.1
Deploying the BPEL process
You deploy a BPEL process via the JDeveloper. To do this, specify the Connection Name
which you defined under Integration Server Connection.
11.3.2.2
Example: Modeling a BPEL process for an openUTM service
The following diagram provides an outline view of a BPEL process which calls (invokes) a
service with the service name COBSOA in a UTM partner application. The partner link is
also named COBSOA. This operation makes use of the activities assign, invoke, receive
and reply.
356
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k11
BPEL support
Creating a BPEL process
Figure 62: Calling (Invoking) an openUTM service as a Partner Link for a BPEL process
receiveInput
June 8, 2009 7:06 pm
AssignCobSoaRequestData
client
InvokeCOBSOA
COBSOA
AssignCobSoaResponseData
replyOutput
11.3.2.3
Creating a WSDL file
Dokuschablonen fr DARB XML in FSC-Layout Version 1.0 fr FrameMaker ab Version 7 vom 19.05.2005
cognitas GmbH 2001-2005
You must create a WSDL file for a PartnerLink. You can do this using the tool BPEL WSDL
Generator which is supplied with BeanConnect, see Section 11.4, "BPEL WSDL
generator".
The following file named bcCOBSOA.wsdl can be used for the example above:
Example 24 WSDL file
<?xml version="1.0" encoding="UTF-8"?>
<definitions
name="CobSoa"
targetNamespace="http://xmlns.fsc.net/adapter/beanconnect/CobSoa"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:tns="http://xmlns.fsc.net/adapter/beanconnect/CobSoa"
xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
xmlns:jca="http://xmlns.oracle.com/pcbpel/wsdl/jca/"
xmlns:pc="http://xmlns.oracle.com/pcbpel/"
xmlns:impReq="http://beanconnect.fsc.net/COBSOA_REQUEST"
xmlns:impRes="http://beanconnect.fsc.net/COBSOA_RESPONSE"
xmlns:hdr="http://xmlns.fsc.net/adapter/beanconnect/"
xmlns="http://schemas.xmlsoap.org/wsdl/">
BeanConnect V2.1
357
Creating a BPEL process
BPEL support
<types>
<schema xmlns="http://www.w3.org/2001/XMLSchema">
<import namespace="http://beanconnect.fsc.net/COBSOA_REQUEST"
schemaLocation="COBSOAIN.xsd"/>
</schema>
<schema xmlns="http://www.w3.org/2001/XMLSchema">
<import namespace="http://beanconnect.fsc.net/COBSOA_RESPONSE"
schemaLocation="COBSOAOUT.xsd"/>
</schema>
</types>
<message name="CobSoa_Request">
<part name="Root-Element" element="impReq:Root-Element"/>
</message>
<message name="CobSoa_Response">
<part name="Root-Element" element="impRes:Root-Element"/>
</message>
<portType name="CobSoa_ptt">
<operation name="CobSoa">
<input message="tns:CobSoa_Request"/>
<output message="tns:CobSoa_Response"/>
</operation>
</portType>
<binding name="CobSoa_binding" type="tns:CobSoa_ptt">
<jca:binding />
<operation name="CobSoa">
<jca:operation
InteractionSpec="net.fsc.jca.beanconnect.bpel.BpelBCCciInteractionSpec"
xmlFormat="nfb"
serviceName="COBSOA"/>
<input>
<jca:header message="CobSoa_Request" part="Root-Element"/>
</input>
<output>
<jca:header message="CobSoa_Response" part="Root-Element"/>
</output>
</operation>
</binding>
<service name="CobSoa">
<port name="CobSoa_pt" binding="tns:CobSoa_binding">
<jca:address adapterInstanceJndi="eis/bpelUpicMCF"/>
</port>
</service>
<plt:partnerLinkType name="CobSoa_plt">
<plt:role name="CobSoa_role">
<plt:portType name="tns:CobSoa_ptt"/>
</plt:role>
</plt:partnerLinkType>
</definitions>
358
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k11
BPEL support
Creating a BPEL process
The above example makes use of the UPIC connection factory with the JNDI name
eis/bpelUpicMCF .
The associated InteractionSpec is used for the CCI API:
InteractionSpec net.fsc.jca.beanconnect.bpel.BpelBCCciInteractionSpec
The Oracle Native Format Builder (xmlFormat="nfb") is used to convert the XML data into
binary data. The employed openUTM service name (=TAC name) is COBSOA (serviceName="COBSOA").
InteractionSpecs and their attributes
A total of three InteractionSpecs can be used in the BPEL environment:
●
net.fsc.jca.beanconnect.bpel.BpelBCCciInteractionSpec
Communication with an openUTM partner using the UPIC protocol
●
net.fsc.jca.beanconnect.bpel.BpelBCOltpCciInteractionSpecAsync
Asynchronous communication with an openUTM or CICS partner via OSI-TP / LU6.2
●
net.fsc.jca.beanconnect.bpel.BpelBCOltpCciInteractionSpecDialog
Synchronous communication with an openUTM or CICS partner via OSI-TP / LU6.2
xmlFormat="nfb"
XML documents are converted to binary data using the Oracle Native
Format Builder before being sent to the openUTM-/CICS application. The
binary response data is converted to an XML document by the Oracle
Native Format Builder for further processing in the BPEL process.
xmlFormat="xml"
The XML document is passed to the openUTM / CICS application as an
XML string. An XML string is expected as a response. This is converted to
an XML document for further processing in the BPEL process.
serviceName
Name of the openUTM / CICS service that is to be called
Dokuschablonen fr DARB XML in FSC-Layout Version 1.0 fr FrameMaker ab Version 7 vom 19.05.2005
cognitas GmbH 2001-2005
Each of these InteractionSpecs supports the following attributes:
BeanConnect V2.1
359
Creating a BPEL process
11.3.2.4
BPEL support
Generated schemas
In the above example, the Oracle Native Format Builder is used to convert between XML
documents and binary data. In this case, the input data for the TAC COBSOA is described by
the schema COBSOAIN.xsd and the output data is described by the schema
COBSOAOUT.xsd. The following two attributes in the schemas are of relevance for the
different target platforms:
nxsd:encoding
nxsd:encoding="Cp273" : UTM BS2000
nxsd:encoding="ASCII" : UTM Linux/Solaris/Windows
nxsd:encoding="Cp1047" : CICS
nxsd:byteOrder
nxsd:byteOrder="bigEndian"
: Mainframe, Solaris SPARC
nxsd:byteOrder="littleEndian" : Intel architecture
Below, you can see the file generated by the Oracle Native Format Builder COBSOAIN.xsd:
Example 25 xsd file COBSOAIN.xsd
<?xml version="1.0" encoding="UTF-8" ?>
<!--Native format was generated from COBOL copybook :
D:DevelopmentBPELOraBetaTestCOBSOAIN.cpy-->
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd"
xmlns:extn="http://xmlns.oracle.com/pcbpel/nxsd/extensions"
targetNamespace="http://beanconnect.fsc.net/COBSOA_REQUEST"
xmlns:tns="http://beanconnect.fsc.net/COBSOA_REQUEST"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
nxsd:version="NXSD"
nxsd:encoding="ASCII"
nxsd:byteOrder="bigEndian"
nxsd:stream="chars">
<xsd:element name="Root-Element">
<xsd:complexType>
<xsd:sequence>
<!--COBOL declaration : 01 MGET-MSG-->
<xsd:element name="MGET-MSG" minOccurs="1"
maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<!--COBOL declaration : 03 ACCOUNT-DATA-->
<xsd:element name="ACCOUNT-DATA">
<xsd:complexType>
360
BeanConnect V2.1
Dokuschablonen fr DARB XML in FSC-Layout Version 1.0 fr FrameMaker ab Version 7 vom 19.05.2005
cognitas GmbH 2001-2005
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k11
BPEL support
Creating a BPEL process
<xsd:sequence>
<!--COBOL declaration : 05 NR PIC X(16)-->
<xsd:element name="NR" type="xsd:string"
nxsd:style="fixedLength"
nxsd:padStyle="tail"
nxsd:paddedBy=" "
nxsd:length="16"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<!--COBOL declaration : 03 HOLDER-DATA-->
<xsd:element name="HOLDER-DATA">
<xsd:complexType>
<xsd:sequence>
<!--COBOL declaration : 05 DAY-OF-BIRTH PICX(8)-->
<xsd:element name="DAY-OF-BIRTH"
type="xsd:string"
nxsd:style="fixedLength"
nxsd:padStyle="tail"
nxsd:paddedBy=" "
nxsd:length="8"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
Below, you can see the file generated by the Oracle Native Format Builder COBSOAOUT.xsd
Example 26 xsd file COBSOAOUT.xsd
<?xml version="1.0" encoding="UTF-8" ?>
<!--Native format was generated from COBOL copybook :
D:DevelopmentBPELOraBetaTestCOBSOAOUT.cpy-->
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd"
xmlns:extn="http://xmlns.oracle.com/pcbpel/nxsd/extensions"
targetNamespace="http://beanconnect.fsc.net/COBSOA_RESPONSE"
xmlns:tns="http://beanconnect.fsc.net/COBSOA_RESPONSE"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
nxsd:version="NXSD"
BeanConnect V2.1
361
Creating a BPEL process
BPEL support
nxsd:encoding="ASCII"
nxsd:byteOrder="bigEndian"
nxsd:stream="bytes">
<xsd:element name="Root-Element">
<xsd:complexType>
<xsd:sequence>
<!--COBOL declaration : 01 MPUT-MSG-->
<xsd:element name="MPUT-MSG" minOccurs="1"
maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<!--COBOL declaration : 03 ACCOUNT-DATA-->
<xsd:element name="ACCOUNT-DATA">
<xsd:complexType>
<xsd:sequence>
<!--COBOL declaration : 05 CARD-COMPANY PIC X(10)-->
<xsd:element name="CARD-COMPANY"
type="xsd:string"
nxsd:style="fixedLength"
nxsd:padStyle="tail"
nxsd:paddedBy=" "
nxsd:length="10"/>
<!--COBOL declaration : 05 CARD-VALID PIC X-->
<xsd:element name="CARD-VALID"
type="xsd:string"
nxsd:style="fixedLength"
nxsd:padStyle="tail"
nxsd:paddedBy=" "
nxsd:length="1"/>
<!--COBOL declaration : 05 AUTHENTICATED PIC X-->
<xsd:element name="AUTHENTICATED"
type="xsd:string"
nxsd:style="fixedLength"
nxsd:padStyle="tail"
nxsd:paddedBy=" "
nxsd:length="1"/>
<!--COBOL declaration : 05 EXPIRY-DATE PIC X(5)-->
<xsd:element name="EXPIRY-DATE"
type="xsd:string"
nxsd:style="fixedLength"
nxsd:padStyle="tail"
nxsd:paddedBy=" "
nxsd:length="5"/>
<!--COBOL declaration : 05 NR PIC X(19)-->
<xsd:element name="NR"
type="xsd:string"
nxsd:style="fixedLength"
nxsd:padStyle="tail"
362
BeanConnect V2.1
Dokuschablonen fr DARB XML in FSC-Layout Version 1.0 fr FrameMaker ab Version 7 vom 19.05.2005
cognitas GmbH 2001-2005
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k11
BPEL support
Creating a BPEL process
nxsd:paddedBy=" "
nxsd:length="19"/>
<!--COBOL declaration : 05 CREDIT PIC S9(10) COMP-5:
Clause could not be correctly converted to a schema type. Please modify
the generated schema to cater to this type.
Refer to the documentation for assistance.-->
<!-- xsd:element name="CREDIT"
type="xsd:string"
nxsd:style="signZoned"
extn:sign="ticked"
extn:picSize="10"
extn:signPosn="tailUpperNibble"/
-->
<xsd:element name="CREDIT"
type="xsd:string"
nxsd:style="integer"
extn:octet="8"
extn:align="0"
extn:sign="ticked"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<!--COBOL declaration : 03 HOLDER-DATA-->
<xsd:element name="HOLDER-DATA">
<xsd:complexType>
<xsd:sequence>
<!--COBOL declaration : 05 HNAME-->
<xsd:element name="HNAME">
<xsd:complexType>
<xsd:sequence>
<!--COBOL declaration : 07 LASTNAME PIC X(80)-->
<xsd:element name="LAST-NAME"
type="xsd:string"
nxsd:style="fixedLength"
nxsd:padStyle="tail"
nxsd:paddedBy=" "
nxsd:length="80"/>
<!--COBOL declaration : 07 FIRSTNAME PIC X(80)-->
<xsd:element name="FIRST-NAME"
type="xsd:string"
nxsd:style="fixedLength"
nxsd:padStyle="tail"
nxsd:paddedBy=" "
nxsd:length="80"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<!--COBOL declaration : 05 ADDRESS-1 PIC X(80)-->
BeanConnect V2.1
363
Creating a BPEL process
BPEL support
<xsd:element name="ADDRESS-1"
type="xsd:string"
nxsd:style="fixedLength"
nxsd:padStyle="tail"
nxsd:paddedBy=" "
nxsd:length="80"/>
<!--COBOL declaration : 05 ADDRESS-2 PIC X(80)-->
<xsd:element name="ADDRESS-2"
type="xsd:string"
nxsd:style="fixedLength"
nxsd:padStyle="tail"
nxsd:paddedBy=" "
nxsd:length="80"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
364
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k11
BPEL support
BPEL WSDL generator
11.4 BPEL WSDL generator
The BPEL WSDL Generator is supplied with BeanConnect and provides a graphical user
interface for the simple generation and administration of WSDL files. This user interface is
similar to the Management Console user interface and possesses the same look & feel.
Installing the BPEL WSDL generator
The BPEL WSDL Generator is supplied as a Java program and is installed in the same way
as the other BeanConnect tools, see Section 3.5, "Installing the BeanConnect tools".
11.4.1 Starting and exiting the BPEL WSDL generator
Starting the BPEL WSDL generator
You start the BPEL WSDL Generator by means of the script startbpelwsdlgen.
Proceed as follows:
1. In Solaris or Linux systems, open a shell, and in Windows systems, open a DOS
command window.
2. Change to the BPEL WSDL Generator's home directory.
3. Call the script as follows:
shsc/startbpelwsdlgen.sh (on Solaris/Linux systems) or
The BPEL WSDL Generator's graphical user interface is started and the main window
BeanConnect BPEL WSDL Generator is displayed.
Exiting the BPEL WSDL generator
To exit the BPEL WSDL Generator, open the File menu and choose Exit.
Dokuschablonen fr DARB XML in FSC-Layout Version 1.0 fr FrameMaker ab Version 7 vom 19.05.2005
cognitas GmbH 2001-2005
shscstartbpelwsdlgen.cmd (on Windows systems)
BeanConnect V2.1
365
BPEL WSDL generator
BPEL support
11.4.2 Online Help system for the BPEL WSDL generator
Starting the online Help system
To start the online Help system for the BPEL WSDL Generator, open the Help menu and
choose Content.
If you want to call context-sensitive help, click the Help button in the corresponding dialog
box or panel or press the F1 key.
Changing the language of the online Help system
BPEL WSDL Generator installation installs both the English and German versions of the
online Help system. A copy of the two versions is written to the installation directory's
JavaHelp subdirectory. These two versions are named
BeanConnectBPELWsdlGenHelp_de.jar (German) and
BeanConnectBPELWsdlGenHelp_en.jar (English).
By default, the BPEL WSDL Generator is started in English.
To change the language setting, copy the jar file corresponding to the required language
from the JavaHelp directory to the lib directory and save it there under the name
BeanConnectBPELWsdlGenHelp.jar.
11.4.3 Functions of the BPEL WSDL generator
You use the BPEL WSDL Generator to define the properties of WSDL files and save these
in the form of WSDL instances. You can generate a WSDL file from a WSDL instance
whenever you want at the "touch of a button".
11.4.3.1
Creating a WSDL file
Perform the following steps to create a WSDL file:
●
366
Start the BPEL WSDL Generator and enter the context menu command New WSDL
Instance at the node BPEL WSDL. The properties sheet Add WSDL Instance opens.
BeanConnect V2.1
BPEL WSDL generator
Figure 63: Creating a WSDL instance
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k11
BPEL support
Dokuschablonen fr DARB XML in FSC-Layout Version 1.0 fr FrameMaker ab Version 7 vom 19.05.2005
cognitas GmbH 2001-2005
●
Enter the parameters for the WSDL instance in the three tabs General, Properties 1
and Properties 2:
–
In General, you enter the file name and directory name under which the WSDL file
is to be subsequently saved..
–
In Properties 1 and Properties 2, you enter the parameters which define the
service that is to be called together with its configuration properties. For details,
refer to the BPEL WSDL Generator's online Help system.
●
Click the Apply button. The parameters are now stored in the WSDL BPEL Generator
and the newly created WSDL instance is displayed in the tree structure; in the example,
this is CobSoa.
●
In CobSoa, you must now choose the context menu command Generate Wsdl
Instance to generate the WSDL file with the XML tags.
BeanConnect V2.1
367
BPEL WSDL generator
BPEL support
Figure 64: Creating a WSDL file
The WSDL file is generated and saved under the file name and path name specified in
General. You can specify this WSDL file as a Partner Link in your BPEL project.
I
11.4.3.2
To view a WSDL file, open the Extras menu and choose the Show Textfile...
command to go to the required directory. Please note that a WSDL file generated
by the BPEL WSDL Generator always has the suffix .wsdl.
Viewing, modifying and removing WDSL instances
You can use the context menu command Show Wsdl Instances... in the BPEL WSDL note
to output a table containing all the WSDL instances together with their properties.
If you want to modify the properties of a WDSL instance, open the instance's context menu
and choose Edit Properties. You can then edit the Instances properties in the window Edit
Properties of Wsdl Instance.
The Remove Wsdl Instance command in an instance's context menu allows you to remove
a WDSL instance from the BPEL WSDLGenerator. Any WSDL file that has been generated
in the interim will not be deleted.
368
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k12
The BeanConnect proxy container is installed with default configuration values. For
heavy-load operations it may be necessary to change this configuration. In most cases a
specific message is output to the proxy container logging when configuration limits are
reached.
This chapter provides information on:
●
Shared memory of the proxy container
●
Number of proxy container processes
●
Page pool area and cache of the proxy container
●
Number of parallel connections to the EIS partner
●
Asynchronous processing in the proxy container
●
OSI-SCRATCH-AREA in the proxy container
●
Number of semaphores in the proxy container
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
12 High availability and scalability
BeanConnect V2.1
369
Shared memory of the proxy container
High availability and scalability
12.1 Shared memory of the proxy container
All messages sent and received by the proxy container are stored in a shared memory
before executing in one of the proxy container processes. During communication scenarios
with large quantities of data, it may happen that the shared memory in which messages are
buffered is too small.
You can solve this problem via the environment variables UTM_IPC_LETTER and UTM_IPC_
EXPT_LETTER, which are specified in the start procedure of the proxy container:
●
Solaris and Linux systems:
<proxy_cont_home>/shsc/startcontainer.sh
●
Windows systems:
<proxy_cont_home>\shsc\startcontainer.cmd
12.1.1 Adapting the shared memory
The necessary modification depends on the insert in the U189 message:
●
U189 &OBJ1 ( &PTRM, &PRNM ): IPC shortage of LETT EXTP FULL or
U189 &OBJ1 ( &PTRM, &PRNM ): IPC shortage of LETT MAX ILETT or
U189 &OBJ1 ( &PTRM, &PRNM ): IPC shortage of LETT MAX OLETT
These inserts mean that the size of a message exceeds the maximum size of the data
area for a connection. The default maximum size after installation is 32 (specified in
4KB units).
To correct it, you must change the value of the UTM_IPC_EXTP_LETTER environment
variable to a bigger value.
●
U189 &OBJ1 ( &PTRM, &PRNM ): IPC shortage of LETT IPC FULL
These inserts mean that the size of all messages exceeds the maximum size of the data
area for all connections. The default maximum size after installation is 1600 (specified
in 4KB units).
To correct it, you must change the value of the UTM_IPC_LETTER environment variable
to a bigger value.
370
BeanConnect V2.1
Shared memory of the proxy container
In most cases, however, the following "rule of thumb" can be used:
●
UTM_IPC_EXTP_LETTER = maximum size of an outbound/inbound message in 4KB
units
●
UTM_IPC_LETTER = <nConn> * UTM_IPC_EXTP_LETTER, but not less than
1600 (6.4 MB).
<nConn> is the maximum number of connections between the proxy container and its
partner applications (EIS partner, resource adapter, Management Console).
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k12
High availability and scalability
BeanConnect V2.1
371
Number of proxy container processes
High availability and scalability
12.2 Number of proxy container processes
The maximum number of processes required in the proxy container is as high as the sum
of processes required for outbound and inbound communication.
Outbound communication
For outbound communication, the number of processes required of the bean is the number
of parallel connections of the bean if the connections are not organized in groups. If the
connections are organized in groups, the number of processes required is the number of
connection groups used at a time.
In addition, the total number of processes depends on the number of beans using outbound
communication at a time and whether this communication is transactional or non-transactional. In the case of transactional communication, a proxy process is exclusively assigned
to a bean until the transaction is completed; in the case of non-transactional communication
this is done only for the time required for a conversation.
Inbound communication
For inbound communication, the number of required processes is at least as high as the
maximum number of parallel inbound messages. The parallel inbound messages can at
most be as many as the number of parallel connections to all EIS partners.
12.2.1 Displaying the workload of processes
You can display the workload of the container application in the Management Console:
1. Open the subtree of the proxy in the navigation area.
2. Under Advanced Features choose the entry Properties/Statistics.
The value for the workload is given in the Properties / Statistics panel under Workload. If
the value under Workload (maximum) is higher than 80%, you should increase the number
of processes (see the following section).
372
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k12
High availability and scalability
Number of proxy container processes
12.2.2 Setting the number of processes
By default, three processes are started. You can change the number of processes in the
Management Console:
1. From the context menu of the proxy, select the entry Edit Properties.
2. In the Edit Properties of Local/Remote Proxy property sheet choose the Performance Settings tab.
3. Under Number of Proxy Container Processes change the value for Total.
The maximum number of processes is limited by internal settings to 250. You should also
take into account that a higher number of processes also increases the system overhead
for managing those processes and affects the size of the recovery file.
Moreover, additional virtual memory is required for each container process. For example,
when running on Solaris systems in 32-bit mode, each additional utmwork process requires
approximately 30-40 MB of additional memory. The precise requirement is dependent on
the configuration.
V
Caution!
If too little physical memory (RAM) is made available then the system transfers
memory areas to hard disk (paging). This can drastically slow down operation..
If there are more than 50 processes to be started, you additionally have to change the statements MAX TASKS, MAX TASKS-IN-PGWT and/or MAX ASYNTASKS in the file
input.system.txt manually.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
You find the file input.system.txt
●
on Solaris and Linux systems under the directory:
<proxy_cont_home>/def
●
on Windows systems under the directory:
<proxy_cont_home>\def
Adapt the statements as described in the following text:
●
MAX TASKS=<number>
To increase the number of processes, increase the value for <number> in this
statement. <number> specifies the maximum number of processes.
●
MAX TASKS-IN-PGWT=<number>
<number> specifies the maximum number of messages for outbound communication,
which can be processed in parallel.
BeanConnect V2.1
373
Number of proxy container processes
●
High availability and scalability
MAX ASYNTASKS=<number>
<number>specifies the maximum number of asynchronous messages for inbound
communication, which can be processed in parallel.
To activate these changes you have to carry out an update configuration and restart the
proxy (see "Saving and activating the configuration of the BeanConnect proxy" on
page 228):
1. From the context menu of the proxy, choose the entry Update Configuration.
2. From the context menu of the proxy, choose the entry Start Proxy.
374
BeanConnect V2.1
Page pool area and cache of the proxy container
12.3 Page pool area and cache of the proxy container
The required memory size for the proxy container depends on the size and the number of
the outbound and inbound messages that must be processed in parallel. Asynchronous
outbound and inbound messages occupy memory in the proxy container until they are sent
or processed completely.
The cache of the proxy container is a shared memory. Therefore the main memory required
on the computer on which the proxy container is running depends on the cache size.
●
If the Proxy Container Mode is set to Performance Enhanced (Non-durable
Asynchronous Processing) (default setting) and the main memory is sufficient, you
should set the cache to the same size as the page pool to avoid read/write access due
to a cache shortage.
●
If the Proxy Container Mode is set to Durable Asynchronous Processing, the cache
can only save on read access, as the data is always saved in the page pool.
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k12
High availability and scalability
The setting for the Proxy Container Mode is to be found as described below:
1. From the context menu of the proxy, select the entry Edit Properties.
2. In the Edit Properties of Local/Remote Proxy property sheet choose the Performance Settings tab.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
I
You must activate the Expert Mode to display the Performance
Settings tab.
For detailed information refer to the online help system of the
Management Console.
Changing the size of the storage areas
After installation, the size of the page pool area as well as the cache size is set to 20 MB.
You can change the size of these storage areas in the Management Console:
1. From the context menu of the proxy, select the entry Edit Properties.
2. In the Edit Properties of Local/Remote Proxy property sheet choose the Performance Settings tab.
3. Under Proxy Container Storage Area Sizes change the value for Pagepool (MB) and
Cache (MB).
BeanConnect V2.1
375
Number of parallel connections to the EIS partner
High availability and scalability
12.4 Number of parallel connections to the EIS partner
Parallel connections to an EIS partner via the OSI-TP or LU6.2 protocol
The number of parallel connections required from the proxy container to an EIS partner
depends on the maximum number of parallel messages that can be exchanged simultaneously between the applications in the application server and the EIS partners
You change the number of connections to the EIS partner in the Management Console:
1. Open the subtree of the proxy in the navigation area.
2. Open the subtree below EIS Partners.
3. From the context menu of the according EIS partner, choose the entry Edit Properties.
4. On the tab General specify the value for Connections.
The Management Console outputs the Number Of Connections Modified dialog box
where it suggests that you also modify the values of the other connection parameters. To
accept this suggestion, click Accept.
If you reject the suggestion with Cancel then please note that you must set sensible values
for the other connection parameters yourself:
If more outbound than inbound communication is carried out via the connections to an EIS
partner, less than half of the connections should be defined as contention winner. The
number has to be adjusted to the number of contention winners defined in the EIS configuration. The sum of both definitions has to be equal to the number of connections.
376
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k12
High availability and scalability
Number of parallel connections to the EIS partner
Number of parallel connections for inbound communication via the UPIC, RFC1006
or openUTM Socket protocol
You can change the number of UPIC, socket and RFC1006 connections for the inbound
communication in the Management Console:
1. From the context menu of the proxy, select the entry Edit Properties.
2. In the Edit Properties of Local/Remote Proxy property sheet choose the Performance Settings tab.
3. Under Number of Parallel Connections change the value for Inbound UPIC,
Inbound Socket or Inbound RFC1006.
These values also refer to the number of parallel connections to all EIS systems which
communicate using these protocols. The default value for all three partner types is 10
parallel connections.
The Management Console itself also requires a UPIC
connection to communicate with the proxy.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
I
BeanConnect V2.1
377
Asynchronous processing in the proxy container
High availability and scalability
12.5 Asynchronous processing in the proxy container
For the settings for asynchronous processing in the proxy container the duration of the
requests has to be considered as well as whether inbound or outbound communication is
used.
12.5.1 Duration of asynchronous requests
Asynchronous outbound requests which have not yet been sent to the EIS will be deleted
by default when the proxy container is stopped. This applies to
●
scheduled requests which have not yet reached their execution time.
●
requests which could not be sent yet because there is no connection to the EIS partner.
Asynchronous inbound requests which have not yet been started will also be deleted when
the proxy container is stopped. This applies to
●
requests which have not yet been sent to the application server.
●
requests which have to be sent to the application server again (redelivery).
If you want asynchronous requests to last longer, set the Proxy Container Mode to
Durable Asynchronous Processing via the Management Console. In this case you
should increase the page pool size too, if necessary (see "Changing the size of the storage
areas" on page 375).
You change the setting for the Proxy Container Mode in the Management Console:
1. From the context menu of the proxy, select the entry Edit Properties.
2. In the Edit Properties of Local/Remote Proxy property sheet choose the Performance Settings tab.
3. Under Proxy Container Mode choose the option for Durable Asynchronous
Processing.
I
378
You must activate the Expert Mode to display the Performance
Settings tab.
For detailed information refer to the online help system of the
Management Console.
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k12
High availability and scalability
Asynchronous processing in the proxy container
12.5.2 Inbound communication
The number of processes that may be active in parallel for processing an asynchronous
inbound message depends on the application scenario, but may only be as high as the
number of available processes minus one. By default, the proxy is started with the setting
that a maximum of two processes at a time may be active for processing asynchronous
inbound messages.
You can change the number of processes in the Management Console:
1. From the context menu of the proxy, select the entry Edit Properties.
2. In the Edit Properties of Local/Remote Proxy property sheet choose the Performance Settings tab.
3. Under Number of Proxy Containers change the value for For Asynchronous Jobs.
You must activate the Expert Mode to display the Performance
Settings tab.
For detailed information refer to the online help system of the
Management Console.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
I
BeanConnect V2.1
379
OSI-SCRATCH-AREA in the proxy container
High availability and scalability
12.6 OSI-SCRATCH-AREA in the proxy container
The size of the dynamic storage area for OSI-TP connections is defined in the
input.system.txt file with the following statement:
MAX OSI-SCRATCH-AREA=<value>
<value> indicates the size of the storage area in KB.
The default value is 1024 (1MB), the maximum value is 32767 KB.
You find the file input.system.txt
●
on Solaris and Linux systems under the directory:
<proxy_cont_home>/def
●
on Windows systems under the directory:
<proxy_cont_home>\def
Adjusting the storage area
If the dynamic storage area is not sufficient during operation (e.g. due to a large number of
parallel connections), the execution of the proxy container is aborted with the message
K060. The message contains an insert specifying the reason for the abortion whose
description indicates a storage shortage, e.g. SACT08 or SACT28. Reasons for an abortion
are described in chapter "Logging, diagnostics and troubleshooting" on page 383.
In this case you should change the value of the statement
MAX OSI-SCRATCH-AREA=<value>. As an initial measure it makes sense to double the
value. Then you must update the proxy configuration (e.g. in the Management Console:
Update Configuration command in the context menu of the proxy container).
380
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k12
High availability and scalability
Number of semaphores in the proxy container
12.7 Number of semaphores in the proxy container
The proxy container uses a range of semaphore keys for global operations. If you run a
large number of container processes the maximum value should be increased. In the case
of a shortage, you will find the message U189 with the insert SEMA USED in the container
logging file (see on page 463).
Increasing the number of semaphores
The number of semaphores is defined in the input.system.txt file with the following
statement:
MAX SEMARRAY=(<key>, <number>)
You find the file input.system.txt
●
on Solaris and Linux systems under the directory:
<proxy_cont_home>/def
●
on Windows systems under the directory:
<proxy_cont_home>\def
To increase the number of semaphores, increase the value for <number> in the
MAX SEMARRAY statement. For calculating <number> the following formula applies:
<number>=nProc/20+2
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
<nProc> specifies the number of container processes.
BeanConnect V2.1
381
Number of semaphores in the proxy container
382
High availability and scalability
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
June 8, 2009 7:06 pm
© cognitas GmbH
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
13 Logging, diagnostics and troubleshooting
This chapter provides information on the following topics:
●
Logging with Log4j
●
Logging with JDK logging
●
Configuring logging with Log4j
●
Diagnosis of the BeanConnect resource adapter
●
Diagnosis of the BeanConnect proxy container
●
Diagnosis of the BeanConnect Management Console
●
Diagnosis of the openUTM-LU62 Gateway
●
Diagnosis of SNAP-IX for Solaris systems
●
Diagnosis of the IBM Communications Server for Linux
●
Diagnosis of the IBM Communications Server for Windows systems
●
Collecting diagnostic information
●
Error messages of the BeanConnect proxy container
●
Error messages of the openUTM-LU62 Gateway
●
Error codes
I
BeanConnect V2.1
Since the BeanConnect proxy is based on openUTM, you will also require the
openUTM manual "Messages, Debugging and Diagnostics (UNIX, Windows NT)"
for diagnostic operations.
383
Logging with Log4j
Logging, diagnostics and troubleshooting
13.1 Logging with Log4j
BeanConnect uses the software product Log4j for logging functionality. Log4j is part of the
Apache Jakarta project. Log4j offers interfaces for logging information (runtime information,
trace records, etc.) and for configuring log output.
Log4j uses configuration files written in XML. The names of these files are fixed. All
BeanConnect components using Log4j are delivered with preconfigured configuration
files.The names of the output files are predefined in the configuration files. Different
BeanConnect components use different names for their output files.
This section provides information on the following topics:
●
Basic principles of Log4j
●
Loggers
●
Appenders
●
How the rolling file appender works
I
You can find more detailed information on Log4j at
http://logging.apache.org/log4j/1.2/manual.html
13.1.1 Basic principles of Log4j
Log4j uses two main components: the “logger”, which is the source of the messages, and
the “appender”, which defines the destination of the messages. The messages transferred
to a logger are output by all the appenders assigned to this logger.
13.1.1.1
Loggers
A logger is a source of messages. A program that is to write log information obtains logger
objects from Log4j and outputs its messages via these objects.
Name space
The logger name space has a hierarchical structure. The naming convention is the same
as that for Java packages. In other words, the individual levels of the hierarchy are
separated from each other by dots in the name. Within this hierarchy, loggers inherit their
properties from their parent loggers unless they have explicitly defined their own properties.
The root of the hierarchy is formed by the “root logger”, which does not have its own name
but is always present.
384
BeanConnect V2.1
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Logging with Log4j
Example 27 Logger name space
The logger called BeanConnect is the (direct) parent logger of the logger called
BeanConnect.info and is also the parent logger of the logger
BeanConnect.Datasources.OLTP.
Level
The level is a property that can be assigned to both a logger and a message. When the
logger is called, the logging program decides which level a message has. Depending on
which level has been assigned to the relevant logger, Log4j decides whether or not the
transferred message is to be logged. Messages are logged if the message level is greater
than or equal to the logger level. The logger is disabled if the level is OFF.
Log4j supports the following levels (in descending order):
Level
Meaning
FATAL
Serious error, highest level
ERROR
Error
WARN
Warning
INFO
Information
DEBUG
Debug output
TRACE
Trace output, lowest level
OFF
Can only be assigned to loggers. All messages output via this logger
are suppressed. The logger is switched off.
Example 28 Logging level
If a logging event with the level DEBUG is passed to a logger assigned to the level INFO, this
message is suppressed, but INFO, WARN, ERROR and FATAL messages are still output.
If you set the logger level ERROR, only messages with the level ERROR and FATAL are output.
BeanConnect V2.1
385
Logging with Log4j
13.1.1.2
Logging, diagnostics and troubleshooting
Appenders
The message destinations are defined by appenders. Log4j provides a number of different
predefined appenders, including the following:
●
File appender
The messages are written to a file.
●
Console appender
The messages are written to System.out or System.err.
●
Socket appender
The messages are written to a socket and can thus also be sent between computers to
a Log4j socket reader that can further process the messages (see the section "Configuring the BeanConnect Management Console as a Log4j socket reader" on page 394
for the resource adapter and for the proxy).
●
Rolling file appender
The messages are written to a file. When the specified extent threshold is reached, the
file is closed and the messages are written to a new trace file.
The logging events transferred to a logger are output through the appender(s) assigned to
the logger.
Example 29 Output of logging events through the appender
If there is a logger called Trace to which the appenders Console (console appender) and
File (file appender) are assigned, any message that is output by this logger is output
through both the file appender and the console appender. It thus appears both in the file
and on the console.
386
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
13.1.1.3
Logging with Log4j
How the rolling file appender works
The rolling file appender enables logging to a file with several backup files. You can
configure the maximum amount of disk space that the trace files may use. The rolling file
appender works in a single tasking environment (as in the resource adapter) as well as in
a multi tasking environment (as in the proxy container).
Logging files
The rolling file appender creates the files <File>.gen and (in a multi tasking configuration)
<File>.lck for internal use only and requires these in operation. <File> is the name of
the current logging file, e.g. BeanConnect.logging.txt. The file in the given example is
specified in the configuration file for the BeanConnectShortLoggingFile appender.
The rolling file appender always writes to the logging file <File>. At switch-over:
●
The file <File> is copied to a backup file.
●
The file <File> is written again.
At switch-over, the oldest existing backup files are deleted when:
●
After the file is copied, there are more backup files than the value specified for
<MaxNbrBackupFiles> and
●
<MaxNbrBackupFiles> is greater than 0.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
Specifications in angle brackets (<>) such as<File> or <MaxNbrBackupFiles> are
appender properties. For further information, see the sections "Predefined logging configuration of a resource adapter" on page 405 and "Predefined logging configuration of a
proxy" on page 412.
BeanConnect V2.1
387
Logging with Log4j
Logging, diagnostics and troubleshooting
Example 30 Logging files
In this example, <File>=<Filename>.txt and <MaxNbrBackupFiles>=3.
Situation before switch-over:
<Filename>.txt
In use
<Filename>.13.txt
Oldest backup file
<Filename>.14.txt
<Filename>.15.txt
Newest backup file
At switch-over, <Filename>.txt is copied to <Filename>.16.txt, <Filename>.13.txt
is deleted, and <Filename>.txt is then written again.
Situation after switch-over:
<Filename>.txt
In use
<Filename>.14.txt
Oldest backup file
<Filename>.15.txt
<Filename>.16.txt
388
Newest backup file
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Logging with JDK logging
13.2 Logging with JDK logging
The Apache Log4j package is used as standard for logging in BeanConnect products. Since
the BeanConnect resource adapter runs in an application server, it is possible that Log4j
should/may not be used in the server environment.
To solve this problem, the BeanConnect Logging Framework is used at all points within the
resource adapter. This logging framework is based on the Apache Jakarta Commons
Logging 1.0.4 package.
The BeanConnect Logging Framework supports the following logging packages as
standard:
●
Apache Log4j
●
Java 5 Logging API
Logging with Apache Log4j is the default setting. It is used if you do not make any changes
to the BeanConnect RAR archive supplied with the resource adapter.
To use Java 5 Logging, proceed as follows
●
Delete the file BeanConnectLog4j.jar from the resource adapter's BeanConnect
RAR archive.
JDK logging functions in a similar way to Log4j, see Section 13.1.1, "Basic principles of
Log4j".
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
You must enter the BeanConnect-specific logger manually in a JDK logging configuration
file. For a description of JDK logging, refer to the Java 5 documentation under
http://java.sun.com/j2se/1.5.0/docs/guide/logging/index.html.
BeanConnect V2.1
389
Configuring logging with Log4j
Logging, diagnostics and troubleshooting
13.3 Configuring logging with Log4j
This section contains information on the following topics:
●
Configuring logging for BeanConnect resource adapter and proxy
●
Editing the Log4j configuration file using the BeanConnect Management Console
●
Configuring the BeanConnect Management Console as a Log4j socket reader
●
Displaying the logging events in the BeanConnect Management Console
●
Display the Log4j logging file using the BeanConnect Management Console
13.3.1 Configuring logging for BeanConnect resource adapter and proxy
The following Log4j configuration file is preconfigured for the BeanConnect resource
adapter:
BeanConnect.log4j.properties.xml. After installation of the resource adapter (see
Chapter 3, "Installing BeanConnect"), this XML file is stored in the config subdirectory.
I
If you want to use the Management Console to process the file
BeanConnect.log4j.properties.xml for the resource adapter then an
MC-CmdHandler must be available on the computer on which the application
server is running.
The Log4j configuration file log4j.properties.xml is preconfigured for the
BeanConnect proxy. After installation of the proxy (see Chapter 3, "Installing
BeanConnect"), this XML file is stored in the proxy's config subdirectory.
I
The changes to the logging configuration do not take effect until you start or save
and restart the proxy (Save/Restart command - Save & Restart in the proxy's
context menu).
You can edit the configuration entries in both configuration files using a text editor. Alternatively, you can edit the file using the Management Console as described below. The
Management Console allows you to add loggers or to configure and remove loggers and
appenders.
390
BeanConnect V2.1
13.3.1.1
Configuring logging with Log4j
Configuring loggers
Use the Management Console to adapt the configuration of the loggers of a resource
adapter:
1. Open the Log4j configuration file as follows:
BeanConnect resource adapter:
–
In the resource adapters' navigation tree, click the node
Log4j Configuration.
BeanConnect proxy:
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
–
If necessary, start the MC-CmdHandler for the remote proxy.
–
In the proxy's navigation tree, click the nodes
Advanced Features - Diagnosis - Configuration - Proxy Container Log4j.
The Management Console displays the configuration in the Logging Configuration
panel.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
Figure 65: Configuring the loggers (example of BeanConnect proxy)
The loggers are displayed in a tree structure. All the existing loggers are listed under
the Loggers node. The identifier of a logger consists of its name and the level assigned
to it in parentheses. If the logger inherited the level from its parent, the level is indicated
by an arrow (-->).
BeanConnect V2.1
391
Configuring logging with Log4j
Logging, diagnostics and troubleshooting
2. To change the configuration, right-click a logger or one of its subnodes and choose the
appropriate command from the context menu.
You will find detailed information on the panels and the commands of the context menus in
the Management Console's online help system.
13.3.1.2
Configuring appenders
Use the Management Console to adapt the configuration of an appender:
1. Open the Log4j configuration file as follows:
BeanConnect resource adapter:
–
In the resource adapter's navigation tree, click the node
Log4j Configuration.
BeanConnect proxy:
–
If necessary, start the MC-CmdHandler for the remote proxy.
–
In the proxy's navigation tree, click the nodes
Advanced Features - Diagnosis - Configuration - Proxy Container Log4j.
The Management Console displays the configuration in the Logging Configuration
panel.
Figure 66: Configuring the appenders (example of BeanConnect proxy)
392
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Configuring logging with Log4j
The appenders are displayed in a tree structure. All the existing appenders are listed
under the Appenders node.
2. To change the configuration, right-click an appender or one of its subnodes and choose
the appropriate command from the context menu.
If you want to add a logger to the appender, for example, choose the Add Logger
command from the appender's context menu. The list displays all the loggers that can
still be added to the appender.
You will find detailed information on the panels and the commands of the context menus in
the Management Console's online help system.
13.3.2 Editing the Log4j configuration file using the BeanConnect
Management Console
The Management Console allows you to edit any Log4j configuration file in XML format:
1. Choose the Extras - Edit Log4j Configuration File command in the Management
Console.
The Choose Log4j Configuration File (XML) dialog box appears.
2. In this dialog box, select a configuration file in XML format.
You will find detailed information on the panels and commands of the context menus in the
Management Console's online help system.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
The Management Console displays the configuration contained in this file in the Edit
Log4j Configuration File panel. You edit any configuration file in the same way as the
Log4j configuration file of a resource adapter or a proxy (see the sections "Configuring
loggers" and "Configuring appenders" on page 391).
BeanConnect V2.1
393
Configuring logging with Log4j
Logging, diagnostics and troubleshooting
13.3.3 Configuring the BeanConnect Management Console as a Log4j socket
reader
The Management Console can function as a Log4j socket reader for a resource adapter or
a proxy. Consequently, logging output can be sent directly to a Management Console
window (see the section "Displaying the logging events in the BeanConnect Management
Console" on page 396).
To configure the Management Console for this, proceed as follows:
1. Choose the Configure Management Console as Listener command from the context
menu of any node in the Logging Configuration panel.
2. If the Management Console is to wait for logging events at the specified listener port
right from the start of any subsequent session, select the Automatically Begin to
Listen option on the General tab of the General Diagnostic Info Configuration panel.
3. BeanConnect resource adapter:
Set the appender BeanConnectMCSocketAppender as required in the resource
adapter file BeanConnect.log4j.properties.xml :
●
The host on which the Management Console is running must be specified in the
RemoteHost parameter.
●
In the Port parameter, you must specify the listener port at which the Management
Console waits for logging events from the proxy container.
I
The Management Console provides a list of all the logging listeners. This can be
accessed via the Log4j Logging Listeners node at the topmost level of the
navigation tree.
For the proxy, configuration involves the following steps:
1. If a socket listener port has not yet been entered in the properties of the relevant proxy
for this case, the Management Console first asks for this port.
I
394
The port is a local listener port and must therefore be different
from all the other local listener ports already used on the
Management Console's host. However, the Management
Console can only check whether the ports entered are unique
by referring to its own data and is subject to the same constraint
when enforcing uniqueness. Listener ports used by other applications on the host cannot be checked by the Management
Console. The user has to check that they are unique.
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Configuring logging with Log4j
2. After the port has been entered, the Management Console checks whether the
following appenders exist in the logging configuration of the proxy:
●
an async appender with the name BeanConnectManagementConsole
●
a socket appender with the name BeanConnectMCSocketAppender
If these appenders are missing, they are created by the Management Console. If they
exist, certain parameters of the appenders are checked and set appropriately.
3. The Management Console assigns the BeanConnectManagementConsole appender
to the loggers BeanConnect and de.siemens (if they exist). Consequently, logging
events are output to the Management Console via these two loggers or via loggers that
inherit the appenders from these two loggers.
4. The Management Console activates logging for the current session and waits for
logging events at the specified listener port.
Changing a listener port
To change the socket listener port subsequently, proceed as follows:
●
Click Advanced Features - Diagnosis - Configuration - General Diagnostic Info in
the navigation tree of the proxy and enter the MC Logging Listener Port.
This change does not take effect until the proxy is started again
or saved and reloaded (Save/Restart - Save & Restart
command in the context menu of the proxy).
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
I
BeanConnect V2.1
395
Configuring logging with Log4j
Logging, diagnostics and troubleshooting
13.3.4 Displaying the logging events in the BeanConnect Management
Console
If you have configured the Management Console appropriately (see the section "Configuring the BeanConnect Management Console as a Log4j socket reader" on page 394), it
receives the logging events output to the socket appender provided on the relevant
resource adapter or proxy.
To display the logging events on the Management Console:
●
Start the relevant proxy (see the section "Starting a proxy" on page 249).
●
Check whether the Automatically Begin to Listen option in the General Diagnostic
Info Configuration panel is set. Only if this option is selected does the Management
Console wait for logging events at the specified listener port right from the start.
Alternatively, you can also use the Start Listening command in the context menu of the
Proxy Container Log4j node beneath the Configuration node.
●
Click Advanced Features - Diagnosis - Output - Proxy Container Log4j in the
navigation tree of the proxy.
The Management Console displays the messages received in the Logging Output
panel.
Figure 67: Logging output
396
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Configuring logging with Log4j
The Logging Output panel consists of the following areas:
●
Logger Tree: Displays all the loggers for which there are messages in the Management
Console. Loggers whose paths are shown in red in the structure have at least one
message with the logging level WARN.
●
Logging Event List: Displays those logging events available in the Management
Console that match the current settings in the Logging Output panel. Messages that
appear in red have at least the logging level WARN.
When you select an event from the event list, it is displayed in detail in the lower part of
the event list.
You will find detailed information on the panels and commands of the context menus in the
Management Console's online help system.
Changing the layout of the panel
By default, the logger tree is displayed on the left of the panel and the message list on the
right. You can change this setting so that the logger tree and message list are each
displayed on a separate tab:
1. Click the Properties button in the Logging Output panel.
The Logging Properties dialog box appears.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
2. Select the display mode under Display Mode.
●
split
The logger tree and logging event list are displayed on the left and right of the panel
respectively.
●
tabbed
The logger tree and logging event list are displayed on two separate tabs.
Activating/deactivating the display of the loggers
The event list only displays the events of loggers that are activated in the event list.
To activate or deactivate the display for a logger:
Click the relevant logger node or its check box. This node, all the nodes in the path of the
node up to the node logger and all the associated child nodes are activated/deactivated.
BeanConnect V2.1
397
Configuring logging with Log4j
Logging, diagnostics and troubleshooting
Changing the display of messages
Events are displayed in the event list in accordance with the following criteria:
●
Only messages of the loggers that are activated in the logger tree (see the section
described above).
●
Only messages that are not currently suppressed.
The Clear button in the Logging Output panel consigns to the background all the logging
events of the relevant proxy that currently exist in the Management Console. The
messages are then no longer included in the output in the panel although they still exist
in the Management Console. You can display them again by clicking the Consider All
button.
●
Only those messages whose logging level corresponds at least to the minimum logging
level set for the list.
You set the logging level for the message list either by means of the buttons in the
Logging Output panel or by means of the Minimum Displayed Logging Level option
in the Logging Properties dialog box.
●
398
If a Filter Mask is entered in the Logging Properties dialog box, only the messages
that contain the filter text in at least one column (a distinction is drawn between
uppercase and lowercase).
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Configuring logging with Log4j
13.3.5 Display the Log4j logging file using the BeanConnect Management
Console
The Management Console allows you to display Log4j logging files in XML format offline.
A logging file in XML format is created, for example, when you have added an XML file
appender to a predefined file appender (Add XML File Appender command in the context
menu of the relevant file appender).
To display the logging file created:
1. Choose the Extras - Open Log4j Logging File (XMC) command in the Management
Console.
The Choose a Log4j Logging File (XMC) dialog box appears.
2. Select a logging file in XML format in this dialog box. By default, a logging file in XML
format has file name extension .xmc.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
The Management Console displays the logging file offline in the Log4j Logging File
panel. The panel is structured in the same way as the Logging Output panel, in which
messages are output online in the Management Console (see the section "Displaying
the logging events in the BeanConnect Management Console" on page 396).
BeanConnect V2.1
399
LogWriter for connection factories
Logging, diagnostics and troubleshooting
13.4 LogWriter for connection factories
The application server provides LogWriters to which the BeanConnect resource adapter
writes system level information on managed connection factories and managed connections when certain events occur. This information is intended for the application server
administrator and is not intended for the diagnosis of problems in application programs.
Events and event classes
The events are subdivided into the following classes which comprise specific events:
●
Errors
●
Transactions:
●
–
Begin of a transaction for a connection
–
Commit/Rollback of a transaction for a connection
Lifecycle:
–
Generation of a managed connection
–
Request for a connection handle for a managed connection
–
Switch of a connection handle for a managed connection
–
Release of a connection handle and inclusion of the managed connection in the
application server's connection pool
–
Removal of a managed connection from the application server's connection pool
–
Release of a managed connection
–
Application exceptions for a connection handle that are thrown to an application
–
System exceptions that are thrown for a managed connection
Configuring a LogWriter in the application server
In the case of Oc4j 10.1.3, you configure the LogWriter for a managed connection factory
in the file oc4j-ra.xml as follows:
●
Path name
In the <log> tag in the connection factory definition, set the
<file path> attribute to the path name for logging output, e.g.:
<log>
<file path="D:/temp/log/BeanConnect/echo.log" />
</log>
The directory specified in <file path> must exist. If it does not, Oc4j reports an error.
400
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
I
●
LogWriter for connection factories
In Oc4j, you should enter different data for different connection factories. Otherwise,
conflicts may occur when writing the files and the log records may be truncated.
Logging level
In Oc4j, you configure the logging level using the logLevel property in the file
oc4j-ra.xml. This value can be set separately for each managed connection factory.
There are four log levels: NONE, ERROR, INFO and ALL.
In the application server, you can configure whether or not a LogWriter is to be created for
a managed connection factory, where the resource adapter information is to be output, and
the logging level that is to apply.
For details, see Section 4.3, "Setting configuration properties for outbound communication
via OSI-TP / LU6.2", Section 4.4.1.2, "Setting the configuration properties for UPIC" and
Example 9, "Configuration properties in the file oc4j-ra.xml" on page 122.
Format of the logging records
All the records that BeanConnect writes to the LogWriter have the following structure:
BeanConnect:<date-time> <identifier> message
<date-time>
Specifies the date and time on which the record was written.
Format (example): 2008-05-04 14:48:44.241+0200.
<identifier>
Specifies the identifier.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
In the case of a managed connection factory, this is the value configured in
the DisplayName property of the file oc4j-ra.xml, see Section 4.3, "Setting
configuration properties for outbound communication via OSI-TP / LU6.2" and
Section 4.4.1.2, "Setting the configuration properties for UPIC".
In the case of a managed connection, the identifier has the form BCUnnnnn,
where each n stands for a digit.
In the case of a connection handle, the identifier has the form BCUnnnnn.i,
where each n stands for a digit and i stands for a number.
message
BeanConnect V2.1
Message output by the resource adapter
401
LogWriter for connection factories
Logging, diagnostics and troubleshooting
Example 31 Entries in the LogWriter file
1. In the case of lifecycle events, the date, time and identifier of the managed connection
are logged:
BeanConnect: 2008-05-04 14:49:59.546+0200 <sample application/echo>: Managed
connection with id <BCU00005> destroyed
2. In the case of events which refer to an exception, the exception is also logged:
BeanConnect: 2008-05-04 14:49:50.045+0200 <sample application/echo>:: Exception thrown
for connection <BCU00005.1>: net.fsc.jca.communication.EISConnectionException:
BCP02694X: Error when sending to EIS , error code: shortage of resources,
diagnosticString: //Service name:echo/Service type:Dialog/
KCOP:APRO/KCOM:DM/RCCC:40Z/RCDC:KD10/ Error message: shortage of resources (40Z,KD10):
no connection to partner; ; partner: (SMPOSICL,echo), Dialog//
3. In the case of communications with transactions, six logging records are usually
generated:
BeanConnect: 2008-05-04 14:49:49.905+0200 <sample application/echo>: Managed
connection with id <BCU00005> created
BeanConnect: 2008-05-04 14:49:50.045+0200 <sample application/echo>: Connection handle
with id <BCU00005.2> created
BeanConnect: 2008-05-04 14:49:52.430+0200 <sample application/echo>: Transaction
started for managed connection "BCU00005"; xid=formatID=1330790740, gtrid=AC187E91
AE7E0000 568B2057 12010000 00000000 00000000 , bqual=8AF22041 00000000 00000000
00000001
BeanConnect: 2008-05-04 14:49:57.183+0200 <sample application/echo>: Transaction
committed for managed connection "BCU00005"; xid=formatID=1330790740, gtrid=AC187E91
AE7E0000 568B2057 12010000 00000000 00000000 , bqual=8AF22041 00000000 00000000
00000001
BeanConnect: 2008-05-04 14:49:59.256+0200 <sample application/echo>: Connection handle
with id <BCU00005.2> released
BeanConnect: 2008-05-04 14:49:59.428+0200 <sample application/echo>: Managed
connection with id <BCU00005> returned for pooling
4. In the case of communication without transactions, four logging records are usually
generated:
BeanConnect: 2008-05-10 10:15:19.504+0200 <sample application/echo>:
connection with id <BCU00003> taken from pool
BeanConnect: 2008-05-10 10:15:19.504+0200 <sample application/echo>:
with id <BCU00003.2> created
BeanConnect: 2008-05-10 10:15:26.764+0200 <sample application/echo>:
with id <BCU00003.2> released
BeanConnect: 2008-05-10 10:15:26.982+0200 <sample application/echo>:
connection with id <BCU00003> returned for pooling
402
Managed
Connection handle
Connection handle
Managed
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Diagnosis of the BeanConnect resource adapter
13.5 Diagnosis of the BeanConnect resource adapter
This section provides information on the following topics:
●
Overview of logging in the BeanConnect resource adapter
●
Predefined logging configuration of a resource adapter
●
Logging of user interface calls
13.5.1 Overview of logging in the BeanConnect resource adapter
This section provides information on logging in the BeanConnect resource adapter. The
logging facilities use Log4j by default. The scope of logging is controlled by configuration
files. The following configuration files are delivered with the BeanConnect resource adapter
installation:
●
the file config/BeanConnect.log4j.properties.xml
basic logging information (default)
●
The file config/BeanConnect.log4j.properties_default.xml
corresponds to the file config/BeanConnect.log4j.properties.xml
●
the file config/BeanConnect.log4j.properties_debug.xml
detailed logging information
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
●
the file config/BeanConnect.log4j.properties_error.xml
only the information on errors is logged
You can use one of these configuration files depending on your requirements.
You will find detailed information on controlling the depth of logging manually in the sections
"Logging with Log4j" on page 384 and "Diagnosis of the BeanConnect resource adapter"
on page 403.
Default logging in the resource adapter
After the resource adapter has been deployed, basic logging is activated automatically.
●
●
BeanConnect V2.1
The logging files are saved in the logging directory of the application server (for OC4J
in j2ee/home/log).
403
Diagnosis of the BeanConnect resource adapter
●
Logging, diagnostics and troubleshooting
The following logging files are created:
–
BeanConnect.logging.txt (information for the user)
–
BeanConnect.extlogging.txt (logging data which you must send to system
service if an error occurs.)
–
BeanConnect.extlogging.txt.xmc (additional logging data which you must
send to the system service if an error occurs.)
Adapting logging in the resource adapter
Copy the configuration files present in the resource adapter installation to the application
server's configuration directory..
For OC4J, the directory is j2ee/home/config.
404
●
To extend logging (comprehensive runtime logging):
Rename the copied file
config/BeanConnect.log4j.properties_debug.xm to
BeanConnect.log4j.properties.xml.
●
To restrict logging (error logging only)
Rename the copied file
config/BeanConnect.log4j.properties_error.xml to
BeanConnect.log4j.properties.xml
●
Application-specific logging control for the resource adapter
Adapt the file config/BeanConnect.log4j.properties.xml to your requirements
as described below (see Section 13.1, "Logging with Log4j" and Section 13.5,
"Diagnosis of the BeanConnect resource adapter") and rename it to
BeanConnect.log4j.properties.xml.
BeanConnect V2.1
Diagnosis of the BeanConnect resource adapter
13.5.2 Predefined logging configuration of a resource adapter
Logging in the resource adapter is preconfigured with the following default values in the file
BeanConnect.log4j.properties.xml (see the section "Predefined logging configuration of a resource adapter" on page 405).
Appender
BeanConnectSysoutShort
Description:
Console appender with the destination System.out
and “short” output format, i.e. without a specification of
the message source.
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
At this appender, BeanConnect outputs messages on
the resource adapter configuration as well as warnings
and error messages.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
Recommendation:
No further loggers should be assigned to this
appender.
BeanConnect V2.1
405
Diagnosis of the BeanConnect resource adapter
BeanConnectShortLoggingFile
Logging, diagnostics and troubleshooting
Description:
Rolling file appender for logging to a file with several
backup files (see the section "How the rolling file
appender works" on page 387) and "short" output.
The same information is output to this appender that is
sent to BeanConnectSysoutShort.
At this appender, BeanConnect outputs messages on
the resource adapter configuration as well as warnings
and error messages
This appender has three parameters:
●
File
(Relative) file name of the current logging file
Default: log/BeanConnect.logging.txt
●
MaxNbrBackupFiles
Maximum number of backup files. If you specify 0
here, no backup files are created.
Default: 10
●
MaxFileSizePerProcessKB
The maximum size in KB that the output file is
allowed to reach before being rolled over to
backup files.
Default: 1024
Recommendation:
No further loggers should be assigned to this
appender. However, the user may increase the level for
the BeanConnect.ui logger if necessary (i.e. from
WARN to INFO, DEBUG or TRACE).
406
BeanConnect V2.1
BeanConnectLoggingFile
Diagnosis of the BeanConnect resource adapter
Description:
Rolling file appender for logging to a file with several
backup files (see the section "How the rolling file
appender works" on page 387) and, in contrast to
BeanConnectShortLoggingFile, more output with
technical details.
This appender is used for system diagnosis. If
necessary, BeanConnect writes detailed diagnostic log
information to this appender.
This appender has three parameters:
●
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
File
(Relative) file name of the current logging file
Default: log/BeanConnect.extlogging.txt
●
MaxNbrBackupFiles
Maximum number of backup files. If you specify 0
here, no backup files are created.
Default: 10
●
MaxFileSizePerProcessKB
The maximum size in KB that the output file is
allowed to reach before being rolled over to
backup files.
Default: 1024
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
Recommendation:
No further loggers may be added to this appender. If
necessary, users should be able to increase the level
for the BeanConnect.ui logger (i.e. from WARN to
INFO, DEBUG or TRACE, see Section 13.5.3,
"Logging of user interface calls") on their own initiative,
i.e. without consulting the system diagnostics.
BeanConnect V2.1
407
Diagnosis of the BeanConnect resource adapter
BeanConnectLoggingFileXML
Logging, diagnostics and troubleshooting
Description:
Rolling file appender for logging to a file with several
backup files (see the section "How the rolling file
appender works" on page 387). The output of this
appender has an XML-like layout. The file is provided
for input to the Management Console (see also section
"Display the Log4j logging file using the BeanConnect
Management Console" on page 399).
The same information is output to this appender that is
sent to the appender BeanConnectLoggingFile.
This appender is used for system diagnosis. If
necessary, BeanConnect writes detailed diagnostic log
information to this appender.
This appender has three parameters:
●
File
(Relative) file name of the current logging file
Default:
log/BeanConnect.extlogging.txt.xmc
●
MaxNbrBackupFiles
Maximum number of backup files. If you specify 0
here, no backup files are created.
Default: 10
●
MaxFileSizePerProcessKB
The maximum size in KB that the output file is
allowed to reach before being rolled over to
backup files.
Default: 1024
Recommendation:
No further loggers may be added to this appender.
If necessary, users should be able to increase the
level for the BeanConnect.ui logger (i.e. from
WARN to INFO, DEBUG or TRACE, see
Section 13.5.3, "Logging of user interface calls")
on their own initiative, i.e. without consulting the
system diagnostics.
408
BeanConnect V2.1
BeanConnectMCSocketAppender
Diagnosis of the BeanConnect resource adapter
Description:
Auxiliary appender used to log to the Management
Console.
This appender has four parameters:
●
RemoteHost
Host where the Management Console is running.
Default: localhost
●
Port
Listener port of the Management Console.
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Default: 31015
●
LocationInfo
Always true.
●
ReconnectionDelay
A positive integer representing the number of
milliseconds between each failed connection
attempt to the server.
Default: 10000
Recommendation
No further loggers should be added to this appender.
BeanConnectManagementConsole
Description:
Appender for logging to the Management Console.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
Recommendation:
Loggers that are to be displayed at the Management
Console should be added to this appender.
BeanConnect V2.1
409
Diagnosis of the BeanConnect resource adapter
Logging, diagnostics and troubleshooting
Loggers
You are recommended not to change the logger settings - with the exception of the logger
BeanConnect.ui.
BeanConnect
Parent logger of all the other BeanConnect loggers
Level: WARN
BeanConnect.in
Logger for BeanConnect inbound communication.
BeanConnect.info
Logger for runtime information
Level: INFO
BeanConnect.out
Logger for BeanConnect outbound communication.
BeanConnect.ui
Logger for the BeanConnect user interface calls
Level: WARN
In the default configuration, the output of the logger
BeanConnect.ui is sent to the appenders
BeanConnectShortLoggingFile,
BeanConnectLoggingFile,
BeanConnectLoggingFileXML.
de.siemens
net.fsc
Parent loggers of all class-specific BeanConnect
loggers that serve to output debug traces
Level: WARN
net.fsc.beanta.encoding
Logger for BeanConnect's encoding support
Level: WARN
net.fsc.tpbasics.util.L
410
Logger for supporting Log4j
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Diagnosis of the BeanConnect resource adapter
13.5.3 Logging of user interface calls
Application (EJB) calls to BeanConnect are logged at separate loggers
(BeanConnect.ui and its child loggers). This output can assist users in diagnosing
problems in their applications.
Output to the logger BeanConnect.ui may use the levels INFO, DEBUG or TRACE. For a
summary, see the following table:
List of the BeanConnect.ui loggers, their levels and meaning
Logger
Level
Meaning
BeanConnect.ui.out
INFO
Logging of outbound interface calls without data
BeanConnect.ui.oltpmsg
INFO
Logging of OLTP message interface calls without
data
BeanConnect.ui.data.api DEBUG
Logging of all data transferred at the user interface
BeanConnect.ui.data.net TRACE
Logging of all data transferred at the user interface in
the form in which it is transferred in the network, i.e.
possibly recoded.
BeanConnect.ui.in
Logging of the OLTP message objects
transferred to and from the message endpoint
application
INFO
Example 32 Control of logging output
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
●
Logger BeanConnect.ui set to level INFO:
All the user interface calls are logged without data.
●
Logger BeanConnect.ui set to level DEBUG:
All the user interface calls are logged together with the data transferred on these calls.
●
Logger BeanConnect.ui set to level TRACE:
All the user interface calls are logged together with the data transferred on these calls
and any encoded data.
●
Logger BeanConnect.ui.out set to level INFO and BeanConnect.ui.data.net set
to level TRACE:
All the outbound interface calls are logged together with the encoded data. Calls at the
OLTP message interface and data transferred at the outbound interface are not logged.
BeanConnect V2.1
411
Diagnosis of the BeanConnect proxy container
Logging, diagnostics and troubleshooting
13.6 Diagnosis of the BeanConnect proxy container
There is a variety of information available for diagnosis of a BeanConnect proxy container.
This information is distributed among a number of files in the container home directory on
the basis of functionality.
This section provides information on the following topics:
●
Predefined logging configuration of a proxy
●
Log files of the BeanConnect proxy container
●
Traces of the BeanConnect proxy container
13.6.1 Predefined logging configuration of a proxy
The logging of each proxy is preconfigured with the following default values after installation.
Appender
BeanConnectSysoutShort
Description:
Console appender with the destination System.out
and “short” output format, i.e. without any specification
of the message source.
BeanConnect outputs general messages as well as
warnings and error messages at this appender
Recommendation:
No further loggers should be added to this appender.
BeanConnectSysout
Console appender with the destination System.out
and detailed output format for making easier the
system diagnosis.
BeanConnect outputs fatal messages for which no
other appender is configured to this appender.
Recommendation:
No further loggers should be added to this appender.
412
BeanConnect V2.1
BeanConnectLoggingFile
Diagnosis of the BeanConnect proxy container
Description:
Rolling file appender for logging to a file with several
backup files (see the section "How the rolling file
appender works" on page 387)
This appender is used for system diagnosis.
BeanConnect writes detailed diagnostic logging
information to this appender if necessary.
This appender has three parameters:
●
File
(Relative) file name of the current logging file
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Default: logs/logging.txt
●
MaxNbrBackupFiles
Maximum number of backup files. If you specify 0
here, no backup files are created.
Default: 10
●
MaxFileSizePerProcessKB
Process-specific switchover threshold in KB. When
the writing of a logging event causes the file size
to exceed this process-specific threshold, the file
is switched. The size of a logging file at switchover
is thus somewhere between the values for
<MaxFileSizePerProcessKB> and <number_of_
processes>*<MaxFileSizePerProcessKB>.
Default: 500
BeanConnectLoggingFileXML
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
Recommendation:
No further loggers should be added to this appender.
Description:
Rolling file appender for logging to a file with multiple
backup files (see Section 13.1.1.3, "How the rolling file
appender works"). The output from this appender has
an XML-like layout. The file can be evaluated at the
Management Console (see also Section 13.3.5,
"Display the Log4j logging file using the BeanConnect
Management Console").
Although this appender is preconfigured, it is not used
in the standard BeanConnect configuration. It is used
for system diagnostics. If necessary, BeanConnect
writes detailed diagnostic logging information to this
appender.
Recommendation:
If required or if so requested by the system service,
this appender should be assigned the same loggers as
the appender BeanConnectLoggingFile.
BeanConnect V2.1
413
Diagnosis of the BeanConnect proxy container
Logging, diagnostics and troubleshooting
Loggers
It is recommended not to change the logger settings.
Root-Logger
Level: FATAL.
BeanConnect
Parent logger of all the other BeanConnect loggers
Level: ERROR
BeanConnect.c
Logger for debug traces from the C components of
BeanConnect
Level: ERROR
BeanConnect.info
Logger for runtime information
Level: INFO
BeanConnect.Datasources.OLTP
Logger for OLTP data sources
Level: ERROR
BeanConnect.kdcs
Logger for debug traces of the KDCS calls from the
proxy container application.
Level: ERROR
de.siemens
and
net.fsc
net.fsc.tpbasics.util.L
Parent loggers of all class-specific BeanConnect
loggers that serve to output debug traces.
Level: ERROR
Logger for supporting Log4j
Level: WARN
net.fsc.beanta.encoding
.EncoderImpl
414
BeanConnect's logger for encoding support
Level: WARN
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Diagnosis of the BeanConnect proxy container
13.6.2 Log files of the BeanConnect proxy container
The proxy container is based on openUTM. There are several logging and diagnosis files
with information from openUTM. This section provides information on the following topics:
13.6.2.1
●
stdout/stderr log
●
System log file SYSLOG
●
Dumps and diagnostic dumps
●
Application log under Windows
stdout/stderr log
Messages from the proxy container to stdout/stderr are logged to files in the proxy
container home directory. The files are available by default. The files utmp.err.<suffix>
and utmp.out.<suffix> are created for the first time when the proxy container is started
and the suffix YY-MM-DD.HHMMSS corresponds to the start time.
Switching the log file
At runtime, the proxy container application is set in such a way that stdout/stderr output
is switched to new files every day at midnight. The suffix YY-MM-DD.HHMMSS added to these
files corresponds to the switchover time.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
In addition, you can also switch over the stdout/stderr files manually using the
Management Console. To do this, choose the Switch Protocol Files command in the proxy
or proxy cluster's context menu.
Displaying the log files
You can display the content of the files as follows:
●
In the Management Console, choose the nodes Advanced Features - Diagnosis Output - General Diagnostic Info under the proxy container's node. In the case of a
proxy cluster, you must also select the proxy.
Select the entry Container STDERR Diagnostics or Container STDOUT
Diagnostics Then click the Show File button.
The Management Console then lists all the utmp.out.* or utmp.err.* files for
selection. Select the required files and click the OK button. The Management Console
transfers the selected files to the local diagnostic path of the proxy and displays them in
a Text File panel.
For details, please refer to the Management Console's online help system.
BeanConnect V2.1
415
Diagnosis of the BeanConnect proxy container
Logging, diagnostics and troubleshooting
●
You can also view and evaluate these logs using a standard editor directly in the proxy
container's home directory.
●
Under Windows you can also use the commands Advanced - Show STDERR
Diagnostics or Advanced - Show STDOUT Diagnostics in the program group of the
proxy container to display the utmp.err or utmp.out file respectively.
Backing up the log files
The files are backed up to the proxy container directory out-err the next time the proxy
container is started. Before the backup, all the files in the directory out-err are deleted. If
you want to use these files for diagnostic purposes, you must therefore back them up before
restarting the proxy.
If the proxy container is executed as a service on Windows systems (see section "Starting
the proxy container as a Windows service" on page 251), its first output to stdout is written
to the file utmp.out and its first output to stderr is written to the file utmp.err.
If the log is switched, the files have the names:
utmp.err.<suffix> and utmp.out.<suffix>.
The logs from the last application run are automatically backed up in the directory out-err.
13.6.2.2
System log file SYSLOG
The system log file records important events (in the form of binary messages) from the
proxy container run. It contains important information which can be used to diagnose errors.
It is stored in the file directory SYSLOG in the proxy container home directory. The file is
available by default.
It can be displayed as follows:
●
In the Management Console, choose the nodes Advanced Features - Diagnosis Output - General Diagnostic Info under the proxy container's node and select the
entry Container Syslog Files. Then click the Show File button.
If there is more than one file of the selected type, the Select Diagnostic File To Show
dialog box opens showing the appropriate files on the host. Select the diagnostic file you
want to show.
The Management Console transfers the converted text file syslog.<number>.txt to
the local diagnostic path of the proxy and displays the file in a Text File panel.
For details, please refer to the Management Console's online help system.
416
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
●
Diagnosis of the BeanConnect proxy container
On Solaris and Linux systems, change to the proxy container home directory and call
the script as follows:
shsc/syslog.sh
The available log files are listed and you are asked whether you want to display each
file in sequence. If you select a file, the formatted information is written to the slogout
file in the proxy container home directory and displayed in the system's default editor.
●
On Windows systems (cmdline), choose the command Advanced - Show Syslog in
the program group of the proxy container.
June 8, 2009 7:06 pm
A command line prompt is opened in which the available log files are listed. Select the
number of the file you want to display. The formatted information is then written to the
slog.out file in the proxy container home directory and displayed in the system's
default editor.
●
On Windows systems, change to the proxy container home directory and call the script
as follows:
shsc\syslog.cmd
The formatted information is then written to the slog.out file in the proxy container
home directory and displayed in the system's default editor.
13.6.2.3
Dumps and diagnostic dumps
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
If the proxy container crashes or fatal errors occur while the proxy container is running, an
openUTM dump is generated and stored in the subdirectory DUMP of the proxy container
home directory.
I
13.6.2.4
Please note that these dumps should be analyzed primarily by
BeanConnect specialists.
Application log under Windows
If the proxy container is started as a service and problems occur during startup, the application log may provide additional information (see the section "Starting the proxy container
as a Windows service" on page 251):
1. Choose Start - Settings - Control Panel - Administrative Tools - Event Viewer.
2. In the event viewer, click Application Log, and then select the source openUTM.
BeanConnect V2.1
417
Diagnosis of the BeanConnect proxy container
Logging, diagnostics and troubleshooting
13.6.3 Traces of the BeanConnect proxy container
This section provides information on the following topics:
13.6.3.1
●
OSS trace
●
BCAM trace
●
CMX trace
OSS trace
The function logs activities in the proxy container relating to OSI-TP connections to the
openUTM partner application or to the openUTM-LU62 Gateway.
By default the OSS trace is deactivated. To activate the OSS trace of the proxy container in
the Management Console:
1. Select the following nodes in the navigation tree of the proxy:
Advanced Features - Diagnosis - Configuration - General Diagnostic Info.
The General tab of the General Diagnostic Info Configuration panel is displayed.
2. Select the option Activate OSS Trace.
If the proxy container is running, the change comes into effect dynamically when saving the
proxy. If the proxy container is not running, the change comes to effect when the proxy is
next started.
The traces are written in a binary format to OSST.* files in the proxy container home
directory. You can evaluate and display the trace information:
●
In the Management Console, choose the nodes
Advanced Features - Diagnosis - Output - General Diagnostic Info in the navigation
tree of the proxy and select the entry Container OSS Traces. Then click the Show File
button.
The Management Console transfers the converted text file osstrac.txt to the local
diagnostic path of the proxy (default: diag/<proxy_cont_name> in the Management
Console home directory) and displays the file in a Text File panel.
●
On Solaris and Linux systems, change to the proxy container home directory and call
the script as follows:
shsc/ositrace.sh
The traces produced are then written to the osstrac.txt file in the proxy container
home directory and displayed in the system's default editor.
418
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
●
Diagnosis of the BeanConnect proxy container
On Windows systems, change to the proxy container home directory and call the script
as follows:
shsc\ositrace.cmd
The traces produced are then written to the osstrac.txt file in the proxy container
home directory and displayed in the system's default editor.
For further diagnosis, you have to send the evaluated trace to the diagnostic system
service.
13.6.3.2
BCAM trace
The function logs all connection-oriented activities within the proxy container.
By default, the BCAM trace is deactivated. To activate the BCAM trace of the proxy
container in the Management Console:
1. Select the following nodes in the navigation tree of the proxy:
Advanced Features - Diagnosis - Configuration - General Diagnostic Info.
The General tab of the General Diagnostic Info Configuration panel is displayed.
2. Select the option Activate BCAM Trace.
If the proxy container is running, the change comes into effect dynamically when saving the
proxy. If the proxy is not running, the change comes to effect when the proxy is next started.
The traces are written in a binary format to KDCBTRC.* files in the proxy container home
directory. You can evaluate and display the trace information:
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
●
In the Management Console choose the nodes Advanced Features - Diagnosis Output - General Diagnostic Info and select the entry Container BCAM Traces.
Then click the Show File button.
The Management Console transfers the converted text file btrc.txt to the local
diagnostic path of the proxy
(default: diag/<proxy_cont_name> in the Management Console home directory).
The Management Console displays the file in a Text File panel.
●
On Solaris and Linux systems, change to the proxy container home directory and call
the script as follows:
shsc/nettrace.sh
The traces produced are then written to the btrc.txt file in the proxy container home
directory and displayed in the system's default editor.
BeanConnect V2.1
419
Diagnosis of the BeanConnect proxy container
●
Logging, diagnostics and troubleshooting
On Windows systems, change to the proxy container home directory and call the script
as follows:
shsc\nettrace.cmd
The traces produced are then written to the btrc.txt file in the proxy container home
directory and displayed in the system's default editor.
For further diagnosis, you have to send the evaluated trace to the diagnostic system
service.
13.6.3.3
CMX trace
This function logs transport layer activities in the proxy container relating to connections to
the openUTM partner application or to the openUTM-LU62 Gateway.
By default the CMX trace is deactivated. To activate the CMX trace of the proxy container
in the Management Console:
1. Select the following nodes in the navigation tree of the proxy:
Advanced Features - Diagnosis - Configuration - General Diagnostic Info.
The General tab of the General Diagnostic Info Configuration panel is displayed.
2. Select the option Activate CMX Trace.
The change comes into effect when the proxy is next started.
Solaris and Linux systems
The CMX traces of the proxy container are written in a binary format in CMX* files in the
cmxt subdirectory of the proxy container home directory.
Windows systems
The CMX traces of the proxy container are written in binary format to <number>.CMX files.
These files are processed in the configured trace path of CMX. You can specify the trace
path by using the PCMX-32 tool Trace Control. Choose the command Options - Trace
Path and specify the path. To start Trace Control, select the command Trace Control from
the PCMX-32 program group. The PCMX-32 program group is available after installing
PCMX-32.
420
BeanConnect V2.1
Diagnosis of the BeanConnect proxy container
Displaying the CMX traces in the BeanConnect Management Console
You can evaluate and display the CMX trace information in the Management Console.
In the Management Console, choose the nodes Advanced Features - Diagnosis - Output
- General Diagnostic Info under the proxy's node and select the entry Container CMX
Traces. Then click the Show File button.
The Management Console transfers the converted text file with the appended suffix .txt
to the local diagnostic path of the proxy (default: diag/<proxy_cont_name> in the
Management Console home directory). The Management Console displays the file in a
Text File panel.
For further diagnosis, you have to send the evaluated trace to the diagnostic system
service.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
BeanConnect V2.1
421
Diagnosis of the BeanConnect Management Console
Logging, diagnostics and troubleshooting
13.7 Diagnosis of the BeanConnect Management Console
The Management Console uses Log4j to output its own logging messages and debug
traces.
The traces are written in the file logging.txt in the subdirectory logs of the Management
Console. The files are always available by default. The content of the files can be displayed
using any text editor.
The output traces are controlled by the file log4j.properties.xml in the config subdirectory of the Management Console.
You will find detailed information on the trace mechanism of the Management Console in
the Management Console's online help system.
422
BeanConnect V2.1
Diagnosing the BeanConnect tools
13.8 Diagnosing the BeanConnect tools
MC-CmdHandler
By default, logging for the MC-CmdHandler is performed using Log4j. The scope of logging
is controlled via configuration files. The following configuration files are present in the
BeanConnect resource adapter installation:
●
The file mccmdhandler.log4j.properties.xml
Basic logging data (default)
●
The file mccmdhandler.log4j.properties_debug.xml
Detailed logging data
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
BeanConnect V2.1
423
Diagnosis of the openUTM-LU62 Gateway
Logging, diagnostics and troubleshooting
13.9 Diagnosis of the openUTM-LU62 Gateway
This section provides information on the following topics:
●
Traces and logs of the openUTM-LU62 Gateway
●
Diagnosis information for the openUTM-LU62 Gateway
13.9.1 Traces and logs of the openUTM-LU62 Gateway
The openUTM-LU62 Gateway writes messages into log files and optionally provides trace
information for diagnostics functionality. There are two different kinds of traces:
●
Instance traces
●
XAP-TP traces
You can define different trace levels to configure the extent of the instance traces.
13.9.1.1
Activate/deactivate traces
By default, the instance traces and the XAP-TP traces are deactivated. You can activate the
traces for the openUTM-LU62 Gateway using the Management Console.
Select the openUTM-LU62 Gateway under the item openUTM-LU62 Gateways in the
navigation tree or openUTM-LU62 Gateways in the proxy's navigation tree and choose
Edit Properties in the context menu. The table Edit Properties of openUTM-LU62
Gateway lists the defined values which you are now able to edit.
●
Trace Level
Specifies the level of instance traces logged by the openUTM-LU62 Gateway.
●
Activate XAP-TP Trace
Select this option to specify that the openUTM-LU62 Gateway is to log XAP-TP
traces.The function logs the activities of the components XAP-TP provider and OSS
with respect to connections to the proxy container.
If the openUTM-LU62 Gateway is running, the trace settings come into effect dynamically
when saving the openUTM-LU62 Gateway.
424
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Diagnosis of the openUTM-LU62 Gateway
If the traces are activated, they are written in the following files:
●
June 8, 2009 7:06 pm
●
On Solaris and Linux systems:
●
instance trace file
/opt/lib/utmlu62/PROT/inlog.<lu_name>.<suff>
●
XAP-TP trace file
/opt/lib/utmlu62/PROT/xaplog.
<lu_name>.<suff1>.<suff2>
On Windows systems:
●
instance trace file
<gateway_home>\PROT\inlog.<lu_name>.<suff>
●
XAP-TP trace file
<gateway_home>\PROT\xaplog.<lu_name>.<suff1>.<suff2>
Here <lu_name> stands for a local LU alias name, <suff>/<suff1>/<suff2> are
numerical suffixes and <gateway_home> indicates the directory where the openUTM-LU62
Gateway is installed.
13.9.1.2
Evaluating traces and logs
The traces of the openUTM-LU62 Gateway are written in binary format.
You can convert and display all the openUTM-LU62 Gateway traces and log files in the
Management Console:
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
1. Choose the following nodes in the navigation tree of the proxy:
Advanced Features - Diagnosis - Output - General Diagnostic Info
2. Select one of the following entries:
●
LU62 Gateway Instance Traces
●
LU62 Gateway Instance Protocol Flow
●
LU62 Gateway XAP-TP Traces
●
LU62 Gateway Protocol Files
3. Click the Show File button.
The Management Console transfers the converted text file to the local diagnostic path and
displays the file in a Text File panel.
Two files result from the conversion of a binary instance trace:
●
generated instance trace
●
instance log flow
BeanConnect V2.1
425
Diagnosis of the openUTM-LU62 Gateway
Logging, diagnostics and troubleshooting
In addition to the trace files the openUTM-LU62 Gateway writes messages into log files:
●
On Solaris and Linux systems:
/opt/lib/utmlu62/PROT/prot.<lu_name>
●
On Windows systems:
<gateway_home>\PROT\prot.<lu_name>.txt
Here <lu_name> stands for a local LU alias name and <gateway_home> indicates the
directory where the openUTM-LU62 Gateway is installed.
The names of the log files and the generated traces in the local diagnostic path are as
follows:
●
instance traces: inlog.*.txt
●
instance protocol flow: inlog.*.flow.txt
●
XAP-TP traces: xaplog.*.txt
●
log files: prot.*.txt
Instance protocol flow
In the instance protocol flow files you will find an abbreviated description of the protocol flow
(LU6.2 and OSI-TP protocol).
The openUTM-LU62 Gateway uses the APPC interface for communication via the LU6.2
protocol and the XAP-TP interface for communication via the OSI-TP protocol.
On the side of the LU6.2 protocol, the following information is displayed in the protocol flow
for every message:
●
name of the APPC call
●
TP-ID which is assigned by the SNAP-IX or the IBM Communications Server
●
direction of processing
●
additional parameters
The direction of processing is indicated by an arrow. An arrow pointing to the left indicates
a message sent by the openUTM-LU62 Gateway and an arrow pointing to the right
indicates a message received by the openUTM-LU62 Gateway.
The administration data is exchanged between the openUTM-LU62 Gateway and the LU6.2
partner while the openUTM-LU62 Gateway is starting up or if a connection error occurs.
The transaction code X'06F2' is used for this purpose. These protocol flows are indicated
by a single arrow (-->). A protocol flow of an application program is indicated by a double
arrow (==>).
426
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Diagnosis of the openUTM-LU62 Gateway
Each message contains a correlation number in order to make it easier to associate an
LU6.2 conversation and a parallel connection via XAP-TP. Protocol flows that are not
associated with a conversation are assigned the correlation number zero.
Additionally, every message is output with the time and the corresponding line number in
the original output file. The protocol flow does not contain user data. This user data can only
be found in the original output file.
13.9.2 Diagnosis information for the openUTM-LU62 Gateway
The following information is required when diagnosing errors:
●
The status of the openUTM-LU62 Gateway. Check this using the Management Console.
Select the Check Availability command from the context menu of the openUTM-LU62
Gateway.
The openUTM-LU62 Gateway and its availability are displayed in a table. If the
openUTM-LU62 Gateway is available, you can display detailed information by
double-clicking on this entry or by using the button Result Details.
The following information is relevant:
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
–
LLU-NAME: Alias name of the local LU via which the EIS partner is identified. It
consists of
–
the value specified for the EIS partner in the Management Console in the Prefix
field on the General tab of the Edit Properties of EIS Partner property sheet
–
another generated name part to ensure that names are unique.
–
atot: The number of parallel connections established between the proxy container
and the openUTM-LU62 Gateway.
–
stot: The number of established connections (sessions) between the
openUTM-LU62 Gateway and the CICS application.
The number of control sessions is also output. If the number of control sessions is 0,
then a configuration error has occurred. If atot indicates the value 0, then a configuration error has occurred or the proxy container has not been started. If stot indicates
the value 0, then a configuration error has occurred or the communication service has
not been started or the EIS partner is not running. If stot indicates the value 2, then a
configuration error has occurred and the specified mode is not known in VTAM on the
z/OS.
●
BeanConnect V2.1
The description of the error situation.
427
Diagnosis of the openUTM-LU62 Gateway
●
Logging, diagnostics and troubleshooting
All available diagnosis files:
●
●
On Solaris and Linux systems:
–
instance trace files
/opt/lib/utmlu62/PROT/inlog.<lu_name>.<suff>
–
XAP-TP trace files
/opt/lib/utmlu62/PROT/xaplog.<lu_name>.<suff1>.<suff2>
–
log files
/opt/lib/utmlu62/PROT/prot.<lu_name>
On Windows systems:
–
instance trace files
<gateway_home>\PROT\inlog.<lu_name>.<suff>
–
XAP-TP trace files
<gateway_home>\PROT\xaplog.<lu_name>.<suff1>.<suff2>
–
log files
<gateway_home>\PROT\prot.<lu_name>.txt
Here <lu_name> stands for a local LU alias name, <suff>, <suff1> and <suff2>
are numerical suffixes and <gateway_home> indicates the directory where the
openUTM-LU62 Gateway is installed.
V
If you restart an openUTM-LU62 Gateway, the following diagnostic
files in the subdirectory <gateway_home>/PROT are deleted:
■
in.dump.<lu_name>
■
xaplog.<lu_name>.*
■
xap.dump.<lu_name>.*
■
prot.<lu_name>.old
■
prot.<lu_name>.*.old
■
core.<lu_name>
This means that you must save the diagnostic files before restarting
the openUTM-LU62 Gateway.
The files prot.<lu_name> and inlog.<lu_name>.* are saved with
the suffix .old. On Windows systems, the file prot.<lu_name> has
the additional suffix .txt.
428
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Diagnosis of SNAP-IX for Solaris systems
13.10 Diagnosis of SNAP-IX for Solaris systems
Logging files containing different types of messages and several trace options are provided
for diagnosing SNAP-IX problems.
Messages in log files
SNAP-IX differentiates between three types of messages in log files:
●
Problem
Messages with the type Problem indicate a serious and unexpected event and are
always logged.
●
Exception
Messages with the type Exception indicate events which degrade system performance or which will cause problems or degrade performance in the future.
●
Audit
Messages with the type Audit indicate normal events during the SNAP-IX run.
SNAP-IX traces
SNAP-IX provides several trace options for diagnosing SNAP-IX-specific problems (Line
Tracing, API Tracing, Client-Server-Tracing, TN Server Tracing and Internal Tracing).
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
13.10.1 Diagnosis with the Management Console
You can configure logging and traces for SNAP-IX and evaluate and display message logs
and trace files using the Management Console.
Configuring logging and traces
Select a communication service under the item Communications Services in the
navigation tree or in Communication Service in the proxy's navigation tree and then
choose Edit Properties in the communication service's (in this case SNAP-IX) context
menu. The table Edit Properties of Communication Service Instance lists the defined
values which you are now able to edit.
Check the appropriate options to activate or deactivate logging and traces. Additionally, you
can switch on more detailed versions of audit logging (with the Verbose Audits option) and
of problem and exception logging (with the Verbose Errors option).
If SNAP-IX is running, the change comes into effect when you save the Communication
Service.
BeanConnect V2.1
429
Diagnosis of SNAP-IX for Solaris systems
Logging, diagnostics and troubleshooting
Evaluating logging and traces
SNAP-IX writes the following files to the directory /var/opt/sna/:
●
Audit messages to the logging file sna.aud.
●
Error messages (problem and exception logging) to the logging file sna.err.
●
Line traces in binary form to the trace files sna1.trc and sna2.trc.
To display these files, choose the following nodes in the navigation tree of the proxy:
Advanced Features - Diagnosis - Output - General Diagnostic Info. In the table, select
one of the entries SNAP-IX Audit Log, SNAP-IX Error Log or SNAP-IX Line Trace. Then
click the Show File button.
The Management Console converts a selected trace file to a text file and transfers the
converted text file or the message log file to the local diagnostic path and displays the file
in a Text File panel.
For detailed information, please refer to the SNAP-IX documentation.
430
BeanConnect V2.1
Diagnosis: IBM Communications Server (Linux)
13.11 Diagnosis of the IBM Communications Server for Linux
Logging files containing different types of messages and several trace options are provided
for diagnosing IBM Communications Server problems.
Messages in Log Files
The IBM Communications Server differentiates between three types of messages in log
files:
●
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Problem
Messages with the type Problem indicate serious and unexpected events and are
always logged.
●
Exception
Messages with the type Exception indicate events which degrade system performance or which will cause problems or degrade performance in the future.
●
Audit
Messages with the type Audit indicate normal events during the IBM Communications
Server run.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
IBM Communications Server traces
The IBM Communications Server provides several trace options for diagnosing
IBM-Communications-Server-specific problems (Line Tracing, API Tracing,
Client-Server-Tracing, TN Server Tracing and Internal Tracing).
13.11.1 Diagnosis with the Management Console
You can configure logging and traces for the IBM Communications Server and evaluate and
display message logs and trace files using the Management Console.
Configuring logging and traces
Select a communication service under the item Communications Services in the
navigation tree or in Communication Service in the proxy's navigation tree and then
choose Edit Properties in the communication services (in this case IBM Communications
Server for Linux) context menu. The table Edit Properties of Communication Service
Instance lists the defined values which you are now able to edit.
Check the appropriate options to activate or deactivate logging and traces. Additionally you
can switch on more detailed versions of audit logging (with the Verbose Audits option) and
of problem and exception logging (with the Verbose Errors option).
BeanConnect V2.1
431
Diagnosis: IBM Communications Server (Linux)
Logging, diagnostics and troubleshooting
If the IBM Communications Server is running, the change comes into effect when you save
the Communication Service.
Evaluating logging and traces
The IBM Communications Server writes the following files to the directory
/var/opt/ibm/sna/:
●
Audit messages to the logging file sna.aud.
●
Error messages (problem and exception logging) to the logging file sna.err.
●
Line traces in binary form to the trace files sna1.trc and sna2.trc.
To display these files, choose the following nodes in the navigation tree of the proxy:
Advanced Features - Diagnosis - Output - General Diagnostic Info. In the table, select
one of the entries Communications Server (Linux) Audit Log, Communications Server
(Linux) Error Log or Communications Server (Linux) Line Trace. Then click the Show
File button.
The Management Console converts a selected trace file to a text file and transfers the
converted text file or the message log file to the local diagnostic path and displays the file
in a Text File panel.
For detailed information, please refer to the IBM Communications Server documentation.
432
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Diagnosis: IBM Communications Server (Windows)
13.12 Diagnosis of the IBM Communications Server for Windows
systems
On Windows systems, the IBM Communications Server provides a Log Viewer and a
Trace Facility for diagnosing problems. These tools have graphical user interfaces. You can
start the tools from the relevant program groups.
For detailed information, please refer to the IBM Communications Server documentation.
13.12.1 Diagnosis with the Management Console
You can evaluate and display the message log and the trace log files of the IBM Communications Server using the Management Console.
Configuring logging and traces
Select a communication service under the item Communications Services in the
navigation tree or in Communication Service in the proxy's navigation tree and then
choose Edit Properties in the communication service's (in this case IBM Communications
Server for Linux) context menu. The table Edit Properties of Communication Service
Instance lists the defined values which you are now able to edit.
Check the appropriate options to activate or deactivate logging and traces. Additionally you
can switch on more detailed versions of audit logging (with the Verbose Audits option) and
of problem and exception logging (with the Verbose Errors option).
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
If the IBM Communications Server is running, the change comes into effect when you save
the Communication Service.
Evaluating logging and traces
To display these files, choose the following nodes in the navigation tree of the proxy:
Advanced Features - Diagnosis - Output - General Diagnostic Info. In the table, select
one of the entries Communications Server (Windows) Message Log or Communications Server (Windows) Trace Log. Then click the Show File button.
The Management Console converts a selected trace file to a text file and transfers the
converted text file or the message log file to the local diagnostic path and displays the file
in a Text File panel.
BeanConnect V2.1
433
Collecting diagnostic information
Logging, diagnostics and troubleshooting
13.13 Collecting diagnostic information
BeanConnect provides support for gathering all available diagnostic information in the
proxy with a single mouse click.
In the Management Console, select the command Advanced Features - Diagnosis Output - General Diagnostic Info from the navigation tree of the proxy. Then click the Get
All Files button or select the Get All Files command from the context menu of any table
entry.
A Select File dialog box is opened where you can specify the target directory for the traces
and log files. In this dialog box, a subdirectory of the configured local diagnostic path is
proposed. The name of the subdirectory is built from the current date and time
(<local-diag-path>/<date-time>).
After selection of the target directory, the Management Console starts to collect all available
files with diagnostic information for the BeanConnect proxy and for the proxy components.
If necessary, the files are converted from binary format to text format and then the files are
copied into the target directory. An action dialog box is displayed which provides information
about the progress and the outcome of the action.
434
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages proxy container
13.14 Error messages of the BeanConnect proxy container
This section provides information on the following topics:
●
Configuration error messages
●
Runtime error messages
13.14.1 Configuration error messages
openUTM, on which the BeanConnect proxy container is based, is configured using the
configuration tool KDCDEF. The workflow and input to this tool are controlled by the
Management Console. KDCDEF normally works without any manual intervention by the
user.
V
If you intervene in the configuration process and, for example,
manipulate the KDCDEF input files, successful configuration
can no longer be guaranteed.
Each KDCDEF run is logged with messages to the kdcdef.out file in the def subdirectory
of the proxy container home directory. You will find error messages in this file if they are
available.
The configuration was successful if the process terminated with the message
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
●
K450 KDCFILE generated; KAA size: &KAASIZE K
If errors are detected in the input files or another internal error occurs, the process is terminated with one of the following messages:
●
K448 KDCFILE generated with warnings; KAA size: &KAASIZE K
●
K449 There was at least one ERROR. Generation aborted.
Please inform system service if you cannot identify any connection with manual manipulation of the input files with respect to the preceding error messages.
BeanConnect V2.1
435
Error messages proxy container
Logging, diagnostics and troubleshooting
13.14.2 Runtime error messages
The messages generally indicate problems between the resource adapter and the proxy
container or between the proxy container and the EIS partner or openUTM-LU62 Gateway.
User errors or internal problems in BeanConnect or in the openUTM-LU62 Gateway could
be the reasons for these problems.
13.14.2.1
Types of messages
In BeanConnect, there are three groups of messages:
Group 1
Messages which log normal behavior.
Group 2
Messages which log problems and errors. You
can respond to these messages.Any notes or
actions are described in this document.
Group 3
Internal messages from BeanConnect.
This chapter contains all messages of groups 2 and 3 which can be displayed at runtime of
the proxy container in alphabetical order. Messages of group 1 are not described.
The runtime messages are logged in the files utmp.out.<suffix> and
utmp.err.<suffix> where <suffix> indicates the date and time stamp. The files are
saved in the proxy container home directory.
Each message is preceded by an individual ID. A "&" character precedes the name of an
insert. The description of a message provides the meaning of those inserts needed by the
BeanConnect user. All other inserts are needed by system service for diagnosis. Some
inserts contain information on error codes during file processing (DMS error codes) or on
error codes of the system. These inserts are described in the section "System error codes"
on page 481.
Meaning of the openUTM-specific terms in the BeanConnect proxy container which are
used in the messages:
436
DMS
File access
UTM
openUTM component
UTM-D
Component for distributed communication
XAP-TP
Component for the OSI-TP protocol stack
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages proxy container
Please check the following issues before contacting system service:
●
Does the configuration of the proxy container in the Management Console correspond
to the configuration of the resource adapter, e.g. the values for proxyURL or inboundListenerPort (see the configuration of resource adapter in section "Defining global
properties in ra.xml" on page 89 and the configuration in the Management Console in
section "Configuring the BeanConnect resource adapter" on page 184)?
●
Does the configuration of the proxy container in the Management Console correspond
to the configuration of the EIS partner or openUTM-LU62 Gateway, e.g. the values for
Host and Port?
●
Have the proxy container, all proxy components and the EIS partner been started and
are they available? You can check availability with the Management Console (see the
section "Checking the availability of BeanConnect proxies" on page 263).
The following lists contain the messages which can be issued by BeanConnect. Additional
information has been added to the descriptions to explain the actions (responses) to the
messages:
●
K messages
●
P messages
●
U messages
K messages and U messages are output by default.
If a K message is output, you should take into account the corresponding P or U message
where appropriate.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
P messages only occur during the communication via the OSI-TP protocol, i.e. during
communication between the proxy container and the EIS partner or between the proxy
container and openUTM-LU62 Gateway.
BeanConnect V2.1
437
Error messages proxy container (K messages)
13.14.2.2
Logging, diagnostics and troubleshooting
K messages
BCSYSEX K009 Transaction code &TAC is invalid (&RCDC) - input please
Invalid service name called by an EIS using a UPIC, Socket or RFC1006 connection.
Action: The table below lists the possible error codes together with error causes and
possible error recovery actions. If an error message occurs that is not described in the list
below, inform system service.
Error code &RCDC
&RCDC
Meaning
KM01
The service has not been generated.
Action: Configure an inbound service and assign this service name to the inbound
message endpoint or change the client program.
BCSYSEX K017 Service &TCVG terminated by openUTM (&RCCC/&RCDC &RCF2A) - input
please
An inbound transaction was rolled back.
Action: Normal behavior if &RCCC is 70Z and &RCDC is K306. Otherwise inform system
service.
K036 Connection setup: &PTRM/&PRNM/&BCAP/&LTRM &RSLT, &REA1
BeanConnect outputs the message when the connection from the resource adapter to the
proxy container is set up.
&RSLT
Meaning
Y
Connection set up.
N
Connection was not set up; the cause is given in &REA1.
&REA1
Meaning
X' 00'
Connection already set up.
X' 0A'
BeanConnect proxy container shut down.
Action: Start the BeanConnect proxy container.
X' 0C'
Connection cleardown being executed.
Action: Repeat the request.
X' 12'
No further free entry available in terminal pool.
Action: Depends on the insert &LTERM.
438
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages proxy container (K messages)
&REA1
Meaning
X' 1B'
The IP address of the EIS partner could not be determined
Action: Check EIS partner host and /or inform network administration
X' 2E'
The connection has not yet been completely cleared down.
Action: Repeat the request.
&LTERM
Meaning
BCRA
Action: Increase the Number of Parallel Outbound Connections in the
Performance Settings tab of the Edit Properties of Proxy property sheet in the
Management Console.
BCUP
Action: Increase the Number of Parallel Inbound UPIC Connections in the
Performance Settings tab of the Edit Properties of Proxy property sheet in the
Management Console.
BCSO
Action: Increase the Number of Parallel Inbound Socket Connections in the
Performance Settings tab of the Edit Properties of Proxy property sheet in the
Management Console.
K040 Warning level &WLEV for page pool no longer exceeded
The proxy container storage area size (page pool) is reduced again because messages
have been sent or executed.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
K041 Warning level &WLEV for page pool exceeded
Action: Increase the Proxy Container Storage Area Size (Page Pool) in the Performance
Settings tab of the Edit Properties of Proxy property sheet using the Management
Console and carry out the todo topics which are shown in the todo topic list of the
Management Console.
K043 DMS error &DMSE for file &FNAM
The DMS error code is output in insert &DMSE.
Action: The possible DMS error codes are described in the section "Error codes" on
page 480. Alternatively inform system service.
BeanConnect V2.1
439
Error messages proxy container (K messages)
Logging, diagnostics and troubleshooting
K049 Error = &RCCC2 during application startup
The BeanConnect proxy container issues message K049 whenever the start of a container
task is aborted due to an error. The error code &RCCC2 shows the cause of the error.
Action: The table below lists the possible error codes together with error causes and
possible error recovery actions. If an error message occurs that is not described in the list
below, inform system service.
Error code &RCCC2
440
Code Error cause
Action
20
Shared memory cannot be allocated by the first
task of the BeanConnect proxy container due to
insufficient address space.
Check system generation.
21
Shared memory cannot be allocated by the first
task of the BeanConnect proxy container due to
insufficient address space or due to the proxy
container being terminated.
As for 20 or normal behavior.
22
File access error.
See DMS error code, section "Error
codes" on page 480.
24
File access error.
See DMS error code, section "Error
codes" on page 480.
32
The task lock bourse could not be created. This
error occurs when there are too few semaphore
entries available for the BeanConnect processes.
This can occur when the termination of a process
and its restart overlap.
Start again with a larger number of
semaphores (see the section
"Number of semaphores in the
proxy container" on page 381).
33
BeanConnect refuses to start more tasks for the
proxy container because the proxy container has
already terminated (normal or abnormal
termination).
Normal behavior.
35
While restarting a proxy container task,
BeanConnect detects that the proxy container is
being aborted.
Normal behavior.
50
As for 20.
Check system generation.
55
DMS error with KDCA file.
See DMS error code, section "Error
codes" on page 480.
56
DMS error with page pool file.
See DMS error code, section "Error
codes" on page 480.
57
DMS error with restart file.
See DMS error code, section "Error
codes" on page 480.
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages proxy container (K messages)
Code Error cause
Action
58
Delete (if necessary) and
regenerate the prepared SYSLOG
file in the <proxy_cont_home>
directory with following commands:
Error with the SYSLOG file of the BeanConnect
proxy. Possible causes:
The <proxy_cont_home>/SYSLOG directory is
not correct.
●
Solaris and Linux:
. ./initenv.sh
$UTMPATH/ex/kdcslog . 20
●
Windows:
initenv.cmd
%UTMPATH%\ex\kdcslog . 20
59
Error when opening SYSLOG file.
See DMS error code, section "Error
codes" on page 480.
79
A BeanConnect proxy container task makes a
request, but it runs out of memory.
Check system generation.
84
Insufficient memory.
Check system generation.
85
Insufficient memory.
Check system generation.
91
Error when starting BeanConnect proxy
container. You can find a detailed description of
the error under message K124.
See message K124 on page 451.
An asynchronous inbound transaction was rolled back and the asynchronous inbound
message will be redelivered if necessary.
Action: Normal behavior when KCRCCC is 000 and KCRCDC is 0000 or KCRCCC is 70Z
and KCRCDC is K306. Otherwise inform system service.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
K055 Asynchronous service &ATAC1 terminated by openUTM; KCRCCC=&RCCC;
KCRCDC=&RCDC;user=&USER; LTERM=&LTRM
BeanConnect V2.1
441
Error messages proxy container (K messages)
Logging, diagnostics and troubleshooting
K060 Application run aborted; reason = &TRMA
BeanConnect creates a memory dump whenever a proxy container application is aborted
or a dump requested. Such a dump is produced for each work process of the proxy
container.
The Group column in the table below describes the reason group to which the dump error
code (&TRMA) belongs. The following groups exist:
A
The cause is a user error, e.g. an error in
●
generating and administering proxy container applications with the Management
Console
●
generating the system (e.g. division of the address space)
D
The dump was created for diagnostic purposes.
F
The dump is a continuation dump, another task has caused the BeanConnect proxy
container to terminate abnormally.
M
The cause is a memory bottleneck.
U, S, X
The cause is an internal error in BeanConnect.
If an error message occurs that is not described in the list below, inform system service.
Code
Group
Reason
ALGxxx
ASU
Shared memory bottleneck.
Action: Tune the system kernel.
ASA061
F
The BeanConnect network process is no longer active.
See also the comments for U3xx of the BeanConnect proxy container
Action: Check the BeanConnect proxy generation.
ASIS99
D
BeanConnect proxy container was terminated abnormally by the
administrator.
BRSREM F
BeanConnect proxy container was terminated abnormally by the
administrator.
CACHT1
through
CACHT6
After a process has initiated the abnormal termination of the
BeanConnect proxy container, another task of the BeanConnect proxy
container has terminated abnormally itself (= continuation dump).
F
Action: Depends on the reason for the abnormal termination of the proxy
container.
442
DIAGDP
D
A diagnostic dump has been generated. The BeanConnect proxy
container is running normally.
ENDE14
F
As for code CACHT1.
BeanConnect V2.1
Error messages proxy container (K messages)
Code
Group
Reason
ENDPET
A
The BeanConnect proxy container cannot be terminated normally
because distributed transactions still exist with the status preliminary end
of transaction.
The transaction can be terminated after the BeanConnect proxy container
has been restarted. Additionally, a connection to the EIS partners that are
involved in the distributed transactions must exist.
Action: Restart the BeanConnect proxy container.
FMMM10 A
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
An input message cannot be stored because the page pool is full.
IOyxxx
ASU
An unrecoverable error has occurred during file processing, yxxx = DMS
error code, see the section "Error codes" on page 480.
IPC035
A
Error on locking the IPC shared memory segment. This may be caused
by the remove script being called or by a Forced Clear while the
BeanConnect proxy container is still running.
IPC037
FU
After a process has initiated abnormal termination of the BeanConnect
proxy container, another task of the BeanConnect proxy container has
terminated abnormally itself (= continuation dump).
IPCEND
FU
After a process has initiated abnormal termination of the BeanConnect
proxy container, another process of the BeanConnect proxy container has
terminated abnormally itself (= continuation dump).
IPCREM
F
The BeanConnect proxy container was terminated abnormally with the
remove script or Forced Clear.
© cognitas GmbH
ISLPT1
through
ISLPT4
F
As for code CACHT1.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
Action: Increase the Proxy Container Storage Area Size (Page Pool) in
the Performance Settings tab of the Edit Properties of Proxy property
sheet in the Management Console.
LATCT1
F
As for code CACHT1.
JVMABT
The JVM has initiated the abnormal termination of the BeanConnect
proxy container, see also file hs_err*.log in the container directory
LCACT1
F
As for code CACHT1.
LKAA04
US
As for code CACHT1.
LKAAT1
F
As for code CACHT1.
LKLCT1
through
LKLCT4
F
As for code CACHT1.
LPCMT1
F
As for code CACHT1.
OSAFT2
F
As for code CACHT1.
BeanConnect V2.1
443
Error messages proxy container (K messages)
Logging, diagnostics and troubleshooting
Code
Group
Reason
OSTM07
A
A log record for a distributed transaction cannot be backed up, since the
page pool is full.
Action: Increase the Proxy Container Storage Area Size (Page Pool) in
the Performance Settings tab of the Edit Properties of Proxy property
sheet in the Management Console.
PCMM05
AU
The page pool is full.
Action: Increase the Proxy Container Storage Area Size (Page Pool) in
the Performance Settings tab of the Edit Properties of Proxy property
sheet in the Management Console.
PEND02
A
No further data can be written because the page pool is full.
Action: Increase the Proxy Container Storage Area Size (Page Pool) in
the Performance Settings tab of the Edit Properties of Proxy property
sheet in the Management Console.
PENDER
AUD
A dump was created after abnormal termination of a transaction. Before
this, the message K017 or K055 was output. The proxy container is still
running normally.
PENDT1
PENDT2
F
As for code CACHT1.
PUTR01
AU
Error on writing to file.
Possible reason: Disk storage bottleneck.
PWRT03
AU
Memory bottleneck.
Action: Check memory requirements and operating system generation.
PWRT06
AU
As for code CACHT1.
RESTRT
D
The diagnostic dump is taken with a restart of the BeanConnect proxy
container after an abnormal termination.
SACT08
MU
SACT28
M
Memory bottleneck.
Action: Modify the value for OSI-SCRATCH-AREA in the proxy container
and update the configuration files of the proxy container. Otherwise inform
system service. For details see Chapter 12, "High availability and
scalability".
SHM002
A
The shared memory key is not unique on the host. This may be an
inherited error from K078 OSS 03.
Action: Check the proxy container generation.The used shared memory
keys are written to the
<proxy_cont_home>/def/input.system.txt file. Parameter: MAX *SHMKEY.
The shared memory keys depend on the generated port number. If
necessary, you must generate the proxy container with another port
number.
444
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages proxy container (K messages)
Code
Group
Reason
SLOG09
SU
Problem when writing the message buffer to the current SYSLOG file.
Action: The DMS error code in the preceding K043 message may explain
the cause of the error. Otherwise inform system service.
SLOG10
SU
An attempt by a continuation work process to switch over to the current
SYSLOG file generation has failed.
Action: It may be necessary to take into account any preceding K043
messages. Otherwise inform system service.
SMSG03
ASU
Problem when writing the message buffer to the current SYSLOG file.
Action: The DMS error code in the preceding K043 message may explain
the cause of the error. Otherwise inform system service.
STnnnn
ADSU
Error when processing the start of a proxy container task, where nnnn is
the number indicating the error cause in the message "K049 Error nnnn
during application startup".
Processes of the BeanConnect proxy container that are still active
continue running.
WAIT41
ASU
Problem when connecting to the network. See also the corresponding
message U3xx of the BeanConnect proxy container.
Action: Check the BeanConnect proxy container generation
F
As for code CACHT1.
XATT02
F
As for code CACHT1.
XFGE01
F
As for code CACHT1.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
WAITT1
WAITT2
BeanConnect V2.1
445
Error messages proxy container (K messages)
Logging, diagnostics and troubleshooting
K065 Net message: &PTRM/&PRNM/&BCAP/&LTRM &FIL1B &FIL2B
Action: Depends on the values FIL1B and FIL2B.
The inserts &FIL1B and &FIL2B have the following meaning:
FIL1B
Meaning
X' F0' - X' FF' Normal behavior.
other
See actions for FIL2B.
FIL2B
Meaning
Actions
00000008
Invalid parameter.
Inform system service.
00000014
Connection letter too long.
Inform system service.
00000030
Internal error.
Inform system service.
0400001C
Resource bottleneck.
Inform system service.
04000020
BeanConnect proxy container not signed Inform system service.
on.
30000020
Error signing on.
Inform system service.
other
Connection-specific events.
Normal behavior.
K075 Program exchange aborted by the task &Process; &CTYP &PROG &PVER
Action: Inform system service.
446
BeanConnect V2.1
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages proxy container (K messages)
K078 ffffffff yyyyyyyyy
Meaning of the parameters:
ffffffff
Contains a short code for the error that has occurred (see table below).
yyyyyyyyy
Specific, context-related error message.
If an error code ffffffff occurs that is not described in the list below, inform system service.
ffffffff
Reason
Actions
ALME 01
Memory bottleneck on application start.
Check memory requirement, tune
operating system.
ATEXIT 00 - 04 Process termination.
Information message.
DIAG 01 - 07
Information about the process
environment.
Information message.
ENV 00 - 04
Information about the process
environment.
Information message.
IPC 02
Memory bottleneck when creating the
IPC shared memory.
Tune system kernel parameter.
IPC 03 - 07
Information about the dimension of the
IPC shared memory.
Information message.
MEM 01
Memory bottleneck when starting the
application. Full text:
Check storage requirements; tune
operating system.
K078 MEM 01 in utmwork nn Bytes not
available.
MSG 01 - 02
Information about the process
environment.
Information message.
NET 01 - 02
Information about the process
environment.
Information message.
OSS 01
Information about the OSS shared
memory.
Information message.
OSS 03
Error while loading the OSS shared
memories into the address space.
Check storage requirements; tune
operating system.
PIPE 01
Information about the process
environment.
Information message.
BeanConnect V2.1
447
Error messages proxy container (K messages)
Logging, diagnostics and troubleshooting
ffffffff
Reason
Actions
SEM 01
Error while creating a semaphore. A
semaphore is not unique on the host.
Check the proxy container
generation. The semaphore keys
depend on the generated port
number. The used semaphore keys
are written to the file
<proxy_cont_home>/
def/input.system.txt
(MAX SEMARRAY). Change the first
value in the brackets or you must
generate the proxy container with
another port number.
SIGNAL 01 02
Signal handling in utmwork process.
Information message.
SYSPROT 01 - Information about the process
02
environment.
Information message
K104 UTM-D TIMEOUT (&RCVDANNO): &LSES, &LPAP, &AGUS; old state: ( &OCVST,
&OTAST );
action: &ACTION; new state: ( &NCVST, &NTAST ).
Reason: Timeout during communication between the proxy container and the EIS partner.
Action: Depends on the value of RCVDANNO.
ACTION
Meaning
ASYNCH
Timeout during asynchronous communication: Either the association occupancy
timer or the reply timer has expired.
STPROG
Timeout during outbound dialog communication without any impact on the
transaction.
COMMIT
RESET
Timeout during outbound/inbound communication: The transaction is either
committed (COMMIT) or rolled back (RESET).
RCVDANNO
(Bytes 1-2)
Meaning
X'F331
A timer has expired during inbound communication after the sending of a response
to the EIS.
Action: Use the Management Console to increase the value of Transaction
Communication Timer in the Timer Settings tab of the Edit Properties of Proxy
property sheet.
448
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages proxy container (K messages)
RCVDANNO
(Bytes 1-2)
Meaning
X'F332'
A timer has expired during outbound communication after all the EIS partners
involved in the distributed transaction have been requested to initiate termination of
the transaction.
Action: Use the Management Console to check and, if necessary, increase the
value for Reply Timer in the Edit Properties of an Outbound Service property
sheet for all the outbound services involved in the transaction.
X'F332'
The ready timer has expired during inbound communication via OSI-TP.
Action: Use the Management Console to increase the value of Prepare to Commit
Timer in the Timer Settings tab of the Edit Properties of Proxy property sheet.
X'F400'
The OSI-TP association occupancy timer for a dialog job has expired during
outbound communication.
X'F520'
The OSI-TP association occupancy timer for an asynchronous job (internal timer of
60 seconds) has expired during outbound communication.
X'F522'
The timer which monitors reception of acknowledgment of an asynchronous
message sent via an OSI-TP association during outbound communication has
expired.
X'F534'
The response timer has expired during outbound communication for a dialog job.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
Action: Use the Management Console to increase the value for Reply Timer in the
outbound service's Edit Properties of an Outbound Service property sheet.
BeanConnect V2.1
449
Error messages proxy container (K messages)
Logging, diagnostics and troubleshooting
K119 OSI-TP error information: &OSLPAP, &USER, &TAC, &DIA1, &DIA2, &DIA3
The inserts &DIA1, &DIA2, &DIA3 contain the reasons for outputting message K119.
Reason with openUTM: The dialog with the EIS partner was terminated.
Reason with CICS: The dialog with the proxy component openUTM-LU62 Gateway was
terminated.
Action: See the table below.
&DIA1
&DIA2
&DIA3
Meaning
01
06
02
No free connection available.
Action: Increase the number of connections in the General tab of
the Edit Properties of an EIS Partner property sheet in the
Management Console.
02
02
01
Outbound communication: The outbound service is not known in
the EIS.
Action: Harmonize the partner service name specified in the
outbound service with the service name generated in the EIS.
02
03
18
Outbound communication: The EIS partner has rejected
auhentication with the specified security credentials.
Action: Check the configuration or programming.
02
03
19
Outbound communication: The EIS partner has rejected the
OSI-TP dialog because the partner LPAP which represents the
proxy container in the EIS partner is locked or is in QUIET state.
02
03
21
Outbound communication: Memory bottleneck at the EIS partner.
02
03
22
Outbound communication: The outbound service is not known in
the EIS partner or is locked or there is no authorization.
Possible action: Harmonize the partner service name specified in
the outbound service with the service name generated in the EIS.
02
03
23
Outbound communication: The outbound service is known in the
EIS partner but cannot be called.
02
03
24
Outbound communication: The queue level for the asynchronous
outbound service has been reached at the EIS partner.
02
03
25
Outbound communication: The dialog-based outbound service is
configured as an asynchronous service in the EIS partner.
03
03
18
Inbound communication: The user employed by the EIS partner for
the dialog is not configured in the proxy container or the employed
password is false.
Action: Check the configuration.
450
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
&DIA1
&DIA2
&DIA3
Meaning
04
02
00
01
The EIS partner has terminated the dialog.
21
Inbound communication: The proxy container storage area (page
pool) is full.
03
03
© cognitas GmbH
Action: See the messages in the EIS partner.
Action: In the Management Console, increase the value of
Pagepool in the Performance Settings tab in Proxy Container
Storage Area Size in the Edit Properties of Proxy property sheet
i
09
09
03
03
21
31
10
11
xx
No free connection available
12
xx
13
xx
Action: In the Management Console, increase the number of
connections (Connections) in the General tab of the Edit
Properties of an EIS Partner property sheet.
15
xx
16
xx
17
xx
10
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
Error messages proxy container (K messages)
The proxy container storage area (page pool) is full.
Action: In the Management Console, increase the value of
Pagepool in Proxy Container Storage Area Size in the
Performance Settings tab of the Edit Properties of Proxy
property sheet
An inbound dialog process is active for every connection to the EIS
partner and another inbound process is received on a connection
that was closed and newly generated during this time.
Action: Increase the reply timer in the Edit Properties of an
Outbound Service property sheet in the Management Console.
The specified value must be greater than the reply timer in the EIS
partner
other values
Inform system service.
K124 Error: &RCXAPTP at startup of XAP-TP occurred in phase: &PHAXAPTP
Action:
For RCXAPTP = 106: Possible cause: Work process could not be started because proxy is
already shut down
Otherwise: Inform system service.
BeanConnect V2.1
451
Error messages proxy container (K messages)
Logging, diagnostics and troubleshooting
K128 UTM-D job rejected: &CON/&PRNM/&BCAP/&LPAP &LSES &REA1 &RCDC &TAC
Meaning of the inserts with openUTM:
Insert
Meaning
&CON
OSI-CON name
&PRNM
Eight blanks
&BCAP
ACCESS-POINT name
&LTRM
OSI-LPAP name
The insert &REA1 contains the reason that message K128 was output.
&REA1
Meaning
Action
X' 01'
Invalid service name called by an EIS using an
OSI-TP connection.
If &RCDC=KM01:
Configure an inbound message
endpoint and assign this service
name to the inbound message
endpoint or change the OSI-TP
client.
Otherwise inform the system
service.
X' 02'
Service name is generated with an error.
Inform system service.
- Recipient tpsu title in TP-BEGIN-DIALOGUE-RI
X' 03'
An asynchronous service is to be started, the
service which is assigned to the message
endpoint is configured as a dialog-orientated
service.
- Receipt of a TP-END-DIALOGUE-RI protocol
element
Check whether the OLTP
message-driven bean implements
the asynchronous interface and
maybe enter the inbound message
endpoint with the asynchronous
service again.
Or change the OSI-TP client.
X' 04'
A dialog-orientated service is to be started, the
service which is assigned to the message
endpoint is configured as an asynchronous
service.
Check whether the OLTP
message-driven bean implements
the dialog-orientated interface and
maybe enter the inbound message
endpoint with the dialog-orientated
service again.
Or change the OSI-TP client.
X' 05'
An asynchronous service is to be started, but the
message queue of the service has reached the
generated threshold.
Inform system service.
- The connection is cleared down.
452
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages proxy container (K messages)
K135 UPIC message: &PTRM/&PRNM/&BCAP/&LTRM/&UPCREAS/&UPCSTAT/
&UPCPROT/&UPVENC1/&UPPENC2
Action if UPCREAS = 0D:
Increase the proxy container storage area size in the Performance Settings tab of the
Edit Properties of Proxy property sheet in the Management Console.
Action if UPCREAS ≠0D: Inform system service.
K139 Switching SYSLOG failed! Still using file &FNAM
Action: It may be possible to ascertain the reason for the error that occurred on switchover
from the DMS error code in the preceding message K043. Otherwise inform system
service.
K147 Sign on for &USRTYPE user &USER not successful &PTRm/&PRNM/&BCAP/&LTRM
Reason: &REA7
Reason: Depends on the &USER value.
&USER
Reason
BCUxxxxx
Outbound communication: Problems during communication between the resource
adapter and the proxy container.
BCADMIN
Administration: Problems communicating with the proxy container in the
Management Console.
© cognitas GmbH
other
Inbound communication: Problems during communication between the EIS
partner and the proxy container.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
BCURAxxx Outbound communication in a cluster configuration or in multiple resource adapter
mode.
If REA7=U3: Normal behavior
Otherwise: Problems during communication between the resource adapter and
the proxy container
Action: Depends on the &REA7 value.
&REA7
Meaning
U1
Inbound: The USER that is used for the dialog by the EIS partner is not
configured in the proxy container. See section "Configuring inbound
communication" on page 219.
Outbound: Internal error. Inform system service.
U3
Inbound: You have tried to start more than one parallel dialog with the same user
and without commit functionality.
Outbound: Internal error. Inform system service.
BeanConnect V2.1
453
Error messages proxy container (K messages)
Logging, diagnostics and troubleshooting
&REA7
Meaning
U4
Inbound: The password used for the dialog by the EIS partner is not configured in
the proxy container. See section "Configuring inbound communication" on
page 219.
Outbound: Internal error. Inform system service.
Administration: An incorrect password is specified in the Management Console for
access to the proxy container.
U17
The administrator has started termination of the proxy container. It is therefore not
possible to start the dialog.
other
Inform system service.
K152 Heuristic report: &COND &MTYPE &OLPAP &USER &LTAC &AAIS &AAID
Action: Depends on the &COND value.
&COND
Meaning
MIX
Inbound: The application server and the EIS partner are not synchronized with
respect to transaction security.
Possible database inconsistency. To coordinate this, manual contact to one of the
involved databases is required.
Outbound: The EIS partner has detected a heuristic MIX.
HAZ
The application server has rolled back the transaction. The termination of this
transaction (commit/rollback) is unknown in the EIS partner.
Possible database inconsistency. To coordinate this, manual contact to one of the
involved databases is required.
K160 The &TACNTR. transaction of the &TCVG service was reset by &RBCAUSER
(&RCCC/&RCDC); (pid: &TASK).
If &TCVG = KDCGIOPU, there is an outbound communication process.
For inbound communication &TCVG contains the service name that is assigned to the
message endpoint in the Management Console.
Action with openUTM: Normal behavior, see the process in the resource adapter or EIS
partner.
Action with CICS: Normal behavior, see the process in the resource adapter or proxy
component openUTM-LU62 Gateway.
K204 XA (&PID) Precommit requires global rollback; cause: &XATXT TA= &INTTAID
Action: Inform system service.
454
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages proxy container (K messages)
K210 XA (&PID) Return code: &XATXT Open RM &TEXT32, &INSTNUM
Action: Inform system service.
K211 XA (&PID) Return code: &XATXT Close RM &TEXT32, &INSTNUM
Action: Inform system service.
K212 XA (&PID) xa_start( &XAFLAG) - Return code &XATXT TA= &INTTAID
Action: Inform system service.
K213 XA (&PID) xa_end( &XAFLAG) - Return code &XATXT TA= &INTTAID
Action: Inform system service.
K214 XA (&PID) xa_commit() - Return code &XATXT TA= &INTTAID
Cause: Normal behavior if no abnormal termination of the proxy container follows.
Action: Inform system service on abnormal termination.
K215 XA (&PID) xa_rollback() - Return code &XATXT TA= &INTTAID
Cause: Normal behavior if no abnormal termination of the proxy container follows.
Action: Inform system service on abnormal termination.
K216 XA (&PID) Return code &XATXT, recover PTC list, RM: &TEXT32,&INSTNUM
Cause: Normal behavior if no abnormal termination of the proxy container follows.
Action:
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
●
Abnormal termination during the start-up phase may be caused by a faulty connection
to the resource adapter (e.g. incorrect port number or invalid protocol between the proxy
container and the resource adapter). The cause is described in more detail in the
messages in the log files utmp.err.* and utmp.out.* as well as in the proxy
container's logging file. If an incorrect port number has been assigned to the resource
adapter then this can be set correctly using the Management Console. It is possible to
restart the proxy container.
If the BeanConnect proxy container and the resource adapter have different versions,
the resource adapter clears the connection and the proxy container is therefore terminated while still in the start-up phase. The comment on the incorrect version designation
is logged in resource adapter logging.
●
If the cause of abnormal termination during the start-up phase cannot be identified as
described above, please inform the system service.
K217 XA (&PID) xa_prepare() - Return code &XATXT TA= &INTTAID
Cause: Normal behavior if no abnormal termination of the proxy container follows.
Action: Inform system service on abnormal termination.
BeanConnect V2.1
455
Error messages proxy container (K messages)
Logging, diagnostics and troubleshooting
K218 XA (&PID) xa_forget() - Return code &XATXT TA= &INTTAID
Cause: Normal behavior if no abnormal termination of the proxy container follows.
Action: Inform system service on abnormal termination.
K220 XA (&PID) Error: xa_switch definition not found for specified RM: &TEXT32
Action: Inform system service.
K221 XA (&PID) Error: Start parameters not found for defined RM: &TEXT32
Action: Inform system service.
K222 XA (&PID) Error: Linked RM is not &XASPEC compatible &TEXT32
Action: Inform system service.
K223 XA (&PID) Syntax error in start parameters
Action: Inform system service.
K224 XA (&PID) &XACALL - return code &XASTAT from RM instance &INSTNUM, &TEXT32
is not XA(CAE) compliant
Action: Inform system service.
K225 XA (&PID) recursive call: &XADBC1 - Error/signal in DB/XA connection for &XADBC2
Action: Inform system service.
K230 XA (&PID) Int. error: &TEXT32
Action: Inform system service.
K231 XA (&PID) Int. error: PETA not supported
Action: Inform system service.
K232 XA (&PID) Int. error: DBSTAT secondary opcode inconsistent
Action: Inform system service.
456
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
13.14.2.3
Error messages proxy container (P messages)
P messages
All messages from the OSI-TP protocol stack start with the letter “P”.
P messages with openUTM occur between the proxy container and the EIS partner.
P messages with CICS can occur in the proxy container or in the openUTM-LU62 Gateway.
If the term "proxy component" is used for the description of the P message, the proxy
container or the openUTM-LU62 Gateway is meant, depending on the component where
the message occurred.
P001 Error on OSS call (&XPFUNC): &XPRET, &XPERR, &XP1INFO, &XP2INFO
Error on OSI-TP communication between the proxy container and the EIS partner or
between the proxy components.
If the error has been reported by the transport system, message P012 is also output.
Action: Inform system service.
P002 Error on association establishment (&XPFUNC): &ACPNT, &OSLPAP, &XPRET,
&XPERR, &XP1INFO, &XP2INFO
Error on OSI-TP connection generation between the proxy container and the EIS partner or
between the proxy components.
If the error has been reported by the transport system, message P012 is also output.
Action: Inform system service.
P003 Association rejected (a_assin() ): &ACPNT, reason: &XPRJCT, length: &XPLTH
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
Action: Inform system service.
P004 Association rejected (a_assin() ): &ACPNT, &OSLPAP, reason: &XPRJCT
This message is issued if a request to establish an association was rejected by the EIS
partner.
Action: See the table below.
XPRJCT Action
1 - 16
17
Inform system service.
Unknown partner application.
Action: Check the generation in the proxy container and in the EIS system openUTM
resp. in the proxy components. Possibly the generation input which is generated by
the Management Console was not activated at one of the partners or at the
components.
18 - 33
BeanConnect V2.1
Inform system service.
457
Error messages proxy container (P messages)
Logging, diagnostics and troubleshooting
XPRJCT Action
34 - 35
Configuration problem. A different number of connections was generated on both
sides.
Action: Check the generation in the proxy container and in the EIS system openUTM
resp. in the proxy components. Possibly the generation input which is generated by
the Management Console was not activated at one of the partners or at the
components.
36 - 39
Inform system service.
40
Timeout during connection establishment. Connection establishment was started but
could not be completed in the specified time.
Action with openUTM partner: See the messages of the EIS partner. Alternatively,
inform system service.
Action with CICS partner: See the messages of the EIS partner and the proxy
components and try to find out which component did not respond. Alternatively,
inform system service.
41 - 46
Inform system service.
P005 Association rejected (a_assin() ): &ACPNT, reason: unknown partner,
partner address:
This message is issued if a request to establish an association was rejected from outside
because the remote partner is not known to the local application.
Action: Check the generation in the proxy container and in the EIS system openUTM resp.
in the proxy components. Possibly the generation input which is generated by the
Management Console was not activated at one of the partners or at the components.
P006 Association rejected (a_assin() ): &ACPNT &OSLPAP, reason: wrong application
context name (&XP0OBID, &XP1OBID, &XP2OBID, &XP3OBID, &XP4OBID,
&XP5OBID, &XP6OBID, &XP7OBID, &XP8OBID, &XP9OBID)
This message is issued if a request to establish an association was rejected from outside.
The application context name for the remote partner does not match the application context
name generated for this partner in the local application.
Action: Check the generation in the proxy container and in the EIS system openUTM resp.
in the proxy components. Possibly the generation input which is generated by the
Management Console was not activated at one of the partners or at the components.
P007 Error on association establishment ( a_assrs() ): &ACPNT, &OSLPAP, &XPRET,
&XPERR, &XP1INFO, &XP2INFO
This message is output when a request to establish an association from outside returns an
error. If the error has been reported by the transport system, message P012 is also output.
Action: Inform system service.
458
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages proxy container (P messages)
P008 Association established: &ACPNT, &OSLPAP
This message is issued when an association has been established.
Action: Normal behavior.
P009 Association rejected (a_asscf() ): &ACPNT, &OSLPAP, reason: &XPRJCT,
length: &XPLTH
This message is issued when active establishment of an association is rejected because
the confirmation from the communication partner cannot be accepted.
Action: Inform system service.
P010 Association rejected (a_asscf() ):
&ACPNT,
&OSLPAP,
reason: unknown
partner address: &PARTADDR
(&XASSREF)
This message is issued when active establishment of an association is rejected because
the remote partner confirms establishment of an association with an address which is
unknown to the local application.
Action: Inform system service.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
P011 Association rejected (a_asscf() ): &ACPNT &OSLPAP, reason: wrong application
context name (&XP0OBID, &XP1OBID, &XP2OBID, &XP3OBID, &XP4OBID,
&XP5OBID, &XP6OBID, &XP7OBID, &XP8OBID, &XP9OBID)
This message is issued when active establishment of an association is rejected because
the remote partner confirms establishment of an association with an application context
name other than the one configured for this partner in the local application.
Action: Check the generation in the proxy container and in the EIS system openUTM resp.
in the proxy components. Possibly the generation input which is generated by the
Management Console was not activated at one of the partners or at the components.
P012 CMX diagnostic information: &XPCTYPE, &XPCCLS, &XPCVAL
Action:
XPCVAL > 15: Error code from the transport system. Inform system service.
XPCVAL <other value>: Inform system service.
BeanConnect V2.1
459
Error messages proxy container (P messages)
Logging, diagnostics and troubleshooting
P013 Association rejected ( a_asscf() ): &ACPNT, &OSLPAP, reason: &XPCRES,
&XPSRC, &XPNDIA, CCR V2 = &XP1BOOL, Version Incompatibility = &XP2BOOL,
ContWin Assignment rejected = &XP3BOOL, Bid mandatory rejected =
&XP4BOOL, No reason = &XP5BOOL
This message is issued when active establishment of a connection to the EIS system resp.
between the proxy components is rejected by the remote partner.
Action:
If XP1BOOL, XP2BOOL or XP4BOOL are set to TRUE: Inform system service.
If XP3BOOL = TRUE: Temporary shortage concerning the number of connections.
If XP5BOOL = TRUE: Action depends on XPNDIA, see the table below.
XPNDIA Action
1
Inform system service.
2 - 10
Configuration problem.
Action: Check the generation in the proxy container and in the EIS system openUTM
resp. in the proxy components. Possibly the generation input which is generated by
the Management Console was not activated at one of the partners or at the
components.
With openUTM partners: Check that the host name specified in the Management
Console for the EIS partner corresponds to the host name used in the connection
request. In the event of an error, the correct name is output in message U315 of the
proxy container. If message U315 contains the value *ANY for the host name, you
must add the host name of the openUTM partner application to the host file of the
system.
11 - 24
Inform system service.
P014 Error on association disconnection ( &XPFUNC ): &ACPNT, &OSLPAP,
&XPRET, &XPERR, &XP1INFO, &XP2INFO
Action: Inform system service.
460
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages proxy container (P messages)
P015 Association disconnected ( &XPFUNC ): &ACPNT, &OSLPAP, &XPLNK,
&XPSRC, &XPNDIA, &XPINI, &XP1INFO, &XP2INFO
This message is issued when an OSI-TP association is cleared.
Action: See the table below.
XPINI
Meaning
0
Normal behavior.
401
The local transport system has cleared the association. The subsequent message
P012 contains the detailed CMX return code.
402
openUTM partner:
The EIS partner's transport system has cleared the connection.
CICS partner: The openUTM-LU62 proxy component's transport system has cleared
the connection.
&XP1INFO contains the reason for the connection cleardown.
The following is a subset of &XP1INFO values:
0 (T_USER)
The communication partner cleared the connection, possibly as a result of a user
error on the partner side.
258 (T_RSAP_NOTATT)
The partner cleared the connection because the addressed communication endpoint
was not registered there.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
482 (T_RLNOCONN)
The local transport system could not establish the connection because no network
connection is available.
403 406
Inform system service.
407
The originator is the local proxy component.
408
The EIS partner or the proxy component openUTM-LU62 Gateway initiated the
abort.
BeanConnect V2.1
461
Error messages proxy container (P messages)
Logging, diagnostics and troubleshooting
P016 Association disconnected ( a_relin() ): &ACPNT, &OSLPAP, &XPLNK, &XPNDIA
This message is issued if an association is cleared because a "release indication" was
received.
Action: See the table below.
XPNDIA Meaning
0
NO_REASON_GIVEN
21 - 23
The association is cleared by the EIS partner or by the partner proxy component
with release.
P017 OSS decoding error: &XPDU, &XP1DIA, &XP2DIA, &XP3DIA
Action: Inform system service.
P018 FSM protocol error: &ACPNT, &OSLPAP,
&XPPTYP, &XPFSMN
Action: Inform system service.
P019 APDU contains invalid value: &ACPNT, &OSLPAP,
&XPAPDU, &XP3INFO
Action: Inform system service.
462
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
13.14.2.4
Error messages proxy container (U messages)
U messages
U184 DMS error &DMSE for file &FNAM
Action: See the DMS error code in the section "Error codes" on page 480 or inform system
service.
U185 kdcdef not allowed during application run
Action: User error. You can update the proxy container configuration only after you have
stopped the proxy container.
U189 &OBJ1 ( &PTRM, &PRNM ): IPC shortage of &IPCOBJ &IPCREAS
Action: For the meaning of the inserts &IPCOBJ and &IPCREAS see the table below. For
inserts which are not contained in the table inform system service.
&IPCOBJ &IPCREAS
Meaning
Action
TSAP
openUTM network
process not yet started.
Normal behavior at application start.
tsapname
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
It was not possible to log
in at transport system
Otherwise:
Check BCAMAPPL and
ACCESS-POINT in openUTM
generation.
NET
PROC DEAD openUTM net process
terminated.
See the earlier message U3nn.
LETT
IPC FULL
Data area already too full
to take any more data for
this connection.
Check openUTM generation or
UTM_IPC_LETTER environment
variable (see note below).
LETT
EXTP FULL
Data area for received
messages already fully
occupied.
Check openUTM generation or
UTM_IPC_LETTER environment
variable (see note below).
LETT
USED
Data area is occupied.
Check openUTM generation or
UTM_IPC_LETTER environment
variable (see note below).
LETT
MAX ILETT
LETT
MAX OLETT
Maximum data area per
connection in use.
Check openUTM generation or
UTM_IPC_EXPT_LETTER environment
variable (see note below).
SEMA
USED
Maximum number of
semaphores in use.
Check openUTM generation or
UTM_IPC_EXPT_LETTER environment
variable (see note below).
BeanConnect V2.1
463
Error messages proxy container (U messages)
I
Logging, diagnostics and troubleshooting
The message with &PCOBJ=LETT refers to the data area in shared
memory which is used for the exchange of messages between the
proxy container processes.
Increase the value for the environment variables UTM_IPC_LETTER
(default: 1600) and UTM_IPC_EXTP_LETTER (default: 32) in the
following file:
■
■
Solaris and Linux systems:
<proxy_cont_home>/shsc/startcontainer.sh
Windows systems:
<proxy_cont_home>\shsc\startcontainer.cmd
To activate the value, you must restart the proxy. You can find further
information in the section "Shared memory of the proxy container" on
page 370.
U190 &OBJ1 SHM error ( key: &SHMKEY, lth: &SHMLTH): &UERRNO
The insert &UERRNO has the following meaning:
&UERRNO Meaning
Action
1
The shared memory cannot be
established with the specified size.
User error.
The shared memory cannot be
established.
Inform system service.
2-5
Action: If necessary, the system has to be
tuned. Please refer to the release notes.
U205 utmtimer: Error &UERRNO during utmtimer run
The insert &UERRNO has the following meaning:
&UERRNO Meaning
Action
1 - 21
Internal error.
Inform system service.
22
Proxy container is being
terminated.
Normal behavior.
29 - 32
Internal error.
Inform system service.
U206 utmtimer: Message with incorrect type received
Action: Inform system service.
464
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages proxy container (U messages)
U207 utmtimer: Reallocation of timer list from &DIA1 to &DIA2 elements
Action: Inform system service.
U223 &OBJ1 UTM application &APPL still running according to internal status,
appfile: &OBJ3
You have tried to start the proxy container more than once.
U227 &OBJ1 UTM application &APPL terminated by kdcrem
Action: Remove script or Forced Clear has been activated.
U228 utmmain: Read error on pipe, errno: &ERRNO
Action: Inform system service.
U229 utmmain: &OBJ1 process died, pid: &PID, &SIGEXIT ( &STRTIME )
Action: Inform system service.
U231 utmmain: utmwork process died, pid: &PID unexpected exit code: &EXTCODE
&SIGEXIT ( &STRTIME )
Action: Inform system service.
U304 &OBJ1 ( pid: &PID, &TNSNAME ): &NETFCT call: Error &NETERR
Error during activation of communication endpoint &NETFCT.
Action: Configuration problem (see message U305) or inform system service.
U305 &OBJ1 ( pid: &PID): CMX application &BCAP already attached
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
Error during activation of communication endpoint &BCAP. This communication endpoint is
not unique on the host.
Action: The communication endpoints depend on the container name and the generated
container port number. The used communication endpoints are written to the file
<proxy_cont_home>/def/input.system.txt (BCAMAPPL <communication
endpoint>). You must install the proxy container with another container name or port
number.
U306 &OBJ1 ( pid: &PID, &TNSNAME ): Error &UERRNO during process run
Action: See the table below.
The insert &UERRNO has the following meaning:
&UERRNO Meaning
Action
1 - 11
Internal error during container
connection setup.
Inform system service.
12
No work process when receiving.
Normal behavior when the proxy container
terminates.
BeanConnect V2.1
465
Error messages proxy container (U messages)
Logging, diagnostics and troubleshooting
&UERRNO Meaning
Action
13
Internal error during container
connection setup.
Inform system service.
14
Concurrent clearing of connections. Normal behavior.
19 - 21
Internal error during container
connection setup.
Inform system service.
22
No work process when sending application terminated.
Normal behavior when the proxy container
terminates.
23 - 24
Internal error during container
connection setup.
Inform system service.
25
Connection was cleared down by
the container.
Normal behavior.
26
Connection cleardown was
identified on sending.
Normal behavior.
27 - 36
Internal error during container
connection setup.
Inform system service.
37 - 38
Login for local communication
User error: Change the configuration, see
endpoints was unsuccessful (error also U304/U305.
when activating the communication
endpoint)
41 - 43
Internal error during container
connection setup.
Inform system service.
44
Recipient of connection setup
request could not be determined.
User error: Change the configuration.
45
Connection already cleared down.
Normal behavior.
51 - 58
Internal error during container
connection setup.
Inform system service.
82
Sender of connection setup request User error: Change the configuration.
could not be determined.
83 - 283
Internal error during container
connection setup.
Inform system service.
U307 &OBJ1 ( pid: &PID, &TNSNAME ): Invalid event &EVENT
Action: Inform system service.
U309 &OBJ1 ( pid: &PID, &TNSNAME ): KDCSTRMA called - reason:
&TRMA ( &STRTIME )
Action: Inform system service.
466
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages of the openUTM-LU62 Gateway
13.15 Error messages of the openUTM-LU62 Gateway
This section lists all messages of the openUTM-LU62 Gateway:
●
openUTM-LU62 Gateway error messages on start-up
●
openUTM-LU62 Gateway error messages at runtime
●
openUTM-LU62 Gateway error messages on status queries
●
openUTM-LU62 Gateway error messages during administration
●
openUTM-LU62 Gateway error messages during configuration
13.15.1 openUTM-LU62 Gateway error messages on start-up
When the openUTM-LU62 Gateway starts, the openUTM-LU62 utility
u62_start outputs messages to stdout.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
All the messages start with the string u62_start <nn>, where <nn> indicates the
message number.
●
The messages with the following numbers indicate normal behavior:
17, 18, 24, 25, 26, 28, 29
●
For information on the messages with the numbers 05, 06 and 07, see below.
●
If any other u62_start <nn> messages which are not listed are output, inform the
system service.
05 Directory &DIRNAME cannot be read, errno &ERRNO (&ERRTEXT)
Action: For ERRNO, see Section 13.16.2, "System error codes" and/or inform the system
service.
06 Configuration file &FILENAME cannot be opened, errno &ERRNO
(&ERRTEXT)
Action: For ERRNO, see Section 13.16.2, "System error codes" and/or inform the system
service.
07 Error reading configuration file &FILENAME, errno &ERRNO
(&ERRTEXT)
Action: For ERRNO, see Section 13.16.2, "System error codes" and/or inform the system
service.
BeanConnect V2.1
467
Error messages of the openUTM-LU62 Gateway
Logging, diagnostics and troubleshooting
13.15.2 openUTM-LU62 Gateway error messages at runtime
Messages concerning the OSI-TP protocol stack for connections between the proxy
container and the openUTM-LU62 Gateway begin with letter P. All of these messages are
described in the section "P messages" on page 457.
All other messages of the openUTM-LU62 Gateway begin with the string
u62_tp[<comp>]<nnn>.
In this prefix, <comp> specifies the sub-component of the openUTM-LU62 Gateway and
<nnn> the message number.
004 Error on signal handling, errno &ERRNO (&ERRTEXT)
Action: Inform system service.
006 Error opening the configuration file &FILENAME, errno &ERRNO (&ERRTEXT)
Action: For ERRNO see the section "System error codes" on page 481 or inform system
service.
010 The instance for the local LU name &LUNAME is already running
Action: Inform system service.
012 Internal error occurred
Action: Inform system service.
015 PID file &PIDFILE cannot be created, errno &ERRNO (&ERRTEXT)
Action: For ERRNO see the section "System error codes" on page 481 or inform system
service.
016 Write to PID file &PIDFILE failed, errno &ERRNO (&ERRTEXT)
Action: For ERRNO see the section "System error codes" on page 481 or inform system
service.
026 Crash of openUTM-LU62 in module &MODULNAME
Action: Inform system service. Save the contents of the following directory:
●
On Solaris and Linux systems: /opt/lib/utmlu62/PROT
●
On Windows systems: <gateway_home>\utmlu62\PROT
If possible, you should reproduce the error with the instance trace activated.
468
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages of the openUTM-LU62 Gateway
027 Shutdown by the XAP-TP provider: &REASON
Action: Inform system service. Save the contents of the following directory:
●
On Solaris and Linux systems: /opt/lib/utmlu62/PROT
●
On Windows systems: <gateway_home>\utmlu62\PROT
If possible, you should reproduce the error with the XAP-TP trace activated.
036 Error in allocating a new shared memory of length &LEN,
errno &ERRNO (&ERRTEXT)
Action: For ERRNO see the section "System error codes" on page 481 or inform system
service.
040 Error in the configuration of the local LU &LLUNAME or of the partner LU
&RLUNAME
Action: Generation error in one of the following proxy components:
●
On Solaris systems: SNAP-IX
●
On Linux and Windows systems: IBM Communications Server
048 The node is deactivated: No conversations can be established
The node of the SNAP-IX or IBM Communications Server was presumably deactivated by
the administrator. It is no longer possible to start conversations to the EIS partner.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
Action: Check the following proxy component:
●
On Solaris systems: SNAP-IX
●
On Linux and Windows systems: IBM Communications Server
302 Conversation rejected, TP Name &TPNAME, job submitted by LU6.2 side:
Restart of the nominated control instance not completed yet
This can occur when the connection to the EIS partner is re-established after a crash, but
the connection between the openUTM-LU62 Gateway and the proxy container has not yet
been re-established.
Action: Repeat the job.
303 Incoming conversation (TP Name &TPNAME, job submitted by LU6.2 side)
supplies initialization data that will be discarded by openUTM-LU62.
Action: Inform system service.
304 Conversation rejected, TP Name &TPNAME, job submitted by LU6.2 side:
Security data not supported by the OSI TP partner or contain invalid characters.
Action: Inform system service.
BeanConnect V2.1
469
Error messages of the openUTM-LU62 Gateway
Logging, diagnostics and troubleshooting
305 Conversation rejected, TP Name &TPNAME, job submitted by LU6.2 side:
The alias name &ALIAS of the partner LU is not identical with the configured
name &CONFALIAS.
Action: Check the openUTM-LU62 Gateway generation.
306 Conversation rejected, TP Name &TPNAME, job submitted by LU6.2 side:
Service TPs using mapped (!) conversations are not supported!
The LU6.2 partner has attempted to start a conversation with a non-printable TP name (i.e.
a transaction code between X'00' and X'3F'). The openUTM-LU62 Gateway does not
support these types of service TPs, except for the resync-TP X'06F2'. This message
appears, for example, when the EXEC CICS START function that addresses the service TP
X'02' in the openUTM-LU62 Gateway is used.
307 Conversation rejected, TP Name &TPNAME, job submitted by LU6.2 side:
Configuration error: The net name of the local and/or of the partner LU has been
changed!
Action: Check the openUTM-LU62 Gateway generation.
308 Conversation rejected, TP Name &TPNAME, job submitted by LU6.2 side:
Error in the exchange of the log names between the local and the remote LU!
The LU6.2 partner has opened a conversation to the openUTM-LU62 Gateway with
sync-level 2 although the log names have not yet been exchanged between the two LUs, or
a fatal error occurred the last time the log names were exchanged. The openUTM-LU62
Gateway reacts to this protocol violation by immediately closing the conversation.
Action: The administrator of the transactional resources must check which actions must be
reset. System service cannot check this.
309 RECEIVE_ALLOCATE rejected due to configuration error:
The local LU alias name &LUNAME is not configured!
Action: Check the generation of
●
The openUTM-LU62 Gateway
●
On Solaris systems: SNAP-IX
●
On Linux and Windows systems: IBM Communications Server
310 RECEIVE_ALLOCATE failed: LU6.2 base software is not running!
Action: Start the following proxy component:
470
●
On Solaris systems: SNAP-IX
●
On Linux and Windows systems: IBM Communications Server
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages of the openUTM-LU62 Gateway
311 RECEIVE_ALLOCATE failed: system error (errno &ERRNO ) occurred: &ERRTEXT
Error
●
On Solaris systems: in SNAP-IX
●
On Linux and Windows systems: in the IBM Communications Server
Action: For ERRNO see the section "System error codes" on page 481 or inform system
service.
312 Allocation of a conversation to the LU6.2 partner rejected, TP Name &TPNAME,
job submitted by OSI TP side.
Action: Check the generation of
●
The openUTM-LU62 Gateway
●
On Solaris systems: SNAP-IX
●
On Linux and Windows systems: IBM Communications Server
313 Allocation of a conversation to the LU6.2 partner rejected, TP Name &TPNAME,
job submitted by OSI TP side: The LU6.2 base software is not running!
Reason: The proxy component is not started.
Action: Start the following proxy component:
●
On Solaris systems: SNAP-IX
●
On Linux and Windows systems: IBM Communications Server
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
314 Allocation of a conversation to the LU6.2 partner rejected, TP Name &TPNAME,
job submitted by OSI TP side: system error (errno &ERRNO ) occurred: &ERRTEXT
Error
●
On Solaris systems: in SNAP-IX
●
On Linux and Windows systems: in the IBM Communications Server
Action: For ERRNO see the section "System error codes" on page 481 or inform system
service.
315 Actively allocated conversation to LU6.2 partner deallocated (TP Name &TPNAME,
job submitted by OSI TP side) again due to a configuration error:
The net name of the local and/or of the partner LU has been changed!
Action: Check the generation of
●
The openUTM-LU62 Gateway
●
On Solaris systems: SNAP-IX
●
On Linux and Windows systems: IBM Communications Server
BeanConnect V2.1
471
Error messages of the openUTM-LU62 Gateway
Logging, diagnostics and troubleshooting
320 Allocation of a conversation to LU6.2 partner failed, TP Name &TPNAME, job
submitted by OSI TP side: Allocation error (code = &ERRTEXT)
No conversations to the TP &TPNAME of the LU6.2 partner can be actively opened at the
moment. (&TPNAME is in this case the CICS transaction code, for example.) The error code
&ERRTXT then contains the return code of the corresponding LU6.2 call in plain text.
Action: Start the CICS application.
321 Allocation of a conversation to LU6.2 partner failed, TP Name &TPNAME, job
submitted by OSI TP side: Inconsistency in the configurations of openUTM-LU62
and the LU6.2 base software
Action: Check the generation of
●
The openUTM-LU62 Gateway
●
On Solaris systems: SNAP-IX
●
On Linux and Windows systems: IBM Communications Server
322 Allocation of a conversation to LU6.2 partner failed, TP Name &TPNAME, job
submitted by OSI TP side: Security data invalid
Action: Inform system service.
332 Conversation to the LU6.2 partner (TP Name &TPNAME, job submitted by OSI TP
side) terminated by shutdown of the LU6.2 base software!
Action: Check the diagnostic information and restart
●
On Solaris systems: SNAP-IX
●
On Linux and Windows systems: IBM Communications Server
333 Conversation to the LU6.2 partner (TP Name &TPNAME, job submitted by LU6.2
side) terminated by shutdown of the LU6.2 base software!
Action: Check the diagnostic information and restart
●
On Solaris systems: SNAP-IX
●
On Linux and Windows systems: IBM Communications Server
334 Conversation to the LU6.2 partner (TP Name &TPNAME, job submitted by OSI TP
side) terminated by conversation error!
Possibly caused by an administrative shutdown of all sessions.
Action: Inform the administrator or system service.
335 Conversation to the LU6.2 partner (TP Name &TPNAME, job submitted by LU6.2
side) terminated by conversation error!
Possibly caused by an administrative shutdown of all sessions.
Action: Inform the administrator or system service.
472
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages of the openUTM-LU62 Gateway
336 User control data received on a conversation to the LU6.2 partner
(TP Name &TPNAME, job submitted by OSI TP side)
=> Termination of the conversation by openUTM-LU62!
Action: Inform system service.
337 User control data received on a conversation to the LU6.2 partner
(TP Name &TPNAME, job submitted by LU6.2 side)
=> Termination of the conversation by openUTM-LU62!
Action: Inform system service.
338 Return code AP_STATE_CHECK received on a conversation to the LU6.2 partner
(TP Name &TPNAME, job submitted by OSI TP side)
=> Termination of the conversation by openUTM-LU62!
Action: Inform system service.
339 Return code AP_STATE_CHECK received on a conversation to the LU6.2 partner
(TP Name &TPNAME, job submitted by LU6.2 side)
=> Termination of the conversation by openUTM-LU62!
Action: Inform system service.
340 Incoming conversation to the LU6.2 partner rejected,
(TP Name &TPNAME, job submitted by LU6.2 side)
Expiration of the timer for the supervision of the association allocation
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
This maximum wait time is configurable in the openUTM-LU62 Gateway using the
parameter ALLOC-TIME, where the default value is 30 seconds. If this message appears
often, you should either increase the session limit or decrease the number of parallel
connections for the openUTM-LU62 Gateway. Alternatively, inform system service.
341 Incoming conversation to the LU6.2 partner rejected,
(TP Name &TPNAME, job submitted by OSI TP side)
Expiration of the timer for the supervision of the association allocation
This maximum wait time is configurable in the openUTM-LU62 Gateway using the
parameter ALLOC-TIME, where the default value is 30 seconds. If this message appears
often, you should either increase the session limit or decrease the number of parallel
connections for the openUTM-LU62 Gateway. Alternatively, inform system service.
350 XAP-TP provider rejects association allocation
(TP Name &TPNAME): result = &RES, source = &SRC, reason = &RSN
The proxy container rejects the association.
Action: See the proxy container messages.
351 XAP-TP provider reports loss of association
(TP Name &TPNAME): source = &SRC, reason = &RSN, event = &EVT
The proxy container rejects the association.
Action: See the proxy container messages.
BeanConnect V2.1
473
Error messages of the openUTM-LU62 Gateway
Logging, diagnostics and troubleshooting
352 OSI-TP partner (XAP-TP user) rejects begin dialogue request:
TP Name &TPNAME, job submitted by LU6.2 side
The proxy container rejects the dialog request.
Action: See the corresponding proxy container message or inform system service.
353 OSI-TP partner (XAP-TP user) rejects begin dialogue request:
TP Name &TPNAME, job submitted by OSI TP side: Reason = &RSN
The proxy container rejects the dialog request.
Action: See the corresponding proxy container message or inform system service.
354 Diagnostic information in the initialization data of
AP_TP_BEGIN_DIALOGUE_CNF: 0xhhhh (d,d)
hhhh represents the hexadecimal value and d,d represent the according decimal values.
For UTM as OSI-TP partner, the initialization data contains further information on the
reason, why the dialog has been rejected. The first value shows whether the fault is
transient (1) or permanent (2).
The second value shows the detailed reason for rejection.
For the meaning of these values see Section 13.14.2.2, "K messages", description DIA3 in
message K119 for DIA1=2.
361 Incoming dialogue rejected, job submitted by OSI-TP side:
Cannot decode local TPSU title
Action: Inform system service.
373 Incoming dialogue rejected, TP Name &TPNAME, job submitted by OSI-TP side:
Restart of the nominated control instance not completed yet
Action: Repeat the job.
374 Incoming dialogue rejected, TP Name &TPNAME, job submitted by OSI-TP side:
Remote application process title is not consistent with the configuration
Action: Check the generation of the proxy container and the openUTM-LU62 Gateway.
375 Incoming dialogue rejected, TP Name &TPNAME, job submitted by OSI-TP side:
Remote application entity qualifier is not consistent with the configuration
Action: Check the generation of the proxy container and the openUTM-LU62 Gateway.
390 OSI-TP dialogue aborted by partner (XAP-TP provider),
TP Name &TPNAME, job submitted by LU6.2 side
Action: See the corresponding proxy container message or inform system service.
391 OSI-TP dialogue aborted by partner (XAP-TP provider),
TP Name &TPNAME, job submitted by OSI TP side
Action: See the corresponding proxy container message or inform system service.
474
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages of the openUTM-LU62 Gateway
392 OSI-TP dialogue aborted by partner (XAP-TP user),
TP Name &TPNAME, job submitted by LU6.2 side
Action: See the corresponding proxy container message or inform system service.
393 OSI-TP dialogue aborted by partner (XAP-TP user),
TP Name &TPNAME, job submitted by OSI TP side
Action: See the corresponding proxy container message or inform system service.
408 OSI-TP partner indicates heuristic mix.
TP Name &TPNAME, job submitted by &PARTNER side
Probably the transaction between the proxy container and openUTM-LU62 Gateway is
inconsistent.
Action: You usually need to change the participating database manually in this case to
recoordinate the inconsistent database records. Inform system service.
409 OSI-TP partner indicates heuristic hazard.
TP Name &TPNAME, job submitted by &PARTNER side
Probably the transaction between the proxy container and openUTM-LU62 Gateway is
inconsistent.
Action: You usually need to change the participating database manually in this case to
recoordinate the inconsistent database records. Inform system service.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
410 Syncpoint request received from LU6.2 job-receiving service.
TP Name &TPNAME. Transaction is aborted.
A job receiving program on the CICS side has requested a syncpoint (e.g. EXEC CICS
SYNCPOINT) without having been requested to do so by the proxy container. This is
prohibited. The transaction is aborted. &TPNAME specifies the transaction code on the CICS
side.
Action: Change the CICS application program.
420 Error during resynchronization of a transaction. LU6.2 partner does not accept
the state &STATE.
A transaction has been interrupted in the commit phase due to a loss of the connection on
the LU6.2 side. An error has occurred during resynchronization with the LU6.2 partner. The
transaction cannot be reset or aborted.
Action: You usually need to change the participating database manually in this case to
recoordinate the inconsistent database records. The administrator must abort the transaction manually.
BeanConnect V2.1
475
Error messages of the openUTM-LU62 Gateway
Logging, diagnostics and troubleshooting
421 Log name error during resynchronization of a transaction.
A transaction has been interrupted in the commit phase due to a loss of the connection on
the LU6.2 side. An error has occurred during resynchronization with the LU6.2 partner. The
transaction cannot be reset or aborted.
Action: You usually need to change the participating database manually in this case to
recoordinate the inconsistent database records. The administrator must abort the transaction manually.
423 Protocol error of LU6.2 partner:
Compare States &LUWSTATE &RRI received in state &STATE1/&STATE2.
Malfunction of the EIS partner.
Action: You usually need to change the participating database manually in this case to
recoordinate the inconsistent database records. Inform the EIS partner's administrator.
424 LU6.2 partner indicates a protocol error. State: &STATE1/&STATE2,
TP Name &TPNAME, job submitted by &PARTNER side.
Action: Inform system service.
425 Invalid log record (error type &ERROR). Transaction is removed.
A faulty log record was read during a warm start of the openUTM-LU62 Gateway. The transaction recorded in this log record can therefore not be resynchronized.
Action: You usually need to change the participating database manually in this case to
recoordinate the inconsistent database records. The administrator must abort the transaction manually.
426 Problem at the XAP-TP interface. &EVENT received.
Action: Inform system service.
427 Error &ERRNO when issuing &CALL.
An error has occurred in a Solaris or Linux system call. This can lead to the abnormal termination of the openUTM-LU62 Gateway.
Action: For ERRNO see the section "System error codes" on page 481 or inform system
service.
510 The LU (alias name = &ALIASNAME, net name = &NETNAME) has returned an
abnormal reply to the Exchange Logname command.
Action: Inform system service.
511 A cold start has been attempted by LU (alias name = &ALIASNAME, net
name = &NETNAME), but the local LU has logical units of work that are awaiting
resynchronization from the previous activation.
Action: Inform system service.
476
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages of the openUTM-LU62 Gateway
13.15.3 openUTM-LU62 Gateway error messages on status queries
When checking the availability of the openUTM-LU62 Gateway in the Management
Console, the openUTM-LU62 u62_sta utility outputs messages to stdout.
All these messages begin with the prefix u62_sta <nn>, where <nn> specifies the
message number.
●
For messages with the numbers 06, 09, 12 and 13 see below.
●
For all the other u62_sta <nn> messages that are not listed above, inform system
service.
06 Instance &INST:
Instance is still initializing or terminating.
The proxy component openUTM-LU62 Gateway is currently being started or terminated.
Action: Repeat the state request.
09 Instance &INST:
Instance does not respond in time.
Delay which can occur with high load and in large configurations.
Action: Try checking again. Otherwise increase the preset waiting time of 20 seconds in the
following script:
●
Solaris and Linux systems: <proxy_cont_home>/shsc/checkgateway.sh
●
Windows systems: <proxy_cont_home>\shsc\checkgateway.cmd
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
12 No openUTM-LU62 instance active.
The proxy component openUTM-LU62 Gateway has not been started yet.
Action: Start the openUTM-LU62 Gateway.
13 The given instance is not active.
The proxy component openUTM-LU62 Gateway has not been started yet.
Action: Start the openUTM-LU62 Gateway.
BeanConnect V2.1
477
Error messages of the openUTM-LU62 Gateway
Logging, diagnostics and troubleshooting
13.15.4 openUTM-LU62 Gateway error messages during administration
When administering the openUTM-LU62 Gateway in the Management Console
(activating/deactivating traces) the openUTM-LU62 u62_adm utility outputs messages to
stdout.
All these messages begin with the prefix u62_adm <nn>, where <nn> specifies the
message number.
●
Messages with the following numbers indicate normal behavior:
20 to 45, 56
●
For messages with the numbers 06, 09, 12, 13, 52, 53 and 59 see below.
●
For all the other u62_adm <nn> messages that are not listed above, inform system
service.
06 Instance &INST:
Instance is still initializing or terminating.
The proxy component openUTM-LU62 Gateway is currently being started or terminated.
Action: Repeat the action.
09 Instance &INST:
Instance does not respond in time.
Delay which can occur with high load and in large configurations.
Action: Repeat the action.
12 No openUTM-LU62 instance active.
The proxy component openUTM-LU62 Gateway has not been started yet.
Action: Start the openUTM-LU62 Gateway.
13 The given instance is not active.
The proxy component openUTM-LU62 Gateway has not been started yet.
Action: Start the openUTM-LU62 Gateway.
52 Error opening the trace file &FILENAME, errno &ERRNO (&ERRTXT)
Action: For ERRNO see the section "System error codes" on page 481 or inform system
service.
53 Error reading from trace file &FILENAME, errno &ERRNO (&ERRTXT)
The specified file is not a trace file of the openUTM-LU62 Gateway.
Action: Specify the correct file.
59 Extracting the protocol trace may take some time. Please wait ...
Action: Wait for trace extraction to be completed.
478
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error messages of the openUTM-LU62 Gateway
13.15.5 openUTM-LU62 Gateway error messages during configuration
When configuring the openUTM-LU62 Gateway in the Management Console (update
configuration), the openUTM-LU62 u62_gen utility outputs messages to stdout.
All these messages begin with the prefix u62_gen <nn>, where <nn> specifies the
message number.
●
A message with the number u62_gen 60 indicates normal behavior.
●
For the messages 51, 58, and 59 see below.
●
For all the other u62_gen <nn> messages that are not listed above, inform system
service.
51 File &FILENAME cannot be opened, errno &ERRNO (&ERRTEXT)
Action: For ERRNO see the section "System error codes" on page 481 or inform system
service.
58 Error in writing to file &FILENAME, errno &ERRNO (&ERRTEXT)
Action: For ERRNO see the section "System error codes" on page 481 or inform system
service.
59 Error in reading from file &FILENAME, errno &ERRNO (&ERRTEXT)
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
Action: For ERRNO see the section "System error codes" on page 481 or inform system
service.
BeanConnect V2.1
479
Error codes
Logging, diagnostics and troubleshooting
13.16 Error codes
This section provides information on the following topics:
●
Error codes during file processing (DMS error codes)
●
System error codes
13.16.1 Error codes during file processing (DMS error codes)
In conjunction with file processing, return codes in the form yxxx occur in the event of an
error. These are also known as DMS errors and have the following meanings:
y
The first character y denotes the function in which the error occurred. y may have the
following values:
A Error in loading shared memories into the address space
C Error in close call
D Error in signing off from a shared memory area
F Error in fstat/stat call
G Error in allocating shared memory
L Error in lseek call
O Error in open call
R Error in read call
W Error in write call
X Error in create call
xxx The three characters xxx represent, in printable form, the error number which is stored by
the operating system in the external variable errno. The meanings of the individual error
numbers are described in the operating system manuals and in the errno.h header file.
You will find some of the error codes which occur most often in the section "System error
codes" on page 481.
In addition, the errors CONS, LERR, OERR, REND, RERR, WERR, SXDE, SDDE and SDFE can
occur. These have the following meaning:
CONS The data contents are inconsistent.
LERR lseek could not be positioned at the desired point.
OERR An attempt was made to open a directory as a normal file.
REND End-of-file reached on reading from a file.
RERR Insufficient bytes could be read.
480
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k13
Logging, diagnostics and troubleshooting
Error codes
WERR Insufficient bytes could be written.
SXDE A directory could not be created.
SDDE A directory could not be deleted.
SDFE A file could not be deleted.
13.16.2 System error codes
Several messages from the BeanConnect proxy container and the openUTM-LU62
Gateway contain as an insert a message number which is returned by the operating
system. The actions in response to these messages depend on the error code.
The following table provides information on the most frequent reasons for errors. All other
reasons not listed in this table are severe errors. Inform system service if these errors occur.
ERRNO
2
12
Meaning
File or directory not available.
Storage bottleneck in the system.
13
No access rights for file or directory.
17
File already exists.
28
Disk bottleneck.
Operating facility deleted.
Dokuschablonen fÐꬽr DARB XML in FSC-Layout Version 1.0 fÐꬽr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH
36
BeanConnect V2.1
481
Error codes
482
Logging, diagnostics and troubleshooting
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k14
June 8, 2009 7:06 pm
14 Cobol2Java
BeanConnect clients can communicate with a BS2000/OSD-COBOL application using a
number of different protocols. Byte arrays or strings are used for the exchange of
information. The structure of the information is defined by the COBOL application. As a
result, it is difficult for application developers to exchange data with the legacy service since
this demands precise knowledge of the data structure of the COBOL program. Cobol2Java
helps simplify the integration of BS2000/OSD-COBOL applications and BeanConnect
clients.
This chapter contains information on the following subjects:
Mapping COBOL data types to Java classes
●
Converting COBOL data types
●
Programming reference
●
Example
●
Error messages and error handling
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
●
BeanConnect V2.1
483
Mapping COBOL data types to Java classes
Cobol2Java
14.1 Mapping COBOL data types to Java classes
Cobol2Java permits the object-oriented mapping of COBOL data structures to Java
classes.
Cobol2Java consists of the following parts:
●
Cobol2XML, a BS2000 tool for generation of an XML description of a BS2000 COBOL
structure
●
a framework with Cobol2Java conversion classes
●
a program generator for the generation of application-specific classes on the basis of
this framework
The program generator makes use of an XSLT stylesheet to generate application-specific
Java classes. This is performed on the basis of an XML description of the COBOL service
that you can generate using the Cobol2XML tool in BS2000/OSD.
The Cobol2Java classes are able to process the byte arrays of a COBOL program or
generate a byte array that can be interpreted by the COBOL service. To access the
individual data fields within the byte array, Cobol2Java provides data access methods
appropriate for the data type as it is defined in the COBOL structure.
The figure below illustrates the generation operation.
Figure 68: Cobol2Java generation procedure
Java class
Cobol2Java
program
BS2000
Cobol2XML
COBOL source
COBOL-XML
description
(XSLT
processing)
XSLT stylesheet
Java class
Java class
The Cobol2XML tool in BS2000/OSD can be used to generate an XML file from the
BS2000/OSD-COBOL source. Cobol2Java then uses this file as the basis for creation of the
Java classes.
484
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k14
Cobol2Java
Mapping COBOL data types to Java classes
It is also possible to use Cobol2Java with COBOL programs developed for other platforms,
such as UNIX systems. For this to be possible, the XML description must be generated on
a BS2000 system. It is not, however, possible to guarantee full functionality since the
memory allocation is dependent on the COBOL compiler.
14.1.1 System requirements
The following operating systems are supported as Cobol2Java target platforms:
●
Solaris, Linux and other UNIX systems
●
Windows
The following programs must be installed before you can use Cobol2Java:
●
Java 2 SDK
●
XSLT processor
●
–
Xalan (supplied) or
–
Saxon
Ant (supplied)
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Cobol2XML must be installed on a BS2000/OSD system.
BeanConnect V2.1
485
Mapping COBOL data types to Java classes
Cobol2Java
14.1.2 Installation
The components required for Cobol2Java are made available together with the
BeanConnect tools.
The installation of Cobol2Java is described in Section 3.5, "Installing the BeanConnect
tools".
The following directory structure is created on installation:
/
build.xml
Ant script
cobol2java.properties
Configuration file
runAnt.sh
Ant script (UNIX system)
runAnt.bat
Ant script (Windows system)
xml2java.sh
Script (UNIX system)
xml2java.cmd
Script (Windows system)
Javadoc
/api
COB2XML.LIB
BS2000 tool Cobol2XML for
file transfer with FTP
/BS2Files/openFT COB2XML.LIB
BS2000 tool Cobol2XML for
file transfer with openFT
/Docs
Copyright.htm
Copyright notes for the
employed openSource
products
Readme.pdf
Release Notice
ant.jar
Ant
/BS2Files/ftp
/lib
ant-launcher.jar
BeanConnectCob2java.jar
Transfer tool: XML to Java
BeanConnectCob2java_ext.jar Necessary for the execution
of the generated Cobol2Java
classes if Cobol2Java is
used in a separate program
without BeanConnect
486
BeanConnectEncoding.jar
Code conversion
functions.xslt
XSLT stylesheet
mkcob2java.xslt
XSLT stylesheet
newformat.dtd
Document Type Definition
BeanConnect V2.1
Mapping COBOL data types to Java classes
samples
xalan.jar
Xalan
xercesImpl.jar,
xmlParserAPIs.jar
Xerces
*.xml
Sample XML files generated
using Cobol2XML within
BS2000/OSD
newformat.dtd
Document Type Definition
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k14
Cobol2Java
BeanConnect V2.1
487
Converting COBOL data types
Cobol2Java
14.2 Converting COBOL data types
Mapping COBOL data types to Java classes comprises the following steps:
●
Creating an XML description for a COBOL program in BS2000
●
Generating Java classes on UNIX or Windows systems
14.2.1 Creating an XML description for a COBOL program in BS2000
The BS2000/OSD tool Cobol2XML is used to convert a COBOL program or COPY element
to XML. The following steps are required:
14.2.1.1
●
Transferring the LMS library COB2XML.LIB to BS2000/OSD
●
Converting the data structures from COBOL programs or COPY elements to XML using
the procedure D.XMLPROG or D.XMLCOPY
●
Transferring the XML descriptions in text format to UNIX systems or Windows systems
for further processing with Cobol2Java.
Transferring the LMS library to BS2000/OSD
Cobol2XML is a BS2000/OSD tool. You must therefore transfer the library COB2XML.LIB to
a BS2000/OSD user ID. Depending on the transfer mode, you can either transfer the file
COB2XML.LIB under cobol2java/BS2Files/ftp or the file COB2XML.LIB under
cobol2java/BS2Files/openFT.
I
V
488
When transferring with ftp, use binary mode.
When transferring with openFT, use the file type binary.
If the BS2000 system does not possess sufficient storage
space, with ftp you may get the error message DD33 (File not
present).
Do not rename the library in the BS2000/OSD system since the
conversion procedure accesses elements of this library.
BeanConnect V2.1
14.2.1.2
Converting COBOL data types
Converting the data structures
The conversion procedure can only be called under the user ID where the library
COB2XML.LIB is stored.
Before calling the conversion procedure, assign the link names COBLIB<n>
(<n>= 1, .., 9) to the COPY libraries required for compilation of the source. For example, for
a UTM COBOL program assign a link name to the library containing the UTM-COPY
elements in order to ensure that the UTM-COPY elements can be found. You do this using
the command ADD-FILE-LINK:
/ADD-FILE-LINK COBLIB1, <copy_library>
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k14
Cobol2Java
(see also the manual “COBOL2000 (BS2000/OSD), COBOL-Compiler”).
I
The link name COBLIB is used internally.
You can then start the procedures D.XMLPROG or D.XMLCOPY from the library
COB2XML.LIB. The parameters are described in the sections below.
14.2.1.3
D.XMLPROG
D.XMLPROG generates an XML description of the data structures used in a COBOL program
on the basis of the corresponding program source.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Start D.XMLPROG with the command CALL-PROCEDURE as follows:
CALL-PROC
FROM-FILE=*LIBRARY-ELEMENT(LIBRARY=COB2XML.LIB,ELEM=D.XMLPROG)
,PROCEDURE-PARAMETERS=(
{SRC=FILE,TSTNAM=<cobol_source>|SRC=LIB,LIB=<cobol_lib>, TSTNAM=<cobol_
source>},
[XMLOUT=<ouptput_file>,]
[COBRUN=<compiler_options>] )
Description of the parameters:
SRC=FILE,TSTNAM=<cobol_source>
The COBOL program from whose data structures an XML description is to be generated
can be found in the file <cobol_source>.
SRC=LIB,LIB=<cobol_lib>, TSTNAM=<cobol_source>
The COBOL program from whose data structures an XML description is to be generated
can be found in the element <cobol_source> in the LMS library <cobol_lib>.
BeanConnect V2.1
489
Converting COBOL data types
Cobol2Java
XMLOUT=<output_file>
Name of the file to which the data structures are written in XML format. The name must have
the suffix .xml. If this parameter is not specified and the link name XMLLINK is not defined
then the XML description is written to the file XMLFIL.COBOL.<progID>.XML where
<progID> stands for the program name defined in PROGRAM-ID.
COBRUN=<compiler_options>
Specification of compiler options in the form of a string of maximum 121 characters. You
separate the individual options with commas. You can specify, for example:
COMMENT=YES/NO
Comment lines are not output if the option COMMENT=NO is set.
DTD=YES/NO
The reference to the Document Type Definition is not output if the option DTD=NO is set.
14.2.1.4
D.XMLCOPY
D.XMLCOPY generates an XML description of the data structures defined in a COBOL
COPY element on the basis of the corresponding COPY element.
You start D.XMLCOPY with the command CALL-PROCEDURE as follows:
CALL-PROC
FROM-FILE=*LIBRARY-ELEMENT(LIBRARY=COB2XML.LIB,ELEM=D.XMLCOPY)
,PROCEDURE-PARAMETERS=(
LIB=<cobol_lib>,
ELEM=<cobol_copy>,
[XMLOUT=<output_file>,]
[COBRUN=<compiler_options>] )
Description of the parameters:
LIB=<cobol_lib>, ELEM=<cobol_copy>
The COBOL COPY element from whose data structures an XML description is to be
generated is available as the element <cobol_copy> in the LMS library <cobol_lib>.
XMLOUT=<output_file>
Name of the file to which the data structures are written in XML format. The name must have
the suffix .xml. If this parameter is not specified and the link name XMLLINK is not defined
then the XML description is written to the file XMLFIL.COBOL.<cobol_copy>.XML where
<cobol_copy> stands for the name of the COPY element.
490
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k14
Cobol2Java
Converting COBOL data types
COBRUN=<compiler_options>
Specification of compiler options in the form of a string of maximum 121 characters. You
separate the individual options with commas. You can specify, for example:
COMMENT=YES/NO
Comment lines are not output if the option COMMENT=NO is set.
DTD=YES/NO
The reference to the Document Type Definition is not output if the option DTD=NO is set.
14.2.1.5
Example call
/PROC A
/REMARK is necessary for converting UTM programs
/ADD-FILE-LINK COBLIB1,$TSOS.SYSLIB.UTM.053.COB
/ADD-FILE-LINK COBLIB2,COBOLCOPY.LIB
/CALL-PROC F-F=*LIB(LIB=COB2XML.LIB,ELEM=D.XMLPROG),P-P=(SRC=FILE / ,TSTNAM=COBTAC.CBL / ,XMLOUT=COBTAC.XML),LOG=N
/ENDP
14.2.1.6
Generated files
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
The output from D.XMLPROG and D.XMLCOPY can be found in the file which is either
●
assigned previously to the link name XMLLINK using the ADD-FILE-LINK command, or
●
specified in the XMLOUT parameter.
If you do not make use of any of these possibilities, the output from D.XMLPROG and
D.XMLCOPY is written to the file XMLFIL.COBOL.<progID>.XML. Here <progID> stands for
the program name defined in PROGRAM-ID (D.XMLPROG) or the name of the COPY element
(D.XMLCOPY).
You have to transfer the generated files containing the XML description in text format to
UNIX or Windows systems for further processing with Cobol2Java.
BeanConnect V2.1
491
Converting COBOL data types
Cobol2Java
14.2.2 Generating Java classes on UNIX or Windows systems
You can generate Java classes with or without Ant.
14.2.2.1
Generating Java classes with Ant
Java classes are generated by means of an Ant script. The parameters are given with the
file cobol2java.properties as follows:
xml.file=<xml_file>
cobol.struct=<list_of_structure_names>
package.name=<package_name>
doc.dir=<doc_directory>
jar.dest=<jarfile_name>
code.convention={java|cobol}
undef.pic9=<undef_value>
Description of the parameters:
xml.file=<xml_file>
The parameter xml.file specifies the name of the file containing the XML description of
the COBOL structure that is to be processed.
V
Make sure that the DTD newformat.dtd is located in the same
directory as the XML file. You can find a copy of
newformat.dtd in the directories lib and samples.
cobol.struct=<list_of_structure_names>
In the parameter cobol.struct, specify a space-separated list of COBOL structures.
Cobol2Java searches all the elements (records as well as fields) in the input file for the
names contained in <list_of_structure_names>. For each found element a Java class
is generated. At least one structure name must be specified.
Certain specifications for the parameter cobol.struct are of little use. You should
therefore observe the following restrictions:
●
492
Do not specify two structures that are nested one within the other in a single call.
Reason: The class of the lower-level structure is generated twice (as root level and as
sub-level class). The class that is generated later overwrites the first and errors occur
during the compilation and use of the classes.
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k14
Cobol2Java
Converting COBOL data types
●
Do not enter any recurrent structure or field names (occurs, Array). Reason: It is only
possible to access the first element of the array via the generated class. Instead, you
should specify higher-level structures.
●
The specification of recurrent structure or field names is not permitted. A message is
output and no Java classes are generated.
package.name=<package_name>
The parameter package.name contains the name of the package under which the
generated Java classes are to be grouped.
doc.dir=<doc_directory>
doc.dir contains the name of the directory for Javadoc.
jar.dest=<jarfile_name>
jar.dest contains the name of the JAR file that is to be generated.
code.convention={java|cobol}
code.convention specifies the naming convention that is to be used by the Java classes.
If cobol is specified then all the names are taken over from the COBOL program wherever
possible. Otherwise, all the names are adapted to the Java naming conventions for the
naming of classes, variables, methods and objects (see also "Naming conventions" on
page 500).
undef.pic9=<undef-value>
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
undef.pic9 specifies the specific value in Pic9 fields that is to indicate "undefined". Here,
<undef-value> can have the following form:
0x<nn>
where <nn> is the hexadecimal byte value, or
"'<char>'"
where <char> is a printing character with a 1-byte representation.
To obtain the value '<char>' in the Java class, the parameter must also be
specified in quotes ("), e.g. undef.pic9="''"
If undef.pic9 is not specified then '0' is the predefined value for undefined Pic9 fields.
Caution! If you specify the byte value with encoding active then you may need to take
account of code conversion. See also Section 14.3.3.2, "Reading a data field".
BeanConnect V2.1
493
Converting COBOL data types
I
Cobol2Java
If you compile generated Java classes, it is important that the
class and file names correspond in terms of the use of
case-sensitive notation. Since the Windows file system does not
make any distinction between uppercase/lowercase, the Java
compiler may report the following error when compiling, for
example, a class Benid within a file BENID.java:
"[javac] BENID.java:19:class Benid is public,
should be declared in a file named Benid.java"
This error occurs if you create the same COBOL structure with
code.convention=cobol and then again with
code.convention=java. If you want to modify
code.convention, you must first delete the sources that were
created beforehand in the src directory.
To start the program you call the script runAnt.sh (UNIX system) or runAnt.bat
(Windows). This starts generation using the Ant program supplied with Cobol2Java. This
generation process results in the Java sources being created in the src directory, compiled,
and stored in the JAR file specified in jar.dest. If you do not want to use the Ant supplied,
call Ant in the directory containing the build.xml file.
I
V
Some of the tools used here require a very large amount of
RAM. You should therefore use the options-Xss (stack
size) and -Xmx (heap size) to make the adaptations
necessary for the large data structures. In UNIX systems, it may
also be necessary to adapt the stack size limit using the
ulimit command.
If runAnt is to run correctly, it must be possible to call the Java
programs javac and javadoc; i.e. the Java SDK program
directory must be present in the environment variable PATH.
It is necessary to use the separator "/" or "\\" when specifying the
path names for xml.file, doc.dir and jar.dest since Ant
interprets "\" and the following character as a control character.
494
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k14
Cobol2Java
Converting COBOL data types
Example 33 Example for a cobol2java.properties file
# Properties to set for Cobol2Java Program
# used by Ant
# Name of Source XML generated by the BS2000 COBOL Compiler
# Make sure the DTD File is available!!
xml.file=cobkb.xml
# Name of the COBOL Records
# Space separated list:
# cobol.struct=RECORD1 RECORD3 will create Java classes for
# RECORD1 and RECORD3
cobol.struct=MPUT-MSG
# Name of the package to be generated
package.name=de.siemens.cob2java.cobkb
#
# Directory for Javadoc
doc.dir=doc/cobkb
# Jar file name
jar.dest=cobkb.jar
# Determines what code convention the generated code will use
#
# code.convention=java
# code.convention=cobol
# defines a non numeric value which marks a PIC9 field as undefined
#
undef.pic9=0x20
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
code.convention=java
BeanConnect V2.1
495
Converting COBOL data types
14.2.2.2
Cobol2Java
Generating Java classes without Ant
The generation procedure described above is usable limited for batch processing and bulk
data operations.
If you are in the Cobol2Java home directory you can call the following command in procedures in order to perform a large number of generations on the basis of your own specifications.
java -Xss8m -Xmx512m -classpath
lib/BeanConnectCob2java.jar;lib/xalan.jar;lib/xercesImpl.jar;
lib/xmlParserAPIs.jar
de.siemens.cob2java.Cob2Java [-undef.pic9=<default-value>] <xml_file>
<package_name>
<code_convention>
<cobol_struct1> [<cobol_struct2> ...]
Description of the parameters:
undef.pic9=<default-value>
undef.pic9 specifies the specific value for Pic9 fields that is to represent "undefined". For
details, see the description of undef.pic9 in Section 14.2.2.1, "Generating Java classes
with Ant".
<xml_file>
Name of the XML file containing the description of the COBOL data structures.
<package_name>
Package name for the generated classes.
<code_convention>
Convention used by the generated classes: cobol or java.
When using this parameter, please note the comments concerning the code.convention
parameter on page 493.
<cobol_struct>[1...<n>]
Space-separated list of COBOL structures that are to be converted. At least one name must
be specified.
496
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k14
Cobol2Java
Converting COBOL data types
I
Since some of the tools used here require a large amount of
memory, it is generally necessary to use the options
-Xss (stack size) and -Xmx (heap size) and make the
required adaptations for large data structures. In UNIX systems,
it may also be necessary to adapt the stack size limit using
the ulimit command.
Example 34 Generating Java classes
June 8, 2009 7:06 pm
java -Xss8m -Xmx512m -classpath
lib//BeanConnectCob2java.jar;lib/xalan.jar;lib/xercesImpl.jar;
lib/xmlParserAPIs.jar
de.siemens.cob2java.Cob2Java cobkb.xml de.cobol java
MPUT-MSG BENID
This program simply generates the Java classes in the subdirectory src. It does not
perform any compilation or create any JAR files or documentation.
An example can be found in the script xml2java.sh on UNIX systems or xml2java.cmd
on Windows systems.
V
Replacing the XSLT processor
If Saxon is used instead of Xalan as the XSLT processor then the library saxon.jar must
be entered instead of xalan.jar in the Ant script runAnt or in the Cobol2Java start
command.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
14.2.2.3
Make sure that the DTD newformat.dtd is located in the same
directory as the XML file. You can find a copy of
newformat.dtd in the directories lib and samples.
BeanConnect V2.1
497
Programming reference
Cobol2Java
14.3 Programming reference
This section contains a presentation of the framework that is used to convert COBOL data
types to Java and vice versa.
14.3.1 Type assignment
The table below presents an overview of the Java classes present in the framework together
with a brief description of the COBOL types for which the classes are used.
Java class
Description
DataType
Basic class for all conversion classes
CobolRecord
Basic class for COBOL structures
PicX
For alphabetical/alphanumerical COBOL types: PIC X(n)
PicN
For national COBOL types: PIC N(n)
Pic9
For positive, integer numerical COBOL types: PIC 9
Pic9COMP
For integer numerical COBOL types: PIC S9(n) and
PIC 9(n) USAGE [COMP, BINARY, COMP-5]
PicU
For COBOL types for which Cobol2Java offers no special data
conversion classes. The data is made available in the Java program
without conversion as a byte array.
The directory api-doc contains the documentation for these classes.
498
BeanConnect V2.1
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k14
Cobol2Java
Programming reference
The table below indicates the support provided for the various COBOL types and clauses:
COBOL clause
Java support
Data structures with level
numbers
CobolRecord
Pic X (n) (alphanumerical)
PicX
Combinations of A, X, 9
(not only 9)
PicX
Pic 9 (n) (numerical)
Pic9
Pic N (n) (national)
PicN
BINARY, COMP, COMP-5
Pic9Comp for PIC9(1)to PIC9(18)
Not supported:
PIC 9(19) to PIC 9(31) is mapped to PicU
COMP-1, COMP-2, COMP-3
Not supported.
Alphanumerical, ready for printing
Alphabetical, ready for printing
Mapped to PicX.
The preparation mask is ignored.
Numerical, ready for printing
Not supported. Mapped to PicU.
BLANK WHEN ZERO
Not supported. Mapped to PicU.
INDEX
Not supported.
POINTER; PROCEDURE POINTER,
OBJECT REFERENCE
Not supported.
JUSTIFIED RIGHT
PicX, ignored.
SYNCHRONIZED
Supported.
Level number 77
Supported.
OCCURS
Limited support.
●
Dynamic arrays (OCCURS DEPENDING ON) are
created with a fixed length.
●
OCCURS INDEXED BY, OCCURS KEY IS is not
supported.
REDEFINES
Supported.
RENAMES
Supported.
BeanConnect V2.1
499
Programming reference
Cobol2Java
14.3.2 Naming conventions
This section describes how the names in the Java classes are constructed for the different
code conventions.
When cobol is used as code convention, the following mapping rules apply:
●
The COBOL name is retained as far as possible.
●
Hyphens are replaced by underscores.
●
All arrays are indexed with 0.
If java is used as code convention then the following mapping rules apply:
●
All uppercase are converted to lowercase.
●
Letters following a hyphen are written in uppercase. All hyphens are removed.
●
The first letter of a class name is written in uppercase.
●
The names of get methods are formed from get plus the attribute name and the first
letter of the attribute name is written in uppercase.
●
The names of set methods are formed from set plus the attribute name and the first
letter of the attribute name is written in uppercase.
●
All arrays are indexed with 0.
Example 35 Name assignment for the different code conventions
Depending on the code convention, the following names are formed for the COBOL field
named EMPLOYEE-RECORD:
Code convention
Java attribute name
Java get/set method name
cobol
EMPLOYEE_RECORD
getEMPLOYEE_RECORD ()
setEMPLOYEE_RECORD ()
java
employeeRecord
getEmployeeRecord()
setEmployeeRecord()
If the data structure contains substructures with the name FILLER or if the program
contains multiple substructures with the same name then these structures are numbered in
order in accordance with their sequence in the xml input file. When the Java classes are
generated, this number n is appended to the generated names in the form _R_n.
If the data structure contains fields with the name FILLER then these fields are numbered
in order in accordance with their sequence in the xml input file. When the Java classes are
generated, this number n is appended to the generated names in the form _n.
500
BeanConnect V2.1
Programming reference
14.3.3 Accessing COBOL fields
The hierarchical COBOL data structure is mapped to a hierarchical class structure.
Consequently, a field <XXX> can be addressed as follows:
Read access:
level01.getLevel02().getLevel03().get<XXX>()
Write access:
level01.getLevel02().getLevel03().set<XXX>()
The construction can be used to achieve high-performance access to deeply nested fields.
Instead of
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k14
Cobol2Java
in.getArray2(1).getLineTab().getLinex(3).getKeyx().setData1
(1,"Value1");
in.getArray2(1).getLineTab().getLinex(3).getKeyx().setData2
(1,"Value2");
the fields can be accessed level by level:
Keyx keyx;
keyx = in.getArray2(1).getLineTab().getLinex(3).getKeyx();
keyx.setData1(1,"Value1");
keyx.setData2(1,"Value2");
14.3.3.1
Writing a data field
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
To write a data field <XXX> it is necessary to call the method setXXX(). An object of the
COBOL data field type is passed as the parameter.
EmployeeRecord out = new EmployeeRecord();
out.setLastName(new PicX("LastName"));
For each COBOL data type, there are additional methods with parameters of the type
String, or int and long:
for PicX, PicN:
setXXX(String): out.setLastName("LastName");
for Pic9:
setXXX(int), setXXX(long)
BeanConnect V2.1
501
Programming reference
14.3.3.2
Cobol2Java
Reading a data field
To read a data field <XXX> it is necessary to call the method get<XXX>(). The return value
supplied by this method is an object of the same type as the COBOL data field. Each object
possesses methods adapted to the type that are used to extract the data:
for PicX:
toString()
for Pic9:
longValue()
When COBOL is used, it is possible that a numerical data field (PIC 9(n)) is initialized with
a non-numerical value, e.g. blanks or 'X00'. To avoid the output of any NumberFormatException when accessing this type of "undefined" field, the following methods are available
to check the content:
for Pic9:
isUndefined(), isUndefined(byte)
The default value for "undefined" can be specified when the Java class is created. (see
Section 14.2.2, "Generating Java classes on UNIX or Windows systems").
If a data field is only initialized with the default value for "undefined" (isUndefined()
returns true) and if this default value is not numerical, then the value 0 is returned when
the field is read.
14.3.3.3
Replacement data type PicU
The replacement data type PicU is used for non-supported data fields. This permits transparent access to the data. The application programmer can then process this data with
his/her own resources. The unchanged data of the partner application is provided as byte
array.
This type possesses the following methods:
502
Read access:
getBytes()
Write access:
setBytes()
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k14
Cobol2Java
14.3.3.4
Programming reference
Setting and reading the data for the entire structure (for sending and receiving)
The data for an entire record or data group is read using the getBytes() method and
written using the setBytes() method.
With the communication methods of BeanConnect for sending and receiving data
(sndRecord(), rcvRecord() and call() methods with the ByteContainer parameter)
it is also possible to specify the Java objects directly because all classes representing
COBOL structures generated by Cobol2Java implement the ByteContainer interface.
Example 36 Sending and receiving data
// Java object which was created by Cobol2Java
EmployeeRecord emplRecord = new EmployeeRecord();
// Set encoding of the connection
emplRecord.setEncoding( connection.getEncoding() );
emplRecord.setEncodingActive( connection.isEncodingActive() );
// Connection object: sndRecord/rcvRecord method
connection.sndRecord(emplRecord);
connection.rcvRecord(emplRecord);
With the sndRecord() call the data from emplRecord is sent on the connection and with
the rcvRecord() call the data from the connection is stored in emplRecord.
Detailed information on encoding is provided in the Chapter 10, "Encoding and national
language support".
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
I
To modify a data field XXX, it is not sufficient simply to modify the
object obtained via the get<XXX> method. Instead, the field has
to be modified using one of the set<XXX> methods.
Example 37 Getting and storing data
// Data is received and stored in the EmployeeRecord
connection.rcvRecord(in);
(1)
PicX
lastName;
String
newName = "MyName";
lastName = in.getLastName();
(2)
lastName.setString(newName);
(3)
in.setLastName(lastName);
(4)
// or in.setLastName(newName);
(5)
// The data stored in EmployeeRecord is sent connection.sndRecord(in);
BeanConnect V2.1
503
Programming reference
Cobol2Java
where:
(1) Java class which was created by Cobol2Java from a COBOL data structure
(2) Return data field as PicX object
(3) Modify PicX object
(4) Modify data field via set method with PicX parameter
(5) Modify data field via set method with String parameter
14.3.4 Java/EBCDIC conversion
For conversion, proceed as follows:
1. Create the Cobol2Java objects with an empty constructor.
cob2javaclass cob2java = new cob2javaclass();
2. Then set the encoding of the connection:
cob2java.setEncoding( connection.getEncoding() );
cob2java.setEncodingActive( connection.isEncodingActive() );
3. Specify the Cobol2Java objects directly in the communication methods:
sndRecord(ByteContainer), rcvRecord(ByteContainer),
call(ByteContainer, ByteContainer)
Detailed information on encoding is provided in the Chapter 10, "Encoding and national
language support".
14.3.5 Formatted mode support
Cobol2Java provides restricted formatted mode support. The Kcat class is used to simplify
the use of +formats. This class contains constants for KDCS ATTRIBUTE for formatted mode
support.
504
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k14
Cobol2Java
Example
14.4 Example
This section provides an example for the conversion of the data types in a COBOL program
into Java classes. It contains information on how to convert a simple COBOL program in a
standard case. Below you will find information on the:
●
COBOL example program
●
Creating the XML description
●
Generating the Java classes
●
Use of the generated classes
14.4.1 COBOL example program
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
The following program employee.cbl is used as an example.
IDENTIFICATION DIVISION.
PROGRAM-ID. EMPLOYEE.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 EMPLOYEE-RECORD
05 EMPLOYEE-NUMBER
05 FIRST-NAME
05 LAST-NAME
05 PAY-METHOD
05 SALARY-INFO.
10 ANNUAL-SALARY
LINKAGE SECTION.
COPY KCKBC.
...
COPY KCPAC.
PROCEDURE DIVISION
...
BeanConnect V2.1
PIC
PIC
PIC
PIC
X(08).
X(20).
X(20).
X.
PIC 9(5).
505
Example
Cobol2Java
14.4.2 Creating the XML description
The XML description employee.xml can be generated in BS2000/OSD with Cobol2XML
on the basis of the COBOL program employee.cbl. The file employee.xml must then be
transferred to the UNIX or Windows system.
Detailed information on Cobol2XML is provided in Section 14.2.1, "Creating an XML
description for a COBOL program in BS2000"
Transferring the LMS library COB2XML.LIB to BS2000/OSD
Send the file COB2XML.LIB to BS2000/OSD (see Section 14.2.1.1, "Transferring the LMS
library to BS2000/OSD").
Converting the data structures from the COBOL program to XML
1. Log on to the BS2000/OSD system under the user ID where the files COB2XML.LIB and
EMPLOYEE.CBL are located.
2. Assign the link name COBLIB<n> (<n>= 1, .., 9) to the COPY libraries required for
converting the source:
/ADD-FILE-LINK COBLIB1, $TSOS.SYSLIB.UTM.053.COB
3. Start the D.XMLPROG procedures from the COB2XML.LIB library:
CALL-PROC
FROM-FILE=*LIBRARY-ELEMENT(LIBRARY=COB2XML.LIB,ELEM
=D.XMLPROG)
,PROCEDURE-PARAMETERS=(
SRC=FILE,TSTNAM=employee.cbl,
XMLOUT=employee.xml)
The D.XMLPROG procedure generates the XML description of the data structures used
in the COBOL program in the file employee.cbl. The XML description is stored in the
file employee.xml.
Transferring the XML descriptions to the UNIX system or Windows system
Transfer the XML description employee.xml in text format to the UNIX system or Windows
system, for example to the samples subdirectory of Cobol2Java, for further processing.
506
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k14
Cobol2Java
Example
14.4.3 Generating the Java classes
The EmployeeRecord class is generated by Cobol2Java in UNIX systems or Windows on
the basis of the XML file employee.xml. The classes are generated by Ant, compiled, and
packed in the JAR file employee.jar, which can then be used as a basis for a
BeanConnect client. You call Ant with the script runAnt.
Detailed information on generation is provided in Section 14.2.2, "Generating Java classes
on UNIX or Windows systems".
Defining the configuration
Edit the parameter file cobol2java.properties for Ant as follows:
xml.file=samples/employee.xml
cobol.struct=EMPLOYEE-RECORD
package.name=de.siemens.cob2java.test
doc.dir=doc
jar.dest=employee.jar
code.convention=java
Setting the PATH variable
To enable runAnt to run, it must be possible to call the Java programs javac and javadoc.
Extend your PATH environment variable by adding the Java SDK program directory.
2. Call runAnt.sh (UNIX systems) or runAnt.bat (Windows systems).
During generation, the Java sources are created in the src directory, compiled, and stored
in the JAR file employee.jar. The Javadoc of the created classes can be found in the doc
directory.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Starting generation
1. Switch to the Cobol2Java home directory.
BeanConnect V2.1
507
Example
Cobol2Java
14.4.4 Use of the generated classes
It is possible to create applications on the basis of the generated classes. The following
class provides an example of a BeanConnect client on the basis of the class EmployeeRecord.
package net.fsc.jca.beanconnect.qa;
import javax.ejb.SessionBean;
import javax.ejb.SessionContext;
import de.siemens.cob2java.cobtypes.*; // Runtime of Cobol2Java
import de.siemens.cob2java.test.EmployeeRecord
public class EmployeeServiceBean implements SessionBean
{
private net.fsc.jca.communication.EISConnectionFactory cf;
public void ejbCreate() throws javax.ejb.CreateException
{
try {
javax.naming.Context ic = new
javax.naming.InitialContext();
cf =(net.fsc.jca.communication.EISConnectionFactory)
ic.lookup
("java:comp/env/eis/myEIS");
} catch (javax.naming.NamingException ex) {
throw new javax.ejb.CreateException
("NamingException:"+ex);
}
}
public void ejbActivate()
{
}
public void ejbPassivate()
{
}
public void ejbRemove()
{
}
public void setSessionContext(SessionContext ctx)
{
}
508
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k14
Cobol2Java
Example
public String addSalary(String employeeNr, int
salaryIncrease)
{
String retValue = "";
net.fsc.jca.communication.EISConnection con = null;
try {
con = cf.getConnection();
con.setServiceName("EMPLOYEE");
June 8, 2009 7:06 pm
// Create EmployeeRecord and accept the encoding setting
// of the connection
EmployeeRecord employee = new EmployeeRecord();
try
{
employee.setEncoding( con.getEncoding() ); }
catch (net.fsc.beanta.encoding.EncoderException encEx) {
// todo Error handling
} // catch EncoderException
employee.setEncodingActive( con.isEncodingActive() );
// Fetch the required EmployeeData
employee.setEmployeeNumber( employeeNr );
con.sndRecord( employee );
con.rcvRecord( employee );
© cognitas GmbH 2001-2
// Increase the salary and send modification
int oldSalary =employee.getSalaryInfo().
getAnnualSalary().intValue();
employee.getSalaryInfo().setAnnualSalary( oldSalary+
salaryIncrease );
con.sndRecord( employee );
con.rcvRecord( employee );
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
retValue="Salary for "+employee.getLastName()+"
increased from "+oldSalary +" to "+
employee.getSalaryInfo().getAnnualSalary();
con.close();
} // try
catch (net.fsc.jca.communication.EISConnectionException
eisEx) {
if (con != null) {
try {
con.close();
} catch(Throwable thr) { }
}
throw new javax.ejb.EJBException
("EISConnectionException:"+eisEx);
BeanConnect V2.1
509
Example
Cobol2Java
} // catch EISConnectionException
catch (de.siemens.cob2java.cobtypes.
Cob2JavaException cobEx) {
if (con != null) {
try {
con.close();
} catch(Throwable thr) { }
}
throw new javax.ejb.EJBException("Cob2JavaException:
"+cobEx);
} // catch Cob2JavaException
return retValue;
} // addSalary
}
510
BeanConnect V2.1
Error messages and error handling
14.5 Error messages and error handling
The following table provides an overview of the error messages that may be output by the
tool Cobol2Java:
No Errors
Error handling
1
Check whether all the required JAR files are
present in the Cobol2Java lib directory.
Saxon:
No compatible XSLT Processor
found. Please use Saxon 6.5.2
or Xalan 2.5.2+ Processor
●
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicso.k14
Cobol2Java
saxon.jar
Xalan
●
xalan.jar
●
xercesImpl.jar
2
TransformerFactoryConfigurationError
See 1.
3
Could not create file <name>
Please make sure that you possess the necessary
data access authorizations for the data medium.
4
No Record/Field <name> found
in specified XML document
The name of the data structure is incorrect.
Please check.
5
WARNING! Multiple occurrence
of <name>
The document contains multiple structures
with the specified name. In this case, there is
no generation.
If a data element that is not supported by Cobol2Java is encountered then a generic data
element of type PicU is generated. Developers can access the information relating to this
element by means of getBytes/setBytes.
Error handling in the Cobol2Java classes is based on COBOL and is extremely tolerant.
Input data longer than the field it is to be stored in is truncated to the destination field length.
Invalid inputs, for example the input of an invalid number, result in the generation of a
NumberFormatException.
BeanConnect V2.1
511
Error messages and error handling
512
Cobol2Java
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\glossary.fm
June 8, 2009 7:06 pm
Glossary
access point
See service access point.
ACID properties
Acronym for the fundamental properties of a transaction: atomicity, consistency, isolation
and durability.
advanced program-to-program communication (APPC)
Another name for the LU6.2 protocol and the underlying architecture.
APPC
See advanced program-to-program communication (APPC).
appender
Log4j message destination. The logging messages transferred to a logger are output by the
appender(s) assigned to the logger.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
application entity
An application entity represents all the aspects of a real application which are relevant to
communications. An application entity is identified by a globally unique name ("globally" is
used here in its literal sense, i.e. worldwide), the application process title (APT). Every application entity represents precisely one application process. One application process can
encompass several application entities.
application entity qualifier (AEQ)
According to the OSI standard, the application entity qualifier identifies a service access
point within an application.
application entity title
An application entity title is a globally unique name for an application entity ("globally" is
used here in its literal sense, i.e. worldwide). It is made up of the application process title
(APT) of the relevant application process and the application entity qualifier (AEQ).
BeanConnect V2.1
513
application process
Glossary
application process
The application process represents an application in the OSI reference model. It is uniquely
identified globally by the application process title (APT).
application process title (APT)
According to the OSI standard, the application process title is used for the unique identification of applications on a global (i.e. worldwide) basis.
association (OSI)
An association is a communication relationship between two application entitys.
application server
An application server (J2EE Server) is the basic component of an EJB architecture. The
application server offers the services of enterprise applications to the EJB clients.
application server cluster
Cluster consisting of multiple application servers. In such a cluster, n instances of the
application server can be assigned to m proxy instances.
asynchronous job
Job carried out by the job receiver at a later time. Processing is carried out independently
of the job submitter.
asynchronous service
A service in openUTM which processes a background job.
authentication
See system access control.
authorization
See data access control.
Basic Communication Access Method (BCAM)
BCAM forms the basis for the data communication system for BS2000 hosts or in the
BeanConnect proxy container.
basic conversation
A basic conversation is a type of APPC conversation in which the CICS application must
add control bytes to the application data for transmission to the partner.
514
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\glossary.fm
Glossary
BCAM
BCAM
see Basic Communication Access Method (BCAM).
BeanConnect Management Console
The BeanConnect Management Console is the tool for administering and configuring the
BeanConnect components. It provides a graphical user interface.
BeanConnect proxy
A BeanConnect proxy is the BeanConnect component which communicates with the
resource adapter within the application server as well as with the EIS.
A BeanConnect proxy consists of a proxy container based on the transaction monitor
openUTM.
With CICS, a BeanConnect proxy consists additionally of an openUTM-LU62 Gateway and
the communication service.
BeanConnect proxy container
The BeanConnect proxy container is the core of the BeanConnect proxy. The proxy
container comprises the definitions of the objects used for outbound communication and
inbound communication and the configuration of the communication partner (resource
adapter and EIS partners).
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
BeanConnect resource adapter
The BeanConnect resource adapter is the BeanConnect component that is running on the
application server and that implements the JCA-compliant interfaces. In the case of
inbound communication and outbound communication via the OSI-TP protocol, the
BeanConnect proxy is additionally needed for the connection between the EIS and the
resource adapter.
BPEL
see Business Process Execution Language (BPEL).
Business Process Execution Language (BPEL)
The Business Process Execution Language (BPEL) is an XML-based language for the
description of business processes whose individual activities are implemented via Web
services, see Web Service Description Language (WSDL).
CCI
See common client interface (CCI).
CICS
See Customer Information Control System (CICS).
BeanConnect V2.1
515
cluster
Glossary
cluster
A cluster is a number of networked computers that are seen as a single computer from the
outside for many purposes. As a rule, the individual elements in a cluster are connected to
each other over a fast network. The aim of establishing a cluster is to increase CPU capacity
or availability.
See also application server cluster and proxy cluster.
CMX
See Communications Manager for UNIX Systems (CMX).
common client interface (CCI)
CCI is a component of the J2EE Connector architecture (JCA) and provides an EIS
independent client API for accessing EISs.
communication service
Service required by a BeanConnect proxy for communication between the proxy container
and a CICS partner. The communication service works directly with the openUTM-LU62
Gateway and is provided by the IBM Communications Server or SNAP-IX independently of
the platform. SNAP-IX or the IBM Communications Server represent software prerequisites
for BeanConnect if communication is to be performed with CICS partners. However, they
are not supplied with BeanConnect.
Communications Manager for UNIX Systems (CMX)
CMX is the basic product for communication software running on operating systems like
Solaris. A license is required for its use.
component
Reusable software unit with standardized interfaces that can usually be manipulated in a
development environment.
configuration property
Configuration properties are used to configure the resource adapter. A configuration
property is set in a configuration file by means of XML tags.
connection factory
A connection factory is used by an EJB of an application server to open a connection to an
external data source (EIS). The connection factory is provided when the application server
is started in the JNDI name directory.
516
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\glossary.fm
Glossary
connection pooling
connection pooling
Connection pooling manages connections that are expensive to create and destroy.
Connection pooling is used to improve scalability and performance in an application
environment.
connector architecture
See J2EE Connector architecture (JCA).
container.properties
Configuration file of a BeanConnect proxy. Many of the changes you make using the
BeanConnect Management Console are saved in the container.properties file.
contention winner / contention loser
Each connection between two partners is managed by one of the partners. This partner is
called the contention winner, while the other partner is referred to as the contention loser.
Jobs can be initiated by both partners. If both partners submit a job at the same time, priority
is given to the contention winner.
control point (CP)
The control point is responsible for managing the end node and its resources in an APPN
(advanced peer-to-peer-networking) network.
conversation
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
A conversation is a logical connection between two transaction programs in an LU6.2
session. A conversation begins with Allocate and ends with Deallocate. A conversation
allocates a session for its entire life and locks out all other users.
CP
See control point (CP).
Customer Information Control System (CICS)
CICS is the IBM transaction monitor. CICS is available for various platforms such as
CICS/ESA for the z/OS operating system. An OLTP application based on CICS is called a
CICS application.
data access control
The application server checks whether a communication partner/client is authorized to
access a particular business method. The access rights are set as part of the configuration.
BeanConnect V2.1
517
data link control (DLC)
Glossary
data link control (DLC)
Data link control is the service provided by the data link layer. The data link layer corresponds to layer 2 of the Open Systems Interconnection model for network communication
(LAN, Enterprise Extender for example).
deployment descriptor
A deployment descriptor is a file in XML format that is used for the deployment of EJBs or
resource adapters. A deployment descriptor provides configuration information that is not
contained in the EJB code or the resource adapter code.
dialog service
Service which processes a job interactively (synchronously) in conjunction with the job
submitter. A dialog service processes dialog messages received from the job submitter and
generates dialog messages to be sent to the job submitter. A dialog service comprises at
least one transaction. In general for openUTM, a dialog service encompasses at least one
dialog step.
dialog step
A dialog step starts when a dialog message is received by the openUTM application. It ends
when the openUTM application responds.
distributed program link (DPL)
DPL is a program interface that enables a CICS program to call another CICS program
which may reside on a remote CICS system. DPL is like calling a subprogram.
distributed transaction
See global transaction.
distributed transaction processing (DTP
with openUTM partners:
Transaction-oriented distributed processing with global transactions. Distributed
processing means that jobs are processed by several different applications.
with CICS partners:
Distributed transaction processing is a programming interface that enables a CICS transaction to invoke another CICS transaction (possibly in another CICS system). DTP
supports the handling of global transactions. It is similar to the client-sever programming
model.
DLC
See data link control (DLC).
518
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\glossary.fm
Glossary
DPL
DPL
See distributed program link (DPL).
DTP
See distributed transaction processing (DTP.
EIS
See Enterprise Information System (EIS).
EJB
See Enterprise JavaBeans (EJB).
EJB container
Runtime environment for EJB components. It is embedded in an application server.
Enterprise Information System (EIS)
This is a term used to describe external data sources such as ERP systems (Enterprise
Resource Planning systems such as SAP), OLTP applications such as openUTM applications/CICS applications or database systems such as Oracle DB, SESAM, UDS.
An EIS that communicates with the application server by means of BeanConnect is called
an EIS partner.
Enterprise JavaBeans (EJB)
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
Enterprise JavaBeansTM (EJB) is a component technology that allows the development of
cross-platform, multitier, distributed server applications within a modular architecture.
function unit commit
A function group in the OSI-TP protocol that is required to create distributed transactions.
Whether or not the functional unit commit may be used is negotiated when an association
is set up between the two partners. OSI-TP dialogs can run with or without the functional
unit commit in an association in which the functional unit commit was agreed to. An association is a communication relationship between two applications.
function unit handshake
A function group in the OSI-TP protocol that can be used by the communication partners to
coordinate the processing of a dialog at application level. This function makes it possible to
request processing confirmations and send positive or negative confirmations. No
inter-application transaction management is linked to this function.
global transaction
A global transaction is a transaction extending over more than one application.
BeanConnect V2.1
519
IBM Communications Server
Glossary
IBM Communications Server
IBM Communications Server is an IBM product that connects applications in SNA networks
with applications in TCP/IP networks.
In BeanConnect, the IBM Communications Server is used for communication between a
BeanConnect proxy and a CICS partner application using the LU6.2 protocol on Linux and
Windows systems.
inbound communication
Inbound communication is communication from an EIS to a J2EE application server.
inbound message endpoint
An inbound message endpoint is an endpoint of the inbound communication within the
J2EE application server.
For each inbound message endpoint in the application server, an identically named inbound
message endpoint must be configured in the BeanConnect proxy by means of the
BeanConnect Management Console. A BeanConnect proxy may have several endpoints.
inbound service
Inbound services represent the objects addressed by the EIS partners during inbound
communication. The inbound services known to the Management Console are defined
implicitly by the inbound message endpoints.
Exactly one inbound message endpoint is assigned to each inbound service.
inbound user
An inbound user is a user name and password that can be delivered from the EIS to the
BeanConnect proxy during inbound communication.
J2EE container
A J2EE container is an EJB container which is compliant with the standard of the Java2
Enterprise Edition Specification from Sun Microsystems.
J2EE Connector architecture (JCA)
The J2EE Connector architecture defines a standard architecture for connecting the J2EE
platform to heterogeneous EISs.
Java Development Kit (JDK)
Standard development environment from Sun Microsystems for developing applications
written in Java.
520
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\glossary.fm
Glossary
Java Naming and Directory Interface (JNDI)
Java Naming and Directory Interface (JNDI)
JNDI is a standard Java extension that provides a uniform API for accessing the directory
and naming services of different vendors.
JCA
See J2EE Connector architecture (JCA).
JDK
See Java Development Kit (JDK).
JMX
Java Management Extensions (JMX) is a specification developed by the Java Community
Process (JSR-3) for managing and monitoring Java applications.
JMX client
Client that can access a JMX server and make use of its services. In BeanConnect, the
Management Console represents the JMX client implementation.
JMX server
Instance in a Java application that provides services for monitoring the application. In a
BeanConnect environment, the application server implements the JMX server functionality.
job-receiving service
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
A job-receiving service is a service started by a job-submitting service of another server
application.
job-submitting service
A job-submitting service is a service which requests another service from a different server
application (job-receiving service) in order to process a job.
KDCA
Default name of the KDCFILE.
KDCDEF
openUTM generation tool resp. generation tool of the BeanConnect proxy container.
BeanConnect V2.1
521
KDCFILE
Glossary
KDCFILE
Configuration file of a BeanConnect proxy container. The file contains data required by the
container application for execution. The file is created with the generation tool KDCDEF.
with openUTM partners:
Configuration file of an openUTM partner application. The file contains data required by the
openUTM partner application for execution. The file is created with the openUTM generation tool KDCDEF.
KDCS
Universal openUTM program interface compliant with the national DIN 66 265 standard and
which includes some extensions. KDCS (compatible data communications interface) allows
dialog services to be created, for instance, and provides calls for distributed processing. In
BeanConnect, KDCS is only used as an internal interface.
Log4j
BeanConnect uses the software product Log4j to provide trace and logging functionality.
Log4j is a component of the Apache Jakarta project. Log4j provides interfaces for logging
information (runtime information, trace records etc.) and for configuring the log output.
Log4j is configured by means of the BeanConnect Management Console.
logger
A logger is a Log4j message source. Programs that must write logging information retrieve
logger objects with predefined names from Log4j and output their messages via these
objects. The destination to which Log4j sends the messages is transparent to the program.
logical unit (LU)
A logical unit is a logical virtual port which provides a user with access to network services
in an SNA network. The logical unit corresponds with the control point (CP) and a partner
logical unit representing, for example, a user program.
LU
See logical unit (LU).
LU6.2 protocol
The LU6.2 protocol is a component of the IBM network. LU6.2 defines methods for
program-to-program communication between applications on different computers.
mapped conversation
A mapped conversation is a type of APPC conversation in which the data passed to and
received from another APPC application is simply user data. The user is not concerned with
the internal data formats demanded by the architecture.
522
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\glossary.fm
Glossary
MBean
MBean
Java Bean which represents a resource of a JMX server.
MC-CmdHandler
The MC-CmdHandler is a BeanConnect component which is required in order to administer
another, remote BeanConnect component using the BeanConnect Management Console.
In this case, the function scope is the same as when administering a local component.
message
A message is a data packet that consists of a header and a body. The header contains
addressing data, the network routing and possibly data on the message format. The body
contains the actual message in the form of business data or system messages.
message-driven bean
A message-driven bean is a component of the Enterprise JavaBeans Version 2.1 specification from Sun Microsystems.
Message-driven beans are beans for the reception of messages. Message-driven beans
are only called by the EJB container and therefore have no home or remote interfaces.
message endpoint
message endpoint
A message endpoint is a message-driven bean application deployed in an application
server.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
message listener
message listener
Message consumer. The message listener object is sent messages as soon as they
become available. Message-driven beans are message listeners.
message listener interface
message listener interface
Interface that a message listener must implement. Inbound resource adapters provide
specific message listener interfaces which message listeners must implement if they are to
consume messages from this resource adapter.
mode name
The mode name is a symbolic name for a list of session properties and is required for all
interconnection requests over SNA. The mode name is used by the initiator of a session.
BeanConnect V2.1
523
multiple resource adapter mode
Glossary
multiple resource adapter mode
Configuration in which a BeanConnect proxy interacts with multiple resource adapters.
These resource adapters may be located on different application servers.
multi-step transaction
A multi-step transaction is a transaction which comprises more than one dialog step.
naming
Mapping of names to object references. The mapping is usually performed via a naming
service.
network name
A network name is a name identifying an SNA network and is a component of the logical
unit name, see logical unit (LU).
OC4J
see Oracle Application Server.
OLTP message-driven bean
OLTP message-driven beans are EJBs that receive and process jobs from OLTP applications (openUTM/CICS applications). The OLTP application addresses the OLTP
message-driven bean via an inbound message endpoint.
openUTM
Transaction monitor from Fujitsu Technology Solutions and basic component of the
BeanConnect proxy container.
openUTM application
An OLTP application based on the transaction monitor openUTM of Fujitsu Technology
Solutions.
openUTM-LU62 Gateway
openUTM-LU62 is a BeanConnect proxy component which acts as the interconnection with
partner applications supporting the SNA protocol LU6.2, particularly with CICS applications.
openUTM socket protocol (USP)
A protocol used by openUTM partner applications to convert byte streams into messages
that require the TCP/IP transport system.
Oracle Application Server
Application server from Oracle Corporation. The core J2EE runtime component of Oracle
Application Server is OC4J (Oracle Application Server Containers for J2EE).
524
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\glossary.fm
Glossary
OSI-LPAP partner
OSI-LPAP partner
OSI-LPAP partners are the addresses of the OSI-TP partners generated in the
BeanConnect proxy container. In the case of distributed processing via the OSI-TP
protocol, an OSI-LPAP partner for each partner application must be configured in the proxy
container. In the case of openUTM partners, the OSI-LPAP partner in the proxy container
represents the partner application and in the case of CICS partners, it mirrors the
openUTM-LU62 Gateway instance. During communication, the partner application is
addressed by the name of the assigned OSI-LPAP partner and not by the application name
or address.
OSI reference model
The OSI reference model provides a framework for standardizing communications in open
systems. ISO, the International Organization for Standardization, described this model in
the ISO IS7498 standard. The OSI reference model divides the necessary functions for
system communication into seven logical layers. These layers have clearly defined interfaces to the neighboring layers.
OSI-TP
Open System Interconnection Transaction Processing.
A communication protocol defined by ISO for distributed transaction processing.
A partner of an application that communicates with the BeanConnect proxy container via
the OSI-TP protocol is called an OSI-TP partner.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
In the case of openUTM partners this is the EIS partner and in the case of CICS partners
it is the openUTM-LU62 Gateway.
With CICS, this protocol is used for communication between the BeanConnect proxy
container and the openUTM-LU62 Gateway.
OSS
OSI Session Service
OSS forms the basis for OSI-TP data communication in the BeanConnect proxy container.
outbound communication
Outbound communication is communication from the J2EE application server to the EIS.
outbound communication endpoint
An outbound communication endpoint is a symbolic name representing a service of the
partner EIS.
BeanConnect V2.1
525
outbound service
Glossary
outbound service
An outbound service object describes a service (transaction code) inside the EIS partner
for outbound communication.
PCMX
The basis for communication software which runs on the Solaris, Linux and Windows
operating systems.
physical unit (PU)
Every node in an SNA network contains a physical unit as an addressable SNA instance.
Before two logical units (LUs) can open a communication relationship in the SNA network,
a communication relationship must first be opened between the corresponding PUs.
proxy cluster
Cluster consisting of more than one BeanConnect proxy and which is administered via the
BeanConnect Management Console.
proxy container
See BeanConnect proxy container.
PU
See physical unit (PU).
resource adapter
Resource adapters (also referred to as connectors) connect the application server to an
EIS, see also BeanConnect resource adapter.
resource manager
Resource managers (RMs) manage data resources. Database systems are examples of
resource managers.
RFC1006
A protocol defined by the IETF (Internet Engineering Task Force) belonging to the TCP/IP
family that implements the ISO transport services (transport class 0) based on TCP/IP.
schema
see XML Schema.
526
BeanConnect V2.1
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\glossary.fm
Glossary
service
service
Services process the jobs that are sent to a server application. Services can be requested
by clients or by other servers. A service of an openUTM application or of a CICS application
comprises one or more transactions. The first transaction is called with the service TAC or
transaction program name.
With openUTM, there are two types of services: dialog services and asynchronous
services. openUTM provides the program units of a service with common data areas.
service access point
In the OSI reference model, a layer has access to the services of the layer below at the
service access point. In the local system, the service access point is identified by a selector.
During communication, the openUTM application links up to a service access point. A
connection is established between two service access points.
session
A session is understood to be a communication relationship between two LUs, more
generally between two addressable SNA instances.
single-step transaction
transaction which encompasses precisely one dialog step.
SNA
See Systems Network Architecture (SNA).
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
SNAP-IX
SNAP-IX is a product from Data Connection that connects applications in SNA networks
with applications in TCP/IP networks.
In BeanConnect, SNAP-IX is used for communication between a BeanConnect proxy and
a CICS partner application using the LU6.2 protocol on Solaris systems.
synchronization level (sync-level)
Designation in LU6.2 that characterizes the transaction security for distributed processing:
●
For sync-level 0 (none), only net data and error messages may be sent. Acknowledgments are not allowed.
●
For sync-level 1 (confirm), simple acknowledgments may also be sent in addition to net
data and error messages.
●
For sync-level 2 (sync point), full transaction security is activated for distributed transactions.
BeanConnect V2.1
527
synchronization point (sync point)
Glossary
synchronization point (sync point)
A logical point within the flow of a distributed process at which the common resources are
brought to a defined state. The term "end of transaction" is used instead in openUTM.
system access control
This involves the application server checking whether a user ID is authorized to work with
the application server.
Systems Network Architecture (SNA)
SNA is the designation for a series of communication protocols defined by IBM.
TAC
See transaction code (TAC).
transaction
Processing section within a service which has the ACID properties. If, during the course of
a transaction, changes are made to the application information, they are either made
consistently and in their entirety or not at all (all-or-nothing rule). The end of the transaction
forms a synchronization point (sync point).
transaction code (TAC)
Name by means of which a service of an openUTM application can be called.
user ID
Identifier for a user defined in the configuration for the openUTM / CICS application (with an
optional password for system access control) and to whom special data access rights (data
access control) have been assigned. A client must specify this ID (and any password which
has been assigned) when signing on to the openUTM application/CICS application.
USP
See openUTM socket protocol (USP).
UTM
See openUTM.
UTM application
See openUTM application.
Virtual Telecommunications Access Method (VTAM)
The component in an IBM host system that is responsible for remote data processing.
528
BeanConnect V2.1
Web Service Description Language (WDSL)
Web Service Description Language (WSDL)
The Web Services Description Language (WSDL) defines a platform, programming
language and protocol-independent XML specification for the description of network
services (Web services) for message exchange.
XML
XML (eXtensible Markup Language) is a metalanguage standardized by W3C (WWW
Consortium) in which the interchange formats for data and the associated information can
be defined.
XML Schema
XML Schema is a W3C recommendation for the definition of XML document structures. The
structure is described in the form of an XML document. In addition, a large number of data
types are supported.
Dokuschablonen fкr DARB XML in FSC-Layout Version 1.0 fкr FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2
June 8, 2009 7:06 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\glossary.fm
Glossary
BeanConnect V2.1
529
XML Schema
530
Glossary
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicsoIX.fm
June 8, 2009 3:36 pm
© cognitas GmbH 2001-2005
Dokuschablonen für DARB XML in FSC-Layout Version 1.0 für FrameMaker ab Version 7 vom 19.05.2005
Index
A
aborted application run 442
address an EIS application 299
administrable proxy 148
administration 247
functions 154
MC-CmdHandler 231
user password 170
Ant 485, 486, 492, 507
appender 386
BeanConnectLoggingFile 387, 407, 413
BeanConnectLoggingFileXML 408
BeanConnectManagementConsole 409
BeanConnectMCSocketAppender 409
BeanConnectShortLoggingFile 406
BeanConnectSysout 412
BeanConnectSysoutShort 405, 412
configuring 392
application recommendations
BeanConnect-specific interfaces or CCI 284
application run aborted 442
application server
deployment descriptor 112, 125
generating statistics 276
monitoring with MBean clients 271
application server connection (BPEL) 355
application-managed authentication 107, 121,
300
associated connections 296
asynchronous communication 40, 295, 306, 314
asynchronous request
durability 378
inbound communication 379
authentication
application-managed 107, 121, 300
BeanConnect V2.1
container-managed 107, 121, 300
user ID and password 300
availability
EIS partners 269
MC-CmdHandler 268
resource adapters 266, 267
availability of the proxy 263
B
BCAM configuration 242
BCAM trace 419
BeanConnect
communication variants 37
components 15, 28
EIS support 36
features 29
installing under Linux 53
installing under Solaris 46
installing under Windows 60
platform support 36
software prerequisites 36
target group 16
BeanConnect Management Console see Management Console
BeanConnect proxy see proxy
BeanConnect resource adapter see resource
adapter
BeanConnect tools 28, 83
uninstalling 83
BeanConnect-specific interfaces
application recommendations 284
connection factory interfaces 286
connection interfaces 287
for inbound communication 318
for outbound communication 286
531
Index
BeanConnect-specific interfaces (cont.)
program framework for inbound
communication 322
program framework for outbound
communication 303
beanconnect_i18n.properties 348
BeanConnect_Install.ini 67
BeanConnectI18N.jar 348
BPEL
InteractionSpecs 359
resource type 352
WSDL file 357
BPEL Designer 351
BPEL environment
deploying resource adapters 353
BPEL Process Manager 351
BPEL WSDL Generator 365
exiting 365
installing 365
online Help System 366
starting 365
BS2000/OSD as EIS partner 242
BS2000/OSD COBOL application 483
bufferedIO, property 100
byte array 288
byte container 288
C
CCI 298
application recommendations 284
asynchronous communication 306
Common Client Interface (CCI) 41
connection factory interfaces 298
connection interfaces 298
dialog communication 304
inbound communication 324
outbound communication 298
program framework for inbound
communication 324
program framework for outbound
communication 304
programming information 324
charset
custom 345
532
check availability
proxy cluster 263
CICS 23
configuration 244
input file 244
CICS application
inbound communication 315
outbound communication 301
CICS partners
defining 18
CICS program
invoking by another CICS program 302
cluster
adding proxy 182
displaying 181
generating 180
master 252
removing 183
removing proxy from 183
CMX
installing under Linux 54
CMX trace 420
COB2XML.LIB 486, 488
COBOL application
integrating with BeanConnect 483
COBOL clause
supported by Cobol2Java 499
COBOL COPY element
converting to XML 488
COBOL data structure
converting to XML 489
COBOL data type
mapping to Java class 488
supported by Cobol2Java 499
COBOL program
converting to XML 488
Cobol2Java 483
code conventions 500
conversion class 484
directory structure 486
error handling 511
example 505
formatted mode support 504
generation procedure 484
BeanConnect V2.1
Dokuschablonen für DARB XML in FSC-Layout Version 1.0 für FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2005
June 8, 2009 3:36 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicsoIX.fm
Index
Cobol2Java (cont.)
installing 486
Java-EBCDIC conversion 504
javadoc 486
naming conventions 500
programming reference 498
supported COBOL types and clauses 499
system requirements 485
Cobol2XML 484, 488
example 506
library 488
system requirements 485
code conversion 297, 334
code samples
inbound communication 327
outbound communication 309
code table
IBM 334
OSD_EBCDIC_DF03_IRV 339
OSD_EBCDIC_DF04_1 341
OSD_EBCDIC_DF04_15 343
OSD_EBCDIC_DF04_DRV 335
predefined 337
standard 334, 337
user-defined 345
command line installation
proxy container 67
Common Client Interface see CCI
communication
asynchronous 40, 295, 314
dialog 40, 290, 314
inbound 38, 42, 313
non-transactional 41
outbound 38, 41, 214, 286
transactional 40, 295
communication methods 288
communication protocol 37
communication service 30
starting with the Management Console 249
configuration
activating 228
CICS 244
EIS 239
EIS partner 152, 193
BeanConnect V2.1
error messages 435
files 160
proxy 151
saving 228
configuration file for EIS partner 211
connection
between BeanConnect and EIS partner 243
between BeanConnect and openUTM
via OSI-TP protocol 240
via RFC1006 protocol 242
via socket protocol 242
via UPIC protocol 241
connection factory 286
for deployment in the application server 113,
126
interfaces 286, 298
connection group see associated connections
connection interface 287
communication methods 288
inbound communication 318, 324
outbound communication 287
outbound communication (CCI) 298
connection management 24
connection pooling 106, 120
ConnectionFactory object 112
connections, associated 296
connectionURL, property 101
OSI-TP communication 101
UPIC communication 116
console.properties.xml 160
container-managed authentication 107, 121, 300
create BPEL process 355
custom charset 345
D
D.XMLCOPY 490
D.XMLPROG 489
data exchange
based on OltpMessagePart objects 291, 292
based on OltpMessageRecord objects 292,
294
DEBUG 385
533
Index
deployment descriptor
application server 112, 125
EJB 112, 125, 285
message-driven bean 285
resource adapter 113, 126, 285
diagnosis 150
diagnosis support 156
diagnostics
dumps and diagnostic dumps 417
IBM Communications Server (Linux) 431
IBM Communications Server (Windows) 433
Log4j 384
Management Console 422
openUTM-LU62 Gateway 424
proxy container 412
resource adapter 403
SNAP-IX 429
stderr log 415
stdout log 415
dialog communication 40, 290, 304, 314
display
MBean 273
MBean attributes 274
DMS error 439, 480
return codes 480
DPL (Distributed Program Link) 302
DTP (Distributed Transaction Processing) 302
dumps 417
E
EBCDIC 334
EIS
configuration 239
EIS application
addressing 299
querying information 301
EIS partner 149
adding to the Management Console 194, 203
availability 269
configuration 152
configuration files 211
configuration via the Management
Console 193
inbound communication connections 376
534
EJB
code file 112, 125
deploying 111, 124
deployment descriptor 112, 125
placing BeanConnect calls 299
ejb-jar.xml 112, 285
example 131
em 94
encoding 334
encoding, property
inbound 128
outbound 102, 117
encodingActive, property
inbound 129
outbound 103, 118
endConversation
XATMI outbound 308
Enterprise Java Bean see EJB
ERROR 385
error codes 480
error message
configuration 435
openUTM-LU62 Gateway 467
proxy 435
runtime 436
u62_adm 478
u62_gen 479
u62_sta 477
u62_start 467
u62_tp 468
error number, DMS errors 480
establish connection
to MBean server 272
expert mode 178
F
FATAL
385
BeanConnect V2.1
Dokuschablonen für DARB XML in FSC-Layout Version 1.0 für FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2005
June 8, 2009 3:36 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicsoIX.fm
Index
G
global configuration property 89
inboundListenerPort 93
proxyReconnectCount 140
proxyReconnectInterval 140
proxyURL 90
resourceAdapterAddresses 139
group, dump error code K060 442
H
high availability
369
I
IBM code tables 334
IBM Communications Server 30
diagnostics for Linux 431
diagnostics for Windows 433
starting with the Management Console 249
traces for Linux 431
inbound communication 38, 42
BeanConnect-specific interfaces 318
CCI 324
CICS application 315
communication types 39
interfaces 42
non-openUTM application 317
openUTM application 314
program 313
selecting the interface to be used 285
inbound message endpoint 149
adding to the Management Console 219
inbound programming
XATMI partners 317
inbound user 149
inboundListenerPort, property 93
INFO 385
install
BeanConnect under Linux 53
BeanConnect under Solaris 46
BeanConnect under Windows 60
CMX under Linux 54
Management Console under Linux 59
Management Console under Solaris 52
Management Console under Windows 65
BeanConnect V2.1
master installation under Linux 53
master installation under Solaris 46
master installation under Windows 60
openUTM under Linux 54
openUTM under Solaris 47
openUTM under Windows 61
parameter file 67
PCMX under Solaris 47
PCMX under Windows 61
proxy container under Linux 56
proxy container under Solaris 50
proxy container under Windows 64
proxy container via Windows command
line 67
resource adapter 69
installation
updating under Linux 74
updating under Solaris 73
updating under Windows 76
installation program
starting an update on Solaris systems 73
starting under Linux 56
starting under Solaris 49
starting under Windows 60
starting update under Linux 74
starting update under Windows 76
integration server connection (BPEL) 355
InteractionSpecs
BPEL 359
interface 283
BeanConnect-specific 286, 318
for inbound communication 318
for outbound communication 286
javax.resource.cci 298
javax.resource.cci.MessageListener 42, 324
net.fsc.jca.communication 41
net.fsc.jca.communication.cci 41
interface net.fsc.jca.communication.
AsyncOltpMessageListener 42, 322
EISConnection 287, 288
EISConnectionByteArray 288
EISConnectionByteContainer 288
EISConnectionFactory 286
EISConnectionString 289
535
Index
interface net.fsc.jca.communication. (cont.)
EISOltpConnection 287, 288, 289
EISOltpConnectionFactory 286
EISUpicConnection 287, 289
EISUpicConnectionFactory 286
EncodingDef 289
OltpMessageListener 42, 322
interfaces and programming 283
internationalization 347
J
J2EE
OC4J connection architecture 24
J2EE application server 23, 24
Java class
example for generating from COBOL XML
file 507
for internationalization 347
generating with Ant 492
example 495
parameters 492
generating without Ant 496
example 497
parameters 496
used for COBOL type 498
Java Development Kit (JDK) 26
Java Virtual Machine (JVM) 26
javax.resource.cci.Connection interface 298
javax.resource.cci.MessageListener
interface 324
JCA 1.5 specification 24
JCA contract 24
Common Client Interface 25
connection management 24
lifecycle management 25
message inflow 25
security management 24
transaction inflow 25
transaction management 24
work management 25
536
K
K messages 438
K009 438
K017 438
K036 438
K040
pagepool warning level
K041 439
K043 439
K049
start error 440
K055 441
K060 442
K065 446
K075 446
K078 447
K104 448
K119 450
K124 451
K128 452
K135 453
K139 453
K147 453
K152 454
K160 454
K204 454
K210 455
K211 455
K212 455
K213 455
K214 455
K215 455
K216 455
K217 455
K218 456
K220 456
K221 456
K222 456
K223 456
K224 456
K225 456
K230 456
K231 456
439
BeanConnect V2.1
Dokuschablonen für DARB XML in FSC-Layout Version 1.0 für FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2005
June 8, 2009 3:36 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicsoIX.fm
Index
KDCDEF
statements for OSI-TP communication 240
statements for socket or RFC1006
connection 242
statements for UPIC communication 241
kdcshut 282
L
language
changing via system properties 347
for message output 347
of online help system 145
lifecycle management 25
LINK command
parameter COMMAREA 302
parameter LENGTH 302
parameter PROGRAM 302
parameters 302
Linux
installing a proxy container 56
installing BeanConnect 53
installing CMX 54
installing Management Console 59
installing openUTM 54
installing packages 53
uninstalling BeanConnect 79
update installation 74
listener port 394
LMS library 488, 489, 490
localization 347
log window 146
Log4j 384
appender 386
configuration file in XML format 393
configuring appenders 392
configuring loggers 391
level 385
listener port 394
logger 384
rolling file appender 387
root logger 384
suppressing messages 397, 398
XML logging file 399
log4j.properties.xml 160
BeanConnect V2.1
logger 384
activating/deactivating the display of
messages 397
BeanConnect 410, 414
BeanConnect.c 414
BeanConnect.Datasources.OLTP 414
BeanConnect.in 410
BeanConnect.info 410, 414
BeanConnect.kdcs 414
BeanConnect.out 410
BeanConnect.ui 410
configuring 391
level 385
name space 384
net.fsc 410, 414
net.fsc.beanta.encoding 410
net.fsc.beanta.encoding.EncoderImpl 414
net.fsc.tpbasics.util.L 410, 414
root logger 414
logging
Log4j 384
proxy 415
resource adapter 403
logging configuration, predefined 412
logging file (XML) 399
logging files 387
logging level 398
logging output 396
example 396
LU6.2 protocol 37
M
Management Console 15, 143, 248
administration functions 154
advanced features 150
as Log4j socket reader 394
diagnosis support 156
diagnostics 422
expert mode 178
installing under Linux 59
installing under Solaris 52
installing under Windows 65
language 145
logging file (XML) 399
537
Index
Management Console (cont.)
managed objects 148
MC-CmdHandler 230
message output 347
navigation area 146, 147
outputting messages 396
overview 32
protocol window 146
proxy navigation tree 165
shutting down 145
starting online help 144
starting under Solaris and Linux 144
starting under Windows 144
status bar 146
todo topics 150, 156
user interface 146
work area 146
manual extension file 16
master
proxy cluster 252
master installation
under Linux 53
under Solaris 46
under Windows 60
MBean
displaying 273
operations 281
subscribing to notifications 278
MBean attributes
displaying 274
modifying 275
MBean clients 271
MBean server
establishing a connection 272
MC-CmdHandler 32, 230
administering 231
availability 268
installing 71
security and privileges 230
shutting down 232
starting 231
uninstalling 83
message
BeanConnect proxy container 435
538
u62_adm 478
u62_gen 479
u62_sta 477
u62_start 467
u62_tp 468
message file 348
message inflow 25
message length
XATMI outbound 308
message listener interface 38, 42
message output
determining the language 347
message types 436
message-driven bean see OLTP message-driven
bean
messageEndpoint, property 128
messages
of the proxy 396
outputting 396
suppressing 397, 398
messaging-type, property 127
modify MBean attributes 275
monitor
application server with MBean clients 271
N
navigation area 146, 147
net.fsc.jca.communication 41
net.fsc.jca.communication.cci 41
non-openUTM application
inbound communication 317
non-transactional communication 41
notational conventions 22
notification
from MBeans 278
subscribing 279
O
OC4J
J2EE connection architecture 24
oc4j-ra.xml 285
example 109
OFF
logging output 385
BeanConnect V2.1
Dokuschablonen für DARB XML in FSC-Layout Version 1.0 für FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2005
June 8, 2009 3:36 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicsoIX.fm
Index
OLTP message-driven bean 313
asynchronous communication 314
code samples 327
deploying 127
dialog communication 314
programming information 318, 324
properties 127
OltpMessage object 292
OltpMessagePart object 291, 292
OltpMessageRecord object 294
online help
starting 144
online help system, language 145
openSEAS 15
openUTM 23, 30, 240
installing under Linux 54
installing under Solaris 47
installing under Windows 61
openUTM application
inbound communication 314
openUTM dump 417
openUTM partner 240
configuring in proxy 194
openUTM socket protocol 39, 243
openUTM-LU62 Gateway 30
administering 259
diagnostic information 427
diagnostics 424
displaying status information 260
error messages 467
starting 259
starting via the Management Console
stopping 260
traces 424
operate the proxy 247
operations on MBeans 281
orion-ejb-jar.xml 112
example 134
OSD_EBCDIC_DF03_IRV 339
OSD_EBCDIC_DF04_1 341
OSD_EBCDIC_DF04_15 343
OSD_EBCDIC_DF04_DRV 335
OSI-SCRATCH-AREA 380
OSI-TP error 450
BeanConnect V2.1
OSS trace 418
outbound communication 38, 41
BeanConnect-specific interfaces 286
CCI 298
CICS application 301
code samples 309
configuring with the Management
Console 214
connection factory interfaces 286
connection factory interfaces (CCI) 298
connection interface 287, 298
program framework 303
programming 286
programming information 299
selecting the interface to be used 285
outbound communication endpoint 149, 214
configuring in the Management Console 217
outbound programming
XATMI partners 308
outbound service 149, 214
configuring in the Management Console 214
outputting messages 394
249
P
P messages 457
package net.fsc.jca.communication 41
pagepool area 375
parameter file for installation 67
Partner Link 368
password for authentication 300
PCMX
installing under Solaris 47
installing under Windows 61
PENDER 444
place BeanConnect calls in an EJB 299
port number 51, 58
port number interval, proxy container 64
predefined code table 337
privileges of MC-CmdHandler 230
process workload,workload 372
program 283
inbound communication 313
outbound communication 286
539
Index
program framework
AsyncOltpMessageListener,
OltpMessageListener 322
BeanConnect-specific interfaces 303
inbound communication 322
inbound communication (CCI) 324
javax.resource.cci.MessageListener
interface 324
outbound communication 303
outbound communication (CCI) 304
programming information 299
OLTP message-driven bean 318
OLTP message-driven Beans (CCI) 324
outbound communication 299
properties.xml
resource adapter 403
properties_debug.xml
resource adapter 403
properties_default.xml
resource adapter 403
properties_error.xml
resource adapter 403
property
bufferedIO 100
connectionURL 101, 116
displayName 101
encoding (inbound) 128
encoding (outbound) 102, 117
encodingActive (inbound) 129
encodingActive (outbound) 103, 118
inboundListenerPort 93
logLevel 104
messageEndpoint 128
messaging-type 127
proxyReconnectCount 140
proxyReconnectInterval 140
proxyURL 90
redeliveryThreshold 130
resourceAdapterAddresses 139
RevisionNumber 93
timeout 104, 119
transactional 105
transactionLogDir 92
transactionLogging 91
540
protocol window 146
proxy 15, 148
adding to Management Console 165
adding to Management Console
automatically 167
administrable 148
availability 263
BCAM trace 419
CMX trace 420
components 31
configuration steps 163
configuring 151, 161
context menu 248
diagnostics 412
error messages 435
functions 30
general information 168
ID 169
log files 415
Log4j socket reader 394
managing via the Management Console 248
message output 347
name in the Management Console 169
navigation tree 165
operating 247
OSS trace 418
outputting messages 396
performance settings 178
predefined logging configuration 412
removing from the Management
Console 167
restarting via a local script 256
restarting via the Management Console 155,
251
restarting via the Windows program
group 256
shutting down 154
starting 154
starting after abnormal termination 255
starting as Windows service 251, 255
starting via a local script 254
starting via the Management Console 249
starting via the Windows program group 254
stopping as Windows service 257
BeanConnect V2.1
Dokuschablonen für DARB XML in FSC-Layout Version 1.0 für FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2005
June 8, 2009 3:36 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicsoIX.fm
Index
proxy (cont.)
stopping in cluster 281
stopping via a local script 257
stopping via the Management Console 251
stopping via the Windows program
group 257
timer settings for connection
surveillance 178
traces 418
proxy cluster
checking availability 263
defining 180
master 252
removing 183
synchronizing 253
proxy component
configuring 168
starting via the Management Console 249
proxy container
asynchronous processing 378
cache 375
high availability 369
installing under Linux 56
installing under Solaris 50
installing under Windows 64
installing under Windows via command
line 67
number of processes 372
OSI-SCRATCH-AREA 380
pagepool area 375
port number 64
semaphores 381
shared memory 370
starting via the Management Console 249
workload 372
proxyReconnectCount, property 140
proxyReconnectInterval, property 140
proxyURL, property 90
BeanConnect V2.1
R
ra.xml
example 96, 122
setting the global configuration properties
RAR file
declaring 94
redeliveryThreshold, property 130
resource adapter 15, 24, 148
availability 266, 267
BPEL environment 353
configuration properties for outbound
communication 100, 115
configuring appenders 392
configuring loggers 391
deploying 94
deployment descriptor 113, 126
diagnostics 403
extend logging 404
functions 29
installing 69
logging 403
logging output 394
message output 347
predefined logging configuration 405
preparing logging 135
switching to other proxy 281
undeploying 96
resource type
BPEL 352
resource types 111, 124
resourceAdapterAddresses, property 139
restart proxy 155
RFC1006 application 243
RFC1006 connection
KDCDEF statements 242
RFC1006 protocol 39
rolling file appender 387
root logger 384
runAnt.bat (Windows system) 486, 494
runAnt.sh (UNIX system) 486, 494
runtime
error messages 436
89
541
Index
S
Saxon 485, 497
scalability 369
script
change 256
shutcontainer 257
startcontainer 254
security
MC-CmdHandler 230
security management 24
security settings
for connecting to EIS 107, 121
select the interfaces to be used 285
semaphores
number 381
shared memory 370
shut down
Management Console 145
MC-CmdHandler 232
SNA daemon 261
SNA implementation 30
SNAP-IX 30
diagnostics 429
starting with the Management Console
traces 429
socket connection
KDCDEF statements 242
socket listener port 394
socket reader
Log4j 394
Solaris
installing a proxy container 50
installing BeanConnect 46
installing Management Console 52
installing openUTM 47
installing packages 46
installing PCMX 47
uninstalling BeanConnect 78
update installation 73
standard code table 334, 337
standard conversion 334, 337
542
249
start
Management Console 144
Management Console under Solaris and
Linux 144
Management Console under Windows 144
MC-CmdHandler 231
online help 144
proxy 154
statistical information 150
statistics
for the application server 276
statistics collector 276
status bar 146
stderr 415
stdout 415
stop
proxy in cluster 281
stop proxy 154
with wait time 282
string 289
structure of the documentation 16
structure of the manual 17
subscribe
notifications 279
subscribe notifications 279
switch
resource adapter to other proxy 281
synchronize.
proxy cluster 253
SYSLOG 416
system error codes
ERRNO 481
system log file 416
T
timeout, property 104, 119
todo topics 150, 156
tools 15
uninstalling 83
TPOOL statement 241
TRACE 385
BeanConnect V2.1
Dokuschablonen für DARB XML in FSC-Layout Version 1.0 für FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2005
June 8, 2009 3:36 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicsoIX.fm
Index
traces
BCAM trace 419
CMX trace 420
IBM Communications Server (Linux)
openUTM-LU62 Gateway 424
OSS trace 418
proxy 418
SNAP-IX 429
transaction inflow 25
transaction management 24
transaction monitor openUTM 30
transactional communication 40, 295
transactional, property 105
transactionLogDir, property 92
transactionLogging, property 91
TRMA 442
TSEL-FORMAT statement 241
typed buffer 308
types, of messages 436
U
U messages 463
u62_adm
messages 478
u62_gen
messages 479
u62_sta
messages 477
u62_start
messages 467
u62_tp
messages 468
Unicode 334, 337
uninstall 83
BeanConnect under Linux 79
BeanConnect under Solaris 78
BeanConnect under Windows 80
MC-CmdHandler 83
update installation
under Linux 74
under Solaris 73
under Windows 76
UPIC application 243
UPIC message 453
BeanConnect V2.1
431
UPIC protocol 39
user ID for authentication 300
user interface 146
user-defined code table 345
V
VTAM
input file
244
W
WARN 385
Windows
installing a proxy container 64
installing a proxy container via command
line 67
installing BeanConnect 60
installing Management Console 65
installing openUTM 61
installing PCMX 61
master installation 60
uninstalling BeanConnect 80
update installation 76
work area 146
work management 25
WSDL file 357
creating 366
viewing 368
X
Xalan 485, 487, 497
XATMI partners
configure 213
configure proxy for 179
inbound programming 317
outbound programming 308
Xerces 487
XML
logging file 399
XML files 160
XML format
configuration file 393
XSLT processor 485, 497
XSLT stylesheet 484, 486
543
Index
544
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicsoloe.fm
Juni 8, 2009 3:36 pm
List of Examples
Example 1: Installing multiple packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Example 2: Installing multiple packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Example 3: Configuration properties in the file ra.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Example 4: Connection pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Example 5: Security section in oc4j-ra.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Example 6: Configuration properties in the file oc4j-ra.xml . . . . . . . . . . . . . . . . . . . . . . 109
Example 7: Connection pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Example 8: Security section in oc4j-ra.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Example 9: Configuration properties in the file oc4j-ra.xml . . . . . . . . . . . . . . . . . . . . . . 122
Example 10: ejb-jar.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Example 11: orion-ejb-jar.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Dokuschablonen für DARB XML in FSC-Layout Version 1.0 für FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2005
Example 12: Example of an URL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Example 13: Verifying that the OSI-TP protocol is used for communication
(openUTM partner) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Example 14: Information on the conversation with the EIS application . . . . . . . . . . . . . 301
Example 15: Dialog communication using the EISConnection interface . . . . . . . . . . . 309
Example 16: Dialog communication using the CCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Example 17: Associated connections using the EISConnectionGroup interface. . . . . . 311
Example 18: OLTP message-driven bean for dialog communication . . . . . . . . . . . . . . 327
Example 19: OLTP message-driven bean for asynchronous communication . . . . . . . . 328
Example 20: OLTP message-driven bean (CCI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Example 21: Using predefined code tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
BeanConnect V2.1
545
List of Examples
Example 22: oc4j-ra.xml in the BPEL environment (OSI-TP / LU6.2) . . . . . . . . . . . . . . 353
Example 23: oc4j-ra.xml in the BPEL environment (UPIC) . . . . . . . . . . . . . . . . . . . . . . 354
Example 24: WSDL file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Example 25: xsd file COBSOAIN.xsd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Example 26: xsd file COBSOAOUT.xsd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Example 27: Logger name space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Example 28: Logging level. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Example 29: Output of logging events through the appender . . . . . . . . . . . . . . . . . . . . 386
Example 30: Logging files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Example 31: Entries in the LogWriter file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Example 32: Control of logging output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
Example 33: Example for a cobol2java.properties file . . . . . . . . . . . . . . . . . . . . . . . . . . 495
Example 34: Generating Java classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
Example 35: Name assignment for the different code conventions. . . . . . . . . . . . . . . . 500
Example 36: Sending and receiving data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
Example 37: Getting and storing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
546
BeanConnect V2.1
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicsolof.fm
Juni 8, 2009 3:36 pm
List of Figures
Figure 1: OC4J – J2EE Connection Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Figure 2: BeanConnect components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Figure 3: BeanConnect components for outbound communication with
openUTM partners via UPIC protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Figure 4: BeanConnect proxy components of a CICS proxy . . . . . . . . . . . . . . . . . . . . . . 31
Figure 5: Relationships between the BeanConnect components in standard
operation and without a cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Figure 6: BeanConnect components in multiple resource adapter mode with
2 resource adapters and one proxy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Figure 7: Outbound communication for openUTM partners . . . . . . . . . . . . . . . . . . . . . . 38
Figure 8: Outbound communication for CICS partners . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Figure 9: Inbound communication for openUTM partners . . . . . . . . . . . . . . . . . . . . . . . . 39
Dokuschablonen für DARB XML in FSC-Layout Version 1.0 für FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2005
Figure 10: Inbound communication for CICS partners . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Figure 11: BeanConnect components in cluster operation . . . . . . . . . . . . . . . . . . . . . . . 43
Figure 12: User interface of the Management Console . . . . . . . . . . . . . . . . . . . . . . . . . 146
Figure 13: Navigation area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Figure 14: Starting the configuration wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Figure 15: Configuration wizard window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Figure 16: Proxies within the Management Console . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Figure 17: Adding a new proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Figure 18: General information on a proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Figure 19: Description of the proxy components for CICS partners . . . . . . . . . . . . . . . 172
Figure 20: Configuring the openUTM-LU62 Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . 173
BeanConnect V2.1
547
List of Figures
Figure 21: Configuring a communication service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Figure 22: Configuring the properties of a communication service . . . . . . . . . . . . . . . . 176
Figure 23: Generating a new proxy cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Figure 24: Adding a proxy to a proxy cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Figure 25: Adding a resource adapter without cluster operation . . . . . . . . . . . . . . . . . . 185
Figure 26: Configuring the properties of an MC-CmdHandler . . . . . . . . . . . . . . . . . . . . 187
Figure 27: Adding a resource adapter in cluster operation . . . . . . . . . . . . . . . . . . . . . . 188
Figure 28: Editing the configuration file ra.xml. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Figure 29: Displaying and configuring EIS partners. . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Figure 30: General properties of an EIS partner of Type openUTM . . . . . . . . . . . . . . . 195
Figure 31: Properties of the openUTM partner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Figure 32: Properties of the EIS partner for the availability check . . . . . . . . . . . . . . . . . 201
Figure 33: General properties of an EIS partner of type CICS . . . . . . . . . . . . . . . . . . . 204
Figure 34: Communication service properties of a CICS partner (single proxy) . . . . . . 206
Figure 35: Communication service properties of a CICS partner in a proxy cluster . . . 206
Figure 36: Properties of the CICS partner on a z/OS mainframe . . . . . . . . . . . . . . . . . 208
Figure 37: Properties of the CICS type EIS partner for the availability check . . . . . . . . 210
Figure 38: Configuring outbound services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Figure 39: Configuring outbound communication endpoints . . . . . . . . . . . . . . . . . . . . . 217
Figure 40: Configuring inbound message endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Figure 41: Configuring an inbound service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Figure 42: Configuring users for inbound communication . . . . . . . . . . . . . . . . . . . . . . . 226
Figure 43: Configuring the inbound error prefix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Figure 44: Setting up a JMX client for resource adapters . . . . . . . . . . . . . . . . . . . . . . . 236
Figure 45: Proxy context menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Figure 46: Administering a BeanConnect proxy cluster. . . . . . . . . . . . . . . . . . . . . . . . . 252
548
BeanConnect V2.1
Juni 8, 2009 3:36 pm
Pfad: E:\_Daten_karla\__BeanConnect\e\m0710001\BeanConnect_gesamt_englisch\bc4cicsolof.fm
List of Figures
Figure 47: Checking the availability of a BeanConnect proxy . . . . . . . . . . . . . . . . . . . . 264
Figure 48: Checking the availability of a resource adapter . . . . . . . . . . . . . . . . . . . . . . 266
Figure 49: Checking the availability of an openUTM-LU62 Gateway . . . . . . . . . . . . . . 267
Figure 50: Availability of an MC-CmdHandler instance . . . . . . . . . . . . . . . . . . . . . . . . . 268
Figure 51: Checking the availability of an EIS partner . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Figure 52: Navigation tree for an MBean. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Figure 53: MBean - object name subtree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Figure 54: MBean - attribute table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Figure 55: MBean - statistical values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Figure 56: MBean operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Figure 57: Data exchange based on OltpMessagePart objects (openUTM partners) . . 291
Figure 58: Data exchange based on OltpMessagePart objects (CICS partners) . . . . . 292
Figure 59: Data exchange based on OltpMessageRecord objects
(OSI-TP protocol with openUTM partners) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Figure 60: Data exchange based on OltpMessageRecord objects (CICS partners) . . . 293
Dokuschablonen für DARB XML in FSC-Layout Version 1.0 für FrameMaker ab Version 7 vom 19.05.2005
© cognitas GmbH 2001-2005
Figure 61: Data exchange based on OltpMessageRecord objects (UPIC protocol) . . . 294
Figure 62: Calling (Invoking) an openUTM service as a Partner Link for a
BPEL process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Figure 63: Creating a WSDL instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
Figure 64: Creating a WSDL file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Figure 65: Configuring the loggers (example of BeanConnect proxy). . . . . . . . . . . . . . 391
Figure 66: Configuring the appenders (example of BeanConnect proxy) . . . . . . . . . . . 392
Figure 67: Logging output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Figure 68: Cobol2Java generation procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
BeanConnect V2.1
549
List of Figures
550
BeanConnect V2.1
Download PDF
Similar pages