home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / cpm / utils / filcpy / ppip18.lbr / PPIP.DZC / PPIP.DOC
Text File  |  1989-08-13  |  20KB  |  501 lines
  1.  
  2. PPIP.DOC            07/15/88                 Page 1
  3. ------------------------------------------------------------------------
  4.            Documentation for the PPIP program
  5. ------------------------------------------------------------------------
  6.  
  7.                 OVERVIEW
  8.                 --------
  9.  
  10. PPIP is a file copy program for use with CP/M 80.  It was written to
  11. supplement, not replace, SWEEP, NSWP or PIP.  If you want to copy or
  12. backup just a few files, you can do so with PPIP and you won't have to
  13. wait for SWEEP, VFILER, etc. to load and start.  In addition, PPIP can
  14. be included in SUBMIT files.  PPIP.COM occupies less than 4K.
  15.  
  16. PPIP has the ability, unlike most copy programs, to PUSH or PULL files
  17. between user areas. Areas from 0 to 31 are supported.
  18.  
  19. Wildcards are accepted for BOTH the source and destination file names.
  20. This is another feature that gives you flexibility not offered by most
  21. other copy programs.
  22.  
  23. CRC verification can be done on all operations, and the CRC value can be
  24. reported if you desire.  The algorithm used by PPIP is the same one used
  25. by IMP, KMD, MDM7, MEX, MODEM7, NSWP207, NULU, VFILER, XMODEM, etc.
  26.  
  27. You can specify whether you want to be notified before an existing file
  28. is overwritten.  You can also specify, separately, whether you want to
  29. be alerted before a Read-Only file is overwritten.
  30.  
  31. PPIP supports the CP/M file name archive attribute.  This allows you to
  32. quickly select and copy new files that have not been copied before.
  33.  
  34. You can use this program to write directly from the console to a disk
  35. file as you can with the Digital Research PIP.COM program.  However PPIP
  36. gives you a little more editing freedom.  PPIP does not support devices
  37. other than CON:.
  38.  
  39. File appends are also not supported.
  40.  
  41. PPIP supports Plu*Perfect Systems DateStamper, if present.  The copied 
  42. file is given the same date stamp as the source file.  Note that PPIP 
  43. must be assembled with the DATESTAMP equate set to YES.  Starting with
  44. version 1.7, the datestamper option works on 8080 and 8085 systems.
  45. PPIP can be assembled as a ZCPR utility by setting the ZCPR3 equate to 
  46. YES.  Be sure to install PPIP with Z3INS unless your ZCPR system auto- 
  47. installs all utilities at run time (BGii does).
  48.  
  49. Beginning with version 1.8, Z80DOS timestamping support has been added
  50. and placed in the public domain. This is controlled by an equate that
  51. must be set to YES.
  52.  
  53.                    OPERATION
  54.                    ---------
  55.  
  56. THE COMMAND MODE
  57. ----------------
  58. This program may operate in either the CP/M (tm - Digital Research) com-
  59. mand mode or the MS-DOS (tm - Microsoft) command mode.    The mode is 
  60. determined by PPIP by looking for '='.
  61.  
  62. In the "CP/M mode" the destination file name comes first in the command 
  63. line, as it does when you use DRI's PIP.COM.  You must separate the 
  64. source file name from the destination file name with an equals sign 
  65. ('=').  If only one argument is given, it is assumed to be the SOURCE 
  66. file and the destination file will have the same name on the current 
  67. drive and user area.  So the command format is:
  68.  
  69.         A>PPIP [[DU:]<DEST.EXT>=][DU:]<SOURCE.EXT>
  70.  
  71. In the "MS-DOS mode", the source file name comes first, followed by the
  72. destination file name.    The names should be be separated by a space.
  73.  
  74.        A>PPIP [DU:]<SOURCE.EXT>[ [DU:]<DEST.EXT>]
  75.  
  76. As in the CP/M mode, if only one argument is specified, it is assumed to
  77. be the source file name.
  78.  
  79. In either mode, the DU: (drive/user) or DIR: spec is optional.
  80.  
  81. If the program is invoked with no arguments then a HELP message is
  82. printed on the console.
  83.  
  84. Control-C may be used to abort the program.  The copy in progress will
  85. be completed before the ^C command is obeyed.
  86.  
  87.  
  88. DRIVE/USER SPECIFICATIONS
  89. -------------------------
  90. You may include a DU: spec (or DIR: spec if running under ZCPR with a 
  91. NDR file loaded) with any file name (except CON:, of course).  The drive 
  92. may range from 'A' to 'P' unless the maximum accessible drive is 
  93. otherwise specified in the source program before assembly.  Similarly, 
  94. user areas from 0 to 31 can be accessed unless this is specifically over- 
  95. ridden.  You may specify a drive alone, in which case the program will 
  96. assume the current user area, and you may specify a user area alone and 
  97. the program will assume that you want to use the current drive.  If you 
  98. specify neither a drive nor a user area then the program will fill in 
  99. both the current drive and current user for you.
  100.  
  101.  
  102. WILDCARDS
  103. ---------
  104. Both the source and destination file names can contain wildcards.  Wild-
  105. cards in a source file name are expanded in the usual way.  Wildcards in
  106. the destination file name are resolved from characters in the source file
  107. name by a "matching" process.  A couple of examples will illustrate this.
  108.  
  109.            source:           COPY    .ASM
  110.            wild destination:   ??????10.*
  111.            final destination:  COPY10  .ASM
  112.  
  113.            source:           PPIP    .COM
  114.            wild destination:   Q*       .OBJ
  115.            final destination:  QPIP    .OBJ
  116.  
  117. (You would not enter the spaces that occur between the file name and type
  118. in the examples above.    These are included for clarification only.)
  119.  
  120. As you may realize, this wildcard format makes it quite possible for the
  121. program to create duplicate files.  For example you could enter:
  122.  
  123.             A0>PPIP *.BAK=PPIP.*
  124.  
  125. If the files PPIP.ASM and PPIP.DOC are both on the current DU: then the
  126. destination files would both be named PPIP.BAK.  Clearly this is unde-
  127. sirable.  In a limited effort to eliminate this kind of error, PPIP
  128. stores the name of the LAST file copied and compares it to the name of
  129. the file currently being copied.  If they are the same then a "Dupli-
  130. cate!" error is issued and the current file is skipped.  It is still
  131. possible for a duplicate file to be written when the two files with the
  132. same names are not copied one right after another.  The only guards
  133. against this are the 'E' and 'W' switches which, if OFF, will tell you
  134. that the file about to be written already exists.  As you can see, care
  135. should be exercised in using wildcards.  If used correctly this wildcard
  136. scheme will allow you to do your copying and renaming all in one step.
  137.  
  138. The distributed version of PPIP will handle up to 512 file names.
  139.  
  140.  
  141. FILE ATTRIBUTES
  142. ---------------
  143. All eleven file attribute bits, including Read-Only, System, and Archive
  144. are supported by PPIP and are handled as follows:
  145.  
  146.      1) If the destination file existed before the copy operation
  147.     then its original attributes are retained, unless the copy
  148.     was made with the archive option in effect.
  149.  
  150.      2) If the destination file did not exist before the copy
  151.     operation then it receives the same attributes as the
  152.     source file.
  153.  
  154.      3) If the copy is made with the archive option ON,
  155.     then the archive attribute is SET in the source
  156.     file and RESET in the destination file.
  157.  
  158.  
  159. COMMAND EXAMPLES
  160. ----------------
  161.  
  162.        Command Line        Mode         Action Performed
  163. ------------------------------------------------------------------------
  164. A0>PPIP             either    print the PPIP help menu
  165.  
  166. A0>PPIP B0:*.*            either    copy all files on drive B: and
  167.                     user 0 to the current drive and
  168.                     drive and user area (A0:)
  169.  
  170. C8>PPIP A:*.COM 5:*.OBJ     MS-DOS    copy all .COM files on A8: to
  171.                     .OBJ files with the same names
  172.                     on C5:
  173.  
  174. A0>PPIP B15:X*.* C0:Z*.*    MS-DOS    copy all files on B15: that have
  175.                     names starting with the letter
  176.                     'X' to files with the same names
  177.                     except starting with the letter
  178.                     'Z', on drive/user C0:
  179.  
  180. B14>PPIP *.* C0:?????BAK.*    MS-DOS    copy all files on B14: to C0:
  181.                     and insert the letters "BAK" at
  182.                     the end of the file name field.
  183.  
  184. B8>PPIP D0:=A0:KMD.COM        CP/M    copy the KMD.COM file on A0: to
  185.                     D0:
  186.  
  187. A0>PPIP D0:=B11:*.?Q?        CP/M    copy all files with a 'Q' in the
  188.                     extension that appear on B11: to
  189.                     to D0:
  190.  
  191. A15>PPIP COPY.COM=0:PPIP.COM    CP/M    copy PPIP.COM on A0: to COPY.COM
  192.                     on A15:
  193.  
  194. D5>PPIP B0:MYFILE.DOC=CON:    CP/M    copy console input to MYFILE.DOC
  195.                     drive B: and user 0.
  196.  
  197.  
  198. RUN-TIME OPTIONS
  199. ----------------
  200. There are six options that you can switch ON/OFF from the command line.
  201. Each of these options has a default value which is specified when the
  202. program is assembled.  The default settings will be reported in the HELP
  203. menu.
  204.  
  205. Options are activated from the command line by a special character.  This
  206. character must be specified before assembly and will be reported in the
  207. HELP menu.  In our examples we will use the traditional MS-DOS switch
  208. character '/'.    This is the switch used in the distributed version of
  209. PPIP.
  210.  
  211. The options can appear anywhere in the command line, can be bundled to-
  212. gether, and can appear more than once.    If an option occurs more than
  213. once in the command line, it is toggled each time it is encountered.
  214. Thus all the following commands mean the same thing:
  215.  
  216.           A0>PPIP /V SOURCE /K DEST /W
  217.           A0>PPIP SOURCE DEST /V /K /W
  218.           A0>PPIP /WKV SOURCE DEST
  219.           A0>PPIP /C SOURCE /W DEST /VKC
  220.  
  221.   NOTE: Only two arguments, excluding options, are accepted by
  222.     PPIP. Thus file appends and multiple file operations with
  223.     unambiguous names are not supported.  You will be warned
  224.     about extra arguments.    You will also be warned about un-
  225.     recognized options.
  226.  
  227.  
  228. Here is a list of the valid options and their default status in the dis-
  229. tributed version.
  230.  
  231.   Character          Function              Default Status
  232.  -----------------------------------------------------------------------
  233.  
  234.     A    if ON, only files that have their archive attributes    OFF
  235.     not set (off) will be copied.
  236.  
  237.     C    if ON, the CRC value will be reported in hex (if the    OFF
  238.     /V switch is also ON)
  239.  
  240.     E    if ON, you will NOT be warned before Read/Write files    OFF
  241.     are overwritten.
  242.  
  243.     M   if ON, the source file is erased after the copy is      OFF
  244.         successfully completed.  This option does not toggle.
  245.         If /M is specified, the move mode is enabled and the
  246.         V mode is forced on to provide CRC verification.
  247.  
  248.     W    if ON, you will NOT be warned before Read/Write and    OFF
  249.     Read/Only files are overwritten.
  250.  
  251.     V    if ON, verifies the CRC of the copies (needs /C to    OFF
  252.     also display the CRC value in hex).
  253.  
  254. If the /V or /M switch is on and the Cyclic Redundancy Check fails, the 
  255. copy will be retried.  In the distributed version the copy will be 
  256. retried three times before PPIP gives up.
  257.  
  258. The archiving option has limited usefulness under CP/M 2.x since the
  259. operating system resets archive attributes only when files are created
  260. anew, not when they are updated as should be the case.  You must either
  261. reset the archive bit "by hand" with an utility program or create a new
  262. file before PPIP will recognize that a file has been changed.  Still,
  263. the /A option gives you an easy way to find and copy new files on your
  264. system.     Many BDOS replacements such as ZRDOS, P2DOS and PZDOS properly 
  265. support the archive attribute.
  266.  
  267.  
  268. THE EDITOR
  269. ----------
  270. PPIP contains a very crude text editor that is still a step above
  271. what DRI's PIP.COM offers.  The important differences are:
  272.  
  273.      1) backspaces are not interpreted literally and placed
  274.     into the file.    Instead, you can use BACKSPACE or RUBOUT
  275.     to back up and make corrections to the current line.
  276.     This is a destructive backspace so text to the right
  277.     of the cursor will have to be retyped.    There is no
  278.     provision for editing lines other than the current one
  279.     as this would require terminal-specific code.
  280.  
  281.      2) line feeds are automatically added to carriage
  282.     returns.
  283.  
  284.      3) any control characters can be entered literally
  285.     into the file.    Most control characters can be
  286.     entered just as you would expect, by holding down
  287.     the CONTROL key and hitting the appropriate alpha-
  288.     betic key.  The exceptions to this are:  backspace
  289.     (^H), carriage return (^M) and EOF (^Z).  These
  290.     characters have special meaning to the editor.    To
  291.     enter them you must first enter a "trigger" char-
  292.     acter.    The trigger in the distributed version of
  293.     PPIP is the tilde ('~').  So, to insert a carriage
  294.     return into the text you would enter '~' and then
  295.     the letter 'M'.  The editor will convert lower-case
  296.     characters entered after the trigger to upper-case.
  297.     If the character entered after the trigger will not
  298.     produce a valid control character then it is ignored.
  299.     To enter the trigger character itself, you type it
  300.     two times.
  301.  
  302.      4) lines are automatically wrapped.  Word wrap occurs
  303.     at the first space that you type after there are 10
  304.     characters left on the console line.  If no spaces
  305.     occur during the last 10 characters on the line then
  306.     the line is wrapped one character before the end of
  307.     the line.  Once you leave a line you can't get back
  308.     back to it.
  309.  
  310. Wildcards are inappropriate in the destination file name for a console
  311. copy.  The program will print an error message if you use them.
  312.  
  313. To quit entering text, use CTL-Z, just as you do with PIP.COM.
  314.  
  315. It is unlikely that you will ever fill the memory buffer when entering
  316. console text.  If you do, however, PPIP will ring the console bell when
  317. there are only five characters left in the buffer.  You may heed this
  318. warning and exit the program or you may keep on typing.  When you hit
  319. the end of the buffer, PPIP will write the buffer to disk and return you
  320. to CP/M.
  321.  
  322.  
  323. PROGRAM ALTERATION AND NOTES
  324. ----------------------------
  325. This program was written primarily because I got tired of bringing up
  326. SWEEP just to make a quick back-up of work in progress.  And I wanted a
  327. copy program that would be easy to use from a submit file.  Also, I like
  328. the MS-DOS copy program and wanted a program that could (a) accept just
  329. one argument to copy a file to the current drive/user area and (b) would
  330. accept the source file first on the command line.  PPIP fits the bill
  331. and has a few other niceties to boot.
  332.  
  333. If you are so inclined, you may make changes to the data listed as "User
  334. customizable" to tailor the program to your system.  There's not much to
  335. do here, but you can set your maximum accessible drive and user areas,
  336. and you can change the option switch characters if the ones being used
  337. do not suit you.
  338.  
  339. For your reference, here are the important locations in a NON-ZCPR3 
  340. version of PPIP.  For ZCPR3 versions, add 08H to all addresses.
  341.  
  342.  LABEL     LOCATION          PURPOSE             DEFAULT
  343. ------------------------------------------------------------------------
  344. TRIGGER equate    specifies the trigger you want to use to     '~'
  345.     in    enter literal control character from the
  346.     source    CON:  Note, don't use '^; as trigger since
  347.     code    doing so will prevent you from entering
  348.         the control character '^^'.
  349.  
  350. SWID    equate    your screen width in characters           80
  351.  
  352.  
  353. ***  Note  ***  The following are for NON-ZCPR !!!  Add 8 bytes for ZCPR !!!
  354.  
  355.  
  356. RETRY    0103H    the number of retrys you want PPIP to attempt      3
  357.         if CRC verification fails.
  358.  
  359. MAXDRV    0104H    your maximum accessible drive letter in caps     'P'
  360.  
  361. MAXUSR    0105H    your maximum accessible user number          15
  362.  
  363. SWITCH    0106H    specifies the character to be used to activate     '/'
  364.         options in the command line
  365.            line
  366.  
  367. VERIFY    0108H    the CRC verification option            V - off
  368.  
  369. REPORT    010AH    the CRC report option (shows value in hex)    C - off
  370.  
  371. ARCHIV    010CH    the archive option                A - off
  372.  
  373. EMEND    010EH    the option to allow overwriting R/W  files    E - off
  374.         without asking
  375.  
  376. WIPE    0110H    the option to allow erasing of all files    W - off
  377.         (both R/W and R/O) without asking
  378.  
  379. MOVF    0112H   thhe move option                M - off
  380.  
  381. OPTIONS
  382. ------------------------------------------------------------------------
  383. A note regarding the options:  The options table is terminated
  384. with a zero in the options-character position.    If you want to
  385. "hard-wire" the options, you can simply terminate the table at
  386. the appropriate place.    The options status bytes must remain
  387. intact and must be set the way you want.  For instance, to turn
  388. the EMEND and WIPE options off permanently, you would substitute
  389. a zero for the 'E' at 0110H.
  390.  
  391.                 Messages
  392.                 --------
  393. Here is a list of PPIP messages and their meaning:
  394.  
  395.  
  396.         MESSAGE                  MEANING
  397. --------------------------------   ------------------------------
  398. "<?> - unrecognized option"       you have used an option
  399.                    character that is invalid
  400.  
  401. "Archived"               a copy operation is being
  402.                    skipped because a file has
  403.                    already been archived
  404.  
  405. "bad drive/user spec in <filename>" either the drive or the user
  406.                    area you have specified is out
  407.                    of bounds
  408.  
  409. "Can't close destination"       the destination file has been
  410.                    written but can't be closed
  411.  
  412. "Can't copy to same drive/user"    an attempt has been made to
  413.                    write the destination file on
  414.                    top of the source file
  415.  
  416. "can't open source"           the source file has been
  417.                    located but can't be opened
  418.  
  419. "Directory is full"           there is no room left for
  420.                    another entry in the disk
  421.                    directory
  422.  
  423. "Disk full. Deleting file."       the destination file is too
  424. "Disk full. Copy deleted."       big to fit on the specified
  425.                    disk. The partial file will be
  426.                    deleted.
  427.  
  428. "Duplicate!"               a copy operation is being
  429.                    skipped because it will over-
  430.                    write the file just written
  431.  
  432. "Exists! Delete?"           the file about to be written
  433. "R/O! Delete?"               exists. You should enter the
  434.                    single character 'Y' or 'N' to
  435.                    indicate whether the file
  436.                    should be deleted.
  437.  
  438. "Ignoring:"               the program will list and
  439.                    ignore all arguments other
  440.                    than the source and
  441.                    destination file names and
  442.                    options.
  443.  
  444. "invalid characters in <filename>" you have used an illegal
  445.                    character in the file name.
  446.                    Unacceptable characters are
  447.                    the comma, semi-colon, colon,
  448.                    equals sign, and single and
  449.                    double quotes
  450.  
  451. "No destination file specified"    issued only when CON: is the
  452.                    source file and a destination
  453.                    file name must be specified
  454.  
  455. "no file <filename>"           the file name you have used
  456.                    cannot be found on the
  457.                    specified drive and user area
  458.  
  459. "Ok"                   tells you how the CRC check
  460. "failed"               came out
  461.  
  462. "Out of memory"            PPIP puts all the expanded
  463.                    source file names in memory
  464.                    and uses all memory above that
  465.                    for disk buffering. If no
  466.                    memory is left after the
  467.                    source file name is expanded
  468.                    you will get this error
  469.                    message
  470.  
  471. "Please check your disk"       CRC has failed retry + 1 times
  472.                    so something is seriously
  473.                    wrong
  474.  
  475. "User abort"               you have used control-C to
  476.                    abort the copy process
  477.  
  478. "verify file open error"       the destination file has been
  479.                    written but can't be reopened
  480.                    for verification
  481.  
  482. "Verifying"               tells you that CRC
  483.                    verification is being done
  484.  
  485. "Wildcards not allowed"        issued only when CON: is the
  486.                    source file. The destination
  487.                    file name must be unambiguous
  488.  
  489. -----------------------------------------------------------------
  490. Feel free to toy with PPIP all you want, but do not use it for
  491. commercial purposes or for monetary gain without expressed
  492. written permission from the author.
  493.  
  494.        PPIP is Copyright (C) by David Jewett, III - 1985.
  495.  
  496.               10376 Iron Mill Road
  497.                Richmond, VA  23235
  498.             Day Phone: (804) 794-7667
  499. -----------------------------------------------------------------
  500. 
  501.