IBM GC34-5557-00 User Manual

Download

MQSeries®for AS/400

Quick Beginnings

V5.1

IBM

GC34-5557-00

MQSeries®for AS/400

Quick Beginnings

V5.1

IBM

GC34-5557-00

Note!

Before using this information and the product it supports, be sure to read the general information under “Appendix C. Notices” on page 105.

First edition (March 2000)

This edition applies to MQSeries for AS/400, Version 5 Release 1, and to all subsequent releases and modifications until otherwise indicated in new editions.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Tables..............vii

Welcome to MQSeries for AS/400 ....ix

Conventions ............ix

Chapter 1. About MQSeries.......1

Message Queuing ..........1

MQI – a Common Application

Programming Interface ........1

Time-Independent Applications .....2

Message-Driven Processing ......2

Messages and Queues .........2

What is a Message? .........2

What is a Queue? .........3

MQSeries Objects ..........3

Queue Managers ..........4

Queues .............4

Process Definitions .........5

Channels ............5

Namelists ............6

Clients and Servers ..........6

Instrumentation Events.........7

Types of Event ..........7

Transactional Support .........8

Chapter 2. What’s New in MQSeries for

AS/400, V5.1 ............9

Chapter 3. Planning to Install the MQSeries

for AS/400 Server..........13

Hardware Requirements ........13

Disk Space Required ........13

Software Requirements ........13

Connectivity ............13

AS/400 Install Libraries and Directories. . . 14

AS/400 Library Structure ......14

IFS Root File System ........15

User Profiles ...........16

Compilers Supported for MQSeries for

AS/400, V5.1 Applications .......16

Delivery .............16

MQSeries for AS/400 Components ....16

Creating the System-Default Objects . . . 17

Chapter 4. Installing, Migrating to, and

Deleting MQSeries for AS/400 .....19

Before Installation ..........19

Setting System Values........19

Installation Procedure .........21

Installation of Translated Versions....21

Reinstallation ..........21

Verifying the Installation ........22

Post Installation Tasks........22

Quiescing MQSeries .........23

Quiescing previous releases of MQSeries

for AS/400 ...........23

Quiescing V5.1 of MQSeries for AS/400. . 24

Migrating to MQSeries for AS/400, V5.1 . . 24

What are the Differences .......25

Overview of Migration Process.....25

Before Migration .........26

Migration ............27

Verifying the Migration ........29

After Migration ..........30

Deleting MQSeries for AS/400, V5.1 ....31

Standard Deletion .........31

Entire Deletion ..........31

Chapter 5. Using MQSeries for AS/400,

V5.1 ..............33

Before you Start...........33

Introducing Command Sets .......33

CL Commands ..........34

MQSeries (MQSC) Commands .....36

PCF Commands..........37

Working with MQSeries ........37

Creating a Queue Manager ......37

Starting a Queue Manager ......38

Creating a Local Queue .......38

Sending a Test Message .......41

Browsing Queues .........41

Clearing a Local Queue .......41

Deleting a Local Queue .......41

Stopping a Queue Manager ......41

Deleting a Queue Manager ......42

Checking what Queue Managers you have

Running ............42

Other Things to Do .........42

User Exits............43

Setting the Queue Manager CCSID for

MQSeries for AS/400 ........43

Chapter 6. Planning to Install MQSeries

Clients .............45

Applications on Version 5 Clients .....45

AIX Client: Hardware and Software Required 45

Hardware............45

Software ............45

Compilers for MQSeries Applications on

AIX Clients ...........46

Components for AIX .........46

Digital UNIX Client: Hardware and Software

Required .............47

Hardware............47

Software ............47

Compilers for MQSeries applications on

Digital UNIX clients ........48

DOS Client: Hardware and Software Required 48

Hardware............48

Software ............48

Compilers for MQSeries Applications on

DOS Clients ...........48

Components for DOS .........49

HP-UX Client: Hardware and Software

Required .............49

Hardware............49

Software ............49

Compilers for MQSeries Applications on

HP-UX Clients ..........50

Components for HP-UX ........50

OS/2 Warp Client: Hardware and Software

Required .............50

Hardware............50

Software ............50

Compilers for MQSeries Applications on

OS/2 Warp Clients.........51

Components for OS/2 Warp ......51

Sun Solaris Client: Hardware and Software

Required .............52

Hardware............52

Software ............52

Compilers for MQSeries Applications on

Sun Solaris Clients .........53

Components for Sun Solaris.......53

Windows 3.1 Client: Hardware and Software

Required .............53

Hardware............53

Software ............53

Compilers for MQSeries Applications on

Windows 3.1 Clients ........54

Components for Windows 3.1 ......54

Windows 95 and Windows 98 Client:

Hardware and Software Required.....54

Hardware............54

Software ............54

Compilers for MQSeries Applications on

Windows 95 and Windows 98 Clients . . 54 Components for Windows 95 and Windows

98...............55

Windows NT Client: Hardware and Software

Required .............55

Hardware............55

Software ............55

Compilers for MQSeries Applications on

Windows NT Clients ........55

Components for Windows NT ......56

Chapter 7. Installing MQSeries Clients . . 57

Installing MQSeries Clients on the Same

Machine as the Server.........57

Installing on AIX ..........57

Before Installation .........58

Easy Installation .........60

Custom Installation ........61

Migrating from an Earlier Version of

MQSeries for AIX .........62

Changing the National Language ....63

Translated Messages ........64

Removing an MQSeries Client from AIX 64

Installing on DOS ..........64

Using Setup ...........64

Removing an MQSeries Client from DOS 65

Installing on HP-UX .........65

Before Installation .........65

Installation ...........66

Kernel Configuration ........66

Translated Messages ........66

Removing an MQSeries Client from

HP-UX.............66

Installing on OS/2 Warp ........66

Installation ...........67

Unattended Installation on OS/2 Warp . . 69

Installation and Maintenance Parameters 71

Installation Response Files ......73

Removing an MQSeries Client from OS/2

Warp.............75

Installing on Sun Solaris ........75

Before Installation .........76

iv MQSeries for AS/400, V5.1 Quick Beginnings

Installation ...........76

Kernel Configuration ........77

Translated Messages ........77

Removing an MQSeries Client from Sun

Solaris .............77

Installing on Windows 95 or Windows 98 . . 77

Installation ...........78

Unattended Installation on Windows 95

and Windows 98 .........79

Removing an MQSeries Client from

Windows 95 and Windows 98 .....81

Installing on Windows 3.1 .......81

Installation ...........81

Removing an MQSeries Client from

Windows 3.1 ...........83

Installing on Windows NT .......83

Installation ...........83

Installing from a LAN .......85

Using the System Management Server with

MQSeries for Windows NT ......86

Unattended Installation on Windows NT 87 Removing an MQSeries Client from

Windows NT...........89

Classes for Java ...........89

Configuring and Verifying a Client ....90

Chapter 8. Obtaining Additional

Information ............91

Hardcopy Books ..........93

Online Information..........93

Publications CD-ROM........94

HTML and PDF Books on the World Wide

Web..............96

BookManager CD-ROMs .......97

Online Help ...........97

Appendix A. Sample MQI Programs . . . 99

C, COBOL, and RPG Program Samples . . . 99

Appendix B. Applying Maintenance to

MQSeries for AS/400 ........103

Reinstalling MQSeries for AS/400 ....103

Appendix C. Notices ........105

Trademarks ............107

Index .............109

Sending your comments to IBM ....113

Contents v

vi MQSeries for AS/400, V5.1 Quick Beginnings

Tables

1. National-language versions of MQSeries

for AS/400, V5.1.........14

2. Authorities required to open an object 29

3. Authorities for Context and

AlternateUserID .........29

4. MQSeries for AS/400 books .....91

5. MQSeries publications – file names 95

6. Sample programs – source files ....99

viii MQSeries for AS/400, V5.1 Quick Beginnings

Welcome to MQSeries for AS/400

This book describes IBM®MQSeries for AS/400, Version 5.1. It explains how to plan for, install, and begin to use the product. For latest information about MQSeries for AS/400, V5.1, refer also to the readme file on the publications CD-ROM, and to the MQSeries family Web site at:

http://www.ibm.com/software/ts/mqseries/

Conventions

Knowing the conventions used in this book will help you use it more efficiently.

v Boldface type indicates the name of an item you need to select. v Italic type indicates new terms, book titles, or variable information that you

must replace with actual values.

v Monospace type indicates an example (such as a fictitious path or file name)

or text that is displayed on the screen.

Conventions

MQSeries for AS/400, V5.1 Quick Beginnings

Chapter 1. About MQSeries

This chapter introduces IBM MQSeries and describes its relationship with other products. It contains basic explanations of the following topics:

v “Message Queuing” v “Messages and Queues” on page 2 v “MQSeries Objects” on page 3 v “Clients and Servers” on page 6 v “Instrumentation Events” on page 7 v “Transactional Support” on page 8

For more detailed explanations of these topics see the MQSeries Planning Guide.

Message Queuing

MQSeries enables applications to use message queuing to participate in message-driven processing. Applications can communicate across different platforms by using the appropriate message-queuing software products. The applications are shielded from the mechanics of the underlying communications.

MQI – a Common Application Programming Interface

All MQSeries products implement a common application programming interface (message queue interface or MQI), regardless of the platform on which the applications are run. The calls made by the applications and the messages they exchange are common. This makes it much easier to write and maintain applications than it is when using traditional methods. It also makes it easier to port applications from one platform to another.

The MQI is described in detail in the MQSeries Application Programming Reference book.

Message Queuing

Time-Independent Applications

With message queuing, the exchange of messages between the sending and receiving programs is time independent. This means that the sending and receiving applications are decoupled; the sender can continue processing without having to wait for the receiver to acknowledge receipt of the message. In fact, the target application does not even have to be running when the message is sent. It can retrieve the message when it starts running.

Message-Driven Processing

On arrival on a queue, messages can automatically start an application by using a technique known as triggering. If necessary, the application can be stopped when the message or messages have been processed.

Messages and Queues

Messages and queues are the basic components of a message queuing system.

What is a Message?

A message is a string of bytes that has meaning to the applications that use it. Messages are used to transfer information from one application to another (or to different parts of the same application). The applications can be running on the same platform, or on different platforms.

MQSeries messages have two parts; the application data and a message descriptor. The content and structure of the application data are defined by the application programs that use the data. The message descriptor identifies the message and contains control information, such as the type of message and the priority assigned to it by the sending application.

MQSeries for AS/400, V5.1 Quick Beginnings

What is a Queue?

A queue is a data structure that stores messages. The messages may be put on the queue by applications or by a queue manager as part of its normal operation.

Queues exist independently of the applications that use them. A queue can exist in main storage (if it is temporary), on disk or similar auxiliary storage (if it must be kept in case of recovery), or in both places (if it is currently being used, and must also be kept for recovery). Each queue belongs to a queue manager, which is responsible for maintaining it. The queue manager puts the messages it receives onto the appropriate queue.

Queues can exist either in your local system, in which case they are called

local queues, or at another queue manager, in which case they are called remote queues.

Applications use MQI calls to send and receive messages. One application can put a message on a queue and another application can retrieve the message from the same queue.

MQSeries Objects

An MQSeries object is a recoverable resource that is managed by MQSeries. Many of the tasks that are described in this chapter involve manipulating the following types of MQSeries object:

v Queue managers v Queues v Process definitions v Channels v Namelists

Messages and Queues

MQSeries creates default objects for you when you create a queue manager.

Each object has a name associated with it. You can specify that name in MQSeries commands and MQI calls to refer to the object. Names must be unique within each of the object types. For example, you can have a queue and a process with the same name, but you cannot have two queues with the same name.

Chapter 1. About MQSeries 3

MQSeries Objects

Queue Managers

A queue manager provides queuing services to applications, and manages the queues that belong to it. It ensures that:

v Object attributes are changed according to the commands received. v Special events such as trigger events or instrumentation events are

generated when the appropriate conditions are met.

v Messages are put on the correct queue, as requested by the application that

makes the MQPUT call. The application is informed if this cannot be done, and an appropriate reason code is given.

Each queue belongs to a single queue manager and is said to be a local queue to that queue manager. The queue manager to which an application is connected is said to be the local queue manager for that application. For the application, the queues that belong to its local queue manager are local queues. A remote queue is simply a queue that belongs to another queue manager. A remote queue manager is any queue manager other than the local queue manager. A remote queue manager may exist on a remote machine across the network, or it may exist on the same machine as the local queue manager. MQSeries for AS/400, V5.1 supports multiple queue managers on the same machine.

Queues

A queue is an MQSeries object that can store messages. Each queue has queue attributes that determine what happens when applications reference the queue

in MQI calls. The attributes indicate:

v Whether applications can retrieve messages from the queue (get enabled) v Whether applications can put messages onto the queue (put enabled) v Whether access to the queue is exclusive to one application or shared

between applications

v The maximum number of messages that can be stored on the queue at the

same time (maximum queue depth)

v The maximum size of messages that can be put on the queue (maximum

message size)

MQSeries for AS/400, V5.1 Quick Beginnings

Process Definitions

A process definition object defines an application that is to be started in response to a trigger event on an MQSeries queue manager.

A trigger event is a logical combination of conditions that is detected by a queue manager. For example, a trigger event may be generated when the number of messages on a queue reaches a predefined level. This event causes the queue manager to put a trigger message on a specified initiation queue. This trigger message is retrieved by a trigger monitor, a special application that monitors an initiation queue. The trigger monitor then starts up the application program that was specified in the trigger message.

If a queue manager is to use triggering, at least one initiation queue must be defined for that queue manager.

See the MQSeries Application Programming Guide for more information about triggering.

Channels

A channel provides a communication path. There are two types of channel; message channels and MQI channels.

A message channel provides a communication path between two queue managers on the same, or different, platforms. The message channel is used for the transmission of messages from one queue manager to another. It shields the application programs from the complexities of the underlying networking protocols.

MQSeries Objects

A message channel can transmit messages in one direction only. If you require two-way communication between two queue managers, you need two message channels.

An MQI channel connects an MQSeries client to a queue manager on a server machine. It is for the transfer of MQI calls (for example, MQPUT) and responses only and is bidirectional. A channel definition exists for each end of the link. On some platforms, some types of MQI channel can be defined automatically.

For more information about channels see the MQSeries Intercommunication book.

Chapter 1. About MQSeries 5

MQSeries Objects

Namelists

A namelist is an MQSeries object that contains a list of other MQSeries objects. Typically, namelists are used by applications such as trigger monitors, where they are used to list a number of queues. The advantage of using a namelist is that it is maintained independently of applications. You can update a namelist without having to stop any of the applications that use it. Also, if one application fails, the namelist is not affected and other applications can continue using it.

Clients and Servers

MQSeries supports client/server configurations for MQSeries applications.

An MQSeries client is a part of the MQSeries product, which is used to accept MQI calls from an application and pass them to an MQI server machine. The calls are processed by a queue manager on the server machine. Typically, the client and server reside on different machines, but equally they may exist on the same machine.

An MQI server is a queue manager that provides queuing services to one or more clients. All the MQSeries objects, for example queues, exist only on the queue manager machine, that is, on the MQI server machine. A server can support local MQSeries applications as well.

The benefits of using an MQSeries client include:

v Reduced hardware requirements. v Reduced system administration requirements. v Small installation footprint. v Alternative channels using different transmission protocols may be used.

For more information about clients, client support, and creating channels for clients and servers, see the MQSeries Clients book.

MQSeries for AS/400, V5.1 Quick Beginnings

Instrumentation Events

You can use MQSeries instrumentation events to monitor the operation of queue managers.

Instrumentation events cause special messages, which are called event messages, to be generated whenever the queue manager detects a predefined set of conditions. For example, the following conditions give rise to a Queue Full event:

v Queue Full events are enabled for a specified queue, and v An application issues an MQPUT call to put a message on that queue, but

the call fails because the queue is full.

Other conditions that can give rise to instrumentation events include:

v A predefined limit for the number of messages on a queue being reached v A queue not being serviced within a specified time v A channel instance being started or stopped

If you define your event queues as remote queues, you can put all the event queues on a single queue manager (for those nodes that support instrumentation events). You can then use the events that are generated to monitor a network of queue managers from a single node.

Instrumentation Events

Types of Event

MQSeries events are categorized as follows:

Queue manager events

Performance events

Channel events

These events are related to the definitions of resources within queue managers. For example, if an application attempts to open a queue but the associated user ID is not authorized to perform that operation, a queue manager event is generated.

These events are notifications that a resource has reached a threshold condition. For example, a queue has reached its queue-depth limit following an MQGET request, or a queue has not been serviced within a predefined period of time.

These events are reported by channels as a result of conditions they detect during their operation. For example, a channel event is generated when a channel instance is stopped.

Chapter 1. About MQSeries 7

Transactional Support

An application program can group a set of updates into a unit of work. These updates are usually logically related and must all be successful for data integrity to be preserved. If one update succeeded while another failed then data integrity would be lost.

A unit of work commits when it completes successfully. At this point all updates made within that unit of work are made permanent or irreversible. If the unit of work fails, all updates are instead backed out. Syncpoint coordination is the process by which units of work are either committed or backed out with integrity.

A local unit of work is one in which the only resources updated are those belonging to the MQSeries queue manager. Syncpoint coordination is provided by the queue manager itself, using a single-phase commit process.

A global unit of work is one in which resources that belong to other resource managers, such as a DB2/400

database, are also updated. Here, a two-phase commit procedure must be used and the unit of work is coordinated externally by the operating system commitment controller.

Global units of work make it possible to integrate database updates within MQSeries units of work. That is, you can write an application that makes updates to MQSeries queues and to databases. You can issue commands to commit or roll back the changes to both the queues and the databases.

This is achieved using a two-phase commit protocol. When a unit of work is to be committed, the operating-system commitment controller first asks each resource owner whether it is prepared to commit its updates. Only if the database manager and the queue manager are both prepared to commit, are all of the queue and database updates committed. If the database manager cannot prepare its updates, the unit of work is backed out instead.

