Using Stub Support Functions


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Documentation \| Programming BEA Tuxedo ATMI Applications Using TxRPC \| Local Topics \| Previous Topic \| Next Topic \| Contents

There are a large number of run-time support functions (over 100) defined in the X/OPEN RPC specification. These functions need not all be supported in an X/OPEN TxRPC IDL-only environment. Most of these functions relate to binding and management which are done transparently for ATMI clients and servers.

One area that affects application portability is the management of memory allocated for stub input and output parameters and return values. The Stub Memory Management routines are supported in TxRPC run time with the exception of the two routines to handle threads. The status-returning functions include:

rpc_sm_allocate
rpc_sm_client_free
rpc_sm_disable_allocate
rpc_sm_enable_allocate
rpc_sm_free
rpc_sm_set_client_alloc_free
rpc_sm_set_server_alloc_free
rpc_sm_swap_client_alloc_free

The equivalent exception-returning functions include:

rpc_ss_allocate
rpc_ss_client_free
rpc_ss_disable_allocate
rpc_ss_enable_allocate
rpc_ss_free
rpc_ss_set_client_alloc_free
rpc_ss_set_server_alloc_free
rpc_ss_swap_client_alloc_free

Refer to BEA 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.

The following are a few tips regarding memory management:

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:
```
rpc_ss_set_client_alloc_free(rpc_ss_allocate, rpc_ss_free);
ptr = remote_call_returns_pointer();
/* use returned pointer here */
...
rpc_ss_disable_allocate(); /* this frees ptr */
```
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:
```
rpc_ss_set_client_alloc_free(rpc_ss_allocate, rpc_ss_free);
```
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:
```
long *ptr;
ptr = (long *)rpc_ss_allocate(sizeof(long));
```