Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

MQe_Rules_plugin.h File Reference


Detailed Description

Rules function parameter structures and function pointer type signatures.

This file contains type definitions of the function pointers which the user must set to point to any rules functions which he/she has instantiated. The mapping of rules function pointers to user rules functions is done in the user's initialization function.

This initialization function (MQeRules_NewFunction) is also the function which serves as the entry point to the user's rules module. It is therefore mandatory, whereas all other rules functions are optional.

The initialization function is called when the queue manager is loaded into memory. This is when the rules module is loaded. The module is unloaded when the queue manager is freed from memory. Thus, any one rules implementation is linked to the lifecycle of a single queue manager. Only one rules module can be loaded during a queue manager's lifecycle in memory but other modules can be loaded from this module if required. The 'master rules' functions could invoke the corresponding functions in any other modules as required.

The rules initialization function is the only rules function for which the user has to provide an implementation. Where the user does not provide a function to map to one of the other rules functions, the default behaviour is documented under the relevant function prototype below.

This file also contains definitions of all of the input and output structure parameters to be used in users' implementations of rules functions.

Note in particular the MQEVOID * pPrivateData element in the input structure parameter for most rules and the output structure parameter for MQeRules_NewFunction. This element can be assigned a rules instance structure (as seen in the examples) in MQeRules_NewFunction. This structure is then carried around between user's rules functions so can be used to contain rules 'global' data.


Data Structures

struct  MQeRulesActivateQMgr_in_st_
 input parameter structure for MQeRules_ActivateQMgrFunction. More...

struct  MQeRulesActivateQMgr_out_st_
 output parameter structure for MQeRules_ActivateQMgrFunction. More...

struct  MQeRulesCloseQMgr_in_st_
 input parameter structure for MQeRules_CloseQMgrFunction. More...

struct  MQeRulesCloseQMgr_out_st_
 output parameter structure for MQeRules_CloseQMgrFunction. More...

struct  MQeRulesDeleteMessage_in_st_
 input parameter structure for MQeRules_DeleteMessageFunction. More...

struct  MQeRulesDeleteMessage_out_st_
 output parameter structure for MQeRules_DeleteMessageFunction. More...

struct  MQeRulesGetMessage_in_st_
 input parameter structure for MQeRules_GetMessageFunction. More...

struct  MQeRulesGetMessage_out_st_
 output parameter structure for MQeRules_GetMessageFunction. More...

struct  MQeRulesPutMessage_in_st_
 input parameter structure for MQeRules_PutMessageFunction. More...

struct  MQeRulesPutMessage_out_st_
 output parameter structure for MQeRules_PutMessageFunction. More...

struct  MQeRulesTransmitQueue_in_st_
 input parameter structure for MQeRules_TransmitQueueFunction. More...

struct  MQeRulesTransmitQueue_out_st_
 output parameter structure for MQeRules_TransmitQueueFunction. More...

struct  MQeRulesTransmitQMgr_in_st_
 input parameter structure for MQeRules_TransmitQMgrFunction. More...

struct  MQeRulesTransmitQMgr_out_st_
 output parameter structure for MQeRules_TransmitQMgrFunction. More...

struct  MQeRulesUndoQMgr_in_st_
 input parameter structure for MQeRules_UndoQMgrFunction. More...

struct  MQeRulesUndoQMgr_out_st_
 output parameter structure for MQeRules_UndoQMgrFunction. More...

struct  MQeRulesActivateQueue_in_st_
 input parameter structure for MQeRules_ActivateQueueFunction. More...

struct  MQeRulesActivateQueue_out_st_
 output parameter structure for MQeRules_ActivateQueueFunction. More...

struct  MQeRulesBrowseMessage_in_st_
 input parameter structure for MQeRules_BrowseMessageFunction. More...

struct  MQeRulesBrowseMessage_out_st_
 output parameter structure for MQeRules_BrowseMessageFunction. More...

struct  MQeRulesCloseQueue_in_st_
 input parameter structure for MQeRules_CloseQueueFunction. More...

struct  MQeRulesCloseQueue_out_st_
 output parameter structure for MQeRules_CloseQueueFunction. More...

struct  MQeRulesDuplicateMessage_in_st_
 input parameter structure for MQeRules_DuplicateMessageFunction. More...

struct  MQeRulesDuplicateMessage_out_st_
 output parameter structure for MQeRules_DuplicateMessageFunction. More...

struct  MQeRulesGotMessage_in_st_
 input parameter structure for MQeRules_GotMessageFunction. More...

struct  MQeRulesGotMessage_out_st_
 output parameter structure for MQeRules_GotMessageFunction. More...

struct  MQeRulesBrowsedMessage_in_st_
 input parameter structure for MQeRules_BrowsedMessageFunction. More...

struct  MQeRulesBrowsedMessage_out_st_
 output parameter structure for MQeRules_BrowsedMessageFunction. More...

struct  MQeRulesMessageExpired_in_st_
 input parameter structure for MQeRules_MessageExpiredFunction. More...

struct  MQeRulesMessageExpired_out_st_
 output parameter structure for MQeRules_MessageExpiredFunction. More...

