===================  R:BASE 4.5 README.TXT - 6/17/93 =====================

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

There is an additional file, DOCS.TXT, which contains corrections to
the printed documentation which you may also want to view.  It can be
viewed by either typing TYPE DOCS.TXT at the DOS prompt, or by entering
in the command ZIP VIEWER DOCS.TXT at the R> prompt.

=========================================================================
                           *** Installation ***
========================================================================= 
CD ROM players
--------------
If your system has a CD-ROM attached, you will need to insert a CD and 
close the door before INSTALL will correctly function.

Incompatible TSR's
------------------
* The R:BASE INSTALL program is not compatible with the DOS program MIRROR.
* The R:BASE INSTALL program is not compatible with the Norton utility
   IMAGE.
If you have any of these programs loaded into memory, re-boot your computer
without it before installing R:BASE.
 
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.
 
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 make a line non-executable by putting the
letters REM at the beginning of the line.  Re-boot your machine and re-run
the INSTALL program.  After successful installation, return your CONFIG.SYS
and AUTOEXEC.BAT files to their original state.
 
========================================================================
               Starting R:BASE 4.0 On 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 priviledges), 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 a SET TMP=c:\ before typing RBASE at the DOS 
prompt.

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


=========================================================================
                      Additional Command Line Options
=========================================================================
The -K Command Line Option
--------------------------
The value of K in this command line option is the number of 1024 byte 
blocks which are allocated by R:BASE when memory is needed internally 
for its operations.  The default value for K is 128, so memory is 
allocated in in chunks of 128,000 bytes.  If you change this value 
to 1000, then memory will be allocated in chunks of approximately 1Mb.
This may help resolve locking problems within Windows 3.1.

The -H Command Line Option (286 version only)
---------------------------------------------
The -H command line option is specific to 16-bit versions of R:BASE 
 and has no impact on the 386 version of R:BASE 4.0.

The -Z Command Line Switch
--------------------------
When R:BASE 4.0 executes, it attempts to allocate any memory that it 
might need in extended memory.  By default, it will not use conventional
memory for allocations.  This provides you with the maximum available 
conventional memory for use by programs to which you may want to ZIP.  
This conventional memory will also be used by CODELOCK and GATEWAY, both
of which run in conventional memory, not extended memory.

However, if R:BASE runs out of extended memory, you may need to allow it 
to allocate some of the conventional memory.  To do so, you can tell 
R:BASE to reserve up NNN bytes of conventional memory (for functions 
such as ZIPing to programs).  In this case, it will automatically 
allocate memory first in the extended area, and then proceed to the 
conventional memory if needed. It will not, however, allocate any memory 
beyond what you tell it to reserve.

For example, to tell R:BASE to reserve 250K of conventional memory during
processing, you can use this -Z switch on the R:BASE command line as
follows:

                C>  RBASE -Z250

This forces R:BASE to reserve 250KB of conventional memory for non-R:BASE
use (for example, to be used by a DOS application which you may ZIP to).

The default value for the -Z switch is 999, meaning that unless told
otherwise, R:BASE 4.0 will not allocate any conventional memory during
processing.  This will leave the maximum amount of conventional memory
available.

This switch has no effect for the 16-bit (286) version.


=========================================================================
                  Effects of New 18 Character Name Uniqueness
=========================================================================
In R:BASE 3.X and 4.0(a), the user was 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.  So, for example, you could
create a table named THISONE1TABLE and THISONE2TABLE.  Those prior versions
of R:BASE would correctly identify these tables as different.  However,
if you typed a statement like SELECT * FROM THISONE1TABLE, it would also
work equally as well to mis-type the characters following the eight byte,
so the command SELECT * FROM THISONE1TABEL would be processed as though
there were no typos.

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


========================================================================
               New 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 is maintained in sorted
order internal to the product.   This was not the case in prior versions
of R:BASE.

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 example, the command CONNECT used
to appear after the command CONTAINS, meaning that if you abbreviated
a CONTAINS command to CON, that it would always execute the CONTAINS
command.  Now, if you abbreviate to CON, it will pick the command up
as CONNECT, which of course has no meaning in a command which is 
expecting the CONTAINS command.

