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;
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.
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 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);
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);
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.