HP NonStop Server Guide for BEA WebLogic Server 9.2

Transcription

1 HP NonStop Server Guide for BEA WebLogic Server 9.2 Abstract This manual describes the installation, configuration, and management of the BEA WebLogic Server on HP Integrity NonStop NS-series servers. Product Version HP Integrity NonStop Server Toolkit for BEA WebLogic Server 9.2 Supported Release Version Updates (RVUs) This publication supports H06.10 and all subsequent H-series RVUs until otherwise indicated by its replacement publication. Part Number Published January 2008

2 Document History Part Number Product Version Published HP Integrity NonStop Server Toolkit for BEA WebLogic Server HP Integrity NonStop Server Toolkit for BEA WebLogic Server 9.2 July 2005 January 2008

3 Legal Notices Copyright 2008 Hewlett-Packard Development Company L.P. Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR and , Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein. Export of the information contained in this publication may require authorization from the U.S. Department of Commerce. Microsoft, Windows, and Windows NT are U.S. registered trademarks of Microsoft Corporation. Intel, Itanium, Pentium, and Celeron are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Java is a U.S. trademark of Sun Microsystems, Inc. Motif, OSF/1, UNIX, X/Open, and the "X" device are registered trademarks and IT DialTone and The Open Group are trademarks of The Open Group in the U.S. and other countries. Open Software Foundation, OSF, the OSF logo, OSF/1, OSF/Motif, and Motif are trademarks of the Open Software Foundation, Inc. OSF MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THE OSF MATERIAL PROVIDED HEREIN, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. OSF shall not be liable for errors contained herein or for incidental consequential damages in connection with the furnishing, performance, or use of this material. 1990, 1991, 1992, 1993 Open Software Foundation, Inc. This documentation and the software to which it relates are derived in part from materials supplied by the following: 1987, 1988, 1989 Carnegie-Mellon University. 1989, 1990, 1991 Digital Equipment Corporation. 1985, 1988, 1989, 1990 Encore Computer Corporation Free Software Foundation, Inc. 1987, 1988, 1989, 1990, 1991 Hewlett-Packard Company. 1985, 1987, 1988, 1989, 1990, 1991, 1992 International Business Machines Corporation. 1988, 1989 Massachusetts Institute of Technology. 1988, 1989, 1990 Mentat Inc Microsoft Corporation. 1987, 1988, 1989, 1990, 1991, 1992 SecureWare, Inc. 1990, 1991 Siemens Nixdorf Informationssysteme AG. 1986, 1989, 1996, 1997 Sun Microsystems, Inc. 1989, 1990, 1991 Transarc Corporation. This software and documentation are based in part on the Fourth Berkeley Software Distribution under license from The Regents of the University of California. OSF acknowledges the following individuals and institutions for their role in its development: Kenneth C.R.C. Arnold, Gregory S. Couch, Conrad C. Huang, Ed James, Symmetric Computer Systems, Robert Elz. 1980, 1981, 1982, 1983, 1985, 1986, 1987, 1988, 1989 Regents of the University of California. Printed in the US

4

5 HP NonStop Server Guide for BEA WebLogic Server 9.2 Glossary Index Examples Figures Tables Legal Notices What s New in This Manual v Manual Information v New and Changed Information Legal Notice v v About This Manual vii Who Should Read This Manual vii Organization of This Manual viii Related Documentation viii Notation Conventions ix 1. Introduction The WebLogic Server for the HP NonStop Server 1-1 Server-Specific Features 1-2 Enhancements 1-2 Native Socket Multiplexer 1-3 High Level Architecture 1-6 SMP Systems and HP NonStop Servers Installation 3. Migration 4. Configuring Persistent WebLogic Server Processes Overview of Generic Processes 4-2 Considerations 4-3 Configuration 4-3 Automatic Restart 4-3 Sample Scripts 4-3 Managed Servers 4-4 Generic Process Attributes 4-4 Sample Shell Scripts and TACL Macros 4-6 Hewlett-Packard Company i

6 Contents 4. Configuring Persistent WebLogic Server Processes (continued) 4. Configuring Persistent WebLogic Server Processes (continued) startgp.sh 4-6 startgp.tacl 4-6 Scripts to Start the WebLogic Server Process 4-6 stopgp.sh and stopgp.tacl 4-8 Using the Node Manager on the NonStop Server 4-8 Starting a Managed Server Through the Node Manager 4-9 nodemanager.sh 4-9 CPUselector 4-10 gname_load 4-11 jvm_load 4-11 managed_load 4-11 no_load 4-12 Configuring the Node Manager 4-12 Settings 4-12 Step 1. Create a Machine and Associate Servers to it 4-13 Step 2. Generate Node Manager Configuration Files 4-13 Step 3. Configure and Start the Node Manager 4-13 Step 4. Configure Managed Servers Startup Options 4-14 Step 5. Start Managed Servers Using the Node Manager 4-15 Step 6. Monitor Startup of the Managed Server 4-15 Troubleshooting and Notes 4-15 Starting the Node Manager from a Non-Default Location 4-16 Shutting Down a WebLogic Server Application Configuring JTA 6. XA Resource Manager (XARM) Configuring the WebLogic Server XA Resource Object 6-2 Configuring the XA Resource Manager Error Output Destination 6-3 Configuring the WLSNonStopTxHelper as a Startup Class 6-3 Configuring JDBC Connection Pools for SQL/MX 6-5 Configuring the WebLogic Server Data Sources for SQL/MX 6-8 Additional Considerations for JDBC Access to SQL/MX Databases Configuring JDBC Stores for JMS ii

7 Contents 8. Managing SQL/MX Tables for BLOB and CLOB Data 8. Managing SQL/MX Tables for BLOB and CLOB Data Creating SQL/MX Tables 8-1 Providing Properties to the JDBC Driver Sample Application WebLogic Server Sample Application 9-1 Running MedRec Application in the Installed WebLogic Server Location 9-1 Running MedRec in Another Location 9-5 A. Script Options Usage check-wl-hpns.sh A-1 install-wl-hpns.sh A-2 uninstall-wl-hpns.sh A-3 Glossary Index Examples Figures Tables Example 4-1. Server Environment File 4-10 Figure 1-1. Socket Reader Polling 1-4 Figure 1-2. Single Thread Polling 1-5 Figure 1-3. WebLogic Server on NonStop Server Architecture 1-6 Figure 1-4. WebLogic Server Domain Representation on a 4-Way SMP Machine 1-7 Figure 1-5. WebLogic Server Domain Representation on a NonStop Server 1-8 Figure 9-1. Initial MedRec Screen 9-4 Figure 9-2. MedRec Logon Screen 9-5 Table 4-1. Generic Process Attributes Table 4-5 Table 6-1. Java System Properties used by WLSNonStopTXHelper 6-4 iii

8 Contents iv

9 What s New in This Manual Manual Information Abstract HP NonStop Server Guide for BEA WebLogic Server 9.2 This manual describes the installation, configuration, and management of the BEA WebLogic Server on HP Integrity NonStop NS-series servers. Product Version HP Integrity NonStop Server Toolkit for BEA WebLogic Server 9.2 Supported Release Version Updates (RVUs) This publication supports H06.10 and all subsequent H-series RVUs until otherwise indicated by its replacement publication. Part Number Document History New and Changed Information Changes in the HP Integrity NonStop Server Toolkit for BEA WebLogic Server Manual: Changed the product version of HP Integrity NonStop Server Toolkit for BEA WebLogic Server from 8.1 to 9.2 in all instances. Legal Notice Published January 2008 Part Number Product Version Published HP Integrity NonStop Server Toolkit for July 2005 BEA WebLogic Server HP Integrity NonStop Server Toolkit for BEA WebLogic Server 9.2 January 2008 WebLogic Server is a registered trademark of BEA Systems, Inc. v

10 What s New in This Manual Legal Notice vi

11 About This Manual This manual describes: The BEA WebLogic Server for the HP Integrity NonStop NS-series servers. Installation of the BEA WebLogic Server 9.2 on HP NonStop servers. Possible configurations. The XA Resource Manager. Avitek Medical Records (or MedRec) sample application suite that is run with WebLogic Server. Who Should Read This Manual This manual is intended for users who want to: install and set up the WebLogic Server. administer the WebLogic Server after installation. Note. This manual describes the NonStop server differences and additions that allow BEA WebLogic Server to work on the NonStop platform. You must be familiar with the BEA WebLogic Server 9.2 documentation, located at: vii

12 About This Manual Organization of This Manual Organization of This Manual Section Section 1, Introduction Section 2, Installation Section 3, Migration Section 4, Configuring Persistent WebLogic Server Processes Section 5, Configuring JTA Section 6, XA Resource Manager (XARM) Section 7, Configuring JDBC Stores for JMS Section 8, Managing SQL/MX Tables for BLOB and CLOB Data Section 9, Sample Application Appendix A, Script Options Usage Description Describes the WebLogic Server features and enhancements on the NonStop server platform. Provides the URL for the installation instructions. Discusses migration from WebLogic Server 8.1 SP3 on the MIPs platform (TNS/R) or WebLogic Server 8.1 SP3 Itanium Processor based platform (TNS/E) to WebLogic Server 9.2 on the Intel Itanium Processor based platform (TNS/E). Describes the generic process and its use with the WebLogic Server. Explains how to configure the Node Manager. Sample shell scripts and TACL macros are also described. Discusses configuration of JTA. Describes the WebLogic Server XA resource facilities and other configurations. Explains how the JMS Server can be configured to use a JMS JDBC store. Discusses management of BLOB and CLOB data. Discusses Avitek Medical Records (or MedRec), a sample reference application that demonstrates the BEA WebLogic Server features. Lists options for shell scripts that are used to check, install, and uninstall software. Related Documentation This manual should be used with: The BEA suite of documentation on the WebLogic Server located at SCF Reference Manual for the Kernel Subsystem (describes the generic process mechanism), located at docs.hp.com NonStop TCP/IPv6 documentation, located at docs.hp.com TMF product documentation, located at docs.hp.com viii

