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