home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / database / cbin.zip / CBIN.TXT < prev    next >
Text File  |  1987-07-07  |  13KB  |  382 lines
  1.         The CBIN package is a small collection of BIN routines that
  2. can be LOADed and CALLed by dBase III Plus.  They also work with
  3. FoxBase+.  The name "CBIN" comes from the fact that the routines are
  4. written, not in assembler as in usual for BIN routines, but in the C
  5. programming language.  Russell Freeland modified the start-up code
  6. for Wizard C to work with dBase; Andrew Schulman wrote much of the
  7. C code.
  8.  
  9.         Whereas large packages such as dBase Tools for C or Tom
  10. Rettig's Library require that you load (and learn!) a large software
  11. package simply in order to perform a few functions, the CBIN routines
  12. operate independently of one another.  Learn and load the ones you
  13. need, and you don't have to bother with a 100K memory-resident
  14. program hogging your PC's memory.
  15.         
  16.         For more information, contact either:
  17.  
  18.         Andrew Schulman                        Russell Freeland                
  19.         12 Humboldt Street                    1780 SW 43                      
  20.         Cambridge MA 02140                    Fort Lauderdale FL 33064        
  21.  
  22.         We would appreciate hearing from you:  bug reports would be
  23. particularly appreciated right now.  Also, suggestions for other BIN
  24. routines that you would find useful in your everyday work.  Finally,
  25. any monetary contribution you could make would be appreciated.  We have
  26. big plans for more CBIN utilities, so it's worth your while to become
  27. a CBIN supporter.
  28.  
  29.         In the following descriptions of the BIN routines, note that
  30. all BINs must be LOADed into dBase III Plus before they can be
  31. CALLed.  You can do a RELEASE MODULE when you are done with it.
  32.  
  33.         Also note that some of the BIN files have to be called twice:
  34. once to "seed" them with necessary information they need, and again
  35. to get back the information you need.  
  36.  
  37.  
  38.  
  39.  
  40.         WRITE: Write characters to file or to printer (even chr(0))
  41.         -----
  42.  
  43. Setup:      F = "<filename> <mode>[+]"
  44.             CALL WRITE WITH F
  45.             
  46.             <filename> : any valid DOS filename or PRN: (for printer)
  47.             <mode> : x (for hexadecimal)
  48.                      d (for decimal)
  49.             [+] : optional + sign indicates append to file, not overwrite
  50.  
  51. Return from setup:  
  52.             if F = "-1" then file could not be opened; otherwise F will
  53.             contain DOS file handle, e.g., "04"
  54.  
  55. Use (after setup):
  56.             CALL WRITE WITH "<bytes...>"
  57.             
  58.             <bytes>: if hexadecimal mode was selected, hex designation
  59.                      for characters; if decimal mode was selected, chr()
  60.                      designation.
  61.                      Multiple occurrences of characters are designated
  62.                      with (bytes,number), where number will always be a
  63.                      decimal count.
  64.                      Strings (cannot include spaces) are delimited with 
  65.                      apostrophes:  'hello'
  66.                      (See examples below)
  67.  
  68. Close file:
  69.             CALL WRITE WITH "(!)"
  70.  
  71. Examples:
  72.             To create a DBF file without using CREATE (more useful
  73. DBF files can then be constructed using COPY TO STRUCTURE EXTENDED
  74. and CREATE FROM commands):
  75.  
  76.             LOAD WRITE
  77.             F = "FOO.DBF X"
  78.             CALL WRITE WITH F           && open the file
  79.             IF (F <> "-1")              && check if okay
  80.                 * write characters out to file
  81.                 CALL WRITE WITH "3 (0,7) 41 0 4f (0,21) 46 (4f,2) (0,8)"
  82.                 CALL WRITE WITH "43 (0,4) 4e (0,15) d 1a"
  83.             ENDIF
  84.             CALL WRITE WITH "(!)"       && close the file
  85.             USE FOO                        && do something with it
  86.             
  87.             Note that even though FOO.DBF was opened in hex mode,
  88. (0,21) writes 21 copies of chr(0) out to the file, not 33.  In hex
  89. mode, only the characters themselves are in hex; counts are always in
  90. decimal.  
  91.             
  92.             To set an Epson printer to italic, print the word "Hello" and
  93. return to roman (does not work in FoxBase+):
  94.             
  95.             CALL WRITE WITH "PRN: X"
  96.             CALL WRITE WITH "1b '4' 'Hello' 1b '5' (!)"
  97.  
  98.  
  99.         READ:  Read a character from a file
  100.         ----
  101.  
  102. Setup:          F = "<filename>"
  103.                 CALL READ WITH F
  104.  
  105.                 <filename>:  : any valid DOS filename
  106.  
  107. No value returned by setup.
  108.  
  109. To call (after setup):
  110.                 C = SPACE(1)
  111.                 CALL READ WITH C
  112.  
  113. Return from call:
  114.                 The next available character in file is returned in
  115.                 passed variable.  If end-of-file is reached, or otherwise
  116.                 character can not be retrieved, chr(255) is returned.
  117.                 
  118. Close file:     CALL READ WITH CHR(255)
  119.     
  120. Problems:       That READ is not parallel to WRITE is clearly a problem.
  121.                 This will be fixed in future versions.  This version simply
  122.                 illustrates that you can have relatively fast character-at-a-
  123.                 time access to files from within dBase.  Future versions
  124.                 will let you access multiple characters at a time, and will
  125.                 allow you to retrieve the next word from a file (similar to
  126.                 the C function strtok()).
  127.  
  128. Examples:       
  129.                 * TESTREAD.PRG
  130.                 PARAMETER FILE
  131.                 LOAD READ
  132.                 CALL READ WITH "&FILE"            && open the file
  133.                 ? UPPER(FILE)
  134.                 ?
  135.                 C = SPACE(1)
  136.                 DO WHILE (C <> CHR(255))        && while not end-of-file
  137.                     CALL READ WITH C            && get a char into C
  138.                     ?? C                        && display it
  139.                 ENDDO
  140.                 CALL READ WITH CHR(255)            && close the file
  141.  
  142.                 DO TESTREAD WITH "CBIN.TXT"        && display this file
  143.                 
  144.                 This example merely displays a file on the screen.
  145. Presumably you would want to do something with the characters inside the
  146. do-while loop, other than just display them.
  147.  
  148.  
  149.         PEEK:  Examine PC memory
  150.         ----
  151.  
  152. To call:        M = "<segment> <offset> [count]"
  153.                 CALL PEEK WITH M
  154.  
  155.                 <segment>:<offset> : address
  156.                 [count] : optional number of bytes to retrieve
  157.  
  158. Return from call:
  159.                 After calling PEEK, M will contain the contents of
  160.                 PC memory address segment:offset.  The number of bytes
  161.                 depends retrieved depends on the optional [count]
  162.                 parameter AND ON THE LENGTH OF THE STRING PASSED IN.
  163.                 
  164.                 Note that the information retrieved overwrites the
  165.                 information passed in.  It is assumed that the information
  166.                 passed in is needed by the routine, not by the user.  
  167.  
  168. Problems and Comments:
  169.                 PEEK is very limited right now, as you need routines
  170.                 to retrieve valid addresses for you that can then be
  171.                 passed to PEEK.  PEEK should have a "mode" in which the
  172.                 information retrieved for you is returned in a form
  173.                 that can then be passed back to PEEK.  Any decent book
  174.                 on BASIC gives many illustrations of the wonderful
  175.                 non-portable tricks that can be done with a properly-
  176.                 written PEEK.
  177.                 Valid dBase addresses can be retrieved with VARPTR.
  178.                 (See below)
  179.  
  180. Example:
  181.                 M = "68c1 d 11"            
  182.                 CALL PEEK WITH M
  183.                 ? M
  184.                 "Hello world"
  185.  
  186.  
  187.         POKE : Fondle PC memory
  188.         ----
  189.  
  190. To call:        CALL POKE WITH "<segment> <offset> <bytes...> [switch]"
  191.  
  192.                 <segment>:<offset> : address
  193.                 <bytes...> : arbitrary number of bytes
  194.                 [switch] : optional:  -d means that <bytes...> are in
  195.                     decimal, -a means ascii, default is hex.
  196.                 (See examples)
  197.                 
  198. No value returned by call.
  199.  
  200. Problems and Comments:
  201.                 POKE suffers from the same problems as PEEK.
  202.                 Also note that PEEK and READ should be very similar
  203.                 in operation; and that POKE and WRITE should match
  204.                 each other as well.
  205.  
  206. Example:        The following examples all POKE "Hello" into the
  207.                 same address in memory:
  208.  
  209.                 CALL POKE WITH "68c1 d 48 65 6c 6c 6e"
  210.                 CALL POKE WITH "68C1 000D H E L L O -A"
  211.                 CALL POKE WITH "68c1 000d 72 101 108 108 111 -d"
  212.                 
  213.                 Note that even when the <bytes...> are in decimal, addresses
  214.                 are always in hexadecimal.  This is the convention in
  215.                 addressing memory.
  216.  
  217.  
  218.         VARPTR -- Take address of dBase variable
  219.         ------
  220.         
  221. Setup:              X = <dBase memvar>
  222.                     CALL VARPTR WITH X
  223.  
  224. No value returned by setup.
  225.  
  226. To use:             Y = <storage for return value>
  227.                     CALL VARPTR WITH Y
  228.  
  229. Notes:                The segment returned is dBase's data segment.  
  230.                     The dBase III Plus memvar symbol table can be found
  231.                     near <segment>:0004 (however, this is not the case
  232.                     in FoxBase+).
  233.  
  234. Example:
  235.                     X = "Hello world"
  236.                     CALL VARPTR WITH X
  237.                     Y = SPACE(10)
  238.                     CALL VARPTR WITH Y
  239.                     ? Y
  240.                     68c1 d
  241.  
  242.                     Y = y + " 11" + SPACE(5)
  243.                     CALL PEEK WITH Y
  244.                     ? Y
  245.                     Hello world
  246.  
  247.  
  248.  
  249.         INTER -- do DOS or BIOS interrupt from dBase (yow!)
  250.         ----- 
  251.         
  252. To use:                Using this one is complex enough that a dBase PRG
  253.                     front end, INTER.PRG, has been provided.  If you
  254.                     want to call INTER.BIN directly, see how INTER.PRG
  255.                     is coded.  Otherwise, just call INTER.PRG or include
  256.                     it in your standard procedure file.  The syntax for
  257.                     call INTER.PRG is:
  258.  
  259.                     DO INTER WITH INTNO,AX,BX,CX,DX
  260.  
  261. Note:                Remember that if one of the "high" registers must be
  262.                     loaded (for instance, BH), the value must be multiplied
  263.                     by 256.  See the sample program, TESTINT.PRG
  264.  
  265. Return:                See the sample program, TESTINT.PRG
  266.                     
  267.  
  268.  
  269.  
  270.         BEEP -- Sound the PC speaker
  271.         ---- 
  272.         
  273. To use:                CALL BEEP WITH <pitch>,<duration>
  274.  
  275. Notes:                See the sample program, BACH.PRG, for an example
  276.                     of how to call beep.  The Bach transcription into
  277.                     computer gibberish comes, more or less, from the
  278.                     Framework II Developer's Toolkit.  The BEEP routines
  279.                     were derived from routines published in the February
  280.                     1987 PC TECH JOURNAL with important corrections in
  281.                     the July 1987 letters column.
  282.  
  283.  
  284.  
  285.         RAND -- Generate pseudorandom number
  286.         ---- 
  287.  
  288. Setup:                X = <dBase NUMERIC memory variable>
  289.                     CALL RAND WITH X
  290.  
  291. To use:                X = <dBase NUMERIC memory variable>
  292.                     CALL RAND WITH X
  293.  
  294. Notes:                Unlike the other BIN routines, RAND takes and
  295.                     returns a single dBase numeric memory variable,
  296.                     and NOT its string representation.
  297.  
  298. Example:
  299.                     . load rand
  300.                     . seed = val(substr(time(),7,2))
  301.                     . call rand with seed
  302.                     . x = 0
  303.                     . call rand with x
  304.                     . ? x
  305.                            346
  306.                     . call rand with x
  307.                     . ? x
  308.                            130
  309.                     . call rand with x
  310.                     . ? x
  311.                          10982
  312.                     . call rand with x
  313.                     . ? x
  314.                           1090
  315.  
  316.  
  317.  
  318.         FILEFIND -- Wildcard searches for files, directories
  319.         -------- 
  320.         
  321. Setup:                F = "(!)<pattern> <attribute> <extra space>"
  322.                     CALL FILEFIND WITH F
  323.  
  324. To use:                F = "<enough space to hold file name>"
  325.                     CALL FILEFIND WITH F
  326.  
  327. Notes:                Each time you call FILEFIND, it will retrieve
  328.                     the next DOS file matching the pattern with which
  329.                     you "seeded" it.  To tell FILEFIND you're starting
  330.                     "seeding" a new pattern, preface with pattern with
  331.                     "(!)".
  332.                     The attributes are passed as string representations
  333.                     of the following numbers:
  334.                     0 - normal files
  335.                     1 - read-only files
  336.                     2 - hidden files
  337.                     4 - system files
  338.                     8 - volume label
  339.                     16 - directory
  340.                     32 - archive
  341.  
  342. Example:            F = "\*.* 16" + SPACE(15)
  343.                     CALL FILEFIND WITH F
  344.                     DO WHILE (F <> "-1")        && until the well runs dry...
  345.                         ? F
  346.                         F = SPACE(15)
  347.                         CALL FILEFIND WITH F
  348.                     ENDDO
  349.  
  350.                     This finds all directories and normal files off
  351.                     the main root.
  352.  
  353.                     F = "(!)" + "*.BIN" + STR(0) + SPACE(15)
  354.                     DO WHILE (F <> "-1")
  355.                         ? F
  356.                         F = SPACE(15)
  357.                         CALL FILEFIND WITH F
  358.                     ENDDO
  359.  
  360.                     Can you figure out what this does?
  361.  
  362.  
  363.  
  364.     SRCHPATH -- Search DOS path for file
  365.     --------
  366.  
  367.     See Russell's SRCHPATH.PRG, and all will be revealed unto you.
  368.  
  369.  
  370.                                 -- Andrew Schulman
  371.                                    6 July 1987
  372.  
  373. P.S.  Again the authors of CBIN implore you to send feedback
  374.       and/or contributions.
  375.  
  376.  
  377.  
  378.                     
  379.  
  380.  
  381.         
  382.