VMS Help DCE_RPC, Application Routines, rpc_ns_mgmt_handle_set_exp_age  *Conan The Librarian (sorry for the slow response - running on an old VAX)

 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