In the X/OPEN RPC specification, non-application errors are returned via status parameters or a status return. A fault_status value is returned if there is an RPC server failure and a comm_status value is returned if there is a communications failure. Status returns are specified by defining an operation return value or an [out] parameter of type error_status_t in the IDL file, and declaring the same operation or parameter to have the [fault_status] and/or [comm_status] attribute in the ACF file.The application delimits a block of C or C++ code in which an exception may be raised with the TRY, CATCH, CATCH_ALL, and ENDTRY statements. TRY indicates the beginning of the block. CATCH is used to indicate an exception-handling block for a specific exception, and CATCH_ALL is used to handle any exceptions for which there is not a CATCH statement. ENDTRY ends the block. TRY blocks are nested such that if an exception cannot be handled at a lower level, the exception can be raised to a higher level block using the RERAISE statement. If an exception is raised out of any exception handling block, the program writes a message to the log and exits. Details of the exception handling macros and an example are described in TRY(3c) in the Oracle Tuxedo C Function Reference.In addition to exceptions generated by the communications and server for an RPC call, exceptions are also generated for lower level exceptions, specifically operating system signals. These exceptions are documented within TRY(3c) in the Oracle Tuxedo C Function Reference.Refer to Oracle Tuxedo C Function Reference for more information on these functions.The run-time functions are contained in libtrpc; building RPC clients and servers is discussed in the next topic.
• When an ATMI client calls a client stub, it uses malloc and free by default. All space will be freed on return from the client stub except space allocated for [out] pointers (including implicit [out] pointers in the return value of the operation). To make freeing of [out] pointers easier, call rpc_ss_enable_allocate(), and set alloc/ free to rpc_ss_alloc()/ rpc_ss_free() before calling the RPC by calling rpc_ss_set_client_alloc_free(). Then rpc_ss_disable_allocate() can be used to free all of the allocated memory. For example, to simplify freeing space returned from a client stub the following could be used:
• When an ATMI server stub is executed that calls an application operation, memory allocation using rpc_ss_allocate is always enabled in the server stub. The [enable_allocate] attribute in the ACF file has no effect. All memory will be freed in the server before returning the response to the client. (In DCE, memory allocation is enabled only if [ptr] fields or parameters exist, or the programmer explicitly specifies [enable_allocate].)
• When a server stub calls an application operation which in turn calls a client stub (that is, when a server acts as a client by calling an RPC), the rpc_ss_set_client_alloc_free() function must be called to set up allocation such that any space allocated will be freed when the operation returns. This is done by calling:
• When calling rpc_ss_allocate() or rpc_sm_allocate(), remember to cast the output to match the data type of the pointer being set. For example:
• dce/nbase.h, dce/nbase.idl—renamed rpc/tbase.h and rpc/tbase.idl. Contain the declarations for pre-declared types error_status_t, ISO_LATIN_1, ISO_MULTI_LINGUAL, and ISO_UCS.
• dce/idlbase.h—renamed rpc/tidlbase.h. Contains the IDL base types, as defined in the specification (for example, idl_boolean, idl_long_int), and the function prototypes for the stub functions.
•
• dce/rpcsts.h—renamed rpc/trpcsts.h. Contains the exception and status value definitions for the RPC interface.These header files are located in $TUXDIR/include/rpc. The TxRPC IDL compiler will look in $TUXDIR/include by default as the “system IDL directory.”Constant values are, by default, implemented by generating a #define for each constant. This means that names used for constants should not be used for any other names in the IDL file or any imported IDL files. A TxRPC-specific option on the tidl compiler, -use_const, may be used to get around this problem in an ANSI C environment. This option will cause const declarations instead of #define definitions to be generated. The constant values will be declared in the client and server stubs, and any other source file including the header file will simply get extern const declarations. Note that this has the restriction that the client and server stubs may not be compiled into the same executable file (or duplicate definition errors will occur).
• Do not use the same name for a typedef and a structure or union tag, unless the typedef name matches the struct or union name.
• Warnings that a variable is used before being set when referenced in sizeof() as in the following case:When coding the client and server application software, you should use the data types generated by the IDL compiler, as defined in rpc/tidlbase.h (listed as Emitted Macro in the following table). For instance, if you use a long instead of idl_long_int, then the data type may be 32 bits on some platforms and 64 bits on others; idl_long_int will be 32 bits on all platforms. Table 3‑1 lists the generated data types.
Table 3‑1 Generated Data Types
• Constant, typedef, operation, and enumeration member names are in one name space.Note that an anonymous structure or union (without a tag and not defined as part of a typedef) cannot be used for an operation return or a parameter.The TxRPC executables use the Oracle Tuxedo system to do the RPC communications. Other Oracle Tuxedo interfaces and communications mechanisms can be used within the same clients and servers that are using the RPC calls. Thus, it is possible to have a single client making Request/Response calls (for example tpcall(3c), tpacall(3c), and tpgetrply(3c)), making conversational calls (tpconnect(3c), tpsend(3c), tprecv(3c), and tpdiscon(3c)), and accessing the stable queue (tpenqueue(3c) and tpdequeue(3c)). When a client makes the first call to the Oracle Tuxedo software, either an RPC call, any of these other communications calls, or any other ATMI call (such as a call for buffer allocation or unsolicited notification), the client automatically joins the application. However, if the application is running with security turned on or if the client must run as part of a particular resource manager group, then tpinit(3c) must be called explicitly to join the application. Refer to tpinit(3c) in the Oracle Tuxedo C Function Reference for further details, and a list of options that can be explicitly set. When an application completes work using the Oracle Tuxedo system, tpterm(3c) should be called explicitly to leave the application and free up any associated resources. If this is not done for native (non-Workstation) clients, the monitor detects this, prints a warning in the userlog(3c), and frees up the resources. In the case of Workstation clients, the resources may not be freed up and eventually the Workstation Listener or Handler will run out of resources to accept new clients.The TX functions provide an interface for transaction demarcation. tx_begin(3c) and tx_commit(3c) or tx_rollback(3c) encapsulate any work, including communications, within a transaction. Other primitives are provided to set transaction timeout, declare the transaction as chained or unchained, and retrieve transaction information. These are discussed in detail in the X/OPEN TX Specification, and reviewed in the X/OPEN TxRPC Specification. The X/OPEN TxRPC Specification indicates the interactions between TX and RPC. These are summarized as follows:
• An interface or an operation can have the [transaction_optional] attribute which indicates that if the RPC is called within a transaction, the work done in the called operation will be part of the transaction.
• An interface or an operation can have the [transaction_mandatory] attribute which indicates that the RPC must be called within a transaction or the txrpc_x_not_in_transaction exception is returned.
• If a TxRPC operation is called in the server and tx_open(3c) has not been called, a txrpc_x_no_tx_open_done exception is returned to the caller.