===============================================================================
                        R:BASE 4.5 Plus! README.TXT
===============================================================================

Contents:

    1. Installation
    2. Latest Features
    3. Additional Changes Affecting Applications
    4. General Usage
    5. Environment, Performance, and Integrity
    6. Settings
    7. Programming Notes
    8. Converting From R:BASE Versions
    9. Copyright Acknowledgments

This file contains important information which supplements the materials 
in your R:BASE documentation.

Please note the following:

o   Unless otherwise specified, this information in this file does not apply 
    to R:BASE versions prior to the 4.5 Plus! version.

o   The following ASCII text files provide additional information:

    MEMORY.TXT     Memory usage and suggested configurations
    DOCS.TXT       Corrections to R:BASE documentation
    WINDOWS.TXT    Running R:BASE 4.5 Plus! under Microsoft Windows 3.1

o   Remember to have current backup copies of your system configuration
    files such as CONFIG.SYS and AUTOEXEC.BAT

===============================================================================
1. INSTALLATION

CD ROM Drives------------------------------------------------------------------

If your computer has an attached CD ROM drive, R:BASE installation 
cannot proceed unless there is CD inserted in the drive with the door 
closed.

Incompatible TSRs--------------------------------------------------------------

The R:BASE INSTALL program is not compatible with the following 
programs:

    MIRROR DOS program
    The IMAGE Norton utility

If you have any of these programs loaded into memory, re-boot your 
computer without it before installing R:BASE.

If the INSTALL program does not complete, and you are not running the 
above utilities, there may still be a conflict with a memory-resident 
program. Edit your CONFIG.SYS file so that the only executable lines are 
FILES= and BUFFERS=. Edit your AUTOEXEC.BAT file so that the only 
executable lines are PATH and PROMPT. You can make a line non-
executable by putting the letters REM at the beginning of the line. Re-boot 
your computer and re-run the INSTALL program. After successful 
installation, return your CONFIG.SYS and AUTOEXEC.BAT files to their 
original state.

Bernoulli Box------------------------------------------------------------------

The R:BASE INSTALL program is not compatible with Bernoulli Box 
removable disk drives. You must first install to a fixed disk drive, then 
copy R:BASE to the removable drive.

===============================================================================
2. LATEST FEATURES

The following features are new to 4.5 Plus! version of R:BASE and were 
implemented after publication of the R:BASE manuals and the Startup 
Guide.

Creating Foreign Key Indexes with ALTER TABLE----------------------------------

Foreign keys were introduced in R:BASE 4.5. Inherently, an index is 
always created when you apply a foreign key. The fast foreign key setting 
(FASTFK) introduced in R:BASE 4.5 Plus! lets you apply a foreign key that 
creates a condensed index using counters instead of using pointers to 
table rows. Counters allow R:BASE to maintain the referential 
integrity of the foreign key much faster than by using pointers that point to 
every row in the table. The FASTFK setting is documented in the 4.5 Plus! 
Startup Guide.

A foreign key created with FASTFK ON is the optimum way of maintaining 
referential integrity and quick in performance, but it cannot be used by the 
optimizer to speed up data retrievals based on WHERE clauses. If, on the 
same column, you want a foreign key and an index using row pointers for 
data retrievals you can use the new FOREIGN INDEX option with the 
ALTER TABLE command. This FOREIGN INDEX feature is very new to 
R:BASE and is not documented in the 4.5 Plus! Startup Guide.

The table below summarizes the results of creating foreign keys and 
foreign indexes with the FASTFK setting:

                Result with FASTFK ON       |  Result with FASTFK OFF
                ----------------------------|-----------------------------
Foreign Key:    Key using index w/ counters |  Key using index w/ pointers
Foreign Index:  Key using index w/ pointers |  Key using index w/ pointers

If (with FASTFK ON) you want a foreign key and a full index on the same 
column, you do not need to explicitly create an index after you apply the 
foreign key. By using the FOREIGN INDEX option with the ALTER TABLE 
command you get an index using pointers that you can use for retrieving 
data.