13 About This Manual Notation Conventions NonStop SQL/MX documentation, located at docs.hp.com itp WebServer documentation, located at docs.hp.com SQL/MX Comparison Guide for SQL/MP Users, located at docs.hp.com Java documentation, located at docs.hp.com Notation Conventions Hypertext Links Blue underline is used to indicate a hypertext link within text. By clicking a passage of text with a blue underline, you are taken to the location described. For example: See to Section 6, XA Resource Manager (XARM) for information about the XA resource manager. General Syntax Notation This list summarizes the notation conventions for syntax presentation in this manual. UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: MAXATTACH lowercase italic letters. Lowercase italic letters indicate variable items that you supply. Items not enclosed in brackets are required. For example: file-name computer type. Computer type letters within text indicate C and Open System Services (OSS) keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: myfile.c italic computer type. Italic computer type letters within text indicate C and Open System Services (OSS) variable items that you supply. Items not enclosed in brackets are required. For example: pathname [ ] Brackets. Brackets enclose optional syntax items. For example: TERM [\system-name.]$terminal-name INT[ERRUPTS] A group of items enclosed in brackets is a list from which you can choose one item or none. The items in the list can be arranged either vertically, with aligned brackets on ix

14 About This Manual Change Bar Notation each side of the list, or horizontally, enclosed in a pair of brackets and separated by vertical lines. For example: FC [ num ] [ -num ] [ text ] K [ X D ] address Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in brackets or braces. For example: INSPECT { OFF ON SAVEABEND } Item Spacing. Spaces shown between items are required unless one of the items is a punctuation symbol such as a parenthesis or a comma. For example: CALL STEPMOM ( process-id ) ; If there is no space between two items, spaces are not permitted. In this example, no spaces are permitted between the period and any other items: $process-name.#su-name Line Spacing. If the syntax of a command is too long to fit on a single line, each continuation line is indented three spaces and is separated from the preceding line by a blank line. This spacing distinguishes items in a continuation line from items in a vertical list of selections. For example: ALTER [ / OUT file-spec / ] LINE [, attribute-spec ] Change Bar Notation Change bars are used to indicate substantive differences between this edition of the manual and the preceding edition. Change bars are vertical rules placed in the right margin of changed portions of text, figures, tables, examples, and so on. Change bars highlight new or revised information. For example: The message types specified in the REPORT clause are different in the COBOL85 environment and the Common Run-Time Environment (CRE). The CRE has many new message types and some new message type codes for old message types. In the CRE, the message type SYSTEM includes all messages except LOGICAL-CLOSE and LOGICAL-OPEN. x

15 1 Introduction This section describes the WebLogic Server features and enhancements on the NonStop server platform: The WebLogic Server for the HP NonStop Server on page 1-1 Server-Specific Features on page 1-2 Enhancements on page 1-2 Native Socket Multiplexer on page 1-3 High Level Architecture on page 1-6 SMP Systems and HP NonStop Servers on page 1-7 The WebLogic Server for the HP NonStop Server The WebLogic Server is a standards-based J2EE application server that provides a foundation for building applications and includes features such as: Load balancing Fault tolerance Web services Network transparency Legacy integration Transaction management Security Multi-threading Persistence Database connectivity Resource pooling Development, testing, and packaging The WebLogic Server uses Java for portability to other operating systems supporting the Java platform. WebLogic Server 9.2 is certified by BEA for HP NonStop servers. On properly configured HP NonStop servers, the WebLogic Server runs unchanged similar to that on other platforms. 1-1

16 Introduction Server-Specific Features Server-Specific Features HP provides certain NonStop server-specific features to the WebLogic Server: An XA resource manager for the NonStop Transaction Management Facility (TMF) facility so that NonStop server resources can participate in global transactions coordinated by the WebLogic Server transaction managers. For more information, see Section 6, XA Resource Manager (XARM). A NonStop Server Toolkit for BEA WebLogic Server 9.2 containing: a Java XA resource object adapted specifically for the WebLogic Server so that NonStop server resources can participate in WebLogic Server global transactions. an XA wrapper for Java Database Connection (JDBC) drivers for the NonStop SQL/MX database so that the drivers can be used in the WebLogic Server components needing XA-compliant JDBC data sources. transaction helpers and dummy XA resource objects that will be used by the XA wrappers for the JDBC drivers. Avitek Medical Records (MedRec), a sample application suite that works with the WebLogic Server. See Section 9, Sample Application. Documentation supporting other software that form the NonStop Server Toolkit. Note. Applications using WebLogic Server must use SQL/MX to access NonStop SQL tables. Access to these tables is not supported for programs using NonStop SQL/MP (SQL/MP). For information about the differences between SQL/MX and SQL/MP, see SQL/MX Comparison Guide for SQL/MP Users. Enhancements WebLogic Server has been enhanced to include: UDP: WebLogic Server clusters use UDP multicast-based communications for cluster heartbeat monitoring and propagation of the Java Naming and Directory Interface (JNDI) tree to the members of a cluster. Transaction Manager: The WebLogic Server transaction manager coordinates global transactions with branches contracted to TMF through the Java XA resource object. Since the WebLogic Server accesses only TMF protected resources on the NonStop server, the WebLogic Server transaction manager must be efficient in logging and recovery activities. To this end, the TMF product has been enhanced to support one-phase commit optimization for imported branches. SQL/MX SPR 2.2: SQL/MX SPR 2.2 is HP s next generation relational database management system designed for business-critical applications. SQL/MX brings traditional NonStop fundamentals high availability, scalability, reliability, and parallel processing to a distributed database. 1-2

17 Introduction Native Socket Multiplexer WebLogic Server 9.2 is available for the NonStop Server and depends on Java Standard Edition Version 1.5.0_02. The NonStop Server for Java 1.5 has been updated to conform to this. For more information, see Java documentation. Native Socket Multiplexer The WebLogic Server allows two mechanisms for network socket I/O: a pure Java socket reader implementation, and a platform-optimized native socket multiplexer. However, benchmarks show major performance improvements when the Native Multiplexer is used. The details and the advantages of using the native implementation instead of the pure Java implementation is described next. Prior to Java 2 Standard Edition Platform 1.5.0, there was no facility within the Java Platform for a thread to initiate and poll asynchronous I/O operations (similar to the UNIX select (2) system call). To overcome this, the WebLogic Server has been enhanced to provide a pure Java socket multiplexer that simulates polling functionality. This polling is implemented by using multiple dedicated threads polling for each of the sockets for data (by specifying a timeout for the I/O operation). The polling socket readers are busy polling for data even when there is no data to read, thereby incurring unnecessary overhead. This performance issue is evident when there are more sockets than socket readers. Therefore, each of the socket readers has to poll multiple sockets. As a result, servicing of sockets is delayed because the socket data is not processed immediately and the reader is blocked on data from a socket that has no data. Figure 1-1 illustrates this scenario. There are three socket readers, SR1, SR2, and SR3. There are six open sockets (SP1 through SP6). Sockets SP1, SP3, and SP6 have data and the others do not. The socket readers are polling sockets SP2, SP3, and SP4. Socket reader SR2 immediately detects data on socket SP3 and processes it, whereas the other socket readers are blocked for a chosen polling timeout period before they move to poll other sockets. Sockets SP1 and SP6, though ready with data, are not serviced immediately, whereas the socket readers are polling sockets SP2 and SP4 without data. 1-3

18 Introduction Native Socket Multiplexer. Figure 1-1. Socket Reader Polling SR1 SR2 SR3 SP1SP2 SP3SP4SP5 SP6 VST003.vsd Another aspect of the Java socket multiplexer implementation that impacts the overall performance of the WebLogic Server application is the kernel execute queue. The kernel execute queue is configured with threads that perform server internal functions and application request processing. When the pure Java socket multiplexer is used, the number of socket readers is expressed as a percentage of the kernel default execute queue. As a result, the number of threads that can service other requests is reduced. To overcome this, a native socket multiplexer facility has been included in the WebLogic Server product. This native socket multiplexer eliminates the need to poll the sockets by providing a set of dedicated poller threads. These threads call the native code implemented in C and C++ to use the host operating system-specific facility to wait for I/O events on the sockets. As shown in Figure 1-2, a single thread N1, waits for I/O events on all the active sockets S1 through S6. When an I/O event is triggered in any of the sockets, the operating system notifies the thread about the event. The thread wakes up to service the I/O event on the socket. This greatly reduces the unnecessary overhead in polling the sockets and reduces the processor resource utilization by the WebLogic Server. 1-4

19 Introduction Native Socket Multiplexer. Figure 1-2. Single Thread Polling Native Socket Reader Thread N1 SP1 SP2 SP3 SP4 SP5 SP6 VST004.vsd Another advantage of the native socket implementation is the usage of the kernel execute queue. Unlike the pure Java multiplexer, the native socket polling threads are managed using a separate execute queue distinct from the default kernel queue. Therefore, the kernel execute queue threads are all used to handle application requests, which helps in better performance at reduced resource utilization. 1-5

20 Introduction High Level Architecture High Level Architecture The WebLogic Server provides standards-based access to NonStop server resources protected by TMF. The XA resource object facilitates transactional access of NonStop server resources within the scope of the WebLogic Server global transaction. The WebLogic Server uses the generic process support in the NonStop server to monitor and manage the Node Manager and the Administration Server (there is one Node Manager for each NonStop server node and one Administration Server for each WebLogic Server domain). Figure 1-3. WebLogic Server on NonStop Server Architecture Applications WebLogic Server - J2EE Services Process Management Communications Network Management Load Balancing and Failover WebLogic Transaction Manager XARM NonStop Server Resources SQL/MX Enscribe NonStop JMS others NonStop Server for Java TMF Transaction Management and DB Integration NonStop Kernel Generic process support for managing node manager and admin server. 1-6

21 Introduction SMP Systems and HP NonStop Servers SMP Systems and HP NonStop Servers A WebLogic Server domain deployment on a traditional SMP system is presented in Figure 1-4. The Administrative Server, Managed Servers (part of a cluster), Managed Servers (independent of clusters), and Node Manager run on a single SMP machine. The threads of all Java Virtual Machine (JVM) instances can be scheduled on all the available processors. Fault tolerance is not built into SMP systems. Loss of a processor can bring down the entire system along with all the instances running on the machine. Until the transaction logs and other critical components are recovered on a configured backup system, significant application outages might occur. Figure 1-4. WebLogic Server Domain Representation on a 4-Way SMP Machine Administrative Server Managed Server (part of a cluster) Managed Server (part of a cluster) Managed Server (part of a cluster) Managed Server (independent of cluster) Node Manager Managed Server (independent of cluster) Managed Server (part of a cluster) 4-way SMP Machine VST001.vsd The same domain (without any specific direction from the WebLogic Server domain administrator) can be deployed transparently. 1-7

