Preferences
[Integration Tool Kit]

Detailed Description

Teamcenter has implemented preferences functions that allows users to customize the operating environment.

Detailed information is supplied for the following aspects of preferences functions:

The location of preference files, and the precedence rules employed in reading and writing to them.
The syntax of preference codes and values.
The Preference codes currently defined for preferences in Teamcenter.

Teamcenter makes use of this mechanism itself, and it also provides ITK level functions for programmers to make use of the same preference mechanism.
Programmers can define their own preference codes if they wish, or they can read and write to existing Teamcenter preferences.

If you intend to add new preference codes, we suggest that you prefix them with your company name, thus ensuring that they will not conflict with any preference codes that Teamcenter may implement in the future.

Note:: Teamcenter may alter or obsolete preference codes as the product evolves. These changes will be documented in the Release Notes.

The ITK preference functions include:

An initialization function
A function to inquire on the number of values a specified preference code has
Functions to read and write values of a specified preference code.

To use these functions, include preferences.h.

Data Structures

Typedefs

typedef enum
TC_preference_search_scope_e TC_preference_search_scope_t
typedef enum PREF_import_actions_e PREF_import_actions_t
typedef enum PREF_preference_type_e PREF_preference_type_t
typedef struct
PREF_preference_definition_t * PREF_preference_definition_p_t
typedef struct
PREF_preference_context_values_t * PREF_preference_context_values_p_t
typedef struct
PREF_preference_object_t * PREF_preference_object_p_t

Enumerations

Functions

TC_API int PREF_initialize (void)
TC_API int PREF_reinitialize ()
TC_API int PREF_set_search_scope (TC_preference_search_scope_t scope)
TC_API int PREF_ask_search_scope (TC_preference_search_scope_t *scope)
TC_API int PREF_set_protection_scope (const char *preference_name, TC_preference_search_scope_t protection_scope)
TC_API int PREF_set_protection_scopes (int preference_count, const char **preference_names, TC_preference_search_scope_t protection_scopes[])
TC_API int PREF_ask_protection_scope (const char *preference_name, TC_preference_search_scope_t *protection_scope)
TC_API int PREF_ask_protection_scopes (int preference_count, const char **preference_names, TC_preference_search_scope_t **protection_scopes)
TC_API int PREF_set_environment_set_flag (const char *preference_name, logical flag)
TC_API int PREF_set_environment_set_flags (int preference_count, const char **preference_names, const logical flag[])
TC_API int PREF_ask_environment_set_flag (const char *preference_name, logical *flag)
TC_API int PREF_ask_environment_set_flags (int preference_count, const char **preference_names, logical **flags)
TC_API int PREF_ask_value_count (const char *preference_name, int *value_count)
TC_API int PREF_ask_value_count_at_location (const char *preference_name, TC_preference_search_scope_t location, int *value_count)
TC_API int PREF_set_char_values (const char *preference_name, int value_count, char *values[])
TC_API int PREF_set_char_values_at_location (const char *preference_name, TC_preference_search_scope_t location, int value_count, char *values[])
TC_API int PREF_ask_char_value (const char *preference_name, int index, char **value)
TC_API int PREF_ask_char_values (const char *preference_name, int *count, char ***value)
TC_API int PREF_ask_char_value_at_location (const char *preference_name, TC_preference_search_scope_t location, int index, char **value)
TC_API int PREF_ask_char_values_at_location (const char *preference_name, TC_preference_search_scope_t location, int *count, char ***values)
TC_API int PREF_set_int_values (const char *preference_name, int value_count, int values[])
TC_API int PREF_set_int_values_at_location (const char *preference_name, TC_preference_search_scope_t location, int value_count, int values[])
TC_API int PREF_ask_int_value (const char *preference_name, int index, int *value)
TC_API int PREF_ask_int_values (const char *preference_name, int *value_count, int **values)
TC_API int PREF_ask_int_value_at_location (const char *preference_name, TC_preference_search_scope_t location, int index, int *value)
TC_API int PREF_ask_int_values_at_location (const char *preference_name, TC_preference_search_scope_t location, int *value_count, int **values)
TC_API int PREF_set_double_values (const char *preference_name, int value_count, double values[])
TC_API int PREF_set_double_values_at_location (const char *preference_name, TC_preference_search_scope_t location, int value_count, double values[])
TC_API int PREF_ask_double_value (const char *preference_name, int index, double *value)
TC_API int PREF_ask_double_values (const char *preference_name, int *value_count, double **values)
TC_API int PREF_ask_double_value_at_location (const char *preference_name, TC_preference_search_scope_t location, int index, double *value)
TC_API int PREF_ask_double_values_at_location (const char *preference_name, TC_preference_search_scope_t location, int *value_count, double **values)
TC_API int PREF_set_logical_value (const char *preference_name, logical value)
TC_API int PREF_set_logical_values (const char *preference_name, int value_count, logical values[])
TC_API int PREF_set_logical_values_at_location (const char *preference_name, TC_preference_search_scope_t location, int value_count, logical values[])
TC_API int PREF_ask_logical_value (const char *preference_name, int index, logical *value)
TC_API int PREF_ask_logical_values (const char *preference_name, int *value_count, logical **values)
TC_API int PREF_ask_logical_value_at_location (const char *preference_name, TC_preference_search_scope_t location, int index, logical *value)
TC_API int PREF_ask_logical_values_at_location (const char *preference_name, TC_preference_search_scope_t location, int *value_count, logical **values)
TC_API int PREF_set_definition (const char *preference_name, PREF_preference_object_t preference_object, logical env_variable_enabled)
TC_API int PREF_delete_definition (int nb_of_preferences, const char **preference_names, logical delete_all_custom_definitions)
TC_API int PREF_refresh (const char *preference_name)
TC_API int PREF_export_preference_list (int preference_count, char **preference_names, TC_preference_search_scope_t location, const char *output_file_name)
TC_API int PREF_export_preferences (TC_preference_search_scope_t location, const char *output_file_name)
TC_API int PREF_export_preferences_with_category (TC_preference_search_scope_t location, int number_of_categories, char **categories, const char *output_file_name)
TC_API int PREF_import_preferences (TC_preference_search_scope_t location, const char *input_xml, PREF_import_actions_t action)
TC_API int PREF_import_preferences_with_category (TC_preference_search_scope_t location, const char *input_xml, int number_of_categories, char **category_names, PREF_import_actions_t action)
TC_API int PREF_delete_preference (const char *preference_name)
TC_API int PREF_delete_preference_at_location (const char *preference_name, TC_preference_search_scope_t location)
TC_API int PREF_delete_non_session_preference (char *preference_name, tag_t object)
TC_API int PREF_lock_site_preferences ()
TC_API int PREF_unlock_site_preferences ()

