home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / mbug / mbug106.arc / DBSRC102.LBR / DBSOURCE.DQC / DBSOURCE.DOC
Text File  |  1979-12-31  |  10KB  |  267 lines
  1.           Documentation for DBSOURCE and DBSRC2
  2.  
  3.              Versions 1.02  3-1-85
  4.  
  5.           Copyright (C) 1985 by Merlin R. Null
  6.  
  7.  
  8.     The DBSRC102 library should contain the following files:
  9.  
  10. DBSOURCE.COM    DBSOURCE, reads encoded dBASE II command files.
  11. DBSOURCE.BAS    The MBASIC Source for the above program.
  12. DBSOURCE.HLP    Help file for DBSOURCE.
  13. DBSOURCE.DOC    This documentation.
  14. DBSRC2.COM    A variant of DBSOURCE
  15. DBSRC2.BAS    The MBASIC Source for the above program.
  16. DBSOURCE.CRC    Various stats for checking these files
  17.  
  18. **********    DBSOURCE.COM is a stand alone COM file that
  19. *  NOTE  *    does not require BRUN.COM to run.  It is
  20. **********    compiled MBASIC for 8080 or Z80 machines.
  21.  
  22.  
  23.                 DBSOURCE
  24.  
  25.      DBSOURCE will take a dBASE II command  file  that  has  been
  26. encoded with ENCODE , Ashton-Tates's DBCODE or  with  Gene Head's
  27. DB-SQZ5 or any one of several other commercial encoding  programs
  28. and generate a runable source file.  DBSOURCE can also  send  the
  29. output to the printer or you may view the output on your console.
  30. It will not decode a dBASE III file.  DBCODE for dBASE III uses a
  31. more complex partial compiler.
  32.  
  33.      This type of file is encoded for one of two reasons.  First,
  34. it protects the program  file  from  being  viewed  or  modified.
  35. Second, the encoded programs run about 30% faster.   I feel  that
  36. the latter reason is far more important.  The level of protection
  37. that this type of encoding offers is only moderate. Programs  run
  38. faster because the files are partially tokenized and all comments
  39. are removed.
  40.  
  41.      Encoded command files are for use with dBASE II version  2.4
  42. or higher.  A decoded file might require some translation  to run
  43. on an earlier version of dBASE II.
  44.  
  45.  
  46.               Installation
  47.  
  48.      To install  DBSOURCE,  just  run  the  program.   It is self
  49. installing.  If the clear screen data file,  CLS.DAT,  is missing
  50. on the disk with DBSOURCE, a new one will be generated.  You will
  51. be asked for the decimal values of your  clear  screen  sequence.
  52. For example, on a KayPro or Osborne CP/M machine just enter:
  53.  
  54. Clear screen character 1? 26
  55. Clear screen character 2? <RETURN>
  56.  
  57.      CLS.DAT will then be written and you  will  go  directly  to
  58. operation of DBSOURCE.   If the title screen  is  preceeded  by a
  59. clear screen, the installation  was  successful.   If  the  title
  60. screen scrolls on, it failed.   If it fails,  exit  the  program,
  61. erase CLS.DAT, and run DBSOURCE again.   If  you  don't  like the
  62. clear screen function, simply enter 10 when asked for your  clear
  63. screen sequence.  For each 10 you enter DBSOURCE will scroll  one
  64. line in place of the clear screen.  My older  program,  CLEARSET,
  65. will still  generate  a  correct  CLS.DAT  for  this  version  of
  66. DBSOURCE.
  67.  
  68.  
  69.            Calling a Directory Listing
  70.  
  71.      To call a directory from the title screen simply  enter  the
  72. drive you wish to list.
  73.  
  74. Filename.CMD or Drive:? A:
  75.  
  76.    This will list the directory of drive A and  give  the  prompt
  77. again.
  78.  
  79. Directory of drive A:
  80. FOO    .CMD    DBSOURCE.BAS    DBSOURCE.COM    BRUN    .COM    A10    .CMD
  81. ENCODE  .BAS    ENCODE  .COM    MBASIC    .COM    D    .COM    SAMPLE    .CMD
  82. BOOKS    .DBF    BOOKS    .FRM    DBASE    .COM    CLS    .DAT    CLEARSET.BAS
  83. CLEARSET.COM    DBASEMSG.TXT    DBASEOVR.COM    B4    .CMD    R2D2    .CMD
  84. DBINDENT.BAS    DBINDENT.COM    ELIZA    .BAS    A10    .SRC    A10    .BAK
  85. CLONE    .CMD    TEST    .CMD    CLONE    .SRC    A10    .OLD    DBSRC2    .BAS
  86. DBSRC2    .COM
  87. Filename.CMD or Drive:?
  88.  
  89.     The ZCPR like drive call of A; will  also work  to  call  the
  90. directory, even if you are not running  ZCPR.   The  Filename.CMD
  91. may be  entered  here or a  <RETURN>  will  redisplay  the  start
  92. screen.
  93.  
  94.  
  95.                 Help File
  96.  
  97.      The help file may be called from DBSOURCE by entering a  "?"
  98. at the title screen.  It contains several  screens  of  condensed
  99. information on how to run DBSOURCE.
  100.  
  101. Filename.CMD or Drive:? ?
  102.  
  103.  
  104.         Viewing an Encoded dBASE II File
  105.  
  106.     To view  the  encoded  dBASE II  command  file  "SAMPLE.CMD",
  107. simply type in the file name at the title screen prompt.
  108.  
  109. Filename.CMD or Drive? SAMPLE.CMD
  110.  
  111.      Just use control S to stop the  scrolling  of  the  file  or
  112. control C to quit the program.   The file to be viewed must  have
  113. the extension .CMD
  114.  
  115.  
  116.                  Options
  117.  
  118. P    Send the output to the printer.  Does not generate a file.
  119. F    Send the output to a file.
  120. N    Turn off console output.  May be used only in combination
  121.     with P or F options.
  122.  
  123.      Options must preceded by a space.  Extra spaces entered with
  124. the options do not matter.   SAMPLE.CMD P F N  is  equivalent  to
  125. SAMPLE.CMD PFN.
  126.  
  127.  
  128.              Direct output to Printer
  129.  
  130.      Use the P option to direct the output to the printer:
  131.  
  132. Filename.CMD or Drive? SAMPLE.CMD P
  133.  
  134.      This does not generate a disk file.   It will only print the
  135. file and display the output on the screen.
  136.  
  137.  
  138.              Creating a source File
  139.  
  140.      To generate a runnable source file from an encoded  dBASE II
  141. .CMD program, use the F option:
  142.  
  143. Filename.CMD or Drive? SAMPLE.CMD F
  144.  
  145.      This will write a file  called  SAMPLE.SRC.   If  SAMPLE.SRC
  146. already exists, you will be prompted with the message:
  147.  
  148.             []=========[]
  149.             [] WARNING []
  150.             []=========[]
  151.  
  152. SAMPLE.SRC already exists!  A 'NO' here will cause the current
  153. SAMPLE.SRC to be renamed to SAMPLE.BAK
  154.  
  155.  
  156. Do you wish to overwrite SAMPLE.SRC (Yes/No/Quit)?
  157.  
  158.      The output file will be named SAMPLE.SRC.   After  you  move
  159. this file to another disk and rename it to SAMPLE.CMD, it  should
  160. run the same, only somewhat slower, as the encoded original.
  161.  
  162.  
  163.             No console output
  164.  
  165.      The N option shuts off the normal presentation of the output
  166. file on the console.  This helps speed up generation of a file or
  167. printing of the output.   It can not be  used  unless  the F or P
  168. options are used.  I do not like it with the F option.   I prefer
  169. to see that the decoding is being done correctly.
  170.  
  171.             How does it work?
  172.  
  173.      Files that have been pseudo  compiled by  DBCODE,  ENCODE or
  174. DB-SQZ5 have the first reserved word en each line tokenized.  The
  175. tokens are bytes with decimal  values  between 128 and 194.   128
  176. represents IF, 129 is ELSE, 130 is ENDIF  etc.   Examine  at  the
  177. lookup table at the end of DBSOURCE, if you are curious.
  178.  
  179.      The space at the end of the reserved word  has  been  removed
  180. and the rest of the line converted to high order bytes  by  XORing
  181. them with 255.
  182.  
  183.      To decode, DBSOURCE  just  creates a  print  string  starting
  184. with the reserved word found in the table, adds a space  and  then
  185. adds to it byte by byte using XOR 255 to return  to  the  original
  186. value.
  187.  
  188.          History of DBSOURCE and DBSRC2
  189.  
  190. Rev. 1.02  3/1/85  Added self installation of clear  screen  and
  191. the COM file is now stand alone.
  192.  
  193. Rev. 1.01  2/17/85  Modified for compatibility  with  MBASIC 5.20
  194. under  Apple CP/M.   This required changing TEXT$ to TXT$ as TEXT
  195. is a reserved word in the apple CP/M basic.
  196.  
  197. Versions 1.00 released 1/6/85
  198.  
  199. =================================================================
  200.  
  201.  
  202.                DBSRC2
  203.  
  204.      DBSRC2 was created  to  decode  several  programs  that  had
  205. either included some additional encoding to mix up  the  reserved
  206. words.  Or, I ran into something that was encoded  by a variation
  207. of DBCODE.  If you decode a file with DBSOURCE and there are some
  208. strange placements of reserved words, you should  try  DBSRC2  on
  209. it.  You might see something like  QUIT in the middle of the file
  210. or UNLOCK in place of some other word.
  211.  
  212.       If  you  find  that  there  are  still  errors  in  keyword
  213. translation with either DBSOURCE  or  DBSRC2,  you  may  want  to
  214. generate your own version of DBSOURCE.   Examine the remarks just
  215. before the table of reserved words in DBSRC2 to see what I did to
  216. generate this variant.   It involves  substituting reserved words
  217. in the table.   If you remove a word from the table and put it at
  218. the end,  all reserved words located after the  removal  will  be
  219. offset by one.   This was done with  DBSRC2.   If you find only a
  220. single keyword is wrong,  you should make a swap with the correct
  221. word in the DATA statements.
  222.  
  223.  
  224.              Other Related Programs
  225.  
  226.      I have written two other programs  for  dBASE II  that  have
  227. been released in other  library  files.   They  are,  ENCODE  and
  228. DBINDENT.   ENCODE is the reverse of DBSOURCE.   It  creates  the
  229. tokenized command file.  DBINDENT is a  dBASE II  pretty printer.
  230. Current versions  as  of  the  release  of  this  library  are in
  231. ENCODE4.LBR and DBINDNT1.LBR.
  232.  
  233.  
  234.             COPYRIGHT AND LIMITATIONS
  235.  
  236.      All of  the  above  programs  may  be  copied  for  private,
  237. noncommercial use,  provided that all  copyright  notices  remain
  238. intact.   In fact,  making copies for your friends is encouraged.
  239. They may also be included in distribution disks  from  non-profit
  240. computer clubs, if only a nominal charge of less than $20.00  per
  241. disk is charged to cover costs of  disk,  copying  and  shipping.
  242. These programs are NOT "Public Domain".   To release a program to
  243. public domain causes all control of distribution and sale  to  be
  244. voided.   Any sale of these programs that does  not  comply  with
  245. these conditions will be prosecuted.
  246.  
  247.      None of the programs named at the beginning of this  library
  248. documentation  may be sold for profit or used as an inducement to
  249. buy any other product or program without the  written  permission
  250. of the author:
  251.  
  252.             Merlin R. Null
  253.             P. O. Box 9422
  254.             N. Hollywood, CA 91609
  255.             (818) 762-1429
  256.  
  257.      A small donation, like $5.00, would help me with maintaining
  258. these programs, but is not required.  These programs were written
  259. for DBASE II users and programmers, not with profit in mind.
  260.  
  261.      Please contact me if you have  any  suggestions,  gripes  or
  262. comments about DBSOURCE or DBSRC2.
  263.  
  264.  
  265. dBASE II,  dBASE III,  RUNTIME  and  DBCODE  are  trademarks   of
  266. Ashton-Tate.  MBASIC is a trademark of Microsoft.
  267. ed to cover costs of  disk,  copying  and  shi