4. Building RPC Client and Server Programs

Introduction

This chapter deals with building client and server programs using the IDL stubs.

tidl -cc_cmd "CC -c" -keep all t.idl
CC=CC buildserver -o server -s tv1_0 -f "-I. t_sstub.o server.c -ltrpc"

In the DOS, Windows, and OS/2 environments, C++ compilation is normally accomplished via a flag on the compilation command line or a configuration option rather than a different command name. Use the appropriate options to get C++ compilation.

Interoperability with DCE/RPC

The BEA TUXEDO TxRPC compiler uses the same IDL interface as OSF/DCE but the generated stubs do not use the same protocol. Thus, a BEA TUXEDO TxRPC stub cannot directly communicate with a stub generated by the DCE IDL compiler.

However, it is possible to have the following interoperations between DCE/RPC and BEA TUXEDO TxRPC:

Client side stubs from both DCE and BEA TUXEDO TxRPC can be called from the same program (either client or server).
A BEA TUXEDO server stub can call application code that calls a DCE client stub (as well as a BEA TUXEDO TxRPC client stub).
A DCE server (manager) can call application code that calls a BEA TUXEDO TxRPC client stub.

The following sections show possible interactions between BEA TUXEDO TxRPC and OSF/DCE. In each case, the originator of the request is called the requester. This term is used instead of "client" because the requester could, in fact, be a DCE or BEA TUXEDO service making a request of another service. The terms "client" and "server" refer to the client and server stubs generated by the IDL compilers (either DCE idl(1) or BEA TUXEDO tidl(1)); these terms are used for consistency with the DCE and TxRPC terminology. Finally, the term "application service" is used for the application code that implements the procedure that is being called remotely (it is generally transparent whether the invoking software is the server stub generated by DCE or BEA TUXEDO).

BEA TUXEDO Requester to DCE Service via BEA TUXEDO Gateway

Figure 4-1 BEA TUXEDO Requester to DCE Service via BEA TUXEDO Gateway

The first approach uses a "gateway" such that the BEA TUXEDO client stub invokes a BEA TUXEDO server stub, via TxRPC, that has a DCE client stub linked in (instead of the application services) that invokes the DCE services, via DCE RPC. The advantage to this approach is that it is not necessary to have DCE on the client platform (e.g., in the case of NETWARE or Workstation platforms such as DOS). In fact, the set of machines running BEA TUXEDO and the set of machines running DCE could be disjoint except for one machine where all such gateways are running. This also provides a migration path with the ability to move services between BEA TUXEDO and DCE.

A sample application that implements this approach is described in Appendix B, "A DCE-Gateway Application."

In this configuration, the requester is built as a normal BEA TUXEDO client or server. Similarly, the server is built as a normal DCE server. The additional step is to build the gateway process which acts as a BEA TUXEDO server using a TxRPC server stub and a DCE client using a DCE/RPC client stub.

The process of running the two IDL compilers and linking the resultant files is simplified with the use of the blds_dce(1) command, which builds a BEA TUXEDO server with DCE linked in.

The usage for blds_dce is as follows.

blds_dce [-o output_file] [-i idl_options] [-f firstfiles] [-l lastfile] \
   [idl_file . . . ]

The command takes as input one or more IDL files so that the gateway can handle one or more interfaces. For each one of these files, tidl is run to generate a server stub and idl is run to generate a client stub.

This command knows about various DCE environments and provides the necessary compilation flags and DCE libraries for compilation and linking. If you are developing in a new environment, it may be necessary to modify the command to add the options and libraries for your environment.

This command compiles the source files in such a way (with -DTMDCEGW defined) that memory allocation is always done using rpc_ss_allocate(3c) and rpc_ss_free(3c). This ensures that memory is freed on return from the BEA TUXEDO server. The use of -DTMDCEGW also includes DCE header files instead of BEA TUXEDO TxRPC header files.

The IDL output object files are compiled, optionally with specified application files (using the -f and -l options), to generate a BEA TUXEDO server using buildserver(1). The name of the executable server can be specified with the -o option.

When running this configuration, the DCE server would be started first in the background, then the BEA TUXEDO configuration including the DCE gateway would be booted, and then the requester would be run. Note that the DCE gateway is single-threaded so you will need to configure and boot as many gateway servers as you want concurrently executing services.

