NonStop Server for Java Message Service C++ API Programmer s Guide

Transcription

1 NonStop Server for Java Message Service C++ API Programmer s Guide Abstract 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 and HP Integrity NonStop NS-series systems. Sun Microsystems JMS API provides a generic set of interfaces that enable JMS clients to exchange messages. The NSJMS C++ API 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. As part of U64 program, a new 64-bit dll (yjmscdll) has been included in addition to the already present 32-bit dll (zjmscdll). Product Version NSJMS 3.0 Supported Release Version Updates (RVUs) This publication supports G06.20 and all subsequent G-series RVUs and H06.03 and all H-series RVUs unless otherwise indicated by it s replacement publication. The U64 program support is present from H and all subsequent H-series RVUs unless otherwise indicated by it's replacement publication. U64 program does not support G- series RVUs.

2 Part Number Published February 2013

3 Document History Part Number Product Version Published NSJMS 3.0 November NSJMS 3.0 April NSJMS 3.0 February 2013

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

5

6 NonStop Server for Java Message Service C++ API Programmer s Guide Glossary Index Examples Figures What s New in This Manual v Manual Information v New and Changed Information About This Manual vii Overview vii Who Should Use This Manual How This Manual Is Organized Related Manuals viii Notation Conventions viii v vii vii 1. Introduction to the NSJMS C++ API Features and Functions of the NSJMS C++ API 1-1 Supported Platform 1-1 NSJMS C++ API Client Messaging Components 1-1 Client Application 1-2 NSJMS C++ API Library 1-2 SQL/MX 1-2 NSJMS C++ API Interoperability with NSJMS Installation and Configuration for TNS/R NSJMS C++ API System Requirements 2-1 Hardware 2-1 Software 2-1 Minimum Disk Space 2-1 NSJMS C++ API Installation Process 2-1 Before You Begin the Installation 2-1 Run the IPSetup Program 2-2 Unpax the NSJMS C++ API Product Files. 2-3 Install and Configure the NSJMS C++ API 2-6 NSJMS C++ API Directory Structure 2-8 NSJMS Properties File 2-9 Uninstalling the NSJMS C++ API 2-10 Hewlett-Packard Company i

7 Contents 3. Installation and Configuration for TNS/E 3. Installation and Configuration for TNS/E NSJMS C++ API System Requirements 3-1 Hardware 3-1 Software 3-1 Minimum Disk Space 3-1 NSJMS C++ API Installation Process 3-1 Before You Begin the Installation 3-1 Run the IPSetup Program 3-2 Unpax the NSJMS C++ API Product Files. 3-3 Install and Configure the NSJMS C++ API 3-6 NSJMS C++ API Directory Structure 3-9 NSJMS Properties File 3-9 Uninstalling the NSJMS C++ API NSJMS C++ API Classes and Methods BytesMessage Class 4-2 Consumer Class 4-2 MapMessage Class 4-2 Message Class 4-3 ObjectMessage Class 4-4 Producer Class 4-5 Session Class 4-5 StreamMessage Class 4-6 TextMessage Class Using the NSJMS C++ API Establishing Destinations and Managing Transactions External to the NSJMS C++ API 5-1 Establishing Destinations 5-1 Managing Transactions 5-2 Developing NSJMS C++ API Client Applications 5-2 Creating a Session 5-3 Populating a Message with Data 5-3 Sending a Message 5-5 Receiving a Message 5-9 Retrieving Data from a Message 5-11 Building NSJMS C++ API Client Applications 5-12 Compiling and Linking User Written C++ Programs for use with the NSJMS C++ API 5-13 Running User Written C++ Programs 5-15 ii

8 Contents 6. NSJMS C++ API Sample Client Applications 6. NSJMS C++ API Sample Client Applications PTP Sample Applications 6-1 SimpleSender.cpp 6-1 SimpleReceiver.cpp 6-4 Pub/Sub Sample Applications 6-8 SimplePublisher.cpp 6-8 SimpleConsumer.cpp Managing the NSJMS C++ API Environment NSJMS Administrative Utility Commands and Attributes for the NSJMS C++ API Troubleshooting Recovering from SQL/MX Exceptions 8-1 Recovering within Producer::send() Operations 8-1 Recovering within Consumer::receive() Operations 8-2 Debugging NSJMS C++ API Client Applications 8-3 Tracing NSJMS C++ API Client Applications 8-3 Logger.loglevel 8-3 Logger.type 8-4 Logger.filename 8-4 Sample Log Output 8-4 A. Error Reporting and Messages JMS API Error Messages A-1 NSJMS C++ API Logging Facility A-1 NSJMS C++ API Exception Types A-1 NSJMS_Exception A-1 NSJMS_NoSuchProperty A-2 NSJMS_InvalidConversion A-2 NSJMS_SQLError A-2 NSJMS_InvalidClientID A-2 NSJMS_InvalidDestination A-2 NSJMS_MessageFormatException A-2 NSJMS_IllegalStateException A-2 NSJMS_NullPointerException A-2 NSJMS_MemoryAllocationException A-2 iii

9 Contents Glossary Glossary Index Examples Example 6-1. SimpleSender.cpp Sample Client Application 6-2 Example 6-2. SimpleReceiver.cpp Sample Client Application 6-5 Example 6-3. SimplePublisher.cpp Sample Client Application 6-9 Example 6-4. SimpleConsumer.cpp Sample Client Application 6-12 Figures Figure 1-1. NSJMS C++ API Client Messaging on a NonStop System 1-2 iv

10 What s New in This Manual Manual Information Abstract NonStop Server for Java Message Service C++ API Programmer s Guide 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 and HP Integrity NonStop NS-series systems. Sun Microsystems JMS API provides a generic set of interfaces that enable JMS clients to exchange messages. The NSJMS C++ API 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. As part of U64 program, a new 64-bit dll (yjmscdll) has been included in addition to the already present 32-bit dll (zjmscdll). Product Version NSJMS 3.0 Supported Release Version Updates (RVUs) This publication supports G06.20 and all subsequent G-series RVUs and H06.03 and all H-series RVUs unless otherwise indicated by it s replacement publication. The U64 program support is present from H and all subsequent H-series RVUs unless otherwise indicated by it's replacement publication. U64 program does not support G- series RVUs. Part Number Published February 2013 Document History Part Number Product Version Published NSJMS 3.0 November NSJMS 3.0 April NSJMS 3.0 February 2013 New and Changed Information Changes for manual: Updated the section Software on page 2-1. Updated the procedure, Install and Configure the NSJMS C++ API on page 3-6. Updated the NSJMS C++ API Directory Structure on page 3-9. v

11 What s New in This Manual New and Changed Information Updated the procedure, Uninstalling the NSJMS C++ API on page Updated the code in the procedure, Compiling User Written C++ Programs on page Updated the NSJMS C++ API to NSJMS C++ APIs in chapter 5, Using the NSJMS C++ APIs on page 5-1. Changes for manual: Updated these for NonStop NS-series system/server: NSJMS C++ API System Requirements on page 3-1 NSJMS C++ API Installation Process on page 3-1 Item 1 in Before You Begin the Installation on page 3-1 Run the IPSetup Program on page 3-2 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 COPYOSS to Place the Product Files in /usr/tandem/nsjms on page 3-5 Steps 1 through 7 in Install and Configure the NSJMS C++ API on page 3-6 NSJMS C++ API library in NSJMS C++ API Directory Structure on page 3-9 NSJMS Properties File on page 3-9 Steps 1 and 2 in Uninstalling the NSJMS C++ API on page 3-10 vi

12 Overview About This Manual The NonStop Server for Java Message Service C++ API Programmer s Guide explains how to install, operate, manage, and troubleshoot the NSJMS C++ API on HP NonStop systems. Who Should Use This Manual This manual is written for anyone who installs, manages, or monitors the NSJMS C++ API on a NonStop server. It is assumed the reader is already familiar with Sun Microsystems published specification, Java Message Service, Version How This Manual Is Organized Section Title This section... 1 Introduction to the NSJMS C++ API 2 Installation and Configuration for TNS/R 3 Installation and Configuration for TNS/E 4 NSJMS C++ API Classes and Methods Provides an overview of the NSJMS C++ API. Provides installation and configuration details for the NSJMS C++ API for TNS/R. Provides installation and configuration details for the NSJMS C++ API for TNS/E. Provides brief descriptions of the NSJMS C++ API classes and methods. 5 Using the NSJMS C++ API Provides details on how the NSJMS C++ API implements the JMS interfaces when performing JMS client tasks. 6 NSJMS C++ API Sample Client Applications 7 Managing the NSJMS C++ API Environment Provides NSJMS C++ API sample client applications and brief descriptions of the PTP and Pub/Sub messaging models. Provides details on managing the NSJMS C++ API. 8 Troubleshooting Provides details on troubleshooting the NSJMS C++ API. A Error Reporting and Messages Glossary Provides details on NSJMS C++ API error messages. Provides a glossary of technical terms and abbreviations used throughout the manual. vii

13 About This Manual Related Manuals Related Manuals Depending on the tasks you are performing, other manuals you might need are: NonStop Server for Java Message Service User s Manual DSM/SCM User s Guide IPSetup User s Guide C/C++ Programmer s Guide Open System Services Management and Operations Guide NonStop Server for Java (NSJ) Programmer s Guide nld and noft Manual Open System Services Shell and Utilities Reference Manual 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 Backup DAM Volumes and Physical Disk Drives on page 3-2. General Syntax Notation This list summarizes the notation conventions for syntax presentation in this manual. UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: MAXATTACH lowercase italic letters. Lowercase italic letters indicate variable items that you supply. Items not enclosed in brackets are required. For example: file-name computer type. Computer type letters within text indicate C and Open System Services (OSS) keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: myfile.c viii

14 About This Manual General Syntax Notation italic computer type. Italic computer type letters within text indicate C and Open System Services (OSS) variable items that you supply. Items not enclosed in brackets are required. For example: pathname [ ] Brackets. Brackets enclose optional syntax items. For example: TERM [\system-name.]$terminal-name INT[ERRUPTS] A group of items enclosed in brackets is a list from which you can choose one item or none. The items in the list can be arranged either vertically, with aligned brackets on 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. For example: LISTOPENS PROCESS $appl-mgr-name $process-name ALLOWSU ON OFF Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in brackets or braces. For example: INSPECT OFF ON SAVEABEND Ellipsis. An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed sequence of syntax items any number of times. For example: M address [, new-value ] [ - ] An ellipsis immediately following a single syntax item indicates that you can repeat that syntax item any number of times. For example: "s-char " Punctuation. Parentheses, commas, semicolons, and other symbols not previously described must be typed as shown. For example: error := NEXTFILENAME ( file-name ) ; LISTOPENS SU $process-name.#su-name ix

15 About This Manual Notation for Messages Quotation marks around a symbol such as a bracket or brace indicate the symbol is a required character that you must type as shown. For example: "[" repetition-constant-list "]" Item Spacing. Spaces shown between items are required unless one of the items is a punctuation symbol such as a parenthesis or a comma. For example: CALL STEPMOM ( process-id ) ; If there is no space between two items, spaces are not permitted. In this example, no spaces are permitted between the period and any other items: $process-name.#su-name Line Spacing. If the syntax of a command is too long to fit on a single line, each continuation line is indented three spaces and is separated from the preceding line by a blank line. This spacing distinguishes items in a continuation line from items in a vertical list of selections. For example: ALTER [ / OUT file-spec / ] LINE [, attribute-spec ]!i and!o. In procedure calls, the!i notation follows an input parameter (one that passes data to the called procedure); the!o notation follows an output parameter (one that returns data to the calling program). For example: CALL CHECKRESIZESEGMENT ( segment-id!i, error ) ;!o!i,o. In procedure calls, the!i,o notation follows an input/output parameter (one that both passes data to the called procedure and returns data to the calling program). For example: error := COMPRESSEDIT ( filenum ) ;!i,o!i:i. In procedure calls, the!i:i notation follows an input string parameter that has a corresponding parameter specifying the length of the string in bytes. For example: error := FILENAME_COMPARE_ ( filename1:length!i:i, filename2:length ) ;!i:i!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!i, [ filename:maxlen ] ) ;!o:i Notation for Messages This list summarizes the notation conventions for the presentation of displayed messages in this manual. x

16 About This Manual Notation for Messages Bold Text. Bold text in an example indicates user input typed at the terminal. For example: ENTER RUN CODE?123 CODE RECEIVED: The user must press the Return key after typing the input. 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. For example: Event number = number [ Subject = first-subject-value ] A group of items enclosed in brackets is a list of all possible items that can be displayed, of which one or none might actually be displayed. The items in the list can be arranged either vertically, with aligned brackets on each side of the list, or horizontally, enclosed in a pair of brackets and separated by vertical lines. For example: proc-name trapped [ in SQL in SQL file system ] 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 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. For example: obj-type obj-name state changed to state, caused by Object Operator Service process-name State changed from old-objstate to objstate Operator Request. Unknown. Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in brackets or braces. For example: Transfer status: OK Failed xi

17 About This Manual Change Bar Notation % Percent Sign. A percent sign precedes a number that is not in decimal notation. The % notation precedes an octal number. The %B notation precedes a binary number. The %H notation precedes a hexadecimal number. For example: % %B %H2F P=%p-register E=%e-register 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). The CRE has many new message types and some new message type codes for old message types. In the CRE, the message type SYSTEM includes all messages except LOGICAL-CLOSE and LOGICAL-OPEN. xii

18 1 Introduction to the NSJMS C++ API NSJMS is the JMS provider that implements Sun Microsystems Java Message Service (JMS) API, version 1.0.2, on NonStop systems. Sun Microsystems JMS API provides a generic set of interfaces that enable JMS clients to exchange messages. The NSJMS C++ API 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. Features and Functions of the NSJMS C++ API Enables NSK hosted C++ applications to interoperate with JMS clients using a subset of the functionality provided by Sun Microsystems JMS API. Uses the publish and subscribe features of HP NonStop SQL/MX. Uses the NSJMS administrative utility to manage the NSJMS C++ API environment. Includes sample Point-to-Point (PTP) and Publish/Subscribe (Pub/Sub) client applications that demonstrate use of the NSJMS C++ API. Supported Platform The NSJMS C++ API is supported on NonStop server running a version of the HP NonStop operating system released with G06.20 or later RVU and H06.03 or later RVU. NSJMS C++ API Client Messaging Components The components that enable NSJMS C++ API client messaging are shown in Figure 1-1 on page 1-2. Using the NSJMS C++ API is described in Section 5, Using the NSJMS C++ API. 1-1

