NAME

   rpc_ns_mgmt_set_exp_age - Modifies the application's global expiration
                             age for local copies of name service data

   Used by client, server, or management applications.

 SYNOPSIS

   #include <dce/rpc.h>

   void rpc_ns_mgmt_set_exp_age( unsigned32 expiration_age,
                                 unsigned32 *status );

 PARAMETERS

   Input

   expiration_age
       An integer value that specifies the default expiration age, in
       seconds, for local name service data.  This expiration age applies
       to all RPC name service interface (NSI) read operations (all the
       next operations).  An expiration age of 0 (zero) causes an
       immediate update of the local name service data.  To reset the
       expiration age to an RPC-assigned random value between 8 and 12
       hours, specify a value of rpc_c_ns_default_exp_age.

   Output

   status
       Returns the status code from this routine.  This status code
       indicates whether the routine completed successfully or, if not,
       why not.  The possible status code and its meaning is as follows:

       rpc_s_ok            Success.

 DESCRIPTION

   The rpc_ns_mgmt_set_exp_age() routine modifies the global expiration
   age that the application is using.  The expiration_age parameter
   represents the amount of time, in seconds, that a local copy of data
   from a name service attribute can exist before a request from the
   application for the attribute requires updating the local copy.  When
   an application begins running, the RPC runtime specifies a random
   value of between 8 and 12 hours as the default expiration age.  The
   default is global to the application.

   Normally, you should avoid using this routine; instead, rely on the
   default expiration age.

   The RPC NSI next operations, which read data from name service
   attributes, use an expiration age.  A next operation normally starts
   by looking for a local copy of the attribute data that an application
   requests.  In the absence of a local copy, the next operation creates
   one with fresh attribute data from the name service database.  If a
   local copy already exists, the operation compares its actual age to
   the expiration age being used by the application.  If the actual age
   exceeds the expiration age, the operation automatically tries to
   update the local copy with fresh attribute data from the name service
   database.  If updating is impossible, the old local data remains in
   place and the next operation fails, returning the
   rpc_s_name_service_unavailable status code.

   Permissions Required

   No permissions are required.

 CAUTIONS

   Use this routine with extreme caution.

   Setting the expiration age to a small value causes the RPC NSI next
   operations to frequently update local data for any name service
   attribute that your application requests.  For example, setting the
   expiration age to 0 (zero) forces all next operations to update local
   data for the name service attribute that your application has
   requested. Therefore, setting small expiration ages can create
   performance problems for your application.  Also, if your application
   is using a remote server with the name service database, a small
   expiration age can adversely affect network performance for all
   applications.

 RETURN VALUES

   No value is returned.

 RELATED INFORMATION

   Functions: rpc_ns_mgmt_handle_set_exp_age
              rpc_ns_mgmt_set_exp_age