This chapter contains the following topics that describe how to install MessageQ software on UNIX systems:
Before you install MessageQ, there are several installation requirements you should perform to ensure that the installation runs smoothly and the software is installed correctly. They are:
Preparing to Install the MessageQ Software
Use the bill of materials (BOM) to check the contents of your software distribution kit. The kit contains the following:
Your distribution kit includes a letter, Read Before Installing MessageQ for UNIX. This letter tells you how to access the release notes, which provide late-breaking information you should read before installing, configuring, or using MessageQ. It also describes describes supported hardware and software environments.
Your kit contains a CD-ROM for industry-standard CD-ROM readers, labeled MessageQ for UNIX, Version 4.0.
The MessageQ for UNIX user documentation set contains the following online manuals:
MessageQ provides this online documentation in HTML format which you can read using any World Wide Web browser. For example, Digital UNIX includes the Netscape Navigator Web browser. You can also purchase hardcopies of the online user documentation separately. For more information on how to access the online documentation, refer to the section on Installing Online User Documentation. Hardcopy versions of the documentation are also provided depending upon whether you purchased the run-time or development kit.
Before you install MessageQ software, you must be able to log in as the superuser on the system where you are installing MessageQ. Your system must also meet the hardware, software, and disk space requirements listed in the Read Before Installing MessageQ for UNIX letter.
We recommend that you back up your system disk before installing any software. For details on performing a system disk backup, see your UNIX system user documentation.
This topic describes the tasks for installing the MessageQ software on Digital UNIX and other UNIX systems, as follows:
Complying with the Installation Requirements
Backing up Your System Disk
Installing the MessageQ Software on UNIX Systems
If MessageQ for UNIX is already installed on your system, you must delete the existing subsets and their associated files and symbolic links before installing the new software version. For information on deleting MessageQ subsets, see the Deleting Installed MessageQ Subsets topic. After you have deleted all the existing subsets, you can proceed with the installation for your particular UNIX system.
The length of a MessageQ installation can vary, depending on the type of media from which you are installing and your system configuration. Appendix A lists the files and directories created during the installation.
Note:
MessageQ provides a conversion utility that lets you convert your existing group initialization file to run under MessageQ for UNIX, Version 4.0. For a description of the conversion utility, see the Converting Your Group Initialization File to Version 4.0 topic.
The MessageQ installation dialogues display a list of options that let you choose the subsets you want to install. If you choose a subset and then decide you don't want to install it, you can cancel your selection and redisplay the list of subsets.
Table 1-1 describes the installation subsets. Choosing which Subsets to Install
This topic describes the steps for installing MessageQ development software on most UNIX systems. You can stop the installation procedure at any time by using the terminal interrupt key sequence for your UNIX system (see your system user documentation set for a description of the terminal interrupt key). If you stop the installation, files created up to that point are not deleted automatically; you must delete these files manually.
Installing MessageQ software on a UNIX system requires copying the installation files from the CD-ROM and then installing the software. Table 1-2 lists the .tar files contained on both the development and runtime media kits for each supported UNIX environment. MessageQ software installation on these UNIX systems takes 15 to 30 minutes.
The steps for installing MessageQ development software are as follows:
device is the name of the CD device on the system and
directory is the name of the directory on which you are mounting the CD-ROM:
# cd /mnt/mydisk
tar utility, as
follows:
where # tar -xvf /
device_namedevice_name is the name of the device from which you are installing the media kit. The tar utility creates a directory within the directory you specified in step 1, and installs the files in that subdirectory.
x /etc/setld, 50187 bytes, 99 tape blocks
x output/space, 0 bytes, 0 tape blocks
x output/SPACE, 10240 bytes, 20 tape blocks
x output/instctrl/DMQDEV400.inv, 88 bytes, 1 tape blocks
x output/instctrl/DMQDEV400.ctrl, 109 bytes, 1 tape blocks
x output/instctrl/DMQ400.comp, 0 bytes, 0 tape blocks
x output/instctrl/DMQDEV400.scp, 3860 bytes, 8 tape blocks
x output/instctrl/DMQINC400.inv, 632 bytes, 2 tape blocks
x output/instctrl/DMQINC400.ctrl, 99 bytes, 1 tape blocks
x output/instctrl/DMQINC400.scp, 4367 bytes, 9 tape blocks
x output/instctrl/DMQRTO400.inv, 2545 bytes, 5 tape blocks
x output/instctrl/DMQRTO400.ctrl, 106 bytes, 1 tape blocks
x output/instctrl/DMQRTO400.scp, 12294 bytes, 25 tape blocks
x output/instctrl/DMQCL400.inv, 762 bytes, 2 tape blocks
x output/instctrl/DMQCL400.ctrl, 99 bytes, 1 tape blocks
x output/instctrl/DMQCL400.scp, 4204 bytes, 9 tape blocks
x output/instctrl/DMQDOC400.inv, 1542 bytes, 4 tape blocks
x output/instctrl/DMQDOC400.ctrl, 106 bytes, 1 tape blocks
x output/instctrl/DMQDOC400.scp, 5391 bytes, 11 tape blocks
x output/instctrl/DMQEXA400.inv, 2464 bytes, 5 tape blocks
x output/instctrl/DMQEXA400.ctrl, 102 bytes, 1 tape blocks
x output/instctrl/DMQEXA400.scp, 3768 bytes, 8 tape blocks
x output/instctrl/DMQRLS400.inv, 281 bytes, 1 tape blocks
x output/instctrl/DMQRLS400.ctrl, 99 bytes, 1 tape blocks
x output/instctrl/DMQRLS400.scp, 3765 bytes, 8 tape blocks
x output/instctrl/DMQ.image, 160 bytes, 1 tape blocks
x output/DMQDEV400, 159508 bytes, 312 tape blocks
x output/DMQINC400, 177506 bytes, 347 tape blocks
x output/DMQRTO400, 6115211 bytes, 11944 tape blocks
x output/DMQCL400, 6983511 bytes, 13640 tape blocks
x output/DMQDOC400, 7834159 bytes, 15302 tape blocks
x output/DMQEXA400, 705064 bytes, 1378 tape blocks
x output/DMQRLS400, 706843 bytes, 1381 tape blocks
x output/INSTCTRL, 12427264 bytes, 24272 tape blocks
x output/DMQ.image, 160 bytes, 1 tape blockssetld portable installation utility simplifies the installation of MessageQ
software. Use setld from the current working directory to install MessageQ
software, as follows:
# /etc/setld -l output
*** Enter Subset Selections ***
The subsets listed below are optional:
1) MessageQ Development Environmen 2) MessageQ Include Files
3) MessageQ Run Time Environment 4) MessageQ Client Library
5) MessageQ Online Documentation 6) MessageQ Example Programs
7) MessageQ Release Notes 8) All of the Above
9) None of the Above
10) Exit without installing subsetsEnter your choice(s): 8
Y if you have correctly selected the subsets you want to install. The
installation procedure proceeds from this point without user interaction.
You are installing the following subsets:
MessageQ Development Environment MessageQ Include Files
MessageQ Run Time Environment MessageQ Client Library
MessageQ Online Documentation MessageQ Example Programs
MessageQ Release NotesIs this correct? (y/n): y
A complete installation will take 2 to 15 minutes
depending on processor and installation media typeMessageQ for UNIX, V4.0.0
Copyright (c) BEA Systems, Inc. 1997
All Rights Reserved.MessageQ Development Environment (DMQDEV400)
Copying from output (disk)
VerifyingMessageQ Include Files (DMQINC400)
Copying from output (disk)
VerifyingMessageQ Run Time Environment (DMQRTO400)
Copying from output (disk)
VerifyingMessageQ Client Library (DMQCL400)
Copying from output (disk)
VerifyingMessageQ Online Documentation (DMQDOC400)
Copying from output (disk)
VerifyingMessageQ Example Programs (DMQEXA400)
Copying from output (disk)
VerifyingMessageQ Release Notes (DMQRLS400)
Copying from output (disk)
Verifying You may run the installation verification program
for DMQRTO400 now. If your kernel parameters are
not sufficient for MessageQ, the verification
program may fail. You may run the installation verification at any
time by running: setld -v DMQRTO400* Do you want to run the installation verification
for DMQRTO400 now ? (y/n) : [y] ? n#
Symbolic links required by MessageQ software are created in the following locations:
/usr/bin
After the software is installed, you may want to perform the postinstallation tasks described in the Performing Postinstallation Tasks topic.
During the MessageQ installation procedure, you can choose to install the MessageQ Client for UNIX by selecting the Client Library and Include Files installation subsets (see the Choosing which Subsets to Install topic). The MessageQ Client for UNIX allows applications running in a UNIX environment to send and receive messages to target applications in a networked environment using the MessageQ Client Library Server (CLS) software that is running on a MessageQ server. The CLS is automatically installed when you choose the Run-time Environment subset installation option.
The MessageQ Client for UNIX provides applications with full support of MessageQ features without requiring the system resources needed by a MessageQ UNIX message server that supports full message routing. User applications designed as clients or servers can be deployed on systems running MessageQ Client software.
The MessageQ Client for UNIX User's Guide contains more information about the MessageQ Client for UNIX.
If errors occur during the MessageQ installation procedure, check your preinstallation steps to ensure that the correct versions of prerequisite software have been installed. Errors can occur during the installation if the following conditions exist:
Installing the MessageQ Client for UNIX
Recovering from Installation Errors
For descriptions of error messages generated by these conditions, see the system management user documentation for the UNIX system on which you are running. If an error occurs while installing MessageQ and you believe the error is caused by a problem with MessageQ, call BEA Technical Support at the number provided in the Preface.
After completing the installation procedure, you may want to perform several recommended postinstallation tasks. MessageQ does not require you to perform the postinstallation tasks in a particular order.
The postinstallation tasks are as follows:
Performing Postinstallation Tasks
Note:
You are required to convert your group configuration files
only if you have been running previous versions of MessageQ
for UNIX software.
MessageQ for UNIX systems provides an Installation Verification Procedure (IVP) that allows you check that MessageQ Server software is correctly installed. Note that you cannot run the IVP to verify the installation if you are installing only the Client Library subset.
Running the Installation Verification Procedure (IVP)
where # setld -v DMxRTO400DMx is platform-specific and will be one of the following:
|
|
Digital UNIX |
|
|
All other supported UNIX systems |
The IVP displays the following output:
# setld -v DMARTO400
Do you want to run the installation verification
for DMARTO400 now? (y/n): y
MessageQ Installation Verification Procedure (IVP)
The MessageQ IVP is checking the system IPC resources.############################################################
The MessageQ IVP requires exclusive access to a
single bus and group. The bus and group must not
currently be running and must not be used by any other
process while the IVP is running.* Enter bus id (1-9999) [1] ?
* Enter group id (1-32000) [1] ?###########################################################
Writing group initialization file for group 1 to/tmp/dmq16034.group
Starting group control process using logfile /tmp/dmq16034.log
Waiting for group control processes to start###########################################################
Starting the MessageQ IVP
Checking status of queuing engine
Queuing engine is running
Checking basic messaging functions
All basic messaging functions are working properly
Group shut down successfully###########################################################
The MessageQ IVP has passed.
Cleaning up IVP files in /tmp.#
If for some reason the IVP fails, you will see output similar to the following:
...
Checking status of queuing engine
No response from queuing engine
The MessageQ IVP has failed.
Check log file, /tmp/dmq29166.log, for additional information
setld: ivp failed.
If you run the IVP and it fails, see the log file created by the IVP to determine why the failure occurred.
MessageQ includes online documentation in HTML format that can be read using a World Wide Web browser. Digital UNIX includes the Netscape Navigator Web browser for reading HTML-based documentation. If your non-Digital UNIX system does not currently have a Web browser installed, you can obtain a copy of a Web browser free of charge or for a nominal fee from the Internet.
In addition, most PC environments now include a Web browser. Therefore, if the UNIX system that you are using does not include a Web browser for you to view the MessageQ documentation, you can also can view the documentation using a PC that is networked to a UNIX system running MessageQ.
To read the online user documentation, follow these steps:
OR
/usr/kits/DMA400/books/bookshelf.html (Digital UNIX)
/usr/kits/DMQ400/books/bookshelf.html (All other UNIX systems)
bookshelf.html page. The first page in each book is the table of contents.
Hyperlinks can be used to navigate through the information contained within a
single book. To view information in a different book, you must return to the
contents page of the book you are reading and then jump to the bookshelf page to
select another book.
For those sites with a corporate Intranet, MessageQ documentation can be copied to a single node and linked into the corporate information base contained on an internal Web site. Copying the online documentation to an Intranet server limits the use of disk space to a single system while making it accessible to everyone on the corporate Intranet. After the documentation is copied to the corporate Intranet server, users must be given a URL to access the documentation or a description of the page from which the documentation can be accessed.
MessageQ for UNIX provides a conversion utility that lets you quickly convert your existing group initialization file so that it is compatible with the Version 4.0 software. The conversion utility checks to make sure that the current sections and parameters in the group initialization file are appropriate for use with MessageQ for UNIX, Version 4.0.
Note that the conversion utility does not update the group initialization file to include the new Version 4.0 sections and parameters. To update your initialization file to change and use the new Version 4.0 features, refer to Chapter 3, which describes all the sections and parameters in the group initialization file.
To convert your existing group initialization file, follow these steps:
# cd /usr/kits/DM
x400/util/
Where:
Listing 1-1 and Listing 1-2 provide examples of the %QCT section of a group initialization file prior to and after conversion by the convert.sh utility.
Listing 1-1 QCT Section Prior to Conversion
%QCT
TEMPLATE 0 64000 100 P 0 N L
QUEUE1 1 64000 100 P 0 N L
QUEUE2 2 64000 100 P 0 Y G
QUEUE3 3 64000 100 P 0 Y L
QUEUE4 4 64000 100 M 0 Y L
QUEUE5 5 64000 100 S 3 N L
QUEUE6 6 64000 100 S 3 Y L
QUEUE7 7 64000 100 S 0 N L
QUEUE10 10 64000 100 P 0 N L
QUEUE11 11 64000 100 S 10 N L
QUEUE12 12 64000 100 S 10 N L
! queues with differing quotas. quotas can be turned on
! using the monitor programs (dmqmonc and dmqmonm).
QUEUE13 13 8000 25 P 0 N L
QUEUE14 14 16000 50 P 0 N L
QUEUE15 15 32000 100 P 0 N L
! queues that require explicit confirmation and allow out of
! order confirmation.
QUEUE16 16 64000 100 PE 0 N L
QUEUE17 17 64000 100 PEO 0 N L
! the example_q_n queues are used by the example programs
! provided in the MessageQ Example Programs subset
example_q_1 193 64000 100 P 0 N L
example_q_2 194 64000 100 P 0 N L
! The DEAD_LETTER_QUEUE is the target for UMA modes of
! xx_DLQ. A user process may attach to this queue to collect
! undeliverable messages for application-specific processing
DEAD_LETTER_QUEUE 96 100000 500 P 0 N L
%EOS
Listing 1-2 QCT Section After Conversion
%QCT
TEMPLATE 0 64000 100 None . P 0 . N L N
QUEUE1 1 64000 100 None . P 0 . N L N
QUEUE2 2 64000 100 None . P 0 . Y G N
QUEUE3 3 64000 100 None . P 0 . Y L N
QUEUE4 4 64000 100 None . M 0 . Y L N
QUEUE5 5 64000 100 None . S 3 . N L N
QUEUE6 6 64000 100 None . S 3 . Y L N
QUEUE7 7 64000 100 None . S 0 . N L N
QUEUE10 10 64000 100 None . P 0 . N L N
QUEUE11 11 64000 100 None . S 10 . N L N
QUEUE12 12 64000 100 None . S 10 . N L N
! queues with differing quotas. quotas can be turned on
! using the monitor programs (dmqmonc and dmqmonm).
QUEUE13 13 8000 25 None . S 10 . N L N
QUEUE14 14 16000 50 None . P 0 . N L N
QUEUE15 15 32000 100 None . P 0 . N L N
! queues that require explicit confirmation and allow out
! of order confirmation.
QUEUE16 16 64000 100 None . P 0 EI N L N
QUEUE17 17 64000 100 None . P 0 EO N L N
! the example_q_n queues are used by the example programs
! provided in the MessageQ Example Programs subset
example_q_1 193 64000 100 None . P 0 . N L N
example_q_2 194 64000 100 None . P 0 . N L N
! The DEAD_LETTER_QUEUE is the target for UMA modes of
! xx_DLQ. A user process may attach this queue to collect
! undeliverable messages for application-specific proces-
! sing
DEAD_LETTER_QUEUE 96 100000 500 None . P 0 . Y L N
%EOS
You can display a list of installed MessageQ subsets using the following command:
# setld -i | grep MessageQ
Table 1-3 shows the status display for installation subsets.
This listing will show corrupted subsets if an error occurred during installation. If a MessageQ subset is corrupt, delete that subset by following the instructions in the Deleting Installed MessageQ Subsets topic and reinstall the subset.
To delete a subset and its associated files and symbolic links, enter the following command:
# setld -dsubsetname
where subsetname is the name of the subset you want to delete. For example, to delete the Development Environment Subset on a Digital UNIX system, you would enter the following command:
# setld -d DMADEV400
To delete the Release Notes and Example on other UNIX systems, enter the following command:
# setld -d DMQRLS400 DMQEXA400
After MessageQ has been successfully installed, you should delete the contents of the output directory, which contains the files that you extracted from the media. To delete the files in the output directory, enter the following command:
# rm -r output
If you plan to use MessageQ for UNIX to communicate with MessageQ on other systems, you must have configured TCP/IP or DECnet (only supported on Digital UNIX systems) networking and started the network service.
The remote systems with which you intend to communicate must have their names and addresses entered in the Internet host database (/etc/hosts) or DECnet database.