NonStop JMS User's Manual (H06.03+, J06.03+, NonStop JMS 3.0+)

ManualsBrandsHP ManualsServerHP NonStop G-Series

NonStop Server for

Java Message Service

User’s Manual

Abstract

NonStop Server for Java™ Message Service (NSJMS) is an implementation of Sun

Microsystems Java™ Message Service (JMS) API on HP NonStop™ S-series systems

and HP Integrity NonStop NS-series systems. NSJMS utilizes the performance and

reliability inherent in HP NonStop SQL/MX products to provide standards-based

messaging for JMS clients running on HP NonStop servers. It is assumed the reader is

already familiar with Sun Microsystems published specification, Java Message Service,

Version 1.0.2.

As part of U64 program, a new 64-bit dll (libnsjms_64.so) is included in addition to

the existing 32-bit dll (libnsjms.so)

Product Version

NSJMS 3.0

Supported Release Version Updates (RVUs)

This publication supports G06.18 and all subsequent G-series RVUs and H06.03 and

all subsequent H-series RVUs until otherwise indicated by its replacement publication.

The U64 program support is present from H06.25.00 and all subsequent H-series

RVUs unless otherwise indicated by its replacement publication. U64 program does

not support G-series RVUs.

Summary of content (161 pages)

PAGE 1
NonStop Server for Java Message Service User’s Manual Abstract NonStop Server for Java™ Message Service (NSJMS) is an implementation of Sun Microsystems Java™ Message Service (JMS) API on HP NonStop™ S-series systems and HP Integrity NonStop NS-series systems. NSJMS utilizes the performance and reliability inherent in HP NonStop SQL/MX products to provide standards-based messaging for JMS clients running on HP NonStop servers.
PAGE 2
Part Number Published 522356-006 February 2013
PAGE 3
Document History Part Number Product Version Published 522356-001 NSJMS 1.0 April 2002 522356-002 NSJMS 2.0 April 2003 522356-003 NSJMS 3.0 November 2003 522356-004 NSJMS 3.0 April 2005 522356-005 NSJMS 3.0 June 2011 522356-006 NSJMS 3.
PAGE 4
PAGE 5
Legal Notices  Copyright 2013 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.
PAGE 6
PAGE 7
NonStop Server for Java Message Service User’s Manual Glossary Index What’s New in This Manual Manual Information v New and Changed Information Examples Figures v About This Manual vii Overview vii Who Should Use This Manual vii How This Manual Is Organized vii Related Manuals vii Notation Conventions viii 1.
PAGE 8
2. NSJMS Installation and Configuration for TNS/R Contents 2.
PAGE 9
4. NSJMS and JMS Client Applications (continued) Contents 4. NSJMS and JMS Client Applications (continued) Sending Messages 4-7 Specifying a Destination 4-7 Destination Names 4-8 Temporary Destinations 4-8 Destination IDs 4-8 Persistence 4-8 Priority 4-9 Receiving Messages 4-9 No-Local 4-11 Using Message Listeners 4-11 Best Practices for Developing a JMS Client Threading 4-15 Message Expiration Values 4-16 4-12 5.
PAGE 10
6. NSJMS Administrative Servlet Installation and Configuration Contents 6.
PAGE 11
What’s New in This Manual Manual Information NonStop Server for Java Message Service User’s Manual Abstract NonStop Server for Java™ Message Service (NSJMS) is an implementation of Sun Microsystems Java™ Message Service (JMS) API on HP NonStop™ S-series systems and HP Integrity NonStop NS-series systems. NSJMS utilizes the performance and reliability inherent in HP NonStop SQL/MX products to provide standards-based messaging for JMS clients running on HP NonStop servers.
PAGE 12
What’s New in This Manual New and Changed Information Updated these for NonStop NS-series system/server:         NSJMS System Requirements on page 3-1 NSJMS Installation Procedure on page 3-1 Item 2 in Before You Begin the Installation on page 3-2 Run the IPSetup Program on page 3-2 Step 2 in Use DSM/SCM to Place the Product Files in /usr/tandem on page 3-4 Steps 2 and 6 in Use DSM/SCM and PINSTALL to Place the Product Files in a User-Specified Installation Directory on page 3-4 Step 2 in Use CO
PAGE 13
About This Manual Overview This manual explains how to install, operate, and manage NSJMS on HP NonStop systems. Who Should Use This Manual This manual is written for anyone who installs, manages, or monitors NSJMS on NonStop servers. It is assumed the reader is already familiar with Sun Microsystems published specification, Java Message Service, Version 1.0.2b, August 27, 2001. How This Manual Is Organized Section Title This section... 1 Introduction to NSJMS provides an overview of NSJMS.
PAGE 14
Notation Conventions About This Manual     iTP Secure WebServer System Administrator’s Guide NonStop NS-Series Planning Guide Open System Services User’s Guide NonStop Server for Java Programmer’s Reference 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: This requirement is described under NSJMS System Requirements on page 2-1.
PAGE 15
General Syntax Notation About This Manual 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 { } Braces. A group of items enclosed in braces is a list from which you are required to choose one item. The items in the list can be arranged either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines.
PAGE 16
Notation for Messages About This Manual 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 ]… !i and !o.
PAGE 17
Notation for Messages About This Manual Nonitalic text. Nonitalic letters, numbers, and punctuation indicate text that is displayed or returned exactly as shown. For example: Backup Up. lowercase italic letters. Lowercase italic letters indicate variable items whose values are displayed or returned. For example: p-register process-name [ ] Brackets. Brackets enclose items that are sometimes, but not always, displayed.
PAGE 18
Change Bar Notation About This Manual Change Bar Notation Change bars are used to indicate substantive differences between this manual and its preceding version. 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 COBOL environment and the Common Run-Time Environment (CRE).
PAGE 19
1 Introduction to NSJMS NSJMS is the JMS provider that implements Sun Microsystems JMS API, version 1.0.2, on NonStop systems. NSJMS uses the performance and reliability inherent in SQL/MX products to provide standards-based messaging for local clients running on NonStop servers. NSJMS enables scalability and load distribution through horizontal partitioning and fault-tolerance through process-pair technology. Features and Functions of NSJMS        Implements the JMS API on NonStop systems.
PAGE 20
JMS Client Introduction to NSJMS Figure 1-1. NSJMS Client Messaging on a NonStop System JMS Client JMS API JNDI API JNDI Provider NSJMS SQL/MX DP2 DP2 DP2 Tables Tables Tables VST001.vsd JMS Client A JMS client is a user-written application that uses NSJMS to exchange messages with other JMS client applications. JMS API The Java JMS API provides a generic set of interfaces that enables JMS clients to exchange messages.
PAGE 21
SQL/MX Introduction to NSJMS SQL/MX SQL/MX is the HP relational database management system that provides access to large distributed databases. JMS clients use SQL/MX to access messages and information stored in NSJMS SQL databases. Administrative Utility Components The administrative utility is a Java-based tool used to manage the NSJMS database. The component parts that access and maintain the NSJMS database are shown in Figure 1-2.
PAGE 22
Introduction to NSJMS SQL/MX SQL/MX SQL/MX is the HP relational database management system that provides access to large distributed databases. JMS clients use SQL/MX to access messages and information stored in NSJMS SQL databases. JNDI API The JNDI API provides a generic set of interfaces that enables the administrative utility to access naming and directory services. JNDI Provider The JNDI provider implements the naming and directory services. Supported Platform This publication supports H06.25.
PAGE 23
2 NSJMS Installation and Configuration for TNS/R NSJMS System Requirements Hardware HP NonStop S-series server Software When Running NonStop Server for Java (T0083V31) Caution. Every time you install a new version of the HP NonStop Server for Java (NSJ), you must run the NSJ Makefile to bind the NSJMS libraries with the Java Virtual Machine (JVM). See the NonStop Server for Java Programmer’s Reference for additional information. HP NonStop operating system (T9050G06), G06.
PAGE 24
NSJMS Installation and Configuration for TNS/R Minimum Disk Space NonStop OSS (T8620D40) NonStop Server for Java (T2766V10 or later) NonStop SQL/MX (T1050G08 PVU AAI or later) NonStop SQL/MX EXE (T1051G08 PVU AAI or later) NonStop SQL/MP (T9095G07) JDBC/MX (T1225V30) JDBC/MP (T1227V30) Java Naming and Directory Interface (JNDI) 1.2.1 FS Context Service Provider WARNING. The JNDI 1.2.1 FS Context Service Provider from Sun Microsystems Java Naming and Directory Interface (JNDI) Web site (http://java.sun.
PAGE 25
NSJMS Installation and Configuration for TNS/R  Run the IPSetup Program Determine whether you will use DSM/SCM to move files to Installation Subvolumes (ISVs) after files are placed on your workstation. For additional information about using DSM/SCM, see the DSM/SCM User’s Guide. Note. Using DSM/SCM is optional for G06.18 or later RVUs, but is recommended. Run the IPSetup Program Use the IPSetup program to place the NSJMS components on your host NonStop S-series server.
PAGE 26
NSJMS Installation and Configuration for TNS/R Unpax the NSJMS Product Files 8. On the Host File Placement screen you can either accept the default disk locations or browse to locations of your choice. Click Next when you are satisfied with the locations. 9. On the Placement Manifest screen review the file locations. You can click Back to go back and change the file locations. When you are satisfied with the locations, click Next. This step can take a few minutes to complete. 10.
PAGE 27
NSJMS Installation and Configuration for TNS/R Unpax the NSJMS Product Files 5. Run ZPHIRNM to perform the RENAME step. Note. If the option Manage OSS Files was not selected in the DSM/SCM planner interface in Step 2 above, the NSJMS PAX file is in the Guardian subvolume $ISV.ZOSSUTL (where ISV is the name of your installation subvolume). Use COPYOSS to extract and place the contents of the NSJMS PAX file into the OSS file system. (Go to Use COPYOSS to Place the Product Files in /usr/tandem on page 2-6).
PAGE 28
NSJMS Installation and Configuration for TNS/R Install and Configure NSJMS install-dir is the user-specified installation directory and version is the vproc of this release (for example, T1251V30_30SEP2003_V30). Note. Running the PINSTALL command does not affect any environment currently running on your NonStop S-series server. 7. Go to Install and Configure NSJMS on page 2-6 for detailed instructions about running the install script and configuring NSJMS.
PAGE 29
NSJMS Installation and Configuration for TNS/R Install and Configure NSJMS For example: TACL> LOGON SUPER.SUPER TACL> OSH OSH: cd /usr/tandem/nsjms/version OSH: chmod u+x install OSH: ./install Note. Run the installation script only once after you unpax the NSJMS product files into the version-specific OSS directory. Run the installation script a second time only when you reinstall the T1251 NSJMS libraries or class files. After running the installation script:   The nsjms.
PAGE 30
Install and Configure NSJMS NSJMS Installation and Configuration for TNS/R For example:  If NonStop Server for Java (T0083V31) is installed use these commands: OSH: cd /usr/tandem/nssjava/version/bin/oss/posix_threads OSH: vproc java where version is the vproc of this JVM release (for example, jdk131_v10)  If NonStop Server for Java (T2766V10) is installed use these commands: OSH: cd /usr/tandem/nssjava/version/bin OSH: vproc java where version is the vproc of this JVM release (for example, jdk1
PAGE 31
NSJMS Installation and Configuration for TNS/R Install and Configure NSJMS volume.subvol of the existing or newly created SQL catalog specified in Step 7 on page 2-8. For example: Change: VOLUME; To: VOLUME $volume.
PAGE 32
NSJMS Installation and Configuration for TNS/R Install and Configure NSJMS editor of your choice, update the java.naming.provider.url property in the jndi.properties file with the path for the new directory. The jndi.properties file is described on page 2-15 and contains values that are necessary to use a simple JNDI file service provider on the operating system. The nsjms.properties file and the jndi.properties file contain default key and value combinations and require few or no changes. Note. nsjms.
PAGE 33
Install and Configure NSJMS NSJMS Installation and Configuration for TNS/R a.
PAGE 34
NSJMS Installation and Configuration for TNS/R NSJMS Directory Structure NSJMS Directory Structure After completing the product installation, the /usr/tandem/nsjms/version directory contains the following files and subdirectories. Included are detailed descriptions of the properties contained in the nsjms.properties file and the jndi.properties file:  nsjms.properties – Contains these properties that are used to configure NSJMS: Note.
PAGE 35
NSJMS Installation and Configuration for TNS/R   NSJMS Directory Structure Database.volsubvol Default: vol.subvol Values: vol.subvol Value Description: vol.subvol—The volume and subvolume of the database tables. Example: Database.volsubvol=$data01.nsjms Deadmsg.
PAGE 36
NSJMS Installation and Configuration for TNS/R  NSJMS Directory Structure Logger.loglevel Default: warning Values: fatal | error | exception | warning | info | debug Value Descriptions: fatal—Logs a fatal message that leads to abnormal termination. error—Logs messages that do not necessarily lead to abnormal termination but still should be noted, such as a message about an incorrect configuration parameter.
PAGE 37
NSJMS Installation and Configuration for TNS/R  NSJMS Directory Structure Servlet.xmlvalidate Default: false Values: true | false Value Description: true—Specifies that validation is performed on the administrative servlet XML request and reply using a DTD. false—Specifies that no validation is performed on the administrative servlet XML administrative request and reply using a DTD. Example:  Servlet.xmlvalidation=false Stats.
PAGE 38
NSJMS Installation and Configuration for TNS/R           NSJMS Directory Structure Java.naming.factory.initial Default: com.sun.jndi.fscontext.RefFSContextFactory Value: com.sun.jndi.fscontext.RefFSContextFactory Value Description: com.sun.jndi.fscontext.RefFSContextFactory specifies the JNDI initial context to be the file system. Example: java.naming.factory.initial=com.sun.jndi. fscontext.RefFSContextFactory Java.naming.provider.
PAGE 39
NSJMS Installation and Configuration for TNS/R   SQL/MP Table Partitioning /examples – Contains  SimpleSender.java. This sample program sends simple messages to a queue.  SimpleReceiver.java. This sample program receives simple messages from a queue.  SimplePublisher.java. This sample program publishes simple messages to a topic.  SimpleConsumer.java. This sample program subscribes and consumes messages from a topic.  JmsAdminServlet.html.
PAGE 40
NSJMS Installation and Configuration for TNS/R Adding a Message-Table Dummy Record After completion of the previous SQLCI ALTER TABLE command, the table has two partitions that have these starting destination ID values: Partition Location Starting Destination ID $VOL1 0 $VOL2 10000 An existing partition within a message table that has three partitions is split.
PAGE 41
NSJMS Installation and Configuration for TNS/R Overflow Table Partitioning The creatsql file that is provided with NSJMS includes this command to insert a dummy record that has a destination ID value of 0. SQLCI>> INSERT INTO MESSAGE VALUES (0, 0, 1000000000000000000,0,''); The destination ID value of 0 is never assigned as a destination.
PAGE 42
NSJMS Installation and Configuration for TNS/R Uninstall Cleanup Steps b. Delete the iTP Secure WebServer NSJMS directory by using these commands: OSH: cd /usr/tandem/webserver/samples/Servlets OSH: rm nsjms c. Restart the iTPSecure WebServer by using these commands: OSH: cd /usr/tandem/webserver/conf OSH: ./restart Uninstall Cleanup Steps After uninstalling NSJMS, you can optionally perform these cleanup steps to remove the version-specific NSJMS SQL tables and the NSJMS install directory: 1.
PAGE 43
3 NSJMS Installation and Configuration for TNS/E NSJMS System Requirements Hardware HP NonStop NS-series server Software When Running NonStop Server for Java (T2766H10) HP NonStop operating system (T9050H01) NonStop OSS (T8620H01) NonStop Server for Java (T2766H70) NonStop SQL/MX (T1050H32) NonStop SQL/MX EXE (T1051H32) NonStop SQL/MP (TXXXXXXX) JDBC/MX (T1275H32) Java Naming and Directory Interface (JNDI) 1.2.1 FS Context Service Provider WARNING. The JNDI 1.2.
PAGE 44
NSJMS Installation and Configuration for TNS/E Before You Begin the Installation The following installation instructions are correct as of the time this manual was published; however, the README.TXT file or Softdoc supersedes the information here. Before You Begin the Installation  Check that you have downloaded and extracted FS Context Service Provider on to your workstation from the Sun Microsystems’ JNDI web site (http://java.sun.com/products/jndi/index.html).
PAGE 45
NSJMS Installation and Configuration for TNS/E Unpax the NSJMS Product Files 3. Click the IPSetup button to launch IPSetup. The program displays a Welcome Screen and a License Agreement screen. To continue the installation, click Next on each of these screens. 4. On the Placement Options screen select the NonStop Kernel RISC option.  If you plan on using DSM/SCM, check the box for “Use DSM/SCM to complete installation on host.” Click Next.
PAGE 46
NSJMS Installation and Configuration for TNS/E Unpax the NSJMS Product Files Use DSM/SCM to Place the Product Files in /usr/tandem If you use DSM/SCM, this process will unpax the NSJMS PAX file, T1251PAX, in the standard OSS location, that is, in /usr/tandem. For additional information about using DSM/SCM, see the DSM/SCM User’s Guide. 1. RECEIVE the product files from disk (DSV locations) or tape. 2. Check the Manage OSS Files option for the target configuration within the DSM/SCM Planner Interface.
PAGE 47
NSJMS Installation and Configuration for TNS/E Unpax the NSJMS Product Files 5. Run ZPHIRNM to perform the RENAME step. 6. Use PINSTALL to unpax the NSJMS PAX file into the OSS file system. a. On your NonStop NS-series server, log on as Super.Super: TACL> LOGON SUPER.SUPER b. Navigate to the Guardian subvolume $ISV.ZOSSUTL: TACL> VOLUME $ISV.ZOSSUTL where ISV is the name of your installation subvolume. c.
PAGE 48
NSJMS Installation and Configuration for TNS/E Install and Configure NSJMS COPYOSS extracts the files contained in T1251PAX and places them in the version-specific OSS directory /usr/tandem/nsjms/version, where version for this RVU is: (for example, T1251H10_30MAY2005_H10). Note. Running the copyoss command does not affect any environment currently running on your NonStop NS-series server. 3.
PAGE 49
NSJMS Installation and Configuration for TNS/E If T2766H10 OSH: export OSH: export OSH: export OSH: export OSH: export Install and Configure NSJMS is installed in a non-standard location: JAVA_HOME=//java JREHOME=$JAVA_HOME/jre CLASSPATH=$NSJMS_HOME:$NSJMS_HOME/examples:$CLASSPATH CLASSPATH=`echo $NSJMS_HOME/lib/*.jar | tr ' ' ':'`:$CLASSPATH _RLD_LIB_PATH=$NSJMS_HOME/lib 6. Verify that you have access to an existing SQL catalog, or create a new catalog.
PAGE 50
NSJMS Installation and Configuration for TNS/E Install and Configure NSJMS Note. Database tables, by default, support a maximum of 2 gigabytes (GB) on each partition. If larger partitions are required, use the FORMAT2ENABLED attribute when creating the tables. For information about using the FORMAT2ENABLED attribute within the CREATE TABLE statement, see the SQL/MP Reference Manual. 9. Update the Property Files: a. Using an editor of your choice, update these properties in the nsjms.properties file: 1.
PAGE 51
NSJMS Installation and Configuration for TNS/E Install and Configure NSJMS 11. Compile the sample programs by using these commands. The sample programs use the JNDI object store and destinations created in Step 10 on page 3-8: OSH: cd examples OSH: javac *.java 12. Test the sample programs: You will need two OSS shells to test each sample program. Note. Before testing each sample program, set the NSJMS_HOME variable and the CLASSPATH variable in each shell; see Step 4 on page 3-6 and Step 5 on page 3-6.
PAGE 52
NSJMS Directory Structure NSJMS Installation and Configuration for TNS/E OSH: OSH: OSH: OSH: OSH: OSH: OSH: OSH: cd examples java SimpleSender -queue Q1 -count 5 Publishing: Sending message 0 Publishing: Sending message 1 Publishing: Sending message 2 Publishing: Sending message 3 Publishing: Sending message 4 Finished Publishing 5 messages b.
PAGE 53
NSJMS Installation and Configuration for TNS/E     NSJMS Directory Structure Database.delay Default: 1000 Values: milliseconds Value Description: milliseconds—The time (in milliseconds) that the thread delays after a stream timeout occurs. Example: Database.delay=1000 Database.tabletimeout Default: 3000 Values: milliseconds Value Descriptions: milliseconds—The time (in milliseconds) for a table lock timeout.
PAGE 54
NSJMS Installation and Configuration for TNS/E  NSJMS Directory Structure Deadmsg.deletecount Default: 0 Values: 0 through 5000 Value Description: Dead messages are messages in topics which have been read by all existing subscribers of the topic (including durable subscribers), and are therefore unusable to any subscriber. The messages are deleted periodically as part of the regular receive process. The frequency of deletion is determined by the delete-count value.
PAGE 55
NSJMS Installation and Configuration for TNS/E  NSJMS Directory Structure Logger.loglevel Default: warning Values: fatal | error | exception | warning | info | debug Value Descriptions: fatal—Logs a fatal message that leads to abnormal termination. error—Logs messages that do not necessarily lead to abnormal termination but still should be noted, such as a message about an incorrect configuration parameter.
PAGE 56
NSJMS Installation and Configuration for TNS/E  NSJMS Directory Structure Servlet.xmlvalidate Default: false Values: true | false Value Description: true—Specifies that validation is performed on the administrative servlet XML request and reply using a DTD. false—Specifies that no validation is performed on the administrative servlet XML administrative request and reply using a DTD. Example:  Servlet.xmlvalidation=false Stats.
PAGE 57
NSJMS Installation and Configuration for TNS/E          NSJMS Directory Structure Java.naming.factory.initial Default: com.sun.jndi.fscontext.RefFSContextFactory Value: com.sun.jndi.fscontext.RefFSContextFactory Value Description: com.sun.jndi.fscontext.RefFSContextFactory specifies the JNDI initial context to be the file system. Example: java.naming.factory.initial=com.sun.jndi. fscontext.RefFSContextFactory Java.naming.provider.
PAGE 58
NSJMS Installation and Configuration for TNS/E   SQL/MP Table Partitioning /examples – Contains  SimpleSender.java. This sample program sends simple messages to a queue.  SimpleReceiver.java. This sample program receives simple messages from a queue.  SimplePublisher.java. This sample program publishes simple messages to a topic.  SimpleConsumer.java. This sample program subscribes and consumes messages from a topic.  JmsAdminServlet.html.
PAGE 59
NSJMS Installation and Configuration for TNS/E Adding a Message-Table Dummy Record After completion of the previous SQLCI ALTER TABLE command, the table has two partitions that have these starting destination ID values: Partition Location Starting Destination ID $VOL1 0 $VOL2 10000 An existing partition within a message table that has three partitions is split.
PAGE 60
NSJMS Installation and Configuration for TNS/E Overflow Table Partitioning The creatsql file that is provided with NSJMS includes this command to insert a dummy record that has a destination ID value of 0. SQLCI>> INSERT INTO MESSAGE VALUES (0, 0, 1000000000000000000,0,''); The destination ID value of 0 is never assigned as a destination.
PAGE 61
4 NSJMS and JMS Client Applications This section provides an overview of the JMS model, describes NSJMS administered objects, and provides information about the common tasks performed by JMS client applications including information about how NSJMS implements the JMS interfaces when performing the tasks. The JMS Model This defines an abstract view of a messaging service but does not define an implementation. The JMS model is based on a set of generic interfaces that are defined in Sun’s javax.jms package.
PAGE 62
NSJMS and JMS Client Applications Administered Objects The generic JMS interfaces are further defined within the PTP messaging application as: Queue Interfaces Description QueueConnection Provides an active connection to NSJMS that is used to create one or more QueueSessions. QueueSession Provides methods for creating QueueSender’s and QueueReceiver’s. QueueSender Used to send messages to a queue. QueueReceiver Used to receive messages that have been delivered to a queue.
PAGE 63
Writing JMS Client Applications NSJMS and JMS Client Applications JMS clients use administered objects to create connections to NSJMS and to specify the destinations for messages. All NSJMS-specific information is contained in implementations of these NSJMS administered objects: NSJMS Administered Objects Description QueueConnectionFactory Used within a PTP messaging application by JMS clients for creating connections to NSJMS.
PAGE 64
NSJMS and JMS Client Applications Creating a Connection Creating a Connection A JMS client uses a ConnectionFactory object to create a connection with NSJMS. To create a connection between a JMS client and NSJMS:      Create an Initial Context on page 4-4 Retrieve the Connection Factory on page 4-4 Use the Factory Object to Create a Connection on page 4-5 Start the Connection on page 4-5 Create a Session on page 4-5. Note. At this time, no interoperability exists among the JMS providers.
PAGE 65
NSJMS and JMS Client Applications Creating a Connection Create Connection Factories at Runtime You can, optionally, create ConnectionFactory objects at runtime. However, this requires references to NSJMS specific classes that will reduce the portability of the JMS application. This code fragment creates a QueueConnectionFactory with the default settings: QueueConnectionFactory factory= com.tandem.nsjms.client.
PAGE 66
NSJMS and JMS Client Applications Transactions Both the createQueueSession() method and the createTopicSession() method accept a boolean parameter that specifies whether the session is transacted. Transactions NSJMS supports transacted sessions and external transactions. Transacted sessions allow you to send and receive multiple messages in a single transaction that is local to the session.
PAGE 67
NSJMS and JMS Client Applications Sending Messages Sending Messages A JMS client uses a MessageProducer to send messages to a specified destination. A message producer is an object created by a session that is used by JMS clients to send messages to queues or topics. The PTP messaging application uses the QueueSender interface as its message producer, and the Pub/Sub messaging application uses the TopicPublisher interface as its message producer.
PAGE 68
NSJMS and JMS Client Applications Destination Names Destination Names Queue names and topic names are Java letters and Java digits, limited to 100 bytes, where the first character is a Java letter. This syntax also describes subscription names and client IDs. Temporary Destinations JMS allows for the creation of temporary queues and topics that exist only for the duration of a JMS connection.
PAGE 69
NSJMS and JMS Client Applications Priority Priority JMS allows message priority to be set by the setPriority() method on the MessageProducer object and retrieved using the getPriority() method on the MessageConsumer object. Although NSJMS allows message priority to be set and retrieved, this priority does not affect message-delivery order. Receiving Messages A JMS client uses a MessageConsumer to receive messages from a specified destination.
PAGE 70
NSJMS and JMS Client Applications Receiving Messages This code fragment shows the use of instanceof when pulling the contents from a TextMessage: if (inMessage instanceof TextMessage){ String replyString =((TextMessage)inMessage).getText(); . . . } else { System.out.println("Reply message was not a TextMessage"); } Receiving Messages from a Topic To receive a message from a topic, you create a TopicSubscriber using the createSubscriber() method.
PAGE 71
NSJMS and JMS Client Applications Receiving Messages This method is similar to creating a non-durable subscriber, except that you must pass a subscription name to identify the unique subscriber. For example: TopicSubscriber subscriber= session.createDurableSubscriber(topic,MY_SUB_01); The subscriber becomes active after you start the TopicConnection. Later on, the TopicSubscriber can be closed by calling the close() method of TopicSubscriber object. For example, subscriber.
PAGE 72
NSJMS and JMS Client Applications No-Local No-Local You can ignore messages that are sent or published on the subscriber’s own connection by setting the third parameter of the createSubscriber() method to true. This code fragment causes messages published on the subscriber’s connection to be ignored: TopicSubscriber sub = session.
PAGE 73
NSJMS and JMS Client Applications Best Practices for Developing a JMS Client This code fragment creates a message listener for a topic: import javax.jms.*; public class MyClass implements MessageListener { public void onMessage(Message message) { System.out.println("The message is "+message); . . . } } . . . MyClass listener =new MyClass(); topicSubscriber.setMessageListener(listener); Best Practices for Developing a JMS Client You should use caution when creating active connections to NSJMS.
PAGE 74
NSJMS and JMS Client Applications Best Practices for Developing a JMS Client Topic Publisher/Subscriber Sample Setup (Recommended) This is a sample of the recommended setup process in which the setup steps are performed only once: TopicConnectionFactory factory = TopicConnectionFactory) jndiContext.lookup("TopicConnectionFactory"); TopicConnection connection = factory.createTopicConnection(); TopicSession sessionSub = connection.createTopicSession(true, Session.
PAGE 75
NSJMS and JMS Client Applications Best Practices for Developing a JMS Client Topic Publisher/Subscriber Sample Setup (Not Recommended) This is a sample of a setup process that is not recommended for use because the setup steps are repeated with each message: TopicConnectionFactory factory = (TopicConnectionFactory) jndiContext.lookup("TopicConnectionFactory"); TopicConnection connection = factory.createTopicConnection(); TopicSession sessionSub = connection.createTopicSession(true, Session.
PAGE 76
NSJMS and JMS Client Applications Threading Threading You can use JMS with multithreaded Java applications. Although threading is supported, the send calls block the process during send operations and the receive calls support the non-blocking features of SQL/MX during receive operations when sqlmx_nowait is set to on. Two NSJMS property values specify the threading behavior. The Database.
PAGE 77
NSJMS and JMS Client Applications Message Expiration Values timeout value can improve performance because the SQL operation is stopped and restarted less frequently while awaiting a message; the longer timeout does not block the process since other threads run during the time spent waiting for the message. Message Expiration Values You can change the default expiration value for a message sent to a destination by specifying a value for the expiry attribute in the ADD command.
PAGE 78
NSJMS and JMS Client Applications Message Expiration Values NonStop Server for Java Message Service User’s Manual—522356-006 4-18
PAGE 79
5 Reliable Messaging Bridge Introduction The reliable messaging bridge is hosted on the NonStop platform and sits between a locally hosted JMS client library from a foreign JMS provider and the NSJMS JMS API. Using the standard Sun Microsystems JMS API, the reliable messaging bridge reads from a locally hosted foreign JMS provider and writes to NSJMS, or reads from NSJMS and writes to a locally hosted foreign JMS provider.
PAGE 80
Configure a Reliable Messaging Bridge Reliable Messaging Bridge Figure 5-1. Reliable Messaging Bridge Foreign Platform Foreign JMS Protocol HP NonStop Server JMS Server JMS Client API Application bridges.properties bridges.properties destinations.properties destinations.properties Pathmon start_template.txt start_template.txt stop_template.txt stop_template.txt ServerClass Foreign JMS Protocol JMS Client API NSJMS Bridge Foreign Platform NSJMS API btool.
PAGE 81
Reliable Messaging Bridge Setting the Environment Variables JAVA_HOME Environment Variable Use the export command to set the JAVA_HOME variable. For example: OSH: cd /usr/tandem/nsjms/version/bridge OSH: export JAVA_HOME=/usr/tandem/java where version is the vproc of this RVU (for example, T1251V30_30SEP2003_V30). NSJMS_HOME Environment Variable Use the export command to set the NSJMS_HOME variable.
PAGE 82
Reliable Messaging Bridge Setting the Environment Variables Example 5-1. Modifying the btool.sh Script to Include Foreign-Provider Client Jar Files #!/bin/sh # Script for starting the NSJMS bridge configuration tool # # # Copyright 2003 # Hewlett Packard Development Company, L.P. # Protected as an unpublished work. # All rights reserved.
PAGE 83
Reliable Messaging Bridge Run the btool.sh Script Run the btool.sh Script From within the OSS Shell (OSH), run the btool.sh script located in the /usr/tandem/nsjms/version/bridge directory. Successful completion of the btool.sh script will start the configuration tool. For example, run the btool.sh script as: OSH: /usr/tandem/nsjms/version/bridge: btool.sh java -classpath /usr/tandem/nsjms/bridge:/usr/tandem/nsjms /T1251V30_30SEP2003_V30/lib/nsjms.jar:/usr/tandem/nsjms/T1251V30_30SEP 2003_V30/lib/jndi.
PAGE 84
Using the Configuration Tool Reliable Messaging Bridge Add a Destination The add dest command defines a destination and generates the destinations.properties file. Add Destination Command Prompts The add dest command steps through these command prompts. At each prompt, enter the appropriate value or press Enter to proceed to the next prompt. If a value appears in brackets ([ ]) at a prompt, for example, Store queue0 [N]: pressing Enter without entering a new value will select the value in the brackets.
PAGE 85
Using the Configuration Tool Reliable Messaging Bridge Alter a Destination The alter dest command alters the configured properties for an existing destination and updates the destinations.properties file with the newly configured properties. Caution. If you alter the configured properties of a destination that is in use by a bridge, you must update the bridge pathway configuration using the alter bridge command. Alter Destination Command Prompts The alter dest command steps through these command prompts.
PAGE 86
Using the Configuration Tool Reliable Messaging Bridge Example An example of using the configuration tool to alter the JNDI Destination Name from queue0 to queue99 is shown below. Bold text indicates user input. NSJMS Messaging Bridge Configuration Tool Copyright 2003 Hewlett Packard Development Company, L.P. command: alter dest Destination Name: queue0 Destination Type [queue]: JNDI Initial Context Factory [com.sun.jndi.fscontext.
PAGE 87
Using the Configuration Tool Reliable Messaging Bridge Example An example of using the configuration tool to delete the destination named queue0 from the destinations.properties file is shown below. Bold text indicates user input. NSJMS Messaging Bridge Configuration Tool Copyright 2003 Hewlett Packard Development Company, L.P.
PAGE 88
Using the Configuration Tool Reliable Messaging Bridge Example An example of using the configuration tool to request information for all configured destinations, Destination Name: *, is shown below. Bold text indicates user input. NSJMS Messaging Bridge Configuration Tool Copyright 2003 Hewlett Packard Development Company, L.P. command: info dest Destination Name: * Info for - queue0 DestinationType=queue JndiInitialContextFactory=com.sun.jndi.fscontext.
PAGE 89
Using the Configuration Tool Reliable Messaging Bridge Prompt Usage (page 2 of 3) Database vol/subvol: Required. Must follow the same form as the nsjms.properties Database.volsubvol name/value pair. See Database.volsubvol on page 2-13. NOTE: This property is global to the Pathmon Process Name and any changes to the name/value pair will be implemented across every server class running under the Pathmon Process Name. For information on changing the Database.
PAGE 90
Using the Configuration Tool Reliable Messaging Bridge Prompt Usage (page 3 of 3) Number of Servers: Required. The default is one. For queues, the number of servers may be greater than one. For topics, the number of servers must be one. This property is local to the specific Pathway server class. Store Pathmon_Process_Name._Path wayServer_Class_Name: Enter y to save the bridge configuration. Enter n to leave the task without adding the bridge.
PAGE 91
Using the Configuration Tool Reliable Messaging Bridge Alter Bridge Command Prompts The alter bridge command steps through these command prompts. At each prompt, enter the appropriate value or press Enter to proceed to the next prompt. Pressing Enter without entering a new value will select the value, if any, which appears in brackets ([ ]) at each prompt. For example, Pathway Server Class Name [qtoq]:. Prompt Usage (page 1 of 2) Pathmon Process Name: Required.
PAGE 92
Using the Configuration Tool Reliable Messaging Bridge Prompt Usage (page 2 of 2) Selector: Optional. A JMS selector. The default is “” (null), This property is local to the specified Pathway Server Class and any change to the name/value combination will only be implemented within the specified Pathway Server Class. Batch Size: Optional. The number of messages to transfer in each transaction. The default is one.
PAGE 93
Using the Configuration Tool Reliable Messaging Bridge Example An example of using the configuration tool to alter the batch size in the range 1 through 10 is shown below. Bold text indicates user input. NSJMS Messaging Bridge Configuration Tool Copyright 2003 Hewlett Packard Development Company, L.P. command: alter bridge Pathmon Process Name [sampl]: Pathway Server Class Name [qtoq]: Database vol/subvol [$myvol.
PAGE 94
Using the Configuration Tool Reliable Messaging Bridge Example An example of using the configuration tool to delete the bridge named sampl.qtoq is shown below. Bold text indicates user input. NSJMS Messaging Bridge Configuration Tool Copyright 2003 Hewlett Packard Development Company, L.P. command: delete bridge Pathmon Process Name [sampl]: Pathway Server Class Name [qtoq]: Delete sampl.qtoq [N]: y Generating start_sampl script Generating sampl.
PAGE 95
Reliable Messaging Bridge Using the Configuration Tool Examples An example of using the configuration tool to request information about a specific bridge, sampl.qtoq, is shown below. Bold text indicates user input. NSJMS Messaging Bridge Configuration Tool Copyright 2003 Hewlett Packard Development Company, L.P. command: info bridge Pathmon Process Name [sampl]: Pathway Server Class Name []: qtoq Info for - sampl.qtoq DbVolSubvol=$myvol.
PAGE 96
Reliable Messaging Bridge Run the Bridge from within a Pathway Environment Run the Bridge from within a Pathway Environment The bridge program runs within a Pathway environment using the latest version of executable Pathway scripts (start_pathmon_name and stop_pathmon_name). These scripts assist you in starting and stopping the Pathway environment.
PAGE 97
Reliable Messaging Bridge Start Script Start Script The configuration tool replaces generic configuration placeholders contained in the start_template.txt file with bridge Pathway configured values when the executable Pathway start script (start_pathmon_name) is generated using the add bridge, alter bridge, or delete bridge commands. The start script is used to start a bridge within a Pathway environment (see Starting the Bridge on page 5-18).
PAGE 98
Reliable Messaging Bridge Start Script Example 5-2. start_template.txt File (page 1 of 3) #! /bin/sh # Script for starting a NSJMS Messaging bridge environment # # Usage: # start # The "start" script will start the messaging bridge environment. # Pathcom status messages are redirected to a file.
PAGE 99
Reliable Messaging Bridge Example 5-2. start_template.txt File (page 2 of 3) if [[ -z "$HOMETERM" ]] then X=$(who -m) CNT=$((1)) for i in $X; do if ((CNT==2)) then O_HOMETERM=$i break fi ((CNT+=1)) done HOMETERM=$(basename $O_HOMETERM) TCP_PROCESS=$(basename $(dirname $O_HOMETERM)) G_HOMETERM=\$$TCP_PROCESS.$HOMETERM SLEEP_TIME=10000 else O_HOMETERM=/G/ZTNT/$HOMETERM G_HOMETERM=$ZTNT.
PAGE 100
Reliable Messaging Bridge Start Script Example 5-2. start_template.txt File (page 3 of 3) @@SERVER_PARAMS@@ set server stdout $PWD/@@STDOUT@@ set server stderr $PWD/@@STDERR@@ set server maxservers @@MAXSERVERS@@ set server numstatic @@NUMSTATIC@@ add server @@SERVER_NAME@@ start server @@SERVER_NAME@@ @@END_SERVER@@ eof grep -q -i error $PWD/sampl.pathmon.log if [[ $? -eq 0 ]] then print "Error in starting pathcom, refer to pathmon.
PAGE 101
Reliable Messaging Bridge Start Script Example 5-3. Start Script Sample (page 1 of 3) #! /bin/sh # Script for starting a NSJMS Messaging bridge environment # # Usage: # start # The "start" script will start the messaging bridge environment. # Pathcom status messages are redirected to a file.
PAGE 102
Reliable Messaging Bridge Example 5-3. Start Script Sample (page 2 of 3) if [[ -z "$HOMETERM" ]] then X=$(who -m) CNT=$((1)) for i in $X; do if ((CNT==2)) then O_HOMETERM=$i break fi ((CNT+=1)) done HOMETERM=$(basename $O_HOMETERM) TCP_PROCESS=$(basename $(dirname $O_HOMETERM)) G_HOMETERM=\$$TCP_PROCESS.$HOMETERM SLEEP_TIME=10000 else O_HOMETERM=/G/ZTNT/$HOMETERM G_HOMETERM=$ZTNT.
PAGE 103
Reliable Messaging Bridge Stop Script Example 5-3. Start Script Sample (page 3 of 3) "/usr/tandem/nsjms/T1251V30_30SEP2003_V30:& /usr/tandem/nsjms/T1251V30_30SEP2003_V30/lib/nsjms.jar:& /usr/tandem/nsjms/T1251V30_30SEP2003_V30/lib/jndi.jar:& /usr/tandem/nsjms/T1251V30_30SEP2003_V30/lib/providerutil.jar:& /usr/tandem/nsjms/T1251V30_30SEP2003_V30/lib/fscontext.jar",& "com.tandem.nsjms.bridge.Bridge",& "-pp","sampl",& "-sc","qtoq",& "-sd","queue0",& "-sjd","queue0",& "-sjicf","com.sun.jndi.fscontext.
PAGE 104
pathmon_process_name.properties File Reliable Messaging Bridge Example 5-4. stop_template.txt File #! /bin/sh # Script for shuting down the Messaging Bridge pathway environment # # Execute comand to gracefully shut down servers # # Tell pathmon to shut down. # export PATHMON=@@PATHMON_NAME@@ # gtacl -p pathcom \$$PATHMON <
PAGE 105
Optional Files Created by the User Reliable Messaging Bridge  Bridge.reconnect.delay Default: 60000 Values: milliseconds Value Descriptions: milliseconds—The time (in milliseconds) between when a connection is lost and an attempt is made to reconnect. Example: Bridge.reconnect.delay=60000 An example of the sampl.
PAGE 106
Reliable Messaging Bridge pathmon_process_name.server_class_name. properties File searches it’s CLASSPATH for the server_class.jndi.properties file. If the file is found, the bridge process uses the properties in the server_class.jndi.properties file to override or add to the properties previously passed in from the command line. The bridge process then initializes it’s JNDI context. pathmon_process_name.server_class_name.properties File The pathmon_process_name.server_class_name.
PAGE 107
Reliable Messaging Bridge pathmon_process_name.server_class_name. properties File For example, the bridge process reads in the properties in the below sampl.properties file generated during the Add a Bridge Pathway Configuration with Server Class on page 5-10. #NSJMS Messaging Bridge Properties for sampl #Fri SEP 30 10:24:21 PDT 2003 Bridge.receive.timeout=60000 Logger.filename=sampl.log Bridge.reconnect.delay=60000 Database.delay=1000 Logger.loglevel=info Database.timeout=100 Database.volsubvol=$myvol.
PAGE 108
Reliable Messaging Bridge pathmon_process_name.server_class_name.
PAGE 109
6 NSJMS Administrative Servlet Installation and Configuration This section describes the process for installing the optional NSJMS administrative servlet on your NonStop servers. The administrative servlet enables you to access the NSJMS administrative utility through an XML interface by using an XML formatted request/reply paradigm in a user-defined management application (for example, your web browser).
PAGE 110
NSJMS Administrative Servlet Installation and Configuration Administrative Servlet Installation Procedure for Java Servlets Administrative Servlet Installation Procedure for Java Servlets Use this installation procedure if you are running Java Servlets (T0094V20). 1. Log on as the owner of the /usr/tandem/webserver/conf directory. Note.
PAGE 111
NSJMS Administrative Servlet Installation and Configuration Administrative Servlet Installation Procedure for Java Servlets 5. Copy the JmsAdminServlet.html sample program file located in the NSJMS examples directory to the NSJMS directory created in Step 4: OSH: cp /usr/tandem/nsjms/version/examples/JmsAdminServlet.html_ /usr/tandem/webserver/samples/Servlets/nsjms where /usr/tandem/nsjms/version represents the home directory of the NSJMS installation. 6.
PAGE 112
NSJMS Administrative Servlet Installation and Configuration Administrative Servlet Installation Procedure for NonStop Servlets for JavaServer Pages (T1222V1X) Servlet replies are returned as XML formatted data. For example: VST004.vsd Administrative Servlet Installation Procedure for NonStop Servlets for JavaServer Pages (T1222V1X) Use this installation procedure if you are running NonStop Servlets for JavaServer Pages (T1222V1X) 1. Log on as the owner of the /usr/tandem/webserver/conf directory. Note.
PAGE 113
NSJMS Administrative Servlet Installation and Configuration Administrative Servlet Installation Procedure for NonStop Servlets for JavaServer Pages (T1222V1X) 3. Using an editor of your choice, modify the iTP Secure WebServer servlet.config file: a.
PAGE 114
NSJMS Administrative Servlet Installation and Configuration Administrative Servlet Installation Procedure for NonStop Servlets for JavaServer Pages (T1222V1X) 7. Copy the JmsAdminServlet.html sample program file located in the NSJMS examples directory to the NSJMS directory created in Step 6: OSH: cp /usr/tandem/nsjms/version/examples/JmsAdminServlet.html /usr/tandem/webserver/servlet_jsp/webapps/nsjms where /usr/tandem/nsjms/version/examples/JmsAdminServlet.
PAGE 115
NSJMS Administrative Servlet Installation and Configuration Administrative Servlet Installation Procedure for NonStop Servlets for JavaServer Pages (T1222V1X) 13. The servlet can now be activated by accessing the JmsAdminServlet.html file, http://www.yourserversaddress.com/servlet_jsp/nsjms/JmsAdminServlet.html, through your web browser. For example: VST003.
PAGE 116
NSJMS Administrative Servlet Installation and Configuration Administrative Servlet Installation Procedure for NonStop Servlets for JavaServer Pages (T1222V20) Servlet replies are returned as XML formatted data. For example: VST004.vsd Administrative Servlet Installation Procedure for NonStop Servlets for JavaServer Pages (T1222V20) Use this installation procedure if you are running NonStop Servlets for JavaServer Pages (T1222V20). 1. Log on as the owner of the /usr/tandem/webserver/conf directory. Note.
PAGE 117
NSJMS Administrative Servlet Installation and Configuration Administrative Servlet Installation Procedure for NonStop Servlets for JavaServer Pages (T1222V20) 3. Using an editor of your choice, modify the iTP Secure WebServer servlet.config file: a.
PAGE 118
NSJMS Administrative Servlet Installation and Configuration Administrative Servlet Installation Procedure for NonStop Servlets for JavaServer Pages (T1222V20) 7. Create the NSJMS servlet directory /usr/tandem/webserver/servlet_jsp/webapps/nsjms by executing this command: OSH: mkdir /usr/tandem/webserver/servlet_jsp/webapps/nsjms 8. Copy the JmsAdminServlet.
PAGE 119
NSJMS Administrative Servlet Installation and Configuration Administrative Servlet Installation Procedure for NonStop Servlets for JavaServer Pages (T1222V20) 14. The servlet can now be activated by accessing the JmsAdminServlet.html file, http://www.yourserversaddress.com/servlet_jsp/nsjms/JmsAdminServlet.html, through your web browser. For example: VST003.
PAGE 120
NSJMS Administrative Servlet Installation and Configuration Administrative Servlet Installation Procedure for NonStop Servlets for JavaServer Pages (T1222V20) Servlet replies are returned as XML formatted data. For example: VST004.
PAGE 121
7 Managing the NSJMS Environment This section provides information about using the administrative utility to manage the NSJMS environment and information about using the SQL conversational interface (SQLCI) to query and manage an NSJMS database. Using the Administrative Utility to Manage the NSJMS Environment The administrative utility is a Java-based tool that provides administrative functions to manage the NSJMS environment.
PAGE 122
Managing the NSJMS Environment The Command-Line Interface you can access and manage the NSJMS environment by using any of these commands, which are described in detail in the following pages: ADD HELP ALTER INFO DELETE STATS EXIT Specifying Lines Per Page You can specify the number of lines of returned output that is displayed when using the command-line interface by specifying the Lines Per Page (-llp) argument from the OSS shell.
PAGE 123
The Command-Line Interface Managing the NSJMS Environment expiry attribute value is used when no timetolive value is specified during a send message operation. Default 0 Units milliseconds Range 0 through 9223372036854775807 ID specifies the location of the queue or topic in the NSJMS database. Default If no ID is specified, the ID is generated by adding one to the current highest ID. Range 1 through 32767 Rules     The jndi attribute is not applicable for the NSJMS C++ API environment.
PAGE 124
The Command-Line Interface Managing the NSJMS Environment EXPIRY millisecs specifies the time (in milliseconds) after a message is sent until the message expires. If the EXPIRY attribute value is set to zero, a message never expires. The expiry attribute value is used when no timetolive value is specified during a send message operation. Default 0 Units milliseconds Range 0 through 9223372036854775807 Rules   When queue or topic is specified, name and expiry millisecs are required.
PAGE 125
Managing the NSJMS Environment The Command-Line Interface * is a wild-card character that deletes all queues, topics, messages, or subscriptions from the database. If QUEUE or TOPIC is specified, all queues or topics and any associated subscriptions or messages are deleted. If MESSAGE is specified, all messages are deleted. If SUBSCRIPTION is specified, all subscriptions are deleted. id is the unique ID that identifies a specific message to be deleted from the database.
PAGE 126
Managing the NSJMS Environment  The Command-Line Interface When subscription is specified, if client-id and subscription-name are specified, information about the subscription whose client ID and subscription name match client-id and subscription-name is deleted. client-id and subscription-name are valid only when used with each other.
PAGE 127
The Command-Line Interface Managing the NSJMS Environment command is one of these administrative utility commands for which help is desired: ADD HELP ALTER INFO DELETE STATS EXIT Rules   If the HELP command is run without specifying command, available administrative commands appear. When command is specified, only information about command appears.
PAGE 128
Managing the NSJMS Environment The Command-Line Interface id is the unique ID that identifies a specific message about which information is requested. queue-name is the name of the queue containing the messages about which information is requested. topic-name is the name of the topic containing the messages about which information is requested. expired specifies that information will be returned from the database about all messages with an expiration date prior to the current date.
PAGE 129
Managing the NSJMS Environment The Command-Line Interface Examples The INFO QUEUE command returns a display such as: nsjms-> info queue orders Destination Destination Destination Destination Name: orders ID: 123 Expiry: 1200000 Create Date: Mon Mar 05 18:45:33 PST 1973 The fields returned by the INFO QUEUE command are: Destination Name identifies the name of the queue or topic about which information is requested. Destination ID identifies the location of the queue or topic in the NSJMS database.
PAGE 130
Managing the NSJMS Environment The Command-Line Interface Destination Create Date identifies the date the queue or topic was created.
PAGE 131
Managing the NSJMS Environment The Command-Line Interface JMSPriority identifies the specified message’s priority. A message can fall within two categories of message priorities: Values of 0 through 4 are gradations of normal priority; values of 5 through 9 are gradations of expedited priority. JMSReplyTo identifies a destination to which a reply to the specified message is sent. The destination is supplied by the JMS client when the specified message is sent.
PAGE 132
The Command-Line Interface Managing the NSJMS Environment Destination ID identifies the location of the subscription in the NSJMS database. Nolocal identifies the value of the nolocal attribute. A value of 1 indicates messages published to the topic on the same connection will not be delivered to this subscriber. A value of 0 indicates messages published to the topic on the same connection will be delivered to this subscriber. Message ID identifies the last acknowledged message.
PAGE 133
The Command-Line Interface Managing the NSJMS Environment     If asterisk (*) is specified, statistics for all queues or topics appear. If statistical information is returned by multiple queues or topics, a summary block is displayed. When nsjms is specified, the name attribute is invalid. When nsjms is specified, statistics for all queues and topics appear.
PAGE 134
The Command-Line Interface Managing the NSJMS Environment Process ID: Stats Interval(min): Msgs Sent: Msgs Sent Rate(msg/sec): Msgs Sent Mean(bytes): Msgs Recv: Msgs Recv Rate(msg/sec): Msgs Recv Mean(bytes): Largest Msg Sent(bytes): Largest Msg Recv(bytes): $xyz4 10 907 1.51 4000 607 1.
PAGE 135
The Command-Line Interface Managing the NSJMS Environment Destination: sales Process ID: Stats Interval(min): Msgs Sent: Msgs Sent Rate(msg/sec): Msgs Sent Mean(bytes): Msgs Recv: Msgs Recv Rate(msg/sec): Msgs Recv Mean(bytes): Largest Msg Sent(bytes): Largest Msg Recv(bytes): $xyz2 10 390 0.65 4000 360 0.
PAGE 136
Managing the NSJMS Environment The Command-Line Interface Process ID identifies a process within this destination. Stat Interval (min) identifies the amount of elapsed time in minutes before this process reports statistics. Msgs Sent identifies the number of messages sent by this process. Msgs Sent Rate (msg/sec) identifies the rate at which messages were sent by this process. Msgs Sent Mean (bytes) identifies the mean message size for messages sent by this process.
PAGE 137
Managing the NSJMS Environment The XML Interface Total Msgs Recv identifies the total number of all messages received. Summary Msgs Sent Rate (msg/sec) identifies the summary rate for all messages sent. Summary Msgs Sent Mean (bytes) identifies the summary mean message size for all messages sent. Summary Msgs Recv Rate(msg/sec) identifies the summary rate for all messages received. Summary Msgs Recv Mean (bytes) identifies the summary mean message size for all messages received.
PAGE 138
Managing the NSJMS Environment The XML Interface This is an example of the previous sample request for information when you invoke the administrative utility as a servlet through your web browser. VST003.vsd XML Request DTD This sample request DTD is used internally to validate XML requests when the system property Servlet.
PAGE 139
Managing the NSJMS Environment The XML Interface XML Sample Reply This is the sample reply to the previous request for information about a queue named sales:
PAGE 140
Managing the NSJMS Environment Using SQLCI to Manage an NSJMS Database Using SQLCI to Manage an NSJMS Database NSJMS stores messages and destination information in SQL tables. You can use SQL/MP commands and statements to query and manage an NSJMS database by submitting queries directly through the SQLCI. For additional information about SQL/MP commands and statements, see the SQL/MP Reference Manual.
PAGE 141
A Error Reporting and Messages This appendix provides information about JMS API error messages, the NSJMS API logging facility, the reliable messaging bridge logging facility, the Pathway logging facility, SQL messages, administrative-utility error messages, and administrative-utility warning messages. JMS API Error Messages JMS API error messages and exceptions are described in The Java Message Service specification (see Compliance Information on page 1-4).
PAGE 142
Error Reporting and Messages SQL/MX Messages The SQLCODE field returns a value that describes error information after running an embedded SQL statement: Value Description <0 An error occurred. > 0 (<> 100) A warning occurred. 100 No data was found. 0 The statement completed successfully. The SQLSTATE field returns a five-character variable string that has two parts. The first part is a two-character class code, and the second part is a three-character subclass code.
PAGE 143
Error Reporting and Messages Administrative Utility Error Messages Administrative Utility Error Messages Add Failed NSJMS Err: Add queue|topic name failed:queue|topic name already exists. Cause. An attempt was made to add a queue or topic name that already exists. Effect. The queue or topic name was not added. Recovery. Reenter the command, specifying a queue or topic name that does not already exist. Destination ID Already Exists NSJMS Err: Destination ID already exists Cause.
PAGE 144
Error Reporting and Messages Administrative Utility Error Messages Expiry is required NSJMS Err: Expiry millisecs is required Cause. A value for the expiry attribute is missing. Effect. The command is not run. Recovery. Reenter the command with a value for expiry. Help File Not Found NSJMS Err: Help file not found: help_filename Cause. The specified Help file was not found. Effect. The command is not run. Recovery. Verify the name and existence of the Help file and reenter the command.
PAGE 145
Error Reporting and Messages Administrative Utility Error Messages Invalid Command Attributes NSJMS Err: Expected one of the following attribute(s): attribute_list Cause. The attributes specified for the command are invalid. Valid command attributes are displayed by attribute_list. Effect. The command is not run. Recovery. Reenter the command, using valid attributes. Invalid Destination Name NSJMS Err: Invalid Destination name format: destination_name Cause.
PAGE 146
Error Reporting and Messages Administrative Utility Error Messages Invalid or Out of Range ID Value NSJMS Err: ID value is invalid or out of range: id_value Cause. The Destination ID value contains invalid characters or is too large. Effect. The command is not run. Recovery. Check the definition of Destination ID and reenter the command. Invalid Syntax NSJMS Err: Invalid Syntax Cause. The command syntax is invalid. Effect. The command is not run. Recovery.
PAGE 147
Error Reporting and Messages Administrative Utility Error Messages JNDI Bind Exception NSJMS Err: JNDI bind exception occurred Cause. Review the nsjms.log file to determine the exact cause. Effect. The command is not run. Recovery. Determine the exact cause and take the appropriate corrective action. JNDI Context Exception NSJMS Err: JNDI context exception occurred Cause. Review the nsjms.log file to determine the exact cause. Effect. The command is not run. Recovery.
PAGE 148
Error Reporting and Messages Administrative Utility Error Messages JNDI Unbind Exception NSJMS Err: JNDI unbind exception occurred Cause. Review the nsjms.log file to determine the exact cause. Effect. The command is not run. Recovery. Determine the exact cause and take the appropriate corrective action. Keyword Expected NSJMS Err: Keyword Reset Expected Cause. The keyword Reset was expected but not found. Effect. The command is not run. Recovery. Reenter the command by using the keyword Reset.
PAGE 149
Error Reporting and Messages Administrative Utility Error Messages No Message Found on Queue NSJMS Err: No message(s) found Cause. An attempt was made to display information about a message from a queue, topic, message, or subscription that does not exist. Effect. The message was not displayed. Recovery. Reenter the command, specifying a queue, topic, message, or subscription that contains messages. NSJMS Connection Problem NSJMS Err: NSJMS Connection problem: JMS_error Cause.
PAGE 150
Error Reporting and Messages Administrative Utility Warning Messages SQL Error NSJMS Err: SQL error connecting to database Cause. An error was encountered while attempting to connect to the NSJMS database. Effect. The command is not run. Recovery. Check the location of the database as specified in the nsjms.properties file. Too Many Attributes NSJMS Err: Too many attributes for this command: command Cause. Too many attributes were specified for the command. Effect. The command is not run. Recovery.
PAGE 151
Error Reporting and Messages Administrative Utility Warning Messages Message Not Found NSJMS Warn: Message not found Cause. The specified message was not found. Effect. No information is returned for the specified command. Recovery. This is an informational message. No action is required. No Destination(s) Found NSJMS Warn: No Destination(s) found Cause. No destinations (queue or topic) were found that meet the specified criteria. Effect. No information is returned for the specified command. Recovery.
PAGE 152
Error Reporting and Messages Administrative Utility Warning Messages Statistics Not Active/Available NSJMS Warn: Statistice are not active: No statistics available Cause. The Stats.active property in the nsjms.properties file is set to false. Effect. No information is returned for the specified command. Recovery. This is an informational message. To view and activate statistics, set the Stats.active property to true in the nsjms.properties file.
PAGE 153
Glossary administered object. See NSJMS administered object. API. See application program interface (API). application program. One of the following: A software program written for or by a user for a specific purpose. A computer program that performs a data processing function rather than a control function. application program interface (API). A set of functions or procedures that are called by an application program to communicate with other software components. attribute.
PAGE 154
DSM/SCM Glossary DSM/SCM. See Distributed Systems Management/Software Configuration Manager (DSM/SCM) DTD. See Document Type Definition (DTD) element. The basic unit of information in an XML document. An element has a name and can have content and attributes. 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. Guardian.
PAGE 155
Java Message Service (JMS) Glossary Java Message Service (JMS). A Java API that enables client applications to create, send, receive, and read messages. See also NonStop Server for Java Message Service (NSJMS). Java Naming and Directory Interface (JNDI). A standard extension to the Java platform, which provides Java technology-enabled application programs with a unified interface to multiple naming and directory services. Java Native Interface (JNI).
PAGE 156
NonStop Server for Java Message Service (NSJMS) C++ API Glossary NonStop Server for Java Message Service (NSJMS) C++ API. A JMS provider that implements a subset of the functionality provided by the Sun JMS API, and is used by C++ client applications running on a NonStop system to interoperate with other JMS clients. See also JMS provider. NSJMS. See NonStop Server for Java Message Service (NSJMS). NSJMS C++ API. See NonStop Server for Java Message Service (NSJMS) C++ API. NSJMS administered object.
PAGE 157
shell Glossary 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. SQLCI. The SQL/MP command interpreter. SQL/MP. See HP NonStop SQL/MP. TACL. See HP Tandem Advanced Command Language (TACL). throw. Java keyword used to raise an exception. throws. Java keyword used to define the exceptions that a method can raise. TMF. See Transaction Management Facility (TMF). TNS.
PAGE 158
XML Glossary XML. Extensible Markup Language, a standard for tagging data in an HTML document so as to provide semantic information about content elements.
PAGE 159
Index A ADD command 7-2 administered objects description of 4-2 Queue 4-3 QueueConnectionFactory 4-3 Topic 4-3 TopicConnectionFactory 4-3 ALTER command 7-3 B Best Practices, for developing a JMS client 4-12 C CLASSPATH variable 2-8, 3-6 Client Messaging Components 1-1 command-line interface ADD command 7-2 ALTER command 7-3 DELETE command 7-4 description of 1-3, 7-1 EXIT command 7-6 HELP command 7-6 INFO command 7-7 specifying lines per page 7-2 STATS command 7-12 Compliance Information 1-4 D Database.
PAGE 160
J Index Introduction NSJMS 1-1 reliable messaging bridge 5-1 IPSetup Program, running 2-3, 3-2 J Java.naming.factory.initial 2-16, 3-14 Java.naming.provider.url 2-16, 3-14 JMS API 1-2 JMS Client, best practices for developing 1-2, 4-12 JMS Model 4-1 JNDI API 1-2, 1-4 JNDI Provider 1-2, 1-4 jndi.properties file 2-15, 3-13 L Logger.filename 2-13, 3-11 Logger.loglevel 2-14, 3-12 Logger.
PAGE 161
S Index reliable messaging bridge (continued) configuring 5-2 setting environment variables 5-2 introduction 5-1 monitoring 5-18 pathmon_process_name.server_class_ name.properties file 5-28 running 5-18 server_class.jndi.properties file 5-27 Requirements Disk Space 2-2, 3-1 Hardware 2-1, 3-1 Software 2-1, 3-1 S Servlet.