struct  MQeRulesTransmitMessage_in_st_
 input parameter structure for MQeRules_TransmitMessageFunction. More...

struct  MQeRulesTransmitMessage_out_st_
 output parameter structure for MQeRules_TransmitMessageFunction. More...

struct  MQeRulesUndoQueue_in_st_
 input parameter structure for MQeRules_UndoQueueFunction. More...

struct  MQeRulesUndoQueue_out_st_
 output parameter structure for MQeRules_UndoQueueFunction. More...

struct  MQeRulesFree_in_st_
 input parameter structure for MQeRules_FreeFunction. More...

struct  MQeRulesFree_out_st_
 output parameter structure for MQeRules_FreeFunction. More...

struct  MQeRulesNew_in_st_
 input parameter structure for MQeRules_NewFunction. More...

struct  MQeRulesNew_out_st_
 output parameter structure for MQeRules_NewFunction. More...


Typedefs

typedef MQEVOID(* MQeRules_ActivateQMgrFunction )(MQeRulesActivateQMgr_in_ *, MQeRulesActivateQMgr_out_ *)
 function pointer type signature for a rules plugin ActivateQMgr function implementation.

typedef MQEVOID(* MQeRules_CloseQMgrFunction )(MQeRulesCloseQMgr_in_ *, MQeRulesCloseQMgr_out_ *)
 function pointer type signature for a rules plugin CloseQMgr function implementation.

typedef MQERETURN(* MQeRules_DeleteMessageFunction )(MQeRulesDeleteMessage_in_ *, MQeRulesDeleteMessage_out_ *)
 function pointer type signature for a rules plugin DeleteMessage function implementation.

typedef MQERETURN(* MQeRules_GetMessageFunction )(MQeRulesGetMessage_in_ *, MQeRulesGetMessage_out_ *)
 function pointer type signature for a rules plugin GetMessage function implementation.

typedef MQERETURN(* MQeRules_PutMessageFunction )(MQeRulesPutMessage_in_ *, MQeRulesPutMessage_out_ *)
 function pointer type signature for a rules plugin PutMessage function implementation.

typedef MQERETURN(* MQeRules_TransmitQueueFunction )(MQeRulesTransmitQueue_in_ *, MQeRulesTransmitQueue_out_ *)
 function pointer type signature for a rules plugin TransmitQueue function implementation.

typedef MQERETURN(* MQeRules_TransmitQMgrFunction )(MQeRulesTransmitQMgr_in_ *, MQeRulesTransmitQMgr_out_ *)
 function pointer type signature for a rules plugin TransmitQMgr function implementation.

typedef MQEVOID(* MQeRules_UndoQMgrFunction )(MQeRulesUndoQMgr_in_ *, MQeRulesUndoQMgr_out_ *)
 function pointer type signature for a rules plugin UndoQMgr function implementation.

typedef MQEVOID(* MQeRules_ActivateQueueFunction )(MQeRulesActivateQueue_in_ *, MQeRulesActivateQueue_out_ *)
 function pointer type signature for a rules plugin ActivateQueue function implementation.

typedef MQERETURN(* MQeRules_BrowseMessageFunction )(MQeRulesBrowseMessage_in_ *, MQeRulesBrowseMessage_out_ *)
 function pointer type signature for a rules plugin BrowseMessage function implementation.

typedef MQEVOID(* MQeRules_CloseQueueFunction )(MQeRulesCloseQueue_in_ *, MQeRulesCloseQueue_out_ *)
 function pointer type signature for a rules plugin CloseQueue function implementation.

typedef MQEVOID(* MQeRules_DuplicateMessageFunction )(MQeRulesDuplicateMessage_in_ *, MQeRulesDuplicateMessage_out_ *)
 function pointer type signature for a rules plugin DuplicateMessage function implementation.

typedef MQERETURN(* MQeRules_GotMessageFunction )(MQeRulesGotMessage_in_ *, MQeRulesGotMessage_out_ *)
 function pointer type signature for a rules plugin GotMessage function implementation.

typedef MQERETURN(* MQeRules_BrowsedMessageFunction )(MQeRulesBrowsedMessage_in_ *, MQeRulesBrowsedMessage_out_ *)
 function pointer type signature for a rules plugin BrowsedMessage function implementation.

typedef MQEVOID(* MQeRules_MessageExpiredFunction )(MQeRulesMessageExpired_in_ *, MQeRulesMessageExpired_out_ *)
 function pointer type signature for a rules plugin MessageExpired function implementation.

typedef MQERETURN(* MQeRules_TransmitMessageFunction )(MQeRulesTransmitMessage_in_ *, MQeRulesTransmitMessage_out_ *)
 function pointer type signature for a rules plugin TransmitMessage function implementation.

typedef MQEVOID(* MQeRules_UndoQueueFunction )(MQeRulesUndoQueue_in_ *, MQeRulesUndoQueue_out_ *)
 function pointer type signature for a rules plugin UndoQueue function implementation.

typedef MQEVOID(* MQeRules_FreeFunction )(MQeRulesFree_in_ *, MQeRulesFree_out_ *)
 function pointer type signature for a rules plugin Free function implementation.