There are several optional things to consider when building this gateway.

Setting the DCE Login Context

First, as a DCE client, it is normal that the process runs as some DCE principal. There are two approaches to getting a login context. One approach is to "log in" to DCE. In some environments, this occurs simply by virtue of logging into the operating system. In many environments, it requires running dce_login. If the BEA TUXEDO server is booted on the local machine, then it is possible to run dce_login, then run tmboot(1) and the booted server will inherit the login context. If the server is to be booted on a remote machine which is done indirectly via tlisten(1), it is necessary to run dce_login before starting tlisten. In each of these cases, all servers booted in the session will be run by the same principal. The other drawback to this approach is that the credentials will eventually expire.

The other alternative is to have the process set up and maintain its own login context. The tpsvrinit(3c) function provided for the server can set up the context and then start a thread that will refresh the login context before it expires. Sample code to do this is provided in $TUXDIR/lib/dceserver.c; it must be compiled with the -DTPSVRINIT option to generate a simple tpsvrinit function. (It can also be used as the main() for a DCE server, as described in the following section.) This code is described in further detail in Appendix B, "A DCE-Gateway Application."

Using DCE Binding Handles

BEA TUXEDO TxRPC does not support binding handles. When sending an RPC from the requester's client stub to the server stub within the gateway, the BEA TUXEDO system handles all of the name resolution and choosing the server, doing load balancing between available servers. However, when going from the gateway to the DCE server, it is possible to use DCE binding. If this is done, it is recommended that two versions of the IDL file be used in the same directory or that two different directories be used to build the requester, and the gateway and server. The former approach of using two different file names is shown in the example with the IDL file linked to a second name. In the initial IDL file, no binding handles or binding attributes are specified. With the second IDL file, which is used to generate the gateway and DCE server, there is an associated ACF file that specifies [explicit_handle] such that a binding handle is inserted as the first parameter of the operation. From the BEA TUXEDO server stub in the gateway, a NULL handle will be generated (because handles aren't supported). That means that somewhere between the BEA TUXEDO server stub and the DCE client stub in the gateway, a valid binding handle must be generated.

This can be done by making use of the manager entry point vector. By default, the IDL compiler defines a structure with a function pointer prototype for each operation in the interface, and defines and initializes a structure variable with default function names based on the operation names. The structure is defined as

<INTERF>_v<major>_<minor>_epv_t<INTERF>_v<major>_<minor>_s_epv

where <INTERF> is the interface name and <major>.<minor> is the interface version. This variable is dereferenced when calling the server stub functions. The IDL compiler option, -no_mepv, inhibits the definition and initialization of this variable, allowing the application to provide it in cases where there is a conflict or difference in function names and operation names. In the case where an application wants to provide explicit or implicit binding instead of automatic binding, the -no_mepv option can be specified, and the application can provide a structure definition that points to functions taking the same parameters as the operations but different (or static) names. The functions can then create a valid binding handle that is passed, either explicitly or implicitly, to the DCE/RPC client stub functions (using the actual operation names).

This is shown in the example in Appendix B, "A DCE-Gateway Application." The file dcebind.c generates the binding handle, and the entry point vector and associated functions are shown in dceepv.c.

Note that to specify the -no_mepv option when using the blds_dce, the -i -no_mepv option must be specified so that the option is passed through to the IDL compiler. This is shown in the makefile, rpcsimp.mk, in Appendix B, "A DCE-Gateway Application."

Authenticated RPC

Now that we have a login context and a handle, it is possible to use authenticated RPC calls. As part of setting up the binding handle, it is also possible to annotate the binding handle for authentication by calling rpc_binding_set_auth_info(). This is shown as part of generating the binding handle in dcebind.c in Appendix B, "A DCE-Gateway Application." This sets up the authentication (and potentially encryption) between the gateway and the DCE server. If the requester is a BEA TUXEDO server, then it is guaranteed to be running as the BEA TUXEDO administrator. For more information about authentication for BEA TUXEDO clients, see Administering the BEA TUXEDO System.

Transactions

OSF/DCE does not support transactions. That means that if the gateway is running in a group with a resource manager and the RPC comes into the BEA TUXEDO client stub in transaction mode, the transaction will not carray to the DCE server. There is not much you can do to solve this; just be aware of it.

