OSE - C++ Library User Guide

Graham Dumpleton
Dumpleton Software Consulting Pty Limited
PO BOX 3150
Parramatta, 2124
N.S.W, Australia
email: grahamd@nms.otc.com.au

Table of Contents

Library Information
OSE - C++ Library User GuideLibrary Information

Library Information

1 Library Organisation

The library suite is broken up into four major parts. The main part is the OTCLIB library. This library is a collection of generic classes useful in most C++ programming tasks. The OTCLIB library is portable across DOS, OS/2 and UNIX platforms. Under DOS and OS/2, only 32 bit compilers using a flat memory model are fully supported

For software developers using the UNIX platform, there is also the OUXLIB library. This library is a collection of classes specific to the UNIX platform. The classes are a mixture of standalone classes, and classes which extend the functionality of classes in the OTCLIB library with features specific to UNIX.

The OTKLIB library contains a number of classes which facilitate using the above libraries in conjunction with the TCL/TK libraries developed by John Ousterhout.

The final part is the OSE library. The soul purpose of this library is to record version information about OSE.

2 Release Information

Information about the release of OSE you are using is provided in the header file `OSE/OSE.h'. This information is valuable when your code needs to work with different versions of OSE and some changes in OSE were necessary between versions, or additional features were made available.

Four main definitions are provided. Each is defined as a preprocessor macro with an integral value. The definitions are:

---------------------------------------------------------
Symbol                   Definition                        
---------------------------------------------------------
OSE_MAJOR_RELEASE        Major version number.             
OSE_MINOR_RELEASE        Minor version number.             
OSE_MAINTENANCE_RELEASE  Patch level for release.          
OSE_LIBRARY_RELEASE      Combination of major, minor and   
                         maintenance release numbers.      
---------------------------------------------------------
When the OSE_LIBRARY_RELEASE macro is defined, the minor release number and maintenance release number are expanded to two digits. For example, for OSE version 4.0 patchlevel 0, the OSE_LIBRARY_RELEASE macro will be defined as `40000'. To use this macro in your code, the `#if' preprocessor directive should be used. For example:

  #if OSE_LIBRARY_RELEASE >= 40000
...
#endif
The library release number is also available as a string value, as is the actual name of the release you are using. The two macros providing this information are:

----------------------------------------------------
Symbol              Definition                        
----------------------------------------------------
OSE_RELEASE_NAME    Name of release.                  
OSE_RELEASE_NUMBER  The value of the macro            
                    OSE_LIBRARY_RELEASE as a string.  
----------------------------------------------------
A further set of macros are defined which give information pertaining to the host on which OSE is being used, and where OSE is installed. Each of these macros is defined as a string value. The macros and what they define are:

------------------------------------------------------------
Symbol            Definition                                  
------------------------------------------------------------
OSE_HOST          Tag identifying the host architecture and   
                  operating system.                           
OSE_ROOT_PREFIX   Prefix to the root directory in which all   
                  versions of OSE are installed.              
OSE_ROOT          Root directory in which all versions of     
                  OSE are installed.                          
OSE_VERSION_ROOT  Root directory in which a specific vers     
                  ion of OSE is installed.                    
------------------------------------------------------------
One final means of obtaining information about the release of OSE being used, is the OSE_RELEASE_TAG variable. This variable is located in the OSE library. The OSE library will be forcibly linked in with any application which you develop. The type of the OSE_RELEASE_TAG is a character string. Although not useful inside a program, the value of this variable is useful in determining what version of OSE a particular program executable was produced with. This is achieved by running the UNIX `what' command with your program as argument. For example:

  $ what myapp
myapp:
OSE Release SPARC_SUN4 40000

3 Basic Types and Macros

A number of basic types and macros are used throughout the libraries. These definitions are obtained by including the header file `OTC/OTC.h'. Inclusion of this header file will also result in the `OSE/OSE.h' header file being included. There is no need for you to include these header files if you have included the header file of any class in the libraries, as the class header file will typically include these header files for you. The `OTC/OTC.h' header file may be included in both C and C++ code files.

The most important type to be defined is that of a boolean type. The definitions provided are:

  typedef int OTC_Boolean;
#define OTCLIB_FALSE 0
#define OTCLIB_TRUE 1
These definitions, as are nearly all other definitions in the library, are prefixed with a symbol unique to the library. This is done to avoid a conflict with a boolean type defined by any other libraries which you may be using in conjunction with the class libraries in OSE. When C++ compilers supporting the new `bool' type are available, the above definitions will be conditionally replaced with:

  typedef bool OTC_Boolean;
#define OTCLIB_FALSE false
#define OTCLIB_TRUE true
Macros are used for the definitions of `OTCLIB_FALSE' and `OTCLIB_TRUE' instead of `const' variables, as the use of `const' variables breaks with some C++ compilers on certain platforms when shared libraries are used. Using these definitions, rather than your own will ensure that your code remains portable between C++ compilers and platforms.

Types which are defined if your operating system does not define them are:

  typedef unsigned char u_char;
typedef unsigned short u_short;
typedef unsigned int u_int;
typedef unsigned long u_long;
In addition to these, the following macro definitions are provided. Of these, `EOF' is usually defined in the operating system header files. The other macros are not always present.

  #define EOF (-1)
