Documentation Comments
Use this form to comment on this topic. You can also provide any general observations about the Online Documentation, or request that additional information be added in a future release.
Reality V15.2 Online Documentation (MoTW) Revision 3
New Features (Release Information) (M6862RN+NewFeatures.htm)
Reality V15.2 contains a number of new features since the release of V15.1, including the introduction of hyper files and significant DataBasic enhancements.
Some of the new features have come from the user feedback that we receive during the life of a release, so please continue to use the 'Comment on this topic' links at the top and bottom of each topic in the Online Documentation, or visit the NPS Reality website, in order to help us to improve your Reality.
A hyper file is a logical view on to a number of discrete data sections in multiple physical files, including remote files. Accessing a hyper file accesses these data sections —referred to as hyper sections— as if they constituted one file.
Hyper files are primarily intended as a way to split a very large file into more manageable units. Significantly, item IDs must be unique across all hyper sections and include information —known as the hyper key— that is used to determine in which underlying physical data file each item belongs.
Applications can choose to access and update all of the hyper sections that comprise the hyper file as one logical view, or as each separate underlying physical data section file. Each data section can use dictionary definitions and indexes as normal, with the hyper file able to use all of these for its view across all data sections, provided that they are logically consistent.
For example, sales figures could be updated, processed and analysed as one hyper file opened as SALES, which is actually a view of the separate data section files called SALES_CURRENT, SALES_2014, SALES_2013, and so on. Existing applications could see all these separate data sections as one logical file called SALES.
The SALES hyper file can use English, DataBasic and the rest of the Reality features just like any standard file, including updates using dictionaries and indexes. The same file access is also available to the constituent hyper sections.
The history years of hyper sections could be fully accessible to updates, or restricted within the application to controlled maintenance so that sizing is stable. Hyper sections can be stored locally in the same or different databases, including remotely. They can be updated under application control or reside in non-updating databases. In our example, the SALES_CURRENT hyper section could be the only part of the hyper file within the main live database, growing throughout the year, and optimising performance because all previous years' hyper sections are within another database. When needed, however, all sales figures would be accessible through the SALES hyper file.
This release provides new commands that operate exclusively on hyper files, and updates some existing commands so that they can work with hyper files.
The following commands apply exclusively to hyper files:
Creates a hyper file by creating a hyper file definition item (H-pointer) and optionally the hyper sections.
Edits a hyper file by updating the hyper file definition item (H-pointer).
Adds a new section to an existing hyper file by updating the lookup table in the hyper file definition item (H-pointer).
Creates an index on all hyper sections and then adds it to an existing hyper file.
Adds a specified index to an existing hyper file.
Displays the contents of a hyper file definition item (H-pointer) in a formatted manner.
Reconciles a specific section, or all sections, of a hyper file by moving items to their correct sections.
Removes a specific section, or all sections, from a hyper file by updating the lookup table in the hyper file definition item (H-pointer) and removing any applicable update locks from the sections; optionally, it deletes the data sections themselves.
Removes a specific index from a hyper file definition item (H-pointer).
Validates a hyper file by ensuring that all its constituent hyper sections:
Have the same transaction logging status.
Have the same save/restore status.
Have index definitions that match those in the hyper file definition item (H-pointer).
Can be opened.
Verifies a specified index on all hyper sections in a hyper file.
This release includes enhancements to the DataBasic debugger, including the following new and modified debugger commands:
?Displays help pages.
?MDisplays the name of the program module currently running.
ATEnables or disables Tandem operation.
BAdds an entry to the break point table.
CPToggles switch to enable or disable cursor positioning.
CSDisplays the return stack and its depth at each internal and external subroutine, and external function.
DDisplays the current state of DataBasic debugger controls and options, as set by various debugger commands.
DCCToggles the option that causes a forced break whenever descending to a child context.
DPCToggles the option that causes a forced break whenever ascending to a parent context.
MACauses the debugger to be entered on all active statement lines in a named code module, by adding the module to the list of monitored modules.
MDRemoves monitoring for a named code module, or all code modules, by deleting them from the list of monitored modules.
MECauses the debugger to be entered on entry to the start of a named code module, by adding the module to the list of monitored modules.
MOCauses the debugger to be entered on reaching the line that immediately follows the current call to another module; in other words, it steps over the call.
MOO turns off MO stepping over (and MX stepping out) operations.
MRCauses the debugger to be entered on (re-)entry to a named code module from any other module (that is, after a CALL or RETURN command) by adding the module to the list of monitored modules.
MXCauses the debugger to be entered immediately on returning from the current module to the calling module; in other words, it steps out of the current module.
MXO turns off MX stepping out (and MO stepping over) operations.
SLDisplays the return stack and its depth at each internal and external subroutine, and external function.
A code module can be any single DataBasic code item; that is, a program, an external subroutine or an external function.
The monitored list can contain any number of modules, but the longer the list the greater the potential performance impact.
The monitored list is unique to a single context and is reset on return to TCL.
NoteSome of these enhancements were first announced in the Reality 15.1 Online Documentation (Revision 7) Documentation Note. However, in this current release the MA, ME, MR and MD commands are no longer a separately licensed feature of NPS Reality.
A new DataBasic Email application programming interface (API) provides a mechanism that allows emails with attachments to be sent from within DataBasic.
Optionally specifies an email configuration file that contains any predefined configuration items. This can be unique to the current account, or a Q-pointer to allow for a global configuration.
The default email configuration file (which is assumed if no alternative file is specified by this function) is EM_CONFIG in the account from which the DataBasic Email API is being called.
Defines the start of an email by defining the connection information for the mail server to be used. If a predefined host configuration item is specified the details are loaded from that item; these details can be overridden by providing additional configuration parameters.
Adds authentication details to an existing connection.
Adds the delivery details to the started email, including the email addresses of the sender and at least one recipient. If a predefined delivery configuration item is specified the details are loaded from that item; these details can be overridden by providing additional configuration parameters.
Adds an attachment to the email from the supplied content. The size of the attachment is limited by the size of the memory available to the user.
Adds an attachment to the email from the supplied file and item. The size of the attachment is limited by the size of the memory available to the user.
Adds authentication details to an existing connection.
Adds an HTML-formatted fragment to appear in the body of the email. This is displayed only if the client receiving the email can display HTML.
Adds a plain text version of the email to the body of the email. This is displayed if the client receiving the email cannot display HTML or if an HTML version is not supplied by EM_ADD_HTML_TEXT.
Sends the email that has been constructed using the defined connection information.
Enables the printing of debugging information including the encoded content when the email is sent.
This new feature allows a DataBasic application to dump (save) some information about its state, either automatically or on request.
There are three main situations when a DataBasic application dump may be required:
On generation of a DataBasic run-time warning or fatal error message (WARN or ABORT dump items).
On detection of a DataBasic application internal programming logic error (SOFT dump items).
When requested by the user in the DataBasic debugger (DEBUG dump items).
A default global BASIC-DUMPS file is supplied, in the SYSFILES account, in which to store DataBasic application dump items.
Whenever DataBasic generates a warning or fatal message, even if these messages are suppressed, the system creates a respective WARN or ABORT dump item and saves it to the BASIC-DUMPS file.
However, multiple WARN and ABORT dump items caused by identical errors occurring on the same port, account, user, program and line number are typically suppressed. Instead, a single WARN or ABORT dump item is created at the first occurrence and thereafter a count on the item is incremented each time the error recurs. These duplicate item counts can effectively be reset by using a new RELOG.DB.DUMPS program. The previous functionality, in which all errors are reported regardless, can be restored by setting the DB.DUMP.MULTIPLE custom environment option as described below (it is unset/clear by default).
A BASIC.DUMP DataBasic statement allows the programmer to write a SOFT dump item to the BASIC-DUMPS file whenever required.
A DUMP.BASIC.VARS custom option is provided which, if set in an environment definition, causes the WARN, ABORT and SOFT dump items to include the program variables and their contents. If the option is clear (unset) these items do not include the program variables. DUMP.BASIC.VARS is clear by default.
A DB.DUMP.MULTIPLE custom option is provided which, if set in an environment definition, causes the system to create multiple WARN or ABORT dump items even when reporting identical warning or fatal run-time error occurring on the same port, account, user, program and line number. DB.DUMP.MULTIPLE is clear by default.
A DUMP DataBasic debugger command generates a DEBUG dump item that contains all of the program's variables (regardless of the setting of the DUMP.BASIC.VARS option) plus an optional user-specified message.
A DISP.DB.DUMPS cataloged DataBasic program is provided to display DataBasic application dump items from either the default BASIC-DUMPS file or a user-specified alternative.
The RELOG.DB.DUMPS cataloged DataBasic program clears the dump item cache. This effectively resets the duplicate counts that are maintained while the DB.DUMP.MULTIPLE custom environment option is unset (as it is by default).
The SSM (Security System Maintenance) command has an improved SSM Option 4 - Define Environment Settings option, which is shared by the DEFINE-ENVIRONMENT TCL command. In addition to being significantly easier to use, it now includes the ability to define the default DataBasic compiler for an operating environment.
An environment-specific compiler is also useful to maintain live "current code" that is running on end-user systems while any testing is performed to make sure that any MultiValue compatibility changes, or new or updated features, are fully understood.
If an environment setting is not specified, the BASIC*DEFAULT synonym entry in the BASIC-COMPILERS system file in the SYSFILES account is used instead.
The DataBasic SYSTEM(120) function returns the name of the current environment and SYSTEM(121) returns the name of the current default compiler.
The SSM (Security System Maintenance) command has a new SSM Option 6 - Define Password Definitions option to create and update password definitions for users and accounts.
Password definitions allow you to define the valid composition of passwords including minimum and maximum length; allowed patterns of alphabetic, numeric and special characters; sequences of ascending or descending characters; and so on.
Password definitions are stored as items in a new PW.DEFINITIONS system file in the SYSMAN account. User and account password definitions are distinguished in the file, so that it is possible to have user and account password definitions with the same name (for example, the DEFAULT password definitions).
Each user profile either explicitly references a user password definition or implicitly references the DEFAULT user password definition. Multiple users can share the same password definition.
User password definitions complement existing features of user profiles that control, for example, how long a password remains valid, how many retries are permitted, and so on. In addition there are two new features to force the user to change their password when they next logon, and to specify what happens when the password expires.
User passwords specified by using either the PASSWORD command or SSM Option 2 - Define User Profiles must meet the rules of the relevant user password definition, although these can be overridden from the SYSMAN account.
The DataBasic SYSTEM(119) function returns the name of the current user password definition item.
Each account either uses the account password definition with the same name or, if none exists, the DEFAULT account password definition. However, an account password definition item can be a synonym to an actual account password definition, so multiple accounts can effectively share the same password definition.
Account passwords specified by using either the PASSWORD (A or CREATE-ACCOUNT command should meet the rules of the relevant account password definition, although these can be overridden from the SYSMAN account.
Note:These changes mean that the PasswordLength database configuration parameter is now redundant. On upgrading to this release the current value of PasswordLength (if any) is used to set the Min password length attribute of the DEFAULT user password definition. Similarly, the DEFAULT account password definition is also configured for backwards compatibility.
The User Interface Framework (UIF) is an extensible feature eventually intended to provide a mechanism to separate the business logic of an application from its presentation or display logic.
For example, it is used internally by the MOUNT-IMAGE command.
Depending on user feedback, this feature will be further enhanced in future releases.
Multiple clean log deletions are now possible from tlmenu, allowing simplified maintenance of the data-resilient features Transaction Logging, Shadow, FailSafe and Disaster Recovery.
On using the tlmenu database command:
Administration Options
======================
1. Routine Maintenance
2. Configuration and Setup
3. Database Recovery
4. Miscellaneous
5. Disaster Recovery Configuration and Maintenance
S. Show Logging Status (from any menu)
Enter option (1-5,S) :
On selecting option 1, Routine Maintenance:
Routine Maintenance
===================
1. Switch Clean Log
2. List Clean Logs
3. Archive Clean Log
4. Delete Clean Logs
5. Start Transaction Logging Status Monitor
6. Stop Transaction Logging Status Monitor
7. Save multiple Clean Logs to tape
8. Load multiple Clean Logs from tape
9. List multiple Clean Logs on tape
10. Save the Database
Enter option (1-10) :
On selecting option 4, Delete Clean Logs, the user is prompted:
This option deletes multiple clean logs from disk Do you want to do this (y/n/q) ? :
On entering y, you are shown a number list of clean logs available for deletion, from which you can select individual logs or ranges of logs in any combination. Alternatively, you can enter the name of a particular clean log you want to delete.
Select Clean Logs to Delete
===========================
1. CLOG160119-001
2. CLOG160119-002
3. CLOG160119-003
4. CLOG160119-004
5. CLOG160119-990
6. CLOG160119-991
7. CLOG160119-992
8. CLOG160119-993
9. CLOG160119-994
10. CLOG160119-995
11. CLOG160119-996
12. CLOG160119-997
Enter selections (eg 1,2,4-6) or Clean Log file :
To increase efficiency, and for compatibility with mvEnterprise, the DataBasic MATCH{ES} relational operator now supports a greater variety of patterns, and a new MATCHFIELD function is also provided which is similar to MATCHE{ES} but also returns the characters that match a requested sub-field of a pattern. To preserve backwards compatibility, the extended features of MATCHE{ES} are enabled by a new EXT.MATCH compatibility option.
The / (forward slash) DataBasic debugger command is updated to make it easier to display and edit arrays.
A new BASIC System debugger command is provided to switch to the DataBasic debugger.
A new MOVE TCL command is provided to move items from one file/data section to another file/data section, while preserving their time-stamps.
The DB (DataBasic) TCL command now includes additional @ commands:
?Displays a command summary.
F file-specifierChanges the current file.
I itemChanges the current item.
MEnters the ME editor to edit the program.
All commands are now case-insensitive.
Clean logs are now accessible from DataBasic.
Clean logs can be accessed from DataBasic by opening and reading them as for any standard Reality file. This enables a secure and high level access to Transaction Logging clean logs to provide detailed auditing of all database updates. With access to data becoming ever more complex this feature allows full and accurate audit information on how any database item has been changed, and helps with tracing potential security breaches where unauthorised updates have been made.