DCE Requester to BEA TUXEDO Service Using BEA TUXEDO Gateway

Figure 4-2 DCE Requester to BEA TUXEDO Service Using BEA TUXEDO Gateway

In this figure, the DCE requester uses a DCE client stub to invoke a DCE service which calls the BEA TUXEDO client stub (instead of the application services), which invokes the BEA TUXEDO service (via TxRPC). Note that in this configuration, the client has complete control over the DCE binding and authentication. The fact that the application programmer builds the middle server means that the application also controls the binding of the DCE server to BEA TUXEDO service. This approach would be used in the case where the DCE requester does not want to directly link in and call the BEA TUXEDO system.

The main() for the DCE server should be based on the code provided in $TUXDIR/lib/dceserver.c. If you already have your own template for the main() of a DCE server, there are a few things that may need to be added or modified.

First, tpinit(3c) should be called to join the BEA TUXEDO application. If application security is configured, then additional information may be needed in the TPINIT buffer such as the user name and application password. Prior to exiting, tpterm(3c) should be called to cleanly terminate participation in the BEA TUXEDO application. If you look at dceserver.c, you will see that by compiling it with -DTCLIENT, code is included that calls tpinit and tpterm. The code that sets up the TPINIT buffer must be modified appropriately for your application. To provide more information with respect to administration, it might be helpful to indicate that the client is a DCE client in either the user or client name (the example sets the client name to DCECLIENT). This information shows up when printing client information from the administration interface.

Second, since the BEA TUXEDO system software is not thread-safe, the threading level passed to rpc_server_listen must be set to one. In the sample dceserver.c, the threading level is set to 1 if compiled with -DTCLIENT and to the default, rpc_c_listen_max_calls_default, otherwise.

In this configuration, the requester is built as a normal DCE client or server. Similarly, the server is built as a normal BEA TUXEDO server. The additional step is to build the gateway process, which acts as a BEA TUXEDO client using a TxRPC client stub, and a DCE server, using a DCE/RPC server stub.

The process of running the two IDL compilers and linking the resultant files is simplified with the use of the bldc_dce(1) command which builds a BEA TUXEDO client with DCE linked in.

The usage for bldc_dce is as follows.

bldc_dce [-o output_file] [-w] [-i idl_options] [-f firstfiles] \
   [-l lastfiles] [idl_file . . . ]

The command takes as input one or more IDL files so that the gateway can handle one or more interfaces. For each one of these files, tidl is run to generate a client stub and idl is run to generate a server stub.

This command knows about various DCE environments and provides the necessary compilation flags and DCE libraries. If you are developing in a new environment, it may be necessary to modify the command to add the options and libraries for your environment. The source is compiled in such a way (with -DTMDCEGW defined) that memory allocation is always done using rpc_ss_allocate(3c) and rpc_ss_free(3c) to ensure that memory is freed on return. The use of -DTMDCEGW also includes DCE header files instead of BEA TUXEDO TxRPC header files.

The IDL output object files are compiled, optionally with specified application files (using the -f and -l options), to generate a BEA TUXEDO client using buildclient(1). Note that one of the files included should be the equivalent of the dceserver.o, compiled with the -DTCLIENT option.

The name of the executable client can be specified with the -o option.

When running this configuration, the BEA TUXEDO configuration must be booted before starting the DCE server so that it can join the BEA TUXEDO application before listening for DCE requests.

BEA TUXEDO Requester to DCE Service Using DCE-only

Figure 4-3 BEA TUXEDO Requester to DCE Service Using DCE-only

The approach assumes that the DCE environment is directly available to the client (this can be a restriction or disadvantage in some configurations). The client program has direct control over the DCE binding and authentication. Note that this is presumably a mixed environment in which the requester is either a BEA TUXEDO service that calls DCE services, or a BEA TUXEDO client (or server) that calls both BEA TUXEDO and DCE services.

When compiling BEA TUXEDO TxRPC code that will be used mixed with DCE code, the code must be compiled such that DCE header files are used instead of the TxRPC header files. This is done by defining -DTMDCE at compilation time, both for client and server stub files and for your application code. If you are generating object files from tidl, you must add the -cc_opt -DTMDCE option to the command line. The alternative is to generate c_source from the IDL compiler and pass this C source (not object files) to bldc_dce or blds_dce as in the following examples.

