$read.me (c)Copyright Sequiter Software Inc., 1992-1993. All rights reserved. ---------------------------------------------------------- README - Table of Contents I. Introduction II. CodeBase Electronic Documentation Files (Including additional CodeControls getting started documentation.) III. CodeBase Manual and Code Revisions IV. Bit Optimization Query Technology V. CodeBase Interactive for DOS (CID) VI. Examples VII. Using CodeScreens with CodeBase 5.1 VIII. CodeBase Public-Access: Sequiter BBS and Compuserve Access IX. Accessing More Than 20 Files in DOS and Windows X. CodeBase Multi-Platform C++ Usage ---------------------------------------------------------- I. Introduction CodeBase 5.1 serial and version numbers can be found on the inside-front covers of the supplied Reference Manual. This CodeBase 5.1 release supports the following compilers: i) Borland C++ 3.1, 4.0 ii) Microsoft C++ 7.0 iii) Microsoft C++ 8.0 ( Visual C++ ) iv) Microsoft C++ 8.0 NT ( Visual C++ for NT ) v) Watcom C++ 9.0, 9.5 vi) Borland 1.0 for OS/2 vii) IBM C Set ++ for OS/2 Additional compiler support will be added as it becomes available. ---------------------------------------------------------- II. CodeBase Electronic Documentation Files It is highly recommended that any installed documentation files be read in addition to the CodeBase manuals. The various documentation files provide additional specific information not found in the CodeBase manual. Please note that only documentation files relevant to the options installed will be present on your drive after installation. All electronic documentation files have been suitably formatted for hard-copy printing. To print any document, simply direct that file to your printer, using the 'print' command. The complete list of documentation files that are present on the CodeBase disk are as follows: GENERAL DOCUMENTATION: $READ.ME General user information, manual changes/updates, and installation information. Always installed. INSTALL.DOC Information on CodeBase installation. Includes manual unfolding documentation. CODEREP.DOC Further information on CodeReporter. Includes important information regarding the building of the CodeReporter launch utility executables. Located in subdirectory \CODEBASE\CODEREP\. CODECTRL.DOC Documentation on how to get started with CodeControls in the various configurations. Located in subdirectory \CODEBASE\CODECTRL\. COMPILER DOCUMENTATION: COMPILER.DOC Information specific to the installed compiler. EXAMPLES.DOC Information on usage of the provided source code examples. TEST.DOC Information on usage of the CodeBase test programs ---------------------------------------------------------- III. CodeBase Manual and Code Revisions The following are corrections to the CodeBase 5.1 printed documentation: Getting Started with CodeBase 5.1 : 1. Running an Example (page 13) The referenced batch file CB5WIN.BAT does not exist; the appropriate batch file is C5AP_WIN.BAT and its definition file C5AP_WIN.DEF. The example should read C:\MYDIR> COPY C:\CODEBASE\MSC8\C5AP_WIN.* C:\MYDIR> COPY C:\CODEBASE\WINDOWS\CB5FOX.DLL CB5.DLL 2. Compile & Link Example (page 13) Again, the Windows example D4EX_WIN.C may be compiled with the following DOS command C:\MYDIR> C5AP_WIN D4EX_WIN 3. Building Libraries (page 20) When installed CodeBase 5.1 does not copy a FoxPro compatible version of the DLL into the CODEBASE\CODECTRL sub-directory. The appropriate DLL must be copied into your working directory from the CODEBASE\WINDOWS subdirectory and renamed CB5.DLL. 4. Compile & Link (page 23) The referenced batch file CB5WIN.BAT does not exist; the appropriate batch file is C5AP_WIN.BAT and its definition file C5AP_WIN.DEF. The example should read C:\MYDIR> COPY C:\CODEBASE\MSC8\C5AP_WIN.* C:\MYDIR> COPY C:\CODEBASE\WINDOWS\CB5FOX.DLL CB5.DLL C:\MYDIR> COPY C:\CODEBASE\SOURCE\*.H C:\MYDIR> COPY C:\CODEBASE\EXAMPLES\D4EX_WIN.C C:\MYDIR> C5AP_WIN D4EX_WIN 5. C5AP_WIN.DEF not C5WIN.DEF (page 24) Item 4 under DLL and VBX should read: Link CodeBase as a DLL as discussed above (ie. include C5AP_WIN.DEF in project). 6. DLLINFO Utility (page 28) The described DLLINFO utility does not exist on the CodeBas diskettes. The example programs d4ex_win.c and d4exampl.c will preform the same functions once compiled and run. Alternatively, the correct DLL can either be copied from the CODEBASE\WINDOWS subdirectory or can be rebuilt with the appropriate batch or project file (ie. CB5.BAT or CB5.PRJ ) CodeBase 5.1 USER'S GUIDE: 1. .NTX Descending Order Tags (starting page 105) DESCEND support for numeric or date tags are not currently supported. Ignore any reference to numeric or date tag use with the DESCEND function wherever noted. As a work-around, a tag can be created by subtracting the numeric key from a large constant numeral. eg. For Field 'NUM', index on '9999999999 - NUM'. 2. Opening Index Files (page 115) New Functions: 't4create' should be 'i4create'. CodeBase 5.1 REFERENCE GUIDE: 1. CodeBase Settings and Variables addendum (page 8) New Conditional Compilation Switch. 'S4FLUSH' may be defined if a hard-flush is required when writing data to disk: S4FLUSH This switch automatically calls function file4flush() whenever a write() occurs. This switch is not usually required, since a write() should perform a flush, but some environments do not flush data immediately. S4FLUSH is meant to be used with these environments. See function file4flush(). 2. CODE4.lock_attempts Clarification (page 17) If CODE4.lock_attempts is greater than zero, it is the number of times a CodeBase function will attempt to lock before returning r4locked. If CODE4.lock_attempts is (int) -1, CodeBase retries until it succeeds. Any other value for CODE4.lock_attempts is undefined. 3. file4flush() (page 160) The 'NOTE' at the bottom of the page is incorrect. S4WINDOWS does not have to be defined. file4flush() may be used under DOS or other operating systems. 4. relate4lock() (page 226) Under 'Usage', please note that the return value of relate4lock() is of type 'int'. Usage: int relate4lock( RELATE4 *relate ) 5. The Comparison Function (page 235) At the bottom of the page is a small table with 'Return' and 'Meaning' headings. The '> 0' return should instead read: > 0 The value pointed to by p1 is greater than p2. 6. e4hook() (page 316) 'Description' should instead read: The purpose of this function is to allow the programmer to easily alter error reporting. When CodeBase is built with conditional compilation switch S4ERROR_HOOK, e4hook() is called by e4(), e4describe() and e4severe() to display error messages. Function e4hook() must be created by the user. An example shell for function e4hook() is provided at the top of file "E4ERROR.C". To modify error reporting, alter e4hook() to display error messages as desired. Alternatively, to turn off error reporting entirely, just define S4OFF_ERROR. 7. e4severe() (page 320) The parameter listing under 'Usage' should not include parameter 'CODE4': Usage: void e4severe( int err_code, char *desc ) 8. d4append_data() (page 43) The use of this function is no longer recommended because of the difficulty in updating the file headers. 9. CODE4.mem_size_memo_expr (page 21 ) New CodeBase setting: Usage: unsigned CODE4.mem_size_memo_expr Description:If a memo field has a length over 'CODE4.mem_size_memo_expr', the length over this value is ignored by the expression evaluation functions. For example, function expr4len() assumes that the memo field has exactly this length. Functions expr4vary() and expr4key() ignore the memo field information over this length. In addition, if a memo field's length is less than 'CODE4.memo_size_memo_expr', then expr4vary() and expr4key() add null characters to the end of the result. The number of null characters added to the end is 'CODE4.mem_size_memo_expr' minus the actual memo field length. This effect is the same as when dealing with trimed fields. By default, CODE4.mem_size_memo_expr is 1024. 10.date4format_mdx() (page 116) In 'Description', the value returned should be '1.0E100', not '1.0E300'. MANUAL CORRECTIONS AND ADDITIONS FOR CODEREPORTER 2.0 The documentation for function report4printerDC does not indicate the value of the returned DC. This handle to a device context is the previously specified DC ( if one was set ) or NULL if one was not set. It is the programmers's responsibility to free the returned DC. CodeBase SOURCE CODE CHANGES: Note: Notices of fixes to CodeBase 5.1 will be updated on files contained on Sequiter's BBS system. For more information, refer to section "CodeBase Public-Access Bulletin Board System." CodeBase BATCH FILE CHANGES: Note: CodeBase batch files no longer build import libraries as they are no longer needed. Ordinal exports/imports in the definition files allow the user to recompile the DLL without having to recompile the application. If the import library is needed it can always be created later. ---------------------------------------------------------- IV. Bit Optimization Query Technology When CodeBase 5.1 is able to use Bit Optimization Query Technology (BOT) when performing queries, the performance improvements can be staggering. In addition, there are specific things that you can do to ensure that CodeBase 5.1 is able to use BOT. First of all, BOT capabilities are built into the CodeBase 5.1 relate/query module, the report module and into CodeReporter. The principle of the technology involves using index information to quickly return query results. For example, if you have an 500,000 record invoice item data file and you are interested in sales of product "GIZMO". Then the likely query expression would be "product='GIZMO'". In this case, if the data file was indexed on field "PRODUCT", then CodeBase 5.1 would automatically take advantage of the index to immediately return the query results. So to use BOT, you need to do the following: 1. Make sure that the master data file's index file(s) are opened. 2. Specify a query expression containing, in whole or in part, the tag key compared to a constant. The query expression is set using function relate4query_set() or is set interactively under CodeReporter. 3. BOT is effective only when the query expression involves the master data file. Example: Assume that master data file CUSTOMER.DBF contains fields L_NAME, F_NAME, AGE, DT and COMPANY. It has a production index file with the following tag key expressions: L_NAME Type Character UPPER(COMPANY) Type Character AGE Type Numeric DTOS(DT) Expression DTOS(DT) returns a result of Character even though field DT is of type Date. In this case the following queries can take advantage of BOT. Query Expression Explanation L_NAME="SMITH" L_NAME is a tag expression which is compared to a constant. L_NAME>="S" .AND. Again there are two comparisons L_NAME<="T" of a tag expression against a constant. Both parts of the expression are use BOT. L_NAME="SMITH" .AND. Only the first part of the F_NAME="JOE" expression can use BOT. However, as this first part narrows the query result down considerably, the overall performance will still be very exceptional. UPPER(COMPANY)="IBM" Again, this is a tag expression compared to a constant. In this case, the tag expression is more complicated as it involves a function. Regardless, BOT is used. UPPER(COMPANY)="IBM" .AND. Both parts of the expression use L_NAME="SMITH" BOT. AGE>50 Even though the type of AGE is Numeric, we still have an tag expression being compared to a constant. AGE > 25*2 25*2 is still a constant even though it is a complicated constant. DTOS(DT)>="19930101" This would return all records where the date value in DT is greater than or equal to January 1st, 1993. If the tag expression was DT instead of DTOS(DT), then a query expression such DT>=CTOD("01/01/93") would also use BOT. However, you have to be careful when using CTOD because the format of its parameter depends on the date picture set in 'CODE4.date_format'. Here are some expressions which cannot use BOT. Query Expression Explanation F_NAME="JOE" There is no tag based on F_NAME. L_NAME+F_NAME="SMITH" There is no tag based on L_NAME+F_NAME. Even though there is a tag on L_NAME, it is not identical to the expression being compared to "SMITH". COMPANY="IBM" There is no tag based on COMPANY. The tag is UPPER(COMPANY). Again, the tag expression must match the exression being compared to the constant exactly. L_NAME=F_NAME This expression cannot use BOT because F_NAME is not a constant - it is a field. ---------------------------------------------------------- V. CodeBase Interactive for DOS (CID) Interactive CodeBase 5.1 for DOS (CID) is a CodeBase application that allows the interactive manipulation of databases. Interactive CodeBase may be used to test the operation and consequence of CodeBase functions, or as a tutorial aid to familiarize users with CodeBase functions, or may be used as a quick and easy way to manipulate databases without coding and compiling. A 'FoxPro format' DOS Interactive CodeBase executable is currently provided. The other formats are supported, but must be recompiled or downloaded from the Sequiter BBS. Interactive CodeBase for DOS, known as 'CID', contains much of the CodeBase functionality, as well as interactive browse and edit facilities. To install Interactive CodeBase, select 'Interactive CodeBase for DOS' during the CodeBase INSTALL. Alternatively, you may manually UNFOLD the 'interactive' files, contained in 'CID.FLD'. Using CID: The provided CID executable program can handle only one of the CodeBase-supported index formats. The file format can be determined by examining the last three letters of the executables provided: eg. CID_CDX.EXE is the CDX file format of FoxPro Also, during CID execution, the file format will be displayed on the bottom row of CID's main screen. Please ensure that the CID being used is the proper CID for your file format. If not, recompile as directed, or contact the Sequiter BBS for the correct CID. You can run Interactive CodeBase for DOS in either color or monochrome modes. Pass the command line argument of MONO to select monochrome mode or enter no arguments for color mode: Eg. c:\CID_CDX MONO ** for monochrome mode or c:\CID_CDX ** for color mode Upon startup, Interactive CodeBase for DOS will display a startup message. Press any key to clear this message. The main menu bar will then be activated. You can use the cursor keys to move the highlighting over the item that you desire and press [ENTER] to select. In addition you can use the highlighted hot keys to select a menu item. Holding down the ALT key and pressing a letter will move to appropriate menu. For example, pressing [ALT D] will move you to DATA4 menu. Pressing the letter that is highlighted in an entry of the current menu, will select that item. For example, pressing the [O] key while in the INDEX4 menu will select the i4open function. After selecting a function from a menu, you will be presented with a variety of menus, and input boxes, prompting you to enter in the parameters of the function. Most functions will present you with a list of the databases that are currently open. You can press the [ESC] key to abort most operations. When all of the parameters have been entered, the function will be executed. If CodeBase encounters any errors, they will be displayed in popup boxes. After execution of a function, the return value (if any) will be displayed. Examples: To open a database: -select d4open from the DATA4 menu. A file requester will then appear. -enter the directory containing the database you want to open. -a list of the databases in that directory will appear. -select the database moving the highlighting with the cursor keys and press [ENTER] To set the CODE4.safety to FALSE -select the CODE4 menu. -use the cursor keys to move the highlighting over CODE4.safety -press the [ENTER] key to togle between true and false. Using the Browser: InterActive CodeBase for DOS has a built-in Browser. To browse a database, either open it with d4data, or create it with d4create. Then select BROWSER from the main menu. You will then be presented with a list of open databases. Select the database that you want to browse. NOTE: Memo field browsing and editing is not yet supported. Browse Mode: The following keys have special functions when in browse mode: [UP ARROW] : Selects the previous record [DOWN ARROW] : Selects the next record [LEFT ARROW] : Selects the previous field [RIGHT ARROW] : Selects the next field [ESC] : Leaves Browse mode and activates the menu [ENTER] : Allows you to edit the field [PAGE UP] : Skips back one page of records [PAGE DOWN] : Skips forward one page of records [HOME] : Selects the first field [END] : Selects the last field [CNTL HOME] : Selects the first record [CNTL END] : Selects the last record [INS] : Inserts a new record [DEL] : Toggles the deletion flag Menu Items: BROWSE : Reenters Browse mode d4tag_select : Select one of the database's tags d4go : go to the entered record number d4seek : seek using the currently selected tag d4top : goto the top of the database d4bottom : goto the bottom of the database QUIT BROWSER : quit browser and return the main menu Compiling the Source Code: Source code for InterActive CodeBase for DOS has been provided along with batch files for Borland C++ (CIDBOR.BAT) and for Microsoft (CIDMSC.BAT). Note the special instructions at the top of these batch files. Usage of these batch files assumes that a library, named C5BASE.LIB, has been created first. Also, note that the CodeBase 5.1 header files must be accessible. If you are using Microsoft C ,you will also have to rebuild the CodeBase 5.1 library with the e4error and e4severe functions commented out. InterActive CodeBase for DOS has replacements for those routines and the Microsoft C linker will not allow functions in a library with the same names as those in the source code. ---------------------------------------------------------- VI. Examples There are four sources of CodeBase 5.1 examples: 1. The manual, for short examples of function (and class) usage. 2. The examples present on the CodeBase 5.1 diskette. All examples installed are placed on the CodeBase \EXAMPLES subdirectory. Examples from the manual can be found in \EXAMPLES. 3. The testing and diagnostic code. These programs test the important CodeBase functions, and can also be used to ensure that CodeBase 5.1 was installed correctly. Test code, if installed, can be found in \TEST. 4. Our BBS, which contains new examples produced by our developers and examples which users have uploaded. Please see 'Section IX: The CodeBase Public-Access Bulletin Board System (BBS)' for more information. ---------------------------------------------------------- VII. Using CodeScreens with CodeBase 5.1 Sequiter's 'CodeScreens 1.0' is an add-on package that contains screen management functions for DOS applications. If you are interested in obtaining this screen management library, please contact Sequiter Software for more information. You must have at least CodeScreens version 1.02. Owners of previous versions can contact Sequiter for upgrade information. CodeScreens 1.02 functions are used by creating a separate library, 'W4.LIB', which contains the screen functions. When using any screen function, remember to include 'W4.H' at the top of your program. 'W4.H' can be found with CodeScreens. There are also provided batch files that can be used to compile and link a CodeBase 5.1. application using screen functions. These are named "C4?C.BAT", where '?' is replaced by a specific letter denoting the compiler used. ---------------------------------------------------------- VIII. CodeBase Public-Access: Sequiter BBS and Compuserve Access Any user with a modem may connect with the Sequiter Bulletin Board System. Connection to the BBS is free, although all users are responsible for their own long- distance toll charges. The BBS operates twenty-four hours a day, seven days-a-week, excluding maintenance periods. The BBS operates under the DOS environment, running WildCat(c) communications software. Code updates for CodeBase 5.1 can be accessed from the BBS through the use of patch files, which may be downloaded freely. These files are .ZIP files containing instructions and the patch utility. The patch utility requires an existing copy of CodeBase 5.1 and works by updating your existing source and header modules to the latest version. The patch utility can also be obtained from Compuserve (see below) . The BBS also contains several CodeBase-related files and documents that may be downloaded. There is also a message system so that electronic correspondence may be left for Sequiter staff, or other BBS users. The files include example programs, utilities, add-ons and enhancements, written by both Sequiter developers and CodeBase users. Users are invited to upload interesting CodeBase-related files for the use of all BBS users. A list of the latest enhancements, fixes and additions for all Sequiter products is also maintained on the Sequiter BBS. Users are encouraged to periodically download these files, and make the appropriate changes. The phone number for the BBS is found on the back outside cover of the CodeBase manual. The phone number is currently (403)-437-2229. Settings for the connection are: 1200, 2400 or 9600 baud ANSI terminal type. No parity. 8 bits. 1 stop bit. Upon connection to the Sequiter BBS, a new user will be prompted for some information and the selection of a private password. After selection of your password, please memorize it since you will be asked for that password on future connections to the BBS. Sequiter Software is also a registered member of the 'Data Based Advisor Forum' on CompuServe. Through this forum, messages can be sent to Sequiter Technical Support. Also, support and demonstration files can be downloaded from the DBA library area. To access the DBA forum, type 'GO DBA' at any CompuServe exclamation (!) prompt. Messages can be directed to Sequiter using the following CIS ID number: 71321,1306 This account and the DBA Forum are both monitored for messages approximately once a day. (Week days only) The following are detailed instructions as to how our customers can access Sequiter through the DBA Forum on Compuserv (CIS). 1 - Once user is logged on to CIS, they may get to the DBA Forum from any "!" prompt by entering the command "GO DBA". 2 - This will bring the user into the DBA top menu, at which time the user selects menu item " 1 Data Based Advisor Forum ". 3 - The next screen is the Welcome Screen, at which the user presses the , which then takes the user into the "Forum Menu". 4 - If menu item " 3 LIBRARIES (Files) " is selected, the next menu to come up is one which lists all 17 library areas. All Sequiter files will be located in area " 7 Database OPP, C/C++ ". 5 - After selecting this area, the user can then browse through the message and file sections, searching by a key word which identifies our packages (i.e. SEQUITER, CODEBASE, CODEBASIC, etc.), or if the user knows the name of the file he or she wants to download, he or she can simply select download. -------------------------------------------------------------------- IX. Accessing More Than 20 Files in DOS or Windows Due to a default imposed by most compilers and DOS, no more than twenty files can be opened during the execution of any one single process by default. And since the file streams 'stdout', 'stprn', 'stdin', 'stderr' and 'stdaux' count as files, and your executing application counts as well, this leaves only fourteen database, index and memo files that are allowed to be opened by any one application. CodeBase has no inherent limit to the number of files opened, but will display an error because of the failure of the system function call 'sopen()'. Several compilers have patches available for increasing the file limit. However, because of the nature of these patches, Sequiter does not provide technical support regarding this issue. Please consult your compiler's manufacturer for information. Again, CodeBase has no inherent file limit, but will produce an error message when it receives an 'error' return from any C library function that is called. For further information on your specific compiler please consult the COMPILER.DOC in the appropriate directory. -------------------------------------------------------------------- X. CodeBase Multi-Platform C++ Usage Included with the CodeBase Multi-Platform ANSI diskettes are eight C++ stub files, which can be used to create a C++ CodeBase library. The C++ version has been compiled and tested using several GNU (gcc) compilers. Documentation for the C++ version is provided in the 'CodeBase++ Users Guide' and the 'CodeBase++ Reference Guide'. These manuals may be purchased from Sequiter Software. Contact Sequiter Software at the phone number listed on the back of any color manual for futher information. The eight files are already copied automatically when copy_all is used to install CodeBase. The following command files can be used to compile a CodeBase C++ library, and building C++ applications: FILE NAME DESCRIPTION --------- ----------- compilex This is a command file for compiling the CodeBase C++ library. The compiler is assumed to be the GNU (gcc) compiler. Use the command file cbbuildx to link the compiled objects into a library (or see Chapter 6 in the 'CodeBase Multi-Platform Manual'). cbbuildx This is a command file to build the library libcbx.a after compilation has been completed. See Chapter 6 in the 'CodeBase Multi-Platform Manual' for details. diagx A command file used to compile, link and execute the test programs. buildapx A sample command file used to compile and link source modules withe the CodeBase Multi-Platform C++ library. The compiler is assumed to be the GNU (gcc) compiler. buildapx takes the prefix of one source module as a parameter. The suffix is assumed to be '.cxx'. eg. buildapx d4excpp ------------------- END ---------------------