2
Quick Start

Oracle Message Broker provides sample administration scripts and sample programs that allow you to quickly set up and use the system. By editing the sample scripts you can customize the system for your needs.

Note: This chapter provides a quick start guide for the steps required to operate the Oracle Message Broker in Remote Mode (Non-Local Mode). For information on using the Oracle Message Broker in Local Mode, refer to "Running in Local Mode".

This chapter assumes that you have installed the Oracle Message Broker and that you have access to an LDAP Directory that has been updated to support the Oracle Message Broker. Refer to the Oracle Message Broker Installation Guide for information on installing these components.

This chapter covers the following:

• Working with the Administration Utilities

• Verifying Directory Contents

• Starting and Stopping the Oracle Message Broker

• Running the JMS Sample Programs

Working with the Administration Utilities

This section shows you how to use the sample administration scripts to create Oracle Message Broker administrative objects. Oracle Message Broker stores administrative objects as entries in an LDAP Directory. See Chapter 4 for detailed information on the organization of the LDAP Directory.

Note: The Oracle Message Broker also supports lightweight configuration for administration without using an LDAP Directory Refer to Chapter 13 for information on lightweight configuration.

The Oracle Message Broker retrieves configuration information from the LDAP Directory and uses the directory to locate and set parameters for destinations, message servers, and for other administrative tasks. Client programs also use the directory to locate the Oracle Message Broker and to find destinations for messages.

If you are setting up the Oracle Message Broker, you need to create an OMB Instance and create entries for your destinations and message servers. To perform these administration tasks you can use AdminUtil with the sample administration scripts shown in this chapter, or you can use the Oracle Message Broker Graphical User Interface. The Oracle Message Broker Graphical User Interface provides wizards for creating OMB Instances and other required entries. For information on using ombadmin, see Chapter 11, "Administration GUI".

Overview of the Sample Administration Scripts

The Oracle Message Broker sample administration scripts allow you to quickly create required administrative entries in the directory and set up Oracle Message Broker queues and topics. You can use these scripts as they are or customize them for your needs. Before working with the sample scripts, determine which drivers you need to use for your queues or topics (see Chapter 7, for more information on drivers). The Oracle Message Broker includes the following drivers:

• Oracle Advanced Queuing (AQ) Driver

• Oracle AQ Lite Driver

• IBM MQSeries Driver

• Oracle Volatile Driver

• Oracle Multicast Driver

• TIBCO/Rendezvous Driver

Table 2-1 lists the sample scripts (these are in $OMB_HOME/samples/admin or %OMB_HOME%\samples\admin on Windows NT systems.)

The sample scripts include comments that explain the entries and attributes. If you need to modify a script, copy it and then modify the copy. You can create directory entries for Oracle Message Broker by running AdminUtil using the sample scripts.

Table 2-1  Sample Administration Scripts

Script	Description
SetupOMB	Creates all the basic entries needed to set up an OMB Instance.
SetupACI	Creates entries required for ACI.
SetupAQ	Creates the entries needed to set up an Oracle AQ queue and topic.
SetupAQLite	Creates the entries needed to set up an Oracle AQ Lite queue and topic.
SetupMQSeries	Creates the entries needed to set up an MQSeries queue.
SetupMcast	Creates the entries needed to set up a Multicast topic.
SetupProp	Creates the entries needed to set up a propagation job. This references several entries created in the SetupOMB, SetupMQSeries, and SetupAQ scripts. Execute these scripts before SetupProp.
SetupRv	Creates the entries needed to set up a TIB/Rendezvous topic.
SetupVol	Creates the entries needed to set up Oracle Volatile queues and topics.

Using the Oracle Message Broker Instance Configuration Script

The SetupOMB script creates an Oracle Message Broker Instance (OMB Instance) and the required top level directory entries. An OMB Instance contains the administrative objects, as directory entries, required for an administrator to start or modify an Oracle Message Broker. The SetupOMB script also sets values for several required attributes. To execute the SetupOMB script, perform the following steps (this assumes that $OMB_HOME is set to the Oracle Message Broker installation directory):

1. Set the environment for your system:

   On Unix with the Bourne or Korn shell:

   $ . ./$OMB_HOME/bin/ombenv.sh
   
   

   or with the C-Shell environment:

   % source $OMB_HOME/bin/ombenv.csh
   
   

   On Windows NT run the batch file:

   > C:%OMB_HOME%\bin\ombenv.bat
   
   

   The Oracle Message Broker installation creates these startup scripts (ombenv.bat, ombenv.sh, and ombenv.csh).

