SYSFILES Account

SYSFILES is a pseudo account which contains a substantial number of the system files provided on a Reality database. It has no commands and cannot be logged-on to. The system files it contains are referenced from other accounts via Q-pointers. Most of these Q-pointers are generated when an account is created. System accounts SYSMAN and SYSPROG are provided with Q-pointers to all system files.

System files in the SYSFILES account are listed below; where appropriate, a more detailed description follows.

ACC file

The ACC file holds records of the usage of selected database accounts. Item-ids in ACC are based on user-id and port number, together with project number if usage is charged to a project via the CHARGE-TO command. The account logged-on to is recorded for each session.

If the recording of usage is required for an account, a U is included in attribute 9 of the Account Definition Item. When a user logs off an account, either using the OFF or LOGTO command, or the CHARGE-TO command is executed, the software checks this attribute. If statistics are to be kept, it records the user's logon time, CPU usage and other data in the corresponding item in ACC. If it does not find an appropriate item, it creates one.

Item format

Attributes in ACC items are multivalued. The first value refers to the first use of an account. Subsequent values are added in order of use.

Attribute	Description
item ID	user-id#port-number or user-id*project-number#port-number
001-003	Reserved
004	Dates logged-on (internal format).
005	Times logged-on (seconds past midnight).
006	Durations of logon sessions (seconds).
007	CPU usage values (milliseconds, accurate to within 20 ms).
008	Not used.
009	PLIds.
010	CCIs (-1 means no CCI).
011	Account to which the user is logged.

BASIC-DUMPS file

The BASIC-DUMPS file is used by the DataBasic application dump feature which allows a DataBasic application to dump (save) some information about its state, either automatically or on request.

Four types of dump items can be recorded in the application dump file:

• ABORT - written automatically when a DataBasic program generates a run-time fatal error message.

• WARN - written automatically when a DataBasic program generates a run-time warning message.

• SOFT - written by a BASIC.DUMP DataBasic statement.

• DEBUG - written by a DUMP DataBasic debugger command.

Item format (version 2)

Attribute	Description
item ID	A timestamp consisting of a 5-character internal date and a 6-character internal millisecond time. If multiple errors are produced in the same time interval by any port an additional re-hit parameter from A through to ZZZ is appended.
001	The port number of the user.
002	ABORT, WARN, SOFT or DEBUG.
003	The name of the account.
004	The name of the user.
005	A message specified by the BASIC.DUMP statement (for SOFT dump items).
006	An error number and its parameters (for ABORT and WARN dump items).
007	The abort program information message and its parameters (for ABORT dump items, and also for WARN dump items if warnings are forced to be fatal).
008	The current line of the program.
009	Either Stack empty if there is no stack information, or a value for each subroutine, function call or local GOSUB.
010	Item format version number (2).
011	For WARN and ABORT dump items, a duplicate count. At the first or only occurrence of the error, the value is null. Thereafter, the value is incremented each time the error recurs (that is, when an identical error occurs on the same port, account, user, program and line number). This applies only while the DB.DUMP.MULTIPLE custom environment option is unset (it is unset by default). For example, a WARN dump item with a duplicate count of 4 means that the same error has occurred five times.
012 onwards	An attribute for each program variable and its contents (for DEBUG dump items, and also for ABORT, WARN and SOFT dump items unless variables have not been suppressed by the DUMP.BASIC.VARS custom environment option). The format of these attributes is: variable-name=variable-contents If the variable is a dynamic array then its contents have any system delimiters replaced with their printable representations; that is by “_”, “^”, “]” and “/”.

Item format (version 1)

This layout version is no longer used.

