Functions
int	mdlSystem_getCfgVar (WStringP value, WCharCP cfgVar)
	The mdlSystem_getCfgVar function retrieves the expanded value of the configuration variable cfgVar. More...

int	mdlSystem_getCfgVarAtLevel (WStringP value, WCharCP cfgVar, DgnPlatform::ConfigurationVariableLevel level)
	The mdlSystem_getCfgVarAtLevel function retrieves the expanded value of the configuration variable cfgVarNameP at a particular level. More...

int	mdlSystem_getCfgVarLevel (DgnPlatform::ConfigurationVariableLevel &level, WCharCP cfgVar)
	The mdlSystem_getCfgVarLevel function gets the level at which the passed in configuration variable is defined. More...

int	mdlSystem_defineCfgVar (WCharCP cfgVar, WCharCP value, DgnPlatform::ConfigurationVariableLevel level)
	Description Define a configuration variable. More...

int	mdlSystem_deleteCfgVar (WCharCP cfgVar)
	Remove the variable cfgVar from the configuration variable table. More...

int	mdlSystem_deleteCfgVarAtLevel (WCharCP cfgVar, DgnPlatform::ConfigurationVariableLevel level)
	Remove the variable cfgVar from the configuration variable table at the specified level. More...

int	mdlSystem_lockCfgVar (WCharCP cfgVar)
	Lock the variable cfgVar in the configuration variable table. More...

bool	mdlSystem_isCfgVarLocked (WCharCP cfgVar)
	Query the state of the lock for a given configuration variable. More...

int	mdlSystem_processCfgVarFile (WCharCP fileName, DgnPlatform::ConfigurationVariableLevel startingProcessLevel)
	Normally, configuration variable files are only processed during MicroStation's startup procedure. More...

int	mdlSystem_rewriteCfgVarFile (WCharCP cfgVarFileNameP, WCharCP cfgVarNameP, WCharCP cfgVarValueP)
	Rewrite the cfgVarFileNameP file so that cfgVarNameP will get defined to cfgVarValueP. More...

int	mdlSystem_createListFromCfgVarValue (StringListP *valueStrListPP, WCharCP cfgVarValueP)
	Parse a configuration variable's value into a StringList. More...

Detailed Description

Function Documentation

int mdlSystem_createListFromCfgVarValue	(	StringListP *	valueStrListPP,
		WCharCP	cfgVarValueP
	)

Parse a configuration variable's value into a StringList.

For example, the value of MS_DEF, which is a list of directories to search for design files, would have individual directories separated by the PATH_SEPARATOR_CHAR so it can be stored as a single buffer. mdlSystem_createListFromCfgVarValue breaks up the value at the PATH_SEPARATOR_CHAR and makes each item an entry in the StringList. This function would be called after mdlSystem_getCfgVar or mdlSystem_getExpandedCfgVar.

Parameters

[out]	valueStrListPP	is the address of a StringList pointer. A StringList will be created to hold the individual entries of a configuration variable's value. The calling application must free this StringList by calling mdlStringList_destroy. valueStrListPP can be NULL if the number of entries is the only item of interest.
[in]	cfgVarValueP	points to a buffer containing a configuration variable's value.

Returns: mdlSystem_createListFromCfgVarValue returns the number of entries in the created StringList or -1 if there is an error.

See also: mdlSystem_getCfgVar mdlSystem_getExpandedCfgVar mdlStringList_destroy

Remarks: Required Library: mdlbltin.lib

int mdlSystem_defineCfgVar	(	WCharCP	cfgVar,
		WCharCP	value,
		DgnPlatform::ConfigurationVariableLevel	level
	)

Description Define a configuration variable.

If the variable already exists, its value is redefined.

Parameters

[in]	cfgVar	The name of the configuration variable. Configuration variable names are not case sensitive.
[in]	value	The new value. There is no limit on the length of a variable value. mdlSystem_defineCfgVar makes a copy of this value.
[in]	level	The definition level of configuration variable.

Returns: SUCCESS if the variable is successfully defined. Otherwise it returns ERROR.

See also: mdlSystem_getCfgVar mdlSystem_deleteCfgVar

Remarks: Required Library: mdlbltin.lib

int mdlSystem_deleteCfgVar ( WCharCP cfgVar )

