                     CFX - Cp/m File eXpress
                         User's Manual
             Copyright 4 January 92 by Carson Wilson


                          - CONTENTS -

     1  PURPOSE.
     2  USAGE.
          2.1  Invocation.
               2.1.1  Help Screen.
               2.1.2  File Specification
               2.1.3  Command Line Options.
                    2.1.3.0  Option B - Brief Output Only.
                    2.1.3.1  Option C - Monitor COMn for Carrier.
                    2.1.3.2  Option D - Disk Output.
                    2.1.3.3  Option I - Display File Info Only.
                    2.1.3.4  Option M - Library Member
                             Specification.
                    2.1.3.5  Option N - Don't Uncompress Library
                             Files.
                    2.1.3.6  Option P - Prompt Before Processing
                             Files.
                    2.1.3.7  Option T - Maximum Minutes Allowed.
                    2.1.3.8  Option W - Wait After Last File.
               2.1.4  Combined Command Lines.
          2.2  Output Files to Screen.
          2.3  Errors.
     3  APPLICATION NOTES.
          3.1  BBS Usage.
          3.2  Local Usage.
     4  KNOWN BUGS.
     5  COPYRIGHT.
     6  DEVELOPMENT OF CFX.
     7  ABOUT THE AUTHOR.


                            ---------

1  PURPOSE.

As its name suggests, CFX is a tool intended to allow quick 
access to CP/M files.  While CFX will operate on standard ASCII 
files, its main strength is its ability access files stored with 
the special archiving and compression methods native to the CP/M 
operating system.  Specifically, CFX can handle files compressed 
with Roger Warren's LZH utilities, Steve Greenberg's CRUNCH 
utilities, "squeezed" files, and archives built using Gary 
Novosielski's Library definition.  

Typically, CP/M files stored using these protocols can be 
identified by the three letter file extent as follows:

     Extent   Storage method
     ------   --------------
     .?Y?     LZH compression
     .?Z?     Crunched
     .?Q?     Squeezed
     .LBR     Library

Notes:
  1. Much of what follows applies only to the MSDOS version of
     CFX.  If you are using CFX on a Unix system, please refer to
     the file cfx.1 or cfx.man for usage information.

  1. Library members themselves may be stored under one of the 
     above methods (e.g., crunched library members are common).  
     CFX can extract compressed library members 
     directly to screen or disk.  It can also process library 
     members which are themselves libraries in one step.  
     However, CFX cannot presently extract members from 
     compressed library files in a single step; you must first 
     run CFX on the compressed library file and then invoke CFX 
     again on the uncompressed library file to access library 
     members.

  2. Though LZH, crunched, and squeezed files usually have the 
     extents mentioned above, they are more reliably identified 
     by means of a unique signature at the start of the file.  
     CFX uses this signature to identify the compression method 
     in all cases.  Following the signature check, CFX 
     additionally uses the following standard file extensions to 
     identify files which cannot be displayed to the screen:

     .OBJ, .COM, .EXE, .BIN, .ARC, .ARK, .ZIP, .REL, .SLR, .CFG, 
     .SCN, .LBR, .ZDK, .OVR, .Z3T, .CHN, .CIM, .3OM, .4OM, .T4C, 
     .DAT, .ZRL

     You can add or remove entries from this list of extensions 
     using a binary file patcher.  The default extensions reside 
     at or near offset 53A0h in CFX.EXE (compiled MSDOS version 
     only), and the last few entries are all ".ZRL"  By overwriting 
     a ZRL entry with an extension of your choosing, you can prevent 
     CFX from displaying files and library members of this type.  
     To allow display of one of the above file types, simply 
     overwrite its entry with one of the other extensions from the 
     list.

  3. CFX cannot access members of .ARC, .ZIP, .ZOO, or other 
     common MSDOS file archives.  Plenty of utilities are already 
     available for this purpose.


2  USAGE.
z
     2.1  Invocation.

CFX is invoked as:

     CFX [option ...] [afn ...]