typedef MQERETURN(* MQeRules_NewFunction )(MQeRulesNew_in_ *, MQeRulesNew_out_ *)
 function pointer type signature for a rules plugin New function implementation.


Typedef Documentation

typedef MQEVOID( * MQeRules_ActivateQMgrFunction)( MQeRulesActivateQMgr_in_ * , MQeRulesActivateQMgr_out_ * )
 

function pointer type signature for a rules plugin ActivateQMgr function implementation.

Points to a rule called when the queue manager is activated. The rule implementation must be mapped to fPtrActivateQMgr in the user's rules initialisation function - see MQeRules_NewFunction. It cannot prevent the queue manager being activated - it is for notification purposes only. There is no default behaviour if this rule is not implemented.

Return values:
None 
Example:
      void timeToTrigger();
           
      struct exampleRules_st_ {       // rules instance structure
        MQeAdministratorHndl hAdmin;  // administrator handle to carry around between rules functions
        FILE * ifp;                   // file handle for logging rules 
        MQEBOOL carryOn;              // used for trigger transmission thread 
        MQEINT32 triggerInterval;     // used for trigger transmission thread
        HANDLE hThread;               // handle for the trigger transmission thread 
     };
     
     typedef struct exampleRules_st_ exampleRules_;

      
      ..

     DLLEXPORT MQERETURN MQEPUBLISHED exampleRules_activateQueueManager( MQeRulesActivateQMgr_in_ * pInput
                                  , MQeRulesActivateQMgr_out_ * pOutput) {
           // retrieve exception block - passed from application
           MQeExceptBlock * pExceptBlock = (MQeExceptBlock *)(pOutput->pExceptBlock);
           
           // retrieve private data structure passed between user's rules invocations
           exampleRules_ * pRulesInstance = (exampleRules_ *)(pInput->pPrivateData);
           
           MQeQueueManagerHndl hQueueManager;
           MQERETURN rc = MQERETURN_OK;
               
           rc = mqeQueueManager_getCurrentQueueManager(pExceptBlock, &hQueueManager);
           if(MQERETURN_OK == rc) {     
             DWORD tid;

             //set up the private data administrator handle using the retrieved application queue manager handle
             rc = mqeAdministrator_new(pExceptBlock,&pRulesInstance->hAdmin,hQueueManager);

             // Launch thread to govern calls to trigger transmission
#if MQE_PLATFORM == PLATFORM_WIN32_MVC
             pRulesInstance->hThread = (HANDLE) _beginthreadex(NULL,
                                         0,
                                         timeToTrigger,
                                         (MQEVOID *)pRulesInstance,
                                         0,
                                         &tid);
            if(pRulesInstance->hThread == 0) {
              // thread creation failed
              SET_EXCEPT_BLOCK(pExceptBlock, MQERETURN_RULES_ERROR, MQEREASON_NA);
            }
#else
            pRulesInstance->hThread = (HANDLE) CreateThread(NULL,
                                            0,
                                            timeToTrigger,
                                            (MQEVOID *)pRulesInstance,
                                            0,
                                            &tid);
            if(pRulesInstance->hThread == NULL) {
              // thread creation failed
              SET_EXCEPT_BLOCK(pExceptBlock, MQERETURN_RULES_ERROR, MQEREASON_NA);
            }
#endif      
          }  
        
      }
      
      MQEVOID MQEPUBLISHED timeToTrigger(MQEINT32 interval) {

          MQERETURN rc = MQE_RETURN_OK;
          MQEINT32 lastType, lastState;
          MQeExceptBlock exceptBlock;
          SET_EXCEPT_BLOCK_TO_DEFAULT(&exceptBlock);
          ...

          // retrieve the current queue manager 
          rc = mqeQueueManager_getCurrentQueueManager(&exceptBlock, &hQueueManager);
          if(MQERETURN_OK == rc) {
              while(MQERETURN_OK == EC(&exceptBlock) && pRulesInstance->carryOn == MQE_TRUE) { 
                // now attempt to trigger transmission 
                rc = mqeQueueManager_triggerTransmission(hQueueManager, &exceptBlock);

                // wait for the duration of the trigger interval 
                Sleep(pRulesInstance->triggerInterval);
              }     
          }
      }

typedef MQEVOID( * MQeRules_CloseQMgrFunction)( MQeRulesCloseQMgr_in_ * , MQeRulesCloseQMgr_out_ * )
 

function pointer type signature for a rules plugin CloseQMgr function implementation.

Points to a rule called when the queue manager is closing. The rule cannot be used to prevent the closure of the queue manager. Thus there is no default behaviour imposed if the rule is not implemented. The rule implementation must be mapped to fPtrCloseQMgr in the user's rules initialisation function.

Return values:
None 
Example:

