envStoreEnv

envStoreEnv(
[ ?envFile t_fileName ] 
[ ?tool t_tool[.partition] ] 
[ ?toolStatus t_toolStatus ]
[ ?varStatus s_varStatus ]
[ ?fileStatus t_fileStatus ]
)
=> t / nil

Description

Stores environment variables associated with tools to a specific file. You can choose to save variables for a specific tool, all loaded tools, or all possible tools. You can also specify whether you want to save all the variables for a tool, the variables that have been modified, or only the variables that have been modified and that are different from the default value.

This function is the programmatic equivalent of saving variables with the Save Defaults form.

Arguments

t_fileName	Specifies the name of the file in which you want to store the environment variables. If not specified, the variables gets saved in ~/.cdsenv.
t_tool[.partition]
	The name of the tool and the partition, if any. Use this argument only if you have set t_toolStatus to "Loaded tools by name". A partition is a way of grouping related sets of variables associated with a tool. You can specify the value of this argument in the following ways: tool: Saves all the variables at the top level of the tool and in all the partitions tool.: Saves only the variables at the top level of the tool; does not save the variables in the partitions tool.partition: Saves only the variables in the specified partition If you specify more than one tool, separate the names with a space. The default value of this argument is "ALL".
t_toolStatus	The tools you want to save. Specify one of the following strings: "All possible tools" "All loaded tools" "Loaded tools by name" If you specify "Loaded tools by name," specify the names of the tools in the t_tool[.partition] argument. If you specify "All possible tools," the value of the s_varStatus argument is ignored. All the variables are saved. The default value is "All loaded tools".
s_varStatus	The variables you want to save. Specify one of the following symbols: ’modified: Saves only those variables that have been modified; a variable is considered to be modified if it is changed in any way, even if its value is reset to the original value. ’modifiedFromDefault: Saves only those variables that have been modified and that are different from the default; float variables gets saved if the difference between the current value of the variable and the default value is greater than the tolerance specified in the .cdsenv file. ’all: Saves all the variables. If you specified "All possible tools" as the value of the t_toolStatus argument, the s_varStatus argument is ignored. s_varStatus is assumed to be ’all, regardless of the value you specify.
t_fileStatus	The file status. Specify one of the following strings: Overwrite: Overwrites the original file. Merge values: Merges values that have been modified in the current session with the original file. Retain values: Retains values from the original file. The default is "Merge values". The following table shows the values that are saved to an existing file based on the values of s_varStatus and t_fileStatus:

	Merge Values	Overwrite	Retain values
Modified	All values in the existing default settings file is retained unless the variable has been modified in the current session. If the variable has been modified, its modified value is saved. In addition, non-private values that are not included in the original file but that have been modified is added to the file.	Only non-private values that have been modified in the current session are saved. Any pre-existing contents of the file is removed.	All values in the existing default settings file are retained. Any additional values that are not included in the original file but that have been modified in the current session is added to the file.
ModifiedFrom Default	All values in the existing default settings file are retained unless the variable has been modified in the current session and is different from the default value. If the variable has been modified and its value is different from the default value, its new value gets saved. In addition, non-private values that are not included in the original file is added to the file if they have been modified and are different from the defaults.	Only non-private values that have been modified in the current session and that are different from the default values gets saved. Any pre-existing contents of the file are removed.	All values in the existing default settings file are retained. In addition, any non-private values that are not included in the original file is added to the file if they have been modified and are different from the defaults.
All	All values in the existing default settings file are retained unless the variable has been modified in the current session. If the variable has been modified, its modified value is saved. In addition, all non-private values for the tool are written to the file, whether or not they have been used in the current session.	All non-private values for the tool are saved whether or not they are used in the current session. Any pre-existing contents of the file are removed.	All values in the existing default settings file are retained. In addition, all non-private values for the tool gets written to the file, whether or not they have been used in the current session.

Examples

The following example shows different environment variables that need to be saved to the existing file (myDefs) based on the values of t_toolStatus, t_tool[.partition], s_varStatus, and t_fileStatus. Assume that the list of all possible tools includes testTool, anotherTool and tool3.

Master variable registration file located in etc/tools/testTool/.cdsenv:

testTool      nestLimit           int      5        nil
testTool      showScrollBars      boolean  nil      nil
testTool      setWinTraversal     boolean  nil      nil
testTool       undoLevel           int      1         nil