Typedef Documentation

typedef enum PREF_import_actions_e PREF_import_actions_t

typedef struct PREF_preference_context_values_t * PREF_preference_context_values_p_t

typedef struct PREF_preference_definition_t * PREF_preference_definition_p_t

typedef struct PREF_preference_object_t * PREF_preference_object_p_t

typedef enum PREF_preference_type_e PREF_preference_type_t

typedef enum TC_preference_search_scope_e TC_preference_search_scope_t

Enumeration Type Documentation

enum PREF_import_actions_e

Different actions that can be specified during an import operation, in case of conflict.

Enumerator:

PREF_import_action_skip	Skip the operation for the preference
PREF_import_action_override	Override with the specified preference
PREF_import_action_merge	Merge the specified preference values with the existing ones

Definition at line 76 of file preferences.h.

enum PREF_preference_type_e

Defines the supported preference types

Enumerator:

PREF_preference_string	Preference of type String
PREF_preference_logical	Preference of type Logical
PREF_preference_integer	Preference of type Integer
PREF_preference_double	Preference of type Double
PREF_preference_date	Preference of type Date

Definition at line 86 of file preferences.h.

enum TC_preference_search_scope_e

Defines different values that can be used as protection scopes or value locations.

Enumerator:

TC_preference_all	All scope - Deprecated
TC_preference_user	User value
TC_preference_role	Role value
TC_preference_group	Group value
TC_preference_site	Site value
TC_preference_system	System value (for protection scope only)
TC_preference_cots_location	COTS value (for location only)
TC_preference_overlay_location	OVERLAY value (for location only)
TC_preference_env_variable_location	Environment value (for location only)

Definition at line 61 of file preferences.h.

Function Documentation

TC_API int PREF_ask_char_value	(	const char *	preference_name,
		int	index,
		char **	value
	)

Asks the value of a preference whose data type is char. Index is used to determine which value to retrieve if the preference has multiple values. Index starts at 0.

Parameters:

preference_name	(I) The name of the preference
index	(I) The index of the value to retrieve
value	(OF) The returned value

TC_API int PREF_ask_char_value_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int	index,
		char **	value
	)

Asks the value of a preference whose data type is char at a specific level.
Index is used to determine which value to retrieve if the preference has multiple values. Index starts at 0.

Valid values for the location are TC_preference_user , TC_preference_role , TC_preference_group , TC_preference_site and TC_preference_overlay_location.
The value TC_preference_site applies also to System preferences.

The function returns:

ITK_ok on success. If there is no value at the provided location, the output value will be a null pointer.
PREF_value_cannot_be_asked_at_location, if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location, if the location is invalid.
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND, if the preference does not exist.

Parameters:

preference_name	(I) The name of the preference
location	(I) The location where to retrieve the value
index	(I) The index at which to retrieve the value
value	(OF) The returned value

TC_API int PREF_ask_char_values	(	const char *	preference_name,
		int *	count,
		char ***	value
	)

Asks all the values of the preference whose data type is char.

Note: This ITK returns values array in packed format.
Do not use SM_free on the returned elements and then SM_free on the container.
Do not use TC_free_strings on the container.
The proper way to release the allocated memory is by using SM_free on the container alone

Parameters:

preference_name	(I) Preference name
count	(O) Number of values in the value array
value	(OF) count Array of returned values

TC_API int PREF_ask_char_values_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int *	count,
		char ***	values
	)

Asks all the values of the preference whose data type is char.

Valid values for the location are TC_preference_user , TC_preference_role , TC_preference_group , and TC_preference_site.
The value TC_preference_site applies also to System preferences.

The function returns:

ITK_ok on success
PREF_value_cannot_be_asked_at_location, if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location, if the location is invalid.
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND, if the preference does not exist.

Note: This ITK returns values array in packed format.
Do not use SM_free on the returned elements and then SM_free on the container.
Do not use TC_free_strings on the container.
The proper way to release the allocated memory is by using SM_free on the container alone

Parameters:

preference_name	(I) The name of the preference
location	(I) The location where to retrieve the values
count	(O) The number of values in the value array
values	(OF) count The array of values

TC_API int PREF_ask_double_value	(	const char *	preference_name,
		int	index,
		double *	value
	)

Asks the value of a preference whose data type is double.
Index is used to determine which value to retrieve if the preference has multiple values. Index starts at 0.

Parameters:

preference_name	(I) The name of the preference
index	(I) The index of the value to retrieve
value	(O)

TC_API int PREF_ask_double_value_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int	index,
		double *	value
	)

Asks the value of a preference whose data type is double at a given location.