#define EOL `\n'
#define EOS `\0'
If a definition already exists for any of these macros, it will be assumed that the existing definition is correct, and the macro not redefined.

If a preprocessor adhering to the ANSI standard is used by a compiler, the symbol `__STDCPP__' will be defined. This will either be defined explicitly by the make environment, or defined following checks for a number of macros used by different compilers to indicate that an ANSI preprocessor is being used. If you need to write a preprocessor macro differently based on whether an ANSI preprocessor is used, you need only check for the single symbol `__STDCPP__'. For example:

  #ifdef NDEBUG
#define OTCLIB_ASSERT(ex) ((void)0)
#else
#if defined(__STDCPP__)
#define OTCLIB_ASSERT(ex) \
((void)((ex)||(otclib_error_stop_here(), \
otclib_assert(__FILE__,__LINE__,#ex),0)))
#else
#define OTCLIB_ASSERT(ex) \
((void)((ex)||(otclib_error_stop_here(), \
otclib_assert(__FILE__,__LINE__,"ex"),0)))
#endif
#endif

4 Naming Conventions

Names of all classes, structs, templates, enums and typedefs are prefixed so as to identify the class library they come from. The prefixes consist of three letters, with an underscore separating the prefix from the class name. The prefixes for each of the libraries being `OTC', `OUX' and `OTK'. For example:

  class OTC_String;
template<class T> class OTC_Set<T>;
Where there is a special category of classes in a library, the prefix is extended so as to clearly identify that group of classes. For example, in the OTCLIB library the `OTCERR' prefix identifies exception classes and the `OTCEV' prefix indentifies event classes. For example:

  class OTCERR_PreconditionFailure;
class OTCEV_IOEvent;
The prefix is also extended for the case of macros, constants and enum values. In these cases the full name of the library is used as the prefix, i.e., `OTCLIB', `OUXLIB' and `OTKLIB'. For global functions the same extended prefix is used, except that lower cases characters are used. For example:

  enum OTC_Direction
{
OTCLIB_FORWARD,
OTCLIB_BACKWARD
};
All member functions of classes, structs and templates commence with a lower case letter. The start of any subsequent word in the name of the class commences with an upper case letter. No underscores are used in member function names. For example:

  OTC_List<int> list;
list.addLast(42);

5 Header File Organisation

Header files for each library are located under separate directories. Headers files for a specific library are further divided corresponding to the function performed by the C++ classes or functions which the header file describes. The directories which exist for each library are:

  OTC/misc
OTC/ansi
OTC/ostore
OTC/debug
OTC/memory
OTC/refcnt
OTC/collctn
OTC/text
OTC/options
OTC/files
OTC/program
OTC/dispatch

OUX/files
OUX/system
OUX/program
OUX/dispatch

OTK/dispatch
Names of directories and header files are such that they will work for both UNIX, DOS and OS/2. If you develop under UNIX, but your code must be portable to DOS and OS/2, you must include header files from the directories given above. If you are using UNIX exclusively, and do not expect to use versions of UNIX where you would be restricted to 14 character filenames, you can make use of special header files which are provided. These header files are named corresponding to the name of the C++ class they describe. For example, to be portable, to include the `OTC_String' you should use:

  #include <OTC/text/string.hh>
If only using UNIX, you can instead use:

  #include <OTC/String.hh>
Header files named corresponding to the class they describe, are provided for all the major C++ class. The name of the header file can be derived by dropping the three character library prefix and underscore from the name of the class.

6 Using the Libraries from Makeit

To use the C++ libraries from makeit, you must list `ose' in the MODULES variable. By default, only the OTCLIB and OUXLIB libraries will be linked in. The libraries linked in will be those corresponding to what the VARIANT variable has been defined to, or if not defined, what the DEFAULTVARIANT variable was set to when OSE was installed. If you wish to link in a version of the libraries, different to the variant in which you are working, you can define the OSE_VARIANT variable. For example:

  OSE_VARIANT := opt
This will force optimised versions of the libraries to be linked with your programs even if the VARIANT variable had been defined to `dbg'. The only exception to this will be when you are working in the `prf' variant. When working in the `prf' variant, the versions of the libraries containing profiler information will always be used.

If you want the OTKLIB library to be linked with your program, in addition to the OUXLIB and OTCLIB libraries, you must list `otklib' in the OSE_OPTIONS variable. As the OTKLIB library requires TCL/TK and X Windows, you will also need to list `tcl' and `xwindows' in the MODULES variable. If you forget to do this, makeit will generate a diagnostic reminding you to do so.

When the libraries are linked, the `-L' and `-l' option will be used to inform the linker where the libraries are located. If your system supports shared libraries, this will result in the shared versions of the libraries being used. If you wish to force the use of the static libraries you should list `use_static_libraries' in the OSE_OPTIONS variable. Linking of the static libraries is forced by supplying an absolute pathname to the libraries to the linker, instead of the options above.

When ObjectStore is being used `-L$(OS_ROOTDIR)/lib' and `-los' options will automatically be supplied to the linker. If using any of the other libraries supplied with ObjectStore you will need to list them in the LDLIBS variable in your makefile.