Full recovery support is provided if the queue manager loses contact with the database manager during the commit process. If the database manager becomes unavailable while it is in doubt (that is, it has been called to prepare but the commitment controller has yet to receive a commit or backout decision) the commitment controller remembers the outcome of the unit of work until it has been successfully delivered. Similarly, if the queue manager terminates with incomplete commit operations outstanding, these are remembered over queue-manager restart.

MQSeries for AS/400, V5.1 Quick Beginnings

Chapter 2. What’s New in MQSeries for AS/400, V5.1

MQSeries for AS/400, V5.1 is an update to MQSeries for AS/400, V4.2.1. However, it is more than just an upgrade to the features of that product. It includes significant new function and a redesign of the product base, to bring MQSeries for AS/400 to the same level of function as other version 5.1 products. MQSeries for AS/400, V5.1 now offers platform consistency with the other products at the 5.1 level, which are:

v MQSeries for AIX v MQSeries for OS/2 v MQSeries for HP-UX v MQSeries for Sun Solaris v MQSeries for Windows NT

The features of this release include:

MQSeries queue manager clusters

You can connect MQSeries queue managers to form a cluster. Within a cluster, queue managers can make the queues they host available to every other queue manager. Any queue manager can send a message to any other queue manager in the same cluster without the need for explicit channel definitions, remote queue definitions, or transmission queues for each destination. The main benefits of MQSeries clusters are:

v Fewer system administration tasks v Increased availability v Workload balancing

Clusters are supported by all MQSeries Version 5.1 products, and also by MQSeries for OS/390

, Version 2.1.

See the MQSeries Queue Manager Clusters book for a complete description.

MQSeries Administration Interface (MQAI)

The MQSeries Administration Interface is an MQSeries programming interface that simplifies manipulation of MQSeries PCF messages for administrative tasks. It is described in the MQSeries Administration Interface Programming Guide and Reference book.

Support for Windows 98 clients

You can connect a Windows 98 client to the MQSeries for AS/400, V5.1 server.

What’s New

Java support

MQSeries classes for Java

™

include support for MQSeries for AS/400,

V5.1.

New calls

MQSeries for AS/400, V5.1 supports the following new calls: v MQCONNX, which allows you to specify queue-manager

connection options.

v MQCMIT, MQBACK, and MQBEGIN, which allow MQSeries to

coordinate a local unit of work.

Two-phase commit

MQSeries for AS/400, V5.1 participates as a two-phase commit resource in global units of work (UOW) managed by OS/400

Automatic object creation

MQSeries for AS/400, V5.1 creates default objects automatically when you create a queue manager.

Conversion of the EBCDIC new-line character

You can control the conversion of EBCDIC new-line characters. Thus you can ensure that data transmitted between EBCDIC systems and ASCII systems is unaltered by the ASCII conversion.

Multiple queue managers

MQSeries for AS/400 now supports multiple queue managers. You can nominate one queue manager to be the default queue manager. You can perform actions on a default queue manager without specifying its name on the commands.

Job priority control

Users can set independent priority for individual MQSeries jobs - for example, channel agents.

MQSeries subsystem

MQSeries for AS/400, V5.1 has its own subsystem. Previous releases used QSYSWRK.

Euro support

MQSeries supports new and changed code pages that use the euro currency symbol. Further details of code pages that include the euro symbol are provided in the MQSeries Application Programming Reference book.

Multithreaded channels

MQSeries for AS/400, V5.1 supports multithreaded channels.

Multithreaded applications

MQSeries for AS/400, V5.1 supports multithreaded applications.

MQSeries for AS/400, V5.1 Quick Beginnings

Message queue size

A message queue can be up to 2 GB.

Message size

A single message can be up to 100 MB.

Administration application

The administration application is not supported in MQSeries for AS/400, V5.1.

What’s New

Chapter 2. What’s New in MQSeries for AS/400, V5.1 11

What’s New

MQSeries for AS/400, V5.1 Quick Beginnings

Chapter 3. Planning to Install the MQSeries for AS/400 Server

This chapter provides a summary of the requirements for running MQSeries for AS/400. It discusses the network protocols and compilers supported, the delivery media, and the various components of the product.

The information in this chapter applies to the server environment only. For information about client environments, see “Chapter 6. Planning to Install MQSeries Clients” on page 45.

Hardware Requirements

MQSeries for AS/400, V5.1 runs on any machine that is capable of running OS/400 V4R4, and that has sufficient storage to meet the combined requirements of the programming prerequisites, MQSeries for AS/400, V5.1, the access methods, and the application programs, whether from IBM or other vendors.

The installation requirements depend on the components you install and how much working space you need. This, in turn, depends on the number of queues that you use, the number and size of the messages on the queues, and whether the messages are persistent. You also require archiving capacity on disk, tape, or other media.

Disk Space Required

For the MQSeries for AS/400, V5.1 base code and server you should allow approximately 60 MB of storage.

Software Requirements

This is the minimum supported software level. Later levels, if any, will be supported unless otherwise stated.

OS/400 Version 4 Release 4

Connectivity

The network protocols supported by MQSeries for AS/400 are:

v TCP v SNA LU 6.2

Connectivity

AS/400 Install Libraries and Directories

MQSeries for AS/400 installs into the AS/400 library structure and also uses directories in the IFS root file system.

AS/400 Library Structure

Installation of MQSeries for AS/400 creates the following libraries:

QMQM

The MQSeries base product library.

QMQMSAMP

The MQSeries samples library (if you choose to install the samples).

QMQM29xx

A library containing a message file that is specific to your national language. This message file is automatically copied into the appropriate QSYS29xx library when the product is installed.

The following language versions are available for MQSeries for AS/400, V5.1:

Table 1. National-language versions of MQSeries for AS/400, V5.1

Language ID Language

2909 Belgian English 2966 Belgian French MNCS (Multi-National Character Set) 2981 Canadian French MNCS 2950 English Uppercase 2924 English Uppercase and Lowercase 2938 English Uppercase DBCS (Double-Byte Character Set) 2984 English Uppercase and Lowercase DBCS 2928 French 2940 French MNCS 2932 Italian 2942 Italian MNCS 2931 Spanish 2962 Japanese 2986 Korean 2989 Simplified Chinese

Note: The Japanese language version of this product does not run correctly if

your job CCSID is 5026. For details of supported CCSIDs to use with this language version, see the readme file.

QMxxxx Library

Each time you create a queue manager MQSeries automatically creates an associated library. This library contains objects specific to the queue manager, including journals and associated receivers. The name of this library is

MQSeries for AS/400, V5.1 Quick Beginnings

derived from the name of the queue manager prefixed with the characters QM. For example, for a queue manager called TEST, the library would be called QMTEST.

You can use the WRKLIB command to list all the libraries that MQSeries for AS/400 has created. Against the queue manager libraries, you will see the text

QMGR: QMGRNAME. The format of the command is:

WRKLIB LIB(QM*)

These queue manager-associated libraries are retained when the product is deleted.

IFS Root File System

The integrated file system (IFS) provides a common interface to the different systems on the AS/400. When you install MQSeries for AS/400, V5.1 two directories are created in the root file system. They are:

/QIBM/ProdData/mqm

Subdirectories below this contain all the product data - for example, C++ classes. Data in this directory is deleted and replaced each time the product is installed.

/QIBM/UserData/mqm

Subdirectories below this contain all user data relating to queue managers. Three subdirectories, /QIBM/UserData/mqm/errors, /QIBM/UserData/mqm/qmgrs, and /QIBM/UserData/mqm/trace, are also created when the product is installed.

Connectivity

When you install the product, an mqs.ini file is created in directory /QIBM/UserData/mqm/ (unless it is already there from a previous installation). When you create a queue manager a qm.ini file is created in the directory /QIBM/UserData/mqm/qmgrs/QMGRNAME/ (where QMGRNAME is the name of the queue manager.) The qm.ini file is the equivalent of the QMINI file in previous releases of MQSeries for AS/400.

Data in this directory is retained when the product is deleted.

The IFS file structure is shown in the MQSeries for AS/400 V5.1 System Administration book.

Chapter 3. Planning to Install the MQSeries for AS/400 Server 15

Connectivity

User Profiles

When you install MQSeries for AS/400, V5.1, a number of user profiles are created. These include QMQM, QMQMADM, and NOBODY. These three objects are central to the correct running of MQSeries for AS/400. Under no circumstances should you alter or delete them. If you do, IBM cannot guarantee correct behavior of your product.

These profiles are retained when the product is deleted.

Compilers Supported for MQSeries for AS/400, V5.1 Applications

MQSeries for AS/400, V5.1 supports the following compilers:

v IBM ILE C for AS/400 compiler (5768-CX2) v IBM ILE C++ for AS/400 compiler (5799-GDW) v IBM VisualAge

for C++ for AS/400 compiler (5769-CX4)

v IBM ILE COBOL for AS/400 compiler Version 3 (5769-CB1) v IBM ILE RPG for AS/400 compiler (5769-RG1) v AS/400 Developer Kit for Java (5769-JV1)

Delivery

MQSeries for AS/400, V5.1 is supplied on CD-ROM.

There are three CD-ROMs. v One contains the MQSeries for AS/400, V5.1 base product and sample

programs.

v Another contains the client products that you can use with MQSeries for

AS/400.

v The third contains MQSeries for AS/400 publications.

Java support is supplied on the MQSeries Web site, at:

http://www.ibm.com/software/ts/mqseries/

MQSeries for AS/400 Components

The components are as follows: Base Support to enable you to create and support your own applications.

This includes the run-time component that provides support for external applications. It also includes support for client connections from other MQSeries products.

MQSeries for AS/400, V5.1 Quick Beginnings

Samples

Sample application programs. The source is supplied in the QMQMSAMP library and executables are supplied in the QMQM library. See “Appendix A. Sample MQI Programs” on page 99.

MQSeries online documentation

HTML and PDF versions of the books are supplied on the publications CD-ROM. They are not installable. You can read them directly from the CD-ROM or you can copy them to your system. For example, you could copy them to your PC hard drive, or store them in the AS/400 IFS and then access them using a network drive.

Each book is supplied in U.S. English and also in some or all of the following national languages:

v French v German v Italian v Japanese v Korean v Spanish v Simplified Chinese

See “Chapter 8. Obtaining Additional Information” on page 91 for more information.

MQSeries for AS/400 Components

Readme file

Latest information about the product, which became available after publication of this book. You can find the readme file on the publications CD-ROM and should review it before starting to install MQSeries for AS/400.

See “Chapter 8. Obtaining Additional Information” on page 91 for more information.

Creating the System-Default Objects

System-default objects are created automatically when you issue the CRTMQM command to create a queue manager.

You can refresh them using the STRMQM command. Refer to the online help for information about using this command.

Chapter 3. Planning to Install the MQSeries for AS/400 Server 17

18 MQSeries for AS/400, V5.1 Quick Beginnings

Chapter 4. Installing, Migrating to, and Deleting MQSeries for AS/400

This chapter describes installation of and migration to MQSeries for AS/400, V5.1. It covers the following topics:

v “Before Installation” v “Installation Procedure” on page 21 v “Verifying the Installation” on page 22 v “Quiescing MQSeries” on page 23 v “Migrating to MQSeries for AS/400, V5.1” on page 24 v “Verifying the Migration” on page 29 v “Deleting MQSeries for AS/400, V5.1” on page 31

In addition to reading the information in this chapter, you should refer to the readme file on the publications CD-ROM, and also to the latest information available on the MQSeries Web site at:

http://www.ibm.com/software/ts/mqseries/

Before Installation

If you are migrating from an earlier release of MQSeries for AS/400, refer to “Migrating to MQSeries for AS/400, V5.1” on page 24.

You must have the OS/400 V4R4 operating system installed on your machine in order to run MQSeries for AS/400, V5.1. If you have OS/400 V4R2 or V4R3 operating system installed, you can use only MQSeries for AS/400 V4R2M1.

Setting System Values

Before installing MQSeries for AS/400, you should use the DSPSYSVAL command to check that the following system values are set to the requirements of your enterprise:

v QCCSID v QUTCOFFSET v QSYSLIBL v QALWOBJRST

You can change these values, if necessary, using the CHGSYSVAL command.

Before Installation

QCCSID

Every message has a coded-character set identifier (CCSID) in its header. The CCSID tag identifies the code page and character set of the source. For CCSIDs that are supported on the AS/400 see the AS/400 National Language Support book.

The CCSID information is obtained, when a queue manager is created, from the job CCSID. If this does not contain a valid value in the range 1–65534, the information is obtained from the default CCSID value for the job.

Note: The CCSID must be either Single-byte character set (SBCS), or Mixed,

You can change the CCSID used by the MQSeries queue manager by using the CL command CHGMQM. See “Setting the Queue Manager CCSID for MQSeries for AS/400” on page 43 for more information.

QUTCOFFSET

You should check that the coordinated universal time offset (QUTCOFFSET) system value has been set, to indicate the relationship between the system time and Greenwich Mean Time (GMT). You do this by working with the CHGSYSVAL command.

that is SBCS and DBCS. It must not be DBCS only.

If QUTCOFFSET is not set, it takes the default value of zero. MQSeries for AS/400 then assumes that the local system time is universal time coordinated (UTC) - that is, GMT - and time stamps the MQSeries for AS/400 messages accordingly.

QSYSLIBL

Ensure that QSYS2 is included in the list of libraries that make up the system part of the library list.

MQSeries for AS/400 uses programs in this library for data conversion and SNA LU 6.2 communication.

QALWOBJRST

Ensure that the QALWOBJRST system value is set to *ALL or *ALWPGMADP before you install MQSeries for AS/400. If it is set to *NONE, the installation will fail.

After installation, reset QALWOBJRST to its original value to maintain system security.

MQSeries for AS/400, V5.1 Quick Beginnings

Installation Procedure

1. To install the MQSeries for AS/400, V5.1 base product, issue the

command:

RSTLICPGM LICPGM(5733A38) DEV(install device) OPTION(*BASE)

where:

v 5733A38 is the product identifier for MQSeries for AS/400, V5.1, and v install device is the device from which the product is to be loaded,

typically a CD-ROM - for example, OPT01.

2. To install the sample applications, issue the command:

RSTLICPGM LICPGM(5733A38) DEV(install device) OPTION(1)

Note: You can install only one instance of MQSeries for AS/400 in each

partition of your AS/400 machine.

Installation of Translated Versions

MQSeries for AS/400 is installed in the language that is the primary language on your system.

You can install additional versions of the product in any of the languages shown in Table 1 on page 14. To do so, issue the following command specifying the appropriate language ID:

RSTLICPGM LICPGM(5733A38) DEV(install device) RSTOBJ(*LNG) LNG(language ID)

Installation

This will install the commands, message file, and panel groups into the relevant QSYS library for the language. For example, library QSYS2928 is used for French.

Reinstallation

Reinstallation is discussed in “Reinstalling MQSeries for AS/400” on page 103.

Chapter 4. Installing, Migrating to, and Deleting MQSeries for AS/400 21

Verifying the Installation

To ensure that the product has loaded correctly, issue the Display Software Resources (DSPSFWRSC) command and check that the licensed program 5733A38 is listed. If you have installed the base and the optional samples, you should see:

If you press F11 while viewing the Display Software Resources screen, you will see the library and version number of the products installed:

If you have installed additional language versions, you will also see entries for these. For example, if you have installed the French version, for which the language ID is 2928, you will see:

Resource

ID Option Feature Description 5733A38 *BASE 5050 MQSeries for AS/400 5733A38 *BASE 2924 MQSeries for AS/400 5733A38 1 5050 MQSeries for AS/400 - Samples

Resource Feature ID Option Feature Type Library Release 5733A38 *BASE 5050 *CODE QMQM V5R1M0 5733A38 *BASE 2924 *LNG QMQM V5R1M0 5733A38 1 5050 *CODE QMQMSAMP V5R1M0

Resource

ID Option Feature Description 5733A38 *BASE 2928 MQSeries for AS/400

and when you press F11:

Resource Feature

ID Option Feature Type Library Release 5733A38 *BASE 2928 *LNG QSYS2928 V5R1M0

Post Installation Tasks

When you have correctly installed MQSeries for AS/400, V5.1 on your system:

1. Refer to the MQSeries family Web site at:

http://www.ibm.com/software/ts/mqseries/

for latest product information, and install and apply all PTFs that are recommended.

2. Start the MQSeries subsystem, by issuing the command:

STRSBS SBSD(QMQM/QMQM)

You are now ready to start using MQSeries for AS/400. See “Chapter 5. Using MQSeries for AS/400, V5.1” on page 33.

MQSeries for AS/400, V5.1 Quick Beginnings

Quiescing MQSeries

The orderly shutdown of MQSeries for AS/400 is called quiescing. You may need to quiesce MQSeries for AS/400, for example, to:

v Take a backup of the system, or v Update MQSeries for AS/400

Quiescing previous releases of MQSeries for AS/400

To quiesce one of the previous releases of MQSeries for AS/400:

1. Use F12 (Cancel) to return to your initial MENU

Note: If you have MQSeries Commands (CMDMQM) as your initial

2. Ensure that you have:

v *ALLOBJ authority, or object management authority for the QMQM and

QMQMADM libraries.

v *USE authority for the following programs:

– QMQM/AMQIQES4 – QMQM/AMQIQEM4 – QMQM/AMQSTOP4 – QMQM/AMQSPECA

Quiescing MQSeries

menu, change the initial menu in your user profile, sign off and sign back on.

Notes:

a. If you use QMQM/AMQIQES4 any user signed on to MQSeries, even if that

user is not running the product, will be logged off.

b. The QMQMADM library exists only if you have installed the MQSeries for

AS/400 Administration utility.

3. Warn all users that you are going to stop MQSeries for AS/400.

