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. 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.
Document History Part Number Product Version Published 522356-001 NSJMS 1.0 April 2002 522356-002 NSJMS 2.
NonStop Server for Java Message Service User’s Manual Glossary Index What’s New in This Manual v Manual Information v New and Changed Information Figures v About This Manual vii Overview vii Who Should Use This Manual vii How This Manual Is Organized vii Related Manuals vii Your Comments Invited viii Notation Conventions viii 1.
2. NSJMS Installation and Configuration Contents 2. NSJMS Installation and Configuration NSJMS System Requirements 2-1 Hardware 2-1 Software 2-1 Minimum Disk Space 2-2 NSJMS Installation Procedure 2-2 Before You Begin the Installation 2-2 Run the IPSetup Program 2-2 Unpax the NSJMS Product Files.
4. NSJMS Administrative Servlet Installation and Configuration Contents 4.
Figures Contents NonStop Server for Java Message Service User’s Manual—522356-002 iv
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. 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.
What’s New in This Manual • • • • • • Added new information describing support for non-blocking SQL in Threading on page 3-12 and included an example enabling this support using the sqlmx_nowait system property under Test the Sample Programs on page 2-10. Added the new Deadmsg.deletecount on page 2-13, a new property in the nsjms.properties file.
About This Manual Overview The NonStop Server for Java Message Service User’s Manual explains how to install, operate, and manage NonStop Server for Java Message Service (NSJMS) on a NonStop S-series system. Who Should Use This Manual This manual is written for anyone who installs, manages, or monitors NSJMS on a NonStop S-series server. It is assumed the reader is already familiar with Sun Microsystems published specification, Java Message Service, Version 1.0.2b, August 27, 2001.
Your Comments Invited About This Manual Your Comments Invited After using this manual, please take a moment to send us your comments. You can do this by: • • • Completing the online Contact NonStop Publications form if you have Internet access. Faxing or mailing the form, which is included as a separate file in Total Information Manager (TIM) collections and located at the back of printed manuals. Our fax number and mailing address are included on the form.
General Syntax Notation About This Manual computer type. Computer type letters within text indicate C and Open System Services (OSS) keywords and reserved words; enter these items exactly as shown. Items not enclosed in brackets are required. For example: myfile.c italic computer type. Italic computer type letters within text indicate C and Open System Services (OSS) variable items that you supply. Items not enclosed in brackets are required. For example: pathname [ ] Brackets.
General Syntax Notation About This Manual Punctuation. Parentheses, commas, semicolons, and other symbols not previously described must be entered as shown. For example: error := NEXTFILENAME ( file-name ) ; LISTOPENS SU $process-name.#su-name Quotation marks around a symbol such as a bracket or brace indicate the symbol is a required character that you must enter as shown. For example: "[" repetition-constant-list "]" Item Spacing.
Notation for Messages About This Manual !o:i. In procedure calls, the !o:i notation follows an output buffer parameter that has a corresponding input parameter specifying the maximum length of the output buffer in bytes. For example: error := FILE_GETINFO_ ( filenum , [ filename:maxlen ] ) ; !i !o:i Notation for Messages The following list summarizes the notation conventions for the presentation of displayed messages in this manual. Bold Text.
Change Bar Notation About This Manual { } Braces. A group of items enclosed in braces is a list of all possible items that can be displayed, of which one is actually displayed. The items in the list might 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.
1 Introduction to NSJMS NonStop Server for Java Message Service (NSJMS) is the JMS provider that implements Sun Microsystems Java Message Service (JMS) API, version 1.0.2, on HP NonStop S-series systems. NSJMS uses the performance and reliability inherent in SQL/MX products to provide standards-based messaging for local clients running on HP NonStop servers. NSJMS enables scalability and load distribution through horizontal partitioning and fault-tolerance through process-pair technology.
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.
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 you use to manage the NSJMS database. The component parts that access and maintain the NSJMS database are shown in Figure 1-2 and described following the figure.
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.
2 NSJMS Installation and Configuration This section describes • • • • • The system requirements for using NSJMS (see NSJMS System Requirements on this page). How to install and configure NSJMS on an HP NonStop S-series system (see NSJMS Installation Procedure on page 2-2). The NSJMS directory structure (see NSJMS Directory Structure on page 2-11) which includes detailed descriptions of the properties contained in the nsjms.properties file on page 2-11 and the jndi.properties file on page 2-15.
NSJMS Installation and Configuration Minimum Disk Space Minimum Disk Space 1 Megabyte NSJMS Installation Procedure This subsection describes what you need to do before installing NSJMS and explains how to install and configure NSJMS on a NonStop S-series system. It also includes instructions for creating and testing sample programs. 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.
NSJMS Installation and Configuration Run the IPSetup Program To Run IPSetup Exit all other Windows applications before placing NSJMS software on the host system. 1. Open the product CD by double clicking on the CD drive. 2. Click the View Readme file button. Setup opens the README file in Notepad. Be sure to review the entire README file before proceeding. 3. Click the IPSetup button to launch IPSetup. The program displays a Welcome Screen and a License Agreement screen.
NSJMS Installation and Configuration Unpax the NSJMS Product Files. Unpax the NSJMS Product Files. Select one of the following processes to unpax the NSJMS product files.
NSJMS Installation and Configuration Unpax the NSJMS Product Files. 1. RECEIVE the product files from disk (DSV locations) or tape. 2. Uncheck the Manage OSS Files option for the target configuration within the DSM/SCM Planner Interface. Note. You must be installing NSJMS on a NonStop S-series system running G06.18.5 or later RVU. 3. COPY the received product files to a new software revision of the configuration you want to update. 4. BUILD and APPLY the configuration revision. 5.
NSJMS Installation and Configuration Install and Configure NSJMS 2. Use COPYOSS to unpax the NSJMS PAX file into the OSS file system. a. On your NonStop S-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.
Install and Configure NSJMS NSJMS Installation and Configuration • • • Places TANDEM_SYSTEM_NSK.JMS SCHEMA.LIBNSJMS_timestamp in the /usr/tandem/sqlmx/USERMODULES directory. Automatically rebuilds the Java binaries to include the NSJMS JNI code (libnsjms.a). Updates and relinks the JVM (/usr/tandem/java) to include this version of the NSJMS software libraries and class files. 2. Verify that the installation script did not report any errors. Caution.
NSJMS Installation and Configuration Install and Configure NSJMS 6. Update the CLASSPATH Variable Use the export command to update the CLASSPATH variable. For example: OSH: cd /usr/tandem/nsjms/version OSH: export CLASSPATH=$NSJMS_HOME:$NSJMS_HOME/examples:$CLASSPATH OSH: export CLASSPATH=`echo $NSJMS_HOME/lib/*.jar | tr ' ' ':'`:$CLASSPATH 7. Verify SQL Catalog Access NSJMS uses SQL tables to store messages and destination information.
NSJMS Installation and Configuration Install and Configure NSJMS 9. Create NSJMS SQL Tables Use this command to create the NSJMS SQL tables. For example: OSH: gtacl -p sqlci < creatsql Note. Database tables, by default, will support a maximum of 2 gigabytes (GB) on each partition. If larger partitions are required, use the FORMAT2ENABLED attribute when creating the tables.
NSJMS Installation and Configuration Install and Configure NSJMS 12. Compile the Sample Programs Execute these commands to compile the sample programs that use the JNDI object store and destinations created in Add JNDI and Create a Sample Queue and Topic on page 2-9: OSH: cd examples OSH: javac *.java 13. Test the Sample Programs You will need two OSS shells to test each sample program. Note.
NSJMS Directory Structure NSJMS Installation and Configuration 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 To test the Publish and Subscribe sample, execute these commands: In the first shell: OSH: cd examples OSH: java SimpleConsumer -topic T1 -ackmode 1 In the second shell: OSH:
NSJMS Directory Structure NSJMS Installation and Configuration ° ° ° ° 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.
NSJMS Directory Structure NSJMS Installation and Configuration ° Deadmsg.deletecount Default: 0 Values: 0 through 2147483647 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 and the frequency of the deletion is determined by the delete count value.
NSJMS Directory Structure NSJMS Installation and Configuration ° 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.
NSJMS Directory Structure NSJMS Installation and Configuration ° 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.
NSJMS Directory Structure NSJMS Installation and Configuration ° ° • • • • • • • • 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.
NSJMS Installation and Configuration • 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. This sample program uses the administrative servlet.
NSJMS Installation and Configuration Adding a Message Table Dummy Record After completion of the previous SQLCI ALTER TABLE command, the table has two partitions that have the following 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.
NSJMS Installation and Configuration Overflow Table Partitioning The creatsql file that is provided with NSJMS includes this command to insert a dummy record with 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.
NSJMS Installation and Configuration Uninstall Cleanup Steps b. Delete the iTP Secure WebServer NSJMS directory by executing these commands: OSH: cd /usr/tandem/webserver/samples/Servlets OSH: rm nsjms c. Restart the iTPSecure WebServer by executing these commands: OSH: cd /usr/tandem/webserver/conf OSH: ./restart Uninstall Cleanup Steps After uninstalling NSJMS, you can optionally perform the following cleanup steps to remove the version specific NSJMS SQL tables and the NSJMS install directory: 1.
3 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.
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.
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.
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, you perform these tasks: • • • • • Create an Initial Context on page 3-4 Retrieve the Connection Factory on page 3-4 Use the Factory Object to Create a Connection on page 3-5 Start the Connection on page 3-5 Create a Session on page 3-5. Note.
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.
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.
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.
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 ID’s. Temporary Destinations JMS allows for the creation of temporary queues and topics that exist only for the duration of a JMS connection.
NSJMS and JMS Client Applications Persistence Persistence NSJMS does not optimize for NON_PERSISTENT messages (deliver at most once). All messages are treated as having PERSISTENT delivery mode (deliver once and only once). 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.
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.
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.
NSJMS and JMS Client Applications Threading 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); Threading You can use JMS with multithreaded Java applications.
NSJMS and JMS Client Applications Message Expiration Values threaded programs which use separate threads to receive messages simultaneously from different sources or to perform processing while awaiting messages. The system property sqlmx_nowait toggles the non-blocking function. The default value is off. sqlmx_nowait can be set from the command line by using the -D option (-Dsqlmx_nowait=on|off) or programmatically, before obtaining the first NSJMS connection, by using the System.setProperty() method.
NSJMS and JMS Client Applications Message Expiration Values NonStop Server for Java Message Service User’s Manual—522356-002 3- 14
4 NSJMS Administrative Servlet Installation and Configuration This section describes the process for installing the optional NSJMS administrative servlet on your NonStop S-series server. 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).
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.
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.
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.
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 as follows: a.
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.
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.
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.
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 as follows: a.
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.
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.
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.
5 Managing NSJMS 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.
The Command-Line Interface Managing NSJMS you can access and manage the NSJMS database by executing any of these commands, which are described in detail on 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.
The Command-Line Interface Managing NSJMS 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 • • • When queue or topic is specified, name is required. When jndi is specified, name is invalid.
The Command-Line Interface Managing NSJMS 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. The expiry attribute value is used when no timetolive value is specified during a send message operation.
The Command-Line Interface Managing NSJMS * 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.
The Command-Line Interface Managing NSJMS • 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.
The Command-Line Interface Managing NSJMS command is one of the following 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.
The Command-Line Interface Managing NSJMS 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.
The Command-Line Interface Managing NSJMS 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.
The Command-Line Interface Managing NSJMS Destination Create Date identifies the date the queue or topic was created.
The Command-Line Interface Managing NSJMS JMSPriority identifies the specified message’s priority. A message can fall within two categories of message priorities: Values of 0 - 4 are gradations of normal priority; values of 5 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.
The Command-Line Interface Managing NSJMS 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.
The Command-Line Interface Managing NSJMS • • • 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.
The Command-Line Interface Managing NSJMS 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): $xyz5 10 909 1.51 4000 609 1.01 2000 1900 1000 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): $xyz6 10 290 0.
The Command-Line Interface Managing NSJMS 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): $xyz3 10 904 1.51 4000 604 1.
The Command-Line Interface Managing NSJMS 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. Msgs Recv identifies the number of messages received by this process. Msgs Recv Rate (msg/sec) identifies the rate at which messages were received by this process.
The XML Interface Managing NSJMS 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. Summary Largest Msg Sent (bytes) identifies the largest message size in bytes that was sent by all processes.
The XML Interface Managing NSJMS 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.
The XML Interface Managing NSJMS XML Sample Reply This is the sample reply to the previous request for information about a queue named sales:
Using SQLCI to Manage an NSJMS Database Managing NSJMS 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. For additional information about using SQL/MP to query a database, see the SQL/MP Installation and Management Guide.
A Error Reporting and Messages This appendix provides information about JMS API error messages, the NSJMS API 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). NSJMS API Logging Facility All log records generated by the NSJMS API are contained in the nsjms.log file.
Error Reporting and Messages Administrative Utility Error Messages For example, the following error message might be displayed if an exception occurs while preparing an embedded SQL statement: javax.jms.JMSException: SQL error -4081 reading messages: java.sql.SQLException: SQLCODE: -4081 SQLSTATE: 42000 condition number: 1 message text: *** ERROR[4081] SQL/MP error: *** ERROR from SQL [-4004]: Object \KONA.$DATA30.NSJMS.MESSAGE is not an SQL table or view.
Error Reporting and Messages Administrative Utility Error Messages Destination Name Too Long NSJMS Err: Destination name is too long: destination_name Cause. The length of Destination_Name is too long. Effect. The command is not executed. Recovery. Check the definition of Destination Name and reenter the command. Duplicate Command Attributes NSJMS Err: Duplicate command attributes Cause. The command contains duplicate command attributes. Effect. The command is not executed. Recovery.
Error Reporting and Messages Administrative Utility Error Messages Invalid Command Attribute NSJMS Err: Invalid command attribute: attribute Cause. The attribute specified for the command is unknown or invalid. Effect. The command is not executed. Recovery. Check the command syntax and reenter the command, using valid attributes. Invalid Command Attributes NSJMS Err: Expected one of the following attribute(s): attribute_list Cause. The attributes specified for the command are invalid.
Error Reporting and Messages Administrative Utility Error Messages Invalid or Out of Range Expiry Value NSJMS Err: Expiry value is invalid or out of range: expiry_value Cause. The expiry value contains invalid characters or is too large. Effect. The command is not executed. Recovery. Check the definition of Expiry and reenter the command. 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.
Error Reporting and Messages Administrative Utility Error Messages JNDI Add Failed NSJMS Err: JNDI add failed, security violation Cause. A security violation occurred when executing the ADD command. Effect. The command is not executed. Recovery. Verify the user of the administrative utility has the appropriate permissions to perform this operation. JNDI Bind Exception NSJMS Err: JNDI bind exception occurred Cause. Review the nsjms.log file to determine the exact cause. Effect.
Error Reporting and Messages Administrative Utility Error Messages JNDI Object Directory Not Found NSJMS Err: JNDI object directory not found Cause. The JNDI object store could not be found. Effect. The command is not executed. Recovery. Update the java.naming.provider.url property in the jndi.properties file to reflect the correct location of the JNDI object store. JNDI Unbind Exception NSJMS Err: JNDI unbind exception occurred Cause. Review the nsjms.log file to determine the exact cause. Effect.
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.
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 executed. 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 executed.
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.
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.
Error Reporting and Messages Administrative Utility Warning Messages NonStop Server for Java Message Service User’s Manual—522356-002 A -12
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.
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.
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).
NSJMS Glossary NSJMS. See NonStop Server for Java Message Service (NSJMS). NSJMS administered object. A preconfigured object used by JMS clients to create connections to NSJMS and to specify the destinations for messages. namespace. A context for resolving names, used to prevent ambiguity (or “collisions”) where a name can have different meanings in different situations. To qualify a name by identifying the namespace expresses the idea that the name is used as defined in that namespace.
TACL Glossary 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). topic. A destination for a message in a Pub/Sub messaging system. transaction. A series of operations grouped together into a single unit of work. Transaction Management Facility (TMF).
XML Glossary NonStop Server for Java Message Service User’s Manual—522356-002 Glossary -6
Index A E ADD command 5-2 administered objects 3-2 Queue 3-3 QueueConnectionFactory 3-3 Topic 3-3 TopicConnectionFactory 3-3 ALTER command 5-3 Error Messages Administrative Utility A-2 JMS API A-1 SQL/MX exception condition messages A-1 Error Reporting NSJMS API Logging Facility A-1 EXIT command 5-6 expiration values 3-13 C CLASSPATH variable 2-8 command-line interface 1-3, 5-1 ADD command 5-2 ALTER command 5-3 DELETE command 5-4 EXIT command 5-6 HELP command 5-6 INFO command 5-7 specifying lines per pa
L Index L Logger.filename 2-13 Logger.loglevel 2-14 Logger.
T Index SQL conversational interface (SQLCI) 5-1 using SQLCI to manage NSJMS database 5-20 sqlmx_nowait default value 3-13 system property 3-13 used in sample programs 2-10 SQL/MP Table Partitioning 2-17 STATS command 5-12 Stats.active 2-15 Stats.
X Index NonStop Server for Java Message Service User’s Manual—522356-002 Index -4