See example for MQeRules_ActivateQMgrFunction

     DLLEXPORT MQEVOID MQEPUBLISHED exampleRules_CloseQMgr( MQeRulesCloseQMgr_in_ * pInput
                                                , MQeRulesCloseQMgr_out_ * pOutput)     {
    
        MQERETURN rc = MQERETURN_OK;
        MQeQueueManagerHndl hQueueManager;
        exampleRules_ * pRulesInstance = (exampleRules_ *)pInput->pPrivateData;
        DWORD result;
        MQeExceptBlock exceptBlock = *((MQeExceptBlock *)pOutput->pExceptBlock);


        SET_EXCEPT_BLOCK_TO_DEFAULT(&exceptBlock);
        // Effect the ending of the thread by setting the MQEBOOL continue to MQE_FALSE 
        // This leads to a return from timeToTrigger() and hence the implicit call to _endthreadex
        pRulesInstance->carryOn = MQE_FALSE;

        // wait for the thread in any case 
        result = WaitForSingleObject(pRulesInstance->hThread, INFINITE);
        ...
        // retrieve the current queue manager 
        rc = mqeQueueManager_getCurrentQueueManager(&exceptBlock, &hQueueManager);
        if(MQERETURN_OK == rc) {
            // attempt to trigger transmission one last time to clean up queue 
            rc = mqeQueueManager_triggerTransmission(hQueueManager, &exceptBlock);
        }    
    }     

typedef MQERETURN( * MQeRules_DeleteMessageFunction)( MQeRulesDeleteMessage_in_ * , MQeRulesDeleteMessage_out_ * )
 

function pointer type signature for a rules plugin DeleteMessage function implementation.

Points to a rule called when a request is made to delete a message. The rule can prevent deletion by a return code of MQERETURN_RULES_DISALLOWED_BY_RULE.

The default behaviour is to allow the operation if the rule is not implemented. The rule implementation must be mapped to fPtrDeleteMessage in the user's rules initialisation function.

Return values:
MQERETURN_OK, MQEREASON_NA:  allow the operation
MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA:  do not allow the operation
Example:
        MQEBOOL isEqual = MQE_FALSE;
        
        rc = mqeString_newUtf8(pExceptBlock, &hCompareString, "TopSecretQueue");
        if(MQERETURN_OK == rc) {
            rc = mqeString_equalTo(pInput->hQueueName, pExceptBlock, &isEqual, hCompareString);
            if(MQERETURN_OK == rc && isEqual == MQE_TRUE) {
                // don't allow a message to be deleted from queue named "TopSecretQueue"
                SET_EXCEPT_BLOCK(pExceptBlock,MQERETURN_RULES_DISALLOWED_BY_RULE,MQEREASON_NA);
            }    
        }          

typedef MQERETURN( * MQeRules_GetMessageFunction)( MQeRulesGetMessage_in_ * , MQeRulesGetMessage_out_ * )
 

function pointer type signature for a rules plugin GetMessage function implementation.

Points to a rule called when a request is made to get a message from a queue. The rule can prevent a message being got with a return code of MQERETURN_RULES_DISALLOWED_BY_RULE.

The default behaviour if the rule is not implemented is to allow the operation.

The rule implementation must be mapped to fPtrGetMessage in the user's rules initialisation function.

Return values:
MQERETURN_OK, MQEREASON_NA:  allow the operation
MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA:  do not allow the operation
Example:
           // if the destination queue manager is the local queue manager
           rc = mqeQueueManager_getName( hQueueManager,  pExceptBlock, &hQueueManagerName);
           if(MQERETURN_OK == rc) { 
                rc = mqeString_equalTo(pInput->hQueue_QueueManagerName,pExceptBlock,&isEqual,hQueueManagerName);
                if(MQERETURN_OK == rc && isEqual) {
                    // if the destination queue name is "OutboundQueue"
                    rc = mqeString_newUtf8(pExceptBlock, &hCompareString, "OutboundQueue");
                    rc = mqeString_equalTo(pInput->hQueueName,pExceptBlock,&isEqual,hCompareString);
                    if(MQERETURN_OK == rc && isEqual) {
                        // password required for this queue
                        MQEBOOL contains = MQE_FALSE;
                        rc = mqeString_newUtf8(pExceptBlock,&hFieldName, "password");
                        rc = mqeFields_contains(hFilter, pExceptBlock, &contains, hFieldName);
                        if(MQERETURN_OK == rc && contains == MQE_FALSE) {
                            SET_EXCEPT_BLOCK(pExceptBlock,MQERETURN_RULES_DISALLOWED_BY_RULE,MQEREASON_NA);
                        }
                        else {
                            // parse password, etc.
                        }    
                     }
                }
               
           }

typedef MQERETURN( * MQeRules_PutMessageFunction)( MQeRulesPutMessage_in_ * , MQeRulesPutMessage_out_ * )
 

function pointer type signature for a rules plugin PutMessage function implementation.

Points to a rule called when a request is made to put a message onto a queue. The rule can refuse the request via a return code of MQERETURN_RULES_DISALLOWED_BY_RULE.

The default behaviour is to allow the operation if the rule is not implemented.

The rule implementation must be mapped to fPtrPutMessage in the user's rules initialisation function.

