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