Index is used to determine which value to retrieve if the preference has multiple values. Index starts at 0.

Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, TC_preference_site and TC_preference_overlay_location.
The value TC_preference_site applies also to System preferences.

The function returns:

ITK_ok on success. If there is no value at the provided location, the output value will be a null pointer.
PREF_value_cannot_be_asked_at_location, if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location, if the location is invalid.
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND, if the preference does not exist or does not have any value at this location.

Parameters:

preference_name	(I) The name of the preference
location	(I) The location where to retrieve the value
index	(I) The index of the value to retrieve
value	(O) The returned value

TC_API int PREF_ask_double_values	(	const char *	preference_name,
		int *	value_count,
		double **	values
	)

Asks all the values of the preference whose data type is double.

Parameters:

preference_name	(I) Preference name
value_count	(O) Number of values in the value array
values	(OF) value_count Array of returned values

TC_API int PREF_ask_double_values_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int *	value_count,
		double **	values
	)

Asks all the values of the preference whose data type is double at the specified location.

Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, and TC_preference_site.
The value TC_preference_site applies also to System preferences.

The function returns:

ITK_ok on success. If there is no value at the provided location, the output value will be a null pointer.
PREF_value_cannot_be_asked_at_location, if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location, if the location is invalid.
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND, if the preference does not exist.

Parameters:

preference_name	(I) The name of the preference
location	(I) The location where to retrieve the values
value_count	(O) The number of values in the value array
values	(OF) value_count The array of values

TC_API int PREF_ask_environment_set_flag	(	const char *	preference_name,
		logical *	flag
	)

Asks the flag that authorizes a preference value to come from an environment variable.

The function returns:

ITK_ok on success
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND, if the preference does not exist.

Parameters:

preference_name	(I) The name of the preference
flag	(O) The status for the environment set

TC_API int PREF_ask_environment_set_flags	(	int	preference_count,
		const char **	preference_names,
		logical **	flags
	)

Asks the flags that authorize preference values to come from an environment variable.

The function returns:

ITK_ok on success
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PREF_preferences_not_existing, if one of the preferences does not exist.

Parameters:

preference_count	(I) The number of preferences
preference_names	(I) The array of preference names
flags	(OF) preference_count The array of statuses for the environment set

TC_API int PREF_ask_int_value	(	const char *	preference_name,
		int	index,
		int *	value
	)

Asks the value of a preference whose data type is integer.
Index is used to determine which value to retrieve if the preference has multiple values. Index starts at 0.

Parameters:

preference_name	(I) The name of the preference
index	(I) The index of the value to retrieve
value	(O) The value

TC_API int PREF_ask_int_value_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int	index,
		int *	value
	)

Asks the value of a preference whose data type is integer at a given location.

Index is used to determine which value to retrieve if the preference has multiple values. Index starts at 0.

Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, TC_preference_site and TC_preference_overlay_location.
The value TC_preference_site applies also to System preferences.

The function returns:

ITK_ok on success. If there is no value at the provided location, the output value will be a null pointer.
PREF_value_cannot_be_asked_at_location, if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location, if the location is invalid.
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND, if the preference does not exist or does not have any value at this location.

Parameters:

preference_name	(I) The name of the preference
location	(I) The location where to retrieve the value
index	(I) The index of the value requested
value	(O) The returned value

TC_API int PREF_ask_int_values	(	const char *	preference_name,
		int *	value_count,
		int **	values
	)

Asks all the values of the preference whose data type is integer.

Parameters:

preference_name	(I) Preference name
value_count	(O) Number of values in the value array
values	(OF) value_count Array of returned values

TC_API int PREF_ask_int_values_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int *	value_count,
		int **	values
	)

Asks all the values of the preference whose data type is integer at the specified location.

Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, and TC_preference_site.
The value TC_preference_site applies also to System preferences.

The function returns:

ITK_ok on success. If there is no value at the provided location, the output value will be a null pointer.
PREF_value_cannot_be_asked_at_location, if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location, if the location is invalid.
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND, if the preference does not exist.

Parameters:

preference_name	(I) The name of the preference
location	(I) The location where to retrieve the values
value_count	(O) The number of values in the value array
values	(OF) value_count The array of values

TC_API int PREF_ask_logical_value	(	const char *	preference_name,
		int	index,
		logical *	value
	)

Asks the value of a preference whose data type is logical.

Index is used to determine which value to retrieve if the preference has multiple values. Index starts at 0.

The function returns:

ITK_ok on success
PREF_invalid_preference_name, if the string is invalid ('*', empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND, if the preference does not exist.

Important: The value is returned as specified at the first possible location starting at the location equal to the protectionScope of the preference.

Parameters:

preference_name	(I) The name of the preference
index	(I) The index of the value to retrieve
value	(O) The value

TC_API int PREF_ask_logical_value_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int	index,
		logical *	value
	)

Asks the value of a preference whose data type is logical at the specified location.

Index is used to determine which value to retrieve if the preference has multiple values. Index starts at 0.

Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, TC_preference_site and TC_preference_overlay_location.
The value TC_preference_site applies also to System preferences.

The function returns:

ITK_ok on success. If there is no value at the provided location, the output value will be a null pointer.
PREF_value_cannot_be_asked_at_location, if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location, if the location is invalid.
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND, if the preference does not exist or does not have any value at this location.

Parameters:

preference_name	(I) The name of the preference
location	(I) The location where to retrieve the value
index	(I) The index of the value to retrieve
value	(O) The returned value

TC_API int PREF_ask_logical_values	(	const char *	preference_name,
		int *	value_count,
		logical **	values
	)

Asks all the values of the preference whose data type is logical.

The function returns:

