BSTXIni - Workspace Document
This class implements the workspace document. The workspace document contains the STx configuration and the settings and is implemented as a global object which can be accessed from all STx applications and scripts. The user must not create or destroy the workspace object because these functions are performed by the application startup and cleanup macros. At application startup, a BSTXINI instance is created and linked to the global workspace document. The name of is instance is stored in the shell variable BSTXINI. This instance must (!) be used to access the workspace document.
!! Never call the member functions CONSTRUCT, DESTRUCT, CLOSE or LOAD !!
This class also implements a set of static functions which are used by the master application and the application DataSet to manage to file STX.INI which contains the name of the last used workspace file (for program startup) and the project file history. The automatic workspace version update and some installation and licence checks are also implemented by this class, but not described in this documentation.
Important note: A shell or a script should only access or change the content of the workspace document, while it is attached (locked). This is very important, because this document can be (and is often) accessed by all running shells (e.g. STx applications or scripts). A code section accessing the workspace content should start with $bstxini attach and end with $bstxini detach. See BXMLDoc access control for details.
Contents
Static Functions
The following functions can be called without a BSTXINI instance.
Get last workspace file
- Usage
bstxini ?- Result
- the full path of the last used workspace file
Set last workspace file
- Usage
bstxini ? file- file
- the full path of the workspace file to be set
Get the project history
- Usage
bstxini *- Result
- a simple table containing the full path of recently used project files (one per entry)
Add project file to the history
- Usage
bstxini + file- file
- the full path of the project file to be added; if the file is already in the history, it is moved to the top
Remove project file from the history
- Usage
bstxini - file- file
- the full path of the project file to be removed
Select a project file via a dialog
- Usage
bstxini selectdataset- Result
- the selected or created project file or an empty string if the cancel button was pressed
- Note
- This function displays the standard startup dialog of STx.
Get recently used scripts
- Usage
bstxini scripts- Result
- a simple table containing the full path of recently used script files (one per entry)
Add script file to the history
- Usage
bstxini scripts add file- file
- the full path of the script file to be added; if the file is already in the history, it is moved to the top
Misc. Member Functions
Get STx Version
- Usage
$bstxini getversion- Result
- the full version information string 'version ; revision ; freeflag'
- version: the version number in the format major.minor.bugfixrelease
- revision: the source code revision number
- freeflag: 1 for the freeware version and 0 for the commercial version
Get Workspace File Path
- Usage
$bstxini getpath- Result
- the full path of the loaded workspace file
Get Application Shell or Name
- Usage
$bstxini getapp appname shellid=*- Result
-
- if shellid equals *: return the shell-id of the application named appname or an empty string if not running; if multiple instances of this application are running, a blank separated list of shell-ids is returned
- otherwise: return the name the application executed by the shell with the specified shellid
Member Functions for Setup Element (Profile) Handling
Setup elements (profiles) are xml elements containing settings of STx. All profiles are stored inside the element /CurrentSetup (iref). The argument subsets of the profile functions is appended to the iref (/CurrentSetup/subsets).
Get a List of Profiles
- Usage
$bstxini listprofiles table ; tag ; id ; subset- table
- a simple table to store results; if no table is passed, it is created
- tag
- the xml tag of the profiles
- id
- the id of the current/selected profile of *
- subsets
- the xml path (partial iref) of the element containing the profiles
- Result
- 'table index'
- table: the passed or created table containing the profile names (one per entry)
- index: the index of the profile named id (set to 0 if not found)
Load a Profile
- Usage
$bstxini loadsetupelement tag ; id ; tid ; subset- tag
- the xml tag of the profile
- id
- the id of the profile
- tid
- the id of the profile template
- subsets
- the xml path (partial iref) of the element containing the profile
- Result
- Returns a simple or extended table (depends on the profile) containing the profile settings. If the profile id do not exist, it is created from the template tid and then loaded.
Save a Profile
- Usage
$bstxini savesetupelement table ; del ; tag ; id ; subset- table
- a table (simple or extended, deponds on profile) containing the profile data to be saved
- del
- if set to 1 the passed table is deleted after saving
- tag
- the xml tag of the profile
- id
- the id of the profile
- subsets
- the xml path (partial iref) of the element containing the profile
- Result
- 0 for success or a non-zero error code
- Description
- Saves the table in the profile element. If the profile named id exists already, it is replaced, otherwise it is created. If the option del is set to 1 the data table is deleted after saving.
Delete a profile
- Usage
$bstxini deletesetupelement tag ; id ; subsets- tag
- the xml tag of the profile
- id
- the id of the profile
- subsets
- the xml path (partial iref) of the element containing the profile
- Result
- 0 if profile was deleted for successfully or a non-zero error code
Uncommon Functions and Functions for internal use only
The following functions are not often used and not so important for user script programming. If you want to know more about these functions look at the comments in the source file BSTXIni.stx
LoadAppSetup: load settings of STx standard applicationsSaveAppSetup: save settings of STx standard applications
LoadDefinition: load a xml-doctype definition or the entry defintion of an extended table from the STx configuration
CheckVersion: check STx and workspace version and update/upgrade workspace file if necessary
Save: save workspace documentSave: close workspace document - only used by application manager!
DialogNewSetupElement: a dialog to create a settings profile
