Dissemino Executive Commands
Dissemino application specific functionality has two possible origins; Direct C++ programing and the configs. Dissemino Executive Commands are the means by which such functionality is specified in the latter. There are also two distinct operational areanas for application specific functionality; Periodic tasks controlled by a background thread which draw from the application data as a whole, and the processing of form submissions by individual visitors or logged in users. Of interest here, is the latter.
Dissemino executive commands are manifest as instances of the hdsExec classs. Originally hdsExec was a base class with the various commands being derivatives of it, but this led to unweildy code so the class was condensed. hdsExec is now the sole class for executive commands and has a wider set of methods to cover the full set of operations. The command type is indicated by the Exectype enum as follows:-
| EXEC_SESS_COOKIE | Set a session cookie. Will do nothing if either a session or permanent cookie is in already in use. |
| EXEC_PERM_COOKIE | Set a permanant cookie. Will do nothing if a permanent cookie is in already in use but will upgrade a session cookie. |
| EXEC_SENDEMAIL | Send an email |
| EXEC_SETVAR | Explicity set a user session standalone variable |
| EXEC_ADDUSER | Create a user |
| EXEC_LOGON | Logon a user |
| EXEC_TEST | Test if two values are equal |
| EXEC_EXTRACT | Extract text from a submitted file |
| EXEC_OBJ_TEMP | Create a HTTP event duration object (non cookie forms only). This must specify an object reference key and a pre-defined data class. |
| EXEC_OBJ_START | Assert a session duration object. This must specify an object reference key and a pre-defined data class. |
| EXEC_OBJ_FETCH | Load the named user session object. This must supply the object reference key and name a pre-declared repository. |
| EXEC_OBJ_IMPORT | Load the named user session object from a JSON file. This command must supply the object reference key and specify the full pathname of the data file. |
| EXEC_OBJ_EXPORT | Export the named user session object to a JSON file. This command must supply the object reference key and specify the full pathname of the data file. |
| EXEC_OBJ_SETMBR | Set a member value within the named session object. This command must supply the object reference key, the applicable class (either object host class or a sub-class of it), the member name and define the source of the value. |
| EXEC_OBJ_COMMIT | Commit the named user session object to a repository |
| EXEC_OBJ_CLOSE | Closes the named user session object. This only needs to supply the object reference key. |
| EXEC_TREE_DCL | <xtreeDcl> Declares a public tree if outside an <xpage> and private if within the <procdata> block of its host page or form-handler. This has compulsory attributes of a unique tree id and host page URL. Note that a private tree is only created if it does not already exist in the user session. |
| EXEC_TREE_HEAD | <xtreeHead> Adds an blank header to a user tree. This requires attributes of tree id, parent node id, node id, refname and title. If the header exists, this command has no effect. |
| EXEC_TREE_ITEM | <xtreeItem> Adds an article to a tree. This requires the tree id, parent node id, refname and title. If the item already exists, this tag has no effect. |
| EXEC_TREE_FORM | <xtreeCtl> Adds an form as an article to a tree. This requires the tree id, parent node id, refname and title but also form name and class context. |
| EXEC_TREE_SYNC | <xtreeCtl> Syncs the tree to a standalone object. Both must be tied to a user session. This requires the tree id and the object key. |
| EXEC_TREE_DEL | <xtreeDel> Deletes an item from a user tree. This has two attributes of tree id and item id |
| EXEC_TREE_EXP | <xtreeCtl> Expands an item from a user tree. This has two attributes of tree id and item id |
| EXEC_TREE_CLR | <xtreeCtl> Un-expands an item from a user tree. This has two attributes of tree id and item id. |
| EXEC_SRCH_PAGES | A free text search on site pages |
| EXEC_SRCH_REPOS | A search on a repository |
| EXEC_FILESYS | File system commands direct the creation and deletion of directories and then save/delete files to/from those directories. |
Note in the above, that some commands form groups. The EXEC_OBJ commands are concerned with data object operations while EXEC_TREE commands operate on a hdsTree.
Executive Commands are always grouped under a <procdata> tag which is akin to a function, making the commands themselves akin to statements within a function. <procdata> blocks are invoked whole, execute their commands in the given order and produce a single outcome. In the configs, <procdata> blocks may appear only within the definitions of background tasks, form handlers and pages, with each having slightly different sets of legal commands. Task <procdata> blocks cannot include commands that assume a user session, nor may they perform state change operations on a repository. Form handler <procdata> blocks can include such commands but they cannot read or write reports. Page <procdata> blocks may only declare and initialize temporary working data objects and trees but cannot operate on these resources. However only page <procdata> blocks can call commands that export JavaScript from a tree.
Commands in form handler <procdata> blocks are executed by hdsApp::ProcForm which is called each time a form is submitted. Commands in page <procdata> blocks are run as part of the page HTML generation process. Note that the presence of commands in a page definition, marks the page as active meaning the page HTML is generated each time the page is requested. Note also that as page <procdata> blocks cannot commit data, command outcome is not tested and the HTML generation proceeds regardless. An error condition will only be apparent in the displayed page.
Form Handler Commands
By contrast, form handlers must always provide a HTML response to a form submission. If the submission was successful, the reponse would be an acknowledgement of this plus a button that will move the user on to the next stage of the proceedings. If the submission fails in some way, this should be fully reported to the user. It may be the user needs to correct the data but if not, the user will still need to know what is going on.
There is the built-in user authentication form handler and there can be search forms that only do lookups. Mostly however, forms gather and store data submitted by users. To effect this, the form handler first populates a data object (hdbObject) with the submitted values. Then the data object is commited, usually to a repository but in some cases a user file. Each step of this process involves executive commands. There is a command to create the data object, a command to set each member with values extracted using percent entities, and finally a command to INSERT or UPDATE the data object.
None of these commands will fail as a result of incorrect data class ids or wrongly named members, as such matters are resolved during the config read process. Creation of the data object can thus be assumed. Set member commands can only fail on validation, either because the extracted value is the wrong format or is out of range. If any fail, the submission cannot be submitted and the form will require correction by the user.
The commit command won't fail on format or range as it won't be invoked until all the extract and set commands have been successfully executed. However it can fail on validation if the data violated repository rules on uniqueness. If it does, then again, correction by the user is the only remedy. Other than this, if the commit is to a repository on the local machine, the only error that can occur will be a lack of disk space - a service shutdown condition. However if the commit is to a repository on another machine, a network error or other 'temporary' condition could arise. Under these circumstances, the commit will follow the applicable server arrangements for the repository as described in the ADP.
Note that forms have validation JavaScript to trap invalid formats and out of range values ahead of submission. The validation JavaScript can also, by means of AJAX, trap forbidden duplications (e.g. email address already in use). However the scripts do not eliminate the need for server side data validation. They cannot trap all errors and it must be assumed that clients of malign intent will send deliberately invalid data to break the system.