Skip Headers
Programming an Oracle Tuxedo Application Using TxRPCs
  Go To Table Of Contents
Contents

Previous
Previous
 
Next
Next
 

2 Using the Interface Definition Language (IDL)

This topic includes the following sections:

References

Oracle Tuxedo TxRPC supports the IDL grammar and associated functionality as described in Chapter 3 ("Interface Definition Language") of DCE: REMOTE PROCEDURE CALL (Doc Code: P312 ISBN 1-872630-95-2). This book is available from the following.

X/OPEN Company Ltd (Publications)

P O Box 109

Penn

High Wycombe

Bucks HP10 8NP

United Kingdom

Tel: +44 (0) 494 813844

Fax: +44 (0) 494 814989

The X/OPEN document is the ultimate authority on the language and rules adhered to for the Oracle Tuxedo product in an ATMI environment. Note that the X/OPEN TxRPC IDL-only interface is supported (parts of the document concerning the DCE binding and run time do not apply). The X/OPEN document is based on the OSF DCE AES/RPC document. There are several books containing tutorials and programmer's guides that can be used, although most will not contain the latest features. The programmer's guide available from OSF is OSF DCE Application Development Guide, published by Prentice-Hall (Englewood Cliffs, New Jersey, 07632).

The X/OPEN Preliminary Specification for TxRPC Communication Application Programming Interface is also available from X/OPEN (see above). TxRPC adds transaction support for RPCs to the original X/OPEN RPC interface.

Using uuidgen to Create an IDL Template

A Universal Unique Identifier (UUID) is used to uniquely identify an interface. The uuidgen command is used to generate UUIDs. The output might look something like the following:

$ uuidgen -i > simp.idl
$ cat simp.idl
[uuid(816A4780-A76B-110F-9B3F-930269220000)]
interface INTERFACE
{
}

This template is then used to create the IDL input file for the application (adding type definitions, constants, and operations).

If both the ATMI and DCE uuidgen(1) commands are available, the DCE command can and should be used to generate the template (the DCE version will most likely have a machine-specific approach to getting the node address, as described below).

The ATMI uuidgen command is similar to the DCE command with the exception that the -s option (which generates a UUID string as an initialized C structure), and the -t option (which translates an old style UUID string to the new format) are not supported. See the uuidgen(1) reference page for details of the interface.

The uuidgen command requires a 48-bit node address as described in ISO/IEC 8802-3 (ANSI/IEEE 802.3). There is no platform-independent way to determine this value, and it may not be available at all on some machines (a workstation, for example). The following approach is used for the ATMI uuidgen command:

Changes in the Language

The IDL compiler recognizes the IDL grammar and generates stub functions based on the input. The grammar and its semantics are fully described in both the X/OPEN and OSF/DCE references listed earlier in this chapter. The grammar will be recognized in its entirety with some changes as described in the following sections.

Changes Based on the TxRPC Specification

The following are changes to the base X/OPEN RPC specification that are defined by the X/OPEN TxRPC specification:

Enhancements to the Language

The following are enhancements to the X/OPEN RPC specification. In most cases, the language has been enhanced to more closely follow the C language, simplifying the porting of existing interfaces (converting from ANSI C to IDL prototypes).

Enhancements that May Limit Portability

There are four additional Oracle Tuxedo ATMI enhancements to the X/OPEN RPC specification that, while making the specification more C-like, are not supported in the OSF DCE IDL compiler and thus have the effect of limiting portability of the IDL file:

  • String concatenation is supported (as in ANSI C). That is:

    const char *str = "abc" "def";
    

    is treated the same as

    const char *str = "abcdef";
    
  • Escaped newlines are allowed in string constants. That is:

    const char *str = "abc\
     def";
    

    is treated the same as

    const char *str = "abcdef";
    
  • Enumeration values may also be used in union cases and are treated as integers (that is, automatic conversion is provided as in C).

  • The restriction that the type of each <union_case_label> must be that specified by the <switch_type_spec> will not be enforced. Instead, the type will be coerced as is done with case statements in a C switch statement.

Unsupported Features

The following seven features are not supported in the tidl compiler:

Using tidl, the IDL Compiler

The interface for the IDL compiler is not specified in any X/OPEN specification.

For DCE application portability, the Oracle Tuxedo ATMI IDL compiler has a similar interface to the DCE IDL compiler, with the following exceptions:

By default, the IDL compiler takes an input IDL file and generates the client and server stub object files. The -keep c_source option generates only the C source files, and the -keep all option keeps both the C source and object files. The sample RPC application, listed in Appendix A, "A Sample Application," uses the -keep object option to generate the object files.

By default, at most 50 errors are printed by tidl. If you want to see them all (and have more than 50 errors), use the -error all option. The error output is printed to the stderr.

See tidl(1) in the Oracle Tuxedo Command Reference for details on the many other options that are available.