Object-Oriented Programming Using SOM and DSOM:Distributing Your Objects:Building and Registering the Classes
Building and Registering the Classes
Once you have implemented your classes, your server (optional) and your client program, you have to compile them and register your classes and your server before they can be used. You should compile your classes into dynamic link libraries following the steps described in "Creating a DLL for SOM Classes" on page 79. Your server program should be compiled and linked with somtk.lib. Your client program should be complied and linked with somtk.lib and any other necessary libraries.
You must register the class's interface and implementation in the Interface Repository before an object can be accessed remotely by DSOM. You must also register a description of a server's implementation in the Implementation Repository before the server program, and the class libraries that it manages, can be used.
|HOSTNAME||no||Identifies the name of each machine running DSOM.|
|USER||no||Identifies the name of a DSOM user running a client program.|
|SOMIR||no||Specifies a list of files which, together, make up the Interface Repository|
|SOMDDIR||yes||Specifies the directory where the files that make up the Implementalion Repository should be located. This variable must be set before you reg1ster your server's implementation. If th1s variable is not set, DSOM will use the default directory %SOMBASE%\ etc\DSOM.|
|SOMDPORT||yes||Specifes a well-known port number. The same well-known port number must be used on all machines in a workgroup in order for an application to establish connections successfully.|
|SOMSOCKETS||yes||Specifies the name of a class that Implements communication services. This value is ignored by Workstation DSOM.|
|SOMDTIMEOUT||yes||Specifies how long a receiver should wait for a message or how long a sender should wait for an acknowledgement. The default value is 600 seconds.|
|SOMDDEBUG||yes||Enable DSOM run-time error reporting if set to 1. If set to 0, error reporting is disabled.|
|SOMDTRACELEVEL||yes||Enable DSOM run-time trace if set to 1. If set to 0, tracing is disabled.|
|SOMDMESSAGELOG||yes||Set to the name of the file where DSOM run-time error reporting or tracing messages are recorded. If not set, messages will be sent to the standard output device.|
Registering your Classes in the Interface Repository
DSOM uses the information stored in the Interface Repository extensively. The DSOM servers consult the Interface Repository to find the name of the DLL for a dynamically loaded class. Recall that you set the DLL name for a class in the dllname modifier in the implementation section of the class IDL. DSOM also uses the Interface Repository when transforming local method calls on proxies into messages that are sent to the remote objects.
The Interface Repository is a file that is located by lhe environment variable SOMIR. To populate the Interface Repository, you use the Interface Repository emitter, which can be invoked when you run the sc command with the -u option. If SOMIR is not set, the Interface Repository emitter creates a file named "som.ir" in the current directory. The following compiles the IDL file person.idl and creates an m called "person.ir":
set SOMIR=c:\mydir\person.ir sc -sir -u person.idl
Each class in the DLL must be compiled into the Interface Repository before running your DSOM application. DSOM uses the Interface Repository to find information on method parameters and return type. If a class has not been compiled into the Interface Repository, DSOM will generate a run-time error when an attempt is made to invoke a method from that class. The Interface Repository is described in more detail in Chapter 8.
The SOMobjects Developer Toolkit includes the utility irdump that can be used to find out if a class exists in the Interface Repository. For example, the following displays the definition of SOMObject:
Registering your Server in the Implementation Repository
DSOM uses the Implementation Repository to find out information about a server's implementation. The Implementation Repository contains information such as the name of the server, the name of the executable for the server program, the name of the machine on which the server program is stored, and the classes that are associated with this server. DSOM uses this information to locate a server, and, if necessary, to activate the server so that clients can invoke methods on it.
The Implementation Repository consists of four files:
somdimpl.dat somdimpl.toc somdcls.dat somdcls.toc
The location of the Implementation Repository is specified by the environment variable SOMDDIR. If SOMDDIR is not set, DSOM will attempt to use the default directory %SOMBASE% \etc \ dsom on OS/2.
There are two ways that yo u can populate the Implementation Repository. The first is a static mechanism using the regimpl registration utility. The second is a dynamic mechanism where you can access and update the Implementation Repository using a programmable interface at run-time. These are described below.
Using the regimpl Registration Utility
The regimpl utility can be run either interactively or as a command. To run in interactive mode, type regimpl at the system command prompt. This brings up the DSOM Implementation Registration Utility menu, where you will be prompted for information. The command interface is perhaps more useful since you can invoke it from a makefile.
The following lists all the information that you can specify using the regim.pl utility. The command flag that corresponds to each function is given in parentheses.
- Implementation alias (-i)
This is the name you defined for your server.
- Server program name (-p)
This is the name of the program that will execute as the server. The default program name is somdsvr, which is the DSOM generic server. If you have implemented your own application specific server, enter the full pathname for the program. If the program is located in PATH, then only the program name needs to be specified.
- Server class name (-v)
This is the name of the class that will manage the objects in the server. The default is SOMDServer.
- Multi-threading (-m)
This option specifies whether or not the server expects each method to be run in a separate thread. The default is no.
- Class name (-c)
Use this option to specify the list of classes that are associated with this server.
- Host machine name (-h)
This is the name of the machine on which the server program code is stored. The same name should be set in the HOSTNAME environment variable.
- Reference data file name (-f)
This is an optional parameter that contains the full pathname of the file that is used to store ReferenceData * associated with object references created by this server.
- Backup reference data file name (-b)
- This is an optional parameter that contains the full pathname of the backup file that is used to mirror the primary ReferenceData fi]e. This IDe can be used
to restore the primary copy if it becomes corrupted.
Each of these options can add to, update, or delete from the Implementation Repository. For example, the fo11owing commands add the server, myServer, to the Implementation Repository. The name of the server program jg servprog.exe, and the c1asses that are assoicated with myServer are Classl, Class2, and Class3.
regimpl -A -i myServer -p servprog.exe regimpl-a -i myServer -c Class1 -c Class2 -c Class3
(Reference data is application-specific data if it ia associated with an object reference. It can contain information such as the object location or state thaL is specific to the application. The SOMOA class provides the create and create_constant methods to create and associate reference data with the object reference.)
You can list the information in the Implementation Repository. For example, the command,
regimpl -L -i myServer
displays the list shown in Figure 5.3.
The Implementation ID is a unique ID that is generated by DSOM. This is the ID that you use when you invoke the somFindServer method to locate a server by its Implementation ID.
You can also list the classes associated with a server. For example, the command,
regimpl -1 -i myServer
displays the c1asses shown in Figure 5.4.
Using the Programmable Interface
The Implementation Repository can also be accessed and updated dynamically, using the programmable interface provided by the lmplRepository class. The following summarizes the methods provided by the ImplRepository class:
Implementation id .............. : 2cc7eff7-067c6140-7f-00-0100007fOOOO Implementation alias ........... : myServer Program name ................... : servprog.exe Multithreaded .................. : No Server class ................... : SOMDServer Object reference file .......... : Object reference backup ........ : Hostname ....................... : localhost
Figure 5.3 The Implementation Repository for myServer
|Implementation alias||Classes in this implementation|
Figure 5.4 The classes associated with myServer
- add_impldef-adds an implementation definition to the Implementation Repository.
- add_class_to_impldef-associates a class with a server.
- remove_class_from_impldef-removes the association of a class with a server.
- delete_impldef--deletes an implementation definition from the Implementation Repository.
- update_impldef-updates an implementation definition in the Implementation Repository.
- find_impldef-retums a server implementation definition given its ID.
- find_impldef_by_alias-returns a server implementation definition given its alias.
- find_impldef_by _class-returns a sequence of implementation definitions for servers that are associated with the specified class.
- find_classes_by_impldef-returns a sequence of class names associated with a server.
The code example of Figure 5.5 illustrates how you can retrieve a server implementation given the server's alias. The variable SOMD_ImplRepObject is initialized by SOMD_Init to point to the ImplRepository object. The ImplementationDef object contains attributes for setting and accessing the server's implementation definition.