22 Introduction SMP Systems and HP NonStop Servers Figure 1-5. WebLogic Server Domain Representation on a NonStop Server Administrative Server Managed Server (part of a cluster) Managed Server (part of a cluster) Managed Server (part of a cluster) CPU 0 CPU 1 CPU 2 CPU 3 Managed Server (independent of cluster) Node Manager Managed Server (independent of cluster) Managed Server (part of a cluster) VST002.vsd The WebLogic Server instances are coupled and distributed across all the available CPUs. A JVM and all its threads run within the CPU where the JVM was started. When a CPU is lost, only WebLogic Server instances running on that CPU are affected. The WebLogic Server instances on the failed CPU can be automatically restarted on other CPUs without reconfiguration and migration requirements. The WebLogic Server application on a NonStop server is always available because fault-tolerance is provided by every component (such as TCP/IP, TMF, and SQL/MX). Moreover, the Node Manager and Administration Server are monitored to restart automatically if the processor they run on fails (or the process itself fails). This method provides continued availability of monitoring and management services. The deployment benefits of the NonStop server, such as tight integration with the faulttolerant transaction manager, massively scalable relational database, and TCP/IP are transparently provided to the WebLogic Server application when deployed on a NonStop server. 1-8

23 2 Installation For information on how to install the BEA WebLogic Server 9.2 on HP NonStop servers, go to: 2-1

24 Installation 2-2

25 3 Migration There are no application changes required to migrate from WebLogic Server 8.1 SP3 on the MIPs platform (TNS/R) to WebLogic Server 9.2 on the Itanium based NonStop servers (TNS/E). For general migration information, see H-Series Application Migration Guide. 3-1

26 Migration 3-2

27 4 Configuring Persistent WebLogic Server Processes Overview of Generic Processes on page 4-2 Considerations on page 4-3 Configuration on page 4-3 Automatic Restart on page 4-3 Sample Scripts on page 4-3 Managed Servers on page 4-4 Generic Process Attributes on page 4-4 Sample Shell Scripts and TACL Macros on page 4-6 startgp.sh on page 4-6 startgp.tacl on page 4-6 Scripts to Start the WebLogic Server Process on page 4-6 stopgp.sh and stopgp.tacl on page 4-8 Using the Node Manager on the NonStop Server on page 4-8 Starting a Managed Server Through the Node Manager on page 4-9 nodemanager.sh on page 4-9 CPUselector on page 4-10 gname_load on page 4-11 jvm_load on page 4-11 managed_load on page 4-11 no_load on page 4-12 Configuring the Node Manager on page 4-12 Settings on page 4-12 Step 1. Create a Machine and Associate Servers to it on page 4-13 Step 2. Generate Node Manager Configuration Files on page 4-13 Step 3. Configure and Start the Node Manager on page 4-13 Step 4. Configure Managed Servers Startup Options on page

28 Configuring Persistent WebLogic Server Processes Overview of Generic Processes Step 5. Start Managed Servers Using the Node Manager on page 4-15 Step 6. Monitor Startup of the Managed Server on page 4-15 Troubleshooting and Notes on page 4-15 Starting the Node Manager from a Non-Default Location on page 4-16 Shutting Down a WebLogic Server Application on page 4-17 The WebLogic Server supports three process types: Administration Server Managed Server Node Manager In a typical production application on the HP NonStop server, it is assumed that all three process types are present on a single system. Specifically, there is an Administration Server controlling a set of Managed Servers. This is often configured as a cluster. There is also a Node Manager to start and stop the Managed Servers. To provide persistence on UNIX platforms, BEA recommends configuring the Administration Server and Node Manager as daemon processes. On the NonStop server, there are several mechanisms that support process persistence. The next section describes how to use generic processes to provide process persistence. Overview of Generic Processes For complete documentation about the generic process mechanism, see SCF Reference Manual for the Kernel Subsystem. Generic processes are configured using SCF, and are started and maintained by the $ZPM persistence manager. A generic process can be configured to: start in certain CPUs and restart if the process terminates. However, the process must be a Guardian process and cannot use Guardian ASSIGNs, PARAMs, or DEFINEs. The WebLogic Server processes are Open System Services (OSS) processes and typically require DEFINEs to be set to run with NonStop TCP/IPv6. Therefore, the generic process mechanism cannot be used to directly start and monitor the WebLogic Server application server process. Instead, a program called OSH starts as the generic process. The OSH process runs a shell script that starts and waits for the WebLogic Server process, which is configured as the second persistent process using the ASSOCPROC attribute. If the WebLogic Server process later fails, the shell script and OSH process also fail. $ZPM then restarts the generic process. 4-2

29 Configuring Persistent WebLogic Server Processes Considerations Considerations Configuration Only a member of the SUPER group can configure and start a generic process even though the process can run as any user ID. For security reasons, the WebLogic Server administrator user ID is not typically a member of the SUPER group. Therefore, the script used to configure the generic process must either be owned and run as a member of the SUPER group, or the script must be executed directly by a member of the SUPER group. Automatic Restart Generic processes automatically restart after the system is restarted. The WebLogic Server depends on OSS and NonStop TCP/IPv6. However, part of NonStop TCP/IPv6 does not use the generic process mechanism. Therefore, the generic processes used to support the WebLogic Server must be started after OSS and NonStop TCP/IPv6 have been successfully started. By default, the sample scripts configure the generic process STARTMODE as APPLICATION. If OSS and NonStop TCP/IPv6 are not started by the CIIN processing, set STARTMODE to MANUAL and run the script after NonStop TCP/IPv6 starts. Sample Scripts The sample scripts provided use OSH and shell scripts to start and wait for the WebLogic Server process. If the intervening OSH or shell processes are terminated and the WebLogic Server process is not, all processes will be restarted. One way to reduce the number of intervening shell processes between the OSH process and the WebLogic Server is to use exec. For example, the sample script runs exec./startweblogic.sh, instead of the shell script, started by OSH, running./startweblogic.sh, which starts a second shell process. Using exec causes the second shell process to reuse the existing shell s pid. To completely eliminate the intervening shell process requires exec to be used in all cases where a shell process is being started. In a typical installation, this requires changing scripts in the WebLogic Server home directory or using the files from a different location. By using exec exclusively when starting the intervening processes, it is possible to have the OSH process wait on the WebLogic Server. A drawback to using exec this way is that no shell post-processing can be done. For example, if a script cannot start the Java process, wait for it to terminate, and then perform cleanup processing. OSH is monitored by the generic process mechanism and any script invoked by the generic process must avoid the operations listed: The shell script must wait for the WebLogic Server process. If it does not, the script will terminate causing OSH to terminate and the generic process will restart. 4-3

30 Configuring Persistent WebLogic Server Processes Managed Servers The scripts should avoid calling sleep for any significant period of time unless you modify the AUTORESTART parameter of the generic process to reflect the delay. For example, if a script delays for a failed start attempt of the generic process that takes two minutes, the generic process will continually restart the generic process. By using an AUTORESTART of 10, only ten failures in 10 minutes will cause the generic process to move to the STOPPED state. By using a two-minute delay, the process will not fail ten times in 10 minutes. Managed Servers Instead of using the WebLogic Server Node Manager, you can use the generic process mechanism to monitor Managed Servers. Before using this approach, consider: CPU load balancing may be difficult to achieve than when you use the supplied nodemanager.sh. Each Managed Server must be configured to run in more than one CPU to be fault tolerant and to allow in-doubt transactions to be recovered after a server failure. To provide balance across CPUs, Managed Servers have to be assigned to a subset of CPUs. Therefore, use the FIRSTOF attribute with a list of CPU numbers. The following Node Manager features are not available: The WebLogic Server Administration Server is not able to use the WebLogic Server Node Manager to start Managed Servers. Automatic monitoring the health of Managed Servers and restarting server instances that have reached the failed health state. Shutting down or forcing the shut down of a Managed Server that failed to respond to a shut down request. The generic process mechanism should be faster at restarting Managed Servers that have terminated or failed due to a processor failure. However, this speed requires monitoring and configuring outside the WebLogic Server environment. Generic Process Attributes Table 4-1 contains a brief consideration for each useful attribute. These considerations assume that you are using OSH to start and monitor a WebLogic Server. See the sample scripts later in this section to learn how to set these attributes. 4-4

31 Configuring Persistent WebLogic Server Processes Generic Process Attributes Table 4-1. Generic Process Attributes Table Attribute AUTORESTART CPU NAME PRIORITY PROGRAM STARTMODE STARTUPMSG STOPMODE TYPE USERID ASSOCPROC Consideration A setting of 0 means the process will not be persistent. The sample scripts set the value to 10 to allow up to ten failures in 10 minutes. Reducing this value might help avoid hitting an infinite restart loop. Use FIRSTOF to allow the process to run in a list of available CPUs. Use only FIRST if you want the process to run normally in the CPU 0. Choose an available process name. Unless the script that starts the WebLogic Server process specifies a Guardian priority, set this attribute to ensure that the WebLogic Server process runs at an appropriate priority for your system. An inappropriate setting can significantly affect system performance and user response times. The scripts use $SYSTEM.SYSTEM.OSH so that OSH will be found in the current SYSnn. The WebLogic Server process depends on NonStop TCP/IPv6, therefore only APPLICATION or MANUAL should be used. If NonStop TCP/IPv6 is not started during the CIIN processing, use MANUAL and ensure that the script used to configure and start the WebLogic Server process is run after the system is reloaded. Conversely, if the WebLogic Server process should not be automatically started after a system restart, change the script to use MANUAL to avoid the WebLogic Server process started during system startup. This attribute is limited to 128 characters. The sample scripts use -c script <->>stdout 2>>stderr. In this example, -c tells OSH to run script, <- causes OSH to ignore stdin, >> directs output to stdout, and >>2 directs output to stderr. Using OSH, only STANDARD causes the OSH process to stop during an SCF ABORT PROCESS command. Using SPI or SYSMSG with OSH will cause the ABORT command to succeed, but the process will not stop. You need to manually stop the process. Use OTHER. Set this attribute unless the WebLogic Server process runs as a member of the SUPER group. This might have ramifications with the shell scripts if your environment expects values to be set from the profile of this user ID. Set ASSOCPROC to the Guardian name of the OSS process. Other generic process attributes can be ignored. HOMETERM and OUTFILE should typically be set to $ZHOME. 4-5

