NAME

   rpc_ns_mgmt_handle_set_exp_age - Sets a handle's 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_handle_set_exp_age( rpc_ns_handle_t ns_handle,
                                        unsigned32 expiration_age,
                                        unsigned32 *status );

 PARAMETERS

   Input

   ns_handle
       Specifies the name service handle for which you supply an
       expiration age.  An RPC Name Service Interface (NSI) inquiry
       begin operation returns a name service handle.  An example is
       the operation that rpc_ns_entry_object_inq_begin() performs; it
       returns a name service handle in its inquiry_context parameter.

   expiration_age
       This integer value specifies the expiration age, in seconds, of
       local name service data. This data is read by all RPC NSI next
       routines that use the specified ns_handle parameter.  An example
       is the rpc_ns_entry_object_inq_next() routine; it accepts a name
       service handle in its inquiry_context parameter.  An expiration
       age of 0 (zero) causes an immediate update of the local name
       service data.

   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 codes and their meanings are as
       follows:

       rpc_s_ok                     Success.

       rpc_s_invalid_ns_handle      Invalid name service handle.

 DESCRIPTION

   The rpc_ns_mgmt_handle_set_exp_age() routine sets an expiration age
   for a specified name service handle (in ns_handle).  The expiration
   age is 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.  An expiration age
   applies only to a specific name service handle and temporarily
   overrides the current global expiration age.

   Normally, avoid using this routine; instead, rely on the application's
   global expiration age.

   A handle's expiration age is used exclusively by RPC NSI next
   operations (which read data from name service attributes). A next
   operation normally starts by looking for a local copy of the
   attribute data being requested by an application. 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 (which in this case is the expiration age
   set for the name service handle). If the actual age exceeds the
   handle's expiration age, the operation automatically tries to update
   the local copy with fresh attribute data. 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.

   The scope of a handle's expiration age is a single series of RPC NSI
   next operations.  The rpc_ns_mgmt_handle_set_exp_age() routine
   operates as follows:

    1.  An RPC NSI begin operation, such as the one performed by
        rpc_ns_group_mbr_inq_begin() creates a name service handle.

    2.  A call to rpc_ns_mgmt_handle_set_exp_age() creates an expiration
        age for the handle.

    3.  A series of corresponding RPC NSI next operations for the name
        service handle uses the handle's expiration age.

    4.  A corresponding RPC NSI done operation for the name service
        handle deletes both the handle and its expiration age.

   Permissions Required

   No permissions are required.

 CAUTIONS

   Use this routine with extreme caution.

   Setting the handle's expiration age to a small value causes the RPC
   NSI next operations to frequently update local data for any name
   service attribute requested by your application.  For example, setting
   the expiration age to 0 (zero) forces the next operation to update
   local data for the name service attribute requested by your
   application. Therefore, setting a small expiration age for a name
   service handle 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.

   Limit the use of this routine to the following types of situations:

     +  When you must always get accurate name service data. For example,
        during management operations to update a profile, you may need to
        always see the profile's current contents. In this case, before
        beginning to inquire about a profile, your application must call
        rpc_ns_mgmt_handle_set_exp_age() and specify 0 (zero) for the
        expiration_age parameter.

     +  When a request using the default expiration age fails, and your
        application needs to retry the operation.  For example, a client
        application using import must first try to obtain bindings using
        the application's default expiration age.  However, sometimes the
        import-next operation returns either no binding handles or an
        insufficient number of them.  In this case, the client can retry
        the import operation and, after rpc_ns_binding_import_begin()
        terminates, include a rpc_ns_mgmt_handle_set_exp_age() routine
        that specifies 0 (zero) for the expiration_age parameter.  When
        the client calls the import-next routine again, the small
        expiration age for the name service handle causes the import-next
        operation to update the local attribute data.

 RETURN VALUES

   No value is returned.

 RELATED INFORMATION

   Functions: rpc_ns_binding_import_begin
              rpc_ns_binding_lookup_begin
              rpc_ns_entry_object_inq_begin
              rpc_ns_group_mbr_inq_begin
              rpc_ns_mgmt_inq_exp_age
              rpc_ns_mgmt_set_exp_age
              rpc_ns_profile_elt_inq_begin