4. Warn users not to start Message Queue Interface applications while

MQSeries for AS/400 is being quiesced. To ensure that they cannot start, you should revoke users’ authorities to MQSeries for AS/400 by issuing the RVKMQMAUT command.

5. Exit the Administration utility, if it is running.

6. Quiesce the queue manager by running program AMQSTOP4:

CALL QMQM/AMQSTOP4 PARM(QMGRNAME *CNTRLD 15)

where QMGRNAME is the name of the queue manager and 15 is a time-out value in seconds.

7. If this fails, you can force the queue manager to stop by issuing:

CALL QMQM/AMQSTOP4 PARM(QMGRNAME *FORCE 15)

Chapter 4. Installing, Migrating to, and Deleting MQSeries for AS/400 23

Quiescing MQSeries

Quiescing V5.1 of MQSeries for AS/400

To quiesce MQSeries for AS/400, V5.1:

1. Use F12 (Cancel) to return to your initial MENU

Note: If you have MQSeries Commands (CMDMQM) as your initial

2. Ensure that you have:

v *ALLOBJ authority, or object management authority for the QMQM library. v *USE authority for the following programs:

– QMQM/AMQIQES4 – QMQM/AMQIQEM4 – QMQM/AMQSTOP4 – QMQM/AMQSPECA

3. Warn all users that you are going to stop MQSeries for AS/400.

4. Warn users not to start Message Queue Interface applications while

MQSeries for AS/400 is being quiesced. To ensure that they cannot start, you should revoke users’ authorities to MQSeries for AS/400 by issuing the RVKMQMAUT command.

5. Quiesce all queue managers by running program AMQSTOP4:

CALL QMQM/AMQSTOP4 PARM(*ALL *CNTRLD 15)

menu, change the initial menu in your user profile, sign off and sign back on.

where 15 is a time-out value in seconds.

6. If this fails, you can force queue managers to stop by issuing:

CALL QMQM/AMQSTOP4 PARM(*ALL *FORCE 15)

7. End the MQSeries subsystem, by entering:

ENDSBS SBS(QMQM/QMQM)

Migrating to MQSeries for AS/400, V5.1

You can migrate to MQSeries for AS/400, V5.1 from MQSeries for AS/400 V3R7, MQSeries for AS/400 V4R2, or MQSeries for AS/400 V4R2M1.

You must pay particular attention when migrating to MQSeries for AS/400, V5.1. The product has been altered and enhanced significantly since previous releases.

This section outlines the steps involved in migrating to MQSeries for AS/400, V5.1 from an earlier release. You may find additional, important information that became available after publication of this book if you refer to the readme file on the publications CD-ROM, or to the MQSeries family Web site at:

http://www.ibm.com/software/ts/mqseries/

MQSeries for AS/400, V5.1 Quick Beginnings

What are the Differences

MQSeries for AS/400, V5.1 provides significant new function over previous releases, including support for multiple queue managers, queue manager clusters, and substantially increased message and queue sizes. Enabling this new function has involved some changes to the internal architecture of MQSeries. For example this release makes substantial use of the Integrated File System whereas, previously, all MQSeries data was stored in OS/400 objects in libraries.

Another significant change with this release concerns security. To increase compatibility with the other V5.1 MQSeries platforms and also to provide authorization to individual MQI calls, the OS/400 object-based security model used in previous releases has been replaced by one using the MQSeries OAM (Object Authority Manager).

As a consequence of these, and other changes, migration to MQSeries for AS/400, V5.1 from a previously installed release requires special consideration and careful planning. Areas to which you should apply close attention include:

v Existing RPG, COBOL, and C applications using the MQI (MQSeries

Interface) should work successfully without the need for recompilation. There have been some changes in detail in the way some CL commands are implemented. CL programs using these commands might need to be edited and recompiled.

v All user exits including channel and data conversion exits must be

recompiled using ILE compilers, bound to the threaded MQSeries libraries, made thread-safe and enabled for teraspace memory. Details can be found in the MQSeries Application Programming Guide and the MQSeries Intercommunication book.

v MQSeries authorizations continue to be administered through the

GRTMQMAUT (Grant MQM Authority) and RVKMQMAUT (Revoke MQM Authority) commands, but there are substantial changes:

– Authorization lists and reference objects are no longer supported. – Authorizations that may be given to a user for MQSeries objects are now

grouped into four categories: MQI, Context, Administration, and Generic.

Migrating MQSeries

There are additional security considerations to take into account. For details see the MQSeries for AS/400 V5.1 System Administration book.

Overview of Migration Process

There are two possible migration scenarios: v Either you are migrating from a previous version of MQSeries on the same

machine, or

v You are transferring MQSeries to a new machine.

Chapter 4. Installing, Migrating to, and Deleting MQSeries for AS/400 25

Migrating MQSeries

The process is the same except that: v If you are moving to a new machine, there is one additional step, which is

to transfer data from the old machine to the new.

v If you are upgrading the system on the same machine, you must save your

MQSeries data because the migration process completely deletes your old version of the product.

To help you migrate, MQSeries for AS/400, V5.1 includes a utility program called MIGRATEMQM. This program migrates your MQSeries configuration and objects to MQSeries for AS/400, V5.1. It also creates a new queue manager with the same name as the original one. (This queue manager will act as the default queue manager on your new system unless you have already defined a default queue manager). The migration program reads information from the earlier release and creates a matching queue manager at the new level. It also creates all the MQSeries objects such as queues and channels. It copies messages held on the old queue manager’s queues to the new queue manager. It does not, however, migrate your authority definitions.

In MQSeries for AS/400, V5.1, each queue manager has its own library containing that queue manager’s journals and journal receivers. In earlier versions of MQSeries for AS/400, all the journals were in QUSRSYS and all the receivers were in QMQMDATA. The migration program obtains the configuration and message data from the journals and data library of the earlier release.

Before Migration

Before migrating to MQSeries for AS/400, V5.1, carry out the following procedure on the version of MQSeries for AS/400 that is currently installed:

1. Stop all applications that are using the existing version of MQSeries for

AS/400.

2. End all MQSeries channels. To do this, use the WRKMQMCHL command

and select option 15.

3. Exit the administration utility if it is running.

4. End the MQSeries command server. To do this, enter the command:

ENDMQMCSVR MQMNAME(QMGRNAME) OPTION(*IMMED)

where QMGRNAME is the name of the queue manager.

5. Remove any unwanted messages from your MQSeries queues. To do this,

use the WRKMQMMSG command and select option 4.

6. Resolve any in-doubt messages that are held by sender or server

channels. To do this, use the WRKMQMCHST command and select option 17.

7. Reset the media recovery point. To do this, enter the command:

RCDMQMIMG OBJ(*ALL) OBJTYPE(*ALL)

MQSeries for AS/400, V5.1 Quick Beginnings

Migrating MQSeries

8. Save details of your existing MQSeries authorities. To find these details,

issue the DSPMQMOBJN command to list the queue manager and all the MQSeries queues and processes that you have. Then issue the DSPMQMAUT command to list the access that users have to each of these objects.

9. Quiesce the product. To do this, refer to “Quiescing previous releases of

MQSeries for AS/400” on page 23.

10. Copy your MQSeries CL and MQSC files to a suitable save library such

as QGPL.

11. Save your MQSeries data:

v Create a save file for the libraries QMQMDATA and QMQMPROC. To

do this, issue the commands:

CRTSAVF FILE(QGPL/QMQMDATA) CRTSAVF FILE(QGPL/QMQMPROC)

v Save the libraries QMQMDATA and QMQMPROC into these save files.

To do this, enter the commands:

SAVLIB LIB(QMQMDATA) DEV(*SAVF) SAVF(QGPL/QMQMDATA) SAVLIB LIB(QMQMPROC) DEV(*SAVF) SAVF(QGPL/QMQMPROC)

v Create a save file for your journals. To do this, issue the command:

CRTSAVF FILE(QGPL/QMQMJRN)

v Save the journals into the save file:

SAVOBJ OBJ(AMQ*) LIB(QUSRSYS) DEV(*SAVF) OBJTYPE(*JRN) SAVF(QGPL/QMQMJRN)

12. If you are transferring MQSeries to a new machine, transfer the save files

to the new machine.

13. Do not start this step until you have saved all your MQSeries data.

When you have completed this step your data will be recoverable only from your saved images.

Delete your old version of MQSeries for AS/400. To do this, use the GO LICPGM menu and select option 12 (Delete licensed program). Select all the installable options of MQSeries for AS/400 and delete them.

Migration

To migrate to the new release of MQSeries for AS/400, follow this procedure. Note that you need *ALLOBJ authority to complete the procedure.

1. a. Install MQSeries for AS/400, V5.1. See “Installation Procedure” on

page 21 for details.

b. Verify the installation. See “Verifying the Installation” on page 22 for

details.

c. Perform the tasks described in “Post Installation Tasks” on page 22.

Chapter 4. Installing, Migrating to, and Deleting MQSeries for AS/400 27

Migrating MQSeries

2. Restore the MQSeries objects for libraries QMQMDATA and QMQMPROC

using the following commands:

RSTLIB SAVLIB(QMQMDATA) DEV(*SAVF) SAVF(QGPL/QMQMDATA) RSTLIB SAVLIB(QMQMPROC) DEV(*SAVF) SAVF(QGPL/QMQMPROC)

3. Restore the MQSeries local and remote journals using the following

command:

RSTOBJ OBJ(AMQ*) SAVLIB(QUSRSYS) DEV(*SAVF) OBJTYPE(*JRN) SAVF(QGPL/QMQMJRN)

4. Associate the journal receivers by: a. Issuing the command WRKJRN, specifying the journals

b. Using option 9 to associate the journals

5. Invoke the migration program MIGRATEMQM. To do this, issue the

command:

CALL PGM(QMQM/MIGRATEMQM)

This command may be issued from the command prompt, or may be submitted as a batch job. Depending on the number of MQSeries objects and the number of messages on queues, the program may take some time to complete. The program creates a default queue manager that matches the one on your previous release.

When the program has completed, check the job log for errors. If any errors were encountered during channel-definition migration (for example, no channel-definition file was found) or during the migration of channel-synchronization information (for example, no synchronization file was found), you can rerun these steps individually. To rerun channel-definition migration, enter:

CALL PGM(QMQM/AMQRMCHA) PARM(QMGRNAME)

QUSRSYS/AMQAJRN and QUSRSYS/AMQRJRN

where QMGRNAME is the name of the queue manager.

To rerun the migration of channel-synchronization information, enter:

CALL PGM(QMQM/AMQRMSYA) PARM(QMGRNAME)

6. If you wish to set up your work management environment, job descriptions, and pools, see the MQSeries for AS/400 V5.1 System Administration book for guidance. Otherwise, use the default setup.

7. Migrate and recompile your user exit programs. Recompile all OPM programs and programs that are not thread-safe, to make them ILE compliant and thread-safe. See the MQSeries Application Programming Guide and the MQSeries Intercommunication book for guidance on how to do this.

8. Reapply security to your MQSeries objects, using the command GRTMQMAUT. As mentioned earlier the authority model has changed in this release of MQSeries for AS/400. Use the information in the following tables as guidance for mapping the old authority to the new.

MQSeries for AS/400, V5.1 Quick Beginnings

Migrating MQSeries

Note: Any PCF applications must be given explicit access to the queues.

See the MQSeries for AS/400 V5.1 System Administration book for further information about security.

Table 2. Authorities required to open an object

Opening MQSeries object with option MQOO_

BROWSE *READ *BROWSE INPUT_AS_Q_DEF *READ and *DLT *GET INPUT_EXCLUSIVE *READ and *DLT *GET INPUT_SHARED *READ and *DLT *GET INQUIRE *READ *INQ OUTPUT *ADD *PUT SET *UPD *SET

Table 3. Authorities for Context and AlternateUserID

Opening MQSeries object with option MQOO_

ALTERNATE_USER AUTHORITY

PASS_ALL CONTEXT *MQMPASSALL (+ *READ

PASS_IDENTITY CONTEXT

SET_ALL CONTEXT *MQMSETALL (+ *ADD

SET_IDENTITY CONTEXT *MQMSETID (+ *UPD on

MQSeries object authority required - earlier releases

*MQMALTUSR (+ *DLT on ADM object)

and *OBJOPR on ADM object)

*MQMPASSID (+ *READ on ADM object)

and *UPD on ADM object)

ADM object)

MQSeries object authority required - V5.1

*ALTUSR

*PASSALL

*PASSID

*SETALL

*SETID

Verifying the Migration

Use the following procedure to check that you have migrated to MQSeries for AS/400, V5.1 successfully:

1. Make QMQMADM either the primary or a secondary group profile for

your user profile. To do this, enter one of the following commands:

CHGUSRPRF USRPRF(YOUR PROFILE) GRPPRF(QMQMADM) CHGUSRPRF USRPRF(YOUR PROFILE) SUPGRPPRF(QMQMADM)

Chapter 4. Installing, Migrating to, and Deleting MQSeries for AS/400 29

Migration Verification

2. Ensure that the MQSeries subsystem, QMQM, is active. To do this, issue the command:

DSPSBSD SBSD(QMQM/QMQM)

If it is inactive, issue the command:

STRSBS SBSD(QMQM/QMQM)

3. Ensure that the newly-created default queue manager is available. To check this, use the command:

DSPMQM

If it is not available, start it by issuing the command:

STRMQM MQMNAME(QMGRNAME)

4. If applicable, verify that the queue manager and its objects have been successfully retained. Some of the commands that you might use to do this are:

DSPMQM Display Message Queue Manager (MQM) DSPMQMOBJN OBJ(*ALL) Display MQM object names WRKMQMCHL Work with MQM channel WRKMQMMSG Work with MQM message WRKMQMQ Work with MQM queue

5. Use the commands DSPOBJAUT or DSPMQMAUT to review your authorizations to all types of MQSeries objects (*MQM, *Q, *ALSQ, *LCLQ, *RMTQ, *PRC, *CMD, *NMLIST).

Refer to “Chapter 5. Using MQSeries for AS/400, V5.1” on page 33 or to the online help for more information about these commands and how to use them.

After Migration

When you are satisfied that the migration has completed successfully, you may delete:

v MQSeries journals. To do this issue the commands:

DLTJRN JRN(QUSRSYS/AMQAJRN) DLTJRN JRN(QUSRSYS/AMQRJRN)

v MQSeries data libraries: To do this issue the commands:

DLTLIB LIB(QMQMDATA) DLTLIB LIB(QMQMPROC)

MQSeries for AS/400, V5.1 Quick Beginnings

Deleting MQSeries for AS/400, V5.1

There are two ways of deleting MQSeries for AS/400: v A standard deletion removes MQSeries product code but preserves user

data.

v An entire deletion removes both MQSeries product code and user data.

Standard Deletion

Perform a standard deletion of the MQSeries for AS/400 product if you wish to retain your user data, for example, because you intend to reinstall the product at a later date.

To perform this deletion:

1. Quiesce MQSeries for AS/400. (See “Quiescing V5.1 of MQSeries for

AS/400” on page 24.)

2. End the MQSeries subsystem, by entering:

ENDSBS SBS(QMQM/QMQM)

3. Ensure that no locks are held on the library QMQM.

4. Use the Delete Licensed Program (DLTLICPGM) command to delete the

base product (and also the samples if you chose to install them). To delete the base product and the samples enter:

DLTLICPGM LICPGM(5733A38) OPTION(*ALL)

Deleting MQSeries

To delete only the samples, you could enter:

DLTLICPGM LICPGM(5733A38) OPTION(1)

Deleting MQSeries for AS/400 in this way deletes only the objects that belong to MQSeries. That is, the QMQM library and /QIBM/ProdData/mqm and its subdirectories. None of the queue manager journal libraries or IFS directories is removed.

Entire Deletion

You can, if you wish, delete MQSeries entirely, including all user data. If you do this, save your user data first. It will not be recoverable.

To perform this deletion:

1. Using the WRKMQM command, select option 4 to delete all queue

managers on the system.

2. Quiesce MQSeries for AS/400. (See “Quiescing V5.1 of MQSeries for

AS/400” on page 24.)

Chapter 4. Installing, Migrating to, and Deleting MQSeries for AS/400 31

Deleting MQSeries

3. End the MQSeries subsystem, by entering:

ENDSBS SBS(QMQM/QMQM)

4. Delete the directory /QIBM/UserData/mqm and its subdirectories. Do this using the EDTF command and then use option 9 for the mqm directory.

Note: If you do this, you will no longer have any information regarding

Alternatively, you can delete /QIBM/UserData/mqm and its subdirectories by repeated use of the RMVLNK and RMVDIR commands.

5. Ensure that no locks are held on the library QMQM.

6. Use the Delete Licensed Program (DLTLICPGM) command to delete the

base product (and also the samples if you chose to install them). To delete the base product and the samples enter:

DLTLICPGM LICPGM(5733A38) OPTION(*ALL)

7. Identify all the users who belong to the QMQMADM group. Use the DSPUSRPRF command to display a list of them. You need to remove the QMQMADM group profile from their user profiles before you can delete the QMQMADM user profile. The format of the command is:

DSPUSRPRF USRPRF(QMQMADM) TYPE(*GRPMBR)

8. For each of the user profiles QMQM, QMQMADM, and NOBODY, use the WRKOBJOWN command to list all the objects owned by the profile. You need to alter the ownership or delete the objects before you can delete the user profile. The format of the command is:

WRKOBJOWN USRPRF(PROFILE)

your installation. Use this command with extreme caution. The format of the command is:

EDTF STMF('/QIBM/UserData')

MQSeries for AS/400, V5.1 Quick Beginnings

Chapter 5. Using MQSeries for AS/400, V5.1

This chapter introduces MQSeries command sets and some basic tasks that you can perform to get yourself started with MQSeries for AS/400, V5.1.

Tasks include creating and starting a queue manager, and creating, clearing, browsing, and deleting a local queue. The examples given use CL commands, but you can select the appropriate command from any of the supplied command sets.