Likewise, the COMPUTE command used to be detected, if abbreviated to
COM, prior to the COMMENT command.  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.


=========================================================================
               Running R:BASE 4.5 Under Microsoft Windows 3.1
=========================================================================
R:BASE 4.5 will run under Windows 3.1 providing several conditions are
true.  These conditions are:

1)       You must have sufficient memory to run an instance of R:BASE.
         As a rough estimate, you need approximately 5.5Mb of available
         memory per the HELP / ABOUT dialog box from Windows 3.1.

2)       You must be using the DOS4GW.EXE 1.9 (shipped with R:BASE 4.5).

3)       You must modify your Windows SYSTEM.INI file to include a new
         statement in the 386Enh (enhanced) section as follows if
         your computer does not have a math co-processor.  Add the
         line:

                  device=c:\rbfiles\wemu387.386

         to your SYSTEM.INI file.  You should, of course, specify the
         correct location for your WEMU387.386 files.

4)       If you intend on running R:BASE in a window, then you must 
         either use a PIF file and check the 'windowed' checkbox, or
         you can just press Alt-Enter once R:BASE is loaded to foce
         Windows to reduce the full screen to a window.  However, DO 
         NOT display the R:BASE signon screen in a window or you will
         likely hang your windows session.

The file, WEMU387.386, is a device driver from WATCOM Systems, Inc., 
and is copyrighted and supported by WATCOM.

You have several options for memory managers when running under Windows.
R:BASE 4.5 will run correctly under Windows with simply HIMEM.SYS loaded,
or you may choose to use EMM386.EXE (from Microsoft), QEMM (from 
Quarterdeck), or 386MAX/BlueMax (from Qualitas).  Microrim does not
recommend any particular memory manager.  However, since the DOS 
Extender used by R:BASE (DOS4GW) is both VCPI and DPMI compliant, you
may find less conflicts if you use only HIMEM.SYS or either QEMM or
386Max/BlueMax and avoid EMM386.  EMM386 is not VCPI or DPMI compliant
and Watcom and Rational Systems have both reported intermittent problems
when using EMM386 with the DOS Extender.

There is an icon supplied with R:BASE 4.5 should you choose to use it.
It is installed with R:BASE in the directory and it is called RBASE45.ICO.

You may be able to run multiple sessions (windows) of R:BASE under
Windows simultaneously, depending upon your machine type and the amount
of available memory.  If you choose to run multiple windows of R:BASE,
you should keep in mind two important facts:

1)       The more copies you run, the slower they will all perform.

2)       If you open more than one window, be aware that you cannot
         connect to the same database in the multiple windows unless
         you have the database located on a file server, and provided
         that you have MULTI set to ON.  If you attempt to have two or
         more R:BASE sessions connect to the same local database at
         the same time, you will cause the database to be corrupted.


******* A Caution about Running R:BASE 4.5 (32bit) under Windows *******
------------------------------------------------------------------------
There are still some combinations of machines, memory managers, and
R:BASE applications which will not run reliably under Windows.  We are 
continuing our constant pursuit of these conditions so that they may be
rectified.  Unfortunately, there aren't any known hard and fast rules on
what combinations cause problems.

If you encounter problems where your machine hangs or R:BASE produces a
protection violation (resembling a hex dump of numbers all over your
screen), please report this to Microrim Technical Support so that we may
track your problem for the benefit of all users.

As we continue to improve the reliability of R:BASE under Windows, we
will make these improvements available to the customer base.


Out of Dynamic Space Error
--------------------------
If you are running under Windows and you receive an Out Of Dynamic
Space error, try setting the SORT MAX value to a higher value such as
100 using the command SET SORT MAX 100.  You may receive this error when
printing reports with break points or an explicit ORDER BY.

Disk Caching when Running R:BASE 4.0 Under Windows
---------------------------------------------------
If you are experiencing incompatibility problems running the 32-bit version
of R:BASE 4.0 under Windows, you should try using SMARTDRV.SYS versus
SMARTDRV.EXE.  SMARTDRV.SYS is supplied with DOS 5.0.