Attribute	Description
item ID	A timestamp consisting of a 5-character internal date and a 6-character internal millisecond time. If multiple errors are produced in the same time interval by any port an additional re-hit parameter from A through to ZZZ is appended.
001	The port number of the user.
002	ABORT, WARN, SOFT or DEBUG.
003	The name of the account.
004	The name of the user.
005	A message specified by the BASIC.DUMP statement (for SOFT dump items).
006	An error number and its parameters (for ABORT and WARN dump items).
007	The abort program information message and its parameters (for ABORT dump items, and also for WARN dump items if warnings are forced to be fatal).
008	The current line of the program.
009	Either Stack empty if there is no stack information, or a value for each subroutine, function call or local GOSUB.
010	Item format version number (1).
011 onwards	An attribute for each program variable and its contents (for DEBUG dump items, and also for ABORT, WARN and SOFT dump items unless variables have not been suppressed by the DUMP.BASIC.VARS custom environment option). The format of these attributes is: variable-name=variable-contents If the variable is a dynamic array then its contents have any system delimiters replaced with their printable representations; that is by “_”, “^”, “]” and “/”.

BLOCK-CONVERT File

The BLOCK-CONVERT file contains data used by the BLOCK-TERM and BLOCK-PRINT commands to print ASCII characters in block format.

The standard file contains 66 items with ASCII characters as item-ids, corresponding to all printable characters except lower-case alphabetic letters.

Each item contains the information required to print its ASCII character in block format. Block characters are printed using an array of normal size characters. The array is always 9 characters high and between 10 and 15 characters wide (as defined by attribute 1).

You can create new items if required.

BLOCK-CONVERT contains additional data sections MINI-CONVERT and SMALL-CONVERT. For details of these, see the description of the BLOCK-PRINT command.

Item format

Attribute	Description
item ID	ASCII character
001	Width of block in normal font characters (decimal number).
002-010	One or more decimal numeric values, separated by value marks ']' if more than one, and preceded by the letter B or C: B indicates starting with spaces C indicates starting with characters. The numeric value immediately after the letter indicates the number of normal characters or spaces at the beginning of the corresponding line in the block. Numbers of characters or spaces then alternate as required.

Example

001 12 002 C4]4]4 003 B1]4]2]4]1

Block is 12 columns wide Output 4 characters, 4 blanks, then 4 characters in first line of block Output 1 blank, 4 characters, 2 blanks (and so on) in second line and so on, up to attribute 10.

ERRMSG file

The ERRMSG (Error Message) file contains some of the messages that can be displayed by software. Many of these messages are routine and do not indicate an error. Each message is contained in a separate item with an alphanumeric item-id.

You can modify or add items to ERRMSG using Editor or Screen Editor. However, note that on upgrade modified items may be overwritten. The PRINT-ERR command can be used to display messages from TCL.

Formatting codes

The following codes, appearing as the first character of an attribute, format the message as follows:

A{(n)} Inserts the next output parameter at this point in the message. If n is specified, left-aligns the parameter in a field of n blanks.

C Clears the screen.

D Inserts the system date in the format dd mmm yy.

E{char-string} Prints the item-id of the message (enclosed in brackets) followed by the optional character string.

H{char-string}{+} Prints the specified character string. A plus sign (+) at the end of the string holds the cursor on the current line.

L{(n)} Prints n line feeds (one if n omitted).

P Inserts the port number.

R{(n)} Inserts the next output parameter at this point in the message. If n is specified, right-aligns the parameter in a field of n blanks.

S{(n)} Skips n spaces, counting from the beginning of the line. If the end of the line is reached, the line is printed and a new line started. Starts from the beginning of the line (no spaces) if n is omitted.

T Prints system time in the format hh:mm:ss.

W Inserts the port number.

W(n)Delays n seconds before continuing with the remainder of the message.

X Skips the next parameter.

* Comment. Ignore the rest of the line.

FEATURES file

The FEATURES file contains details about the current database, such as which Reality software release/revision is running the database. It is used by support personnel.

NEWAC file

NEWAC (NEW ACcount) file is used as a model to create the MD for a new account. Its data sections contain command definition items which are copied into the MD of an account by CREATE-ACCOUNT, SYS-UPDATE, UPDATE-ALL-ACCOUNTS, UPDATE-ACCOUNT and MIGRATE.ACCOUNT. The commands are a subset of the SYSPROG command set.

