rpc_ns_mgmt_handle_set_exp_age(3rpc)
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.
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.
Errors
The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.
rpc_s_ok
Success.
rpc_s_invalid_ns_handle
Invalid name service handle.
Related Information
Functions: rpc_ns_binding_import_begin(3rpc)
rpc_ns_binding_lookup_begin(3rpc)
rpc_ns_entry_object_inq_begin(3rpc)
rpc_ns_group_mbr_inq_begin(3rpc)
rpc_ns_profile_elt_inq_begin(3rpc)