SetEnvironmentOptions Method (IPISDKOptions interface)

                    

 

This method takes an ordered  NamedValues collection of environment option names and values and sets the corresponding in-memory flags and structures. The method returns a PIErrors collection. 

Syntax

object.SetEnvironmentOptions pnvsEnvironmentOptions, bPersist

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

The SetEnvironmentOptions method syntax has these parts:

 

Part Description

object

An object expression that evaluates to an IPISDKOptions interface.

pnvsEnvironmentOptions

Passed NamedValues collection containing the names of the desired environment options and their values. If the NamedValues collection is empty (count is 0) the method sets the options to the defaults respecting the bPersist flag. 

bPersist

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

Settings

The supported settings for environment options are:

Setting Description Default
NOPISDKBUFFERING  Flag to enable or disable automatic buffering with pibufss in PISDK 1.4 and later. false
BUFFER_RECOVERABLE_DELAY_SECS Time in seconds the PI-SDK waits after receiving a recoverable error from the buffering subsystem before retrying. 60
BUFFER_RETRY_OPEN_DELAY_SECS Time in seconds the PI-SDK waits after failing to open a collective member server for registration only before retrying. 120
BUFFEREDSERVER For buffering configurations that support only one server or collective, this setting selects which server is buffered. For buffering configurations that support multiple servers, this setting has no effect.  
UILANGUAGE The language which the PISDK uses for displaying PIConstant strings, and COM control strings. The value may be the LCID or LANGID for the chosen language. Using LANG_USER_DEFAULT, LANG_SYSTEM_DEFAULT will reset the mode to use the operating system user or system settings, respectively. Otherwise, changing system or user language settings has no effect on the PISDK strings if another language has been entered. See remarks for further information. 0
SDKCODEPAGE The code page used by the PISDK for transforming UNICODE to multi-byte strings for PI tag and module string attributes. The value -1 is a special case that enables the feature to set the corresponding code page when the UILANGUAGE setting is changed. See remarks for further information. 0
SDKLOCALRPCTIMEOUT The timeout setting for calls to local subsystems such as the buffer subsystem and message subsystem. 5

 

Remarks

 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. 

The UILANGUAGE setting may be used to return constants such as ArchiveSummaryTypeConstants in the specified language. The resources must be available for that language. The COM based common controls (connection manager, tag search) are also affected by this setting and will show controls in the specified language.

Setting SDKCODEPAGE for PIPoint and Module string attributes enables the PISDK to switch the code page used for transformation of UNICODE strings to and from multi-byte format. An example of when this may be useful is using the code page for Japanese (1041, 0x0411) on an operating system set to English (1033, 0x0409). Any PIPoints created or read will use the new code page. If a subsequent client reads the PIPoints created with a different code page, the strings may not be correctly transformed to UNICODE. A special case may be that the code page 65001 for UTF-8 may allow any clients to read the PIPoints created in the same way. Using UTF-8 may not enable correct transformation of PIPoints previously created with a different code page.

The PITimeServer parsing and output strings are not affected by this language setting. In order to change the PITimeServer language, modify the thread locale in the application, or use the control panel locale setting application (regional settings, or format settings depending on which operating system).

The string to floating point translations use the system settings instead of the UILANGUAGE setting. These settings may be modified using the regional settings dialog for Windows.

 

Trappable Errors

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

Error Description
E_INVALIDARG, E_POINTER Some of the function arguments are not valid.
pseFAILEDCAST Cast failed.  _NamedValues to NamedValues smart pointer
pseOPENINGREGKEY Error opening registry key.
pseREGVALWRITE Failed to set a registry value.
Enabling Operational Intelligence