ITK_ok on success
PREF_invalid_preference_name, if the string is invalid ('*', empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND, if the preference does not exist.

Important:The value is returned as specified at the first possible location starting at the location equal to the protectionScope of the preference.

Parameters:

preference_name	(I) Preference name
value_count	(O) Number of values in the value array
values	(OF) value_count Array of returned values

TC_API int PREF_ask_logical_values_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int *	value_count,
		logical **	values
	)

Asks the value of a preference whose data type is logical at the specified location.

Index is used to determine which value to retrieve if the preference has multiple values. Index starts at 0.

Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, TC_preference_site and TC_preference_overlay_location.
The value TC_preference_site applies also to System preferences.

The function returns:

ITK_ok on success. If there is no value at the provided location, the output value will be a null pointer.
PREF_value_cannot_be_asked_at_location, if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location, if the location is invalid.
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND, if the preference does not exist.

Parameters:

preference_name	(I) The name of the preference
location	(I) The location where to retrieve the values
value_count	(O) The number of values in the array
values	(OF) value_count The array of values

TC_API int PREF_ask_protection_scope	(	const char *	preference_name,
		TC_preference_search_scope_t *	protection_scope
	)

Asks the protection scope for a given preference.
Possible returned values are TC_preference_user, TC_preference_role, TC_preference_group, TC_preference_site and TC_preference_system.

The function returns:

ITK_ok on success
PREF_invalid_protection_scope, if the protection scope is invalid.
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND, if the preference does not exist.

Parameters:

preference_name	(I) The name of the preference
protection_scope	(O) The protection scope of the preference

TC_API int PREF_ask_protection_scopes	(	int	preference_count,
		const char **	preference_names,
		TC_preference_search_scope_t **	protection_scopes
	)

Asks the protection scope for several given preferences.
Possible returned values are TC_preference_user, TC_preference_role, TC_preference_group, TC_preference_site and TC_preference_system.

The function returns:

ITK_ok on success
PREF_invalid_protection_scope, if the protection scope is invalid.
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PREF_preferences_not_existing, if one of the preferences does not exist.

Parameters:

preference_count	(I) The number of preferences
preference_names	(I) The array of preference names
protection_scopes	(OF) preference_count The array of protection scopes for the preferences

TC_API int PREF_ask_search_scope ( TC_preference_search_scope_t * scope )

Asks which preferences the system is considering when you ask for values.

Deprecated:: This function is deprecated and will be removed from Tc12. Please refer to the documentation on PREF_set_search_scope for more information.

Parameters:

scope

(O)

TC_API int PREF_ask_value_count	(	const char *	preference_name,
		int *	value_count
	)

Returns the number of values that exist for a particular preference name.

If the preference is not defined at all, returns a 0.

Parameters:

preference_name	(I) The name of the preference
value_count	(O) The number of values

TC_API int PREF_ask_value_count_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int *	value_count
	)

Returns the number of values that exist for a particular preference name at a specific level.
If the preference does not have an instance at the given location, the returned value count is 0.

Valid values for the location are TC_preference_user , TC_preference_role , TC_preference_group, and TC_preference_site.
The value TC_preference_site applies also to System preferences.

The function returns:

ITK_ok on success
PREF_value_cannot_be_asked_at_location, if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location, if the location is invalid.
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND, if the preference does not exist.

Parameters:

preference_name	(I) The number of preferences
location	(I) The location where to look for the preference
value_count	(O) The number of values at the location

TC_API int PREF_delete_definition	(	int	nb_of_preferences,
		const char **	preference_names,
		logical	delete_all_custom_definitions
	)

Deletes the customization made to the definition of the specified preferences.
If the intent is to delete the value, use PREF_delete_preference or PREF_delete_preference_at_location ITKs instead.

If the call is made with the deleteAllCustomDefinition flag set to true, then it is assumed that all custom definitions will be removed.
A custom definition is:

Any change made to the definition of a foundation preference (for instance a change in the protection scope).
Any preference (not part of the foundation preference list) that was imported.
Any preference that was created through the GUI or code API.

The preference definition will be removed, but the preference instances will not. Use the preferences_manager utility in "cleanup" mode in order to do that.

The function returns:

ITK_ok on success
PREF_delete_definitions_incorrect_arguments, if the deleteAllCustomDefinitions flag is set to true, and the nbOfPreferences argument is not 0 or the preference_names is not a null pointer.
SA_not_a_system_administrator, if the logged-in user does not have system administrator privileges.
PREF_preferences_not_existing, if one or more preferences do not exist. The call will proceed with the removal of the other preference definitions though.
PREF_cannot_delete_preference_definition, if one or more preferences are coming from the list of Teamcenter foundation preferences and their preference definitions have not been changed. The call will proceed with the removal of the other preference definitions though.

Parameters:

nb_of_preferences	(I) The number of preference definition to delete.
preference_names	(I) The name of the preferences.
delete_all_custom_definitions	(I) If set to true, indicates to delete all the custom definitions. The nbOfPreferences will need to be set to 0, and the pointer preference_names will need to be a null pointer.

TC_API int PREF_delete_non_session_preference	(	char *	preference_name,
		tag_t	object
	)

Deletes the specified preference instance from the specified location.

The location can be any location for which the logged-in user has privileges.

If an error is encountered during the deletion of any preference, the rest of the list will be skipped.

Parameters:

preference_name	(I) Name of the preference which instance is to be deleted
object	(I) User, Role or Group tag

TC_API int PREF_delete_preference ( const char * preference_name )

Deletes the specified preference instance from the location that matches the preference protection scope.

Restrictions:
If the preference being deleted is a site-protected preference, the logged-in user must have system administrative privileges.
If the preference being deleted is a group/role-protected preference, the logged-in user must have at least group administrative privileges.

Parameters:

preference_name

