Version 6.3.8 for Windows
 —  Operations  —

Registration

If a class is to be made accessible to DCOM clients, it is necessary to add some information about the class to the system registry. DCOM clients will mostly address a class with a meaningful name, the so-called programmatic identifier (ProgID) as in the following example:

CREATE OBJECT #O1 OF CLASS "Employee"

For a Natural class, the class name defined in the DEFINE CLASS statement is written into the registry as a ProgID.

System registry entries map this ProgID to the globally unique ID (GUID) of the class, allowing DCOM to uniquely locate all information about the class. Further information that is stored in the registry includes the path and name of the responsible DCOM server, the path and name of the type library, and interface information.

This document covers the following topics:


Registration with Natural

Natural classes can be registered (or unregistered) manually with the system command REGISTER (or UNREGISTER), automatically after the class is stowed (or deleted), or by running the .reg files, which are generated every time a class is registered.

In order to register classes, you must have the rights to modify the system registry and your system environment must be able to use COM.

It is usually not advisable to change the Natural entries in the system registry directly in the registry editor because this can lead to inconsistent registry entries.

A class is always registered for the server ID under which Natural was started.

Top of page

Automatic Registration

If the profile parameter AUTOREGISTER is set to "ON", a Natural class is automatically registered when it is stowed (cataloged), and unregistered automatically when it is deleted. This means that the user can test the class directly after stowing it.

Automatic registration uses the activation policy setting defined in the WITH ACTIVATION POLICY clause of the DEFINE CLASS statement of the class. If this clause is not specified, the setting from the profile parameter ACTPOLICY is used.

If automatic registration is set and a class is stowed (cataloged), the class is unregistered before it is stowed and registered after the stow has finished so that all old registry entries are removed.

Top of page

Manual Registration

The following topics are covered below:

The REGISTER Command

The system command REGISTER is used to register Natural classes. They are registered for the server ID under which Natural was started.

REGISTER

class-module-name

 

library-name

ES

IM
* * EM

class-module-name

This defines which class or classes are to be registered by specifying the appropriate Natural object module name.

library-name

This defines which library or libraries are to be searched for the class or classes.

ES, IM or EM

This defines the activation policy, which is registered for the class or classes.

You can set one of the following parameters:

Parameter Description
ES Sets activation policy "ExternalSingle".
IM Sets activation policy "InternalMultiple".
EM Sets activation policy "ExternalMultiple".

The following table shows which classes will be registered for all possible class/library combinations:

Class Module Name Specification Library Name Specification
library-name * -  
class-module-name class with class module name class-module-name of library library-name all classes with the class module name class-module-name which are found in the current step libraries class with class module name class-module-name
* all classes which are found in the library library-name are registered all classes which are found in the current step libraries are registered all classes of the current logon library are registered

If this parameter is not specified in the REGISTER command or the DEFINE CLASS statement, the default activation policy defined in the parameter file is used.

The UNREGISTER Command

The system command UNREGISTER is used to unregister Natural classes.

UNREGISTER

class-module-name

 

library-name

[server-id]

* *

class-module-name

This defines which class or classes are to be unregistered by specifying the appropriate Natural object module name.

library-name

This defines the library or libraries which are to be searched for the class or classes.

server-ID

This defines the server ID of the class or classes.

The following table shows which classes will be unregistered for all possible class/library/server ID combinations:

Class Name Specification Library Name /Server ID Combination
-- library-name - library-name server-ID * - *server-ID
class-module-name class with class-module-name in the current logon library if it is registered for the current server ID class with class-module-name of library library-name if it is registered for the current server ID class with class-module-name of library library-name if it is registered for the server server-ID all classes with class-module-name found in the current step libraries if they are registered for the current server ID all classes with the name class-module-name found in the current step libraries which are registered for the server server-ID
* all classes of the current logon library which are registered for the current server ID all classes found in the library library-name which are registered for the current server ID all classes found in the library library-name which are registered for the server server-ID all classes found in the current step libraries which are registered for the current server ID all classes found in the current step libraries which are registered for the server server-ID

A REGISTER or UNREGISTER system command will return an error message if class-module-name or class-module-name and library-name are specified but either the class or library is not found. If only an asterisk (*) is given in the REGISTER or UNREGISTER system command, no error message is returned if no class has been registered or unregistered.

If a class without class GUIDs or interface GUIDs is specified in the REGISTER system command, an error message will be returned. Such a class can only be used in the local Natural session.

Note:
Under Natural Security, this command can only be called for a single library. This means the library name has either to be omitted or a specific library has to be used. It is not possible to use an asterisk (*).

Top of page

Registration Files and Type Library

Registration files (".reg" files) enter information in the system registry when they are executed.

Natural will automatically create registration files for the server and the client side when a class is registered.

The server ".reg" file contains the same information that was entered in the system registry and the client ".reg" file contains all information, which is generated for the client side. When a class is unregistered, the .reg files will be deleted. If a ".reg" file is not to be deleted with the unregistration, the file has to be renamed before unregistering the class because Natural deletes only files with the default ".reg" file names.

The ".reg" files will be named classmodule_name_S.reg (for the server) and classmodule_name_C.reg (for the client) and, to activate a different version, classmodule_name_V.reg.

A type library is created automatically when a class is registered, and it is deleted when a class is unregistered. A reference to the type library is also entered in the registry.

The default type library name is classmodule_name.tlb. A new name will be generated if a type library with this name exists already.

The registration files and the type library are stored in the Natural etc directory as follows:

$NATDIR/$NATVERS/etc/serverid/classname/v<version-number>

Example

The files for version one of a class MY.TEST.CLASS registered for the server ID "SERVER01" are located as follows:

$NATDIR/$NATVERS/etc/SERVER01/MY.TEST.CLASS/v1

Top of page

Client Registration

Natural does not enter the registration information for the clients automatically in the system registry, but creates a registration file for the client. The client registration file contains an entry (RemoteServerName) that tells DCOM on which machine the DCOM server class can be found. This entry is not filled from Natural. It can be entered in either of two ways:

  1. The RemoteServerName can be entered in the registration files. In this case the line

    "RemoteServerName"=

    has to be changed to

    "RemoteServerName"="server_machine_name"

    After this, the registration file has to be executed on the client machine.

  2. The registration file is executed first, and then the RemoteServerName is changed using the DCOMCNFG tool or the Registry Editor (see the section DCOM Configuration on Windows).

Top of page

Registration Hints

The following points should be taken into account when registering and unregistering classes:

Top of page