NAME

rpc_ns_mgmt_set_exp_age- Modifies an application's global expiration age for cached copies of name service data

SYNOPSIS

#include <dce/rpc.h>

void rpc_ns_mgmt_set_exp_age(
	unsigned32 expiration_age,
	unsigned32 *status);

PARAMETERS

Input

expiration_age

Specifies the application's global expiration age, in seconds, for cached copies of name service data.

Applications can reset the expiration age to the implementation-specific default by supplying the value rpc_c_ns_default_exp_age.

Output

status

Returns the status code from this routine. The status code indicates whether the routine completed successfully, or if not, why not.

Possible status codes and their meanings include:

rpc_s_ok

Success.

DESCRIPTION

The rpc_ns_mgmt_set_exp_age() routine sets the application's global name service expiration age.

The effect of expiration age on name service operations is implementation-dependent. For implementations that cache name service data, the expiration age is the maximum amount of time, in seconds, that a cached copy of data from a name service attribute is considered valid by name service operations that read data from a name service. Name service routines that may be affected by expiration age are as follows:

 

rpc_ns_binding_import_done()
rpc_ns_binding_lookup_next()
rpc_ns_entry_object_inq_next()
rpc_ns_group_mbr_inq_next()
rpc_ns_profile_elt_inq_next()

Implementations that cache look for cached copies of the requested data. When there is no cached copy, the operation creates one with fresh data from the name service database. When there is a cached copy, the operation compares its age with the calling application's expiration age. If the copy's age exceeds the expiration age, the operation attempts to update the cached copy with fresh data from the name service. If updating fails, the cached data remains unchanged and the requested operation fails, returning the rpc_s_name_service_unavailable status code.

Implementations that do not cache behave as if the expiration age were 0 (zero). Fresh data is always retrieved from the name service.

Every application maintains a global expiration age value. When an application begins running, the RPC run-time system specifies an implementation-dependent default global expiration age for the application. Applications may query this value by calling rpc_ns_mgmt_inq_exp_age(). Applications may also set the expiration ages of individual name service handles. Whenever a name service operation is performed using a handle for which the application has not set an expiration age, the global expiration age value is used.

Note:

In implementations that cache name service data, setting the expiration age to a small value may cause operations that retrieve data from the name service to update cached data frequently. An expiration age of 0 (zero) forces an update on each operation involving the same attribute data. Frequent updates may adversely affect the performance both of the calling application and any other applications that share the same cache.

Permissions Required

None.

RETURN VALUE

None.

SEE ALSO

rpc_ns_mgmt_handle_set_exp_age()
rpc_ns_mgmt_set_exp_age()
rpc_ns_binding_import_done()
rpc_ns_binding_lookup_next()
rpc_ns_entry_object_inq_next()
rpc_ns_group_mbr_inq_next()
rpc_ns_profile_elt_inq_next().

Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.