32 Configuring Persistent WebLogic Server Processes Sample Shell Scripts and TACL Macros Sample Shell Scripts and TACL Macros Configuring a generic process requires using SCF, the Guardian command interpreter. Commands must be run by a member of the SUPER group. Four sample files are provided for the NonStop server. These sample files are: startgp.sh, startgp.tacl, stopgp.sh, and stopgp.tacl. Two of the scripts are Korn shell scripts and the other two are TACL macros. Therefore, you can choose which command interpreter you prefer to use. Both startgp files must be copied and modified to start either the Administration Server or the Node Manager. The stopgp files take the name of the generic process to be stopped and should not require modification. startgp.sh startgp.sh is a shell script. A member of the SUPER group can copy startgp.sh, update it, and perform chmod command (for example, chmod u+s startgp.sh) so that anyone running the script will be considered as a member of the SUPER group. You can also log on as a SUPER user before running the script. Update the script as outlined in the script instructions (found in the script). You need to ensure that the script uses a unique generic process logical name and a process name. Also ensure that the script starts the correct shell script. Otherwise, the script starts SCF and will attempt to delete, add, and then start the generic process. startgp.tacl startgp.tacl is a TACL macro that must be copied to the Guardian namespace and converted to an EDIT file using CTOEDIT. As with startgp.sh, the macro needs to be updated to reflect the process to be started and must be run by a member of the SUPER group. Scripts to Start the WebLogic Server Process Regardless of the method used to add and start the generic process, a sample script is needed to start the WebLogic Server process. To avoid the character limit of 115 on STARTUPMSG, place the following scripts in a directory near the root directory. The Administration Server script and the Node Manager script use the standard scripts created by the WebLogic Server. These scripts can be expanded as appropriate. Administration Server Script Place the following text into a file, turn the execute bit on, and use its name as the script name used when adding the generic process: #!/bin/sh PATH=/usr/bin:/bin:/usr/local/bin: cd <application directory>../setenv.sh 4-6

33 Configuring Persistent WebLogic Server Processes Scripts to Start the WebLogic Server Process run -name=/g/adsvr ${JAVA_HOME}/bin/java ${JAVA_VM} ${MEM_ARGS} ${JAVA_OPTIONS} -Dweblogic.Name=${ADMIN_SERVER} -Dweblogic.ProductionModeEnabled=${PRODUCTION_MODE} -Djava.security.policy="${WL_HOME}/server/lib/weblogic.policy" -Dweblogic.management.username=${WLS_USER} -Dweblogic.management.password=${WLS_PW} weblogic.server Node Manager Script Place the following text into a file, turn the execute bit on, and use its name as the script name used when adding the generic process: #!/bin/sh PATH=/usr/bin:/bin:/usr/local/bin: cd application directory../setenv.sh run -name=/g/nmgr "${JAVA_HOME}/bin/java" ${JAVA_VM} ${MEM_ARGS} ${JAVA_OPTIONS} - Djava.security.policy="${WL_HOME}/server/lib/weblogic.policy" -Dweblogic.nodemanager.javaHome="${JAVA_HOME}" weblogic.nodemanager 4-7

34 Configuring Persistent WebLogic Server Processes stopgp.sh and stopgp.tacl stopgp.sh and stopgp.tacl The script and macro have one required argument, the generic process name, and an optional delete argument if the generic process entry should be deleted. The script and macro attempt to run an ABORT PROCESS command to cause the generic process to stop. Because the process being stopped is the OSH process, running the ABORT PROCESS command does not cause the WebLogic Server process to stop. Instead, the scripts prompt a message reminding you that the WebLogic Server process also needs to be stopped. If you do not delete the entry, and the system is reloaded, the process will automatically restart if STARTMODE is APPLICATION. Terminating the process only stops the current process while the system is still running. The entry will persist in the system configuration unless you use the delete option. Using the Node Manager on the NonStop Server The Node Manager can be used to start and stop Managed Servers. Its use on the NonStop server is the same as on other platforms. However, due to the NonStop server multi-cpu architecture, the Node Manager is appropriate even when the cluster consists of only one NonStop server. To configure and use the Node Manager, see: Configuring the Node Manager Overview of Node Manager Configuring, Starting, and Stopping Node Manager sections in Configuring and Managing WebLogic Server. The primary consideration when using the Node Manager on the NonStop server is that the native process control is not supported. This means the Node Manager property NativeVersionEnabled must be set to false in either the nodemanager.properties file, or in the shell script (named startnodemanager.sh by default) used to start the Node Manager. Also, the default value for ListenAddress (that is, localhost) will normally need to be changed to be that of the NonStop server TCP/IP process. To optimally use the Node Manager, you might need to change other WebLogic Server properties. For example, the Node Manager only restarts servers if AutoRestart is true (the default value). However, if the same event that causes the Node Manager to fail causes a Managed Server to fail, the server will not be restarted unless HostsMigratableServices is false (the default value is true). For single node domains, it is recommended that HostsMigratableServices be set to false. This property is not externalized on the console; instead the Server element of each Managed Server needs to be updated in the config.xml file directly. If HostsMigratableServices is not set to false, the Node Manager may report the 4-8

35 Configuring Persistent WebLogic Server Processes Starting a Managed Server Through the Node Manager status of a Managed Server as FAILED_MIGRATABLE. In this case, restart the server using the console or weblogic.admin utility. Starting a Managed Server Through the Node Manager When NativeVersionEnabled is set to false as required on the NonStop server, the Node Manager uses a shell script to start a Managed Server. By default that script is named nodemanager.sh but can be changed using the StartTemplate property. The Node Manager passes four arguments to the script: Java command-line stdout to use stderr to use Filename where the pid of the Java process should be written Therefore, the nodemanager.sh could be as simple as: #!/bin/sh. $WL_HOME/common/bin/commEnv.sh java $1 > $2 2>$3 & echo $! > $4 To take advantage of the NonStop server multi-cpu architecture, a sample script and executable are provided that will balance the Managed Servers throughout the system. The nodemanager.sh script is stored in $WL_HOME/server/lib/unix. The script performs some simple processing and then runs a C program, CPUselector, in the same directory to select which CPU should be used by the Managed Server. The script then starts the Managed Server. nodemanager.sh The nodemanager.sh script reads in a server environment file to allow environment variables to be set per server. It invokes the C program named CPUselector to perform the load-balancing functionality. Once CPUselector completes, the script starts the Managed Server in the appropriate CPU. The WebLogic Server uses replication groups to support fault-tolerance by allowing a primary and secondary server to retain state information. To avoid a single point of failure, do not start the primary and secondary server in the same CPU on a NonStop server. nodemanager.sh and CPUselector allow you to ensure that the primary and secondary server do not start on the same CPU. To support replication groups, CPUs are specified for use using a new environment variable named WLS_CPUS. Further, the order in which the CPUs are listed in WLS_CPUS determines the order in which the CPUs are scanned when the load for each CPU is compared. nodemanager.sh scans the script arguments to determine the server name to set the environment variable WLS_SERVER. It then looks for the server environment file in the 4-9

36 Configuring Persistent WebLogic Server Processes CPUselector current working directory. By default, the server environment file is named nmserver.env and must be located in $WL_HOME/common/nodemanager but both values can be changed in the nodemanager.sh script. If the file is present, the script invokes the file (for example,.nm-server.env). The script can then use the variable WLS_SERVER to selectively set the environment variables to be used by CPUselector. Example 4-1. Server Environment File case $WLS_SERVER in ms1) WLS_CPUS="2 3" WLS_LOADBAL_FUNC="no_load" ;; ms2) WLS_CPUS="4 5" WLS_LOADBAL_FUNC="no_load" ;; *) WLS_CPUS=" " WLS_LOADBAL_FUNC="jvm_load" ;; esac # Common DEFINEs and variables can go here or in commenv.sh The server environment file should set the appropriate environment variables and DEFINEs based on the server name passed. The variables and their functions are described later in this section. CPUselector uses the environment variables to determine the load-balancing algorithm, the CPUs to use, and the order for each server. Using these variables, you can avoid configuring replication groups in a way that the primary and secondary server will never be placed in the same CPU. The caveat being that a 2-CPU system will necessitate both servers being placed in the same CPU after a CPU failure; otherwise one of the servers will not restart. CPUselector The task of CPUselector is to determine the CPU to be used when starting the Managed Server. The program first determines the available CPUs. It then calculates the current load and selects the CPU with the minimum load. The two significant environment variables used by CPUselector are WLS_CPUS and WLS_LOADBAL_FUNC. WLS_CPUS is a space-separated list of valid CPU numbers and has a maximum value of 16. WLS_CPUS determines the available CPUs for selection by the server and the order in which the computed loads are compared. That is, WLS_CPUS="3 2 0" will cause the load for CPU 3 to be examined first, then CPU 2, and finally CPU 0. If two CPUs have the same (minimum) load, the first CPU examined will be used. If no CPU contained in WLS_CPUS is currently up, no CPU will be selected. 4-10

37 Configuring Persistent WebLogic Server Processes gname_load The variable WLS_LOADBAL_FUNC determines the load-balancing algorithm used to compute the loads. The next section describes how each load-balancing function computes the current load. The sections also identify the files and environment variables that are used. gname_load gname_load uses Guardian process names to calculate the current load. The process names are specified using the environment variable WLS_GNAMES, which is a spaceseparated list of Guardian process names without the leading dollar sign (WLS_GNAMES="ms1 ms2 ms3 ms4"). gname_load then determines the CPU where the process is being executed and calculates the aggregate load per CPU. To allow Managed Servers to be started with a Guardian process name, the WLS_GNAME variable is used. You must consider two things when using gname_load. One, the process names listed in WLS_GNAMES can be any valid Guardian process name; there is no requirement that the process names only reference WebLogic Server processes. Two, WLS_GNAMES is used to determine the processes that are running; WLS_GNAME (without the "S") assigns a process name to the Managed Server being started. jvm_load Using CPUselector has changed this existing function. A new variable, WLS_JVM_PATHNAMES, determines which executables should be queried when computing the load. WLS_JVM_PATHNAMES is a colon-separated list of OSS executables. For example, WLS_JVM_PATHNAMES/usr/tandem/nssjava/jdk150_h50/bin/java" causes every process using that executable to be included in the load. Likewise, WLS_JVM_PATHNAMES="/usr/bin/java:/bin/ksh" causes both executables to be included in the aggregate load. The above example implies that any valid OSS executable name can be included in WLS_JVM_PATHNAMES. However, avoid including the same executable more than once. This can happen if a hard link or symbolic link is included because the algorithm first converts the OSS pathname to the corresponding Guardian filename, and then does a status for processes using that program filename. If the WLS_JVM_PATHNAMES includes the same Guardian filename twice because the OSS file is a link, the load will be added twice. For example, if /usr/bin/jre/java is a symbolic link to /usr/bin/java, then setting WLS_JVM_PATHNAMES to "/usr/bin/java:/usr/bin/jre/java" causes the same processes to be included in the total twice. managed_load managed_load computes the current load by using files maintained by the Node Manager. Each time a Managed Server starts, its pid is written to a file. This function reads each pid and determines which CPU is being executed by the process. The list 4-11