Master variable registration file located in etc/tools/anotherTool/.cdsenv:

anotherTool   var1    string  "hi"  nil
anotherTool   var2    int     50    nil
anotherTool   var3    cyclic  "v2"  nil ("v1" "v2" "v3")

Master variable registration file located in etc/tools/tool3/.cdsenv:

tool3.part1   check  boolean nil  nil
tool3.partb   level  int     20   nil
tool3          auto   boolean t    nil

Existing file myDefs:

testTool       nestLimit         int 3       
testTool       undoLevel         int 5
tool3          auto              boolean nil
tool3.partb    level             int 9
anotherTool     var3              cyclic  "v3"

Environment variable settings in the current session:

testTool   nestLimit        int 2          (modified and different from default)
testTool   showScrollBars  boolean nil
testTool   setWinTraversal  boolean t      (modified and different from default)
testTool   undoLevel       int 1
tool3      auto             boolean t     (modified and same as default)

The following is a list of environment variables that need to be saved to file myDefs depending on the settings for t_fileStatus, t_tool[.partition], s_varStatus and t_toolStatus.

For ?fileStatus Overwrite, ?toolStatus Loaded tools by name, ?tool testTool tool3, and ?varStatus ’modified:

testTool  nestLimit        int          2
testTool  setWinTraversal  boolean      t
tool3     auto             boolean      t

For ?fileStatus Merge  values, ?toolStatus Loaded tools by name, ?tool testTool tool3, and ?varStatus ’modified:

testTool      nestLimit         int         2
testTool      setWinTraversal   boolean     t
testTool      undoLevel         int         5
tool3         auto              boolean     t
tool3.partb   level             int         9
anotherTool   var3               cyclic      "v3"

For ?fileStatus Retain values, ?toolStatus Loaded tools by name, ?tool testTool tool3, and ?varStatus ’modified:

testTool      nestLimit         int         3
testTool      setWinTraversal   boolean     t
testTool      undoLevel         int         5
tool3         auto              boolean     nil
tool3.partb   level             int         9
anotherTool   var3              cyclic      "v3"

For ?fileStatus Merge  values, ?toolStatus Loaded tools by name, ?tool testTool tool3, and ?varStatus ’modifiedFromDefault:

testTool  nestLimit        int          2
testTool  setWinTraversal  boolean       t

For ?fileStatus Overwrite and ?toolStatus All possible tools:

testTool      nestLimit          int        2
testTool      showScrollBars     boolean    nil
testTool      setWinTraversal    boolean    t
testTool      undoLevel          int        1
anotherTool   var1               string     "hi"
anotherTool   var2               int        50
anotherTool   var3               cyclic     "v2"
tool3.part1   check              boolean    nil
tool3.partb   level              int        20
tool3         auto               boolean    t

For ?fileStatus Merge values and ?toolStatus All possible tools:

testTool      nestLimit          int        2
testTool      showScrollBars     boolean    nil
testTool      setWinTraversal    boolean    t
testTool      undoLevel          int        5
anotherTool   var1               string     "hi"
anotherTool   var2               int        50
anotherTool   var3               cyclic     "v2"
tool3.part1   check              boolean    nil
tool3.partb   level              int        9
tool3         auto               boolean    t

For ?fileStatus Retain values and ?toolStatus All possible tools:

testTool      nestLimit         int         3
testTool      showScrollBars    boolean     nil
testTool      setWinTraversal   boolean     t
testTool      undoLevel         int         5
anotherTool   var1              string      "hi"
anotherTool   var2              int         50
anotherTool   var3              cyclic      "v3"
tool3.part1   check             boolean     nil
tool3.partb   level             int         9
tool3          auto              boolean     nil

For ?fileStatus Overwrite, ?toolStatus Loaded tools by name, ?tool tool3, and ?varStatus ’all:

tool3         auto               boolean     t
tool3.part1   check              boolean     nil
tool3.partb   level               int         20

For ?fileStatus Overwrite, ?toolStatus Loaded tools by name, ?tool tool3., and ?varStatus ’all:

tool3         auto               boolean     t

For ?fileStatus Overwrite, ?toolStatus Loaded tools by name, ?tool tool3.part1, and ?varStatus ’all:

tool3.part1   check              boolean     nil

Related Topics

Cdsenv Editor Functions

Return to top