This document covers the following topics:
Type information is a means to completely describe a class along with all of its interfaces, down to the names and types of the methods. It contains the necessary information about classes and their interfaces, for example, which interfaces exist on which classes, which member functions exist in those interfaces, and which argument those functions require.
This information is used by clients to find out details about a class and its methods, for example, by type-information browsers to present available objects, interfaces, methods and properties to an end user.
Another important area for using type information is the widely-used OLE automation technique which is also used by NaturalX.
There are several ways to store type information. A common way is generating the type information in type library (.TLB) files.
For each Natural class, a type library file is created when the class is registered.
The type library is generated in the <install-dir>/etc/<serverid>/<classname>/<version> directory and connected to the class via an entry in the registry.
The name of the class module is used, and the .tlb extension is appended unless the type library file name conflicts with an existing name. Then a number is attached to the class module name.
Each interface defined in a Natural class is seen by clients as a
dynamic interface (also called a "dispatch interface"). Each
method of an interface is seen by clients under the name defined in the
METHOD statement.
The first interface in a Natural class is marked as the default dispatch interface.
The support of type information also makes it possible to define multiple interfaces with identical method/property names. The Natural client simply addresses the corresponding method by using the interface name (as defined in the Natural class) as the prefix of the method name, as shown in the following example:
CREATE OBJECT #O3 OF CLASS "DepartmentList" SEND "Iterate.PositionTo" TO #O3 WITH "C" RETURN #DEPT
Natural clients use type information to find out to which interface a method or property belongs.
Note:
Natural clients do not use type information at catalog time to
perform syntax checks.
The following topics are covered below:
In order to receive data from clients or to pass data to classes
written in different programming languages, the Natural data formats are
converted to so-called OLE Automation-compatible types. This table shows how
COM clients see the method parameters or properties of a Natural class. For
example, if a Natural class has a method parameter or a property with the
format A, this is seen by a COM client as VT_BSTR.
| Natural Data Format | Automation-Compatible Type |
|---|---|
| A | VT_BSTR |
| B1 | VT_UI1 |
| B2 | VT_UI2 |
| B4 | VT_UI4 |
| Bn (n != 1, 2, 4) | SAFEARRAY of VT_UI1 |
| C | not supported |
| D | VT_DATE |
| F4 | VT_R4 |
| F8 | VT_R8 |
| I1 | VT_I2 |
| I2 | VT_I2 |
| I4 | VT_I4 |
| HANDLE OF GUI | not supported |
| HANDLE OF OBJECT | VT_DISPATCH |
| L | VT_BOOL |
| N15.4 | VT_CY |
| Nn.m (n.m != 15.4) | VT_R8 |
| P15.4 | VT_CY |
| Pn.m (n.m != 15.4) | VT_R8 |
| T | VT_DATE |
| U | VT_BSTR |
An array of a given Natural data format is mapped to a
SAFEARRAY of the corresponding VT type.
There are, however, some special cases:
A variable of format Bn with fixed
length, where n is not 1, 2 or 4, or an array of
such a variable, is mapped to a one-dimensional SAFEARRAY of
VT_UI1. This is for compatibility with previous versions of
Natural, where large and dynamic variables were not yet supported. Therefore,
large binary variables had to be simulated by arrays of variables of type B
with fixed length.
A dynamic variable of format B is mapped to a one-dimensional
SAFEARRAY of VT_UI1.
An array of dynamic variables of format B is mapped to a
SAFEARRAY of variants, each containing a one-dimensional
SAFEARRAY of VT_UI1.
Attribute control variables are not mapped. They have no meaning
outside of Natural. Variables of format HANDLE OF GUI are also not
mapped. There is no corresponding Automation-compatible type. Therefore
properties of the formats Attribute control variable or HANDLE OF
GUI cannot be accessed by clients through COM/DCOM. Method parameters of
these types should be marked as optional in the parameter data area, so that
clients can omit the parameters when calling the method through COM/DCOM.
This table shows how parameters or properties of an external class
can be addressed by Natural. For example, if an external class has a method
parameter or property with type VT_R4, this parameter or property
can be addressed in Natural as F4 or with a format that is
MOVE-compatible to F4.
| Automation -Compatible Type | Natural Data Format |
|---|---|
VT_BOOL |
L |
VT_BSTR |
A or U |
VT_CY |
P15.4 |
VT_DATE |
T |
VT_DISPATCH |
HANDLE OF OBJECT |
VT_UNKNOWN |
HANDLE OF OBJECT |
VT_I1 |
I1 |
VT_I2 |
I2 |
VT_I4 |
I4 |
VT_INT |
I4 |
VT_R4 |
F4 |
VT_R8 |
F8 |
VT_U1 |
B1 |
VT_U2 |
B2 |
VT_U4 |
B4 |
VT_UINT |
B4 |
A SAFEARRAY of up to three dimensions is converted into
a Natural array with the same dimension count and the corresponding format.
SAFEARRAYs with more than three dimensions cannot be used from
within Natural.
There are, however, some special cases:
A VT_BSTR maps either to a Natural variable of format
A or to a one-dimensional array of Natural variables of format A with fixed
length. The additional dimension is then used to store strings longer than 253
characters. This is for compatibility with previous versions of Natural, where
large and dynamic variables were not yet supported. This mapping should no
longer be used. Instead, a dynamic variable of format A should be used.
A SAFEARRAY of VT_BSTRs maps either to an
array of Natural variables of format A with the same dimension count, or to an
array of Natural variables of format A with fixed length with one more
dimension. The additional dimension is then used to store strings longer than
253 characters. This is for compatibility with previous versions of Natural,
where large and dynamic variables were not yet supported. This mapping should
no longer be used. Instead an array of dynamic variables of format A should be
used.
A SAFEARRAY of VT_UI1 can be mapped to an
array of Natural variables of format B with fixed length that has a matching
total size. This is for compatibility with previous versions of Natural, where
large and dynamic variables were not yet supported. This mapping should no
longer be used. Instead a dynamic variable of format B should be used.