Programmer Guide/Macro Library/BDataSet: Difference between revisions
From STX Wiki
Jump to navigationJump to search
No edit summary |
No edit summary |
||
| Line 3: | Line 3: | ||
:'''See also''': [[Programmer_Guide/Macro_Library/BXMLDoc|BXMLDoc]], [[Programmer_Guide/Macro_Library/BXMLDoc|BSTXIni]], [[Programmer_Guide/Macro_Library/DataSetCmd|DataSetCmd]] | :'''See also''': [[Programmer_Guide/Macro_Library/BXMLDoc|BXMLDoc]], [[Programmer_Guide/Macro_Library/BXMLDoc|BSTXIni]], [[Programmer_Guide/Macro_Library/DataSetCmd|DataSetCmd]] | ||
This class implements the ''project document''. The project document is the global database available to all {{STx}} applications and scripts and contains all data and links of the current project. The content of the project document is stored in a [[Programmer_Guide/Shell_Items/File|XML file item]] The programmer must not create or destroy the project object because these functions are performed by the application startup and cleanup macros. | This class implements the '''project document'''. The project document is the global database available to all {{STx}} applications and scripts and contains all data and links of the current project. The content of the project document is stored in a [[Programmer_Guide/Shell_Items/File|XML file item]] The programmer must not create or destroy the project object because these functions are performed by the application startup and cleanup macros. | ||
: Never ever call the member functions <code>CONSTRUCT</code>, <code>DESTRUCT</code> or <code>CLOSE</code>! | : Never ever call the member functions <code>CONSTRUCT</code>, <code>DESTRUCT</code> or <code>CLOSE</code>! | ||
| Line 16: | Line 16: | ||
===Attach & Detach=== | ===Attach & Detach=== | ||
;<code>$bdataset attach [ <var>iref</var> ]</code> | |||
The function <code> | ;<code>$bdataset detach</code>: | ||
:;<var>iref</var>: reference or position of an element of the project document, if specified the element is selected after attaching | |||
Multiple calls of <code> | ;Result: the name of the xml-file item containing the project document data | ||
;Description: The function <code>attach</code> locks the project document and returns the internal xml-file item containing the project data. Only the calling shell can now access the project content, all other shells are blocked. The project document remains locked until the next call to <code>detach</code>. Multiple calls of <code>attach</code> (by the same shell) are possible, but for each call also the function <code>detach</code>must be called. | |||
// example for using ATTACH / DETACH | // example for using ATTACH / DETACH | ||
// first attach call - lock project document and save current xml-position (pos1) | // first attach call - lock project document and save current xml-position (pos1) | ||
$bdataset attach | |||
... | ... | ||
// second attach call - save xml-position (pos2) | // second attach call - save xml-position (pos2) | ||
$bdataset attach | |||
... | ... | ||
// first detach call - restore xml-position pos2 | // first detach call - restore xml-position pos2, project document remains locked! | ||
$bdataset detach | |||
... | ... | ||
// second detach call - restore xml-position and unlock project document, | // second detach call - restore xml-position pos1 and unlock project document, | ||
// if the project document was changed by the code between first attach and second detach, | // if the project document was changed by the code between first attach and second detach, | ||
// the message "DATASETCHANGED" is sent to all running shells | // the message "DATASETCHANGED" is sent to all running shells | ||
$bdataset detach | |||
==Project Properties== | |||
===isNewFile=== | |||
This function returns <code>1</code> if the project file is new (unnamed) and 0 if not. | |||
===GetPath=== | |||
Revision as of 10:50, 26 February 2018
- File: BDataSet.STX, linked to library STX.LIB
- See also: BXMLDoc, BSTXIni, DataSetCmd
This class implements the project document. The project document is the global database available to all STx applications and scripts and contains all data and links of the current project. The content of the project document is stored in a XML file item The programmer must not create or destroy the project object because these functions are performed by the application startup and cleanup macros.
- Never ever call the member functions
CONSTRUCT,DESTRUCTorCLOSE!
At application startup a BDataSet instance is created and linked to the global project document which is created and managed by the STx master shell. The name of this instance is stored in the shell variable BDATASET. This object must be used to access the project document.
The class BDataSet is derived from the class BXMLDoc. Beware of using the base class functions, since they do not update the BDataSet member variables! No static commands are implemented by this class; a call to the macro BDataSet (e.g. bdataset save) will do nothing, returning an empty string.
Before a shell or a script uses or changes the content of the project document, it should be attached (locked) using the function call $bdataset attach (see: Attach & Detach).
Attach & Detach
$bdataset attach [ iref ]$bdataset detach-
- iref
- reference or position of an element of the project document, if specified the element is selected after attaching
- Result
- the name of the xml-file item containing the project document data
- Description
- The function
attachlocks the project document and returns the internal xml-file item containing the project data. Only the calling shell can now access the project content, all other shells are blocked. The project document remains locked until the next call todetach. Multiple calls ofattach(by the same shell) are possible, but for each call also the functiondetachmust be called.
// example for using ATTACH / DETACH // first attach call - lock project document and save current xml-position (pos1) $bdataset attach ... // second attach call - save xml-position (pos2) $bdataset attach ... // first detach call - restore xml-position pos2, project document remains locked! $bdataset detach ... // second detach call - restore xml-position pos1 and unlock project document, // if the project document was changed by the code between first attach and second detach, // the message "DATASETCHANGED" is sent to all running shells $bdataset detach
Project Properties
isNewFile
This function returns 1 if the project file is new (unnamed) and 0 if not.
