home *** CD-ROM | disk | FTP | other *** search
/ Current Shareware 1994 January / SHAR194.ISO / catalogs / gui_data.zip / EUTIL.DOC < prev    next >
Text File  |  1992-09-14  |  11KB  |  281 lines
  1.                                =========
  2.                                EUTIL.EXE
  3.                                =========
  4.  
  5. EUTIL is a database maintenance utility for EllTech Development's "E-
  6. Tree Plus" library. It provides the following functions:
  7.  
  8. *   Set or view the values of EtAuto fields.
  9.     
  10. *   "Clone" the file structure and index definitions of an existing E-
  11.     Tree plus database file to a new, empty file.
  12.  
  13. *   "Create" a new E-Tree file using a special "description file."
  14.  
  15. *   Generate a "Description" file for an existing E-Tree file.
  16.  
  17. *   "Drop" (delete) an existing index.
  18.  
  19. *   "Export" data from an E-Tree file to a comma-delimited ASCII file.
  20.  
  21. *   "Import" data from a comma-delimited file into an existing E-Tree
  22.     file.
  23.  
  24. *   Create a new "Index."
  25.  
  26. *   "Rebuild" or pack an existing E-Tree file.
  27.  
  28. *   "Reset" the database header and record lock semaphores.
  29.  
  30. *   Get the "Status" of an existing E-Tree file. This includes a
  31.     summary of the field names, index definitions, and other related
  32.     information.
  33.  
  34.  
  35.                               USING EUTIL
  36.                               ===========
  37.  
  38. EUTIL is a command-line driven utility that may be freely distributed
  39. with the applications you develop using E-Tree Plus. It's syntax is as
  40. follows:
  41.  
  42.           EUTIL -Switch EtreeFile [other options]
  43.  
  44. The first command line argument is always a "switch" that indicates the
  45. desired EUTIL operation. EtreeFile is the name of the E-Tree database
  46. file that will be created or manipulated. The other options vary
  47. depending on the switch used. If EUTIL is executed without an command
  48. line arguments, a summary of available switches and options will be
  49. displayed.
  50.  
  51. During potentially long operations (rebuild, import, export), you can
  52. press the Escape key to terminate the current operation. You'll be
  53. asked to confirm this choice before EUTIL actually terminates.
  54.  
  55. If EUTIL terminates are a result of an error, the DOS "errorlevel" will
  56. be set to a value of one. If termination resulted from the user
  57. pressing Escape, the errorlevel will be set to a value of two.
  58.  
  59. EUTIL's output may be redirected to a DOS file or device by using the
  60. ">" redirection symbol on the DOS command line:
  61.  
  62.           EUTIL [switches and options] > FileOrDevice
  63.  
  64. Redirection is automatically detected within EUTIL and, during such
  65. operation, prompts for user input are bypassed.
  66.  
  67.  
  68.                             EUTIL SERVICES
  69.                             ==============
  70.                                    
  71.  
  72. The following is a list of EUTIL's command line switches and a
  73. description of their use. Only the first three characters of each
  74. switch is significant. That is, "-Clone" can be abbreviated "-Clo",
  75. etc.
  76.  
  77. -AUTOINCREMENT EtreeFile [FldName [NextValue]]
  78.  
  79. This switch is used to view the current auto increment value of a specied
  80. field (or all EtAuto field), or to set a specific EtAuto field to a specific
  81. value. For example:
  82.  
  83.     EUTIL -AUT TEST.ETR
  84.  
  85. Displays the current values of all EtAuto fields.
  86.  
  87.     EUTIL -AUT TEST.ETR FldName
  88.  
  89. Displays the current value of the field named "FldName".
  90.  
  91.     EUTIL -AUT TEST.ETR FldName 1234
  92.  
  93. Sets auto increment value for FldName to 1234. The next new record inserted
  94. into the database will have 1234 assigned to the FldName field (assuming that
  95. field had a value of zero when inserted).
  96.  
  97.  
  98. -CLONE ETreeFile NewFile
  99.  
  100. This service "clones" or copies an existing E-Tree database file's
  101. (ETreeFile) structure to a new, empty file (NewFile).  The structure
  102. copied includes field and index definitions only.  No record data is
  103. copied.  For example:
  104.  
  105.           EUTIL -CLO TEST.ETR NEWFILE.ETR
  106.  
  107. This command creates an empty database file called "NEWFILE.ETR" which
  108. has the same structure as TEST.ETR.
  109.  
  110.  
  111. -CREATE EtreeFile DescFile
  112.  
  113. This service reads a "database description file" (DescFile) and creates
  114. an E-Tree database file based on that description.  The description
  115. file includes the names, types and lengths of fields, and index names.
  116. It can optionally define the file page size, maximum number of indices
  117. the file will contain (MaxKeys), and the amount of disk space that will
  118. be pre-allocated to the file. The following is a sample description
  119. file:
  120.  
  121. ' This is an EUTIL database description file. It is structured as
  122. ' follows:
  123. '
  124. ' Lines beginning with an apostrophe are ignored (good for comments)
  125. ' "#Fields" is a metacommand which must preceed field names.
  126. ' Field name entries are structured as follows:
  127. '
  128. '       FieldName FieldType FieldLength
  129. '
  130. ' Field lengths are needed only for String fields. See page page 33 of
  131. ' the E-Tree documentation under "Named Constants" for a list of valid
  132. ' field types. If wish to include a variable-length field, it must be
  133. ' the -last- field defined.
  134. '
  135. ' #Index is a metacommand that must preceed index definitions. #Fields
  136. ' MUST preceed #Index. #Index entries must be structured as follows:
  137. '
  138. '    IndexName [Unique] [FieldName [FieldName ... etc.]]
  139. '
  140. ' IF "Unique" is omitted, duplicate key values will be allow for the
  141. ' index. If FieldName is omitted, it is assumed that the key will have
  142. ' a single segment which is comprised of the field with the same name
  143. ' as the Index.
  144. '
  145. ' #PageSize allows you to define the file page size: #PageSize 8192.
  146. ' Using a value of 0 (or omitting #PageSize altogether) will direct
  147. ' EUTIL to calculate a page size optimized for performance (yielding
  148. ' larger files). Using a value of -1 directs EUTIL to calculate a page
  149. ' size optimized for file size (smaller files with slightly slower
  150. ' performance).
  151. '
  152. ' #MaxKeys allows you to define the maximum number of indices you'll be
  153. ' using at once. If #PageSize > 0 then the #MaxKeys value is ignored.
  154. '
  155. ' #PreAllocation allows you to "pre-allocate" the specified amount of
  156. ' disk space (in bytes) to the file.
  157. '
  158. ' EUTIL can build a description file for an existing E-Tree database
  159. ' file. See the documentation for the -DEF.
  160.  
  161. ' The following will create an E-Tree file matching the one in
  162. ' EXAMPLE.BAS.
  163.  
  164. #PageSize -1                    'Comments can also be placed out here
  165. #MaxKeys 5                      ' just like in your BASIC program.
  166.  
  167. #Fields
  168. CustNumber  EtAuto   1234       'The "1234" is the optional starting value
  169. FirstName   EtString 20
  170. LastName    EtString 20
  171. Addr        EtString 30
  172. City        EtString 20
  173. State       EtString 2
  174. ZipCode     EtString 10
  175. AreaCode    EtString 3
  176. PhoneNum    EtString 8
  177. AmountDue   EtDouble
  178. Age         EtInteger
  179.  
  180. #Index
  181. CustNumber Unique
  182. FullName LastName FirstName
  183. ZipCode
  184. AmountDue
  185.  
  186. '-----------------------End of Description file-----------------------
  187.  
  188.  
  189. -DESCRIPTION ETreeFile [DescFile]
  190.  
  191. This service creates a description file (DescFile) for an existing E-
  192. Tree Plus database file (ETreeFile). The output description file name
  193. is optional. If omitted, the name ETreeFile.DES will be used.
  194.  
  195.  
  196. -DROP ETreeFile IndexName
  197.  
  198. This service "drops" or "deletes" an index (IndexName) from an E-Tree
  199. database file (ETreeFile).
  200.  
  201.  
  202. -EXPORT ETreeFile OutputFile [FldDescFile]
  203.  
  204. This service exports all data from ETreeFile to OutputFile in standard
  205. comma-delimited ASCII format, one record per line in the OutputFile.
  206. FldDescFile is a standard ASCII text file which contains a list of the
  207. fields that you want to export. This FldDescFile should contain only
  208. one line consisting of a list of field names with each seperated by a
  209. comma. For example:
  210.  
  211.           LastName,FirstName,CustNumber,ZipCode
  212.  
  213. Using the above FldDescFile, the OutputFile will contain only the above
  214. list of fields.
  215.  
  216. If FldDescFile is omitted, all fields comprising each record will be
  217. exported. Also, the first line of OutputFile will contain the list of
  218. field names exported in the same order which the data appears in the
  219. file. This information can be used by the -IMPORT function to determine
  220. the order of the data in OutputFile and the fields into which the data
  221. should be placed.
  222.  
  223.  
  224. -HEADER EtreeFile ["New Database ID String"]
  225.  
  226. Assigns a new database ID to ETreeFile. If the database ID is omitted, the
  227. default ID of "EllTech Development Corp. E-Tree ISAM Version 1.0" will
  228. be assigned. If you change the database ID from the default, you must
  229. call the EtSetID routine in your program before you can open the database
  230. with EtOpen. Failure to do so will result in a Status of -9.
  231.  
  232.  
  233. -IMPORT ETreeFile InputFile [FldDescFile]
  234.  
  235. This service imports data from a comma-delimited ASCII file (InputFile)
  236. into an E-Tree database file (ETreeFile).  FldDescFile is an ASCII text
  237. file structure as described in the -EXPORT service (above). It simply
  238. lists the names of the ETreeFile's fields into which the data will be
  239. inserted. If FldDescFile is omitted, the first line of InputFile must
  240. contain the field name information (in the same format as FldDescFile).
  241.  
  242.  
  243. -INDEX ETreeFile IndexName [Unique] [FldName [FldName...]]
  244.  
  245. This service creates an index (IndexName) in the specified E-Tree
  246. database file (ETreeFile).  The "Unique" keyword can follow the
  247. IndexName to instruct EUTIL that duplicate key values for IndexName are
  248. NOT allowed.  One or more FldNames can also be listed to instruct EUTIL
  249. of the various segments comprising the index.  If no FldNames are
  250. listed, it is assumed that a field with the same name as IndexName will
  251. be the only segment for this index.
  252.  
  253.  
  254. -REBUILD ETreeFile
  255.  
  256. This service is used to "pack" or recover a corrupted E-Tree database
  257. file.  Because of the very efficient method E-Tree uses to track and
  258. reuse "dead" space within a database file, packing is rarely necessary.
  259. However, if your E-Tree file is corrupt, this service will recover most
  260. (if not all) of the record data and indices stored in the file. EUTIL
  261. displays an error message pertaining to any data that could not be
  262. recovered. The output file is called ETreeFile.REB.
  263.  
  264.  
  265. -RESET ETreeFile
  266.  
  267. This service resets the file header and record locking "semaphores"
  268. within ETreeFile.  Use of this service should only be necessary if a
  269. program or network workstation "crashes" with record locks in place,
  270. thus preventing E-Tree's record manager from properly releasing those
  271. locks automatically. This service should only be used when no other
  272. processes are accessing the database file.
  273.  
  274. -STATUS ETreeFile
  275.  
  276. This service displays a summary of ETreeFile's record and index
  277. structure, as well as other information containing in the file's header
  278. (number of active records, etc.).
  279.  
  280.  
  281.