========================================================================
                     STATICDB Setting with R:BASE 4.5
========================================================================
If you use the new R:BASE 4.5 setting, SET STATICDB ON, R:BASE will 
prohibit you from making any schema changes in your session.  However,
you will be allowed to create new temporary tables during the session.
These tables go away automatically with a DISCONNECT from the database.

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

Also note that if you have STATICDB ON, and if you create any temporary
tables or views, then these temporary tables or views will go away if
you run Application Express since Application Express automatically does
a DISCONNECT when it starts up.


========================================================================
           Running R:BASE 4.5 16-bit and 32-bit Concurrently
========================================================================
If you are running on a network, and if you have a mixture of work-
stations of both 16-bit and 32-bit R:BASE 4.5, then you and/or your
applications must obey the rules of database limits as though everyone
is running 16-bit R:BASE.  Specifically, all users (whether running
the 16-bit or 32-bit R:BASE) must stay within the 1000 table / 2000 column
limits which are imposed by 16-bit R:BASE IF those users concurrently
access the same database.
 

========================================================================
                Transaction Processing and R:BASE 4.5
========================================================================
If you have a situation whereby you are using transactions (TRANSACT ON)
and there is a column definition that has a NOT NULL UNIQUE constraint on
it, then if you issue an UPDATE TABLE SET COLUMN = (COLUMN + 1), there
will be a temporary conflict and it will force a constraint violation.

In 4.0a, R:BASE would temporarily set the rules off and allow the update.  
In 4.5, R:BASE does not do this since constraints are meant to enforce
data integrity rules.  R:BASE 4.5 will verify the updates row by row and
if there is a conflict, it will stop the process and rollback the 
transaction.

A CHANGE FROM R:BASE 4.0A - If you have transactions set to ON, then you
are no longer allowed to issue an ALTER TABLE command.  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 transaction mode is set to OFF.

=========================================================================
                     The SET USER Command
=========================================================================
The SET USER command is not contained in the R:BASE 4.5 documentation.
SET USER (at the R> or in your application file) sets the user name to
allow access to a database.  In your RBASE.CFG file, you can use the
USER command to do the same thing.  The syntax of each is:

                           SET USER bob
                                or
                           USER bob

=========================================================================
              Autonumbering and Constraints and R:BASE 4.5
=========================================================================
If there is a column defined to be NOT NULL UNIQUE using a contraint and
if that column is AUTONUMBERed, then if the user attempts to renumber that
column, R;BASE 4.5 is going to detect a constraint violation and prohibit
the update.


========================================================================
            Running R:BASE 4.5 (DOS version) with OS/2 2.0/2.1
========================================================================
RBASE 4.5 (32bit) will run in a DOS box under OS/2 2.0/2.1 if the 
following settings are adjusted using the workplace shell:

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).
         Less than that will not work.

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


=======================================================================
        Performance and R:BASE's Usage of Index on Text Fields
=======================================================================
R:BASE 4.5 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 if
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 that unique indexes could be created for each row.
If you choose a smaller number than 20, then R:BASE will perform 
sequential searches of the data when searching on that index since the 
indexes created will not be unique, and therefore a sequential search 
of the rows will be faster than reading the non-unique indexes followed 
by reading of the actual rows.


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


=======================================================================
            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
         outside of the loop.  Values can be changed within the loop, 
         just don't define them inside of 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 enforces this requirement now!
4)       If you issue multiple SET VARs 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.

=======================================================================
                 Database Conversion from 2.X to 4.5
=======================================================================
When converting a 2.X database which contains illegal column names, the
4.0 DBCONV program correctly reports that these columns are illegal and must
be renamed.  NEWDB, the 4.5 program, assumes that the user has legal column
names and therefore does 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.


=======================================================================
             Creating Primary Keys, Uniques, Foreign Keys
=======================================================================
Primary keys, uniques, and foreign keys 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 which has been created
using explicitly created by the user for performance improvement.

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


==========================================================================
                         *** General Usage ***