Before you Start

Before you can use MQSeries for AS/400 you must start a subsystem. If you have not already done so, issue the command:

STRSBS SBSD(QMQM/QMQM)

To use MQSeries CL commands, for example CRTMQM (create queue manager) or STRMQM (start queue manager), your user profile must be a member of the group profile QMQMADM. Use the CHGUSRPRF command to change your user profile, and specify QMQMADM against either the group profile (GRPPRF) parameter or the supplementary group profile (SUPGRPPRF) parameter.

It is not essential for your user profile to belong to the QMQMADM group profile for issuing PCF commands from an administration program or MQI calls from an application program.

If you have installed the samples, ensure that all users have access to the QMQMSAMP library. Do this using the GRTOBJAUT command:

GRTOBJAUT OBJ(QMQMSAMP) OBJTYPE(*LIB) USER(*PUBLIC) AUT(*USE)

For details of MQSeries Work Management and security, see the MQSeries for AS/400 V5.1 System Administration book.

Introducing Command Sets

MQSeries provides three command sets for performing administration tasks:

v Command Language commands (CL commands) v MQSC commands v PCF commands

Before you Start

CL Commands

The AS/400 CL commands for MQSeries can be grouped as follows:

v Channel commands - used to create, start, and delete channels. v Cluster commands - used to work with queue manager clusters. v Command server commands - used to display, start, and end the command

v Data type conversion command - used to convert data types. v Dead-letter queue handler command - used to start the dead-letter queue

v Media recovery commands - used to record and re-create objects. v MQSeries command - used to start a batch of MQSeries commands. v Name command - used to display object names. v Namelist commands - used to work with namelists. v Process commands - used to change, copy, and delete processes. v Queue commands - used to create, delete, and work with queues. v Queue manager commands - used to connect, create, and delete queue

v Security commands - used to display, grant, and revoke object authority. v Trace command - used to trace service jobs. v Transaction commands - used to display and resolve transactions. v Trigger monitor commands - used to start trigger monitors.

server.

handler.

managers.

Using CL Commands

You can enter CL commands from a command line.

The following table gives a brief description of each MQSeries CL command. To display online help for a CL command, enter the command and press F1. To see a full list of MQSeries commands, enter the command GO CMDMQM from the MQSeries menu.

Command Usage

CCTMQM (connect message queue manager) supported only for compatibility with previous

CHGMQM (change message queue manager) to change the attributes of a message queue

CHGMQMCHL (change MQM channel) to change the attributes of an existing channel. CHGMQMNL (change MQM namelist) to change the attributes of a namelist. CHGMQMPRC (change MQM process) to change the attributes of a process definition. CHGMQMQ (change MQM queue) to change the attributes of a queue. CLRMQMQ (clear MQM queue) to delete all messages from a local queue. CPYMQMCHL (copy MQM channel) to create a copy of an existing channel

CPYMQMNL (copy MQM namelist) to create a copy of a namelist. CPYMQMPRC (copy MQM process) to create a copy of a process definition. CPYMQMQ (copy MQM queue) to create a copy of an existing queue definition. CRTMQM (create message queue manager) to create a local queue manager. CRTMQMCHL (create MQM channel) to create a new channel definition.

releases.

manager.

definition.

MQSeries for AS/400, V5.1 Quick Beginnings

Before you Start

Command Usage

CRTMQMNL (create MQM namelist) to create a new namelist. CRTMQMPRC (create MQM process) to create a new process definition. CRTMQMQ (create MQM queue) to create a queue definition. CVTMQMDTA (convert MQM data type

command) DLTMQM (delete message queue manager) to delete a local queue manager. DLTMQMCHL (delete MQM channel) to delete a channel definition. DLTMQMNL (delete MQM namelist) to delete a namelist. DLTMQMPRC (delete MQM process) to delete a process definition. DLTMQMQ (delete MQM queue) to delete a queue. DSCMQM (disconnect message queue

manager) DSPMQM (display message queue manager) to display the attributes of a local queue

DSPMQMAUT (display MQM object authority) to display a list of authorized users and their

DSPMQMCHL (display MQM channel) to display the attributes of a channel definition. DSPMQMCSVR (display MQM command

server) DSPMQMNL (display MQM namelist) to display the attributes of a namelist. DSPMQMOBJN (display MQM object names) to display the AS/400 name and type for any

DSPMQMPRC (display MQM process) to display the attributes of a process definition. DSPMQMQ (display MQM queue) to display the attributes of a queue definition. ENDMQM (end message queue manager) to end the local message queue manager. ENDMQMCHL (end MQM channel) to close a channel. ENDMQMCSVR (end MQM command server) to stop the command server for a specified

ENDMQMLSR (end MQM listener) to stop the MQSeries listener program. GRTMQMAUT (grant MQM object authority) to grant specific authority for an object to other

PNGMQMCHL (ping MQM channel) to test a channel. RCDMQMIMG (record MQM object image) to provide a marker for a selected set of

RCRMQMOBJ (re-create MQM object) to provide recovery for a damaged set of

RFRMQMCL (refresh cluster) to refresh the cluster information that a queue

RSMMQMCLQM (resume cluster queue manager)

RSTMQMCHL (reset MQM channel) to reset the message sequence number for a

RSTMQMCL (reset queue manager cluster) to reset the information held in a cluster about

RSVMQMCHL (resolve MQM channel) to request a channel to commit or back out

RSVMQMTRN (resolve MQSeries transaction) to resolve in-doubt MQSeries transactions. RVKMQMAUT (revoke MQM authority) to remove authority for named objects.

to create a fragment of code that performs data conversion on data type structures.

supported only for compatibility with previous releases.

manager.

authorities for a specified object.

to display the status of the command server.

object name and type.

local queue manager.

users.

objects.

manager has stored. to inform cluster queue managers that the local

queue manager has become available.

channel to a specific number.

its queue managers.

in-doubt messages.

Chapter 5. Using MQSeries for AS/400, V5.1 35

Before you Start

Command Usage

SPDMQMCLQM (suspend cluster queue manager)

STRMQM (start message queue manger) to start a local queue manager. STRMQMCHL (start MQM channel) to start a channel. STRMQMCHLI (start MQM channel initiator) to start a channel initiator. STRMQMCSVR (start MQM command server) to start a command server for a queue

STRMQMDLQ (start MQSeries dead-letter queue handler)

STRMQMLSR (start MQM listener) to start a message queue manager listener. STRMQMMQSC (start MQSeries commands) to initiate a set of MQSeries commands. STRMQMTRM (start trigger monitor) to start a trigger monitor. TRCMQM (trace MQM job) to start and stop MQSeries trace. WRKMQM (work with message queue

managers) WRKMQMCHL (work with MQM channel) to work with channel definitions. WRKMQMCHST (work with MQM channel

status) WRKMQMCL (work with clusters) to work with clusters. WRKMQMCLQ (work with cluster queues) to work with cluster queues. WRKMQMMSG (work with MQM messages) to work with specified messages on a local

WRKMQMNL (work with MQM namelists) to work with namelists. WRKMQMPRC (work with MQM process) to work with process definitions. WRKMQMQ (work with MQM queues) to work with queues. WRKMQMTRN (work with MQSeries

transactions)

to inform cluster queue managers that the local queue manager is not available.

manager. to start the dead-letter queue handler.

to work with queue managers.

to work with the status of channel definitions.

queue.

to work with in-doubt MQSeries transactions.

MQSeries (MQSC) Commands

You use the MQSeries (MQSC) commands to manage queue manager objects, including the queue manager itself, channels, queues, and process definitions. For example, there are commands to define, alter, display, and delete a specified queue.

When you display a queue, using the DISPLAY QUEUE command, you display the queue attributes. For example, the MAXMSGL attribute specifies the maximum length of a message that can be put on the queue. The command does not show you the messages on the queue.

For detailed information about each MQSC command, see the MQSeries Command Reference.

Running MQSC Commands

You run MQSC commands by entering the CL command STRMQMMQSC on the command line. This allows you to run a series of commands that you have previously entered in a member of a source physical file.

MQSeries for AS/400, V5.1 Quick Beginnings

PCF Commands

MQSeries programmable command format (PCF) commands allow you to program administration tasks into an administration program. For a complete description of the PCF commands and how to use them, see the MQSeries Programmable System Management book.

Working with MQSeries

If you are new to MQSeries for AS/400, you are recommended to set up a test system. Then you can verify that you have installed the product correctly and perform some basic MQSeries operations.

To set up a test system you need to create a queue manager and a local queue. As an introduction to MQSeries for AS/400, create these objects with CL commands from the command line, and work through the AS/400 panels.

Creating a Queue Manager

1. Issue the CRTMQM command from the command line and press F4. The

screen shown in Figure 1 appears.

Type choices, press Enter.

Message Queue Manager name... __________________________________________ ______

Text ’description’ ....... *BLANK____________________________________

___________________________________

Trigger interval........ 999999999__ 0-999999999

Undelivered message queue . . . *NONE_____________________________________ ______ Default Transmission queue... *NONE_____________________________________ ______

Maximum handle limit...... 256________ 1-999999999

Maximum uncommitted messages . . 10000______ 1-10000

Default Queue Manager ..... *NO *YES, *NO

Before you Start

Create Message Queue Manager (CRTMQM)

F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display F24=More keys Parameter MQMNAME required.

Figure 1. CRTMQM panel

Bottom

If the screen does not appear, it may be that you have not installed MQSeries for AS/400 correctly. If this is the case, delete the product as described in “Deleting MQSeries for AS/400, V5.1” on page 31. Then reinstall the *BASE product and try the CRTMQM command again.

Chapter 5. Using MQSeries for AS/400, V5.1 37

Working with MQSeries

2. On the CRTMQM panel, type in a Message Queue Manager name, for example TEST.QMANAGER and press Enter.

The name of the queue manager can be a maximum of 48 characters in length. Valid characters are detailed in MQSeries for AS/400 V5.1 System Administration book.

The queue manager is then created, along with a set of default objects.

Starting a Queue Manager

Start the queue manager from the command line by issuing the command:

STRMQM MQMNAME(QMGRNAME)

where QMGRNAME is the name of the queue manager that you have just created.

After a short period you receive the message Message Queue Manager started.

Creating a Local Queue

To create a local queue:

1. Type CRTMQMQ on the command line and press F4. This displays the following panel:

Type choices, press Enter.

Queue name........... __________________________________________

_____

Queue type........... *ALS, *LCL, *MDL, *RMT

Message Queue Manager name... *DFT______________________________________ _____

Create MQM Queue (CRTMQMQ)

F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display F24=More keys Parameter QNAME required.

Figure 2. CRTMQMQ panel (part 1)

2. On the Create MQM Queue panel, type the name of the queue you want

to create in the Queue name field. For example TEST.QUEUE. To specify a mixed-case name, enclose the name in apostrophes.

3. Type *LCL in the Queue type field.

MQSeries for AS/400, V5.1 Quick Beginnings

Bottom

Working with MQSeries

4. Fill in the name of your queue manager in the

Message Queue Manager name field. For example TEST.QMANAGER.

5. Press Enter.

There are three more parts to the CRTMQMQ panel. Scroll through them and enter values for the other options if you wish, or otherwise just accept all the defaults. The panels are shown in Figure 3 through Figure 5.

Create MQM Queue (CRTMQMQ)

Type choices, press Enter.

Queue name...........>TEST.QUEUE_________________________________

_____

Queue type...........>*LCL *ALS, *LCL, *MDL, *RMT

Message Queue Manager name...>TEST.QMANAGER______________________________ _____

Replace ............ *NO *NO, *YES

Text 'description'....... ''________________________________________

__________________________________

Put enabled .......... *YES *SYSDFTQ, *NO, *YES

Default message priority.... 0 0-9, *SYSDFTQ

Default message persistence . . *NO *SYSDFTQ, *NO, *YES

Process name.......... ''________________________________________

_____

Triggering enabled....... *NO *SYSDFTQ, *NO, *YES

Get enabled .......... *YES *SYSDFTQ, *NO, *YES

Sharing enabled ........ *YES *SYSDFTQ, *NO, *YES

F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display F24=More keys

More...

Figure 3. Create MQM Queue panel (part 2)

Chapter 5. Using MQSeries for AS/400, V5.1 39

Working with MQSeries

Type choices, press Enter.

Default share option...... *YES *SYSDFTQ, *NO, *YES

Message delivery sequence . . . *PTY *SYSDFTQ, *PTY, *FIFO

Harden backout count...... *YES *SYSDFTQ, *NO, *YES

Trigger type.......... *FIRST *SYSDFTQ, *FIRST, *ALL...

Trigger depth ......... 1 1-999999999, *SYSDFTQ

Trigger message priority.... 0 0-9, *SYSDFTQ

Trigger data.......... ''________________________________________

_____

Retention interval....... 999999999 0-999999999, *SYSDFTQ

Maximum queue depth ...... 5000 0-640000, *SYSDFTQ

Maximum message length..... 4194304 0-4194304, *SYSDFTQ

Backout threshold ....... 0 0-999999999, *SYSDFTQ

Backout requeue name...... ''________________________________________

_____

Initiation queue........ ''________________________________________

_____

F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display F24=More keys

Figure 4. Create MQM Queue panel (part 3)

Type choices, press Enter.

Usage ............. *NORMAL *SYSDFTQ, *NORMAL, *TMQ

Queue depth high threshold... 80 0-100, *SYSDFTQ Queue depth low threshold . . . 20 0-100, *SYSDFTQ Queue full events enabled . . . *YES *SYSDFTQ, *NO, *YES Queue high events enabled . . . *YES *SYSDFTQ, *NO, *YES

Queue low events enabled.... *YES *SYSDFTQ, *NO, *YES

Service interval........ 999999999 0-999999999, *SYSDFTQ

Service interval events .... *NONE *SYSDFTQ, *HIGH, *OK, *NONE

Distribution list support . . . *NO *SYSDFTQ, *NO, *YES

Cluster Name.......... ''________________________________________

_____

Cluster Name List ....... ''________________________________________

_____

Default Binding ........ *OPEN *SYSDFTQ, *OPEN, *NOTFIXED

Create MQM Queue (CRTMQMQ)

More...

Create MQM Queue (CRTMQMQ)

F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display F24=More keys

Figure 5. Create MQM Queue panel (part 4)

When you have finished reviewing and making changes to the values, press Enter to create the queue.

MQSeries for AS/400, V5.1 Quick Beginnings

Bottom

Sending a Test Message

To put a test message on your queue use the supplied sample programs. For example, to put messages to a queue called TEST.QUEUE, defined for a queue manager called TEST.QMANAGER, enter the command:

CALL PGM(QMQM/AMQSPUT0) PARM(TEST.QUEUE TEST.QMANAGER)

You can now type a message (a simple character string is sufficient) and press Enter to send the message to the queue. Press Enter again to return to a command line.

To see the message on the queue, either:

v Browse the queue (see “Browsing Queues”), or v Type CALL PGM(QMQM/AMQSGET4) PARM(TEST.QUEUE TEST.QMANAGER) on a

command line.

See “Appendix A. Sample MQI Programs” on page 99 for a list of the supplied sample programs.

Browsing Queues

To browse the messages on a local queue called TEST.QUEUE, defined for a queue manager called TEST.QMANAGER, use the following command:

WRKMQMMSG MQMNAME(TEST.QMANAGER) QNAME(TEST.QUEUE)

Working with MQSeries

This command displays all messages on the queue, and allows you to view the message contents.

Clearing a Local Queue

To delete all the messages on a local queue called TEST.QUEUE, defined for a queue manager called TEST.QMANAGER, use the following command:

CLRMQMQ MQMNAME(TEST.QMANAGER) QNAME(TEST.QUEUE)

Deleting a Local Queue

To delete a local queue called TEST.QUEUE, defined for a queue manager called TEST.QMANAGER, use the following command:

DLTMQMQ MQMNAME(TEST.QMANAGER) QNAME(TEST.QUEUE)

Note: You must delete all messages from the queue using the CLRMQMQ

command before you can delete a queue.

Stopping a Queue Manager

There are two ways of quiescing a queue manager:

1. Either use the command ENDMQM MQMNAME(QMGRNAME), where QMGRNAME is the

name of the queue manager, or

2. Enter the command WRKMQM *ALL, enter option 6 (end) against the queue

manager name, and then press F4.

Chapter 5. Using MQSeries for AS/400, V5.1 41

Working with MQSeries

There are 4 options you can use when ending a queue manager:

1. OPTION (*CNTRLD). This allows current transactions to complete, and all applications to disconnect, before ending the queue manager. This option is the default.

2. OPTION (*IMMED). This immediate shutdown allows any current calls to complete, but stops any new calls. It does not wait for applications to disconnect from the queue manager.

3. OPTION (*WAIT). This performs the same type of shutdown as the (*CNTRLD) option, but gives you confirmation that the queue manager has

ended. The command prompt does not return until the queue manager has ended.

4. OPTION (*PREEMPT). This preemptive shutdown ends all queue manager code immediately. It can have unpredictable consequences and should not be used unless all other options have failed.

Deleting a Queue Manager

To delete a queue manager, first stop it, then issue the command:

DLTMQM MQMNAME(QMGRNAME)

Note: When you delete a queue manager you also delete all resources

associated with that queue manager, including all queues, all messages, and all object definitions.

Checking what Queue Managers you have Running

Sometimes you may want to remind yourself how many queue managers you have running. You can do this using the WRKMQM command. Enter the command with no parameters. A list of all configured queue managers will be displayed, showing which are active and which are inactive.

Other Things to Do

The test system set up in “Working with MQSeries” on page 37 allows you to manage a single queue manager and queue. In reality you will need many more tasks and MQSeries objects to use MQSeries effectively. For example, you must also create: v A remote queue (that is, a local definition for a queue on a remote queue

manager)

v A transmission queue v Sender and receiver channels

