home *** CD-ROM | disk | FTP | other *** search
/ High Voltage Shareware / high1.zip / high1 / DIR4 / T2B120.ZIP / TXT2BIN.DOC < prev    next >
Text File  |  1994-01-04  |  16KB  |  531 lines
  1.            TXT2BIN - Text-To-Binary Conversion Program
  2.                   Version 1.20 (January 3, 1994)
  3.                 Copyright 1992,1993,1994 Bruce Lum
  4.  
  5.  
  6.  
  7. DISCLAIMER
  8. ----------
  9.  
  10. The TXT2BIN program is provided "AS-IS".  You use this program
  11. strictly at your own risk.  No warranty of any kind exists.  The
  12. author is not responsible for any incidental or consequential
  13. damages to your computer or the data stored on it as a result of
  14. misuse or the inability to run the program.  By running TXT2BIN,
  15. you agree to this.
  16.  
  17.  
  18.  
  19. TRADEMARKS
  20. ----------
  21.  
  22. HP, LaserJet, DeskJet and PCL are U.S. registered trademarks of
  23. Hewlett-Packard Company.
  24.  
  25. IBM is a registered trademark of International Business Machines
  26. Corporation.
  27.  
  28. Epson is a registered trademark of Epson America Incorporated.
  29.  
  30.  
  31.  
  32. INTRODUCTION
  33. ------------
  34.  
  35. TXT2BIN is a utility program for the IBM PC (or compatible) that
  36. helps you to create and maintain a binary file by describing the
  37. contents in the form of a text file.
  38.  
  39. In contrast, you could create or modify a binary file with a hex
  40. editor or a debugger.  However, you may restricted to the use of
  41. hexadecimal numbers, in addition to ASCII text.  However, a
  42. binary file is all that you are left with.  Documented changes to
  43. the file exist elsewhere.
  44.  
  45.  
  46. What can you do with TXT2BIN?  Here is an application:
  47.  
  48.     A text file describes the initial settings of a dot-matrix or
  49.     laser printer, with documentation in the file.  TXT2BIN
  50.     translates this text file into the equivalent binary
  51.     information and sends it to the printer.
  52.  
  53.  
  54. With TXT2BIN, you can work with any base (e.g. decimal,
  55. hexadecimal, etc.) that you feel comfortable with.  Any changes
  56. can be accompanied by comments in the text file.  Symbols can
  57. also be used to represent bytes in a more legible way.
  58.  
  59. To use TXT2BIN, all you need is a text editor to describe the
  60. contents of the binary file.  From the text file, TXT2BIN creates
  61. the binary file for you.  If the binary file needs any changes,
  62. just change the text file and run TXT2BIN again.
  63.  
  64.  
  65.  
  66. COMMAND SYNTAX
  67. --------------
  68.  
  69. To run TXT2BIN from the DOS prompt, use the following syntax:
  70.  
  71.     TXT2BIN  [option...]  <textfile>  <target>
  72.  
  73. where:
  74.  
  75.     [option] is one or more special instructions to be used
  76.     during the conversion process;
  77.  
  78.     <textfile> is the name of the file that contains the textual
  79.     representation of the individual bytes in the binary file;
  80.  
  81.     <target> is the name of the file or device that will receive
  82.     the bytes resulting from the conversion process.
  83.  
  84.  
  85.  
  86. THE TEXT FILE
  87. -------------
  88.  
  89. The text file consists of one or more lines (or records) that
  90. describe the contents of the binary file.
  91.  
  92. To create the text file, use a text editor or word processor that
  93. can save files in the ASCII text format.  Non-ASCII files may
  94. produce error messages during the conversion process.
  95.  
  96. You can use any ASCII character whose value falls within the
  97. following ranges (inclusive):
  98.  
  99.     (a) 21 - FF (hexadecimal), or 33 - 255 (decimal);
  100.  
  101.     (b) SPACE:      20 (hex) or 32 (dec);
  102.  
  103.     (c) TAB:        9 (hex/dec);
  104.  
  105.     (d) FORM-FEED:  0C (hex) or 12 (dec)
  106.  
  107.  
  108. Each line in the text file can contain any of the following:
  109.  
  110.     (a) a list of bytes
  111.     (b) a text string
  112.     (c) a comment
  113.     (d) a directive
  114.     (e) a combination of the above
  115.     (f) a blank line
  116.  
  117.  
  118. The first four (4) types are discussed in detail below.
  119.  
  120.  
  121.  
  122. Representation of Individual Bytes
  123. ----------------------------------
  124.  
  125. Each byte must be composed of alphabetic and/or numeric
  126. characters conforming to the radix (base) that is currently in
  127. effect.
  128.  
  129.     Examples:
  130.  
  131.         If the radix is 2, then the characters that
  132.         make up the byte can only be 0 and 1.
  133.  
  134.         If the radix is 8, then the characters that
  135.         make up the byte can only be from 0 to 7 (inclusive).
  136.  
  137.  
  138. With a radix greater than 10, use the alphabetic characters
  139. (starting from the letter A) to represent the digits higher than
  140. 9.
  141.  
  142.     Examples:
  143.  
  144.         If the radix is 12, then the characters that make up
  145.         the byte can only be from 0 to 9 (inclusive), and the
  146.         letters A and B (to represent 10 and 11, respectively).
  147.  
  148.         If the radix is 16, then the characters that make up
  149.         the byte can only be from 0 to 9 (inclusive) and from A
  150.         to F (inclusive).  The letters from A to F will represent
  151.         the digits from 10 to 15, respectively.
  152.  
  153.  
  154. Regardless of the radix, the total value of each byte must be
  155. between 0 to 255 (inclusive).
  156.  
  157. Leading zeroes are not required, and you must have spaces between
  158. the bytes.
  159.  
  160.  
  161.     Examples (all representing a set of identical bytes):
  162.  
  163.         1B 26 6C 31 4F          (radix=16: HEXADECIMAL)
  164.  
  165.         27 38 108 49 79         (radix=10: DECIMAL)
  166.  
  167.         33 46 154 61 117        (radix=8: OCTAL)
  168.  
  169.         00011011 00100110 01101100 00110001 01001111
  170.                                 (radix=2: BINARY !!)
  171.  
  172.  
  173.  
  174. Text Strings
  175. ------------
  176.  
  177. The text string enclosed by a pair of double quote characters.
  178.  
  179.     Examples:
  180.  
  181.         "%-12345X"
  182.  
  183.         "A text string"
  184.  
  185.  
  186. Escape sequences may also be part of a text string.
  187.  
  188.     Example:
  189.  
  190.         "\fA text string\n"
  191.  
  192.  
  193. (For more details, see the following section called "Escape
  194. Sequences in Text Strings".)
  195.  
  196.  
  197. For double quotes, precede them with a backslash character (\).
  198. For example, if the text string is
  199.  
  200.         PARM="CD-ROM AVAILABLE";
  201.  
  202. then you must set it up as follows:
  203.  
  204.         "PARM=\"CD-ROM AVAILABLE\";"
  205.  
  206.  
  207.  
  208. Escape Sequences in Text Strings
  209. --------------------------------
  210.  
  211. The escape sequence allows certain hard-to-get characters (such
  212. as control codes) to be represented.  These characters usually
  213. cannot be entered from within the text editor or word processor.
  214.  
  215. An escape sequence starts with the backslash character (\) and is
  216. followed by one or more octal, hexadecimal or ASCII characters.
  217.  
  218. Here is the list of escape sequences that TXT2BIN currently
  219. supports:
  220.  
  221.  
  222.     Sequence    Value   Char    Description
  223.  
  224.     \a          0x07    BEL     Bell (Alert)
  225.     \b          0x08    BS      Backspace
  226.     \f          0x0C    FF      Formfeed
  227.     \n          0x0A    LF      Newline
  228.     \r          0x0D    CR      Carriage return
  229.     \t          0x09    HT      Horizontal tab
  230.     \v          0x0B    VT      Vertical tab
  231.     \'          0x27    '       Single quote (apostrophe)
  232.     \?          0x3F    ?       Question mark
  233.     \"          0x22    "       Double quote
  234.     \\          0x5C    \       Backslash
  235.  
  236.     \Onnn               (any)   'nnn' is a string of up to 3
  237.                                 octal digits
  238.  
  239.     \Xhh                (any)   'hh' is a string of hex digits
  240.     \xhh                (any)   'hh' is a string of hex digits
  241.  
  242.     \nnn                (any)   'nnn' is a string of up to 3
  243.                                 octal digits
  244.  
  245.  
  246. Examples:
  247.  
  248.     "\aFatal error!\r\n"
  249.  
  250.     "The \"right\" way of using double-quotes"
  251.  
  252.     "The ESC code is represented by \033"
  253.     "The ESC code is represented by \x1B"
  254.     "The ESC code is represented by \X1B"
  255.     "The ESC code is represented by \O033"
  256.  
  257.  
  258.  
  259. Comments
  260. --------
  261.  
  262. A comment starts with a semi-colon.  Anything to the right of the
  263. semi-colon is completely ignored by TXT2BIN.  The comment can
  264. start anywhere on the line.
  265.  
  266.     Example:
  267.  
  268.         ;-------------------------------------------------
  269.         ; These three entire lines are ignored by TXT2BIN
  270.         ;-------------------------------------------------
  271.  
  272.         27 "1@"     ; This part of the line will be ignored
  273.  
  274.  
  275.  
  276. Directives
  277. ----------
  278.  
  279. These are instructions asking TXT2BIN to take some form of
  280. action.  Although directives can appear anywhere in the text
  281. file, and as often as required, only one directive is allowed on
  282. a line.
  283.  
  284. A directive starts with a period (.) and is followed by a special
  285. keyword.  Other parameters may follow the keyword.
  286.  
  287.  
  288. This version of TXT2BIN supports the following directives:
  289.  
  290.     (a) DEFINE
  291.     (b) INCLUDE
  292.     (c) RADIX
  293.  
  294. These directives are described below.
  295.  
  296.  
  297.  
  298. .DEFINE  Symbol  Replacement
  299.  
  300.     What this means to TXT2BIN is "After this line, if you ever
  301.     encounter <Symbol> later in the text file (except within a
  302.     comment), replace it with the contents of Replacement".  This
  303.     is useful if one or more bytes can be commonly identified by
  304.     a symbolic name.
  305.  
  306.     The name of the symbol, "Symbol", must start with an
  307.     alphabetic character (A-Z, a-z), followed by a mixture of
  308.     alphabetic, numeric (0-9), and underscore (_) characters.
  309.     The maximum length of a symbol is 32 characters.
  310.  
  311.     Within the name of a symbol, an alphabetic letter can either
  312.     be lowercase or uppercase; there is no distinction.  Thus,
  313.     the symbols "Esc" and "ESC" are considered as identical.
  314.  
  315.     "Replacement" is a sequence of bytes, strings, and symbols
  316.     that you intend to replace <Symbol> with during the
  317.     conversion process.  You may also include comments.  The
  318.     maximum length of "Replacement" is 255 characters (including
  319.     comments).
  320.  
  321.     Example:
  322.  
  323.         .DEFINE Esc   27        ; Replace <Esc> with 27
  324.         .DEFINE CR_LF 13 10     ; Replace <CR_LF> with 13 10
  325.  
  326.             <Esc> "&l1T" <CR_LF>
  327.  
  328.         ; TXT2BIN replaces <Esc> and <CR_LF>, so that the
  329.         ; line will be processed as:
  330.         ;
  331.         ;     27 "&l1T" 13 10
  332.  
  333.  
  334. .INCLUDE  FileName
  335.  
  336.     This directive allows you to insert lines from a specified
  337.     file into your text file.
  338.  
  339.     When this directive is encountered, TXT2BIN reads and
  340.     processes the lines in the file called "FileName".  After all
  341.     the lines are processed, TXT2BIN continues with the line
  342.     following the INCLUDE directive.
  343.  
  344.     The two files DEFINES.10 and DEFINES.16 (contained in your
  345.     TXT2BIN package) defines the list of ASCII control characters
  346.     (in decimal and the other in hexadecimal, respectively).
  347.     Instead of having to type the definitions repeatingly for all
  348.     your text files, you can use the INCLUDE directive to refer
  349.     to one of the two files.
  350.  
  351.     Examples:
  352.  
  353.         .INCLUDE  defines.10
  354.  
  355.         .INCLUDE  Z:\PUBLIC\TXT2BIN\INCLUDE\defines.16
  356.  
  357.  
  358. .RADIX nn
  359.  
  360.     This changes the radix (number base) to any value between 2
  361.     to 36, inclusive.  'nn' is the value of the desired radix, in
  362.     decimal.  The default radix value is 10 (that is, the decimal
  363.     numbering system).
  364.  
  365.     Examples:
  366.  
  367.         .RADIX 10   ; Change base to 10 (DECIMAL)
  368.  
  369.         .RADIX 16   ; Change base to 16 (HEXADECIMAL)
  370.  
  371.         .RADIX 8    ; Change base to 8  (OCTAL)
  372.  
  373.         .RADIX 2    ; Change base to 2  (BINARY)
  374.  
  375.  
  376.  
  377. ERROR MESSAGES
  378. --------------
  379.  
  380. During TXT2BIN's processing of the contents of the text file,
  381. messages may appear as a result of one or more encountered
  382. errors.  Each message will also identify the exact location of
  383. the error by telling you the line and column number.
  384.  
  385.  
  386. Error messages can also be redirected to a file or device.  Here
  387. are some examples:
  388.  
  389.     TXT2BIN filename.txt filename.bin >error.msg
  390.  
  391.     TXT2BIN filename.txt filename.bin >NUL
  392.  
  393.     TXT2BIN filename.txt filename.bin >LPT1
  394.  
  395.  
  396. The complete list of error messages can be found in the file
  397. called TXT2BIN.MSG that comes with the TXT2BIN program.
  398.  
  399.  
  400.  
  401. COMMAND-LINE OPTIONS
  402. --------------------
  403.  
  404. Only one option is currently available in TXT2BIN that you can
  405. use during the conversion process.
  406.  
  407.     -q      QUIET switch.  This option eliminates all status and
  408.             error messages that are normally displayed on the
  409.             screen.
  410.  
  411.                 Example:
  412.  
  413.                     TXT2BIN -q INFILE.TXT OUTFILE.BIN
  414.  
  415.  
  416.  
  417. EXAMPLE
  418. -------
  419.  
  420. The following text file contains a set of commands that
  421. initializes a Hewlett-Packard LaserJet IIISi printer.
  422.  
  423. (This can be found in the file called EXAMPLE.HPL that comes with
  424. the TXT2BIN program.)
  425.  
  426.  
  427.     ;-----------------------------------------------------------
  428.     ; EXAMPLE.HPL
  429.     ;
  430.     ; This text file contains the instructions to initialize a
  431.     ; HP LaserJet(tm) IIISi (or 4) printer
  432.     ;
  433.     ; (Use the TXT2BIN program to create the binary image file)
  434.     ;
  435.     ; HP and LaserJet are U.S. registered trademarks of
  436.     ; Hewlett-Packard Company.
  437.     ;-----------------------------------------------------------
  438.  
  439.         .RADIX 16                   ; Set base to hexadecimal
  440.  
  441.         .INCLUDE defines.16         ; Include list of control
  442.                                     ; codes (in hexadecimal)
  443.  
  444.     ;--------------------------------------
  445.     ; Job Control
  446.     ;--------------------------------------
  447.     <Esc> "%-12345X"                ; Universal Exit Language /
  448.                                     ;   Start of PJL
  449.  
  450.     "@PJL ENTER LANGUAGE=PCL" <LF>  ; Enter PCL mode
  451.  
  452.     <Esc> "E"                       ; Reset the printer
  453.     <Esc> "&l1X"                    ; Number of copies = 1
  454.     <Esc> "&l1S"                    ; Duplex, long-edge binding
  455.  
  456.     ;--------------------------------------
  457.     ; Page Control
  458.     ;--------------------------------------
  459.     <Esc> "&l0O"                    ; Page orientation: Portrait
  460.     <Esc> "&l2A"                    ; Page size: Letter
  461.     <Esc> "&l6D"                    ; Line spacing: 6 lines/inch
  462.     <Esc> "&l1E"                    ; Select upper output bin
  463.     <Esc> "&l60F"                   ; Text length: 60 lines
  464.     <Esc> "&l1H"                    ; Main paper source feed
  465.  
  466.  
  467.  
  468. DISTRIBUTION
  469. ------------
  470.  
  471. You may freely distribute the TXT2BIN package, provided that the
  472. following files are distributed together:
  473.  
  474.     TXT2BIN.EXE     The TXT2BIN program
  475.     TXT2BIN.DOC     The documentation file for TXT2BIN
  476.     TXT2BIN.MSG     List of error messages from TXT2BIN
  477.  
  478.     README.1ST      Installation procedure, list of latest
  479.                     changes, and any last-minute information
  480.                     (this file)
  481.  
  482.     DEFINES.10      List of ASCII control character definitions
  483.                     (in decimal or base 10)
  484.  
  485.     DEFINES.16      List of ASCII control character definitions
  486.                     (in hexadecimal or base 16)
  487.  
  488.     EXAMPLE.ESN     Text file to reset Epson LQ-2500 printer
  489.     EXAMPLE.HPD     Text file to reset HP DeskJet printer
  490.     EXAMPLE.HPL     Text file to reset HP LaserJet printer
  491.     EXAMPLE.IBM     Text file to reset IBM Proprinter printer
  492.  
  493.  
  494.     BIN2TXT.EXE     A supplemental program that converts a binary
  495.                     file into a textual representation
  496.  
  497.     BIN2TXT.DOC     The documentation file for BIN2TXT
  498.  
  499.  
  500.  
  501. CONTRIBUTIONS
  502. -------------
  503.  
  504. If you find TXT2BIN useful, please send $10.00 (in U.S. funds) or
  505. $12.00 (in Canadian funds) to the author at the postal address
  506. below.  If you have access to Compuserve or Internet, please
  507. include your ID/address; you will be notified of any updates or
  508. new products.
  509.  
  510. Your support is greatly appreciated.
  511.  
  512.  
  513.  
  514. CORRESPONDENCE
  515. --------------
  516.  
  517. If you have any problems, questions, or any type of feedback,
  518. electronic mail may be sent to the author (Bruce Lum) at the
  519. following addresses:
  520.  
  521.     Compuserve:     72727,3104
  522.     Internet:       72727.3104@compuserve.com
  523.  
  524.  
  525. If you are using the postal service, the address is:
  526.  
  527.     Bruce Lum
  528.     P.O. Box 5098, Station A
  529.     Toronto, Ontario
  530.     CANADA  M5W 1N4
  531.