NonStop Server for Java 7.0 Programmer's Reference HP Part Number: 693949-002 Published: February 2014 Edition: J06.15 and subsequent J-series RVUs and H06.
© Copyright 2013, 2014 Hewlett-Packard Development Company, L.P. Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, 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.
Contents About this manual.........................................................................................7 Manual information..................................................................................................................7 New and changed information...................................................................................................7 Intended audience....................................................................................................................
Implementation specifics............................................................................34 Headless support....................................................................................................................34 Additional files.......................................................................................................................35 Additional environment variable...............................................................................................
-d64 option.......................................................................................................................63 Using 64–bit java launcher.................................................................................................64 32–bit process support............................................................................................................64 Large heap support......................................................................................................
Public library directory........................................................................................................92 Java based JAR file locations...............................................................................................92 Dynamic link libraries.........................................................................................................93 Makefile to link native libraries...........................................................................................
About this manual NonStop Server for Java 7.0 Programmer's Reference manual identifies the changes in the HP adaptation of the reference Java implementation, emphasizing the differences between the reference implementation and NSJ7. For more information on the standard architecture, see Oracle Java documentation. Manual information Abstract This manual describes the HP NonStop™ Server for Java™, based on Java Platform Standard Edition 7.
Document changes • Added a note in the section “Installation requirements” (page 20). • Updated version procedure information in the section “Verifying the Java installation” (page 23). • Added a section “Handling large GC log files” (page 55). • Updated the section “JVM data segment for 32–bit JDK7” (page 56). • Updated the section “JVM data segment for 64–bit JDK7” (page 57). • Added a section “Java signal handlers” (page 65). • Added a section “SecureRandom startup enhancement” (page 69).
Table 1 Organization of chapters Section Description “Introduction to NSJ7” (page 14) Explains NonStop software fundamentals applicable to NSJ7, describes associated Java products on the NonStop system, lists the J2SE and JDK features supported by NSJ7. “Installation and configuration” (page 20) Explains installation and configuration requirements, NSJ7 directory structure, procedures to run Java tools and to verify the installation.
NonStop server for Java library In addition to this manual, the NonStop Server for Java library includes: • NonStop Server for Java 7.0 Tools Reference • NonStop Server for Java API Reference Pages NonStop system computing documents The following NonStop system computing documents are available in the HP NonStop Technical Library at Business Support Center (BSC).
• ◦ SQL/MP Programming Manual for C ◦ SQL/MP Programming Manual for COBOL ◦ See also SQL Supplement for H-series RVUs. SQL/MX Manuals NonStop Server for Java includes JDBC drivers that enable Java programs to interact with NonStop SQL databases with SQL/MX.
• Java Transaction Service (JTS) document • Java Remote Method Invocation (RMI) document Notation conventions Bold type Bold type within text indicates terms defined in the Glossary. For example, abstract class Computer type Computer type letters within text indicate keywords, reserved words, command names, class names, and method names; enter these items exactly as shown. For example: myfile.
Punctuation Parentheses, commas, equal signs, and other symbols not previously described must be entered as shown. For example: -D propertyName=newValue Item spacing Spaces shown between items are required unless one of the items is a punctuation symbol such as a parenthesis or comma. If there is no space between two items, spaces are not permitted. In the following example, spaces are not permitted before or after the period: subvolume-name.
1 Introduction to NSJ7 NonStop Server for Java 7.0 (NSJ7) provides a Java environment that supports compact, concurrent, and dynamic portable programs for the NonStop systems. NSJ7 is supported on the NonStop Open System Services (OSS) environment. NSJ7 uses the NonStop operating system to provide scalability and program persistence to the Java environment. NSJ7 is based on the Java Platform Standard Edition (Java SE) 7.0 reference, which is a Java implementation for Solaris.
NOTE: • ◦ For user thread limitation see Open System Services Programmer's Guide. ◦ Parallel and CMS GC are not supported on single core machines. NSJ7 continues to provide headless support NSJ7 is a headless JVM that conforms to the Oracle's headless support standards regarding Java Abstract Window Toolkit (AWT) classes and methods. For implementation-specific information, see “Headless support” (page 34).
For more information on the core packages of Java SE Development Kit 7.0, see “Oracle Java documents” (page 11). Java naming and directory interface (JNDI) The JNDI provides naming and directory functionality to Java programs. It is independent of any specific directory service implementation; therefore, it allows a variety of directories to be accessed in a common way. The JNDI architecture consists of an Application Programming Interface (API) and a Service Provider Interface (SPI).
Figure 1 Java based products on NonStop systems JDBC drivers for NonStop SQL database access JDBC drivers implement JDBC API and provide access to NonStop SQL databases. You can use JDBC API calls in your Java programs to access SQL tables on NonStop systems. The following are the available drivers and the access they provide are: • • Type 2, which is native API driver to use in Java programs running with NonStop Server for Java on a NonStop system. The type 2 driver is installed using SUT.
Pathway API for Java The Pathway API for Java provides access to a file called $RECEIVE, which is required to enable a process to act as a Pathway server. These servers are typically used in legacy applications. Pathway server programs read requests from requestor programs and act on those requests. The Guardian requestor or server model is described in the TS/MP 2.5 Pathsend and Server Programming Manual.
• Supports the NSJMS C++ API, which implements a subset of the functionality provided by the Oracle JMS API, and is used by C++ client applications running on a NonStop system to interoperate with other JMS clients. • Uses the NSJMS administrative utility to manage the NSJMS environment. You can invoke the utility through a command-line interface or XML interface. NSJMS conforms to Oracle's published specification, Java Message Service, except as noted in NSJMS documentation.
2 Installation and configuration Summary of installation and configuration tasks • Perform the installation requirements task described in “Installation requirements” (page 20). • Perform the preinstallation tasks described in “Preinstallation tasks” (page 20). • Perform the installation tasks described in “Installing NSJ7” (page 20). • Perform the post-installation tasks described in “Post-installation tasks” (page 22) as per your requirement.
Placing the new software on the NonStop system using DSM/SCM NOTE: The following procedure is applicable for both 32–bit and 64–bit NSJ7. • Receive the SPR from disk or tape. • Copy the SPR to a new revision of the software configuration you want to update. • Build and apply the configuration revision. • Run ZPHIRNM to perform the rename step. DSM/SCM places the pax file in $tsvvol.ZOSSUTL subvolume, where, tsvvol is the disk volume in which the DSM/SCM places the target subvolumes (TSVs).
For 32–bit NSJ7 Use PINSTALL with the —s option and type the following command in the TACL prompt: TACL> PINSTALL -s:/usr/tandem::-rvf /G/tsvvol/zossutl/T2766PAX PINSTALL delivers the contents of T2766PAX to the OSS directory located at: /nssjava/jdk170_h70 Example 1 To install the product in the location /h/myjava Type the following command in the TACL prompt: TACL> PINSTALL -s:/usr/tandem:/h/myjava: -rvf /G/tsvvol/zossutl/T2766PAX PINSTALL delivers the contents of T2766PAX to
Verifying the Java installation Check with your system administrator for the installed NSJ7 (32–bit and 64–bit) software locations, and verify the installation and the environment. This example assumes that NSJ7 is installed in a nonstandard location— /home/lee/nssjava/jdk170_h70 directory: NOTE: For more information about the operating system requirements, see T2766H70 or T2866H70 Softdoc file. 1.
Creating larger or additional swap file HP recommends that the swap file size must be equal to the physical memory size, for each processor that runs the Java virtual machine (JVM). If you plan to run multiple large processes in the same processor, you might need to create additional swap files because processes running in the same processor share the same swap file. Your system administrator can use the NSKCOM tool to create additional swap files.
export CLASSPATH=classpath1:classpath2... jdkTool A command-line tool, such as java or javac. For the tools list, see NonStop Server for Java 7.0 Tools Reference. classpath1:classpath2 Class paths to the .jar, .zip, or .class files. Each class path must end with a filename or directory name depending on the specific setting. • For a .jar or .zip file that contains .class files, the class path ends with the name of the .jar or .zip file. • For .
_RLD_LIB_PATH The _RLD_LIB_PATH environment variable specifies the library path for DLLs. You need to use this environment variable if you use user DLLs. You can specify one or more directories as required. Separate each directory in the list by using a colon (:). Set this environment variable as follows: export _RLD_LIB_PATH=dll_path[:dll_pathn]... where, dll-path and dll-pathn are the directories where the user DLLs reside.
Java server-side applications are typically configured with large Java heap sizes, larger than 128 MB. In addition, the JVM and its native components (for example, NSJSP transport library, JDBC Driver for SQL/MP, JDBC Driver for SQL/MX, SQL/MX call-level interface, and potentially any custom-user JNI code) allocate memory for their own use. Thus, the overall heap space required by a JVM process is considerably higher than the configured Java heap space.
Segment Type........... Segment Size........... MDs in Use............. Max MDs Used........... Last Fail Size......... Current Pool Size...... Max Pool Size.......... Current Pool Alloc..... Current Pool Frags..... KSEG2 268435456 1248 2357 0 16774788 Initial Pool Size...... 16776992 Min Pool Size.......... 4516992 Max Pool Alloc.......... 375 Max Pool Frags.............. 16776992 16776992 4715520 382 • The QIO segments on this system (\GOBLIN) are moved to KSEG2 based on the value of the segment type.
Table 4 Demonstration programs Demonstration Program Description /demo/invocation_api/oss How to properly build an executable that can create its own Java virtual machine (JVM). Contains source and Makefile to create 32–bit invocation API demo. /demo/invocation_api/oss64 How to properly build an executable that can create its own Java virtual machine (JVM). Contains source and Makefile to create 64–bit invocation API demo. /demo/javahjni/oss How to create a native library.
3 Getting started Although this manual assumes that you are familiar with using Java and HP NonStop Open System Services (OSS), this section provides background information for those who are not familiar with these products. Additionally, this section explains how to perform common tasks that are characteristic to running Java applications on NonStop systems.
This command must display the fully qualified name of the java executable found in your path. If no Java executable is found, the command displays the message, java not found. 4. Compile the Java source code by using the javac tool. a. Ensure you have performed step 3 so that javac is in your current path. b. At the OSS prompt, change the directory (cd command) to where your Java source file is stored. c.
For more information on using -name option with 32–bit JDK and 64–bit JDK, see “Java process name” (page 98). For more information about the run(1) utility, see Open System Services Shell and Utilities Reference Manual. Configuring a Java Pathway serverclass Following is a brief overview of the specific Java requirements for configuring a Java program to run as a Pathway serverclass. Complete information about the topic is available in the TS/MP 2.5 System Management Manual.
PROGRAM Set the PROGRAM attribute to the java executable. The java executable is located by default in /usr/tandem/nssjava/jdk170_h70/bin. For example, from the OSS prompt, start a PATHMON (process monitor) named $foo and set the PROGRAM attribute at the PATHCOM prompt: $gtacl -p pathcom \$foo PATHCOM .....
4 Implementation specifics This section explains the various topics pertaining to the implementation specifics of NonStop Server for Java: • “Headless support” (page 34) • “Additional files” (page 35) • “Additional environment variable” (page 35) • “Java native interface (JNI)” (page 35) • “Floating-point implementation” (page 39) • “Multi-threaded programming” (page 40) • “Java print service” (page 44) • “Using the Guardian printer” (page 45) • “Java authentication and authorization servic
When GraphicsEnvironment.isHeadless returns true, and if your Java programs use classes and methods that require a display, keyboard, sound, or mouse operation, the class or method throws a HeadlessException. This value is always true in NSJ7. Classes and methods that support printing, fonts, and imaging are fully supported in a headless JVM. While the Oracle documentation for the reference implementation states that you must set the system property –Djava.awt.
the POSIX User Thread (PUT) Model Library” section in the Open System Services Programmer's Guide. The calls are: ◦ PUT_ABORTTRANSACTION() ◦ PUT_BEGINTRANSACTION() ◦ PUT_ENDTRANSACTION() ◦ PUT_RESUMETRANSACTION() NOTE: OSS supports a maximum of 1000 concurrent transactions in a process. However, JVM is an exception where the maximum transactions allowed are 200 as described in “Controlling maximum concurrent transactions” (page 82).
NOTE: If the native code has large variables on the stack, then calling this native code might exceed the default stack space provided for each thread. If the native code exceeds the amount of stack space allocated for it, then it results SIGSTK. To prevent overflowing the available stack space, consider allocating large variables on the heap rather than using the stack. Otherwise, you can increase the default stack size for each thread by specifying the -Xss option when starting java.
AttachCurrentThread() return JNI_EUNSUPPORTED error if they are called from the main thread with distributed GC enabled. NOTE: All the instances of distributed GC in this manual refer to parallel and CMS GC. • Compile code written in C++ by using the compiler command-line options as explained in “Linker and compiler options” (page 38). • NSJ7 provides DLLs. Therefore, you can build your own executable and link it to the JVM DLL, libjvm.so.
In addition, a compilation unit containing JNI code that has any floating-point parameters being passed across the JNI boundary and that is directly called by the JVM, must use the IEEE floating-point arithmetic. IEEE floating-point format is the default for TNS/E native compilers, and hence it is not needed to be defined in the compile command-line. Any compilation units not called directly by the JVM can be compiled without conforming to the IEEE floating-point format.
Double-precision values For double-precision values, TNS floating-point representations have smaller exponents (hence a smaller range) than IEEE floating-point representations, but they are more precise, which is demonstrated in Table 6 (page 40): Table 6 Double-precision ranges Floating-Point representation Minimum positive decimal value Maximum decimal value TNS 1.7272337110188889e-77 1.15792089237316192e77 IEEE 4.94065645841246544e-324 1.
process address space in the same CPU. With PUT library on NonStop systems, one thread can never be preempted by another thread if the -XX:ThreadTimeSlice option is not used. This section includes the following topics: • “Thread scheduling” (page 41) • “Threading considerations for Java code” (page 43) • “Threading considerations for native code” (page 43) • “ThreadDumpPath support” (page 44) Thread scheduling When a Java thread is created, the thread inherits its priority from the parent thread.
} } } On the NonStop system, the execution of threads is not time-sliced. Messages from one thread precede those from the other thread for thread 0 and thread 1 as follows: Thread Thread Thread Thread Thread Thread Thread Thread Thread Thread Thread #0, #0, #0, #0, #0, #0, #0, #0, #1, #1, #1, tick tick tick tick tick tick tick tick tick tick tick = = = = = = = = = = = 50000 100000 150000 200000 250000 300000 350000 400000 500000 100000 150000 When the SelfishRunner.
NOTE: This option is an experimental option and HP does not recommend this option to be used in the production environment. Threading considerations for Java code A thread-aware function blocks only the thread calling that function, rather than blocking the entire process. NSJ7 uses the PUT library in which all I/O are nonblocking. JToolkit provides a thread-aware API for performing I/O to Enscribe files, $RECEIVE, and Pathway servers by using Pathsend procedure calls.
timer callbacks and detection of I/O completions can be severely impacted by long-running threads. • You must be careful when using thread-aware interfaces. The Open System Services Programmer’s Guide lists thread-aware equivalents of NonStop system-specific interfaces. These interfaces have an explicit put_ prefix.
printers, see Spooler FASTP Network Print Processes Manual. For information on the Spooler subsystem, see Spooler Utilities Reference Manual. All printing features and attributes in the JPS classes listed below work when the NonStop spooler and printer support the API. However, the NonStop operating system requirement for sending text and postscript files to separate printers also applies when printing in JPS. The following are the JPS classes: • javax.print • javax.print.attribute • javax.print.
1. 2. 3. Export DUMP_CORE=1. Start the Java application. Press Ctrl+break while the process is running. Saveabend file generation If distributed GC is enabled, then the saveabend files are generated differently. The Java process or GC process can encounter a problem and terminate abnormally. When one process in the Java process group terminates abnormally, then the other processes detect the abnormal termination and also terminate abnormally.
JavaBeans JavaBeans are reusable software components that can run in both a design environment (inside a builder tool) and runtime environment. The design environment is highly visual and requires that JavaBeans provide design information to the programmer and to customize its behavior and appearance. In the runtime environment, JavaBeans might be visible in the case of a Graphical User Interface (GUI), or invisible in the case of a data feed control.
-Xnoagent Disables the old Sun.tools.debug agent. This is the default value. -agentlib:jdwp=sub-options sub-options are specified in the following format: name1[=value1],name2=[=value2]... The sub-options are as follows: transport Indicates the name of the transport. The value is dt_socket, and by default, NSJ7 uses dt_socket.
Example 5 When the port number is specified java -Xdebug -Xnoagent -agentlib:jdwp=transport=dt_socket,server=y,address=4000, suspend=y classname arguments Example 6 When the range of ports are specified and hostname is implicit java -Xdebug -Xnoagent -agentlib:jdwp=transport=dt_socket,server=y,address=4000-4050, suspend=y classname arguments Example 7 When the machine name and port range are specified java -Xdebug -Xnoagent -agentlib:jdwp=transport=dt_socket,server=y,address=someMachine:4000-4050, suspend=y
To debug native code, wait until the DLL is loaded. Visual Inspect allows you to stop the program after the DLL is loaded so that you can set breakpoints. For information on how to set the breakpoints, see Native Inspect Manual. You can view and debug the native routine to be debugged and other native routines that routine calls. All other scopes above the native routine are either compiled or interpreted Java code, which the inspect debugger has no knowledge about.
NOTE: The -tclient option is not valid with NSJ7. -tserver Runs the application in the Java HotSpot server VM. NOTE: The -tserver is the default option for NSJ7. Hence, specifying -tserver is optional. For more information about jdb and how to start a Java program so that jdb can attach to it, see jdb in the NonStop Java 7.0 Tools Reference Pages.
Figure 2 Layout for generations The following list describes the various generations: • Young (also called new) generation—The JVM allocates objects in the young generation pool. Minor garbage collection happens when this young generation is full and the JVM is unable to allocate new objects. The young generation also includes two survivor spaces.
NOTE: You must consider the amount of physical memory available on the system while choosing a value for —Xmx. If the virtual memory of a process exceeds the physical memory, then memory thrashing occurs and the application performance slows down. NOTE: HP recommends that the application specifies the same value for —Xms and —Xmx. If only —Xmx is specified in the command-line, the default value used for —Xms is the same value that is specified for —Xmx.
This option enables parallel GC for the old generation. This option automatically enables parallel scavenge (for young generation). –XX:+UseParallelOldGCCompacting This option is used to enable parallel old compacting collector for the tenured generation. -XX:+UseAdaptiveSizePolicy This option enables adaptive size policy for the Java heap. By default, this option is disabled in NSJ7. However, if the parallel GC is enabled, this option is enabled automatically unless it is disabled it in the command-line.
This option enables concurrent mark sweep GC for the old generation. Note that the default GC is the serial GC for old generation, and hence this option must be specified to enable concurrent mark sweep GC. By default, if this is selected, UseParNewGC is selected for the young generation. -Xconcgc This option enables concurrent mark sweep GC. –XX:+CMSIncrementalMode This option enables running CMS GC for the old generation in the incremental mode.
HP’s GC log rotation option, —XX:GCLogLimits, remains unchanged and supports both —Xloggc and —Xverbosegc options. NOTE: HP’s LogRotation option —XX:GCLogLimits=M,N overrides Javasoft’s LogRotation options. If HP's —XX:GCLogLimits is specified, GC logs rotate to new log file after N records. Other CMS/Parallel GC options In earlier versions of NSJ, JVM does not throw an error message if some of the parallel and CMS GC related options are used.
In the sample command invocation, the first JVM segment (segment ID 1069) size is 64 MB. Then the remaining 192 MB memory is divided (calculated dynamically) among the next five segments whose segment ID range is 1070–1074. JVM data segment for 64–bit JDK7 64–bit NSJ7 JDK/JRE allocates one extensible flat segment for its internal dynamic memory requirement. The initial size of this segment is 512 MB, and the maximum size is 12 GB. This segment is referred as JVM data segment.
on the Internet. GC tuning is assisted by GC profile data which can be collected and analyzed as explained in the subsequent sections. Since GC occurs when generations fill up, the amount of available total heap memory has direct impact on the performance.
• The article, Turbo-charging Java HotSpot Virtual Machine, v1.4.x to Improve the Performance and Scalability of Application Servers. • Java Performance Documentation.
round-robin method. This allows GC data to be archived easily and thus helps to limit the amount of disk space consumed by the GC log files. Log rotation is also supported when using zero-preparation -Xverbosegc. To enable log rotation, use the following option along with -Xverbosegc, -Xloggc, or zero-preparation verbosegc: -XX:GCLogLimits=M,N where, M is a non-negative integer that specifies the number of rotating GC log records per file. A value of 0 specifies unlimited number of GC log records per file.
Other HeapDump options In addition to -XX:+HeapDump, the following three different HeapDump options are available: -XX:+HeapDumpOnCtrlBreak, -XX:+HeapDumpOnOutOfMemoryError, and -XX:+HeapDumpOnly. Table 8 (page 61) lists the heap dump options. Table 8 HeapDump options Option Trigger Format -XX:+HeapDump SIGQUIT ASCII; Set the java___
NOTE: The —XX:+HeapDumpOnOutOfMemoryError option does not work with the low-pause collector (option —XX:+UseConcMarkSweepGC). • -XX:+HeapDumpOnly It enables heap dumps using the SIGWINCH signal (signal 12) with the help of —XX:+HeapDumpOnly option or _JAVA_HEAPDUMP_ONLY environment variable. This interface is provided to separate the generation of thread and trace information triggered through SIGQUIT from the heap dump information.
However, using this option increases the application start up time, since the initialization of JVM is slower. HP recommends that a pilot run be conducted before deploying this option in production environment. The objective of the pilot run is to ensure that the increase in the application start-up time is tolerable, and that there is a visible reduction in the application stalls (pause times) during GC. For more information, see “Application tuning and profiling” (page 86).
Using 64–bit java launcher To launch a 64–bit Java process use the following steps: 1. Set the PATH environment variable to point to the 64–bit launcher using the following command at the OSS prompt: $ export PATH=/home/lee/nssjava/jdk170_h70/bin/oss64:$PATH 2. Run the application using the 64–bit launcher: java NOTE: If the 64–bit Java launcher is launched with -d64 option, the option is ignored and it does not performs an exec to create new 64–bit Java process.
Large heap support If a Java application requires large heap (greater than 1276 MB), 64–bit JDK must be used. After the installation, you can run the application with heap sizes greater than 1276 MB using –Xms and –Xmx command-line options.
Table 9 Reserved Signals List Reserved Signals (Always) Reserved Signals (depending upon command line options)1 SIGFPE “SIGWINCH” (page 66) SIGILL “SIGALRM” (page 66) SIGSEGV “SIGUSR2” (page 66) SIGQUIT “SIGHUP” (page 66) SIGUSR1 “SIGINT” (page 67) SIGSTK “SIGTERM” (page 67) 1 Click on the specific signal to obtain information about how to install signal handlers for the corresponding signals. SIGWINCH HeapDumpOnly feature uses SIGWINCH signal.
SIGINT JVM uses this signal to support shut down hook if —Xrs is not specified in the command line option (reduce signal usage). If –Xrs is specified in the command line option, the application can install signal handlers for SIGINT signal. SIGTERM JVM uses this signal to support shut down hook if —Xrs is not specified in the command line option (reduce signal usage). If –Xrs is specified in the command line option, the application can install signal handlers for SIGTERM signal.
Example 10 The following is the first few lines of the error log file when a Java process with parallel or concurrent GC terminates abnormally # # A fatal error has been detected by the Java Runtime Environment: # # SIGSEGV (0xb) at pc=7ed16ab4, pid=1979711505, tid=10 # # JRE version: 7.0 # Java VM: Java HotSpot(TM) Server VM (21.1-b02-svcnedccadmin:2012jul25-11:47 mixed mode nsk oss-ia64 ) # Problematic frame: # C [(DLL libjvm.so)+0x0] invoke__17PSParallelCompactSFb + 0x1C0 (DLL libjvm.
Example 12 When the filename is specified as errorlog%p java –XX:ErrorFile=errorLog%p SampleJava where, errorLog is the filename of the error file.
By default, this option is not enabled. Use the following option to enable the same: —Djava.security.nativeRNG=true NOTE: This option can be used in NonStop Server for Java 6.0 also. VirtualMachine.list() support On earlier versions of NSJ, the list method of VirtualMachine API (attach API) used to return an empty value on NonStop system. However, on other platforms the list method used to return the list of Java process running on it.
5 Java infrastructure Java - WORA Applications written in Java, as is well known, are platform agnostic. The platform specific features are implemented by the Java Virtual Machine (JVM) thus insulating applications from platform idiosyncrasies. Thus Java applications exhibit similar behavior even when run on different software platforms. This is a unique feature of Java and is popularly called Write Once Run Anywhere (WORA).
Figure 3 Client server application with TCP/IP and JI as communication channels Client Application Client Application Application Application java.net.Socket/ java.nio.socketChannel java.net.Socket/ java.nio.socketChannel TCP JI Pathsend / FS API TCP JI java.net.Socket/ java.nio.socketChannel java.net.Socket/ java.nio.
server class (JISVC is an assumed server class name), whereas the client is configured to act as a Pathsend client. The configuration details are explained in the section “Mapping file” (page 76). Sequence Calls Description (1) ssock.accept(); The server starts listening on $RECEIVE for any new connections. For more information on connections, see “Establishing a connection” (page 79). This call is initiated on the server side. (2) new Socket(“nonstop.server.
Figure 4 Creating a java.net.socket Application Start Application creates a client/server socket new Socket(“nonstop.server.com”,8070); Allow TCP socket creation No JI library checks if there is an entry in JI mapping file for the socket address? Yes Make JISocketlmpl as Socketlmpl for the socket SelectableChannels in java.nio.channelspackage NSJ defines a service provider interface (spi) package (java.nio.channels.spi) in NIO. This package defines an abstract class SelectorProvider.
Figure 5 Creating a java.nio.SocketChannel Application Start Application obtains a Socket channel by invoking SocketChannel.open () JI library return JI’s implementation of java.nio.SocketChannel Application invokes SocketChannel.
Mapping file When the JI library is loaded, it searches for a mapping file to determine what sockets and channels need to use NonStop IPC. The mapping file contains key value pairs delimited by . The JI library searches for the mapping file in the following sequence: 1. Java System Property: The JI library searches for a system property by name ji.mapping.file. For example, java -Dji.mapping.file=/usr/home/ji.prop 2.
Table 11 Attributes relevant for a client socket Relevant for File system IPC Attribute name Default value Mandatory Relevant for Pathsend IPC node None No Yes Yes None Yes Not applicable Yes The value of the port with a prefix of the letter Q. No Not applicable Yes BI_DIRECTIONAL No Yes Yes None Yes (If the domain attribute is not mentioned) Yes Not applicable None Yes Yes Not applicable Name of the NonStop node where the server process is running.
Table 11 Attributes relevant for a client socket (continued) Attribute name Default value Mandatory Relevant for Pathsend IPC The value of the port No The value of this attribute is used by the server with a prefix of letter to accept the connection from the Pathsend IPC Q. For example, socket. pathsend_qualifier=Q6547. Yes Not applicable domain1 Yes Not applicable pathsend_qualifier None The value is the domain name in case the server class is configured in a TS/MP domain.
Examples Example 14 client_socket-lab.ind.hp.com:9080 process_name=MRSS This means any client socket trying to connect to lab.ind.hp.com and port 9080 internally connects to the process by name MRSS running on the same node as the client and establishes a BI-DIRECTIONAL communication. Example 15 server_socket-0.0.0.0:9080 This means a server socket that is listening for connections on any TCP interface (0.0.0.
A NonStop IPC socket supports both the modes of communication with the default being BI-DIRECTIONAL. BI-DIRECTIONAL mode To support BI-DIRECTIONAL communication, the client establishes a second channel of communication by opening the server process at the time of establishing a connection. At any given time the second channel is in a state where the server can send data to the client.
JI client with a legacy TS/MP serverclass for context-free communication The client socket in the mapping file needs to be configured with the attribute pathsend_qualifier set to **CONTEXT-FREE**. For example, pathsend_qualifier=**CONTEXT-FREE**. Internally no operations are performed during the connect operation.
6 Transactions NSJ7 allows you work with transactions in the following ways: • Use the Current class methods to define transactions across transaction services, such as transactions that include JDBC calls. • Use the Java Transaction API (JTA). This section explains the following topics: • “Controlling maximum concurrent transactions” (page 82) • “Current Class methods” (page 82) • “Java transaction API” (page 83) If you use JNI and transactions, see “Java native interface (JNI)” (page 35).
Table 13 Current Class methods (continued) Method Description set_timeout Modifies the time-out value associated with transactions started by subsequent invocations of the begin method. suspend Suspends the association of the calling thread with a transaction context. The following code fragment shows how to use the begin() and commit() methods of the Current class: import com.tandem.tmf.Current; Current tx = new Current(); // start a new transaction in the current thread tx.begin(); // ...
NSJ Transaction API supports all of the preceding interfaces, but only UserTransaction is available for client programs. UserTransaction allows the client to control transaction boundaries programmatically. UserTransaction methods perform the following: • Begin transaction • Commit transaction • Obtain transaction status • Mark transaction for rollback • Rollback transaction • Set timeout for transaction javax.transaction exceptions Oracle JTA package (javax.
Example 17 By default, NSJ transaction API-TMF The following code gets a reference to UserTransaction based on TMF (by default). It then starts and ends a transaction. import javax.transaction.UserTransaction; import com.tandem.jta.JTAFactory; // Get a reference to UserTransaction based on TMF (by default). UserTransaction utx = JTAFactory.getUserTransaction(); // Start transaction utx.begin(); // Do work ... // Commit transaction utx.
7 Application tuning and profiling This chapter provides information about application tuning and profiling, and it includes the following topics: • “Profiling application performance” (page 86) • “Tuning application performance” (page 89) Profiling application performance Application profiling and monitoring are supported through HPjmeter tool, which works in combination with NSJ options, —Xeprof and —agentlib:hprof. HPjmeter tool contains support for both 32–bit and 64–bit NSJ7.
1) 2) 3) b. c. 4. 5. $JMETER_HOME/lib/oss, to monitor pre—NSJ7 Java process. $JMETER_HOME/lib/oss32, to monitor 32–bit NSJ7 Java process. $JMETER_HOME/lib/oss64, to monitor 64–bit NSJ7 Java process. export JAVA_HOME=/usr/tandem/nssjava/jdk170_h70 java -agentlib:jmeter[=options] Start the HPjmeter console from a local installation on your client workstation (HP-UX, Windows, or Linux). To download HPjmeter consoles for these platforms, visit http:// www.hp.com/go/hpjmeter.
The following message is displayed. eprof: starting profiling Allow the profiling to continue for a desired length of time. 4. Stop the profiling interval by sending the same signal to the JVM: kill -USR2 pid The following message is displayed. eprof: terminating profiling writing profile data to ./filename.eprof 5. You can now open the saved file in the HPjmeter console and view the collected metrics. The HPROF profiler HPROF is a profiling agent that is based on a profiling interface called JVMTI.
The GC data is written to a file named java_pid.vgc in the current directory of the JVM process. Allow the profiling to continue for a desired length of time. iv. Stop the data collection interval by sending the same signal to the JVM: kill -ALRM pid v. You can now open the saved file in the HPjmeter console and view the collected metrics. After completing the data file collection, perform the following steps: 1.
$ gtacl –p nskcom NSKCOM - T5838H02 BASE (15AUG12) - Jun 13 2012 Copyright 1995 Compaq Computer Corporation $SYSTEM.SYSTEM.ZSYSCFG KMS.SWAPFILE = 0 $DATA03.SWAP.CPU0A STOP KMS.SWAPFILE = 0 $DATA03.SWAP.CPU0B STOP . . . KMS.SWAPFILE = 5 $SWAP45.SWAP4.
8 Migrating applications This section describes the changes required to migrate applications that use earlier versions of NSJ. The following lists the various terminologies to be noted: • NSJ4 refers to the product based on J2SE SDK 1.4.x • NSJ5.1 refers to the product based on J2SE JDK 1.5.x • NSJ6 refers to the product based on Java SE JDK 1.6.x • NSJ7 refers to the product based on Java SE JDK 1.7.
Table 14 Summary of migration changes for NonStop server for Java versions (continued) Version 2 of NonStop NonStop Server for Server for Java 4 Java 4 (T2766H10 on (T2766V20 on TNS/R) TNS/E) NonStop Server for NonStop Server for Java 5.1 (T2766H50) Java 6.
When you follow this recommendation, you must include the JAR files of the Java based product in either your CLASSPATH environment variable setting, or the -classpath (-cp) command-line argument. User-provided JAR files Previously, JAR files were installed in (/usr/tandem/java/jre/lib/ext) because you did not have to include such JAR files in the CLASSPATH. Starting with first version of NSJ4 (based on J2SESDK 1.4.
For invocation API users, build your own executable and link that executable against the JVM DLL. For migration considerations information, see “Calling Java methods from C or C++” (page 37). For a demo, see invocation API demo provided by NSJ7 in install_dir/demo/invocation_api. For more information, see “Linker and compiler options” (page 38). Floating-point support By default, NSJ 3.1.x and earlier versions converted any floating-point value that crossed the JNI boundary to a TNS float.
NonStop operating system does not provide support for windowing operations, NonStop Server for Java 3.1.x or earlier versions supported only those Abstract Windowing Toolkit (AWT) classes and methods that did not require a display, keyboard, sound, or mouse operation. Any class or method that required such an operation throws an UnsupportedClassException.
Miscellaneous changes for migration to TNS/E • “JNI_OnLoad and JNI_OnUnLoad functions” (page 96) • “Debugger” (page 96) • “dlfcn.h file” (page 96) JNI_OnLoad and JNI_OnUnLoad functions All applications migrating from TNS/R systems must change the JNI_OnLoad function. The format usage depends on the following system type: • On TNS/R systems, use the following command: JNI_OnLoad_libname where, libname is the name of the library that your program passed to the System.loadLibrary function.
Migrating from serial GC to parallel GC NSJ7 supports Parallel and CMS garbage collectors. Parallel and CMS GC provide reduced application pause time during GC when compared to Serial GC. In NSJ7, when the parallel and CMS GC is enabled using command line option, one process is launched for each GC thread. The Java and corresponding GC processes are called as process group and they perform the following: • Run on a same logical processor. • Run simultaneously on different IPU(s) of the same processor.
Using _RLD_FIRST_LIB_PATH NSJ7 does not support loading of a public DLL from a non-standard private location by using _RLD_FIRST_LIB_PATH environment variable. This limitation is due to the fact that NSJ7 creates a group of processes that should load the public DLLs at the same virtual memory address order, so that the parallel garbage collectors are functioned appropriately. This is unlike earlier versions of NSJ where the entire Java application is run as a single instance of JRE/JVM process.
Method 2: Using 64–bit JDK $ export PATH=/usr/tandem/nssjava/jdk170_h70/bin/oss64:$PATH $ run –name /G/JAVA1/ java HelloWorld NOTE: The 32–bit Java process created first in the Method 1 is a named process having name $JAVA1. This process uses execvp() system call to create the 64–bit Java process. A process created using execvp() does not inherit the name of the calling process, and hence the resultant 64–bit process is unnamed.
A Supported and unsupported features of NSJ7 NSJ7 includes all the features of NSJ6 and it is based on Java SE 7.0. For information about Java SE 7.0 features, see New Features and Enhancements Java SE 7.0 Java SE 7.0 features not implemented in NSJ7 Java SE 7.0 features that do not apply to a server-side HotSpot VM are not implemented in NSJ7. For information about Java SE 7.
B Addendum to HPjmeter 4.3 user's guide This appendix provides instructions for using the HPjmeter tool on NonStop system. It is based on the HP-UX HPjmeter 4.3 User's Guide, available at the following web address: www.hp.com/go/hpjmeter/. This version of HPjmeter supports 32–bit and 64–bit NSJ7. The following sections correspond to those in the HP-UX HPjmeter 4.
Configuring your application to use HPjmeter command—line options Preparing to run Java Complete the following steps to prepare the Java application to run with the JVM agent: • On NSJ7 and later SPRs, you must set the _RLD_LIB_PATH as follows: For 32–bit NSJ7: $JMETER_HOME/lib/oss32 For 64–bit NSJ7: $JMETER_HOME/lib/oss64 For versions earlier than NSJ7: $JMETER_HOME/lib/oss where, JMETER_HOME is set to /usr/tandem/hpjmeter.
Collecting profile data Profiling with —Xeprof Table 17 Supported –Xeprof options time_slice On NonStop Operating Systems, the time interval between the start and stop signals must be more than five minutes. This is because the Java thread switching process is slow due to the nonpreemptive nature of the NonStop Operating System. As a result, the asynchronous signals might be lost if they are posted to the NonStop Operating System Java process at very short intervals.
Troubleshooting Identifying version numbers Run the following commands to identify the version number for HPjmeter components: • nodeagent for NonStop vproc $JMETER_HOME/bin/nodeagent • JVM agent for pre-NSJ vproc $JMETER_HOME/lib/oss/libjmeter.so • JVM agent for 32–bit NSJ7 vproc $JMETER_HOME/lib/oss32/libjmeter.so • JVM agent for 64–bit NSJ7 vproc $JMETER_HOME/lib/oss64/libjmeter.
NOTE: • All instances of PROF in HPjmeter 4.3 User's Guide must be read as ALRM. • All instances of signal 21 must be read as 14. • The dynamic attach feature is not supported on NSJ7.
Glossary A Abstract Class In Java, a class designed only as a parent from which subclasses can be derived, which is not itself suitable for instantiation. An abstract class is often used to "abstract out" incomplete sets of features, which can then be shared by a group of sibling subclasses that add different variations of the missing pieces. Abstract Window Toolkit (AWT) The package that implements graphical user interfaces for Java. For more information, see Oracle AWT Home Page.
Common Gateway Interface (CGI) The World Wide Web standard interface for servers, often written in C. The NSJ7 supports CGI-like use of Java using servlets with iTP Secure WebServer. See also Pathway CGI. Common Object Request Broker Architecture (CORBA) The OMG standard that allows objects that adhere to it to interact over a network regardless of the types of machines or operating systems on which they reside. Java interoperates with this standard using Java IDL and JTS.
processors, Enscribe helps ensure data integrity if a processor module, I/O channel, or disk drive fails. Files on a NonStop system can be Enscribe files, SQL/MP tables, or SQL/MX tables. Enscribe files can be either structured or unstructured. Exception An event during program execution that prevents the program from continuing normally; generally, an error. Java methods raise exceptions using the throw keyword and handle exceptions using try, catch, and finally blocks.
HP NonStop Technical Library The browser-based interface to NonStop computing technical information. HP NonStop Transaction Management Facility (TMF) An HP product that provides transaction protection, database consistency, and database recovery. SQL statements issued through a JDBC driver against a NonStop SQL database call procedures in the TMF subsystem.
2. operating systems from the same vendor. HP documents often use the term connectivity in this context, while other vendors use connectivity to mean hardware compatibility. Within a NonStop system node, the ability to use the features or facilities of one environment from another. For example, the gtacl command in the OSS environment allows an interactive user to start and use a Guardian tool in the Guardian environment.
Java SE Runtime Environment (JRE) The Java virtual machine and the Core Packages. This is the standard Java environment that the java command invokes. Contrast with Java SE Development Kit (JDK). See also, Java Platform Standard Edition 7.0 (Java SE).
K-M Key 1. 2. A value used to identify a record in a database, derived by applying a fixed function to the record. The key is often simply one of the fields (a column if the database is considered as a table with records being rows). Alternatively, the key can be obtained by applying a function to one or more of the fields. A value that must be fed in the algorithm used to decode an encrypted message to reproduce the original plain text.
Old Generation (or Tenured Generation) In generational garbage collection, old or tenure generation is one of the generation in the Java Heap. The objects which are survived for threshold times (in scavenge or young generation) is promoted to old generation. OLTP See online transaction processing (OLTP). OMG See Object Management Group (OMG). Online Transaction Processing (OLTP) A method of processing transactions in which entered transactions are immediately applied to the database.
Private Key An encryption key that is not known to all parties. Protocol A set of formal rules for transmitting data, especially across a network. Low-level protocols define electrical and physical standards, bit-ordering, byte-ordering, and the transmission, error detection, and error correction of the bit stream. High-level protocols define data formatting, including the syntax of messages, the terminal-to-computer dialogue, character sets, sequencing of messages, and so on. Pthread A POSIX thread.
Shell The command interpreter used to pass commands to an operating system; the part of the operating system that is an interface to the outside world. SIP See Scalable TCP/IP (SIP). Skeleton In RMI, the complement of the stub. Together, skeletons and stubs form the interface between the RMI services and the code that calls and implements remote objects. Socket A logical connection between two application programs across a TCP/IP network. SQL/MP See HP NonStop SQL/MP.
Transmission Control Protocol/Internet Protocol (TCP/IP) One of the most widely available nonvendor-specific protocols, designed to support large, heterogeneous networks of systems. TS/MP See HP NonStop TS/MP. U-Z -Xeprof Java application profile collection option. -Xeverbosegc Java application's Garbage Collector (GC) activity profile collection option. Unicode A character-coding scheme designed to be an extension of ASCII.
Index A Application Profiling, 86 -Xeprof versus -agentlib:hprof (HPROF), 88 Analyzing Garbage Collection Data, 88 Collecting profile data for analysis, 87 Monitoring live NSJ7 Java applications, 86 ARGLIST, 32 C Class Data Sharing, 34 Configuring a Java Pathway Serverclass, 32 E ENV, 32 G Getting Started, 30 I Implementation Specifics, 34 -Dnsk.java.
JDK, 15 JNDI, 16 NonStop Server for Java 7.