==========================================================================
Database File Protection Under DOS
----------------------------------
The DOS file system has the unfortunate inability to prevent two concurrent
DOS programs from overwriting the same file at the same time when that file
exists on a local drive.  R:BASE 4.0 has been enhanced to prevent this kind
of file collision in the following manner.  Assuming you are running DOS, 
and assuming you are running R:BASE 4.0 with the database on your 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 will automatically set the file
                attributes for the 3 database files to READ-ONLY, thereby
                preventing the ZIPPED application from concurrently writing
                over the database.
        2)      When control returns to R:BASE (you return from the ZIPPED
                application) from your application, R:BASE 4.0 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 will be left with the
                file attributes set to READ-ONLY, and you will not be able
                to re-CONNECT to your database until you reset the file
                attributes.
        4)      To reset the file attributes, type the following DOS 
                commands at the DOS prompt.  Assuming your database is
                called 'dbname', use the following syntax:

                C>  attrib -r dbname?.rbf  (to reset all database files
                                            at once)

                          or

                C>  attrib -r dbname1.rbf
                C>  attrib -r dbname2.rbf   (to reset the files one at a
                C>  attrib -r dbname3.rbf    time)

This problem will not occur if your database is located on a network 
drive.  Furthermore, if no database is CONNECTed when you invoke an 
external program, then this problem will not occur.  This problem can
also be avoided by using ZIP RETURN or ZIP ROLLOUT instead of ZIP because
all database files will automatically be closed by R:BASE.

New Full Disk Routine.
----------------------
Now, 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 
will run a recovery routine.  If it cannot recover all the rows from 
a table you will see the message telling you how many rows it was unable
 to save.  You may also the message reference a table named "$$$".  
When 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 
during this process, R:BASE is unable to remove the temporary table.  
If you get the message referencing the table $$$, drop the table $$$, 
do a Pack in place or Pack to recover disk space, free up more disk 
space and then repeat the original command. 

Please note that the above scenario may occur as a result of events such 
as a loss of network communications 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.


Stack Overflow errors and Math Coprocessor's
--------------------------------------------
If you receive a 'Stack Overflow' error message, and your machine has
a math coprocessor, you will need to add the following line to your
AUTOEXEC.BAT file:
                    SET NO87=1

Disk Caching in EXPANDED Memory
-------------------------------
When running a disk cache program with Windows and R:BASE 4.0, be sure to
set the cache up in extended memory, not expanded memory.

Rule Violations 
---------------
When importing data, and you have exceptions due to rule 
violations, the value that violated the rule (the exception 
value) is not highlighted.  Instead, the first field in the 
row is highlighted.  The rule message is displayed 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. 

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 zero fill numbers under 10, you must 
locate 3 spaces for the column to accomodate the negative sign that 
may exist.

If you locate only 2 spaces, the numbers under 10 do not get zero 
filled and those 10 and above display as "**".

RBASE.CFG file
--------------
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.
 
New Single Line Scrolling in Forms 
----------------------------------
Previous versions of R:BASE required text and note fields to be
located on at least 2 lines in order 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, a column defined as TEXT 4 but only located
1 character wide will scroll to the right after the first character is
entered and the field then looks empty; it is not, the data has
simply scrolled out of the display window. 

If you do not want text fields to scroll, locate the fields on the
form with a width equal to the defined length of the column.  This
may necessitate redefining the column width smaller.  Alternatively,
locate a variable on the form instead of the column and then use
expressions to store the variable value into the column.  Customize
the field settings for the variable to set a default value of
ALT-255, a hard space (hold down the Alt key and press 255 on the
numeric keypad).  Then define 2 expressions in this order: 
colname=.varname, varname=colname.  

Correlation Names in VIEWS
--------------------------
When you save a view using QBE, 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.

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 will give you the same error message.  This is 
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, go to the R> Prompt, then enter: RUN REPFIX.RMD.  It 
will prompt you for the report to correct.  You need to run the command 
file again for each additional report to be corrected.

"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.


=========================================================================
                            ***** CREDITS *****
=========================================================================
Copyrights:
-----------
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.
