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.