19 Introduction to the NSJMS C++ API Client Application Figure 1-1. NSJMS C++ API Client Messaging on a NonStop System Client Application NSJMS C++ API Library SQL/MX DP2 DP2 DP2 Tables Tables Tables VST005.vsd Client Application A client application is a user-written application that uses the NSJMS C++ API Library to exchange messages with other JMS client applications. NSJMS C++ API Library The NSJMS C++ API Library provides a set of interfaces that enables JMS clients to exchange messages. The interfaces in the NSJMS C++ API Library implement a subset of the functionality provided by the Sun JMS API. 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 message metadata stored in NSJMS SQL databases. NSJMS C++ API Interoperability with NSJMS The NSJMS C++ API provides a subset of the functionality provided by the Sun JMS Specification. The NSJMS C++ API is provided to allow non-java applications to interoperate with NSJMS clients, and is a simplified version of the NSJMS interface. Interoperability between clients written using the NSJMS C++ API and NSJMS is defined as: 1-2

20 Introduction to the NSJMS C++ API NSJMS C++ API Interoperability with NSJMS Clients can send or receive messages from one product and then receive or send messages using the other product. All message types are supported along with access methods for JMS headers and properties. ObjectMessages are supported, although the message body is returned as a byte array instead of as a Java object. MapMessage and StreamMessage object access methods are not provided. For example, getobject(), readobject(), setobject(), and writeobject() are not provided. The item must be retrieved using the correct type, or using getstring() and readstring(). Message methods which return enumerations are not provided. For example, getproperties() and getmapnames() are not provided. JMS connections do not exist in the NSJMS C++ API. When creating a Session object clients will specify the NSJMS properties file to be used. The Session object is used to create the other interface objects (Messages, Consumers, and Producers). The Producer and Consumer objects are used to send and receive messages, respectively. Consumer receive calls allow a timeout value (which may be zero for nowait). A message listener (upcall) interface is not provided. Consumers are created to be destructive (for dequeue access) or non-destructive (queue browsing or topic subscribing). Transactions and acknowledge mode are not part of the NSJMS C++ API, but externally defined transactions are supported. They must be established using an external API, such as HP NonStop Transaction Management Facility (TMF) or HP NonStop Tuxedo, which will establish a TMF transaction for the process. Operations that require an active TMF transaction are the Producer::send() and the Consumer::receive(). If a transaction is aborted, messages sent under the aborted transaction are affected as: Messages sent under a transaction that aborts are not sent. Messages received with a destructive consumer, for example, queue access, are not deleted and are received again if the transaction under which they were received is aborted. Messages received from a durable subscription are received again if the transaction under which they were received is aborted. Messages received with non-destructive, non-durable access are received again if the transaction under which they were received is aborted. Unlike NSJMS, the objects returned by the NSJMS C++ API must be explicitly freed in order to release resources. The session object includes freexxx() methods which are used to free resources for Messages, Consumers, and Producers. For example, 1-3

21 Introduction to the NSJMS C++ API NSJMS C++ API Interoperability with NSJMS The life cycle for messages sent is: Create a message object using the Session::createXXXMessage() methods Add data to the message using the Message::setXXX() methods Send a message using the Producer::send() method Free message resources using the Session::freeMessage() method The life cycle for messages received is: Receive a message using the Consumer::receive() method Retrieve data from the message using the Message::getXXX() methods Free message resources using the Session::freeMessage() method For a detailed description about using the NSJMS C++ API for application development, see Section 5, Using the NSJMS C++ API. 1-4

22 2 Installation and Configuration for TNS/R NSJMS C++ API System Requirements Hardware Software HP NonStop S-series server HP NonStop operating system (T9050G06), G06.20 or later RVU NonStop OSS (T8620D40) NonStop Server for Java Message Service (T1251V30) TNS/E Native C++ (T9225D46 PVU ABE or later), version 2 Minimum Disk Space 4 Megabytes NSJMS C++ API Installation Process This subsection describes what you need to do before installing the NSJMS C++ API and explains how to install and configure the NSJMS C++ API on a NonStop S-series system. The following installation instructions are correct as of the time this manual was published; however, the README.txt and the SOFTDOC supersedes the information here. Before You Begin the Installation Review the README file on the product CD to ensure you have the correct version for all products installed on your NonStop S-series system. Check that your site meets the minimum hardware and software requirements for the installation utility and also any product-specific installation requirements. (See the README on the product CD). Review the USRGUIDE.PDF file in the NSK_SW subdirectory on the product CD. This file contains the IPSetup User s Guide which provides instructions for using IPSetup, a utility that installs Independent Products. 2-1

23 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.20 or later RVUs, but is recommended. Run the IPSetup Program Use the IPSetup program to place the NSJMS C++ API components on your host NonStop S-series server. If TCP/IP and FTP are unavailable, or if you have problems with automatic file placement, see the IPSetup User s Guide (the USRGUIDE.PDF file in the NSK_SW subdirectory on the product CD) for information about how to manually place operating system files. Caution. Every time you use the Install product to install a release of the operating system software, you must reinstall your Independent Product. Installing a release using the Install product can result in overwriting this Independent Product with older versions of software. This problem does not occur if you are using DSM/SCM to install releases. To Run IPSetup Exit all other Windows applications before placing the NSJMS C++ API 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. 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. If you do not plan on using DSM/SCM, uncheck the box for Use DSM/SCM to complete installation on host. Click Next. 5. On the Product Selection screen, highlight NonStop Server for Java Message Service C++ API as the product you want to install. Click the ADD button. Click Next. 6. Log on using a user ID that can write to the /usr OSS directory (for example, super.super) by following the instructions on the Host Information screen. You can use either the system name or the system IP address to log on. Click Next. 7. On the Host Target screen you can either accept the default locations for Work and Backup subvolumes or browse to locations of your choice. Click Next when you are satisfied with the locations. 2-2

24 Installation and Configuration for TNS/R Unpax the NSJMS C++ API 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. On the Placement Complete screen you can choose to view the release documentation or to launch DSM/SCM. You should review the release documentation. 11. After you review the release documentation, click Finish to complete running IPSetup. Unpax the NSJMS C++ API Product Files. Select one of the following processes to unpax the NSJMS C++ API product files. If you will be using DSM/SCM: Use DSM/SCM to Place the Product Files in /usr/tandem/nsjms on page 2-3 Use DSM/SCM and PINSTALL to Place the Product Files in a User-Specified Installation Directory on page 2-4 If you will not be using DSM/SCM: Use COPYOSS to Place the Product Files in /usr/tandem/nsjms on page 2-5 Use DSM/SCM to Place the Product Files in /usr/tandem/nsjms If you use DSM/SCM, this process will unpax the NSJMS C++ API PAX file, T2811PAX, in the standard OSS location, that is, in /usr/tandem/nsjms. 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. Note. You must be installing the NSJMS C++ API on a NonStop S-series system running G06.20 or later RVU. 3. COPY the received product files to a new revision of the software configuration you want to update. 4. BUILD and APPLY the configuration revision. 2-3

25 Installation and Configuration for TNS/R Unpax the NSJMS C++ API 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 C++ API 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 C++ API PAX file into the OSS file system. (Go to Use COPYOSS to Place the Product Files in /usr/tandem/nsjms on page 2-5). 6. Go to Install and Configure the NSJMS C++ API on page 2-6 for detailed instructions about running the install script and configuring the NSJMS C++ API. Use DSM/SCM and PINSTALL to Place the Product Files in a User-Specified Installation Directory If you use DSM/SCM and PINSTALL, this process will unpax the NSJMS C++ API PAX file, T2811PAX, in a user-specified installation directory. For additional information about using DSM/SCM, see the DSM/SCM User s Guide. For additional information about using PINSTALL, see the Open System Services Management and Operations Guide. 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 the NSJMS C++ API on a NonStop S-series system running G06.20 or later RVU. 3. COPY the received product files to a new revision of the software configuration you want to update. 4. BUILD and APPLY the configuration revision. 5. Run ZPHIRNM to perform the RENAME step. 6. Use PINSTALL to unpax the NSJMS C++ API 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. Unpax T2811PAX using the PINSTALL utility: TACL> PINSTALL -s:/usr/tandem:install-dir:-rvf T2811PAX PINSTALL extracts the files contained in T2811PAX and places them in the version-specific OSS directory install-dir/nsjms/t2811-version, where 2-4

26 Installation and Configuration for TNS/R Unpax the NSJMS C++ API Product Files. install-dir is the user-specified installation directory and T2811-version is the vproc of this RVU (for example, T2811V10_30SEP2003_V10). Note. Running the PINSTALL command does not affect any environment currently running on your NonStop S-series server. 7. Go to Install and Configure the NSJMS C++ API on page 2-6 for detailed instructions about running the install script and configuring the NSJMS C++ API. Use COPYOSS to Place the Product Files in /usr/tandem/nsjms If you use COPYOSS, this process will unpax the NSJMS C++ API PAX file, T2811PAX, in the standard OSS location, that is, in /usr/tandem/nsjms. For additional information about using COPYOSS, see the Open System Services Management and Operations Guide. 1. Ensure that the NSJMS C++ API PAX file, T2811PAX, has been transferred into the DSV location. 2. Use COPYOSS to unpax the NSJMS C++ API 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. Unpax T2811PAX using the TACL macro COPYOSS: TACL> COPYOSS T2811PAX COPYOSS extracts the files contained in T2811PAX and places them in the version-specific OSS directory /usr/tandem/nsjms/t2811-version, where T2811-version is the vproc of this RVU (for example, T2811V10_30SEP2003_V10). Note. Running the copyoss command does not affect any environment currently running on your NonStop S-series server. 3. Go to Install and Configure the NSJMS C++ API on this page for detailed instructions about running the install script and configuring the NSJMS C++ API. 2-5

27 Installation and Configuration for TNS/R Install and Configure the NSJMS C++ API Install and Configure the NSJMS C++ API Note. The remaining installation steps do not require super.super privileges. However, to maintain a secure environment, you should choose the same user ID that is configured for the OSS environment and from under which you run your existing NSJMS applications. Use this user ID to perform the following installation steps. 1. Run the /usr/tandem/nsjms/t2811-version installation script located in the OSS file system directory. For example: TACL> LOGON SUPER.NSJMS TACL> OSH OSH: cd /usr/tandem/nsjms/t2811-version OSH:./install Note. Run the installation script only once after you unpax the NSJMS C++ API product files into the version-specific OSS directory. Run the installation script a second time only when you reinstall the T2811 NSJMS C++ API libraries or include files. The installation script places TANDEM_SYSTEM_NSK.JMS_SCHEMA.LIBNSJMSC_T2811-version in the /usr/tandem/sqlmx/usermodules directory. 2. Verify that the installation script did not report any errors. Caution. After verifying installation, do not delete or modify the version-specific directory (/usr/tandem/nsjms/t2811-version) or its subdirectories because OSS symbolic links point back to the version-specific directory tree. If any part of the version-specific directory tree is deleted or modified, you must reinstall the NSJMS C++ API by unpaxing the NSJMS C++ API PAX file (see Unpax the NSJMS C++ API Product Files. on page 2-3). 3. Verify that you have access to an existing SQL Catalog The NSJMS C++ API uses the NSJMS SQL tables to store messages and destination information. Verify you have access to the existing NSJMS SQL catalog and tables. 4. Create a sample queue and topic using your existing NSJMS (T1251) installation by using these commands: Note. The sample queue and topic names specified below are only examples and may already exist in your NSJMS environment. If they already exist, substitute an appropriate name for Q1 and T1. OSH: cd /usr/tandem/nsjms/t1251-version OSH: java com.tandem.nsjms.admin.jmsadmin NSJMS Admin started. nsjms-> add queue Q1 Destination added. nsjms-> add topic T1 Destination added. nsjms-> exit 2-6

28 Installation and Configuration for TNS/R Install and Configure the NSJMS C++ API where T1251-version is the vproc of the NSJMS (T1251) release (for example, T1251V30_30SEP2003_V30). 5. Compile the sample programs by using the following commands. The sample programs use the destinations created in Step 4 above: OSH: cd /usr/tandem/nsjms/t2811-version/examples OSH: make 6. Test the sample programs You will need two OSS shells to test each sample program. Note. It is assumed that the NSJMS_HOME variable exists and is set to the home directory of your NSJMS (T1251) installation. a. Test the Point-to-Point sample program by using these commands: In the first shell: OSH: cd examples OSH: SimpleReceiver -queue Q1 -count 5 In the second shell: OSH: cd examples OSH: SimpleSender -queue Q1 -count 5 Your Point-to-Point sample program output will be similar to: OSH: cd examples OSH: SimpleReceiver -queue Q1 -count 5 OSH: RCV Message: Sending message 0 OSH: RCV Message: Sending message 1 OSH: RCV Message: Sending message 2 OSH: RCV Message: Sending message 3 OSH: RCV Message: Sending message 4 OSH: cd examples OSH: SimpleSender -queue Q1 -count 5 OSH: Sending message 0 OSH: Sending message 1 OSH: Sending message 2 OSH: Sending message 3 OSH: Sending message 4 OSH: Finished Sending 5 messages 2-7

29 Installation and Configuration for TNS/R NSJMS C++ API Directory Structure b. Test the Publish and Subscribe sample program by using these commands: In the first shell: OSH: cd examples OSH: SimpleConsumer -topic T1 -count 5 In the second shell: OSH: cd examples OSH: SimplePublisher -topic T1 -count 5 Your Publish and Subscribe sample program output will be similar to: OSH: cd examples OSH: SimpleConsumer -topic T1 -count 5 Consumer has been set OSH: Received message #0: Publishing this message 0 OSH: Received message #1: Publishing this message 1 OSH: Received message #2: Publishing this message 2 OSH: Received message #3: Publishing this message 3 OSH: Received message #4: Publishing this message 4 OSH: cd examples OSH: SimplePublisher -topic T1 -count 5 Publishing this message 0 Publishing this message 1 Publishing this message 2 Publishing this message 3 Publishing this message 4 OSH: Finished publishing 5 messages NSJMS C++ API Directory Structure After completing the product installation, the /usr/tandem/nsjms/t2811-version directory contains the following files and subdirectories: install Contains the installation script that copies the TANDEM_SYSTEM_NSK.JMS_SCHEMA.LIBNSJMSC_T2811-version file to the SQL/MX directory. For example, /usr/tandem/sqlmx. COPYRIGHT.TXT Contains the copyright notice for the NSJMS C++ API software. /include Contains the header files required for using the NSJMS C++ API. /doc Contains many HTML files which describe the NSJMS C++ API including index.html. This file contains a complete listing of the NSJMS C++ API HTML documentation. /lib Contains NSJMS C++ API library (libnsjmsc.a). This library contains the archive file required for building programs using the NSJMS C++ API. 2-8

