Queue managers need to be created before use. The creation step uses the QueueManagerConfigure Java class or the C administration API to create persistent queue manager data in a registry. The queue manager then uses the registry each time its starts. The WebSphere MQ Everyplace Configuration Guide provides further information on configuring queue managers.
Normally, creating and starting a queue manager can require a large set of parameters. Therefore, the required parameters are supplied as an instance of MQeFields, storing the values as fields of correct type and name.
The parameters fall into two categories, queue manager parameters and registry parameters. Each of these categories is represented by its own MQeFields instance, and both are also enclosed in an MQeFields instance. The following Java example explains this concept, passing the queue managers name, "ExampleQM" and the location of a registry, "C:\ExampleQM":
/*create fields for queue manager parameters and place the queue manager name MQeFields queueManagerParameters = new MQeFields(); queueManagerParameters.putAscii(MQeQueueManager.Name, "ExampleQM"); /*create fields for registry parameters and place the registry location MQeFields registryParameters = new MQeFields(); registryParameters.putAscii(MQeRegistry.DirName, "C:\\ExampleQM\\registry"); /*create fields for combined parameters and place the two sub fields MQeFields parameters = new MQeFields(); parameters.putFields(MQeQueueManager.Registry, queueManagerParameters); parameters.putFields(MQeQueueManager.Registry, registryParameters);
Wherever you see "initialize the parameters" in code snippets, prepare a set of parameters as shown in the example, including the appropriate options. Only one queue manager name and one registry location are mandatory.
The following lists the parameter names that you can pass to the queue manager and the registry:
You always need the first two parameters. The last two are for auto-registration of the registry if it wishes to obtain credentials from the mini-certificate server.
A queue manager can run:
The following sections describe the example client, servers and servlet that are provided in the examples.queuemanager package. All queue managers are constructed from the same base WebSphere MQ Everyplace components, with some additions that give each its unique properties. WebSphere MQ Everyplace provides an example class, MQeQueueManagerUtils, that encapsulates many of the common functions.
All the examples require parameters at startup. These parameters are stored in standard ini files. The ini files are read and the data is converted into an MQeFields object. The loadConfigFile() method in the MQeQueueManagerUtils class performs this function.
The mqeQueueManager_new function loads a queue manager for an established registry. To do this, you need information supplied by a queue manager parameter structure and a registry parameter structure.
The following example shows how you can set these structures to their default values, supplying only the directories of the queue store and registry:
MQeQueueManagerHndl hQueueManager; MQeRegistryParms regParms = REGISTRY_INIT_VAL; MQeQueueManagerParms qmParms = QMGR_INIT_VAL; regParms.hBaseLocationName = hRegistryDirectory; qmParms.hQueueStore = hStore; qmParms.opFlags = QMGR_Q_STORE_OP; rc = mqeQueueManager_new(&exceptBlock, &hQueueManager, hQMName, ®Params, &qmParms);
This creates a queue manager and loads its persistant information from the registry and creates queues. However, you must start the queue manager to:
To start the queue manager, use
rc = mqeQueueManager_start(&hQueueManager, &exceptBlock);
Once the queue manager is started, messaging operations can take place and any queues that have messages on them are loaded.
To stop the queue manager, use:
rc = mqeQueueManager_stop(&hQueueManager, &exceptBlock);
Once stopped, you can restart the queue manager as required.
At the end of the application, you must free the queue manager to release any resources it uses, for example memory. First, stop the queue manager and then use:
rc = mqeQueueManager_free(&hQueueManager, &exceptBlock);
The registry is the primary store for queue manager-related information; one exists for each queue manager. Every queue manager uses the registry to hold its:
For a file registry this parameter should be set to:
com.ibm.mqe.registry.MQeFileSession
For a private registry it should be set to:
com.ibm.mqe.registry.MQePrivateSession
Aliases can be used to represent these values.
A client typically runs on a device platform, and provides a queue manager that can be used by applications on the device. It can open many connections to other queue managers.
A server usually runs for long periods of time, but clients are started and stopped on demand by the application that use them. If multiple applications want to share a client , the applications must coordinate the starting and stopping of the client.
Starting a client queue manager involves:
The following code fragment starts a client queue manager:
/*-------------------------------------*/ /* Init - first stage setup */ /*-------------------------------------*/ public void init( MQeFields parms ) throws Exception { if ( queueManager != null ) /* One queue manager at a time */ { throw new Exception( "Client already running" ); } sections = parms; /* Remember startup parms */ MQeQueueManagerUtils.processAlias( sections ); /* set any alias names */ // Uncomment the following line to start trace before the queue manager is started // MQeQueueManagerUtils.traceOn("MQeClient Trace", null); /* Turn trace on */ /* Display the startup parameters */ System.out.println( sections.dumpToString("#1\t=\t#2\r\n")); /* Start the queue manage */ queueManager = MQeQueueManagerUtils.processQueueManager( sections, null); }
Once you have started the client, you can obtain a reference to the queue manager object either from the static class variable MQeClient.queueManager or by using the static method MQeQueueManager.getReference(queueManagerName).
The following code fragment loads aliases into the system:
public static void processAlias( MQeFields sections ) throws Exception { if ( sections.contains( Section_Alias ) ) /* section present ? */ { /* ... yes */ MQeFields section = sections.getFields( Section_Alias ); Enumeration keys = section.fields( ); /* get all the keywords */ while ( keys.hasMoreElements() ) /* as long as there are keywords*/ { String key = (String) keys.nextElement(); /* get the Keyword */ MQe.alias( key, section.getAscii( key ).trim( ) ); /* add */ } } }
Use the processAlias method to add each alias to the system. WebSphere MQ Everyplace and applications can use the aliases once they have been loaded.
Starting a queue manager involves:
The following code fragment starts a queue manager:
public static MQeQueueManager processQueueManager( MQeFields sections, Hashtable ght ) throws Exception { /* */ MQeQueueManager queueManager = null; /* work variable */ if ( sections.contains( Section_QueueManager) ) /* section present ? */ { /* ... yes */ queueManager = (MQeQueueManager) MQe.loader.loadObject(Section_QueueManager); if ( queueManager != null ) /* is there a Q manager ? */ { queueManager.setGlobalHashTable( ght ); queueManager.activate( sections ); /* ... yes, activate */ } } return( queueManager ); /* return the alloated mgr */ }
MQePrivateClient is an extension of MQeClient with the addition that it configures the queue manager and registry to allow for secure queues. For a secure client, the [Registry] section of the startup parameters is extended as follows:
(ascii)LocalRegType=PrivateRegistry
Location of the registry
(ascii)DirName=.\ExampleQM\PrivateRegistry
Adapter on which registry sits
(ascii)Adapter=RegistryAdapter
Network address of certificate authority
(ascii)CAIPAddrPort=9.20.7.219:8082
Refer to Security for more details on secure queues and MQePrivateClient.
For MQePrivateClient and MQePrivateServer to work, the startup parameters must not contain CertReqPIN, KeyRingPassword and CAIPAddrPort.
A server usually runs on a server platform. A server can run server-side applications but can also run client-side applications. As with clients, a server can open connections to many other queue managers on both servers and clients. One of the main characteristics that differentiate a server from a client is that it can handle many concurrent incoming requests. A server often acts as an entry point for many clients into an WebSphere MQ Everyplace network . WebSphere MQ Everyplace provides the following server examples:
MQeServer is the simplest server implementation.
When two queue managers communicate with each other, WebSphere MQ Everyplace opens a connection between the two queue managers. The connection is a logical entity that is used as a queue manager to queue manager pipe. Multiple connections may be open at any time.
Server queue managers, unlike client queue managers can have one or more listeners. A listener waits for communications from other queue managers, and processes incoming requests, usually by forwarding them to its owning queue manager. Each listener has a specified adapter that defines the protocol of incoming communications, and also specifies any extra data required.
You can create listeners on the local queue manager using either the MQeAdministrator class or administration messages, remotely and locally. However, a remote queue manager must have a listener in order to receiver a message.
This section describes how to create a listener using the MQeAdministrator class. As the listener can take a number of arguments, use MQeProperties to pass the parameters as name and value string pairs. The adapter defines the parameter names and their values. The following example defines a listener using a TcpipHttp adapter, listening on port 8080:
/*create a properties object to pass the adapter parameters to the listener String listenerName = "MyListener"; String adapter = "com.ibm.mqe.adapters.MQeTcpipHttpAdapter"; String port = "8080"; MQeProperties properties = new MQeProperties(); properties.setProperty(MQeCommunicationsAdapter.COMMS_ADAPTER_CLASS, adapter); properties.setProperty(MQeCommunicationsAdapter.COMMS_ADAPTER_PORT, port); properties.setProperty(MQeCommunicationsAdapter.COMMS_ADAPTER_LISTEN, true); /* create an administrator MQeAdministrator admin = new MQeAdministrator(myQMgr); /* created the administrator, now use it to create the listener admin.listenCreateNew(listenerName, properties, timeout, maxChannels); /* now use the administrator itself to start the listener admin.listenerStart(listenerName);
When the listener is started, the server is ready to accept network requests.
When the server is deactivated:
MQePrivateServer is an extension of MQeServer with the addition that it configures the queue manager and registry to allow for secure queues. See Security.
The following section describes some requirements for running Java and C implementations of WebSphere MQ Everyplace and.
The java queue manager runs inside an instance of a JVM. You can have only one queue manager per JVM. However, you can invoke multiple instances of the JVM.
Each of these queue managers must have a unique name. Java applications run inside the same JVM as the queue manager they use.
You can run only one queue manager within a native C process. You need multiple processes for multiple queue managers. Each of these queue managers must have a unique name.