RJLRef: $PH/COOL-BDE/bdegen13/bde/debugMacrosHelp.txt
------------------------------------
This note identifies some of the debug aids
that I came up with to simplify debugging bde.

Calls to macros EP and LP can be inserted by globally
substituting 'EP;' after opening brace '^{',
and 'LP;' before closing brace ('^}') and return statements.
They can be removed the same way.
Caveat: certain standards may require inspection: e.g.,
'else return; must be replced by 'else { return;}' first.

Macro DP can be called wherever a location report is desired
to print location info. All 3 macros use #ifdef DEBUG'.

This simplfies and standardizes error and status reporting,
where all or some of this info would otherwise have to be
manually inserted into print statements and error messages.
For example, see how macro #define SP ... below uses DP to locate
the program counter when it traces current event and state.

The family of functions in bde/pr_util_[no]log/dprint.h
enclose printf with common signatures with #ifdef DPRNT.
================================================

Extract from bde/dprint.h:
---------------------------------
#define EP do{printf("Enter %s at %s:%d\n",__FUNCTION__,__FILE__,__LINE__);}while(0)
#define LP do{printf("Exit %s at %s:%d\n",__FUNCTION__,__FILE__,__LINE__);}while(0)

#define DP do{printf("Inside %s at %s:%d\n",__FUNCTION__,__FILE__,__LINE__);}while(0)
/* In configure.h, #define USEDECC to compile and link with cxx instead of g++*/
/* If USEDECC, cc and cxx do not recognize __FUNCTION__ used by DP EP and SP: */
#ifdef USEDECC 
#define __FUNCTION__  "Function?"
#endif


#ifdef __cplusplus__
/* for g++ */
extern "C" void dprint(const char*);
extern "C" void dprintd(const char*, const int);
extern "C" void dprints(const char*, const char*);
extern "C" void dprintdd(const char*, const int,const int);
extern "C" void dprintds(const char*, const int, const char*);
extern "C" void dprintsd(const char*, const char*, const int);
extern "C" void dprintss(const char*, const char*, const char*);
#else
/* for gcc */
...
#endif
#endif
------------------------------
Here is one example function, from pr_util_[no]log/dprint.c:

void dprintsd(const char* fmt, const char* s, const int j)
{
#if DPRNT
        printf(fmt, s, j);
#endif
}
=============================================

PostErrorMsg in bde/src/textops.cc:1219-1326:
This old function is used in all six bde/src/*ops.cc files.
It should be moved and merged with include/state.h 
or its replacement when bdeState is added.
It has a switch(errorno) with cases like the sample 
below to report an illegal state transition:
---------------------
void PostErrorMsg(int errorno)  // errorno = state code in bde/include/state.h
        // see analogous event->type map to eventname[type] in eventNameList.h
{EP;
  char * tokenstr2 ;
  tokenstr2 = strtok(statename[errorno], " ");

  printf("In state statename[%d] = \" %s \"\n", errorno, tokenstr2);

  switch(errorno) {
...
    case SBpt_move:
        fprintf(stderr, "Out of State(SBpt_move) in bpt_move()\n");
       break;
...
-----------------
These messages have a variable statename string as content
which could be retrieved from array statename[errorno];
note that errorno = state code is not dense.
It has 12 bits (4096 entries)  but there are
well under 100 legal entries. 

In bdeState the state code is a 3-level tree. 
The branches are localized by operatons under classes.
Far fewer entries are required to map the code 
into a composite state name. 

The #defines in state.h should be split into enumerated lists
and maps as proposed in the bdeState class.

=============================================
Aids to print State- and Event-level test  coverage statistics:

fileio.cc:658:#include "eventNameList.h" 
	// table of event type names for printEventStats()
init.cc:374:FILE* STEVfp;  // bde appends state and event type counts.
init.cc:469: * printSTEVcounts prints state change and event stats on exit bde.
init.cc:474:void printSTEVcounts(char* statsFileName)

bde/include contains an array of X11 event names, indexed
by the eventtype code from X11:
----------------------
/* "eventNameList.h" - RJL 040811 */
/* do NOT #include this more than once (e.g. only in init.cc) */
#ifndef NAMELIST
#define NAMELIST
typedef char EventEntry;
#ifdef MAIN  
char  eventname[36][17] 
= { /*initialize this in one place: only*/
"NotUsed         ",
"Errors          ",
"KeyPress        ",
.
.
.
"MappingNotify   ",
"LASTEvent       "
};
#else
extern char  eventname[36][17];
#endif
#endif
---------------------------------
The eventname array is indexed by X11-event type 
and used by the SP  macro 
to trace the current [global] state and event:
#define SP do{printf("\nstate:%s, event %s ",\
    statename[state], &eventname[event->type][0]);DP; }while(0)

The event type to name map is based on this man page:
	$PH/COOL-BDE/XtEvent.man3X11

=================================

Also in bde/include is state.h: the state codes occur in groups 
of up to 16 per class, so hex digits would separate them better:
(They will be obsoleted by a future bdeState class which 
defines a 3-hex-digit encoding for beter encapsulation.)
------------
bde/include/state.h:
.
.
.
#define ALL 0   // skips stateentry count=0 in init:printStateEntries
// index to statename[]  is state-1:
#define NState            1            // No-op state
#define SAttrib           2            // ? not currently implemented
#define SHelp             3            // Help not currently implemented
// this state is used to add identification
#define SIdentifier       4            // used in finishLedit()
.
.
.
#define SCnode            17            // Node Create type Circle
#define SMove             18            // Node Move
#define SDnode1           19            // Node Delete
#define SDnode2           20            // secondary state for SDnode1
#define SSelect           21            // node select not implemented yet
.
.
.
----------------

For examples of state and event data statistics from bde, 
see these files in $RBGB/test:
------------------
mercury.cs.uml.edu(338)> pwd
/nfs/galaxy/faculty/fac1/lechner/bde2alpha_rl/sandbox/bdeNT050526/bdegen13/bde/test
mercury.cs.uml.edu(339)> lg ST_EV_stats.txt EventTypeStats.txt
-rwxr-xr-x    1 lechner  05f523       9928 Nov 22  2004 EventTypeStats.txt
-rwxr-xr-x    1 lechner  05f523      21793 Sep 15 18:19 ST_EV_stats.txt
mercury.cs.uml.edu(340)>
-----------------
(The event type to name map is based on this man page:
        $PH/COOL-BDE/XtEvent.man3X11
)