Connection definition administration in C

There is an important difference between administration available in C to that in Java. The Java product relies solely on the administration message, C provides an administration API for the user to locally administer WebSphere MQ Everyplace. More information may be found about the administration API in Administration using the administrator API. This chapter assumes you have already read the chapter on administration and know how to create an administrator handle and exception block used in the calls to the administration API. This example is in the transport.c, broker.dll for C.

Before we look at the individual functions providing the API to administer the connection definition, it is worthwhile looking at the structure containing the information about the connection definition that is passed into all the functions requiring information, that is all except the function to delete the connection definition. The MQeConnectionDefinitionParms structure is as follows:

MQEVERSION         version;        
MQEINT32           opFlags;        
MQeStringHndl      hDescription;   
MQeStringHndl      hAdapterClass;  
MQeStringHndl *    phAdapterParms; 
MQEINT32           destParmLen;    
MQeStringHndl      hAdapterCommand;
MQeStringHndl      hChannelClass;  
MQeStringHndl      hViaQMName;     

Version
This is a field for internal use only and should not be set by the user.

opFlags
On input to a function this field provides bit flags indicating the areas of the resource that are to be administered. On output from a function if the action has been successful the flags will indicate the operations performed, if the action has failed the flags will indicate the failed component.

hDescription
The description for this connection definition.

hAdapterClass
The communications adapter class that will be used by this connection definition, currently there is just one communications adapter for C. In the MQe_Adapter_Constants.h header file there is a constant to define the class - MQE_HTTP_ADAPTER.

phAdapterParams
An array containing the network information required to connect to the remote queue manager. In an IP network this will contain the network address and IP port. The first element in the array is assumed to be the IP address, the second element is assumed to be the port number.

destParmLen
The length of the phAdapterParams array.

hAdapterCommand
This field may contain a servlet name to be included in an HTTP header.

hChannelClass
The class of channel to use, this should be set to MQE_CHANNEL_CLASS, defined in MQe_Connection_Constants.h

hViaQMName
If this connection definition defines a via connection then all other parameters should be null with this parameter containing the name of the via queue manager name.

A constant in MQe_Connection_Constant.h - CONNDEF_INIT_VAL sets the values of this structure to initial values which can then be altered as required.

Create a connection definition

In order to create a connection definition will need to call the function:

mqeAdministrator_Connection_create(MQeAdministratorHndl, hAdmin,
                                     MQeExceptBlock* pExceptBlock,
                                     MQeStringHndl hConnectionName,
                                     MQeConnectionDefinitionParms* pParams);
 

The third parameter will define the name of the connection definition. As stated, this must be the name of the remote queue manager to which this connection definition holds the route.

The fourth parameter is a structure holding information that is required to setup the connection definition information. Either the hViaQMName field should be set or the hAdapterClass, phAdapterParams, destParmLen, hAdapterCommand and hChannelClass in order to create a connection definition. For instance, to create a connection definition, first create and set up an MQeConnectionDefinition parameter structure:

/* Create the structure and set it to the initial values */
MQeConnectionDefinitionParms parms = CONNDEF_INIT_VAL;

Create an MQeString to hold the name of the remote queue manager, this becomes the name of the connection definition:

rc = OSAMQESTRING_NEW(&error, "ServerQM", SB_STR, &hQueueMgrName);

Set the adapter and channel class names, these must be set to these names as these are the only classes currently supported:

parms.hAdapterClass = MQE_HTTP_ADAPTER;
parms.hChannelClass = MQE_CHANNEL_CLASS;

In order to set up an array we need to allocate some memory then setup the network information. This example shows using the loopback address with the listener expected to be on port 8080:

   OSAMEMORY_ALLOC(&error, (MQEVOID**) &parms.phAdapterParms, 
												(sizeof(MQEHANDLE) * 2), "comms test");
   rc = OSAMQESTRING_NEW( &error, "127.0.0.1", SB_STR, 
									&parms.phAdapterParms[0]);
   rc = OSAMQESTRING_NEW( &error, "8080", SB_STR, 
									&parms.phAdapterParms[1]);

We now set the number of element in the array:

parms.destParmLen = 2;

And last of all set the flags to tell the receiving administration function what information it should look for in the structure:

parms.opFlags = CONNDEF_ADAPTER_CLASS_OP | CONNDEF_ADAPTER_PARMS_OP | 
															CONNDEF_CHANNEL_CLASS_OP;

Now, having set everything up we can call the administration function in order to create our connection definition. Note, it is wise to check the return code in order to determine whether the call has been successful

rc = mqeAdministrator_Connection_create( hAdministrator, &error,
														 h hQueueMgrName,	&parms);
if (MQERETURN_OK == rc) {
         fprintf(pOutput,"connection definition to ServerQM
									at 127.0.0.1:8081 successfully added\n");
      }

The above example creates a direct connection definition. To modify this to create a via connection definition, set the parameter structure to the default values and the name of the remote queue manager as usual:

MQeConnectionDefinitionParms parms = CONNDEF_INIT_VAL;
rc = OSAMQESTRING_NEW(&error, "ServerQM", SB_STR, &hQueueMgrName);
 
Now set the name of the queue manager that routes 
the messages on to the remote queue manager. 
 
rc = OSAMQESTRING_NEW(&error, 
								"RoutingQM",
                     	SB_STR, 
								&parms.hViaQMName);

Now all that remains to do is to set the flags that tell the administration function what to look for in the structure:

parms.opFlags  = CONNDEF_VIAQM_OP;

Then call the function, as with the direct connection definition:

rc = mqeAdministrator_Connection_create(  hAdministrator, 
															&error,
                                           hQueueMgrName,
															&parms);
 

Delete a connection definition

Delete a connection as follows. If the connection does not exist, the return code of MQERETURN_COMMS_MANAGER_WARNING is given with the reason code of MQEREASON_CONDEF_DOES_NOT_EXIST.

rc = mqeAdministrator_Connection_delete(hAdministrator,
										&error, hQueueMgrName);

Update a connection definition

As previously stated, it is strongly recommended that you ensure a connection is not being used when a connection definition is updated. The flags are used to determine which parts of the information in the connection definition are to be updated. Therefore, even if a value is provided in the structure, if the correct flag is not set, that value is not used:

MQeConnectionDefinitionParms parms = CONNDEF_INIT_VAL;

Create a new description:

rc = OSAMQESTRING_NEW(&error, "replacement description", SB_STR, 
								&parms.hDescription);

Set the opFlags field as follows. The description is not updated. Instead the, administration function attempts to update the value for the name of the via queue manager:

parms.opFlags = CONNDEF_VIAQM_OP;

Set the opFlags field as follows to obtain the desired behavior:

Parms.opFlags = CONNDEF_DESC_OP;

Then, call the function to update the connection definition as follows:

rc = mqeAdministration_Connection_update(hAdministrator , &error, 
															hQueueMgrName, &parms);

General comment

As can be seen from the example, much repetitive code is involved in creating and then checking the reply for an administration message. Therefore, put this code into a common class that may be used by all classes creating and checking the replies of administration messages.

The examples contain the full code for updating and deleting a connection definition.



© IBM Corporation 2002. All Rights Reserved