2. Execute AdminUtil using the SetupOMB script. AdminUtil displays its progress as it runs.

   On Unix:

   % cd $OMB_HOME/samples/admin
   % AdminUtil -f SetupOMB
   
   

   On Windows NT:

   > cd %OMB_HOME%\samples\admin
   > AdminUtil -f SetupOMB
   

Note: AdminUtil prompts for an authentication DN and password. In addition, when the SSL level is set to 2 or 3, it prompts for the SSL wallet location and password (the default SSL level is 0). You can enter these parameters either at the prompt, or on the command line. See Chapter 12 for information on Security. Table 4-27 contains a complete list of AdminUtil command line options.

Using the Driver Configuration Scripts

To run the driver sample scripts, perform the following steps:

1. Run the SetupOMB script, (see the section, "Using the Oracle Message Broker Instance Configuration Script").

2. Refer to the comments in the driver setup script for information on changes you can make to customize the script.

3. Execute AdminUtil using the selected script for the driver you want to add. Run the SetupDriver script, where Driver is one of the following: AQ, AQLite, Vol, MQSeries, Mcast, or Rv. AdminUtil displays its progress as it executes.

   For example, to setup the Oracle Volatile Driver on Unix systems:

   % AdminUtil -f SetupVol
   
   

   On Windows NT systems, run the command:

   > AdminUtil -f SetupVol
   
   

Using the Propagation Configuration Script

The propagation job sample script sets up a propagation job for transferring messages between targets. See Chapter 7 for more information on propagation and propagation jobs. To run the propagation sample script, perform the following steps:

1. Run the SetupOMB script, (see the section, "Using the Oracle Message Broker Instance Configuration Script").

2. Run the Setup driver scripts for the drivers you need to support, (see the section, "Using the Driver Configuration Scripts").

3. Refer to the comments found in the SetupProp script for information on changes you need to make to customize the script.

4. Execute AdminUtil using the SetupProp script for the queues or topics that you want to propagate. AdminUtil displays its progress as it executes.

   On Unix:

   % AdminUtil -f SetupProp
   
   

   On Windows NT:

   > AdminUtil -f SetupProp
   
   

Verifying Directory Contents

Use the Oracle Message Broker Manager to view the contents of the directory and verify that the entries you created are in the directory. The command to start the Oracle Message Broker Manager is:

% ombadmin

When you view your OMB Instance using the Oracle Message Broker Manager, you can verify your configuration entries.

You can also use AdminDirCheck to validate entries. Refer to "Checking Directory Entries with AdminDirCheck" for information on AdminDirCheck.

Starting and Stopping the Oracle Message Broker

After creating the administrative entries using the setup scripts, execute the MsgBroker command with the -start option to start the Oracle Message Broker. Table 2-2 shows the MsgBroker command line options. Use the MsgBroker command as follows:

On Unix:

% MsgBroker -omb RDN [options] &

On Windows NT:

> MsgBroker -omb RDN [options] 

where RDN is:

RDN	the relative distinguished name, RDN, for the message broker entry (for more information on distinguished names and LDAP, refer to Chapter 4).

For example, to start the Oracle Message Broker using the RDN, cn=msg_Broker,cn=your_Inst,cn=OMB, use the following command:

On Unix:

% MsgBroker -omb cn=msg_Broker,cn=your_Inst,cn=OMB -start &

On Windows NT:

> MsgBroker -omb cn=msg_Broker,cn=your_Inst,cn=OMB -start

For more information on starting the Oracle Message Broker, see "The msg_broker Entry and Distinguished Names".

You can also start the Oracle Message Broker in Local Mode without using the MsgBroker command. For information on starting the Oracle Message Broker in Local Mode, refer to "Running in Local Mode".

Table 2-2  MsgBroker Command Options