where CFX is the name of the CFX executable file.

          2.1.1  Help Screen.

If no command line parameters are given, the following help 
screen appears:

CFX - Cp/m File eXpress, Version x.x, Copr. 1992 by Carson Wilson
  Usage:
        CFX [option ...] afn ...
  Options:
        /b       - brief output only
        /c n     - monitor COMn for carrier
        /d       - disk output
        /i       - display directory information
        /m "afn" - library member specification
        /n       - don't uncompress library members
        /p       - prompt before processing files
        /t n     - maximum minutes allowed
        /w       - wait after last file

The "/" character in the above help screen is the current MSDOS 
"switch" character, and may change depending on your 
installation.

          2.1.2  File Specification

CFX can be used on one or many files at once, depending on the 
command line arguments it is invoked with.  File compression and 
archiving methods are detected "on the fly" by CFX, and the 
proper decompression or library access operations 
performed as needed.  This makes CFX suitable for use as an 
extension to many existing MSDOS applications, such as file 
viewers or BBS programs (see USAGE EXAMPLES, below).

Files can be specified using single or multiple ambiguous or 
unambiguous filespecs, and filespecs may include path 
information.  If command line options are also given, file 
specifications must appear LAST on the command line.  When 
specifying library files, the .LBR extent is optional.

Examples:

Command                           Results
-------                           -------
CFX *.dzc                         View all files in current 
                                  directory with extension "DZC".

CFX a:\backup\test.bat            View TEST.BAT in directory 
                                  BACKUP on drive A:.

CFX *.lbr ..\*.lbr                View all files with extension 
                                  "LBR" in the current and parent 
                                  directories.

CFX mylbr                         View MYLBR.LBR in current 
                                  directory.


          2.1.3  Command Line Options.

CFX command line options are specified using the current MSDOS 
"switch" character (normally "/"), or "-" under Unix systems.  
Under MSDOS, to specify more than one option you must use the 
switch character once before each option.  Options must come 
BEFORE file specifications (if any) in the command line, [and 
under MSDOS, MUST BE SEPARATED BY SPACES] (see examples below).

               2.1.3.0  Option B - Brief Output Only.

When displaying a library file, CFX normally displays a complete 
library directory before further processing occurs.  Option B 
suppresses the initial directory display.  Useful for slow 
terminals or to save screen space.

               2.1.3.1  Option C - Monitor COMn for Carrier.

MSDOS version only.
Option C causes CFX to monitor one of your computer's serial 
ports for a carrier signal after each line is displayed and when 
waiting for input from a user.  If no carrier is present, CFX 
immediately exits.  This is intended for remote applications of 
CFX in which loss of carrier should normally cause CFX's parent 
program(s) to resume control and prepare for another phone call.  
As a special case, /C 0 specifies no carrier detection, causing 
CFX to operate as though no /C option had been specified.

Example:

Command                           Result
-------                           ------
CFX /C1 test.fil                  Display TEST.FIL and monitor 
                                  COM1 for carrier.

               2.1.3.2  Option D - Disk Output.  

Option D causes CFX to extract files to disk.  Compressed files 
are extracted to the filenames stored at file compression time.  
Files are extracted to the current directory.  

               2.1.3.3  Option I - Display File Info Only.

Option I causes CFX to display file information only.  This 
overrides most other options.

               2.1.3.4  Option M - Library Member Specification.

Normally CFX process all members of specified library files.  
Option M allows you to specify a subset of library members for 
processing.  Unlike the global file specification, the library 
member specification is limited to one ambiguous or unambiguous 
parameter.  If an ambiguous member specification is used, it must 
be enclosed in double quotes ("").  Example:

Command                           Result
-------                           ------
CFX /M "*.dzc" *.lbr              Display all library members 
                                  with the extent "DZC" in the 
                                  current directory.

               2.1.3.5  Option N - Don't Uncompress Library Files.

Option N is intended for use in conjunction with option D (Disk 
output), and tells CFX not to uncompress library members when 
extracting them to disk.  Attempts to display compressed files 
using option N will result in the message "can't display binary 
file." 

               2.1.3.6  Option P - Prompt Before Processing Files.

