home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / dbase / pdxdoc.zip / PDXDOC.DOC < prev    next >
Text File  |  1993-03-05  |  11KB  |  210 lines
  1.  
  2.  
  3.  
  4.      /////////////////////////////////////////////////////////////////////
  5.               Paradox Documentation Utility - PDXDOC Version 1.0
  6.                               Steve M. England
  7.                             3113 Greenhill Drive
  8.                          Huntsville, Alabama  35810
  9.      /////////////////////////////////////////////////////////////////////
  10.  
  11.  
  12.      This product is the public domain release.  It may be shared and
  13.      passed among friends as freely as desired.  Users of this product
  14.      are encouraged to register with the author to receive the complete
  15.      PDXDOC Utility, which includes enhanced features and reporting
  16.      capability.  These features include the ability to document and
  17.      report on program libraries, enhanced system reports including
  18.      Paradox "family" statistics and more.  Users must have either
  19.      Paradox 4.0 or the Runtime version of Paradox 4.0 to utilize this
  20.      utility.  A DOS executable is in the works and should be released
  21.      sometime in the summer of 1993.
  22.  
  23.      The purpose of developing this product was to have a mechanism of
  24.      tracking table definitions and statistics for a developed system.
  25.      Being a Paradox and 'C' developer, I have often developed multiple
  26.      systems and desired to have a means of documenting the database
  27.      objects used by my developments.  In addition, I desired to have this
  28.      documentation presented in such a form as to easily store in my system
  29.      development notebooks and folders.
  30.  
  31.      The ensuing result is PDXDOC.  This utility will "read" Paradox table
  32.      structures and store them in a master description table when added,
  33.      and allow the user to update, edit and even delete these tables when
  34.      desired.  Tables belonging to multiple development efforts can be
  35.      tracked painlessly by using a system/project keyword.  Reports can
  36.      then be generated for the project table listings and the table
  37.      descriptions themselves.  The structure of the program is quite
  38.      simple to follow.  The following provides a short overview of the
  39.      programs menu function.
  40.  
  41.                      ┌───── PDXDOC - Main Menu ─────┐
  42.                      │ 1.  Catalog Functions        │
  43.                      ├──────────────────────────────┤
  44.                      │ 2.  Report Functions         │
  45.                      ├──────────────────────────────┤
  46.                      │ 3.  Set Working Directory    │
  47.                      ├──────────────────────────────┤
  48.                      │ 4.  Exit                     │
  49.                      └──────────────────────────────┘
  50.  
  51.  
  52.      1.0  CATALOG FUNCTIONS
  53.  
  54.      The software is available for immediate use once run from the 
  55.      Paradox environment.  Upon selecting the first option, the user is
  56.      presented with the choice of adding a table to the catalog, editing
  57.      a table already in the catalog, deleting a table from the catalog,
  58.      or updating an existing table within the catalog.
  59.  
  60.  
  61.  
  62.      1.1   Adding Tables
  63.  
  64.      When this option is selected, PDXDOC presents a dialog box listing
  65.      the possible tables that can be added in the current working directory.
  66.      (Should the user desire to add a table in a different directory, choose
  67.      the 3rd menu item from the main menu to set the working directory to the
  68.      desired location.)  Upon selecting a table, PDXDOC presents a form
  69.      with the table name, project name, table description and table purpose
  70.      fields.
  71.  
  72.      The project name field is an optional field, but it is highly suggested
  73.      that if the user wishes to keep track with tables over a variety of
  74.      projects that he assign the project a general title name.  For example,
  75.      if the project dealt with ABC Company Personnel Database development,
  76.      a suggested name might be ABC Personnel.  Then, each table added that
  77.      belongs to this project would be ordered, or categorized as a part of
  78.      the development.  Then, other projects could also be added, making
  79.      PDXDOC a more verstile utility.
  80.  
  81.      The table description field is intended to allow users to spell out the
  82.      full table name associated with a table.  For example, the Paradox
  83.      table name used by most developers is too small, being only 8 characters
  84.      in length.  Therefore a user could have a table PURREQTR and not always
  85.      easily recognize that its actual name is Purchase Requisition 
  86.      Transactions table.
  87.  
  88.      Finally, the table purpose is for the general description of the tables'
  89.      purpose within the project, describing its function in the overall
  90.      schema.  This field is optional.
  91.  
  92.      Once these items are entered, PDXDOC accesses the information for the
  93.      table and catalogs it automatically.  When the operation is completed,
  94.      the user is returned to the main menu.  The speed with which the system
  95.      operates is highly dependent upon the memory the users system contains.
  96.      For example, systems with the minimum 2-megabytes of memory required
  97.      by Paradox will find the operation to be somewhat slow, while users whose
  98.      systems contain 4-megabytes or more of RAM will be quite pleased with the
  99.      speed with which tables are cataloged.
  100.  
  101.      1.2  Editing Cataloged Tables
  102.  
  103.      Once a table has been cataloged, the user has the option of reviewing
  104.      and editing the table entries as desired.  Upon selection of this option
  105.      PDXDOC provides the user with a list of the currently cataloged tables
  106.      in the system.  Selecting one will bring up a form containing the 
  107.      information collected and stored for that table.
  108.  
  109.      The form is subdivided into two parts.  The upper portion deals with
  110.      the master table descriptions itself, similar to the items seen when
  111.      adding new tables to the system.  The lower portion (accessed by pressing
  112.      the F3 function key) contains the tables' column definitions and formats.
  113.      Notice that an additional column exists here which allows the user to
  114.      provide a more detailed description of each column in a table beyond that
  115.      provided for in the column name itself.  This allows enhanced documenting
  116.      for the tables' columns in future references.  Note that this column
  117.      is optional, and data is not required to be listed here for reporting
  118.      purposes (explained later in the reports section).
  119.  
  120.      Pressing F2 (Do_It!) will return the user to the main menu.
  121.  
  122.  
  123.  
  124.      1.3  Deleting A Cataloged Table
  125.  
  126.      There may be a requirement at some time to delete a table from the 
  127.      catalog completely and remove it from the PDXDOC system.  This is provided
  128.      for in this option.  Upon selection the user is presented with a list
  129.      of the tables currently cataloged within the system.  Selecting one
  130.      removes it from the catalog.
  131.  
  132.      1.4  Updating A Cataloged Table
  133.  
  134.      There may come a time when a table structure is changed during development
  135.      thus leaving its cataloged structure out-of-date.  Normally a user would
  136.      probably think of deleting the table from the catalog and then just
  137.      re-adding it to the system.  Although this would work without problem, it
  138.      would be quite a waste if the user had entered descriptions for each of
  139.      columns found in the table definitions cataloged.  These descriptions
  140.      would then have to be re-entered again.
  141.  
  142.      The update function solves this problem to some extent for the user.
  143.      When selected, the user is given a list of the available tables in his
  144.      current directory.  Once chosen, PDXDOC verifies it has already been
  145.      cataloged.  If not, the user is informed so and the operation is aborted.
  146.      If found, however, then the user is re-presented the initial information
  147.      screen to allow any updates or changes to the table descriptions as may
  148.      be needed.  Pressing <F2> will then allow PDXDOC to update the table into
  149.      the catalog.
  150.  
  151.      The update process first loads all of the column information found within
  152.      the new table.  Then, a comparison is made with the old column titles
  153.      with those found in the new cataloged structure.  When column names match,
  154.      the old descriptions are copied and assigned to the new column
  155.      descriptions.  Thus, any unchanged column names will retain their 
  156.      'extended' descriptions.  Any new columns added to the table will have
  157.      blank extended descriptions; however, the user may edit the catalog and
  158.      add descriptions to these columns at any time.
  159.  
  160.      2.0  Reporting Functions
  161.  
  162.      The PDXDOC system provides two levels of reporting capabilities.  One
  163.      level consists of tables at the system level; the second consists of
  164.      table and column definitions.
  165.  
  166.      2.1  System Reports
  167.  
  168.      System Reports generate information concerning the tables belonging to a
  169.      project.  They do not include the table column definitions and their
  170.      respected formats.  When selected, the user is provided the option to
  171.      generate the report for all projects, or for a specific project.  All
  172.      tables associated with a project that are cataloged and documented are
  173.      then generated to a report listing.
  174.  
  175.  
  176.  
  177.      2.2  Table Reports
  178.  
  179.      Table reports provide information concerning the tables themselves: the
  180.      column descriptions, field types, width and more.  Three options are
  181.      available.  Selecting all tables will generate the report for all
  182.      tables in the system catalog.  Selecting the project option allows
  183.      all tables associated with a specific project to be reported, and
  184.      selecting the single table option allows the report to be generated for
  185.      a single table only.
  186.  
  187.      Each report has two an option for two types of output.  The first type
  188.      provides a report format that does not include the extended descriptions
  189.      available for the user to enter when edit a cataloged table.  The second
  190.      type provides a report that does include these descriptions in the 
  191.      output.
  192.  
  193.      3.0  Conclusion
  194.  
  195.      As stated earlier, PDXDOC is a utility developed by the author to assist
  196.      in tracking the system objects (elements) associated with a development.
  197.      The public domain release of this project has been tested and believed
  198.      to be error free and complete.  Preparations are underway to continue
  199.      enhancing this product, and your suggestions would be welcome.  The 
  200.      shareware version of this product is currently in beta testing, and a
  201.      DOS executable version is planned for release sometime in the summer of
  202.      1993 (thus allowing the functions to be performed without dependence on
  203.      the Paradox software).  Any questions, suggestions, hints and/or
  204.      complaints (surely no complaints...???) should be directed to the address
  205.      provided on the first page of this document.
  206.  
  207.      Please make note that Paradox is a registered trademark of Borland
  208.      International and compliance is made with all rights and priviledges
  209.      thereof.
  210.