Administration using the administration message object

A queue manager is administered by sending messages to a special administration queue AdminQ that is owned by the local queue manager. The messages sent to this queue are interpreted and, if found to be valid administration messages, the commands contained within them are executed.

Before a synchronous client can send messages to a queue manager in the WebSphere MQ Everyplace, system, the client must be configured with the IP address and other information for the target queue manager.

The client device can obtain this connection definition by putting a connection administration message (MQeConnectionAdminMsg) to its own local administration queue. This message contains all the addressing information required for the client to establish a connection to the server. Specifically, it contains an WebSphere MQ Everyplace style Url indicating the address, and an additional command used to specify a servlet when interacting with a Web server.

The native code acts as a synchronous client (no visible queues), so the server is not able to put messages onto the client's administration queue directly. However, a client program can remove these connection administration messages from the server queue and put them onto the client administration queue.

The following actions can be used with connection administration messages:

MQE_MAM_ACTION_CREATE
If no definition exists for the target queue manager, create one, else return an error code in any reply message

MQE_MAM_ACTION_DELETE
If a definition exists for the target queue manager, delete it, else return an error code in any reply message

MQE_MAM_ACTION_INQUIRE
If a definition exists for the target queue manager, then return the url and command, else return an error code in any reply message

The connection definitions, once created, are persistent. This means that when a connection definition is successfully put onto the local administration queue, the remote queue manager connection definition remains available until an application removes it.

See the WebSphere MQ Everyplace Application Programming Guide for further information about administration messages and their processing.

The following code shows an example of sending a connection administration message to a local synchronous client.

#include <hmq.h>
/* MQeMsgObject styles */
#define MQE_MSG_STYLE_DATAGRAM 0
#define MQE_MSG_STYLE_REQUEST  1
#define MQE_MSG_STYLE_REPLY    2
 
/* AdminMsg action codes (generic) */
#define MQE_MAM_ACTION_CREATE          1
#define MQE_MAM_ACTION_DELETE          2 
#define MQE_MAM_ACTION_INQUIRE         4
#define MQE_MAM_ACTION_INQUIRE_ALL     5
#define MQE_MAM_ACTION_UPDATE          6
#define MQE_MAM_ACTION_UPDATE_REGISTRY 7
 
#define MQE_QAM_ACTION_ADD_ALIAS 52
#define MQE_QAM_ACTION_REMOVE_ALIAS 53
 
#define MQE_CAM_ACTION_ADD_ALIAS 52
#define MQE_CAM_ACTION_REMOVE_ALIAS 53
 
/* AdminMsg return codes */
#define MQE_MAM_RC_SUCCESS 0
#define MQE_MAM_RC_FAIL    1
#define MQE_MAM_RC_MIXED   2
 
 
 
/* Return a request admin message object of TYPE, targeted to QM,
   with the specified ACTION, STYLE, and CHARACTERISTICS.
 */
MQEHFIELDS hmqAdminMsg(MQEHSESS hSess, MQECHAR *Type, MQECHAR *qm,
		       MQEINT32 action, MQEINT32 style,
		       MQEHFIELDS characteristics,
		       MQEINT32 *pCompCode, MQEINT32 *pReason)
{
  MQEHFIELDS res = MQEHANDLE_NULL;
  MQEBYTE rc = MQE_MAM_RC_SUCCESS;
  MQEINT32 cc,reason;
  struct MQeField_st mam_fd[] = {
    {  MQE_TYPE_INT, 0,  0, "admact", (MQEVOID *)0, 1, (MQEVOID *)0},
    {  MQE_TYPE_INT, 0,  0, MQE_MSG_STYLE, (MQEVOID *)0, 1, (MQEVOID *)0},
    {  MQE_TYPE_BYTE, 0, 0, "admrc", (MQEVOID *)0, 1, (MQEVOID *)0 },
    {  MQE_TYPE_ASCII, 0,  0, "admqmgr", (MQEVOID *)0, 0, (MQEVOID *)0},
    {  MQE_TYPE_FIELDS, 0,  0, "admparms", (MQEVOID *)0, 1, 
       (MQEVOID *)0}
  };
 
  mam_fd[0].fd_data = (MQEVOID *)&action;
  mam_fd[1].fd_data = (MQEVOID *)&style;
  mam_fd[2].fd_data = (MQEVOID *)&rc;
  mam_fd[3].fd_data = (MQEVOID *)qm;
  mam_fd[3].fd_datalen = StrLen(qm);
  mam_fd[4].fd_data = (MQEVOID *)&characteristics;
 
  res = MQeFieldsAlloc(hSess,Type,pCompCode,pReason);
  if (*pCompCode != MQECC_OK) { goto exit; }
 
  cc = MQeFieldsPutByArrayOfFd(hSess,res,&;mam_fd,
			       sizeof(mam_fd)/sizeof(mam_fd[0]),
			       pCompCode,pReason);
  
 exit:
  if (*pCompCode != MQECC_OK && res != MQEHANDLE_NULL) {
    MQeFieldsFree(hSess,res,&cc,&reason);
    res = MQEHANDLE_NULL;
  }
  return res;
 
}
 
 
/* Return a connection admin message suitable for setting up a synchronous
   client connection to a queue manager.
   The client will use URL and CMD to establish a connection to
   queue manager QM.
 */