30 Installation and Configuration for TNS/R NSJMS Properties File TANDEM_SYSTEM_NSK.JMS_SCHEMA.LIBNSJMSC_T2811-version. This file contains the execution plans for the SQL statements. /examples Contains SimpleSender.cpp. This sample program sends simple messages to a queue. SimpleReceiver.cpp. This sample program receives simple messages from a queue. SimplePublisher.cpp. This sample program publishes simple messages to a topic. SimpleConsumer.cpp. This sample program subscribes and consumes messages from a topic. NSJMS Properties File The NSJMS C++ API uses the NSJMS properties file to store and retrieve application properties. The NSJMS properties file name is nsjms.properties and is located in the home directory of your NSJMS (T1251) installation, which is typically /usr/tandem/nsjms/t1251-version. The NSJMS C++ API only makes use of a subset of the properties found in the nsjms.properties file. The properties that the NSJMS C++ API use are: Logger.type Logger.filename Logger.loglevel Database.volsubvol Database.tabletimeout Deadmsg.deletecount For detailed descriptions of these properties, see the NonStop Server for Java Message Service User s Manual. The NSJMS properties file is identified as an argument to the Session constructor. Clients can pass the file name of the NSJMS properties file in the home directory of your NSJMS (T1251) installation, or they can use the name of a different NSJMS properties file. For example: In a production environment, NSJMS C++ API clients should use the NSJMS properties file in the home directory of your NSJMS (T1251) installation. In a test environment, or while troubleshooting a problem, NSJMS C++ API clients might want to use a different properties file in order to write trace or debug statements to a different log file or have them display on the console, or send and receive messages from a different database. In such cases, the NSJMS property file should be copied from the NSJMS installed directory to the NSJMS C++ API test environment. After altering the properties, change the argument in the Session constructor to point to the alternate nsjms.properties file in the NSJMS C++ 2-9

31 Installation and Configuration for TNS/R Uninstalling the NSJMS C++ API API test environment, using a fully qualified filename or an environment variable, as shown in the sample programs. For additional information about using the NSJMS properties file as an argument to the Session constructor, see Creating a Session on page 5-3. Uninstalling the NSJMS C++ API To remove an installed version of the NSJMS C++ API, follow these steps from within the OSS environment: 1. Remove the NSJMS C++ API schema file from the /sqlmx/usermodules directory by using these commands: OSH: cd /usr/tandem/sqlmx/usermodules OSH: rm TANDEM_SYSTEM_NSK.JMS_SCHEMA.LIBNSJMSC_T2811-version where T2811-version represents the vproc for the release (for example, T2811V10_30SEP2003_V10) of the NSJMS C++ API to remove. 2. Remove the NSJMS C++ API install directory by using these commands: OSH: cd /usr/tandem/nsjms OSH: rm -R T2811-version where T2811-version represents the specific version of the NSJMS C++ API to remove. Note. Removal of this directory will require any future installation of the NSJMS C++ API to start with Run the IPSetup Program on page

32 3 Installation and Configuration for TNS/E NSJMS C++ API System Requirements Hardware Software HP NonStop NS-series server HP NonStop operating system (T9050H01) NonStop OSS (T8620H01) NonStop Server for Java Message Service (T1251H10) TNS/R Native C++ (TXXXXXXX) Minimum Disk Space 4 Megabytes NSJMS C++ API Installation Process This subsection describes what you need to do before installing the NSJMS C++ API, and explains how to install and configure the NSJMS C++ API on a NonStop NS-series system. The following installation instructions are correct as of the time this manual was published; however, the README file and the SOFTDOC supersede the information here. Before You Begin the Installation Review the README file on the product CD to make sure that you have the correct version for all products installed on your NonStop NS-series system. Check that your site meets the minimum hardware and software requirements for the installation utility and also any product-specific installation requirements. (See the README on the product CD). Review the USRGUIDE.PDF file in the NSK_SW subdirectory on the product CD. This file contains the IPSetup User s Guide which provides instructions for using IPSetup, a utility that installs Independent Products. 3-1

33 Installation and Configuration for TNS/E 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. Run the IPSetup Program Use the IPSetup program to place the NSJMS C++ API components on your host NonStop NS-series server. If TCP/IP and FTP are unavailable, or if you have problems with automatic file placement, see the IPSetup User s Guide (the USRGUIDE.PDF file in the NSK_SW subdirectory on the product CD) for information about how to manually place operating system files. Caution. Every time you use the Install product to install a release of the operating system software, you must reinstall your Independent Product. Installing a release using the Install product can result in overwriting this Independent Product with older versions of software. This problem does not occur if you are using DSM/SCM to install releases. To Run IPSetup Exit all other Windows applications before placing the NSJMS C++ API 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. 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. If you do not plan on using DSM/SCM, uncheck the box for Use DSM/SCM to complete installation on host. Click Next. 5. On the Product Selection screen, highlight NonStop Server for Java Message Service C++ API as the product you want to install. Click the ADD button. Click Next. 6. Log on using a user ID that can write to the /usr OSS directory (for example, super.super) by following the instructions on the Host Information screen. You can use either the system name or the system IP address to log on. Click Next. 7. On the Host Target screen you can either accept the default locations for Work and Backup subvolumes or browse to locations of your choice. Click Next when you are satisfied with the locations. 3-2

34 Installation and Configuration for TNS/E Unpax the NSJMS C++ API 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. On the Placement Complete screen you can choose to view the release documentation or to launch DSM/SCM. You should review the release documentation. 11. After you review the release documentation, click Finish to complete running IPSetup. Unpax the NSJMS C++ API Product Files. Select one of the following processes to unpax the NSJMS C++ API product files. If you will be using DSM/SCM: Use DSM/SCM to Place the Product Files in /usr/tandem/nsjms on page 3-3 Use DSM/SCM and PINSTALL to Place the Product Files in a User-Specified Installation Directory on page 3-4 If you will not be using DSM/SCM Use COPYOSS to Place the Product Files in /usr/tandem/nsjms on page 3-5 Use DSM/SCM to Place the Product Files in /usr/tandem/nsjms If you use DSM/SCM, this process will unpax the NSJMS C++ API PAX file, T2811PAX, in the standard OSS location, that is, in /usr/tandem/nsjms. 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. 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. 3-3

35 Installation and Configuration for TNS/E Unpax the NSJMS C++ API 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 C++ API 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 C++ API PAX file into the OSS file system. (Go to Use COPYOSS to Place the Product Files in /usr/tandem/nsjms on page 3-5). 6. Go to Install and Configure the NSJMS C++ API on page 3-6 for detailed instructions about running the install script and configuring the NSJMS C++ API. Use DSM/SCM and PINSTALL to Place the Product Files in a User-Specified Installation Directory If you use DSM/SCM and PINSTALL, this process will unpax the NSJMS C++ API PAX file, T2811PAX, in a user-specified installation directory. For additional information about using DSM/SCM, see the DSM/SCM User s Guide. For additional information about using PINSTALL, see the Open System Services Management and Operations Guide. 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 install the NSJMS C++ API on a NonStop NS-series system. 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. Run ZPHIRNM to perform the RENAME step. 6. Use PINSTALL to unpax the NSJMS C++ API 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. Unpax T2811PAX using the PINSTALL utility: TACL> PINSTALL -s:/usr/tandem:install-dir:-rvf T2811PAX PINSTALL extracts the files contained in T2811PAX and places them in the version-specific OSS directory install-dir/nsjms/t2811-version, where 3-4

36 Installation and Configuration for TNS/E Unpax the NSJMS C++ API Product Files. install-dir is the user-specified installation directory and T2811-version is the vproc of this RVU (for example, T2811H10_30MAY2005_H10). 7. Go to Install and Configure the NSJMS C++ API on page 3-6 for detailed instructions about running the install script and configuring the NSJMS C++ API. Use COPYOSS to Place the Product Files in /usr/tandem/nsjms If you use COPYOSS, this process will unpax the NSJMS C++ API PAX file, T2811PAX, in the standard OSS location, that is, in /usr/tandem/nsjms. For additional information about using COPYOSS, see the Open System Services Management and Operations Guide. 1. Ensure that the NSJMS C++ API PAX file, T2811PAX, has been transferred into the DSV location. 2. Use COPYOSS to unpax the NSJMS C++ API 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. Unpax T2811PAX using the TACL macro COPYOSS: TACL> COPYOSS T2811PAX COPYOSS extracts the files contained in T2811PAX and places them in the version-specific OSS directory /usr/tandem/nsjms/t2811-version, where T2811-version is the vproc of this RVU (for example, T2811H10_30MAY2005_H10). 3. Go to Install and Configure the NSJMS C++ API on this page for detailed instructions about running the install script and configuring the NSJMS C++ API. 3-5

37 Installation and Configuration for TNS/E Install and Configure the NSJMS C++ API Install and Configure the NSJMS C++ API Note. The remaining installation steps do not require super.super privileges. However, to maintain a secure environment, you should choose the same user ID that is configured for the OSS environment and from under which you run your existing NSJMS applications. Use this user ID to perform the following installation steps. 1. Run the /<jmsc-install-dir>/nsjms/t2811-version installation script located in the OSS file system directory. For example: TACL> LOGON SUPER.NSJMS TACL> OSH OSH: cd /<jmsc-install-dir>/nsjms/t2811-version OSH:./install where <jmsc-install-dir> is the standard or non-standard NSJMS installation location. Note. Run the installation script only once after you unpax the NSJMS C++ API product files into the version-specific OSS directory. Run the installation script a second time only when you reinstall the T2811 NSJMS C++ API libraries or include files. The installation script places TANDEM_SYSTEM_NSK.JMS_SCHEMA.LIBNSJMSC_T2811-version in the /usr/tandem/sqlmx/usermodules directory. 2. Verify that the installation script did not report any errors. Caution. After verifying installation, do not delete or modify the version-specific directory (/jmsc-install-dir+/nsjms/t2811-version) or its subdirectories because OSS symbolic links point back to the version-specific directory tree. If any part of the version-specific directory tree is deleted or modified, you must reinstall the NSJMS C++ API by unpaxing the NSJMS C++ API PAX file (see Unpax the NSJMS C++ API Product Files. on page 3-3). 3. Copy zjmscdll and yjmscdll: a. Change directory: OSH: cd /<jmsc-install-dir>/nsjms/t2811-version lib b. Copy the zjmscdll to the OSS location /G/system/zdll: OSH: cp zjmscdll /G/system/zdll Copy the yjmscdll to the OSS location /G/system/ydll: OSH: cp yjmscdll /G/system/ydll 4. Change the file format: a. Exit OSS. b. Go to the TACL prompt. 3-6

38 Installation and Configuration for TNS/E Install and Configure the NSJMS C++ API c. Change the file format by typing: TACL: V $SYSTEM.ZDLL TACL: fup alter zjmscdll, code 800 TACL: fup alter yjmscdll, code 800 The installation is completed. To run the sample application perform steps 5 through 9: 5. Set the NSJMS HOME variable: a. Go to OSS. b. Use the export command to set the NSJMS HOME variable: OSH: export NSJMS HOME=<jms-install-dir>/nsjms/ T1251H10 _30MAY2005_H10 <jms-install-dir> is the standard or non-standard NSJMS installation location. 6. Verify that you have access to an existing SQL Catalog. The NSJMS C++ API uses the NSJMS SQL tables to store messages and destination information. Verify that you have access to the existing NSJMS SQL catalog and tables. 7. Create a sample queue and topic using your existing NSJMS (T1251) installation by entering these commands: Note. The sample queue and topic names specified below are only examples and may already exist in your NSJMS environment. If they already exist, substitute an appropriate name for Q1 and T1. OSH: cd /<jms-install-dir>/nsjms/t1251-version OSH: java com.tandem.nsjms.admin.jmsadmin NSJMS Admin started. nsjms-> add queue Q1 Destination added. nsjms-> add topic T1 Destination added. nsjms-> exit where T1251-version is the vproc of the NSJMS (T1251) release (for example, T1251H10_30MAY2005_H10). 8. Compile the sample programs by entering the following commands. The sample programs use the destinations created in Step 7 above: OSH: cd /usr/tandem/nsjms/t2811-version/examples OSH: make 9. Test the sample programs 3-7

39 Installation and Configuration for TNS/E Install and Configure the NSJMS C++ API You need two OSS shells to test each sample program. Caution. It is assumed that the NSJMS_HOME variable exists and is set to the home directory of your NSJMS (T1251) installation as specified in Step a a. Test the Point-to-Point sample program by entering these commands: In the first shell: OSH: cd examples OSH: SimpleReceiver -queue Q1 -count 5 In the second shell: OSH: cd examples OSH: SimpleSender -queue Q1 -count 5 Your Point-to-Point sample program output will be similar to: OSH: cd examples OSH: SimpleReceiver -queue Q1 -count 5 OSH: RCV Message: Sending message 0 OSH: RCV Message: Sending message 1 OSH: RCV Message: Sending message 2 OSH: RCV Message: Sending message 3 OSH: RCV Message: Sending message 4 OSH: cd examples OSH: SimpleSender -queue Q1 -count 5 OSH: Sending message 0 OSH: Sending message 1 OSH: Sending message 2 OSH: Sending message 3 OSH: Sending message 4 OSH: Finished Sending 5 messages b. Test the Publish and Subscribe sample program by entering these commands: In the first shell: OSH: cd examples OSH: SimpleConsumer -topic T1 -count 5 In the second shell: OSH: cd examples OSH: SimplePublisher -topic T1 -count 5 3-8

