Hybrid Btrieve Browser Version 1.00 Copyright (c) 1991 by Michael S. Graham All rights reserved WARRANTY This software is provided as-is. There are no warranties, expressed or implied. MICHAEL S. GRAHAM DISCLAIMS ALL WARRANTIES RELATING TO THIS SOFTWARE, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER MICHAEL S. GRAHAM NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE SUCH SOFTWARE EVEN IF MICHAEL S. GRAHAM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL MICHAEL S. GRAHAM's LIABILITY FOR ANY DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM OF CLAIM. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE. Some states do not allow the exclusion of the limit of liability for consequential or incidental damages, so the above limitation may not apply to you. This agreement shall be governed by the laws of the State of New Jersey and shall inure to the benefit of Michael S.Graham and any successors, administrators, heirs and assigns. Any action or proceeding brought by either party against the other arising out of or related to this agreement shall be brought only in a STATE or FEDERAL COURT of competent jurisdiction located in Morris County, New Jersey. The parties hereby consent to in personam jurisdiction of said courts." HYBRID BTRIEVE BROWSER USER'S MANUAL TABLE OF CONTENTS Shareware ......................................... page 1 Introduction ...................................... page 2 System Requirements ............................... page 3 Installation ...................................... page 3 Files Included .................................... page 3 Patching Btrieve .................................. page 4 The description file .............................. page 6 Changing the demo description file ................ page 8 Demo description file (HBB.DSC) ................... page 9 Demo data file layout (HBB.DAT) .. ................ page 11 Demo data Btrieve description file ................ page 12 Running the Hybrid Btrieve Browser program ........ page 13 Command line switches ............................. page 15 Future versions ................................... page 16 Error messages .................................... page 18 Trademarks and Acknowledgements ................... page 19 SHAREWARE This software is provided as Shareware. This means you have the opportunity to try it before you buy it. If you continue to use this software for more than 90 days you are requested to become a registered user. Registered users will receive an update to the most recent version of the software, one free update, and free support. To register as a user of the HYBRID BTRIEVE BROWSER please send $29.95 to the address below, plus $3.00 for shipping and handling. ($5 for Canada and $8 for airmail outside North America). If you are interested in a site license, please call or write for pricing. The address is: Michael S. Graham 3 Algonquin Ave. Rockaway, NJ 07866 If you have any questions about this product or about registration, you can reach me on Compuserve. My number is 75140,3705. If you would like to talk to me, the number where I can be reached is 201-625-4297. Please call between 6:00pm and 10:00pm EST, as I work during the day. Page 1 INTRODUCTION The Hybrid Btrieve Browser is a TSR (Terminate and Stay Resident) program. It will load into memory and then return control to DOS until you enter the hot key combination of ALT + LEFT SHIFT + R. The Hybrid Btrieve Browser will then open the specified Btrieve file and display the fields setup in the HBB.DSC description file. The description file contains all the information needed to open and display up to 10 different file views, with each view having up to 10 fields displayed at one time. You can switch between views, scroll the view screen four ways (up, down, left, right), search for a specified key, or paste one of the view fields into the keyboard buffer, which can be intercepted by the program that the browser was popped up over. The Hybrid Btrieve browser currently takes up about 85K of conventional memory. This program can be used to display name, address and telephone information of frequently contacted people (ex. customers, patients, vendors). It can be used to add quick searching capabilities to existing programs. It can even be used to display popup help information. Page 2 SYSTEM REQUIREMENTS To run this software you will need an IBM PC, XT, AT or compatible with a minimum of 512K. DOS version 3.x or higher and Btrieve version 4.10 or higher are required. The Hybrid Btrieve Browser will only popup over text screens. It will work with 43 and 50 line text modes. However, it will not popup if you are in graphics mode. INSTALLATION Installation of this software is very easy. Copy all of the files on this disk into the drive and directory in which the browser will be run. Only three files are actually needed. HBB.EXE (the browser program) , HBB.DSC (either the demo description file provided on this disk or an HBB.DSC file that you created), and a Btrieve file (either the demo data file HBB.DAT or a data file that you specify in your HBB.DSC file). FILES INCLUDED HBB.TXT - This document file HBB.DSC - Demo description file HBB.DAT - Demo data file HBB.EXE - Hybrid Btrieve Browser program DEMO.BAT - Batch that will load Btrieve and run HBB.EXE BTRIEVE.EXE - Btrieve for DOS network version 5.10 README.1ST - ASCII file indicating Btrieve was already patched to work with this TSR Page 3 PATCHING BTRIEVE If you elect to use your own copy of Btrieve, instead of the one provided on this disk, you will need to patch the file using debug. If you don't patch it, the program will freeze on the first call Btrieve makes to DOS. Btrieve version 4.xx and 5.xx checks to make sure that DOS is not in a critical state before calling DOS to do a Btrieve operation. If the flag is set Btrieve will loop, waiting until DOS is not in a critical state before continuing. This looping will cause the system to hang. The following debug patches to Btrieve will jump past this checking and allow the Btrieve operation to be performed. Version 4.xx ------------ Copy Btrieve.exe to Btrieve (Don't put an extension on the destination file.) debug Btrieve -r (check registers, find the value of CX (length of file), for example CX = a61c, then use this address in the next line) -s 0 a61c b8 00 34 (this will return 2 addresses) xxxx:QQQQ (where QQQQ is used to reference address 1) xxxx:RRRR (where RRRR is used to reference address 2) -u QQQQ (unassemble to look for first "pop es") -a QQQQ (assemble) xxxx:QQQQ jmp AAAA:BBBB (where AAAA:BBBB is the address of the first "pop es") xxxx:QQQS (just hit enter) Do the same thing for address RRRR After changing QQQQ and RRRR -w (save back) -q (quit) Copy Btrieve to Btrieve.exe Page 4 Version 5.xx ------------ Copy Btrieve.exe to Btrieve (Don't put an extension on the destination file.) debug Btrieve -r (check registers, find the value of CX (length of file), for example CX = a61c, then use this address in the next line) -s 0 a61c b8 00 34 (this will return 1 address) xxxx:QQQQ (where QQQQ is used to reference address 1) -u QQQQ (unassemble to look for first "pop es") -a QQQQ (assemble) xxxx:QQQQ jmp AAAA:BBBB (where AAAA:BBBB is the address of the first "pop es") xxxx:QQQS (just hit enter) -w (save back) -q (quit) Copy Btrieve to Btrieve.exe Page 5 THE DESCRIPTION FILE The description file is the heart of the Hybrid Btrieve Browser system. It contains all the information needed to display up to 10 different views, with 10 fields per view. The HBB description file is a simple ASCII file. It is similar to the description file used by Btrieve to define the record length, page and index information for the Btrieve file when it is created. The HBB program only looks at the data contained between quotation marks. All other information is used to make the description file more readable. Blank lines can be used to separate groups like view information and field information. Value names like "default view = " can be used to easily identify what the value means. Below are examples of each value needed in a description file. An explanation of what it is used for appears on the right hand side.. default view = "2" | Use view number 2 when | | HBB is started up. | # of views = "3" | The total number of | | views is 3. | view title = "Customer Address" | View title which will be| | displayed when you | | choose VIEW while in | | HBB. | view file name = "CUSTOMER.DAT" | Btrieve file name to be | | opened and displayed. | view record length = "512" | The fixed record length | | of the Btrieve file. | | This should be the same | | record length used when | | the file was created. | view index = "1" | The Btrieve index | | number. | view index type = "11" | This number corresponds | | to the Btrieve Extended | | Key Type Codes 0-14. | | Currently only 0 and 11 | | are supported. They are | | string type and C string| Page 6 | type. | view paste field = "1" | The field number between| | 1-10 which will be | | pasted to the keyboard | | buffer if you choose the| | paste option. | view # of columns = "70" | This is the width of the| | browse record window. | | The minimum is 26. The | | maximum is 70. | view # of rows = "10" | This is the height of | | the browse record | | window. The minimum is | | 2. The maximum is 15. | view # of fields = "7" | The number of fields | | that will be displayed | | next to each other for | | each browse record. The | | minimum is 1. The | | maximum is 10. | field title = "Customer" | This is the name of the | | field that will display | | above the value. If the | | length of the field | | value is less than the | | length of the field, | | then the field title | | length will be truncated| | to be equal to the value| | length. | field position = "1" | The starting position of| | the field in the record.| | This is similar to the | | Btrieve description file| | position. | field length = "10" | Field length. Minimum | | length is 1. The maximum| | length is 255. | field type = "0" | This number corresponds | | to the Btrieve Extended | | Key Type Codes 0-14. | | Currently only 0 and 11 | | are supported. They are | | string type and C string| | type. | Page 7 CHANGING THE DEMO DESCRIPTION FILE Before you try creating you own HBB.DSC file, you might want to try changing the demo HBB.DSC file. Below is a listing of the contents of the demo HBB.DSC description file, the record layout of the demo HBB.DAT Btrieve Data file, and the Btrieve description file that was used to create the demo HBB.DAT file. This is included in case you want to experiment with changing the indexes in the demo description file. To run the Hybrid Btrieve Browser with the demo data and description file you need to run Btrieve with a page size of 2048 (ex. BTRIEVE /P:2048). You might want to start off by changing some titles and display field lengths. If you change a length, be sure not to make it longer than the defined length in the data file. Next you can remove the "Attention" field from the first view. Remember to change the "view # of fields = " from 7 to 6. Next, add the Btrieve data file "rep" field to the second view. Be sure to increase the "view # of fields = " by 1. Finally, try adding a new view to the description file. This view should contain account, name, contact1, rep, and misc. Also, use index #1 (index by name), and make the paste field the contact1 field. Page 8 DEMO DESCRIPTION FILE (HBB.DSC) default view = "2" # of views = "2" view title = "Doctor Address" view file name = "HBB.DAT" view record length = "512" view index = "1" view index type = "11" view paste field = "1" view # of columns = "70" view # of rows = "10" view # of fields = "7" field title = "Account #" field position = "1" field length = "10" field type = "11" field title = "Doctor Name" field position = "12" field length = "40" field type = "11" field title = "Address" field position = "53" field length = "40" field type = "11" field title = "City" field position = "94" field length = "20" field type = "11" field title = "State" field position = "115" field length = "2" field type = "11" field title = "Zip" field position = "118" field length = "10" field type = "11" field title = "Attention" field position = "233" field length = "40" field type = "11" view title = "Doctor Phone List" view file name = "HBB.DAT" Page 9 view record length = "512" view index = "0" view index type = "11" view paste field = "2" view # of columns = "70" view # of rows = "8" view # of fields = "6" field title = "Account #" field position = "1" field length = "10" field type = "11" field title = "Doctor Name" field position = "12" field length = "22" field type = "11" field title = "Contact" field position = "233" field length = "15" field type = "11" field title = "Phone" field position = "129" field length = "10" field type = "11" field title = "Fax" field position = "150" field length = "10" field type = "11" field title = "Modem" field position = "171" field length = "10" field type = "11" Page 10 DEMO DATA FILE LAYOUT (HBB.DAT) // Define the doctor record layout. typedef struct { char account[11]; char name[41]; char address[41]; char city[21]; char state[3]; char zip[11]; char phone[21]; char fax[21]; char modem[21]; char principal[41]; char contact1[41]; char contact2[41]; char group[11]; char rep[11]; char support[11]; char dealer[11]; char misc[21]; char filler[132]; // 511 bytes char text[16001]; // 16512 bytes } DOCTOR_FILE_RECORD; Page 11 DEMO DATA BTRIEVE DESCRIPTION FILE record=512 variable=y key=8 page=2048 position=1 length=10 duplicates=n modifiable=y type=zstring alternate=n null=n segment=n position=12 length=40 duplicates=y modifiable=y type=zstring alternate=n null=n segment=n position=115 length=2 duplicates=y modifiable=y type=zstring alternate=n null=n segment=n position=118 length=10 duplicates=y modifiable=y type=zstring alternate=n null=n segment=n position=315 length=10 duplicates=y modifiable=y type=zstring alternate=n null=n segment=n position=326 length=10 duplicates=y modifiable=y type=zstring alternate=n null=n segment=n position=348 length=10 duplicates=y modifiable=y type=zstring alternate=n null=n segment=n position=359 length=20 duplicates=y modifiable=y type=zstring alternate=n null=n segment=n Page 12 RUNNING THE HYBRID BTRIEVE BROWSER In order to run the Hybrid Btrieve Browser, you must first run Btrieve with any switches needed to open the files that are defined in the description file. After Btrieve is loaded just run HBB.EXE. The program will load into memory and display a small window indicating it is loaded and showing the hot key combination (ALT + LEFTSHIFT + R) needed to pop it up. Then, from DOS or from within a text display program, you can use the hot key to pop up HBB. HBB Option Selections --------------------- View - Type "V" for View and a window will come up showing the different views that you can select. A maximum of five views will display in the window. If there are more than five views you can use the arrow keys to scroll to the desired view. If an error occurs when trying to open a Btrieve file, the last view will be redisplayed. Search - Type "S" for Search and a window will come up prompting you for a value (index key) for which to search. Before the search begins, the value you type in will be converted into the proper format (Btrieve Extended Key Type). The index key type is define in the description file. A "greater than" search will be performed. The first record found with a key greater than or equal to the search field will be displayed as the highlighted browse record. If End Of File is encountered, then the last record in the file will be highlighted. Paste - Type "P" or ENTER to paste the predefined field into the keyboard buffer. A carriage return is appended to the field to reduce the number of keystrokes needed for data entry. The paste field number is defined in the description file. Unload - Type "U" to unload the Hybrid Btrieve Browser from memory. About - Type "A" to display a window describing version and copyright information. Help - Type "H" to display a window containing the navigation and selection keys that can be used in the HBB main display. You can scroll this screen using the arrow or page keys. Page 13 Exit - Type "E" or ESCAPE to close the Hybrid Btrieve Browser window and return control back to DOS or to the previously running program. Browse Window Navigation Keys ----------------------------- Escape - is used to leave all windows. Arrow Up - scrolls highlight bar up one line. Arrow Down - scrolls highlight bar down one line. Arrow Left - scrolls screen one character to the left. Arrow Right - scrolls screen one character to the right. Page Up - scrolls records up one page. Page Down - scrolls records down one page. Home - moves highlight bar to top of the screen. End - moves highlight bar to bottom of the screen. Control + Home - displays screen starting from first record. Control + End - displays screen ending with the last record. Shift + Arrow Left - scrolls 10 characters to the left. Shift + Arrow Right - scrolls 10 characters to the right. Control + Arrow Left - displays left most part of screen. Control + Arrow Right - displays right most part of screen. Page 14 COMMAND LINE SWITCHES The Hybrid Btrieve Browser has one command line switch: HBB /U This will unload the HBB.EXE file without having to pop it up and type "U" to unload. Page 15 FUTURE VERSIONS While writing this documentation I have accumulated some thoughts on what features the next version of this product might include. If you have a preference for any of these features, or have some other suggestions please drop me a note on compuserve. My number is 75140,3705. The features included in the next version will depend greatly on the response I receive to this first version. I would appreciate any comments or suggestions that you might have regarding this product. Below is a list of enhancements being considered: Store the view information in a Btrieve file instead of an ASCII file, thus reducing memory requirements. Introduce a new program to maintain this Btrieve view file. This would include conversion of existing ASCII view files, Adding, Changing, Deleting and Querying view information. Swap HBB.EXE to extended/expanded memory or to disk when not in use. Expand on-line help to display an index of help topics instead of just the one help screen. Expand the displayable field types to include integers, longs, floats, and perhaps user defined formats/masks for strings and numbers. Provide command line switches for default view and a user specified description file name. This would allow you to have different description files for different users, without putting the files in different directories or paths. Display more information about the current view, for example view name, data file name, path, key number, key field name, paste field name, free memory, free disk space, number of records in the current view file, and Btrieve version. Allow a view to be used for text display purposes. This would mean you would not see a highlight bar. You would not need to paste anything or search the key field. This would make HBB.EXE better for displaying help or reference information. Provide the ability to search all the display fields for a string value, not just the index field. If a record is found with the string value, then bring it up on the screen as the Page 16 highlighted record. Also include the ability to continue or abort the search. Save the browse screen information so the next time the view is displayed it will appear the same as the last time it was viewed. User specified hot keys. Remember that continued maintenance and improvement of this product depends on you. If you like Hybrid Btrieve Browser, please register by sending $29.95 to the address below, plus $3.00 for shipping and handling. ($5 for Canada and $8 for airmail outside North America). The address is: Michael S. Graham 3 Algonquin Ave. Rockaway, NJ 07866 Page 17 ERROR MESSAGES Most error messages that will be generated by the Hybrid Btrieve Browser will result from an invalid description file or a Btrieve error. If you get an error reading the description file you should check your HBB.DSC file very carefully for mistakes. Some Common Description File Errors ----------------------------------- The value you enter for the # of views is greater than the actual number of views defined. The value you enter for the view # of fields is greater than the actual number of fields defined. One of the values is not within the allowed range, For example, the VIEW # OF COLUMNS minimum is 26 and maximum is 70. If you enter 20 or 76 for this value you will get an error. You can find the value ranges in the section THE DESCRIPTION FILE. Some Common Btrieve Errors -------------------------- Btrieve error number 20 means Btrieve is not loaded. Load Btrieve then run HBB.EXE again. Btrieve error number 12 means the file you defined in the description file can not be opened. This could be the file does not exist or if you are on a network, you may have logged into a user area that does not have access to that file. For most other Btrieve error codes returned by HBB you should refer to your Btrieve manual. When in doubt you can unload Btrieve, then load it again (make sure you use the correct /M and /P command line switches) and then load HBB.EXE again to see if the error occurs again. Page 18 TRADEMARKS Btrieve is a registered trademark of Softcraft, Inc, A Novell Company. IBM is a registered trademark of International Business Machines Corporation. Microsoft is a registered trademark of Microsoft Corporation. NetWare and Novell are registered trademarks of Novell, Inc. Borland C++ is a trademark of Borland International , Inc. QuickBASIC is a trademark of Microsoft Corporation. ACKNOWLEDGEMENTS This product was created using TCXL, Copyright Innovative Data Concepts 1990-1991. Page 19