You also need to start a channel listener if you are using TCP, and you may want to start a channel initiator too. Refer to the MQSeries for AS/400 V5.1 System Administration book, for details of how to set up and use these objects.

MQSeries for AS/400, V5.1 Quick Beginnings

User Exits

Before using user exits on MQSeries for AS/400, V5.1, relink them with the threaded libraries and ensure that they are thread-safe and teraspace enabled. See the MQSeries Application Programming Guide and the MQSeries Intercommunication book for further information about creating user exit programs.

Setting the Queue Manager CCSID for MQSeries for AS/400

When you create a queue manager, its coded character set identifier (CCSID) is set by default. It is set to the value of the CCSID of the OS/400 job you used to create the queue manager.

You can query the value of this CCSID by entering the DSPMQM CL command. This displays the attributes of the local queue manager, including the coded character set identifier.

You can modify the queue manager’s CCSID by using the CHGMQM CL command. Before doing this, make a note of the original CCSID value in case you need to reset it at a later date. To change the CCSID, follow this procedure:

1. Issue the DSPMQM command and make a note of the CCSID value.

2. Change the CCSID to the new CCSID, with the command:

CHGMQM CCSID(value)

3. Stop the queue manager with the ENDMQM command.

4. Restart the queue manager with the STRMQM command and also restart

any channels that it uses.

User Exits

For information about code sets and CCSIDs that are supported by MQSeries for AS/400 see the AS/400 National Language Support book. See the MQSeries Command Reference for more information about MQSeries commands.

Chapter 5. Using MQSeries for AS/400, V5.1 43

44 MQSeries for AS/400, V5.1 Quick Beginnings

Chapter 6. Planning to Install MQSeries Clients

This chapter provides a summary of the hardware and software required to run the following MQSeries clients:

v MQSeries client for AIX v MQSeries client for DOS v MQSeries client for HP-UX v MQSeries client for OS/2 Warp v MQSeries client for Sun Solaris v MQSeries client for Windows 3.1 v MQSeries client for Windows 95 and Windows 98 v MQSeries client for Windows NT

You can install all of these clients from the MQSeries Client CD. The Client CD also contains other MQSeries components that you might need to install on a workstation other than the server.

Applications on Version 5 Clients

A Version 5 client can connect to all queue managers, non-Version 5 as well as Version 5. If you are connecting to a non-Version 5 queue manager, you cannot use the new Version 5.1 features and structures in your MQSeries application on the client.

AIX Client: Hardware and Software Required

This section outlines the hardware and software requirements for an MQSeries client for AIX.

Hardware

An MQSeries client can run on an IBM RISC System/6000®, capable of running AIX Version 4.2 or later. Any other trademarked AIX system can be used, whether from IBM or other vendors such as Bull, Zenith, or Motorola. There must be enough random access memory (RAM) and disk storage for the programming prerequisites (below), the MQSeries client, the access methods, and the application programs.

Software

The following are prerequisites for MQSeries applications running on an AIX client.

Minimum supported software levels are shown. Later levels, if any, will be supported unless otherwise stated.

Hardware and Software, AIX

v AIX Version 4.2 (5765-655 or 5765-C34) or AIX Version 4.3 or later.

Later levels of some listed products might be required for AIX Version 4.2, SMP, and SP support corequisite products.

Connectivity

For TCP/IP connectivity: v TCP/IP (in the operating system)

™

. Later levels of operating system might be required to

For SNA LU 6.2 connectivity: v IBM eNetwork

Optional software

v IBM DCE Version 2.2. This must be the U.S. Domestic version supporting

DES encryption if the user wishes to run the MQSeries-supplied DCE send, receive, or message exits.

MQSeries DCE names and security modules are provided as part of the MQSeries for AIX product.

Compilers for MQSeries Applications on AIX Clients

The following compilers are supported:

v IBM C for AIX, Version 4.4 v IBM C Set++ for AIX, Version 3.1 (5765-421) v IBM C and C++ compiler, Version 3.6 v IBM VisualAge C++ Professional for AIX, Version 4.0 v IBM COBOL Set for AIX, Version 1.1 v Micro Focus COBOL Compiler for UNIX v IBM PL/I Set for AIX, Version 1.1 v IBM VisualAge Java Enterprise Edition for AIX, Version 2.0

Components for AIX

MQSeries Client

™

Communications Server for AIX, Version 5.0

, Version 4.0

The MQSeries client code for your UNIX platform.

Samples

Sample application programs.

Support for DCE in Samples

The DCE samples support. This should be installed only if you are going to use DCE.

Run-time component

Support for external applications. This does not enable you to write your own applications.

Base Support to enable you to create and support your own applications.

Requires the run-time component to be installed.

MQSeries for AS/400, V5.1 Quick Beginnings

MQSeries Client for Java

This allows Java applets running on your client machine to communicate with MQSeries. It includes security exits for encryption and authentication of messages sent across the Web by the MQSeries Client for Java. These exits consist of some Java classes. To use the client for Java you need to have Java run-time code on your machine, at the following (or later compatible) levels:

AIX Java version 1.1.1 HP-UX Java version 1.1.2 Sun Solaris Java version 1.1.1

For information about Java run-time see the MQSeries Using Java book.

Note: If it is possible on your platform, at installation time the

CLASSPATH environment variable will either be updated if already present, or created if not.

MQSeries Internet Gateway documentation

MQSeries Internet Gateway documentation supplied in HTML format.

MQSeries Internet Gateway

Provides access to MQSeries applications via HTML and CGI (only CGI on the Sun Solaris platform). The MQSeries Internet Gateway does not support NSAPI on the HP-UX platform.

Components for AIX

Digital UNIX Client: Hardware and Software Required

This section outlines the hardware and software requirements for an MQSeries client for Digital UNIX (Compaq Tru64 UNIX).

Hardware

An MQSeries client can run on any Digital Alpha machine capable of running Digital UNIX, Version 4.0.D.

Software

The following are prerequisites for MQSeries applications running on a Digital UNIX client.

Minimum supported levels are shown. Later levels, if any, will be supported unless otherwise stated.

v Digital UNIX, Version 4.0.D or later Version 4.0.x

Connectivity

For TCP/IP connectivity, any communications hardware supporting TCP/IP in the Digital UNIX environment can be used.

Chapter 6. Planning to Install MQSeries Clients 47

Hardware and software, Digital UNIX

Compilers for MQSeries applications on Digital UNIX clients

The following compiler is supported: v DEC C, Version 5.2 for Digital UNIX

DOS Client: Hardware and Software Required

This section outlines the hardware and software requirements for an MQSeries client for DOS.

Hardware

An MQSeries client can run on DOS, on a personal computer. There must be enough random access memory (RAM) and disk storage for the programming prerequisites (below), the MQSeries client, the access methods, and the application programs.

Software

The following are prerequisites for MQSeries applications running on a DOS client.

Minimum supported software levels are shown. Later levels, if any, will be supported unless otherwise stated.

v DOS, Version 5.0 or later

Connectivity

v TCP/IP (in the operating system) v SPX

Optional software

v Novell Netware Client for DOS/Win, Version 1.20 and Version 2.5 v Novell LAN Workplace, Version 5.1 v FTP PC/TCP for DOS, Version 5.0

The DOS access kit allows clients access to TCP/IP via programs that run in a DOS window under WIN-OS/2

The Novell Netware Client for OS/2 Warp allows clients access to SPX via programs that run in a DOS window under WIN-OS/2.

Compilers for MQSeries Applications on DOS Clients

The following compiler is supported: v Microsoft

MQSeries for AS/400, V5.1 Quick Beginnings

Visual C++, Version 1.5

Components for DOS

MQSeries Client

The MQSeries client code for your platform.

MQSeries Toolkit

This includes: v Sample programs - some of these are required for verifying the

installation of the MQSeries client/server system

v Header files that you can use when writing applications to run on

the client

HP-UX Client: Hardware and Software Required

This section outlines the hardware and software requirements for an MQSeries client for HP-UX.

Hardware

An MQSeries client can run on HP-UX on any HP 9000 Series 700 or Series 800 or Stratus Continuum/400 machine, with minimum system disk space of 20 MB.

Software

The following are prerequisites for MQSeries applications running an HP-UX client.

Components for DOS

Minimum supported levels are shown. Later levels, if any, will be supported unless otherwise stated.

v HP-UX, Version 10.20 v HP-UX, Version 11

Connectivity

For TCP/IP connectivity: v TCP/IP (in the operating system)

For SNA connectivity: v HP SNAplusII

Optional software

v The HP DCE/9000 version appropriate for the level of the HP-UX operating

system in use.

v MQSeries DCE names and security modules are provided as part of the

MQSeries for HP-UX product.

Chapter 6. Planning to Install MQSeries Clients 49

Hardware and Software, HP-UX

Compilers for MQSeries Applications on HP-UX Clients

The following compilers are supported:

v Micro Focus COBOL for UNIX, Version 4.0 v HP-UX ANSI C compiler v C Softbench, Version 5.0 v HP CFRONT C++, Version 3.1 v IBM C and C++ compilers, Version 3.6 v HP ANSI C++

Components for HP-UX

These are identical to those for AIX. See “Components for AIX” on page 46.

OS/2 Warp Client: Hardware and Software Required

This section outlines the hardware and software requirements for an MQSeries client for OS/2 Warp.

Hardware

An MQSeries client can run on OS/2 Warp, on a personal computer. There must be enough random access memory (RAM) and disk storage for the programming prerequisites (below), the MQSeries client, the access methods, and the application programs.

The system unit must have a CD-ROM device.

Software

The following are prerequisites for MQSeries applications running an OS/2 Warp client.

This is the minimum supported software level. Later levels, if any, will be supported unless otherwise stated.

v OS/2 Warp, Version 4.0 (84H1426) (5622-851) v OS/2 Warp Server, Version 4.0 (25H8002) v OS/2 Warp Server Advanced SMP feature, Version 4.0 v OS/2 Workspace-on-Demand

Connectivity

v IBM eNetwork Communications Server for OS/2 Warp, Version 5.0 v Novell Netware Client for OS/2 Warp, Version 1.20 (for direct IPX/SPX

support)

v IntraNetWare Client for OS/2 Warp, Version 2.12 v TCP/IP for OS/2 Warp, Version 2.0 base kit plus NetBIOS kit, Version 3.5

(base kit is essential)

v NetWare for OS/2 Warp, Version 4.11

MQSeries for AS/400, V5.1 Quick Beginnings

Hardware and Software, OS/2 Warp

Optional software

v IBM Directory and Security Server for OS/2 Warp, Version 4 or later

compatible versions. This must be the U.S. Domestic version supporting DES encryption if the user wishes to run the MQSeries-supplied DCE send, receive, or message exits.

v If used as a DCE server this software is known to run adequately in the

following environment: – On a Pentium

processor running 90 MHz or faster – On a machine with 64 MB or more of memory – Using OS/2 Warp Server, Version 4.0 or later

v MQSeries DCE names and security modules are provided as part of the

MQSeries for OS/2 Warp product.

Compilers for MQSeries Applications on OS/2 Warp Clients

The following compilers are supported:

v IBM VisualAge v Micro Focus COBOL compiler, Version 4.0 (32 bit) v IBM VisualAge C++ for OS/2 Warp, Version 3.0 v Borland C++ compiler, Version 2.0 and Version 5.02 (C bindings only) v IBM C and C++ compilers, Version 3.6 v IBM PL/I for OS/2 Warp, Version 1.2 v IBM VisualAge for PL/I for OS/2 Warp v IBM VisualAge Java Enterprise Edition for OS/2 Warp, Version 2.0 v IBM VisualAge Java Professional Edition for OS/2 Warp, Version 2.0

COBOL for OS/2 Warp, Version 1.1 and Version 2.2

Components for OS/2 Warp

MQSeries Client

The MQSeries client code for your platform.

MQSeries Development Toolkit

This includes:

v Sample programs v Header files that you can use when writing applications to run on

the client

MQSeries Client for Java

This allows Java applets running on your client machine to communicate with MQSeries. It includes security exits for encryption and authentication of messages sent across the Web by the MQSeries Client for Java. These exits consist of some Java classes. To use the client for Java you need Java 1.1.1 (or later compatible version) runtime code on your machine. On Windows NT, you require Microsoft Windows NT Version 4. On OS/2 Warp the MQSeries client

Chapter 6. Planning to Install MQSeries Clients 51

Components for OS/2 Warp

for Java must be installed on an HPFS formatted drive. For information about Java runtime see “HTML and PDF Books on the World Wide Web” on page 96.

Note: If it is possible on your platform, at installation time the

CLASSPATH environment variable will either be updated if already present, or created if not.

MQSeries Internet Gateway documentation

MQSeries Internet Gateway documentation supplied in HTML format.

MQSeries Internet Gateway

Provides access to MQSeries applications via HTML and CGI.

Sun Solaris Client: Hardware and Software Required

This section outlines the hardware and software requirements for an MQSeries client for Sun Solaris.

Hardware

An MQSeries client can run only on:

v Sun SPARC desktop or server v Sun UltraSPARC desktop or server

with a minimum system disk space of 25 MB.

Note: Solaris systems from other manufacturers are not supported.

For connectivity, any communications hardware supporting SNA LU 6.2 or TCP/IP.

Software

The following are prerequisites for MQSeries applications running on a Sun Solaris client.

Minimum supported software levels are shown. Later levels, if any, will be supported unless otherwise stated. v Sun Solaris, Version 2.6 with patches 105210-13 and 105568-10, and Sun

Connectivity

v SunLink SNA Peer-to-Peer, Version 9.1 v TCP/IP as part of the base operating system v If token ring is to be used: SunLink Token Ring Interface /SBus, Version

Solaris 7.

3.0.2. This requires patch 102463 or Sun TRI/P Adapter, Version 1.0

MQSeries for AS/400, V5.1 Quick Beginnings

Hardware and Software, Sun Solaris

Optional software

Transarc DCE, Version 1.1. This must be the U.S. version supporting DES encryption for users to run the MQSeries-supplied DCE send, receive or message exits.

DCE names and security modules for MQSeries are provided as part of the MQSeries for Sun Solaris product.

Compilers for MQSeries Applications on Sun Solaris Clients

The following compilers are supported:

v SunWorkShop Compiler C, Version 4.2 v SunWorkShop Compiler C++, Version 4.2

Components for Sun Solaris

These are identical to those for AIX. See “Components for AIX” on page 46.

Windows 3.1 Client: Hardware and Software Required

This section outlines the hardware and software requirements for an MQSeries client for Windows 3.1.

Hardware

An MQSeries client can run on Windows 3.1, on a personal computer. There must be enough random access memory (RAM) and disk storage for the programming prerequisites (below), the MQSeries client, the access methods, and the application programs.

Software

The following are prerequisites for MQSeries applications running on a Windows 3.1 client.

Minimum supported software levels are shown. Later levels, if any, will be supported unless otherwise stated.

v Windows 3.1 v Windows 95 in 16-bit mode v Windows for Workgroups

Connectivity

v TCP/IP v SPX

Optional software

v Novell Netware client for DOS/Win31, Version 1.20 v SunPC NSF, Version 5.1 v OnNet SDK for Windows

Chapter 6. Planning to Install MQSeries Clients 53

Hardware and Software, Windows 3.1

Compilers for MQSeries Applications on Windows 3.1 Clients

The following compiler is supported: v Microsoft Visual C++, Version 1.5

Components for Windows 3.1

These are identical to those for DOS. See “Components for DOS” on page 49.

Windows 95 and Windows 98 Client: Hardware and Software Required

This section outlines the hardware and software requirements for an MQSeries client for Windows 95 and Windows 98.

Hardware

An MQSeries client can run on Windows 95 or Windows 98 on a personal computer. There must be enough random access memory (RAM) and disk storage for the programming prerequisites (below), the MQSeries client, the access methods, and the application programs.

Software

The following are prerequisites for MQSeries applications running on a Windows 95 and Windows 98 client.

Minimum supported software levels are shown. Later levels, if any, will be supported unless otherwise stated.

v Windows 95 or Windows 98

Connectivity

v TCP/IP (in the operating system) v SPX (in the operating system) v NetBIOS (in the operating system)

Optional software:

v IBM DCE for Windows 95, Version 1.1

A DCE security module is provided as part of the MQSeries client for Windows 95 and Windows 98. IBM DCE for Windows 98 does not currently support DES encryption, so you cannot run the DCE send, receive, or message exits supplied by MQSeries.

Compilers for MQSeries Applications on Windows 95 and Windows 98 Clients

The following compilers are supported:

v Micro Focus COBOL Workbench, Version 4.0 v IBM VisualAge C++ for Windows, Version 3.5 v Microsoft Visual C++ for Windows 95/NT, Version 4.0 and Version 5.0

MQSeries for AS/400, V5.1 Quick Beginnings

Components for Windows 95 and Windows 98

MQSeries Client

The MQSeries client code for Windows 95 and Windows 98.

MQSeries Toolkit

This includes:

v Sample programs v Header files that you can use when writing applications to run on

the client

Windows NT Client: Hardware and Software Required

This section outlines the hardware and software requirements for an MQSeries client for Windows NT.

Hardware

An MQSeries client can run on Windows NT on any Intel®486 processor based IBM PC machine or equivalent (certified as NT compatible). There must be enough random access memory (RAM) and disk storage for the programming prerequisites (below), the MQSeries client, the access methods, and the application programs.

Software

The following are prerequisites for MQSeries applications running on a Windows NT client.

Minimum supported software levels are shown. Later levels, if any, will be supported unless otherwise stated.

v Microsoft Windows NT, Version 4 compatible, to include TCP/IP, NetBIOS,

SNA LU 6.2, and SPX.

Connectivity

v IBM Communications Server for Windows NT, Version 5.0 v Attachmate Extra! Personal Client, Version 6.1 and Version 6.2 v Microsoft SNA Server, Version 2.11 or Version 3 v TCP/IP, NetBIOS, and SPX are part of the base operating system