If the Prompt option is specified, CFX displays the selected 
file's name, compression method and datestamp to the screen and 
prompts the user before displaying each matched file.  Example:

 File Name    Length   Method     Date
------------  ------  --------  --------
CFX.DOC         7064   Stored   06-01-91  View (y/N/q)? 

A response of Y or y causes CFX to display the file's contents.  
Responses of Q, q, control-c, control-x, or control-k cause CFX 
to abort and return to the parent environment.  Any other 
response causes CFX to skip to the next specified file.

               2.1.3.7  Option T - Maximum Minutes Allowed.

Option T is intended for use on remote systems which limit the 
amount of connect time a caller is allowed.  Once the specified 
number of minutes has elapsed, CFX unconditionally displays the 
message

  CFX: x-minute time limit exceeded.

and returns control to the parent environment.

               2.1.3.8  Option W - Wait After Last File.

Option W simply causes CFX to pause and wait for a keystroke 
before returning control to the parent program or operating 
system.  This is useful if you invoked CFX from within a shell 
(such as LIST) which overwrites screen contents after invoking 
CFX.

          2.1.4  Combined Command Lines.

CFX provides a great deal of flexibility by allowing combinations 
of options and file specifications to be given in a single 
command.  Here are some examples:

Command                           Result
-------                           ------
CFX /D /N big.lbr                 Extract all members of BIG.LBR 
                                  to disk without uncompressing 
                                  them.

CFX /I *.?z? *.?q? *.lbr          Display information only on all 
                                  crunched, squeezed, and library 
                                  files in current directory.

CFX /P /M "*.d?c" *.lbr *.d?c     Display all files and library 
                                  members in the current 
                                  directory with the extent 
                                  "D?C," prompting the user for 
                                  each one.

     2.2  Output Files to Screen.

Unless the Disk Output option is specified, CFX always extracts 
CP/M text files to the screen.  Binary files are skipped with the 
message "can't display binary file."  Text files are paged 22 
lines at a time.  When 22 lines have been written to the screen, 
CFX pauses, displays the message "[more]", and awaits input from 
the keyboard.  Keyboard inputs of C, control-c, Q, K, or 
control-k cause CFX to abort and return control to the parent 
environment.  Inputs of X or control-x cause CFX to skip to the 
next specified file, if any (or quit if not).  Inputs of Z or 
control-z cause CFX to scroll the rest of the file past without 
pausing (useful in viewing the end of a file).  Any other input 
causes CFX to display the next page of output to the screen.

When extracting files to the screen, high bits are stripped, so 
WordStar and other types of files which store special meanings in 
bit seven of a character should display properly.  Also, the 
"bell" character (binary 7) is skipped when outputting files to 
the screen. All 8 bits are preserved during disk output.

     2.3  Errors.

Most error messages are self-explanatory.  Some confusion may 
result from CFX's flexible command syntax.  For example, if you 
try to extract a compressed file which is not a library member to 
disk without uncompressing it, you are actually trying to copy a 
file to itself.  In this event, CFX will skip the specified file 
and display the message

  input and output files identical

In fact, the current version of CFX will display this message any 
time the NAMES of the input and output files are identical, even 
if they reside in different directories.  This is a bug, but one 
easily gotten around with the MSDOS COPY or XCOPY commands.

File members with a size of 64K and above will work now, and
CP/M filenames with '/' inside will be converted to have a '-'
inside (with no extra message; Peter Dassow; added in 2006).

3  APPLICATION NOTES.

Because of its flexibly command line syntax, CFX can easily be 
called from within other programs to process CP/M files, 
returning control when finished. Note that in order to execute 
CFX as a subtask, your program must provide access to the MSDOS 
command line.  Most current BBS programs and many other 
applications such as LIST and VDE provide this capability.

     3.1  BBS Usage.