Return values:
MQERETURN_OK, MQEREASON_NA:  allow the operation
MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA:  do not allow the operation
Example:
        // Only allow msgs containing an ID field to be placed on the Queue 
        MQEBOOL contains = MQE_FALSE;
        rc = mqeFields_contains(pInput->hMsg, pExceptBlock, &contains, MQE_MSG_MSGID);
        if(MQERETURN_OK == rc && !contains) {
            SET_EXCEPT_BLOCK(pExceptBlock,MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA);
        }

typedef MQERETURN( * MQeRules_TransmitQueueFunction)( MQeRulesTransmitQueue_in_ * , MQeRulesTransmitQueue_out_ * )
 

function pointer type signature for a rules plugin TransmitQueue function implementation.

Points to a rule called whenever a queue manager attempts to send all of its pending messages - the rule is called for each queue containing messages awaiting transmission. The rule decides whether to allow transmission of those messages for the supplied queue.

The default behaviour if this rule is not implemented is to allow the operation.

The rule implementation must be mapped to fPtrTransmitQueue in the user's rules initialisation function.

Return values:
MQERETURN_OK, MQEREASON_NA:  allow the operation
MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA:  do not allow the operation
Example:
        if (!timeToTransmit())   {       // if not OK to transmit
            SET_EXCEPT_BLOCK(pExceptBlock,MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA);
        }
where timeToTransmit() is a user-written function returning an MQEBOOL to determine whether we are in a cheap-rate transmission period or not.

typedef MQERETURN( * MQeRules_TransmitQMgrFunction)( MQeRulesTransmitQMgr_in_ * , MQeRulesTransmitQMgr_out_ * )
 

function pointer type signature for a rules plugin TransmitQMgr function implementation.

Points to a rule which can allow or prevent the triggering of communications (where communications includes both the transmission of pending messages from remote asynchronous queue definitions and the stimulation of the Home Server Queue into polling its Store-and-Forward Queue). The rule is called from the queue manager's triggerTransmission function.

The default behaviour if this rule is not implemented is to allow the operation.

The rule implementation must be mapped to fPtrTransmitQMgr in the user's rules initialisation function.

Return values:
MQERETURN_OK, MQEREASON_NA:  allow the operation
MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA:  do not allow the operation
Example:
        // allow transmission to be triggered only if the number of pending messages is 10 or more 
        if(pInput->msgsPendingTransmission < 10) {
            SET_EXCEPT_BLOCK(pExceptBlock,MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA);
        }

typedef MQEVOID( * MQeRules_UndoQMgrFunction)( MQeRulesUndoQMgr_in_ * , MQeRulesUndoQMgr_out_ * )
 

function pointer type signature for a rules plugin UndoQMgr function implementation.

Points to a rule called when an undo operation is performed. This rule is for notification purposes only and has no affect on subsequent behaviour

The rule implementation must be mapped to fPtrUndoQMgr in the user's rules initialisation function.

