Setting environment variables for IBM MQ classes for JMS/Jakarta Messaging

Before you can compile and run IBM® MQ classes for JMS or IBM MQ classes for Jakarta Messaging applications, the setting for your CLASSPATH environment variable must include the IBM MQ classes for JMS or IBM MQ classes for Jakarta Messaging Java archive (JAR) file. Depending on your requirements, you might need to add other JAR files to your class path. To run the scripts provided with IBM MQ classes for JMS and IBM MQ classes for Jakarta Messaging, other environment variables must be set.

About this task

To compile and run IBM MQ classes for JMS or IBM MQ classes for Jakarta Messaging applications, use the CLASSPATH setting for your platform and Java messaging version, as shown in the following tables. Alternatively, you can specify the class path on the java command instead of using the environment variable.

For IBM MQ classes for JMS, the setting includes the samples directory, so that you can compile and run the IBM MQ classes for JMS sample applications.

For IBM MQ classes for Jakarta Messaging, new samples are being prepared.

Table 1. CLASSPATH settings for Jakarta Messaging 3.0 to compile and run IBM MQ classes for Jakarta Messaging applications

Platform	CLASSPATH setting
AIX®	CLASSPATH= MQ_INSTALLATION_PATH/java/lib/com.ibm.mq.jakarta.client.jar:
Linux®	CLASSPATH= MQ_INSTALLATION_PATH/java/lib/com.ibm.mq.jakarta.client.jar:
IBM i	CLASSPATH=/QIBM/ProdData/mqm/java/lib/com.ibm.mq.jakarta.client.jar:
Windows	CLASSPATH= MQ_INSTALLATION_PATH\java\lib\com.ibm.mq.jakarta.client.jar;
z/OS®	CLASSPATH= MQ_INSTALLATION_PATH/java/lib/com.ibm.mq.jakarta.client.jar;

Table 2. CLASSPATH settings for JMS 2.0 to compile and run IBM MQ classes for JMS applications, including the sample applications

Platform	CLASSPATH setting
AIX	CLASSPATH= MQ_INSTALLATION_PATH/java/lib/com.ibm.mq.allclient.jar: MQ_INSTALLATION_PATH/samp/jms/samples:
Linux	CLASSPATH= MQ_INSTALLATION_PATH/java/lib/com.ibm.mq.allclient.jar: MQ_INSTALLATION_PATH/samp/jms/samples:
IBM i	CLASSPATH=/QIBM/ProdData/mqm/java/lib/com.ibm.mq.allclient.jar: /QIBM/ProdData/mqm/java/samples/jms/samples:
Windows	CLASSPATH= MQ_INSTALLATION_PATH\java\lib\com.ibm.mq.allclient.jar; MQ_INSTALLATION_PATH\tools\jms\samples;
z/OS	CLASSPATH= MQ_INSTALLATION_PATH/java/lib/com.ibm.mq.allclient.jar: MQ_INSTALLATION_PATH/java/samples/jms/samples:

In these tables, MQ_INSTALLATION_PATH represents the high-level directory in which IBM MQ is installed.

The manifest of the JAR file com.ibm.mq.jakarta.client.jar or com.ibm.mq.allclient.jar contains references to most of the other JAR files required by IBM MQ classes for JMS applications, and so you do not need to add these JAR files to your class path. These JAR files include those required by applications that use the Java Naming Directory Interface (JNDI) to retrieve administered objects from a directory service and by applications that use the Java Transaction API (JTA).

However, you must include additional JAR files in your class path in the following circumstances:

• If you are using channel exit classes that implement the channel exit interfaces defined in the com.ibm.mq package, instead of those defined in the com.ibm.mq.exits package, you must add the IBM MQ classes for Java JAR file, com.ibm.mq.jar, to your class path.
• If your application uses JNDI to retrieve administered objects from a directory service, you must also add the following JAR files to your class path:
  • fscontext.jar
  • providerutil.jar
• If your application uses the JTA, you must also add jta.jar to your class path.

Note: These additional JAR files are required only for compiling your applications, not for running them.

The scripts provided with IBM MQ classes for JMS and IBM MQ classes for Jakarta Messaging use the following environment variables:

MQ_JAVA_DATA_PATH

This environment variable specifies the directory for log and trace output.

MQ_JAVA_INSTALL_PATH

This environment variable specifies the directory where IBM MQ classes for JMS is installed.

MQ_JAVA_LIB_PATH

This environment variable specifies the directory where the IBM MQ classes for JMS libraries are stored, as shown in the previous tables.

• On Windows, after installing IBM MQ, run the command setmqenv.
  If you do not run this command first, the following error message might appear when you are issuing a dspmqver command:

  AMQ8351: IBM MQ Java environment has not been configured 
  correctly, or the IBM MQ JRE feature has not been installed.
  

  Note: This message is to be expected if you did not install the IBM MQ Java runtime environment (JRE) (see Additional Windows features prerequisite checking.
• On AIX and Linux systems, set the environment variables yourself:
  For JMS 2.0, use one of the following scripts to set the environment variables:

  • If you are using a 32-bit JVM, use the script setjmsenv.
  • If you are using a 64-bit JVM on an AIX or Linux system, use the script setjmsenv64.

  For Jakarta Messaging 3.0, use one of the following scripts to set the environment variables:

  • If you are using a 32-bit JVM, use the script setjms30env.
  • If you are using a 64-bit JVM, use the script setjms30env64.

  These scripts are in the MQ_INSTALLATION_PATH/java/bin directory, where MQ_INSTALLATION_PATH represents the high-level directory in which IBM MQ is installed.

  You can use these scripts in a variety of ways. You can use the script as a basis for setting the required environment variables, as shown in the table, or add them to .profile using a text editor. If you have a non-typical setup, edit the script contents as necessary. Alternatively, you can run the script in every session from which JMS startup scripts are to be run. If you choose this option, you need to run the script in every shell window you start, during the JMS verification process:

  • For JMS 2.0, type . ./setjmsenv or ../setjmsenv64.
  • For Jakarta Messaging 3.0, type . ./setjms30env or . ./setjms30env64.

  On IBM i, you must set the environment variable QIBM_MULTI_THREADED to Y. You can then run multithreaded applications in the same way that you run single threaded applications. For more information, see Setting up IBM MQ with Java and JMS.