38 Configuring Persistent WebLogic Server Processes no_load of processes being monitored is maintained in: "./NodeManagerLogs/NodeManagerInternal/MonitorProcessList" by default. The pid files are located in directories under "./NodeManagerLogs" with names of the form domain_server. The addition of WLS_CPUS helps the managed_load algorithm because different Managed Servers can specify a different CPU ordering. This feature helps in a multistart case because no servers will have started. Therefore, all CPUs will have the same load (that is, 0). If a different CPU is listed first for each Managed Server, the servers will still start in different CPUs. However, managed_load still relies heavily on the pid files remaining current. If Managed Servers are started or restarted frequently, it is likely that stale data in the pid files will increase. no_load no_load does not use a load-balancing algorithm. Instead, every CPU listed in WLS_CPUS that is currently up receives a load of 1. Thus, when the CPUs are scanned in WLS_CPUS-order, the first CPU that is currently up is used. The remaining CPUs in the list are examined when all the earlier CPUs in the list are down. In effect, the first CPU in WLS_CPUS is the primary CPU for the Managed Server, the second CPU is the backup, and so on. Using no_load provides control in assigning Managed Servers to specific CPUs. Therefore, when working with replication groups, using no_load allows you to avoid starting the primary and secondary server in the same CPU. However, in a 2-CPU system, the backup CPU for a Managed Server needs to be the primary CPU of another Managed Server. Using no_load, you can avoid any issue with the multi-start case because every server will start in its assigned CPU regardless of where the other servers are started. Configuring the Node Manager This section provides instructions on how to configure the Node Manager, including settings specific to the NonStop server platform. For further information, see the Overview of Node Manager and Configuring, Starting, and Stopping Node Manager sections in the BEA document titled Configuring and Managing WebLogic Server and the Troubleshooting and Notes section. Settings The instructions detailed in this section use and assume these settings: The server host where admin, Node Manager, and managed servers are running is called: icebat4.txn.cpqcorp.net A domain with servers in it already exists and is called rldomain. There are two managed servers called rlserver1 and rlserver

39 Configuring Persistent WebLogic Server Processes Step 1. Create a Machine and Associate Servers to it Step 1. Create a Machine and Associate Servers to it 1. Start an admin server for your domain:../my_env (loading your usual WL_HOME, JAVA_HOME, and so on) cd $WL_HOME/../user_projects/domains/rldomain./startWebLogic.sh Access the GUI. For example: 2. On the left pane: a. Click Machine folder. b. Click Configure a New unix Machine. c. Enter the machine name. d. Click Create. 3. Select the Node Manager tab and update the: Listen Address: icebat4.txn.cpqcorp.net Listen Port: Click Servers tab and select the servers you want Node Manager to control. Step 2. Generate Node Manager Configuration Files 1. Generate Node Manager configuration files by running a first startup of the Node Manager. The two required configuration files, nodemanager.hosts and nodemanager.properties, are created in $WL_HOME/common/nodemanager at the first start of the Node Manager. 2. Run startnodemanager.sh to create the two configuration files: $WL_HOME/server/bin/startNodeManager.sh On the NonStop server platform, the Node Manager will fail to start, giving the error: Node manager could not find the required library, libnodemanager.a, in path - > This error is expected because the use of the native version of the NodeManager must be disabled (see Step 3. Configure and Start the Node Manager). The default configuration files are now available to do so. Step 3. Configure and Start the Node Manager 1. On the NonStop server: cd $WL_HOME/common/nodemanager 4-13

40 Configuring Persistent WebLogic Server Processes Step 4. Configure Managed Servers Startup Options 2. Edit nodemanager.properties to add: NativeVersionEnabled=false ReverseDnsEnabled=true PIDFileReadRetryCount=1 ScavangerDelaySeconds= Edit nodemanager.hosts to add the server where the admin resides: icebat4.txn.cpqcorp.net 4. Start the Node Manager: $WL_HOME/server/bin/startNodeManager.sh 5. In the output, check that new values for the properties are set. Step 4. Configure Managed Servers Startup Options The Node Manager will now start each managed server. You must configure the following for the managed servers because neither the servers usual startup scripts (startmanagedweblogic.sh) nor shell env are used: 1. $WL_HOME/server/lib/unix/nodemanager.sh starts each managed server using NonStop platform-specific variables from nm-server.env: Create $WL_HOME/common/nodemanager/nm-server.env with the minimum contents shown below (TCP/IP stack identification is mandatory. For more information, see CPUselector): export TCPIP_PROCESS_NAME=\$ZSAMA export PTCPIP_FILTER_KEY=rlkey case $WLS_SERVER in rlserver1) WLS_CPUS= 0 ;; rlserver2 WLS_CPUS= 1 ;; esac 2. Configure startup options for each managed server. The environment values for each managed server are mirrored from the Node Manager. For options that must be configured at the managed server level: a. In the Admin console GUI, select a managed server (for example, rlserver1). b. Click Remote Start tab and configure at least: Root Directory: /home/roland/wls/bea/user_projects/domains/rldomain User Name: weblogic Password: ******** 4-14

41 Configuring Persistent WebLogic Server Processes Step 5. Start Managed Servers Using the Node Manager Step 5. Start Managed Servers Using the Node Manager 1. From the Admin console GUI: a. Select a server and click Control tab. b. Click Start this server. 2. From the command line enter:.$wl_home/server/bin/setwlsenv.sh java weblogic.admin -url icebat4:7001 -username webogic -password weblogic START rlserver1 Step 6. Monitor Startup of the Managed Server If the server does not start, check the following logs: (NODEMGR_HOME = $WL_HOME/common/nodemanager) For Node Manager process events: $NODEMGR_HOME/NodeManagerLogs/NodeManagerInternal/ directory For managed server startup events: $NODEMGR_HOME/NodeManagerLogs/domain_server name/ directory Troubleshooting and Notes If one specific server fails to start, test if the server starts in stand-alone: cd into the domain directory and start the managed server with:./startmanagedweblogic.sh rlserver2 PIDFileReadRetryCount defaults to 0 although it is documented in nodemanager.properties to default to 1. Leaving PIDFileReadRetryCount unchanged may cause unexpected behavior because the server might start but its status may not be reported in the Admin console. You should set PIDFileReadRetryCount to at least 1 to avoid error messages that may not be relevant. A value higher than 1 may be needed on slower or busier systems. ScavangerDelaySeconds defaults to 180, which is too low for the NonStop server. 300 seconds is more appropriate. If you do not change the default, the admin console may report failure even though the server started. weblogic.security.ssl.ignorehostnameverification property. Depending on how you used IP addresses and DNS names in the configuration of your servers, this property might need to be set to "true" for the SSL connections to establish between the admin and Node Manager and each servers. The BEA knowledge base states that setting this property to true is needed when using the 4-15

42 Configuring Persistent WebLogic Server Processes Starting the Node Manager from a Non-Default Location demo certificates, However, in this sample we have used successfully both true and false settings: rlserver 1: GUI, configuration, Keystore & SSL, Advanced option: "Hostname Verification = BEA Hostname Verifier" This means weblogic.security.ssl.ignorehostnameverification = false. rlserver 2: GUI, configuration, Keystore & SSL, Advanced option: "Hostname Verification = none" This means weblogic.security.ssl.ignorehostnameverification = true. Additional SSL debugging can be turned on by using the following properties: -Dweblogic.StdoutDebugEnabled=true -Dssl.debug=true Also a debug file can be specified within $WL_HOME/server/lib/unix/nodemanager.sh It is assumed that the default SSL demo Keystore and certificates shipped with WebLogic Server 9.2 are used. When the servers are created, they point to the demo SSL configuration by default (see Keystores and SSL configuration tab). This default allows an administrator to set up the Node Manager without initial SSL administration knowledge. Starting the Node Manager from a Non-Default Location The Node Manager can be used to control Managed Servers for several domains. However, there may be situations where you want to run multiple Node Managers on the same system, or run the Node Manager from a non-default location. To do either task may require several changes. By default, the script used to start the Node Manager sets NODEMGR_HOME to $WL_HOME/common/nodemanager, and then uses that value as its current working directory. This directory must contain nm-server.env, the server environment file that is used by nodemanager.sh. This directory also contains subdirectories that are used if CPUselector is instructed to use the managed_load load-balancing algorithm. To use a different directory, change the startnodemanager.sh script to set NODEMGR_HOME to a different value. Further, update the script to export the NODEMGR_HOME variable (that is, export NODEMGR_HOME) so that the nodemanager.sh script will use the new value. You could also update nodemanager.sh to use the same value for NODEMGR_HOME instead of exporting the variable. To change the location of nodemanager.sh or CPUselector, the Node Manager property named StartTemplate must be changed. By default, the value 4-16

43 Configuring Persistent WebLogic Server Processes Shutting Down a WebLogic Server Application./nodemanger.sh is used, which translates to $WL_HOME/server/lib/unix/nodemanager.sh. The nodemanager.sh script assumes CPUselector is in $WL_HOME/server/lib/unix as well by setting the variable DFLT_CPUSELECTOR to $WL_HOME/server/lib/unix/CPUselector. Change either the StartTemplate and/or nodemanager.sh as appropriate. For example, changing only StartTemplate changes the location where the nodemanager.sh is located, but CPUselector is still used from the default location. Changing DFLT_CPUSELECTOR in the nodemanager.sh script that will be invoked allows CPUselector to be located in a non-default location (for example, if the program has been modified and recompiled). To summarize, changing the value for NODEMGR_HOME in the start script allows multiple Node Managers to be run without conflict. If NODEMGR_HOME is changed, the variable must be exported for the nodemanager.sh script to use the updated location. If each Node Manager then wishes to use a unique nodemanager.sh and/or CPUselector, the StartTemplate property needs to be used to redirect the Node Manager to the non-default location. The nodemanager.sh can then point at a different CPUselector, if desired. Shutting Down a WebLogic Server Application If the generic process mechanism is used to monitor the Administration Server and Node Manager, the generic process must be stopped before the WebLogic Server process is stopped. A sample shell script, stopgp.sh, and TACL macro, stopgp.tacl, are provided. They can be used to abort, and optionally delete, the generic process. Running stopgp.tacl stops the OSH process and prevents $ZPM from restarting the generic process. Once the generic process is stopped, the usual WebLogic Server method of stopping the process can be employed. 4-17

