SetDirectoryOptions Method (IPISDKOptions interface)



This method takes a  NamedValues collection of directory option names and their intended state and sets the corresponding in-memory flags used to control behaviors.  The method returns a PIErrors collection. Before calling this method, the user must first instantiate either the PISDK object and the Servers collection or a ServerManager object.  


object.SetDirectoryOptions pnvsDirectoryOptions, bPersist

The object placeholder is an object expression that evaluates to a IPISDKOptions interface, obtained from a PISDK object.

The SetDirectoryOptions method syntax has these parts:





An object expression that evaluates to an IPISDKOptions interface.


Passed NamedValues collection containing the names and statuses of the behaviors to be set.  The contained NamedValue objects should have their Name property set to one of the supported options below and their value property set to 0 (false) to turn off the option and non-zero (true) to turn on the behavior.  If the NamedValues collection is empty (count is 0) the method sets the options to the defaults respecting the bPersist flag. 


Passed boolean that indicates whether the changes should be persisted to the registry where they affect all applications.  See "Remarks" below.



The supported settings for pnvsDirectoryOptions are:


Setting Description Default
AutoAdd When looking for a server in Servers.Item or ServerManager.Item, if an entry from the Known Servers Table (including checking aliases, etc.) can't be found, create a new Server object and return it. In the case of Servers, there is no request to connect so the only check by default is that the passed name can be resolved to an IP address. For ServerManager, if a connection cannot be made with the new server, an error is returned. True
CheckIP The check for a network resolvable name when performing an "AutoAdd" can be disabled by the "CheckIP" setting . True



The values associated with the names in the collection are treated as booleans where values of  0 represent FALSE and a non zero value for TRUE.

 The "set" method allows the caller to optionally persist the behavior. Persisted behaviors, whether turning them on or off, will affect all subsequently run PI-SDK applications unless they explicitly set behaviors for themselves.  Setting these behaviors in a persistent manner is an administrative behavior, typically performed once.  Reading and setting these behaviors without persisting is a typical application behavior. 

To support a partial success (not all settings could be changed) the method returns success but the PIErrors collection will contain one or more PIError objects where the Cause property is set to the name of the behavior where the error occurred. 


Trappable Errors

In addition to generic errors (such as Out of Memory), the following errors may occur:



E_INVALIDARG, E_POINTER Some of the function arguments are not valid.
pseNOSERVERSORSRVMGR The Servers collection or the ServerManager have not yet been instantiated.
pseUNKNOWNPARENTTYPE The type of the collection holding servers is unrecognized.
pseFAILEDCAST Cast failed.  _NamedValues to NamedValues smart pointer
pseOPENINGREGKEY Error opening registry key.
pseREGVALWRITE Failed to set a registry value.
Enabling Operational Intelligence