Return values:
None 
Example:
        //log the operation    
        MQECHAR * qMgrName;
        MQEINT32 size;
        rc = mqeString_getUtf8( (pInput->hQueue_QueueManagerName, pExceptBlock, NULL, &size);
        if(MQERETURN_OK == rc) {
            rc = mqeString_getUtf8(pInput->hQueue_QueueManagerName, pExceptBlock, qMgrName, &size);
            if(MQERETURN_OK == rc && pRulesInstance->ifp) {           
                fprintf(pRulesInstance->ifp, "Undo operation on queue manager %s\n", qMgrName);
            }
        }    

typedef MQEVOID( * MQeRules_ActivateQueueFunction)( MQeRulesActivateQueue_in_ * , MQeRulesActivateQueue_out_ * )
 

function pointer type signature for a rules plugin ActivateQueue function implementation.

Points to a rule called when a queue is activated. The rule cannot prevent the activation of the queue so there is no default behaviour if the rule is not implemented.

The rule implementation must be mapped to fPtrActivateQueue in the user's rules initialisation function.

Return values:
None 
Example:
      MQECHAR * qName;
      MQEINT32 size; 
       ...
       
      rc =  mqeString_getUtf8(pInput->hQueueName, pExceptBlock, NULL, &size);
      if(MQERETURN_OK == rc) {
           mqeString_getUtf8(pInput->hQueueName, pExceptBlock, qName, &size);
           if(MQERETURN_OK == rc) {
              fprintf(pRulesInstance->ifp, "Activating queue %s \n", qName);  
           }
      }

typedef MQERETURN( * MQeRules_BrowseMessageFunction)( MQeRulesBrowseMessage_in_ * , MQeRulesBrowseMessage_out_ * )
 

function pointer type signature for a rules plugin BrowseMessage function implementation.

Points to a rule called when a filter is being applied during a browseMessage() operation. The rule can allow or reject the operation via the return code.

The default behaviour if the rule is not implemented is to allow the operation.

The rule implementation must be mapped to fPtrBrowseMessage in the user's rules initialisation function.

Return values:
MQERETURN_OK, MQEREASON_NA:  allow the operation
MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA:  do not allow the operation
Example :
        MQeStringHndl hFieldName, hFieldValue, hCompare;
        MQEBOOL contains = MQE_FALSE;
        
        ...
        
        // filter based on the value of a particular message field
        rc = mqeString_newUtf8(pExceptBlock, hFieldName, "MsgType");
        rc = mqeFields_contains(hFilter, pExceptBlock, &contains, hFieldName);
        
        if(MQERETURN_OK == rc && contains) { 
            mqeFields_getAscii(hFilter,pExceptBlock,&hFieldValue,hFieldName);
            if(MQERETURN_OK == rc) {
                MQEBOOL isEqual = MQE_FALSE;
                mqeString_newUtf8(pExceptBlock,hCompare,"OrderResponse"); 
                rc = mqeString_equalTo(hCompare,pExceptBlock,&isEqual,hFieldValue);
                    if(MQERETURN_OK == rc && !isEqual) {
                        // only allow the action if the MsgType is OrderResponse
                        SET_EXCEPT_BLOCK(pExceptBlock,MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA);
                    }
                }
            }
            else {
                ...

typedef MQEVOID( * MQeRules_CloseQueueFunction)( MQeRulesCloseQueue_in_ * , MQeRulesCloseQueue_out_ * )
 

function pointer type signature for a rules plugin CloseQueue function implementation.

Points to a rule called when a queue is closed. The rule cannot prevent the closure of the queue so there is no default behaviour for when the rule is not implemented.

The rule implementation must be mapped to fPtrCloseQueue in the user's rules initialisation function.

Return values:
None 
Example:
      MQECHAR * qName;
      MQEINT32 size; 
       ...
       
      rc =  mqeString_getUtf8(pInput->hQueueName, pExceptBlock, NULL, &size);
      if(MQERETURN_OK == rc) {
           mqeString_getUtf8(pInput->hQueueName, pExceptBlock, qName, &size);
           if(MQERETURN_OK == rc) {
              fprintf(pRulesInstance->ifp, "Closing queue %s \n", qName);  
           }
      }

typedef MQEVOID( * MQeRules_DuplicateMessageFunction)( MQeRulesDuplicateMessage_in_ * , MQeRulesDuplicateMessage_out_ * )
 

function pointer type signature for a rules plugin DuplicateMessage function implementation.

Points to a rule called when a duplicate message is put on a queue. The return code is not used to determine subsequent action and there is no default behaviour for when the rule is not implemented.

The rule implementation must be mapped to fPtrDuplicateMessage in the user's rules initialisation function.

Return values:
None 
Example:
        MqeStringHndl hQueueManagerName;
        MQEINT64 msgTimestamp;
        
        // get message UID fields
        rc = mqeFieldsHelper_getMsgOriginQMgr(hMsg, pExceptBlock, &hQueueManagerName);
        if(MQERETURN_OK == rc) { 
            rc = mqeFieldsHelper_getMsgTimeStamp((hMsg,pExceptBlock,&msgTimestamp);
            if(MQERETURN_OK == rc) { 
                MQEINT32 size;
                MQECHAR * queueMgrName;
                rc = mqeString_getUtf8(hQueueManagerName,pExceptBlock,NULL,&size);
                rc = mqeString_getUtf8(hQueueManagerName,pExceptBlock,queueMgrName,&size);
                if(MQERETURN_OK = rc) {
                
                    //log the duplicate message event
                    fprintf(pRulesInstance->ifp, "Duplicate message with uuid fields %s and %d\n", queueMgrName, msgTimestamp);
                }    
            }
        }    
        ...

typedef MQERETURN( * MQeRules_GotMessageFunction)( MQeRulesGotMessage_in_ * , MQeRulesGotMessage_out_ * )
 

function pointer type signature for a rules plugin GotMessage function implementation.

Points to a rule called when a message has been retrieved from a queue which matches a filter specified in a getMessage operation. The rule can determine whether the message satisfies the getMessage request or not. The default behaviour is to allow the request to be satisfied - this can be altered by a return code of MQERETURN_RULES_DISALLOWED_BY_RULE.

The rule implementation must be mapped to fPtrGotMessage in the user's rules initialisation function.

Return values:
MQERETURN_OK, MQEREASON_NA:  allow the message to match the request
MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_RULES_END_SEARCH:  assert that the message cannot satisfy the request and that the search for a matching message is not to continue
MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_RULES_CONTINUE_SEARCH:  assert that the message cannot satisfy the request but that the search for a matching message can continue
Example:
    // does the message contain a field which states what operations are 
    // allowed upon it?
     
    rc = mqeString_newUtf8(pExceptBlock, hFieldName, "AllowableOperations");
        rc = mqeFields_contains(hFilter, pExceptBlock, &contains, hFieldName);
        
        if(MQERETURN_OK == rc && contains) { 
            mqeFields_getAscii(hFilter,pExceptBlock,&hFieldValue,hFieldName);
            if(MQERETURN_OK == rc) {
                MQEBOOL isEqual = MQE_FALSE;
                mqeString_newUtf8(pExceptBlock,hCompare,"BrowseOnly"); 
                rc = mqeString_equalTo(hCompare,pExceptBlock,&isEqual,hFieldValue);
                    if(MQERETURN_OK == rc && isEqual) {
                        // if the message states that it is browse only, disallow the operation
                        SET_EXCEPT_BLOCK(pExceptBlock,MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA);
                    }
                }
            }
            else {
                ...

typedef MQERETURN( * MQeRules_BrowsedMessageFunction)( MQeRulesBrowsedMessage_in_ * , MQeRulesBrowsedMessage_out_ * )
 

function pointer type signature for a rules plugin BrowsedMessage function implementation.

Points to a rule called when a message has been retrieved from a queue which matches a filter specified in a browseMessage operation. The rule can determine whether the message satisfies the browseMessage request or not. The default behaviour is to allow the request to be satisfied - this can be altered by a return code of MQERETURN_RULES_DISALLOWED_BY_RULE.

The rule implementation must be mapped to fPtrBrowsedMessage in the user's rules initialisation function.

Return values:
MQERETURN_OK, MQEREASON_NA:  allow the message to match the request
MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_RULES_END_SEARCH:  assert that the message cannot satisfy the request and that the search for a matching message is not to continue
MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_RULES_CONTINUE_SEARCH:  assert that the message cannot satisfy the request but that the search for a matching message can continue
Note:
This rule is only invoked when the mqeQueueManager_browseMessages() input parameter, MQEBOOL justUID is set to MQE_FALSE
Example:

typedef MQEVOID( * MQeRules_MessageExpiredFunction)( MQeRulesMessageExpired_in_ * , MQeRulesMessageExpired_out_ * )
 

function pointer type signature for a rules plugin MessageExpired function implementation.

Points to a rule called when a message has exceeded either the queue's or its own expiry interval.

The rule is for notification purposes only and cannot affect subsequent behaviour. The rule implementation must be mapped to fPtrMessageExpired in the user's rules initialisation function.

Return values:
None 
Example:
        MQEBOOL contains = MQE_FALSE;
        MQeFieldsHndl hMsg;
        
        // Place a copy of the message on the dead letter queue 
        // Set re-send flag so that attempt to put message to new queue isn't rejected 
        // First, clone the message as the input parameter is read-only 
        rc = mqeFields_clone(pInput->hMsg, pExceptBlock, &hMsg);
        if(MQERETURN_OK == rc) {
            rc = mqeFields_putBoolean(pInput->hMsg, pExceptBlock, MQE_MSG_RESEND, MQE_TRUE);
            if(MQERETURN_OK == rc) {
                // if the message contains an expiry interval field - remove it 
                rc = mqeFields_contains(pInput->hMsg, pExceptBlock, &contains, MQE_MSG_EXPIRETIME);
                if(MQERETURN_OK == rc && contains) {
                    rc = mqeFields_delete(pInput->hMsg, pExceptBlock, MQE_MSG_EXPIRETIME);
                }
                if(MQERETURN_OK == rc) {
                    // put message onto dead letter queue 
                    MQeStringHndl hQueueManagerName;
                    rc = mqeQueueManager_getName( hQueueManager,  pExceptBlock, &hQueueManagerName);
                    if(MQERETURN_OK == rc) {
                        // use a temporary exception block as don't care if dead letter queue does not exist
                        MQeExceptBlock tempExceptBlock;
                        SET_EXCEPT_BLOCK_TO_DEFAULT(&tempExceptBlock);
                        rc = mqeQueueManager_putMessage( hQueueManager, &tempExceptBlock, hQueueManagerName, MQE_DEADLETTER_QUEUE_NAME, pInput->hMsg, NULL, 0);
                        (MQEVOID)mqeString_free(hQueueManagerName,&tempExceptBlock);
                    }
                }
            }
        }

typedef MQERETURN( * MQeRules_TransmitMessageFunction)( MQeRulesTransmitMessage_in_ * , MQeRulesTransmitMessage_out_ * )
 

function pointer type signature for a rules plugin TransmitMessage function implementation.

Points to a rule called prior to the transmission of an individual message from a remote asynchronous queue . The rule decides whether to allow the message to be transmitted - the default behaviour is to allow transmission.

The rule implementation must be mapped to fPtrTransmitMessage in the user's rules initialisation function.

Return values:
MQERETURN_OK, MQEREASON_NA:  allow the operation
MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA:  do not allow the operation
Example:
        MQEBOOL contains;
        MQEINT32 priority;
        
        // only allow transmission if the message has a priority of greater than 4
        rc = mqeFields_contains(pInput->hMsg, pExceptBlock, contains, MQE_MSG_PRIORITY);
        if(MQERETURN_OK == rc && contains == MQE_TRUE) { 
            rc = mqeFields_getInt32(hMsg, pExceptBlock, &priority, MQE_MSG_PRIORITY);
            if(MQERETURN_OK == rc && priority < 5) {
                SET_EXCEPT_BLOCK(pExceptBlock,MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA);
            }    
        }

typedef MQEVOID( * MQeRules_UndoQueueFunction)( MQeRulesUndoQueue_in_ * , MQeRulesUndoQueue_out_ * )
 

function pointer type signature for a rules plugin UndoQueue function implementation.

Points to a rule called when an undo operation is performed. The rule is invoked for each candidate message for the operation. The rule is for notification purposes only and has no affect upon subsequent behaviour

The default behaviour if the rule is not implemented is to allow the operation.

The rule implementation must be mapped to fPtrUndoQueue in the user's rules initialisation function.

Return values:
None 
Example:
        // Log the match data uid fields

typedef MQEVOID( * MQeRules_FreeFunction)( MQeRulesFree_in_ * , MQeRulesFree_out_ * )
 

function pointer type signature for a rules plugin Free function implementation.

Points to a rule called when rules resources are being freed. This occurs when a queue manager is being freed as rules resources are tied to the lifecycle of a single queue manager. The rule may be used for clean-up of user-defined rules resources. There is no default behaviour if the rule is not implemented.

The rule implementation must be mapped to fPtrFree in the user's rules initialisation function.

Return values:
None 
Note:
It is the user's responsibility to clean up any resources allocated in the user's rules structure.
Example:
         exampleRules_ * pRulesInstance = pInput->pPrivateData;
         if(pRulesInstance->ifp != NULL) {
             fclose(pRulesInstance->ifp);
         }

MQeRules_NewFunction
 

function pointer type signature for a rules plugin New function implementation.

Sets up the information required for a user's rules implementation. It is the user's responsibility within this function to allocate memory for the rules instance structure and also to map rules functions to the user's implementation of those functions.

It is not necessary to provide an implementation of each one of these functions. The default behaviour when an implementation is not provided is described under each function pointer typedef in this document. However, the initialization function itself must be implemented and its name mapped, together with the module name, to a class alias.

The user must register the rules instance in his/her application by providing an alias which maps to two MQeStringHndls: the name of the plugin module and the name of the initialisation function. To do this, use the mqeClassAlias_add api. This alias is then used to register the rules instance. The registration of the rule must be done before the queue manager is created at the beginning of the application, e.g.:

     MQeQueueManagerParms      qmParams;
     
     mqeString_newUtf8(pExceptBlk, &rulesIndex, "exampleRules");     // alias for the module / entry point
     mqeString_newUtf8(pExceptBlk, &moduleName, "exampleRules.dll"); // module
     mqeString_newUtf8(pExceptBlk, &entryPoint, "exampleRules_new"); // entry point
     mqeClassAlias_add(pExceptBlk, rulesIndex, moduleName, entryPoint);
     
     ...
     
     
     qmParams.hQueueStore        = msgStore;     // String parameters for the location of the msg store 
     qmParams.hQueueManagerRules = rulesIndex;  //  Alias for rules module / entry point
     
     //  Indicate what parts of the structure have been set 
     qmParams.opFlags = QMGR_Q_STORE_OP | QMGR_RULES_OP;  
    
    ...
Return values:
MQERETURN_OK, MQEREASON_NA:  operation successful
MQERETURN_RULES_ERROR, MQEREASON_MODULE_ERROR:  problem in loading the module or in allocating resources - operation failed
Example:
    MQERETURN MQEPUBLISHED exampleRules_new( MQeRulesNew_in_ * pInput
                                   , MQeRulesNew_out_ * pOutput) {
                                              
        exampleRules_ * pRulesInstance;  // where exampleRules_ is a user_defined structure holding private data

        MQeExceptBlock * pExceptBlock;
        pExceptBlock = (MQeExceptBlock *) pOutput->pExceptBlock;
        SET_EXCEPT_BLOCK_TO_DEFAULT(pExceptBlock) ;


        // allocate the memory for the private data structure
        // this holds user's private data which can be accessed in all rules 
        pRulesInstance = malloc(sizeof(exampleRules_)); 
 
 
        if (pRulesInstance != NULL) {
            // set up function table and rules instance in output structure 
            // map user rule function implementations to output structure function pointers
        
            pOutput->fPtrActivateQMgr     = exampleRules_ActivateQMgr; 
            pOutput->fPtrCloseQMgr        = exampleRules_QueueManagerClose;              
            pOutput->fPtrDeleteMessage    = exampleRules_DeleteMessage;
            pOutput->fPtrGetMessage       = exampleRules_GetMessage;
            pOutput->fPtrPutMessage       = exampleRules_PutMessage; 
            pOutput->fPtrActivateQueue    = exampleRules_ActivateQueue;
            pOutput->fPtrCloseQueue       = exampleRules_CloseQueue;
            pOutput->fPtrBrowseMessage    = exampleRules_BrowseMessage;
            pOutput->fPtrFree             = exampleRules_free;
            
            pRulesInstance->carryOn = MQE_TRUE;
            pRulesInstance->triggerInterval = 6000;
            pRulesInstance->hAdmin = NULL;
            pRulesInstance->hThread = NULL;
            pRulesInstance->ifp = fopen("traceFile.txt","w");
            pOutput->pPrivateData = (MQEVOID *)pRulesInstance;
        }
        else {
            // We had a problem so clear and report error
            SET_EXCEPT_BLOCK(...
        }

        return EC(pExceptBlock);
    
    }


Generated Thu Aug 11 23:27:12 2005 for Websphere MQ Everyplace for Multiplatforms C Programming Reference