The USER data section allows you to customise the accounts in your database. By default, any command and command synonym definition items it contains are copied into the account's MD, overwriting existing items with the same names.

In addition, you can create two optional items in the USER data section of NEWAC that allow you specify non-default operations for particular items:

USER-DELETE This can contain an attribute-mark-separated list of items to be deleted from the MD of an account. The listed items are deleted even if they exist in the USER data section.

USER-ADD This can contain an attribute-mark-separated list of items to be added to the MD of an account, but without overwriting items that already exist. The listed items must exist in the USER data section of NEWAC.

The default operation is performed only for items that are in neither of these lists.

The updates are performed in the following order:

1. Items in the default data section of NEWAC (supplied by NEC Software Solutions) are copied into the MD of the account, overwriting any existing items.
2. Items in the USER-DELETE list are deleted from the MD.
3. Items in the USER-ADD list are added to the MD without overwriting any existing items.
4. Items in the USER data section that are not in the USER-ADD list are added to the MD, overwriting any existing items.

PH-HISTORY file

PH-HISTORY is a log of status information related to Terminal Independent Handler (TIPH) processes. It is accessed using the PH-STATUS command.

Item format

Attribute	Description
Item ID	date*time*port-number
001	Name of the account onto which the TIPH process is logged.
002	Date the TIPH process started.
003	Time the TIPH process started.
004	Name of the account that started the TIPH process.
005	Name of the TIPH process specified in the PH-START command.
006	Port number running the TIPH process.
007	Options assigned to the TIPH process by PH-START.
008	Spooler print job number that contains the terminal output.
009	Current status of the TIPH process; that is: AActive. KAborted by PH-KILL. TTerminated normally. XAbnormal abort.

POINTER-FILE

POINTER-FILE contains items that are either lists generated by the List Generating Commands and saved using the SAVE-LIST command (for example), or cataloged DataBasic programs.

POINTER-FILE item-ids have the following format:

account*tag*name

where:

accountThe name of the account the list was saved under, or the account under which the DataBasic program was cataloged.

tag LFor saved lists or C for cataloged DataBasic programs.

nameThe name of the saved list or the cataloged DataBasic program.

Accessing items in POINTER-FILE

• To create, display, merge, modify, or delete an English generated list, use the EDIT-LIST command.
• To display the contents of a cataloged DataBasic program item use the PRINT-CATALOG command.

Using a local POINTER-FILE

If you wish, you can create a local file called POINTER-FILE to store your saved lists; cataloged DataBasic programs will normally continue to be stored in the global POINTER-FILE. Refer to Introduction to Accounts and the description of the CATALOG command for more information.

The item-ids in a local POINTER-FILE consist of just the list name.

PROCLIB file

PROCLIB contains standard Procs that are available for use on the database. To execute one of these Procs from an account, a calling Proc must exist in that account's MD.

For details of the Proc language, refer to the Proc Reference.

SERVICE-LOG file

This file contains a data section for each Reality licensed service. To list the data sections, log on to the SYSMAN account and enter:

LISTFILES SERVICE-LOG

Within each data section, each item represents a single report, identified by a numeric item ID with a value from 1 to 999, with each report that is logged being given the next number. When the number passes 999, it restarts at 1, overwriting the oldest log.

The items in the licensed service logs contain the following attributes:

Name	Description
AVERAGEDELAY	The average delay since the last report (TOTALDELAY/DELAYS).
DATE	The date the report was logged.
DELAYPERREQUEST	The average delay per licensed service call since the last report (TOTALDELAY/REQUESTS).
DELAYS	The number of times a licensed service call has been delayed since the last report.
LICENCE	The licensed number of data units per shift.
PEAKDELAY	The maximum delay imposed on any licensed service call since the last report.
REQUESTS	The number of requests (for example, licensed service calls) since the last report.
SHIFT	Number of hours in the rolling shift period over which data transfers are averaged.
TIME	The time the report was logged.
TOTALDELAY	The total (in seconds) of all delays since the last report.
USED	The number of licensed data units that have been used in current shift period.

