home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 January / usenetsourcesnewsgroupsinfomagicjanuary1994.iso / sources / misc / volume28 / cfx / part02 / cfx.doc < prev    next >
Text File  |  1992-02-02  |  18KB  |  457 lines
  1.                      CFX - Cp/m File eXpress
  2.                          User's Manual
  3.              Copyright 4 January 92 by Carson Wilson
  4.  
  5.  
  6.                           - CONTENTS -
  7.  
  8.      1  PURPOSE.
  9.      2  USAGE.
  10.           2.1  Invocation.
  11.                2.1.1  Help Screen.
  12.                2.1.2  File Specification
  13.                2.1.3  Command Line Options.
  14.                     2.1.3.0  Option B - Brief Output Only.
  15.                     2.1.3.1  Option C - Monitor COMn for Carrier.
  16.                     2.1.3.2  Option D - Disk Output.
  17.                     2.1.3.3  Option I - Display File Info Only.
  18.                     2.1.3.4  Option M - Library Member
  19.                              Specification.
  20.                     2.1.3.5  Option N - Don't Uncompress Library
  21.                              Files.
  22.                     2.1.3.6  Option P - Prompt Before Processing
  23.                              Files.
  24.                     2.1.3.7  Option T - Maximum Minutes Allowed.
  25.                     2.1.3.8  Option W - Wait After Last File.
  26.                2.1.4  Combined Command Lines.
  27.           2.2  Output Files to Screen.
  28.           2.3  Errors.
  29.      3  APPLICATION NOTES.
  30.           3.1  BBS Usage.
  31.           3.2  Local Usage.
  32.      4  KNOWN BUGS.
  33.      5  COPYRIGHT.
  34.      6  DEVELOPMENT OF CFX.
  35.      7  ABOUT THE AUTHOR.
  36.  
  37.  
  38.                             ---------
  39.  
  40. 1  PURPOSE.
  41.  
  42. As its name suggests, CFX is a tool intended to allow quick 
  43. access to CP/M files.  While CFX will operate on standard ASCII 
  44. files, its main strength is its ability access files stored with 
  45. the special archiving and compression methods native to the CP/M 
  46. operating system.  Specifically, CFX can handle files compressed 
  47. with Roger Warren's LZH utilities, Steve Greenberg's CRUNCH 
  48. utilities, "squeezed" files, and archives built using Gary 
  49. Novosielski's Library definition.  
  50.  
  51. Typically, CP/M files stored using these protocols can be 
  52. identified by the three letter file extent as follows:
  53.  
  54.      Extent   Storage method
  55.      ------   --------------
  56.      .?Y?     LZH compression
  57.      .?Z?     Crunched
  58.      .?Q?     Squeezed
  59.      .LBR     Library
  60.  
  61. Notes:
  62.   1. Much of what follows applies only to the MSDOS version of
  63.      CFX.  If you are using CFX on a Unix system, please refer to
  64.      the file cfx.1 or cfx.man for usage information.
  65.  
  66.   1. Library members themselves may be stored under one of the 
  67.      above methods (e.g., crunched library members are common).  
  68.      CFX can extract compressed library members 
  69.      directly to screen or disk.  It can also process library 
  70.      members which are themselves libraries in one step.  
  71.      However, CFX cannot presently extract members from 
  72.      compressed library files in a single step; you must first 
  73.      run CFX on the compressed library file and then invoke CFX 
  74.      again on the uncompressed library file to access library 
  75.      members.
  76.  
  77.   2. Though LZH, crunched, and squeezed files usually have the 
  78.      extents mentioned above, they are more reliably identified 
  79.      by means of a unique signature at the start of the file.  
  80.      CFX uses this signature to identify the compression method 
  81.      in all cases.  Following the signature check, CFX 
  82.      additionally uses the following standard file extensions to 
  83.      identify files which cannot be displayed to the screen:
  84.  
  85.      .OBJ, .COM, .EXE, .BIN, .ARC, .ARK, .ZIP, .REL, .SLR, .CFG, 
  86.      .SCN, .LBR, .ZDK, .OVR, .Z3T, .CHN, .CIM, .3OM, .4OM, .T4C, 
  87.      .DAT, .ZRL
  88.  
  89.      You can add or remove entries from this list of extensions 
  90.      using a binary file patcher.  The default extensions reside 
  91.      at or near offset 53A0h in CFX.EXE (compiled MSDOS version 
  92.      only), and the last few entries are all ".ZRL"  By overwriting 
  93.      a ZRL entry with an extension of your choosing, you can prevent 
  94.      CFX from displaying files and library members of this type.  
  95.      To allow display of one of the above file types, simply 
  96.      overwrite its entry with one of the other extensions from the 
  97.      list.
  98.  
  99.   3. CFX cannot access members of .ARC, .ZIP, .ZOO, or other 
  100.      common MSDOS file archives.  Plenty of utilities are already 
  101.      available for this purpose.
  102.  
  103.  
  104. 2  USAGE.
  105. z
  106.      2.1  Invocation.
  107.  
  108. CFX is invoked as:
  109.  
  110.      CFX [option ...] [afn ...]
  111.  
  112. where CFX is the name of the CFX executable file.
  113.  
  114.           2.1.1  Help Screen.
  115.  
  116. If no command line parameters are given, the following help 
  117. screen appears:
  118.  
  119. CFX - Cp/m File eXpress, Version x.x, Copr. 1992 by Carson Wilson
  120.   Usage:
  121.         CFX [option ...] afn ...
  122.   Options:
  123.         /b       - brief output only
  124.         /c n     - monitor COMn for carrier
  125.         /d       - disk output
  126.         /i       - display directory information
  127.         /m "afn" - library member specification
  128.         /n       - don't uncompress library members
  129.         /p       - prompt before processing files
  130.         /t n     - maximum minutes allowed
  131.         /w       - wait after last file
  132.  
  133. The "/" character in the above help screen is the current MSDOS 
  134. "switch" character, and may change depending on your 
  135. installation.
  136.  
  137.           2.1.2  File Specification
  138.  
  139. CFX can be used on one or many files at once, depending on the 
  140. command line arguments it is invoked with.  File compression and 
  141. archiving methods are detected "on the fly" by CFX, and the 
  142. proper decompression or library access operations 
  143. performed as needed.  This makes CFX suitable for use as an 
  144. extension to many existing MSDOS applications, such as file 
  145. viewers or BBS programs (see USAGE EXAMPLES, below).
  146.  
  147. Files can be specified using single or multiple ambiguous or 
  148. unambiguous filespecs, and filespecs may include path 
  149. information.  If command line options are also given, file 
  150. specifications must appear LAST on the command line.  When 
  151. specifying library files, the .LBR extent is optional.
  152.  
  153. Examples:
  154.  
  155. Command                           Results
  156. -------                           -------
  157. CFX *.dzc                         View all files in current 
  158.                                   directory with extension "DZC".
  159.  
  160. CFX a:\backup\test.bat            View TEST.BAT in directory 
  161.                                   BACKUP on drive A:.
  162.  
  163. CFX *.lbr ..\*.lbr                View all files with extension 
  164.                                   "LBR" in the current and parent 
  165.                                   directories.
  166.  
  167. CFX mylbr                         View MYLBR.LBR in current 
  168.                                   directory.
  169.  
  170.  
  171.           2.1.3  Command Line Options.
  172.  
  173. CFX command line options are specified using the current MSDOS 
  174. "switch" character (normally "/"), or "-" under Unix systems.  
  175. Under MSDOS, to specify more than one option you must use the 
  176. switch character once before each option.  Options must come 
  177. BEFORE file specifications (if any) in the command line, [and 
  178. under MSDOS, MUST BE SEPARATED BY SPACES] (see examples below).
  179.  
  180.                2.1.3.0  Option B - Brief Output Only.
  181.  
  182. When displaying a library file, CFX normally displays a complete 
  183. library directory before further processing occurs.  Option B 
  184. suppresses the initial directory display.  Useful for slow 
  185. terminals or to save screen space.
  186.  
  187.                2.1.3.1  Option C - Monitor COMn for Carrier.
  188.  
  189. MSDOS version only.
  190. Option C causes CFX to monitor one of your computer's serial 
  191. ports for a carrier signal after each line is displayed and when 
  192. waiting for input from a user.  If no carrier is present, CFX 
  193. immediately exits.  This is intended for remote applications of 
  194. CFX in which loss of carrier should normally cause CFX's parent 
  195. program(s) to resume control and prepare for another phone call.  
  196. As a special case, /C 0 specifies no carrier detection, causing 
  197. CFX to operate as though no /C option had been specified.
  198.  
  199. Example:
  200.  
  201. Command                           Result
  202. -------                           ------
  203. CFX /C1 test.fil                  Display TEST.FIL and monitor 
  204.                                   COM1 for carrier.
  205.  
  206.                2.1.3.2  Option D - Disk Output.  
  207.  
  208. Option D causes CFX to extract files to disk.  Compressed files 
  209. are extracted to the filenames stored at file compression time.  
  210. Files are extracted to the current directory.  
  211.  
  212.                2.1.3.3  Option I - Display File Info Only.
  213.  
  214. Option I causes CFX to display file information only.  This 
  215. overrides most other options.
  216.  
  217.                2.1.3.4  Option M - Library Member Specification.
  218.  
  219. Normally CFX process all members of specified library files.  
  220. Option M allows you to specify a subset of library members for 
  221. processing.  Unlike the global file specification, the library 
  222. member specification is limited to one ambiguous or unambiguous 
  223. parameter.  If an ambiguous member specification is used, it must 
  224. be enclosed in double quotes ("").  Example:
  225.  
  226. Command                           Result
  227. -------                           ------
  228. CFX /M "*.dzc" *.lbr              Display all library members 
  229.                                   with the extent "DZC" in the 
  230.                                   current directory.
  231.  
  232.                2.1.3.5  Option N - Don't Uncompress Library Files.
  233.  
  234. Option N is intended for use in conjunction with option D (Disk 
  235. output), and tells CFX not to uncompress library members when 
  236. extracting them to disk.  Attempts to display compressed files 
  237. using option N will result in the message "can't display binary 
  238. file." 
  239.  
  240.                2.1.3.6  Option P - Prompt Before Processing Files.
  241.  
  242. If the Prompt option is specified, CFX displays the selected 
  243. file's name, compression method and datestamp to the screen and 
  244. prompts the user before displaying each matched file.  Example:
  245.  
  246.  File Name    Length   Method     Date
  247. ------------  ------  --------  --------
  248. CFX.DOC         7064   Stored   06-01-91  View (y/N/q)? 
  249.  
  250. A response of Y or y causes CFX to display the file's contents.  
  251. Responses of Q, q, control-c, control-x, or control-k cause CFX 
  252. to abort and return to the parent environment.  Any other 
  253. response causes CFX to skip to the next specified file.
  254.  
  255.                2.1.3.7  Option T - Maximum Minutes Allowed.
  256.  
  257. Option T is intended for use on remote systems which limit the 
  258. amount of connect time a caller is allowed.  Once the specified 
  259. number of minutes has elapsed, CFX unconditionally displays the 
  260. message
  261.  
  262.   CFX: x-minute time limit exceeded.
  263.  
  264. and returns control to the parent environment.
  265.  
  266.                2.1.3.8  Option W - Wait After Last File.
  267.  
  268. Option W simply causes CFX to pause and wait for a keystroke 
  269. before returning control to the parent program or operating 
  270. system.  This is useful if you invoked CFX from within a shell 
  271. (such as LIST) which overwrites screen contents after invoking 
  272. CFX.
  273.  
  274.           2.1.4  Combined Command Lines.
  275.  
  276. CFX provides a great deal of flexibility by allowing combinations 
  277. of options and file specifications to be given in a single 
  278. command.  Here are some examples:
  279.  
  280. Command                           Result
  281. -------                           ------
  282. CFX /D /N big.lbr                 Extract all members of BIG.LBR 
  283.                                   to disk without uncompressing 
  284.                                   them.
  285.  
  286. CFX /I *.?z? *.?q? *.lbr          Display information only on all 
  287.                                   crunched, squeezed, and library 
  288.                                   files in current directory.
  289.  
  290. CFX /P /M "*.d?c" *.lbr *.d?c     Display all files and library 
  291.                                   members in the current 
  292.                                   directory with the extent 
  293.                                   "D?C," prompting the user for 
  294.                                   each one.
  295.  
  296.      2.2  Output Files to Screen.
  297.  
  298. Unless the Disk Output option is specified, CFX always extracts 
  299. CP/M text files to the screen.  Binary files are skipped with the 
  300. message "can't display binary file."  Text files are paged 22 
  301. lines at a time.  When 22 lines have been written to the screen, 
  302. CFX pauses, displays the message "[more]", and awaits input from 
  303. the keyboard.  Keyboard inputs of C, control-c, Q, K, or 
  304. control-k cause CFX to abort and return control to the parent 
  305. environment.  Inputs of X or control-x cause CFX to skip to the 
  306. next specified file, if any (or quit if not).  Inputs of Z or 
  307. control-z cause CFX to scroll the rest of the file past without 
  308. pausing (useful in viewing the end of a file).  Any other input 
  309. causes CFX to display the next page of output to the screen.
  310.  
  311. When extracting files to the screen, high bits are stripped, so 
  312. WordStar and other types of files which store special meanings in 
  313. bit seven of a character should display properly.  Also, the 
  314. "bell" character (binary 7) is skipped when outputting files to 
  315. the screen. All 8 bits are preserved during disk output.
  316.  
  317.      2.3  Errors.
  318.  
  319. Most error messages are self-explanatory.  Some confusion may 
  320. result from CFX's flexible command syntax.  For example, if you 
  321. try to extract a compressed file which is not a library member to 
  322. disk without uncompressing it, you are actually trying to copy a 
  323. file to itself.  In this event, CFX will skip the specified file 
  324. and display the message
  325.  
  326.   input and output files identical
  327.  
  328. In fact, the current version of CFX will display this message any 
  329. time the NAMES of the input and output files are identical, even 
  330. if they reside in different directories.  This is a bug, but one 
  331. easily gotten around with the MSDOS COPY or XCOPY commands.
  332.  
  333.  
  334. 3  APPLICATION NOTES.
  335.  
  336. Because of its flexibly command line syntax, CFX can easily be 
  337. called from within other programs to process CP/M files, 
  338. returning control when finished. Note that in order to execute 
  339. CFX as a subtask, your program must provide access to the MSDOS 
  340. command line.  Most current BBS programs and many other 
  341. applications such as LIST and VDE provide this capability.
  342.  
  343.      3.1  BBS Usage.
  344.  
  345. A prime example of CFX's use is with MSDOS BBS applications.  
  346. Using the C, P, and T options, CFX can display the contents of 
  347. CP/M files to remote callers, monitoring for loss of carrier and 
  348. timing out after a specified amount of time has been exceeded.  
  349. The current version of CFX will NOT direct its output to the 
  350. modem as do the Samuel H. Smith's popular ZIPTV and ARCTV file 
  351. display utilities.  Rather, CFX relies on MSDOS I/O redirection 
  352. to achieve this task.  You can redirect CFX output entirely to 
  353. the serial port using the COMx device, or obtain GATEWAY.SYS, 
  354. which allows program output to be split between a COM port and 
  355. the local console (see the file GATEWAY2.ZIP, found on many 
  356. bulletin boards).
  357.  
  358. Many MSDOS BBS systems implement remote file viewing through 
  359. MSDOS BATCH files created by the sysop.  Here are some sample 
  360. BATCH commands which tell CFX to display the file given as the 
  361. first parameter, monitoring COM1 for loss of carrier and 
  362. returning control to the BBS program after 10 minutes:
  363.  
  364.      Using MSDOS COM1:
  365.  
  366.           CFX /C 1 /P /T 10 %1 < COM1 > COM1
  367.  
  368.      Using GATEWAY.SYS:
  369.  
  370.           CFX /C 1 /P /T 10 %1 < GATE1 > GATE1
  371.  
  372. If you are running RBBS-PC, you probably want to change "%1" in 
  373. the above examples to "[1]".  This causes RBBS-PC to shell 
  374. directly to the first line of the BATCH file rather than to the 
  375. BATCH file itself, and in practice has proven to be the more 
  376. reliable approach.  You can also substitute "/C [3]" for "/C 1".  
  377. This will allow local use of CFX, since [3] is substituted with 
  378. the number of the COM line RBBS is using, or 0 if RBBS is being 
  379. used locally.
  380.  
  381. Note: when used remotely, control-C does not cause CFX to abort, 
  382. though this signal still operates on the local console.
  383.  
  384.      3.2  Local Usage.
  385.  
  386. CFX can also be used to access CP/M files from within other MSDOS 
  387. programs.  A good example is its ability to display CP/M files 
  388. from within Vernon Buerg's popular LIST utility.  LIST allows you 
  389. to patch in the name of your favorite text editor for invocation 
  390. on the pointed-to file with LIST's E command.  By substituting 
  391. the name of CFX at the location dedicated to your editor's name, 
  392. you can create a version of LIST which will display any 
  393. pointed-to CP/M (LZH, crunched, library, or squeezed) file using 
  394. LIST's E command.  See LIST.DOC for instructions on patching 
  395. LIST.COM.
  396.  
  397.  
  398. 4  KNOWN BUGS.
  399.  
  400.   1. If a wildcarded argument to the /m option is used, the 
  401.      argument must be quoted ("") to avoid expansion by the 
  402.      command line parser.
  403.  
  404.   2. Does not display embedded file datestamps.
  405.  
  406.   3. Does not set datestamps of output files.
  407.  
  408.   4. Not yet extensively tested with nested .LBR files.
  409.  
  410.  
  411. 5  COPYRIGHT.
  412.  
  413. Consider this is a "free sample" of my best programming work; for 
  414. more you may have to pay.  Programmers must eat.  CFX and its 
  415. documentation are copyright 1992 by Carson Wilson.  As long as 
  416. you don't charge money to others for the use of CFX, you don't 
  417. owe me any money either.  Otherwise please contact me regarding a 
  418. license to use CFX commercially.
  419.  
  420. Also, if you wish to incorporate CFX's source code into a 
  421. project of your own, I'd appreciate it if you would contact me 
  422. first.  There are two reasons for this: 1) I may have corrected 
  423. errors in the source code since this release, and 2) I may 
  424. already be working on a project similar to yours.  In either 
  425. case, we are both better off if we pool our efforts.
  426.  
  427.  
  428. 6  DEVELOPMENT OF CFX.
  429.  
  430. Most of the design work on CFX done with Borland's Turbo C 
  431. version 2.01.  It is written entirely in the C language, and 
  432. should be portable to other systems with standard C compilers.
  433.  
  434.  
  435. 7  ABOUT THE AUTHOR.
  436.  
  437. Carson Wilson is a doctoral candidate in Political Science at 
  438. Loyola University of Chicago.  He has also spent quite a bit of 
  439. time learning to program CP/M, MSDOS, and Unix systems.  Please 
  440. address all correspondence to
  441.  
  442.      Carson Wilson
  443.      1359 W. Greenleaf, #1D
  444.      Chicago, IL 60626
  445.  
  446.               - or -
  447.  
  448.      carson@sputnik.uucp
  449.  
  450.               - or - 
  451.  
  452.      Carson Wilson
  453.      Antelope Freeway RBBS
  454.      708-455-0120, 24 hours, 3/12/2400 baud, Franklin Park, IL.
  455.  
  456. Any and all comments and suggestions will be appreciated.
  457.