tidl -keep c_source -server none t.idl
idl -keep c_source -server none dce.idl
bldc_dce -o output_file -f client.c -f t_cstub.c -f dce_cstub.c

blds_dce -o output_file -s service -f server.c -f t_cstub.c -f dce_cstub.c

In this example, we are not building a gateway process so .idl files cannot be specified to the build commands. Also note that the blds_dce command cannot figure out the service name associated with the server so it must be supplied on the command line using the -s option.

DCE Requester to BEA TUXEDO Service Using BEA TUXEDO-only

Figure 4-4 DCE Requester to BEA TUXEDO Service Using BEA TUXEDO-only

In this final case, the DCE requester calls the BEA TUXEDO client stub directly.

Again, -DTMDCE must be used at compilation time, both for client and server stub files and for your application code. In this case the requester must be a BEA TUXEDO client.

tidl -keep c_source -client none t.idl
bldc_dce -o output_file -f -DTCLIENT -f dceserver.c -f t_cstub.c

Note that dceserver.c should call tpinit(3c) to join the application and tpterm(3c) to leave the application, as was discussed earlier.

Building Mixed DCE/RPC and BEA TUXEDO TxRPC Clients and Servers

This section summarizes the rules to follow if you are compiling a mixed client or server without using the bldc_dce or blds_dce commands:

When compiling the generated client and server stubs, and compiling the client and server application software that includes the header file generated by tidl, TMDCE must be defined (for example, -DTMDCE=1). This causes some DCE header files to be used instead of the BEA TUXEDO TxRPC header files. Also, some versions of DCE have a DCE compilation shell that adds the proper directories for the DCE header files and ensures the proper DCE definitions for the local environment. This shell should be used instead of directly using the C compiler. The DCE/RPC compiler and TMDCE definition can be specified using the -cc_cmd option on tidl. For example,
```
tidl -cc_cmd "/opt/dce/bin/cc -c -DTMDCE=1" simp.idl
```
or
```
tidl -keep c_source simp.idl 
 /opt/dce/bin/cc -DTMDCE=1 -c -I. -I$TUXDIR/include simp_cstub.c
 /opt/dce/bin/cc -DTMDCE=1 -c -I. -I$TUXDIR/include client.c
```
On a system without such a compiler shell, it might look like the following:
```
cc <DCE options> -DTMDCE=1 -c -I. -I$(TUXDIR)/include \
   -I/usr/include/dce simp_cstub.c
```
Refer to the DCE/RPC documentation for your environment.
If the server makes an RPC call, then set_client_alloc_free() should be called to set the use of rpc_ss_allocate() and rpc_ss_free(), as described earlier.
When linking the executable, use -ldrpc instead of -ltrpc to get a version of the BEA TUXEDO TxRPC run-time that is compatible with DCE/RPC. For example,
```
buildclient -o client -f client.o -f simp_cstub.o -f dce_cstub.o \
   -f-ldrpc -f-ldce -f-lpthreads -f-lc_r
```
or
```
CC=/opt/dce/bin/cc buildclient -d " " -f client.o -f simp_cstub.o \ 
   -f dce_cstub.o -f -ldrpc -o client
```
Assume that simp_cstub.o was generated by tidl and dce_cstub.o was generated by idl. The first example shows building the client without a DCE compiler shell; in this case, the DCE library (-ldce), threads library (-lpthreads), and re-entrant C library (-lc_r) must be explicitly specified. The second example shows the use of a DCE compiler shell which transparently includes the necessary libraries. In some environments, the libraries included by buildserver and buildclient for networking and XDR will conflict with the libraries included by the DCE compiler shell (there may be reentrant versions of these libraries). In this case, the buildserver and buildclient libraries may be modified using the -d option. If a link problem occurs, trying using -d " " to leave out the networking and XDR libraries, as shown in the example above. If the link still fails, try running the command without the -d option and with the -v option to determine the libraries that are used by default; then use the -d option to specify a sub-set of the libraries if there is more than one. The correct combination of libraries is environment-dependent because the networking, XDR, and DCE libraries vary from one environment to another.
Mixing DCE and BEA TUXEDO TxRPC stubs is not currently supported on DOS, Windows, or OS/2.

[Top] [Prev] [Next] [Bottom]