Dictionary definition items allow you to use English to list, sort and select items from the log by any of these attributes. The default listing contains the DATE, TIME, LICENCE, USED, DELAYS, TOTALDELAY and PEAKDELAY attributes. The FULL macro provides a fuller listing, including the SHIFT, AVERAGEDELAY and DELAYPERREQUEST attributes.

Statistics are automatically logged when a licensed service call is made, provided it is an hour or more since the last report. The UPDATE-SERVICE-LOG TCL command allows you to generate a report for a particular licensed service at any time if required.

TCL.LOG file

This file contains logs of commands that have run from TCL. Logging can be configured using SSM and command logging TCL commands.

Items in TCL.LOG are of two types:

• Audit logs, created for each logon session. These contain only commands that were entered at the TCL prompt. They are retained until manually deleted.
• Support logs. These contain not only commands that were entered at the TCL prompt, but also those that were run from within those commands. Only two support logs are retained for each port: the current log and that for the previous session. Each time a user logs on, the previous log is deleted, the current log from the previous session is renamed to become the previous log and a new current log is created.

See Command Logging for more details.

Item format - Audit Log

Attribute	Description
item ID	portNumber*date*time where date and time are the log on data and time in internal format.
001	The log on date in the format dd MMM yyyy.
002	The log on time in the format hh:mm:ss.
003	The user's PLid.
004	The Reality user ID.
005	The account.
006	Not used.
007 onwards	The date, time and command entered.

For example:

 00401*14227*39383
001 Date.... 13 Dec 2006
002 Time.... 10:56:23
003 Plid.... UNIX-900383-pts/1
004 User.... daveh
005 Account. SYSMAN
006
007 Key.....  n Context,  : TCL,  - Proc,  < Macro,  * Basic,  # SQL,  ~ Rpl
008 13 Dec 2006 10:56:26 who
009 13 Dec 2006 10:56:40 where
010 13 Dec 2006 10:56:52 off

Item format - Support Log

Attribute	Description
item ID	portNumber or portNumber*PREVIOUS
001	The log on date in the format dd MMM yyyy.
002	The log on time in the format hh:mm:ss.
003	The user's PLid.
004	The Reality user-id.
005	The account.
006	Not used.
007	The key to the context characters used in the lines that follow.
008 onwards	A context key character followed by the command entered.

For example:

00401
001 Date.... 13 Dec 2006
002 Time.... 12:05:21
003 Plid.... UNIX-900383-pts/1
004 User.... daveh
005 Account. SYSMAN
006
007 Key.....  n Context,  : TCL,  - Proc,  < Macro,  * Basic,  # SQL,  ~ Rpl
008 : LOGON.PROC
009 - SET-STACK (200)
010 - WHO
011 - SP-ASSIGN = DESKJET
012 - TERM ,,,,,,,,4
013 : LOGTO ACC2
014 : ACC2
015 - BLOCK-TERM "ACC2"
016 : LISTFILES
017 1: SSELECT DICT // WITH DPTR = "1" BY *A1
018 1: SSELECT DICT //FIXES WITH DPTR = "1"
019 : OFF

This shows that the logon control program ran the commands SET-STACK, WHO, SP-ASSIGN and TERM, and the user then logged to account ACC2 before running the commands BLOCK-TERM and LISTFILES (which in turn ran SSELECT twice). The user then logged off.

USER.LOG file

USER.LOG contains an item for each user currently logged on to a database. Each item-id is the number of the port through which the user logged on.

Item format

Attribute	Description
item ID	Port number of user.
001	user-id, or user-id*project-name if the CHARGE-TO command has been executed.
002	Description of the user.
003	PLId.
004	Location.
005	Name of account to which logged on.
006	Logon date in internal format.
007	Logon time in internal format.