home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-385-Vol-1of3.iso / t / tutil40.zip / TUTILITY.DOC < prev    next >
Text File  |  1992-12-15  |  24KB  |  585 lines
  1.                            TUTILITY - Version 4.0
  2.       Copyright, 1985-1992 - Borland International, ALL RIGHTS RESERVED
  3.       -----------------------------------------------------------------
  4.  
  5.  
  6. TABLE OF CONTENTS
  7. -----------------
  8.  
  9. 1.  Introduction
  10. 2.  TUTILITY Essentials
  11. 3.  Compatibility
  12. 4.  Loading TUTILITY
  13. 5.  Main Menu commands
  14. 6.  Command-line options
  15. 7.  Using TUTILITY with SQL Replicas
  16.  
  17. 1. INTRODUCTION
  18. ---------------
  19.  
  20. TUTILITY checks a Paradox table for damage and rebuilds it if
  21. necessary. Paradox tables can be damaged by power failures, hardware
  22. failures, bad network cards or connections, removing a floppy disk
  23. that Paradox is accessing, or rebooting the system while Paradox is
  24. active in memory. You should always make regular backups of your
  25. important data.
  26.  
  27. Paradox tables consist of two sections, the header and the data blocks.
  28. The header contains information about the number of fields, the
  29. primary key, passwords, write protection, sort order, and the version
  30. of Paradox that created the table. Indexes and memos are stored in
  31. separate files, which belong to the table as part of its "family."
  32. (For more information on the Paradox family, see the Paradox "User's
  33. Guide.")
  34.  
  35. If the table header is intact, but there is damage to the data blocks,
  36. TUTILITY rebuilds the table automatically. If the header is damaged,
  37. however, you must provide additional information about the header so
  38. TUTILITY can reconstruct the table.
  39.  
  40.  
  41. 2. TUTILITY ESSENTIALS
  42. ----------------------
  43.  
  44. The following information is essential to your understanding of
  45. TUTILITY. Even if you are familiar with a previous version of
  46. TUTILITY, you should read this section for important information
  47. on version 4.0.
  48.  
  49. Limitations of the Verify Option
  50. --------------------------------
  51. When TUTILITY verifies a table, it does not verify the primary index.
  52. If a table exhibits unusual behavior in Paradox and TUTILITY reports
  53. no problems, try to rebuild the primary index in Paradox or in
  54. TUTILITY.
  55.  
  56. Enforcing Validity Checks on Rebuilt Tables and Keys
  57. ----------------------------------------------------
  58. When TUTILITY rebuilds a primary key, it doesn't preserve existing
  59. validity checks on the table. Restructure the table in Paradox to
  60. force Paradox to recognize the .VAL file and enforce validity checks
  61. on the table.
  62.  
  63. Rebuilding a Table vs. Restructuring a Table
  64. --------------------------------------------
  65. When you rebuild a table with the Manual option, you must supply
  66. information about the damaged table's original structure. DO NOT
  67. attempt to modify the original structure of the damaged table in
  68. TUTILITY. Rebuild the table as it was originally then use
  69. Modify|Restructure in Paradox if you want to alter the table's
  70. structure.
  71.  
  72. How TUTILITY Creates Backup Tables
  73. ----------------------------------
  74. When you rebuild a table, TUTILITY prompts you for a table name of up
  75. to seven characters to use for a backup table. This ensures that if
  76. something occurs during the rebuild (for example, a power failure),
  77. the original table will still exist.
  78.  
  79. For example, if you want to rebuild a table ORIGINAL.DB, you can
  80. rename the table as BACKUP1.DB. If TUTILITY is unable to rebuild the
  81. table correctly, you can use the backup table, BACKUP1.DB, to try
  82. again.
  83.  
  84. When TUTILITY creates a copy of the original table, it also
  85. creates a copy of all of the table's family members.
  86.  
  87. Restoring Image Settings and Table Views After a Rebuild
  88. --------------------------------------------------------
  89. When TUTILITY rebuilds a table, it doesn't preserve existing Image
  90. Settings (.SET files in Paradox for DOS) or Table Views (.TV files in
  91. Paradox for Windows). TUTILITY copies these files to the same name as
  92. the backup table (with the appropriate extension) prior to rebuilding
  93. the table. If you want to restore Image Settings or Table Views on a
  94. table, you must use Tools|Copy|JustFamily in Paradox (or the DOS COPY
  95. command) to copy the files to the same directory and name as the
  96. table. Then you must restructure the table in Paradox to force Paradox
  97. to recognize the .SET or .TV file.
  98.  
  99. Backward Compatibility Note
  100. ---------------------------
  101. Do not use this version of TUTILITY with Paradox 2.0 tables. If you have
  102. tables created with Paradox 2.0, use the previous version of TUTILITY or
  103. restructure your tables in Paradox 4.0.
  104.  
  105. Rebuilding Large Tables and Tables with Large Memos
  106. ---------------------------------------------------
  107. TUTILITY can rebuild large tables with large memo fields. This process
  108. takes a long time, however, and it may appear that TUTILITY is frozen
  109. during the rebuild. For very large tables or tables with very large
  110. memos, you should allow a few hours for the rebuild.
  111.  
  112. Disk Space Considerations for Rebuild Operations
  113. ------------------------------------------------
  114. When TUTILITY rebuilds a table it creates a backup copy of the table
  115. and its family. This means that at the start of a rebuild, the disk
  116. space used by these files doubles. In most cases, the rebuilt table
  117. will increase in size.  This size increase can be as large as the
  118. table itself. Therefore, you should allow for at least two times the
  119. amount of disk space required by the original table (and its family)
  120. for a rebuild.
  121.  
  122. You can reclaim some of this disk space after the table is rebuilt by
  123. deleting the backup table and its family. You can also restructure the
  124. table in Paradox to reclaim additional space. See the note following
  125. the section on Rebuild for more information.
  126.  
  127. Paradox 4.0
  128. -----------
  129. When you shell to DOS from Paradox (using [Ctrl][O] DOS or [Alt][O]
  130. DOSBig) or your application, Paradox may be tracking a table
  131. internally, even if it is not visible on the workspace. Rebuilding
  132. this table can result in further damage. If you are using Paradox
  133. interactively, you should exit Paradox completely before loading
  134. TUTILITY.
  135.  
  136. If you are a PAL developer, you can use a PAL script to run TUTILITY.
  137. See the discussion on "Running TUTILITY from a PAL script" in section
  138. 6 of this document.
  139.  
  140. Microsoft Windows
  141. -----------------
  142. To run TUTILITY from Windows, enable local table
  143. sharing from the TUTILITY Setup dialog box and ensure that DOS
  144. file sharing is enabled. To enable DOS file sharing, use
  145. SHARE.EXE, which shipped with DOS. These steps ensure that
  146. Paradox files are correctly shared and that the proper locking
  147. protocol is followed. To run TUTILITY at the same time as Paradox for
  148. Windows, you must enable local share in Paradox for Windows, as well.
  149.  
  150.  
  151. 3. COMPATIBILITY
  152. ----------------
  153.  
  154. TUTILITY refers to tables as having Paradox 3.5 or Paradox 4.0
  155. formats only. TUTILITY works with Paradox tables created by the
  156. following applications:
  157.  
  158. Application                               Table formats
  159. -------------------------------------------------------------
  160. Paradox SE, Paradox 3.0 and 3.5            3.5
  161. Paradox 4.0                                3.5/4.0
  162. Paradox for Windows                        4.0
  163. ObjectVision 1.0 and 2.0                   3.5
  164. ObjectVision 2.1                           3.5/4.0
  165. Quattro Pro 3.0                            3.5
  166. Quattro Pro 4.0                            4.0
  167. Quattro Pro for Windows                    4.0
  168. Sidekick 2.0                               3.5
  169. Paradox Engine 1.0 and 2.0                 3.5
  170. Paradox Engine 3.0                         3.5/4.0
  171. -------------------------------------------------------------
  172.  
  173. TUTILITY can rebuild tables with memo fields and composite
  174. secondary indexes or keys (available in Paradox 4.0 and
  175. Paradox for Windows).
  176.  
  177. This version of TUTILITY doesn't work with Paradox 2.0 tables. You
  178. can use the previous version of TUTILITY with Paradox 2.0 tables or
  179. you can update the format of your tables by restructuring them in
  180. Paradox 4.0.
  181.  
  182.  
  183. 4. LOADING TUTILITY
  184. -------------------
  185.  
  186. To load TUTILITY, type TUTILITY at the DOS prompt, then press
  187. Enter. (Optional command-line switches and arguments are described
  188. later.) A menu of choices appears:
  189.  
  190. ≡  Table  Directory  Setup  Exit
  191.  
  192. Choose any one of these commands with the mouse, or choose a command
  193. with the keyboard by using the Right and Left arrow keys to move the
  194. highlight bar, then press Enter. Alternatively, type the highlighted
  195. letter for each menu command. Press [Alt][Spacebar] to access the System
  196. menu (≡).
  197.  
  198. Press [F1] for help anywhere in the program.
  199.  
  200. If a menu is not highlighted, press [F10] to activate it.
  201.  
  202.  
  203. 5. MAIN MENU COMMANDS
  204. ---------------------
  205.  
  206. System menu ≡
  207. -------------
  208. This menu contains one command, About, which displays copyright
  209. and version information for TUTILITY.
  210.  
  211. Table
  212. -----
  213. When you choose Table, the Select Table dialog box appears,
  214. which allows you to select a Paradox table to verify or
  215. rebuild.
  216.  
  217. In a network or shared environment, TUTILITY places a full lock
  218. on the selected table for verification or rebuilding. If someone
  219. else is accessing the table, you will not be able to load the
  220. table into TUTILITY.
  221.  
  222. When you select a table, TUTILITY performs initial tests to ensure
  223. that it can read the table header. If TUTILITY is unable to read
  224. the table header, TUTILITY asks if you want to perform a manual
  225. rebuild (described later).
  226.  
  227. If the header passes the initial tests, the Table Info dialog box
  228. appears. If you press [Esc] or click Cancel, you activate a menu
  229. with the FamilyObjects menu and the Return command.
  230.  
  231. Choose Return to go back to the main menu.
  232.  
  233. The FamilyObjects menu contains three commands that rebuild
  234. different parts of the table automatically. The commands are
  235. Data, PrimaryKey, and SecondaryKey.
  236.  
  237. 1)  Data: If you choose Data from the FamilyObjects menu, the Table
  238.     Info dialog box appears. From the Table Info dialog box you can
  239.     either Verify, or Rebuild automatically or in Manual mode.
  240.  
  241.     a. Verify - Choose Verify to check the table and determine if
  242.        the table descriptor is consistent with the data, and if the
  243.        internal links between records are unbroken. If the table
  244.        is damaged, you are given the option to rebuild it.
  245.  
  246.        NOTE: When TUTILITY verifies a table, it does not
  247.        verify the primary index. If a table exhibits unusual
  248.        behavior in Paradox and TUTILITY reports no problems,
  249.        try to rebuild the primary index in Paradox or in
  250.        TUTILITY.
  251.  
  252.     b. Rebuild - Choose Rebuild to automatically reconstruct a
  253.        table whose record links have been severed. If the table has
  254.        not been damaged beyond repair, Rebuild links the records back
  255.        together. Rebuild will prompt you for a table name of up to
  256.        seven characters to use for a backup table.
  257.  
  258.        It is possible that TUTILITY will not be able to recover all
  259.        data. If it cannot, TUTILITY attempts to save records it cannot
  260.        recover to a Problems table. This table will have the same name
  261.        as the backup table, with the letter P appended to the end of
  262.        the table name (Note that backup table names cannot be longer
  263.        than seven characters to allow for this). For example, if you
  264.        want to rebuild a table ORIGINAL.DB and you rename the table as
  265.        BACKUP1.DB, TUTILITY names the Problems table BACKUP1P.DB. If
  266.        there are any problem records, TUTILITY displays the number of
  267.        problem records when it completes the rebuild.
  268.  
  269.        If a table has been damaged beyond recovery, you'll see a
  270.        message saying the rebuild was unsuccessful.
  271.  
  272.        NOTE: When TUTILITY rebuilds a table, it may change the size
  273.        of the table. If the table was loosely packed before the
  274.        rebuild, it may decrease in size. Conversely, if the table
  275.        was tightly packed, as is the case with a recently
  276.        restructured table, the table size may increase.
  277.  
  278.        If TUTILITY increases the size of a table and you want to
  279.        recover the disk space, you can use the Modify|Restructure
  280.        command in Paradox to pack the table. Before you choose to
  281.        restructure the table, you should be aware of the following
  282.        performance disadvantage:
  283.  
  284.        When you INSERT records into a tightly-packed table, Paradox
  285.        must create a new space to accommodate the record. This
  286.        degrades the performance of data entry. This also causes
  287.        newly-added records to reside in non-contiguous blocks,
  288.        thereby degrading the performance of queries.
  289.  
  290.        If disk space is a concern, you may choose to restructure the
  291.        table. This reduces the overall size of the table and closes
  292.        up the space between records.
  293.  
  294.     c. Manual - Choose Manual if TUTILITY is unable to rebuild the
  295.        table automatically. For TUTILITY to successfully rebuild
  296.        the table, you will need to provide additional information.
  297.  
  298.        The first screen you see allows you to reconstruct the table's
  299.        original structure. (This screen is similar to the
  300.        Create/Restructure mode in Paradox.) TUTILITY also allows you to
  301.        borrow the structure of an existing table, which you know to be
  302.        undamaged, or to compare the structure you enter against another
  303.        table on disk.
  304.  
  305.        When you have reconstructed the original table structure, choose
  306.        Do-It! to display a dialog box where you must specify additional
  307.        information:
  308.  
  309.        - the Paradox table format
  310.        - the table's sort order
  311.        - if the table is write-protected
  312.        - if referential integrity should be enforced for this table
  313.        - if the table is password-protected
  314.        - the maximum table size
  315.        - the number of auxiliary passwords
  316.        - the DOS code page in use when the table was created
  317.          (if different than the active DOS code page)
  318.  
  319.        Select OK to proceed with the Manual rebuild. If you indicated
  320.        that the table is password-protected, TUTILITY prompts you
  321.        for the password.
  322.  
  323.        WARNING: If some of the information you specify is incorrect,
  324.        TUTILITY may not rebuild the table correctly. Use the backup
  325.        table created by TUTILITY to try again.
  326.  
  327.        If you specify a password on a table that is not
  328.        password-protected or if you specify the incorrect password
  329.        for the table, TUTILITY will not be able to successfully
  330.        rebuild the table.
  331.  
  332.        When you reconstruct the table, DO NOT modify the original
  333.        structure of the damaged table. If you want to modify the
  334.        table's structure, rebuild the table as it was originally
  335.        then use Modify|Restructure in Paradox to alter the
  336.        structure.
  337.  
  338. 2)  Primary Key:
  339.  
  340.     If Paradox reports that your primary key is out of date or
  341.     corrupt, and the table passes the verification tests, you can
  342.     rebuild just the key information by choosing Primary Key.
  343.     This option rebuilds all primary keys and secondary indexes or
  344.     keys.
  345.  
  346.     NOTE: When TUTILITY verifies a table, it does not verify
  347.     the primary index. If a table exhibits unusual behavior in
  348.     Paradox and TUTILITY reports no problems, try to rebuild
  349.     the primary index in Paradox or in TUTILITY.
  350.  
  351.     When TUTILITY rebuilds a primary key, it doesn't preserve
  352.     existing validity checks on the table. Restructure the table
  353.     in Paradox to force Paradox to recognize the .VAL file and
  354.     enforce validity checks on the table.
  355.  
  356. 3)  Secondary Key:
  357.  
  358.     If Paradox reports that a secondary index or key is out of
  359.     date or corrupt, and the table passes the verification
  360.     tests, you can rebuild just the index or key information by
  361.     choosing Secondary Key. You will be prompted to select
  362.     which index to rebuild; only one index can be rebuilt at a
  363.     time.
  364.  
  365.     If a secondary index header is corrupt, TUTILITY will not be
  366.     able to rebuild the index; you must delete it with DOS,
  367.     then regenerate it with Paradox.
  368.  
  369. Directory
  370. ---------
  371. To verify or rebuild a table that is not in the current working
  372. directory, you can first choose Directory to change your
  373. directory path. You can change your working directory to any
  374. directory on your system.
  375.  
  376. Setup
  377. -----
  378. Setup configures TUTILITY to work in your environment. You can
  379. change the following settings:
  380.  
  381. -  Local share enables table sharing on a local drive. This
  382.    can be useful for multi-tasking operating systems. To use
  383.    this feature, DOS file-sharing must be enabled. Consult your
  384.    Paradox manual or DOS reference guide for more information
  385.    about SHARE. Network sharing enables the use of SHARE only
  386.    for files located on a network. No sharing disables all
  387.    file sharing. The default is Network share.
  388.  
  389. -  US numbers specifies the number format to be used by
  390.    TUTILITY when displaying numbers. The default display is U.S.
  391.    numbers. If U.S. numbers is not selected, TUTILITY uses
  392.    international number formats.
  393.  
  394. -  B&W mode changes the display from color to black
  395.    and white. This can be useful, for example, on portables
  396.    or computers with monochrome monitors that emulate color monitors.
  397.    The default is Color.
  398.  
  399. -  The 4.0-style locks checkbox allows you to indicate that
  400.    TUTILITY should use file locking compatible with Paradox
  401.    4.0. Disable this option when running on networks that use
  402.    3.5-style file locking.
  403.  
  404. -  The PARADOX.NET or PDOXUSRS.NET path type-in box allows you to
  405.    specify the directory where the PARADOX.NET file is located
  406.    for network or multi-tasking systems for Paradox 3.5 tables, and
  407.    where the PDOXUSRS.NET file is located for Paradox 4.0 tables.
  408.    This directory should be the same as that specified in NUPDATE
  409.    (for Paradox for DOS) or ODAPI.CFG (for Paradox for Windows).
  410.    For more information, consult your Paradox manual. The default
  411.    is to use the current directory.
  412.  
  413. Exit
  414. ----
  415. When you are finished, choose Exit to exit TUTILITY.
  416.  
  417.  
  418. 6. COMMAND-LINE OPTIONS
  419. -----------------------
  420.  
  421. TUTILITY supports a number of command-line options:
  422.  
  423. TUTILITY [options]
  424.  
  425. Where [options] are one or more of the following:
  426.  
  427. -help
  428. -rebuild <table> <backup>
  429. -verify <table>
  430. -netpath = <path>
  431. -nettype = <type>
  432. -b&w
  433. -pdox35
  434. -pdox40
  435. -share
  436. -password="<password>"
  437.  
  438. These options are described below.
  439.  
  440. -help
  441. -----
  442. Displays a help screen showing these options.
  443.  
  444. -rebuild
  445. --------
  446. Rebuilds <table> and creates <backup>, which is an exact copy of the
  447. original table and its family members. You must specify names for
  448. <table> and <backup>. TUTILITY returns an error code of 0 if the
  449. table was rebuilt successfully, or 255 if the table header is
  450. corrupt or another problem exists that prevents TUTILITY from
  451. successfully rebuilding this table.
  452.  
  453. You can specify the path to <table> but you must use the same path
  454. for <backup>. If you do not specify a path, TUTILITY assumes that
  455. <table> exists in and <backup> should be created in the current
  456. directory.
  457.  
  458. -verify
  459. -------
  460. Verifies <table>, which must be specified. TUTILITY returns an error
  461. code of 0 if the table is not corrupt, or 255 if the table is
  462. corrupt.
  463.  
  464. -netpath=<path>
  465. -----------------
  466. Specifies the <path> where the PARADOX.NET and PDOXUSRS.NET files
  467. are stored.
  468.  
  469. nettype=<type>
  470. ----------------
  471. Specifies the network type. You must use either LOCALSHARE, NETSHARE,
  472. or NOSHARE as the <type>.
  473.  
  474. - LOCALSHARE     enables file sharing on local and network drives
  475. - NETSHARE       enables file sharing only on files located on a network
  476. - NOSHARE        disables file sharing
  477.  
  478. -b&w
  479. ----
  480. Changes the display from color to black and white.
  481.  
  482. -pdox35
  483. -------
  484. Uses Paradox 3.5-style locking.
  485.  
  486. -pdox40
  487. -------
  488. Uses Paradox 4.0-style locking.
  489.  
  490. -share
  491. ------
  492. Enables Paradox file and record sharing.
  493.  
  494. -password="<password>"
  495. ----------------------
  496. Uses <password> as the password. The -password parameter must
  497. follow the table name in the parameter list.
  498.  
  499. NOTE: Use the password option ONLY if you are certain that
  500. the table is password-protected. If you specify this option on
  501. a table that is not password-protected or if you specify the
  502. incorrect password for the table, TUTILITY will not be able to
  503. successfully rebuild the table.
  504.  
  505. For example, to rebuild the Customer table (which is encrypted with
  506. the password "mags") automatically with Paradox 3.5-style record
  507. locking and create a backup of the original table named Custback, you
  508. would type:
  509.  
  510. TUTILITY -rebuild customer custback -password="mags" -pdox35
  511.  
  512. then press Enter. The .DB table extension is optional for table
  513. names.
  514.  
  515. Running TUTILITY from a PAL script
  516. ----------------------------------
  517. Developers can include table verification and rebuilding in their
  518. applications using these command-line options and the Paradox RUN BIG
  519. command. To interpret DOS error codes, you must use the NOSHELL option.
  520. For example,
  521.  
  522. SAVETABLES
  523. RESET
  524. RUN BIG NOSHELL "TUTILITY -verify Customer"
  525. IF Retval=255 THEN
  526.    DAMAGED_TABLE_ROUTINE()     ; procedure to rebuild
  527. ENDIF
  528.  
  529. Use the SAVETABLES and RESET commands prior to running TUTILITY
  530. from within Paradox to ensure that all internal references
  531. to your tables are written to disk and that the workspace is cleared.
  532.  
  533. A successful rebuild with the -rebuild command line option returns an
  534. error code of 0. Any other error code implies that TUTILITY was
  535. unable to rebuild the original table. This may occur, for example,
  536. if there is insufficient disk space or if a manual rebuild is required.
  537.  
  538.  
  539. 7. USING TUTILITY WITH SQL REPLICAS
  540. -----------------------------------
  541.  
  542. TUTILITY cannot repair or rebuild replicas created
  543. with Paradox SQL Link, but TUTILITY can verify the
  544. table header in SQL replicas.
  545.  
  546. If you select a SQL replica from the Select Table dialog box,
  547. TUTILITY performs initial tests to ensure that it can read the
  548. table header. If TUTILITY is able to read the header, the
  549. Table Info dialog box appears.
  550.  
  551. - If you choose Verify, TUTILITY verifies the Paradox
  552.   header information. If TUTILITY detects any problems, it
  553.   checks the replica's size to ensure that it is not larger
  554.   than 4K and it checks the header for information that
  555.   indicates the presence of records. Since SQL replicas are
  556.   never larger than 4K and contain no records, then it is
  557.   possible that the selected .DB file is not a SQL replica as
  558.   the header reports. If the .DB file is larger than 4K or
  559.   contains records, TUTILITY displays a Table Inconsistent
  560.   dialog box with the message "Table header incorrectly
  561.   reports that this is a SQL replica". You can select OK
  562.   to rebuild the table or Cancel to cancel the rebuild.
  563.  
  564. - If you choose Rebuild, TUTILITY checks the replica's size
  565.   and header for information indicating the presence of
  566.   records before attempting to rebuild the table. If
  567.   TUTILITY determines that the .DB file is a table,
  568.   TUTILITY rebuilds the table. If TUTILITY determines that
  569.   the .DB file is a SQL replica (because it is less than 4K
  570.   in size and appears to contain no records), you receive
  571.   the message "Cannot rebuild SQL replica".
  572.  
  573. - If you choose Manual, TUTILITY treats the replica as a
  574.   corrupt table and will attempt to rebuild the .DB file as
  575.   a table. If the .DB file is a SQL replica, you will need
  576.   to regenerate it with SQL Setup.
  577.  
  578. If a replica is damaged or out of date (the structure
  579. of the remote table has changed since you created the replica),
  580. you can regenerate the replica with SQL Setup.
  581.  
  582.  
  583.                --------- End of TUTILITY.DOC ---------
  584.  
  585.