NAME

   rpc_sm_set_thread_handle - Sets a thread handle for the stub memory
                              management environment

 SYNOPSIS

   #include <rpc.h>
   void rpc_sm_set_thread_handle ( rpc_sm_thread_handle_t id,
                                   unsigned32 *status );

 PARAMETERS

   Input

   id      Specifies a thread handle returned by a call to
           rpc_sm_get_thread_handle.

   Output

   status  Returns the status code from this routine.  This status code
           indicates whether the routine completed successfully or, if
           not, why not.

           Possible status codes and their meanings include:

           rpc_s_ok      Success.

 DESCRIPTION

   An application thread calls rpc_sm_set_thread_handle to set a thread
   handle for memory management within the stub memory management
   environment.  A thread that is managing memory within the stub memory
   managment scheme calls rpc_sm_get_thread_handle to get a thread handle
   for its current stub memory management environment.  A thread that
   calls rpc_sm_set_thread_handle with this handle is able to use the
   same memory management environment.

   When multiple threads call rpc_sm_allocate and rpc_sm_free to manage
   the same memory, they must share the same thread handle.  The thread
   that established the stub memory management environment calls
   rpc_sm_get_thread_handle to get a thread handle before spawning new
   threads that will manage the same memory.  The spawned threads then
   call rpc_sm_set_thread_handle with the handle provided by the parent
   thread.

   Typically, rpc_sm_set_thread_handle is called by a thread spawned by
   a server manager routine.  Normally the stub sets up the memory
   management environment for the manager routine and the manager calls
   rpc_sm_get_thread_handle to get a thread handle.  Each spawned thread
   then calls rpc_sm_get_thread_handle to get access to the manager's
   memory management environment.

   A thread may also use rpc_sm_get_thread_handle and
   rpc_sm_set_thread_handle to save and restore its memory
   management environment.

 RETURN VALUES

 RELATED INFORMATION

   Functions: rpc_sm_get_thread_handle
              rpc_sm_allocate
              rpc_sm_free