Optional software

v IBM DCE, Version 1.1

Compilers for MQSeries Applications on Windows NT Clients

The following compilers are supported:

v IBM VisualAge COBOL for Windows NT, Version 2.1 v IBM VisualAge COBOL Enterprise, Version 2.2 v IBM VisualAge C++, Version 3.5

Chapter 6. Planning to Install MQSeries Clients 55

Hardware and Software, Windows NT

v Microsoft Visual C++ for Windows 95 and Windows NT, Version 4.0 and

Version 5.0

v IBM C and C++ compilers, Version 3.6 v IBM PL/I for Windows, Version 1.2 v IBM VisualAge for PL/I for Windows v IBM VisualAge PL/I Enterprise, Version 2.1 v IBM Visual Basic for Windows, Version 4.0 (16-bit) and Version 5.0 (32-bit)

or higher

v IBM VisualAge for Java, e-Business Edition for Windows 95 and Windows

v IBM VisualAge Java Enterprise Edition, Version 2.0 v IBM VisualAge Java Professional Edition, Version 2.0

Components for Windows NT

These are identical to those for OS/2 Warp. See “Components for OS/2 Warp”

on page 51.

MQSeries for AS/400, V5.1 Quick Beginnings

Chapter 7. Installing MQSeries Clients

This chapter describes the following:

v “Installing MQSeries Clients on the Same Machine as the Server” v “Installing on AIX” v “Installing on DOS” on page 64 v “Installing on HP-UX” on page 65 v “Installing on OS/2 Warp” on page 66 v “Installing on Sun Solaris” on page 75 v “Installing on Windows 95 or Windows 98” on page 77 v “Installing on Windows 3.1” on page 81 v “Installing on Windows NT” on page 83 v “Classes for Java” on page 89 v “Configuring and Verifying a Client” on page 90

Installing MQSeries Clients on the Same Machine as the Server

To install MQSeries client components on an MQSeries server machine, use the MQSeries Server CD-ROM (not the MQSeries Client CD-ROM). Choose the client install option to install client components from the MQSeries Server CD-ROM.

Use the MQSeries Client CD-ROM only to install MQSeries client components on a machine that is not an MQSeries server.

You may install client components from the MQSeries Client CD-ROM and later decide to install the MQSeries server on the same machine. Before you can do this, you must remove all the MQSeries client components from the machine. Then use the MQSeries Server CD-ROM to install the server and the client. You cannot install the server on a machine that already has client components installed from the MQSeries Client CD-ROM.

Remember that even when your server and client both reside on the same machine, you still need to define the MQI channels between them. See the MQSeries Clients book for details.

Installing on AIX

To install an MQSeries client on an AIX system, use the MQSeries Client CD-ROM supplied as part of the MQSeries product.

Installing on AIX

The MQSeries client is installed into the /usr/mqm directory. This cannot be changed. However, if you do not have enough space in the /usr/mqm file system, follow the procedure given in “Creating Another File System for the Client” on page 59.

If you have a previous version of the MQSeries for AIX client installed on your system, or if a file system remains from a previous AIX client installation, see “Migrating from an Earlier Version of MQSeries for AIX” on page 62.

If you plan to install an MQSeries client and server on the same machine, see “Installing MQSeries Clients on the Same Machine as the Server” on page 57.

Before Installation

Before you can install the MQSeries client on your AIX system you are advised to create and mount a /var/mqm file system, or /var/mqm, /var/mqm/log, and /var/mqm/errors file systems.

If you create separate partitions, the following directories must be on a local file system:

v /var/mqm v /var/mqm/log

You can choose to NFS mount the /var/mqm/errors directory to conserve space on your local system.

A user ID with the name mqm, whose primary group is mqm, is automatically created during installation. You can create the user and group IDs yourself (see “Creating the mqm User ID and Group” on page 59), but make sure you do this before installing the client. User ID and group must both be mqm.

For stand-alone machines, you can create the new user and group IDs locally. For machines administered in a network information services (NIS) domain, you can create the user and group IDs on the NIS master server machine.

After installation, the mqm user ID owns the directories and files that contain the resources associated with the product. This group and user must be defined for any machine on which the MQSeries software is to be installed, whether the machine is a client or a server machine.

MQSeries for AS/400, V5.1 Quick Beginnings

Installing on AIX

Creating Another File System for the Client

If you do not want to have the client installed in the /usr/mqm file system, you can do either of the following things:

1. Create a new file system and mount it as /usr/mqm.

2. Create a new directory anywhere on your machine that is large enough to

contain the client files, and create a symbolic link from /usr/mqm to this new directory. For example:

mkdir /bigdisk/mqm ln -s /bigdisk/mqm /usr/mqm

Whichever of these options you choose, you must do it before installing the client.

The file system into which the client is installed can be a remote network device, for example NFS, provided that the mount options are defined on that device to allow setuid programs (including root access) to be run.

Creating the mqm User ID and Group

If you want to create the required IDs yourself, follow this procedure before you install the client. You must create both user ID and group as mqm.

Create the new IDs using the System Management Interface Tool (SMIT), for which you require root authority. The procedure for this, if you use the SMIT windows, is:

1. Create the mqm group. You can display the required window using this

sequence:

Security & Users

Groups

Add a Group

You can take the default values for the attributes of the new group or change them as required.

2. Create the new user, mqm. You can display the window for doing this using

this sequence:

Security & Users

Users

Add a User

Set the primary group for this user to be mqm. You can take the default values for the attributes of the new group or change them if you wish.

Chapter 7. Installing MQSeries Clients 59

Installing on AIX

3. Add a password to the new user ID. You can display the window for

4. Add the newly created group mqm to an existing user ID. You can display

Note: You need not have your primary group set to mqm. As long as mqm is in

Easy Installation

This section describes the ‘Easy Installation’ procedure using the MQSeries Client CD-ROM.

doing this using this sequence:

Security & Users

Passwords

the window for doing this using this sequence:

Security & Users

Users

Change / Show Characteristics of a User

When the window is displayed, enter the name of the user who is to have the mqm group added. In the user details window, add mqm to the Group set field, which is a comma-separated list of the groups to which the user belongs.

your set of groups, you can use the commands. If you are running applications that use the queue manager only, you do not need mqm group authority.

Note: If you have a previous version of the MQSeries for AIX client installed

on your system, or if a file system remains from a previous AIX client installation, see “Migrating from an Earlier Version of MQSeries for AIX” on page 62.

1. Log on as root.

2. Insert the MQSeries Client CD-ROM into the CD-ROM drive.

3. Type xinstallm -ez

Note: xinstallm is part of VSM (Visual System Management), which may

not be installed on your system. It is part of the xll.vsm.rte fileset. You can use SMIT or the underlying installp command as alternatives.

The MQSeries Welcome window is displayed.

4. Make sure you are installing the correct client for your system, as

displayed in the Welcome window. A window is then displayed where you can make some choices.

5. Choose the software source: CD-ROM.

6. For Which bundle of software would you like to install? choose:

Media-defined.

MQSeries for AS/400, V5.1 Quick Beginnings

7. Click on Install/Update.

A bundle of software products is created:

mqm.Client

8. Choose the mqm.Client bundle and click on Install/Update again.

A work in progress window gives information as the installation proceeds.

9. At the end of installation you can click on the View log button and scroll

to the bottom of the log to see the filesets that have been installed successfully.

Custom Installation

This section describes custom installation using the System Management Interface Tool (SMIT).

Note: If you have a previous version of the MQSeries for AIX client installed

on your system, or if a file system remains from a previous AIX client installation, see “Migrating from an Earlier Version of MQSeries for AIX” on page 62.

You can use SMIT for a custom installation as follows:

1. Log on as root.

2. Go into SMIT and from the shell, type:

smit

3. Select the device appropriate for your installation, using this sequence of

windows:

Software Installation and Maintenance

Install and Update Software

Installing on AIX

Install and Update from Latest Available Software

Alternatively, you can use the fastpath command:

smitty install_latest

4. Press the List button to display the Single Select List window.

5. Select /dev/cd0 (CD-ROM Drive)

6. Press Do to display the parameters for Install Latest Level.

7. Press F4 to get a list of components to install.

8. Follow the SMIT instructions to select the components you want to

install.

9. Press Enter.

10. If you have a previous version of the product on your machine, change

the Auto Install prerequisite software to No and Overwrite existing version to Yes.

11. Press Do to install.

Chapter 7. Installing MQSeries Clients 61

Installing on AIX

Migrating from an Earlier Version of MQSeries for AIX

If you want to migrate from an MQSeries for AIX V5.0 client to an MQSeries for AIX V5.1 client, you must first end all MQSeries activity on the target machine, and remove any shared resources that are used by MQSeries. Do this either by shutting down the system and restarting it, or by issuing the icprm command to remove the shared resources.

The migration procedure described in this section applies only to migration from MQSeries for AIX V5.0 clients to MQSeries for AIX V5.1 clients. If you are migrating from an earlier version of MQSeries for AIX, you are advised to uninstall your current version before installing the MQSeries for AIX V5.1 client.

Migration from MQSeries for AIX V5.0 involves updating any currently installed filesets, and installing any new filesets that might be required.

To update currently installed filesets:

1. Go into SMIT for root authority. From the shell, enter:

2. Select the device appropriate for your installation using the following

smit

sequence of windows:

Software Installation and Maintenance

Install and Update Software

Update Installed Software to Latest Level (Update All)

Alternatively, you can use the fastpath command to select the appropriate device:

smitty update_latest

3. Select the List button to display the Single Select List window.

4. Select /dev/cd0 (CD-ROM Drive).

5. Select OK to display the parameters for Update All.

6. Update all previously installed software for MQSeries by selecting the

_update_all option in the Software to update field.

7. Press Enter.

8. Select OK in the confirmation window to start updating the software.

Once all previously installed filesets have been updated to the latest level, you can install any additional filesets. See “Custom Installation” on page 61 for more information.

Changes to the Installation Path

Changes in AIX LPP Version 4 packaging mean that the MQSeries for AIX V5.1 client installs into directory /usr/mqm, whereas previous versions of the product installed into directory /usr/lpp/mqm.

MQSeries for AS/400, V5.1 Quick Beginnings

Installing on AIX

Installation of the MQSeries for AIX V5.1 client will fail if a file system mounted as /usr/lpp/mqm is detected. If you are migrating from an earlier version and a file system exists for this directory, you will need to do one of the following things before installing the MQSeries for AIX V5.1 client. Either:

v Uninstall your existing MQSeries client, and either delete the file system or

move it to the new install path of /usr/mqm

v Move the old file system of /usr/lpp/mqm to the new installation path of

/usr/mqm and create a symbolic link from the old path to the new by

issuing the following command:

ln -s /usr/mqm /usr/lpp/mqm

If you uninstall your existing client and either delete or move your existing file system, you can then install the MQSeries for AIX V5.1 client as described in “Custom Installation” on page 61 or “Easy Installation” on page 60.

However, if you move the old file system to the new installation path, you should then perform the migration installation described in “Migrating from an Earlier Version of MQSeries for AIX” on page 62.

Note: If you have already symbolically linked a file system to /usr/lpp/mqm,

installation of the MQSeries for AIX V5.1 client will destroy the contents of the file system and the symbolic link, leaving an empty file system. If this happens, you are advised to uninstall your existing MQSeries client and either delete the file system or relink it to the new install path of /usr/mqm, before installing the MQSeries for AIX V5.1 client.

The installation process for the MQSeries for AIX V5.1 client creates a symbolic link from the old install path (/usr/lpp/mqm) to the new install path (/usr/mqm). Therefore any existing scripts or makefiles that reference the old path are still valid.

Changing the National Language

The easy installation and the custom installation default to the national language that was specified when your operating system was installed.

It is possible to install the MQSeries client software so that the online help and messages are in another national language. Use SMIT as follows to install the message catalog for another national language:

1. Type smit

2. Follow this sequence of windows:

Chapter 7. Installing MQSeries Clients 63

Installing on AIX

3. Press the List button to display the Single Select List window.

4. Select:

5. Press the List button on the Software to Install field.

6. Select the message catalog that you want to install.

7. Press Do to install the chosen message catalog or catalogs.

To check the initial locale setting for your machine type:

and press Enter. If this is not one of the national languages provided by MQSeries, you must select a national language, otherwise you will not get a message catalog installed on your system.

Translated Messages

Messages in U.S. English are always available. If you require one of the other languages that is supported by MQSeries for AIX, you must ensure that your NLSPATH environment variable includes the appropriate directory.

Software Installation and Maintenance

Install and Update Software

Install and Update from ALL Available Software

/dev/cd0 (CD-ROM Drive)

smitty mle_cc_cust_hdr

For example, to select messages in German use the following:

export LANG=de_DE export NLSPATH=/usr/lib/nls/msg/%L/%N

Removing an MQSeries Client from AIX

Use SMIT as usual to remove all the MQSeries client files that were installed.

Installing on DOS

To install an MQSeries client on a DOS system you use the MQSeries Client CD-ROM supplied as part of the MQSeries product.

Using Setup

1. Insert the MQSeries Client CD-ROM into the CD-ROM drive.

2. Change to the DOS directory on the CD-ROM drive.

3. Copy the setup.exe file from the DOS directory to the directory where you

4. Change directory to c:\mqmdos and type the command:

want to install the MQSeries client, for example c:\mqmdos.

setup -d

This results in a self-exploding file being run to generate a tree of subdirectories containing the DOS client.

MQSeries for AS/400, V5.1 Quick Beginnings

5. Edit the autoexec.bat file using a suitable editor. If the PATH statement

exists, add the following to it:

If the PATH statement does not exist, add the following line to the autoexec.bat file.

SET PATH=c:\mqmdos;c:\mqmdos\bin;c:\mqmdos\en_us

Removing an MQSeries Client from DOS

Delete all the files in the directory where you installed the MQSeries client, and then remove the directory.

Installing on HP-UX

To install an MQSeries client on an HP-UX system you use the MQSeries Client CD-ROM supplied as part of the MQSeries product.

Note: If you plan to install an MQSeries client and server on the same

The MQSeries client is installed into the /opt/mqm directory. This cannot be changed.

Installing on DOS

c:\mqmdos;c:\mqmdos\bin;c:\mqmdos\en_us

machine, see “Installing MQSeries Clients on the Same Machine as the Server” on page 57.

Before Installation

Before you can install an MQSeries client on your HP-UX system you:

v Must create a group with the name mqm. v Must create a user ID with the name mqm. v Are recommended to create and mount a /var/mqm file system, or /var/mqm,

/var/mqm/log, and /var/mqm/errors file systems. If you create separate partitions, the following directories must be on a local

file system: – /var/mqm – /var/mqm/log

You can choose to NFS mount the /var/mqm/errors and /var/mqm/trace directories to conserve space on your local system.

After installation, this user ID (mqm) owns the directories and files that contain the resources associated with the product. This group and user must be defined for any machine on which the MQSeries software is to be installed, whether the machine is a client or a server machine.

Chapter 7. Installing MQSeries Clients 65

Installing on HP-UX

Installation

Use the HP-UX swinstall program, or use SAM, after mounting the CD-ROM. For further details, see the appropriate HP-UX documentation.

If you are using HP-UX V10.x, the depot to use is in the HPUX10/MQS510.000.V10 file under the mount point. If you are using HP-UX V11.x, the depot to use is in the HPUX11/MQS510.000.V11 file under the mount point.

If the files on your CD-ROM appear in uppercase with a “;1” suffix, use this name for the depot.

Kernel Configuration

See the MQSeries family Web site for a SupportPac™that gives additional performance information - see “HTML and PDF Books on the World Wide Web” on page 96.

Translated Messages

Messages in U.S. English are always available. If you require one of the other languages that is supported by MQSeries for HP-UX, you must ensure that your NLSPATH environment variable includes the appropriate directory.

For example, to select messages in German use the following:

export LANG=de_De.iso88591 export NLSPATH=/usr/lib/nls/msg/%L/%N

Removing an MQSeries Client from HP-UX

To remove an MQSeries client from your HP-UX system, use the swremove command, or use SAM. You can then delete the /var/mqm directory tree.

Installing on OS/2 Warp

To install an MQSeries client on an OS/2 Warp system you use the MQSeries Client CD-ROM supplied as part of the MQSeries product.

Note: If you plan to install an MQSeries client and server on the same

machine, see “Installing MQSeries Clients on the Same Machine as the Server” on page 57. If you currently have a manually installed MQSeries client on your OS/2 Warp system from a previous release of MQSeries, you must delete it manually before attempting to install the Version 5.1 client. Before you delete the previous version, save your MSQ.INI file because the deletion process will delete this file.

MQSeries for AS/400, V5.1 Quick Beginnings

You can install the version of the MQSeries client software specific to your national language. This means that the installation program, online help and messages will be in your national language.

Installation

Online help is available by selecting the Help push button or by pressing PF1.

Before you start, make sure that you have at least 150 KB of free space on the drive containing the operating system. This is required by the installation program.

1. Open an OS/2 Warp window (or start a full-screen session).

2. Insert the CD-ROM and change to the CD-ROM drive. Access the drive

3. At the command prompt, in the root directory, type INSTALL, then press

4. On the MQSeries Language Selection panel, select the language of your

5. The install panel is then displayed. Select the Update CONFIG.SYS

6. Select the OK push button to continue. The Install - directories panel is

7. The list box shows the installation options that you can select. When you

8. If there is not enough space on your hard disk to install all the

Installing on OS/2 Warp

and directory containing the installation program if you are installing from a remote drive.

Enter.

choice, and click on the OK button or press Enter. The MQSeries Welcome panel is displayed. Make sure you are installing

the correct client for your system, OS/2 Warp, as displayed in the Welcome panel.