Another benefit of using the FOREIGN INDEX option is the impact on 
database file 3. If you were to create a foreign key with FASTFK set ON, 
and then explicitly create an index on that same column you would have 
the index and key information stored in two locations in the database
file 3, resulting in a larger file size. The following commands would
cause this to occur:

    ALTER TABLE transmaster ADD FOREIGN KEY (custid)  REFERENCES customer
    CREATE INDEX custid_fk ON transmaster (custid)

The new FOREIGN KEY option of the ALTER TABLE command stores both 
the key and index information at one location in file 3, thereby not 
increasing the size of file 3 unnecessarily. The preferable command, with 
FASTFK ON, is as follows:

    ALTER TABLE transmaster ADD FOREIGN INDEX (custid) REFERENCES customer

This command can only be executed from the R> prompt. It is not 
available through the R:BASE menus. When FASTFK is set ON, use the 
FOREIGN INDEX option of ALTER TABLE instead of FOREIGN KEY when 
you want to have an index for retrieving data or in multi-table selects.

Note that if FASTFK is OFF, then using ADD FOREIGN INDEX is no 
different than creating a foreign key with ADD FOREIGN KEY; both 
resulting in an index using row pointers. 

As a rule of thumb, with FASTFK ON a column with many unique values is a
great candidate for a foreign index. A column containing many duplicated
values is better as a foreign key.

Using Expressions with INSERT--------------------------------------------------

