       CP/M 3 User's Guide                                                     The DIR Command

                       4A>DIR *.BAS

                       Displays all DIR files with filetype BAS for user 4 on drive A.

                       B >DIP A: X+.  C?D

                       Displays all DIR files for user 0 on drive A whose filename begins with
                       the letter X, and whose three character filetype contains the first chat-
                       acter C and last character D.

                       A'>DIRS@IS

                       Displays all files for user 0 on drive A that have the system (SYS)
                           'bute.
                       attri

                       3A >DIRS *. COM

                       This abbreviated form of the DIRSYS command displays all SYS files
                       with filetype COM on the default drive A for user 3.

        Display Directory with Options

        Syntax:        DIR Id:l [options]
                       DIR Ifilespecl Ifilespecl ... [options]

        Explanation:   The DIR command with options is an enhanced version of the DIR
                       command.  The DIR command displays CP/M 3 files In a variety of
                       ways.  DIR can search for files on any or all drives, for any or all user
                       numbers.

                       DIR allows the option list to occur anywhere in the command tall.
                       These options modify the entire command line.  Only one option list is
                       allowed.

                       Options must be enclosed in square brackets.  The options can be used
                       individually, or strung together separated by commas or spaces.  Options
                       can be abbreviated to only one or two letters if the abbreviation unam-
                       biguously identifies the option.



        [K [)I(ill'AI-RFSEAR(li@"                                                               5-21

    The DIR Command                                                     CP/M 3 User's Guide

                  If a directory listing exceeds the size of your screen, DIR automatically
                  halts the display when it fills the screen.  Press any key to continue the
                  display.

                                      Table 5-5.  DIR Display Options
                    Option              Function

                    ATT

                                        displays the user-definable file attributes Fl, F2,
                                        F3, and F4.

                    DATE

                                        displays files with date and time stamps.  If date
                                        and time stamping is not active, DIR displays the
                                        message:

                                        D at e an d T i me St amp i n!l I n a c t i v e

                    DIR

                                        displays only files that have the DIR attribute.

                    DRIVE = ALL

                                        displays files on all accessed drives.  DISK is also
                                        acceptable in place of DRIVE in all the DRIVE
                                        options.

                    DRIVE = (A,B,C,...,P)

                                        displays files on the drives specified.

                    DRIVE = d

                                        displays files on the drive specified by d.


    5-22                                                                Ea DIGITAL RESEARCH'"

        CP/M 3 User's Guide                                                      The DIR Command

                                                 Table 5-5. (continued)

                         Option                Function

                         EXCLUDE

                                               displays the files on the default drive and user
                                               area that do not match the files specified in the
                                               command line.

                         FF

                                               sends an initial fo:-m-feed to the printer device if
                                               the printer has been activated by CTRL-P.  If the
                                               LENGTH= n option is also specified, DIR issues
                                               a form-feed every n lines.  Otherwise, the FF option
                                               deactivates the default paged output display.

                         FULL

                                               shows the name of the file and the size of the file.
                                               The size is shown as the amount of space in ki-
                                               lobytes and the number of 128-byte records allo-
                                               cated to the file.  FULL also shows the attributes
                                               the file. (See the SET command for description of
                                               file attributes).  If there is a directory label on the
                                               drive, DIR shows the password protection mode
                                               and the time stamps.  The display is alphabetically
                                               sorted.  FULL is the default output format for dis-
                                               play when using DIR with options.

                          LENGTH       n

                                               displays n lines of output before inserting a table
                                               heading. n must be in the range between 5 and
                                               65536.  The default length is one full screen of
                                               information.








         Ell 1)1(,ITAI, RESEAR(,H"
                                                                                                  5-23

   Tle DIR Command                                                       CP/M 3 User's Guide

                                           Table 5-5. (continued)
                    Option              Function

                    MESSAGE

                                        displays the names of the specified drives and user
                                        numbers it is currently searching.  If there are no
                                        files in the specified locations, DIR displays the
                                        file not found message.

                    NOPAGE

                                        continuously scrolls information by on the screen.
                                        Does not wait for you to press a key to restart
                                        the scrolling movement.

                    NOSORT

                                        displays files in the order it finds them on the
                                        disk.  If this option is not included, DIR displays
                                        the files alphabetically.

                    RO

                                        displays only the files that have the Read-Only
                                            'bute.
                                        attri

                    RW

                                        displays only the files that are set to Read-Write.

                    SIZE                displays the filename and file size in kilobytes.

                    SYS

                                        displays only the files that have the SYS attribute.




                                                                        l@ DL(,ITAL RESEARCH'-
   -5-24

           CP/M 3 User's Guide                                                                      The DIR Command

                                                             Table 5-5. (continued)

                               Option                    Function

                               USER= ALL

                                                         displays all files under all the user numbers for
                                                         the default drive.

                               USER = n

                                                         displays the files under the user number specified
                                                         by n.

                               USER = (0,            15)

                                                         displays files under the user numbers specified.


            Examples:        A >DIR C: [FULL I
                             A >DIR C: RBIZEJ

                             The following is sample output of the [FULL] option display format
                             shown in the first example of the DIR command:

                 Directory for Drive C: User 0

                      Name.         Bytes     Recs     Attributes Prot                Update                    Access
                 ------------ ----- ------- ---------- ------ --------------- ---------------
                 DITS        BAK          IK         I Dir   RW         Read      09/01/82 13:04         09/01/82 13:07
                 DITS        TES          I K        I D i r RD         N o n e   09/01/82 13:07         0 9 / 0 1 / 8 21 3 : 0 9
                 DITS        y            IK         I Dir   RW         None      08/25/82 03:33         OB/25/82      03:33
                 DITS        zz           IK         I Dir   RW         None      Oe/25/82 03:36         00/25/82      03:36
                 SETOEF      COM          4K        29 Dir   RD         None                             08/25/82      03:38
                 SUBMIT      TX2          ik         I Dir   RD         None
                 SUBMIT      TXl          5k        43 Dir   RD         None

                 Total Bytes                    14k    Total Records =              77 Files Found                  7
                 Total lk BlocKs                1 4    Used/MaK Dir Entries for Drive C:                   1 1 /   64




              [)I("I I'Al, RESEAR(]H"'                                                                                  5-25

   The DIR Command                                                      CP/M 3 User's Guide

                  The following is sample output of the [SIZE] option display format
                  shown in the second example of the DIR command:

              Directory for Drive C.      U s e r0

              C; DITS        BAK    IK : DITS       TES     lk   DITS      y        lk
              C: DITS       zz      lk :  SETDEF    com     4k   SUBMIT    TX2      IR
              C: SUBMIT      TXl    5k :

              Total Bytes               14K Total   Records         77 Files Found           7
              Total IK ElocKs           14   Used/Max Dir Entries for Drive C:        II/ 64

                  Both the full format and the size format follow their display with two
                  lines of totals.  The first line displays the total number of kilobytes, the
                  total number of records, and the total number of files for that drive
                  and user area.  The second line displays the total number of 1K blocks
                  needed to store the listed files.  The number of 1K blocks shows the
                  amount of storage needed to store the files on a single density disk, or
                  on any drive that has a block size of one kilobyte.  The second line also
                  shows the number of directory entries used per number of directory
                  entries available on the drive.

                  A>DIR [DRIVE=CTFFJ

                  DIR sends a form-feed to the printer before displaying the files on
                  drive C.

                  A>DIRD: ER14tSI'SJ

                  The preceding example     displays all the files on drive D with Read-
                  Write and SYS attributes.

                  A>DIR C: CUSER=ALLJ

                  Displays all the files under each user number (0-15) on drive C.

                  A>DIR [USER=21

                  Displays all the files under user 2 on the default drive.


   5-26                                                                 @Ecl DIGITAL, RESEARCH"'

       CPIM I User's Guide                                                  The DIR Command

                       A >DIR C: [USER= (3 t4 p I 0) I

                       This example displays all the files under user numbers 3, 4, and 10 on
                       drive C.

                       A>DIR RDRIVE=ALLJ

                       Displays all the files under user 0 on all the drives in the drive search
                       chain. (See the SETDEF command.)

                       4A>DIR [DRIVE=CL

                       Displays all the files under user 4 on drive C.

                       A >DIR [DRI@JE= (B PO) J

                       Displays all the files under user 0 on drives B and D.

                       A>DIR lexcludej *,COM

                       The preceding example above lists all the files on the default drive and
                       user 0 that do not have a filetype of COM.

                       A>DIR Cuser=all Pdrive=all ts),sj *.PLI *#COM *#ASM

                       The preceding command line instructs DIR to list all the system files of
                       type PLI, COM, and ASM on the system in the currently active drives
                       for all the user numbers on the drives.

                       A >DIR X. SUB RMESSAGE t USER=ALL @DRI @)E=ALL J

                       The preceding command searches all drives under each user number for
                       X.SUB. During the search, DIR displays the drives and user numbers.

                       A>DIR fdrive=all tiser=allj TESTFILE.BOB

                       The preceding example instructs DIR to display the filename
                       T'ESTFILE.BOB if it is found on any logged-in drive for any user number.


        'Ea DIGITAL RESEARCH"'                                                              5-27

    The DIR Command                                                     CP/M 3 User's Guide

                   A>DIR rsize,,,rwJD:

                   The preceding example instructs DIR to list each Read-Write file that
                   resides on drive D with its size in kilobytes.  Note that D: is equivalent
                   to D:








                                                                       l@G 1)1(;ITAL RESEAR(,H"'
    5-28

       cp,m ' User's Guide                                             The DUMP Command


       The DUMP Command


       Syntax:      DUMP filespec

       Explanation: Dump displays the contents of a file in hexadecimal and ASCII format.

       Example:      A >DUMP ABC, TEX

                     Console output can look like the following:

                DUMP - Yersion 3.0
                0000: 41 42 43 OD OA 44 45 46 OD OA 47 48 49 OD OA IA ABC..DEF..GHI ....
                0010: 1A IA IA 1A IA LA IA IA IA 1A 1A 1A 1A IA 1A IA








       El-a] 1)1(;I'TAL. RESEAR(]H                                                      5-29

     ne ED Command                                                         CP/M 3 User's Guide

     The ED Command

     Syntax:       ED linput-filespec Id: I output-filespecll

     Explanation:  The ED transient utility lets you create and edit a disk file.

                   The ED utility is a line-oriented context editor.  This means that you
                   create and change character files line-by-line, or by referencing individual
                   characters within a line.

                   The ED utility lets you create or alter the file named in the file specifi-
                   cation.  Refer to Section 6 for a description of the ED utility.

                   The ED utility uses a portion of your user memory as the active text
                   buffer where you add, delete, or alter the characters in the file.  You use
                   the A command to read all or a portion of the file into the buffer.  You
                   use the W or E command to write all or a portion of the characters from
                   the buffer back to the file.

                   An imaginary character pointer, called CP, is at the beginning of the
                   buffer, between two characters in the buffer, or at the end of the buffer.

                   You interact with the ED utility in either command or insert mode.  ED
                   displays the * prompt on the screen when ED is in command mode.  When
                   the * appears, you can enter the single letter command that reads text
                   from the buffer,, moves the CP, or changes the ED mode of operation.
                   When in command mode, you can use the line-editing characters CTRL-
                   C, CTRL-E, CTRL-H, CTRL-U, CTRL-X, and RUBOUT to edit your
                   input.  In insert mode, however, you use only CTRL-H, CTRL-U, CTRL-
                   X, and RUBOUT.








                                                                         F'70 DIGITAL RESEARCH  T@
     -30

     CP/M 3 User's Guide                                         The ED Command

                                Table 5-6.  ED Command Summary
                   Command          Action

                   nA

                                    Append n lines from original file to memory
                                    buffer.

                   OA

                                    Append file until buffer is one half full.

                   *A

                                    Append file until buffer is full (or end of file).


                                    Move CP to beginning (B) or bottom (-B) of
                                    buffer.

                   nc t -nc

                                    Move CP n characters forward (C) or back (-C)

                   nD t -nD         through buffer.


                                    Delete n characters before (-D) or from (D) the
                                    CP.

                   E

                                    Save new file and return to CP/M 3.

                   Fstring('IZI

                                    Find character string.





     feel Dl(;ITAI.  RE.@'EAR(:H
                                                                             5-31

     T'he ED Command                                                 CP/M 3 User's Guide

                                         Table 5-6. (continued)

                    Command            Action

                    H

                                       Save the new file, then reedit, using the new file
                                       as the original file,


                                       Enter insert mode; use T Z or ESCape to exit
                                       insert mode.

                    Istririg('IZ@

                                       Insert string at CP.

                    Note: upper-case I forces all input to upper-case; while lower-case
                    i allows upper- and lower-case.

                    Js e a rc h-s t r Z i n s-s t r ' Zd e 1 -t o-s t r@ 'I Z I

                                       juxtapose strings.

                    r,K t -nK

                                       Delete (kill) n lines from the CP.

                    nL t -nL t OL

                                       Move CP n lines.

                    nmcommands


                    ri t - n           Execute commands n times.


                                       Move CP n lines and display that line.



                                                                    Liji Dl(;ITAI.  RESLAR(:H
    5-32

    CP/M 3 User's Guide                              The ED Command

                               Table 5-6. (continued)

                Command       Action

                n

                              Move to line n.

                :ncommand     Execute command through line n.

                Nstrinsf@'IZI

                              Extended find string.

                0


                nP t -nP      Return to original file.


                              Move CP n lines forward and display n lines at
                              console.

                              Abandon new file, return to CP/M 3.
                R@'I'Z )
                              Read X$$$$$$$.LIB file into buffer.
                Rfilespec('IZI
                              Read filespec into buffer.
                S d e 1 e t e s t r i n !f ' Z i n s e rt s t r i n !I( 'I Z I
                              Substitute string.

      1)1(;I-TAI. RLSLAR(,H"-'                                 5-33
    Tlc ED Command                              CP/M 3 Uscr's Guide

                             Table 5-6. (continued)

              Command       Action
              nT t -nT t OT

                            Type n lines.

              U  -U

                            Upper-case translation.

              V  -V t OY

                            Line numbering on/off, display free buffer space.

              nw

                            Write n lines to updated file.

              n X( 'I Z I

                            Write or append n lines to X$$$$$$$.LIB.

              nXfilespec(I'ZI

                            Write n lines to filespec or append if previous x
                            command applied to the same file.

              oxt +1 z I

                            Delete file X$$$$$$$.LIB.

              OXfilespec@'IZ)


              nZ            Delete filespec.


                            Wait n seconds.



                                                ,ED] DIGITAL RESEARCH:"
    5-34
       CP/M 3 User's Guide                                                        The ED Command

                       Section 6 gives a detailed description of the overall operation of the ED
                       utility and the use of each command.

                       If you do not include a command tail in the ED command, it prompts
                       you for the input filespec and the output filespec as follows:

                       En t e r I n P ut F i 1 e :

                       After you enter the input filespec, ED prompts again:

                       Ente r Output Fi le :

                       Enter a filename or drive if you want the output file or its location to
                       be different from that of the input file.  Press RETURN if you want the
                       output file to replace the input file.  In this case, the input file is renamed
                       to type BAK.

                       If the second file specification contains only the drive specifier, the
                       second filename and filetype become the same as the first filename and
                       filetype.

                       If the file given by the first file specification is not present, ED creates
                       the file and writes the message:

                       NEW FILE

                       If the file given by the first filespec is already present, you must issue
                       the A command to read portions of the file to the buffer.  If the size of
                       the file does not exceed the size of the buffer, the command

                       # a

                       reads the entire file to the buffer.

                       The 1 (Insert) command places ED in insert mode.  In this mode, any
                       characters you type are stored in sequence in the buffer starting at the
                       current CP.



        i-,'- DIGITAL. RLSEAR(,H                                                                  5-35

    T'he ED Command                                                      CP/M 3 User's Guide

                    Any single letter commands typed in insert mode are not interpreted as
                    commands, but are simply stored in the buffer.  To return from insert
                    mode to command mode, press CTRL-Z or the ESC kev.  Note that
                    you can always substitute the ESC key for CTRL-Z in ED.

                    The single letter commands are usually typed in lower-case.  The com-
                    mands that must be followed by a character sequence end with CTRL-
                    Z if they are to be followed by another command letter.

                    Any single letter command typed in upper-case tells ED to internally
                    translate to upper-case all characters up to the CTRL-Z that ends the
                    command.

                    When enabled, line numbers that appear on the left of the screen take
                    the form:

                    nnnnn:

                    where nnnnn is a number in the range 1 through 65535.  Line numbers
                    are displayed for your reference and are not contained in either the
                    buffer or the character file.  The screen line starts with


                    when the CP is at the beginning or end of the buffer.

    Examples:       A'>ED M)'PROG, PAS

                    If not already present, this command line creates the file MYPROG.PAS
                    on drive A. The command prompt


                    appears on the screen.  This tells you that the CP is at the beginning of
                    the buffer.  If the file is already present, issue the command

                    : * v a                                                                       I

                    to fill the buffer.  Then type the command

                    :*op


     S-36                                                                9 DIGITAL RESEARCH"'

       CP/M 3 User's Guide                                                   The ED Command

                     to fill the screen with the first n lines of the buffer , where n is the
                     current default page size (See the DEVICE command to set the page
                     size).

                     Type the command


                     to stop the ED utility when you are finished changing the character file.
                     The ED utility leaves the original file unchanged as MYPROG.BAK
                     and the altered file as MYPROG.PAS.

                     A >ED M@"PROG, PAS B:NEWPROG, PAS

                     The original file is MYPROG.PAS on the default drive A. The original
                     file remains unchanged when the ED utility finishes, with the altered
                     file stored as NEWPROG.PAS on drive B.

                     A >B:ED tl@'PROG, PAS B :

                     The ED.COM file must be on drive B. The original file is MYPROG.PAS
                     located on drive A. It remains unchanged, with the altered program
                     stored on drive B as MYPROG.PAS.








          1)1(@l I Al- RL.@EARC@H                                                          5-37

    ne ERASE Command                                                CP/M 3 User's Guide

   The ERASE Command

   Syntax:       ERASE ifilespecl i[CONFIRM]l

   Explanation:  The ERASE command removes one or more files from a disk's direc-
                 tory in the current user number.  Wildcard characters are accepted in
                 the filespec.  Directory and data space are automatically reclaimed for
                 later use by another file.  The ERASE command can be abbreviated to
                 ERA.

                 Use the ERASE command with care because all files in the current user
                 number that satisfy the file specification are removed from the disk
                 directory.

                 Command lines that take the form

                 ERASE id:lwlldcard-filespec

                 require your confirmation because they erase an entire group of files,
                 not 'ust one file.  The system prompts with the following message:
                     I

                 ERASE @ d : lw i 1 d c a rd - f i 1 e s Pe c ( Y /N ) ?

                 Respond with y if you want to remove all matching files, and n if you
                             'd erasing any files.
                 want to avot

                 If no files match the file specification, you see the following message:

                 No Fi le

                 The CONFIRM option informs the system to prompt for verification
                 before erasing each file that matches the filespec.  You can abbreviate
                 CONFIRM to C.

                 If you use the CONFIRM option with wildcard-filespec, then ERASE
                 prompts for confirmation for each file.  You can selectively erase the
                 files you want by responding Y to the confirm message, or keep the
                 files by responding N to the confirm message.

    5-38                                                            @lc@ DI(;I-FA[, RESEAR(,Ei"'

      CPIM I U,er', Guide                                            The ERASE Command

      Examples:     A >ERASE X - PAS

                    This command removes the file X.PAS from the disk in drive A.

                    A"/, ERA *. PRN

                    The systen,,, asks to confirm:

                    ERASE *.PRN (Y/N)?Y

                    All files with the filetype PRN are removed from the disk in drive A.

                    B >ERA A: MY*. * ECONFIRMJ

                    Each file on drive A with a filename that begins with MY is displayed
                    with a question mark for confirmation.  Type Y to erase the file dis-
                    played, N to keep the file.

                    A >ERA B: * # *
                    ERASE B: *. * (Y /N) ? Y

                    All files on drive B are removed from the disk.








         1)1(11-I'Al- RESEAR(]H                                                       5-39

    The GENCOM Command                                                  CP/M 3 User's Guide

    The GENCOM Command

    Syntax:        GENCOM ICOM-filespecl fRSX-filespecl...
                                               F[LOADERINULLISCB = (offset,value)])

    Explanation:   The GENCOM command is a transient utility that creates a special
                   COM file with attached RSX files.  RSX files are used as Resident Sys-
                   tem Extensions and are discussed in detail in the CPIM Plus (CP/M
                   Version 3) Operating System Programmer's Guide.  GENCOM places a
                   special header at the beginning of the output program file to indicate
                   to the system that RSX loading is required.  It can also set a flag to
                   keep the program loader active.

                   The GENCOM command can also restore a file already processed by
                   GENCOM to the original COM file without the header and RSXS.
                   GENCOM has three options that help you attach RSX files:

                   0  The LOADER option sets a flag to keep the program loader active.
                      (For complete details on the LOADER option read about CP/M
                      function 59 in the CPIM Plus (CPIM Version 3) Operating System
                      Programmer's Guide.) This option is used only if no RSX files are
                      attached to the COM file.
                   0  The NULL option indicates that only RSX files are specified.
                      GENCOM creates a dummy COM file for the RSX files.  The output
                      COM filename is taken from the filename of the first RSX-filespec.
                   0  The SCB = (offset,value) option sets the System Control Block from
                      the program by using the hex values specified by (offset,value).  For
                      complete details on the SCB option read about CP/M function 49 in
                      the CPIM Plus (CPIM Version 3) Operating System Programmer's
                      Guide.

     Attach RSX Files to a COM File

     Syntax:       GENCOM COM-filespec RSX-filespec...
                                                            [LOADERISCB = (offset,value)]l


     5-40                                                               l@c 1)1(,ITAL RESEAR(,'l I"'

      cp,m ' U,C","Gui",                                              The GENCOM Command

      Explanation: The preceding form of the GENCOM command creates a COM file
                     with a header and attached RSXS.  A maximum of 15 RSXs can be
                     attached.  GENCOM expects the first filespec to be a COM file and the
                     following filespecs to be RSX files.  Note that the original COM file is
                     replaced by the newly-created COM file.

      Example:       A >GENCOM 11@'PROG PROGI PROG2

                     The preceding command generates a new COM file MYPROG.COM
                     with attached RSXs PROG1 and PROG2.


      Generate a COM File Using only RSX Files

      Syntax:        GENCOM RSX-filespec fRSX-filespecl...
                                               [NULL FSCB = (offset,value)l]

      Explanation:   The preceding form of the GENCOM command attaches the RSX files
                     to a dummy COM file.  GENCOM creates a COM file with the file-
                     name of the first RSX-filespec in the command tail.  This format allows
                     the system to load RSXs directly.

      Example:       A>GENCOtl PROGI PROG2 ENULLJ

                     The preceding command creates a COM file PROG1.COM with Resi-
                     dent System Extensions PROG1.RSX and PROG2.RSX.


      Restore a File with Attached RSXs to Original COM File

      Syntax:        GENCOM filename

      Explanation: The preceding form of the GENCOM file takes a file that has already
                     been processed by GENCOM and restores it to its original COM file
                     format.  This form of the command assumes a filetype of COM.

      Example:       A> GENCOM tlYPROG

                     In the preceding command, GENCOM takes MYPROG.COM, strips
                     off the header and deletes all attached RSXs to restore it to its original
                     COM format.

                 RI-.SEAR('Ii
                                                                                             5-41

     The GENCOM Command                                              CP/M 3 User's Guide

     Update (Add or Replace) RSX Files

     Syntax:      GENCOM COM-filespec RSX-filespec...
                                                      I[LOADER I SCB = (offset,value)]l

     Explanation: The preceding form of the GENCOM command adds and/or replaces
                  RSX files to a file already processed by GENCOM.

                  GENCOM inspects the list of RSX files.  If they are new, they are added
                  to the file already processed by GENCOM.  If they already exist, then
                  GENCOM replaces the existing RSXs with the new RSX files.

     Example:     A> GENCOM MYPROG PROGI PROG2

                  In the preceding example, GENCOM looks at MYPROG.COM, which
                  is already processed by GENCOM, to see if PROG1.RSX and
                  PROG2.RSX are already attached RSX files in the module.  If either
                  one is already attached, GENCOM replaces it with the new RSX mod-
                  ule.  Otherwise, GENCOM appends the specified RSX files to the COM
                  file.

     Attach a Header Record

     Syntax:      GENCOM filename [SCB = (offset,value),... I LOADER]

     Explanation: The preceding syntax line attaches a GENCOM header record, with
                  the SCB or loader flag set, to a file of type COM that contains no
                  RSXS.  This form of the command does not attach RSXs to a file.








                                                                  - [W DIGITAL RESEARCH T@l
     5-42

     CPIM I U,cr', Guil,,                                           The GENCOM Command

     Examples:     A>GENCOMFILETIWO IloaderJ

                   The preceding command attaches a 256-byte header record to the file
                   FILETWO.COM and sets the loader flag in the header record.

                   A>GENCOMFILEFOUR rscb=(l tl)J

                   The preceding command causes the program loader to set byte 1 of the
                   System Control Block to 1 when it loads FILEFOUR.COM.

                   For more information,, see functions 49, Set/Get System Control Block,
                   and 59, Load Overlay or Resident System Extensions, in the CPIM Plus
                   (CPIM Version 3) Operating System Programmer's Guide.








     Ec Dl(,ITAI, RESEAR(.H"'                                                           5-43

     'ne GET Command                                                  CP/M 3 User's Guide

     The GET Command

     Syntax:       GET {CONSOLE INPUT FROM) FILE filespec
                                                         f[fECHOINO ECHOJISYSTEMIJ
                   GET ICONSOLE INPUT FROMI CONSOLE

     Explanation:  The GET command is a transient utility that directs CP/M 3 to take
                   console input from a file.  The file can contain CP/M 3 system com-
                   mands and/or input for a user program.  If you use the SYSTEM option,
                   GET immediately takes the next system command from the file.

                   Console input is taken from a file until the program terminates.  If the
                   file is exhausted before program input is terminated, the program looks
                   for subsequent input from the console.  If the program terminates before
                   exhausting all its input, the system reverts back to the console for
                   console input.

                   When the SYSTEM option is used, the system immediately goes to the
                   file specified for console input.  If you omit the SYSTEM option, you
                   can enter one system command to initiate a user program whose con-
                   sole input is taken from the file specified in the GET command.  The
                   system reverts to the console for input when it reaches the end of the
                   GET file input.  The system also reverts to the console for console input
                   if a GET CONSOLE INPUT FROM CONSOLE command is included
                   in the input file.

     Get Console Input from a File

     Syntax:       GET ICONSOLE INPUT FROMI FILE filespec {[options])

     Explanation: The preceding form of the GET command tells the system to get sub-
                   sequent console input from a file.  Table 5-7 lists the GET options that
                   you use in the following format:

                   [JECHO I NO ECHOI I SYSTEM]



     5-44                                                              100 DIGITAL RESEARCH"

      CPIM I U5er', Guide                     Table 5-7. GET Options         The GET Command


                         Option                                  Meaning

                      ECHO                  specifies that the input is echoed to the console.
                                            This is the default option.

                      NO ECHO               specifies that the file input is not to be echoed to
                                            the console.  The program output and the system
                                            prompts are not affected by this option and are
                                            still echoed to the console.

                      SYSTEM                specifies that all system input is to be taken from
                                            the disk file specified in the command line.  GET
                                            takes system and program input from the file until
                                            the file is exhausted or until GET reads a GET
                                            console command from the file.


      Examples:      A> GET FILE XINPUT
                     A>MYPROG

                     The preceding sequence of commands tells the system to activate the
                     GET utility.  However, because SYSTEM is not specified, the system
                     reads the next input line from the console and executes MYPROG.  If
                     MYPROG program requires console input, it is taken from the file
                     XINPUT.  When MYPROG terminates, the system reverts to the con-
                     sole for console input.

                     A>GET FILE XIN2 rsYSTEMI

                     The preceding command immediately directs the system to get subse-
                     quent console input from file XIN2 because it includes the SYSTEM
                     option.  The system reverts to the console for console input when it
                     reaches the end of file in XIN2.  Or, XIN2 can redirect the system back
                     to the console if it contains a GET CONSOLE command.




       IL70 DL(,ITAL RLSLAR(H"'                                                              5-45

    'ne GET Command                                                   CP/M 3 User's Guide

    Terminate Console Input from a File

    Syntax:       GET FCONSOLE INPUT FROMI CONSOLE

    Explanation:  Ile preceding form of the GET command tells the system to get con-
                  sole input from the console.

    Example:      A >GET CONSOLE

                  The preceding GET command tells the system to get console input from
                  the console.  You can use this command in a file (previously specified in
                  a GET FILE command) which is already being read by the system for
                  console input.  It is used to redirect the console input to the console
                  before the end of the file is reached.








                                                                      0 DL(.ITAL RESEAR(-H"'
    5-46

        cp,m ' User's Guide                                                The HELP Command

        The HELP Command


        Syntax:       HELP Itopiclfsubtopicl subtopic2 ... subtopic8lf[NO PAGEILIST]L
                      HELP [EXTRACT]
                      HELP[CREATE]

        Explanation:  The HELP command is a transient utility that provides summarized
                      information for all of the CP/M 3 commands described in this manual.
                      In the distributed CP/M 3 system, HELP presents general information
                      on a command as a topic and detailed information on a command as a
                      subtopic.  HELP with no command tall displays a list of all the available
                      topics.  HELP with a topic in the command tail displays information
                      about that topic, followed by any available subtopics.  HELP with a
                      topic and a subtopic displays information about the specific subtopic.

                      After HELP displays the information for your specified topic, it displays
                      the special prompt HELP> on your screen.  Subtopics can be accessed
                      by preceding the subtopic with a period.  The period causes the subtopic
                                                                                             i
                      search to begin at the last known level.  You can continue to specify
                      topics for additional information, or simply press the RETURN key to
                      return to the CP/M 3 system prompt.

                      You can abbreviate the names of topics and subtopics.  Usually one or
                      two letters is enough to specifically identify the topics.


        Display Information

        Syntax:       HELP topic fsubtopicl ... subtopic8lf[NO PAGE!LIST]L
                      HELP>.Subtopic

        Explanation:  The preceding forms of the HELP command display the information
                      for the specified topic and subtopics.  Use the following two options
                      with this form of the HELP command:

                      n  The NOPAGE option disables the default paged display of every n
                         lines, where n is the number of lines per page as set by the system or
                         as set by the user.  To stop the display, press CTRL-S.  To resume the
                         display, press CTRL-Q.  You can abbreviate NOPAGE to N. (See the
                         DEVICE command for more information about setting the number
                         of lines per page.)

        @c I)IGITAL. RLSLAR(:H"@                                                            5-47

    -Me HELP Command                                                     CP/M 3 User's Guide

                   m The LIST option is the same as NOPAGE, except that it eliminates
                     extra lines between headings.  Use this option with CTRL-P to list
                     the help information on the printer.

    Examples:      A>HELP

                   The preceding command displays a list of topics for which help is
                      ']able.
                   aval

                   A>HELP DATE

                   This command displays general information about the DATE com-
                   mand.  It also displays any available subtopics.

                   A>HELP DIR OPTIONS rNJ

                   The preceding command includes the subtopic options.  In response,
                   HELP displays information about options associated with the DIR
                   command.  The display is not in paged mode.

                   A >HELP ED

                   The preceding command displays general information about the ED
                   utility.

                   A:>HELP ED COMMANDS

                   This form of HELP displays information about commands internal to
                   ED. The preceding example can also be entered as

                   A>HELP ED
                   HELP>.CDMMANDS

    Add Your Own Descriptions to the HELP.HLP File

    Syntax:        HELP [EXTRACT,]
                   HELP[CREATE]


    5-48                                                                9 DIGITAL, RESEARCH"'

         CP/M 3 User's Guide                                                The HELP Command

         Explanation:  CP/M 3 is distributed with two related HELP files: HELP.COM and
                       HELP.HLP. The HELP.COM file is the command file that processes
                       the text of the HELP.HLP file and displays it on the screen.  The
                       HELP.HLP file is a text file to which you can add customized informa-
                       tion, but you cannot directly edit the HELP.HLP file.  You must use the
                       HELP.COM file to convert HELP.HLP to a file named HELP.DAT
                       before you can edit or add your own text.

                       This form of the HELP command has the following options:

                       0  The EXTRACT option accesses the file HELP.HLP on the default
                          drive and creates a file called HELP.DAT on the default drive.  You
                          can now invoke a word processing program to edit or add your own
                          text to the HELP.DAT file.  EXTRACT can be abbreviated to E.
                       0  The CREATE option accesses your edited HELP.DAT file on the
                          default drive and builds a revised HELP.HLP file on the default drive.
                          CREATE can be abbreviated to C.

                       You must add topics and subtopics to the HELP.DAT file in a specific
                       format.  A topic heading in the HELP.DAT file takes the form:

                       ///nTopicname<cr>

                       The three backslashes are the topic delimiters and must begin in col-
                       umn one.  In the preceding format statement, n is a number in the range
                       from 1 through 9 that signifies the level of the topic.  A main topic
                       always has a level number of 1. The first subtopic has a level number
                       of 2. The next level of subtopic has a level number of 3, and so forth,
                       up to a maximum of nine levels.  Topicname is the name of your topic,
                       and allows a maximum of twelve characters.  The entire line is termi-
                       nated with a carriage return.

                       Use the following guidelines to edit and insert text into the HELP.DAT
                       file.

                          Topics should be placed in alphabetical order.
                          Subtopics should be placed alphabetically within their respective
                          supertopic.
                          Levels must be indicated by a number 1-9.


         l@o [)[(,I-FAL RESEAR('H"'                                                          5-49

   T'he HELP Command                                                  CP/M 3 User's Guide

                  Some examples of topic and subtopic lines in the HELP.HLP file follow

                  ///lNEW UTILITY<cr>

                  ///2COMMANDS<cr>

                  ///3PARAMETERS<cr>

                  ///2EXAMPLES<cr>

                  The first example illustrates the format of a main topic line.  The second
                  example shows how to number the first subtopic of that main topic.
                  The third example shows how the next level subtopic under level 2
                  should be numbered.  The fourth example shows how to return to the
                  lower level subtopics Any topic name with a level number of 1 is a
                  main topic.  Any topic name with a level number of 2 is a subtopic
                  within its main topic.

                  When you are executing the HELP.COM file, you need only enter enough
                  letters of the topic to unambiguously identify the topic name.  When
                  referencing a subtopics you must type the topic name AND the sub-
                  topic, otherwise the HELP program cannot determine which main topic
                  you are referencing.  You can also enter a topic and subtopic following
                  the program's internal prompt, HELP>, as follows

                  HELP>ED COMMANDS

                  This form of HELP displays information about commands internal to
                  the editing program, ED.







   5-50                                                               ILCI 1)1(;ITAL RESEARCH"

       CP/M 3 User's Guide                                        The HEXCOM Command

       The HEXCOM Command


       Syntax:      HEXCOM filename

       Explanation: The HEXCOM command is a transient utility that generates a com-
                    mand file (filetype COM) from a HEX input file.  It names the output
                    file with the same filename as the input file but with filetype COM.
                    HEXCOM always looks for a file with filetype HEX.

       Example:     A> HEXCOM B.- PROGRAII

                    In the preceding command, HEXCOM generates a command file
                    PROGRAM.COM from the input hex file PROGRAM.HEX.








         [)I("]I-AL RESEARCH"'                                                         5-51

    The INITDIR Command                                                 CP/M 3 User's Guide

   The INITDIR Command


   Syntax:        INITDIR d:

   Explanation:   The INITDIR command can initialize a disk directory to allow date
                  and time stamping of files on that disk or remove date and time stamps.

                  You must use INITDIR to initialize the directory for any disk on which
                  you plan to record date and time stamps for your files.  If the disk is
                  blank, INITDIR initializes the directory to record date and time stamps.
                  If files already exist on the disk, INITDIR checks the space available
                  for date and time stamps in the directory.  If there is not enough room
                  for date and time stamps, INITDIR does not initialize the directory and
                  returns an error message.

                  After you initialize the directory for date and time stamps, you must
                  use the SET command to specify time stamp options on the disk.

   Examples:      A>INITDIR C:

                  The system prompts to confirm:

                  INITDIR WILL ACTIVATE TIME STAMPS FOR SPECIFIED DRIVE.
                  Do You real ly want to re-f a rmat the di recto ry : C ( Y/N) ?

                  If the directory has previously been initialized for date and time stamps,
                  INITDIR displays the message:

                  Di re oto ry al ready re-f o rmatte,J
                  Do Y c u w i sh to rec o ve r d ate/t ime d i rec to ry s Pac e
                  ( Y / N ) ?

                  Enter Y to reinitialize the directory to eliminate date and time stamps.
                  If you enter N, date and time stamping remains active on your disk
                  and INITDIR displays the following message:

                  Do Y ou wan t th e e x i st i n 9 d ate/t ime s tamps c 1 ea red ( Y/N ) ?

                  Enter Y to clear the existing stamps.  Enter N to keep the existing date
                  and time stamps.


   5-52                                                                  I 1)1('.ITAL RESEAI@('H

        CP/M 3 User's Guide                                                    The LIB Command

        The LIB Command


        Syntax:       LIB filespec{[IIMIPID]l
                      LIB filespecf [IIMIP]L = filespeclmodifierl
                                                f,filespeclmodifierl ... I

        Explanation:  A library file contains a collection of ob'ect modules. Use the LIB utility
                                                                I
                      to create libraries, and to append, replace, select, or delete modules
                      from an existing library.  You can also use LIB to obtain information
                      about the contents of library files.

                      LIB creates and maintains library files that contain object modules in
                      MicroSoft@ REL format.  These modules are produced by Digital
                      Research's relocatable macro-assembler program, RMAC, or any other
                      language translator that produces modules in MicroSoft REL format.

                      LINK-80" links the object modules contained in a library to other
                      ob'ect files.  LINK-80 automatically selects from the library only those
                         i
                      modules needed by the program being linked, and then forms an exe-
                      cutable file with a filetype of COM.

                      The library file has the filetype REL or IRL depending on the option
                      you choose.  Modules in a REL library file must not contain backward
                      references to modules that occur earlier in the library, because LINK-
                      80 currently makes only one pass through a library.








          t)l(,I'I'Al.  RESEAR(I[I
                                                                                              5-5 3

    The LIB Command                                                         CP/M 3 User's Guide

                                             Table 5-8.  LIB Options
                     Option                                   Meaning

                        I             The INDEX option creates an indexed library file of
                                      type IRL.  LINK-80 searches faster on indexed librar-
                                      ies than on nonindexed libraries.

                       m              The MODULE option displays module names.

                        p             The PUBLICS option displays module names and the
                                      public variables for the new library file.

                        D             The DUMP option displays the contents of object
                                      modules in ASCII form.


                   Use modifiers in the command line to instruct LIB to delete, replace, or
                   select modules in a library file.  Angle brackets enclose the modules to
                   be deleted or replaced.  Parentheses enclose the modules to be selected.

                   Unless otherwise specified, LIB assumes a filetype of REL for all source
                   filenames.  When you follow a filename by a group of module names
                   enclosed in parentheses, these modules are included in the new library
                   file.  If modules are not specified, LIB includes all modules from the
                   source file in the new library file.

                                            Table 5-9.  LIB Modifiers
                     Modifier                                  Meaning

                     Delete             <module = >

                     Replace            <module = filename.REL>

                                        If module name and filename are the same this
                                        shorthand can be used:

                                        <filename>

                     Select             (modFIRST-modLAST,modl,mod2,...,modN)

                                                                            100 DIGITAL RESEARCH"
    5-54

       CP/M 3 User's Guide                                               The LIB Command

       Examples:     A>LIB TEST4rpi
                     A>LIB TEST5[P]=FILEI tFILE2

                     The first example displays all modules and publics in TEST4.REL. The
                     second example creates TEST5.REL from FILEL.REL and FILE2.REL,
                     and displays all modules and publics in TEST5.REL.

                     A >L IB TEST= TESTI (MODI tMOD4) o TESTZ (Cl -C4 PCG)

                     In the preceding example LIB creates a library file TEST.REL from
                     modules in two source files.  TEST1.REL contributes MOD1 and MOD4.
                     LIB extracts modules Cl, C4, all the modules located between them,
                     and module C6 from TEST2.REL.

                     A>LIB FILEZ=FILE3<MDDA=>

                     In this example, LIB creates FILE2.REL from FILE3.REL, omitting
                     MODA which is a module in FILE3.REL.

                     A>LIB FILE6=FILE5<tlODA=FILEB#REL>
                     A>LIB FILE6=FILE5<THISNAME>

                     In the first example, MODA is in the existing FILE5.REL. When LIB
                     creates FILE6.REL from FILE5.REL, FILEB.REL replaces MODA.

                     In the second example, module THISNAME is in FILES.REL. When
                     LIB creates FILE6.REI, from FILES.REL the file THISNAME.REL
                     replaces the similarly named module THISNAME.

                     A>LIB FILEI[I]=B:FILE2(PLOTSPFINDPSEARCH-DISPLAY)

                     In this example LIB creates FILE1.IRL on drive A from the selected
                     modules PLOTS, FIND, and modules SEARCH through the module
                     DISPLAY, in FILE2.REL on drive B.





        En Dl(,ITAL, RESEARCH"@                                                         5-55

   The LINK Command                                                       CP/M 3 User's Guide


   The LINK Command


   Syntax:        LINK difilespec,f[o]l=lfilespeci[o]li,.--@

   Explanation:   The LINK command combines relocatable ob'ect modules such as those
                                                                   i
                  produced by RMAC and PL/1-80" into a COM file ready for execu-
                  tion.  Relocatable files can contain external references and publics.  Relocat-
                  able files can reference modules in library files.  LINK searches the library
                  files and includes the referenced modules in the output file.  The LINK
                  command is the LINK-80 utility and are synonymous in this discussion.
                  See the Programmer's Utilities Guide for the CPIM Family of Operat-
                  ing Systems for a complete description of LINK-80.

                  You can use LINK option switches to control the execution parameters
                  of LINK-80.  LINK options follow the file specifications and are enclosed
                  within square brackets.  Multiple switches are separated by commas.


                                          Table 5-10. LINK Options

                    Option                                   Meaning

                    A                Additional memory; reduces buffer space and writes
                                     temporary data to disk.

                    B                BIOS link in banked CP/M 3 system. Aligns data
                                     segment on page boundary; puts length of code seg-
                                     ment in header; defaults to SPR filetype.

                    Dbhhh            Data origin; sets memory origin for common and
                                     data area.

                    Gn               Go; set start address to label n.

                    Lhhhh            Load; change default load address of module to hhhh.
                                     Default 0100H.

                    Mhhhh            Memory size; define free memory requirements for
                                     MP/M" modules.

                    NL               No listing of symbol table at console.


                                                                         Eo DIGITAL RESEARCHTY
   5-56

        cp,m     User's Guide                                                 The LINK Command

                                                Table 5-10. (continued)

                         Option                                  Meaning

                         NR               No symbol table file.

                         oc               Output COM command file. Default.

                         OP               Output PRL page relocatable file for execution under
                                          MP/M in relocatable segment.

                         OR               Output RSP Resident System Process file for execu-
                                          tion under MP/M.

                         Os               Output SPR System Page Relocatable file for execu-
                                          tion under MP/M.

                         Phhhh            Program origin; changes default program origin
                                          address to hhhh.  Default is 0100H.

                         Q                Lists symbols with leading question mark.

                         s                Search preceding file as a library.

                         $Cd              Destination of console messages, d, can be X for
                                          console, Y for printer, or Z for zero output.  Default
                                          is X.

                         $Id              Source of intermediate files; d is disk drive A-P.
                                          Default is current drive.

                         $Ld              Source of library files; d is disk drive A-P. Default is
                                          current drive.

                         $Od              Destination of object file; d can be Z, or disk drive
                                          A-P.  Default is to same drive as first file in the LINK-
                                          80 command.

                         $Sd              Destination of symbol file; d can be Y, Z, or disk
                                          drive A-P.  Default is to same drive as first file in
                                          LINK-80 command.


         IL79 DIGITAL RESEARCH"'                                                               5-57

   The LINK Command                                                 CP/M 3 User's Guide

   Examples:     A>LINK B:MYFILE[NRJ

                 LINK-80 on drive A uses as input MYFILE.REL on drive B and pro-
                 duces the executable machine code file MYFILE.COM on drive B. The
                 [NR] option specifies no symbol table file.

                 A>LINK ml ,ftt2tftt3

                 LINK-80 combines the separately compiled files ml, m2, and m3, resolves
                 their external references', and produces the executable machine code file
                 ml.COM.

                 A>LINK ftt=tnl pftt2pm3

                 LINK-80 combines the separately compiled files ml, m2, and m3 and
                 produces the executable machine code file M.COM.

                 A>LINK MYFILEtFILE5EsJ

                 The [s] option tells LINK-80 to search FILE5 as a library.  LINK-80
                 combines MYFILE.REL with the referenced subroutines contained in
                 FILE5.REL on the default drive A and produces MYFILE.COM on
                 drive A.








                                                                   -1c] DIGITAL RESEARCH"'
  5-58

       CP/M 3 User's Guide                                               The MAC Cotnmand

       The MAC Command

       Syntax:       MAC filename I$optionsl

       Explanation:  MAC, the CP/M Macro Assembler, is a transient utility that reads
                     assembly language statements from a disk file of filetype ASM.  MAC
                     assembles the statements and produces three output files with the input
                     filename and output filetypes of HEX, PRN, and SYM.

                     Filename.HEX contains IntelO hexadecimal format ob'ect code.  You
                                                                             I
                     can debug the HEX file with a debugger, or use HEX COM to create a
                     COM file and execute it.

                     Filename.PRN contains an annotated source listing that can be printed
                     or examined at the console.  The PRN file includes a 16-column wide
                     listing at the left side of the page that shows the values of literals,
                     machine code addresses, and generated machine code.  An equal sign
                     denotes literal addresses to eliminate confusion with machine code
                     addresses.

                     Filename.SYM contains a sorted list of symbols defined in the program.

                     Before invoking MAC, you must prepare a source program file with
                     the filetype ASM containing assembly language statements.

                     You can direct the input and output of MAC using the options listed
                     in the following table.  Use a letter with the option to indicate the
                     source and destination drives, console, printer, or zero output.  Valid
                     drive names are A through 0. X directs output to the console.  P directs
                     output to the printer.  Z specifies that output files will not be created.








        IEOL Dl(,ITAI- RESEAR(,H"'
                                                                                          5-59



                                                                                                IN

     The MAC Command                                                    CP/M 3 User's Guide

                                      Table 5-11. Input/Output Options
                     Option                                 Meaning

                        A            source drive for ASM file (A-0)

                        H            destination drive for HEX file (A-0, Z)

                        L            source drive for macro library LIB files called by the
                                     MACLIB statement.

                        p            destination drive for PRN file (A-0, X, P, Z)

                        s            destination drive for SYM file (A-0, X, P, Z)


                                      Table 5-12. Output File Modifiers
                     Modifier                               Meaning

                        + L            lists input lines read from macro library LIB files
                        - L            suppresses listing (default)

                        +M             lists all macro lines as they are processed during
                                       assembly
                        - m            suppresses all macro lines as they are read during
                                       assembly
                        *M             lists only hex generated by macro expansions

                        + Q            lists all LOCAL symbols in the symbol list
                        - Q            suppresses all LOCAL symbols in the symbol list
                                       (default)

                        + s            appends symbol file to print file
                        - s            suppresses creation of symbol file

                        + 1            produces a pass 1 listing for macro debugging in
                                       PRN file
                                       suppresses listing on pass 1 (default)





                                                                        9 DIGITAL RESEARCH"
      5-60

       CP/M 3 User's Guide                                             The NUC Command

       Examples:    A >MAC SAMPLE

                    In the preceding example MAC is invoked from drive A and operates
                    on the file SAMPLE.ASM also on drive A.

                    A>MAC SAMPLE $PB AA HB SX

                    In this example, an assembly option parameter list follows the MAC
                    command and the source filename.  The parameters direct the PRN file
                    to drive B. obtain the ASM file from drive A, direct the HEX file to
                    drive B,, and send the SYM file to the console.  You can use blanks
                    between option parameters.








         LKGJ 1)1(;['FAL RESEAR('H
                                                                                        5-61

    ]Me PATCH Command                                               CP/M 3 User's Guide

    The PATCH Command

    Syntax:      PATCH filename Itypl inj

    Explanation: The PATCH command displays or installs patch number n to the
                 CP/M 3 system or CP/M 3 command files.

                 Only CP/M 3 system files of filetype COM, PRL, or SPR can be patched
                 with the PATCH command.  If the typ option is not specified, the PATCH
                   'I'ty looks for a file with a filetype of COM.
                 uti I

                 The patch number n must be between 1 and 32 inclusive.

    Examples:    A > PA TCH SH014 2

                 The preceding command patches the system SHOW.COM file with
                 patch number 2. The system displays the followin question:
                                                                  9

                 Do Y o u wan t to i n d i c at e t hat Pat ch #2
                 h as b een i n s ta 1 1 e d f o r SHOW . COM?  Y

                 If the patch is successful, the system displays the message:

                 Pat c h I n s t a 1 1 e d

                 If the patch is not successful, the system displays the following mes-
                 sage:

                 Patch not Instal I ed

                 One of the following error messages might be displayed:

                 0 ERROR: Patch requires CP/M 3.
                 0 ERROR: Invalid filetype typ.
                 n ERROR: Serial Number mismatch.
                 m ERROR: Invalid patch number n






                                                                   9 DIGITAL RESEARCH"
    5-62

     CP/M 3 User's Guide                                                      The PIP Command

     The PIP Command

     Syntax:         PIP dest-filespecld:f [Gn]} = src-filespec{[o]H,...l @ d: f [o]l

     Explanation:    PIP is a transient utility that copies one or more files from one disk
                     and/or user number to another.  PIP can rename a file after copying it.
                     PIP can combine two or more files into one file.  PIP can also copy a
                     character file from disk to the printer or other auxiliary logical output
                     device.  PIP can create a file on disk from input from the console or
                     other logical input device.  PIP can transfer data from a logical input
                     device to a logical output device, thus the name Peripheral Interchange
                     Program.

                     PIP copies file attributes with the file.  This includes Read-Write or
                     Read-Only and SYS or DIR file attributes and the user-definable attri-
                     butes Fl through F4.  If a file is password-protected, you must enter the
                     password in the command line following the filename and/or filetype to
                     which it belongs.  If the password fails, the file is skipped and the failure
                     noted.

                     When you specify a destination file with a password, PIP assigns that
                     password to the destination file and automatically sets the password
                     protection mode to READ.  When you specify a destination file with no
                     password, PIP does not assign a password to the destination file.  When
                              'fy only a destination drive, PIP assigns the same password and
                     you speci
                     password protection mode to the destination file as specified in the
                     source file.  When you specify a destination file with a password, PIP
                     automatically sets the password protection mode to READ.  This means
                     that you need a password to read the file. (See the SET command.)

      Single File Copy

      Syntax:        PIP d:{[Gn]l = src-filespeci[options]l

                     PIP dest-filespecf[Gn]l = d:l[options]}

                     PIP dest-filespecf[Gn]l = src-filespeci[o]l





      9 DIGITAL RESEARCH'@
                                                                                             5-63

    T'he PIP Command                                                       CP/M 3 User's Guide

     Explanation:  The first form shows the simplest way to copy a file. PIP looks for the
                   file named by src-filespec on the default or optionally specified drive.
                   PIP copies the file to the drive specified by d: and gives it the name
                        'fied by src-filespec.  If you want, you can use the [Gn] option to
                   speci
                   place your destination file (dest-filespec) in the user number specified by
                   n. The only option recognized for the destination file is [Gn].  Several
                   options can be combined together for the source file specification (src-
                   filespec).  See the Table 5-13, PIP options.

                   The second form is a variation of the first.  PIP looks for the file named
                   by dest-filespec on the drive specified by d:, copies it to the default or
                   optionally specified drive, and gives it the name specified by dest-filespec.

                   The third form shows how to rename the file after you copy it.  You
                   can copy it to the same drive and user number, or to a different drive
                   and/or user number.  Rules for options are the same.  PIP looks for the
                   file specified by src-filespec, copies it to the location specified in dest-
                   filespec, and gives it the name indicated by dest-filespec.

                   Remember that PIP always goes to and gets from the current default
                   user number unless you specify otherwise with the [Gn] option.

                   Before you start PIP, be sure that you have enough free space in kilo-
                   bytes on your destination disk to hold the entire file or files that you
                   are copying.  Even if you are replacing an old copy on the destination
                   disk with a new copy, PIP still needs enough room for the new copy
                   before it deletes the old copy.  Use the DIR command to determine
                   filesize and the SHOW command to determine disk space.  If there is
                   not enough space, you can delete the old copy first by using the ERASE
                   command.

                   Data is first copied to a temporary file to ensure that the entire data file
                   can be constructed in the space available on the disk.  PIP gives the
                   temporary file the filename specified for the destination, with the file-
                   type $$$.  If the copy operation is successful, PIP changes the temporary
                   filetype $$$ to the filetype specified in the destination.

                   If the copy operation succeeds and a file with the same name as the
                   destination file already exists, the old file with the same name is erased
                   before renaming the temporary file.



                                                                          IGJ I)I(;ITAL, RESEAR("H"@
    5-64

      CPIM I U,,,,,', Guile                                                     The PIP Command

                      File attributes (DIR, SYS, RO, RW) are transferred with the files.
                                                                               I

                      If the existing destination file is set to Read-Only (RO), PIP asks you if
                      you want to delete it.  Answer Y or N. Use the [W] option to write over
                      Read-Only files.

                      You can include PIP options following each source name.  There is one
                      valid option ([Gn]-go to user number n) for the destination file speci-
                      fication.  Options are enclosed in square brackets.  Several options can
                      be included for the source files.  They can be packed together or sepa-
                      rated by spaces.  Options can verify that a file was copied correctly,
                      allow PIP to read a file with the system (SYS) attribute, cause PIP to
                      write over Read-Only files, cause PIP to put a file into or copy it from
                      a specified user number, transfer from lower- to upper-case, and much
                      more.

       Examples:      A >PIP B : =A: a 1 df i I e . da t
                      A >PIP B : o 1 d f i I e . da t = A

                      Both forms of this command cause PIP to read the file oldfile.dat from
                      drive A and put an exact copy of it onto drive B. This is called the
                      short form of PIP, because the source or destination names only a drive
                      and does not include a filename.  When using this form you cannot copy
                      a file from one drive and user number to the same drive and user
                      number.  You must put the destination file on a different drive or in a
                      different user number. (See the section on PIP Options, and the USER
                      Command.) The second short form produces exactly the same result as
                      the first one.  PIP looks for the file oldfile.dat on drive A, the drive
                          'fied as the source.
                      speci

                      A > PIP B: r) ewf i I a , da t =A.- o 1 d f i I e . da t

                      This command copies the file oldfile.dat from drive A to drive B and
                      renames it to newfile.dat. The file remains as oldfile.dat on drive A.
                      This is the long form of the PIP command, because it names a file on
                      both sides of the command line.




       1--c DIGITAL RESEARCH"!                                                                  5-65

     T'he PIP Command                                                    CP/M 3 User's Guide


                   A>PIP newf i I e. dat = ol df i I e. dat

                   Using this long form of PIP, you can copy a file from one drive and
                   user number (usually user 0 because CP/M 3 automatically starts out
                   in user 0-the default user number) to the same drive and user number.
                   This gives you two copies of the same file on one drive and user num-
                   ber, each with a different name.

                   A >PIP B: PROGRAM, BAR' = A: PROGRAM# DATEGI I

                   The preceding command copies the file PROGRAM.DAT from user 1
                   on drive A to the current selected user number on drive B and renames
                   the filetype on drive B to BAK.

                   B > PIP P roq ratri2. da t = A : P roqraml , da t CE t' G3J

                   In this command, PIP copies the file named programl.dat on drive A
                   and echoes [E] the transfer to the console, verifies [V] that the two
                   copies are exactly the same, and gets [G3] the file programl.dat from
                   user 3 on drive A. Because there is no drive specified for the destina-
                   tion,, PIP automatically copies the file to the default user number and
                   drive, in this case user 0 and drive B.


     Multiple File Copy

     Syntax:       PIP d:f[Gnll =fd:lwlldcard-filespec{[options])

     Explanation:  When you use a wildcard in the source specification, PIP copies match-
                   ing files one-by-one to the destination drive, retaining the original name
                   of each file.  PIP displays the message COPYING followed by each
                   filename as the copy operation proceeds.  PIP issues an error message
                   and aborts the copy operation if the destination drive and user number
                   are the same as those specified in the source.

     Examples:     A > PIP B : =A: * # COM

                   This command causes PIP to copy all the files on drive A with the
                   filetype COM to drive B.




     5-66                                                                iDo DIGITAL RESEARCHTI

         CP/M 3 User's Guide                                                  The PIP Command

                       A > PI P B: =A:

                       This command causes PIP to copy all the files on drive A to drive B.
                       You can use this command to make a back-up copy of your distribu-
                       tion disk.  Note, however, that this command does not copy the CP/M 3
                       system from the system tracks.  COPYSYS copies the system for you.

                       A>PIP B:=A:PROG????,*

                       The preceding command copies all files whose filenames be in with PROG
                                                                                91
                       from drive A to drive B.

                       A>PIP B:EGIJ=A:*.BAS

                       This command causes PIP to copy all the files with a filetype of BAS on
                       drive A in the default user number (user 0) to drive B in user number 1.
                       Remember that the DIR, TYPE, ERASE, and other commands only access
                       files in the same user number from which they were invoked. (See the
                       USER Command.)

         Combining Files

         Syntax:       PIP dest-filespecl[Gn]) = src-filespeci[o]l, src-filespecf[o]H,...l

         Explanation:  This form of the PIP command lets you specify two or more files in the
                       source.  PIP copies the files specified in the source from left to right and
                       combines them into one file with the name indicated by the destination
                       file specification.  This procedure is called file concatenation.  You can use
                       the [Gn] option after the destination file to place it in the user number
                           'fied by n. You can specify one or more options for each source file.
                       spect

                       Some of the options force PIP to copy files character-by-character.  In
                       these cases, PIP looks for a CTRL-Z character to determine where the
                       end of the file is.  All of the PIP options force a character transfer except
                       the following:

                       Al C, Gn, K, 0, R, V, and W.

                       Copying data to or from logical devices also forces a character transfer.


        170 DIGITAI- RESEARCH["
                                                                                           5-67

     T'he PIP Command                                                     CP/M 3 User's Guide


                    You can terminate PIP operations by typing CTRL-C.

                    When concatenating files, PIP only searches the last record of a file for
                                                                   if PIP is doing a character
                    the CTRL-Z end-of-file character. However, 1              1
                    transfer, it stops when it encounters a CTRL-Z character.

                    Use the [01 option if you are concatenating machine code files.  The [0)
                    option causes PIP to ignore embedded CTRL-Z (end-of-file) characters,
                    which indicate the end-of-file character in text files, but might be valid
                    data in object code files.

     Examples:      A>PIP NE14FILE=FILEIPFILE2tFILE3

                    The three files named FILE1, FILE2, and FILE3 are 'oined from left to
                                                                                        N
                    right and copied to NEWFILE.$$$. NEWFILE.$$$ is renamed to EW-
                    FII,E upon successful completion of the copy operation.  All source and
                    destination files are on the disk in the default drive A.

                    A>PIP B:X.BAS = )',BAS.- B:Z.BAS

                    The file Y.BAS on drive A is joined with Z.BAS from drive B and placed
                    in the temporary file X.$$$ on drive B. The file X.$$$ is renamed to
                    X.BAS on drive B when PIP runs to successful completion.


     Copy Files to and from Auxiliary Devices

     Syntax:        PlPdest-filespecl[Gn]) = src-filespecf[o])
                        AUX:                  AUX: f [o]l
                        CON:                  CON: l[ojl
                        PRN:                  NUL:
                        LST:                  EOF:

     Explanation-.  This form  is a special case of the PIP command line that lets you copy
                    a file from a disk to a device, from a device to a disk or from one device
                    to another.  The files must contain printable characters.  Each peripheral
                    device is assigned to a logical device that identifies a source device that
                    can transmit data or a destination device that can receive data. (See the
                    DEVICE command.) A colon follows each logical device name so it
                    cannot be confused with a filename.  Enter CTRL-C to abort a copy
                    operation that uses a logical device in the source or destination.

                                                                          @Ea Dl(;I'rAL RESEARCH"
     5-68

      CP/M 3 User's Guide                                                    The PIP Command

                     The logical device names are listed as follows:

                     0  CON: Console input or output device. When used as a source, usually
                        the keyboard; when used as a destination, usually the screen.
                     0  AUX: Auxiliary Input or Output Device.
                     0  LST: The destination device assigned to the list output device, usually
                        the printer.

                     The following three device names have special meaning:

                     n  NUL: A source device that produces 40 hexadecimal zeros.
                     0  EOF: A source device that produces a single CTRL-Z, the CP/M 3
                        end-of-file mark.
                     m  PRN: The printer device with tab expansion to every eighth column,
                        line numbers, and page ejects every sixtieth line.

      Examples:      B>PIP PRN: =CON: tH@'DATA#DAT

                     Characters are first read from the console input device, generally the
                     keyboard, and sent directly to your printer device.  You type a CI'RL-Z
                     character to tell PIP that keyboard input is complete.  At that time, PIP
                     continues by reading character data from the file MYDATA.DAT on
                     drive B. Because PRN: is the destination device, tabs are expanded, line
                     numbers are added, and page ejects occur every sixty lines.

                     Note that when the CON: device is the source you must enter both the
                     carriage return (RETURN) and line-feed (LF) keys for a new line.

                     A>PIP B:FUNFILE.SUE = CON:

                     Whatever you type at the console is written to the file FUNFILE.SUE on
                     drive B. End the keyboard input by typing a CTRL-Z.

                     A>PIP LST:=CDN:

                     Whatever you type at the console keyboard is written to the list device,
                     generally the printer.  Terminate input with a CTRL-Z.


      OF-C Dl(,['FAL. RESEAR(,H"                                                            5-69

    The PIP Command                                                    CP/M 3 User's Guide

                   A>PIP LST:=B:DRAFT.TXTETBJ

                   The file DRAFT.TXT on drive B is written to the printer device.  Any tab
                   characters are expanded to the nearest column that is a multiple of 8.

                   A>PIP PRN:=B:DRi4FT,TXT

                   The preceding command causes PIP to write the file DRAFT.TXT to the
                   list device.  It automatically expands the tabs, adds line numbers, and
                   ejects pages after sixty lines.

     Multiple Command Mode

     Syntax:       PIP

     Explanation: This form of the PIP command starts the PIP utility and lets you type
                   multiple command lines while PIP remains in user memory.

                   PIP writes an asterisk on your screen when ready to accept input com-
                   mand lines.

                   You can type any valid command line described under previous PIP
                   formats following the asterisk prompt.

                   Terminate PIP by pressing only the RETURN key following the asterisk
                   prompt.  The empty command line tells PIP to discontinue operation and
                   return to the CP/M 3 system prompt.

     Examples:     A>PIP
                   CP/M 3 PIP VERSION 3*0
                   *NE;4FILE=FILEltFILE2tFILE3
                   * APROG.COM=BPROG.COM
                   * A:=B:X,BAS
                   * B : = * , *
                   * .1m
                   A>

                   This command loads the PIP program.  The PIP command input prompt',
                   *, tells you that PIP is ready to accept commands. The effects of this
                   sequence of commands are the same as in the previous examples, where


     5-70                                                              9 DIGITAL RESEAR(HR"