(I) Name of the preference which instance is to be deleted.

TC_API int PREF_delete_preference_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location
	)

Deletes the specified preference instance from the specified location.

The location are the ones as seen from the logged-in user.
Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, and TC_preference_site.
If the preference being deleted is a site-protected preference, the logged-in user must have system administrative privileges.
If the preference being deleted is a group/role-protected preference, the logged-in user must have at least group administrative privileges.

The function returns:

ITK_ok on success
PREF_insufficient_privileges, if the logged-in user does not have the privilege to remove instances at the provided location.
PREF_invalid_location, if the location is invalid.
PREF_instance_not_found_at_location, if the location is invalid.

Parameters:

preference_name	(I) Name of the preference which instance is to be deleted
location	(I) The location where to delete the preference instance

TC_API int PREF_export_preference_list	(	int	preference_count,
		char **	preference_names,
		TC_preference_search_scope_t	location,
		const char *	output_file_name
	)

Exports the specified preferences from the specified location to the specified output file.
Nothing will be exported if the named preferences are not found under the specified location.

The possible values for the location parameter are:

TC_preference_user Exports the specified preferences from the user location.

TC_preference_role Exports the specified preferences from the user location.

TC_preference_group Exports the specified preferences from the group location.

TC_preference_site Exports the specified preferences from the site location.

The user/role/group are the ones for the current logged-in user.

Parameters:

preference_count	(I) Number of preferences to export
preference_names	(I) Name of the preferences to export
location	(I) Location of the preferences to export
output_file_name	(I) Output export file name

TC_API int PREF_export_preferences	(	TC_preference_search_scope_t	location,
		const char *	output_file_name
	)

Exports all the preferences at the specified location to the specified output file.
Nothing will be exported if there are no preferences under the specified scope.
(For e.x. if the scope is specified as TC_preference_user, all the user preferences for the current logged in user would be exported.)

The possible values for the location parameter are:

TC_preference_user Exports all the preferences at the user location.

TC_preference_role Exports all the preferences at the user location.

TC_preference_group Exports all the preferences at the group location.

TC_preference_site Exports all the preferences at the site location.

The user/role/group are the ones for the current logged-in user.

Parameters:

location	(I) Location to be considered for export
output_file_name	(I) Output export file name

TC_API int PREF_export_preferences_with_category	(	TC_preference_search_scope_t	location,
		int	number_of_categories,
		char **	categories,
		const char *	output_file_name
	)

Exports all the preferences belonging to the specified categories from the specified location scope to the specified output file.
Nothing will be exported if there are no preferences matching the criteria at the specified location.
E.g. if the specified location is TC_preference_user, all the user preferences for the current logged-in user will be exported.

The possible values for the location parameter are:

TC_preference_user Exports all the preferences at the user location.

TC_preference_role Exports all the preferences at the role location.

TC_preference_group Exports all the preferences at the group location.

TC_preference_site Exports all the preferences at the site location.

The user/role/group are the ones for the current logged-in user.

Parameters:

location	(I) Location to be considered for export
number_of_categories	(I) Number of categories
categories	(I) Categories to be considered for export
output_file_name	(I) Output export file name

TC_API int PREF_import_preferences	(	TC_preference_search_scope_t	location,
		const char *	input_xml,
		PREF_import_actions_t	action
	)

Imports all the preferences in the specified xml file at the specified location.

The possible values for the location parameter are:

TC_preference_user Imports the preferences in the xml file at the user location.

TC_preference_role Imports the preferences in the xml file at the role location.

TC_preference_group Imports the preferences in the xml file at the group location.

TC_preference_site Imports the preferences in the xml file at the site location.

The user/role/group are the ones for the current logged-in user.

The action parameter specifies the action to be taken in the event of a preference existing in the database. The possible values for the action parameter are:

PREF_import_action_skip Skips the preference and does not do any further processing for this preference.

PREF_import_action_override Overrides the values of the preference in the database with the values in the specified xml file.

PREF_import_action_merge Merges the values for the preference in the database with the values in the specified xml file. This merge is a simple union of the values in the database and the xml file.

Restrictions:
If the specified location TC_preference_site, the logged-in user must have system administrative privileges.
If the specified location is TC_preference_group or TC_preference_role, the logged-in user must have at least group administrative privileges.

Parameters:

location	(I) Location where to import the preferences
input_xml	(I) Path to the input XML file name
action	(I) Action to be considered in the event of conflict with the information already present in the database

TC_API int PREF_import_preferences_with_category	(	TC_preference_search_scope_t	location,
		const char *	input_xml,
		int	number_of_categories,
		char **	category_names,
		PREF_import_actions_t	action
	)

Imports the preferences in the specified xml file, only from the specified categories, and into the specified location.

The possible values for the location parameter are:

TC_preference_user Imports the preferences in the xml file at the user location.

TC_preference_role Imports the preferences in the xml file at the role location.

TC_preference_group Imports the preferences in the xml file at the group location.

TC_preference_site Imports the preferences in the xml file at the site location.

The action parameter specifies the action to be taken in the event of a preference existing in the database. The possible values for the action parameter are:

PREF_import_action_skip Skips the preference and does not do any further processing for this preference.

PREF_import_action_override Overrides the values of the preference in the database with the values in the specified xml file.

PREF_import_action_merge Merges the values for the preference in the database with the values in the specified xml file. This merge is a simple union of the values in the database and the xml file.

Restrictions:
If the specified location is TC_preference_site, the logged-in user must have system administrative privileges.
If the specified location is TC_preference_group or TC_preference_role, the logged-in user must have at least group administrative privileges.

Parameters:

