NAME

   rpc_ss_allocate - Allocates memory within the RPC stub memory
                     management scheme

   Used by server or possibly by client applications.

 SYNOPSIS

   #include <dce/rpc.h>

   idl_void_p_t rpc_ss_allocate( idl_size_t size );

 PARAMETERS

   Input

   size      Specifies, in bytes, the size of memory to be allocated.

   Note that in ANSI standard C environments, idl_void_p_t is defined as
   void * and in other environments is defined as char *.

 DESCRIPTION

   Usually, the rpc_ss_allocate() routine is used in the manager code
   that is called from a server stub.  Memory allocated by
   rpc_ss_allocate is released by the server stub after marshalling
   any output parameters at the end of the remote call in which the
   memory was allocated.  If you want to release memory allocated by
   rpc_ss_allocate() before returning from the manager code use
   rpc_ss_free().

   You can also use rpc_ss_free() in manager code to release memory
   pointed to by a full pointer (ptr) in an input parameter.

   When the server uses rpc_ss_allocate(), the server stub creates the
   environment the routine needs.  If the parameters of the operation
   include any pointers other than those used for passing parameters by
   reference, the environment is set up automatically.

   If you need to use rpc_ss_allocate() in a manager code routine that
   does not have a pointer in any of its parameters, use an ACF and apply
   the enable_allocate attribute to the relevant operation.  This causes
   the generated server stub to set up the necessary environment.

   Note that memory allocated by allocators other than rpc_ss_allocate()
   is not released when the operation on the server side completes
   execution.

   If you want to use rpc_ss_allocate() outside the code called from a
   server stub, you must first create an environment for it by calling
   rpc_ss_enable_allocate().

   See the OSF DCE Application Development Guide for more information.

 RETURN VALUES

   A pointer to the allocated memory.

   An exception, rpc_x_no_memory, when no memory is available for
   allocation.

 RELATED INFORMATION

  Functions:  rpc_ss_free
              rpc_ss_enable_allocate
              rpc_ss_disable_allocate
              rpc_ss_get_thread_handle
              rpc_ss_set_thread_handle