40 Installation and Configuration for TNS/E NSJMS C++ API Directory Structure Your Publish and Subscribe sample program output will be similar to: OSH: cd examples OSH: SimpleConsumer -topic T1 -count 5 Consumer has been set OSH: Received message #0: Publishing this message 0 OSH: Received message #1: Publishing this message 1 OSH: Received message #2: Publishing this message 2 OSH: Received message #3: Publishing this message 3 OSH: Received message #4: Publishing this message 4 OSH: cd examples OSH: SimplePublisher -topic T1 -count 5 Publishing this message 0 Publishing this message 1 Publishing this message 2 Publishing this message 3 Publishing this message 4 OSH: Finished publishing 5 messages NSJMS C++ API Directory Structure After completing the product installation, the /usr/tandem/nsjms/t2811-version directory contains the following files and subdirectories: install Contains the installation script that copies the TANDEM_SYSTEM_NSK.JMS_SCHEMA.LIBNSJMSC_T2811-version file to the SQL/MX directory. For example, /usr/tandem/sqlmx. COPYRIGHT.TXT Contains the copyright notice for the NSJMS C++ API software. /include Contains the header files required for using the NSJMS C++ API. /doc Contains many HTML files which describe the NSJMS C++ API including index.html. This file contains a complete listing of the NSJMS C++ API HTML documentation. /lib Contains NSJMS C++ API library (zjmscdll). NSJMS C++ 64-bit API library (yjmscdll). TANDEM_SYSTEM_NSK.JMS_SCHEMA.LIBNSJMSC_T2811-version. TANDEM_SYSTEM_NSK.JMS_SCHEMA. LIBNSJMSC64_T2811- version. These files contain the execution plans for the SQL statements for 32-bit and 64-bit DLLs respectively. /examples Contains SimpleSender.cpp. This sample program sends simple messages to a queue. 3-9

41 Installation and Configuration for TNS/E NSJMS Properties File SimpleReceiver.cpp. This sample program receives simple messages from a queue. SimplePublisher.cpp. This sample program publishes simple messages to a topic. SimpleConsumer.cpp. This sample program subscribes and consumes messages from a topic. NSJMS Properties File The NSJMS C++ API uses the NSJMS properties file to store and retrieve application properties. The NSJMS properties file name is nsjms.properties and is located in the home directory of your NSJMS (T1251) installation, which is typically /<jms-install-dir>/nsjms/t1251-version. The NSJMS C++ API only makes use of a subset of the properties found in the nsjms.properties file. The properties that the NSJMS C++ API use are: Logger.type Logger.filename Logger.loglevel Database.volsubvol Database.tabletimeout Deadmsg.deletecount For detailed descriptions of these properties, see the NonStop Server for Java Message Service User s Manual. The NSJMS properties file is identified as an argument to the Session constructor. Clients can pass the file name of the NSJMS properties file in the home directory of your NSJMS (T1251) installation, or they can use the name of a different NSJMS properties file. For example: In a production environment, NSJMS C++ API clients should use the NSJMS properties file in the home directory of your NSJMS (T1251) installation. In a test environment, or while troubleshooting a problem, NSJMS C++ API clients might want to use a different properties file in order to write, trace or debug statements to a different log file or have them display on the console, or send and receive messages from a different database. In such cases, the NSJMS property file should be copied from the NSJMS installed directory to the NSJMS C++ API test environment. After altering the properties, change the argument in the Session constructor to point to the alternate nsjms.properties file in the NSJMS C++ API test environment, using a fully qualified filename or an environment variable, as shown in the sample programs. For additional information about using the NSJMS properties file as an argument to the Session constructor, see Creating a Session on page

42 Installation and Configuration for TNS/E Uninstalling the NSJMS C++ API Uninstalling the NSJMS C++ API To remove an installed version of the NSJMS C++ API, follow these steps from within the OSS environment: 1. Remove the NSJMS C++ API schema file from the /sqlmx/usermodules directory by using these commands: OSH: cd /usr/tandem/sqlmx/usermodules OSH: rm TANDEM_SYSTEM_NSK.JMS_SCHEMA.LIBNSJMSC_T2811-version where T2811-version represents the vproc for the RVU (for example, T2811H10_30MAY2005_H10) of the NSJMS C++ API to remove. 2. Remove the NSJMS C++ API DLLs from the /G/system/zdll and /G/system/ydll directories by using these commands: OSH: cd /G/system/zdll OSH: rm -R T2811-version OSH: cd /G/system/ydll OSH: rm -R T2811-version 3. Remove the NSJMS C++ API install directory by using these commands: OSH: cd /usr/tandem/nsjms OSH: rm -R T2811-version where T2811-version represents the specific version of the NSJMS C++ API to remove. Note. Removal of this directory will require any future installation of the NSJMS C++ API to start with Run the IPSetup Program on page

43 Installation and Configuration for TNS/E Uninstalling the NSJMS C++ API 3-12

44 4 NSJMS C++ API Classes and Methods This section briefly describes the following NSJMS C++ API classes and the methods associated with each class. Note. Detailed programmatic descriptions of the NSJMS C++ API classes and methods are located in /usr/tandem/nsjms/t2811-version/doc, where T2811-version is the vproc of this RVU (for example, T2811V10_30SEP2003_V10). BytesMessage Class on page 4-2 Consumer Class on page 4-2 MapMessage Class on page 4-2 Message Class on page 4-3 ObjectMessage Class on page 4-4 Producer Class on page 4-5 Session Class on page 4-5 StreamMessage Class on page 4-6 TextMessage Class on page

45 NSJMS C++ API Classes and Methods BytesMessage Class BytesMessage Class The BytesMessage class extends the Message class and sends a message that contains a stream of uninterpreted bytes. BytesMessage Methods readbytes writebytes Consumer Class The Consumer class is a client that uses a message consumer to receive messages from a destination. A Consumer is created by passing a destination and consumer type to a createconsumer() method supplied by a Session object. Consumer Method receive MapMessage Class Description Read a portion of the bytes-message stream. Write a byte array to the bytes-message stream. Description Receive the next message that arrives within the specified timeout interval. The MapMessage class extends the Message class and sends a message that contains name-value pairs. MapMessage Methods Description (page 1 of 2) getboolean Return the boolean value with the given name. getbyte Return the byte value with the given name. getbytes Return the byte array value with the given name. getdouble Return the double value with the given name. getfloat Return the float value with the given name. getint Return the integer value with the given name. getlong Return the long value with the given name. getshort Return the short value with the given name. getstring Return the string value with the given name. itemexists Indicates whether an item exists in this MapMessage object. setboolean Set a boolean value with the given name, into the Map. setbyte Set a byte value with the given name, into the Map. setbytes Set a byte array value with the given name, into the Map. setdouble Set a double value with the given name, into the Map. setfloat Set a float value with the given name, into the Map. setint Set a integer value with the given name, into the Map. 4-2

46 NSJMS C++ API Classes and Methods Message Class MapMessage Methods Description (page 2 of 2) setlong setshort setstring Message Class Set a long value with the given name, into the Map. Set a short value with the given name, into the Map. Set a string value with the given name, into the Map. The Message class is the base class of all message classes. Message Methods Description (page 1 of 2) clearproperties getbooleanproperty getbyteproperty getbytesproperty getdoubleproperty getfloatproperty getintproperty getjmscorrelationid getjmsdeliverymode getjmsdestination getjmsexpiration getjmsmessageid getjmspriority getjmsreplyto getjmstimestamp getjmstype getlongproperty getshortproperty getstringproperty propertyexists setbooleanproperty setbyteproperty Clears the message s header fields and properties, the body is not cleared. Returns the value of the boolean property with the specified name. Returns the value of the byte property with the specified name. Returns the value of the byte-array property with the specified name. Returns the value of the double property with the specified name. Returns the value of the float property with the specified name. Returns the value of the integer property with the specified name. Gets the correlation ID for the message. Gets the delivery mode value specified for this message. Gets the destination object for the message. Gets the expiration value for the message. Gets the message ID for the message. Gets the priority level for the message. Gets the destination object to which a reply to this message should be sent. Gets the timestamp for the message. Gets the message type identifier supplied by a client when a message is sent. Returns the value of the long property with the specified name. Returns the value of the short property with the specified name. Returns the value of the string property with the specified name. Indicates whether a property value exists for the message. Sets a boolean property value with the specified name into the message. Sets a byte property value with the specified name into the message. 4-3

47 NSJMS C++ API Classes and Methods ObjectMessage Class Message Methods Description (page 2 of 2) setbytesproperty Sets a byte array property value with the specified name into the message. setdoubleproperty Sets a double property value with the specified name into the message. setfloatproperty Sets a float property value with the specified name into the message. setintproperty Sets an integer property value with the specified name into the message. setjmscorrelationid Sets the correlation ID for the message. setjmsdeliverymode Sets the DeliveryMode value specified for this message. setjmsdestination Sets the Destination object for the message. setjmsexpiration Sets the expiration value for the message. setjmsmessageid Sets the message ID for the message. setjmspriority Sets the priority level for the message. setjmsreplyto Sets the Destination object to which a reply to this message should be sent. setjmstimestamp Sets the timestamp for the message. setjmstype Sets the message type identifier for the message. setlongproperty Sets a long property value with the specified name into the message. setshortproperty Sets a short property value with the specified name into the message. setstringproperty Sets a string property value with the specified name into the message. ObjectMessage Class The ObjectMessage class extends the Message class and sends a message that contains a serializable Java object. If the ObjectMessage was published by an NSJMS client, this message body contains a serializable Java object. Although, the message body is returned as a byte array instead of as a Java object. ObjectMessage Methods readbytes writebytes Description Read a portion of the bytes-message stream. Write a byte array to the bytes-message stream. 4-4

48 NSJMS C++ API Classes and Methods Producer Class Producer Class The Producer class is a client that uses a message producer to send messages to a destination. A Producer is created by passing a destination to a createproducer() method supplied by a Session. Producer Methods send send send Session Class Description Send a message to the destination. Use the Producer's default delivery mode and priority, and use the Destination s default time to live. Send a message to a destination specifying delivery mode and priority, but use the Destination s default time to live. Send a message to a destination specifying delivery mode, priority and time to live. The Session class is a context used to create and free all NSJMS C++ API objects. A Session provides methods for creating Consumers (receivers and subscribers), Producers, Durable Subscribers, BytesMessages, MapMessages, ObjectMessages, StreamMessages, and TextMessages. Session Methods Session createconsumer createdurablesubscriber createproducer createmessage createtextmessage createstreammessage createmapmessage createobjectmessage createbytesmessage freeconsumer Description (page1of2) This is the Session constructor. It is used by clients as the first call to initiate an NSJMS C++ API session. Create a Consumer for the specified destination. A client uses a message Consumer to consume/receive messages from a destination. Creates or restarts a durable subscriber (consumer) instance given a Client Id, Subscription Name, and Topic Name. Create a Producer for the specified destination. A client uses a Producer for publishing/sending messages to a destination. Create an empty message, a message with headers and properties only, no message body. Create a TextMessage. Create a StreamMessage. Create a MapMessage. Create a ObjectMessage. Create a ByteMessage. Deallocates resources for a Consumer instance. 4-5

49 NSJMS C++ API Classes and Methods StreamMessage Class Session Methods freemessage freeproducer unsubscribe Description (page2of2) Deallocates resources for a Message instance. Deallocates resources for a Producer instance. Unsubscribe from a durable subscription that has been created by a client. StreamMessage Class The StreamMessage class extends the Message class and sends a message that contains a stream of primitives. StreamMessage Methods readboolean readbyte readbytes readdouble readfloat readint readlong readshort readstring reset writeboolean writebyte writebytes writedouble writefloat writeint writelong writeshort writestring Description Reads a boolean from the string message. Reads a byte value from the string message. Reads a byte array field from the string message. Reads a double from the string message. Reads a float from the string message. Reads an integer from the string message. Reads a 64-bit integer from the string message. Reads a 16-bit integer from the string message. Reads a string from the string message. Puts the StreamMessage body in read-only mode and repositions the stream to the beginning. Writes a boolean to the stream message. The value true is written as the value 1; the value false is written as the value 0. Writes a byte value to the string message. Writes a byte array field to the string message. Writes a double to the string message. Writes a float to the string message. Writes an integer to the string message. Writes a long to the string message. Writes a short to the string message. Writes a string to the string message. 4-6

50 NSJMS C++ API Classes and Methods TextMessage Class TextMessage Class The TextMessage class extends the Message class and sends a message that contains a character string. TextMessage Methods settext gettext Description Gets the string containing the message's data. Sets the message's data with the null-terminated string sent as argument 4-7

51 NSJMS C++ API Classes and Methods TextMessage Class 4-8

52 5 Using the NSJMS C++ APIs This section describes The functionality that must be implemented outside of the NSJMS C++ APIs (see Establishing Destinations and Managing Transactions External to the NSJMS C++ API on page 5-1). How to develop NSJMS C++ API client applications (see Developing NSJMS C++ API Client Applications on page 5-2). How to build clients that use NSJMS C++ API classes (see Building NSJMS C++ API Client Applications on page 5-12). Establishing Destinations and Managing Transactions External to the NSJMS C++ APIs The NSJMS C++ APIs implement only a subset of the functionality provided by the Sun JMS API. Destinations and externally defined transactions are not part of the functionality implemented by the NSJMS C++ APIs and must be established prior to running NSJMS C++ APIs client applications. Establishing Destinations Destinations (queue and topic) must be created prior to use within the NSJMS C++ API. Use the NSJMS administrative utility ADD Command (see the NonStop Server for Java Message Service User s Manual) to create queue and topic destinations. 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. Destination IDs Destinations (queues and topics) within NSJMS are assigned IDs that represent the destinations in the database. The IDs allow efficient storage for messages and flexible partitioning of the message table. Assignment of the destination ID is done when the destination is first created. This assignment can be automatic (implicit) or explicit within the administrative commands. Explicit destination-id assignment is useful when you need message-table partitioning. The IDs are chosen so that ranges are defined over the IDs to identify the partitions. For example, you can group destinations by 100s with separate partitions assigned to each range of 100. Destination IDs must be positive numbers, 1 to (SHORT_MAX). 5-1