location	(I) Location where to import the preferences
input_xml	(I) Path to the input XML file name
number_of_categories	(I) Number of categories given as input
category_names	(I) Categories to be considered for import
action	(I) Action to be considered in the event of conflict with the information already present in the database

TC_API int PREF_initialize ( void )

Loads all of the values from the preference files.

TC_API int PREF_lock_site_preferences ( )

Locks site preferences. Use this to have exclusive modification privileges to site preferences. Once the modifications are done, use PREF_unlock_site_preferences() to unlock.

Restrictions: The logged-in user must have site administrative privileges.

TC_API int PREF_refresh ( const char * preference_name )

Refreshes those parts of the current Teamcenter session (if there is one) whose state depends on the value of the named preference. (Use of PREF_set_xxx functions alone affects only future sessions; subsequent use of this function affects the current session also.)

Restrictions: This function is currently only supported for the following preferences:

WS_Menu_Entry_Suppression
PSE_Menu_Entry_Suppression

Parameters:

preference_name

(I) Name of preference to refresh

TC_API int PREF_reinitialize ( )

Re-reads any appropriate preference files to reflect updates from outside the session

TC_API int PREF_set_char_values	(	const char *	preference_name,
		int	value_count,
		char *	values[]
	)

Sets the value(s) of a preference whose data type is char.

Parameters:

preference_name	(I) The name of the preference
value_count	(I) The number of values
values	(I) value_count The array of values

TC_API int PREF_set_char_values_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int	value_count,
		char *	values[]
	)

Sets the value(s) of a preference whose data type is char at a specific level.

Valid values for the locations are TC_preference_user , TC_preference_role , TC_preference_group , and TC_preference_site.
The value TC_preference_site applies also to System preferences.

The function returns:

ITK_ok on success
PREF_value_cannot_be_set_at_location, if the specified level does not match the existing protection scope for the preference.
PREF_invalid_location, if the location is invalid.
PREF_insufficient_privileges, if the logged-in user does not have the privilege to write at the given location:
1. Only system administrators can write at the site location
2. Only group administrators can write at the group or role location
3. Normal users can only write at the user location
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).

Important: If the preference does not exist, no error. Instead the preference will be created.
The value of the "location" argument will also become the protection scope.
However, the system will match what is possible:

if the logged-in user is a site administrator, any value can be given to the protection scope. The preference value will be set at the location.
if the logged-in user is a group administrator, the location can be anything but "TC_preference_site". If the value is "TC_preference_site", the protection scope of the preference and the location of the value will be set as "TC_preference_user".
if the logged-in user is a regular user, the protection scope of the preference and the location of the value will be set as "TC_preference_user".

Parameters:

preference_name	(I) The name of the preference
location	(I) The location where to set the values
value_count	(I) The number of values in the value array
values	(I) The array of values

TC_API int PREF_set_definition	(	const char *	preference_name,
		PREF_preference_object_t	preference_object,
		logical	env_variable_enabled
	)

Creates or changes a preference according to a PREF_preference_object structure.

The function returns:

ITK_ok on success
PREF_user_not_system_admin, if the logged-in user does not have the system privilege.

If the preference does not already exist in the database, all the declaration data will be needed, otherwise an error (as explained below) will be returned.

In the input structure:

preferenceName
- PREF_missing_preference_name, if the string is empty.
- PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
preferenceCategory
The name of the category where the preference is sorted.
This can be changed only for non-OOTB preferences.
If the string is empty, the parameter will not be taken into account. However, in case the preference has not been created yet, it will be assumed that the preference will go under the General category.
If the string is not empty, the code will consider this to be a category modification. Therefore:
- PREF_parameter_value_not_applicable_to_ootb_preferences, in case the value is different from the current value and the preference is an OOTB preference.
- PREF_invalid_definition_value will also be returned if the category does not exist yet in the system.
preferenceDescription
The description associated with the preference.
- If the string is empty, the parameter will not be taken into account.
  However, in case the preference has not been created yet, this parameter is mandatory otherwise the error PREF_missing_definition_parameter is returned.
- If the string is not empty, the code will consider this to be a description modification.
  Therefore, an error PREF_parameter_value_not_applicable_to_ootb_preferences, in case the value is different from the current value and the preference is an OOTB preference.
preferenceScope
The protection scope: valid values are User, Role, Group, Site and System.
- If the preference does not exist, this information is mandatory.
  PREF_invalid_definition_value will be returned if the protection scope is invalid.
- If the preference exists:
  If the string is empty, the parameter will not be taken into account.
  If the string is not empty, the code will consider this to be a modification. Therefore:
  - PREF_invalid_definition_value, if the protection scope is invalid.
  - PREF_no_protection_scope_change_on_ootb_system_preference will also be returned in case the value is different from the current value and the preference is an OOTB preference with protection scope of System.
preferenceType
Defines the type of the preference: PREF_preference_string, PREF_preference_logical, PREF_preference_integer, PREF_preference_double, PREF_preference_date.
If the preference does not exist, this piece of information will be needed.
If the preference exists and is an OOTB preference, this argument is discarded.
If the preference exists and is not an OOTB preference, the change will be taken into consideration. If the conversion from the old type to the new one is not possible, any further call to a "getPreferences" operation will revert to giving the value at the higher level instead of returning an error.
contextValues
The context information is discarded.

Parameters:

preference_name	(I) The name of the preference
preference_object	(I) The preference object describing the preference to add
env_variable_enabled	(I) Defines if the value for the given preference can come from the environment variable.

TC_API int PREF_set_double_values	(	const char *	preference_name,
		int	value_count,
		double	values[]
	)

Sets the value(s) of a preference whose data type is double. PREF_not_a_double_value, if one of the values is not a double.

Parameters:

preference_name	(I) The name of the preference
value_count	(I) The number of values
values	(I) value_count The array of values

