OS/2 Shareware BBS: 10 Tools/10-Tools.zip/cset21v5.zip/TOOLKT21/SC/SOMOBJ.SC

Text File | 1993-05-03 | 11KB | 244 lines

# This file was generated by the SOM Compiler.
# FileName: somobj.sc.
# Generated using:
#     SOM Precompiler spc: 1.22
#     SOM Emitter emitcsc: 1.10

--  SOMObject: System Object Model root class
--  Copyright (c) International Business Machines Corporation
--                1991, 1992

class: SOMObject,
    external stem = somob, function prefix = somo_, major version = 1,
    minor version = 1, file stem = somobj;

    --  This is the SOM root class, all SOM classes must be descended from
    --  <SOMObject>. <SOMObject> has no instance data so there is no
    --  per-instance cost to to being descended from it.


release order:
    somInit, somUninit, somFree,
    somMissingMethod, somGetClassName, somGetClass,
    somIsA, somRespondsTo, somIsInstanceOf,
    somGetSize, somDumpSelf, somDumpSelfInt,
    somPrintSelf, somFreeObj, somDispatchV,
    somDispatchL, somDispatchA, somDispatchD;

methods:
group: InitTerm;

    --  Initialization / Termination group

    void    somFree();

    --  Releases the storage associated with <self>, assuming that <self>
    --  was created by <somNew> (or another class method that used
    --  <somNew>).  No future references should be made to <self>.  Will
    --  call <somUninit> on <self> before releasing the storage.
    --
    --  This method must only be called on objects created by <somNew> (see
    --  the definition of <somClass>) and never on objects created by
    --  <somRenew>.
    --
    --  It should not be necessary to override this method. (Override
    --  <somUninit> instead.)

    void    somInit();

    --  Initializes <self>.  As instances of <SOMObject> do not have any
    --  instance data there is nothing to initialize and you need not call
    --  this method.  It is provided to induce consistency among
    --  subclasses that require initialization.
    --
    --  <somInit> is called automatically as a side effect of object
    --  creation (ie, by <somNew>).  If this effect is not desired, you
    --  can supply your own version of <somNew> (in a user-written metaclass)
    --  which does not invoke <somInit>.
    --
    --  When overriding this method you should always call the parent class
    --  version of this method BEFORE doing your own initialization.

    void    somUninit();

    --  Un-initializes self.  As instances of <SOMObject> do not have any
    --  instance data there is nothing to un-initialize and you need not
    --  call this method.  It is provided to induce consistency among
    --  subclasses that require un-initialization.
    --
    --  Use this method to clean up anything necessary such as dynamically
    --  allocated storage. However this method does not release the actual
    --  storage assigned to the object instance. This method is provided as
    --  a complement to <somFree> which also releases the storage
    --  associated with a dynamically allocated object. Usually you would
    --  just call <somFree> which will always call <somUninit>. However, in
    --  cases where <somRenew> (see the definition of <SOMClass>) was used
    --  to create an object instance, <somFree> cannot be called and you
    --  must call <somUninit> explicitly.
    --
    --  When overriding this method you should always call the parentclass
    --  version of this method AFTER doing your own un-initialization.

group: Access;

    SOMClass *   somGetClass();

    --  Returns this object's class object.

    zString    somGetClassName();

    --  Returns a pointer to this object's class's name, as a NULL
    --  terminated string.
    --
    --  It should not be necessary to override this method as it just
    --  invokes the class object's method (<somGetName>) to get the name.

    integer4    somGetSize();

    --  Returns the size of this instance in bytes.

group: Testing;

    int    somIsA(SOMClass *aClassObj);

    --  Returns 1 (true) if <self>'s class is a descendent class of
    --  <aClassObj> and 0 (false) otherwise.  Note: a class object is
    --  considered to be descended from itself for the purposes of this
    --  method.

    int    somIsInstanceOf(SOMClass *aClassObj);

    --  Returns 1 (true) if <self> is an instance of the specified
    --  <aClassObj> and 0 (false) otherwise.

    int    somRespondsTo(IN somId mId);

    --  Returns 1 (true) if the indicated method is supported by this
    --  object's class and 0 (false) otherwise.