53 Using the NSJMS C++ APIs Managing Transactions If no explicit ID is specified, the ID is generated by adding one to the current highest ID. Destination IDs cannot be changed once assigned. You must delete and re-create a destination to change an ID. Managing Transactions Transactions and acknowledge mode are not part of the NSJMS C++ API, but externally defined transactions are supported. They must be established using an external API, such as HP NonStop Transaction Management Facility (TMF) or HP NonStop Tuxedo, which will establish a TMF transaction for the process. Operations that require an active TMF transaction are the Producer::send() and the Consumer::receive(). If a transaction is aborted, messages sent under the aborted transaction are affected as follows: Messages sent under a transaction that aborts are not sent. Messages received with a destructive consumer, for example, queue access, are not deleted and are received again if the transaction under which they were received is aborted. Messages received from a durable subscription are received again if the transaction under which they were received is aborted. Messages received with non-destructive, non-durable access are received again if the transaction under which they were received is aborted. Developing NSJMS C++ APIs Client Applications NSJMS C++ APIs client applications hosted on the operating system use the NSJMS C++ APIs to send and receive messages to and from other JMS clients or other NSJMS C++ APIs clients. Descriptions of common tasks performed by NSJMS C++ APIs clients, and information about how the NSJMS C++ APIs implement the JMS interfaces when performing the tasks are provided in: Creating a Session on page 5-3 Populating a Message with Data on page 5-3 Sending a Message on page 5-5 Receiving a Message on page 5-9 Retrieving Data from a Message on page 5-11 Note. The code fragments in this section illustrate how specific tasks are implemented within the NSJMS C++ APIs and are based on the sample programs in Section 6, NSJMS C++ API Sample Client Applications. 5-2

54 Using the NSJMS C++ APIs Creating a Session Creating a Session A Session is a context used to create and free all NSJMS C++ APIs objects. A Session provides methods for creating Consumers (receivers and subscribers), Producers, Durable Subscribers, BytesMessages, MapMessages, ObjectMessages, StreamMessages, and TextMessages. A Session object is created using a constructor which specifies a file name containing the NSJMS properties file. These properties are used to configure NSJMS clients, as well as NSJMS C++ API clients. If the name is unqualified, the current working directory is assumed. This constructor is used by clients as the first call to initiate NSJMS C++ APIs sessions. Note. Creating a Session object must be done prior to creating any other NSJMS C++ API objects. Creating a Session object when using a properties file in the current working directory is shown is this code fragment: // Create a new session Session *pses = new Session("nsjms.properties"); Creating a Session object when using an environment variable to dynamically assign a directory is shown in this code fragment: char *propfile = getenv("nsjms_home"); strcat(propfile, "/nsjms.properties"); pses = new Session(propFile); Populating a Message with Data The NSJMS and NSJMS C++ APIs messaging products treat messages as entities that consist of a header, a body, and, optionally, application-defined property values. The header contains fields used for message routing and identification; the body contains the application data being sent. Prior to populating a message with data, the client must first create a message object as shown in these code fragments: // Creating a Text Message TextMessage *pmsg = pses->createtextmessage(); // Creating a Bytes Message BytesMessage *pmsg = pses->createbytesmessage(); // Creating a Map Message MapMessage *pmsg = pses->createmapmessage(); // Creating a Stream Message StreamMessage *pmsg = pses->createstreammessage(); // Creating a Object Message ObjectMessage *pmsg = pses->createobjectmessage(); 5-3

55 Using the NSJMS C++ APIs Populating a Message with Data Message class The Message class is the base class of all message subclasses. The Message class defines the JMS header and property methods used for all message types. A JMS Message is made up of these components: Message Header Message Properties Message Body Message Header All messages support the same set of header fields. Header fields contain values used by both clients and providers to identify and route messages. Header fields are never in a read-only mode. Most JMS headers are set automatically by the NSJMS C++ APIs software with the exception of JMSCorrelationID and JMSReplyTo as shown in this table: Header Fields JMSDestination JMSDeliveryMode JMSExpiration JMSPriority JMSMessageID JMSTimestamp JMSCorrelationID JMSReplyTo JMSType Set By NSJMS C++ APIs Software NSJMS C++ APIs Software NSJMS C++ APIs Software NSJMS C++ APIs Software NSJMS C++ APIs Software NSJMS C++ APIs Software Client Client NSJMS C++ APIs Software Using the client to set the JMSReplyTo header is shown in this code fragment: // Set JMS ReplyTo header pmsg->setjmsreplyto("q1"); Message Properties A Message object contains a built-in facility for supporting application-defined property values. In effect, this facility provides a mechanism for adding application-specific header fields to a message. Property values can be boolean, byte, short, int, long, float, double, and String. Property values are set prior to sending a message. When a 5-4

56 Using the NSJMS C++ APIs Populating a Message with Data client receives a message, its properties are in read-only mode. If a client attempts to set properties at this point, an NSJMS_Exception is thrown. Note that header fields are distinct from properties. Setting an application-defined string property is shown in this code fragment: // Set an application-defined string property pmsg->setstringproperty("test","simplesender"); Message Body The message body contains the application data that is being sent. The Sun JMS API defines these five types of message bodies: Stream A StreamMessage object's message body contains a stream of primitive values. The message body is filled and read sequentially. Map A MapMessage object's message body contains a set of name-value pairs. The entries can be accessed sequentially or randomly by name. The order of the entries is undefined. Text A Text Message contains ASCII text. This message type can be used to transport plain-text messages. Object An ObjectMessage object's message body contains an array of bytes. If the ObjectMessage was sent by a JMS client, this message body contains a serializable Java object. Bytes A BytesMessage object's message body contains a stream of uninterpreted bytes. Populating a TextMessage message body is shown in this code fragment: // Populating a TextMessage message body pmsg->settext("sending text message"); Free Message Resources The Session class contains the freemessage() method for freeing message resources. This method takes a pointer to a Message object as an argument. This method results in the Message destructor being called, as well as any Message subclass destructors. The method frees all memory used to store message headers, message properties, and message bodies. Message resources should be freed after a message is sent or received and no longer needed. Freeing all memory used to store message headers, message properties, and message bodies is shown in this code fragment: // Freeing Message pses->freemessage(pmsg); 5-5

57 Using the NSJMS C++ APIs Sending a Message Sending a Message NSJMS C++ APIs client uses a Producer to send messages to a specified destination. A message producer is an object created by a session that is used by clients to send messages to queues or topics. The PTP messaging application and the Pub/Sub messaging application both use the Producer class as their message producer. Sending a message to a Queue or Topic To send a message to a queue or topic, clients create a Producer object using the createproducer() method from the Session class. Note. Destinations (queue and topic) must be created prior to use within the NSJMS C++ API. Use the NSJMS administrative utility ADD Command (see the NonStop Server for Java Message Service User s Manual) to create queue and topic destinations. Creating a queue producer is shown in this code fragment: char *queuename = MyQueue ; // Create a Queue Producer Producer *pproducer = pses->createproducer(queuename); Creating a topic producer is shown in this code fragment: char *topicname = MyTopic ; // Create a Topic Producer Producer *pproducer = pses->createproducer(topicname); Producer class The Producer class supports three send() methods: and and void send(message *message); void send(message *message, int deliverymode, int priority ); void send(message *message, int deliverymode, int priority, int64 timetolive ); Starting a transaction, sending a message using the default send options, and ending the transaction is shown in this code fragment: /* Starting Transaction, Sending the Message using the default send options*/ BEGINTRANSACTION(); pproducer->send(pmsg); ENDTRANSACTION(); Note. The Producer send operation must be wrapped within a transaction because the MESSAGE table is audited. 5-6

58 Using the NSJMS C++ APIs Sending a Message A client can send a message using the default delivery mode, priority, and time-to-live for messages sent by a message producer or, a client can specify a delivery mode, priority, and time-to-live per message. The default values are: deliverymode = DELIVERYMODE_PERSISTENT, priority = DEFAULT_JMSPRIORITY, timetolive = DEFAULT_JMSEXPIRATION Message Delivery Mode NSJMS C++ APIs allows a message s delivery mode to be set using the deliverymode argument of the Producer::send() method, and retrieved using the Message::getJMSDeliveryMode() method of the Message class. Neither NSJMS nor the NSJMS C++ APIs optimize for NON_PERSISTENT messages (deliver at most once). All messages are treated as having PERSISTENT delivery mode (deliver once and only once). Message Priority NSJMS C++ APIs allows a message s priority to be set using the priority argument of the Producer::send() method, and retrieved using the Message::getJMSPriority() method of the Message class. Although the NSJMS C++ APIs allow a message s priority to be set and retrieved, this priority does not affect message-delivery order. Message Expiration Value (timetolive) NSJMS C++ APIs allow a message s expiration value to be set using the timetolive argument of the Producer::send() method, and retrieved using the Message::getJMSExpiration() method of the Message class. A client specifies a time-to-live value in milliseconds for each message it sends. For example, if a message is to expire one day after it was sent, you would assign the following value to the timetolive argument of the Producer::send() method: long long oneday = 1000*60*60*24; where 1000 is the number of milliseconds in one second, 60 is the number of seconds in one minute, 60 is the number of minutes in one hour, and 24 is the number of hours in one day. When a message is sent, the expiration time is left unassigned. After completion of the send() method, the message's JMSExpiration header field contains the expiration time of the message. The message's expiration time is calculated, in milliseconds, to be the sum of the timeto-live value and the Greenwich mean time (GMT) when the message is sent (this is the time the client sends the message and not the time the send transaction is committed). This unit of time is consistent with the Java System.currentTimeMillis() method which returns the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC. Internally, 5-7

59 Using the NSJMS C++ APIs Sending a Message this expiration value is converted to a Julian timestamp and stored in the msg_expiration column of the MESSAGE table. The conversion algorithm is: julian = (millis + MILLIS_TILL_1970) * 1000; where MILLIS_TILL_1970 is If the time-to-live value is 0, then the message remains in the database forever, or until it is deleted by a queue receiver or manually deleted. The two send() methods that do not include time-to-live as an argument use the value assigned to the DEST_EXPIRY column of the DEST table as the default time-to-live value. Queue Message Removal The application determines the rate of removal for messages in queues, which are deleted as they are received. Messages in queues might also have expiration attributes that specify that the messages can be removed before they are received. Topic Message Removal Messages on topics are not removed by subscribers. The messages exist until they are removed because they have expired or are dead. A topic message is expired when the message-expiration value is exceeded. An expiration value is specified when the message is sent. If no expiration value is specified, the message never expires. A topic message is dead after it has been read by all subscribers. To remove expired and dead messages, do either of these: Use the NSJMS administrative utility DELETE command. Set the Deadmsg.deletecount property in the nsjms.property file to a value greater than 0. This value represents the number of messages received between the deletion of dead messages. For example, a delete count of 100 means that after every 100th message received from a topic, all existing dead messages are deleted. Setting the Deadmsg.deletecount property to 0 disables dead-message removal. Free Producer Resources The Session class contains the freeproducer() method for freeing producer resources. This method takes a pointer to a Producer object as an argument. This method results in the Producer destructor being called, which frees all memory used by the Producer. Freeing a producer is shown in this code fragment: //Freeing the producer pses->freeproducer(pproducer); 5-8

60 Using the NSJMS C++ APIs Receiving a Message Receiving a Message NSJMS C++ APIs client uses a Consumer to receive messages from a specified destination. A message consumer is created by passing a destination name (queue or topic) and consumer type to the createconsumer() method supplied by a Session class. The PTP messaging application and the Pub/Sub messaging application both use the Consumer class as its message consumer. Consumer class The Consumer class supports a single receive() method: Message* receive(int timeout); A client can request the next message from a message consumer that uses its receive() method. This call blocks until a message arrives or the timeout expires. The receive() method takes a timeout argument in milliseconds. This value defines how long the receive() method should wait when there are no messages available. For example: receive(3000); //wait 3 seconds A value of zero blocks the receive() call indefinitely. Receiving Messages from a Queue To receive a message from a queue, clients create a Consumer object by using the createconsumer() method from the Session class, which has the Consumer::RECEIVER constant as the consumer type. This method uses a queue destination to define the location from which the messages are received. Creating the consumer for a queue (a receiver), starting a transaction, receiving the message, and then ending the transaction is shown in this code fragment: char *queuename = MyQueue ; // Creating the Receiver Consumer *pconsumer = pses->createconsumer(queuename, Consumer::RECEIVER); // Starting Transaction, Receiving the Message BEGINTRANSACTION(); Message *pmsg = pconsumer->receive(3000); ENDTRANSACTION(); Note. The Consumer receive operation must be wrapped within a transaction because the MESSAGE table is audited. Free Consumer Resources The Session class contains the freeconsumer() method for freeing consumer resources. This method takes a pointer to a Consumer object as an argument. This 5-9

61 Using the NSJMS C++ APIs Receiving a Message method results in the Consumer destructor being called, which frees all memory used by the Consumer. Freeing a consumer is shown in this code fragment: // Freeing the Consumer pses->freeconsumer(pconsumer); Receiving Messages from a Topic To receive a message from a topic, clients create a Consumer object using either the createconsumer() method or the createdurablesubscriber() method from the Session class, depending on whether a non-durable subscriber or a durable subscriber is desired. Non-DurableSubscribers Non-durable subscribers only receive messages that are published on a chosen topic while the subscriber is active. For non-durable subscribers, clients create a consumer object by using the createconsumer() method from the Session class, which has the Consumer::SUBSCRIBER constant as the consumer type. This method uses a topic destination to define the location from which the messages are received. Creating the consumer for a topic (a non-durable subscriber), starting a transaction, receiving the message, and then ending the transaction is shown in this code fragment: char *topicname = MyTopic ; // Creating the Subscriber Consumer *pconsumer = pses->createconsumer(topicname, Consumer::SUBSCRIBER); // Starting Transaction, Receiving the Message BEGINTRANSACTION(); pmsg = pconsumer->receive(3000); ENDTRANSACTION(); Note. The Consumer receive operation must be wrapped within a transaction because the MESSAGE table is audited. Non-durable subscribers automatically terminate themselves, that is, the subscription, when their Session::freeConsumer() method is called. Durable Subscribers Durable subscribers receive all messages published on a topic, including messages published while the subscriber is inactive. For durable subscribers, clients create a durable subscriber object by using the createdurablesubscriber() method from the Session class. This method is similar to creating a non-durable subscriber, except that you pass a client ID and a subscription name to uniquely identify the subscriber. 5-10

