New features in Reality V15.6

Reality V15.3 contains a number of new features since the release of V15.2.

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 NEC Reality website, in order to help us to improve your Reality.

Note

The online documentation includes all the updates till fix version V15.1.0.0420.

Database Configuration Parameters

A new PlidByPeer feature has been added to Reality and is only available on UNIX and Linux. It enables the use of session licences on SSH connections (that is, more than one connection per licence).

Y Reality generates a PLId based on the TCP/IP address of the peer, with the format:

INET-IPaddress-TTY

For example: INET-172.16.100.72-TTY

N Reality generates a PLId based on the Reality serial number.

Default: N

tlmenu Menus and Procedures

Once the database has been identified, tlmenu displays a main menu entitled Administration Options, similar to that shown below.

Transaction Logging Menu System                Fri  Jan 12 10:25:12 2016
Database name : drtestslv                             Host name : gate10
State         : Transaction Handling/Logging enabled
       Administration Options
       ======================

       1. Routine Maintenance
       2. Configuration and Setup
       3. Database Recovery
       4. Miscellaneous
       5. Disaster Recovery Configuration and Maintenance
       6. Clean Log Export Configuration and Maintenance		
       S. Show Logging Status (from any menu)

       Enter option (1-6,S) :

Selection of each main menu option displays a sub-menu with another set of options. The sub-menu displayed varies according to the option selected and whether Shadow Database or FailSafe is being supported.

Note

Option 5 (Disaster Recovery Configuration and Maintenance) is available only if you have purchased the optional Disaster Recovery feature.

tlmenu is sensitive to enhancement keys. In the above mentioned Administration Options, the Clean Log Export Configuration and Maintenance option is at position 6 as a Disaster Recovery Configuration and Maintenance option is also present.

Clean Log Export Option

A new clean log export option has been added. Clean log export option is used to hold status information which can be displayed from the tlmenu. This is done by going to TCL in the SYSMAN account in the relevant database(s)

CREATE-FILE CLOG.EXPORT (I 
Account name:SYSFILES

The filters must be placed here to include or exclude the Account or Files. The filter can be given any name.

Use tlmenu for the relevant database. The Clean Log Export Configuration and Maintenance option in the tlmenu displays the following sub-menu.

Transaction Logging Menu System                Fri  Jan 12 10:25:12 2016
Transaction Logging Menu System                       Mon Jun 20 2022
Database name : ace.tester                        Host name : hempol01
State         : Transaction Handling/Logging enabled
       Clean Log Export Configuration and Maintenance
       ==============================================

       1. Configure/Reconfigure Clean Log Export
       2. Start Clean Log Export
       3. Stop Clean Log Export
       4. Stop Clean Log Export on next switch
       S. Show Clean Log Export Status


       Enter option (1-5,S) :

Option 1 on the new clog export option is for configuration tlmenu.

              Clean Log Export Configuration 
       ==============================================

       1. Export folder: /real0/clogs/ace.tester/export
       2. Filter name: NONE
       3. Include system accounts: N
       

Export folder holds the name of the directory which will hold the exported data - this may be a mounted disk (in the case of a failsafe pair, a disk should be mounted that both machines can access)

Filter name holds the Filter name if filter is required

Include system accounts may hold Y or N (Y will include data held in SYSMAN, SYSFILES and SYSPROG) - Generally such data may be excluded.

SP-SUMMARY and Related Procedures

A new SP-SUMMARY verb has been added to summarise formqueue contents and statuses.

This topic describes how to use SP-SUMMARY and its associated commands to summarise the formqueues contents and statuses. The following action codes and associated TCL commands are described:

Action Code

Action

Equivalent TCL command

Action Code 1

Switch View

No equivalent TCL Command

Action Code 2

SP-STATUS

SP-STATUS

Action Code 3

SP-JOBS

SP-JOBS

Action Code 4

Reset Selection

No equivalent TCL Command

Note

Action Code 4 (Reset Selection) is available only from the alternate Form Queue Status Summary screen).