TC_API int PREF_set_double_values_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int	value_count,
		double	values[]
	)

Sets the value(s) of a preference whose data type is double at a specific location.

Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, and TC_preference_site.
The TC_preference_site applies also to System preferences.

The function returns:

ITK_ok on success
PREF_invalid_location, if the location is invalid.
PREF_value_cannot_be_set_at_location, if the specified level does not match the existing protection scope for the preference.
PREF_insufficient_privileges, if the logged-in user does not have the privilege to write at the given location:
1. Only system administrators can write at the site location.
2. Only group administrators can write at the group or role location.
3. Normal users can only write at the user location.
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PREF_not_a_double_value, if one of the values is not a double.

Important: If the preference does not exist, no error,. Instead the preference will be created.
The value of the "location" argument will also become the protection scope.
However, the system will match what is possible:

if the logged-in user is a site administrator, any value can be given to the protection scope. The preference value will be set at the location.
if the logged-in user is a group administrator, the location can be anything but "TC_preference_site". If the value is "TC_preference_site", the protection scope of the preference and the location of the value will be set as "TC_preference_user".
if the logged-in user is a regular user, the protection scope of the preference and the location of the value will be set as "TC_preference_user".

Parameters:

preference_name	(I) The name of the preference
location	(I) The location where to set the value
value_count	(I) The number of values in the value array
values	(I) The array of values

TC_API int PREF_set_environment_set_flag	(	const char *	preference_name,
		logical	flag
	)

Sets the flag that authorizes a preference value to come from an environment variable.
Valid values are true (allow) or false.

The function returns:

ITK_ok on success
PREF_user_not_system_admin, if the user of is not a system administrator.
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND, if the preference does not exist.

Parameters:

preference_name	(I) The name of the preference
flag	(I) The status for the environment set

TC_API int PREF_set_environment_set_flags	(	int	preference_count,
		const char **	preference_names,
		const logical	flag[]
	)

Sets the flag that authorizes preference values to come from an environment variable.
Valid values are true (allow) or false.

The function returns:

ITK_ok on success
PREF_user_not_system_admin, if the user of is not a system administrator.
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PREF_preferences_not_existing, if one of the preferences does not exist.

Parameters:

preference_count	(I) The number of preferences
preference_names	(I) The array of preference names
flag	(I) The array of statuses for the environment set

TC_API int PREF_set_int_values	(	const char *	preference_name,
		int	value_count,
		int	values[]
	)

Sets the value(s) of a preference whose data type is integer. PREF_not_a_int_value, if one of the values is not an integer.

Parameters:

preference_name	(I) The name of the preference
value_count	(I) The number of values
values	(I) value_count The array of values

TC_API int PREF_set_int_values_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int	value_count,
		int	values[]
	)

Sets the value(s) of a preference whose data type is integer at a specific location.

Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, and TC_preference_site.
The value TC_preference_site applies also to System preferences.

The function returns:

ITK_ok on success
PREF_invalid_location, if the location is invalid.
PREF_value_cannot_be_set_at_location, if the specified level does not match the existing protection scope for the preference.
PREF_insufficient_privileges, if the logged-in user does not have the privilege to write at the given location:
1. Only system administrators can write at the site location
2. Only group administrators can write at the group or role location
3. Normal users can only write at the user location
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PREF_not_a_int_value, if one of the values is not an integer.

Important: If the preference does not exist, no error,. Instead the preference will be created.
The value of the "location" argument will also become the protection scope.
However, the system will match what is possible:

if the logged-in user is a site administrator, any value can be given to the protection scope. The preference value will be set at the location.
if the logged-in user is a group administrator, the location can be anything but "TC_preference_site". If the value is "TC_preference_site", the protection scope of the preference and the location of the value will be set as "TC_preference_user".
if the logged-in user is a regular user, the protection scope of the preference and the location of the value will be set as "TC_preference_user".

Parameters:

preference_name	(I) The name of the preference
location	(I) The location where to set the value
value_count	(I) The number of values in the value array
values	(I) The array of values

TC_API int PREF_set_logical_value	(	const char *	preference_name,
		logical	value
	)

Sets the value of a preference whose data type is logical

The function returns:

ITK_ok on success
PREF_invalid_preference_name, if the string is invalid ('*', empty string or a string only composed of any number of ' ' characters for instance).
PREF_insufficient_privileges, if the logged-in user does not have the privileges
1. Only system administrators can write at the site location.
2. Only group administrators can write at the group or role location.
3. Normal users can only write at the user location.
PREF_not_a_logical_value, if the value is not a logical.

Important: The value is set at the location which is the protection scope if the preference definition exist or else a runtime definition is created

Parameters:

preference_name	(I) The name of the preference
value	(I) The value

TC_API int PREF_set_logical_values	(	const char *	preference_name,
		int	value_count,
		logical	values[]
	)

Sets the values of a preference whose data type is logical

The function returns:

ITK_ok on success
PREF_invalid_preference_name, if the string is invalid ('*', empty string or a string only composed of any number of ' ' characters for instance).
PREF_insufficient_privileges, if the logged-in user does not have the privileges:
1. Only system administrators can write at the site location.
2. Only group administrators can write at the group or role location.
3. Normal users can only write at the user location.
PREF_not_a_logical_value, if one of the values is not a logical.

Important: The value is set at the location which is the protection scope if the preference definition exist or else a runtime definition is created

Parameters:

preference_name	(I) The name of the preference
value_count	(I) The number of values in the array
values	(I) The array of values

TC_API int PREF_set_logical_values_at_location	(	const char *	preference_name,
		TC_preference_search_scope_t	location,
		int	value_count,
		logical	values[]
	)

Sets the values of a preference whose data type is logical at the specified location.