62 Using the NSJMS C++ APIs Retrieving Data from a Message Creating the consumer for a topic (a durable subscriber), starting a transaction, receiving the message, and then ending the transaction is shown in this code fragment: char *clientid = MyClientID ; char *subscriptionname = MySubName ; char *topicname = MyTopic ; // Creating a Durable Subscriber Consumer *pconsumer = pses->createdurablesubscriber( clientid, subscriptionname, topicname); // Starting Transaction, Receiving the Message BEGINTRANSACTION(); pmsg = pconsumer->receive(3000); ENDTRANSACTION(); Note. The Consumer receive operation must be wrapped within a transaction because the MESSAGE table is audited. To terminate a durable subscriber use the Session::unsubscribe() method and pass in the Consumer pointer and the unique clientid and subname that created the subscriber. Terminating a durable subscription is shown in this code fragment: // Unsubscribe a Durable Subscription pses->unsubscribe(clientid, subname); Durable subscriptions do not terminate automatically when their Session::freeConsumer() method is called. Only an unsubscribe() operation ends a durable subscription. Subsequent durable subscriber objects that have the same identity can resume the subscription in the state it was left by the prior subscriber by calling createdurablesubscriber() and using a previously used client ID, subscription name, and topic. If no subscriber is active for a durable subscription, NSJMS retains the subscription's messages until they are received by the subscription or until they expire. Retrieving Data from a Message The receive() method returns the same type of message that was sent to the queue. For example, if a StreamMessage is sent to a queue, the receive() method returns an object of type StreamMessage. To pull the content from the body of a message, you must identify the subclass of the message contents, such as TextMessage. If you do not know the subclass of the message contents, use Message::getJMSType() to determine the subclass before retrieving a specific subclass of data from a message as shown in the following code 5-11

63 Using the NSJMS C++ APIs Building NSJMS C++ APIs Client Applications fragments. It is good practice to always test the message class before casting, so that unexpected errors are handled gracefully. // Confirm this is a TextMessage before calling gettext() if (strcmp(pmsg->getjmstype(),"textmessage") == 0) // Confirm this is a BytesMessage before calling readbytes() if (strcmp(pmsg->getjmstype(),"bytesmessage") == 0) // Confirm this is a MapMessage before calling getxxx() if (strcmp(pmsg->getjmstype(),"mapmessage") == 0) // Confirm this is a StreamMessage before calling readxxx() if (strcmp(pmsg->getjmstype(),"streammessage") == 0) /* Confirm this is an ObjectMessage before calling readbytes()*/ if (strcmp(pmsg->getjmstype(),"objectmessage") == 0) Using the getjmstype() when retrieving the contents from a TextMessage is shown in this code fragment: // Starting Transaction, Receiving the Message BEGINTRANSACTION(); pmsg = pconsumer->receive(3000); ENDTRANSACTION(); if (pmsg!= NULL) // Confirm this is a TextMessage before calling gettext() if (strcmp(pmsg->getjmstype(),"textmessage") == 0) char *ptext = (( TextMessage* )pmsg)->gettext(); cout << "Rcv Message: " << ptext << endl; else cout << "Received message was not a TextMessage" << endl; Building NSJMS C++ APIs Client Applications This subsection describes how to compile and link user written C++ programs and run NSJMS C++ API clients that use the NSJMS C++ API classes. See the /usr/tandem/nsjms/t2811-version/examples/makefile, for a working example of compiling and linking NSJMS C++ APIs clients, as described in these subsections. 5-12

64 Using the NSJMS C++ APIs Compiling and Linking User Written C++ Programs for use with the NSJMS C++ API Compiling and Linking User Written C++ Programs for use with the NSJMS C++ API Information about compiling and linking user written C++ programs for use with the NSJMS C++ APIs are described in: Compiling User Written C++ Programs Linking User Written C++ Programs on page 5-14 Detailed descriptions of the compile options and link options can be found in these manuals: nld and noft Manual describes how to use the native link editor (nld) and the native object file tool (noft). C/C++ Programmer's Guide describes how to write C and C++ programs that run in the Open System Services (OSS) environment on NonStop systems. Additionally, the manual describes HP extensions to the C and C++ languages for NonStop servers. Open System Services Shell and Utilities Reference Manual describes the syntax and semantics for using the OSS shell and utilities, which includes c89 and nld. Compiling User Written C++ Programs NSJMS C++ APIs header files are installed in an include subdirectory within the NSJMS C++ APIs installation directory, /usr/tandem/nsjms/t2811-version/include. This include directory must be added to the list of directories searched by c89 during compilation of programs that use the NSJMS C++ APIs classes. The following include statement is required to include the necessary header files for the NSJMS C++ API: #include "nsjmsc.h" 5-13

65 Using the NSJMS C++ APIs Compiling and Linking User Written C++ Programs for use with the NSJMS C++ API The contents of nsjmsc.h are: /** * Copyright (c) Hewlett-Packard Company, * Protected as an unpublished work. * All rights reserved. * * The computer program listings, specifications, and documentation * herein are the property of Hewlett-Packard Company or a third party * supplier and shall not be reproduced, copied, disclosed, or used in * whole or in part for any reason without the prior express written * permission of Hewlett-Packard Company. */ #ifndef NSJMSC_H #define NSJMSC_H #include "BytesMessage.h" #include "Consumer.h" #include "MapMessage.h" #include "Message.h" #include "NSJMSException.h" #include "ObjectMessage.h" #include "Producer.h" #include "Session.h" #include "StreamMessage.h" #include "TextMessage.h" #endif The NSJMS C++ APIs classes use exceptions, and therefore require the c89 flag -Wversion2 to be specified for compilation of the program. Use the try-catch construct to handle exceptions thrown by the NSJMS C++ API. For CAPI_HOME=/usr/tandem/nsjms/T2811-version, other required c89 options are: -I $(CAPI_HOME)/include -D_XOPEN_SOURCE_EXTENDED=1 -Wsystype=oss -WIEEE_float -Wextensions -Wcplusplus -Wversion2 If loading yjmscdll, then we must additionally provide the following option: -Wlp64 Linking User Written C++ Programs A /lib directory containing the archive file required for building programs using the NSJMS C++ APIs classes is included in the installed NSJMS directory, /usr/tandem/nsjms/t2811-version/lib/libnsjmsc.a. This archive file must be added to the list of libraries included by nld during the linkage of programs that use the NSJMS C++ APIs classes. 5-14

66 Using the NSJMS C++ APIs Running User Written C++ Programs To include the libnsjmsc.a archive file when building the user code, add the following two options: -lnsjmsc -L$(CAPI_HOME)/lib The -lnsjmsc option searches for a library named libnsjmsc.a. The lib at the beginning of the name, and the.a at the end are implied. -lztlhsrl -lzrwslsrl -lzclisrl -lzcplsrl These TNS/R shared run-time libraries (SRLs) are required. For CAPI_HOME=/usr/tandem/nsjms/T2811-version, other required nld options are: -elf -set systype oss -obey /usr/lib/libc.obey /usr/lib/crtlmain.o -lztlhsrl -lzrwslsrl -lzclisrl -lzcplsrl -lnsjmsc -L$(CAPI_HOME)/lib Running User Written C++ Programs The steps required to run NSJMS C++ APIs client, are similar to those outlined for running the example programs in Section 2, Installation and Configuration for TNS/R. Add the queues and/or topics needed by the client to the database by using the NSJMS administrative utility. Have an NSJMS properties file in the location designated in the Session constructor propertyfile argument. For example, pses = new Session("/dir/subdir/nsjms.properties"); In all the example programs, this location is NSJMS_HOME. Run the client by issuing the run program_file_path [arguments] command. For example, run SimpleSender -queue q1 -count

67 Using the NSJMS C++ APIs Running User Written C++ Programs 5-16

68 6 NSJMS C++ API Sample Client Applications This section contains NSJMS C++ API sample client applications along with brief descriptions of the Point-to-Point (PTP) and Publish/Subscribe (Pub/Sub) messaging models. Source code files for the sample client applications described in this section are provided as part of the NSJMS C++ API software package. They reside (by default) in the /usr/tandem/nsjms/t2811-version/examples directory. Note that the sample client applications are subject to change in future release version updates (RVUs). Note. For details about how to compile and bind programs written in the HP C++ programming language, see Building NSJMS C++ API Client Applications on page 5-12 or the C/C++ Programmer s Guide. PTP Sample Applications A PTP messaging application is a one-to-one messaging model which uses queues for messaging destinations. A message is sent by a sending client to a specific queue where the message can be received by the receiving client. A queue retains a message until it is received by the receiving client or until the message expires. You can use the SimpleSender.cpp and SimpleReceiver.cpp on page 6-4 sample client applications to demonstrate basic PTP sending and receiving of messages using the NSJMS C++ API. SimpleSender.cpp This SimpleSender.cpp sample client application creates a Session and a Producer, and begins to publish messages. The application expects a Queue Name and a Message Count as arguments. If a Queue Name and a Message Count are not specified, an exception is raised. 6-1

69 NSJMS C++ API Sample Client Applications SimpleSender.cpp Example 6-1. SimpleSender.cpp Sample Client Application (page 1 of 3) /** * * Copyright (c) Hewlett-Packard Company, * Protected as an unpublished work. * All rights reserved. * * The computer program listings, specifications, and documentation herein * are the property of Hewlett-Packard Company or a third party supplier and * shall not be reproduced, copied, disclosed, or used in whole or in part * for any reason without the prior express written permission of * Hewlett-Packard Company. */ #include <unistd.h> #include <libgen.h> #include <strstream.h> #include <cextdecs.h(juliantimestamp,begintransaction,endtransaction)> #include "nsjmsc.h" const static int PRIORITY = 1; bool qgiven = FALSE; bool persistent = false; int deliverymode = DELIVERYMODE_NONPERSISTENT; unsigned long msgcount = 10; char* destname; Session* pses; Producer* pproducer; TextMessage* pmsg; /** * Print out information on running this sevice */ void usage(char * appname) cerr<<" Usage: "<<basename(appname)<<" [options]"<<endl; cerr<<" -queue <string> Queue destination name"<<endl; cerr<<" -count <number> Number of messages to send (10)"<<endl; cerr<<" -persistent Specifies persistent delivery mode"<<endl; cerr<<" -help This Message"<<endl; return; /** * Sends a message to the destination. */ int send_message() try // Use an environment variable to dynamically assign a directory char *propfile = getenv( NSJMS_HOME ); strcat(propfile, /nsjms.properties ); pses = new Session(propFile); /* Create a new session using a properties file in the current working directory*/ /*********************************************** pses = new Session("nsjms.properties"); ***********************************************/ 6-2

70 NSJMS C++ API Sample Client Applications SimpleSender.cpp Example 6-1. SimpleSender.cpp Sample Client Application (page 2 of 3) // Creating the Producer. pproducer = pses->createproducer(destname); for (unsigned long count = 0; count < msgcount; count++) strstream msg; // Setting Message msg<<"sending message "<<count<<ends; cout << msg.str() << endl; // Creating Test Message pmsg = pses->createtextmessage(); pmsg->setstringproperty("test","simplesender"); // Setting Text pmsg->settext (msg.str()); // Starting Transaction Sending the Message BEGINTRANSACTION(); pproducer->send(pmsg, deliverymode,priority,default_jmsexpiration); ENDTRANSACTION(); // Freeing Message pses->freemessage(pmsg); pmsg = NULL; long long end = JULIANTIMESTAMP(); long long perf = (juliantomillis(end) - juliantomillis(start)); cout<<"finished Sending "<<msgcount<<" messages, took "<< perf << " msecs"<<endl; //Freeing the producer object. pses->freeproducer(pproducer); delete pses; catch(nsjms_exception & excp) cout << "NSJMS_Exception: " << excp.getclassname() << ", " << excp.getmessage() << endl; pses->freemessage(pmsg); pses->freeproducer(pproducer); return 1; catch (exception & excp) cout << excp.what() << endl; return 1; return 0; int main(int argc, char *argv[]) int optind; for (optind = 0; optind < argc; optind++) 6-3

71 NSJMS C++ API Sample Client Applications SimpleReceiver.cpp Example 6-1. SimpleSender.cpp Sample Client Application (page 3 of 3) if (strcmp(argv[optind],"-help") == 0) usage(basename(argv[0])); return 1; else if (strcmp(argv[optind],"-queue") == 0) destname=strdup(argv[++optind]); qgiven=true; else if (strcmp(argv[optind],"-persistent") == 0) persistent = true; else if (strcmp(argv[optind],"-count") == 0) msgcount = atol(argv[++optind]); else if (strcmp(argv[optind],"-") == 0) usage(basename(argv[0])); return 1; if (qgiven == FALSE) usage(basename(argv[0])); return 1; if (persistent) deliverymode = DELIVERYMODE_PERSISTENT; if (!send_message()) cout<< "Message Send successful"<< endl; return 0; else cout<<"message Send Failed" << endl; return 1; return 0; SimpleReceiver.cpp This SimpleReceiver.cpp sample client application waits for a specified number of messages from a specific queue and then exits. 6-4

72 NSJMS C++ API Sample Client Applications SimpleReceiver.cpp Example 6-2. SimpleReceiver.cpp Sample Client Application (page 1 of 3) /** * * Copyright (c) Hewlett-Packard Company, * Protected as an unpublished work. * All rights reserved. * * The computer program listings, specifications, and documentation herein * are the property of Hewlett-Packard Company or a third party supplier and * shall not be reproduced, copied, disclosed, or used in whole or in part * for any reason without the prior express written permission of * Hewlett-Packard Company. */ #include <unistd.h> #include <libgen.h> #include <cextdecs.h(juliantimestamp,begintransaction,endtransaction)> #include "nsjmsc.h" bool qgiven = FALSE; unsigned long msgcount=10; char *destname; Session* pses; Consumer* pconsumer; Message* pmsg; /** * Print out information on running this sevice */ void usage(char * appname) cerr<<" Usage: "<<basename(appname)<<" [options]"<<endl; cerr<<" -queue <string> Queue destination name"<<endl; cerr<<" -count <number> Number of messages to receive (10)"<<endl; cerr<<" -help This message"<<endl; return; /** * Receives a message from the destination. */ int receive_message() try // Use an environment variable to dynamically assign a directory char *propfile = getenv( NSJMS_HOME ); strcat(propfile, /nsjms.properties ); pses = new Session(propFile); /* Create a new session using a properties file in the current working directory*/ /*********************************************** pses = new Session("nsjms.properties"); ***********************************************/ 6-5

