Schema Classes. Polyhedra Ltd

(1)

Schema Classes

Polyhedra Ltd

(2)

(3)

i

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

(4)

(5)

iii

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

(6)

(7)

v

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 Utility classes add certain operating system capabilities to Polyhedra Control Language.

Schema Classes Schema classes provide access to the definitions of all the classes loaded into a running system.

Communications Classes 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.

(10)

(11)

Schema Classes Using this manual

3

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 specifies the type of the attribute.

Name specifies the name of the attribute.

Restrictions 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.

Attributes defined by this class.

Attributes inherited from superclass.

Attributes inherited from superclass' superclass

(12)

Using this manual Schema Classes

4

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 specifies the type of the return value of the handler, if the handler returns a value.

Format defines the handler name and the types of any parameters it takes.

Restrictions 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.

Page 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

(13)

Schema Classes Schema classes

5

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.

(14)

Schema classes Schema Classes

6

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"

Class Name SuperClass

"Object"

"Schema"

"Property"

Null

Figure 2: Class objects

(15)

Schema Classes Schema classes

7

A summary of attributes and handlers for each class is shown below:

Class

¹

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

Integer GetInstanceCount( ) 9

Integer GetInstanceSize( ) 9

Table 2 - Class handlers

Library

¹

array of Class Classes get only 11

Table 3 - Library attributes

Object

¹

reference Class Class get only 12

Table 4 - Object attributes

Boolean InTransaction( ) 12

Boolean InError( ) 12

String ErrorText( ) 12

Table 5 - Object handlers

1The Default field is left blank because instances of these classes cannot be created explicitly.

(16)

Schema classes Schema Classes

8

Property

²

Boolean Exported get only 13

String Filename 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

²

array of Class Classes get only 15

array of Library Libraries get only 15

Table 7 - Schema attributes

2The Default field is left blank because instances of these classes cannot be created explicitly.

(17)

Schema Classes Class

9

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 pre- defined 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.

(18)

Class Schema Classes

10

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.

(19)

Schema Classes Library

11

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.

(20)

Object Schema Classes

12

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.

(21)

Schema Classes Property

13

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 pre- defined 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.

(22)

Property Schema Classes

14

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.

(23)

Schema Classes Schema

15

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.

(24)

(25)

Schema Classes Index

17

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

Schema Classes. Polyhedra Ltd

Schema Classes

Polyhedra Ltd

Copyright notice

Trademarks

Manual Details

Software Version

PREFACE

CONTENTS

Tables

1. Overview of classes

2. Using this manual

2.1 Class summary layout

2.2 Class description layout

attribute-name

handler-name

3. Schema classes

Class

Library

Object

Property

Schema

Class

FileName

GetInstanceCount

GetInstanceSize

Instances

MyLibrary

Name

Primitive

Properties

SuperClass

Library

Classes

Name

Object

Class

ErrorText

InTransaction

InError

Property

Exported

FileName

Name

ParentClass

PropertyType

Type

Value

Schema

Classes

Libraries

Index