13 —
Example Programs
[Previous]
[Next]
[Contents]
[Index]
13.1 Overview of Remote Procedure Call Programs
Several example programs are supplied with the Application Developer's Kit subset. These programs are located in directories under /usr/examples/dce. This chapter provides information about the example programs provided with Gradient DCE for Tru64 UNIX. Each example program also has an online README file located in the same directory as the program. The next table shows the different features of each example program.
Copy the example files to another area before you attempt to build them. You also may want to open two separate windows for the client and server processes.
The following sections describe the example programs.
13.2 RPC Test Program #1
RPC Test Program #1 is a simple client/server program that makes minimal use of the DCE services. The server does not register transport endpoints with the DCE daemon, and no binding information is exported to the directory service. The server binding information has to be transferred to the client manually by the user.
To build this example program, enter the following commands:
% cp /usr/examples/dce/rpc/test1/* .
% make -f makefile.test1
After the build is completed, start the server with the following command syntax:
% test1d [protseq]
The server reports binding information for each of the various protocol sequences that are available and both displays the information on the terminal screen and writes it to a file called binding.dat. This binding information consists of three elements: a protocol sequence, a network address, and a transport endpoint. For example, the server might report the following binding information:
ncacn_ip_tcp 66.0.0.7 4344
If you want the server to use a specific protocol sequence, you can include that as an argument in the server startup command. For example:
% test1d ncacn_ip_tcp
This command causes the server to use that protocol sequence only. The protocol sequences currently supported include ncacn_ip_tcp (connection protocol) and ncadg_ip_udp (datagram protocol).
Once the server is running, you can run the client on the same host or on any other host in the network. To run the client, you must provide the server binding information reported by the server. For example, you can run the client with the following command syntax:
% test1 protseq networkaddr endpoint [number of passes] [calls per pass]
For example:
% test1 ncacn_ip_tcp 66.0.0.7 4344
% test1 ncacn_ip_tcp hostname 4344
The client makes a number of remote procedure calls, each of which causes a simple arithmetic function to execute. 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 additional arguments to the client startup command. For example, the following command instructs the client to make 5 passes, with 1000 calls per pass:
% test1 ncacn_ip_tcp 66.0.0.7 4344 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 to a relatively high number (at least 1000).
The client can be run as many times as desired, as long as the server is still running. If you want to clean up the directory for this test so that you can build it again, enter the following command:
% make -f makefile.test1 clean
13.3 RPC Test Program #2
RPC Test Program #2 is a simple client/server program that makes more use of the DCE services than RPC Test Program #1. In this program, the server registers transport endpoints with the DCE 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:
% cp /usr/examples/dce/rpc/test2/* .
% make -f makefile.test2
Because this program exports and imports an entry to the global namespace (.:), you must perform a dce_login operation as cell_admin or some other privileged principal before you start the server process. 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 on the client system that can be used to locate the server binding information in the namespace during the auto-handle process:
% setenv RPC_DEFAULT_ENTRY /.:/test2_server
After you define the environment variable, run the client with the following command syntax:
% test2 [passes][calls per pass]
The client imports server binding information from the namespace. It makes a number of remote procedure calls, each of which causes a simple arithmetic function to execute. 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. If you want to clean up the directory for this test so that you can build it again, enter the following command:
% make -f makefile.test2 clean
13.4 RPC Test Program #3
RPC Test Program #3 is a simple client/server program that makes minimal use of the DCE services. The server registers transport endpoints with the DCE daemon, but no binding information is exported to the directory service.
To build this example program, enter the following commands:
% cp /usr/examples/dce/rpc/test3/* .
% make _f makefile.test3
After the build is completed, ensure that dced is running, and then start the server with the following command:
% test3d [protseq]
The server reports binding information for each of the various protocol sequences that are available and both displays the information on the terminal screen and writes it to a file called binding.dat. This binding information consists of two elements: a protocol sequence and a network address. For example, the server might report the following binding information:
ncacn_ip_tcp 66.0.0.7
If you want the server to use some specific protocol sequence, you can include that as an argument in the server startup command. For example:
% test3d ncacn_ip_tcp
This command causes the server to use that protocol sequence only. The protocol sequences currently supported include ncacn_ip_tcp (connection protocol) and ncadg_ip_udp (datagram protocol).
Once the server is running, you can run the client on the same host, or on any other host in the network. To run the client, you must provide the server binding information reported by the server. For example, you can run the client with the following command syntax:
% test3 protseq hostaddr [passes] [calls per pass]
For example:
% test3 ncacn_ip_tcp 66.0.0.7
or
% test3 ncacn_ip_tcp hostname
The client makes a number of remote procedure calls, each of which causes a simple arithmetic function to execute. 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 additional arguments to the client startup command. For example, the following command instructs the client to make 5 passes, with 1000 calls per pass:
% test3 ncacn_ip_tcp 66.0.0.7 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 to a relatively high number (at least 1000).
The client can be run as many times as desired, as long as the server is still running. If you want to clean up the directory for this test so that you can build it again, enter the following command:
% make _f makefile.test3 clean
13.5 Book Distributed Calendar Program
The Book distributed calendar program (book) is a fairly sophisticated client/server application that uses of a number of DCE services. The program registers transport endpoints with the DCE daemon and 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:
% cp /usr/examples/dce/rpc/book/* .
% make -f makefile.book
After the build is completed, log in as root, perform a dce_login operation, and start the server with the following command:
% bookd [-d][-v][bookname]
The server calls a useful set of initialization routines from the DCE library. The first call, rpc_server_init( ), forks a process 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 fork). 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.
The server takes three optional command arguments that affect the initialization sequence, as shown in Table 13-2.
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. Start the client with the following command:
% book [bookname]
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. To clean up the directory for this application so you can build it again, enter this command:
% make -f makefile.book clean
13.6 The Time Operations Sample Application
The timop_svc program exercises the basic DCE technologies: threads, RPC, security, directory, time and serviceability. Its detailed description is in the README file the /usr/examples/dce/svc/timop_svc directory.
13.6.1 Overview
The two parts of timop are a client and a server, implemented by the timop_svc_client and timop_svc_server processes. The server manages a single operation, getting the span of time used in calculating the factorial of a random number specified by the client. The client spawns several threads that make parallel RPC service calls to designated servers. The client prints the name, invocation order, and time span that each server reports, and the number for which the server calculated the factorial. It also prints out a total time span that encompasses all the job events at the servers and the sum of the random numbers.
The transport provider is UDP. Authentication and integrity-secure RPC ensure data communication. Named-based authorization (not ACLs) is employed. Clients and servers use different physical clocks that are in agreement with one another because they are synchronized by the time service. All times and time calculations are in UTC, not local civil time; permitting clients and servers to operate in different time zones.
Because timop uses the security service, the timop clients and servers must run as security principals, but with only minimum use of security. The timop_client runs as a principal named /.../mycell/tclient and timop_server as a principal named /.../mycell/tserver. These names can be changed to suit your environment by modifying timop_svc_aux.h file.
Additional information on serviceability can be found in the OSF DCE Application Development Guide - Core Components volume. See also the log.8dce reference page (about the dcecp log object, through which the DCE components' serviceability routes and settings are managed) in the OSF DCE Command Reference.
13.6.2 Building timop_svc
Before building timop_svc, make sure that the DCE Application Development Environment (which includes the IDL compiler) is installed. Next, read the comments of the Makefile, and remove comment flags and options as appropriate to your platform.
To build timop_svc, enter the following command.
% make -f Makefile.timop_svc
13.6.3 Setting Up to Run timop_svc
Before you can run timop_svc, you must first set up your DCE cell with the security registry and namespace information necessary for the program and for its client and server principal entities. You must also set up an authentication key table file on each machine on which you intend to run the server. To do so, follow these steps:
-
Add the client and server principals to the Security registry.
-
Create a keyfile to be used by the server.
-
Create a CDS namespace entry, to which the server exports its binding information, and from which the clients import it.
-
Set up the correct permissions on the namespace entry so that the server can write to it correctly.
Included with the example's files are a pair of dcecp scripts that automatically perform (or undo) all of the above steps, except the second step (creating the keytab file). Each script also logs in to the cell as cell_admin as its first operation. The login operation uses the default cell password (-dce-).
The following examples show how to run the setup script:
% ./timop_svc_setup.dcecp /.:/ts_entry
principal create {tsserver tsclient}
group add none -member tsserver
group add none -member tsclient
organization add none -member tsserver
organization add none -member tsclient
account create tsserver -group none -organization none \
-password qwerty -mypwd -dce-
account create tsclient -group none -organization none \
-password xyzzy -mypwd -dce-
Adding CDS entries.
Once the setup script has been run, you should log in as the Cell Administrator using dce_login and run rgy_edit to set up the server's keyfile:
% dce_login cell_admin -dce-
% rgy_edit
Current site is: registry server at /.../your_cell/subsys/dce/sec/master
rgy_edit=> ktadd -p tsserver -pw qwerty -f /tmp/tskeyfile
rgy_edit=> quit
bye.
You have now finished the timop_svc setup.
For more information about rgy_edit, see the OSF DCE Administration Guide - Core Components and the OSF DCE Command Reference.
The name of the server's keyfile, /tmp/tskeyfile, is specified by the value of the KEYFILE constant in the timop_svc_server.h file; the name you give to the ktadd subcommand must be identical to the value of this constant.
To undo the setup, run the unsetup script, as follows:
% ./timop_svc_unsetup.dcecp /.:/ts_entry
principal delete {tsserver}
principal delete {tsclient}
account delete tsserver
Registry object not found
account delete tsclient
Registry object not found
Deleting CDS entries.
13.6.4 timop_svc Message Catalog
The DCE Serviceability API uses XPG4 message catalogs to store and retrieve message text. The catalogs are generated by the DCE sams utility. The catalogs should be installed in their correct platform-specific location. For example:
/usr/lib/nls/msg/LANG
However, if the serviceability routines cannot find a catalog there, they default to their respective current working directory. If they cannot find the catalogs there either, they retrieve messages from the in-memory table, if one has been defined by the application. See the Serviceability chapter in the OSF DCE Application Development Guide for details. Thus you should be able to run timop_svc successfully without doing any extra message catalog installation.
13.6.5 Running the timop_svc Server
To run timop_svc, you must first start the server and invoke one or more clients to perform the timop_svc operation. An example of how to do this follows.
On the machine on which you want to run the server, enter this command:
% ./timop_svc_server -e1 /.:/ts_entry
NOTE:
You should start the server in the background, in a window different
from the one in which you intend to run the client, or on a separate terminal.
The /.:/ts_entry is the server's name in the namespace. It is the name of the CDS entry to which it exports its bindings, and therefore is the name by which it is known to clients. The entry was set up when you ran the dcecp setup script earlier; it can have any name you choose.
The -e1 specifies the object UUID that the server should export and register its bindings with. Two object UUIDs are available, specified to the server as -e1 or -e2. Having two UUIDs allows you to have two servers running at the same time (and even on the same machine). Clients can bind to the server they choose simply by specifying the correct object number in the client command line (as will be seen below). Even when two timop_svc servers export to different name entries, if the servers are active at the same time, their exported partial bindings will be identical if they are running on the same machine; requiring that the bindings be exported and imported with an object UUID specified prevents different server instances from getting mixed up.
The server displays a series of messages, most of them output through the Serviceability API. For more information about these messages and how to control them, see the sample output in the README file. At the end of all this preliminary activity, the server displays a "ready" message.
13.6.6 Running the timop_svc Client
After you have invoked the server, wait until you get a message similar to this one:
1994-05-26-19:36:32.915+00:00I----- ./timop_svc_server NOTICE tsv server
0x7aff3f20
Server /.:/ts_entry (object 1) ready...
(This is the serviceability form of the "Server ready" message displayed by the timop server.)
You can now invoke the client (either in the same window, if you ran the server in the background, or in a different window). To get rid of your tsserver identity when invoking the client from the same window, enter:
% exit
Next, log in as the tsclient principal and then start the timop_svc_client program. Enter:
% dce_login tsclient xyzzy
% timop_svc_client -o1 /.:/ts_entry
The -o1 specifies that the client is to import the bindings registered with object UUID 1, which is the object the server exported to. If the server had specified -e2, then the client would have had to specify -o2. If two servers were active and each had exported to a different object, clients could specify either object (or both) to import.
If all has gone well, the timop_svc client now begins printing out results continuously until you stop it. (See Section 13.6.8 on page 168 for details on how to do this.)
On multiple machines in the same cell, you can try something like the following:
% timop_svc_server -e1 /.:/ts_entry # on machine A
% timop_svc_server -e2 /.:/xs_entry # on machine B
% timop_svc_client /.:/ts_entry /.:/xs_entry /.:/ys_entry # on machine D
% timop_svc_client /.:/ys_entry /.:/xs_entry /.:/ts_entry # on machine E
To do this, you must first set up xs_entry and ys_entry names in CDS by specifying these additional names to the timop_svc_setup.dcecp script.
13.6.7 Sample Server Output
Following is an example of the kind of server output you can expect to see if you invoke the timop_svc server with full debugging enabled, and with serviceability NOTICE type messages routed to standard error.
In general, the first groups of messages are output as a result of straightforward test calls to various routines; the later messages contain authentic information being output via the serviceability interface. As explained above, once this message appears, the server waits, and the client (or clients) can then be started.
1994-05-26-19:36:32.915+00:00I----- ./timop_svc_server NOTICE tsv server
0x7aff3f20
Server /.:/ts_entry (object 1) ready...
Once a client is started, the server resumes its messaging activity; the amount of activity is determined by the debug level you specify (the default is no debug messaging) and the routing you have set. In the preceding example, the "Server ... ready" message is about the 16th from the last; the subsequent messages represent a sample of what happens once a client has become active.
See the timop_svc source code (which is fully commented) for details of which serviceability routines are called.
Refer to Section 13.6.9 on page 168 and Section 13.6.10 on page 169 for more information on how to specify various aspects of timop_svc's behavior.
For more information on Serviceability functionality, see the serviceability chapter in the OSF DCE Application Development Guide - Core Components volume.
See the README file for examples of server and client output.
13.6.8 Stopping timop_svc
You must kill clients and servers by hand, either by using the interrupt key or with a combination of the ps and kill commands. Doing so leaves server binding information in the endpoint map and namespace, which is normal for persistent servers. The information can be removed afterwards by running the timop_svc_unsetup.dcecp script.
13.6.9 timop_svc Server Options
The timop_svc server is invoked as follows:
timop_svc_server [-wsvc_route [-wsvc_route ... ]] \
[-d"dbg_route" [-d"dbg_route" ... ]] \
[-D"dbg_level" [-D"dbg_level" ... ]] \
[-f] -enr entry_name
For more information on Serviceability functionality, see the serviceability chapter in the OSF DCE Application Development Guide - Core Components volume.
13.6.10 timop_svc Client Options
The timop_svc client is invoked as follows:
timop_svc_client _onr [ -onr ... ] \
server_entry [ server_entry ... ] \
[-D"dbg_level" [-D"dbg_level" ... ]] \
[-d"dbg_route" [-d"dbg_route" ... ]] \
[-wsvc_route[-wsvc_route ... ]] [-l] [-C] [-R] [-f]
or:
timop_svc_client -onr -b"string_binding" \
[-D"dbg_level" [-D"dbg_level" ... ]] \
[-d"dbg_route" [-d"dbg_route" ... ]] \
[-wsvc_route[-wsvc_route ... ]] [-l] [-C] [-R] [-f]
For more information on Serviceability functionality, see the OSF DCE Application Development Guide - Core Components.
13.6.11 timop_svc Principal And Keytab Names
13.6.12 timop_svc Debug Message Levels
You can set to nine different debug levels (by means of the _D switch in the server or client command line; see Section 13.6.10 on page 169 ). Table 13-3 shows the debug level significance in timop_svc:
For more information on Serviceability functionality, see the OSF DCE Application Development Guide - Core Components.
13.7 Microsoft RPC Phonebook Program
This section describes how to build and run a phonebook application called phnbk. Company employees use the phnbk client program to look up employee contact information that resides with the phnbk server.
The phnbk application is included with Gradient DCE for Tru64 UNIX. Because the phnbk source code is portable, you can build and run the phnbk server on a Tru64 UNIX system that has Gradient DCE for Tru64 UNIX installed, as well as on other DCE machines.
The sample phnbk client/server program demonstrates several aspects of cross-environment applications:
13.7.1 Source Files for the phnbk Example
To run the example programs, copy the example source files to the Microsoft RPC and DCE platforms. The following list identifies the source files you need to build an executable client and server program for Gradient DCE for Tru64 UNIX.
13.7.2 Building the Tru64 UNIX phnbk Client and Server Programs
To build the phnbk client and server programs on a Tru64 UNIX system that has Gradient DCE for Tru64 UNIX installed, use make to build the executable client and server programs:
% make -f phnbk.unix ALPHA=_std1 alpha
This command creates a server program called phnbkd and a client program called phnbk.
13.7.3 Starting and Stopping the phnbk Server
To start the server phnbkd, enter the following command:
% phnbkd&
The server displays the binding information for each protocol sequence it is using. Three elements make up a server's binding information: a protocol sequence, a network address, and a transport endpoint. For example, a server might report the following binding information:
% phnbkd&
[1] 23789
ncacn_ip_udp:16.20.16.134.[1229]
ncacn_ip_tcp:16.20.15.134.[1474]
When you are done using the server program, stop it using the kill command.
13.7.4 Starting and Stopping the phnbk Client Program
To start the phnbk client (phnbk), use one of the following binding methods:
13.8 The Echo Example Program
The Echo example program* (echo) demonstrates how a distributed application can secure itself using the GSSAPI security interface.
The echo example consists of a server program (echo_server) and a client program (echo_client). When echo_server is running, it waits for echo_client to attempt to connect over TCP/IP. Once a connection is established, user input from echo_client is transmitted across the network to the server and echoed back to the client.
When a user enters the -s switch, echo_client uses GSSAPI to authenticate itself to the server and to protect messages that flow from client to server. Messages in the reverse direction are not protected.
The echo example demonstrates how a distributed application:
To build the echo example, copy the files in /etc/examples/dce/gssapi into a directory, edit Makefile.echo to match your environment (if necessary), and issue the following command:
% make -f Makefile.echo
You need to establish the echo server and client as DCE principals having principal names, accounts, and group and organization membership.
% dcecp
dcecp> principal create {echo_server echo_client}
dcecp> group add none -member echo_server
dcecp> group add none -member echo_client
dcecp> organization add none -member echo_server
dcecp> organization add none -member echo_client
dcecp> account create echo_server -group none -organization none \
> -password qwerty -mypwd -dce-
dcecp> account create echo_client -group none -organization none \
> -password xyzzy -mypwd -dce-
You must also create a keytable for managing the server authentication keys.
% rgy_edit
Current site is: registry server at /.../snafu_cell/subsys/dce/sec/master
rgy_edit=> ktadd -p echo_server -pw qwerty -f /tmp/echo_keyfile
rgy_edit=> quit
bye.
%
You can run the example from a single system or move echo_client and echo_server to two different systems. On the server, start echo_server using the following command syntax:
% echo_server [-p port] [-s server_name] [-f keytable_file]
The command arguments for the server are described in the next table.
You can try using another port if the server fails to start and produces an error like:
server: Can't bind local address
You can perform authenticated or unauthenticated client operations. To perform authenticated client operations, you must acquire DCE credentials with integrated login on an SIA-enabled system or by running the dce_login program. To perform unauthenticated operations, do not use the -s option to the echo_client command.
On the client, start echo_client using the following command syntax:
% echo_client [-h host] [-p port] [-s server-name]
The command arguments for the server are described in the next table.
Once the connection is open, each line you type to echo_client is sent across the network to the server and echoed back to the client. Press <Ctrl/D> to stop the client.
13.9 Time Provider Example Programs
The directory /usr/examples/dce/dts contains many example programs for various types of external time providers. These examples contain extensive information about how to build and use them. For additional information about the time provider interface, see the OSF DCE Application Development Guide.
13.10 The Serviceability API Sample Program
The hello_svc program provides a simple demonstration of the DCE Serviceability API. When executed, it writes a "Hello world" message to standard error via the serviceability interface.
The program was developed during the writing of the OSF DCE Application Development Guide chapter on serviceability, and is included with the DCE software as a very simple demonstration of the interface.
13.10.1 Building the Program
To build the example, copy the files from /usr/examples/dce/svc into a writeable directory and issue this command:
% make _f Makefile.hello_svc
Once you have built hello_svc, execute it by typing this command with no arguments:
% hello_svc
You should see two messages similar to these:
1994-06-10-13:07:33.628+00:00I----- ./hello_svc NOTICE hel main 0xa448c444
Hello world
1994-06-10-13:07:33.628+00:00I----- ./hello_svc NOTICE hel main 0xa448c444
Hello world
The message is printed twice because it is routed to standard error twice: once via a call to dce_svc_routing( ) within the program, and again by the "attributes" field in the message definition in the hel.sams file.
For more information on Serviceability functionality, the OSF DCE Application Development Guide - Core Components. See also the log.8dce reference page (about the dcecp log object, through which the DCE components serviceability routes and settings are managed) in the OSF DCE Command Reference.
13.11 The Generic Sample Application
The generic sample DCE client/server application includes extensive examples of ACL management, serviceability code, security setup, and signal handling. It also has the necessary initialization and cleanup code. The manager code (sample_manager.c) consists of one generic remote call that does no actual work, but which does make use of the ACL manager and the serviceability code.
13.11.1 Building the Sample Application
To build the sample application program, copy the source files from /usr/examples/dce/generic_app/*. Use the following command to build the application:
make _f Makefile.generic_app
13.11.2 Installing the Sample Application
Before you can run the sample application, you must install sample_client and sample_server on the machines you want to use. This installation involves these steps:
-
Adding the client and server principals and server group to the Security registry.
-
Creating a keyfile to be used by the server.
-
Creating a CDS namespace entry for the server to export its binding information to (and for the clients to import binding information from).
-
Setting up the correct permissions on the namespace entry to allow the server to use it (that is, to write to it) correctly.
Assuming that the server's principal name is sample_server and that the client's principal name is sample_client, you should perform these steps as follows:
-
Log in as the cell administrator:
$ dce_login cell_admin -dce-
You must first login as the cell administrator to be able to execute the
registry operations in step 2.
NOTE:
The password at your site is probably different from that given
above (as the last parameter). For further information about the use of
dce_login, see the OSF DCE Administration Guide.
-
Add the server and client principals to the registry, and set up the server's keyfile:
% dcecp
dcecp> group create sample_servers
dcecp> user create sample_server -g sample_servers -org none
> -pass server_password -mypwd -dce-
dcecp> user create sample_client -g none -org none
> -pass client_password -mypwd -dce-
dcecp> keytab create /.:/hosts/mccann/config/keytab/sample_keytab
> -storage /tmp/sample_keytab
> -data {sample_server plain 1 server_password}
> -noprivacy -local
dcecp>
NOTE:
server_password and client_password are the passwords that you
assign to the server and client, respectively. You can substitute any other
values but be sure to remember these values: you need to use them to
perform a dce_login operation before executing the client and server
programs. For further information about dcecp, see the OSF DCE
Administration Guide - Core Components and the OSF DCE Command
Reference.
The name of the server's keyfile, /tmp/sample_keytab, is specified by the
value of the KEYTAB constant in the sample_server.c file; the name you
give to the keytab subcommand must be identical to the value of this
constant.
-
Create the CDS entry to be used to hold the server's binding information. For example:
% dcecp -c create directory /.:/sample
% dcecp -c rpcentry create /.:/sample/sample_server_entry
You can substitute any legal CDS name for sample.
-
Set up the ACL on the entry to allow access to the server:
% dcecp
dcecp> acl modify /.:/sample/sample_server_entry -entry \
> add {user sample_server rwdtc}
dcecp> exit
NOTE:
sample_server is the principal name used in the previous steps and
must be identical to the value of the principal_name argument you specify
on the command line to sample_server.
You have now installed the sample application.
13.11.3 Running the Sample Application
This section describes how to run the server and client.
Before you run the server you must create in the local directory, a subdirectory called db_sample_acl. This directory is where the sample application's backing store database files will be created. The pathname to these files is determined by the value of the ACL_DB_PATH constant at the top of the sample_server.c file; you can change this value if you want to.
Invoke the server as follows:
sample_server principal_name CDS_dir_name/
NOTE:
There is a /(slash) after the directory name.
where:
For example (with setup done as described in first section):
./sample_server sample_server /.:/sample/
At present, the server's serviceability messages are routed by default values coded at the top of the sample_server.c file. The default behavior sets full debugging and routes everything to stderr. If you compile the server as is, you see lots of messages appearing on your screen when you run it (For an example, see the end of the README file.) To change this behavior, you must change the hard-coded defaults, because currently there is no way to change routing via the command line.
13.11.3.1 Running the Client
Before running the client you must first set the environment variable RPC_DEFAULT_ENTRY to the value of the full name of the server's CDS name entry. For example (with setup done as described in first section):
setenv RPC_DEFAULT_ENTRY /.:/sample/sample_server_entry
You must be logged in via dce_login as the sample_client principal to properly allow the client to do what it needs to do. This is because the only principal who is given any meaningful permissions on the objects managed by the application is the owner who is defined at the top of server_sample.c to be sample_client.
The client is invoked as follows:
sample_client object_name | kill
You can try any of three command forms (because at present there are only two objects set up by the server).
To bind via the junction to the mgmt object and view its contents, enter:
./sample_client sample_object
To bind to the sample object and view its contents, enter:
./sample_client server_mgmt
To kill the server via the remote management interface, enter:
./sample_client kill
13.11.4 What the Sample Application Does
You can run the client in either of two modes: you can specify that the server be killed or you can specify a single object to bind to. The object name is specified by a namespace pathname, but neither of the two possible objects is a namespace entry. Instead, the sample application implements a "junction" located at its server entry in the namespace, and clients bind to objects through this junction.
When the client tries to bind to the overqualified CDS entry formed by concatenating the specified object name to the server entry name it obtains a partial binding to the server. The client then makes a call to the remote bind operation with that binding, ostensibly to get the object UUID of the object whose name was specified (to bind to) when the client was invoked. These objects reside in a backing store database. The remote call makes its way by the familiar procedure to the server; the application's name_to_object( ) routine (defined in sample_bind.c) then simply looks up the desired object UUID by accessing the name-indexed backing store. When the remote call completes, the client has a full binding and the desired object UUID.
13.11.5 Viewing the Server ACL
With the sample_server running, you can also access the server's ACL managers using dcecp. For example, to get a list of the contents of the ACL, enter:
dcecp -c acl show /.:/sample/sample_server_entry/sample_object
This command produces the following output:
{user sample_client rwdctx}
The same commands can be used to bind to and list the contents of the server_mgmt ACL.
The README file contains sample output from the Generic Application.
For further information the acl object in dcecp, see the OSF DCE Command Reference.
13.11.6 Notes
A detailed explanation of the operation of the ACL management code is in the OSF DCE Application Development Guide - Introduction and Style Guide.
The sample application does not use the OSF DCE dced facilities, by which a DCE application can be registered (either via calls to the dced_server_ routines or via dcecp by a system administrator) with dced, and then, by means of calls to the dce_server_ routines, to have dced do almost all of its namespace and security initialization for it. For more information on the dced_server_ and dce_server_ routines and their use, see the OSF DCE Application Development Guide - Introduction and Style Guide and the OSF DCE Application Development Guide - Core Components.
13.12 Object Oriented idl Programs
This section describes how to build and run four example programs that demonstrate the use of C++ idl extensions. The four programs are
13.12.1 Preparing to Run the Example Programs
The C++ example programs require C++ software to be installed and configured on the client and server machines.
Establish your environment for building and running the example programs as follows:
-
Copy the four example programs into a directory tree with a root name of ./idlcxx.
% cp _R /usr/examples/dce/rpc/idlcxx/* .
The ./idlcxx directory has the following files and subdirectories
-
Log in to the DCE cell as cell_admin and run the idlcxx_setup shell script. This creates a test directory in the Cell Directory Service and establishes necessary ACL entries.
% dce_login
Enter Principal Name: cell_admin
Enter Password:
% idlcxx_setup
%
Once a server has been built and is executing, you can start and stop client programs as many times as desired. You can remove the executable client and server programs from a directory using the command:
% make clean
13.12.2 The account Example Program
The account example program tests inheritance, binding to an object using another interface, binding to an object with an unsupported interface, and the reflexive, symmetrixc, and transitive relation properties of the bind( ) API. A Savings interface is derived from an Account interface. A now/Account implementation class is derived from the Savings and Checking interfaces. A oldAccount implementation class is derived from the Savings but not the checking class which implies that an oldAccount does not support a Checking interface.
This example program requires C++ software to be installed and configured on the client and server machines.
Build this example program by entering the command:
% make
Start the server by entering the command:
% ./server &
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 on the client system that can be used to locate the server binding information in the namespace during the auto-handle process:
% setenv RPC_DEFAULT_ENTRY /.:/subsys/DEC/examples/account_server
After you define the environment variable, run the client with the command:
% client
The client binds to an object, uses different interfaces, and binds to dynamic interfaces. It also exercises bind relation properties.
13.12.3 The accountc Example Program
The accountc example program tests the same properties as the account program (see Section 13.12.1 on page 180), but uses the C interfaces for all the APIs.
This example program requires C++ software to be installed and configured on the client and server machines.
Build this example program by entering the command:
% make
Start the server by entering the command:
% ./server &
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 on the client system that can be used to locate the server binding information in the namespace during the auto-handle process:
% setenv RPC_DEFAULT_ENTRY /.:/subsys/DEC/examples/accountc_server
After you define the environment variable, run the client with the command:
% client
13.12.4 The card Example Program
The card example program tests the passing of C++ objects as parameters using the [cxx_delegate] attribute and the polymorphism property of the base class. A Player implementation class is a generic sports card class. Derived from Player are a BaseballPlayer class and a BasketballPlayer class. The application interfaces with the Player class to invoke virtual operations in the derived class.
This example program requires C++ software to be installed and configured on the client and server machines.
Build this example program by entering the command:
% make
Start the server by entering the command:
% ./server &
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 on the client system that can be used to locate the server binding information in the namespace during the auto-handle process:
% setenv RPC_DEFAULT_ENTRY /.:/subsys/DEC/examples/card_server
After you define the environment variable, run the client with the command:
% client
13.12.5 The stack Example Program
The stack example program tests the passing of C++ objects as parameters using the [cxx_delegate] attribute and a user defined Stack class. This test implements a reverse Polish notation algorithm where the binary arithmetic operations are performed on the server.
This example program requires C++ software to be installed and configured on the client and server machines.
Build this example program by entering the command:
% make
Start the server by entering the command:
% ./server &
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 on the client system that can be used to locate the server binding information in the namespace during the auto-handle process:
% setenv RPC_DEFAULT_ENTRY /.:/subsys/DEC/examples/stack_server
After you define the environment variable, run the client with the command:
% client
[Previous]
[Next]
[Contents]
[Index]
To make comments or ask for help, contact
support@entegrity.com.
Copyright © 2001 Entegrity Solutions Corporation & its subsidiaries.
Copyright © 1998-2001 Compaq Computer Corporation.
All rights reserved.