home *** CD-ROM | disk | FTP | other *** search
/ Current Shareware 1994 January / SHAR194.ISO / textutil / txt2bin.zip / TXT2BIN.DOC next >
Text File  |  1993-10-21  |  8KB  |  307 lines
  1.            TXT2BIN - Text-To-Binary Conversion Program
  2.  
  3.                   Version 1.13 (October 21, 1993)
  4.  
  5.                   Copyright 1992,1993 Bruce Lum
  6.  
  7.  
  8.  
  9. DISCLAIMER
  10. ----------
  11.  
  12. The TXT2BIN program is provided "AS-IS".  You use this program
  13. strictly at your own risk.  No warranty of any kind exists.  The
  14. author is not responsible for any incidental or consequential
  15. damages to your computer or the data stored on it as a result of
  16. misuse or the inability to run the program.  By running TXT2BIN,
  17. you agree to this.
  18.  
  19.  
  20.  
  21. Trademarks
  22. ----------
  23.  
  24. LaserJet is a trademark of Hewlett-Packard Company.
  25.  
  26.  
  27.  
  28. Introduction
  29. ------------
  30.  
  31. TXT2BIN is a utility that helps you to create and maintain binary
  32. files with the use of plain text files.
  33.  
  34. With TXT2BIN, you can avoid the use of hex editors and debuggers.
  35. Hex editors tend to like working with hexadecimal characters.
  36. Debuggers may allow a mixture of hexadecimal characters and text
  37. strings; in the end, however, you are left with only the binary
  38. image.
  39.  
  40. To use TXT2BIN, all you need is a text editor to describe the
  41. contents of the binary file.  From the text file, TXT2BIN creates
  42. the binary file for you.  If the binary file needs any changes,
  43. just change the text file and run TXT2BIN again.
  44.  
  45. Your text file can even contain comments for documentation
  46. purposes.
  47.  
  48.  
  49. Below is the description of how to use TXT2BIN, from creating the
  50. text file to actually running TXT2BIN to create the binary file.
  51. Error messages are also described.  The examples all refer to an
  52. area where TXT2BIN may become useful: the sending of customized
  53. commands to a printer.
  54.  
  55.  
  56.  
  57. The Text File
  58. -------------
  59.  
  60. Each line in the text file can contain the following:
  61.  
  62.  
  63.     1.  The hexadecimal representation of the bytes.  Each byte
  64.         must consist of a pair of hexadecimal characters (0-9,
  65.         A-F, a-f).  You may optionally insert spaces between
  66.         bytes.
  67.  
  68.             Examples:       1B 26 6C 31 4F
  69.  
  70.                             1B 266C31 4F
  71.  
  72.  
  73.     2.  A text string enclosed by double quotes.
  74.  
  75.             Example:        "%-12345X"
  76.  
  77.         Escape sequences may also be part of a text string.  See
  78.         the section later in this file called "Escape Sequences"
  79.         for more details.
  80.  
  81.     3.  A comment which starts with a semi-colon.  The comment
  82.         can start anywhere on the line.  Anything to the right of
  83.         the semi-colon is ignored.
  84.  
  85.             Example:        ; This is a comment that TXT2BIN will
  86.                             ; ignore
  87.  
  88.  
  89.     4.  A combination of the above.
  90.  
  91.             Example:        1B "%-12345X"   ; Start of print job
  92.                             1B "E"          ; Reset printer
  93.  
  94.  
  95.     5.  A blank line.
  96.  
  97.  
  98. In this version, a single line is limited to the maximum of 254
  99. characters.
  100.  
  101.  
  102. The following example is part of a text file which contains the
  103. instructions for initializing a Hewlett-Packard LaserJet IIP
  104. printer:
  105.  
  106.     ;--------------------------------------
  107.     ; Reset the printer
  108.     ;--------------------------------------
  109.     1B "E"
  110.  
  111.     ;--------------------------------------
  112.     ; Number of copies = 1
  113.     ;--------------------------------------
  114.     1B "&l1X"
  115.  
  116.     ;--------------------------------------
  117.     ; Paper source: MP Tray
  118.     ;--------------------------------------
  119.     1B "&l1H"
  120.  
  121.  
  122.  
  123. Escape Sequences
  124. ----------------
  125.  
  126. The escape sequence allows certain hard-to-get characters (e.g.
  127. control codes) to be represented.  Usually, these characters
  128. cannot easily be entered within a text editor.
  129.  
  130. An escape sequence is started with the backslash character (\)
  131. and is followed by one or more octal, hexadecimal or ASCII
  132. characters.
  133.  
  134. Here is the list of escape sequences that TXT2BIN currently
  135. supports:
  136.  
  137.  
  138.     Sequence    Value   Char    Description
  139.  
  140.     \a          0x07    BEL     Bell (Alert)
  141.     \b          0x08    BS      Backspace
  142.     \f          0x0C    FF      Formfeed
  143.     \n          0x0A    LF      Newline
  144.     \r          0x0D    CR      Carriage return
  145.     \t          0x09    HT      Horizontal tab
  146.     \v          0x0B    VT      Vertical tab
  147.     \'          0x27    '       Single quote (apostrophe)
  148.     \?          0x3F    ?       Question mark
  149.     \"          0x22    "       Double quote
  150.     \\          0x5C    \       Backslash
  151.  
  152.     \Onnn               (any)   'nnn' is a string of up to 3
  153.                                 octal digits
  154.  
  155.     \Xhh                (any)   'hh' is a string of hex digits
  156.     \xhh                (any)   'hh' is a string of hex digits
  157.  
  158.     \nnn                (any)   'nnn' is a string of up to 3
  159.                                 octal digits
  160.  
  161.  
  162. Examples:
  163.  
  164.     "\aFatal error!\r\n"
  165.  
  166.     "The \"right\" way of using double-quotes"
  167.  
  168.     "The ESC code is represented by \033"
  169.     "The ESC code is represented by \x1B"
  170.     "The ESC code is represented by \X1B"
  171.     "The ESC code is represented by \O033"
  172.  
  173.  
  174.  
  175. Converting the Text File to a Binary Image
  176. ------------------------------------------
  177.  
  178. The command to convert your text file has the following syntax:
  179.  
  180.     TXT2BIN  textfile  binaryfile
  181.  
  182. where:
  183.  
  184.     'textfile'      - your text file with the hexadecimal bytes
  185.                       and text strings;
  186.  
  187.     'binaryfile'    - the binary file to be created
  188.  
  189.  
  190.  
  191. Error Messages
  192. --------------
  193.  
  194. During TXT2BIN's validation of the contents of the text file,
  195. messages may appear as a result of an encountered error.  These
  196. messages will indicate the line and column numbers of where the
  197. errors are located.
  198.  
  199. The error messages may be redirected to a file or to another
  200. device other than the console screen.
  201.  
  202. Examples:
  203.  
  204.     TXT2BIN filename.txt filename.bin >error.msg
  205.  
  206.     TXT2BIN filename.txt filename.bin >NUL
  207.     TXT2BIN filename.txt filename.bin >LPT1
  208.  
  209.  
  210.  
  211. The following is the list of possible messages:
  212.  
  213.  
  214.     Incomplete hexadecimal character at column NNNNN
  215.  
  216.         Only the first half of a hexadecimal character was
  217.         specified.  Either the second half is missing, or an
  218.         invalid character was encountered.
  219.  
  220.  
  221.     Incomplete hexadecimal character at the end of this line
  222.  
  223.         The end of the line was unexpectedly encountered before
  224.         the hexadecimal character was completed.
  225.  
  226.  
  227.     Invalid character at column NNNNN
  228.  
  229.         A non-hexadecimal character was encountered.  The valid
  230.         range of characters are:
  231.  
  232.             -   from 0 to 9 (inclusive);
  233.             -   from A to F (inclusive);
  234.             -   from a to f (inclusive).
  235.  
  236.  
  237.     Non-terminated string found
  238.  
  239.         A text string did not end properly with a double-quote
  240.         (").
  241.  
  242.  
  243.     Numeric constant too big at column NNNNN
  244.  
  245.         Within a text string, an octal value (\Onnn or \nnn) was
  246.         found to be more than 255 (or \O377 or \377).
  247.  
  248.  
  249.     Unable to open input file
  250.  
  251.         The source text file could not be opened.  Possible
  252.         causes are:
  253.  
  254.             (1) the file name was misspelled;
  255.  
  256.             (2) the file exists in another drive/directory.
  257.  
  258.  
  259.     Unable to open output file
  260.  
  261.         The target binary file could not be opened.  Possible
  262.         causes are:
  263.  
  264.             (1) the file already exists, with its attribute set
  265.                 as READ-ONLY;
  266.  
  267.             (2) the file is the name of a directory or volume
  268.                 label.
  269.  
  270.  
  271.  
  272. Distribution
  273. ------------
  274.  
  275. You may freely distribute this program, provided that the
  276. following two files are distributed together:
  277.  
  278.     TXT2BIN.DOC     (The documentation file)
  279.     TXT2BIN.EXE     (The program file)
  280.  
  281.  
  282.  
  283. Contributions
  284. -------------
  285.  
  286. If you find TXT2BIN useful, please send $10.00 to the author at
  287. the postal address below.  Your support is greatly appreciated.
  288.  
  289.  
  290.  
  291. Correspondence
  292. --------------
  293.  
  294. If you have any problems, questions, or any type of feedback,
  295. electronic mail may be sent to the author (Bruce Lum) at the
  296. following locations:
  297.  
  298.     Compuserve:     72727,3104
  299.     Internet:       72727.3104@compuserve.com
  300.  
  301.  
  302. If you are using the postal service, the address is:
  303.  
  304.     P.O. Box 5098, Station A
  305.     Toronto, Ontario
  306.     CANADA  M5W 1N4
  307.