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