OS/2 Shareware BBS: 8 Other

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 8 Other / 08-Other.zip / SOMINF.ZIP / SOMSOM.INF (.txt) < prev next >

Wrap

OS/2 Help File | 1992-05-13 | 34KB | 1,189 lines

ΓòÉΓòÉΓòÉ 1. Background ΓòÉΓòÉΓòÉ o OOP is increasingly recognized as an important new programming technology - It offers expanded opportunities for software reuse and extensibility. - Improved programmer productivity when compared to conventional software development paradigms. o Different languages emphasize different aspects of OOP - Objects from one language may not be usable in another - Language boundaries become barriers to interoperability o Benefits of OOP can be appealing, but commitment to a single language can cause a closed system. o System Object Model (SOM) is IBM's answer to this set of problems ΓòÉΓòÉΓòÉ 2. Introduction to SOM ΓòÉΓòÉΓòÉ o SOM is an object oriented programming interface for building and manipulating software objects. - SOM is language neutral - Users of a SOM class can create a subclass that may or may not be written in the same language as the base class o With SOM the only details available to the clients are those published by the implementer. o SOM permits changes to implementation details without causing the client to be re-compiled - Add new methods - Add, change or delete unpublished instance variables - Insert new classes into the class hierarchy - Relocate methods upward in the class hierarchy. o SOM provides method resolution designed to co-exist with current OOP languages - Offset resolution o Roughly equivalent to the C++ virtual function concept. o Implies a static scheme for typing objects with polymorphism based strictly on class inheritance. - Name resolution o Similar to that employed by Smalltalk and Objective-C o Supports untyped (dynamically typed) access to objects, with polymorphism based on the actual protocols that objects honor. - Dispatch function resolution o Unique feature to SOM that permits method resolution to be based on arbitrary rules known only in the domain of the receiving object o Languages that require special entry or exit sequences are good candidates for using this feature o The implementer decides whether to support offset or name resolution for methods in a SOM class o Clients of SOM classes may also make choices about method resolution - If the implementer has selected offset resolution, the client may make use of any of the three method resolution techniques. - If the implementer has selected name resolution, clients may use name or dispatch function resolution. - If the implementer supports only dispatch function resolution, the clients are confined to use this as well. o Programmers may use SOM in two ways - If using a native OOP language (eg. C++ or Smalltalk), SOM may be used to front end the native language. - If using a language with no object model (eg. C), SOM can be used to create a full object oriented language. ΓòÉΓòÉΓòÉ 3. The SOM development process ΓòÉΓòÉΓòÉ o Development begins with a class definition o Public definition of a SOM class is given in a formal specification language that is independent of the language to be used for implementation. o The more complete specification would be provided in a language specific form. o The development process begins with development of a <filename>.CSC file that defines the class with its data and methods. o The SOM compiler creates a more public file, the <filename>.SC file that contains all class definitions except any methods, data or implementation details that are declared to be private. o The SOM compiler processes the class specification and provides the binding files that allow SOM to be used with the implementation language (currently only 'C'). o The bindings for 'C' come in the form of macros and functions that are included in the source program and subsequently compiled by the 'C' compiler. ΓòÉΓòÉΓòÉ 4. SOM Object Interface Definition Language (OIDL) ΓòÉΓòÉΓòÉ o Provides the basis for generating the bindings files that enable programming languages to provide and use SOM objects. o OIDL extensions for the 'C' language - Public header file for programs that use a class. Use of a class includes instantiating objects, calling object methods and sub-classing to create new classes. - Private header file that provides bindings to private methods (if any). - An implementation header file for use by the class implementer. - An implementation template which is the source code framework. - A language neutral public definition file. - A language neutral definition file that contains the private parts of the class interface. - An OS/2 .DEF file that can be used to package the object as a DLL. o OIDL files may contain the following sections - Include section (R) - Class section (R) - Release Order section (O) - Metaclass section (O) - Parent Class section (R) - Passthru section (O) - Data section (O) - Method section (O) ΓòÉΓòÉΓòÉ 5. Notes on SOM usage ΓòÉΓòÉΓòÉ o Environment variables needed by the SOM compiler - SMINCLUDE tells the compiler where to find included class definitions (eg. .SC files). This is similar to the INCLUDE environment variable. - SMEMIT indicates to the compiler which emitter programs should be executed. Each item designates a file type to be created by the compiler: SET SMEMIT=H;IH;SC;DEF This item may be overridden by the -s "string" compiler switch. - SMTMP specifies the path where the compiler is to create intermediate files. If no value is specified, the SOM compiler will default to the root of the current drive; o SOM bindings for 'C' - Three of the files created by the SOM compiler can be considered as 'C' language binding files o <class stem>.H is the public usage header file that must be included by a 'C' program in order to make use of the class object. o <class stem>.PH is the private usage binding file. This file must be included in a source module in order to reference the private parts of the class. o <class stem>.IH is the implementation header file. This file must be included in the source file that implements the class. This file will include the .PH file if one exists, or will include the .H file. - In addition the SOM compiler can create or update the <class stem>.C file that contains the class implementation. o Using a class and its objects - Declaring object variables - sizes of SOM objects are NOT known at compile time. Therefore it is NEVER correct to create an object like: <class> obj; instead, always create a pointer to the object: <class> *obj; - Instances are usually created by the <class>New() macro: <class> *obj = <class>New(); However, there may be times when it is necessary to pre-allocate space, then create objects in that space. This may be accomplished by using the <class>Renew() macro: <class> *obj = <class>Renew( buffer ); where buffer is a pointer to the allocated space. o Methods and private instance data are reference by: _<method>( <targetObject> ) or _<variable> o Public instance variables can be referenced by: get_<variable>( <targetObject> ); o Parent methods may be accessed by: parent_<method>( <targetObject> ); o Debugging Facilities - <class name>MethodDebug() is a macro generated as part of the method stubs created by the SOM compiler. It takes as arguments, a class name and a method name and is actuated by setting the SOM_TraceLevel variable to 1 or 2. - SOM_Test() takes an arbitrary Boolean expression as an argument. If the expression evaluates to TRUE, execution continues; otherwise SOM_Error is invoked with a warning-level error code. This macro is actuated by setting the SOM_WarnLevel variable to 1 or 2. - SOM_WarnMsg() takes a string as input and writes the string if SOM_WarnLevel is set to a 1 or 2. - SOM_Assert() allows assertions to be placed in the code. It takes as input a Boolean expression and an error code. If the expression evaluates to FALSE, SOM_Error is called with the error code. - SOM_Expect() is similar to SOM_Assert, except that it takes only a Boolean expression as input. If the expression evaluates to false, SOM_WarnMsg is invoked to produce a warning message. - In addition to the above SOM automatically performs basic validity checking at runtime for SOM method invocations. Once the code has been tested thoroughly, this checking may be removed by placing #define SOM_NoTest in the source file prior to the include of the .IH file. Note: On any of the above where a value may be set to 1 or 2, setting the value to 2 will cause any methods provided by SOM to produce error or tracing messages. o Customization features - Memory management functions - SOM provides a subset of the ANSI 'C' memory functions: SOMCalloc, SOMFree, SOMMalloc, SOMRealloc These methods may be overridden for specialized processing. It is recommended that, if any of these methods are overridden, they are ALL replaced. - SOM provides three DLL management functions: SOMLoadModule SOMClassInitFuncName SOMDeleteModule These methods may need to be overridden if it is intended to package more than one class in a single DLL. - The default SOM character output function simply takes a character as input, and writes the character to STDOUT. This can be replaced if it is wished to record the output in a log file, display a messagebox, etc. This is accomplished by writing the output function, then setting the SOMOutCharRoutine variable to the address of your function. - SOMError is the default error handling function. This function may be overridden in order to record errors in a way more approriate to your application, attempt application level recovery by restarting at a known point, etc. ΓòÉΓòÉΓòÉ 6. SOM Classes ΓòÉΓòÉΓòÉ ΓòÉΓòÉΓòÉ 6.1. SOMObject: base class to all SOM objects ΓòÉΓòÉΓòÉ Class: SOMObject Parent: <none> Metaclass: SOMClass File stem SOMOBJ Definition: SOMOBJ.SC Header file: SOMOBJ.H (always included from SOM.H) Description: SOMObject is the root class for all SOM classes. It defines the essential behavior common to all SOM objects. As SOMObject has no instance data, it contributes nothing to the size of derived classes. Notes on subclassing: All SOM classes are expected to derive from SOMObject. Three methods would typically be overridden by any subclass that has instance data-somInit, somUninit, and somDumpSelfInt. See the descriptions of these methods for further information. New methods: [Initialization/Termination Group] somFree somInit somUninit [Access Group] somGetClass somGetClassName somGetSize [Testing Group] somIsA somIsInstanceOf somRespondsTo [Dynamic Group] somDispatchA somDispatchD somDispatchL somDispatchV [Development Support Group] somDumpSelf somDumpSelfInt somPrintSelf Inherited methods: None Overridden methods: None ΓòÉΓòÉΓòÉ 6.2. SOMClass: root class for all SOM metaclasses. ΓòÉΓòÉΓòÉ Class: SOMClass Parent: SOMObject Metaclass: SOMClass (only class with itself as metaclass) File stem SOMCLS Definition: SOMCLS.SC Header file: SOMCLS.H (always included from SOM.H) Description: SOMClass is the root class for all SOM metaclasses. It defines the essential behavior common to all SOM classes, In particular, it has two generic methods for manufacturing object instances (somNew and somRenew), and a suite of methods for constructing classes. It also has methods that can be used to dynamically obtain (or augment) information about a class and its methods at run time. Notes on subclassing: All SOM classes are expected to have SOMClass or a class derived from SOMClass as their metaclass. Metaclasses define "class" methods (sometimes called "factory" methods or "constructors") that can be used to manufacture objects of any class for which they are the metaclass. If you wish to define your own class methods for your objects, or impart specialized behavior to the generic class methods supplied in SOMClass, you will need to define your own metaclass by subclassing SOMClass or one of its other subclasses. Three methods that SOMClass inherits and overrides from SOMObject would typically be overridden by any metaclass that has instance data - somInit, somUninit, and somDumpSelfInt. See the descriptions of these methods in SOMObject for further information. The new methods introduced in SOMClass that might frequently be overridden are somNew, somNewNoInit, somRenew, somRenewNoInit, and somClassReady. Other reasons that you may want to create your own metaclass include tracking object instances, automatic garbage collection, interfacing to a persistent object store, or providing/managing information that is global to a set of object instances. New methods: [Initialization/Termination Group] somAddStaticMethod somClassReady somInitClass somOverrideSMethod [Instance Creation (Factory) Group] somNew somNewNoInit somRenew somRenewNoInit [Access Group] somGetApplyStub somGetClassData somGetClassMtab somGetInstanceOffset somGetInstancePartSize somGetInstanceSize somGetName somGetNumMethods somGetNumStaticMethods somGetParent somGetPClsMtab somSetClassData [Testing Group] somCheckVersion somDescendedFrom somSupportsMethod [Dynamic Group] somFindMethod somFindMethodOk Inherited methods: somDispatchA somDispatchD somDispatchL somDispatchV somDumpSelf somFree somGetClassName somGetClass somGetSize somIsA somIsInstanceOf somPrintSelf somRespondsTo Overridden methods: somDumpSelfInt somInit somUninit ΓòÉΓòÉΓòÉ 6.3. SOMClassMgr: runtime registry for all SOM class objects. ΓòÉΓòÉΓòÉ Class: SOMClassMgr Parent: SOMObject Metaclass: SOMClass File stem SOMCM Definition: SOMCM.SC Header file: SOMCM.H (always included from SOM.H) Description: One instance of SOMClassMgr is created during SOM initialization. It acts as a run-time registry for all SOM class objects that have been created or dynamically loaded by the current process. Each SOM class automatically registers itself with the SOMClassMgr instance (pointed to by the global variable, SOMClassMgrObject) during the final stage of its initialization. Notes on subclassing: You can subclass SOMClassMgr to augment the functionality of its registry (to make it persistent, for example, or to coordinate the name of a class with the location of its code in the file system). If you want your subclass to replace the SOM-supplied SOMClassMgrObject, you can use the somMergeInto method to place the existing registry information from SOMClassMgrObject into your new class-manager object as a final step in the creation of an instance of your subclass. The former SOMClassMgrObject is then freed, and the address of your new class manager is placed in this global variable. New methods: [Basic Functions Group] somLoadClassFile somLocateClassFile somRegisterClass somUnloadClassFile somUnregisterClass [Access Group] somGetInitFunction [Dynamic Group] somClassFromId somFindClass somFindClsInFile somMergeInto Inherited methods: somDispatchA somDispatchD somDispatchL somDispatchV somDumpSelf somFree somGetClass somGetClassName somGetSize somIsA somIsInstanceOf somPrintSelf somRespondsTo Overridden methods: somDumpSelfInt somInit somUninit ΓòÉΓòÉΓòÉ <hidden> Include Section ΓòÉΓòÉΓòÉ This section contains an include statement that is a directive to the OIDL preprocessor telling the compiler where to find the class interface definition for this class' parent class, the class' metaclass if the class specifies one, and the private interface files for any ancestor class for which this class overrides one or more of its private methods. Note: The include statements must appear in the order shown below. In addition, the ancestor include statements must be in inheritance order (from the root down). The syntax for an include statement is: [#include ( <ancestor> | "ancestor" )]* #include ( <parent> | "parent" ) [#include ( <metaclass> | "metaclass" )] Example: #include "barfile.sc" #include "foofile.sc" #include <metafile.sc> where: <ancestor> [optional] is the name of the OIDL file containing the private part of an ancestor class' interface needed in the definition of this class. <parent> [required] is the name of the OIDL file containing the parent class of the class for which the include statement is provided. <metaclass> [optional] is the OIDL file containing the metaclass of the class for which the include statement is provided. ΓòÉΓòÉΓòÉ <hidden> Class Section ΓòÉΓòÉΓòÉ This required section introduces the class, giving its name, attributes, and optionally a description of the class as a whole. The syntax for a class statement is: class: name [, file stem = stem] [, external stem = stem] [, function prefix = prefix | , external prefix = prefix] , classprefix = prefix] [, major version = number] [, minor version = number] [, global | local]; [, classinit = function]; [description] Example: class: Foo, local, file stem = foofile, external prefix = xx_, major version = 1, minor version = 3; -- This is the Foo class. It does nothing. where: <name> [required] is the name for this class. file stem = stem [optional] is an attribute that specifies how the compiler is to construct file names for various generated files. The constructed file names will all begin with stem. Note: This value is also used as the class library name in any generated .DEF file. This attribute defaults to the name of the file containing the class-interface definition. external stem = stem [optional] is an attribute that governs the formation of external names that appear in the text of the generated output files. On some systems, external names are limited in length to a small number of characters. The SOM Compiler uses the value stem as the basis for generating short external names. A suffix is appended to stem for each external name. Because OS/2 2.0 external names may be up to 255 characters in length, short external names are generally not used. This attribute defaults to the same value given (or defaulted) by file stem. function prefix = prefix [optional] is an attribute that directs the compiler to construct method function names by prefixing method names with prefix. For example, function prefix = xx_ would result in a function name of xx_foo for a method called foo. Note: It is an error to specify both function prefix and external prefix as attributes of the same class. This attribute has no default. external prefix = prefix [optional] is an attribute that is similar to function prefix except this attribute will also cause each method function to be an external name, whereas method functions usually are local to the module in which they are defined. Making method functions external can be useful in development environments whose debuggers have difficulty dealing with local procedures. Note: It is an error to specify both external prefix and function prefix as attributes of the same class. This attribute has no default. classprefix = prefix [optional] is similar to the function prefix attribute, but applies only to methods that have the class attribute. If you use the class attribute (for any methods in the current class definition), you are required to supply a classprefix value within the class statement. This attribute has no default. major version = number [optional] is an attribute that specifies the major version number of this class definition. Number must be in the range of 0 to (2**31)-1. This will produce bindings that will verify that any code that purports to implement this class has the same major version number, unless number is 0, in which case no test is made. This attribute defaults to major version = 0. minor version = number [optional] is an attribute that specifies the minor version number of this class definition. Number must be in the range of 0 to (2**31)-1. This will produce bindings that will verify that any code that purports to implement this class has the same or higher minor version number, unless number is 0, in which case no test is made. This attribute defaults to minor version = 0. global | local [optional] is an attribute that indicates how binding files are to be linked together. Local means link to other files in the local context first. Global means bypass the local context. For example, local will result in C-language statements like: #include "file.h" Global will result in statements like: #include <file.h> This attribute defaults to global. classinit = function [optional] allows you to provide user-written code that participates in the construction of your class. function designates a function you supply that is called when your class is created. This function receives one argument; a pointer to your newly created class object. You can use this function to perform any supplemental processing that you need. If you specify this attribute in your class definition, a template for this function will be provided automatically in the generated .C file. By default, your class will not have a user-written classinit function. description [optional] is a description of the class as a whole and must be in the form of a comment. Several comment styles are supported including: /* * line1 * line2 */ -- line 1 (starts with 2 consecutive dashes) -- line 2 // line 1 // line 2 Because OIDL files are used to generate language bindings, comments must be strictly associated with particular syntactic elements, so they will appear at the appropriate points in the output files. Therefore, comments must be placed in OIDL files with more care than in some programming languages. If you do not place your comments with strict adherence to the OIDL section syntax, the comments probably will not appear where you expect to see them. A fourth style for OIDL comments is referred to as throw-away comments. They may be placed anywhere in an OIDL file, because they are not intended to appear in any binding files. Throw-away comments start with the character (#) and end at the end of the line. You can use throw-away comments to "comment-out" sections of an OIDL file. # # This is an example of a throw-away comment # Note: Comments will appear in files produced by the SOM Compiler in various forms appropriate to the intended use of the file. Sometimes these files are intended as input to a programming- language compiler. Therefore, it is best to avoid using characters in the body of comments that are not generally allowed in most programming-language comments. For example, the C language does not allow "*/" to occur in a comment, so its use is to be avoided. Refer to SOM Compiler Command Syntax for information about the effect of global attributes on OIDL comments. ΓòÉΓòÉΓòÉ <hidden> Release Order Section ΓòÉΓòÉΓòÉ This optional section contains a release order statement that forces the compiler to build certain critical data structures with their items arranged in the order specified. This allows the class interface and implementation to be evolved without requiring programs that use this class be recompiled. Release order applies to all method names and public or private (that is, non-internal) data items. If the release order of some method or non-internal data item is not specified, it will default to an implementation-specific order based on its occurrence in the OIDL file. The introduction of new public or private data items or methods might cause the default ordering of other public or private data items or methods to change; programs using the class would then need to be recompiled. The SOM Compiler has a "pretty print" mode in which it will reproduce a class definition in a nicely formatted manner with release order specified for all relevant items. Programmers are advised to use this facility to update the release order statement whenever they make significant additions to a class. The syntax for a release order statement is: release order: name [, name ]* ; Example: release order: m1, m2, pd1, m3; where: name [, name ]* [optional] contains all method names introduced by this class (whether public or private), and the names of any non-internal instance variables. It must not contain the names of any inherited methods (even if they are to be overridden), except as noted below. As the class evolves, new names can be added to the end of this list, but once a name is on this list, it must not be reordered or removed. Doing either will require the recompilation of programs that use this class. If a method named on the list is to be moved up in the class hierarchy (for example, to the parent class of this class), its name should remain just as it is on the current list, but it also must be added to the release-order list for the class that will now introduce it. ΓòÉΓòÉΓòÉ <hidden> Metaclass Section ΓòÉΓòÉΓòÉ This optional section specifies the class' metaclass, giving its name and, optionally, a description of the reason for the metaclass, or other comments about its role in this class' interface. If a metaclass is specified, its definition must be included in the include section. If no metaclass is specified, the metaclass of this class' parent class will be used. Therefore, if you intend the metaclass of this class' parent class to be used, it is generally best not to specify the metaclass. A class' metaclass can also be implicitly defined through the use of the class attribute in the data section or the class attribute in the method section. If you use either of these attributes you must bypass (that is, omit) the metaclass section altogether. In this case, your implied metaclass will be a subclass of the metaclass of your parent class. The syntax for a metaclass description statement is: metaclass: name; [description] Example: metaclass: FooMeta; /* * This is the metaclass for the Foo class. * Note that several forms of comment are allowed. */ where: name [optional] is the name of the metaclass to be used to create the class object for this class. This attribute defaults to the parent's metaclass. description [optional] is a description of the metaclass and must be in the form of a comment (see Class Section for the discussion about comment styles). Note: You can add the attributes major version, minor version, file stem, and global | local to the metaclass statement. If you include at least file stem, you do not have to include the metaclass definition in the include section. ΓòÉΓòÉΓòÉ <hidden> Parent Section ΓòÉΓòÉΓòÉ This required section specifies the class' parent class, giving its name and, optionally, a description of the role of the parent class in this class' interface. The syntax for a parent class description statement is: parent [class]: name; description Example: parent: SOMObject; // Foo will be directly descended from the SOM root class, SOMObject. // Note, this is yet another style of comment. where: name [required] is the name of the class of which this class is a subclass. description [optional] is a description of the parent class and must be in the form of a comment (see Class Section for the discussion about comment styles). Note: You may add the attributes major version, minor version, file stem, and global | local to the parent class statement. ΓòÉΓòÉΓòÉ <hidden> Passthru Section ΓòÉΓòÉΓòÉ This optional section provides blocks of code to be passed by the compiler into various binding files. The contents of the passed lines are essentially ignored by the compiler and can contain anything that needs to be placed near the beginning of a binding file. Note: Even comments contained in passthru lines are processed without modification. The syntax for the passthru section is: [passthru: language.suffix, [ before | after ]; line 1 line 2 .. line n endpassthru; [description]]* Example: passthru: C.h: typedef int *foobar; #define SIZE 89 endpassthru; -- The two lines above will be placed in the public binding file for -- all C language users of this class. Note: the next passthru clause -- has no comment. passthru: C.ih; static char *name; endpassthru; where: language [required] is the programming language whose binding files are to be affected. Currently only the C language is supported. In the future other languages might be supported. suffix [required] specifies which binding file is to be affected. For C, the currently supported binding files are: .H The binding file for all users of the class .PH The binding file for users with access to private methods of the class .IH The binding file for implementers of the class .C The program template file used in implementing the class .SC The language-neutral core version of the OIDL file .PSC Additional language-neutral information about the private methods in the class .CS2 A "pretty printed" version of the OIDL file Note: In general, you would not normally place passthru lines into a .C file, because a .C file is usually generated only once and then filled in with source code by a programmer. Subsequent updates to a .C file by the SOM Compiler consist only of the addition of new method templates at the end of the file. Place passthru lines needed by the class' implementation code in the .IH file instead. Because the .IH file can be completely regenerated each time the OIDL class definition is compiled, changes to your passthru lines will be automatically included. before | after [optional] is the attribute that indicates whether passthru lines should precede or follow any include statements at the beginning of the binding file. This attribute defaults to before. line [optional] is a line to be placed near the beginning of the binding file exactly as written. description [optional] is a description of the purpose of the passthru lines. ΓòÉΓòÉΓòÉ <hidden> Data Section ΓòÉΓòÉΓòÉ This optional section lists the instance variables for this class. This section is generally present only in the language-specific version of the class interface definition (a .CSC file). However, it must be present in the public form of the class interface definition if the class contains public instance variables. ANSI C syntax is used to describe these variables. The syntax for the data section is: data: [description1] [declaration [, private | , public | , internal] [, class]; [description2]]* Example: data: -- This is the instance data for the Foo class. int FooSize, public; -- FooSize is a public instance variable. This means that all users of -- the Foo class will have access to FooSize. char *fooName; -- fooName is a private instance variable; therefore, only the -- implementer of the Foo class will have access to it. where: description1 [optional] is a description of the instance data as a whole and must be in the form of a comment (see Class Section for the discussion about comment styles). declaration [optional] is an ANSI C declaration for an instance variable. private | public | internal is the attribute that controls the type of binding (if any) to be exported for the instance data item. Internal prevents any binding from being exported. Private causes the binding to be part of private-usage binding files, and public causes the binding to be placed in public-usage binding files. For C, the exported binding is a macro of the form get_name(obj), where name is the name of the instance data item, and obj is an object containing the item. The macro returns an expression representing the item, which may be used on the left- or right-hand side of assignment statements. This attribute defaults to internal. class is an attribute that designates that the data item belongs to an implicitly defined metaclass. Data items having this attribute do not appear in instances of the class, but instead appear in the class itself. Methods defined in the methods section to have the class attribute can be created to manipulate class items. If you use this attribute your class definition cannot also contain an explicit metaclass section. By default, data items are not considered as class data. description2 is an optional description of the instance variable and must be in the form of a comment (see Class Section for the discussion about comment styles). ΓòÉΓòÉΓòÉ <hidden> Methods Section ΓòÉΓòÉΓòÉ This optional section lists the methods to be supported by this class. ANSI C function-prototype syntax is used to define the calling sequence to each method. The syntax for the methods section is: methods: [description1] [[group: name; [description2]] [method prototype [, public | , private] [, method | , procedure] [, class] [, offset | , name lookup] [, local | , external] [, use = name]; [description3]]* [override: method name [, public | , private] [, class] [, local | , external] [, use = name]; [description4]]* Example: methods: -- This section lists all the methods that are to be -- introduced by the Foo class, as well as all the -- methods that Foo inherits and wants to override. void m1 (int parm1, char parm2); -- m1 is a public method with a fixed calling sequence. -- It does not return a value. int m2 (), private; -- m2 is a private method with no arguments (except -- for its target object) that returns an int. long m3 (int parm1), procedure; -- m3 will be a simple procedure. It cannot be overridden. -- It will still have a "somSelf" argument like any other method. group: g2; -- The rest of the methods listed in this section are -- in group "g2". int m4 (int numargs, ...); -- m4 is a public method that has one required argument -- and any number of additional arguments that can be -- of any types. override: somInit; -- This class will override the implementation of -- somInit that it inherits from one of its ancestor -- classes. override: m6, private; int m5 (int p1, /* first parameter */ int p2, /* second parameter */ char *p3 /* last parameter */); -- Note how comments can be embedded in the method -- prototype. where: description1 [optional] is a description of this class' methods as a whole and must be in the form of a comment (see Class Section for the discussion about comment styles). name [required in each group statement] is the name of this group. Currently, groups serve no purpose except to improve the readability of the object interface definition. description2 [optional] is a description of this group of methods as a whole and must be in the form of a comment (see Class Section for the discussion about comment styles). <method prototype> [required in each method specification] is the ANSI C function prototype that defines the calling sequence to this new method with the two exceptions below: 1. Even though the first parameter to each method is the target object, this object is not mentioned in the method prototype. 2. Each parameter can be preceded by one of, IN, INOUT, or OUT, indicating whether it is an input, input/output, or output parameter. Comments can occur after the separating comma between parameter specifications and after the last parameter, but before the closing parenthesis (see the declaration of m5 in the example above). public | private [optional] is an attribute that indicates to the compiler whether or not this method is part of the public interface to this class. There is no real difference between public and private methods, but the compiler will separate the bindings to these two classes of methods so that bindings for public methods can be distributed without distributing bindings for private methods. This attribute defaults to public. local | external [optional] is an attribute that directs the compiler to declare the method function for this method as an external name or as a local name (directly accessible only to the compilation unit in which it occurs). When specified, this attribute overrides the class default for method functions (see the descriptions for function prefix and external prefix under Class Section). This attribute defaults to the class default. This attribute has not been implemented at this time. use = name [optional] is an attribute that tells the compiler that the method function for this method is to have the name name. This overrides any class prefix specification. This attribute has no default. This attribute has not been implemented at this time. method | procedure [optional] is an attribute that indicates whether or not this method can be overridden by a subclass. If method is specified, the method will operate on instances of the class and can be overridden by a method in a subclass. If procedure is specified, the method will be a simple procedure. None of the normal method resolution mechanisms will be used in invoking the method procedure; it will be called directly. This attribute defaults to method. class is an attribute that specifies whether the method operates on instances or the class itself. If class is specified the method is considered to be associated with an implicit metaclass. In this case the method will operate directly on the class itself and not on its instances. This is a convenient way of defining constructors or factory methods that can be invoked when no object instances exist. The implicit metaclass is considered to be a subclass of the parent class' metaclass. If you use the class attribute you cannot also define an explicit metaclass section. In addition, you must also supply a classprefix value in the class statement (see Class Section). If this attribute is omitted, the method is assumed to operate on object instances rather than the class. offset | name lookup [optional] is an attribute that indicates the preferred invocation binding to be used for this method. Generally, methods are invoked on the basis of information provided by the class that introduces the method definition (called offset resolution). However, this requires that the class of the method's target object be known at compile time. Sometimes a method definition is introduced by several classes. For such methods, name lookup (which invokes the method using the method's name as a key) is a more appropriate choice. This attribute defaults to offset. description3 [optional] is a description of the method and must be in the form of a comment (see Class Section for the discussion about comment styles). method name [optional] is the name of a method introduced by an ancestor class that this class will re-implement. Attributes on an override method have the same meaning as previously stated for new methods. description4 [optional] is a description of the override method or of your reason for overriding it, or both, and must be in the form of a comment (see Class Section for the discussion about comment styles).