Valid values for the location are TC_preference_user, TC_preference_role, TC_preference_group, and TC_preference_site.
The value TC_preference_site applies also to System preferences.

The function returns:

ITK_ok on success
PREF_invalid_location, if the location is invalid.
PREF_value_cannot_be_set_at_location, if the specified level does not match the existing protection scope for the preference.
PREF_insufficient_privileges, if the logged-in user does not have the privilege to write at the given location:
1. Only system administrators can write at the site location.
2. Only group administrators can write at the group or role location.
3. Normal users can only write at the user location.
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PREF_not_a_logical_value, if one of the values is not a logical.

Important: If the preference does not exist, no error,. Instead the preference will be created. br>The value of the "location" argument will also become the protection scope.
However, the system will match what is possible:

if the logged-in user is a site administrator, any value can be given to the protection scope. The preference value will be set at the location.
if the logged-in user is a group administrator, the location can be anything but "TC_preference_site". If the value is "TC_preference_site", the protection scope of the preference and the location of the value will be set as "TC_preference_user".
if the logged-in user is a regular user, the protection scope of the preference and the location of the value will be set as "TC_preference_user".

Parameters:

preference_name	(I) The name of the preference
location	(I) The location where to set the value
value_count	(I) The number of values in the array
values	(I) The array of values

TC_API int PREF_set_protection_scope	(	const char *	preference_name,
		TC_preference_search_scope_t	protection_scope
	)

Sets the protection scope for a given preference.
Valid values for the protection scope are TC_preference_user, TC_preference_role, TC_preference_group, TC_preference_site and TC_preference_system.
The TC_preference_system value is only to be used to convert a hierarchical preference to a System preference: this is only possible for non out-of-the-box preferences.

The function returns:

ITK_ok on success
PREF_invalid_protection_scope, if the protection scope is invalid.
PREF_user_not_system_admin, if the user of is not a system administrator.
PREF_cannot_change_protection_scope_of_system_pref, if the preference is an out-of-the-box system preference.
PREF_cannot_convert_to_system_pref, if the preference is an out-of-the-box hierarchical preference.
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PF_NOTFOUND will be returned, if the preference does not exist.

Parameters:

preference_name	(I) The name of the preference
protection_scope	(I) The new protection scope

TC_API int PREF_set_protection_scopes	(	int	preference_count,
		const char **	preference_names,
		TC_preference_search_scope_t	protection_scopes[]
	)

Sets the protection scope for several given preferences.
Valid values for the protection scopes are TC_preference_user, TC_preference_role, TC_preference_group, TC_preference_site and TC_preference_system.

The function returns:

ITK_ok on success
PREF_invalid_protection_scope if the protection scope is invalid.
PREF_user_not_system_admin, if the user of is not a system administrator.
PREF_cannot_change_protection_scope_of_system_prefs, if one of the preferences is an out-of-the-box system preference.
PREF_cannot_convert_to_system_prefs, if the preference is an out-of-the-box hierarchical preference.
PREF_invalid_preference_name, if the string is invalid ('*�, empty string or a string only composed of any number of ' ' characters for instance).
PREF_preferences_not_existing, if one of the preferences does not exist.

Parameters:

preference_count	(I) The number of preferences
preference_names	(I) The array of preference names
protection_scopes	(I) The array of new protection scopes

TC_API int PREF_set_search_scope ( TC_preference_search_scope_t scope )

Specifies which preferences you want to consider when asking for values. The possible values for this are:

TC_preference_all All preferences.

TC_preference_role Role preferences.

TC_preference_user User preferences.

TC_preference_group Group preferences.

TC_preference_site Site preferences.

Deprecated:: This function is deprecated and will be removed from Tc12. There is no replacement to this ITK, because the declared protection scope of the preference will enable the Preferences code layer to determine where to start looking for a preference value.
Therefore, starting Tc10.0, call the following:

to retrieve the preference value, simply call the PREF_ask_<type>_value or PREF_ask_<type>_values ITKs.
to set the preference value, simply call the PREF_set_<type>_values ITK.

If there is a need to obtain or set the preference value at a very specific location (and only then), use the PREF_ask/set_<type>_value/values_at_location ITKs.

Parameters:

scope

(I)

TC_API int PREF_unlock_site_preferences ( )

Unlocks site preferences.

Restrictions: The logged-in user must have site administrative privileges.

TC_preference_user	Exports the specified preferences from the user location.
TC_preference_role	Exports the specified preferences from the user location.
TC_preference_group	Exports the specified preferences from the group location.
TC_preference_site	Exports the specified preferences from the site location.

TC_preference_user	Exports all the preferences at the user location.
TC_preference_role	Exports all the preferences at the user location.
TC_preference_group	Exports all the preferences at the group location.
TC_preference_site	Exports all the preferences at the site location.

TC_preference_user	Imports the preferences in the xml file at the user location.
TC_preference_role	Imports the preferences in the xml file at the role location.
TC_preference_group	Imports the preferences in the xml file at the group location.
TC_preference_site	Imports the preferences in the xml file at the site location.

PREF_import_action_skip	Skips the preference and does not do any further processing for this preference.
PREF_import_action_override	Overrides the values of the preference in the database with the values in the specified xml file.
PREF_import_action_merge	Merges the values for the preference in the database with the values in the specified xml file. This merge is a simple union of the values in the database and the xml file.

TC_preference_all	All preferences.
TC_preference_role	Role preferences.
TC_preference_user	User preferences.
TC_preference_group	Group preferences.
TC_preference_site	Site preferences.

Preferences [Integration Tool Kit]

Detailed Description

Data Structures

Typedefs

Enumerations

Functions

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Preferences
[Integration Tool Kit]