home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / mbug / mbug060.arc / CPM#006.LBR / ENCODE.DOC < prev    next >
Text File  |  1979-12-31  |  12KB  |  323 lines
  1.      Documentation For ENCODE Version 1.05  3/20/85
  2.  
  3.           Copyright (C) 1985 by Merlin R. Null
  4.  
  5.  
  6.      ENCODE is pseudo compiler for dBASE II version 2.4 or higher
  7. command files.   Programs encoded with ENCODE will run  with  the
  8. regular version of dBASE II version 2.4 or higher.  Ashton-Tate's
  9. RUNTIME is not required, although it could be  used.   RUNTIME is
  10. simply an amputated version of dBASE II that only has the ability
  11. to run programs, not edit them.
  12.  
  13.  
  14.     The ENCODE library should contain the following files:
  15.  
  16. ENCODE.COM    ENCODE, pseudo compiles dBASE II command files
  17.         to run up to 30% faster.
  18. ENCODE.BAS    The MBASIC source for the above program.
  19. ENCODE.HLP    Help file for ENCODE.
  20. ENCODE.DOC    This documentation on ENCODE.
  21.  
  22.  
  23. ************    ENCODE.COM  is  a  stand  alone  compiled  MBASIC
  24. *   NOTE   *    program.   BRUN.COM, the Microsoft compiled basic
  25. ************    runtime  package  is  NOT  required.   ENCODE.BAS
  26.         requires the  MBASIC  interpreter  to  run.   The
  27.         compiled version is in 8080 code.  It will run on
  28.         an 8080 or Z80 machine.
  29.  
  30.  
  31.               Installation
  32.  
  33.      To install  ENCODE,  just  run  the  program.   It  is  self
  34. installing.  If the clear screen data file,  CLS.DAT,  is missing
  35. on the disk with ENCODE, a new one will be  generated.   You will
  36. be asked for the decimal values of your  clear  screen  sequence. 
  37. For example, on a KayPro or Osborne CP/M machine just enter:
  38.  
  39. Clear screen character 1? 26
  40. Clear screen character 2? <RETURN>
  41.  
  42. CLS.DAT will  then  be  written  and  you  will  go  directly  to
  43. operation of ENCODE.  If the title screen is preceeded by a clear
  44. screen, the installation was  successful.  If  the  title  screen
  45. scrolls on, it failed.   If it fails,  exit  the  program,  erase
  46. CLS.DAT, and run ENCODE again. If you don't like the clear screen
  47. function, simply enter  10  when  asked  for  your  clear  screen
  48. sequence.   For each 10 you enter ENCODE will scroll one line  in
  49. place of the clear screen.   My  older  program,  CLEARSET,  will
  50. still generate a correct CLS.DAT for this version of ENCODE.
  51.  
  52.  
  53.            Calling a Directory Listing
  54.  
  55.      To call a directory from the title screen simply  enter  the
  56. drive you wish to list.
  57.  
  58. Filename.SRC or Drive:? A:
  59.  
  60.    This will list the directory of drive A and give the prompt
  61. again.
  62.  
  63. Directory of drive A:
  64. FOO    .CMD    DBSOURCE.BAS    DBSOURCE.COM    TEST2    .CMD    A10    .CMD
  65. ENCODE  .BAS    ENCODE  .COM    MBASIC    .COM    D    .COM    SAMPLE    .CMD
  66. BOOKS    .DBF    BOOKS    .FRM    DBASE    .COM    CLS    .DAT    CLEARSET.BAS
  67. CLEARSET.COM    DBASEMSG.TXT    DBASEOVR.COM    B4    .CMD    R2D2    .CMD
  68. DBINDENT.BAS    DBINDENT.COM    ELIZA    .BAS    A10    .SRC    A10    .BAK
  69. CLONE    .CMD    TEST    .CMD    CLONE    .SRC    A10    .OLD    DBSRC2    .BAS
  70. DBSRC2    .COM
  71. Filename.CMD or Drive:?
  72.  
  73.     The  ZCPR like drive call of A; will also work  to  call  the
  74. directory, even if you are not running  ZCPR.   The  Filename.CMD
  75. may be entered here  or  a  <RETURN>  will  redisplay  the  start
  76. screen.
  77.  
  78.  
  79.              Encoding a File
  80.  
  81.      A file to be encoded MUST have  the  extension  .SRC.   Just
  82. rename your  source  file  to  <filename>.SRC.   Then  enter  the
  83. <filename>.SRC  at the ENCODE prompt:
  84.  
  85. Filename.SRC or Drive:? SAMPLE.SRC
  86.  
  87.      ENCODE requires all characters in the input  file  have  the
  88. 8th bit set low.   You may have to run your source file through a
  89. filter, like UNSOFT.
  90.  
  91.      ENCODE creates a partially tokenized file that  can  not  be
  92. listed with anything but DBSOURCE or a commercial decoder.  It is
  93. also hard to modify a command file protected  with  ENCODE.   The
  94. file is reduced in size as all indenting and comments preceded by
  95. * are removed.  In addition comments after the END statements are
  96. removed.  Example:
  97.  
  98. ENDIF .NOT. green
  99.  
  100.      Becomes a single byte for  the  reserved  word  ENDIF.   The
  101. ".NOT. green" is purely a comment  that  repeats  the  conditions
  102. that began the IF statement that should read:
  103.  
  104. IF .NOT. green
  105.  
  106.      Such comments make a program easier to read  but  will  slow
  107. down operation as  dBASE II  reads program lines from the disk as
  108. they are executed.   The latest versions of Ashton-Tate's  DBCODE
  109. and Gene Head's DB-SQZ5 that I have seen leave these comments in.
  110.  
  111.      You can label a file by enclosing  a message   between  TEXT
  112. and ENDTEXT.  This leaves all lines between TEXT  and  ENDTEXT as
  113. in the source file.  ENDTEXT may be abbreviated to ENDT. Example:
  114.  
  115. TEXT
  116.         (C) 1985 by Croggle Software, Inc.
  117. ENDTEXT
  118.  
  119.      Caution should be taken that the  ENDTEXT  is included.   If
  120. omitted, all of the remaining file  will  not  be  encoded.   The
  121. command TEXT shuts off  encoding,  ENDTEXT  turns  it  on  again.
  122. Indentation within the TEXT area will be left as  in  the  source
  123. file.  Use this feature as little as you can.   The  extra  lines
  124. will slow down the program a little for each line added.   ENCODE
  125. requires that source files have initial  reserved  words  written
  126. out in full.  This insures a fully readable source  file.   dBASE
  127. looks for only  the  first  four  letters  of  a  reserved  word.
  128. Reserved words in any postion on a line but the first word may be
  129. abbreviated.  ENCODE does not check syntax on  anything  but  the
  130. first word in each line of dBASE command files.
  131.  
  132.      ENCODE also requires that you name the source file  with the
  133. extension .SRC.  This keeps the  programmer  from  mistaking  the
  134. pseudo compiled (.CMD) file for the source  (.SRC)  file.   If  a
  135. file is requested and the .CMD file already exists, you  will  be
  136. warned:
  137.  
  138.             []=========[]
  139.             [] WARNING []
  140.             []=========[]
  141.  
  142.  
  143. SAMPLE.CMD already exists!  If you answer NO, the old SAMPLE.CMD
  144. will be renamed to SAMPLE.OLD
  145.  
  146.  
  147. Do you wish to overwrite SAMPLE.CMD (Yes/No/Quit)?
  148.  
  149.      If you choose not to overwrite SAMPLE.CMD, the old file will
  150. be renamed SAMPLE.OLD.  The .OLD extension is used  to  keep  the
  151. encoded backup files distinct from the source backup which  would
  152. have a .BAK extension.  If you opt to quit, you will be taken  to
  153. the end of the program and see:
  154.  
  155. Are you finished?
  156.  
  157.      A <RETURN>, or any answer but yes, will return  you  to  the
  158. start screen for another file.
  159.  
  160.  
  161.               Macro Support
  162.  
  163.      Unlike Ashton-Tate's  DBCODE,  ENCODE  provides  full  macro
  164. support.   It is recommended that macros be used only when  other
  165. means are not available.  Macro operation is usually  slower.   A
  166. line starting with a macro will not be encoded.   This will  slow
  167. the program even more.  You must retain  the  "&"  as  the  macro
  168. symbol if you want to start a line with a macro.  ENCODE will not
  169. recognize a different symbol at the start  of  a  line,  even  if
  170. dBASE II can be configured to do so.   If  macros are confined to
  171. locations other than the start of a line, the "&" may be changed.
  172. If you do plan on using ENCODE to create a file for Ashton-Tate's
  173. RUNTIME, do not use an initial macro.   RUNTIME  will  not accept
  174. it.
  175.  
  176.  
  177.                 Sub Files
  178.  
  179.      ENCODE requires separate encoding of any sub files you  wish
  180. to use in a dBASE II program package.   It is not  required  that
  181. all sub programs be encoded when operation is with dBASE II,  but
  182. it should be done for speed.   Only the command  files  with  the
  183. extension .CMD are encoded.
  184.  
  185.  
  186.                Continuation Lines
  187.  
  188.      Continuation lines will be work with  ENCODE,  but  are  not
  189. recommended.  They tend to add extra  bytes  to  the  file.   The
  190. usual reason for the broken line  is  to  handle  80  columns  of
  191. display.  A pair of lines like the following:
  192.  
  193. @ 6,0 SAY '-----------------------------------------------------------------';
  194. +'---------------'
  195.  
  196. Could be written:
  197.  
  198. @ 6,0 SAY '-------------------------------------------------------------------
  199. -------------'
  200.  
  201.      The line is  allowed  to  wrap  (without a <RETURN>)  and be
  202. longer than 80 columns.  This is only possible if you use a  word
  203. processor to generate the CMD file.   dBASE II  will amputate the
  204. lines at 80 columns.   This method produces the shortest  output. 
  205. Another way to handle it is as follows:
  206.  
  207. @ 6,0 SAY '----------------------------------------'
  208. @ 6,40 SAY '----------------------------------------'
  209.  
  210.      This is 14 bytes longer than the previous  example  and  11
  211. bytes longer than the first, when encoded.
  212.  
  213.  
  214.            Abbreviated Reserved Words
  215.  
  216.      Reserved words may be abbreviated to four letters  in  your
  217. source file.  For example:
  218.  
  219. DO WHIL    =    DO WHILE
  220. OTHE    =    OTHERWISE
  221. STOR    =    STORE
  222. ENDI    =    ENDIF
  223.  
  224.      This produces a source file that is a little harder to read,
  225. but it allows faster code  writing.   You may also want to encode
  226. files already written in this style.  It is often used to produce
  227. a dBASE II command file that will run  slightly faster because of
  228. the shorter length of the file.   There  is  no gain in ENCODE to
  229. abbreviate the  initial  reserved  word  in  each  line.   ENCODE
  230. converts it to a single byte  token  anyway.   Please  note  that
  231. only the full reserved word and the four letter  abbreviation are
  232. supported  by  ENCODE  for  initial  reserved  words.   OTHE  for
  233. OTHERWISE is ok, but OTHER or OTHERW will not work. 
  234.  
  235.  
  236.                 Help File
  237.  
  238.      The help file may be called from ENCODE by  entering a  "?"
  239. at the title screen.
  240.  
  241. Filename.SRC or Drive:? ?
  242.  
  243.  
  244.                  Option
  245.  
  246. N    No console display of  input  file.   This  is  the  only
  247.     option.  The N option must preceded by a space:
  248.  
  249. Filename.SRC or Drive:? SAMPLE.SRC N
  250.  
  251.  
  252.                  History
  253.  
  254. Rev. 1.05  3/20/85    Fixed bug that doubled  encoded  bytes  for
  255. reserved words with a length of  4.   WAIT was encoded to WAIT =.
  256. In hex:  C2 C2.  Bug present from version 1.02 thru 1.04.
  257.  
  258. Rev. 1.04  2/28/85    Minor correction to  installation  routine.
  259.  
  260. Rev. 1.03  2/27/85    Changed to remove  comments  starting  with
  261. NOTE and fixed bug in abbreviations of DO WHILE and DO CASE.
  262.  
  263. Rev. 1.02  2/24/85    Added the ability to recognize  four letter
  264. abbreviations of  initial  reserved  words.   Clear  screen  self
  265. installation added.   ENCODE.COM distributed as a stand alone COM
  266. file, BRUN.COM no longer required.
  267.  
  268. Rev. 1.01  2/17/85    Modified for compatibility with MBASIC 5.20
  269. under Apple CP/M.   This required changing TEXT$ to TXT$  as TEXT
  270. is a reserved word in the  Apple CP/M basic.   Added the  ability
  271. to accept initial reserved  words in lower case.   Also  modified
  272. to handle continuation lines and remove indentation at the  start
  273. of the continued line.  Blank lines  will  no  longer  abort  the
  274. encoding, provided they contain no spaces or tabs.
  275.  
  276. ENCODE version 1.00 released 1/6/85
  277.  
  278.  
  279.               LEGAL NOTICE
  280.  
  281.      ENCODE  is NOT  "Public Domain."   Copyright  is held by the
  282. author:
  283.  
  284.             Merlin R. Null
  285.             P. O. Box 9422
  286.             N. Hollywood, CA 91609
  287.             (818) 762-1429
  288.  
  289.      Permission is given  only  for  private,  nonprofit  use  of
  290. ENCODE.  Feel free to make copies of the  program  for  your  own
  291. use or for your friends.   However, ENCODE may  NOT  be  sold  or
  292. included with any collection of programs for sale or used  as  an
  293. inducement to buy another product or program without the  written
  294. permission of the author.  Permission is also given for nonprofit
  295. computer clubs to include this  program  in  distribution  disks,
  296. provided total charges for the entire disk  of  programs, copying
  297. and shipping do not exceed $20.00.   My vote  of  thanks  goes to
  298. those clubs that have kept their charges under $10.00.
  299.  
  300.  
  301.                 Donation
  302.  
  303.      If you like the program and use  it,  a  small  donation  of
  304. about $5.00 would be appreciated,  though it is  not required  to
  305. use ENCODE.  I will do my part to keep ENCODE maintained.
  306.  
  307.      Please report any bugs to me at the above address  or  phone
  308. number.  I can also be  reached  by  leaving  a  message  on  the
  309. Glendale Literaria RCP/M (818) 956-6164.
  310.  
  311.  
  312.               Other dBASE Utilities
  313.  
  314.      I have two  other  programs  that  may  be  of  interest  to
  315. dBASE II users.   They are: DBSOURCE, a program to return encoded
  316. dBASE II command files to source code.   And  DBINDENT, to pretty
  317. print  dBASE II  source  code.    The  current  versions  are  in
  318. DBSRC102.LBR and DBINDENT.LBR.
  319.  
  320. MBASIC and BRUN are Trademarks of Microsoft.
  321. dBASE II, DBCODE and RUNTIME are Trademarks of Ashton-Tate.
  322. d total charges for the entire disk  of  programs, copying
  323. and shipping do not exceed $20.00.   My