check box if you want your CONFIG.SYS file updated automatically as part of the installation process. Your original CONFIG.SYS file is renamed to CONFIG.BAK and is stored in the same directory. If you do not select this check box, a CONFIG.ADD file is generated. This file is a copy of CONFIG.SYS with the necessary updates to the LIBPATH and PATH statement. You can rename the CONFIG.ADD file to CONFIG.SYS.

displayed.

select one or more of these options, the Bytes needed field shows the amount of disk space required for installation.

The component MQSeries Client for Java should be installed only if you have Java 1.1.1 (or later compatible) runtime code on your machine. This component must be installed on an HPFS formatted drive.

components, select an option that uses less disk space. If there is too little space on your hard disk for any of the MQSeries for OS/2 installation options, a dialog box appears before the Install - directories panel. In this case, cancel the installation by selecting the OK push button. Find out which of your existing files you can archive or delete to make more space before proceeding further.

Chapter 7. Installing MQSeries Clients 67

Installing on OS/2 Warp

Use the push buttons as necessary:

v To display descriptions of the selected options, select Descriptions. v To select all of the options, select Select all. v To deselect all of the options, select Deselect all.

The Work and File Directory field allows you to specify a drive and directory other than the default for the installation files (File directory) and for the working files that might be created when you use the MQSeries client (Working directory).

Select a drive from the list box if required. When you return to the Install - directories panel, your selected drive is shown. Select the OK push button to return to the Install - directories panel.

9. Select the Install push button to continue. The Install-progress panel is

displayed. This panel shows: v The file currently being installed (source) and the drive and directory

to which it is being installed (target).

v A progress bar, indicating the percentage of files already unpacked and

installed.

v The elapsed time. v The status; for example, unpacking, processing, or transferring.

If you select the Stop push button, you are asked whether you want to delete the partial system you have installed. Select Yes to delete the files already installed and return to the introductory panel. Select Start install from the File menu to start the installation again.

10. A cyclic redundancy check (CRC) is performed on the installed software

and any errors are written to a log file. This is the file specified by the /L1 parameter of the INSTALL command by default. If /L1 is not specified, the log file is MQMERR.LOG in the high-level directory chosen for installation.

Note: The log files must be on a local drive. If the product has been

installed on a remote drive, change the path of the log files in the mqs.ini file.

11. When installation is complete, the Installation and Maintenance panel is

displayed. Select OK. The introductory MQSeries for OS/2 panel is then displayed. Leave the installation program by selecting the Exit push button.

12. When the installation process is complete, a folder is created on the OS/2

Warp desktop, containing objects as follows:

READ.ME MQSeries Installation and Maintenance MQSeries Information

MQSeries for AS/400, V5.1 Quick Beginnings

Installing on OS/2 Warp

Note that the MQSeries client is a set of services and it does not have to be explicitly run. Therefore the folder does not have an object called a “client”.

13. Remove the installation CD-ROM from the drive.

14. If your CONFIG.SYS file has been updated, shut down the system and

restart. If the CONFIG.SYS file was not updated, rename the CONFIG.ADD file to CONFIG.SYS before shutting down the system (CONFIG.ADD will be in the same directory as CONFIG.SYS).

15. To obtain MQSeries messages in the correct language two environment

variables must be set correctly. The installation process sets the environment variable NLSPATH including <installation directory>\LOCALE\%L\%N, where <installation directory> is the directory in which you choose to install the product. You must set the environment variable LANG=<lang>, where <lang> is the subdirectory in which the message catalog for your language is installed, selecting a language from the list below:

Directory Language

En_US U.S. English Pt_BR Brazilian Portuguese Fr_FR French De_DE German It_IT Italian Ja_JP Japanese Ko_KR Korean Es_ES Spanish Zh_CN Simplified Chinese Zh_TW Traditional Chinese

Unattended Installation on OS/2 Warp

You can install MQSeries clients on OS/2 Warp workstations without user interaction being required at the workstation. You can perform this unattended installation using response files. The sample response file AMQISMC2.RSP shows an example of unattended client installation.

This kind of automatic installation is particularly useful for installing clients over a network because installation can be performed from a redirected drive on a LAN server.

Chapter 7. Installing MQSeries Clients 69

Installing on OS/2 Warp

Attention

Note that the INSTALL.EXE file in the root directory of the CD-ROM must not be used to perform unattended installations.

You must instead invoke the INSTALL.EXE file located in the directory corresponding to the language version of the product that you want to install.

Starting Unattended Installation

The following steps describe how to perform an unattended installation:

1. Connect to the drive containing the MQSeries product software. This can

be a local CD-ROM drive containing the MQSeries client CD, or a remote network drive. For example, F:.

2. Change to the directory appropriate to your language. The directories are

as follows:

Directory Language

\OS2\En_Us U.S. English \OS2\Pt_BR Brazilian Portuguese \OS2\Fr_FR French \OS2\De_DE German \OS2\It_IT Italian \OS2\Ja_JP Japanese \OS2\Ko_KR Korean \OS2\Es_ES Spanish \OS2\Zh_CN Simplified Chinese \OS2\Zh_TW Traditional Chinese

3. Change to the subdirectory samples.

4. Edit the supplied response file, AMQISMC2.RSP for client installation, or

create a new response file. The supplied response file can be used for install and delete actions.

5. Type install together with the required parameters (described in

“Installation and Maintenance Parameters” on page 71). For example:

INSTALL /A:I /R:J:\INSTMQS\AMQISMC2.RSP

This example uses U.S. English. To use another language, substitute en_us with the directory appropriate to your language. When you issue this

MQSeries for AS/400, V5.1 Quick Beginnings

/S:J:\INSTMQS\en_us /L1:J:\INSTMQS\MQM.OUT /L2:J:\INSTMQS\MQM.HIS /X

command, you must type it as one continuous line. In the example above, for clarity, the command is spread over several lines.

In this example, the MQSeries client is installed from the redirected drive J: on the server, according to the options supplied in the response file AMQISMC2.RSP. Note that drive J: must be a writeable drive that you must create, and the .RSP file must be put on that drive. The installation log files will also be created on the J: drive. The response file specifies the drive and directory in which to install the client. Errors are logged in MQM.OUT and the history log is contained in MQM.HIS. The /X parameter specifies that the installation is non-interactive.

The example also shows that you must have the INSTALL.EXE available to your system. This file is supplied on the client CD-ROM, but is not installed onto your system. You must make a copy of this file available when you perform maintenance updates on your system.

Installation and Maintenance Parameters

The installation and maintenance parameters are as follows:

Installing on OS/2 Warp

INSTALL /A:action

/G:include path /L1:error log /L2:history log /R:response file /S:source location /T:install target directory /TU:update CONFIG.SYS directory /X

Note: You can enter the parameters in any order. Equals signs (=) can be used

instead of colons (:) in the parameters. Values can be upper or lower case.

/A:action

Specifies the action to be performed by the installation program. If you specify this parameter, the main window of the installation program is not displayed. Valid values for action are:

D Delete an installed MQSeries for OS/2 Warp system I Install a new MQSeries for OS/2 Warp system R Restore a backed up MQSeries for OS/2 Warp system U Update an installed MQSeries for OS/2 Warp system

Note: The installation program is not supplied with a corrective service

medium. Therefore, if you are updating, restoring, or deleting an MQSeries for OS/2 Warp system, you must have access to the installation program used to install it.

Chapter 7. Installing MQSeries Clients 71

Installing on OS/2 Warp

/G:include path

Specifies the drive and path of a general response file to be included by the specific response file. For more information about response files, see “Installation Response Files” on page 73.

/L1:error log

Specifies the drive, path, and file name of the error log file. The error log contains messages associated with installation, including confirmations and error messages. Messages are written to the error log if you specify the /X parameter.

You should specify the drive and path where the installation program is running. If you do not specify the /L1 parameter, no error log is maintained. If the error log already exists, it is appended to.

Example:

/L1:D:\LOG\INSMQM.OUT

/L2:history log

Specifies the drive, path, and file name of the history log file. The history log contains an entry for each file transferred, each object created, and each installation exit run.

You should specify the drive and path where the install program is running. If you do not specify the /L2 parameter, no history log is maintained. If the history log already exists, it is appended to.

Example:

/L2:D:\LOG\INSMQM.HIS

/R:response file

Specifies the drive, path, and file name of a response file; see “Installation Response Files” on page 73.

Example:

/R:L:\MQMINS\AMQISAM2.RSP

/S:source location

Specifies the drive and path containing the source files to be installed or updated.

/T:install target directory

Specifies the drive and path that MQSeries for OS/2 Warp files are installed on to. If you specify this parameter, it overrides the FILE path, which must be specified in the response files.

/TU:update CONFIG.SYS directory

Specifies the drive and path of the target CONFIG.SYS to be updated.

/X Specifies that the installation is fully automatic.

MQSeries for AS/400, V5.1 Quick Beginnings

When you specify this parameter, no progress indicator panel is shown and error messages are logged in the error log file. (You specify the path name of the error log file using the /L1 parameter.) If you do not specify all of the information required for the action to complete, an error occurs.

If you do not specify the /X parameter, the user is prompted for any information that the install program needs to complete the action. In this interactive mode of operation, progress indication is shown and error messages are displayed in secondary windows.

Installation Response Files

An installation response file is an ASCII text file containing answers to the options that you select when you install or maintain an MQSeries for OS/2 Warp system. This allows installation and maintenance to be performed automatically, without interaction.

In an installation response file you can specify:

v Whether CONFIG.SYS should be updated automatically v The MQSeries for OS/2 Warp components to be installed v The path for installation or maintenance v Whether existing files should be overwritten v Whether only backup versions of MQSeries for OS/2 Warp should be

deleted

Installing on OS/2 Warp

The installation response file supplied with MQSeries for OS/2 Warp can be found as a sample file on the installation media. You can use this file to install or delete MQSeries for OS/2 Warp. To perform other actions you must prepare your own installation response files using a suitable editor.

Normally you have only one response file, specified by the /R parameter of the installation program. However, if you need to install or update MQSeries for OS/2 Warp on a workstation with different options, you can use two files. One would be a specific response file that contains options specific to a particular workstation, and the other a general installation response file that contains options common to all workstations.

For example, you might use a general and a specific response file to install a particular component only on some workstations.

You use the /R parameter to specify the specific installation response file, and the /G parameter to specify the location of the general response file.

Keywords for Response Files

The following keywords are supported in response files for MQSeries for OS/2 Warp:

Chapter 7. Installing MQSeries Clients 73

Installing on OS/2 Warp

CFGUPDATE

Specifies whether CONFIG.SYS is updated automatically. Valid values for this keyword are:

Actions: INSTALL, UPDATE, DELETE.

COMP

Specifies the name of a component on which to perform an action. See the server or client component lists for valid values.

You do not need to enclose the product names within quotes.

Actions: ALL actions.

DELETEBACKUP

Specifies whether to delete only the backup version of MQSeries for OS/2 Warp or the entire product. Valid values are YES and NO.

When you remove MQSeries for OS/2 Warp, none of your user-supplied information, for example queue manager data, is deleted. This is particularly important if you intend to delete and reinstall the product, because your previous queue manager data will remain.

AUTOAutomatically updates CONFIG.SYS MANUALDoes not update CONFIG.SYS

This can lead to an unexpected directory and file structure, if you attempt to recreate queue managers with identical names to those used in the previous installation, because such data might already be present.

Actions: DELETE.

FILE Specifies the drive and directory for MQSeries for OS/2 Warp code.

For example the C:\MQM directory.

Actions: INSTALL.

WORK

Specifies the drive and directory for MQSeries data files. For example the C:\MQM directory.

Actions: INSTALL.

INCLUDE

Specifies which general response files to include with a specific response file. The format of this keyword is:

INCLUDE = filespec

Where filespec specifies the general response file to be included. If the file specification contains any global characters (* or ?), the first

MQSeries for AS/400, V5.1 Quick Beginnings

Installing on OS/2 Warp

file found that matches the specification is included. If the specification is not valid, no general response file is included.

Note: You should not have more than five levels of included response

files.

Actions: All actions.

OVERWRITE

Specifies whether to overwrite files automatically during installation. Valid values for this keyword are YES and NO.

Actions: INSTALL, UPDATE.

SAVEBACKUP

Specifies whether to save a backup version of MQSeries for OS/2 Warp when it is updated. Valid values for this keyword are YES and NO.

Actions: UPDATE.

Response File Structure

There are two kinds of line in a response file:

v Comment lines

Comment lines are either blank or start with an asterisk (*) or a semicolon (;).

v Response lines

Response lines are used to determine the options and configurations to install on the target system. Response lines have the following syntax:

keyword = value

Keyword-value pairs can be in any order. However, there can be only one pair per line. You can enter keywords in upper or lower case letters. You cannot include spaces within keywords.

The maximum line length in a response file is 255 characters.

Removing an MQSeries Client from OS/2 Warp

Use the MQSeries Installation and Maintenance icon in the MQSeries Client folder on the desktop, and select Actions/Delete. All the MQSeries client files that were there at the time of installation are deleted.

Installing on Sun Solaris

To install an MQSeries client on a Sun Solaris system you use the MQSeries Client CD-ROM supplied as part of the MQSeries product.

Chapter 7. Installing MQSeries Clients 75

Installing on Sun Solaris

Note: If you plan to install an MQSeries client and server on the same

machine, see “Installing MQSeries Clients on the Same Machine as the Server” on page 57.

The MQSeries product is installed into the /opt/mqm directory. This cannot be changed.

Before Installation

Before you can install an MQSeries client on your Sun Solaris system you:

v Must create a group with the name mqm. v Must create a user ID with the name mqm. v Are recommended to create and mount a /var/mqm file system, or /var/mqm,

/var/mqm/log, and /var/mqm/errors file systems. If you create separate partitions, the following directories must be on a local

file system: – /var/mqm – /var/mqm/log

You can choose to NFS mount the /var/mqm/errors and /var/mqm/trace directories to conserve space on your local system.

Installation

Carry out the following procedure:

1. Check whether Volume Manager is running on your system by typing the

following command:

/usr/bin/ps -ef | /bin/grep vold

If it is running, the CD is mounted on /cdrom/mqclient automatically. If it is not running, mount the CD by typing the following commands:

mkdir -p /cdrom/mqclient mount -F hsfs -r /dev/dsk/cntndnsn /cdrom/mqclient

substituting cntndnsn with the name of your CD-ROM device.

2. Use the Sun Solaris pkgadd program to install the MQSeries client

software by carrying out the following procedure: a. Type pkgadd -d /cdrom/mqclient/solaris/mqs510.img.

MQSeries for AS/400, V5.1 Quick Beginnings

b. You are prompted for a list of components to be installed. Select the

ones you require - if you want to install all the components, select all. The component MQSeries Client for Java should be installed only if

you have Java 1.1.1 (or later compatible) runtime code on your machine. You also require Version 2.6 or later of the Sun Solaris operating system.

c. Press the Enter key.

For further information on using pkgadd to install software packages, see the Sun Solaris documentation.

Kernel Configuration

See the MQSeries family Web site for a SupportPac that gives additional performance information - see “HTML and PDF Books on the World Wide Web” on page 96.

Translated Messages

Messages in U.S. English are always available. If you require one of the other languages supported by MQSeries for Sun Solaris, you must ensure that your NLSPATH environment variable includes the appropriate directory.

For example:

export LANG=de export NLSPATH=/usr/lib/locale/%L/LC_MESSAGES/%N

Installing on Sun Solaris

Removing an MQSeries Client from Sun Solaris

If you have previously installed MQSeries on your system, you must remove the product using the pkgrm program.

If the product is present, but not installed correctly, you might need manually to delete the files and directories contained in:

/var/mqm /opt/mqm

Installing on Windows 95 or Windows 98

To install an MQSeries client on a Windows 95 or a Windows 98 system you use the MQSeries Client CD-ROM supplied as part of the MQSeries product.

If you plan to install an MQSeries client and server on the same machine, see “Installing MQSeries Clients on the Same Machine as the Server” on page 57.

Note: The client installation will fail if the PATH variable that has been set up

is greater than 267 characters long.

Chapter 7. Installing MQSeries Clients 77

Installing on Windows 95 or 98

Installation

1. Insert the MQSeries Client CD-ROM into the CD-ROM drive.

2. The installation automatically starts and an MQSeries Language Selection

window is displayed.

Note: If you have disabled auto-playing of CD-ROMs, run SETUP

instead, from the root directory.

This window presents you with a list of the national languages that are available.

3. On the MQSeries Language Selection window select the language of your

choice, and click on the Next button or press Enter. The MQSeries Welcome window is displayed.

4. Make sure you are installing the correct client for your system, as

displayed in the Welcome window.

5. Select Destination Directory requires a destination directory into which

the MQSeries files will be installed. You can change the default shown by selecting the browse button and

choosing a different drive and directory, then click on OK. Click on the Next button or press Enter to continue.

6. Choose MQSeries Components displays a list of components from which

you can select the ones you want to be installed. To select a component, click in the box next to it so that a check mark

appears (just highlighting the line does not select it). The space needed for each component is shown here, and the space available on the drive you have selected.

Click on the Next button or press Enter to continue.

7. Select Program Folder prompts you for a folder name to contain the

MQSeries objects. The default name is MQSeries Client for MQSeries client for Windows 95 and Windows 98. You can rename the default or choose an existing folder.

8. Start Copying Files displays all the selections you have made. Click on

the Back button if you want to return to a previous window to change any of your choices.

When you have checked your choices, click on the Next button or press Enter to start the file copying process.

The progress indicator shows which components are being copied and the percentage of copying completed.

9. The next window presents you with the opportunity to view the

README file. If you do not want to view the README file at this point, it will be available in the MQSeries client folder.

MQSeries for AS/400, V5.1 Quick Beginnings

Installing on Windows 95 or 98

If you view the README file, close the window of the README to continue the installation process.

10. The installation of the MQSeries client is now complete, and a window is

displayed giving you the option of restarting your computer now or leaving it until later. It is recommended that you restart your computer now. Close all the other applications that are running before continuing with this step.