73 NSJMS C++ API Sample Client Applications SimpleReceiver.cpp Example 6-2. SimpleReceiver.cpp Sample Client Application (page 2 of 3) // Creating the Consumer. pconsumer = pses->createconsumer(destname, Consumer::RECEIVER); cout << "Receiver has been set" << endl; long long start = 0; for(int count = 0; count < msgcount; ) // Starting Transaction, Receiving the Message BEGINTRANSACTION(); pmsg = pconsumer->receive(3000); ENDTRANSACTION(); if (pmsg!= NULL) if (strcmp(pmsg->getjmstype(),"textmessage") == 0) char * ptext = ((TextMessage * )pmsg)->gettext(); cout<< "Rcv Message: " << ptext<<endl; delete[] ptext; pses->freemessage(pmsg); pmsg = NULL; count++; else /* This test can stop only after finishing the intervals requested.*/ cout << "No message found, 3 sec delay... " << endl; //end for long long end = JULIANTIMESTAMP(); long long perf = (juliantomillis(end) - juliantomillis(start)); cout<<"finished Receiving "<<msgcount<<" messages, took "<< perf << " msecs"<<endl; pses->freeconsumer(pconsumer); catch (NSJMS_Exception & excp) cout << "NSJMS_Exception: " << excp.getclassname() << ", " << excp.getmessage() << endl; pses->freemessage(pmsg); pses->freeconsumer(pconsumer); return 1; catch(exception & excp) cout << excp.what() << endl; return 1; return 0; int main(int argc, char* argv[]) int optind; for (optind = 0; optind < argc; optind++) 6-6

74 NSJMS C++ API Sample Client Applications SimpleReceiver.cpp Example 6-2. SimpleReceiver.cpp Sample Client Application (page 3 of 3) if (strcmp(argv[optind],"-help") == 0) usage(basename(argv[0])); return 1; else if (strcmp(argv[optind],"-queue") == 0) destname=strdup(argv[++optind]); qgiven=true; else if (strcmp(argv[optind],"-count") == 0) msgcount = atol(argv[++optind]); else if (strcmp(argv[optind],"-") == 0) usage(basename(argv[0])); return 1; if (qgiven == FALSE) usage(basename(argv[0])); return 1; if (!receive_message()) cout<<"receive Message Successful" << endl; return 0; else cout<<"receive Message Failed" << endl; return 1; return 1; 6-7

75 NSJMS C++ API Sample Client Applications Pub/Sub Sample Applications Pub/Sub Sample Applications A Pub/Sub messaging application is a one-to-many messaging model that uses topics for messaging destinations. A message is published by a sending client to a topic where any receiving client who is subscribed to the topic can receive the message. A topic retains a message until the message expires. You can use the SimplePublisher.cpp on page 6-8 and SimpleConsumer.cpp on page 6-11 client applications to demonstrate basic Pub/Sub sending and receiving of messages using the NSJMS C++ API. SimplePublisher.cpp This SimplePublisher.cpp sample client application creates a Session and a Producer, and begins to publish messages. The application expects a Topic Name to be specified on the command line. If a Topic Name is not specified, an exception is raised. 6-8

76 NSJMS C++ API Sample Client Applications SimplePublisher.cpp Example 6-3. SimplePublisher.cpp Sample Client Application (page 1 of 3) /** * * Copyright (c) Hewlett-Packard Company, * Protected as an unpublished work. * All rights reserved. * * The computer program listings, specifications, and documentation herein * are the property of Hewlett-Packard Company or a third party supplier and * shall not be reproduced, copied, disclosed, or used in whole or in part * for any reason without the prior express written permission of * Hewlett-Packard Company. */ #include <unistd.h> #include <libgen.h> #include <strstream.h> #include <cextdecs.h(juliantimestamp,begintransaction,endtransaction)> #include "nsjmsc.h" const static int PRIORITY = 1; bool tgiven = FALSE; bool persistent = false; int deliverymode = DELIVERYMODE_NONPERSISTENT; unsigned long msgcount = 10; char *destname; Session * pses; Producer* pproducer; TextMessage* pmsg; /** * Print out information on running this sevice */ void usage(char * appname) cerr<<" Usage: "<<basename(appname)<<" [options]"<<endl; cerr<<" -topic <string> Topic destination name"<<endl; cerr<<" -count <number> Number of messages to send (10)"<<endl; cerr<<" -persistent Specifies persistent delivery mode"<<endl; cerr<<" -help This Message"<<endl; return; /** * Sends a message to the destination. */ int send_message() try // Use an environment variable to dynamically assign a directory char *propfile = getenv( NSJMS_HOME ); strcat(propfile, /nsjms.properties ); pses = new Session(propFile); /* Create a new session using a properties file in the current working directory*/ /*********************************************** pses = new Session("nsjms.properties"); ***********************************************/ 6-9

77 NSJMS C++ API Sample Client Applications SimplePublisher.cpp Example 6-3. SimplePublisher.cpp Sample Client Application (page 2 of 3) // Creating the Producer. pproducer = pses->createproducer(destname); long long start = JULIANTIMESTAMP(); for (unsigned long count = 0; count < msgcount; count++) strstream msg; // Setting Message msg<<"publishing this message " << count << ends; cout << msg.str() << endl; // Creating Test Message pmsg = pses->createtextmessage(); // Setting Text pmsg->settext (msg.str()); // Starting Transaction Sending the Message BEGINTRANSACTION(); pproducer->send(pmsg, deliverymode, PRIORITY, DEFAULT_JMSEXPIRATION); ENDTRANSACTION(); pses->freemessage(pmsg); pmsg = NULL; long long end = JULIANTIMESTAMP(); long long perf = (juliantomillis(end) - juliantomillis(start)); cout<<"finished Publishing "<<msgcount<<" messages, took "<< perf << " msecs"<<endl; //Freeing the producer object. pses->freeproducer(pproducer); delete pses; catch (NSJMS_Exception & excp) cout << "NSJMS_Exception: " << excp.getclassname() << ", " << excp.getmessage() << endl; pses->freemessage(pmsg); pses->freeproducer(pproducer); return 1; catch (exception & excp) cout << excp.what() << endl; return 1; return 0; int main(int argc, char* argv[]) int optind; for (optind = 0; optind < argc; optind++) 6-10

78 NSJMS C++ API Sample Client Applications SimpleConsumer.cpp Example 6-3. SimplePublisher.cpp Sample Client Application (page 3 of 3) if (strcmp(argv[optind],"-help") == 0) usage(basename(argv[0])); return 1; else if (strcmp(argv[optind],"-topic") == 0) destname=strdup(argv[++optind]); tgiven=true; else if (strcmp(argv[optind],"-persistent") == 0) persistent = true; else if (strcmp(argv[optind],"-count") == 0) msgcount = atol(argv[++optind]); else if (strcmp(argv[optind],"-") == 0) usage(basename(argv[0])); return 1; if (tgiven == FALSE) usage(basename(argv[0])); return 1; if (persistent) deliverymode = DELIVERYMODE_PERSISTENT; if (!send_message()) cout<<"message Sending successful" << endl; return 0; else cout<<"message Send Failed" << endl; return 1; return 0; SimpleConsumer.cpp This SimpleConsumer.cpp sample client application creates a Session and then creates a Consumer or Durable Subscriber. The application expects a Topic Name, Message Count, and optionally a Durable Subscriber name and Client ID. If a Topic Name is not specified, an exception is raised. 6-11

79 NSJMS C++ API Sample Client Applications SimpleConsumer.cpp Example 6-4. SimpleConsumer.cpp Sample Client Application (page 1 of 3) /** * * Copyright (c) Hewlett-Packard Company, * Protected as an unpublished work. * All rights reserved. * * The computer program listings, specifications, and documentation herein * are the property of Hewlett-Packard Company or a third party supplier and * shall not be reproduced, copied, disclosed, or used in whole or in part * for any reason without the prior express written permission of * Hewlett-Packard Company. */ #include <unistd.h> #include <libgen.h> #include <cextdecs.h(juliantimestamp,begintransaction,endtransaction)> #include "nsjmsc.h" bool tgiven = FALSE; bool durable=false; int msgcount=10; unsigned long msgsize = 128; unsigned long messages_received = 0; char *destname,*subname, *clientid; Session* pses; Consumer* pconsumer; Message* pmsg; /** * Print out information on running this sevice */ void usage(char * appname) cerr<<" Usage: "<<basename(appname)<<" [options]"<<endl; cerr<<" -topic <string> Topic destination name"<<endl; cerr<<" -name <string> Durable Subscriber subscription name"<<endl; cerr<<" -id <string> Durable Subscriber client id"<<endl; cerr<<" -count <number> Number of messages to receive (10)"<<endl; cerr<<" -help This Message"<<endl; return; /** * Receives a message from the destination. */ int receive_message() try pses = NULL; pconsumer = NULL; pmsg = NULL; // Use an environment variable to dynamically assign a directory char *propfile = getenv( NSJMS_HOME ); strcat(propfile, /nsjms.properties ); pses = new Session(propFile); 6-12

80 NSJMS C++ API Sample Client Applications SimpleConsumer.cpp Example 6-4. SimpleConsumer.cpp Sample Client Application (page 2 of 3) /* Create a new session using a properties file in the current working directory*/ /*********************************************** pses = new Session("nsjms.properties"); ***********************************************/ // Creating the Consumer. if (durable) pconsumer = pses->createdurablesubscriber(clientid, subname, destname); else pconsumer = pses->createconsumer(destname, Consumer::SUBSCRIBER); cout << "Consumer has been set" << endl; long long start = 0; for(int count = 0; count < msgcount; ) // Starting Transaction, Receiving the Message BEGINTRANSACTION(); pmsg = pconsumer->receive(3000); ENDTRANSACTION(); if (pmsg!= NULL) if (strcmp(pmsg->getjmstype(), TextMessage ) == 0) char * ptext = ((TextMessage * )pmsg)->gettext(); cout<<"received message #"<< count << ": " << ptext << endl; delete[] ptext; pses->freemessage(pmsg); pmsg = NULL; count++; else /* This test can stop only after finishing the intervals requested.*/ cout << "No message found, 3 sec delay... " << endl; //end for long long end = JULIANTIMESTAMP(); long long perf = (juliantomillis(end) - juliantomillis(start)); cout<<"finished Consuming "<<msgcount<<" messages, took "<< perf << " msecs"<<endl; if (durable) pses->unsubscribe(clientid, subname); pses->freeconsumer(pconsumer); catch (NSJMS_Exception & excp) cout << "NSJMS_Exception: " << excp.getclassname() << ", " << excp.getmessage() << endl; pses->freemessage(pmsg); if (durable) pses->unsubscribe(clientid, subname); pses->freeconsumer(pconsumer); return 1; 6-13

81 NSJMS C++ API Sample Client Applications SimpleConsumer.cpp Example 6-4. SimpleConsumer.cpp Sample Client Application (page 3 of 3) catch(exception & excp) cout << excp.what() << endl; return 1; return 0; int main(int argc, char* argv[]) int optind; for (optind = 0; optind < argc; optind++) if (strcmp(argv[optind],"-help") == 0) usage(basename(argv[0])); return 1; else if (strcmp(argv[optind],"-topic") == 0) destname=strdup(argv[++optind]); tgiven=true; else if (strcmp(argv[optind],"-id") == 0) clientid = strdup(argv[++optind]); durable = true; else if (strcmp(argv[optind],"-name") == 0) subname = strdup(argv[++optind]); durable = true; else if (strcmp(argv[optind],"-count") == 0) msgcount = atol(argv[++optind]); else if (strcmp(argv[optind],"-") == 0) usage(basename(argv[0])); return 1; if (tgiven == FALSE) usage(basename(argv[0])); return 1; if (!receive_message()) cout<<"receiving Message Completed" << endl; return 0; else cout<<"receiving message has failed" << endl; return 1; return 1; 6-14

82 7 Managing the NSJMS C++ API Environment The NSJMS C++ API shares the NSJMS environment, and the NSJMS administrative utility is used to manage the NSJMS and the NSJMS C++ API environments. The NSJMS administrative utility is documented in the NonStop Server for Java Message Service User s Manual. NSJMS Administrative Utility Commands and Attributes for the NSJMS C++ API COMMAND ATTRIBUTES ADD QUEUE name, EXPIRY millisecs, ID dest-id ADD TOPIC name, EXPIRY millisecs, ID dest-id ALTER QUEUE name, EXPIRY millisecs ALTER TOPIC name, EXPIRY millisecs DELETE QUEUE name * DELETE TOPIC name * DELETE MESSAGE id queue-name topic-name expired * DELETE SUBSCRIPTION client-id, subscription-name * EXIT HELP command INFO QUEUE name * INFO TOPIC name * INFO MESSAGE id queue-name topic-name expired * INFO SUBSCRIPTION client-id, subscription-name * For detailed NSJMS administrative utility command descriptions, syntax, and usage, see the NonStop Server for Java Message Service User s Manual. 7-1

83 Managing the NSJMS C++ API Environment NSJMS Administrative Utility Commands and Attributes for the NSJMS C++ API 7-2

84 8 Troubleshooting Recovering from SQL/MX Exceptions The SQL/MX exception condition messages listed below are retryable within the context of the NSJMS C++ API as shown in Recovering within Producer::send() Operations on page 8-1 and Recovering within Consumer::receive() Operations on page 8-2. SQL The operation is prevented by a unique constraint. Cause. You attempted to perform an operation that is prevented by a unique constraint. This is sometimes referred to as a duplicate key error. Effect. SQL/MX could not perform the operation. Recovery. Make the data you enter unique to be consistent with the constraint. SQL Error NSK_err was returned by the Distribution Service on detail_text. Cause. The Distribution Service returned error NSK_err on detail text. Effect. SQL/MX is unable to run the statement. Recovery. Use the error in the message to diagnose and correct the problem. When 73 is returned by NSK_err, this indicates the disk file or record is locked. Because there are numerous types of errors that can be returned to a client, the NSJMS C++ API internals will return 73 from a call to NSJMS_SQLError::getErrorCode() to differentiate between an -8551/73 error and other -8551/nnn errors. Recovering within Producer::send() Operations Producer::send() operations will occasionally encounter SQL and SQL and should be retried. Using the retry logic is shown in this code fragment: const static int RETRYCNT=100; for (int dupcount=0; dupcount<retrycnt; dupcount++) try // Starting Transaction, Sending the Message BEGINTRANSACTION(); pproducer->send(pmsg, deliverymode, PRIORITY, DEFAULT_JMSEXPIRATION); ENDTRANSACTION(); 8-1

