                                           Section 2

                            Files, Disks, and Drives



          CP/M 3's most important task is to access and maintain files on your disks.  With
        CP/M 3 you can create, read, write, copy, and erase disk files.  This section tells you
        what a file is, how to create, name, and access a file, and how files are stored on
        your disks.  It also tells how to change disks and change the default drive.

        2.1 What is a File?

          A CP/M 3 file is a collection of related information stored on a disk.  Every file
        must have a unique name because CP/M 3 uses that name to access that file.  A
        directory is also stored on each disk.  The directory contains a list of the filenames
        stored on that disk and the locations of each file on the disk.

          In general, there are two kinds of files: program (command) files and data files.  A
        program file contains an executable program, a series of instructions that the com-
        puter follows step-by-step.  A data file is usually a collection of information: a list of
        names and addresses, the inventory of a store, the accounting records of a business,
        the text of a document, or similar related information.  For example, your computer
        cannot execute names and addresses, but it can execute a program that prints names
        and addresses on mailing labels.

         A data file can also contain the source code for a program.  Generally, a program
        source file must be processed by an assembler or compiler before it becomes a pro-
        gram file.  In most cases, an executing program processes a data file.  However, there
        are times when an executing program processes a program file.  For example, the
        copy program PIP can copy one or more program files.

        2.2 How Are Files Created?

         There are many ways to create a file.  One way is to use a text editor.  The CP/M 3
        text editor ED (described in Section 6) can create a file and assign it the name you
           'fy.  You can also create a file by copying an existing file to a new location,
        speci                                                    I
        perhaps renaming it in the process.  Under CP/M 3, you can use the PIP command to
        copy and rename files.  Finally, some programs such as MAC" create output files as
        they process input files.

         DI(',]I'AL RESEAR(,H"'
                                                                                              2-1

     2.3 How Are Files Named?                                              CP/M 3 User's Guide

     2.3 How Are Files Named?

       CP/M 3 identifies every file by its unique file specification.  A file specification can
     be simply a one- to eight-character filename, such as:

     MYFILE

       A file specification can have four parts: a drive specifier, a filename, a filetype, and
     a password.

       The drive specifier is a single letter (A-P) followed by a colon.  Each drive in your
                                                                       'fier as part of the file
     system is assigned a letter.  When you include a drive speci
     specification, you are telling CP/M 3 that the file is stored on the disk currently in
     that drive.  For example, if you enter

     B:MYFILE

     CP/M 3 looks in drive B for the file MYFILE.

       The filename can be from one to eight characters.  When you make up a filename,
     try to let the name tell you something about what the file contains.  For example, if
     you have a list of customer names for your business, you could name the file:

     CUSTOMER

     so that the name gives you some idea of what is in the file.

       As you begin to use your computer with CP/M 3, you will find that files fall
     naturally into categories.  To help you identify files belonging to the same category,
     CP/M 3 allows you to add an optional one- to three-character extension, called a
     filetype, to the filename.  When you add a filetype to the filename, separate the filetype
     from the filename with a period.  Try to use three letters that tell something about
     the file's category.  For example, you could add the following filetype to the file that
     contains a list of customer names:

     CUSTOMER.NAM

     When CP/M 3 displays file specifications in response to a DIR command, it adds
     blanks to short filenames so that you can compare filetypes quickly.  The program
     files that CP/M 3 loads into memory from a disk have different filenames, but all
     have the filetype COM.

                                                                           P DIGITAL RESEARCH'M
     2-2

       CP/M 3 User's Guide                                           2.3 How Are Files Named?

          In banked CP/M 3, you can add a password as an optional part of the file specifi-
       cation.  The password can be from one to eight characters.  If you include a password,
       separate it from the filetype (or filename, if no filetype is included) with a semicolon,
       as follows:

       CUSTOMER.NAM;ACCOUNT

       If a file has been protected with a password, you must ENTER the password as part
       of the file specification to access the file.  Section 2.7.3 describes passwords in more
       detail.

          We recommend that you create filenames, filetypes, and passwords from letters
       and numbers.  You must not use the following characters in filenames, filetypes, or
       passwords because they have special meanings for CP/M 3:

            < > @ , ! I * I & / $ [ I ( ) - : ; \ + -

          A complete file specification containing all possible elements consists of a drive
       specification, a primary filename, a filetype, and a password, all separated by their
       appropriate delimiters, as in the following example:

       A:DOCUMENT.LAW;SUSAN

       2.4 Do You Have the Correct Drive?

          When you type a file specification in a command tall without a drive specifier, the
       program looks for the file in the drive named by the system prompt, called the
       default drive.  For example, if you type the command

       A>DIR COP)'S)'S*CDM

       DIR looks in the directory of the disk in drive A for COPYSYS.COM. If you have
       another drive, B for example, you need a way to tell CP/M 3 to access the disk in
       drive B instead.  For this reason, CP/M 3 lets you precede a filename with a drive
       specifier.  For example, in response to the command

       A>DIR B:M@'FILE,LIB





       t DL(;ITAL RLSLAR(]H"'
                                                                                               2-3

     2.4 Do You flave the Correct Drive?                                CP/M 3 User's Guide

     CP/M  3 looks for the file MYFILE.LIB in the directory of the disk in drive B. When
     you give a command to CP/M 3, note which disk is in the default drive.  Many
     application programs require that the data files they access be stored in the default
     drive.

        You can also precede a program filename with a drive specifier, even if you use the
     program filename as a command keyword.  For example, if you type the following
     command

     A'.', B : P I P

     CP/M 3 looks in the directory of the disk in drive B for the file PIP.COM. If CP/M 3
     finds PIP on drive B, it loads PIP into memory and executes it.

        If you need to access many files on the same drive, you might find it convenient to
     change the default drive so that you do not need to repeatedly enter a drive specifier.
     To change the default drive, enter the drive specifier next to the system prompt and
     press RETURN.  In response, CP/M 3 changes the system prompt to display the new
     default drive:

     A ",B
     B "@

        Unlike the filename and filetype which are stored in the disk directory, the drive
     specifier for a file changes as you move the disk from one drive to another.  Therefore,
     a file has a different file specification when you move a disk from one drive to
     another.  Section 4 presents more information on how CP/M 3 locates program and
     data files.

     2.5 Do You Have the Correct User Number?

        CP/M 3 further identifies all files by assigning each one a user number which
     ranges from 0 to 15.  CP/M 3 assigns the user number to a file when the file is
     created.  User numbers allow you to separate your files into sixteen file groups.  User
     numbers are particularly useful for organizing files on a hard disk.

        When you use a CP/M 3 utility to create a file, the file is assigned to the current
     user number, unless you use PIP to copy the file to another user number.  You can
     determine the current user number by looking at the system prompt.




                                                                        -1 L)I(,
                                                                       [IC  'ITAI, RE.@EAR(.H"'

     2-4

      CP/M 3 User's Guide                          2. 5 Do You Have the Correct User Number?

      4A>          User number 4, drive A
      A >          User number 0, drive A
      2B>          User number 2,   drive B

      The user number always precedes the drive identifier.  User 0, however, is the default
      user number and is not displayed in the prompt.

         You can use the built-in command USER to change the current user number.

      A >USER 3
      3A>

         You can change both the user number and the drive by entering the new user
      number and drive specifier together at the system prompt:

      A >3B
      3 B >

         Most commands can access only those files that have the current user number.  For
      example, if the current user number is 7, a DIR command with no options displays
      only the files that were created under user number 7. However, if a file resides in
      user 0 and is marked with a special file attribute, the file can be accessed from any
      user number. (Section 2.7.1 discusses file attributes.)

      2.6 Accessing More Than One File

         Certain CP/M 3 built-in and transient utilities can select and process several files
      when special wildcard characters are included in the filename or filetype.  A file spec-
      ification containing wildcards is called an ambiguous filespec and can refer to more
      than one file because it gives CP/M 3 a pattern to match.  CP/M 3 searches the disk
      directory and selects any file whose filename or filetype matches the pattern.








         1)1(,ITAI- RESEAR(,H"'
                                                                                           2-5

     2.6 Accessing Multiple Files                                          CP/M 3 User's Guide

       The two wildcard characters are ?, which matches any single letter in the same
     position, and *, which matches any character at that position and any other charac-
     ters remaining in the filename or filetype.  The following list presents the rules for
     using wildcards.

          m   A ? matches any character in a name, including a space character.
          m   An * must be the last, or only, character in the filename or filetype. CP/M 3
              internally replaces an * with ? characters to the end of the filename or
              filetype.
          m   When the filename to match is shorter than eight characters, CP/M 3 treats
              the name as if it ends with spaces.
          m   When the filetype to match is shorter than three characters, CP/M 3 treats
              the filetype as if it ends with spaces.

       Suppose, for example, you have a disk that contains the following six files:

     A. COM     AA. COM      AAA*COM        B. COM     A. ASM      and B.ASM

     The following wildcard specifications match all, or a portion of, these files:

                                 is treated as ????????.???

                                 matches all six names

     *.COM                       is treated as ????????.COM

                                 matches the first four names

     ?.COM                       matches A.COM and B.COM

     ? . *                       is treated as ?. ? ? ?

     ?*???                       matches A.COM, B.COM, A.ASM, and B.ASM

     A?.COM                      matches A.COM and AA.COM

     A*.COM                      is treated as A???????.COM

     A???????*COM                matches A.COM, AA.COM, and AAA.COM


                                                                          Flo] DIGITAI, RESEARCH'@"
     2-6

       CP/M 3 User's Guide                                           2.6 Accessing Multiple Files

         Remember that CP/M 3 uses wildcard patterns only while searching a disk direc-
       tor-y, and therefore wildcards are valid only in filenames and filetypes.  You cannot
       use a wildcard character in a drive specifier.  You also cannot use a wildcard charac-
       ter as part of a filename or filetype when you create a file.

       2.7 How to Protect Your Files

         Under CP/M 3 you can organize your files into groups to protect them from
       accidental change and from unauthorized access.  You can specify how your files are
       displayed in response to a DIR command, and monitor when your files were last
       accessed or modified.  CP/M 3 supports these features by assigning the following to
       files:

            o  user numbers
            0  attributes
            0  time and date stamps
            0  passwords (banked CP/M 3 only)

       All of this information for each file is recorded in the disk directory.

       2.7.1 File Attributes
         File attributes control how a file can be accessed.  When you create a file, CP/M 3
        1               'butes. You can change the attributes with a SET command.
       g ves it two attri

         The first attribute can be set to either DIR (Directory) or SYS (System).  This
       attribute controls whether CP/M 3 displays the file's name in response to a DIR
       command or DIRSYS command.  When you create a file, CP/M 3 automatically sets
       this attribute to DIR.  You can display the name of a file marked with the DIR
       attribute with a DIR command.  If you give a file the SYS attribute, you must use a
       DIRSYS command to display the filename.  Simple DIR and DIRSYS commands dis-
       play only the filenames created under the current user number.

         A file with the SYS attribute has a special advantage when it is created under user
       0. When you give a file with user number 0 the SYS attribute, you can read and
       execute that file from any user number.  This feature gives you a convenient way to
       make your commonly used programs available under any user number.  Note, how-
       ever, that a user 0 SYS file does not appear in response to a DIRSYS command unless
       0 is the current user number.



         Dl(;I'I'Al- RESEAR(H:"
                                                                                               2-7

     2.7 How to Protect Your Files                                       CP/M 3 User's Guide


        The second file attribute can be set to either R/W (Read-Write) or R/O (Read-
     Only).  If a file is marked R/0, any attempt to write data to that file produces a Read-
     Only error message.  Therefore, you can use the R/O attribute to protect important
     files.  A file with the R/W attribute can be read or written to, or erased at any time,
     unless the disk is physically write-protected.

     2.7.2 Date and Time Stamping

        If you use date and time stamps, you can quickly locate the most recent copy of a
     file, and check when it was last updated or changed.  You can choose to have the
     system tell you either when you created the file, or when you last read from or wrote
     to the file.  You use the SET command to enable date and time stamping, and the
     DIR command with the DATE option to display a file's time and date stamp.

        A SET command enables the option you want to monitor.  You can use the follow-
     ing commands to enable time and date stamping on a disk, but you must choose
     between ACCESS and CREATE.  If you choose ACCESS, the stamp records the last
     time the file was accessed.  If you choose CREATE, the stamp records when the file
     was created.

     A>SET EACCESS=ONJ
     A>SET ECREATE=ONJ
     A>SET EUPDATE=ONJ

        Files created on or copied to a disk that has time and date stamping are automati-
     cally stamped.  The DATE command allows you to display and reset the time and
     date that CP/M 3 is using.  For a complete discussion of time and date stamping, see
     the descriptions of the SET and INITDIR commands in Section 5.

     2.7.3 Passwords (Banked CP/M 3 Only)

        Passwords allow you to protect your files from access by other users.  You can use
     passwords to limit access to certain files for security purposes.

        The SET utility allows you to enable password protection on a drive, assign a
     password to SET itself (so that unauthorized users cannot disable password protec-
     tion on a drive), and assign passwords to specific files that have already been created.
     You can assign passwords to all program and data files.  This means that a command
     line could require the entry of two passwords in order to execute: one password to
     access the command program, and a second password to access the file specified in
     the command tail.



     2-8                                                                 OF-0 DIGITAI- RESEARCH"'

       CPIM I Use,,', 'Guide                                        2.7 How to Protect Your Files

          Some CP/M 3 commands and most word processing, accounting, and other appli-
       cation programs running under CP/M 3 do not accept passwords in the command
       tail.  If you want to protect your file and still use those programs, you can set a
       default password before executing the application program.  See the description of
       the SET command in Section 5 for an explanation of this process.

       2.8 How Are Files Stored on a Disk?

          CP/M 3 records the filename, filetype, password, user number, and attributes of
       each file in a special area of the disk called the directory.  In the directory, CP/M 3
       also records which parts of the disk belong to which file.

          CP/M 3 allocates directory and storage space for a file as records are added to the
       file.  When you erase a file, CP/M 3 reclaims storage in two ways: it makes the file's
       directory space available to catalog a different file, and frees the file's storage space
       for later use.  It is this dynamic allocation feature that makes CP/M 3 powerful.  You
       do not have to tell CP/M 3 how big your file will become, because it automatically
       allocates more storage for a file as needed, and releases the storage for reallocation
       when the file is erased.  Use the SHOW command to determine how much space
       remains on the disk.

       2.9 Changing Floppy Disks

          CP/M 3 cannot, of course, do anything to a file unless the disk that holds the file
       is inserted into a drive and the drive is ready.  When a disk is in a drive, it is online
       and CP/M 3 can access its directory and files.

          At some time, you will need to take a disk out of a drive and insert another that
       contains different files.  You can replace an online disk whenever you see the system
       prompt at your console.  This is a clear indication that no program is reading or
       writing to the drive.

          You can also remove a disk and insert a new one when an application program
       prompts you to do so.  This can occur, for example, when the data that the program
       uses does not fit on one floppy disk.

       Note: you must never remove a disk if a program is reading or writing to it.



          DIGITAI- RESEAR(,H"@
                                                                                                2-9

    2.9 Changing Floppy Disks                                         CP/M 3 User's Guide

      You can change disks on the drive without sending any special signals to CP/M 3.
    This allows you to insert another disk at a program's request and read files from or
    create files on the new disk.

    2.10 Protecting a Drive

      Under CP/M 3, drives can      be marked R/O just as files can be given the R/O
    attribute.  The default state of a drive is R/W.  You can give a drive the R/O attribute
    by using the SET command described in Section 5. To return the drive to R/W, use
    the SET command or press a CTRL-C at the system prompt.

                                       End of Section 2








                                                                       9 DI(-.ITAL RESEARCH"'
     2-10

                                          Section 3

                               Console and Printer



         This section describes how CP/M 3 communicates with your console and printer.
       It tells how to start and stop console and printer output, edit commands you enter
       at your console, and redirect console and printer input and output.  It also explains
       the concept of logical devices under CP/M 3.

       3.1 Controlling Console Output

         Sometimes CP/M 3 displays information on your screen too quickly for you to
       read it.  Sometimes an especially long display scrolls off the top of your screen before
       you have a chance to study it.  To ask the system to wait while you read the display,
       hold down the CONTROL (CTRL) key and press S. A CTRL-S keystroke causes the
       display to pause.  When you are ready, press CTRL-Q to resume the display.  If you
       press any key besides CTRL-Q during a display pause, CP/M 3 sounds the console
       bell or beeper.

         DIR, TYPE, and other CP/M 3 utilities support automatic paging at the console.
       This means that if the program's output is longer than what the screen can display
       at one time, the display automatically halts when the screen is filled.  When this
       occurs, CP/M 3 prompts you to press RETURN to continue.

       3.2 Controlling Printer Output

         You can also use a control command to echo console output to the printer.  To
       start printer echo, press a CTRL-P.  To stop, press CTRL-P again.  While printer echo
       is in effect, any characters that appear on your screen are listed at your printer.

         You can use printer echo with a DIR command to make a list of files stored on a
       floppy disk.  You can also use CTRL-P with CTRL-S and CTRL-Q to make a hard
       copy of part of a file.  Use a TYPE command to start a display of the file at the
       console.  When the display reaches the part you need to print, press CTRL-S to stop
       the display, CTRL-P to enable printer echo, and then CTRL-Q to resume the display
       and  start pr inting. You can use another CTRL-S, CTRL-P, CTRL-Q sequence to
       terminate printer echo.

         1)1(;II'Al, RESEAR("H                                                                3-1

    3.3 Console Line Editing                                           CP/M 3 User's Guide

    3.3 Console Line Editing

       You can correct simple typing errors with the BACKSPACE key.  CP/M 3 also
    supports additional line-editing functions for banked and nonbanked systems that
    you perform with control characters.  You can use the control characters to edit
    command lines or input lines to most programs.

    3.3.1 Line Editing in Nonbanked CP/M 3
       Nonbanked CP/M 3 allows you to edit your command line using the set of char-
    acters listed'in Table 3-1.  To edit a command line in nonbanked CP/M 3, use control
    characters to delete characters left of the cursor, then replace them with new characters.

       In the following example command line, the command keyword PIP is mistyped.
    The underbar represents the cursor.

    A>POP A:=B:*.*-

    To move the cursor to the letter 0, hold down the CTRL key and press the letter H
    eleven times.  CTRL-H deletes characters as it moves the cursor left, leaving the
    following command line:

    A>P

       Now, type the correct letters, press RETURN, and send the command to CP/M 3.

    A>PIP A:=B:*.*-








    3-2                                                               9 DIGITAL RESEARCH'"

        CPIM I User's Guide                                           3.3 Console Line Editing

          Table 3-1 lists all line-editing control characters for nonbanked CP/M 3.

                  Table 3-1.  Nonbanked CP/M 3 Line-editing Control Characters
         Cbaracter                                      Meaning

         CTRL-E             Forces a physical carriage return but does not send the com-
                            mand line to CP/M 3. Moves the cursor to the beginning of the
                            next line without erasing your previous input.

         CTRL-H             Deletes a character and moves the cursor left one character
                            position.

         CTRL-1             Moves the cursor to the next tab stop. Tab stops are automati-
                            cally set at each eighth column.  Has the same effect as pressing
                            the TAB key.

         CTRL-J             Sends the command line to CP/M 3 and returns the cursor to
                            the left of the current line.  Has the same effect as a RETURN
                            or a CTRL-M.

         CTRL-M             Sends the command line to CP/M 3 and returns the cursor to
                            the left of the current line.  Has the same effect as a RETURN
                            or a CTRL-J.

         CTRL-R             Places a # at the current cursor location, moves the cursor to
                            the next line, and displays any partial command you typed so
                            far.

         CTRL-U             Discards all the characters in the command line, places a # at
                            the current cursor position, and moves the cursor to the next
                            command line.

         CTRL-X             Discards all the characters in the command line, and moves the
                            cursor to the beginning of the current line.


          You probably noticed that some control characters have the same meaning.  For
        example, the CTRL-J and CTRL-M keystrokes have the same effect as pressing the
        RETURN key; all three send the command line to CP/M 3 for processing.  Also,
        CTRL-H has the same effect as pressing the BACKSPACE key.

        @j' I)I(il'TAL RLSEARCH"'                                                           3-3

    3.3 Console Line Editing                                              CP/M 3 User's Guide


    3.3.2 Line Editing in Banked CP/M 3

      Banked CP/M 3 allows you to edit your command line without deleting all char-
    acters.  Using the line-editing control characters listed in Table 3-2, you can move the
    cursor left and right to insert and delete characters in the middle of a command line.
    You do not have to retype everything to the right of your correction.  In banked
    CP/M 3, you can press RETURN when the cursor is in any position in the command
    line; CP/M 3 reads the entire command line.  You can also recall a command for
    reediting and reexecution.

      In the following sample session, the user mistyped PIP, and CP/M 3 returned an
    error message.  The user recalls the erroneous command line by pressing CTRL-W
    and corrects the error (the underbar represents the cursor):

    A)POP A:=B:*#*-                        (PIP mistyped)
    POP?

    A>PDP A:=B:*#*-                        (CTRL-W recalls the line)

    A>POP A:=B:*.*                         (CTRL-B to beginning of line)

    A>POP A:=B:*,*                         (CTRL-F to move cursor right)

    A>PP A:=B:*.*                          (CTRL-G to delete error)

    A>PIP A:=B:*.*                         (type I to correct the command name)

      To execute the corrected command line      , the user can press return even though the
    cursor is in the middle of the line.  A return keystroke, or one of its equivalent control
    characters, not only executes the command, but also stores the command in a buffer
    so that you can recall it for editing or reexecution by pressing CTRL-W.

      When you insert a character in the middle of a line, characters to the right of the
                                                                                I    I         -
    cursor move to the right.  If the line becomes longer than your screen is wide, char
    acters disappear off the right side of the screen.  These characters are not lost.  They
               if you delete characters from the line or if you press CTRL-E when the
    reappear I                                               I
    cursor is  in the middle of the line. CTRL-E     moves all characters to the right of the
    cursor to  the next line on the screen.

      Table 3-2 gives a complete list of line-editing control characters for a banked
    CP/M 3 system.


    3-4                                                                     I)[(,I-I'Al, RESEAR(,H

       CPIM I User', Guide                                            3.3 Console Line Editing

                   Table 3-2.  Banked CP/M 3 Line-editing Control Characters
         Cbaracter                                      Meaning

         CTRL-A             Moves the cursor one character to the left.

         CTRL-B             Moves the cursor to the beginning of the command line without
                            having any effect on the contents of the line.  If the cursor is at
                            the beginning, CTRL-B moves it to the end of the line.

         CTRL-E             Forces a physical carriage return but does not send the com-
                            mand line to CP/M 3. Moves the cursor to the beginning of the
                            next line without erasing the previous input.

         CTRL-F             Moves the cursor one character to the right.

         CTRL-G             Deletes the character indicated by the cursor. The cursor does
                            not move.

         CTRL-H             Deletes a character and moves the cursor left one character
                            position.

         CTRL-1             Moves the cursor to the next tab stop. Tab stops are automati-
                            cally set at each eighth column.  Has the same effect as pressing
                            the TAB key.

         CTRL-J             Sends the command line to CP/M 3 and returns the cursor to
                            the beginning of a new line.  Has the same effect as a RETURN
                            or a CTRL-M keystroke.

         CTRL-K             Deletes to the end of the line from the cursor.

         CTRL-M             Sends the command line to CP/M 3 and returns the cursor to
                            the beginning of a new line.  Has the same effect as a RETURN
                            or a CTRL-J keystroke.

         CTRL-R             Retypes the command line. Places a # at the current cursor
                            location, moves the cursor to the next line, and retypes any
                            partial command you typed so far.




          1)1(@ITAI.  RESEAR(,H"'
                                                                                            3-5

     3.3 Console Line Editing                                           CP/M 3 User's Guide

                                    Table 3-2. (continued)
       Cbaracter                                     Meaning
       CTRL-U            Discards all the characters in the command line, places a # at
                         the current cursor position, and moves the cursor to the next
                         line.  However, you can use a CTRL-W to recall any characters
                         that were to the left of the cursor when you pressed CTRL-U.

       CTRL-W            Recalls and displays previously entered command line both at
                         the operating system level and within executing programs, if the
                         CTRL-W is the first character entered after the prompt.  CTRL-
                         J, CTRL-M, CTRL-U, and RETURN define the command line
                         you can recall.  If the command line contains characters, CTRL-
                         W moves the cursor to the end of the command line.  If you
                         press RETURN, CP/M 3 executes the recalled command.

       CTRL-X            Discards all the characters left of the cursor and moves the cur-
                         sor to the beginning of the current line.  CTRL-X saves any
                         characters right of the cursor.


       You probably noticed that some control characters have the same meaning.  For
     example, the CTRL-J and CTRL-M keystrokes have the same effect as pressing the
     RETURN key; all three send the command line to CP/M 3 for processing.  Also,
     CTRL-H has the same effect as pressing the BACKSPACE key.  Notice that when a
     control character is displayed on your screen, it is preceded by an up-arrow, T. For
     example, a CTRL-C keystroke appears as TC on your screen.

     3.4 Redirecting Input and Output

        CP/M 3's PUT command allows you to direct console or printer output to a disk
     file.  You can use a GET command to make CP/M 3 or a utility program take console
     input from a disk file.  The following examples illustrate some of the conveniences
     GET and PUT offer.




     3-6                                                               9 DIGITAL RESEAR('H"'

       CP/M 3 User's Guide                                    3.4 Redirecting Input/Output

        You can use a PUT command to direct console output to a disk file as well as the
       console.  With PUT, you can create a disk file containing a directory of all files on that
       disk, as follows-.

       A>PUT CONSOLE OUTPUT TO FILE DIR,PRN
       Puttini console output to file: DIR.PRN

       A)DIR
       A: FILENAME tEX   FRONT     TEX : FRONT     BAK : ONE     BAK : THREE     TEX
       A: FOUR     TEX   ONE       TEX : LINEDIT   TEX : EXAMPI  TXT : TWO       BAK
       A: TWO      TEX   THREE     BAK  :EXAMP2    TXT

       AITYPE DIR,PRN
       A: FILENAME TEX   FRONT     TEX  :FRONT     BAK   ONE       BAK   THREE     TEX
       A: FOUR     TEX   ONE       TEX   LINEDIT   TEX   EXAMPI    TXT   TWO       15AK
       A-. TWO     TEX   THREE     BAK   EXAMP2    TXT

        You can use a similar PUT command to direct printer output to a disk file as well
       as the printer.

         A GET command can direct CP/M 3 or a program to read a disk file for console
       input instead of the keyboard.  If the file is to be read by CP/M 3, it must contain
       standard CP/M 3 command lines.  If the file is to be read by a utility program, it must
       contain input appropriate for that program.  A file can contain both CP/M 3 com-
       mand lines and program input if it also includes a command to start a program.

         You add or omit the SYSTEM option in the GET command line to specify whether
       CP/M 3 or a utility program is to start reading the file, as shown in the following
       sample session.  If you omit the SYSTEM option, the system prompt returns so that
                ' itiate the program t' at is to take input from the specified file.  If you
       you can in                       n
       include the SYSTEM option, CP/M 3 immediately takes input from the specified file.








       900 1)1(;I-FAI. RESEARCH"'                                                        3-7

      3.4 Redirecting Input/Output                                                             CP/M 3 User's Guide


      3A>type Pip,dat
      b:=front.tex
      b    a n et e x
      b    t w ot e x

      3A>slet console input from file Pip.dat

      Getting console input from file: PIP.DAT
      3A>Pip
      CP/M 3 PIP VERSION 3.0
      *b:=front.tex

      *6:=CnE,teK

      *b:=tWO,teK

      * , < c r.)

      3A>type ccp,da't
      d i r
      s h o w
      di rs Ys

      3A>Yet console input from file ccp,dat IsystemJ
      Getting console input from file; CCP.DAT
      3A>dir

      A: FILENAME TEX           FRONT        TEX      FRONT        BAK     ONE          BAK      THREE        TEX
      A: FOUR          TEX      ONE          TEX      LINEDIT      TEX     EXAMPI       TXT      TWO          BAK
      A; TWO           TEX      EXAMP3                EXAMP2       TXT     PIP          DAT      EXAMP4
      A: THREE         BAK      EXAMP5                CCP          DAT

      3A>show
      A: RWt Space:             3t392K
      5: RWt Space:                 452K

      3A>dirsys
      NON-SYSTEM FILE(S) EXIST

         See the descriptions of GET and PUT in Section 5 for more ways to use redirected
      input and output.





      3-8                                                                                    #Fol DIGITAL RESEARCH"'

      CP/M 3 User's Guide                                       3.5 Assigning Logical Devices

      3.5 Assigning Logical Devices

         Most CP/M 3 computer systems have a traditional console with a keyboard and
      screen display.  Many also have letter-quality printers.  If you use your computer for
      unusual tasks, you might want to add a different kind of character device to your
      system: a line printer, a teletype terminal, a modem, or even a joystick for playing
      games.  To keep track of these physically different input and output devices, CP/M 3
      associates different physical devices with logical devices.  Table 3-3 gives the names
      of CP/M 3 logical devices.  It also shows the physical devices assigned to these logical
      devices in the distributed CP/M 3 system.

                               Table 3-3.  CP/M 3 Logical Devices
               Logical                                                  Pbysical Device
            Device Name                    Device Type                    Assignment

             CONIN:                     Console input                        Keyboard

             CONOUT:                    Console output                       Screen

             AUXIN:                     Auxiliary input                      Null

             AUXOUT:                    Auxiliary output                     Null

             LST:                       List output                          Printer


         In some implementations of     CP/M 3, you can change these assignments with a
      DEVICE command.  If your system supports the DEVICE command, you can, for
      example, assign AUXIN and AUXOLTT to a modem so that your computer can
      communicate with others over the telephone.

                                          End of Section 3




      [1-11 t)l(,ITAI, RESEAR('H@'I                                                         3-9

                                        Section 4

                    CP/M 3 Command Concepts



         As we discussed in Section 1, a CP/M 3 command line consists of a command
      keyword, an optional command tall, and a carriage return keystroke.  This section
      describes the two kinds of programs the command keyword can identify, and tells
      how CP/M 3 searches for a program file on a disk.  This section also tells how to
      execute multiple CP/M 3 commands, and how to reset the disk system.

      4.1 Two Kinds of Commands

         A command keyword identifies a program that resides either in memory as part of
      CP/M 3, or on a disk as a program file.  Commands that identify programs in mem-
      ory are called built-in commands.  Commands that identify program files on a disk
      are called transient utility commands.

         CP/M 3 has six built-in commands and over twenty transient utility commands.
      You can add utilities to your system by purchasing various CP/M 3-compatible appli-
      cation programs.  If you are an experienced programmer, you can also write your
              ']'ties that operate with CP/M 3.
      own utt 1 1                 1

      4.2 Built-in Commands

         Built-in commands are part of CP/M 3 and are always available for your use
      regardless of which disk you have in which drive.  Built-in commands reside in mem-
      ory as a part of CP/M 3 and therefore execute more quickly than the transient
      utilities.

         Some built-in commands have options that require support from a related transient
      utility.  The related transient has the same name as the built-in and has a filetype of
      COM.  This type of transient utility is loaded only when a built-in command line
      contains options that cannot be performed by the built-in command.






      -VD DL(,ITAL RESEAR(,H"'
                                                                                          4-1

    4.2 Built-in Commands                                           CP/M 3 User's Guide

       If you include certain options in the command tall for a built-in command,
    CP/M 3 might return a . C 0 M R e q u i r e d message, This means that the command
    tall options require support from a related transient utility and CP/M 3 could not
    find that program file.  The following files must be accessible to support all the
    functions these built-ins offer: ERASE.COM, RENAME.COM, TYPE.COM, and
    DIR.COM.

       Section 5 explains in detail the built-in commands listed in Table 4-1.

                              Table 4-1.  Built-in Commands
       Command                                     Function

       DIR              Displays filenames of all files in the directory except those marked
                        with the SYS attribute.

       DIRSYS           Displays filenames of files marked with the SYS (system) attri-
                        bute in the directory.

       ERASE            Erases a filename from the disk directory and releases the stor-
                        age space occupied by the file.

       RENAME           Renames a disk file.

       TYPE             Displays contents of an ASCII (TEXT) file at your screen.

       USER             Changes to a different user number.


    CP/M 3 allows you to abbreviate the built-in commands as follows:

       DIRSYS         DIRS
       ERASE          ERA
       RENAME         REN
       TYPE           TYP
       USER           USE






                                                                    F'70 DIGITAL RESEARCIH"
    4-2

       CP/M 3 User's Guide                                   4.3 Transient Utility Commands

       4.3 Transient Utility Commands

         When you enter a command keyword that identifies a transient utility, CP/M 3
       loads the program file from the disk and passes it any filenames, data, or parameters
       you entered in the command tail.  Section 5 provides the operating details for the
       CP/M 3 transient utilities listed in Table 4-2.

                            Table 4-2.  Transient Utility Commands
          Name                                        Function

        COPYSYS             Creates a new boot disk.

        DATE                Sets or displays the date and time.

        DEVICE              Assigns logical CP/M devices to one or more physical devices,
                            changes device driver protocol and baud rates, or sets console
                            screen size.

        DUMP                Displays a file in ASCII and hexadecimal format.

        ED                  Creates and alters character files.

        GET                 Temporarily gets console input from a disk file rather than the
                            keyboard.

        HELP                Displays information on how to use CP/M 3 commands.

        HEXCOM              Uses the output from MAC to produce a program file.

        INITDIR             Initializes a disk directory to allow time and date stamping.

        LINK                Links REL (relocatable) program modules produced by RMAC"
                            (rclocatable macro assembler) and produces program files.

        MAC                 Translates assembly language programs into machine code form.

        PIP                 Copies files and combines files,


       @c Dl(.11-AL RF-SEAR(.H                                                            4-3

   4.3 Transient Utility Commands                                       CP/M 3 User's Guide

                                   Table 4-2. (continued)

      Name                                           Function

     PUT                 Temporarily directs printer or console output to a disk file.

     RMAC                Translates assembly language programs into relocatable pro-
                         gram modules.

     SET                 Sets file options including disk labels, file attributes, type of
                         time and date stamping, and password protection.

     SETDEF              Sets system options including the drive search chain.

     SHOW                Displays disk and drive statistics.

     SID                 Helps you check your programs and interactively correct pro-
                         gramming errors.

     SUBMIT              Automatically executes multiple commands.

     XREF                Produces a cross-reference list of variables used in an assembler
                         program.


   4.4 How CP/M 3 Searches for Program and Data Files

     This section describes how CP/M 3 searches for program and data files on disk.  If
   it appears that CP/M 3 cannot find a program file you specified in a command line,
   the problem might be that CP/M 3 is not looking on the drive where the file is
   stored.  Therefore, you need to understand the steps CP/M 3 follows in searching for
   program and data files.

   4.4.1 Finding Data Files

      As you recall, when you enter a command line, CP/M 3 passes the command tail
   to the program identified by the command keyword.  If the command tail contains a
   file specification, the program calls CP/M 3 to search for the data file.  If CP/M 3
   cannot find the data file, the program displays an error message at the console.
   Typically, this message is F i 1 e n o t f o u n d or N o F i 1 e, but the message depends
   on the program identified by the command keyword.


                                                                        9 DIGITAL RESEARCH'M
   4-4

         CP/M 3 User's Guide                                 4.4 How CP/M 3 Searches for Files

          If you do not include a drive specifier with the filename in a command tail,
         CP/M 3 searches the directory of the current user number on the default drive.  If the
         file is not there, CP/M 3 looks for the file with the SYS attribute in the directory of
         user 0 on the default drive.  If CP/M 3 finds the file under user 0, it allows the
         program Read-Only access to the file.  For example, if you enter the following com-
         mand line,

         3A>TYPE M)"FILE,TXT

         CP/M 3 first searches the directory for user 3 on drive A. If it does not find
         MYFILE.TXT there, it searches the directory of user 0 on drive A for MYFILE.TXT
         marked with the SYS attribute.  If the file is not in either directory, CP/M 3 returns
         control to TYPE, which then displays No F i 1 e.

          Some CP/M 3 utilities, such as PIP and DIR, restrict their file search to the current
         user number.  Because CP/M 3 does not allow Read-Write access to SYS files,-ERASE
         and RENAME also restrict their search to the current user number.

          The search procedure is basically the same if you do include a drive specifier with
         the filename.  CP/M 3 first looks in the directory of the current user number on the
         specified drive.  Then, if it does not find the file, it looks in the directory for user 0
         on the specified drive for the file with the SYS attribute.  If CP/M 3 does not find the
         data file after these two searches, it displays an error message.

         4.4.2 Finding Program Files
           The search procedure for a program file can be very different from a data file
         search.  This is because you can use the SETDEF command described in Section 5 to
         define the search procedure you want CP/M 3 to follow when it is looking for a
         program file.  With SETDEF you can ask CP/M 3 to make as many as sixteen searches
         when you do not include a drive specifier before the command keyword, but that is
         a rare case!  We will begin by describing how CP/M 3 searches for program files
         when you have not yet entered a SETDEF command.

           If a command keyword identifies a transient utility, CP/M 3 looks for that program
         file on the default or specified drive.  It looks under the current user number, and
         then under user 0 for the same file marked with the SYS attribute.  At any point in
         the search process, CP/M 3 stops the search if it finds the program file.  CP/M 3 then
         loads the program into memory and executes it.  When the program terminates,
         CP/M 3 displays the system prompt and waits for your next command.  However, if
         CP/M 3 does not find the command file, it repeats the command line followed by a
         question mark, and waits for your next command.

         B DIG[ rAL RESF-ARCH"@                                                                 4-5

    4.4 How CP/M 3 Searches for Files                                      CP/M 3 User's Guide

       If you include a drive specifier before the command keyword, you are telling
    CP/M 3 precisely where to look for the program file.  Therefore, CP/M 3 searches
    only two locations: the directory for the current user on the specified drive, and then
    for user 0 on the specified drive, before it repeats the command line with a question
    mark.  For example, if you enter

    4C>A:SH014 [SPACEJ

    CP/M 3 looks on drive Al, user 4 and then user 0 for the file SHOW.COM.

       If you do not include a drive specifier before the command keyword,            CP/M 3
    searches directories in a sequence called a drive chain.  When you first receive
    CP/M 3, there is only one drive in your chain, the default drive.  Unless you change
    the chain with a SETDEF command, CP/M 3 looks in two places for the program
    file.  For example, if you enter

    7E>SHO,W ISPACEJ

    CP/M 3 searches the following locations for the file SHOW.COM:

         1. drive E,   user 7
         2. drive E,   user 0

    Remember that a SHOW.COM file under user 0 must be marked with the SYS
    attribute or else  CP/M 3 cannot find it. Use a SET command to give program files
    under user 0 to    the SYS attribute because they can then be accessed automatically
    from all other user areas.  You do not have to duplicate frequently used program files
    in all user areas on all drives.

       When you use a SETDEF command to define your own drive chain, include the
    default drive, and the drive that contains your most frequently used utilities.  For an
    example, assume you defined your drive chain as * (the default drive) and drive A.
    When you enter the following command:

    2D>SH014 [SPACE]




    4-6                                                                  9 DIGITAL RESEARCH  T

       cp,m ' user's Guide                                 4.4 How CP/M 3 Searches for Filcs

       CP/M 3 looks for SHOW.COM in the following sequence:

           1.  drive D, user 2
           2.  drive D, user 0
           3.  drive A, user 2
           4.  drive A, user 0

       You can include your default drive in your drive chain with an option in a SETDEF
       command.  Any drive chain you specify with SETDEF remains in effect until you
       restart or reset the system.

         You can also use a SETDEF command to enable automatic submit in your drive
       chain.  See Section 4.5 for a description of automatic submit.

       4.5 Executing Multiple Commands

         In the examples so far, CP/M 3 has executed only one command at a time.
       CP/M 3 can also execute a sequence of commands.  You can enter a sequence of
       commands at the system prompt, or you can put a frequently needed sequence of
       commands in a disk file.  Once you have stored the sequence in a disk file, you can
       execute the sequence whenever you need to with a SUBMIT command.

         To enter multiple commands at the system prompt, separate each command key-
       word and associated command tail from the next keyword with an exclamation
       point, !. When you complete the sequence, press RETURN.  CP/M 3 executes your
       commands in order:

       3A>dirsys!dir examP*-*!Show IsPacvl
       NON-SYSTEM FILE(S) EXIST
       3A>dit eKaMP*,*
       A: EXAMP7        : EXAMPI    TXT : EXAMP3          EXAMP2    TXT   EXAMP4
       A: EXAMP5        : EXAMPG
       3A>show rspacei

       A: 111, lp,3c,,:     3t344K




       9 DIGITAL RESEARCH                                                                   4-7

     4.5 Executing Multiple Commands                                      CP/M 3 User's Guide

        If you find you need to execute the same command sequence frequently, store the
     sequence in a disk file.  To create this file, use ED or another character file editor.
     The file must have a filetype of SUB.  Each command in the file must start on a new
     line.  For example, an UPDATE.SUB file might look like this:

     DIR A:*.COM
     ERA B:*.COM
     PIP B:=A:*,COM

     To execute this list,, enter the following command:

     A>SUBtlIT UPDATE

     The SUBMIT utility passes each command to CP/M 3 for sequential execution.  While
     SUBMIT executes, the commands are usually echoed at the console, as well as any
     program's screen display, such as the directory or PIP's "COPYING..." message.
     When one command completes, the system prompt reappears either with the next
     command in the SUB file, or, when the SUB file is exhausted, by itself to wait for
     your next command from the keyboard.

        If PROFILE exists, PROFILE.SUB is a special submit file that CP/M 3 automati-
     cally executes at each cold start.  This feature is especially convenient if you regularly
     execute a standard set of commands, such as SETDEF and DATE SET, before begin-
     ning a work session.  A PROFILE.SUB might already exist on your distribution disk.
     If not, you can create one using ED or another editor.

        The description of the SUBMIT utility in Section 5 gives more details on how to
     create a SUB file and use SUBMIT parameters to pass options to the programs to be
     executed.

        You can also use CTRL-C to reset the disk system.  This is sometimes called a
     warm start.  When you press CTRL-C and the cursor Is at the system prompt,
     CP/M 3 logs out all the active drives, then logs in the default drive. ne active drives
     are any drives you have accessed since the last cold or warm start.  A SHOW [SPACE]
     command displays the remaining space on all active drives.  In the following example,
     SHOW [SPACE] indicates that three drives are active.  However, if you press CTRL-C
     immediately after this display and then enter another SHOW [SPACE] command, only
     the space for the default drive, A, is displayed.


     4-8                                                                 0 DIGITAL RESEARCH

     CP/M 3 User's Guide                                            4.6 Terminating Programs

      4.6 Terminating Programs

        You can use the two keystroke command CTRL-C to terminate program execution
      or reset the disk system.  To enter a CTRL-C command, hold down the CTRL key
      and press C.

        Not all application programs that run under CP/M can be terminated by a
      CTRL-C, However, most of the transient utilities supplied with CP/M 3 can be
      terminated immediately by a CTRL-C keystroke.  If you try to terminate a program
      while it is sending a display to the screen, you might need to press a CTRL-S to halt
      the display before entering CTRL-C.

        You can also use CTRL-C to reset the disk system.  This is sometimes called a
      warm start.  When you press CTRL-C and the cursor is at the system prompt,
      CP/M 3 logs out all the active drives, then logs in the default drive.  The active drives
      are any drives you have accessed since the last cold or warm start.  A SHOW [SPACE]
      command displays the remaining space on all active drives.  In the following exam-
      ple, SHOW [SPACE] indicates that three drives are active.  However, if you press
      CTRL-C immediately after this display and then enter another SHOW [SPACE]
      command, only the space for the default drive, A, is displayed.

      A>SH014 ESPACE]
      A: RWt Space:                9t4B8k
      B: RO# Space:                2t454k
      C: RO, Space:                1PG65K
      A> "C
      A>SHDk4 [SPACE]
      A: RW# Space:                9#488K

      4.7 Getting Help

        CP/M 3 includes a transient utility command called HELP that can display a
      summary of what you need to know to use each command described in this manual.
      To get help, simply enter the command:

      A>HELP






      o@l DIGITAL RESEAR(,H"@
                                                                                            4-9

    4.7 Getting Help                                               CP/M 3 User's Guide

      In response, the HELP utility displays a list of topics for which summaries are
       'Table.  After HELP lists the topics available, it displays its own prompt:
    aval

    HELP'>

    To this prompt, you can enter one of the topics presented in the list, for example,

    HELP>SHDIW

    After displaying a summary of the SHOW command, HELP lists subtopics that detail
    different aspects of the SHOW command.  To display the information on a subtopic
    when you have 'ust finished reading the main topic, enter the name of the subtopic
                    i
    preceded by a period,

    HELP >. OPTIONS

    In the preceding example, HELP then displays the options available for the SHOW
    command.  As you become familiar with HELP, you might want to call a HELP
    subtopic directly from the system prompt as follows:

    A.I%HELP SHON OPTIONS

      HELP lets you learn the basic CP/M 3 commands quickly.  You might find that
    you reference the command summary in Section 5 only when you need details not
         ded in the HELP summaries.  When you add new utilities, you can modify HELP
    provi    I
    to add or subtract topics, or even modify the summaries HELP presents.  See the
    description of HELP in Section 5 for complete details.

                                     End of Section 4







    4-10                                                           1:11 DIGITAI- RESEAR(,H

                                          Section 5

                              Command Summary



         This section describes the commands and programs supplied with your CP/M 3
       operating system.  The commands are in alphabetical order.  Each command is fol-
       lowed by a short explanation of its operation and examples.  More complicated com-
       mands are described later in detail.  For example, ED is described in Section 6. Other
       commands, such as SID and MAC, are described fully in other CP/M manuals.

         CP/M 3 has replaced some commands from previous CP/M versions. @C replaces
       ASM; SHOW and DIR include the previous STAT functions; and SID replaces DDT.

       5.1 Let's Get Past the Formalities

         This section describes the parts of a file specification in a command line.  There are
       four parts in a file specification; to avoid confusion, each part has a formal name:

            o   drive specifier-the optional disk drive A, B, C, ...P that contains the file or
                group of files to which you are referring.  If a drive specifier is included in
                your command line, a colon must follow it.
                filename-the one- to eight-character first name of a file or group of files.
                filetype-the optional one- to three-character category name of a file or group
                of files.  If the filetype is present, a period must separate it from the filename.
                password-the optional one- to eight-character password which allows you
                to protect your files.  It follows the filetype, or the filename if no filetype is
                assigned, and is preceded by a semicolon.

          If you do not include a drive specifier, CP/M 3 automatically uses the default drive.
       If you omit the period and the filetype, CP/M 3 automatically includes a filetype of
       three blanks.








       ED [)I(;ITAL RLSEAR(.H"'
                                                                                                5-1

     5.1 Let's Get Past the Forinalities                                      CP/M 3 User's Guide

      This general form is called a file specification.  A file specification names a particu-
     lar file or group of files in the directory of the on-line disk given by the drive
     specifier.  For example,

     B:MYFILE.DAT

     is a file specification that indicates drive B:, filename MYFILE, and filetype DAT.  File
          'ficat'on is abbreviated to
     speci    I   I          I

          filespec

     in the command syntax statements.

       Some CP/M 3 commands accept wildcards in the filename and filetype parts of the
     command tall.  For example,

     E5 : MY* . A??

     is a file specification with drive specifier B:, filename MY*, and filetype A??.  This
     ambiguous file specification might match several files in the directory.

       Put together, the parts of a file specification are represented like this:

          d:filename.typ;password

       In the preceding form, d: represents the optional drive specifier, filename represents
     the one- to eight-character filename, and typ represents the optional one- to three-
     character filetype.  The syntax descriptions in this section use the term filespec to
     indicate any valid combination of the elements included in the file specification.  The
     following list shows valid combinations of the elements of a CP/M 3 file specification.

          o   filename
          0   filename.typ
          a   filename;password
          0   filename.typ;password
          m   d: filename
          m   d:filename.typ
          0   d:filename;password
          0   d: filename. typ;password



                                                                             II-ol 1)1(;ITAI- RESEAR(H"'
     S-2

         CP/M 3 User's Guide                                            5.1 Let's Get Past the Formalities

           The characters in Table S-1 have special meaning in CP/M 3, so do not use these
         characters in file specifications except as indicated.

                                       Table 5-1.  Reserved Characters
                Character                                             Meaning

            < =   7 ! I >                  file specification delimiters
          tab space
          carriage return

                                           drive delimiter in file specification

                                           filetype delimiter in file specification

                                           password delimiter in file specification

                                             'Idcard characters in an ambiguous file specification
                                           wi

            < >            +               option list delimiters

                                           option list delimiters for global and local options

                                           delimiters for multiple modifiers inside square brackets
                                           for options that have modifiers

                                           option delimiters in a command line

                                           comment delimiter at the beginning of a command line








         0 DIGITAL RLSEARCH"'                                                                             5-3

     5.1 Let's Get Past the Formalities                                      CP/M 3 User's Guide

       CP/M 3 has already established several file groups.  Table 5-2 lists some of their
     filetypes with a short description of each family.  Appendix C provides the complete
     lst.

                                   Table 5-2.  CP/M 3 Filetypes

           Ft'letype                                    Meaning

            ASM               Assembler source file

            BAS               CBASIC8 source program

            com               8080) 8085, or equivalent machine language program

            HLP               HELP message file

            SUB               List of commands to be executed by SUBMIT

            $$$               Temporary file


       In some   commands,    descriptive qualifiers are used with filespecs to further qualify
     the type of filespec accepted by the commands.  For example, wildcard-filespec denotes
       'Idcard spec'ficat'ons, dest-filespec denotes a destination filespec, and src-filespec
     wi             I    I                                     I   I
     denotes a  source filespec.

       You now understand command keywords, command tails, --Ontrol characters, default
     drive, and wildcards.  You also see how to use the formal names filespec, drive
          'fier, filename, and filetype.  These concepts give you the background necessary to
     speci
     compose complete command lines.

     5.2 How Commands Are Described

       CP/M 3 commands appear in alphabetical order.  Each command description is
                      'fic form.  This section also describes the notation that indicates the
     given in a spect                I      I
     optional parts of a command line and other syntax notation.

          0 The description begins with the command keyword in upper-case.
          m The syntax section gives you one or more general forms to follow when you
              compose the command line.

     5-4                                                                     1-01 DIGITAL RESEAR(,H

       CP/M 3 User's Guide                               5.2 How Commands Are Described

             n The explanation section defines the general use of the command keyword,
               and points out exceptions and special cases.  The explanation sometimes
               includes tables or lists of options that you can use in the command line.
               The examples section lists a number of valid command lines that use the
               command keyword.  To clarify examples of interactions between you and the
               operating system, the characters that you enter are slanted.  The responses
               that CP/M 3 shows on your screen are in vertical type.

         The notation in the syntax lines describes the general command form using these
        rules:

             m Words in capital letters must be spelled as shown, but you can use any
               combination of upper- or lower-case letters.
             0 The symbolic notation d:, filename, typ, ;password, and filespec have the
               general meanings described in Section 5.1.
             0 You must include one or more space characters where a space is shown,
               unless otherwise specified.  For example, the PIP options do not need to be
               separated by spaces.

         The following table defines the special symbols and abbreviations used in syntax
       lines.

                                  Table 5-3. Syntax Notation
             Symbol                                   Meaning

             DIR            Directory attribute.

             n              You can substitute a number for n.

             0              Indicates an option or an option list.

             RO             Read-Only.

             RW             Read-Write.

             s              You can substitute a string, which consists of a group of
                            characters, for s.




        1)1(@'ll'AL RLSLAR(,H@"

    5.2 How Commands Are Described                                       CP/M 3 User's Guide

                                    Table 5-3. (continued)
        Symbol                                         Meaning
     SYS                    System attribute.

                            Items within braces are optional.  You can enter a command
                            without the optional items.  The optional items add effects to
                            your command line.

                            Items in square brackets are options or an option list.  If you
                            use an option specified within the brackets, you must type the
                            brackets to enclose the option.  If the right bracket is the last
                            character on the command line, it can be omitted.

                            Items in parentheses indicate a range of options.  If you use a
                            range from an option list, you must enclose the range in
                            parentheses.

                            Ellipses tell you that the previous item can be repeated any
                            number of times.

                            The or bar separates alternative items in a command line.
                            You can select any or all of the alternatives specified.  Mutually
                            exclusive options are indicated in additional syntax lines or
                                    'fically noted in the text.
                            are speci

      T or CTRL             Represent the CTRL key on your keyboard. (CTRL charac-
                            ters show as ' on your screen.)

      <cr>                  Indicates a carriage return keystroke.

                            Wildcard character-replaces all or part of a filename and/or
                            filetype.

                            Wildcard character-replaces any single character in the same
                            position of a filename or filetype.







                                                                         H DIGITAL RESEARCH"
     5-6

        cp,m ' User's Guide                               5.2 How Commands Are Described

          Let's look at some examples of syntax notation.  The CP/M 3 DIR (DIRectory)
        command displays the names of files cataloged in the disk directory and, optionally,
        displays other information about the files.

          The syntax of the DIR command with options shows how to use the command
        line syntax notation:

            Syntax:     DIRfd:l I Ifilespeclf[options]l
                              I      I         I
                         optional optional optional

        This tells you that the command tail following the command keyword DIR is optional.
        DIR alone is a valid command, but you can include a file specification, or a drive
        specification, or 'ust the options in the command line.  Therefore,

            DIR
            DIR filespec
            DIR d:
            DIR [RO]

        are valid commands. Furthermore, the drive or file specification can be followed by
        another optional value selected from one of the following list of DIR options:

            RO
            RW
            DIR
            SYS

        Therefore,

            DIR d:filespec [RO]

        is a valid command.

          Recall that in Section 2 you learned about wildcards in filenames and filetypes.
        The DIR command accepts wildcards in the file specification,



         I)[(;ITAI- RESEAR(H"'                                                           5-7

      5.2 How Commands Are Described                                            CP/M 3 User's Guide

      Using this syntax, you can construct several valid command lines:

        DIR
        DIR X.PAS
        DIR X.PAS [RO]
        DIR X.PAS [SYS]
        DIR *.PAS
        DIR       [RWI
        DIR X.* [DIRI

        The CP/M 3 command PIP (Peripheral Interchange Program) is the file copy pro-
      gram.  PIP can copy information from the disk to the screen or printer.  PIP can
      combine two or more files into one longer file.  PIP can also rename files after copying
      them.  Look at one of the formats of the PIP command line for another example of
      how to use command line notation.  PIP also copies files from one disk to another
      disk.

           Syntax:    PIP dest-filespec = src-filespecf,filespec ... I

        In the preceding example, dest-filespec is further defined as a destination file speci-
      fication or peripheral device (printer, for example) that receives data.  Similarly, src-
      filespec is a source file specification or peripheral device (keyboard, for example) that
      transmits data.  PIP accepts wildcards in the filename and filetype. (See the PIP com-
      mand for details regarding other capabilities of PIP.) There are, of course, many valid
      command lines that come from this syntax.  Some examples follow.

      PIP    NEWFILE#DAT=OLDFILE#DAT
      PIP    B:=A:THISFILE#DAT
      PIP    B:X+BAS=Y,BASP Z*BAS
      PIP    X.BAS=A.BASt B,BAST C#BAS
      PIP    B:=A:*.BAK
      PIP    B:=A:*,*

                                                                                                    ity.
      The remainder of this section contains a complete description of each CP/M 3 util'
      The descriptions are arranged alphabetically for easy reference.




      5-8                                                                       t DIGITAL RESEARCH

      CPIM 3 User's Guide                                          The COPYSYS Command

      The COPYSYS Command

      Syntax:       COPYSYS

      Explanation:  The COPYSYS command copies the CP/M 3 system from a CP/M 3
                    system disk to another disk.  The disk must have the same format as
                    the original system disk.  For example, if the system disk is a single-
                    density disk, the disk you use to copy onto must also be in single-
                    density format.

                    The COPYSYS utility copies only the system tracks onto the new disk.
                    To use the new disk as a CP/M 3 system disk, you must also copy the
                    system file CPM3.SYS to the new disk. COPYSYS gives you the     option
                    to copy CPM3.SYS to the new disk.  To copy other files onto the new
                    disk,, use the PIP command.

      Example:      AICIIPI'SYS
                    Copysys Ye r 3.0
                    Source d ri Ye name ( o r return f o r def aul t )C
                    Source on C then type return

                    Place the disk to be copied in drive C, then enter <cr>.

                    Function Complete
                    Destination drive name (or return to reboot)C
                    Destination on C then type return

                    Replace the system disk in C with the new disk, then enter <cr>.

                    Function complete
                    Do You wish to copy CPM3.SYS?)'
                    Source drive name (or return for default)<cr,>
                    Source on default then type return
                    Function complete
                    Destination drive name (or return to reboot)C
                    Destination on C then type return


      i--c- 1)1(,ITAI- RESEAR(,'Il"'                                                    5-9

      "e COPYSYS Command                                             CP/M 3 User's Guidc

                  Place the disk to be copied in drive C then enter <cr>.

                   Function complete

      The preceding example copies the CP/M 3 system using only one disk
      drive C. In the preceding messages, the word source refers to the disk
      that contains the CP/M 3 system, and the word destination refers to
      the disk to which the CP/M 3 system is to be copied.

      The system file CPM3.SYS is copied from the default drive A to the
      -iew d'sk in drive C. CP/M 3 requires the file CPM3.SYS to be on the
      systetii disk.








      5-10                                                            I 1)1(,I'TAL RESLARCH"'

       cp,m ' User's Guide                                                  The DATE Command

       The DATE Command

       Syntax:        DATE (CONTINUOUS)
                      DATE ftime-specificationj
                      DATE SET

       Explanation:   The DATE command is a transient utility that lets you display and set
                      the date and time of day.  When you start CP/M 3, the date and time
                      are set to the creation date of your CP/M 3 system.  Use DATE to
                      change this initial value to the current date and time.

       Display Current Date and Time

       Syntax:        DATE ICONTINUOUSI

       Explanation:   The preceding form of the DATE command displays the current date
                      and time.  The CONTINUOUS option allows continuous display of the
                      date and time.  The CONTINUOUS option can be abbreviated to C.
                      You can stop the continuous display by pressing any key.

       Examples:      A>DATE
                      A>DATE C

                      The first example displays the current date and time.  A sample display
                      might be:

                      Fri OB/13/82 09:15:37

                      The second example displays the date and time continuously until you
                      press any key to stop the display.

       Set the Date and Time

       Syntax:        DATE Itime-specificationj
                      DATE SET


          DI(,-ITAL RESEAR('H                                                                 5-11

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

     Explanation: The first form allows the user to enter both date and time in the com-
                   mand.  The time-specification format is

                   MM/DD/YY HH:MM:SS

                   where:

                   MM is a month value in the range 1 to 12.
                   DD is a day value in the range 1 to 31.
                   YY is the two-digit year value relative to 1900.
                   HH is the hour value in the range of 0 to 23.
                   MM is the minute value in the range of 0 to 59.
                   SS is the second value in the range of 0 to 59.

                   The system checks the validity of the date and time entry and deter-
                   mines the day for the date entered.

                   The second form prompts you to enter the date and the time.  To keep
                   the current system date or time, press the carriage return.

      Examples:    A>DATE 08114IB2 10:30:00

                   The system responds with

                   Press any key to set time

                   When the time occurs, press any key.  DATE initializes the time at that
                   instant, and displays the date and time:

                   Sat OE3/14/82 10:30:00

                   A>DATE SET

                   The system prompts with

                   Ente r today 's date (MM/DD/YY)



      5-12                                                       100 DIGITAL RESEARCH TM

    CP/M 3 User's Guide                                          The DATE Command

                  Press the carriage return to skip or enter the date.  Then the system
                  prompts with

                  Enter the time (HH:MM:SS)

                  Press the carriage return to skip or enter the time and the system prompts
                  with

                  P ress any K e Y to set t ime

                  to allow you to set the time exactly.








      [1-@ 1)1(,ITAL, RLSEAR(Iti                                                 5-13

    Tle DEVICE Command                                                CP/M 3 User's Guide

   The DEVICE Command

    Syntax:       DEVICE INAMES I VALUES I physical-dev I logical-devl
                  DEVICE logical-dev = physical-dev loptionj
                                        (,physical-dev foptionl,...l
                  DEVICE logical-dev = NULL
                  DEVICE physical-dev foptionj
                  DEVICE CONSOLE [PAGE I COLUMNS = columns I LINES = linesl

    Explanation:  The DEVICE command is a transient utility that displays current
                  assignments of CP/M 3 logical devices and the names of physical devices.
                  DEVICE allows you to assign logical CP/M 3 devices to peripheral
                  devices attached to the computer.  The DEVICE command also sets the
                  communications protocol and speed of a peripheral device, and dis-
                  plays or sets the current console screen size.

                  CP/M 3 supports the following five logical devices:

                  CONIN:
                  CONOUT:
                  AUXIN:
                  AUXOUT:
                  LST:

                  These logical devices are also known by the following names:

                  CON: (for CONIN: and CONOUT:)
                  CONSOLE: (for CONIN: and CONOUT:)
                  KEYBOARD (for CONIN:)
                  AUX: (for AUXIN: and AUXOUT:)
                  AUXILIARY: (for AUXIN: and AUXOUT:)
                  PRINTER (for LST:)

                  The physical device names on a computer vary from system to system.
                  You can use the DEVICE command to display the names and attributes
                  of the physical devices that your system accepts.



    5-14                                                              1(0: DIGITAL RESEARCH"'

         CPIM I User's Guile                                                      The DEVICE Command

         Display Device Characteristics and Assignments

         Syntax:         DEVICE I NAMES I VALUES I physical-dev I logical-devl

         Explanation:    The preceding form of the DEVICE command displays the names and
                             'butes of the physical devices and the current assignments of the
                         attri                     1        1
                         logical devices in the system.

         Examples:       A>DE@JIGE

                         The preceding command displays the physical devices and current
                         assignments of the logical devices in the system.  The following is a
                         sample response:

                         Physical Devices:
                         I=Input tD=Output PS=Serial tX=Xon-Xoff
                         CRT      9600 IDS        LPT     9600    IOSX    CRTI     9600    Los
                         CRT2     9600 IDS        CRT3    4800    IDS     LPTI     134     iosx
                         CEN      NONE    0       MDDEM1  19200   IDS     MODEM2   300        s
                         CTRLRI   150     0       GRACRT  19200   IDS     DIABLO   110      0
                         CTRLR2   300     0       SCRTY   7200

                         Current Assignments:
                         CONIN:    = CRT
                         CONOUT: = CRT
                         AUXIN.-   = Null Device
                         AUXOUT.-  = Null Device
                         LST-      = LPT

                         Enternew assignment or hit RETURN:

                         The system prompts for a new device assignment.  You can enter any
                         valid device assignment (as described in the next section).  If you do not
                         want to change any device assignments, press the RETURN key.

                         A> DEVICE NAMES

                         The preceding command lists the physical devices with a summary of
                         the device characteristics.



            Dl(,'ITAI- RESEAR(-HI"
                                                                                                        5-15

   T'he DEVICE Command                                             CP/M 3 User's Guidc

                 A>DE@JICE @JALLIES

                 The preceding command displays the current logical device assignments.

                 A >DETJICE CRT

                 The preceding command displays the attributes of the physical device
                 CRT.

                 A >DEVICE CON

                 The preceding command displays the assignment of the logical device
                 CON:

    Assign a Logical Device

    Syntax:      DEVICE logical-dev = physical-dev foptionj
                                        f,physical-dev loptionl,...)
                 DEVICE logical-dev = NULL

    Explanation: The first form assigns a logical device to one or more physical devices.
                 The second form disconnects the logical device from any physical device.








    5-16                                                            le-ul 1)1(;[ t'Al. RESEAR(H

        CP/M 3 User's Guide                                               The DEVICE Command

                                            Table 5-4.  DEVICE Options
                         Option                                Meaning

                        XON             refers to the XON/XOFF communications protocol.
                                        This protocol uses two special characters in the ASCII
                                        character set called XON and XDFF.  XON signals
                                        transmission on, and XOFF signals transmission off.
                                        Before each character is output from the computer to
                                        the peripheral device, the computer checks to see if
                                        there is any incoming data from the peripheral.  If the
                                        incoming character is XO,FF, the computer suspends
                                        all further output until it receives an XON from the
                                        device, indicating that the device is again ready to
                                        receive more data.

                        NOXON           indicates no protocol and the computer sends data to
                                        the device whether or not the device is ready to receive
                                        it.

                        baud-rate       is the speed of the device. The system accepts the
                                        following baud rates:

                                        50        75       110        134
                                        150       300      600        1200
                                        1800      2400     3600      4800
                                        7200      9600     19200


        Examples:      A >DETJICE CONDLIT: =L PT TCRT
                       A >DE@'ICE AUXIN: =CR T2 EXON t 9600 J
                       A >DE@'ICE LST: =NLJLL

                       The first example assigns the system console output, CONOUT:, to the
                       printer, LPT, and the screen, CRT.  The second example assigns the
                           'I'ary logical input device, AUXIN:, to the physical device CRT
                       auxii
                       using protocol XONIXOFF and sets the transmission rate for the device
                       at 9600.  The third example disconnects the list output logical device,
                       LST:.


           1)1("I-FAI RLSLAR(Ifill@                                                           5-17

    The DEVICE Command                                                 CP/M 3 User's Guide

    Set Attributes of a Physical Device

    Syntax:       DEVICE physical-dev {option)

    Explanation: The preceding form of the DEVICE command sets the attributes of the
                  physical device specified in the command.

    Example:      A >DE@JICE LPT EXON t96OOJ

                  The preceding command sets the XON/XOFF protocol for the physical
                  device LPF and sets the transmission speed at 9600.

    Display or Set the Current Console Screen Size

    Syntax:       DEVICE CONSOLE [PAGE I COLUMNS = columns I LINES = lines]

    Explanation:  The preceding form of the DEVICE command displays or sets the cur-
                  rent console size.

    Examples:     A >DE@JICE CONSOLE [PAGEJ
                  A > DETJ I CE CONSOL ErCOLUMNS=40t LINES=16J

                  The first example displays the current console page width in columns
                  and length in lines.  The second example sets the screen size to 40
                  columns and 16 lines.








    5-18                                                               9 DIGITAL RESEARCH   T"

         CP/M 3 User's Guide                                                   The DIR Command

         The DIR Command

         Syntax:       DIR Id:l
                       DIR Ifilespecl

                       DIRSYS Id:l
                       DIRSYS Ifilespecl

                       DIR fd:l [options]
                       DIR Ifilespecl ffilespecl ... [options]

         Explanation:  The DIR command displays the names of files and the attributes asso-
                       crated with the files.  DIR and DIRSYS are built-in utilities-, DIR with
                       options is a transient uti ity.

         Display Directory

         Syntax:       DIR id:l
                       DIR ifilespec)

                       DIRSYS Id:l
                       DIRSYS Ifilespecl

         Explanation:  The DIR and DIRSYS commands display the names of files cataloged
                       in the directory of an on-line disk.  The DIR command lists the names
                       of files in the current user number that have the Directory (DIR) attri-
                       bute.  DIR accepts wildcards in the file specification.  You can abbreviate
                       the DIRSYS command to DIRS.

                       The DIRSYS command displays the names of files in the current user
                       number that have the System (SYS) attribute.  Although you can read
                       System (SYS) files that are stored in user 0 from any other user number
                       on the same drive, DIRSYS only displays user 0 files if the current user
                       number is 0. DIRSYS accepts wildcards in the file specification.

                       If you omit the drive and file specifications, the DIR command displays
                       the names of all files with the DIR attribute on the default drive for the
                       current user number.  Similarly, DIRSYS displays all the SYS files.


         9 DIGITAI, RESEARCH"                                                                 5-19

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


                   If the drive specifier is included, but the filename and filetype are omit-
                   ted, the DIR command displays the names of all DIR files in the current
                   user on the disk in the specified drive.  DIRSYS displays the SYS files.

                   If the file specification contains wildcard characters, all filenames that
                   satisfy the match are displayed on the screen.

                   If no filenames match the file specification, or if no files are cataloged
                   in the directory of the disk in the named drive, the DIR or DIRSYS
                   command displays the message:

                   No Fi le

                   If system (SYS) files match the file specification, DIR displays the message:

                   SYSTEM F I LE (S) EX I ST

                   If nonsystem (DIR) files match the file specification, DIRSYS displays
                   the message:

                   NON-SYSTEM FILES(S) EXIST

                   The DIR command pauses after filling the screen.  Press any key to
                   continue the display.

                   Note: You can use the DEVICE command to change the number of
                   columns displayed by DIR or DIRSYS.

    Examples:      A>DIR

                   Displays all DIR files cataloged in user 0 on the default drive A.

                   A >DIR B:

                   Displays all  DIR files for user 0 on drive B.

                   A >DIR B: X. BAS

                   Displays the name X.BAS if the file X.BAS is present on drive B.




    5-20                                                                   'Eu I)ICITAL RESEAR(H"'

