manual.txt

AlertDriver c++模块化类库

                                                Logical Operators
                                Professional Software Development
                                          & Computer Consultation
                                                                 
                                              707-A Dunbar Avenue
                                                     P.O. Box 815
                                            Dunbar WV  25064-0815
                                         Telephone: [phone]

                                THE ALERTDRIVER C++ CLASS LIBRARY
                                       EXCERPTS FROM USER'S GUIDE
                                                     Version 1.00
                                                                 
  References to businesses, organizations, and individuals
 within this publication are supplied only for informational
    purposes and in no way imply or infer endorsement or
  recommendation of the products and/or services of Logical
 Operators or its associates or affiliates unless explicitly
                           stated.
   
   All brand names, trademarks, and registered trademarks
 appearing throughout this document are properties of their
   respective owners. The AlertDriver Class Library source
   code, object code, and all associated documentation are
 copyrighted 1994 by Logical Operators. All Rights Reserved.
                   Part number ADUG940125.



Preface


At Logical Operators, we encountered many problems, portability
issues, and maintenance issues when writing error-reporting
code for the reusable libraries used in our applications.  Nested
if-then-else code detracted from the clarity of algorithms,
hard-coded error messages caused reusability problems, and
re-routing messages from the screen to other devices (such as
printers) was difficult to say the least.

Our solution to these problems, the AlertDriver Class Library,
avoids all of these problems while providing a new software
library with modularity, encapsulation, a consistent call
interface, and efficient code size and speed. The AlertDriver
Class Library is reusable and extensible to multiple application
environments and hardware configurations. And perhaps most
importantly, this easy-to-use class library provides the
flexibility of multiple error-reporting methods within the same
program while including the capability to easily enable, disable,
or change reporting methods at both compile-time and run-time!



Chapter 2           AlertDriver Class Library Concepts
                    

More Than Just Errors

The   AlertDriver  Class  Library  does  more  than  just  simple
error-reporting,  it  alerts the user to  virtually  any  program
condition   during   execution  (hence  the  name).   There   are
several  types  of  program  conditions,  or  alerts,  which  you
may  wish  to  present  to  the user  during  program  execution:
errors, information, messages, and warnings.

Errors,  the  most  serious  types  of  alerts,  occur   when   a
program  detects  a  state  which  makes  continuation   of   the
current   branch   of   execution  impossible.   In   interactive
applications,  an  error  usually stops program  execution  until
acknowledged  by  the  user. A typical error  might  be:  "Cannot
find file C:\YOURFILE.DAT."

Information  alerts  occur whenever an  application  informs  the
user  of  a  program  condition or the occurrence  of  an  event.
Information   alerts  do  not  reflect  execution  problems   and
exist  only  for  the  convenience of the  user.  In  interactive
applications,  an  information  alert  stops  program   execution
until  acknowledged  by  the  user. A typical  information  alert
might be:  "File C:\YOURFILE.DAT was successfully loaded."

Messages  also  occur when the application informs  the  user  of
a   program  condition.  Like  information  alerts,  messages  do
not   reflect   execution  problems  and  exist  only   for   the
convenience  of  the  user. Unlike information  alerts,  messages
do  not  stop  program  execution  in  interactive  applications.
Once   posted,  a  message  remains  active  until  replaced   by
another   message  or  cleared  by  the  application.  A   sample
message might be:  "Loading file C:\YOURFILE.DAT..."

Warnings   (sometimes   referred   to   as   confirmations)   are
reported   when   the  application  prompts  the   user   for   a
decision.  Warnings  are  typically  posed  as  a  question  with
three  possible  answers:   YES, NO, or  CANCEL.  Warnings  pause
program   execution  until  the  user  makes  a  decision,   then
continue   program   execution  based  upon  that   decision.   A
common   warning   is   "Do   you   want   to   overwrite    file
C:\YOURFILE.DAT?"

Although  the  AlertDriver Class Library provides  the  means  to
deal  with  all  of  these  types of alerts,  this  chapter  will
concentrate   only   on   error   handling   to   simplify    the
discussion.  Please  keep  in mind that  the  concepts  of  error
handling also apply to each of the other types of alerts.


The AlertableObject Concept

In   most   class   libraries,  the  majority  of   classes   are
ultimately  descendants  of a single root  class  (usually  named
something    like    Object    and    having    little     actual
functionality).  Most  new  classes  created  by  users  of   the
library  inherit  the properties of an existing  class,  even  if
the  class  is  as  basic  as  Object.  Thus,  most  objects  (or
class   instantiations)  in  an  application  can  be  referenced
and treated as a lowest common denominator - an Object.

Now  let's  suppose  that  the root  class  has  the  ability  to
report   errors  it  encounters  during  method  executions.   If
such   a   class   exists,  it  becomes  easy  to   derive   more
specialized  classes  while  simply  inheriting  the  ability  to
report  errors.  Our  programs can invoke  the  member  functions
of  an  object,  knowing  that if an  error  occurs,  the  object
itself  will  report  the  problem  to  the  user!  Our  programs
only  need  to  be  aware  of  the  success  or  failure  of  the
member function's execution.

If  such  a  capability could be added to the  root  class  of  a
commercial  application  framework,  then  the  majority  of  the
framework's  classes  (and their descendants)  would  be  capable
of   reporting  their  errors  to  the  user  in  a  standardized
manner   right   out   of   the  box   without   any   additional
programming!   Of  course,  not  every  programmer   would   have
access  to  the  framework's source code to implement  this,  and
we   may   not  want  to  add  additional  overhead  to  such   a
rudimentary  class  anyway.  So in the  true  spirit  of  object-
oriented   programming,  we  would  design  a  new  class   which
directly  inherits  the  capabilities of the  framework's  Object
counterpart  and  adds  some  basic  error-handling  capabilities
(see Example 4).

