src/clipsrules/core/watch.c Source File

00001    /*******************************************************/
00002    /*      "C" Language Integrated Production System      */
00003    /*                                                     */
00004    /*             CLIPS Version 6.24  06/05/06            */
00005    /*                                                     */
00006    /*                    WATCH MODULE                     */
00007    /*******************************************************/
00008 
00009 
00010 /*************************************************************/
00011 /* Purpose: Support functions for the watch and unwatch      */
00012 /*   commands.                                               */
00013 /*                                                           */
00014 /* Principal Programmer(s):                                  */
00015 /*      Gary D. Riley                                        */
00016 /*                                                           */
00017 /* Contributing Programmer(s):                               */
00018 /*      Brian Dantes                                         */
00019 /*                                                           */
00020 /* Revision History:                                         */
00021 /*      6.23: Changed name of variable log to logName        */
00022 /*            because of Unix compiler warnings of shadowed  */
00023 /*            definitions.                                   */
00024 /*                                                           */
00025 /*      6.24: Renamed BOOLEAN macro type to intBool.         */
00026 /*                                                           */
00027 /*            Added EnvSetWatchItem function.                */
00028 /*                                                           */
00029 /*************************************************************/
00030 
00031 #define _WATCH_SOURCE_
00032 
00033 #include "setup.h"
00034 
00035 #if DEBUGGING_FUNCTIONS
00036 
00037 #include <stdio.h>
00038 #define _STDIO_INCLUDED_
00039 #include <string.h>
00040 
00041 #include "constant.h"
00042 #include "envrnmnt.h"
00043 #include "memalloc.h"
00044 #include "router.h"
00045 #include "argacces.h"
00046 #include "extnfunc.h"
00047 #include "watch.h"
00048 
00049 /***************************************/
00050 /* LOCAL INTERNAL FUNCTION DEFINITIONS */
00051 /***************************************/
00052 
00053    static struct watchItem       *ValidWatchItem(void *,char *,int *);
00054    static intBool                 RecognizeWatchRouters(void *,char *);
00055    static int                     CaptureWatchPrints(void *,char *,char *);
00056    static void                    DeallocateWatchData(void *);
00057 
00058 /**********************************************/
00059 /* InitializeWatchData: Allocates environment */
00060 /*    data for watch items.                   */
00061 /**********************************************/
00062 globle void InitializeWatchData(
00063   void *theEnv)
00064   {
00065    AllocateEnvironmentData(theEnv,WATCH_DATA,sizeof(struct watchData),DeallocateWatchData);
00066   }
00067   
00068 /************************************************/
00069 /* DeallocateWatchData: Deallocates environment */
00070 /*    data for watch items.                     */
00071 /************************************************/
00072 static void DeallocateWatchData(
00073   void *theEnv)
00074   {
00075    struct watchItem *tmpPtr, *nextPtr;
00076 
00077    tmpPtr = WatchData(theEnv)->ListOfWatchItems;
00078    while (tmpPtr != NULL)
00079      {
00080       nextPtr = tmpPtr->next;
00081       rtn_struct(theEnv,watchItem,tmpPtr);
00082       tmpPtr = nextPtr;
00083      }
00084   }
00085 
00086 /*************************************************************/
00087 /* AddWatchItem: Adds an item to the list of watchable items */
00088 /*   that can be set using the watch and unwatch commands.   */
00089 /*   Returns FALSE if the item is already in the list,       */
00090 /*   otherwise returns TRUE.                                 */
00091 /*************************************************************/
00092 globle intBool AddWatchItem(
00093   void *theEnv,
00094   char *name,
00095   int code,
00096   unsigned *flag,
00097   int priority,
00098   unsigned (*accessFunc)(void *,int,unsigned,struct expr *),
00099   unsigned (*printFunc)(void *,char *,int,struct expr *))
00100   {
00101    struct watchItem *newPtr, *currentPtr, *lastPtr;
00102 
00103    /*================================================================*/
00104    /* Find the insertion point in the watchable items list to place  */
00105    /* the new item. If the item is already in the list return FALSE. */
00106    /*================================================================*/
00107 
00108    for (currentPtr = WatchData(theEnv)->ListOfWatchItems, lastPtr = NULL;
00109         currentPtr != NULL;
00110         currentPtr = currentPtr->next)
00111      {
00112       if (strcmp(currentPtr->name,name) == 0) return(FALSE);
00113       if (priority < currentPtr->priority) lastPtr = currentPtr;
00114      }
00115 
00116    /*============================*/
00117    /* Create the new watch item. */
00118    /*============================*/
00119 
00120    newPtr = get_struct(theEnv,watchItem);
00121    newPtr->name = name;
00122    newPtr->flag = flag;
00123    newPtr->code = code;
00124    newPtr->priority = priority;
00125    newPtr->accessFunc = accessFunc;
00126    newPtr->printFunc = printFunc;
00127 
00128    /*=================================================*/
00129    /* Insert the new item in the list of watch items. */
00130    /*=================================================*/
00131 
00132    if (lastPtr == NULL)
00133      {
00134       newPtr->next = WatchData(theEnv)->ListOfWatchItems;
00135       WatchData(theEnv)->ListOfWatchItems = newPtr;
00136      }
00137    else
00138      {
00139       newPtr->next = lastPtr->next;
00140       lastPtr->next = newPtr;
00141      }
00142 
00143    /*==================================================*/
00144    /* Return TRUE to indicate the item has been added. */
00145    /*==================================================*/
00146 
00147    return(TRUE);
00148   }
00149 
00150 /*****************************************************/
00151 /* EnvWatch: C access routine for the watch command. */
00152 /*****************************************************/
00153 globle intBool EnvWatch(
00154   void *theEnv,
00155   char *itemName)
00156   {
00157    return(EnvSetWatchItem(theEnv,itemName,ON,NULL));
00158   }
00159 
00160 /**************************************************/
00161 /* Watch: C access routine for the watch command. */
00162 /**************************************************/
00163 #if ALLOW_ENVIRONMENT_GLOBALS
00164 globle intBool Watch(
00165   char *itemName)
00166   {
00167    return(EnvWatch(GetCurrentEnvironment(),itemName));
00168   }
00169 #endif
00170 
00171 /*********************************************************/
00172 /* EnvUnwatch: C access routine for the unwatch command. */
00173 /*********************************************************/
00174 globle intBool EnvUnwatch(
00175   void *theEnv,
00176   char *itemName)
00177   {
00178    return(EnvSetWatchItem(theEnv,itemName,OFF,NULL));
00179   }
00180 
00181 /******************************************************/
00182 /* Unwatch: C access routine for the unwatch command. */
00183 /******************************************************/
00184 #if ALLOW_ENVIRONMENT_GLOBALS
00185 globle intBool Unwatch(
00186   char *itemName)
00187   {
00188    return(EnvUnwatch(GetCurrentEnvironment(),itemName));
00189   }
00190 #endif
00191 
00192 /***********************************************************************/
00193 /* EnvSetWatchItem: Sets the state of a specified watch item to either */
00194 /*   on or off. Returns TRUE if the item was set, otherwise FALSE.     */
00195 /***********************************************************************/
00196 globle int EnvSetWatchItem(
00197   void *theEnv,
00198   char *itemName,
00199   unsigned newState,
00200   struct expr *argExprs)
00201   {
00202    struct watchItem *wPtr;
00203 
00204    /*======================================================*/
00205    /* If the new state isn't on or off, then return FALSE. */
00206    /*======================================================*/
00207 
00208    if ((newState != ON) && (newState != OFF)) return(FALSE);
00209 
00210    /*===================================================*/
00211    /* If the name of the watch item to set is all, then */
00212    /* all watch items are set to the new state and TRUE */
00213    /* is returned.                                      */
00214    /*===================================================*/
00215 
00216    if (strcmp(itemName,"all") == 0)
00217      {
00218       for (wPtr = WatchData(theEnv)->ListOfWatchItems; wPtr != NULL; wPtr = wPtr->next)
00219         {
00220          /*==============================================*/
00221          /* If no specific arguments are specified, then */
00222          /* set the global flag for the watch item.      */
00223          /*==============================================*/
00224 
00225          if (argExprs == NULL) *(wPtr->flag) = newState;
00226 
00227          /*=======================================*/
00228          /* Set flags for individual watch items. */
00229          /*=======================================*/
00230 
00231          if ((wPtr->accessFunc == NULL) ? FALSE :
00232              ((*wPtr->accessFunc)(theEnv,wPtr->code,newState,argExprs) == FALSE))
00233            {
00234             SetEvaluationError(theEnv,TRUE);
00235             return(FALSE);
00236            }
00237         }
00238       return(TRUE);
00239      }
00240 
00241    /*=================================================*/
00242    /* Search for the watch item to be set in the list */
00243    /* of watch items. If found, set the watch item to */
00244    /* its new state and return TRUE.                  */
00245    /*=================================================*/
00246 
00247    for (wPtr = WatchData(theEnv)->ListOfWatchItems; wPtr != NULL; wPtr = wPtr->next)
00248      {
00249       if (strcmp(itemName,wPtr->name) == 0)
00250         {
00251          /*==============================================*/
00252          /* If no specific arguments are specified, then */
00253          /* set the global flag for the watch item.      */
00254          /*==============================================*/
00255 
00256          if (argExprs == NULL) *(wPtr->flag) = newState;
00257 
00258          /*=======================================*/
00259          /* Set flags for individual watch items. */
00260          /*=======================================*/
00261 
00262          if ((wPtr->accessFunc == NULL) ? FALSE :
00263              ((*wPtr->accessFunc)(theEnv,wPtr->code,newState,argExprs) == FALSE))
00264            {
00265             SetEvaluationError(theEnv,TRUE);
00266             return(FALSE);
00267            }
00268 
00269          return(TRUE);
00270         }
00271      }
00272 
00273    /*=================================================*/
00274    /* If the specified item was not found in the list */
00275    /* of watchable items then return FALSE.           */
00276    /*=================================================*/
00277 
00278    return(FALSE);
00279   }
00280 
00281 /******************************************************************/
00282 /* EnvGetWatchItem: Gets the current state of the specified watch */
00283 /*   item. Returns the state of the watch item (0 for off and 1   */
00284 /*   for on) if the watch item is found in the list of watch      */
00285 /*   items, otherwise -1 is returned.                             */
00286 /******************************************************************/
00287 globle int EnvGetWatchItem(
00288   void *theEnv,
00289   char *itemName)
00290   {
00291    struct watchItem *wPtr;
00292 
00293    for (wPtr = WatchData(theEnv)->ListOfWatchItems; wPtr != NULL; wPtr = wPtr->next)
00294      { 
00295       if (strcmp(itemName,wPtr->name) == 0) 
00296         { return((int) *(wPtr->flag)); }
00297      }
00298 
00299    return(-1);
00300   }
00301 
00302 /****************************************************************/
00303 /* ValidWatchItem: Returns TRUE if the specified name is found  */
00304 /*   in the list of watch items, otherwise returns FALSE.       */
00305 /****************************************************************/
00306 static struct watchItem *ValidWatchItem(
00307   void *theEnv,
00308   char *itemName,
00309   int *recognized)
00310   {
00311    struct watchItem *wPtr;
00312 
00313    *recognized = TRUE;
00314    if (strcmp(itemName,"all") == 0)
00315      return(NULL);
00316 
00317    for (wPtr = WatchData(theEnv)->ListOfWatchItems; wPtr != NULL; wPtr = wPtr->next)
00318      { if (strcmp(itemName,wPtr->name) == 0) return(wPtr); }
00319 
00320    *recognized = FALSE;
00321    return(NULL);
00322   }
00323 
00324 /*************************************************************/
00325 /* GetNthWatchName: Returns the name associated with the nth */
00326 /*   item in the list of watchable items. If the nth item    */
00327 /*   does not exist, then NULL is returned.                  */
00328 /*************************************************************/
00329 globle char *GetNthWatchName(
00330   void *theEnv,
00331   int whichItem)
00332   {
00333    int i;
00334    struct watchItem *wPtr;
00335 
00336    for (wPtr = WatchData(theEnv)->ListOfWatchItems, i = 1;
00337         wPtr != NULL;
00338         wPtr = wPtr->next, i++)
00339      { if (i == whichItem) return(wPtr->name); }
00340 
00341    return(NULL);
00342   }
00343 
00344 /***************************************************************/
00345 /* GetNthWatchValue: Returns the current state associated with */
00346 /*   the nth item in the list of watchable items. If the nth   */
00347 /*   item does not exist, then -1 is returned.                 */
00348 /***************************************************************/
00349 globle int GetNthWatchValue(
00350   void *theEnv,
00351   int whichItem)
00352   {
00353    int i;
00354    struct watchItem *wPtr;
00355 
00356    for (wPtr = WatchData(theEnv)->ListOfWatchItems, i = 1;
00357         wPtr != NULL;
00358         wPtr = wPtr->next, i++)
00359      { if (i == whichItem) return((int) *(wPtr->flag)); }
00360 
00361    return(-1);
00362   }
00363 
00364 /**************************************/
00365 /* WatchCommand: H/L access routine   */
00366 /*   for the watch command.           */
00367 /**************************************/
00368 globle void WatchCommand(
00369   void *theEnv)
00370   {
00371    DATA_OBJECT theValue;
00372    char *argument;
00373    int recognized;
00374    struct watchItem *wPtr;
00375 
00376    /*========================================*/
00377    /* Determine which item is to be watched. */
00378    /*========================================*/
00379 
00380    if (EnvArgTypeCheck(theEnv,"watch",1,SYMBOL,&theValue) == FALSE) return;
00381    argument = DOToString(theValue);
00382    wPtr = ValidWatchItem(theEnv,argument,&recognized);
00383    if (recognized == FALSE)
00384      {
00385       SetEvaluationError(theEnv,TRUE);
00386       ExpectedTypeError1(theEnv,"watch",1,"watchable symbol");
00387       return;
00388      }
00389 
00390    /*=================================================*/
00391    /* Check to make sure extra arguments are allowed. */
00392    /*=================================================*/
00393 
00394    if (GetNextArgument(GetFirstArgument()) != NULL)
00395      {
00396       if ((wPtr == NULL) ? TRUE : (wPtr->accessFunc == NULL))
00397         {
00398          SetEvaluationError(theEnv,TRUE);
00399          ExpectedCountError(theEnv,"watch",EXACTLY,1);
00400          return;
00401         }
00402      }
00403 
00404    /*=====================*/
00405    /* Set the watch item. */
00406    /*=====================*/
00407 
00408    EnvSetWatchItem(theEnv,argument,ON,GetNextArgument(GetFirstArgument()));
00409   }
00410 
00411 /****************************************/
00412 /* UnwatchCommand: H/L access routine   */
00413 /*   for the unwatch command.           */
00414 /****************************************/
00415 globle void UnwatchCommand(
00416   void *theEnv)
00417   {
00418    DATA_OBJECT theValue;
00419    char *argument;
00420    int recognized;
00421    struct watchItem *wPtr;
00422 
00423    /*==========================================*/
00424    /* Determine which item is to be unwatched. */
00425    /*==========================================*/
00426 
00427    if (EnvArgTypeCheck(theEnv,"unwatch",1,SYMBOL,&theValue) == FALSE) return;
00428    argument = DOToString(theValue);
00429    wPtr = ValidWatchItem(theEnv,argument,&recognized);
00430    if (recognized == FALSE)
00431      {
00432       SetEvaluationError(theEnv,TRUE);
00433       ExpectedTypeError1(theEnv,"unwatch",1,"watchable symbol");
00434       return;
00435      }
00436 
00437    /*=================================================*/
00438    /* Check to make sure extra arguments are allowed. */
00439    /*=================================================*/
00440 
00441    if (GetNextArgument(GetFirstArgument()) != NULL)
00442      {
00443       if ((wPtr == NULL) ? TRUE : (wPtr->accessFunc == NULL))
00444         {
00445          SetEvaluationError(theEnv,TRUE);
00446          ExpectedCountError(theEnv,"unwatch",EXACTLY,1);
00447          return;
00448         }
00449      }
00450 
00451    /*=====================*/
00452    /* Set the watch item. */
00453    /*=====================*/
00454 
00455    EnvSetWatchItem(theEnv,argument,OFF,GetNextArgument(GetFirstArgument()));
00456   }
00457 
00458 /************************************************/
00459 /* ListWatchItemsCommand: H/L access routines   */
00460 /*   for the list-watch-items command.          */
00461 /************************************************/
00462 globle void ListWatchItemsCommand(
00463   void *theEnv)
00464   {
00465    struct watchItem *wPtr;
00466    DATA_OBJECT theValue;
00467    int recognized;
00468 
00469    /*=======================*/
00470    /* List the watch items. */
00471    /*=======================*/
00472 
00473    if (GetFirstArgument() == NULL)
00474      {
00475       for (wPtr = WatchData(theEnv)->ListOfWatchItems; wPtr != NULL; wPtr = wPtr->next)
00476         {
00477          EnvPrintRouter(theEnv,WDISPLAY,wPtr->name);
00478          if (*(wPtr->flag)) EnvPrintRouter(theEnv,WDISPLAY," = on\n");
00479          else EnvPrintRouter(theEnv,WDISPLAY," = off\n");
00480         }
00481       return;
00482      }
00483 
00484    /*=======================================*/
00485    /* Determine which item is to be listed. */
00486    /*=======================================*/
00487 
00488    if (EnvArgTypeCheck(theEnv,"list-watch-items",1,SYMBOL,&theValue) == FALSE) return;
00489    wPtr = ValidWatchItem(theEnv,DOToString(theValue),&recognized);
00490    if ((recognized == FALSE) || (wPtr == NULL))
00491      {
00492       SetEvaluationError(theEnv,TRUE);
00493       ExpectedTypeError1(theEnv,"list-watch-items",1,"watchable symbol");
00494       return;
00495      }
00496 
00497    /*=================================================*/
00498    /* Check to make sure extra arguments are allowed. */
00499    /*=================================================*/
00500 
00501    if ((wPtr->printFunc == NULL) &&
00502        (GetNextArgument(GetFirstArgument()) != NULL))
00503      {
00504       SetEvaluationError(theEnv,TRUE);
00505       ExpectedCountError(theEnv,"list-watch-items",EXACTLY,1);
00506       return;
00507      }
00508 
00509    /*====================================*/
00510    /* List the status of the watch item. */
00511    /*====================================*/
00512 
00513    EnvPrintRouter(theEnv,WDISPLAY,wPtr->name);
00514    if (*(wPtr->flag)) EnvPrintRouter(theEnv,WDISPLAY," = on\n");
00515    else EnvPrintRouter(theEnv,WDISPLAY," = off\n");
00516 
00517    /*============================================*/
00518    /* List the status of individual watch items. */
00519    /*============================================*/
00520 
00521    if (wPtr->printFunc != NULL)
00522      {
00523       if ((*wPtr->printFunc)(theEnv,WDISPLAY,wPtr->code,
00524                              GetNextArgument(GetFirstArgument())) == FALSE)
00525         { SetEvaluationError(theEnv,TRUE); }
00526      }
00527   }
00528 
00529 /*******************************************/
00530 /* GetWatchItemCommand: H/L access routine */
00531 /*   for the get-watch-item command.       */
00532 /*******************************************/
00533 globle int GetWatchItemCommand(
00534   void *theEnv)
00535   {
00536    DATA_OBJECT theValue;
00537    char *argument;
00538    int recognized;
00539 
00540    /*============================================*/
00541    /* Check for the correct number of arguments. */
00542    /*============================================*/
00543 
00544    if (EnvArgCountCheck(theEnv,"get-watch-item",EXACTLY,1) == -1)
00545      { return(FALSE); }
00546 
00547    /*========================================*/
00548    /* Determine which item is to be watched. */
00549    /*========================================*/
00550 
00551    if (EnvArgTypeCheck(theEnv,"get-watch-item",1,SYMBOL,&theValue) == FALSE)
00552      { return(FALSE); }
00553 
00554    argument = DOToString(theValue);
00555    ValidWatchItem(theEnv,argument,&recognized);
00556    if (recognized == FALSE)
00557      {
00558       SetEvaluationError(theEnv,TRUE);
00559       ExpectedTypeError1(theEnv,"get-watch-item",1,"watchable symbol");
00560       return(FALSE);
00561      }
00562 
00563    /*===========================*/
00564    /* Get the watch item value. */
00565    /*===========================*/
00566 
00567    if (EnvGetWatchItem(theEnv,argument) == 1)
00568      { return(TRUE); }
00569 
00570    return(FALSE);
00571   }
00572 
00573 /*************************************************************/
00574 /* WatchFunctionDefinitions: Initializes the watch commands. */
00575 /*************************************************************/
00576 globle void WatchFunctionDefinitions(
00577   void *theEnv)
00578   {
00579 #if ! RUN_TIME
00580    EnvDefineFunction2(theEnv,"watch",   'v', PTIEF WatchCommand,   "WatchCommand", "1**w");
00581    EnvDefineFunction2(theEnv,"unwatch", 'v', PTIEF UnwatchCommand, "UnwatchCommand", "1**w");
00582    EnvDefineFunction2(theEnv,"get-watch-item", 'b', PTIEF GetWatchItemCommand,   "GetWatchItemCommand", "11w");
00583    EnvDefineFunction2(theEnv,"list-watch-items", 'v', PTIEF ListWatchItemsCommand,
00584                    "ListWatchItemsCommand", "0**w");
00585 #endif
00586 
00587    EnvAddRouter(theEnv,WTRACE,1000,RecognizeWatchRouters,CaptureWatchPrints,NULL,NULL,NULL);
00588    EnvDeactivateRouter(theEnv,WTRACE);
00589   }
00590 
00591 /**************************************************/
00592 /* RecognizeWatchRouters: Looks for WTRACE prints */
00593 /**************************************************/
00594 #if WIN_BTC
00595 #pragma argsused
00596 #endif
00597 static intBool RecognizeWatchRouters(
00598   void *theEnv,
00599   char *logName)
00600   {
00601 #if MAC_MCW || WIN_MCW || MAC_XCD
00602 #pragma unused(theEnv)
00603 #endif
00604 
00605    if (strcmp(logName,WTRACE) == 0) return(TRUE);
00606 
00607    return(FALSE);
00608   }
00609 
00610 /**************************************************/
00611 /* CaptureWatchPrints: Suppresses WTRACE messages */
00612 /**************************************************/
00613 #if WIN_BTC
00614 #pragma argsused
00615 #endif
00616 static int CaptureWatchPrints(
00617   void *theEnv,
00618   char *logName,
00619   char *str)
00620   {
00621 #if MAC_MCW || WIN_MCW || MAC_XCD
00622 #pragma unused(logName)
00623 #pragma unused(str)
00624 #pragma unused(theEnv)
00625 #endif
00626    return(1);
00627   }
00628 
00629 #endif /* DEBUGGING_FUNCTIONS */
00630