Action Code 1 Switch View

Switches the display to the alternative view showing a summary of the statuses for each formqueue similar to the following:

13:52:42  30 Apr 2020                2 Print Jobs               Page  1/  1


Queue Name         Status          Number  .... Size ....  .... Copies ....

                                     Jobs  Total  Printed   Total   Printed

                                      

STANDARD           Hold                 2      3        0        2        0




1. Switch view   2. SP-STATUS   3. SP-JOBS    4. Reset      99. Exit

Enter action code / Option (P# / Q queuename)

This alternate screen displays a list of current formqueue names with a breakdown of their jobs summarised by status, together with their total number of print jobs and totals for their sizes and copies. At the bottom of the screen, five action codes are displayed. Action codes 2 and 3 correspond to the equivalent TCL commands that perform the same function.

Note

This screen only shows the status of queues in the Reality environment.

Action Code 2 SP-STATUS and SP-STATUS

Monitors and maintains the Spooler's formqueues.

Action Code 3 SP-JOBS and SP-JOBS

Displays and maintains print jobs in the Spooler's formqueues.

Action Code 4 Reset Selection

Resets the screen so that it displays summarised details for all formqueues. This may be used after a Q option has been entered at the prompt:

Enter Action Code / Option (P# / Q queuename)

That restricts the display to a single formqueue.

realevent

A new configuration parameter added.

Syntax elements

paramSpecifies the configuration parameter to be set or cleared. Must be one of the following:

htmltemplate
The path to an HTML message template.

In addition two new Notifiers have been added

Syntax elements

notificationMethod
The notification method to be configured. One of:

htmle
Similar to html but adds a 'Number: ' field containing a unique ascending identifier based on the date/time. The type is 'html'.

item
Notifies by creating a file for each notification in the directory with a prefix specified by the recipient. If no prefix is specified it defaults to 'files/event.'.

The filename is suffixed with a unique ascending identifier based on the date/time. This same identifier is included in the item as an additional a 'Number: ' field.

NEW.LISTVERBS

A new verb has been added which provides an improved and more descriptive layout of details than the original LISTVERBS verb.

Command class

Proc.

Syntax

NEW.LISTVERBS {(options}

Options

N Suppresses automatic paging (No Page).

P Sends output to printer assigned to your port (Printer).

GOnly shows entries in the GLOBAL MD.

AOnly shows entries in the users alternative MD.

MOnly shows entries in the user's (local) MD.

XShows all items in the MD rather than just verbs. (This a debugging option.)

LISTVERBS

A new option R has been added to the LISTVERBS verb.

Option

RCalls a revised version of LISTVERBS, NEW.LISTVERBS.

PH-MONITOR

A new verb has been added that monitors the Terminal Independent Process Handler (TIPH) process and displays the latest output lines of a specified TIPH port.

Important

The M option of PH-START must be used for this verb to work on Microsoft Windows systems.

Syntax

PH-MONITOR portNo {lines}

Syntax elements

portNo  The port number of the TIPH to display the output from.

lines  The number of lines to display from the end of the TIPH output. If not specified, the default is the last 10 lines.

PH-START

A new option M has been added to the PH-START verb.

Option

M Enables a monitoring tag in TIPH output — required to work on Microsoft Windows.

LISTFILES

A new option has been added to LISTFILES verb.

Options

V{limit}Sort the output by the descending total size of each file. An optional limit may be specified to restrict the output to files with a total size of over that value.

Using the GSSM Command

A new verb GSSM has been added. GSSM extends the capabilities of SSM to allow you to create and update multiple network, user, and security profiles at the same time, based on a new or existing item. The list of profiles to create or update can be provided by (all or part of) an active SELECT list, or the list can be created on the fly. GSSM uses the existing SSM screens for NETWORK, USERS, and SECURITY to modify an existing source item or create a new one

Syntax

GSSM {?} item ([NUS] {A}{C}{M}

Syntax elements

? Shows the usage details.

item The item-id of a source item to be used as the basis for creating or updating profiles. This can be an existing item in the NETWORK, USERS, or SECURITY file (as appropriate), or it can be created on the fly by the C option. There are restrictions on the existing items than can be used as source items.

N Applies to network profiles in the NETWORK file. When using an existing profile, the Location Description and CCI fields cannot be modified.

The following NETWORK items are reserved cannot be used as the source item: DEFAULT.

U Applies to user profiles in the USERS file. When using an existing profile, the Description and Password fields cannot be modified.

The following USER items are reserved cannot be used as the source item: DEFAULT, DSPMON, FILEDSP, NETDSP, REMFS, RLTYXDSP, SQLDEMO, SYSMAN and TAPEDSP.

S Applies to security profiles in the SECURITY file.

The following SECURITY items are reserved cannot be used as the source item: DEFAULT, DEFAULT.EXPLORER, DEFAULT.HARNESS, DEFAULT.REALWEB, DEFAULT.WEBSERVICE, REMFS, SYSMAN, SYSMAN.EXPLORER and TL.SECURITY.

A Adds any items from the select list that do not already exist in the relevant file. If this option is absent, only items in the select list that already exist in the file are updated.

C Allows the creation of a new source item if it does not already exist in the relevant file.

M Allows modification of the active select list of items, or creation of a new select list if one is not active (see list maintenance details below). The command validates that each item already exists in the relevant file before adding it to the list, unless the A option is also being used.

Restriction

Can only be run from the SYSMAN account.

Comments

One of the options N, U, or S must be specified.

Newly-created items based on the source item will use their id as the description rather than the source item's description.

If no changes are made to an existing source item using either EX or FI, the items in the active select list will not be changed and will report "No changes made."

If the existing source item is deleted using FD or a new item is abandoned using EX, the items in the active select list will not be changed and will report "'<itemid>' has been deleted."

List maintenance

The M option allows the entries in an active selection list to be modified or, if no list is active, create a new list of items.

File Triggers

Additional trigger types have been added: PRE-WRITE, POST-WRITE, PRE-DELETE or POST-DELETE, PRE-READ or POST-READ, PRE-CLEAR-FILE or POST-CLEAR-FILE, PRE-DELETE-FILE or POST-DELETE-FILE.

CREATE-TRIGGER

Syntax

CREATE-TRIGGER file-specifier trigger-name trigger-type

Syntax elements

trigger-type The type of trigger - one of the following:

WRITE or PRE-WRITE

Runs the trigger routine before writing a file item.

POST-WRITE

Runs the trigger routine after writing a file item.

READ or PRE-READ

Runs the trigger routine before reading an item from the file.

POST-READ

Runs the trigger routine after reading an item from the file.

CLEAR or PRE-CLEAR-FILE

Runs the trigger routine before a CLEAR-FILE operation on a file data section.

POST-CLEAR-FILE

Runs the trigger routine after a CLEAR-FILE operation on a file data section.

DELETE-FILE or PRE-DELETE-FILE

Runs the trigger routine before a DELETE-FILE operation on a file dictionary or data section.

POST-DELETE-FILE

Runs the trigger routine after a DELETE-FILE operation on a file dictionary or data section.

DELETE or PRE-DELETE

Run the trigger routine before deleting an item from the file.

POST-DELETE
Run the trigger routine after deleting an item from the file.

DELETE-TRIGGER

Syntax

DELETE-TRIGGER file-specifier[trigger-type*]

Syntax elements

file-specifier is the name of the file with which the trigger is associated.

trigger-type The type of trigger: WRITE or PRE-WRITE, POST-WRITE, DELETE or PRE-DELETE, POST-DELETE, READ or PRE-READ, POST-READ, CLEAR-FILE or PRE-CLEAR-FILE, POST-CLEAR-FILE, DELETE-FILE or PRE-DELETE-FILE, POST-DELETE-FILE.

Asterisk * specifies all triggers.

Note that many of the keywords have synonyms.

LIST-ALL-TRIGGERS

A new verb has been added which lists all the triggers associated with a Reality account.

Syntax

LIST-ALL-TRIGGERS file-specifier

Comments

The file specifier may be a local file (dictionary or data section), the master dictionary of an account, or a combination of both. Triggers cannot be associated with Q-pointers. If no file specifier is provided, the current account is assumed.

ACCESS Function

ACCESS(30)

For each of the different calling environments, ACCESS(30) returns a number associated with the command or reason for entry.

Environment ACCESS(23) ACCESS(30) Calling Sub-environment
Trigger 1 0 PRE WRITE trigger.
    1 POST WRITE trigger.
    2 PRE DELETE trigger.
    3 POST DELETE trigger.
    4 PRE READ trigger
    5 POST READ trigger
    6 PRE CLEAR FILE trigger.
    7 POST CLEAR FILE trigger.
    8 PRE DELETE FILE trigger.
    9 POST DELETE FILE trigger.
Conversion 3 0 CALL conversion code.
    1 B conversion code.
    2 User-defined User Exit.

TIDYPF

Displays saved lists and cataloged items associated with accounts, and optionally removes them for accounts that no longer exist.

Syntax

TIDYPF {account-name} {(options}

Syntax elements

account-nameThe name of a single account. Alternatively, a list of accounts can be supplied from an active select list.

If no account name is supplied, and there is no active select list, the default is to show all saved lists and cataloged items for all non-existent accounts.

Options

L Considers only saved lists.

C Considers only cataloged items.

N Suppresses automatic pagination.

R Removes items when prompted to confirm. This works only if a single non-existent account is specified; otherwise, this option is ignored.

D Does not show any details and does not prompt for confirmation. Each item that is deleted is represented by a dot character. This can only be used in conjunction with the R option.

E Include existing accounts, to produce an output similar to LISTPF. Nothing is removed (the R option is ignored if present).

A Produces an alternative view of the items.

Restrictions

Only available in the SYSMAN account.

DELETE-ACCOUNT

A new option has been added to DELETE-ACCOUNT verb.

Options

C Cleans up (removes) the deleted account's saved lists and catalogued items when prompted to confirm. This option has the same effect as the TIDYPF (R command.

XDT

A new verb XDT has been added which displays dates and times converted between internal and external formats.

Syntax

XDT {value} {(options}

Options

A Uses an alternative display format. Times are displayed in 12-hour format and dates with 2-digit years. (The defaults are 24-hour times and 4-digit years.)

I Inhibits the prompt for a date/time value if none is specified.

Operation

The command attempts to determine the type of value supplied from its format. If no value is supplied, the default is to use the current date and time and prompt for a value. If the value supplied is ambiguous then both time and date results are displayed.

Comments

The date format is recognised and displayed using the current DATE-FORMAT setting. The use of full stops in times is determined by the current setting of the ALT.MT environment option.

LIST-TABLE

LIST-TABLE is a new English reference command added which generates a formatted listing of the contents of a file based on the selection criteria entered in the same way as LIST, but tabulated in a similar way to an SQL SELECT statement, and without pagination

Syntax

LIST-TABLE file-specifier {item-list} {selection-criteria} {USING file-specifier} {sort-criteria} {output-specification} {format-specification} {macro-call} {(options}

Refer to Sentence Structure for descriptions of these parameters and the standard options.

Special options

S Displays a summary at the end of the listing.

Comments

As the width of the columns cannot be determined until all the data has been processed, large data sets will take longer to display.

SORT-TABLE

SORT-TABLE is a new English reference command which generates a formatted listing of the contents of a file based on the selection criteria entered in the same way as SORT, but tabulated in a similar way to an SQL SELECT statement, and without pagination.

Syntax

SORT-TABLE file-specifier {item-list} {selection-criteria} {USING file-specifier} {sort-criteria} {output-specification} {format-specification} {macro-call} {(options}

Refer to Sentence Structure for descriptions of these parameters and the standard options.

Special options

S Displays a summary at the end of the listing.

Comments

As the width of the columns cannot be determined until all the data has been processed, large data sets will take longer to display.

EESEARCH

EESEARCH is a new English reference command which searches a single file, a list of files, or all files in current account for specified character strings. T

Syntax

EESEARCH {filename}{(options}

Syntax elements

filenameThis is the file name to be searched. An asterisk can be used to signify all accounts. If a select list is active, the filename is not necessary and is ignored. If the file name is omitted and no select list is active then a No items present error is generated.

Prompts

After the sentence is entered, the processor prompts:

STRING:

Enter a character string and press RETURN. The prompt is repeated until only RETURN is pressed. The total of all character strings entered can be up to 500 characters .

Double quotes should not be entered.

Options

A ANDs string together. Items must contain all specified strings.

F Includes the item-id in the search.

N Selects only those items that do not contain the specified string(s).

O Sorts the resulting matched items in a file alphabetically. Searching large files will slow the process if this option is used.

R Suppresses the No items present message that is generated if no items are selected.

U Specifies that case is significant when comparing strings.

W Specifies that case should be ignored when comparing strings.

Comments

As the search can involve a large amount of data and/or items, the user has a number of opportunities to abort sections of the search using certain keystrokes:

Control-XAborts the search and immediately returns to TCL.

Control-YAborts the search of the current file data section and begins searching the next data section.

The process checks for the use of selected keystrokes before processing a file, and after each batch of 500 items in the file.

The name of the file and data section currently being processed is displayed to provide an indication of the progress.

DataBasic object code is not searched.

Case sensitivity

If neither U nor W is specified, the current data case setting (set with the DATA.CC environment option or the CASE TCL command) is used. See Case Sensitivity for more details.

If both U and W are specified an error message is displayed and no list is generated.

The differences between similar verbs are shown below

FIND Locates files with an item ID of the required field.

ESEARCH Locates an item within the named file that contains the given string.

EESEARCH Will locate items with the required ID or any items which contain the given string.

GENML, SGENML

Syntax

GENML file-specifier {item-list} {selection-criteria} {USING file-specifier} {sort-criteria} {output-specification} {format-specification} {macro-call} {(options}

SGENML file-specifier {item-list} {selection-criteria} {USING file-specifier} {sort-criteria} {output-specification} {format-specification} {macro-call} {(options}

Options

F Defines items as described below.

P Sends the listing to the printer. You will not be prompted for an output file or item.

T Sends the output to the terminal. You will not be prompted for an output file or item.

X Requests the output type for the results. This can be HTML (the default if none is given), JSON or XML.

If the X option is specified, the following prompt is displayed:

Conversion Type:

The valid responses are HTML, JSON, or XML. If you simply press RETURN, the default of HTML is used. If an invalid type is given, the message, Item not on file error is displayed and the type is requested again.

Operation

The F option uses a template item containing placeholders that will be replaced by the relevant values in the columns from the data. Each row of data will create an item in the specified file or if the output is to the screen or printer, a continuous listing. This overrides the X option and the supply of a template file and item is mandatory. This allows the user more detailed formatting of the generated data.

The template item uses placeholders to indicate where values from a row of data will appear. The placeholders are formatted as <%n%> where n is the number of the column to show the value from. For example, if a row of data consists of 123 VM ABC VM 456 and the template contains <%3%>~<%2%>~<%1%>, the resulting data will be 456~ABC~123. Any placeholders that are greater than the maximum number of columns in the data will not be changed.

If the output is to a file, the requested output item id will be used to create unique item ids in the file. The entered value will generate an id consisting of the value from the first column of a row of data suffixed with a dot then the entered id. For example, if the value in the first column contains 123 and the entered id is ABC then the resulting id of 123.ABC will be generated. A supplied id containing an asterisk signifies the position of the first columns value in the generated id. For example, an entered id of ABC-*-DEF would result in an id of ABC-123-DEF being used. The asterisk can be used any number of times and each occurrence will be replaced with the first columns value.

SLS

Removes redundant data from various system logs, with optional reporting.

Syntax

SLS log[lower-date{,upper-date} ‖ -n] {(options}

Syntax elements

logIdentifies the log to be processed:

ACCAccounting log.

DBD

DataBasic Debugger Dumps.

PHHTIPH log.

SERServices log.

TCLTCL Audit log.

ALLAll of the above.

lower-dateItems earlier than this date are not selected.

upper-dateItems later than this date are not selected.

nItems younger than n days are not selected.

Options

S Produces a summary listing of the selected items but does not actually remove them. This is the default option if none is specified.

R Actually removes the selected items.

D Produces a detailed listing of removed items (can only be used with the R option).

realclone

Options

-{p}uUpdates the specified instance to match the base version of the Reality software where all the files are copied regardless of the timestamp, rather than just the new files. The p option ensures that any files that are no longer present in the base version are deleted from the instance.

ENCRYPT

Two new encryption methods are now supported.

method An integer expression specifying one of the following encryption methods:

7 Provides access to the openSSL message digest algorithms for MD4, MD5, MDC2, RIPEMD160, whirlpool, SHA0, SHA1, SHA224, SHA256, SHA384 & SHA512. The algorithm to use is passed as the key parameter of the function. The returned data is binary so care must be taken to process values such as character 255 that may occur in the result.

8 Provides access to the openSSL ciphers for AES-128-CBC, AES-192-CBC, AES-256-CBC, DES-CBC and DES-EDE3-CBC. The cipher, key (in hex) and initialisation vector (in hex) are passed as an attribute separated list in the key parameter. The returned data is binary so care must be taken to process values such as character 255 that may occur in the result.

DECRYPT

Two new decryption methods are now supported.

methodAn expression that evaluates to an integer specifying one of the following decryption methods:

7 It will return a null value as decrypting a digest is not possible.

8 Provides access to the openSSL ciphers such as AES-128-CBC, AES-192-CBC, AES-256-CBC, DES-CBC and DES-EDE3-CBC. The cipher, key (in hex) and initialisation vector (in hex) are passed as an attribute separated list in the key parameter. The passed string is binary (as returned from a corresponding ENCRYPT). The returned data is binary so care must be taken to process values such as character 255 that may occur in the result.

SET-FILE

A new option D has been added to SET-FILE command.

Options

D Allows Q-pointered file to be set on another account.

Important

The D option needs GRU flag to be set manually by changing attribute 48 of SECURITY SYSMAN to 7 before editing the source code for SET-FILE on fork.

 

U2-SET

Defines the connection details when creating a new U2-VIEW / U2-RBASIC file.

Syntax

U2-SET system, [port], [default account], user, password

U2-VIEW

Creates a local Reality file that is used to access a remote U2 file and requires a U2-SET to be active in this session.

Syntax

U2-VIEW [DICT]Reality_file[U2_ACCOUNT][DICT]U2_FILE[(options]

U2-RBASIC

Configures a Reality file to be used to access a remote Basic subroutine on the U2 / Universe server.

Syntax

U2-RBASIC reality_file

U2-CHANGE

U2-CHANGE verb has been added to allow U2-VIEWS to enable password amendment with U2-VIEW’S.

Syntax

U2-CHANGES local file-namepassword new_value{(Option

Syntax Elements

local file-name The name of the file you want to change the parameters. It can be omitted if a SELECT list is active.

passwordpassword is required as a security measure and if any parameters are missing, a usage message is displayed.

Options

SChange remote system name.

UChange remote user name.

EChange the password used for the user in the connection.