--- /dev/null
+#LyX 1.1 created this file. For more info see http://www.lyx.org/
+\lyxformat 218
+\textclass linuxdoc
+\language english
+\inputencoding default
+\fontscheme default
+\graphics default
+\paperfontsize 10
+\spacing single
+\papersize Default
+\paperpackage a4
+\use_geometry 0
+\use_amsmath 0
+\paperorientation portrait
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\defskip medskip
+\quotes_language english
+\quotes_times 2
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+
+\layout Title
+\added_space_top vfill \added_space_bottom vfill
+SALOME Kernel resources for developer
+\layout Author
+
+Antoine Yessayan, Paul Rascle
+\layout Date
+
+Version 0.1 January 16, 2002
+\layout Abstract
+
+ABSTRACT
+\layout Abstract
+
+This document describes the development environment for C++ and Python.
+ Makefiles generation and usage are introduced in another document:
+\begin_inset Quotes eld
+\end_inset
+
+using the SALOME configuration and building system environment
+\begin_inset Quotes erd
+\end_inset
+
+.
+ Development environment is intended here as: trace and debug macros usage;
+ SALOME exceptions usage, in C++ and Python; user CORBA exceptions usage,
+ in C++ and Python, with and without Graphical User Interface; some general
+ purpose services such as singleton, used for CORBA connection and disconnection.
+\layout Standard
+
+
+\begin_inset LatexCommand \tableofcontents{}
+
+\end_inset
+
+
+\layout Section
+
+Trace and debug Utilities
+\layout Standard
+
+During the development process, an execution log is useful to identify problems.
+ This log contains messages, variables values, source files names and line
+ numbers.
+ It is recommended to verify assertions on variables values and if necessary,
+ to stop the execution at debug time, in order to validate all parts of
+ code.
+\layout Subsection
+
+Two modes: debug and release
+\layout Standard
+
+The goal of debug mode is to check as many features as possible during the
+ early stages of the development process.
+ The purpose of the utilities provided in SALOME is to help the developer
+ to add detailed traces and check variables values, without writing a lot
+ of code.
+\layout Standard
+
+When the code is assumed to be valid, the release mode optimizes execution,
+ in terms of speed, memory, and display only user level messages.
+\layout Standard
+
+But, some informations must always be displayed in both modes: especially
+ messages concerning environment or internal errors, with version identification.
+ When an end user is confronted to such a message, he may refer to a configurati
+on documentation or send the message to the people in charge of SALOME installat
+ion, or to the development team, following the kind of error.
+\layout Subsection
+
+C++ Macros for trace and debug
+\layout Standard
+
+SALOME provides C++ macros for trace and debug.
+ These macros are in
+\family typewriter
+SALOME/src/utils/utilities.h
+\family default
+ and this file must be included in C++ source.
+ Some macros are activated only in debug mode, others are always activated.
+ To activate the debug mode,
+\family typewriter
+_DEBUG_
+\family default
+ must be defined, which is the case when SALOME Makefiles are generated
+ from configure, without options.
+ When
+\family typewriter
+_DEBUG_
+\family default
+ is undefined (release mode), the debug mode macros are defined empty (they
+ do nothing).
+ So, when switching from debug to release, it is possible (and recommended)
+ to let the macro calls unchanged in the source.
+\layout Standard
+
+All the macros writing on the standard output start by flushing the standard
+ error.
+ At the end of the display those macros flush the standard output.
+\layout Standard
+
+Two informations are systematically added in front of the information displayed:
+\layout Itemize
+
+the name of the source file in which the macros is set;
+\layout Itemize
+
+the line number of the source file at which the macro is set.
+\layout Subsubsection
+
+Macros defined in debug and release modes
+\layout Paragraph
+
+INFOS_COMPILATION
+\layout Standard
+
+The C++ macro
+\family typewriter
+INFOS_COMPILATION
+\family default
+ writes on the standard output informations about the compiling process:
+
+\layout Itemize
+
+the name of the compiler :
+\family typewriter
+g++, KCC, CC, pgCC
+\family default
+;
+\layout Itemize
+
+the date and the time of the compiling processing process.
+\layout Standard
+
+This macro
+\family typewriter
+INFOS_COMPILATION
+\family default
+ does not have any argument.
+ Moreover, it is defined in both compiling mode :
+\family typewriter
+_DEBUG_
+\family default
+ and
+\family typewriter
+_RELEASE_
+\family default
+.
+\layout Standard
+
+Example :
+\layout Verbatim
+
+#include "utilities.h"
+\layout Verbatim
+
+int main(int argc , char **argv)
+\layout Verbatim
+
+{
+\layout Verbatim
+
+ INFOS_COMPILATION;
+\layout Verbatim
+
+ ...
+\layout Verbatim
+
+}
+\layout Paragraph
+
+INFOS(str)
+\layout Standard
+
+In both compiling mode
+\family typewriter
+_DEBUG_
+\family default
+ and
+\family typewriter
+_RELEASE_
+\family default
+, The C++ macro
+\family typewriter
+INFOS
+\family default
+ writes on the standard output the string which has been passed in argument
+ by the user.
+\layout Standard
+
+Example :
+\layout Verbatim
+
+#include "utilities.h"
+\layout Verbatim
+
+int main(int argc , char **argv)
+\layout Verbatim
+
+{
+\layout Verbatim
+
+ ...
+
+\layout Verbatim
+
+ INFOS("NORMAL END OF THE PROCESS");
+\layout Verbatim
+
+ return 0;
+\layout Verbatim
+
+}
+\layout Standard
+
+displays :
+\layout Verbatim
+
+main.cxx [5] : NORMAL END OF THE PROCESS
+\layout Subsubsection
+
+Macros defined only in debug mode
+\layout Paragraph
+
+MESSAGE(str)
+\layout Standard
+
+In
+\family typewriter
+_DEBUG_
+\family default
+ compiling mode only, the C++ macro
+\family typewriter
+MESSAGE
+\family default
+ writes on the standard output the string which has been passed in argument
+ by the user.
+ In
+\family typewriter
+_RELEASE_
+\family default
+ compiling mode, this macro is blank.
+\layout Standard
+
+Example :
+\layout Verbatim
+
+#include "utilities.h"
+\layout Verbatim
+
+#include <string>
+\layout Verbatim
+
+using namespace std;
+\layout Verbatim
+
+int main(int argc , char **argv)
+\layout Verbatim
+
+{
+\layout Verbatim
+
+ ...
+
+\layout Verbatim
+
+ const char *str = "Salome";
+\layout Verbatim
+
+ MESSAGE(str);
+\layout Verbatim
+
+ ...
+ const string st;
+\layout Verbatim
+
+ st = "Aster";
+\layout Verbatim
+
+ MESSAGE(c_str(st+" and CASTEM"));
+\layout Verbatim
+
+ return 0;
+\layout Verbatim
+
+}
+\layout Standard
+
+displays :
+\layout Verbatim
+
+- Trace main.cxx [8] : Salome
+\layout Verbatim
+
+- Trace main.cxx [12] : Aster and CASTEM
+\layout Paragraph
+
+BEGIN_OF(func_name)
+\layout Standard
+
+In
+\family typewriter
+_DEBUG_
+\family default
+ compiling mode, The C++ macro
+\family typewriter
+BEGIN_OF
+\family default
+ appends the string
+\family typewriter
+"Begin of "
+\family default
+ to the one passed in argument by the user and displays the result on the
+ standard output.
+ In
+\family typewriter
+_RELEASE_
+\family default
+ compiling mode, this macro is blank.
+\layout Standard
+
+Example :
+\layout Verbatim
+
+#include "utilities.h"
+\layout Verbatim
+
+int main(int argc , char **argv)
+\layout Verbatim
+
+{
+\layout Verbatim
+
+ BEGIN_OF(argv[0]);
+\layout Verbatim
+
+ return 0;
+\layout Verbatim
+
+}
+\layout Standard
+
+displays :
+\layout Verbatim
+
+- Trace main.cxx [3] : Begin of a.out
+\layout Paragraph
+
+END_OF(func_name)
+\layout Standard
+
+In
+\family typewriter
+_DEBUG_
+\family default
+ compiling mode, The C++ macro
+\family typewriter
+END_OF
+\family default
+ appends the string
+\family typewriter
+"Normal end of "
+\family default
+ to the one passed in argument by the user and displays the result on the
+ standard output.
+ In
+\family typewriter
+_RELEASE_
+\family default
+ compiling mode, this macro is blank.
+\layout Standard
+
+Example :
+\layout Verbatim
+
+#include "utilities.h"
+\layout Verbatim
+
+int main(int argc , char **argv)
+\layout Verbatim
+
+{
+\layout Verbatim
+
+ END_OF(argv[0]);
+\layout Verbatim
+
+ return 0;
+\layout Verbatim
+
+}
+\layout Standard
+
+displays :
+\layout Verbatim
+
+- Trace main.cxx [4] : Normal end of a.out
+\layout Paragraph
+
+SCRUTE(var)
+\layout Standard
+
+In
+\family typewriter
+_DEBUG_
+\family default
+ compiling mode, The C++ macro
+\family typewriter
+SCRUTE
+\family default
+ displays its argument which is an application variable followed by the
+ value of the variable.
+ In
+\family typewriter
+_RELEASE_
+\family default
+ compiling mode, this macro is blank.
+\layout Standard
+
+Example :
+\layout Verbatim
+
+#include "utilities.h"
+\layout Verbatim
+
+int main(int argc , char **argv)
+\layout Verbatim
+
+{
+\layout Verbatim
+
+ const int i=999;
+\layout Verbatim
+
+ if( i > 0 ) SCRUTE(i) ; i=i+1;
+\layout Verbatim
+
+ return 0;
+\layout Verbatim
+
+}
+\layout Standard
+
+displays :
+\layout Verbatim
+
+- Trace main.cxx [5] : i=999
+\layout Paragraph
+
+ASSERT(condition)
+\layout Standard
+
+In
+\family typewriter
+_DEBUG_
+\family default
+ compiling mode only, The C++ macro
+\family typewriter
+ASSERT
+\family default
+ checks the expression passed in argument to be not NULL.
+ If it is NULL the process is stopped and the condition is written on the
+ standard output.
+ In
+\family typewriter
+_RELEASE_
+\family default
+ compiling mode, this macro is blank.
+ N.B.
+ : if
+\family typewriter
+ASSERT
+\family default
+ is already defined, this macro is ignored.
+\layout Standard
+
+Example :
+\layout Verbatim
+
+#include "utilities.h"
+\layout Verbatim
+
+...
+
+\layout Verbatim
+
+const char *ptrS = fonc();
+\layout Verbatim
+
+ASSERT(ptrS!=NULL);
+\layout Verbatim
+
+cout << strlen(ptrS);
+\layout Verbatim
+
+float table[10];
+\layout Verbatim
+
+int k;
+\layout Verbatim
+
+...
+
+\layout Verbatim
+
+ASSERT(k<10);
+\layout Verbatim
+
+cout << table[k];
+\layout Section
+
+Exceptions
+\layout Subsection
+
+C++ exceptions: class SALOME_Exception
+\layout Subsubsection
+
+definition
+\layout Standard
+
+The class
+\family typewriter
+SALOME_Exception
+\family default
+ provides a generic method to send a message, with optional source file
+ name and line number.
+ This class is intended to serve as a base class for all kinds of exceptions
+ SALOME code.
+ All the exceptions derived from
+\family typewriter
+SALOME_Exception
+\family default
+ could be handled in a single catch, in which the message associated to
+ the exception is displayed, or sent to a log file.
+\layout Standard
+
+The class
+\family typewriter
+SALOME_Exception
+\family default
+ inherits its behavior from the STL class exception.
+\layout Subsubsection
+
+usage
+\layout Standard
+
+The header
+\family typewriter
+SALOME/src/utils/utils_SALOME_Exception.hxx
+\family default
+ must be included in the C++ source, when raised or trapped:
+\layout Standard
+
+
+\family typewriter
+#include
+\family default
+"
+\family typewriter
+utils_SALOME_Exception.hxx
+\family default
+"
+\layout Standard
+
+The
+\family typewriter
+SALOME_Exception
+\family default
+ constructor is:
+\layout Verbatim
+
+SALOME_Exception( const char *text,
+\layout Verbatim
+
+ const char *fileName=0,
+\layout Verbatim
+
+ const unsigned int lineNumber=0 );
+\layout Standard
+
+The exception is raised like this:
+\layout Verbatim
+
+throw SALOME_Exception("my pertinent message");
+\layout Standard
+
+or like this:
+\layout Verbatim
+
+throw SALOME_Exception(LOCALIZED("my pertinent message"));
+\layout Standard
+
+where LOCALIZED is a macro provided with
+\family typewriter
+utils_SALOME_Exception.hxx
+\family default
+ which gives file name and line number.
+\layout Standard
+
+The exception is handled like this:
+\layout Verbatim
+
+try
+\layout Verbatim
+
+ {
+\layout Verbatim
+
+ ...
+\layout Verbatim
+
+ }
+\layout Verbatim
+
+catch (const SALOME_Exception &ex)
+\layout Verbatim
+
+ {
+\layout Verbatim
+
+ cerr << ex.what() <<endl;
+\layout Verbatim
+
+ }
+\layout Standard
+
+The
+\family typewriter
+what()
+\family default
+ method overrides the one defined in the STL exception class.
+\layout Subsection
+
+CORBA exceptions
+\layout Subsubsection
+
+definition
+\layout Standard
+
+The idl
+\family typewriter
+SALOME_Exception
+\family default
+ provides a generic CORBA exception for SALOME, with an attribute that gives
+ an exception type,a message, plus optional source file name and line number.
+
+\layout Standard
+
+This idl is intended to serve for all user CORBA exceptions raised in SALOME
+ code, as IDL specification does not support exception inheritance.
+ So, all the user CORBA exceptions from SALOME could be handled in a single
+ catch.
+\layout Standard
+
+The exception types defined in idl are:
+\layout Description
+
+COMM CORBA communication problem,
+\layout Description
+
+BAD_PARAM Bad User parameters,
+\layout Description
+
+INTERNAL_ERROR application level problem (often irrecoverable).
+\layout Standard
+
+CORBA system and user exceptions already defined in the packages used within
+ SALOME, such as OmniORB exceptions, must be handled separately.
+\layout Subsubsection
+
+usage
+\layout Paragraph
+
+CORBA servant, C++
+\layout Standard
+
+The CORBA Server header for
+\family typewriter
+SALOME_Exception
+\family default
+ and a macro to throw the exception are provided with the header
+\family typewriter
+SALOME/src/Utils/Utils_CorbaException.hxx
+\family default
+:
+\layout Verbatim
+
+#include "Utils_CorbaException.hxx"
+\layout Standard
+
+The exception is raised with a macro which appends file name and line number.
+\layout Verbatim
+
+if (myStudyName.size() == 0)
+\layout Verbatim
+
+ THROW_SALOME_CORBA_EXCEPTION("No Study Name given",
+\backslash
+
+\layout Verbatim
+
+ SALOME::BAD_PARAM);
+\layout Paragraph
+
+CORBA Client, GUI Qt C++
+\layout Standard
+
+The CORBA Client header for
+\family typewriter
+SALOME_Exception
+\family default
+ and a Qt function header that displays a message box are provided in
+\family typewriter
+SALOME/src/SALOMEGUI/SALOMEGUI_QtCatchCorbaException.hxx
+\family default
+:
+\layout Verbatim
+
+#include "SALOMEGUI_QtCatchCorbaException.hxx"
+\layout Standard
+
+A typical exchange with a CORBA Servant will be:
+\layout Verbatim
+
+try
+\layout Verbatim
+
+ {
+\layout Verbatim
+
+ ...
+ // one ore more CORBA calls
+\layout Verbatim
+
+ }
+\layout Verbatim
+
+catch (const SALOME::SALOME_Exception & S_ex)
+\layout Verbatim
+
+ {
+\layout Verbatim
+
+ QtCatchCorbaException(S_ex);
+\layout Verbatim
+
+ }
+\layout Verbatim
+
+\layout Paragraph
+
+CORBA Client, C++, without GUI
+\layout Standard
+
+Nothing specific has been provided to the developer yet.
+ See the idl or the Qt function
+\family typewriter
+SALOMEGUI_QtCatchCorbaException.hxx
+\family default
+ to see how to get the information given by the exception object.
+\layout Section
+
+Miscellaneous tools
+\layout Subsection
+
+Singleton
+\layout Subsubsection
+
+Definition
+\layout Standard
+
+A singleton is an application data which is created and deleted only once
+ at the end of the application process.
+ The C++ compiler allows the user to create a static singleton data before
+ the first executable statement.
+ They are deleted after the last statement execution.
+\layout Standard
+
+The
+\family typewriter
+SINGLETON_
+\family default
+ template class deals with dynamic singleton.
+ It is useful for functor objects.
+ For example, an object that connects the application to a system at creation
+ and disconnects the application at deletion.
+\layout Subsubsection
+
+Usage
+\layout Standard
+
+To create a single instance a POINT object :
+\layout Verbatim
+
+# include "Utils_SINGLETON.hxx"
+\layout Verbatim
+
+...
+
+\layout Verbatim
+
+POINT *ptrPoint=SINGLETON_<POINT>::Instance() ;
+\layout Verbatim
+
+assert(ptrPoint!=NULL) ;
+\layout Standard
+
+No need to delete ptrPoint.
+ Deletion is achieved automatically at exit.
+ If the user tries to create more than one singleton by using the class
+ method
+\family typewriter
+SINGLETON_<TYPE>::Instance()
+\family default
+, the pointer is returned with the same value even if this is done in different
+ functions (threads ?).
+\layout Verbatim
+
+POINT *p1=SINGLETON_<POINT>::Instance() ;
+\layout Verbatim
+
+...
+
+\layout Verbatim
+
+POINT *p2=SINGLETON_<POINT>::Instance() ;
+\layout Verbatim
+
+assert(p1==p2)
+\layout Subsubsection
+
+Design description
+\layout Standard
+
+Here are the principles features of the singleton design :
+\layout Itemize
+
+the user creates an object of class
+\family typewriter
+TYPE
+\family default
+ by using the class method
+\family typewriter
+SINGLETON_<TYPE>::Instance()
+\family default
+ which returns a pointer to the single object ;
+\layout Itemize
+
+to create an object,
+\family typewriter
+SINGLETON_<TYPE>::Instance()
+\family default
+ uses the default constructor of class
+\family typewriter
+TYPE
+\family default
+ ;
+\layout Itemize
+
+at the same time, this class method creates a destructor object which is
+ added to the generic list of destructor objects to be executed at the end
+ of the application (
+\family typewriter
+atexit
+\family default
+) ;
+\layout Itemize
+
+at the end of the application process all the deletions are performed by
+ the
+\family typewriter
+Nettoyage()
+\family default
+ C\SpecialChar ~
+function which executes the destruction objects end then deletes the destructi
+ons objects themselves ;
+\layout Itemize
+
+the
+\family typewriter
+Nettoyage()
+\family default
+ C \SpecialChar ~
+function using atexit() C \SpecialChar ~
+function is embedded in a static single object
+
+\family typewriter
+ATEXIT_()
+\family default
+.
+\the_end
