home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / lambda / soundpot / a / dbsource.lbr / DBSOURCE.DZC / DBSOURCE.DOC
Encoding:
Text File  |  1993-10-26  |  17.9 KB  |  469 lines

  1.       DOCUMENTATION FOR DBSOURCE AND ENCODE  1-6-85
  2.  
  3.           Copyright (C) 1985 by Merlin R. Null
  4.  
  5.  
  6.     The DBSOURCE library should contain the following files:
  7.  
  8. DBSOURCE.DOC    This general library documentation.
  9. DBSOURCE.COM    DBSOURCE, reads encoded dBASE II command files.
  10. DBSOURCE.BAS    The MBASIC Source for the above program.
  11. DBSOURCE.HLP    Help file for DBSOURCE.
  12. DBSRC2.COM    A variant of DBSOURCE
  13. DBSRC2.BAS    The MBASIC Source for the above program.
  14. ENCODE.COM    ENCODE, pseudo compiles dBASE II command files
  15.         to run about 30% faster.
  16. ENCODE.BAS    The MBASIC Source for the above program.
  17. ENCODE.HLP    Help file for ENCODE.
  18. CLEARSET.COM    Writes CLS.DAT, a file containing the clear screen
  19.         information used in all of the above programs.
  20. CLEARSET.BAS    The MBASIC Source for the above program.
  21. CLS.DAT        Clear Screen data file.  Distribution version is for
  22.         the STM Pied Piper.
  23.  
  24. NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE
  25.  
  26. THE CLS.DAT HAS BEEN SET UP FOR THE KAYPRO AND OSBORNE
  27. THE PROGRAMS HAVE BEEN COMPILED WITH OSLIB SO THAT THEY RUN WITHOUT BRUN.COM
  28.  
  29. NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE:NOTE
  30.         
  31.  
  32. *************    Microsoft's BRUN.COM is required to run any of the
  33. * IMPORTANT *    COM files listed above.  They are in compiled MBASIC.
  34. *************    If you do not have MBASIC.COM or BRUN.COM, none of
  35.         these programs will do anything other than take up
  36.         disk space.  If at all possible (you must have BRUN)
  37.         use the compiled versions.  They are up to 10 times
  38.         faster.  The interpreted versions will do a good job,
  39.         they just take a little longer.  The compiled versions
  40.         are in 8080 code.  They will run on an 8080 or Z80
  41.         machine.
  42.  
  43.  
  44.          Running the DB-Utility Programs
  45.  
  46.      First call the programs by entering MBASIC <filename>, if
  47. you have only MBASIC.  If you have Microsoft's BRUN.COM the
  48. BASCOM run time package, use the COM file by entering <filename>
  49. at the CP/M prompt.  BRUN.COM must be on the same disk as the
  50. program you wish to run.  These programs were written in MBASIC
  51. version 5.21.  Most of them will not run in OBASIC, Microsoft's
  52. older version of BASIC (4.51 or earlier), due to the use of
  53. WHILE-WEND loops.
  54.  
  55.  
  56.            Calling a Directory Listing
  57.  
  58.      DBSOURCE, DBSRC2 and ENCODE use a similar command for listing a
  59. directory at the title screen.
  60.  
  61.      To call a directory from the title screen simply enter the
  62. drive you wish to list.  This sample is from DBSOURCE:
  63.  
  64. Filename.CMD or Drive:? A:
  65.  
  66.    This will list the directory of drive A and give the prompt
  67. again.
  68.  
  69. Directory of drive A:
  70. FOO    .CMD    DBSOURCE.BAS    DBSOURCE.COM    BRUN    .COM    A10    .CMD
  71. ENCODE  .BAS    ENCODE  .COM    MBASIC    .COM    D    .COM    SAMPLE    .CMD
  72. BOOKS    .DBF    BOOKS    .FRM    DBASE    .COM    CLS    .DAT    CLEARSET.BAS
  73. CLEARSET.COM    DBASEMSG.TXT    DBASEOVR.COM    B4    .CMD    R2D2    .CMD
  74. DB-IND    .BAS    DB-IND    .COM    ELIZA    .BAS    A10    .SRC    A10    .BAK
  75. CLONE    .CMD    TEST    .CMD    CLONE    .SRC    A10    .OLD    DBSRC2    .BAS
  76. DBSRC2    .COM
  77. Filename.CMD or Drive:?
  78.  
  79.     The ZCPR like drive call of A; will also work to call the
  80. directory, even if you are not running ZCPR.  The Filename.CMD
  81. may be entered here or a <RETURN> will redisplay the start
  82. screen.
  83.  
  84. ======================================================================
  85.  
  86.  
  87.               INSTALLATION
  88.  
  89.      To run any of the first eight .COM or .BAS programs in the
  90. this library, you should run CLEARSET first.  CLEARSET generates
  91. the information needed by your terminal to do the clear screen
  92. function.  It does this by writing the small file, CLS.DAT.  If
  93. you were to type the CLS.DAT file, you might see this:
  94.  
  95. 126
  96. 28
  97. 26
  98.  
  99.      These numbers are the decimal values of the clear screen
  100. command.  You can also use CLEARSET to cause the programs to use
  101. scrolling instead of clear screen.  The distribution copy of
  102. CLS.DAT, the file written by CLEARSET, is set for the STM Pied
  103. Piper.  It is a combination of the Hazeltine 1500 and ADM-3A
  104. clear screen commands.  This will work on many other terminals.
  105.      If you do not have a copy of CLS.DAT on the same disk as the
  106. other programs on this disk, you will get an error message:
  107.  
  108. CLS.DAT not found.  Please run CLEARSET to generate it.
  109.  
  110. And, you will be returned to CP/M.
  111.  
  112.      When you run CLEARSET you will get the following menu:
  113.  
  114. 1. ADM-3A, Televideo 912    (Kaypro, Osborne)
  115. 2. ADM-31, Televideo 950
  116. 3. Hazeltine 1500
  117. 4. STM Pied Piper        (Combination of Hazeltine 1500 and ADM-3A)
  118. 5. DEC VT52            (Telcon Zorba)
  119. 6. Custom installation
  120. 7. I don't know.  Use scrolling.
  121. 8. Exit without changing CLS.DAT
  122.  
  123.      Select your terminal from numbers 1 thru 5, if it is listed.
  124. Use choice number 6 if you know what the clear screen command is
  125. for your terminal.
  126.     To use the custom installation, you must find the DECIMAL
  127. values of your terminal's clear screen command.  For example, if
  128. your clear screen command is ESCAPE *, you will need to enter as
  129. follows:
  130.  
  131. Enter your clear screen sequence in ASCII decimal numbers.
  132. Enter <RETURN> to end sequence.
  133.  
  134. Example: for <ESCAPE> enter 27, for * enter 42.
  135.  
  136. Clear screen sequence character number 1 ? 27
  137. Clear screen sequence character number 2 ? 42
  138. Clear screen sequence character number 3 ? <RETURN>
  139.  
  140.      You should then see:
  141.  
  142. CLS.DAT Written.
  143.  
  144.      The clear screen commands are entered in DECIMAL numbers not
  145. HEX.  If you don't like clear screen in a program or you really
  146. don't know what your terminal uses for clear screen, select:
  147.  
  148. 7. I don't know.  Use scrolling.
  149.  
  150.      You will then be asked:
  151.  
  152. How many blank lines do you want for scrolling?
  153.  
  154.      Any number from 1 to 24 will be accepted.    Numbers larger
  155. than 24 default to 24.    Numbers less than 1 default to 1.  If you
  156. do not mind some old information staying on screen when you run
  157. the program, use 1.  If you wish all old lines to scroll off
  158. screen, use at least 12.  More might be required.  24 will be
  159. sure to get everything off screen, but it makes operation a
  160. little slower.
  161.      The clear screen command makes operation much faster.  It is
  162. highly recommended.  If you do not know your clear screen
  163. command, try several of the menu selections to see if one of them
  164. works.  Most of the common ones are covered by the menu listings.
  165.      CLEARSET could be adapted for many MBASIC programs.  It
  166. makes an MBASIC program that uses a clear screen function
  167. configureable for many different terminals without modifying the
  168. source code.
  169.      To use the CLS.DAT file written by ClearSet with another
  170. MBASIC program, just copy in the routine at the beginning of any
  171. of the dBASE utility programs and add the error handling routine
  172. from the end.  Then when the program is run, it will read CLS.DAT
  173. and enter the values in CLS$ for use throughout the program.
  174.  
  175. ======================================================================
  176.  
  177.  
  178.                 DBSOURCE
  179.  
  180.      DBSOURCE will take a dBASE II command file that has been
  181. encoded with ENCODE , Ashton-Tates's DBCODE or with Gene Head's
  182. DB-SQZ5 and generate a runable source file.  DB-Source can also
  183. send the output to the printer or you may view the output on your
  184. console.  It will not decode a dBASE III file.  DBCODE for dBASE
  185. III uses a more complex partial compiler.
  186.      This type of file is encoded for one of two reasons.  First,
  187. it protects the program file from being viewed or modified.
  188. Second, the encoded programs run about 30% faster.  I feel
  189. that the latter reason is far more important.  The level of
  190. protection that this type of encoding offers is only moderate.
  191. Programs run faster because the files are partially tokenized and
  192. all comments are removed.
  193.      Encoded command files are for use with dBASE II version 2.4
  194. or higher.  A decoded file might require some translation to run
  195. on an earlier version of dBASE II.
  196.  
  197.                 Help File
  198.  
  199.      The help file may be called from DB-Source by entering a "?"
  200. at the title screen.  It contains several screens of condensed
  201. information on how to run DB-Source.
  202.  
  203. Filename.CMD or Drive:? ?
  204.  
  205.  
  206.         Viewing an Encoded dBASE II File
  207.  
  208.     To view the encoded dBASE II command file "SAMPLE.CMD",
  209. simply type in the file name at the title screen prompt.
  210.  
  211. Filename.CMD or Drive? SAMPLE.CMD
  212.  
  213.      Just use control S to stop the scrolling of the file or
  214. control C to quit the program.  The file to be viewed must have
  215. the extension .CMD
  216.  
  217.  
  218.                  Options
  219.  
  220. P    Send the output to the printer.  Does not generate a file.
  221. F    Send the output to a file.
  222. N    Turn off console output.  May be used only in combination
  223.     with P or F options.
  224.  
  225.      Options must preceded by a space.  Extra spaces entered with
  226. the options do not matter.  SAMPLE.CMD P F N is equivalent to
  227. SAMPLE.CMD PFN.
  228.  
  229.  
  230.              Direct output to Printer
  231.  
  232.      Use the P option to direct the output to the printer:
  233.  
  234. Filename.CMD or Drive? SAMPLE.CMD P
  235.  
  236.      This does not generate a disk file.  It will only print the
  237. file and display the output on the screen.
  238.  
  239.  
  240.              Creating a source File
  241.  
  242.      To generate a runnable source file from an encoded dBASE II
  243. .CMD program, use the F option:
  244.  
  245. Filename.CMD or Drive? SAMPLE.CMD F
  246.  
  247.      This will write a file called SAMPLE.SRC.  If SAMPLE.SRC
  248. already exists, you will be prompted with the message:
  249.  
  250.             []=========[]
  251.             [] WARNING []
  252.             []=========[]
  253.  
  254. SAMPLE.SRC already exists!  A 'NO' here will cause the current
  255. SAMPLE.SRC to be renamed to SAMPLE.BAK
  256.  
  257.  
  258. Do you wish to overwrite SAMPLE.SRC (Yes/No/Quit)?
  259.  
  260.      The output file will be named SAMPLE.SRC.  After you move
  261. this file to another disk and rename it to SAMPLE.CMD, it should
  262. run the same, only somewhat slower, as the encoded original.
  263.  
  264.  
  265.             No console output
  266.  
  267.      The N option shuts off the normal presentation of the output
  268. file on the console.  This helps speed up generation of a file or
  269. printing of the output.  It can not be used unless the F or P
  270. options are used.  I do not like it with the F option.  I prefer
  271. to see that the decoding is being done correctly.
  272.  
  273.             How does it work?
  274.  
  275.      Files that have been pseudo compiled by DBCODE, ENCODE
  276. or DB-SQZ5 have the first reserved word en each line tokenized.
  277. The tokens are bytes with decimal values between 128 and 194.
  278. 128 represents IF, 129 is ELSE, 130 is ENDIF etc.  Examine at the
  279. lookup table at the end of DBSOURCE, if you are curious.
  280.      The space at the end of the reserved word has been removed
  281. and the rest of the line converted to high order bytes by XORing
  282. them with 255.
  283.      To decode, DBSOURCE just creates a print string starting
  284. with the reserved word found in the table, adds a space and then
  285. adds to it byte by byte using XOR 255 to return to the original
  286. value.
  287.  
  288. ======================================================================
  289.  
  290.  
  291.                DBSOURCE II
  292.  
  293.      DBSOURCE II was created to decode several programs that had
  294. either included some additional encoding to mix up the reserved
  295. words. Or, I ran into something that was encoded by a variation
  296. of DBCODE.  If you decode a file with DB-Source and there are
  297. some strange placements of reserved words, you should try
  298. DB-Source II on it.  You might see something like QUIT in the
  299. middle of the file or UNLOCK in place of some other word.
  300.  
  301.      If you find that there are still errors in keyword
  302. translation with either DBSOURCE or DBSOURCE II, you may want
  303. to generate your own version of DBSOURCE.  Examine the remarks
  304. just before the table of reserved words in DB-Source II to see
  305. what I did to generate this variant.  It involves substituting
  306. reserved words in the table.  If you remove a word from the table
  307. and put it at the end,  all reserved words located after the
  308. removal will be offset by one.  This was done with DBSOURCE II.
  309. If you find only a single keyword is wrong, you should make a
  310. swap with the correct word in the DATA statements.
  311.  
  312. ======================================================================
  313.  
  314.  
  315.                  ENCODE
  316.  
  317.      ENCODE is pseudo compiler for dBASE II version 2.4 or
  318. higher command files.  Programs encoded with ENCODE will run
  319. with the regular version of dBASE II version 2.4 or higher.
  320. Ashton-Tate's RUNTIME is not required, although it could be
  321. used.  RUNTIME is simply an amputated version of dBASE II
  322. that only has the ability to run programs, not edit them.
  323.      ENCODE creates a partially tokenized file that can not be
  324. listed with anything but DBSOURCE or a commercial decoder.  HILCO
  325. Software has been offering DECODE and RECODE as a package to do
  326. the same thing as DBSOURCE and ENCODE.  I have not had the
  327. opportunity to try them, so I can't say how they compare to
  328. DBSOURCE and ENCODE.  It is also hard to modify a command file
  329. protected with ENCODE.  The file is reduced in size as all
  330. indenting and comments preceded by * are removed.  In addition
  331. comments after the END statements are removed.  Example:
  332.  
  333. ENDIF .NOT. green
  334.  
  335.      Becomes a single byte for the reserved word ENDIF.  The
  336. ".NOT. green" is purely a comment that repeats the conditions that
  337. began the IF statement that should read:
  338.  
  339. IF .NOT. green
  340.  
  341.      Such comments make a program easier to read but will slow
  342. down operation as dBASE II reads program lines from the disk as
  343. they are executed.  The latest versions of Ashton-Tate's DBCODE
  344. and Gene Head's DB-SQZ5 that I have seen leave these comments in.
  345.      Comments beginning with the reserved word NOTE are left in.
  346. This gives the programmer a way of marking a file with his name
  347. or copyright in a way that can only be listed with DBSOURCE.
  348.      You can also label a file by enclosing a message in between
  349. TEXT and ENDTEXT.  This leaves all lines between TEXT and ENDTEXT
  350. as in the source file.  ENDTEXT may be abbreviated to ENDT example:
  351.  
  352. TEXT
  353.         (C) 1985 by Croggle Software, Inc.
  354. ENDTEXT
  355.  
  356.      Caution should be taken that the ENDTEXT is included.  If
  357. omitted, all of the remaining file will not be encoded.  The
  358. command TEXT shuts off encoding, ENDTEXT turns it on again.
  359. Indentation within the TEXT area will be left as in the source
  360. file.  Use this feature as little as you can.  The extra lines
  361. will slow down the program a little for each line added.  DB-Encode
  362. requires that source files have initial reserved words written
  363. out in full.  This insures a fully readable source file.  dBASE
  364. looks for only the first four letters of a reserved word.
  365. Reserved words in any postion on a line but the first word may be
  366. abbreviated.  DB-Encode does not check syntax on anything but the
  367. first word in each line of dBASE command files.
  368.      DB-Encode also requires that you name the source file with the
  369. extension .SRC.  This keeps the programmer from mistaking the
  370. pseudo compiled (.CMD) file for the source (.SRC) file.  If a
  371. file is requested and the .CMD file already exists, you will be
  372. warned:
  373.  
  374.             []=========[]
  375.             [] WARNING []
  376.             []=========[]
  377.  
  378.  
  379. SAMPLE.CMD already exists!  If you answer NO, the old SAMPLE.CMD
  380. will be renamed to SAMPLE.OLD
  381.  
  382.  
  383. Do you wish to overwrite SAMPLE.CMD (Yes/No/Quit)?
  384.  
  385.      If you choose not to overwrite SAMPLE.CMD, the old file will
  386. be renamed SAMPLE.OLD.  The .OLD extension is used to keep the
  387. encoded backup files distinct from the source backup which would
  388. have a .BAK extension.  If you opt to quit, you will be taken to
  389. the end of the program and see:
  390.  
  391. Are you finished?
  392.  
  393.      A <RETURN>, or any answer but yes, will return you to the
  394. start screen to try again.
  395.  
  396.  
  397.               Macro Support
  398.  
  399.      Unlike Ashton-Tate's DBCODE, ENCODE provides full macro
  400. support.  It is recommended that macros be used only when other
  401. means are not vailable.  Macro operation is slower in most cases.
  402. A line starting with a macro will not be encoded.  This will slow
  403. the program even more.  You must retain the "&" as the macro
  404. symbol if you want to start a line with a macro.  ENCODE will
  405. not recognize a different symbol at the start of a line, even if
  406. dBASE II can be configured to do so.  If macros are confined to
  407. locations other than the start of a line, the "&" may be changed.
  408.      ENCODE requires separate encoding of any sub files you wish
  409. to use in a dBASE II program package.  It is not required that
  410. all sub programs be encoded when operation is with dBASE II, but
  411. it should be done for speed.  Only the command files with the
  412. extension .CMD are encoded.
  413.  
  414.  
  415.                 Help File
  416.  
  417.      The help file may be called from ENCODE by entering a "?"
  418. at the title screen.
  419.  
  420. Filename.SRC or Drive:? ?
  421.  
  422.  
  423.                  Option
  424.  
  425. N    No console display of input file.  This is the only option.
  426.  
  427.      The N option must preceded by a space:
  428.  
  429. Filename.SRC or Drive:? SAMPLE.SRC N
  430.  
  431. ======================================================================
  432.  
  433.  
  434.             COPYRIGHT AND LIMITATIONS
  435.  
  436.      All of the above programs may be copied for private,
  437. noncommercial use, provided that all copyright notices remain
  438. intact.  In fact, making copies for your friends is encouraged.
  439. They may also be included in distribution disks from non-profit
  440. computer clubs, if only a nominal charge of less than $20.00 per
  441. disk is charged to cover costs of disk, copying and shipping.
  442. These programs are NOT "Public Domain".  To release a program to
  443. public domain causes all control of distribution and sale to be
  444. voided.  Any sale of these programs that does not comply with
  445. these conditions will be prosecuted.
  446.      None of the programs named at the beginning of this library
  447. documentation may be sold for profit without the written
  448. permission of the author:
  449.  
  450.             Merlin R. Null
  451.             P. O. Box 9422
  452.             N. Hollywood, CA 91609
  453.             (818)762-1429
  454.  
  455.      A small donation, like $5.00, would help me with maintaining
  456. these programs, but is not required.  These programs were
  457. written for the hobbyist, not with profit in mind.
  458.  
  459.      Please contact me if you have any suggestions, gripes or
  460. comments about any of the DB-UTIL programs.
  461.  
  462. ======================================================================
  463.  
  464. dBASE II, dBASE III, RUNTIME and DBCODE are trademarks of Ashton-Tate
  465. MBASIC is a trademark of Microsoft
  466. WordStar is a trademark of MicroPro
  467. II, RUNTIME and DBCODE are trademarks of Ashton-Tate
  468. MBASIC is a trademark of Microsoft
  469. WordStar is a t