44 Configuring Persistent WebLogic Server Processes Shutting Down a WebLogic Server Application 4-18

45 5 Configuring JTA Java Transaction API (JTA) elements of the configuration describe several attributes for controlling the WebLogic Server Transaction Manager. The JTA attributes can be changed if the TMF configuration is different for your application. This is an example highlighting some NonStop server-specific changes. <JTA AbandonTimeoutSeconds= 7200 MaxTransactions= 1000 CheckpointIntervalSeconds= 60 ForgetHeuristics= true Name= examples /> Listed below are explanations of the JTA attributes specified in the example above: AbandonTimeoutSeconds Number of seconds after which a transaction is abandoned if not complete. TMF defaults the autoabort timeout to 7200 seconds, making it sensible to restrict the WebLogic Server AbandonTimeout to be the same as TMF. MaxTransactions Controls the maximum number of transactions that can execute concurrently. When a static TMF resource manager is configured, the maximum number of transactions that can be started is restricted by the TFILE depth. The TFILE depth is Since the WebLogic Server can create transaction table entries on startup to recover indoubt transactions, this parameter should be set to a higher value than the maximum number of concurrent TMF transactions. The default value is and can be left unchanged without negative performance impact. CheckpointIntervalSeconds The default value is 300 seconds (5 minutes). The transaction manager creates new TLOG files and checks old TLOG files for deletion at this interval. This attribute has the side effect of determining the interval at which a registered XA resource is polled for in-doubt transactions. The correct behavior for a transaction manager is to call the recover on a resource manager immediately after it registers so that the resource manager can remove locks and be available for general transaction processing. 5-1

46 Configuring JTA 5-2

47 6 XA Resource Manager (XARM) The XA Resource Manager (XARM) for the HP NonStop server is a software component specifically written for and tested with the BEA WebLogic Server. It is written in C and Java and implements the Java XA resource interface as defined in the Java Transaction API (JTA) specification. The sections listed below describe the configuring options available: Configuring the WebLogic Server XA Resource Object Configuring the XA Resource Manager Error Output Destination Configuring the WLSNonStopTxHelper as a Startup Class Configuring JDBC Connection Pools for SQL/MX Configuring the WebLogic Server Data Sources for SQL/MX Additional Considerations for JDBC Access to SQL/MX Databases Normally, the WebLogic Server Transaction Manager enlists an XA resource in a transaction only when the associated resource manager is accessed within a WebLogic Server transaction. A special construct is needed so that a Transaction Management Facility (TMF) transaction is associated with the thread along with the WebLogic Server transaction. Whenever a WebLogic Server transaction associated with a thread changes, the TMF transaction association should change. This requirement is achieved by registering a static resource manager object with the WebLogic Server. A static resource object is a special construct in the WebLogic Server. A statically registered XA resource manager is enlisted in every transaction started by the WebLogic Server. When the XARM is registered as a static resource manager with the WebLogic Server, it interacts with the WebLogic Server to import transaction branches into TMF when instructed by the WebLogic Server and takes part in the commitment of the branch under the direction of the WebLogic Server transaction manager. As part of each WebLogic Server startup instance, the NonStop server XA resource must be registered as a static resource with that instance. Whenever a WebLogic Server transaction is started (either implicitly or explicitly), a branch of the transaction is contracted to TMF by the WebLogic Server transaction manager through the NonStop XA resource. The imported branch protects all NonStop server resources accessed within the scope of the WebLogic Server transaction. The static resource manager protects the NonStop server resources when it is accessed within the scope of a WebLogic Server transaction. However, the WebLogic Server transaction manager treats a resource as a transactional resource only if it supports the XA resource (even if the XA resource does not really perform transaction management). For example, for a SQL/MX connection pool to take part in a transaction involving other XA resources, the JDBC (Java Database Connectivity) driver for SQL/MX must have an XADataSource driver. However, JDBC/MX does not support XADataSource and 6-1

48 XA Resource Manager (XARM) Configuring the WebLogic Server XA Resource Object XAConnection interfaces. Because of this, a JDBC/MX wrapper driver has been provided to support the XADataSource and XAConnection interfaces. The associated XA resource is a dummy resource because it ignores all the XA requests from the WebLogic Server transaction manager. This satisfies the WebLogic Server requirement that JDBC/MX be XA-aware. Configuring the WebLogic Server XA Resource Object To configure the NonStop server XA resource object into a WebLogic Server, you must define a startup class. A startup class is a special class that implements the T3StartupDef interface. This startup class is loaded by the WebLogic Server as part of the WebLogic Server startup. For the NonStop server, the startup class WLSNonStopTxHelper must be configured for every server in the domain. This class, when instantiated, constructs the Java XA resource object for TMF and registers that resource as a static resource manager with the WebLogic Server. The object is also published in the JNDI as a non-replicated custom object so that the WebLogic Server does not attempt to replicate it to other servers in the cluster. The WLSNonStopTxHelper, when creating the Java XA resource, passes configuration information to the Java object so that the communication between the XA resource object and TMF can be realized. You can provide these parameters to the startup class in a property file or as Java system properties. If specified, the Java system property for a parameter takes precedence. To specify the property file explicitly for an instance, set the Java system property hp.nsk.xares.properties to refer to the properties file. Use absolute paths to specify the file so that the file can be opened and processed regardless of the current directory of the WebLogic Server instance on startup. The property file can be implicitly specified by naming it servername.xaproperties, where servername is the name of the WebLogic Server instance to which the property file applies. This file must be placed in the current directory (typically the domain directory) or under the server root directory. Note that the server root directory defaults to "." but you can change the root directory by using the ServerStart element in the configuration file. However, this change is useful only when the Node Manager is used. You should explicitly specify the Property file so that no confusion occurs between the current directory and root directory checks. When configuring servers that are to be started using the Node Manager, for each configured server, set the arguments of the ServerStart element to specify this property. 6-2

49 XA Resource Manager (XARM) Configuring the XA Resource Manager Error Output Destination Configuring the XA Resource Manager Error Output Destination You can control the destination of the XA resource manager error output by configuring the following environment variables: Name XARM_SYSLOG XARM_LOG_FILE Description Set to Y to log the XA resource manager error output to the Event Management Service (EMS). Set to N to disable logging the error output to EMS. The default setting is Y. The name of the log file for error and debug output. If not specified, the trace file name is xalog-year-monthstring-date-hour-minute-secs.txt For example, xalog-2003-apr txt. Configuring the WLSNonStopTxHelper as a Startup Class You can use the WebLogic Server console to configure startup classes. Below is an XML fragment showing the StartupClass element that is used to configure the startup class for the WLSNonStopTxHelper. All the XA resource object files reside in the package com.hp.nsk.xares. <StartupClass ClassName= com.hp.nsk.xares.wlsnonstoptxhelper DeploymentOrder= 1 FailureIsFatal= true LoadBeforeAppActivation= true LoadBeforeAppDeployments="false" Name= NSKXAResource Targets= VCluster /> ClassName Describes the Java class implementing the T3Startup interface. LoadBeforeAppActivation Determines if the startup class should be loaded after the connection pools are created but before the applications are activated. Activation is the second phase in the 2-phase deployment model. LoadBeforeAppActivation should be used when the startup class needs to be invoked after the connections pools are available but before the applications are activated and ready to service client requests. 6-3

50 XA Resource Manager (XARM) Configuring the WLSNonStopTxHelper as a Startup Class LoadBeforeAppDeployments Name Determines whether a startup class is loaded and run before the server creates JMS and JDBC services or deploys applications and EJBs. If you specify true for this option, the server loads and runs the class before the prepare() phase in the 2- phase deployment model. At this point, JMS and JDBC services are not yet available, and no applications or EJBs have been deployed. If you specify false, the server loads the class after all other types of modules have been deployed. Used by the WebLogic Server Mbeans for configuration purposes. The Startup class has no arguments. The arguments for specifying various options are specified in the startup script as Java system properties or by using a properties file. Table 6-1. Java System Properties used by WLSNonStopTxHelper Property Name used in Property File Name when Specified with the -D Java Command Line Option Description name hp.nsk.xares.name Specifies the name of the TMF recoverable resource manager the XA resource manager uses.this name must be unique in a NonStop server node. It should be independent of the recoverable resource manager names used by other WebLogic Server instances regardless of their domain, HP NonStop Tuxedo Domain gateway resource manager, as well as those used by HP NonStop CORBA. A valid value is a name that is a valid TMF recoverable resource name. The default value is WLSdomainName-WLSservername. flags hp.nsk.xares.flags Valid values are 0-7. These values are represented by three bits. Bit 0, if set, enables statistics. Bit 1 enables auditing, and Bit 2 enables asynchronous import of transactions. The default value is 0. maxtrans hp.nsk.xares.maxtrans Specifies the maximum number of concurrent TMF transactions that will be handled by the XA resource manager, for the entire process. It is limited by the TMF TFILE depth. The maximum TFILE depth is Valid values are 100 and higher. For a value greater than 100 to take effect, you must also set the value into the environment variable. Default value is