Option	Description
-D auth_dn	The auth_dn supplies the DN to use for user name authentication.
-errorlevel level	Set the error reporting level. The parameter level is set to an integer value in the range 1-4: 1 - print error message for the top exception 2 - print error messages for all linked exceptions 3 - print stack trace for the top exception 4 - print stack trace for all linked exceptions The default value for errorlevel is 2.
-fullVersion	Displays the full program version information.
-heap size	Supplies a heap size to the specified, size, in Megabytes. This sets the size of the JVM heap used by the Oracle Message Broker process.
-noauth	Specifies that LDAP authentication is not required on the LDAP server.
-omb RDN	Specifies the relative distinguished name, RDN, for the message broker entry (for more information on distinguished names and LDAP, refer to Chapter 4). The RDN must be enclosed in quotes on Windows NT systems.
-P wallet_password	Specifies the wallet password. This is ignored if the value of -U is 0 or 1.
-ping	Displays the status of the specified Oracle Message Broker. The status message indicates if the Oracle Message Broker is running. The MsgBroker command returns 0 if the MsgBroker is running. Otherwise, the MsgBroker command returns non-zero if the MsgBroker cannot be contacted. This option is not available for Local Mode operation.
-start	Use this option to start the specified MsgBroker.
-stats format	Produces a DMS log file containing Oracle Message Broker DMS statistics. The name of the DMS log file is the same as the associated Oracle Message Broker log file, prepended with "dms-". Refer to "Collecting Runtime Metrics" for details on the format of the DMS log file. The parameter format is set to an integer value in the range 1-4: 1 - dump DMS statistics by appending to the existing log file and use pretty print format for the data. If the DMS log file does not exist, it is created. 2- dump DMS statistics by appending to the existing log file, do not use pretty print format for printing the data. If the DMS log file does not exist, it is created. 3 - dump DMS statistics by replacing the existing DMS log file and use pretty print format for the data. 4 - dump DMS statistics by replacing the existing DMS log file, do not use pretty print format for printing the data. This option is ignored when -start or -stop are also specified on the same command-line.
-stop	Using this option to shutdown the specified MsgBroker.
-U value	Specifies if SSL is used, and the authentication level. Valid values are: 0, 1, 2, and 3. 0 - no SSL. This is the default if -U is not specified. 1 - SSL with no authentication. 2 - SSL with server-side authentication. 3 - SSL with server-side and client-side authentication.
-version	Displays the program version number.
-w auth_passwd	Supplies a password, auth_passwd, for authentication on the LDAP server.
-W wallet_path	Specifies the path to an exported wallet file. This is ignored if the value of -U is 0 or 1.

If you do not supply the security command line options to MsgBroker, a dialogue box prompts for a user DN and password. Enter a user DN and password. If the directory does not use authentication, or if you have set properties to indicate the user DN and password, leave these fields blank and select the Continue button. If you select the Exit button, the MsgBroker command exits (for more information security, refer to Chapter 12, "Security").

If -w is specified without -D, then a dialogue box prompts for the user DN.

If -D is specified without -w, then a dialogue box prompts for the user password associated with the DN supplied with the -D.

If -noauth is specified, the -D and -w options are ignored. If no authentication properties are defined, the Oracle Message Broker attempts an anonymous bind to the LDAP Directory.

Authentication and authorization are delegated to the LDAP server. The credentials required to start the Oracle Message Broker are those required for updating Oracle Message Broker entries.

The msg_broker Entry and Distinguished Names

Starting and stopping the Oracle Message Broker using the MsgBroker command requires that you enter a RDN for a msg_broker entry. For example:

% MsgBroker -start -omb cn=msg_Broker,cn=your_Inst,cn=OMB

Where the RDN for the message broker entry is:

cn=msg_Broker,cn=your_Inst,cn=OMB

In this example, the full DN for the msg_Broker entry is the relative distinguished name shown above, plus the following:

cn=Products,cn=OracleContext,ou=sales,o=oracle,c=us

The Oracle Message Broker installer writes several distinguished name components to the startup scripts, including: the country, c=, the organization, o=, and the organizational unit, ou=. These scripts set environment variables that the MsgBroker command uses to start the Oracle Message Broker. Oracle standards specify the following entries:

cn=OMB,cn=Products,cn=OracleContext

The initial naming context is the top level component of the full message broker DN. For example, in the sample above, the initial naming context is:

cn=Products,cn=OracleContext,ou=sales,o=oracle,c=us

The OMB_IC environment variable, that the MsgBroker command uses contains the initial context. This variable is set in the startup scripts: ombenv.bat, ombenv.csh, and ombenv.sh (see "Using the Oracle Message Broker Instance Configuration Script" for information on these scripts).