Remove the variable cfgVar from the configuration variable table.

Parameters

[in] cfgVar The name of the variable to delete

Remarks: The mdlSystem_deleteCfgVarAtLevel differs from the mdlSystem_deleteCfgVar function in that it only removes the a definition at a single level. For example, if MS_DEF had a value at the system level and had been overridden at the user level MicroStation would use the value defined at the user level. The mdlSystem_deleteCfgVarAtLevel function could be used to delete the value at the user level. After successful completion of this function MicroStation would then use the value of MS_DEF that was defined at the system level. If the mdlSystem_deleteCfgVarAtLevel function is used to remove the level that contains the only definition of a configuration variable then it functions exactly as mdlSystem_deleteCfgVar.; mdlSystem_deleteCfgVar and mdlSystem_deleteCfgVarAtLevel cannot be used to remove values for instances of operating system environment variables.

Returns: mdlSystem_defineCfgVar returns SUCCESS if the variable is successfully deleted. If it cannot find cfgVarP in the variable table, it returns ERROR.

See also: mdlSystem_getCfgVar mdlSystem_defineCfgVar

Remarks: Required Library: mdlbltin.lib

int mdlSystem_deleteCfgVarAtLevel	(	WCharCP	cfgVar,
		DgnPlatform::ConfigurationVariableLevel	level
	)

Remove the variable cfgVar from the configuration variable table at the specified level.

Parameters

[in]	cfgVar	The name of the variable to delete
[in]	level	level to remove

Remarks: The mdlSystem_deleteCfgVarAtLevel differs from the mdlSystem_deleteCfgVar function in that it only removes the a definition at a single level. For example, if MS_DEF had a value at the system level and had been overridden at the user level MicroStation would use the value defined at the user level. The mdlSystem_deleteCfgVarAtLevel function could be used to delete the value at the user level. After successful completion of this function MicroStation would then use the value of MS_DEF that was defined at the system level. If the mdlSystem_deleteCfgVarAtLevel function is used to remove the level that contains the only definition of a configuration variable then it functions exactly as mdlSystem_deleteCfgVar.; mdlSystem_deleteCfgVar and mdlSystem_deleteCfgVarAtLevel cannot be used to remove values for instances of operating system environment variables.

Returns: mdlSystem_defineCfgVar returns SUCCESS if the variable is successfully deleted. If it cannot find cfgVarP in the variable table, it returns ERROR.

See also: mdlSystem_getCfgVar mdlSystem_defineCfgVar

Remarks: Required Library: mdlbltin.lib

int mdlSystem_getCfgVar	(	WStringP	value,
		WCharCP	cfgVar
	)

The mdlSystem_getCfgVar function retrieves the expanded value of the configuration variable cfgVar.

If the configuration variable does not exists, MicroStation attempts to find a system level environment variable with that name.

Remarks: If the definition of cfgVar contains references to other configuration variables, the string resultinf from expansion of those nested configuration variables is returned.

Parameters

[out]	value	Points to a WString that receives the value of the configuration variable. valuep can be NULL if mdlSystem_getCfgVar is used to check for the existence of the configuration variable.
[in]	cfgVar	The name of the configuration variable.

Returns: SUCCESS if the configuration variable is defined. Otherwise, it returns a non-zero value.

See also: mdlSystem_getenv mdlSystem_getCfgVarLevel

Remarks: Required Library: mdlbltin.lib

int mdlSystem_getCfgVarAtLevel	(	WStringP	value,
		WCharCP	cfgVar,
		DgnPlatform::ConfigurationVariableLevel	level
	)

The mdlSystem_getCfgVarAtLevel function retrieves the expanded value of the configuration variable cfgVarNameP at a particular level.

This is different from mdlSystem_getCfgVar which checks all levels.

Parameters

[out]	value	Points to a WString that receives the value of the configuration variable. valuep can be NULL if mdlSystem_getCfgVarAtLevel is used to check for the existence of the configuration variable at a particular level.
[in]	cfgVar	The name of the configuration variable.
[in]	level	Specifies the level to look for a value for cfgVarNameP.

Returns: SUCCESS if the configuration variable is defined at the specifed level. Otherwise, it returns a non-zero value.

See also: mdlSystem_getCfgVar