85 Troubleshooting Recovering within Consumer::receive() Operations break; catch (NSJMS_Exception& sqle) int sqlcode = sqle.geterrorcode(); if (sqle.geterrorcode() == DUPLICATE_ROW ) //-8102 ABORTTRANSACTION(); continue; if (sqle.geterrorcode() == RECORD_LOCK ) //73 ABORTTRANSACTION(); DELAY(10); // wait.1 sec continue; else throw sqle; //end for dupcount Recovering within Consumer::receive() Operations Consumer::receive() operations, will occasionally encounter SQL and should be retried. Using the retry logic is shown in this code fragment: const static int RETRYCNT=100; for (int dupcount=0; dupcount<retrycnt; dupcount++) try // Starting Transaction, Sending the Message BEGINTRANSACTION(); pmsg = pconsumer->receive(3000); ENDTRANSACTION(); break; catch (NSJMS_Exception& sqle) int sqlcode = sqle.geterrorcode(); if (sqle.geterrorcode() == RECORD_LOCK ) //73 ABORTTRANSACTION(); DELAY(10); // wait.1 sec continue; else throw sqle; //end for dupcount 8-2

86 Troubleshooting Debugging NSJMS C++ API Client Applications Debugging NSJMS C++ API Client Applications To debug an NSJMS C++ API client application, start an NSJMS C++ API client within an Inspect session by issuing the run -debug program_file_path [arguments] command. The operating system first starts the process in the hold state then starts the Inspect debugging tool, at which time you can set breakpoints and step through code statements. For example: TACL: run -debug SimpleSender -queue q1 -count 5 INSPECT - Symbolic Debugger - T9673D40 - (30APR03) System \POOH Copyright Tandem Computers Incorporated 1983, INSPECT 201,03,00345 SimpleSender #main.#118(simplesender.cpp) -SimpleSender- Detailed descriptions about using the Inspect debugging tool to debug client applications can be found in the Inspect Manual Tracing NSJMS C++ API Client Applications To enable tracing of an NSJMS C++ API client application, use the following NSJMS properties located in the nsjms.properties file. Logger.loglevel Logger.type Logger.filename Logger.loglevel The Logger.loglevel property uses the following case-sensitive keywords to specify the level of messages that are returned to the log file. The information returned by each keyword is: 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. A log level of error displays messages that have log levels of fatal and error warning Logs messages that do not effect the integrity of the JMS client but should be brought to the JMS client s attention. warning is the default. A log level of warning displays messages that have log levels of fatal, error, and warning. info Logs messages that do not imply an error but could indicate an important event, such as a message that the JMS client is connected. A log level of info displays messages that have log levels of fatal, error, warning, and info. 8-3

87 Troubleshooting Logger.type debug Logs messages useful during a debugging session. Setting Logger.loglevel to debug can substantially degrade performance and should be used only when requested by support personnel. A log level of debug displays all levels of messages: fatal, error, warning, info, and debug. Logger.type The Logger.type property uses these case-sensitive keywords to specify where to direct the output collected in the log file. FileLogger Events will be logged to the disk file specified in Logger.filename. FileLogger is the default. ConsoleLogger Events will be logged to the console, typically the client hometerm. Logger.filename The Logger.filename property uses these case-sensitive keywords to specify the name of the log file where messages are posted. nsjmscapi.log The default file location that contains the log information anyfilename The user specified file location that contains the log information. Sample Log Output Setting the logger.loglevel property to debug, the logger.filename to nsjmscapi.log, and the logger.type to ConsoleLogger will produce output similar to this sample log output 08:05: DEBUG [2,177] - Session::Session, property file: /usr/tandem/nsjmsv30/nsjms.properties, log file: ConsoleLogger, trace level: debug 08:05: DEBUG [2,177] - Consumer::setDeadMsgDeleteCountProp, deadmsgdeletecountprop set to: :05: DEBUG [2,177] - Session::Session: setup() called using: $data02.sbnsjms, 3000, returned: 1 08:05: DEBUG [2,177] - Producer::Producer constructor, dest: q1 Sending message 0 08:05: DEBUG [2,177] - Producer::send(msg,mode: 1,pri: 1,timeToLive: 0) 08:05: DEBUG [2,177] - Producer::send, msglen: 110, msg_id: Sending message 1 08:05: DEBUG [2,177] - Producer::send(msg,mode: 1,pri: 1,timeToLive: 0) 08:05: DEBUG [2,177] - Producer::send, msglen: 110, msg_id: :05: DEBUG [2,177] - Producer::~Producer destructor 08:05: DEBUG [2,177] - Session::~Session: destructor Message Send successful For additional information on these NSJMS properties, see the NSJMS Properties File on page 2-9 or the NonStop Server for Java Message Service User s Manual. 8-4

88 A Error Reporting and Messages This appendix provides information about JMS API error messages, the NSJMS C++ API logging facility, and the NSJMS C++ API exception types. JMS API Error Messages JMS API error messages and exceptions are described in the Sun Microsystems published specification, Java Message Service, Version The specification is available on the Sun Microsystems Java Message Service (JMS) web site ( NSJMS C++ API Logging Facility All log records generated by the NSJMS C++ API are contained in the nsjmscapi.log file. The type of records generated by the NSJMS C++ API is determined by the Logger.loglevel setting in the nsjms.properties file. For a description of the level of records that can be generated and reported to the nsjmscapi.log file, see Logger.loglevel on page 8-3 or the NonStop Server for Java Message Service User s Manual. Client programs should be written to catch the exceptions and handle them appropriately. If an exception is not handled, the default behavior is termination of the program. NSJMS C++ API Exception Types Exception types are thrown when error conditions occur. The following exception types are defined by the NSJMS C++ API. NSJMS_Exception NSJMS_Exception is the base class of all exception classes. It includes the following access methods to retrieve messages and codes for exception types. int geterrorcode(); char * getmessage(); Additionally, NSJMS_Exception also includes these methods: void setlinkedexception(exception *); which adds a linked exception. exception* getlinkedexception(); which gets the exception linked to this exception. char* getclassname(); which returns the name of the exception subclass. A-1

89 Error Reporting and Messages NSJMS_NoSuchProperty NSJMS_NoSuchProperty NSJMS_NoSuchProperty is thrown when a method attempts to read a non-existent property. NSJMS_InvalidConversion NSJMS_InvalidConversion is thrown when a get method attempts to read a property using an access type which does not match the property type. NSJMS_SQLError NSJMS_SQLError is thrown when a SQL error is returned by the method. The SQLCODE may be retrieved using the geterrorcode() method. NSJMS_InvalidClientID NSJMS_InvalidClientID exception must be thrown when a client attempts to set a client ID to a value that is rejected by a provider. NSJMS_InvalidDestination NSJMS_InvalidDestination exception must be thrown when a destination is not understood by a provider or is no longer valid. NSJMS_MessageFormatException NSJMS_MessageFormatException exception must be thrown when an NSJMS client attempts to use a data type that is not supported by that type of message. It must also be thrown when equivalent errors are made with message property values. NSJMS_IllegalStateException NSJMS_IllegalStateException exception is thrown when a method is invoked at an illegal or inappropriate time or if the provider is not in an appropriate state for the requested operation. NSJMS_NullPointerException NSJMS_NullPointerException exception must be thrown when a JMS client attempts to use a null pointer. NSJMS_MemoryAllocationException NSJMS_MemoryAllocationException exception must be thrown when a memory allocation problem occurs in the system. A-2

90 Glossary 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. An item of descriptive data associated with a command-line tool command or XML element. An attribute has a name and a value. client. A software process, hardware device, or combination of the two that requests services from a server. Often, the client is a process residing on a programmable workstation and is the part of a program that provides the user interface. The workstation client might also perform other portions of the program logic. Distributed Systems Management/Software Configuration Manager (DSM/SCM). A GUI-based program that installs new software and creates a new operating system. DSM/SCM creates a new software revision and activates the new software on the target system. See Distributed Systems Management/Software Configuration Manager (DSM/SCM). DSM/SCM. See Distributed Systems Management/Software Configuration Manager (DSM/SCM) 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. An environment available for interactive or programmatic use with the operating system. Processes that run in the Guardian environment usually use the Guardian system procedure calls as their application program interface; interactive users of the Guardian environment usually use the HP Tandem Advanced Command Language (TACL) or another HP product s command interpreter. Contrast with Open System Services (OSS). HP NonStop operating system. The operating system for HP NonStop systems. HP Tandem Advanced Command Language (TACL). The user interface to the operating system. The TACL product is both a command interpreter and a command language. Users can write TACL programs that perform complex tasks or provide a consistent user interface across independently programmed applications. Glossary-1

91 Glossary interface interface. In general, the point of communication or interconnection between one person, program, or device and another, or a set of rules for that interaction. See also application program interface (API). 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) C++ API. JMS. See Java Message Service (JMS). JMS client. A user-written application used to produce and consume messages. JMS provider. A messaging system that implements the JMS API and includes administrative and management functionality (See NonStop Server for Java Message Service (NSJMS) C++ API). Makefile. In a UNIX or OSS environment, a script used to build an application process. message. A request, report, or event that is created, sent, and received by JMS clients. MessageConsumer. An object used for receiving messages sent to a destination. MessageProducer. An object used for sending messages to a destination. 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 C++ API. See NonStop Server for Java Message Service (NSJMS) C++ API. Open System Services (OSS). A POSIX-compliant operating environment for NonStop systems. OSS. See Open System Services (OSS). PTP. See point-to-point message system (PTP). Pub/Sub. See publish/subscribe message system (Pub/Sub). point-to-point message system (PTP). A messaging application based on a one-to-one messaging model which uses queues for messaging destinations. A message is sent by a sending client to a specific queue where the message can be received by the receiving client. publish/subscribe message system (Pub/Sub). A messaging application based a one-tomany messaging model which uses topics for messaging destinations. A message is published by a sending client to a topic where any receiving client who is subscribed to the topic will receive the message. Glossary-2

92 Glossary queue queue. A destination for a message in a PTP messaging system. scalability. The ability to increase the size and processing power of an online transaction processing system by adding processors and devices to a system, systems to a network, and so on, and to do so easily and transparently without bringing systems down. Sometimes called expandability. session. A context for JMS clients to send and receive messages. 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. TACL. See HP Tandem Advanced Command Language (TACL). throw. C++ keyword used to raise an exception. TMF. See Transaction Management Facility (TMF). TNS. Denotes fault-tolerant HP computers that: Support the operating system Are based on microcoded complex instruction-set computing (CISC) technology. TNS systems run the TNS instruction set. Contrast with TNS/R and TNS/E. TNS/E. Denotes fault-tolerant HP computers that support the operating system and that are based on the Intel Itanium processor-based architecture. TNS/E systems run the Itanium instruction set and can run TNS object files by interpretation or after acceleration. TNS/E systems include all HP systems that use NSAL-x processors. Contrast with TNS and TNS/R. TNS/R. Denotes fault-tolerant HP computers that: Support the operating system Are based on 32-bit reduced instruction-set computing (RISC) technology. TNS/R systems run the MIPS-1 RISC instruction set and can run TNS object files by interpretation or after acceleration. TNS/R systems include all HP systems that use NSR-x processors. Contrast with TNS and TNS/E. 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). A set of HP software products that assures database integrity by preventing incomplete updates to a database. It can continuously save the changes that are made to a database (in real time) and back out these changes when necessary. It can also take online snapshot backups of the database and restore the database from these backups. Glossary-3

93 Glossary Transaction Management Facility (TMF) Glossary-4

94 Index A administrative utility applicable NSJMS C++ API commands 7-1 tracing client applications 8-3 B building client applications compiling user written C++ programs 5-13 description of 5-12 linking user written C++ programs 5-14 running user written C++ programs 5-15 BytesMessage class 4-2 C classes and methods 4-1 client application debugging 8-3 defined 1-2 SimpleConsumer.cpp 6-11 SimplePublisher.cpp 6-8 SimpleReceiver.cpp 6-4 SimpleSender.cpp 6-1 tracing 8-3 client messaging components 1-1 Consumer class 4-2, 5-9 D debugging client applications 8-3 destinations description of 5-1 destination IDs 5-1 destination names 5-1 establishing 5-1 developing client applications creating a session 5-3 description of 5-2 populating a message with data 5-3 receiving a message 5-9 retrieving data from a message 5-11 sending a message 5-5 directory structure 2-8, 3-9 E error messages, JMS API A-1 error reporting exception types A-1 logging facility A-1 exception types A-1 F features and functions 1-1 freeing resources consumer 5-9 message 5-5 producer 5-8 I Install 2-6, 3-6 installation process description of 2-1, 3-1 when not using DSM/SCM 2-3, 3-3 when using DSM/SCM 2-3, 3-3 interoperability with NSJMS 1-2 introduction 1-1 IPSetup program, running 2-2, 3-2 M managing the NSJMS C++ API using the NSJMS administrative utility 7-1 Index-1

95 Index N managing transactions 5-2 MapMessage class 4-2 message delivery mode 5-7 expiration value 5-7 priority 5-7 removal from a queue 5-8 removal from a topic 5-8 Message class description of 4-3 message body 5-5 message header 5-4 message properties 5-4 messaging models PTP 6-1 Pub/Sub 6-8 N NonStop SQL/MX 1-2 NSJMS administrative utility 7-1 properties file 2-9, 3-9 NSJMS C++ API Library 1-2 O ObjectMessage class 4-4 P Producer class 4-5, 5-6 properties file 2-9, 3-9 PTP messaging application 6-1 Pub/Sub messaging application 6-8 Q queue creating a sample 2-6, 3-7 sending a message to 5-6 R receiving messages from a queue 5-9 from a topic 5-10 requirements disk space 2-1, 3-1 hardware 2-1, 3-1 software 2-1, 3-1 S Session class 4-5 SimpleConsumer.cpp 6-11 SimplePublisher.cpp 6-8 SimpleReceiver.cpp 6-4 SimpleSender.cpp 6-1 SQL/MX exceptions, recovering from 8-1 StreamMessage class 4-6 subscribers durable 5-10 non-durable 5-10 supported platform 1-1 T TextMessage class 4-7 topic creating a sample 2-6, 3-7 sending a message to 5-6 tracing client applications 8-3 transactions, managing 5-2 U uninstalling the NSJMS C++ API 2-10, 3-10 unpaxing product files description of 2-3, 3-3 using COPYOSS 2-5, 3-5 using DSM/SCM 2-3, 3-3 using DSM/SCM and PINSTALL 2-4, 3-4 Index-2