home *** CD-ROM | disk | FTP | other *** search
/ 8bitfiles.net/archives / archives.tar / archives / canada-remote-systems / c64 / utils / ace14-bc.doc < prev    next >
Encoding:
Text File  |  2019-04-13  |  7.0 KB  |  117 lines
  1. ACE-128/64 BCODE/UNBCODE DOCUMENTATION  for version 1.00   [June 29, 1995]
  2. ------------------------------------------------------------------------------
  3. 1. INTRODUCTION
  4.  
  5. This document contains the documentation for the "bcode" and "unbcode"
  6. programs for ACE.  There are also (more advanced) versions of these programs
  7. available in the C programming language for Unix and MS-DOS environments.
  8.  
  9. These programs allow you to encode binary data into a text format that can
  10. be e-mailed or posted to USENET newsgroups.  Functionally, they are quite
  11. similar to the uuencode/uudecode standard Unix utilities, except that these
  12. programs can use a different encoding technique from "uucode" which allow
  13. for the automatic splitting, reordering, and incremental reassembly of
  14. multiple file segments for long files, and provide CRC-32 and size error
  15. checking on each encoded segment.  These ACE programs will eventually be
  16. extended to the level of the C-language programs, which can handle uucode
  17. and hexcode formats in addition to bcode format.
  18.  
  19. 2. BCODE PROGRAM
  20.  
  21. bcode [-help] [-v] [-u] [-m] [-l max_line_count] [filename ...]
  22.  
  23. Encode the given files into BCODE format.  This format, like uuencoded
  24. format, is used for transmitting binary information through a text-only
  25. medium.  The "-help" flag is used to display "usage" information to stderr.
  26. The command will exit after encountering the flag, before doing any work.
  27.  
  28. The "-v" flag means to give "verbose" information about what is going on.
  29. The "-u" and "-m" flags instruct bcode to output in either Unix (Ascii-Lf)
  30. or MESS-DOS (Ascii-CrLf) format.  The default is good ole Petscii.
  31.  
  32. The "-l" flag and value allows you to specify the maximum number of bcoded
  33. lines to include in each segment of the bcoded data.  When this flag is
  34. used, output is sent to special output files rather than to stdout (where it
  35. is usually sent).  One segment is sent to each special output file.  These
  36. special output files are named after the file being encoded, appended with a
  37. ".b" followed by the at-least-two digit segment number.  If the full name
  38. would exceed 16 characters, the "basename" is truncated.  If the source file
  39. includes a path, the path is ignored and the special file is put in the
  40. current directory.  For example,
  41.  
  42. bcode -l 800 b:junkfile
  43.  
  44. would put the bcoded segment data into "junkfile.b01", "junkfile.b02", ...,
  45. "junkfile.b99", "junkfile.b100", etc., in the current directory.  Each line
  46. of bcoded data contains 72 characters (which represent 54 raw data bytes),
  47. so 800 lines will produce 59200 bytes of output (counting CR and LF at the
  48. end of each line), which is a good size for posting or for mailing to
  49. brain-damaged mailers (under 64K).  The max_line_count does not include the
  50. two control lines in the bcode format.
  51.  
  52. If you include filenames on the command line, then input will be taken from
  53. them in turn.  Otherwise, input will NOT be taken from stdin and no work
  54. will be done.  You may include many filenames (and associated aliases) on a
  55. command line to create a BCODE archive (which should be suffixed ".bca").
  56.  
  57. If you specify that a file is to be broken into multiple segments for
  58. encoding, then last segment may be of zero length.  This is not an error and
  59. will be decoded correctly, although it may be a bit of a pain.
  60.  
  61. 3. UNBCODE PROGRAM
  62.  
  63. unbcode [-help] [-i] [-v] [-d] [filename ...]
  64.  
  65. This is a full-blown BCODE decoder.  It will read BCODE data from files
  66. named in any order and reconstruct the original binary files that were
  67. encoded using the BCODE program above.  If the "-help" flag is specified,
  68. usage information will be given and the program will exit.
  69.  
  70. The three other flags are used to request different levels of operational
  71. information: informative, verbose, and debugging.  Informative messages
  72. include when a file is completely pieced back together, verbose information
  73. includes when a file is opened or closed, and debugging information includes
  74. a dump of the internal "have" table that keeps track of which segments of
  75. which files the decoder currently has.  Currently, informative and verbose
  76. information is hard-wired on.
  77.  
  78. Intermediate segments are decoded immediately and placed into temporary
  79. files in the current directory with names like "0BC00001", with different
  80. numbers.  These files are created and deleted as needed.  Between runs, if
  81. there are any files that have not yet been completely pieced together, the
  82. "have" information is saved into "0BC-STAT", which can be listed to see what
  83. is in the temporary files and which segments of the files are missing.  An
  84. example of its contents would be:
  85.  
  86. 00001-00001  beg  0000001223  0BC00002  filea
  87. 00001-00001  beg  0000540122  0BC00004  fileb
  88. 00003-00003  mid  0000002832  0BC00001  fileb
  89. 00005-00005  end  0000000023  0BC00003  fileb
  90.  
  91. The first two columns with the dash between indicate the range of segment
  92. numbers that are contained in the temporary file.  The next column gives the
  93. interpretation of the temporary file, indicating if it is the beginning,
  94. middle, or the end of the complete file being decoded.  The next column
  95. gives the length of the temporary data (used for error recovery).  The next
  96. column gives the name of the temporary file, and the final column gives the
  97. name of the file that the "fragment" belongs to.
  98.  
  99. The fact that the status of decoding is kept between runs means that you
  100. don't have to have all of the segments of the final file(s) present at any
  101. one run.  Error checking is performed on each segment as it is being
  102. decoded, and if an error is encoutered, the segment will be ignored.
  103. Because of the "incremental decode" feature, you can obtain correct copies
  104. of the segments that were found to be in error before and run them through
  105. again.
  106.  
  107. This program will recover from all errors in the input data, including one
  108. tricky case that the C unbcode program released earlier before could not.
  109. The only ways that things can get fowled up are if unbcode has access
  110. problems to the temporary files, or if you STOP the program at an
  111. inopportune time.  To recover from all errors, you just have to delete all
  112. of the "0BC" temporary files, including "0BC-STAT".
  113.  
  114. During decoding, this program will overwrite existing "0BC" files or files
  115. being decoded.
  116. ------------------------------------------------------------------------END---
  117.