R:BASE

================= R:BASE 4.5 OS/2 README.TXT - 6/27/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 OS/2 prompt, or by entering in the command ZIP VIEWER DOCS.TXT at the R> prompt. ========================================================================= *** Installation *** ========================================================================= Adding your RBASE installation directory to your PATH in CONFIG.SYS ------------------------------------------------------------------- If you are going to execute R:BASE 4.5 from anywhere but the directory where you have RBASE installed, you must manually edit your OS/2 CONFIG.SYS file and add the path to your R:BASE 4.5 installation to the PATH command line. The installation process will NOT perform this operation. 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. 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. Starting R:BASE 4.5 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 OS/2 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 OS/2 prompt. If you type RBASE at the OS/2 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 value should ONLY be changed if you consistently have trouble completing your application or requests due to R:BASE running out of memory, or if your OS/2 SWAP file continually grows in size. If this does not solve these types of memory consumption, we recommend that you exit and restart R:BASE at appropriate intervals in order to refresh OS/2's memory management. ========================================================================= 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. ======================================================================== 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 OS/2 and 16-bit (DOS) R:BASE 4.5 Concurrently ======================================================================== If you are running on a network, and if you have a mixture of work- stations of both 16-bit (DOS) and 32-bit (OS/2) 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 DOS or 32-bit OS/2) must stay within the 1000 table / 2000 column limits which are imposed by 16-bit DOS 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. ======================================================================= 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 ("). ========================================================================= User Defined Functions (UDFs) - OS/2 2.x ========================================================================= OS/2 2.x is a 32 bit operating system and implements a flat memory model. Because of this, UDF's that run with the 32 bit DOS version of R:BASE must be changed to access the shared memory area slightly differently. The DOS 32 bit (and OS/2 1.X 16 bit) UDF's receive a segment name. This segment name is passed to the function DosGetShrSeg and a pointer is returned. This pointer is passed to the function MAKEP to get the usable pointer. The segment pointer must also be freed with the DosFreeSeg function once the UDF is finished with it. The 32 bit UDF replaces those 3 steps and function calls with a single function call. R:BASE 4.5 OS/2 will pass the UDF a shared memory name instead of a shared segment. This shared memory name is passed to the OS/2 2.x function DosGetNamedSharedMem, and the function returns a usable pointer to the memory. The parameters for this function are: ErrorRtn = DosGetSharedMemName( PPVOID pBaseAddress, /* pointer to memory (returned) */ PSZ pszSharedMemoryName /* passed in from R:BASE */ ULONG ulAttributeFlags /* PAG_READ | PAG_WRITE */ ) Example: OS/2 16 bit method (DOS 32 bit) strcpy(MemoryName, argv[2]); /* sets the storage area */ pReturnSegment = &ReturnSegment; /* make the FAR pointer */ error = DosGetShrSeg(MemoryName, pReturnSegment); pResult = MAKEP(ReturnSegment, 0); /* Clear out the shared segment */ memset(pResult, '\0', 1500); memcpy(pResult, wordnum, lw); pResult[lw]='\0'; /* RBASE requires a NULL at end */ error = DosFreeSeg(*pReturnSegment); OS/2 32 bit method strcpy(MemoryName, argv[2]); error = DosGetNamedSharedMem(&pResult, MemoryName, PAG_READ | PAG_WRITE); /* Clear out the shared Memory */ memset(pResult, '\0', 1500); memcpy(pResult, wordnum, lw); pResult[lw]='\0'; /* RBASE requires a NULL at end */ ======================================================================= 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.5 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 explicitly 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 *** ========================================================================== 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. 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. ========================================================================= *** Multiuser Considerations *** ========================================================================= R:BASE 4.5 for OS/2 2.0 and NOVELL NETWARE ------------------------------------------ There is a bug in some versions of the Netware Requester for OS/2 2.0. In order to use R:BASE 4.5 with Netware under OS/2 2.0, you should obtain the Novell fix release, NSD20L01.ZIP from Novell. Running Multiple OS/2 RBASE Sessions on a single Workstation ------------------------------------------------------------ R:BASE allows you to run concurrent sessions of RBASE.EXE on the same workstation. In order to be charged as a single concurrent license against your SERVER.SY5 file, however, each session must share the same RBASE.CFG file. Transactions Processing and multiple RBASE sessions --------------------------------------------------- If you are running multiple RBASE sessions on the same workstation against a single database, locally or over a network, you cannot run with TRANSACTIONS ON. ========================================================================= ***** 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.