MQEHFIELDS hmqConnectionAdminMsg(MQEHSESS hSess, MQECHAR *qm, 
				 MQECHAR *url, MQECHAR *cmd,
				 MQEINT32 *pCompCode, MQEINT32 *pReason)
{
  MQEINT32 cc, reason, n;
  MQEHFIELDS h1 = MQEHANDLE_NULL;
  MQEHFIELDS h2 = MQEHANDLE_NULL;
  MQEHFIELDS res = MQEHANDLE_NULL;
  struct MQeField_st fd[3];
 
  /* Allocate adapter fields object. */
  h1 = MQeFieldsAlloc(hSess,MQE_OBJECT_TYPE_MQE_FIELDS,pCompCode,pReason);
  if (*pCompCode != MQECC_OK) { goto exit; }
 
  /* Fill in adapter info */
  fd[0].fd_name = "cad";
  fd[0].fd_namelen = 3;
  fd[0].fd_datatype = MQE_TYPE_ASCII;
  fd[0].fd_base = (MQEVOID *)0;
  fd[0].fd_data = url;
  fd[0].fd_datalen = StrLen(url);
  fd[1].fd_name = "cadap";
  fd[1].fd_namelen = 5;
  fd[1].fd_datatype = MQE_TYPE_ASCII;
  fd[1].fd_base = (MQEVOID *)0;
  fd[1].fd_data = cmd;
  fd[1].fd_datalen = StrLen(cmd);
 
  cc = MQeFieldsPutByArrayOfFd(hSess,h1,&amp;fd,2,pCompCode,pReason);
  if (*pCompCode != MQECC_OK) { goto exit; }
 
  /* Allocate characeristics fields object. */
  h2 = MQeFieldsAlloc(hSess,MQE_OBJECT_TYPE_MQE_FIELDS,pCompCode,pReason);
  if (*pCompCode != MQECC_OK) { goto exit; }
 
  /* Fill in characteristics */
  n = 1; /* number of adapters */
  fd[0].fd_name = "cads:0";
  fd[0].fd_namelen = 6;
  fd[0].fd_datatype = MQE_TYPE_FIELDS;
  fd[0].fd_base = (MQEVOID *)0;
  fd[0].fd_data = (MQEVOID *)&h1;
  fd[0].fd_datalen = 1;
  fd[1].fd_name = "cads";
  fd[1].fd_namelen = 4;
  fd[1].fd_datatype = MQE_TYPE_ARRAYELEMENTS;
  fd[1].fd_base = (MQEVOID *)0;
  fd[1].fd_data = (MQEVOID *)&n;
  fd[1].fd_datalen = 1;
  fd[2].fd_name = "admname";
  fd[2].fd_namelen = 7;
  fd[2].fd_datatype = MQE_TYPE_ASCII;
  fd[2].fd_base = (MQEVOID *)0;
  fd[2].fd_data = qm;
  fd[2].fd_datalen = StrLen(qm);
 
  cc = MQeFieldsPutByArrayOfFd(hSess,h2,&fd,3,pCompCode,pReason);
  if (*pCompCode != MQECC_OK) { goto exit; }
 
  res = hmqAdminMsg(hSess,MQE_OBJECT_TYPE_MQE_CONNECTION_ADMIN_MSG,
		    qm, MQE_MAM_ACTION_CREATE, MQE_MSG_STYLE_REQUEST, h2,
		    pCompCode,pReason);
 exit:
 
  if (h1 != MQEHANDLE_NULL) {
    MQeFieldsFree(hSess,h1,&cc,&reason);			 
  }
  if (h2 != MQEHANDLE_NULL) {
    MQeFieldsFree(hSess,h2,&cc,&reason);			 
  }
  return res;
}
 
/* Configure local client to establish connections to QM via URL and CMD.
   Return zero on success.
*/
MQEINT32
hmqSetConnection(MQEHSESS hSess, MQECHAR *qm, MQECHAR *url, MQECHAR *cmd) {
  MQEHFIELDS cam;
  MQEINT32 cc,reason,res;
 
  cam = hmqConnectionAdminMsg(hSess,qm,url,cmd,&cc,&reason);
  if (cam != MQEHANDLE_NULL) {
    MQeQMgrPutMsg(hSess,"","AdminQ",(MQEVOID *)0,cam,&res,&reason);
    MQeFieldsFree(hSess,cam,&cc,&reason);
  } 
  return res;
}
 


© IBM Corporation 2002. All Rights Reserved