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

(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 H06.25.00 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

(3)

Document History

Part Number Product Version Published

526459-001 NSJMS 3.0 November 2003

526459-002 NSJMS 3.0 April 2005

(4)

Legal Notices

Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

The information contained herein is subject to change without notice. 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.

© 1987, 1988, 1989 Carnegie-Mellon University. © 1989, 1990, 1991 Digital Equipment Corporation. © 1985, 1988, 1989, 1990 Encore Computer Corporation. © 1988 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. © 1988 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,

(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 v About This Manual vii

Overview vii

Who Should Use This Manual vii How This Manual Is Organized vii Related Manuals viii

Notation Conventions viii

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 1-2

2. 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

(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 3-10

4. 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 4-7

5. 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

(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 6-11

7. Managing the NSJMS C++ API Environment

NSJMS Administrative Utility Commands and Attributes for the NSJMS C++ API 7-1

8. 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

(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

(10)

What’s New in This Manual

Manual Information

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 H06.25.00 and all subsequent H-series RVUs unless otherwise indicated by it's replacement publication. U64 program does not support G-series RVUs.

Document History

New and Changed Information

Changes for 526459-003 manual:



Updated the section Software on page 2-1.



Part Number Published

526459-003 February 2013

Part Number Product Version Published

526459-001 NSJMS 3.0 November 2003

526459-002 NSJMS 3.0 April 2005

(11)

What’s New in This Manual New and Changed Information



Updated the procedure, Uninstalling the NSJMS C++ API on page 3-11.



Updated the code in the procedure, Compiling User Written C++ Programs on page 5-13.



Updated the “NSJMS C++ API” to “NSJMS C++ APIs” in chapter 5, Using the NSJMS C++ APIs on page 5-1.

Changes for 526459-002 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

(12)

About This Manual

Overview

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 1.0.2.

How This Manual Is Organized

Section Title This section...

1 Introduction to the NSJMS C++ API

Provides an overview of the NSJMS C++ API.

2 Installation and Configuration for TNS/R

Provides installation and configuration details for the NSJMS C++ API for TNS/R.

3 Installation and Configuration for TNS/E

Provides installation and configuration details for the NSJMS C++ API for TNS/E.

4 NSJMS C++ API Classes and Methods

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

Provides NSJMS C++ API sample client applications and brief descriptions of the PTP and Pub/Sub messaging models.

7 Managing the NSJMS C++ API Environment

Provides details on managing the NSJMS C++ API.

8 Troubleshooting Provides details on troubleshooting the NSJMS C++ API.

A Error Reporting and Messages

Provides details on NSJMS C++ API error messages.

Glossary Provides a glossary of technical terms and abbreviations used throughout the manual.

(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:

(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 ]…

[ - ] {0|1|2|3|4|5|6|7|8|9}…

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:

(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.

(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: 123.00

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:

(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:

%005400 %B101111 %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.

(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.

(19)

Introduction to the NSJMS C++ API Client Application

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:

Figure 1-1. NSJMS C++ API Client Messaging on a NonStop System

DP2 DP2

DP2

Tables Tables Tables

SQL/MX Client Application

NSJMS C++ API Library

(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,

(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

(22)

2

Installation and Configuration

for TNS/R

NSJMS C++ API System Requirements

Hardware

HP NonStop S-series server

Software

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.

(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.

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.

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.

Note. Using DSM/SCM is optional for G06.20 or later RVUs, but is recommended.

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.

(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.

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.

Note. You must be installing the NSJMS C++ API on a NonStop S-series system running G06.20 or later RVU.

(25)

5. Run ZPHIRNM to perform the RENAME step.

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.

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

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).

Note. You must be installing the NSJMS C++ API on a NonStop S-series system running G06.20 or later RVU.

(26)

install-dir is the user-specified installation directory and T2811-version is the vproc of this RVU (for example, T2811V10_30SEP2003_V10).

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:

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).

3. Go to Install and Configure the NSJMS C++ API on this page for detailed

Note. Running the PINSTALL command does not affect any environment currently running on your NonStop S-series server.

Note. Running the copyoss command does not affect any environment currently running on your NonStop S-series server.

(27)

Installation and Configuration for TNS/R Install and Configure the NSJMS C++ API

Install and Configure the NSJMS C++ API

1. Run the /usr/tandem/nsjms/T2811-version installation script located in the OSS file system directory. For example:

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.

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 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.

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.

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).

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

(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:

6. Test the sample programs

You will need two OSS shells to test each sample program.

a. Test the Point-to-Point sample program by using these commands: In the first shell:

In the second shell:

Your Point-to-Point sample program output will be similar to:

OSH: cd /usr/tandem/nsjms/T2811-version/examples OSH: make

Note. It is assumed that the NSJMS_HOME variable exists and is set to the home directory of your NSJMS (T1251) installation.

OSH: cd examples

OSH: SimpleReceiver -queue Q1 -count 5

OSH: cd examples

OSH: SimpleSender -queue Q1 -count 5

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

(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:

Your Publish and Subscribe sample program output will be similar to:

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.

OSH: cd examples

OSH: SimpleConsumer -topic T1 -count 5

OSH: cd examples

OSH: SimplePublisher -topic T1 -count 5

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

(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

(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:

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:

where T2811-version represents the specific version of the NSJMS C++ API to remove.

OSH: cd /usr/tandem/sqlmx/USERMODULES

OSH: rm TANDEM_SYSTEM_NSK.JMS_SCHEMA.LIBNSJMSC_T2811-version

OSH: cd /usr/tandem/nsjms OSH: rm -R T2811-version

Note. Removal of this directory will require any future installation of the NSJMS C++ API to start with Run the IPSetup Program on page 2-2.

(32)

3

Installation and Configuration

for TNS/E

NSJMS C++ API System Requirements

Hardware

HP NonStop NS-series server

Software

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.

(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.

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.

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.

(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.

(35)

5. Run ZPHIRNM to perform the RENAME step.

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.

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:

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

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).

(36)

install-dir is the user-specified installation directory and T2811-version is the vproc of this RVU (for example, T2811H10_30MAY2005_H10).

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:

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

(37)

Installation and Configuration for TNS/E Install and Configure the NSJMS C++ API

Install and Configure the NSJMS C++ API

1. Run the /<jmsC-install-dir>/nsjms/T2811-version installation script located in the OSS file system directory. For example:

where <jmsC-install-dir> is the standard or non-standard NSJMS installation location.

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.

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.

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.

TACL> LOGON SUPER.NSJMS TACL> OSH

OSH: cd /<jmsC-install-dir>/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.

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).

(38)

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:

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:

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 OSH: cd /usr/tandem/nsjms/T2811-version/examples OSH: make

(39)

You need two OSS shells to test each sample program.

a. Test the Point-to-Point sample program by entering these commands: In the first shell:

Your Point-to-Point sample program output will be similar to:

b. Test the Publish and Subscribe sample program by entering these commands: In the first shell:

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

OSH: cd examples

OSH: SimpleReceiver -queue Q1 -count 5

OSH: cd examples

OSH: SimpleSender -queue Q1 -count 5

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

OSH: cd examples

OSH: SimpleConsumer -topic T1 -count 5

OSH: cd examples

(40)

Installation and Configuration for TNS/E NSJMS C++ API Directory Structure

Your Publish and Subscribe sample program output will be similar to:

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.



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

(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 5-3.

(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:

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:

3. Remove the NSJMS C++ API install directory by using these commands:

where T2811-version represents the specific version of the NSJMS C++ API to remove. OSH: cd /usr/tandem/sqlmx/USERMODULES OSH: rm TANDEM_SYSTEM_NSK.JMS_SCHEMA.LIBNSJMSC_T2811-version OSH: cd /G/system/zdll OSH: rm -R T2811-version OSH: cd /G/system/ydll OSH: rm -R T2811-version OSH: cd /usr/tandem/nsjms OSH: rm -R T2811-version

Note. Removal of this directory will require any future installation of the NSJMS C++ API to start with Run the IPSetup Program on page 3-2.

(43)

(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.



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 4-7

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).

(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.

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.

MapMessage Class

The MapMessage class extends the Message class and sends a message that contains name-value pairs.

BytesMessage Methods Description

readBytes Read a portion of the bytes-message stream.

writeBytes Write a byte array to the bytes-message stream.

Consumer Method Description

receive Receive the next message that arrives within the specified timeout interval.

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.

(46)

NSJMS C++ API Classes and Methods Message Class

Message Class

The Message class is the base class of all message classes.

setLong Set a long value with the given name, into the Map.

setShort Set a short value with the given name, into the Map.

setString Set a string value with the given name, into the Map.

Message Methods Description (page 1 of 2)

clearProperties Clears the message’s header fields and properties, the body is not cleared.

getBooleanProperty Returns the value of the boolean property with the specified name.

getByteProperty Returns the value of the byte property with the specified name.

getBytesProperty Returns the value of the byte-array property with the specified name.

getDoubleProperty Returns the value of the double property with the specified name.

getFloatProperty Returns the value of the float property with the specified name.

getIntProperty Returns the value of the integer property with the specified name.

getJMSCorrelationID Gets the correlation ID for the message.

getJMSDeliveryMode Gets the delivery mode value specified for this message.

getJMSDestination Gets the destination object for the message.

getJMSExpiration Gets the expiration value for the message.

getJMSMessageID Gets the message ID for the message.

getJMSPriority Gets the priority level for the message.

getJMSReplyTo Gets the destination object to which a reply to this message should be sent.

getJMSTimestamp Gets the timestamp for the message.

getJMSType Gets the message type identifier supplied by a client when a message is sent.

getLongProperty Returns the value of the long property with the specified name.

getShort