Digital DCE for OpenVMS VAX and OpenVMS Alpha

Updated: 24 May 2001

Digital DCE for OpenVMS VAX and OpenVMS Alpha
Product Guide

Contents

Index

20.2 RPC Test Program #2

The RPC Test Program #2 is a simple client/server program that makes slightly more use of the DCE services than RPC Test Program #1. In this program, the server registers transport end points with the RPC daemon and exports binding information to the directory service. The client uses the auto-handle mechanism to import server binding information.

To build this example program, enter the following commands:

$ COPY/LOG SYS$COMMON:[SYSHLP.EXAMPLES.DCE.RPC.TEST2]*.* []

$ @TEST2.COM

After the build is complete, define the server executable file as a foreign command. Assign a symbol using the following command syntax:

$ TEST2D:== $disk:[directoryTEST2D.EXE

For example, enter the following command:

$ TEST2D:== $WORK1:[SMITH.MYDCETEST2]TEST2D.EXE

Then start the server with the following command:

$ TEST2D

Once the server is running, you can run the client on the same host, or on any other host in the network that is configured to run in the same cell as the server host. Before running the client, you must define an environment variable (logical name) on the client system that can be used to locate the server binding information in the namespace during the auto-handle process:

$ DEFINE RPC_DEFAULT_ENTRY "/.:/test2_server"

After you define the environment variable, define the client executable file as a foreign command. Assign a symbol using the following command syntax:

$ TEST2:== $disk:[directoryTEST2.EXE

For example, enter the following command:

$ TEST2:== $WORK1:[SMITH.MYDCETEST2]TEST2.EXE

Then run the client with the following command:

$ TEST2

The client imports server binding information from the namespace. It makes a number of remote procedure calls, each of which results in a simple arithmetic function being executed. After making a sequence of calls, the client reports the average elapsed time for the calls to complete. By default, the client makes 10 passes with 100 calls per pass. You can specify the number of passes and the number of calls per pass by adding two arguments to the client startup command. For example, the following command instructs the client to make 5 passes, with 1000 calls per pass:

$ TEST2 5 1000

Because of the granularity of the clock on most systems, the average time per call will not be very accurate unless you set the number of calls per pass relatively high (at least 1000).

The client can be run as many times as desired, as long as the server is still running.

20.3 Object-Oriented RPC Test Program #1

This example implements a 2x2 matrix in a server application and allows the client application to manipulate the matrix with an IDL interface. The following features are listed:

Server advertises a named object with the DCE Naming service.
Server provides a callout for object lookup management.
Server provides a creator function for creating dynamic objects.
Server provides two static functions for creating dynamic objects.
Client binds to the named object three different ways.
Client creates dynamic objects using the object creator operation.
Client creates dynamic objects using the static member function operation.

20.3.1 How to Build Test Program #1 on OpenVMS Systems

Copy files from the DCE examples directory to your local directory.

$ SET DEFAULT MYDISK:[MYDIRECTORY] $ COPY SYS$COMMON:[SYSHLP.EXAMPLES.DCE.RPC.MATRIX1]*.* []

To build the application, first define the symbol netaddr as the network address of the server. Then run the following command procedure:

$ netaddr = "<NETWORK-ADDRESS>" $ @matrix

If you have MMS on your system, you can use the included description file:

$ MMS/MACRO=NETADDR="<NETWORK-ADDRESS>"

20.3.2 How to Run Test Program #1 on OpenVMS Systems

The server advertises a named object with the DCE name service using the name defined by the IdentityMatrix literal defined in the globals.h header file. In order for the client to bind to this object using only the object's UUID, the RPC_DEFAULT_ENTRY environment variable must be set to this name. The server is run as follows:

$ dce_login $ @matrix clean $ @matrix setup $ run server

You can also run the server using the MMS script as follows:

$ mms cleancds $ mms/macro=netaddr="<NETWORK-ADDRESS> " CDS $ define RPC_DEFAULT_ENTRY "/.:/objects/identityMatrix" $ run server

The advertised object is associated with a specific object UUID as noted by the IdentityMatrixId literal. In order to reuse the same object UUID consistently, an entry with the object UUID and interface UUID is explicitly exported to the name service. The following commands perform this task and are included in the command procedure:

$ cdscp create directory /.:/objects $ rpccp export -o dcea4900-65ba-11cd-bb34-08002b3d8412 -i d784B260-B5DB-11CB-832C-08002B2A1BCA -b ncacn_ip_tcp:16.31.48.49 -b ncadg_ip_udp:16.31.48.49 /.:/objects/identityMatrix

Run the client as follows:

$ define RPC_DEFAULT_ENTRY "/.:/objects/identityMatrix" $ run client

20.3.3 How to Build the Application Under POSIX

Copy the files from the DCE examples directory to your POSIX accessible directory.

psx> cd /mydev/mydir psx> copy /usr/dce/examples/gde_dce_apps/matrix1/* .

To build the application, run the following commands:

psx> netaddr="<NETWORK=ADDRESS> " psx> export netaddr psx> make

20.3.4 How to Run the Application Under POSIX

The server advertizes a named object with the DCE name service using the name defined by the IdentityMatrixId literal defined in the globals.h header file. In order for the client to bind to this object using only the object's UUID, the RPC_DEFAULT_ENTRY must be set to this name. The server is run as follows:

psx> dce_login psx> make cds psx> ready psx> server

The advertized object is associated with a specific object UUID as noted by the IdentityMatrixId literal. In order to reuse the same object UUID consistently, an entry with the object UUID and interface UUID is explicitly exported to the name service. The following commands perform this task and are included in the make file:

psx> cdscp create directory /.:/objects psx> rpccp export -o dcea4900-65ba-11cd-bb34-08002b3d8412 -i d784B260-B5DB-11CB-832C-08002B2A1BCA -b ncacn_ip_tcp:16.31.48.49 -b ncadg_ip_udp:16.31.48.49 /.:/objects/identityMatrix

Run the client as follows:

psx> ready psx> client

20.3.5 Application Files

Table 20-2 lists the application files.

Table 20-2 Object-Oriented RPC Test Program#1 Application Files
descrip.mms Contains the description of how the application is compiled.

matrix.com Command procedure for building the application.

matrix.idl Contains the interface definition for a matrix.

matrix.acf Contains the attributes for the interface definition.

globals.h Defines some global literals used by the application.

matrixmgr.h Contains the class definition of a 2x2 matrix supporting the Matrix interface.

matrixmgr.cxx Contains the implementation of a 2x2 matrix supporting the Matrix interface.

client.cxx Illustrates several ways to manipulate remote objects.

server.cxx Initializes the server and advertises a named object with the DCE name service.

lookup.h Declares the function prototype for a server object lookup operation.

lookup.cxx Returns a reference to the 2x2 identity matrix if the parameter specifies the proper object UUID. Otherwise, returns zero.

check_status.h Defines an error-checking macro used by the application.

ready. Sets up environment variable.

readme.txt Instructions on how to build and run the example.

20.4 Object-Oriented RPC Test Program #2

This example implements a 2x2 matrix in a server application and allows the client application to manipulate the matrix with an IDL interface. The location transparency feature of IDL C++ support is emphasized in this example. The following features are illustrated:

Server provides a creator function for creating dynamic objects.
Server provides a static function and overrides the name.
Client creates dynamic objects using the object creator operation.
Client creates local objects and interfaces to it with the Matrix interface.
Client performs local Matrix operations while referencing a remote object.
Client performs remote Matrix operations while referencing a local object.

20.4.1 How to Build the Application on OpenVMS Systems

Copy files from the DCE examples directory to your local directory.

$ SET DEFAULT MYDISK:[MYDIRECTORY] $ COPY SYS$COMMON:[SYSHLP.EXAMPLES.DCE.RPC.MATRIX1]*.* []

To build the application, first define the netaddr as the network address of the server, then run the following command procedure:

$ @matrix

If you have MMS, you can use the included description file as follows:

$ MMS

20.4.2 How to Run the Application on OpenVMS

This application makes use of the auto_handle feature of IDL. The server registers the binding handle under the name as specified by the environment variable EXAMPLE2_SERVER_ENTRY. The client must set the RPC_DEFAULT_ENTRY environment variable to this value before starting the process.

$ dce_login $ define EXAMPLE2_SERVER_ENTRY "/.:/example2_<SERVER_HOST_NAME> " $ run server

Run the client as follows:

$ dce_login $ define RPC_DEFAULT_ENTRY "/.:/example2_<SERVER_HOST_NAME> " $ run client

To provide object location transparency, the client application must be linked with the server stub and the server application must be linked with the client stub. In order to avoid a name conflict with the static member function createMatrix, the name is overridden in the ACF with the name ClassFactory.

20.4.3 How to Build the Application Under POSIX

Copy the files from the DCE examples directory to your POSIX accessible directory.

psx> cd /mydev/mydir psx> copy /usr/dce/examples/rpc/matrix2/* .

To build the application, enter the following command:

psx> make

20.4.4 How to Run the Application Under POSIX

psx> dce_login psx> export EXAMPLE2_SERVER_ENTRY=/.:/example2_<SERVER_HOST_NAME> psx> server

Run the client as follows:

psx> dce_login psx> export RPC_DEFAULT_ENTRY=/.:/example2_<SERVER_HOST_NAME> psx> client

20.4.5 Application Files

Table 20-3 lists the application files.

Table 20-3 Object-Oriented RPC Test Program#2 Application Files
descrip.mms Contains the description of how the application is compiled.

matrix.com Command procedure for building the application.

matrix.idl Contains the interface definition for a matrix.

matrix.acf Contains the attributes for the interface definition.

matrixmgr.h Contains the class definition of a 2x2 matrix supporting the Matrix interface.

matrixmgr.cxx Contains the implementation of a 2x2 matrix supporting the Matrix interface.

client.cxx Creates local and remote objects and illustrates object location transparency.

server.cxx Initializes the server.

statics.h Declares the function prototype for a the ClassFactory operation.

statics.cxx Creates and returns a reference to a 2x2 matrix.

check_status.h Defines an error-checking macro used by the application.

readme.txt Instructions on how to build and run the example.

20.5 Book Distributed Calendar Program

The Book distributed calendar program (book) is a fairly sophisticated client/server application that makes use of a number of DCE services. The program registers transport end points with the RPC daemon, and it exports server binding information to the directory service. It also demonstrates some minimal use of mutex locks to protect resources on the server from access by multiple call threads.

To build this example program, enter the following commands:

$ COPY/LOG SYS$COMMON:[SYSHLP.EXAMPLES.DCE.RPC.BOOK]*.* []

$ @BOOK.COM

After the build is complete, define the server executable file as a foreign command. Assign a symbol using the following command syntax:

$ BOOKD:== $disk:[directory]BOOKD.EXE

For example, enter the following command:

$ BOOKD:== $WORK1:[CARL.MYBOOKDIR]BOOKD.EXE

Then start the server with the following command:

$ BOOKD -v

The server takes two optional command arguments that affect the initialization sequence, as shown in Table 20-4.

Table 20-4 Options for Starting the Distributed Calendar Program
Argument Description

-d (Debug mode) Do not create a separate child process (run the server in the parent process).

-v (Verbose mode) Display informational messages during initialization.

The server calls a useful set of initialization routines from the DCE library (source code is also available for these in the modules rpcserver.c and rpcserver.h). The first call, to routine rpc_server_init(), starts a subprocess to run the server and initializes the RPC runtime with the appropriate parameters. The program does this before any other calls are made by the server to the RPC runtime and before any other threads calls are made (because thread context is not guaranteed to be preserved across a spawned or detached process). After performing other initialization functions (this program initializes a global mutex), the program makes a second call to rpc_server_detach(). This call releases the terminal associated with the parent process, after which the parent process is free to exit. The server then starts listening for client requests.

Once the server is running, you can run the client on the same host, or on any other host in the network that is configured to run in the same cell as the server host.

For example, enter the following command:

$ BOOK:== $WORK1:[CARL.MYBOOKDIR]BOOK.EXE

Then start the client with the following command:

$ BOOK

The client imports server binding information from the directory service and causes the server to update the calendar file for the account in which the client is running. The client has a help facility that lists the commands that you can execute to modify the calendar database on the server.

You can execute the client as many times as desired, as long as the server is still running. You can also run multiple clients with different names by passing different names as parameters to book. The following example runs one client program, for a user named David.

$ BOOK david

20.6 System Exerciser Example Program

The system exerciser example program exercises the basic DCE technologies: RPC, Security, CDS, DTS, and threads. The program is described in detail in the README file located in [SYSHLP.EXAMPLES.DCE.SX].

To build this example program, enter the following commands:

$ COPY/LOG SYS$COMMON:[SYSHLP.EXAMPLES.DCE.SX]*.* []

$ @DCESX.COM

To run the program on OpenVMS systems, you must define a foreign command. To maintain consistent program names on DCE for OpenVMS systems, use the foreign command name shown in the following example. Assign a symbol using the following command syntax:

$ DCESX:== $disk:[directory]DCE$SX.EXE

For example, enter the following command:

$ DCESX:== $WORK1:[SMITH.MYDCESXDIR]DCE$SX.EXE

Then start the system exerciser with the following command.

$ DCESX -p1 -s

The system exerciser command takes six optional command arguments, as shown in Table 20-5.

Table 20-5 Options for Starting the System Exerciser
Argument Description

-p n Number of passes through interface table. Supply a value for n.

-t n Number of seconds to delay between remote procedure calls. Supply a value for n.

-i n Number of interfaces in interface table. Supply a value for n between 1 and 10.

-s (Single system mode) Do not use shared group and profile.

-v (Verbose mode) Include hostname, process ID, thread ID, data, and time in output.

-q (Quiet mode) Limit output to a dot (.) for each remote procedure call that is made. This is the default mode.