Starting queue managers

A queue manager can run:

The following sections refer extensively to the example code to illustrate how to start queue managers. 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 a class MQeQueueManagerUtils that encapsulates many of the common functions.

All the examples require parameters at startup.

Client queue managers

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 and, if configured with a peer connection can accept incoming requests from other queue managers.

Class Aliases

The aliases are not processed by the queue manager itself. The queue manager requires these aliases to have been processed prior to its activation as several of these aliases are required to allow the queue manager to activate properly. For example, queues must have a queue store adapter defined so that they have a storage area in which to hold their messages. MsgLog is the default queue store adapter, if this is not present then a MsgLog not found exception is thrown.

MQeRegistry parameters for the queue manager

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:

Registry type

MQE_REGISTRY_LOCAL_REG_TYPE
The type of registry being opened. file registry and private registry are currently supported. A private registry is required for some of the security features. See Security.

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.

File registry parameters

The following parameter is needed for a file registry:

MQE_REGISTRY_DIR_NAME
The name of the directory holding the registry files.

Private registry parameters

The following parameters can be used for a private registry.

MQE_REGISTRY_DIR_NAME
The name of the directory holding the registry files

MQE_REGISTRY_PIN
The PIN for the private registry

MQE_REGISTRY_KEY_RING_PASSWORD
The password or phrase used to protect the registry's private key

MQE_REGISTRY_CA_IP_ADDR_PORT
The address and port number of a mini-certificate server

MQE_REGISTRY_CERT_REQ_PIN
The certificate request number preallocated by the mini-certificate administrator to allow the registry to obtain its credentials

The first three parameters are always needed. The last two parameters are needed for auto-registration of the registry if it wishes to obtain its credentials from the mini-certificate server.

Note:
For security reasons, the PIN and KeyRingPassword, if supplied, are deleted from the startup parameters as soon as the queue manager has been activated.

For either type of registry MQE_REGISTRY_SEPARATOR is also needed if you want to use a non-default separator. The separator is the character that is used between the components of an entry name, for example:

<QueueManager><Separator><Queue>

This parameter is specified as a string but it should contain a single character. If it contains more than one only the first character is used.

You should use the same separator character every time a registry is opened. It should not be changed once a registry is in use.

If this parameter is not specified the separator defaults to '+'.

RegistryAdapter

MQeRegistry.RegistryAdapter (ascii)
The class, (or an alias that resolves to a class), of the adapter that the registry uses to store its data. This value should be included if you want the registry to use an adapter other than the default MQeDiskFieldsAdapter. Any valid adapter class can be used.

Starting a client queue manager

Starting a client queue manager involves:

  1. Adding any aliases to the system
  2. Enabling trace if required
  3. Starting the queue manager

The following code fragment starts a client queue manager:

MQERETURN createQueueManager(MQeExceptBlock *pErrorBlock, MQeQueueManagerHndl
 										*phQMgr, MQeFieldsHndl hInitFields, 
										 MQeStringHndl hQStore)
{
 
   MQERETURN rc;
   MQeQueueManagerConfigureHndl hQMgrConfigure;
 
      /* Create instance of QueueManagerConfigure Class */
      rc = mqeQueueManagerConfigure_new(pErrorBlock,&hQMgrConfigure,
														hInitFields,hQStore);
 
      if (MQERETURN_OK == rc) {
         /* define queue manager */
         rc = mqeQueueManagerConfigure_defineQueueManager(hQMgrConfigure, 
																					pErrorBlock);
         if (MQERETURN_OK == rc) {
            /* define system default queues */
            rc = mqeQueueManagerConfigure_defineDefaultSystemQueue
														(hQMgrConfigure, pErrorBlock, NULL);
         }
 
         /* close mqeQueueManagerConfigure */
         (void)mqeQueueManagerConfigure_close(hQMgrConfigure, NULL);
         if (MQERETURN_OK == rc) {
            /* create queue manager */
            rc = mqeQueueManager_new(pErrorBlock, phQMgr);
            if (MQERETURN_OK == rc) {
               rc = mqeQueueManager_activate(*phQMgr, pErrorBlock, hInitFields);
            } 
         }
         /* free mqeQueueManagerConfigure */
         (void)mqeQueueManagerConfigure_free(hQMgrConfigure, NULL);
      }
 
   return rc;
}

Once you have started the client, you can obtain a reference to the queue manager object by using API call mqeQueueManager_getReference(queueManagerName).

Server queue managers

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 .

Example MQeServer

MQeServer is the simplest server implementation.

This server can be started with the following command:

qm_server server_QMgr_name [-p private_reg_PIN]

You must supply the -p parameter if the queue manager uses a private registry. Otherwise, the queue manager's registry is treated as a file registry. The program activates the queue manager (including a channel listener listening on port 8081) and goes into an indefinite sleep.

Use ctrl-C to shut down the server.

To delete the constructed queue manager, use the example qm_delete.

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.

The new parameters control the use of the connection. The MaxChannels parameter controls the maximum number of connections that can be open at any time. A special value of 0 means that the queue manager can handle an unlimited number of connections.

The following parameters control how incoming network requests are handled:

Listen
The network adapter that handles incoming network requests. For example this could be an http adapter or a pure tcp/ip adapter. As well as the adapter name, you can pass parameters that dictate how the adapter should listen. For instance Listen=Network::8082 means use the Network adapter where Network is an alias to listen on port 8082. (This assumes that the Network alias is set to either an http or a tcp/ip adapter.)

Network
This parameter is used to specify the adapter to use for network read and write requests, once the initial network request has been accepted. Usually this is the same as the adapter used on the Listen parameter.

TimeInterval
The time in seconds before idle connections are timed out. As connections are persistent logical entities that last longer than a single queue manager request, and can survive network breakages, it may be necessary to time out connections that have been inactive for a period of time.

Once the server has been initialized it must be activated.

When you activate a server the following occurs:

  1. A channel manager is started
  2. The queue manager is started
  3. The channel listener is started

Code to demonstrate server activation is provided in queue manager example Ex2.

Example MQePrivateServer

MQePrivateServer is an extension of MQeServer with the addition that it configures the queue manager and registry to allow for secure queues. See Security.



© IBM Corporation 2002. All Rights Reserved