group: Dynamic;

    --  These methods make it easier for very dynamic domains to bind to
    --  the SOM object protocol boundry.
    --
    --  These methods determine the appropriate method procedure and then
    --  call it with the arguments specified.  The default implementation
    --  of these methods provided in this class simply lookup the method by
    --  name and call it.  However, other classes may choose to implement
    --  any form of lookup they wish.  For example, one could provide an
    --  implementation of these methods that used the CLOS form of method
    --  resolution. For domains that can do so it will generally be much
    --  faster to invoke their methods directly rather than going through a
    --  dispatch method.  However, all methods are reachable through the
    --  dispatch methods.  SOM provides a small set of external procedures
    --  that wrap these method calls so that the caller need never do method
    --  resolution.
    --
    --  These methods are declared to take a variable length argument list,
    --  but like all such methods the SOM object protocol boundry requires
    --  that the variable part of the argument list be assembled into the
    --  standard, platform-specific, data structure for variable argument
    --  lists before the method is actually invoked.  This can be very
    --  useful in domains that need to construct the argument list at
    --  runtime. As they can invoke methods without being able to put the
    --  constructed arguments in the normal form for a call.  This is
    --  helpful because such an operation is usually impossible in most
    --  high level languages and platform-specific assembler language
    --  routines would have to be used.
    --
    --  Note: It was decided to have different methods for different return
    --  value shapes. This avoids the memory mangement problems that would
    --  arise in some domains if an additional parameter was required to
    --  carry the return value.
    --
    --  Note: SOM does not support return values except for the four
    --  families shown below. Within a family (such as integer) SOM only
    --  supports the largest member.

    void    somDispatchV(INOUT somId methodId,
        INOUT somId descriptor,
        ...);

    --  Does not return a value.

    integer4    somDispatchL(INOUT somId methodId,
        INOUT somId descriptor,
        ...);

    --  Returns a 4 byte quanity in the normal manner that integer data is
    --  returned. This 4 byte quanity can, of course, be something other
    --  than an integer.

    void *   somDispatchA(INOUT somId methodId,
        INOUT somId descriptor,
        ...);

    --  Returns a data structure address in the normal manner that such data is
    --  returned.

    float8    somDispatchD(INOUT somId methodId,
        INOUT somId descriptor,
        ...);

    --  Returns a 8 byte quanity in the normal manner that floating point
    --  data is returned.

group: Development;

    --  The methods in this group are provided to support program
    --  development.  They have been defined in such a way that most
    --  development contexts will find them easy to expoit. However, some
    --  contexts may need to customize their I/O facilities. We have
    --  attempted to allow this customization in a very portable manner,
    --  however not all contexts will be able to perform the customization
    --  operations directly because they require passing function
    --  parameters. We chose this approach because it allows great
    --  platform-neutral flexibility and we felt that any provider of
    --  development support would find it reasonable to provide the
    --  customizations necessary for her/his specific development
    --  environment.
    --
    --  The chosen approach relies on a character output routine.  An
    --  external variable, <SOMOutCharRoutine>, points to this routine.  The
    --  SOM environment provides an implementation of this routine that should
    --  work in most development environments (it writes to the standard output
    --  stream).  A development context can, however, assign a new value to
    --  <SOMOutCharRoutine> and thereby redefine the output process.  SOM
    --  provides no special support for doing this assigment.

    SOMObject *   somPrintSelf();

    --  Uses <SOMOutCharRoutine> to write a brief string with identifying
    --  information about this object.  The default implementation just gives
    --  the object's class name and its address in memory.
    --  <self> is returned.

    void    somDumpSelf(int level);

    --  Uses <SOMOutCharRoutine> to write a detailed description of this object
    --  and its current state.
    --
    --  <level> indicates the nesting level for describing compound objects
    --  it must be greater than or equal to zero.  All lines in the
    --  description will be preceeded by <2*level> spaces.
    --
    --  This routine only actually writes the data that concerns the object
    --  as a whole, such as class, and uses <somDumpSelfInt> to describe
    --  the object's current state.  This approach allows readable
    --  descriptions of compound objects to be constructed.
    --
    --  Generally it is not necessary to override this method, if it is
    --  overriden it generally must be completely replaced.

    void    somDumpSelfInt(int level);

    --  Uses <SOMOutCharRoutine> to write out the current state of this object.
    --  Generally this method will need to be overridden.  When overriding
    --  it, begin by calling the parent class form of this method and then
    --  write out a description of your class's instance data. This will
    --  result in a description of all the object's instance data going
    --  from its root ancestor class to its specific class.

#include <somcls.sc>