Schema Classes Polyhedra Ltd
Copyright notice This document is copyright 1994-2006 by Polyhedra Ltd. All Rights Reserved. This document contains information proprietary to Polyhedra Ltd. It is supplied in confidence and must not be used for any purpose other than that for which it was supplied. This document may not, in whole or in part, be copied, photocopied, reproduced, translated or reduced to any electronic medium or machine readable form without prior written consent from Polyhedra Ltd. Trademarks Polyhedra is a registered trademark of Polyhedra Ltd. Certain terms used in this document are trademarks: while these are not acknowledged as such in the text, this should in no way be construed as a challenge to that trademark status, or as an infringement of that status. Manual Details Manual title Schema Classes Document number manuals/schemacl Revision number 6.3.0 Revision Date 22nd June 2006 Software Version This documentation corresponds to the following version of the software: Version 6.3 i
PREFACE This document describes the Schema Classes library provided with Polyhedra. The Schema classes are a collection of predefined Control Language (CL) classes providing access to the CL schema. All the Schema classes are supported by the Control Language Client (CLC). A subset are also supported by the Real-Time Relational Database (RTRDB). This document is a reference manual and it is recommended that the reader should also read Polyhedra Overview, Polyhedra User's Guide and the appropriate Polyhedra component document prior to reading this manual. This manual should be used in conjunction with the Control Language Reference manual. This document is aimed at the application writer and therefore it is assumed that the reader is familiar with object-oriented concepts. The organisation of the document is as follows: Section 1 Overview of classes Section 2 How to use the manual Section 3 Description of Schema classes iii
CONTENTS 1. OVERVIEW OF CLASSES...1 2. USING THIS MANUAL...3 2.1 Class summary layout...3 2.2 Class description layout...4 3. SCHEMA CLASSES...5 Class...9 Library...11 Object...12 Property...13 Schema...15 Tables TABLE 1 - CLASS ATTRIBUTES...7 TABLE 2 - CLASS HANDLERS...7 TABLE 3 - LIBRARY ATTRIBUTES...7 TABLE 4 - OBJECT ATTRIBUTES...7 TABLE 5 - OBJECT HANDLERS...7 TABLE 6 - PROPERTY ATTRIBUTES...8 TABLE 7 - SCHEMA ATTRIBUTES...8 v
Schema Classes Overview of classes 1. Overview of classes Polyhedra Control Language (CL) includes a large number of pre-defined classes. These typically provide useful functions or access to certain operating system capabilities. They can be used either directly or as the superclass for deriving classes specific to an individual application. All pre-defined classes in CL operate in the same way, independent of platform; they have the same specification no matter what host operating system is being used to run Polyhedra. As a result, a graphical application developed in CL to run on UNIX system will run in the same way on, say, Microsoft Windows. This independence shields the application writer from the specific details of a particular platform and allows truly portable applications to be developed. The pre-defined CL classes may be supported by CL in the Real-time Relational Database or the Control Language Client (CLC). Pre-defined classes are divided into libraries. The following libraries are currently supported by Polyhedra: Utility Classes Schema Classes Communications Classes Utility classes add certain operating system capabilities to Polyhedra Control Language. Schema classes provide access to the definitions of all the classes loaded into a running system. Communication classes provide the ability to program UDP and TCP sockets in this way, the programmer is able to control communication to and from processes on local or remote machines. 1
Schema Classes Using this manual 2. Using this manual This manual is arranged with two purposes in mind. First, it is intended to provide a complete description of each class. It is also designed to be suitable as a quick reference guide. As a result, the material in Section 3 is presented in two parts. The first contains a summary of each class, with a brief account of the defined attributes and handlers. The second part holds a full description of the classes, including small samples of code where appropriate. 2.1 Class summary layout The class summaries are laid out in the following manner: Each class in the library is treated in alphabetical order. For each class, tables of attributes and advanced attributes are given, in the following format: Type Name Restrictions Default Page where: Type Name Restrictions specifies the type of the attribute. specifies the name of the attribute. specifies whether the attribute is get only, set only or both. If this field is blank, the attribute can be both written to and read from in CL. If the attribute can only be set, set only is specified and if the attribute can only be read, get only is specified. Default defines the default values of the attribute. Page specifies on which page a detailed description of the attribute is given. Advanced attributes are the same as any other attributes in terms of their implementation and use. They generally deal with advanced topics which an inexperienced user may not have encountered. Only experienced users are expected to use advanced attributes. The lists include attributes inherited from superclasses as well as those defined by the class itself. Those defined by the class are listed first, in alphabetical order. They are separated from the lists of inherited attributes by a thick double line as shown in the table below. Type Name Restrictions Default Page Attributes defined by this class. Attributes inherited from superclass. Attributes inherited from superclass' superclass 3
Using this manual Schema Classes The attribute tables are followed by a separate table of handlers, ordered in the same manner. The handler table has the following format: Type Format Restrictions Page where: Type Format Restrictions Page specifies the type of the return value of the handler, if the handler returns a value. defines the handler name and the types of any parameters it takes. states whether the handler definition can be redefined by derived classes or whether it is call only and cannot be redefined by derived classes. If this field is blank, the handler can be both redefined and called. specifies on what page a detailed description of the handler is given. 2.2 Class description layout The complete class descriptions follow the class summary tables. Each class description contains the following: 1. The class name (as the page title). 2. The word abstract, if the class is abstract. Abstract classes cannot be used directly, but only as a superclass for subclasses. 3. A brief description of the class. 4. An inheritance list if the class is derived. The list specifies the class and all superclasses in order of inheritance. 5. Attribute and advanced attribute details. 6. Handler details. Only those attributes and handlers defined in the class itself are described; inherited attributes and handlers are described in the details of the base class. The descriptions have the following format: attribute-name type attribute-name = default-value attribute description. handler-name type handler-name(parameters) handler description 4
Schema Classes Schema classes 3. Schema classes The Schema class library defines a number of CL pre-defined classes that provide access to the CL schema. The CL schema is a collection of objects representing the CL classes defined in the system. Every defined CL class has a corresponding object, a class object. This object has a set of attributes describing the class. For instance, a class object has a Name attribute whose value is the class name. These objects are instances of the class called Class. Class also has its own class object, which is itself an instance of the Class class. A diagram may be useful to illustrate this: Class Name SuperClass "Class" Null "A" Null "B" Figure 1: Class objects An class object also has an attribute called Properties. This is an array of references to objects of class type Property, each of which describes a property (i.e. an attribute or a handler) of the class. For example, a property object has a Type attribute referencing the class object describing the property's type. Other attributes exist and are described in detail later. The CL schema is accessible via a global variable called Schema referencing the Schema object (there is always one and only one Schema object in the system). The Schema object is an instance of the class called Schema. It has an attribute called Classes which is an array of references to class objects. The array holds descriptions of all the classes defined in the system. In summary, starting from the Schema object, it is possible to navigate through all the classes defined in CL, and to discover all the properties of any class. For example, consider the following code fragment which iterates over all the CL classes: local reference Class c repeat foreach c in Classes of Schema -- c now points to a class object -- Name of c references the name of the class end repeat CL also allows navigation from an object to its class definition. CL considers all classes to be derived from the class Object. The Object class has one attribute called class. This is a reference to the class object describing the object's class. 5
Schema classes Schema Classes The following function uses this information to detect whether the class of a particular object is derived from the class of another object. function Boolean IsDerivedFrom(Object o1, Object o2) local reference Class c set c to Class of o1 repeat while exists c if c = Class of o2 then return True set c to SuperClass of c end repeat return False end IsDerivedFrom Here is an updated diagram showing the complete arrangement of the CL schema: Schema Class Classes Class Name SuperClass "Class" "Object" Null "Schema" "Property" Figure 2: Class objects 6
Schema Classes Schema classes A summary of attributes and handlers for each class is shown below: Class 1 Type Name Restrictions Default Page String FileName get only 9 array of Object Instances get only 9 reference Library MyLibrary get only 9 String Name get only 9 Boolean Primitive get only 9 array of Property Properties get only 10 reference Class SuperClass get only 10 Table 1 - Class attributes Type Format Restrictions Page Integer GetInstanceCount( ) 9 Integer GetInstanceSize( ) 9 Table 2 - Class handlers Library 1 Type Name Restrictions Default Page String Name get only 11 array of Class Classes get only 11 Table 3 - Library attributes Object 1 Type Name Restrictions Default Page reference Class Class get only 12 Table 4 - Object attributes Type Format Restrictions Page Boolean InTransaction( ) 12 Boolean InError( ) 12 String ErrorText( ) 12 Table 5 - Object handlers 1 The Default field is left blank because instances of these classes cannot be created explicitly. 7
Schema classes Schema Classes Property 2 Type Name Restrictions Default Page Boolean Exported get only 13 String Filename get only 13 String Name get only 13 reference Class ParentClass get only 13 Integer PropertyType get only 14 reference Class Type get only 14 String Value get only 14 Table 6 - Property attributes Schema 2 Type Name Restrictions Default Page array of Class Classes get only 15 array of Library Libraries get only 15 Table 7 - Schema attributes 2 The Default field is left blank because instances of these classes cannot be created explicitly. 8
Schema Classes Class Class An instance of the Class class provides details about a single class defined in the system. All classes are included, even those that are not loaded. FileName String FileName FileName contains the name of the file on disk containing its definition. For predefined classes the value is an empty string. FileName is get only. GetInstanceCount Integer GetInstanceCount() GetInstanceCount returns the number of instances that currently exist for the class. This function is only supported in the Control Language Client (CL) GetInstanceSize Integer GetInstanceSize() GetInstanceSize returns the size of an individual object in bytes. This function is only supported in the Control Language Client (CL) Instances array of Object Instances Instances represents an array containing references to all instances of this class. Contents of the array cannot be modified directly. Instances is get only. This attribute is only supported in the Control Language Client (CL). MyLibrary reference Library MyLibrary MyLibrary contains a reference to the library where the class is defined and is get only. Name String Name Name contains the name of the class. It is get only. 9
Class Schema Classes Primitive Boolean Primitive Primitive is get only. It indicates whether the type is primitive or a class. A value of True indicates that the class is primitive, such as Integer, Real, Boolean, DateTime or String. A value of False indicates that the type is a class. Properties array of Property Properties Properties is an array of property objects (one for each property defined for the class) and it is get only. This array is empty if the class has not been loaded. This attribute is only supported in the Control Language Client (CL). SuperClass reference Class SuperClass SuperClass is a reference to the class object representing the superclass of the class. It is get only. The value is Null if the class has no superclass or it has not been loaded. 10
Schema Classes Library Library The Library class provides access to information about a Control Language class library. In a running system there exists one instance of the library class for each library defined in the system. Classes array of Class Classes Classes is an array of the classes contained in the library, and it is get only. This attribute is only supported within the Control Language Client (CL). Name String Name Name contains the name of the library as supplied in the source text of the library. It is get only. 11
Object Schema Classes Object The Object class is the base class for all classes. It is present in the Real-time Relational Database, but has no properties. Class reference Class Class Class is a reference to the class object representing the class of this object. ErrorText String ErrorText() ErrorText contains the text of the error, if any, generated by the last commit or data change made on this object. InTransaction Boolean InTransaction() This indicates whether the object is currently included in a transaction. This can be used to prevent the attempted inclusion of an object in a second transaction which would result in a run-time error. InError Boolean InError() This indicates whether the last commit or data change made to this object failed. 12
Schema Classes Property Property The Property class provides details about a single property of a class. Exported Boolean Exported Exported indicates whether the property is exported. It is get only. FileName String FileName FileName contains the name of the file on disk containing its definition. For predefined classes the value is an empty string. FileName is get only. Name String Name Name contains the name of the property. It is get only. ParentClass reference Class ParentClass ParentClass contains a reference to the class object representing the class in which this property is defined. It is get only. 13
Property Schema Classes PropertyType Integer PropertyType PropertyType contains an integer value indicating what kind of property this is. Possible values and meanings are: 5 Constant 6 Override 7 Export 8 Attribute 10 Handler 11 Function 12 On-set handler It is get only. Type reference Class Type This is a reference to the class object representing the type of the property. It is get only. Value String Value Value is a textual representation of the value of the property. It is get only. 14
Schema Classes Schema Schema The Schema class provides access to the CL schema. Classes array of Class Classes Classes is an array of Class objects, one for each class defined in the system. It is get only. Libraries array of Library Libraries Libraries is an array of Library objects; one for each library loaded into the system. It is get only. 15
Schema Classes Index Index Attribute Class (Object class), 7, 12 Classes (Library class), 7, 11 Classes (Schema class), 8, 15 Exported (Property class), 8, 13 FileName (Class class), 7, 9, 13 Instances (Class class), 7, 9 Libraries (Schema class), 8, 15 MyLibrary (Class class), 7, 9 Name (Class class), 7, 9 Name (Library class), 7, 11 Name (Property class), 8, 13, 14 Primitive (Class class), 7, 10 Properties, 5 Properties (Class class), 7, 10 summary of attributes and handlers, 7 SuperClass (Class class), 7, 10 Type (Property class), 8, 14 Value (Property class), 8, 14 CL schema, 5 CL schema (updated diagram), 6 Class Class, 9 Library, 11 Object, 12 Property, 5, 13 Schema, 15 Class attribute (Object class), 7, 12 Class class, 9 Classes Communications, 1 Schema, 1 Utility, 1 Classes attribute (Library class), 7, 11 Classes attribute (Schema class), 8, 15 Communications classes, 1 ErrorText handler (Object class), 7, 12 Exported attribute (Property class), 8, 13 FileName attribute (Class class), 7, 9, 13 Handler ErrorText (Object class), 7, 12 Handlers and attributes summary, 7 InError (Object class), 7, 12 Instantiate (Class class), 7 InTransaction (Object class), 7, 12 InError handler (Object class), 7, 12 Instances attribute (Class class), 7, 9 Instantiate handler (Class class), 7 InTransaction handler (Object class), 7, 12 Libraries attribute (Schema class), 8, 15 Library class, 11 MyLibrary attribute (Class class), 7, 9 Name attribute, 5 Name attribute (Class class), 7, 9 Name attribute (Library class), 7, 11 Name attribute (Property class), 8, 13, 14 Object class, 12 Primitive attribute (Class class), 7, 10 Properties attribute, 5 Properties attribute (Class class), 7, 10 Property class, 5, 13 Schema CL, 5 class objects diagram, 5 class objects updated diagram, 6 Schema class, 15 Schema classes, 1, 5 Summary attributes and handlers, 7 SuperClass attribute (Class class), 7, 10 Type attribute (Property class), 8, 14 Utility classes, 1 Value attribute (Property class), 8, 14 17