The INSERT command now accepts expressions when using the VALUES 
option. For example,

    INSERT INTO table1 (column1,column2) VALUES (100,(.#date+30) )

New System Variable------------------------------------------------------------

The variable MICRORIM_SELMARGIN lets you control the starting column 
for output from the SELECT command. Create this variable and set the 
value to the column in which output will start. For example, set the 
variable to 1 to have the output start in column 1 (no leading space). Set 
the variable to 10 to have the output start in column 10.

    SET VAR MICRORIM_SELMARGIN = 1

===============================================================================
3. ADDITIONAL CHANGES AFFECTING APPLICATIONS

LJS Function-------------------------------------------------------------------

The LJS function handles NULL values differently in the 4.5 Plus! version 
of R:BASE. In prior versions, the function would not preserve spaces 
when the value in the LJS function was NULL. Spaces are preserved in 
4.5 Plus! version of R:BASE. For example, see the different results 
returned by the following function when column1 contains a NULL:

       (LJS(column1,30) + column2)

     4.5 result                           4.5 Plus! result
     -----------------                    --------------------
     one               aaa                one                  aaa
     two               bbb                two                  bbb
     ccc                                                       ccc
     four              ddd                four                 ddd

Column1 contains a NULL on row three; 4.5 Plus! preserves the blanks 
from the LJS function. This now makes it easy to do columnar menus and 
reports.

If you have an existing expression that used this feature and now 
displays differently, enclose the LJS function inside an IFEQ function to 
test for NULL. For example, replace the above expression with the 
following:

(IFEQ(column1,NULL,column2,(LJS(column1,30 + column2))

This expression gives the same result as earlier versions of R:BASE.

WRITE Command------------------------------------------------------------------

In R:BASE 4.5 Plus!, the WRITE command now operates differently when 
wrapping data that would extend beyond column 80. When using the "AT 
row/column" option to display a string of text at a specific string location, 
R:BASE 4.5 Plus! does not automatically wrap the text to the next line if it 
extends beyond column 80. The part of the string that extends past 
column 80 is lost. This was changed to prevent the screen scrolling when 
writing strings on line 24 or 25.

If you need to write a string of text longer than 80 characters, change a 
single WRITE command to be two commands, or do not use the "AT 
row/column" option.

===============================================================================
4. GENERAL USAGE

Autonumbering and Constraints--------------------------------------------------

If there is a column defined as NOT NULL UNIQUE using a constraint and 
if that column is AUTONUMBERed, then if the user attempts to 
renumber that column, R:BASE 4.5 Plus! will detect a constraint 
violation and prevent the update.

Rule Violations ---------------------------------------------------------------

R:BASE now highlights the first field in a row of imported data if there was 
a rule violation, instead of highlighting the exception value that caused 
the violation.

The rule message displays at the bottom of the screen for your reference. 
To correct a rule violation exception, you must first move the cursor to the 
field that is referenced by the rule message. Then edit the data and load 
exceptions as normal. 

Printing Labels----------------------------------------------------------------

When adding printer control codes to labels, you must also locate a 
variable that is set to (CHAR(255)) on that line. 

Columns with Picture Format----------------------------------------------------

If a column contains numbers 1 through 99, and you want to setup a 
picture format of 00 that will pad numbers under 10 with a 0 (such as 01, 
02, 03 and so on), then you must locate 3 spaces for the column to 
accommodate any negative signs.

If you only locate 2 spaces, numbers below 10 are not padded and 
numbers 10 and above display as "**".

===============================================================================
5. ENVIRONMENT, PERFORMANCE, AND INTEGRITY

Running R:BASE for DOS under OS/2 2.0 or Higher--------------------------------

Use the following DOS settings in the Workplace shell to run RBASE 4.5 
Plus! (32-bit) in a DOS box under OS/2 2.0 or higher:

1.  After selecting a DOS box icon, click the right mouse button on that icon 
    and choose SETTINGS.

2.  Click the SESSION tab using the left button, and then click on the DOS 
    SETTINGS button.

3.  Make sure that the DPMI_DOS_API setting is set either to AUTO or to 
    ENABLED.

4.  Make sure that the DPMI_MEMORY_LIMIT is set to at least 5 (MB), any 
    less may not work.

5.  If you elect to run R:BASE in a DOS Window box, then you must 
    deactivate the R:BASE sign-on screen. To do this, use the -R option on the 
    R:BASE command line when starting up the 4.5 Plus! version of R:BASE.

Running 16-bit and 32-bit Versions Concurrently--------------------------------

If you are running on a network and you have a mixture of workstations of 
both 16-bit and 32-bit R:BASE 4.5 Plus!, then you and your applications 
must obey the rules of database limits as though everyone is running the 
16-bit R:BASE. For users concurrently accessing the same database from 
both R:BASE versions, they must stay within the 1000 table/2000 column 
limits as imposed by the 16-bit version.

Database File Protection Under DOS---------------------------------------------

The DOS file system does not have the ability to prevent two concurrent 
DOS programs from overwriting the same file at the same time, when that 
file exists on a non-network local drive such as the C: drive. R:BASE 4.5 
Plus! prevents this kind of file collision in the following manner (the 
following instructions assume you are running the 4.5 Plus! version of 
R:BASE, DOS, and your database is on a local drive):

1.  If your database is CONNECTed, and if you ZIP to an external 
    application (like GATEWAY, CODELOCK, VIEWER, or one of your own 
    applications), R:BASE automatically sets the file attributes for the 3 
    database files to READ-ONLY. This prevents the ZIPped application from 
    concurrently writing over the database.

2.  When control returns to R:BASE (you return from the ZIPped 
    application), R:BASE 4.5 Plus! automatically resets the file attributes to 
    READ-WRITE.

3.  If, for any reason, your application fails to return to R:BASE, then your 
    database files remain set as to READ-ONLY preventing you from 
    reconnecting to your database until you reset the file attributes.

4.  To reset the file attributes, type the following DOS commands at the 
    DOS prompt (replacing 'dbname' with the name of your database):

     To reset all the files at once:

                ATTRIB -R DBNAME.RB?

     To rest the files individually:

                ATTRIB -R DBNAME.RB1
                ATTRIB -R DBNAME.RB2
                ATTRIB -R DBNAME.RB3

This problem does not occur if your database is located on a network 
drive and if you're not connected to a database when you invoke an 
external program. This problem can also be avoided by using ZIP 
RETURN or ZIP ROLLOUT instead of ZIP because R:BASE closes all 
database files.

Disk Caching in Expanded Memory------------------------------------------------

When running a disk cache program with Windows and R:BASE 4.5 Plus!, 
be sure to set the cache up in extended memory, not expanded memory.

Performance and R:BASE's Usage of Index on Text Fields-------------------------

R:BASE 4.5 Plus! allows you to define the number of characters to 
preserve in an index for a text column. This is done via the SIZE 
parameter when creating the index via the menus or the CREATE INDEX 
command.

You should be aware that the R:BASE query optimizer makes decisions 
on whether or not to utilize indexes on TEXT fields based upon the 
uniqueness of indexes on that TEXT column. The SIZE parameter 
determines the number of characters that R:BASE will preserve in the 
TEXT index. If you have, for example, a TEXT column defined to be 60 
bytes and the data in that column is typically unique after the first 20 
bytes, then you would want the SIZE parameter (# of bytes to preserve) to 
be at least 21 bytes so unique indexes could be created for each row. If 
you choose a number less than 20, then R:BASE performs sequential 
searches of the data when searching on that index. In these cases, 
R:BASE determines that sequential searches are faster than reading a 
non-unique index followed by reading the actual rows.

Applying Constraints-----------------------------------------------------------

Primary and foreign keys, and unique constraints internally use indexes 
to aid in the enforcement of the specified table constraints. The query 
optimizer can use these internal indexes in the same ways as an index 
explicitly created by a user for performance improvement.

To prevent unnecessary waste of storage resources, R:BASE does not 
permit a user to create an index that exactly duplicates an internal index.

When creating and dropping primary and foreign keys, you must have the 
multi-user setting off (SET MULTI OFF).

Full Disk Routine--------------------------------------------------------------

When you get the error message "Disk Problems - Please check disk and 
files" or "I/O problems - Check for a full disk", you may also get the 
warning message "Insufficient disk space to save <n> rows from 
<tablename>." 

Whenever R:BASE has a problem writing to the disk, it initiates a 
recovery routine. If R:BASE cannot recover all the rows from a table, it 
displays how many rows it was unable to save. 

Whenever you make a change to table structure by adding or dropping 
columns, R:BASE uses a temporary table named $$$. If you run out of 
disk space while changing a table's structure, R:BASE displays a 
message referring to the $$$ table; you should then perform the following 
steps:

1.  Use the DROP command to remove the $$$ table
2.  Use the PACK command to recover disk space
3.  Free up as much disk space as possible and repeat the original command. 

Please note that the above scenario can occur if network communications 
are lost during WRITE operations. If this happens, R:BASE may 
incorrectly report that it cannot save any of the data in the database where 
in reality no data has been lost.

Using a Read-Only Drive--------------------------------------------------------

If you attempt to start R:BASE from a read-only drive (such as a network 
drive which has read-only privileges), you must set a DOS environment 
variable, TMP, to a path on a drive with read/write access.  

For example, if drive F: on your computer is a read-only drive containing 
the R:BASE executables, and if you are currently logged on to drive F:, 
then you must first issue the following statement before typing RBASE at 
the DOS prompt.

     SET TMP=c:\ 

If you type RBASE at the DOS prompt but your default drive is a drive with 
read/write privileges, then you do not have to use the TMP environment 
setting.

Stack Overflow errors and Math Co-processors-----------------------------------

If you receive a 'Stack Overflow' error message, and your computer has a 
math co-processor, you need to add the following line to your 
AUTOEXEC.BAT file:

    SET NO87=1

===============================================================================
6. SETTINGS

The SET USER Command-----------------------------------------------------------

The SET USER command is not contained in the R:BASE 4.5 Plus! 
documentation. The SET USER command (either at the R> prompt or in an 
application) sets the user name to allow access to a database. You can 
also allow access to a database by specifying SET USER in your 
RBASE.CFG file. Use the following syntax:

    SET USER RACHEL
or
    USER RACHEL

STATICDB Setting---------------------------------------------------------------

If you use the new R:BASE 4.5 Plus! setting, SET STATICDB ON, R:BASE 
prohibits you from making any schema changes in your session. 
However, you are allowed to create new temporary tables during the 
session. R:BASE will delete these tables when you disconnect from the 
database.

Note that if you create any new Forms, Reports or Labels on your 
temporary tables or views, these objects will remain in the database even 
though the tables and views go away when you disconnect from the 
database. You must remove them manually if you want them to be 
deleted from the database.

Also note that if you have STATICDB ON, Application Express deletes any 
temporary tables and views because it always performs a database 
disconnect when started.

Printer Fold Table in RBASE.CFG------------------------------------------------

The documentation for editing the printer fold table is wrong. The fold 
table tells the printer how to print every character; if the printer does not 
normally print the character, the fold table tells it what characters it should 
combine to create the desired character.

For example "FOLD   131 97 BS 94" tells the printer to create character 
131, " ," by using the string that follows. If your printer can actually print 
" " without combining characters, then edit that line to say "FOLD   131 
131 00 00".

Do NOT delete any lines in this table.

===============================================================================
7. PROGRAMMING NOTES

The Do's and Don'ts of WHILE LOOPS and Variables-------------------------------

1.  DON'T clear your WHILE variable(s).

2.  DON'T define variables within your WHILE loop. Define them only 
    outside of the loop because values can change within the loop.

3.  DO adhere to the syntax rules for the SWITCH statement by making 
    sure that the argument for the SWITCH statement is an expression. Prior 
    versions of R:BASE were lax on this requirement. R:BASE 4.5 Plus! now 
    enforces this requirement.

4.  If you issue multiple SET VAR commands on a single command line, 
    then those variables will NOT be optimized. If you want to increase the 
    speed for that loop, you should put those SET VARs on separate lines.

User Defined Functions (UDFs) - Parameters-------------------------------------

When a parameter is passed to a User Defined Function (UDF) that 
contains a leading tab, a space character, or imbedded spaces, the 
parameters to the UDF need to be explicitly quoted with the double-quote 
character ("). 

"CON" as an abbreviation-------------------------------------------------------

Please note that "CON" is now an abbreviation for the CONNECT 
command, and is no longer an abbreviation for the "CONTAINS" keyword. 
Using "CON" as an abbreviation for "CONTAINS" produces a syntax error.

===============================================================================
8. CONVERTING FROM EARLIER R:BASE VERSIONS

Transaction Processing---------------------------------------------------------

When processing transactions (TRANSACT setting is ON) with a column 
definition that includes a NOT NULL UNIQUE constraint, then if you issue 
an UPDATE TABLE SET COLUMN = (COLUMN + 1) there will be a 
temporary conflict and therefore a constraint violation.

In a change from R:BASE 4.0a, the ALTER TABLE command cannot be 
used when the TRANSACT setting is ON. If you attempt to do so, you will 
receive a message "Command not allowed in transaction mode." If you 
must alter a table structure, you must do it when the R:BASE TRANSACT 
mode is set to OFF.

In 4.0a, R:BASE used to temporarily set the rules off and allow an update. 
In the 4.5 Plus! version of R:BASE, constraints are meant to enforce data 
integrity rules and updates are verified row by row. If there is a conflict, 
R:BASE 4.5 Plus! stops the process and rollsback the transaction.

Effects of New 18 Character Name Uniqueness------------------------------------

In R:BASE 3.X and 4.0a, you were allowed to create up to 18 character 
names for tables, columns, and views. However, there was a restriction 
that the first 8 characters had to be unique. This allowed flexibility in 
using long table names. For example, you could create a table named 
THISONE1TABLE and THISONE2TABLE. These prior versions of R:BASE 
would correctly identify these tables as different. Note that if you typed a 
statement like SELECT * FROM THISONE1TABLE, any miss-typed 
characters beyond the eight character would not cause an error because 
characters after the eighth byte were not used to determine uniqueness.

In R:BASE 4.5 Plus!, the names are unique out to 18 characters, so typos 
after the eighth byte are no longer forgiven by R:BASE. R:BASE 4.5 Plus! 
checks every character of the name used so you cannot be careless in 
your use of long names.

Single Line Scrolling in Forms-------------------------------------------------

Previous versions of R:BASE required TEXT and NOTE fields to be 
located on at least two lines to scroll through all the data. Now, TEXT and 
NOTE fields can be located on only one line and can be scrolled to see 
data beyond the located width. On small TEXT fields, however, this can 
appear as if data is not being entered into the field. For example, with a 
column defined as TEXT 4 and a located width of one character, scrolling 
to the right beyond the first character causes the field to appear empty, 
but actually the data has simply scrolled our of the display window.

If you do not want single line text fields to scroll, use the [<] format mask. 

Sort Order of Commands in R:BASE Parser----------------------------------------

R:BASE maintains a keyword list of all valid keywords used in the R:BASE 
command language. This list in R:BASE 4.5 Plus! is maintained in sorted 
order internal to the product. This was not the case in prior R:BASE 
versions.

Since R:BASE commands can be abbreviated to a minimum of 3 
characters, you should be careful on a few commands which now appear 
to the R:BASE parser in a different sequence. For instance, the CONNECT 
command previously appeared after the CONTAINS command, meaning 
that if you abbreviated a CONTAINS command to CON, the CONTAINS 
command executes. Now, if you abbreviate to CON, it picks the command 
up as CONNECT, which of course has no meaning in a command 
expecting the CONTAINS command.

Likewise, the COMPUTE command was previously detected with a COM 
abbreviation. Now due to the alphabetical listing, a COM statement to 
compute some value will parse to a COMMENT ON statement.

If you abbreviate to three characters and those three characters do not 
represent a unique keyword, you should modify your programming style 
to use enough characters to determine a unique match in the R:BASE 
keyword list. For a listing of R:BASE keywords, refer to Appendix E in the 
Startup Guide.

Correlation Names in VIEWS-----------------------------------------------------

When you save a view using QBE (Query By Example), R:BASE gives 
each table an alias, also called a correlation name. In version 3.1B and 
earlier, the alias used was #T. In version 3.1C the alias was changed to 
T_. It was changed to provide compatibility with R:BASE/V (the Vanguard 
Client) and other SQL-based systems.

For information about QBE, enter "help QBE" at the R> prompt.

Views that have been modified and saved in 3.1C or later may no longer 
work with reports created in earlier versions. When you print the report 
you may get the error message "-ERROR- Undefined break column or 
variable name." Modifying the report gives you the same error message 
because the table alias in the report no longer matches the table alias in 
the view.

To correct this, first CONNECT the database then run the R:BASE 
command file REPFIX.RMD which will update the table alias in the report. 
To run the command file, enter "RUN REPFIX.RMD" at the R> prompt and 
then enter the report to correct. You need to run the command file again to 
correct additional reports.

Database Conversion from 2.X to 4.5 Plus!--------------------------------------

When converting a 2.X database containing illegal column names, the 4.0 
DBCONV program correctly reports that these columns are illegal and 
must be renamed. NEWDB, the 4.5 Plus! program, assumes the user has 
legal column names and will not check for legality.

If you are converting from 2.X and have illegal column names, be sure to 
correct the naming conflicts prior to running NEWDB.

===============================================================================
9. COPYRIGHT ACKNOWLEDGMENTS

Microrim and R:BASE are registered trademarks of Microrim, Inc.
WEMU387.386 (c) 1991-1992, WATCOM Systems, Inc.
DOS4GW.EXE (c) 1991-1992, Rational Systems, Inc.
Novell and Netware are registered trademarks of Novell, Inc.
OS/2 2.0  and OS/2 2.1 are registered trademarks of IBM, Inc.
Instalit is a registered trademark of HPI, Inc.
Windows is a trademark, and Microsoft and MS-DOS are registered 
    trademarks of Microsoft Corporation.

END OF FILE ===================================== Thank You for Choosing R:BASE