51 XA Resource Manager (XARM) Configuring JDBC Connection Pools for SQL/MX Table 6-1. Java System Properties used by WLSNonStopTxHelper (continued) Property Name used in Property File Name when Specified with the -D Java Command Line Option Description maxthreads hp.nsk.xares.maxthreads Specifies the maximum number of threads that can concurrently take part in a transaction. Typically, set to the maximum number of transactions configured so that the case where each thread operates on only one transaction is allowed for. Valid values are 100 and higher. Default value is enabletrace hp.nsk.xares.enabletrace Enables or disables tracing of the XA operations by the XA resource manager. Valid values are true and false. Default value is false. tracefile hp.nsk.xares.tracefile Specifies that the file cannot be opened and trace output is redirected to System.err destination. Valid value is null or a valid path to a file. Default value is null. If set to null, tracing is disabled. auditfile hp.nsk.xares.auditfile If auditing is enabled in the flags, this file is used as the audit file. If the filename is null or invalid and auditing is enabled in the flags, an audit file with the name xaaudit-date+time.txt is created for audit messages. Configuring JDBC Connection Pools for SQL/MX The JDBC/MX driver does not support the optional XA support specified in the JDBC specification because there is no need for the XA interfaces in the NonStop platform. However, the WebLogic Server and other J2EE containers depend on data sources to provide the XA resource for coordinating the participation of these resources in global transactions. The WebLogic Server can optionally provide an XA emulation driver for a non-xa resource. However, only one resource with WebLogic Servers-provided XA emulation can participate in a distributed transaction. Further, using the WebLogic serverprovided XA resource can result in more heuristic completions. To participate in a distributed transaction without depending on the WebLogic Server-provided XA emulation, the resource manager should be XA-aware. An XA resource interface for NonStop server resources does not have to perform transaction management when used with the WebLogic Server because the static resource manager handles the transaction management and is enlisted in all WebLogic Server transactions. 6-5

52 XA Resource Manager (XARM) Configuring JDBC Connection Pools for SQL/MX A wrapper driver has been written for JDBC/MX. The wrapper driver does not perform transaction management, but implements the XA interface. The XA resource implemented by JDBC/MX responds with XA_RDONLY, implying that no change was done to the underlying resource. The static XA resource manager protects changes to resources managed by JDBC/MX. Returning XA_RDONLY tells the WebLogic Server transaction manager to ignore the resource in the second phase of commit processing. If all the resources accessed with a WebLogic Server transaction are JDBC/MX resources pools, the WebLogic Server transaction manager does not write a transaction log during the commit processing. This provides better performance and reliability as the transaction log is protected with TMF audit trails. The following is a sample configuration element for the JDBCConnectionPool using the wrapper drivers. Note that the JDBC URL does not change from the underlying JDBC driver that is being wrapped. <JDBCConnectionPool CapacityIncrement= 1 DriverName= DriverName InitialCapacity= 1 MaxCapacity= 10 Name= PoolName RefreshMinutes= 0 ShrinkPeriodMinutes= 15 ShrinkingEnabled= true Targets= examplesserver TestConnectionsOnRelease= false KeepXAConnTillTxComplete= true TestConnectionsOnReserve= false RollbackLocalTxUponConnClose= true SupportsLocalTransaction= true URL= JDBCUrl /> DriverName Name Specifies the JDBC driver associated with the Pool. It can be the name of the class for the Type 2 JDBC driver or the XA DataSource driver. The Type 2 driver name is com.tandem.sqlmx.sqlmxdriver The XA DataSource driver name is com.hp.nsk.xares.wlstxsqlmxdatasource The name of the connection pool that is used when referencing the connection pool when configuring the data sources. PoolName is also used by the WebLogic Server Mbeans management infrastructure. 6-6

53 XA Resource Manager (XARM) Configuring JDBC Connection Pools for SQL/MX KeepXAConnTillTxComplete Tells the WebLogic Server not to close the connection until the global transaction is complete. This attribute must be set in the JDBCConnectionPool for the WebLogic Server to invoke the settransactionisolation method. When generating primary keys using a named sequence table, the WebLogic Server sets the transaction isolation level on the JDBC connection to TRANSACTION_SERIALIZABLE. To change the transaction isolation level, the WebLogic Server must be instructed to remain connected until the transaction is complete. This implies that all requests to acquire a connection from a specific JDBCConnectionPool for a given transaction will return the same connection object. RollbackLocalTxUponConnClose If set to true, the connection pool calls rollback() on the connection before putting it back in the pool. Enabling this attribute impacts performance because the rollback call requires communication with the database server. The NonStop SQL/MX JDBC/MX driver requires that local transactions be terminated before enlisting a connection in a global transaction. Therefore, you must set RollbackLocalTxUponConnClose to true. SupportsLocalTransaction URL Applies only to the JDBC/MX connection pools. The JDBC/MX driver can determine if it was called within the context of an external transaction (in the case of the WebLogic Server, a transaction that was imported into TMF as a branch of a WebLogic Server global transaction). If so, it defers transaction management to the application managing the transaction. Otherwise, the JDBC driver manages the transactions by itself. This flag tells the WebLogic Server that the JDBC driver has the ability to do JDBC work even without a WebLogic Server transaction in progress and is used in some sample applications used by the WebLogic Server (including repopulating the MedRec database). Designates different database instances so that the JDBC driver can determine whether it can open the database based on the URL provided. The JDBC driver should be able to parse the URL and make a connection to the database. Unlike the driver name, the JDBC URL does not change between non-xa and XA drivers. The JDBC URL is: jdbc:sqlmx: 6-7

54 XA Resource Manager (XARM) Configuring the WebLogic Server Data Sources for SQL/MX Properties The Properties field is useful only with the XADataSource driver. The property names and the various acceptable values are provided the following table. Property Name maxstatements maxpoolsize minpoolsize Description Configuring the WebLogic Server Data Sources for SQL/MX While configuring the JDBC data sources for SQL/MX, one of the XA or non-xa pools configured for SQL/MX, described in Configuring JDBC Connection Pools for SQL/MX, is used. A transaction data-source must either use the XA connection pool or must have the EnableTwoPhaseCommit attribute set to true. For example: <JDBCTxDataSource JNDIName= examples-tx-mx-datasource Name= examples-tx-mx-datasource PoolName= PoolName EnableTwoPhaseCommit= true Targets= targetservers /> Has the same meaning as specified in the JDBC specification. Valid value is greater than or equal to zero (>=0). Zero (0) disables statement caching. Less than zero (>0) enables statement caching with specific number of statements. Default value is 0. The maximum number of physical connections the pool should keep available at all times. Valid values are -1 and 0 or less than zero (<0). Negative 1 (-1) disables use of the connection pooling data source to get a connection. Zero or greater than 0 (0 or >0) value results in a data source object being created in the background and used for connection pooling. Default value is 0. This value indicates no maximum size. The number of physical connections the pool should keep available at all times. Valid values are -1 and 0 or greater than 0 (<0). Value must be less than maxpoolsize. Negative 1 (-1) disables use of the connection pooling data source to get a connection. Default value is 0. This value indicates that connections should be created as needed. The EnableTwoPhaseCommit attribute instructs the WebLogic Server to emulate an XA resource object if the underlying JDBC driver supporting the connection pool does not have XA support. This attribute is otherwise ignored. 6-8

55 XA Resource Manager (XARM) Additional Considerations for JDBC Access to SQL/MX Databases To configure non-transactional data sources, a connection pool using the default JDBC driver, or the wrapper JDBC driver can be specified. Additional Considerations for JDBC Access to SQL/MX Databases When the NonStop XA resource is registered statically with the WebLogic Server, all subsequent access to the SQL/MX database within the scope of the WebLogic Server transaction is automatically protected by the TMF transaction imported as a branch to the WebLogic Server transaction. There are three possible configuration options when configuring the WebLogic Server data sources to access SQL/MX: 1. Configure a WebLogic Server JDBC data source based on the Type 2 JDBC/MX driver. In this configuration, a WebLogic Server data source object is created based on the JDBC/MX driver. The data source is not an XA-aware resource. Therefore, it cannot be used with WebLogic containers that require an XA-aware JDBC driver (such as the Container-Managed Persistence Service (CMP) container). If a WebLogic Server transaction is started before the invocation of the component that uses the WebLogic Server JDBC data source, either initiated by the client or container-initiated transactions based on declarative requirements of the component, all the JDBC access by the component will be within the context of the imported transaction. The JDBC/MX driver operates in the context of an external TMF transaction (one not started by the JDBC/MX driver itself). Therefore, the application components should not call commit/rollback method of the JDBC/MX driver to commit/rollback the database work. Instead, the JTA methods for commiting/rolling back should be used. During commit processing, the WebLogic Server will coordinate with the static resource manager to drive the TMF transaction to completion. This is the most efficient use of JDBC/MX with the WebLogic Server. It allows the WebLogic Server to do one-phase commit optimization (if no other XA resource other than the static XA resource manager is involved in the transaction) and lets TMF perform onephase commits efficiently. 2. Configure a WebLogic Server JDBC transactional data source based on the Type 2 JDBC/MX driver. In this configuration, a TxDataSource object is created based on a non XA-aware driver by setting the EnableTwoPhaseCommit attribute to true in the data source configuration. The WebLogic Server provides an XA wrapper with JDBC/MX. The JDBC/MX driver operates in the context of an external TMF transaction (one not started by the JDBC driver itself). The XA wrapper provided by WebLogic Server does not run real transaction management. When the application calls the JTA methods to 6-9

56 XA Resource Manager (XARM) Additional Considerations for JDBC Access to SQL/MX Databases commit or rollback the transaction, the WebLogic Server calls the JDBC driver to perform the commit/rollback. The JDBC/MX driver ignores this request because the transaction is managed externally to the JDBC driver. During commit processing, the WebLogic Server coordinates with the static resource manager to drive the TMF transaction to completion This transactional data source can be used with the WebLogic Server containers that require XA-aware resources, like the WebLogic Server CMP. A restriction is that only one NonStop server data source can take part in the global transaction. Note that each data source is an independent XA resource. To use this method effectively, it is desirable to define a single TxDataSource object in the WebLogic Server configuration to access the SQL/MX database. Note that even if only the JDBC/MX resources are involved in the transaction, WebLogic Server will do a 2- phase commit processing involving the static XA resource manager and the WebLogic Server XA wrapper resources associated with each of the TxDataSource object. 3. Configure a TxDataSource object using the WLSTxSQLMXDataSource JDBC XADataSource driver provided with the WebLogic Server. This driver implements the XA interfaces (XADataSource and XAConnection) using the JDBC/MX driver facilities. In this case as in the previous cases, the JDBC/MX driver operates in the context of an external TMF transaction (one not started by the JDBC driver itself). During commit processing, the WebLogic Server coordinates with the static resource manager to drive the TMF transaction to completion. Just like the TxDataSource configured in Option 2 above, this can also be used with CMP configuration. An important thing to note is that, in this case, the WebLogic Server JDBC wrapper drivers know that the JDBC/MX driver has a resource-specific XA resource object. Therefore, the WebLogic Server expects the JDBC connection to be used as in the J2EE model. In the J2EE model, an application that uses JDBC connections is supposed to use the "acquire, use and release" model. If a connection reference is kept between method invocations under different transaction contexts, runtime errors will occur. 6-10

