|
The Diamond installation provides an example of a user-defined cluster in the folder <3L>Diamond\server\cluster. This builds a library, Clu3L_0C.dll, to support references to cluster 12 (0C16). You can take this code as a base and develop your own cluster from it. The cluster is set up as a Microsoft Visual C++ project, with workspace ExCluster.dsw.
1.
|
Start by selecting a name for your new service cluster. You should take copies of the relevant files from the example and rename them accordingly.
|
2.
|
Select a Cluster Number for your new service cluster: any application may use cluster number 2 as an End-User cluster. This service is never used by 3L or third-party clusters. Cluster 3 is similarly reserved as a Prototyping cluster. If you intend supplying your service cluster to other users of Diamond as a third-party cluster, you should develop it using cluster 3 and then apply to 3L for a Registered Service Cluster before shipping to customers. Cluster 12 is reserved for the example cluster.
|
3.
|
Define a header file for your cluster based on ExCluster.h and change:
a.
|
CLASS. This name is given to the class that defines your cluster. The example uses Ex_Cluster.
|
b.
|
CLUSTER_ID. This C-style string is returned in exceptions thrown by the cluster. The example uses "Example Cluster".
|
c.
|
The list of the services that your cluster provides. This is actually a list of the names of the member functions in the class that you are going to create. Each entry is of the form:
REF_SERVICE(<member function name>)
For example: REF_SERVICE(Square)
|
|
4.
|
Define the entry point for your library based on the file Example.cpp. The only change you need to make in your version is to replace "ExCluster.h" with the name of the header file created in step 2 above.
|
5.
|
Define the services your cluster provides based on the file ExCluster.cpp. You need to change 3 things:
a.
|
Replace "ExCluster.h" with your header defined in step 2
|
b.
|
Define the member functions that implement your services. These must correspond with the references specified in step 2.c above. Each service is defined as in the following example:
DEF_SERVICE(Square) {
int value = P->get_int();
return value*value;
}
This defines a member function Square that takes a single integer value from the parameter stream (get_int) and return the square of that value. The way services communicate with the server is discussed here. The example defines three member functions, but you may define any number, although defining no services would be very strange! The functions communicate with the root CPU using the presentation interface pointer, P. They may also use core functions accessed through the pointer C.
Define the mapping of command numbers to member functions by creating the array Services. When the CPU requests command n from this cluster, the member function identified by element n in this array is called. Each element must be one of:
i.
|
ENTRY(service-name)
service-name must be the name of the member function to be called when the corresponding command is requested. For example, if you want the function Square, defined above, to be called on command 6, you would set element 6 of the array to ENTRY(Square).
|
ii.
|
NO_ENTRY
This is used as a dummy entry when a command number has no corresponding member function. Requesting this service results in a no_service exception being thrown. Note that element 0 is always a null service and that the size of the Services array is derived automatically.
|
 While a service function is being executed, the link from the root DSP to the host is blocked. Hence it is generally a bad idea to write service functions that wait for any reason. If you need to do this, it is better for the service function to start a thread to wait for the event and then provide a separate service that can be called to determine if the expected event has happened.
|
|
6.
|
You should now build your cluster and create a DLL. You must call the library "Clu3Lxx.dll", where xx is the hexadecimal representation of the cluster number you have selected with a minimum of two characters.
|
7.
|
The server must be able to locate your library. You should put your new library in one of the following places:
a.
|
The folder from which the server is loaded, usually \3L\Diamond\bin.
|
b.
|
The current directory.
|
c.
|
The Windows system folder, usually C:\WINDOWS\System32.
|
d.
|
A folder listed in the PATH environment variable.
|
Refer to the Windows documentation on LoadLibrary for further details.
|
|