The TxRPC feature allows programmers to use a remote procedure call (RPC) interface, such that a client process can call a remote function (that is, a remote service) in another process using a local function call. The application writer must specify the operations (that is, procedures) and data types that are used as parameters to those operations via an Interface Definition Language (IDL). Operations are grouped together in an interface. An IDL compiler is used to generate substitute procedures called stubs which allow the operation to be remote. An important concept to understand from the beginning is that there are two fundamental levels of naming: the interface has a name and within an interface, one or more operations are named. At run time, the interface is made available, which means that any of the operations in the interface can be called; an individual operation within an interface cannot be made available (if you need this, define the operation in its own interface).Figure 1‑1 illustrates how an RPC is made to look like a local procedure call.Figure 1‑1 RPC CommunicationIn addition to the steps needed for building a monolithic application, it is necessary to completely define the interface between the client and server. As stated earlier, the interface contains the definition of data types and operations used for the remote procedure calls. Normally, the name of the file containing the definition has an “.idl” suffix; using this convention makes the file type self-documenting.Every interface must have its own unique identifier. This Universal Unique Identifier (UUID) consists of 128-bits that uniquely identify the interface among all interfaces. The job of generating a UUID is done for the application programmer by the uuidgen program. By running the uuidgen program with the -i option, it generates an interface template that contains a new UUID. Refer to Appendix , A Sample Application for a complete example (including code) for the development of a simple RPC application; the first step illustrates how to run the uuidgen command and the resulting output. More information about other options of this command are given in the uuidgen(1) manual page.Once the template IDL is generated by uuidgen, the application program must provide a definition of all data types and operations in the interface. The language looks very much like the declarative parts of C or C++ (without the procedural statements). Data types are declared via typedef statements, and the operations are declared via function prototypes. Additional information is provided via IDL attributes. Attributes appear in the language within square brackets, for example, [in]. These provide information about such things as pointer types (for example, whether or not a pointer can be NULL at run time), about parameters (for example, whether a parameter is for input, output, or both), and much more. The IDL language and the associated compiler are discussed further in Using the Interface Definition Language (IDL) on page 2‑1.In addition to the IDL file, an optional Attribute Configuration File (ACF) may also be provided to give additional attributes of the interface. Most important is the definition of status variables in the operations for returning the status of each RPC operation. The use of status variables will be discussed further in Writing RPC Client and Server Programs on page 3‑1. Attributes in the ACF file do not affect the communications between the client and server (as do attributes in the IDL file), but generally have an impact on the interface between the application code and the generated stubs.The IDL and optional ACF files are compiled using the IDL compiler. The compiler first generates a header file that contains all of the type definitions and function prototypes for the operations defined in the IDL file. This header file can be included in application code that makes RPC calls defined in the interface. If the input files are file.idl and file.acf, then the default header file name is file.h. The compiler generates stub code for both the client and server (for example, file_cstub.c and file_sstub.c). These stub files were described earlier and contain the data packaging and communications for the RPC. By default, the IDL compiler invokes the C compiler to generate client and server stub object files (for example, file_cstub.o and file_sstub.o) and the stub source files are removed. There are various IDL compiler options to request, limit generation of, and keep source and object files, and change the output filenames and directories. See the tidl(1) reference page for further details.After completing the interface definition, the major portion of work is writing the application code. The client code will call the operations defined in the interface, and the server code must implement the operations (note that a server can also act as a client by calling an RPC). Further considerations regarding writing the application are discussed in Using the Interface Definition Language (IDL) on page 2‑1.When the application code is completed, it’s time to compile and link it together with the Oracle Tuxedo ATMI run time. Two programs are provided to simplify this process: buildserver for the server, and buildclient for the client. These programs compile any source files and link the object and library files with the Oracle Tuxedo ATMI run time to produce the executable files. These programs allow for alternate compilers and compilation options to be specified. See the buildserver(1) and buildclient(1) reference pages for further details.The complete process for building a server and client are shown in Figure 1‑2 and Figure 1‑3. More details about building client and server programs on different platforms are provided in “Building RPC Client and Server Programs” on page 4‑1.Figure 1‑2 Building an RPC ServerFigure 1‑2 illustrates the following steps in the process for building a server:
1. Run uuidgen to generate a skeleton IDL file (simp.idl) with a UUID. Edit the template IDL file to define the interface between the client and server using the interface definition language.
2. Run the IDL compiler (tidl) using simp.idl and optional simp.acf to generate the interface header file and the server stub object file.
3. After writing the server application code (server.c), run buildserver to compile it and link it with the server stub, Oracle Tuxedo ATMI run time, and TxRPC run time to generate an executable server.Figure 1‑3 Building an RPC Client
4. Using the IDL file created in Step 1, run the IDL compiler (tidl) to generate the interface header file and the client stub object file.
5. After writing the client application code (client.c), run buildclient to compile it and link it with the client stub, Oracle Tuxedo ATMI run time, and TxRPC run time to generate an executable client.