57 7 Configuring JDBC Stores for JMS The WebLogic Java Messaging Service (JMS) Server can be configured to use a JMS JDBC store when the underlying JDBC connection pool uses NonStop SQL/MX 2.2 with ANSI tables as the database. The JMS database contains two system tables (generically called JMSState and JMSStore) that are generated automatically and are used internally by each JMS server. Because the JMSStore table has a column defined with a BLOB data type, a special table is used by the JDBC/MX driver to store the BLOB data. Consider the following situations regarding this special table: When using a JMS Server in a WebLogic Server domain, you must pre-create this table before you start WebLogic Server. To pre-create the table, use the JdbcMxLobAdmin utility supplied with the JDBC/MX driver. The JDBC Driver for SQL/MX Programmer s Reference Manual describes how to do this. You must identify the name of the BLOB table to the JDBC/MX driver by specifying the following in the JAVA_OPTIONS environment variable: -Djdbcmx.blobTableName=catalog.schema.table-name where catalog is your catalog, schema is your schema, and table-name is the name you gave the table. If your application runs in a cluster, you must specify the prefix name for JMSDBStore to uniquely identify the tables used by a particular JMS Server. The prefix must contain the catalog name, the schema name, and a unique identifier. JMS prepends the prefix to the generic table name to form a valid table name. Specifying the prefix using the following format results in a valid table name: [catalog.] [schema.] unique-identifier where catalog is the catalog used by the application, schema is the schema used by the application, and unique-identifier is any value you choose. Note. If you specify -Djdbcmx.catalog=catalog and -Djdbcmx.schema=schema in the JAVA_OPTIONS environment variable, you do not need to specify the catalog or schema. For example, specifying a prefix such as mycat.myschema.s1 causes JMS to create tables named mycat.myschema.s1jmstate and mycat.myschema.s1jmstore. Because JDBC/MX stores BLOB data for the JMSStore table in the special BLOB table, you must create TRIGGERs to delete the BLOB data from the BLOB table when the BLOB data is deleted or changed in the base JMSStore table. Use the 7-1

58 Configuring JDBC Stores for JMS JdbcMxLobAdmin utility to create these triggers. The JDBC Driver for SQL/MX Programmer s Reference Manual describes how to do this. Note. You cannot configure a transaction (XA) JDBC connection pool or JDBC TxDataSource to use with a JMS JDBC store. JMS must use a JDBC connection pool that uses a non-txdatasource with a non-xaresource driver. For more information, see Section 8, Managing SQL/MX Tables for BLOB and CLOB Data. 7-2

59 8 Managing SQL/MX Tables for BLOB and CLOB Data Creating SQL/MX Tables on page 8-1 Providing Properties to the JDBC Driver on page 8-1 Creating SQL/MX Tables WebLogic Server uses Large Objects (LOBs) in its application. LOBs are stored by SQL/MX in a special manner and can only be accessed by configuring a JDBC Connection Pool to use either the com.tandem.sqlmx.sqlmxdriver driver or the com.hp.nsk.xares.wlstxsqlmxdatasource driver. See Configuring JDBC Connection Pools for SQL/MX in Section 6. WebLogic Server stores both Binary Large Object (BLOB) data and Character Large Object (CLOB) data. The JDBC driver implementation of BLOB/CLOB requires the existence of two special tables to store the BLOB/CLOB data. Generically, these tables are called a blobtable (for BLOB data) and a clobtable (for CLOB data). When data is inserted or updated in a base table (a table containing a column with a BLOB or CLOB datatype), the JDBC driver places a reference to the blobtable or clobtable in the base table and stores the actual BLOB/CLOB data in the blobtable or clobtable. Providing Properties to the JDBC Driver You must identify the location of these tables to the supported driver by specifying their names as properties to the driver. You use the JAVA_OPTIONS environment variable to supply the properties as follows: export JAVA_OPTIONS= -Djdbcmx.blobTableName=mycat.myschema.ZZWLI_BLOBTABLE -Djdbcmx.clobTableName=mycat.myschema.ZZWLI_CLOBTABLE Note. These three lines should be typed as one line. mycat is the catalog name of your catalog and myschema is the name of your schema. For ease of use, you can put the export statement in a shell script that you execute each time you start your application. 8-1

60 Managing SQL/MX Tables for BLOB and CLOB Data Providing Properties to the JDBC Driver 8-2

61 9 Sample Application WebLogic Server Sample Application on page 9-1 Running MedRec Application in the Installed WebLogic Server Location on page 9-1 Accessing MedRec from a Web Browser on page 9-3 Running MedRec in Another Location on page 9-5 WebLogic Server Sample Application MedRec is a sample reference application that demonstrates the BEA WebLogic Server features. For NonStop SQL/MX Version 2.2 Native Tables, the SQL/MX directory is medrec_sqlmx2. Running MedRec Application in the Installed WebLogic Server Location The easiest place to run MedRec is in the installed location which, by default, is /usr/bea/weblogic92. However, running MedRec in the installed location changes files in the installed directories, which can cause problems for other users who want to run private copies of MedRec. Also, you need write access to the installation directories. Before you run MedRec or other applications with WebLogic Server, ensure that the NonStop server is using the correct software prerequisites and your shell environment has correct values. Note that the MedRec sample application accesses the internet. If your server requires a proxy to access the internet, edit the startmedrecserver_sqlmx.sh command procedure to set -Dhttp.proxyHost, -Dhttp.proxyPort, and -Dhttp.nonProxyHosts. Set and export environment variables for use of NonStop Server for Java 5.0 and NonStop TCP/IPv6. For example: ksh [125] export JAVA_HOME=/usr/tandem/java ksh [126] export PATH=$JAVA_HOME/bin:$PATH ksh [127] export WL_HOME=/usr/bea/weblogic92 ksh [128] add_define =PTCPIP^FILTER^KEY class=map file=mykey If your NonStop TCP/IPv6 process is not named $ZTC0, create a define so that WebLogic Servers started by this shell use NonStop TCP/IPv6. For example: ksh [129] add_define =TCPIP^PROCESS^NAME class=map file=\$zsm1 It is recommended that you save these commands in a file, such as.profile. 9-1

62 Sample Application Running MedRec Application in the Installed WebLogic Server Location The prerequisite software and shell environment can be checked using the same script run during the installation. For example: ksh [130] $WL_HOME/server/lib/hpns/check-wl-hpns.sh To run MedRec in directories outside the installed WebLogic Server location, see Running MedRec in Another Location. During installation of the NonStop Server Toolkit, extra files needed to run MedRec sample application are copied into the directory: $WL_HOME/samples/domains/medrec_sqlmx2 if you are running SQL/MX Version 2.2 MX tables This location can be used to run MedRec immediately after installation. If you have previously run medrec_sqlmx2, you might need to clean up before running medrec_sqlmx2 again. To clean up, run the cleanmedrec_sqlmx.sh script using the same user ID as the previous user who ran medrec_sqlmx2. To run the sample application, ensure that environment variables are set and exported, then use the startmedrecserver_sqlmx.sh script. For example: ksh [134] export JAVA_HOME=/usr/tandem/nssjava/jdk150_h50 ksh [135] export PATH=$PATH:$JAVA_HOME/bin ksh [136] export WL_HOME=/usr/bea/weblogic92 ksh [137] cd $WL_HOME/samples/domains/medrec_sqlmx2 ksh [138]../startMedRecServer_sqlmx.sh Note that startmedrecserver_sqlmx.sh calls $WL_HOME/common/bin/commEnv.sh, which sets the variables _RLD_LIB_PATH and _RLD_FIRST_LIB_PATH. The following portions of output from the startmedrecserver_sqlmx.sh script are useful to note: *************************************************** * To start WebLogic Server, use a username and * * password assigned to an admin-level user. For * * server administration, use the WebLogic Server * * console at * *************************************************** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ After the server has booted, point your browser to the URL " to view the WebLogic Server Index running on this server. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ <Dec 2, :00:20 PM PST> <Notice> <WebLogicServer> <BEA > <Server started in RUNNING mode> <Dec 2, :00:19 PM PST> <Notice> <WebLogicServer> <BEA > <Thread "ListenThread.Default" listening on port 7001, ip address *.*> <Dec 2, :00:19 PM PST> <Notice> <WebLogicServer> <BEA > <Thread "SSLListenThread.Default" listening on port 7002, ip address *.*> 9-2

63 Sample Application Running MedRec Application in the Installed WebLogic Server Location The NonStop SQL catalog is created and populated the first time you start this sample application and the catalog name is put into files you can use to control the catalog. Subsequent starts of MedRec will keep the same catalog data. Also, the scripts that control the catalog are available in the directory db where you are running the application. The defaults used with NonStop SQL are: SQL/MX catalog SQL/MX schema SQL/MP subvolume (applies to SQL/MX 2.0 native tables only) TMF resource manager The current user s group. For example, DEV. The current user s ID. For example, USER. The current user s default subvolume. medrec To specify other values for these default values, read the instructions in the script create_medrecdb.sh. Be sure to escape the dollar-sign ($) character in the volume name. To use any of these scripts, change to the correct directory and run the script. For example, to repopulate the catalog: ksh [142] cd $WL_HOME/samples/domains/medrec_sqlmx2/db ksh [143] create_medrecdb.sh -reload The other scripts are input files to SQL. Ensure that you use the correct command interpreter. For example, to remove the catalog after you have finished using the sample application: ksh [144] cd $WL_HOME/samples/domains/medrec_sqlmx2/db ksh [145] create_medrecdb.sh -drop Accessing MedRec from a Web Browser From a web browser, view the initial MedRec screen at the address that was output at the shell when the application started. Figure 9-1 and Figure 9-2 show the initial MedRec screens. 9-3

64 Sample Application Running MedRec Application in the Installed WebLogic Server Location Figure 9-1. Initial MedRec Screen 9-4

65 Sample Application Running MedRec in Another Location Figure 9-2. MedRec Logon Screen Running MedRec in Another Location You might want to run MedRec outside the WebLogic Server installation directories if: you are not the user who installed WebLogic Server. you want to keep a clean set of MedRec files in the installed location so that other users can copy them for their private use. The standard mechanism for creating a private copy of MedRec is the Configuration Wizard, config.sh. BEA documentation describes how to run the Wizard in Console mode. Another way to run a private copy of MedRec is to copy existing sample files and change values in them. 1. Create your own directory to run MedRec. For example: ksh [146] MYMEDREC=/h/me/mymedrec 9-5