Once this has been done, select Yes, I want to restart my computer now and click on the Finish button to complete the setup.

11. When setup is complete, the MQSeries Client folder is added to the

desktop, or the location you specified. Note that the MQSeries client is a set of services and it does not have to be explicitly run, so the folder does not have an object called a “client”.

Unattended Installation on Windows 95 and Windows 98

You can install a Windows client on a remote machine without interaction. This process is known as unattended installation, sometimes referred to as silent installation, and uses response files.

An installation response file is an ASCII text file containing values for the options that you select when you install an MQSeries for Windows system.

For unattended installation, you must:

1. Carry out an installation on a machine and record the actions performed

to install the product. In this example, the machine is being used as a server – see “Setting up

the Server”.

2. Use the recording you have created to install the product on a remote

machine. See “Installing on the Remote Machine” on page 80.

Setting up the Server

To set up your server, follow these steps:

1. Load the MQSeries client CD-ROM. When the Language Selection window

appears, select Cancel.

2. Copy the win95 or win98 subdirectory, and all of its subdirectories, from

the client CD-ROM to a shared-resource image directory.

3. Select one of the following language directories:

v SetupCn – Simplified Chinese v SetupDe – German v SetupEn – English v SetupEs – Spanish v SetupFr – French v SetupIt – Italian v SetupJp – Japanese

Chapter 7. Installing MQSeries Clients 79

Installing on Windows 95 or 98

v SetupKo – Korean v SetupPt – Brazilian Portuguese v SetupTw – Traditional Chinese

4. From the selected language directory, run setup.exe, with the -r option to

create a response file. This can be done by:

a. Highlighting setup.exe b. Dragging it to the Start, Run dialog c. Adding -r to the end of the fully-qualified file name d. Selecting OK to start the process e. Selecting the components that you want to install

Notes:

a. When the installation has ended, a response file will have been

automatically generated that can be used as the basis for unattended installation.

b. The response file SETUP.ISS will be generated in the WINDOWS

directory for Windows 95 or Windows 98.

5. When the response file has been generated, you can copy it to the

language dependent directory in the shared-resource image directory for your national language.

For example, to copy the SETUP.ISS file from the WINNT35 directory to \IMAGE\SETUPEN, type:

COPY C:\WINNT35\SETUP.ISS M:\INSTMQS\IMAGE\SETUPEN

where SETUPEN is the appropriate language directory for your system.

This assumes that the Windows 95 or 98 operating system was installed to the C drive and that the MQSeries installation image on the server resides on M:\INSTMQS.

Now you have set up your server, you can go on to install on the remote machine.

Installing on the Remote Machine

Unattended installation is particularly useful for installing a client over a network because you can do it from a redirected drive on a LAN server.

The remote machine must have access to the shared-resource image directory, which includes the:

v Appropriate language subdirectory v Disk subdirectories

To connect the workstation to the redirected drive on the server, follow these steps:

MQSeries for AS/400, V5.1 Quick Beginnings

Installing on Windows 95 or 98

1. Use the NET USE command as follows:

NET USE devicename \\servername\netname

For example:

NET USE J: \\MQMNT\MQMSHARE

where: v J: is the logical drive name to be connected to the shared resource

directory.

v MQMSHARE is the netname for M:\INSTMQS.

2. Go to the language directory that contains the SETUP.EXE and SETUP.ISS

files and run SETUP -s.

Notes:

1. The -s parameter indicates that the installation is to be carried out in silent

mode. This parameter is mandatory for an unattended installation.

2. SETUP.EXE uses the SETUP.ISS file in the current directory to silently

install the product.

Removing an MQSeries Client from Windows 95 and Windows 98

If you want to remove the MQSeries client files from your machine, use Settings/ Control Panel/ Add-Remove Programs. First select MQSeries Client, which launches the uninstall program. Then select the components you want to remove and click Remove.

If you choose to remove all MQSeries components and are then likely to reinstall MQSeries, you should restart your computer to complete the uninstall process. You cannot reinstall any components until you have restarted.

All the MQSeries client files that were created at installation time are removed by the process.

Installing on Windows 3.1

To install an MQSeries client on a Windows 3.1 system you use the MQSeries Client CD-ROM supplied as part of the MQSeries product.

Installation

1. Insert the MQSeries Client CD-ROM into the CD-ROM drive.

2. Open the directory WIN31.

3. Change to the appropriate language subdirectory for the language you

wish to install:

Chapter 7. Installing MQSeries Clients 81

Installing on Windows 3.1

setupen - English setuppt - Brazilian Portuguese setupfr - French setupde - German setupit - Italian setupjp - Japanese setupko - Korean setupes - Spanish setupcn - Simplified Chinese setuptw - Traditional Chinese

4. Run setup.exe

The MQSeries Welcome window is displayed.

5. Make sure you are installing the correct client for your system, Windows

3.1, as displayed in the Welcome window.

6. Select Destination Directory requires a destination directory into which

the MQSeries files will be installed. You can change the default directory by selecting the browse button and

choosing a different drive and directory, then click on OK. Click on the Next button or press Enter to continue.

7. Choose MQSeries Components displays a list of components from which

you can select the ones you want to be installed. To select a component, click in the box next to it so that a check mark

appears (just highlighting the line does not select it). The space needed for each component is shown here, and the space available on the drive you have selected. Click on the Next button or press Enter to continue.

8. Select Program Folder prompts you for a folder name to contain the

MQSeries objects. The default name is MQSeries Client for Windows 3.1. You can rename the default or choose an existing folder.

9. Start Copying Files displays the selection you have made. Click on the

Back button if you want to return to change your choice. Now click on the Next button or press Enter to start the file copying

process. The progress indicator shows what components are being copied and the

percentage of copying completed.

10. The next window presents you with the opportunity to view the

README file. If you do not want to view the README file at this point, it will be available in the MQSeries client folder.

If you view the README file, close the window of the README to continue the installation process.

11. The installation of the MQSeries client is now complete, and a window is

MQSeries for AS/400, V5.1 Quick Beginnings

Select Yes, I want to restart my computer now and click on the Finish button to complete the setup.

12. When setup is complete, the MQSeries Client folder is added to the

Program Manager. Note that the MQSeries client is a set of services and it does not have to be explicitly run, so the folder does not have an object called a “client”.

Removing an MQSeries Client from Windows 3.1

If you want to remove the MQSeries client files from your machine, use the process provided to do this efficiently.

Run Uninstall from the MQSeries client folder. You are prompted before continuing.

All the MQSeries client files that were created at installation time are removed by the process.

Installing on Windows NT

To install an MQSeries client on Windows NT, use the MQSeries Client CD-ROM supplied as part of the MQSeries product.

Note: If you plan to install an MQSeries client and server on the same

machine, see “Installing MQSeries Clients on the Same Machine as the Server” on page 57.

Installing on Windows 3.1

Installation

To install an MQSeries client for Windows NT, you must be logged on to Windows NT as an administrator.

MQSeries checks for any existing MQSeries configuration files (MQS.INI). If it finds any, it automatically migrates configuration information to the Windows NT registry. Otherwise, MQSeries automatically puts its configuration information directly into the Windows NT registry.

Installation Procedure

1. Insert the MQSeries Client CD-ROM into the CD-ROM drive.

2. The installation automatically starts and an MQSeries Language Selection

window is displayed.

Note: If you have disabled auto-playing of CD-ROMs, run SETUP

instead, from the root directory.

This window presents you with a list of the national languages that are available.

Chapter 7. Installing MQSeries Clients 83

Installing on Windows NT

3. On the MQSeries Language Selection window select the language of your

choice, and click on the OK button or press Enter. The MQSeries Welcome window is displayed.

4. Make sure you are installing the correct client for your system, as

displayed in the Welcome window.

5. Choose Installation Folders lets you choose folders into which the

MQSeries program files and data files will be installed. You can change the default shown by selecting the browse button and

choosing a different drive and directory, then click on OK. Click on the Next button or press Enter to continue.

6. Select Components displays a list of components from which you can

select the ones you want to be installed. The component Java Client should be installed only if you have Java

1.1.1 (or later compatible) runtime code on your machine. To select a component, click in the box next to it so that a check mark

appears (just highlighting the line does not select it). The space needed for each component is shown on the panel, and the space available on the drive you have selected.

If you deselect a previously installed component it is removed. Click on the Next button or press Enter to continue.

7. Select Program Folder prompts you for a folder name to contain the

MQSeries objects. The default name is IBM MQSeries Client. You can rename the default or choose an existing folder.

8. Ready to Copy Files displays all the selections you have made. Click on

the Back button if you want to return to a previous window to change any of your choices.

When you have checked your choices, click on the Next button or press Enter to start the file copying process.

The progress indicator shows which components are being copied and the percentage of copying completed.

9. The Setup Complete window appears when the selected components

have been installed. Click the Finish button or press Enter to close the window (after optionally selecting Launch Notepad to View the Release Notes).

10. The installation of the MQSeries client is now complete.

11. When setup is complete, the IBM MQSeries folder is added to the Start

menu. Note that MQSeries Clients are sets of services and do not have to be explicitly run, so the folder does not have an object called “client”.

MQSeries for AS/400, V5.1 Quick Beginnings

Installing from a LAN

There are two ways to put MQSeries installation files on a LAN file server for easier access: you can make the MQSeries for Windows NT Client CD-ROM drive shareable, or you can copy the installation files from the CD-ROM to a file server, by following these steps:

1. Create a folder on the LAN file server to store the installation files. For

example:

md m:\instmqs

2. Load the MQSeries for Windows NT client CD-ROM. If you have autorun

enabled, the language selection panel will appear. Cancel this panel.

3. Copy the Winnt directory structure from the CD-ROM to the m:\instmqs

folder. For example:

xcopy e:\Winnt\*.* m:\instmqs /e

You can save space on the hard drive by copying only the subfolders for the languages that you require. The language subfolders are:

SetupCn Simplified Chinese SetupDe German SetupEn U.S. English SetupEs Spanish SetupFr French SetupIt Italian SetupJp Japanese SetupKo Korean SetupPt Brazilian Portuguese SetupTw Traditional Chinese

Installing on Windows NT

4. Give all licensed users access to the folder that now contains the CD-ROM

image (in this example, the m: drive).

5. From a command prompt on the target machine, connect to the

appropriate drive and folder using the net use command:

net use devicename \\servername\netname

For example:

net use x: \\mqmnt\instmqs

where x: is the required mapped drive on the target machine. Alternatively, use Windows NT Explorer or another method to map the shared resource to a drive letter.

6. Change to the installation directory (in this example x), type Setup and

press Enter.

7. Follow the prompts.

Chapter 7. Installing MQSeries Clients 85

Installing on Windows NT

Using the System Management Server with MQSeries for Windows NT

This section describes how to install, or remove, an MQSeries for Windows NT client using the System Management Server (SMS).

Creating SMS Packages and Jobs for MQSeries

You must create:

v An SMS software package containing the MQSeries software. v An SMS job to distribute and install the software package (see “Creating the

MQSeries SMS Job” on page 87).

For more detailed information on how to create a software package and a job, refer to the Microsoft System Management Server documentation.

Creating the MQSeries SMS Software Package

To create the SMS software installation package:

1. From the Microsoft SMS Administrator application, open the Packages

folder and then create a new package.

2. In the SMS Package Properties dialog click on the Import button to

create the software package by importing a Package Definition File (PDF).

3. In the File Browser dialog, select the drive where the IBM MQSeries

client CD-ROM is located.

4. Select the Winnt directory, which contains the package definition file

MQSERIES.PDF. You can also find the MQSERIES.PDF file in the local drive, or shared

network drive where you copied the MQSeries Installation software.

5. Select the MQSERIES.PDF file and click on the OK button.

6. Click on the Workstation button. In the Source Directory entry field,

specify the fully-qualified path name to the MQSeries root directory that contains the MQSeries installation software.

7. Select the appropriate Workstation Command Line:

v Automated Uninstallation of IBM MQSeries - Windows NT client v Automated Installation of IBM MQSeries - Windows NT client (US

English)

8. Click on the Properties button for each process and review the

Command Line entry field to ensure that the parameters are correct.

Note: The -i<miffilepath> parameter specifies the full path and file

name of a Management Information Format (.mif) file that installation and uninstallation can generate. Remove the parameter if you do not want to generate a .mif file.

9. Click on the Close button to close the Workstation Properties dialog.

MQSeries for AS/400, V5.1 Quick Beginnings

Installing on Windows NT

Note: If you specified a local path in the Source Directory entry field,

you get a pop-up dialog warning you that the local path you specified might not be accessible to SMS components running on another machine. Click on the OK button to continue.

10. Click on the OK button to close the Package Properties window.

A pop-up dialog appears indicating that SMS will update the software package at all sites. Click the OK button to continue.

The software package has been created and can be installed by creating an SMS job.

Creating the MQSeries SMS Job

You must now create an SMS job to distribute and install the software packages you created that contain the MQSeries installation software.

Refer to the Microsoft System Management Server documentation for detailed information on how to create and run a job.

Notes:

1. You must be logged onto the target machine with Administrator authority

in order to install the MQSeries Server.

2. When creating an SMS Job to distribute and install the software package,

ensure that you select the appropriate workstation command. The workstation commands are displayed on the Job Details dialog in the Run Phase section and appear in a drop-down list box.

Unattended Installation on Windows NT

You can install MQSeries for Windows NT on a remote machine without interaction, provided that the remote machine can share the client CD-ROM, or a copy of the files on it, and that you can execute a command on the remote machine. This process is called unattended (or silent) installation, and is particularly useful for installing MQSeries for Windows NT clients over a network because you can do it from a shared drive on a LAN file server.

Because there is no user interaction, unattended installation uses a response file. A response file is an ASCII text file containing values for the installation options you want to select. For information on the format of response files, see the MQSeries Clients book.

There are three ways to generate a response file:

1. Edit the response file (setup.iss) supplied in the Winnt directory on the

MQSeries for Windows NT client CD-ROM, using an ASCII file editor.

2. Generate your own response file using an ASCII file editor.

Chapter 7. Installing MQSeries Clients 87

Installing on Windows NT

3. Carry out an installation on a machine and record the options selected to

install the product in a response file. To do this you must run setup.exe with the -r parameter, and optionally, the -noinst parameter:

a. Load the MQSeries for Windows NT client CD-ROM. If you have

autorun enabled, the language selection panel will appear. Cancel this panel.

b. Run setup.exe from the root folder of the CD-ROM, with the -r

parameter. This can be done by dragging setup.exe from Windows NT Explorer to the Run dialog in the start menu and adding -r to the end of the file name, or by typing the fully-qualified path to setup.exe into the Run dialog, followed by -r.

c. The language selection dialog reappears. Perform an installation as you

want it performed on the remote machine.

d. If you are asked to restart the system, you do not need to do so if you

are only generating a response file.

The -noinst parameter (which, if present, must precede the -r parameter) suppresses the MQSeries installation; Setup generates only a response file. The installation creates a response file called setup.iss in the Windows directory, normally c:\winnt. Save this file; you can edit it if necessary.

Use the response file you have created to install the product on a remote machine. (See “Installing on the Remote Machine”.)

Installing on the Remote Machine

The remote machine must have access to a shared resource or drive on a file server that contains the client CD-ROM or a copy of it. Perform the procedure described in “Installing from a LAN” on page 85 up to the point where you run Setup. Copy your response file to a location on the file server that is accessible from the remote machine. You can now start the installation on the remote machine:

1. On the remote machine, go to the Setupxx folder on the shared resource.

2. Substitute Setupxx with the name of the language subfolder for the

language that you require.

3. Run setup.exe:

setup -g<logfile> -f1<responsefile> -f2<secondarylogfile> -s

This installs in the language specified by Setupxx.

In the above command:

The full path to an installation log file. Setup creates a U.S. English ASCII text log file containing details of what happens during installation. You should check this file to see if any errors occurred. If

MQSeries for AS/400, V5.1 Quick Beginnings

IBM GC34-5557-00 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Tables

Welcome to MQSeries for AS/400

Conventions

Chapter 1. About MQSeries

Message Queuing

MQI – a Common Application Programming Interface

Time-Independent Applications

Message-Driven Processing

Messages and Queues

What is a Message?

What is a Queue?

MQSeries Objects

Queue Managers

Queues

Process Definitions

Channels

Namelists

Clients and Servers

Instrumentation Events

Types of Event

Transactional Support

Chapter 2. What’s New in MQSeries for AS/400, V5.1

Chapter 3. Planning to Install the MQSeries for AS/400 Server

Hardware Requirements

Disk Space Required

Software Requirements

Connectivity

AS/400 Install Libraries and Directories

AS/400 Library Structure

QMxxxx Library

IFS Root File System

User Profiles

Compilers Supported for MQSeries for AS/400, V5.1 Applications

Delivery

MQSeries for AS/400 Components

Creating the System-Default Objects

Chapter 4. Installing, Migrating to, and Deleting MQSeries for AS/400

Before Installation

Setting System Values

QCCSID

QUTCOFFSET

QSYSLIBL

QALWOBJRST

Installation Procedure

Installation of Translated Versions

Reinstallation

Verifying the Installation

Post Installation Tasks

Quiescing MQSeries

Quiescing previous releases of MQSeries for AS/400

Quiescing V5.1 of MQSeries for AS/400

Migrating to MQSeries for AS/400, V5.1

What are the Differences

Overview of Migration Process

Before Migration

Migration

Verifying the Migration

After Migration

Deleting MQSeries for AS/400, V5.1

Standard Deletion

Entire Deletion

Chapter 5. Using MQSeries for AS/400, V5.1

Before you Start

Introducing Command Sets

CL Commands

Using CL Commands

MQSeries (MQSC) Commands

Running MQSC Commands

PCF Commands

Working with MQSeries

Creating a Queue Manager

Starting a Queue Manager

Creating a Local Queue

Sending a Test Message

Browsing Queues