A prime example of CFX's use is with MSDOS BBS applications.  
Using the C, P, and T options, CFX can display the contents of 
CP/M files to remote callers, monitoring for loss of carrier and 
timing out after a specified amount of time has been exceeded.  
The current version of CFX will NOT direct its output to the 
modem as do the Samuel H. Smith's popular ZIPTV and ARCTV file 
display utilities.  Rather, CFX relies on MSDOS I/O redirection 
to achieve this task.  You can redirect CFX output entirely to 
the serial port using the COMx device, or obtain GATEWAY.SYS, 
which allows program output to be split between a COM port and 
the local console (see the file GATEWAY2.ZIP, found on many 
bulletin boards).

Many MSDOS BBS systems implement remote file viewing through 
MSDOS BATCH files created by the sysop.  Here are some sample 
BATCH commands which tell CFX to display the file given as the 
first parameter, monitoring COM1 for loss of carrier and 
returning control to the BBS program after 10 minutes:

     Using MSDOS COM1:

          CFX /C 1 /P /T 10 %1 < COM1 > COM1

     Using GATEWAY.SYS:

          CFX /C 1 /P /T 10 %1 < GATE1 > GATE1

If you are running RBBS-PC, you probably want to change "%1" in 
the above examples to "[1]".  This causes RBBS-PC to shell 
directly to the first line of the BATCH file rather than to the 
BATCH file itself, and in practice has proven to be the more 
reliable approach.  You can also substitute "/C [3]" for "/C 1".  
This will allow local use of CFX, since [3] is substituted with 
the number of the COM line RBBS is using, or 0 if RBBS is being 
used locally.

Note: when used remotely, control-C does not cause CFX to abort, 
though this signal still operates on the local console.

     3.2  Local Usage.

CFX can also be used to access CP/M files from within other MSDOS 
programs.  A good example is its ability to display CP/M files 
from within Vernon Buerg's popular LIST utility.  LIST allows you 
to patch in the name of your favorite text editor for invocation 
on the pointed-to file with LIST's E command.  By substituting 
the name of CFX at the location dedicated to your editor's name, 
you can create a version of LIST which will display any 
pointed-to CP/M (LZH, crunched, library, or squeezed) file using 
LIST's E command.  See LIST.DOC for instructions on patching 
LIST.COM.


4  KNOWN BUGS.

  1. If a wildcarded argument to the /m option is used, the 
     argument must be quoted ("") to avoid expansion by the 
     command line parser.

  2. Does not display embedded file datestamps.

  3. Does not set datestamps of output files. FIXED in V1.3 !

  4. Not yet extensively tested with nested .LBR files.


5  COPYRIGHT.

Consider this is a "free sample" of my best programming work; for 
more you may have to pay.  Programmers must eat.  CFX and its 
documentation are copyright 1992 by Carson Wilson.  As long as 
you don't charge money to others for the use of CFX, you don't 
owe me any money either.  Otherwise please contact me regarding a 
license to use CFX commercially.

Also, if you wish to incorporate CFX's source code into a 
project of your own, I'd appreciate it if you would contact me 
first.  There are two reasons for this: 1) I may have corrected 
errors in the source code since this release, and 2) I may 
already be working on a project similar to yours.  In either 
case, we are both better off if we pool our efforts.


6  DEVELOPMENT OF CFX.

Most of the design work on CFX done with Borland's Turbo C 
version 2.01.  It is written entirely in the C language, and 
should be portable to other systems with standard C compilers.


7  ABOUT THE AUTHOR.

Carson Wilson is a doctoral candidate in Political Science at 
Loyola University of Chicago.  He has also spent quite a bit of 
time learning to program CP/M, MSDOS, and Unix systems.  Please 
address all correspondence to

     Carson Wilson
     1359 W. Greenleaf, #1D
     Chicago, IL 60626

              - or -

     carson@sputnik.uucp

              - or - 

     Carson Wilson
     Antelope Freeway RBBS
     708-455-0120, 24 hours, 3/12/2400 baud, Franklin Park, IL.

Any and all comments and suggestions will be appreciated.