Remarks: Required Library: mdlbltin.lib

int mdlSystem_getCfgVarLevel	(	DgnPlatform::ConfigurationVariableLevel &	level,
		WCharCP	cfgVar
	)

The mdlSystem_getCfgVarLevel function gets the level at which the passed in configuration variable is defined.

Parameters

[out]	level	The definition level.
[in]	cfgVar	The name of the configuration variable.

Returns: SUCCESS if the configuration variable is defined and ERROR if the configuration variable is not defined. If ERROR is returned, the value in level is not valid.

See also: mdlSystem_getCfgVar

Remarks: Required Library: mdlbltin.lib

bool mdlSystem_isCfgVarLocked ( WCharCP cfgVar )

Query the state of the lock for a given configuration variable.

If it is of concern to the application, a call to mdlSystem_getCfgVar can be used to determine the configuration variable's existence.

Parameters

[in] cfgVar The name of the variable to check.

Returns: mdlSystem_isCfgVarLocked returns true if the variable is locked and false if it is not locked. If it cannot find cfgVarP in the variable table or in the system environment, it also returns false.

See also: mdlSystem_getCfgVar mdlSystem_defineCfgVar

Remarks: Required Library: mdlbltin.lib

int mdlSystem_lockCfgVar ( WCharCP cfgVar )

Lock the variable cfgVar in the configuration variable table.

Once a configuration variable is locked the configuration variable cannot be deleted and its value cannot be changed.

Parameters

[in] cfgVar The name of variable to lock

Returns: mdlSystem_lockCfgVar returns SUCCESS if the variable is successfully locked. If it cannot find cfgVarP in the variable table or in the system environment, it returns ERROR.

See also: mdlSystem_getCfgVar mdlSystem_defineCfgVar

Remarks: Required Library: mdlbltin.lib

int mdlSystem_processCfgVarFile	(	WCharCP	fileName,
		DgnPlatform::ConfigurationVariableLevel	startingProcessLevel
	)

Normally, configuration variable files are only processed during MicroStation's

startup procedure.

The mdlSystem_processCfgVarFile function can be used to initialize additional configuration variables inside of MicroStation.

Parameters

[in]	fileName	is the name of the configuration variable file to process.
[in]	startingProcessLevel	is the level at which to start processing the file. Valid values are the CFGVAR_LEVEL_xxx constants defined in msdefs.h and correspond to the configuration file processing levels. Most applications will want to use ConfigurationVariableLevel::User.

Remarks: mdlSystem_processCfgVarFile should only be used to set directory search paths or application specific configuration variables that require no additional initialization. Certain MicroStation configuration variables, (MS_SYMBRSRC and MS_USERPREF for example) require additional initialization upon MicroStation startup. It would therefore be invalid to set these variables through the mdlSystem_processCfgVarFile call.

Returns: mdlSystem_processCfgVarFile returns ERROR if any errors occur during the processing of the configuration variable file. Otherwise it returns SUCCESS.

See also: mdlSystem_getCfgVar mdlSystem_deleteCfgVar

Remarks: Required Library: mdlbltin.lib

int mdlSystem_rewriteCfgVarFile	(	WCharCP	cfgVarFileNameP,
		WCharCP	cfgVarNameP,
		WCharCP	cfgVarValueP
	)

Rewrite the cfgVarFileNameP file so that cfgVarNameP will get defined to cfgVarValueP.

It does so without disturbing comments, etc. elsewhere in the file. mdlSystem_rewriteCfgVarFile does not affect the current session's environment. Use mdlSystem_defineCfgVar to change the current session.

Parameters

[in]	cfgVarFileNameP	is the name of the configuration variable file to rewrite. If NULL is passed, the current user configuration file is assumed.
[in]	cfgVarNameP	is the name of the configuration variable.
[in]	cfgVarValueP	is the value of cfgVarNameP that should be written to cfgVarFileNameP.

Returns: mdlSystem_rewriteCfgVarFile returns SUCCESS if cfgVarFileNameP was updated successfully. Otherwise, a non-zero value is returned.

See also: mdlSystem_processCfgVarFile mdlSystem_defineCfgVar mdlSystem_getCfgVar

Remarks: Required Library: mdlbltin.lib

Functions

Detailed Description

Function Documentation