home *** CD-ROM | disk | FTP | other *** search
/ Black Box 4 / BlackBox.cdr / database / bhlp18.arj / BTRHELP.DOC < prev    next >
Text File  |  1991-03-01  |  43KB  |  1,181 lines
  1.  
  2.  
  3.  
  4.                                    BTR HELP!
  5.  
  6.                     A File Maintenance Utility for Btrieve
  7.                                  Version 1.85
  8.  
  9.  
  10.  
  11.  
  12.                                 By David Smith
  13.                        (c) 1991 Informative Technologies
  14.                           1718 M Street NW, Suite 292
  15.                             Washington, D.C. 20036
  16.                              Voice (202) 675-4528
  17.                               FAX (202) 675-4529
  18.                              CompuServe 71311,2334
  19.  
  20. INTRODUCTION
  21.  
  22.     Btrieve is Novell's record-manager system designed to aid PC programmers
  23.     in the development of applications. BTR HELP! is a file maintenance
  24.     utility for software developers who use Btrieve.
  25.  
  26.     Integrating Btrieve into applications is time-consuming and tedious.
  27.     BTR HELP! was created to provide functions needed during the design,
  28.     development, and maintenance of Btrieve applications.
  29.  
  30. Some of the features of BTR HELP! are:
  31.  
  32.        o  A File Rebuilder for damaged Btrieve files.
  33.        o  Tests the integrity of Btrieve files.
  34.        o  Unloads Btrieve and shows the version loaded.
  35.        o  Browse and delete records from a Btrieve file.
  36.        o  Browse and edit records in HEX or ASCII format.
  37.        o  Displays Btrieve file statistics.
  38.        o  Supports text modes 100x60, 80x60, and 80x43.
  39.        o  Clones Btrieve files.
  40.        o  Lists File Operations, Key Types, and Error Codes.
  41.        o  Full Mouse Support.
  42.        o  Executes functions from batch files.
  43.  
  44. BROWSE
  45.  
  46.     This option allows you to browse a Btrieve file and select records. You
  47.     can select records with the mouse or with the arrow keys.
  48.  
  49.     EDIT
  50.  
  51.         Positioning the highlight bar over a record and selecting 'E' allows
  52.         you to edit the record. You are able to edit the file in HEX or
  53.         ASCII. To switch between editing in HEX or ASCII, press the TAB key.
  54.         HEX values show on the left of the window and ASCII on the right.
  55.         If the entire record does not display in the edit window press PgDn
  56.         or PgUp to see the rest of the Btrieve record. The record will be
  57.         saved as you edit it.
  58.  
  59.     DELETE
  60.  
  61.         Positioning the highlight bar over a record and selecting
  62.         'D' allows you to delete the record.
  63.  
  64.     KEY
  65.  
  66.         Pressing the 'K' key allows you to change the key path that you are
  67.         browsing on.
  68.  
  69.     UNDO
  70.  
  71.         If you want to undo the changes that you have made, you are given
  72.         the chance to after you are through browsing. Or you can press 'U'
  73.         to undo the changes immediately.
  74.  
  75.     COMMIT
  76.  
  77.         Pressing 'C' causes the changes that you made to the btrieve file
  78.         to become permanent.
  79.  
  80.     EXIT
  81.  
  82.         Pressing 'X' causes you to exit the browse menu.
  83.  
  84.     MODE
  85.  
  86.         Pressing 'M' allows you to select the way the records are displayed
  87.         when you are browsing them. Selecting 'K' from this menu displays
  88.         the records by the key segments for the current browse key.
  89.         Selecting 'A' displays the records by their ASCII characters.
  90.         Selecting 'H' displays the records in HEX format.
  91.  
  92.     SEARCH
  93.  
  94.         TEXT
  95.  
  96.             This option allows you  to do a text search on the file. Text
  97.             is searched in the format as it is shown on the screen. If you
  98.             are currently displaying the file in ASCII mode, the raw data
  99.             in the file will be searched. If you are displaying the records
  100.             in the file in key mode, the formatted keys will be searched.
  101.             The search begins with the record following the current one
  102.             highlighted on the screen. The records are searched in key
  103.             order along the currently displayed key path.
  104.  
  105.             --------------------------------------------------------------
  106.             Example 1
  107.  
  108.                 To find a certain hex string in a file:
  109.  
  110.                 1. Switch the browse mode to HEX BROWSE.
  111.                 2. Enter the hex values as the search text.
  112.                    (FF 43 52 33   - for example)
  113.                 Notice the spaces between each byte. You must enter the
  114.                 values you wish to search for in the same format as they
  115.                 are displayed on the screen.
  116.  
  117.             --------------------------------------------------------------
  118.             Example 2
  119.  
  120.                 To find the text 'SMITH' that could be any place in a record:
  121.                 1. Switch the browse mode to ASCII BROWSE.
  122.                 2. Enter 'SMITH' as the search text.
  123.  
  124.             --------------------------------------------------------------
  125.             Example 3
  126.  
  127.                 To find the text 'SMITH' that could be ONLY a part
  128.                 of key 3 when it is formatted for the display:
  129.                 1. Switch the browse mode to KEY BROWSE.
  130.                 2. Set the key path to 3.
  131.                 3. Enter 'SMITH' as the search text.
  132.  
  133.                 In all cases, the text you are searching for must be
  134.                 visible for the current KEY and BROWSE MODE.
  135.             --------------------------------------------------------------
  136.  
  137.             PARAMETERS
  138.  
  139.             This option allows you to select the text search parameters.
  140.  
  141.             Case Sensitive
  142.  
  143.                 If case sensitive is set to 'YES', Btr Help! differentiates
  144.                 between uppercase and lowercase when performing text searches.
  145.  
  146.             Search Degree
  147.  
  148.                 This selects how exact the match must be when performing a
  149.                 fuzzy text search. A setting of '0' means an exact match is
  150.                 requested. A setting of '1' means there can be a one
  151.                 character difference between the search text and text
  152.                 that matches in a record. Setting the search degree to any
  153.                 number 'N' means there can be a 'N' character difference
  154.                 between the search text and the matching text in a record.
  155.  
  156.                 Search   Search          Btrieve
  157.                 Degree   Text            Text          Result
  158.                 ------   ------          --------      --------
  159.  
  160.                   0      SMITH           SMITH         Matches
  161.                   1      WILLIAMS        WILIAMS       Matches
  162.                   1      BALLOON         BABOON        No Match
  163.                   2      BALLOON         BABOON        Matches
  164.                   2      DRIVE           ALIVE         Matches
  165.                   8      SUNSHINE        MISSILES      Matches
  166.                   1      FF 3E 55 C0     FF 3E 54 C0   Matches
  167.                   1      FF 3E 55 C0     FF 54 3E C0   No Match
  168.                   2      01/19/1990      01/22/1990    Match
  169.  
  170.     ADD
  171.  
  172.         This option allows you to add records to a Btrieve file. The btrieve
  173.         file record can be entered in ASCII or HEX format. Pressing the TAB
  174.         key switches between editing in HEX and ASCII format. If the entire
  175.         record does not display in the edit window press PgDn or PgUp to
  176.         see the rest of the Btrieve record. When you are through editing
  177.         the record, press the ESC key.  The record will be saved as you
  178.         edit it. If you do not want to add the record that you have entered,
  179.         you may press 'U' to UNDO the add. You are able to edit records up
  180.         to 64K in size.
  181.  
  182.     HOLD
  183.  
  184.         This menu option saves the physical location of the currently
  185.         highlighted record. After you have saved the currently highlighted
  186.         record, you can page through the file or change the current key
  187.         because HOLD has saved the location of the record in the file.
  188.         Selecting GOTO DIRECT will then take you back to the record.
  189.  
  190.     GOTO DIRECT
  191.  
  192.         The option takes you directly to a record. This uses the Get Direct
  193.         function to go directly to a record at a physical location in the
  194.         file. Enter the decimal number representing the offset of the record
  195.         into the file.  This command also works in conjunction with the HOLD
  196.         command.
  197.  
  198.     LOCK
  199.  
  200.         The highlighted record is locked and is not available to other
  201.         stations. NOTE: If you are using transaction processing the entire
  202.         file is locked while you edit it. The LOCK menu option is only
  203.         available if you are not using transaction processing.
  204.  
  205. FILE OPTIONS
  206.  
  207.     CLONE A BTRIEVE FILE
  208.  
  209.         This option allows you to make an exact duplicate of a btrieve file.
  210.         The file you create will not contain any records. The clone Btrieve
  211.         file will have the same file structure as the original Btrieve file.
  212.  
  213.     EMPTY FILE
  214.  
  215.         This option will remove all records in a Btrieve file.  It removes
  216.         all the records by creating a clone btrieve file of the selected
  217.         original file. Then it deletes the original btrieve file and
  218.         renames the clone btrieve file to the name of the original file.
  219.  
  220.     ADD RECORDS
  221.  
  222.         This option allows you to add records to a Btrieve file.
  223.         Records can be entered in ASCII or HEX format. Pressing the TAB key
  224.         switches between editing in HEX and ASCII format. If the entire
  225.         record does not display in the edit window press PgDn or PgUp to
  226.         see the rest of the Btrieve record. When you are through editing
  227.         the record press the ESC key.  The record will be saved as you edit
  228.         it. If you do not want to add the record that you have entered,
  229.         you are given the chance to after you are through editing the
  230.         record.
  231.  
  232.     STATISTICS
  233.  
  234.         This option displays the statistics on a Btrieve file in a
  235.         scrollable window. Press PgUp or PgDn to view the file information.
  236.         This option displays the number of records in a file, the number of
  237.         unique key values stored for each index in the file, and the number
  238.         of unused pages in the file. The "Space Utilization" shows the
  239.         amount of space in the ^Btrieve^ file that is actual data. The
  240.         "Space Per Record" is the average number of bytes needed for each
  241.         record in the file (including indexes). Also shown is the file path
  242.         if you Extend a Btrieve file.
  243.  
  244.  
  245. MISCELLANEOUS
  246.  
  247.     RESET BTRIEVE
  248.  
  249.         This option performs the Btrieve (28) RESET operation.  This
  250.         operation aborts any transactions the station has pending, releases
  251.         all locks, and closes any open files for the station.
  252.  
  253.     LOAD BTRIEVE
  254.  
  255.         This will load Btrieve without exiting BTR HELP!. If Btrieve is not
  256.         loaded when BTR HELP! begins, BTR HELP! attempts to load it. If you
  257.         would like to load Btrieve with different options you will have to
  258.         unload Btrieve first. This option loads Btrieve with the options
  259.         specified on the configuration screen. It is recommended that you
  260.         load Btrieve before starting Btr Help!. Loading Btrieve from within
  261.         Btr Help! can sometimes cause problems.
  262.  
  263.     UNLOAD BTRIEVE
  264.  
  265.         This will remove Btrieve from memory, close all open files at this
  266.         station, abort any transactions, and release all locks held by the
  267.         station.
  268.  
  269.     BTRIEVE VERSION
  270.  
  271.         This shows the Btrieve type, version, and revision.
  272.  
  273.     CONFIGURATION
  274.  
  275.         This option allows you to change various program settings. You can
  276.         choose SAVE SETTINGS to save the program options after they have
  277.         been set.
  278.  
  279.     TOGGLE SCREEN SIZE
  280.  
  281.         This option changes the number of lines on the screen from 25 to 43
  282.         if you have a EGA adaptor or from 25 to 50 if you have a VGA adaptor.
  283.  
  284.     SAVE SETTINGS
  285.  
  286.         This menu option saves the current program settings. Some settings
  287.         do not take effect until Btr Help! is     reloaded. The settings
  288.         are saved in a file called BTRHELP.CFG. This file is located in
  289.         the same directory as BTRHELP.EXE.
  290.  
  291. CONFIGURATION
  292.  
  293.     This menu option allows you to change various program settings. Some
  294.     settings will take effect as soon as you leave the configuration window.
  295.     Other settings will not take effect until the settings are saved and the
  296.     program is reloaded. These settings are overridden by the command line
  297.     settings.
  298.  
  299.     DATA BUFFER SIZE
  300.  
  301.         This is the maximum data record length that can be passed to or from
  302.         Btrieve. The Maximum Record Length on the file server should match
  303.         this value if you are using a server based Btrieve. Also BREQUEST
  304.         will need to be loaded with the /D: parameter matching this setting.
  305.  
  306.     BROWSE MODE
  307.  
  308.         This is the default browse mode setting. It can be set to ASCII,
  309.         KEY, or HEX.
  310.  
  311.     BTRIEVE AUTOLOAD
  312.  
  313.         This option allows you to select how Btrieve is loaded
  314.         after Btr Help! is loaded. There are four options.
  315.  
  316.               BTRIEVE  - Loads BTRIEVE.EXE with its command line options.
  317.  
  318.               BREQUEST - Loads BREQUEST.EXE with its command line options.
  319.  
  320.               BOTH     - Attempts to load BTRIEVE.EXE and if that fails it
  321.                          then tries to load BREQUEST.EXE.
  322.  
  323.               NONE     - Does not try to load BTRIEVE or BREQUEST.
  324.  
  325.     BIOS SCREEN WRITES
  326.  
  327.         If this option is set to 'YES', the text displayed on the screen
  328.         will use BIOS writes instead of direct writes for greater
  329.         compatibility. If this option is set to 'NO', the screen
  330.         updates will be much faster.
  331.  
  332.     MONOCHROME  COLORS
  333.  
  334.         This option causes the screen to use monochrome colors.
  335.  
  336.     CLEAR BACKGROUND
  337.  
  338.         If you select 'YES', the screen background will be cleared using
  339.         solid block character. If you select 'NO', the background will not
  340.         be cleared.
  341.  
  342.     SPACE FOR BTRIEVE
  343.  
  344.         This is the amount of space need to load BTRIEVE.EXE or
  345.         BREQUEST.EXE from within Btr Help! in bytes.
  346.  
  347.             To determine this value:
  348.                 1. Go to the dos prompt.
  349.                 2. Run CHKDSK.EXE to determine the amount of free memory.
  350.                 3. Load BTRIEVE.EXE with the parameters you wish to use.
  351.                 4. Run CHKDSK.EXE again.
  352.                 5. Subtract the free memory in step 4 from step 2.
  353.                 6. Add 10K to the number.
  354.  
  355.         This gives you space needed to load btrieve.
  356.  
  357.     BREQUEST LOAD PARAMETERS
  358.  
  359.         These are the options used to load BREQUEST.EXE from within
  360.         Btr Help!. If Btrieve is not loaded when Btr Help! begins,
  361.         Btr Help! attempts to load it. If you would like to load Btrieve
  362.         with different options you will have to unload Btrieve first.
  363.  
  364.     USE LOG FILE
  365.  
  366.         If this option is set to 'YES', the results of File Integrity and
  367.         File Rebuilder will be written to a file called BTRHELP.LOG. This
  368.         file is located in the same directory as BTRHELP.EXE.
  369.  
  370.     EMS VROOM
  371.  
  372.         If this option is set to 'YES', Btr Help! will check for the
  373.         presence of expanded memory and use it for the overlays needed by
  374.         the program. If you set this option to 'NO', Btr Help! will not
  375.         use expanded memory for overlays.
  376.  
  377.     EXT VROOM
  378.  
  379.         If this option is set to 'YES', Btr Help! will check for the
  380.         presence of extended memory and use it for the overlays needed by
  381.         the program. If you set this option to 'NO', Btr Help! will not use
  382.         extended memory for overlays. The use of extended memory is not
  383.         standardized and other programs that use extended memory may
  384.         conflict with Btr Help!.
  385.  
  386.     ALLOW ESC KEY
  387.  
  388.         If this option is set to 'YES', Btr Help! will allow the ESC key
  389.         to be pressed to abort File Integrity or File Rebuilder. You may
  390.         want to set this option to 'NO' if you do not want the file
  391.         rebuild interrupted or if you are rebuilding files from within a
  392.         batchfile.
  393.  
  394.     UNLOAD BTRIEVE
  395.  
  396.         If this option is set to 'YES', Btr Help! will unload Btrieve when
  397.         you exit Btr Help!. Btr Help! will always unload Btrieve if
  398.         Btr Help! loads it. Set this option to 'YES' if you load Btrieve
  399.         before you start Btr Help! and you want Btrieve unloaded when
  400.         Btr Help! ends.
  401.  
  402.     TRANSACTIONS
  403.  
  404.         If this option is set to 'YES', Btr Help! will allow the use of
  405.         transaction processing when you edit a file. This allows you to undo
  406.         changes that you make to the file. If you do not start Btrieve with
  407.         transaction processing on, you will want to set this option to 'NO'.
  408.  
  409.     43/50 LINE MODE
  410.  
  411.         If this option is set to 'YES' and you are using a EGA or VGA
  412.         monitor, Btr Help! will display more lines on the display. 43
  413.         for a EGA monitor and 50 for a VGA monitor.
  414.  
  415.     SHADOWED WINDOWS
  416.  
  417.         If this option is set to 'YES', Btr Help! will display shadows on
  418.         the program windows.
  419.  
  420.     OWNER
  421.  
  422.         If all of your Btrieve files use the same owner name you may want
  423.         to put the owner name here. Btr Help! will use it as the default
  424.         for accessing all files.
  425.  
  426.     BTRIEVE LOAD PARAMETERS
  427.  
  428.         These are the options used to load Btrieve from within Btr Help!.
  429.         Btr Help! attempts to load Btrieve if it is not loaded when Btr Help!
  430.         is started. Btr Help! uses these parameters to load Btrieve.
  431.  
  432.     FILE SPECIFICATION
  433.  
  434.         The file specification determines which files are displayed in the
  435.         browse or which file Btr Help! performs its functions on.  If the
  436.         file specification is not given then the default is '*.*' which
  437.         selects all file names.
  438.  
  439.  
  440. FILE INTEGRITY
  441.    
  442.     These options allow you to check the integrity of the key paths in a
  443.     Btrieve file. These options will determine if a Btrieve file's key
  444.     paths have been corrupted. If the key paths are corrupted you will
  445.     have to use the file rebuilder to repair the Btrieve file.
  446.  
  447.     FILE ERRORS INTEGRITY
  448.  
  449.         All the key paths in the file are traversed from beginning to end
  450.         and then from the end to the beginning. Checking the integrity will
  451.         show if any Btrieve errors occurred during the traversal of all of
  452.         the key paths.
  453.  
  454.     FILE LINKS INTEGRITY
  455.  
  456.         All the key paths in the file are traversed. A check is made to
  457.         make sure that the forward link for each record points to the same
  458.         record that has a reverse link pointing to it.
  459.  
  460.             Good links:
  461.  
  462.             A -> B -> C -> D -> E      "Forward Links"
  463.             A <- B <- C <- D <- E      "Reverse Links"
  464.  
  465.             An example of corrupted links:
  466.  
  467.             A -> C -> B -> A ->...     "Forward Links"
  468.             A <- C <- D <- E <- ...    "Reverse Links"
  469.  
  470.         Sometimes when key paths are corrupted, the pointer to the next
  471.         record will point to itself or point to some random record.
  472.         Checking the integrity will show if the key paths have been
  473.         corrupted in this way.
  474.  
  475. FILE REBUILDER
  476.  
  477.     These are options to rebuild a damaged Btrieve files. If you get an
  478.     (2) I/O Error status code when you try to access a Btrieve file, then
  479.     the file probably needs to be rebuilt. You have four options;
  480.     Regular Rebuilder, Quick Rebuilder, and File Recovery are used to
  481.     recover records.  Repair Header is used to fix damaged btrieve headers.
  482.  
  483.     REGULAR REBUILDER
  484.  
  485.         If you value your Btrieve file and it is damaged, try rebuilding a
  486.         copy of the file. Rebuild the file on the same drive as the damaged
  487.         Btrieve file. First, this option will create a new file with the
  488.         same Btrieve structure as the file you want to rebuild. Then the
  489.         program copies as many records as it can into the new file starting
  490.         from the beginning of the old file. If it encounters any problems,
  491.         it will try to copy records from the end of the file. When it has
  492.         copied as many records as it can into the new file, the old file
  493.         is deleted and the new file is renamed to the old file's name.
  494.  
  495.     QUICK REBUILDER
  496.  
  497.         This option only works with Btrieve version 5.1 or higher. It uses
  498.         the Get Next Extended and the Insert Extended to rebuild the file.
  499.         If you value your Btrieve file and it is damaged, try rebuilding a
  500.         copy of the file. Rebuild the file on the same drive as the damaged
  501.         Btrieve file. First, this option will create a new file with the
  502.         same Btrieve structure as the file you want to rebuild. Then the
  503.         program copies as many records as it can into the new file starting
  504.         from the beginning of the old file. When all of the records have
  505.         been copied into the new file, the old file is deleted and the new
  506.         file is renamed to the old file's name. Note: Quick rebuilder will
  507.         be "quickest" if it is using a server based btrieve. To rebuild
  508.         using a server based Btrieve with BREQUEST it will need to be
  509.         loaded with the settings: BREQUEST /D:54000. Also, the Maximum
  510.         Record Length on the file server will need to be changed to 54000.
  511.         After it is changed on the file server you will need to reload
  512.         Btrieve. 54000 was selected in this example for the maximum rebuild
  513.         speed. The maximum record size is selectable on the configuration
  514.         screen.
  515.  
  516.     REPAIR HEADER
  517.  
  518.         Rebuilding the header is not trivial. You can just as easily damage
  519.         a good file using this option as to repair a damaged file. This
  520.         option is used to repair a damaged Btrieve file header. It should
  521.         ONLY be used if:
  522.  
  523.             (1) You receive a (2) I/O Error when opening the file.
  524.  
  525.             (2) Incorrect or strange values are shown when you
  526.                 display the statistics on the file key structure.
  527.  
  528.             (3) You receive a (30) Not a Btrieve file error when
  529.                 opening the file.
  530.  
  531.         Rebuilding the header starts by replacing the damage header in the
  532.         btrieve file. It then makes modifications to the header based on the
  533.         number of possible data pages in the file.  After repairing the
  534.         header, rebuild the file before you try to access the file. You
  535.         should only work with a copy of the damaged file. Even though it
  536.         is damaged you may want to keep a copy of the original damaged
  537.         file to try another repair method.
  538.  
  539.     FILE RECOVERY
  540.  
  541.         This option is for the most seriously damaged btrieve files. It
  542.         calculates every possible position a record could be in a file and
  543.         tries to extract the record and inserts the records into a new
  544.         btrieve file. Select START RECOVERY to recover the file with the
  545.         default parameters. Note: This method sometimes recovers more
  546.         records than were originally in the file. If you browse the
  547.         recovered file you will be able to see the extra records at the
  548.         start or end of a key path. This method may not be valid with
  549.         Btrieve versions greater than 5.1 because the file format may change.
  550.  
  551.         PAGE OPTIONS
  552.  
  553.             This is where you can select the starting and ending pages for
  554.             the file recovery. Normally you will not need to change these
  555.             settings. If you interrupt a rebuild, you can restart it by
  556.             setting the starting page as the page where the rebuild was
  557.             interrupted.
  558.  
  559.             ----------------------------------------------------------------
  560.             Example
  561.  
  562.                 For a file with 10,000 pages. You could break it into two
  563.                 steps that could be run at night.
  564.  
  565.                 FIRST NIGHT   Starting Page = 1 and Ending Page = 5,000
  566.  
  567.                 SECOND NIGHT  Starting Page = 5,001 and Ending Page = 10,000
  568.             ----------------------------------------------------------------
  569.  
  570.             Preallocate Pages - This is the number of pages that will be
  571.             preallocated for the recovered records. If the file exists, this
  572.             option does not affect the file. The default setting is the
  573.             number of pages in the original file. Preallocating the pages
  574.             speeds the recovery process.
  575.  
  576.         FILE OPTIONS
  577.  
  578.             This is where you can select the file for the recovered records.
  579.  
  580.         RECOVERY OPTIONS
  581.  
  582.             Normally you will not need to change these settings.
  583.  
  584.             Get Direct Key - This is the key value used to perform the
  585.             Get Direct operation to recover the records. The default setting
  586.             is -1. Some versions of Btrieve do not support using -1 as the
  587.             key for Get Direct operations. Btr Help! will determine if your
  588.             version of Btrieve supports -1 as the key. If it does not, it
  589.             will automatically switch to using 0 as the key. If Btrieve
  590.             does not support -1 as the key, you may not be able to recover
  591.             as many of the records.
  592.  
  593.             Eliminate Blank Records - When this option is set to 'YES',
  594.             Btr Help! will not add records that are filled with all binary
  595.             0s it recovers from the damaged file. If this option is set to
  596.             'NO', blank records will be added if they are found. The default
  597.             setting for this option is 'YES'.
  598.  
  599. LISTS
  600.  
  601.     This menu option lets you view lists of error codes, key types, and
  602.     file operations.
  603.  
  604.     ERROR CODES
  605.  
  606.         This is a list of all the Btrieve error codes and their
  607.         corresponding numbers. A nonzero status does not always mean
  608.         that an error occurred. If you get an END OF FILE error, it may
  609.         mean you may have just retrieved the last record for a key path.
  610.         If you move the highlight bar over an error code and press [ENTER]
  611.         or select one with the mouse, information about that error code
  612.         will be displayed. I have tried to include hints for why certain
  613.         errors occur when I can.
  614.  
  615.     OPERATIONS
  616.  
  617.         This is a list of all the Btrieve file Operations and their
  618.         corresponding numbers. If you move the highlight bar over a file
  619.         operation code and press [ENTER] or select one with the mouse,
  620.         information describing that file operation code will be displayed.
  621.  
  622.     KEY TYPES
  623.  
  624.         This is a list of btrieve key types and their corresponding numbers.
  625.         If you move the highlight bar over a key type and press [ENTER] or
  626.         select one with the mouse, information describing that key type will
  627.         be displayed.
  628.  
  629. COMMAND LINE ARGUMENTS
  630.  
  631.     All command line arguments are optional.
  632.  
  633.     BTRHELP FILESPEC -SWITCHES KEYS @FILE -O<OWNER>
  634.  
  635.         FILESPEC       File Specification
  636.         SWITCHES       Switches -bhmstpux
  637.         KEYS           Auto Keys
  638.         FILE           Auto Keys File
  639.         OWNER          File Owner
  640.  
  641.     FILE SPECIFICATION
  642.  
  643.         The file specification determines which files are displayed in the
  644.         browse or which file BTR HELP! performs its functions on. If the
  645.         file specification is not given then the default is '*.*' which
  646.         selects all file names.
  647.  
  648.     SWITCHES
  649.  
  650.         -b             Uses BIOS for video writes. If your computer has
  651.                        trouble displaying some of the windows on your
  652.                        screen, use this switch.  This assists with
  653.                        incompatibility in the display.
  654.  
  655.         -e             Do not use expanded or extended memory for VROOM
  656.                        overlays.
  657.  
  658.         -h             Displays files in 43/50 line mode.
  659.  
  660.         -m             Disables color. Runs program in monochrome mode.
  661.  
  662.         -p             Automatically types keys when the program begins.
  663.                        See: Auto Keys
  664.  
  665.         -s             Disables clearing of the screen. Does not display
  666.                        the solid background behind the program window.
  667.  
  668.         -t             Do not use transaction processing when deleting or
  669.                        editing records.
  670.  
  671.         -u             Unload Btrieve when you quit the program.
  672.  
  673.         -x             Do not allow ESC to be pressed to abort File
  674.                        Integrity or File Rebuilder.
  675.  
  676.     AUTO KEYS
  677.  
  678.         If the -p switch is selected on the command line, the next group of
  679.         characters is typed automatically when the program begins. The
  680.         symbol '!' acts as the enter key and '#' is the ESC key.
  681.  
  682.         -------------------------------------------------------------------
  683.         Example
  684.  
  685.             BTRHELP DATABASE.DBF -xp RR!###
  686.  
  687.             In this example the 'R' key is pressed to rebuild the file
  688.             DATABASE.DBF. after the file is rebuilt the ESC keys cause the
  689.             program to end.
  690.         -------------------------------------------------------------------
  691.  
  692.         If the group of characters to be entered contains a space character,
  693.         enclose the characters in quotes (").
  694.  
  695.     AUTO KEYS FILE
  696.  
  697.         The characters in this file are typed when the program begins. The
  698.         characters typed are treated just like auto keys.
  699.  
  700.     FILE OWNER
  701.  
  702.         Specifies the owner name for the files used.
  703.  
  704.         -------------------------------------------------------------------
  705.         Example
  706.  
  707.             BTRHELP -oDEPT1
  708.         -------------------------------------------------------------------
  709.  
  710.     LIST OF FILES
  711.  
  712.         BTRHELP.EXE     Btrieve File Maintenance Program.
  713.         BTRHELP.HLP     Help file for BTRHELP.EXE
  714.         BSTOP.BAT       Batch file that uses BTRHELP.EXE to unload btrieve.
  715.         BREBUILD.BAT    Batch file that uses BTRHELP.EXE to rebuild a
  716.                         btrieve file.
  717.         BRESET.BAT      Batch file that uses BTRHELP.EXE to reset btrieve.
  718.         BEDIT.BAT       Batch file that loads BTRHELP.EXE to edit a
  719.                         btrieve file.
  720.         BEMPTY.BAT      Batch file that loads BTRHELP.EXE to empty a
  721.                         btrieve file.
  722.         BTR.BAT         Batch file that loads BTRIEVE.EXE.
  723.         SITELICE.DOC    Site and distribution license information.
  724.         REGISTER.BAT    Batch file that displays the registration form
  725.                         screen. This is on the shareware version only.
  726.         REGISTER.DOC    Registration information and Registration form.
  727.         NWSPAPER.BTR    Sample Btrieve file to try the features of BTR HELP!
  728.         VENDOR.DOC      List of disk vendor instructions.
  729.         README.DOC      Installation Instructions
  730.         BTRHELP.DOC     BTR HELP! Documentation
  731.  
  732. CONTEXT-SENSITIVE HELP
  733.  
  734.     Pressing F1 at any time displays a help screen that relates to the
  735.     current context of the program. Use the PgUp/PgDn keys to display
  736.     the different pages of help text on the screen. Use the arrow keys to
  737.     move between cross-referenced items on the help screen and press
  738.     [ENTER] to select another help item.
  739.  
  740. NOTES
  741.     All software or service names mentioned are trademarks, servicemarks,
  742.     or registered trademarks of their respective holders.
  743.  
  744. TECHNICAL SUPPORT
  745.     There are several ways to contact the author:
  746.  
  747.         1.  Send EMAIL on CompuServe to David Smith  #71311,2334
  748.         2.  Send a FAX to (202) 675-4529
  749.         3.  Leave a message at the Programmers Corner BBS for
  750.             David Smith #1082, BBS# (301) 596-1180
  751.         4.  Leave a voice mail message at (202) 675-4528 for David Smith.
  752.         5.  By mail to:
  753.                  David Smith
  754.                  Informative Technologies Corporation
  755.                  1718 M Street NW, Suite 292
  756.                  Washington, DC 20036
  757.  
  758.     The Association of Shareware Professionals (ASP) wants to make sure
  759.     that the shareware principle works for you. If you are unable to
  760.     resolve a shareware-related problem with an ASP member by contacting
  761.     the member directly, ASP may be able to help. The ASP Ombudsman can
  762.     help you resolve a dispute or problem with an ASP member, but does
  763.     not provide technical support for members' products. Please write
  764.     to the ASP Ombudsman at 545 Grover Road, Muskegon, MI 49442 or send
  765.     a Compuserve message via email to ASP Ombudsman 70007,3536.
  766.  
  767. PROGRAM KEYS
  768.  
  769.     CURSOR MOVEMENT
  770.  
  771.         Arrow Keys           Cursor Movement
  772.         Ctrl-Left Arrow      Word Left
  773.         Ctrl-Right Arrow     Word Right
  774.         Home                 Beginning of Field
  775.         End                  End of Line/Field
  776.         Ctrl-Home            Beginning of First Field
  777.         Ctrl-End             End of Last Field
  778.         Tab                  Next field
  779.         Shift-Tab            Previous field
  780.  
  781.     INSERTING AND DELETING
  782.  
  783.         Ins                  Toggle Insert Mode
  784.         Del                  Delete Character at Cursor
  785.         Backspace            Delete Character Left
  786.         Ctrl-Backspace       Delete Word Left
  787.         Ctrl-T               Delete Word Right
  788.         Ctrl-U               Delete to End of Field
  789.         Ctrl-Y               Delete to Last Field
  790.  
  791.     OTHER EDITING KEYS
  792.  
  793.         Enter                Process Current Field
  794.         Ctrl-Enter or F10    Process All Fields
  795.         Ctrl-R               Restore Field
  796.         ESC                  Abort Data Entry
  797.  
  798.     SPECIAL KEYS
  799.  
  800.         F1                   BTR HELP! Help
  801.         Alt+S                Shell to DOS.
  802.         Alt+D                Debug Window.
  803.         Alt+X or ESC         Quit BTR HELP!
  804.         Alt+F1               Toggle BIOS Screen Writes
  805.  
  806.     BROWSE KEYS
  807.  
  808.         Ctrl+Home            Goes to the first record.
  809.         Ctrl+End             Goes to the last record.
  810.         Esc                  Ends the browse.
  811.         Home                 Puts the highlight bar on the first
  812.                              record on the screen.
  813.         End                  Puts the highlight bar on the last
  814.                              record on the screen.
  815.         Ctrl+Right Arrow     Pages forward through a record a screen
  816.                              at a time.
  817.         Ctrl+Left Arrow      Pages backward through a record a screen
  818.                              at a time.
  819.         Up Arrow             Scroll up one record.
  820.         Down Arrow           Scroll down one record.
  821.  
  822.  
  823.     BTR 'C' LIBRARY
  824.     ---------------
  825.  
  826.     The BTR 'C' Library is available with the registered version of
  827.     Btr Help!. All the calls to the BTR 'C' LIBRARY reference btrieve
  828.     files by a handle (integer). This handle is returned when the file
  829.     is opened with the iBtrOpen function. The function BtrInitialize
  830.     should be called at the beginning of your program and iBtrCloseAll
  831.     should be called at the end of your program.
  832.  
  833.     #include <stdio.h>
  834.     #include <btrieve.h>
  835.     void main( void )
  836.         {
  837.         int iNews;
  838.  
  839.         BtrInitialize();
  840.         iNews = iBtrOpen("NWSPAPER.BTR", NULL, B_OPEN);
  841.         iBtrCall( iNews, B_GET_LOWEST, 1);
  842.         /* Application Code goes here.. */
  843.         iBtrClose( iNews );
  844.         iBtrCloseAll();    /* Close all Files still open */
  845.         }
  846.  
  847.    char *BtrErrorCode(int iBtrError)
  848.    ---------------------------------
  849.  
  850.    Returns the string for a btrieve error code.
  851.  
  852.       INPUTS
  853.    iBtrError - Error code number
  854.  
  855.       RETURNS
  856.    String for a btrieve error code.
  857.  
  858.       EXAMPLE
  859.    printf("Btrieve Error 10=%s\n", BtrErrorCode( 10 ));
  860.  
  861.  
  862.    char *BtrOperationCode(int iBtrOper)
  863.    ------------------------------------
  864.  
  865.    Returns the string for a btrieve Operation code.
  866.  
  867.       INPUTS
  868.    iBtrOper - Btrieve Function code
  869.  
  870.       RETURNS
  871.    String for a btrieve operation code.
  872.  
  873.       EXAMPLE
  874.    printf("Operation 3 is %s\n",BtrOperationCode( 3 ));
  875.  
  876.  
  877.    int BtrOpen(char *sFile, void *acRecord, int iOpenType)
  878.    -------------------------------------------------------
  879.  
  880.    Opens a btrieve file. Does a statistics function call on
  881.    the file. Stores the record size and key information.
  882.    Returns a handle (integer) to refer to the Btrieve file.
  883.  
  884.       INPUTS
  885.    sFile........Btrieve file path and name
  886.    acRecord.....Pointer to btrieve record or NULL if you
  887.                 want a record to be automatically
  888.                 allocated for you.
  889.    iOpenType....Type of open for the btrieve file.
  890.  
  891.        B_OPEN             Regular btrieve open
  892.        B_OPEN_ACCELERATED Open Accelerated
  893.        B_OPEN_READ_ONLY   Open Read Only
  894.        B_OPEN_VERIFY      Open Verify for local DOS disks
  895.        B_OPEN_EXCLUSIVE   Open Exclusive access to file
  896.  
  897.       RETURNS
  898.    Btrieve file handle or 0 if an error occurs.
  899.  
  900.       EXAMPLE
  901.    iBtr=BtrOpen("MAIL.BTR", &rMail, B_OPEN);
  902.  
  903.  
  904.    int BtrClose(int iBtrHandle)
  905.    ----------------------------
  906.  
  907.    Closes a the file and Deallocates data space used by it.
  908.  
  909.       INPUTS
  910.    iBtrHandle....File handle (integer) that refers to the
  911.                  file.
  912.  
  913.       RETURNS
  914.    The Btrieve result status code of the close.
  915.  
  916.       EXAMPLE
  917.    BtrClose(iBtr);
  918.  
  919.  
  920.    void BtrShowError( int iBtrHandle )
  921.    -----------------------------------
  922.  
  923.    Displays a btrieve error on the screen. You will
  924.    probably want to modify this routine for your particular
  925.    user interface.
  926.  
  927.       INPUTS
  928.    iBtrHandle...Btrieve file handle to display last
  929.                 operation result.
  930.       RETURNS
  931.    Nothing
  932.  
  933.       EXAMPLE
  934.    BtrShowError( iBtr );
  935.  
  936.  
  937.    int BtrCreate(char *sFile, FILE_SPEC *specs, int iKey)
  938.    ------------------------------------------------------
  939.  
  940.    Creates a btrieve file.
  941.  
  942.       INPUTS
  943.    sFile........The file name supplied.
  944.    specs........The Btrieve specs to create the file.
  945.    iKey.........Create Status Key.
  946.  
  947.         CHECK_EXISTS    -  Check if file exists on create.
  948.         NO_CHECK_EXISTS -  Don't check if file exists.
  949.  
  950.       RETURNS
  951.    The btrieve result status code of the create.
  952.  
  953.       EXAMPLE
  954.    BtrCreate("TEMP.BTR",&FileSpecs, 0);
  955.  
  956.  
  957.    int BtrCall(int iBtr, int iFuncCode, int iKeyNumber)
  958.    ----------------------------------------------------
  959.  
  960.    Executes a function call on a file specified by iBtr.
  961.  
  962.       INPUTS
  963.    iBtr.........Btrieve file handle
  964.    iFuncCode....Btrieve function code to execute
  965.    iKeyNumber...Key path to use
  966.  
  967.       RETURNS
  968.    Btrieve result status of the function.
  969.  
  970.       EXAMPLE
  971.    BtrCall(iBtr, B_GET_NEXT, 0);
  972.  
  973.  
  974.    int BtrFillKey(int iBtrHandle, void *sKeyField)
  975.    -----------------------------------------------
  976.  
  977.    Fills a btrieve key field from a string.
  978.  
  979.       INPUTS
  980.    iBtrHandle...Handle of btrieve file
  981.    sKeyField....String to load into the key field
  982.  
  983.       RETURNS
  984.    FILE_NOT_OPEN if the handle is invalid, else it
  985.    returns 0.
  986.  
  987.       EXAMPLE
  988.    BtrFillKey(iBtr, "NEW YORK");
  989.  
  990.  
  991.    int BtrFillKeyN(int iBtr, void *sKeyField, int iLength)
  992.    -------------------------------------------------------
  993.  
  994.    Fills the key field from an array of length iLength.
  995.  
  996.       INPUTS
  997.    iBtr........Handle of btrieve file
  998.    sKeyField...Address of bytes to load into the key field.
  999.    iLength.....Number of bytes to load
  1000.  
  1001.       RETURNS
  1002.    FILE_NOT_OPEN if the handle is invalid, else it returns 0
  1003.  
  1004.       EXAMPLE
  1005.    BtrFillKeyN(iBtr, rKeyStruct, sizeof(rKeyStruct);
  1006.  
  1007.  
  1008.    int BtrSetRecordLength(int iBtr, int iRecordLength)
  1009.    ---------------------------------------------------
  1010.  
  1011.    Sets the record length of a btrieve record.
  1012.  
  1013.       INPUTS
  1014.    iBtr.............Handle of btrieve file
  1015.    iRecordLength....Size of the btrieve record.
  1016.  
  1017.       RETURNS
  1018.    FILE_NOT_OPEN if the handle is invalid, else
  1019.    it returns 0.
  1020.  
  1021.       EXAMPLE
  1022.    BtrSetRecordLength(iBtr, sizeof(rMail));
  1023.  
  1024.  
  1025.    int iBtrGetRecordLength(int iBtrHandle)
  1026.    ---------------------------------------
  1027.  
  1028.    Returns the record length of the last record read.
  1029.  
  1030.       INPUTS
  1031.    iBtrHandle...Handle of the btrieve file.
  1032.  
  1033.       RETURNS
  1034.    0 if the handle is invalid, else it returns the record
  1035.    length.
  1036.  
  1037.       EXAMPLE
  1038.    iLength = iBtrGetRecordLength( iBtr );
  1039.  
  1040.  
  1041.    void BtrInitialize(void)
  1042.    ------------------------
  1043.  
  1044.    Initializes btrieve and the data structures.
  1045.  
  1046.       INPUTS
  1047.    None
  1048.  
  1049.       RETURNS
  1050.    None
  1051.  
  1052.       EXAMPLE
  1053.    BtrInitialize();
  1054.  
  1055.  
  1056.    long lBtrGetPosition(int iBtrHandle)
  1057.    ------------------------------------
  1058.  
  1059.    Returns a long integer indicating the position of
  1060.    the current record.
  1061.  
  1062.       INPUTS
  1063.    iBtrHandle...Handle of the btrieve file.
  1064.  
  1065.       RETURNS
  1066.    The position of the current btrieve record.
  1067.  
  1068.       EXAMPLE
  1069.    lPosition = lBtrGetPosition( iBtr );
  1070.  
  1071.  
  1072.    int iBtrSetPosition(int iBtr, long lPosition, int iKey)
  1073.    -------------------------------------------------------
  1074.  
  1075.    Sets the position of the current record using a long int.
  1076.  
  1077.       INPUTS
  1078.    iBtr..........Handle of the btrieve file.
  1079.    lPosition.....Position to set in the btrieve file.
  1080.    iKey..........Key path to set the current positioning.
  1081.  
  1082.       RETURNS
  1083.    The btrieve result status for the B_GET_DIRECT call.
  1084.  
  1085.       EXAMPLE
  1086.    iBtrSetPosition(iBtr, lPosition, 0);
  1087.  
  1088.  
  1089.    int BtrCloseAll(void)
  1090.    ---------------------
  1091.  
  1092.    Closes all btrieve files that may be open.
  1093.  
  1094.       INPUTS
  1095.    None
  1096.  
  1097.       RETURNS
  1098.    0
  1099.  
  1100.       EXAMPLE
  1101.    int BtrCloseAll();
  1102.  
  1103.  
  1104.    int BtrKeyInit(int iBtrHandle)
  1105.    ------------------------------
  1106.  
  1107.    Fills a btrieve key field with nulls.
  1108.  
  1109.       INPUTS
  1110.    iBtrHandle........Handle of the btrieve file.
  1111.  
  1112.       RETURNS
  1113.    0 or FILE_NOT_OPEN if the handle is invalid.
  1114.  
  1115.       EXAMPLE
  1116.    BtrKeyInit( iBtr );
  1117.  
  1118.  
  1119.    int BtrKeyMax(int iBtrHandle)
  1120.    -----------------------------
  1121.  
  1122.    Fills a btrieve key field with 0xFF.
  1123.  
  1124.       INPUTS
  1125.    iBtrHandle....Handle of the btrieve file.
  1126.  
  1127.       RETURNS
  1128.    0 or FILE_NOT_OPEN if the handle is invalid.
  1129.  
  1130.       EXAMPLE
  1131.    BtrKeyMax( iBtr );
  1132.  
  1133.  
  1134.    char *BtrDataRecord(int iBtrHandle)
  1135.    -----------------------------------
  1136.  
  1137.    Returns a pointer to the btrieve data record given the
  1138.    file handle.
  1139.  
  1140.       INPUTS
  1141.    iBtrHandle...Handle of the btrieve file.
  1142.  
  1143.       RETURNS
  1144.    Pointer to the btrieve data record.
  1145.  
  1146.       EXAMPLE
  1147.    prMail = BtrDataRecord( iBtr );
  1148.  
  1149.  
  1150.    long BtrNumberOfRecords( iBtr )
  1151.    -------------------------------
  1152.  
  1153.    Returns a long integer containing the number of records
  1154.    in a file when the file was opened. Does not reflect
  1155.    any records added or deleted since the file was open.
  1156.  
  1157.       INPUTS
  1158.    iBtrHandle...Handle of the btrieve file.
  1159.  
  1160.       RETURNS
  1161.    The number of records in a btrieve file.
  1162.  
  1163.       EXAMPLE
  1164.    lRecords = BtrNumberOfRecords( iBtr );
  1165.  
  1166.  
  1167.    void *BtrSpecRecord(int iBtrHandle)
  1168.    -----------------------------------
  1169.  
  1170.    Returns a pointer to the btrieve file specifications
  1171.    for a btrieve file.
  1172.  
  1173.       INPUTS
  1174.    iBtrHandle....Handle of the btrieve file.
  1175.  
  1176.       RETURNS
  1177.    Pointer to the btrieve file specifications for a file.
  1178.  
  1179.       EXAMPLE
  1180.    Specs = BtrSpecRecord( iBtr );
  1181.