Example  4  - A sample class declaration which could  add  error-
handling   capabilities  to  the  base  class  (Object)   of   an
application  framework.  The AlertDriver  class  library  creates
an error-handling class in a similar manner.

class AlertableObject : public Object
{
   /*add member functions below to
     enable error handling*/
   ...
};   //class AlertableObject

The  AlertDriver  Class  Library  includes  a  class  similar  to
that  in  Example  4  and implements the  class  in  such  a  way
that  it  can  either  be  used  without  a  class  hierarchy  or
integrated  into  practically any  C++  class  library:   new  or
existing,  commercial  or  private.  We  have  named  this  class
AlertableObject:   it  provides the functionality  to  alert  the
user  of  errors.  By  serving as a base  class,  AlertableObject
provides   a  common  calling  interface  to  our  error-handling
member    functions.   In   addition,   because   AlertableObject
contains   a   public  member  function  interface,  our   error-
handling    routines   are   accessible   from    program    code
throughout the application.


Benefiting From AlertableObject

By   making   AlertableObject   a   direct   descendant   of    a
framework's   root   class   in  the  class   hierarchy,   error-
handling   capabilities  can  easily   be   inherited   by   your
classes  and  their  descendants. Of course,  classes  which  are
derived   from   the  root  class  (and  bypass  AlertableObject,
like  the  existing classes in the framework)  will  not  inherit
the error-handling capabilities.

So  what  other  benefits  exist from using  the  AlertableObject
class  in  an  application? Suppose we have a code  module  which
has   just   invoked  a  member  function  of  a  descendant   of
AlertableObject.  Our  calling  module  does   not   report   any
errors   which   occur  within  the  object's   member   function
(that's   the  object's  responsibility).  However,  our  calling
module   may   be  interested  in  determining  if   the   member
function was able to execute successfully, and if not, why.

This   simple  scenario  is  an  excellent  reason  to  have   an
object's  member  functions return error codes.  It  is  easy  to
declare   a   group   of   constants   which   represent    error
conditions  for  each  class  (see  Example  5).  Not  only  does
this   practice  enforce  good  programming  by  removing   hard-
coded  values  from  the member functions  and  calling  modules,
but  a  wide  range  of  values can  be  represented  within  the
code  returned  by  each member function. In  addition,  returned
error   codes   remove   the  need  for  an  unnecessary   global
variable  (such  as  errno) or class data  member  to  store  the
most recent result of a method execution.

Example   5   -  Error  constants  can  easily  be  created   and
returned from AlertableObjects.

const long int NOERR = 0;
const long int FILENOTFOUND = 1;
const long int OUTOFMEMORY = 2;
...
class MyObj : public AlertableObject
{
   public:
      virtual long int MemFunc1(void);
         //returns error code
   ...
};   //class MyObj

By  testing  the  returned error codes, the module  calling  such
member  functions  can  smoothly recover  from  errors  occurring
within    the   object   while   avoiding   the   "matching-else"
syndrome   for  error  reporting  (see  Example  6).  A  pleasant
side-effect   is   that  the  source  code  becomes   much   more
readable and understandable.

Example   6   -  The  same  algorithm  used  in  Example   1   is
implemented   here,   using   calls   to   an   object's   member
functions   rather  than  "plain"  function  calls.  The   object
MyObj  is  derived  from  class AlertableObject,  allowing  MyObj
to  report  errors  to  the  user when  they  occur.  Notice  how
much  more  readable  the code below appears  than  the  code  of
Example 1.

...
if (MyObj.func1() == NOERR)
   if (MyObj.func2() == NOERR)
      if (MyObj.func3() == NOERR)
         ...

Perhaps  the  biggest  benefit of the  AlertableObject,  however,
lies   in   its  encapsulation.  Because  the  object  is   self-
contained  and  able  to  report its own errors  in  a  platform-
independent   manner,   it   can   be   linked   into    multiple
applications,  none  of  which has to  deal  with  reporting  the
errors  which  could occur internally. Imagine  how  much  easier
your  next  programming  project would be  if  you  could  simply
plug  some  of  your existing classes together and  forget  about
handling  the  errors,  confident  that  they  will  be   handled
automatically! With the AlertDriver Class Library, you can!


Introducing The AlertDriver

The  AlertDriver  is  the class in the hierarchy  which  provides
the     platform-    and    hardware-dependent    error-reporting
capabilities  to  objects  derived  from  AlertableObject.   Each
object   derived   from  AlertableObject  uses   an   AlertDriver
object   to   perform  the  actual  reporting   of   each   error
message.  The  AlertDriver  object  determines  how  each   error
message  is  reported  using  the  API  (application  programming
interface)  calls  and  hardware available  to  the  application;
hence,  each  AlertDriver  object is  an  "error  device  driver"
for   the  application  environment.  Because  AlertDrivers   are
implemented  as  classes, any AlertDriver can  be  subclassed  by
the  application  programmer to change or  control  its  specific
actions.

The  AlertDriver  class library supplies  classes  which  can  be
used   to   report   errors   to  the  screen   for   interactive
applications,  or  log  errors to a  printer  or  disk  file  for
programs   which   normally   run  without   human   supervision.
Additional  AlertDrivers can be obtained  or  written  for  other