Note: The MsgBroker command, with the -omb option fails with an "unexpected error: entry not found" when a full DN is supplied rather than a RDN for the message broker entry.

Required Environment Variables

Oracle Message Broker clients, and the MsgBroker command require the environment variables, OMB_EF, OMB_IC, OMB_LP, and OMB_OF. The ombenv scripts define the values for these environment variables (for more information on the ombenv scripts, see "Using the Oracle Message Broker Instance Configuration Script"). Table 2-3 shows the required environment variables.

Table 2-3 Oracle Message Broker Environment Variables

Variable	Description
OMB_EF	Entry Factory
OMB_IC	LDAP Initial Context
OMB_LP	LDAP Provider Properties
OMB_OF	Object Factory

Stopping the Oracle Message Broker

The Oracle Message Broker command MsgBroker -stop executes a shutdown of all drivers, connections, and open transactions. To shut down the Oracle Message Broker and stop the system, issue the command:

On Unix:

% MsgBroker -omb RDN -stop &

On Windows NT:

> MsgBroker -omb RDN -stop

Where the value RDN is the relative distinguished name (RDN) for the message broker entry of the active Oracle Message Broker.

Note: Stopping the Oracle Message Broker using MsgBroker with the -stop option can take several seconds, or longer.

For example:

% MsgBroker -omb cn=msg_broker,cn=your_Inst1,cn=OMB -stop

If you do not supply the security command line options to MsgBroker, a dialogue box prompts for a user DN and password. Enter a user DN and password. If the directory does not use authentication, or if you have set properties to indicate the user DN and password, leave these fields blank and select the Continue button. If you select the Exit button, the MsgBroker command exits (for more information security, refer to Chapter 12, "Security").

Authentication and authorization are delegated to the LDAP server. The credentials required to stop the Oracle Message Broker are those required for updating Oracle Message Broker entries.

You can also stop the Oracle Message Broker when it is running in Local Mode. For information on using the Oracle Message Broker in Local Mode, refer to "Running in Local Mode".

Checking the Status of the Oracle Message Broker

Use the -ping option to MsgBroker to check if an Oracle Message Broker is available. Table 2-2 shows the MsgBroker command line options, including the -ping option. To check the status of the Oracle Message Broker, use the MsgBroker command as follows:

On Unix:

% MsgBroker -ping -omb RDN [options]

On Windows NT:

> MsgBroker -ping -omb RDN [options] 

where RDN is:

RDN	the relative distinguished name, RDN, for the message broker entry that you want to check the status for (for more information on distinguished names and LDAP, refer to Chapter 4).

If the specified Oracle Message Broker is available, MsgBroker displays the following message and returns with a 0 return value:

Broker answered

If the specified Oracle Message Broker is not available, MsgBroker displays the following message and returns with a non-zero return value:

Broker unreachable

Running Oracle Message Broker as an NT Service

When running on Windows NT systems with Java 1.2, the Oracle Message Broker can be installed as a service that can be started automatically when the system starts up. To start Oracle Message Broker as a service, use the command:

%OMB_HOME%\bin\Register options

Where, options are the same as available for the MsgBroker command (Table 2-2 shows the MsgBroker command line options). For example, the following command registers an Oracle Message Broker instance as a service:

> Register -noauth -omb cn=msg_broker,cn=testomb,cn=OMB -start

Note that only one instance of Oracle Message Broker can be started as a service per system. Before running the register command, set the default JVM for the system to the JVM installed by Oracle Message Broker. In addition, the default PATH environment variable for the system must contain %OMB_HOME%\jdk\bin, %OMB_HOME%\bin, and %OMB_HOME%\..\..\orb\bin.

To unregister a previously registered Windows NT service, use the command:

%OMB_HOME%\bin\Unregister

Running the JMS Sample Programs

The $OMB_HOME/samples/client/java/queue directory contains sample programs for sending and receiving messages (on Windows NT systems, the directory is, %OMB_HOME%\samples\client\java\queue). Sample programs for publishing and subscribing using JMS topics are in the directory $OMB_HOME/samples/client/java/topic (on Windows NT systems, %OMB_HOME%\samples\client\java\topic). The Readme files in these directories provide information on compiling and running the sample programs.

All Java client programs should include the environment variables shown in Table 2-3 on the Java command line. These environment variables set values that allow the Oracle Message Broker to run.