       CP/M 3 User's Guide                                                      The PIP Command

                      the command line is included in the command tail.  PIP is not loaded
                      into memory for each command.  To exit this PIP command mode,
                      press RETURN or one of its equivalent control characters, CTRL-J or
                      CTRL-M as shown.

       Using Options With PIP

       Explanation:   With options you can process your source file in special ways. You can
                      expand tab characters, translate from upper- to lower-case, extract por-
                      tions of your text, verify that the copy is correct, and much more.

                      The PIP options are listed in Table 5-13 using n to represent a number
                      and s to represent a sequence of characters terminated by a CTRL-Z.
                      An option must immediately follow the file or device it affects.  The option
                      must be enclosed in square brackets [ ]. For those options that require a
                      numeric value, no blanks can occur between the letter and the value.

                      You can include the [Gn] option after a destination file specification.  You
                      can include a list of options after a source file or source device.  An option
                      list is a sequence of single letters and numeric values that are optionally
                      separated by blanks and enclosed in square brackets








      9 Dl(,'ITAL RLSEARCH"'                                                                  5-71

    The PIP Command                                                    CP/M 3 User's Guide

                                          Table 5-13.  PIP Options
                    Option                                Function

                        A            Copy only the files that have been modified since the
                                     last copy.  To back up only the files that have been
                                     modified since the last back-up, use PIP with the
                                     archive option, [A].

                        c            Prompt for confirmation before performing each copy
                                     operation.  Use the [C] option when you want to copy
                                     only some files of a particular filetype.

                      Dn             Delete any characters past column n. This parameter
                                     follows a source file that contains lines too long to
                                     be handled by the destination device, for example,
                                     an 80-character printer or narrow console.  The num-
                                     ber n should be the maximum column width of the
                                     destination device.

                        E            Echo transfer at console. When this parameter fol-
                                     lows a source name, PIP displays the source data at
                                     the console as the copy is taking place.  The source
                                     must contain character data.

                         F           Filter form-feeds. When this parameter follows a
                                     source name, PIP removes all form-feeds embedded
                                     in the source data.  To change form-feeds set for one
                                     page length in the source file to another page length
                                     in the destination file, use the F command to delete
                                     the old form-feeds and a P command to simultane-
                                     ously add new form-feeds to the destination file.

                       Gn            Get source from or go to user number n. When this
                                     parameter follows a source name, PIP searches the
                                     directory of user number n for the source file.  When
                                     it follows the destination name, PIP places the desti-
                                     nation file in the user number specified by n. The
                                     number must be in the range 0 to 15.





                                                                        1-0 Dl(;II'AL RESEARCH"'
     5-72

        CP/M 3 User's Guide                                                        The PIP Command

                                                 Table 5-13. (continued)
                         Option                                   Function
                             H            Hex data transfer. PIP checks all data for proper Intel
                                          hexadecimal file format.  The console displays error
                                          messages when errors occur.

                              I           Ignore :00 records in the transfer of Intel hexadeci-
                                          mal format file.  The I option automatically sets the
                                          H option.

                             L            Translate upper-case alphabetics in the source file to
                                          lower-case in the destination file.  This parameter fol-
                                          lows the source device or filename.

                             N            Add line numbers to the destination file. When this
                                          parameter follows the source filename, PIP adds a
                                          line number to each line copied, starting with 1 and
                                          incrementing by one.  A colon follows the line num-
                                          ber.  If N2 is specified, PIP adds leading zeros to the
                                          line number and inserts a tab after the number.  If the
                                          T parameter is also set, PIP expands the tab.

                             0            Object file transfer for machine code (noncharacter
                                          and therefore nonprintable) files.  PIP ignores any
                                          CTRL-Z end-of-file during concatenation and trans-
                                          fer.  Use this option if you are combining object code
                                          files.

                            Pn            Set page length. n specifies the number of lines per
                                          page.  When this parameter modifies a source file, PIP
                                          includes a page eject at the beginning of the destina-
                                          tion file and at every n lines.  If n = 1 or is not
                                          specified, PIP inserts page e'ects every sixty lines.  When
                                          you also specify the F option, PIP ignores form-feeds
                                          in the source data and inserts new form-feeds in the
                                          destination data at the page length specified by n.



        -@i 1)1(;ITAL RLSLAR(@H@"                                                                5-73

      The PIP Command                                                     CP/M 3 User's Guide

                                             Table 5-13. (continued)
                      Option                                 Function
                        Qs             Quit copying from the source device after the string
                                       s. \Vhen used with the S parameter, this parameter
                                       can extract a portion of a source file.  The string
                                       argument must be terminated by CTRL-Z.

                         R             Read system (SYS) files. Usually, PIP ignores files
                                       marked with the system attribute in the disk direc-
                                       tory.  But when this parameter follows a source file-
                                       name, PIP copies system files, including their attri-
                                       butes, to the destination.

                         Ss            Start copying from the source device at the string s.
                                       The string argument must be terminated by CTRL-
                                       Z. When used with the Q parameter, this parameter
                                       can extract a portion of a source file.  Both start and
                                       quit strings are included in the destination file.

                         Tn            Expand tabs. When this parameter follows a source
                                       filename, PIP expands tab (CTRL-1) characters in the
                                       destination file.  PIP replaces each CTRL-1 with enough
                                       spaces to position the next character in a column
                                       divisible by n.

                         u             Translate lower-case alphabetic characters in the
                                       source file to upper-case in the destination file.  This
                                       parameter follows the source device or filename.

                          v            Verify that data has been copied correctly. PIP com-
                                       pares the destination to the source data to ensure
                                       that the data has been written correctly.  The desti-
                                       nation must be a disk file.








                                                                          [ko@ DIGITAL RESEARCH"'
       5-74

       CPIM I U,,,r', Guide                                                   The PIP Command

                                              Table 5-13. (continued)
                       Option                                 Function
                           w           Write over files with RO (Read-Only) attribute. Usu-
                                       ally, if a PIP command tail includes an existing RO
                                       file as a destination, PIP sends a query to the console
                                       to make sure you want to write over the existing file.
                                       When this parameter follows a source name, PIP
                                       overwrites the RO file without a console exchange.
                                       If the command tail contains multiple source files,
                                       this parameter need follow only the last file in the
                                       list.

                           z           Zero the parity bit. When this parameter follows a
                                       source name, PIP sets the parity bit of each data byte
                                       in the destination file to zero.  The source must con-
                                       tain character data.


       Examples:      A >PIP NE14PROG , BAS=CDDE# BASIL J P DA TA # BAS[U]

                      This command constructs the file NEWPROG.BAS on drive A by join-
                      ing the two files CODE.BAS and DATA.BAS from drive A. During the
                      copy operation, CODE.BAS is translated to lower-case, while DATA.BAS
                      is translated to upper-case.

                      A> PIP CON: =JWIDEFILE# BASEDBOJ

                      This command writes the character file WIDEFILE.BAS from drive A
                      to the console device, but deletes all characters following the 80th col-
                      umn position.

                      A > PIP B: =LETTER . TXTREJ

                      The file LETTER.TXT from drive A is copied to LETTER.TXT on
                      drive B. The LETTER.TXT file is also written to the screen as the copy
                      operation proceeds.


       [ioi [)I(;ITAI- RLSEAR(-H"-'                                                         5-75

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

                   A > P IP L ST: =B: LONGPAGE # TXTrFP65J

                   This command writes the file LONGPAGE.TXT from drive B to the
                   printer device.  As the file is written, form-feed characters are removed
                   and reinserted at the beginning and every 65th line thereafter.

                   B > P I P LST: = PROGRAM, BASENTBUJ

                   This command writes the file PROGRAM.BAS from drive B to the
                   printer device.  The N parameter tells PIP to number each line.  The T8
                   parameter expands tabs to every eighth column.  The U parameter
                   translates lower-case letters to upper-case as the file is printed.

                   A > PIP PORTION, TXT=LETTER, TXTISDea r Si P'Z QSi nc e re I Y "ZJ

                   This command abstracts a portion of the LET-FER.TXT file from drive
                   A by searching for the character sequence "Dear Sir" before starting
                   the copy operation.  When found, the characters are copied to
                   PORTION.TXT on drive A until the sequence "Sincerely" is found in
                   the source file.

                   B > PI P B.- =A: *. COME V14RJ

                   This command copies all files with filetype COM from drive A to drive
                   B. The V parameter tells PIP to read the destination files to ensure that
                   data was correctly transferred.  The W parameter lets PIP overwrite any
                   destination files that are marked as RO (Read-Only).  The R parameter
                   tells PIP to read files from drive A that are marked with the SYS (Sys-
                   tem) attribute.







    5-76                                                                iE DIGITAL RESEARCH"'

       CP/M 3 User's Guide                                                   'Me PUT Command

      The PUT Command


       Syntax:       PUT CONSOLE JOUTPUTTO} FILE filespec i[oll
                     PUTPRINTER JOUTPUTTOIFILEfilespeci[o]l
                     PUT CONSOLE (OUTPUT TOI CONSOLE
                     PUTPRINTER JOUTPUTTOIPRINTER

      Explanation:   The PL7 command is a transient utility that lets you direct console
                     output or printer output to a file.  PUT allows you to direct the system
                     to put console output or printer output to a file for the next system
                     command or user program entered at the console.  Or, PUT directs all
                     subsequent console or printer output to a file when you include the
                     SYSTEM option.

                     Console output is directed to a file until the program terminates.  Then,
                     console output reverts to the console.  Printer output is directed to a file
                     until the program terminates.  Then printer output is directed back to
                     the printer.

                     When you use the SYSTEM option, all subsequent console/printer out-
                     put is directed to the specified file.  This option terminates when you
                     enter the PUT CONSOLE or PLTT PRINTER command.

                     The syntax for the option list is

                     [{ECHO I NO ECHOI IFILTER I NO FILTER} I ISYSTEMI]

                     Table 5-14 defines the preceding option list.








       li-L" 1)1(,ITAI. RESEAR(]H                                                            5-77

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


                                          Table 5-14.  PUT Options

                       Option                                 Meaning

                    ECHO                  specifies that the output is echoed to the con-
                                          sole.  ECHO is the default option when you direct
                                          console output to a file.

                    NO ECHO               specifies that the file output Is not to be echoed
                                          to the console.

                    FILTER                specifies that filtering of control characters is
                                          allowed, which means that control characters
                                          are translated to printable characters.  For
                                          example, an escape character is translated to '[.       I

                    NO FILTER             means that PUT does not translate control
                                          characters.  This is the default option.

                    SYSTEM                specifies that system output and program out-
                                          put is written to the file specified by filespec.
                                          Output is written to the file until a subsequent
                                          PUT CONSOLE command redirects console
                                          output back to the console.



    Direct Console Output to a File

    Syntax:        PUT CONSOLE {OUTPUTI TO FILE filespec f[o])

    Explanation: The preceding form of the PUT command tells the system to direct
                   subsequent console output to a file.

    Example:       A> PUT CONSOLE OUTPUT TO FILE XDUT RECHOJ

                   The preceding command directs console output to file XOUT with the
                   output echoed to the console.






                                                                       - 4UO DL(;ITAL RESEAR(,H"'
    5-78

        CPIM I Usor's Guide                                                The PUT Command

        Put Printer Output to a File

        Syntax:       PUT PRINTER JOUTPUT TOI FILE filespec l[o]l

        Explanation:  The preceding form of the PUT command directs printer output to a
                      file.

                      The options are the same as in the PUT CONSOLE command, except
                      that option NO ECHO is the default for the PUT PRINTER command.
                      Note that if ECHO is specified, printer output is echoed to the printer.

        Examples:     A> PUT PRINTER OUTPUT TO FILE XOUT
                      A>MYPROG

                      The preceding example directs the printer output of program MYPROG
                      to file XOLTR.  The output is not echoed to the printer.

                      A> PUT PRINTER OUTPUT TO FILE XOUT2 [ECHO TSYSTEMJ

                      The preceding command directs all printer output to file XOLTT2 and
                      to the printer, and the PUT is in effect until you enter a PUT PRINTER
                      OUTPUT TO PRINTER command.

                      The printer output can be directed to one or more files.  The output to
                      these files is terminated when you revert printer output to the printer
                      using the following command:

                      PUT PRINTER OUTPUT TO PRINTER

        Terminate Console Output to a File

        Syntax:       PUT CONSOLE FOUTPUT TOI CONSOLE

        Explanation: The preceding form of the PUT command directs console output to the
                      console.

        Example:      A > PU T CONSOL E OU TPU T TO CONSOL E

                      The preceding command directs console output to the console.


        9 DL(;ITAL RFSEAR('H                                                               5-79

   ne PUT Command                                                  CP/M 3 User's Guide

   Terminate Printer Output to a File

   Syntax:      PUT PRINTER JOUTPUT TOI PRINTER

   Explanation: The preceding form of the PUT command directs the printer output to
                the printer.

   Example:     A> PUT PRINTER OUTPUT TO PRINTER

                The preceding example directs printer output to the printer.








   5-80                                                           f@o DL(;ITAL RESEAR(,H"I

         CPIM I U,er's Guile                                               The @NAME Command

         The RENAME Command

         Syntax:         RENAME inew-filespec = old-filespecl

         Explanation:    The RENAME command lets you change the name of a file that is
                         cataloged in the directory of a disk.  It also lets you change several
                         filenames if you use wildcards in the filespecs.  You can abbreviate
                         RENAME to REN.

                         The new-filespec must not be the name of any existing file on the disk.
                         The old-filespec identifies an existing file or files on the disk.

                         The RENAME command changes the file named by old-filespec to the
                         name given as new-filespec.

                         RENAME does not make a copy of the file.  RENAME changes only
                         the name of the file.

                         If you omit the drive specifier, RENAME assumes the file to rename is
                         on the default drive.  You can include a drive specifier as a part of the
                         newname.  If both file specifications name a drive, it must be the same
                         drive.

                         If the file given by oldname does not exist, RENAME displays the
                         following message on the screen:

                         No File

                         If the file given by newname is already present in the directory, RENAME
                         displays the following message on the screen:

                         No t r e n a m e d f i 1 e n am e . t y p f i I e a 1 r e a d Y e x i s t s
                         del ete ( Y/N     ?

                         If you want to delete the old file, type Y to delete.  Otherwise, type N
                         to keep the old file and not rename the new file.







                                                                                                 5-81

    The RENAME Command                                                  CP/M 3 User's Guide

                   If you use wildcards in the filespecs, the wildcards in the new filespec
                   must correspond exactly to the wildcards in the old filespec.  For exam-
                   ple, in the following two commands, the wildcard filespecs correspond
                   exactly:

                   A > REN *, TXl        TEX
                   A >REN A*.  T*=S*,, T*

                   In the following example, the wildcards do not match and CP/M 3
                   returns an error message.

                   A >REN A*.  TEX=A.  T*

    Examples:      A >RENAIIE NE14ASM, BAS=DLDFILE, BAS

                   The file OLDFILE.BAS changes to NEWASM.BAS on drive A.

                   A>RENAME

                   The system prompts for the filespecs:

                   Enter New Name:X,PRN
                   Enter Old Name:Y.PRN
                   y           PRN=X                  PRN
                   A>

                   File Y.PRN is renamed X.PRN on drive A.

                   B>REN A:X# PAS = Y# PLI

                   The file Y.PLI changes to X.PAS on drive A.

                   A >RENAME S*.  TEX=A*.  TEX

                   The preceding command renames all the files matching the wildcard
                   A*.TEX to files with filenames matching the wildcard S*.TEX,
                   respectively.



      5-82                                                               [K DIGITAL RESEAR(H

      CPIM I User's Guile                                    The RENAME Command

                   A'> REN B: NE14L I S T= B: OL DL I 9 T

                   The file OLDLIST changes to NEWLIST on drive B. Because the sec-
                   ond drive specifier, B: is implied by the first, it is unnecessary in this
                   example.  The preceding command line has the same effect as the
                   following:

                   A>REN B:NEWLIST=DLDLIST

                   or

                   A >REN NENL IST=B: OLDL IST








                                                                                5-8@3

    ne PMAC Command                                                      CP/M 3 User's Guide

    The RMAC Command

    Syntax:       RMAC filespec @$Rd I $Sd I $Pdl

    Explanation:  RMAC is a relocatable macro assembler that assembles files of type
                  ASM into REL files that can be linked to create COM files.

                  The RMAC command options specify the destination of the output
                  files.  The additional specifier d defines the destination drive of the
                  output files.  A-0 specifies drives A through 0. X means output to the
                  console, P means output to the printer, and Z means zero output.  Table
                  5-15 lists the RMAC command options.

                                  Table 5-15.  RMAC Command Options
                                   Option                          d =output option

                            R drive for REL file                     (A-0, Z)
                            S drive for SYM file                     (A-0, X, P, Z)
                            P drive for PRN file                     (A-0, X, P, Z)


                  In the MAC command, the assembly parameter of H controls the des-
                  tination of the HEX file.  In the RMAC command this parameter is
                  replaced by R, which controls the destination of the REL file; however,
                  you cannot direct the REL file to the console or printer, RX or RP,
                  because the REL file is not an ASCII file.

    Examples:     A>RMAC TEST $PX SB RB

                  In the preceding example RMAC assembles the file TEST.ASM from
                  drive A, sends the listing file (TEST.PRN) to the console, puts the
                  symbol file (TEST.SYM) on drive B and puts the relocatable object file
                  (TEST.REL) on drive B.




    S-84                                                                P DIGITAL RESLAR(,H"'

        CP/M 3 User's Guide                                                 The SAVIE Command

        The SAVE Command

        Syntax:       SAVE

        Explanation:  The SAVE command copies the contents of memory to a file. To use
                      the SAVE utility, first issue the SAVE command, then run your pro-
                      gram which reads a file into memory.  When your program exits, it
                      exits to the SAVE utility.  The SAVE utility prompts you for the filespec
                      to which the memory is to be copied, and the beginning and ending
                      address of the memory to be saved.

        Example:      A > SA@JE

                      The preceding command activates the SAVE utility.  Now enter the
                      name of the program that loads a file into memory.

                      A >SID dutrip, c otri

                      Next, execute the program.

                      # -q 0

                      When the program exits, SAVE intercepts the return to the system and
                      prompts you for the filespec and the bounds of memory to be saved.

                      SAYE Ye r 3 . 0
                      File (or RETURN to exit)?dutTtp2.coirt
                      Delete dump2.coiti?@'
                      From?100
                      To?400

                      A>

                      The contents of memory from 100H, hexadecimal, to 400H is copied
                      to file DUMP2.COM.







          1)1(11 IRE@EAR(:fl
                                                                                             5-95
    '"e SET Command                                                     CP/M 3 User's Guide

    The SET Command

    Syntax:       SET[options]
                  SET d: [options]
                  SET filespec [options]

    Explanation:  The SET command initiates password protection and time stamping of
                  files in the CP/M 3 system. It also sets file and drive attributes, such as
                  the Read-Only, SYS, and user-definable attributes. It lets you label a
                  disk and password protect the label.

                  The SET command include options that affect the disk directory, the
                  drive, or a file or set of files.  The discussion of the SET command
                  explicitly states which of the three categories are affected.

                  To enable time stamping of files, you must first run INITDIR to format
                  the disk directory.

    Set File Attributes

    Syntax:       SET filespec[attribute-options]

    Explanation: The preceding SET command        sets the specified attributes of a file or a
                  group of files.

                                     Table 5-16.  SET File Attributes
                         Option                               Meaning

                          DIR              Sets the file from the SYS directory to the
                                           (DIR) attribute.

                          SYS              Gives the file the System SYS attribute.

                          RO               Sets the file attribute to allow Read-Only
                                           access.

                          RW               Sets the file attribute to allow Read-Write
                                           access.


                                                                      IED] DIGITAL RESEARCH"'
    5-86

         CP/M 3 User's Guide                                                    The SET Command

                                                 Table S-16. (continued)
                               Option                                 Meaning
                          ARCHIVE = OFF            Sets the archive attribute to off. This means
                                                   that the file has not been backed up (archived).
                                                   PIP with the [A] option can copy files with
                                                   the archive attribute set to OFF.  PIP with this
                                                   option requires an ambiguous filespec and
                                                   copies only files that have been created or
                                                   changed since the last time they were backed
                                                   up with the PIP[A] option.  PIP then sets the
                                                   archive attribute to ON for each file success-
                                                   fully copied.

                          ARCHIVE       ON         Sets the archive attribute to on. This means
                                                   that the file has been backed up (archived).
                                                   The archive attribute can be turned on
                                                   explicitly by the SET command, or it can be
                                                   turned on by PIP when copying a group of
                                                   files with the PIP [A] option.  The archive
                                                   attribute is displayed by DIR.

                          Fl = ONIOFF              Turns on or off the user-definable file attri-
                                                   bute Fl.

                          F2 = ONIOFF              Turns on or off the user-definable file attri-
                                                   bute F2.

                          F3 = ONIOFF              Turns on or off the user-definable file attri-
                                                   bute F3.

                          F4 = ONIOFF              Turns on or off the user-definable file attri-
                                                   bute F4.

           Example:      A >SET MYFILE. TEXERO SYSJ
                         The preceding command sets MYFILE.TEX to Read-Only and System.


          9 DIGITAL RESEARCH"'
                                                                                                5-87

   Ile SET Command                                                    CP/M 3 User's Guide

                 A>SET MYFILE, TEX ER14 DIRJ

                 The preceding command sets MYFILE.TEX to Read-Write with the
                 Directory (DIR) attribute.

   Set Drive Attribute

   Syntax:       SET Id:l [RO]
                 SET fd:l [RWI

   Explanation:  The preceding SET commands set the specified drive to Read-Only or
                 Read-Write.

                 If a drive is set to Read-Only, PIP cannot copy a file to it, ERASE
                 cannot delete a file from it, RENAME cannot rename a file on it.  You
                 cannot perform any operation that requires writing to the disk.  When
                 the specified drive is set to Read-Write, you can read or write to the
                 disk in that drive.  If you enter a CTRL-C at the system prompt, all
                 drives are reset to Read-Write.

   Example:      A >SET B: ERDJ

                 The preceding command sets drive B to Read-Only.

   Assign a Label to the Disk

   Syntax:       SET ID:I[NAME = labelname.typ]

   Explanation:  The preceding SET command assigns a label (name) to the disk in the
                     'fied or default dr'
                 speci                 ive.

                 CP/M 3 provides a facility for creating a directory label for each disk.
                 The directory label can be assigned an eight-character name and a
                 three-character type similar to a filename and filetype.  Label names
                 make it easier to catalog disks and keep track of different disk direc-
                 tories.  The default label name is LABEL.





                                                                     [I--D) DIGITAL RESEARCH"'
   5-88

         CP/M 3 User's Guide                                                 The SET Command

         Example:      A>SETINAME=DISK100J

                       The preceding example labels the disk on the default drive DISK100.

         Assign Password to the Label

         Syntax:       SET [PASSWORD= password]
                       SET [PASSWORD= <cr>

         Explanation:  The first form of the preceding SET command assigns a password to
                       the disk label.  The second form of the command removes password
                       protection from the label.

                       You can assign a password to the label.  If the label has no password,
                       any user who has access to the SET program can set other attributes to
                       the disk which might make the disk inaccessible to you.  However, if
                       you assign a password to the label, then you must supply the password
                       to set any of the functions controlled by the label.  SET always prompts
                       for the password if the label is password-protected.

         Examples:     A >SETEPASS14ORD=SECRETJ
                       A > SE T C PASS14ORD = @'c r.>

                       The first command assigns SECRET to the disk label.  The second com-
                       mand nullifies the existing password.

                       Note: If you use password protection on your disk, be sure to record
                       the password.  If you forget the password, you lose access to your disk
                       or files.

         Enable/Disable Password Protection for Files on a Disk

         Syntax:       SET [PROTECT= ON]
                       SET [PROTECT= OFF]

         Explanation: The first form of the SET command turns on password protection for
                       all the files on the disk.  The password protection must be turned on
                       before you can assign passwords to individual files or commands.



         l@o 1)1(-,ITAL RESEAR(,H@"
                                                                                            5-89

   'Me SET Command                                                  CP/M 3 User's Guide

                 The second SET command disables password protection for the files on
                 your disk.

                 After a password is assigned to the label and the PROTECT option is
                 turned on, you are ready to assign passwords to your files.

                 You can always determine if a disk is password-protected by using the
                 SHOW command to display the label.

   Assign Passwords to Files

   Syntax:       SET filespec[PASSWORD =password]

   Explanation:  The preceding SET command sets the password for filespec to the pass-
                 word indicated in the command tall.  Passwords can be up to eight
                 characters long.  Lower-case letters are translated to upper-case.

                 You can use wildcards in the filespec.  SET assigns the specified pass-
                 word to the files that match the wildcard-filespec.

                 Note: always record the passwords that you assign to your files.
                 Without the password, you cannot access those files unless password
                 protection is turned off for the whole disk.  If you forget the password
                 to the directory label, you cannot turn off the password protection for
                 the disk.

   Example:      A>SET HYFILE, TExrPASS14ORD=MYFILI

                 MYFIL is the password assigned to file MYFILE.TEX.

   Set Password Protection Mode for Files with Passwords

   Syntax:       SET filespec [PROTECT= READ]
                 SET filespec [PROTECT= WRITE]
                 SET filespec [PROTECT= DELETE]
                 SET filespec [PROTECT= NONE]





                                                                   9 DIGITAL RESEARCHT@
   5-90

         CP/M 3 User's Guide                                                    The SET Command

         Explanation: You can assign one of four modes of password protection to your file.
                        The protection modes are READ, WRITE, DELETE, and NONE and
                        are described in the following table.

                                        Table 5-17.  Password Protection Modes
                           Mode                                   Protection

                          READ               The password is required for reading, copying,
                                             writing, deleting, or renaming the file.

                          WRITE              The password is required for writing, deleting, or
                                             renaming the file.  You do not need a password to
                                             read the file.

                          DELETE             The password is only required for deleting or re-
                                             naming the file.  You do not need a password to
                                             read or modify the file.

                          NONE               No password exists for the file. If a password exists,
                                             this modifier can be used to delete the password.


           Assign a Default Password

           Syntax:        SET [DEFAULT = password]

           Explanation:   The preceding set command assigns a default password for the system
                          to use during your computer session.  The system uses the default pass-
                          word to access password-protected files if you do not specify a pass-
                          word,, or if you enter an incorrect password.  The system lets you access
                          the file if the default password matches the password assigned to the
                          file.

           Example:       B > BE T    TEx r PA B514ORD = SECRE T t PRO TEC T = 14R I TE I

                          The preceding command assigns the password SECRET to all the TEX
                          files on drive B. Each TEX file is given a WRITE protect modc to
                          prevent unauthorized editing.



           9 Dl(;ITAL.  RESEARCH'M
                                                                                                  5-91

      Tle SET Command                                                     CP/M 3 User's Guide

      Example:       A>SETEDEFAULT=ddJ

                     The preceding command instructs the system to use dd as a password
                     if you do not enter a password for a password-protected file.

      Set Time Stamp Options on Disk

      Syntax:        SET [CREATE= ON]
                     SET [ACCESS= ON]
                     SET [UPDATE= ON]

      Explanation:   The preceding SET commands allow you to keep a record of the time
                     and date of file creation and update, or of the last access and update of
                     your files.

                     [CREATE     ON]           turns on CREATE time stamps on the disk in
                                               the default drive.  To record the creation time
                                               of a file, the CREATE option must have been
                                               turned on before the file is created.

                     [ACCESS = ON]             turns on ACCESS time stamps on the disk in
                                               the default drive.  ACCESS and CREATE
                                               options are mutually exclusive.  This means that
                                               only one can be in effect at a time.  If you turn
                                               on the ACCESS time stamp on a disk that has
                                               the CREATE time stamp, the CREATE time
                                               stamp is automatically turned off.

                     [UPDATE = ON]             turns on UPDATE time stamps on the disk in
                                               the default drive.  UPDATE time stamps rec-
                                               ord the time the file was last modified.

                     To enable time stamping', you must first run INITDIR to format the
                     disk directory for time and date stamping.

                     Although there are three kinds of date/time stamps, only two date/time
                     stamps can be associated with a given file at one time.  You can choose
                     to have either a CREATE date or an ACCESS date for files on a partic-
                     ular disk.


                                                                          19 DIGITAL RESEARCH"
      5-92
       CP/M 3 Uscr's Guide                                                       The SET Command

                        When you set both UPDATE and CREATE time stamps, notice that
                        editing a file changes both the UPDATE and CREATE time stamps.
                        This is because ED does not update the original file but creates a new
                        version with the name of the original file.

        Example:        A>SET[ACCESS=DNJ

                        The DIR with [FULL] option displays the following date and time
                        stamps:

                B>DIR   RFIJLL]

                Directory fo  r Drive   5:

                     Name        Bytes   Recs   Attributes    Prot      Update            Access
                ------------     -----   ---- ----------      ---- -------------- --------------
                ONE        TEX      9k     71   Dir RW        None                   08/03/81 10:56
                THREE      TEX      12K    95   Dir RW        None                   08/05/81 15:45
                TWO         TEX     IOK    76   Dir RW        None                   08/10/81 09:13

                        The access time   stamps displayed    show the time the file was last dis-
                        played or edited.  Note that displaying a filename in a directory listing
                        does not constitute an access and is not recorded.

                        A>SET ECREATE=ONPUPDATE=ONJ

                        The following DIR output below shows how files with create and update
                        time stamps are displayed.

               5>DIP [FULL]

               Di rectory f or D rive 5

                    Name       Bytes    Recs  Attributes     Prot       Update             Create
               ------------    -----   ---- ----------       ---- --------------       --------------
               GENLED DAT        losk    873  Dir RW         None  08/05/81 14:01 08/01/81 09:3G
               RECEIPTS.DAT       59K    475  Dir RW         None  08/09/81 12:11 08/01/81 09:40
               INVOICES.DAT       7GK    608  Dir RW         None  OB/OB/81 08:46 08/01/81 10:15








         9 DL(;ITAL RESEARC:H"
                                                                                                   S-93

    The SET Command                                                      CP/M 3 User's Guide

    Additional SET Examples

    Examples:     A>SET *.CGMrSYSPRO.-PASS=122tPRDT=READI

                  The preceding setting gives the most protection for all the COM files on
                  drive A. With the password protection mode set to READ, you cannot
                  even read one of the COM files without entering the password 123,
                  unless the default password has been set to 123.  Even if the correct
                  password is entered, you still cannot write to the file because the file is
                  Read-Only.

                  A>SET *#COM rRidtPROTECT=NONEtDIRJ

                  The preceding command reverses the protection and access attributes of
                  the COM files affected by the previous example.  After executing the
                  preceding command, there is no password protection, the files of type
                  COM can be read from or written to, and are set to DIR files.








                                                                        F,70 DIGITAL RESEARCH'"
    5-94

       CP/M 3 User's Guide                                              The SETDEF Command

       The SETDEF Command

       Syntax:       SETDEF {d:f,d:f,d:@,d:llll ITEMPORARY = d:] I [ORDER = (typ f,typl)ll
                     SETDEF [DISPLAY I NO DISPLAY]
                     SETDEF [PAGE I NO PAGE]

       Explanation:  The SETDEF command lets you display or define the disk search order,
                     the temporary drive, and the filetype search order.  The SETDEF defini-
                     tions affect only the loading of programs and/or execution of SUBMIT
                     (SUB) files.  The SETDEF command also lets you turn on/off the DISPLAY
                     and PAGE modes for the system.  When DISPLAY mode is on, the system
                     displays the location and name of programs loaded or SUB files executed.
                     When PAGE mode is on, CP/M 3 utilities stop after displaying one full
                     screen of information.  Press any key to continue the display.

                     The system usually searches the specified drive or the default drive for
                     files.  The user can use the SETDEF command, to extend the search for
                     program files and submit files, for execution purposes only.

                     Note: A CP/M 3 program file has a filetype of COM.  A file containing
                     commands to be executed by SUBMIT has a filetype of SUB.

       Display the Program Loading Search Definitions

       Syntax:       SETDEF

       Explanation: The preceding form of the SETDEF command displays the disk search
                     order, the temporary drive, and the filetype search order.

       Assign the Drive for Temporary Files

       Syntax:       SETDEF [TEMPORARY= D:l

       Explanation: The preceding form of the SETDEF command defines the disk drive to
                     be used for temporary files.  The default drive used for temporary files is
                     the system default drive.




       L170 DIG[TAL RESEAR(:H"
                                                                                             5-95

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

      Example:       A>SETDEF ITEMPORARY=C:J

                     The preceding command sets disk drive C as the drive to be used for
                     temporary files.

      Define the Disk Drive Search Order

      Syntax:        SETDEF f d: f,d: f,d: f,d:llll

      Explanation:   The preceding form of the SETDEF command defines the disks to be
                     searched by the system for programs and/or submit files to be executed.
                     The CP/M 3 default is to search only the default drive.

                     Note:   * can be substituted for d: to indicate that the default drive is
                     to be included in the drive search order.

      Example:       A'>SETDEF C:i*

                     The preceding example tells the system to search for a program on drive
                     C, then, if not found, search for it on the default drive.

      Define the Filetype Search Order

      Syntax:        SETDEF [ ORDER = (typ i,typl)
                              where typ = COM or SUB

      Explanation:   The preceding form of the SETDEF command defines the filetype search
                     order to be used by system for program loading.  The filetype, indicated
                     as typ in the syntax line, must be COM or SUB.  The CP/M 3 default
                     search is for COM files only.

      Example:       A>SETDEF CORDER=(SUBtCOM)J

                     The preceding command instructs the system to search for a SUB file to
                     execute.  If no SUB file is found, search for a COM file.






                                                                         lL70 DIGITAL RESEAR('H
      5-96

       CP/M 3 User's Guide                                                 The SETDEF Command

       Tum On/Off System Display Mode

       Syntax:        SETDEF [DISPLAY I NO DISPLAY]

       Explanation:   The preceding command turns the system display mode on or off. The
                      default system display mode is off.  When the display mode is on,
                      CP/M 3 displays the following information about a program file before
                      loading it for execution: drive, filename, filetype (if any), and user number
                      (if not the default user number).

       Example:       A>SETDEF EDISPLA@'J

                      The preceding command turns on the system display mode.  The system
                      now displays the name and location of programs loaded or submit files
                      executed.  For example, if you enter the PIP command after turning on
                      the system display mode, CP/M 3 displays the following:

                      A>PIP
                      A : P I P         com
                      CP/M 3 PIP        VERSION 3oO


                      indicating that  the file PIP.COM was loaded from drive A under the
                      current user number.  If the current user number is not 0, and if PIP.COM
                      does not exist under the current user number, then the system displays
                      the location of PIP.COM as follows:

                      4A>PIP
                      A:PIP             COM (User 0)
                      CP/M 3 PIP VERSION 340


                      indicating that PIP.COM was loaded from drive A under user number
                      0. This mode is in effect until you enter

                      SETDEF ENO DISPLAYJ

                      to turn off the system DISPLAY mode,



       E Dl(,ITAI- RESEAR(H"I                                                                   5-97

     The SETDEF Command                                                   CP/M 3 User's Guide

     Tum On/Off System Page Mode

     Syntax:        SETDEF [ PAGEI NO PAGE I

     Explanation:   The preceding command turns on/off the system page mode. When the
                    PAGE mode is set to on, CP/M 3 utilities stop after displaying one full
                    screen of information, called a console page.  The utilities resume after
                    you press any key.

                    The default setting of the system page mode is ON.

     Example:       A>SETDEF rNO PAGEJ

                    The preceding command turns off the system page mode.  CP/M 3 utilities
                    do not pause after displaying a full console page, but continue to scroll.








                                                                          @o DIGITAL RESEARCH"
      5-98
        CP/M 3 User's Guide                                                The SHOW Command

        The SHOW Command

        Syntax:       SHOW Id:)4[SPACE ILABEL JUSERS IDIR IDRIVEII

        Explanation:  The SHOW command displays the following disk drive information:

                      0   access mode and amount of free disk space
                      0   disk label
                      0   current user number
                      s   number of files for each user number on the disk
                      a   number of free directory entries for the disk
                      m   drive characteristics

        Display Access Mode and Disk Space Available

        Syntax:       SHOW fd:lf[SPACE]l

        Explanation:  The preceding form of the SHOW command displays the drive, the access
                      mode for that drive, and the remaining space in kilobytes for the specified
                      drive.  SHOW by itself displays the information for all logged-in drives
                      in the system.

        Examples:     A>SH014 B:
                      B: RWt Space:             9t488K
                      A>SHOld
                      A: RWi Space:                   4K
                      B: RWt Space:             9t4BE3K

                      The first example shows that drive B has Read-Write access and it has
                      9,488K bytes of space left.  The second example shows that drive A also
                      is Read-Write and has only 4K bytes left and drive B is Read-Write and
                      has 9,488K bytes left.

        Display Disk Label

        Syntax:       SHOW fd:I[LABEL]

        Explanation: The preceding form of the SHOW command displays disk label information,

        PLC] DIGI'TAL RESEARCH"'
                                                                                             5-99

     The SHOW Command                                                              CP/M 3 User's Guide


     Example:         A > SH014 B: RLABELJ

                      The preceding command displays the following for drive B:

                      Label for drive B:

                      Directory Passwds          Stamp Stamp Label Created Label Updated
                      Label         Reqd         Create Update
                      ---------- -------         ------ ------ -------------- --------------
                      TOMSDISK.       on           on       on    07/04/81 10:30 07/08/81 09:30

                      The first column, directory label, displays the name assigned to that
                      drive directory.  The second column, Passwds Reqd, shows that pass-
                      word protection has been turned on for that drive.

                      As described in the SET command, each file can have up to two time
                      stamps.  The first of these time stamps can be either the creation date
                      and time for the file or the date and time of the last access to the file.
                      Access is defined as reading from or writing to the file.  The third
                      column of the SHOW [LABEL] output displays both the type of stamp
                      and whether     or not it is on. In the preceding example, creation time
                      stamps are given to new files as shown by the stamp create column
                      heading.

                      The fourth column displays the status of the second time stamp field,
                      the update time stamp.  Update time stamps display the date and time
                      of the last update to a file, that is, the last time someone wrote to the
                      file.  In the SHOW [LABEL] display, update time stamps are turned on.

                      Besides showing the password protection and the active time stamps on
                      a drive, SHOW [LABEL] also displays the date and time that the label
                      was created and last updated.


      Display User Number Information

      Syntax:         SHOW Id:I[USERS]

      Explanation: The preceding command displays the current user number and all the
                      users on the drive and the corresponding number of files assigned to
                      them.




                                                                                    I,oJ DIGITAL RFSEAR(,H"'
      5-100

       CPIM I User's Guile                                           The SHOW Command

       Example:     A>SH014 EUSERSJ
                    Act i v e Use r :        1
                    Act i v e Fi 1 es :      0     2     3     4
                    A: # of files: 95 40                  1 26
                    A: Number of f ree di rectory entries: 350
                    A>

       Display Number of Free Directory Entries

       Syntax:      SHOW fd:I[DIR]

       Explanation: The preceding command displays the number of free directory entries
                    cil the specified drive.

       Example:     A >SH014 C: EDIRJ

                    C : N um b e r o f f r e e d i r e c t o r Y e n t r i e s : 24

                    A>

                    The preceding command shows that there are only 24 free directory
                    entries on drive C.








       !IC] t)[("IlAt, RE@LAR('H@"                                                    5-101

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

    Display Drive Characteristics

    Syntax:       SHOW Id:I[DRIVE]

    Explanation: The preceding form of the SHOW command displays th@ drive charac-
                  teristics of the specified drive.

    Example:      A>SHOW [DRITJEJ

                  The following is an example of the system display for the preceding
                  command:

                       A: Drive Characteristics
                  3,600: 128 Byte Record Capacity
                     450: Kilobyte Drive Capacity
                     96: 32 Byte Directory Entries
                     96: Checked Directory Entries
                     128: Records / Directory Entry
                     16: Records / Block
                     48: Sectors / Track
                     512: Bytes / Physical Record








    5-102                                                            [(GI DIGITAI. RESEAR(,H"

       cp,m ' User's Guide                                                  "e SID Command

       The SID Command

       Syntax:      SID Ipgm-filespecl f,sym-filespecl

       Explanation: The SID (Symbolic Instruction Debugger) allows you to monitor and
                    test programs developed for the 8080 microprocessor.  SID supports
                    real-time breakpoints, fully monitored execution, symbolic disassembly,
                    assembly, and memory display and fill functions.  Utility programs are
                    supplied with CP/M 3 that can be dynamically loaded with SID to
                         'de traceback and histogram facilities.
                    provi

                    SID commands display memory and CPU registers and direct the break-
                    point operations during the debugging session.

                    Without a file specification SID loads into memory without a test pro-
                    gram.  Use this form to examine memory or to write and test simple
                    programs using the A command.  You must not use the SID commands
                    G, T, or U, described later, until you have first loaded a test program.

                    A SID command line with a pgm-filespec loads both SID and the test
                    program into memory.  If the filetype is omitted from the filespec, COM
                    is assumed.  SID optionally loads in a symbol table file specified by sym-
                    filespec.  The sym-filespec needs no filetype because SID looks for a file
                    with filetype SYM.  Use the C, G, T, or U command to begin execution
                    of the test program under supervision of SID.

                    Use CTRL-S to halt the screen display.  CTRL-Q restarts the display.
                    Abort lengthy displays by typing any keyboard character.  Use CTRL-C
                    to exit from SID.

                    SID can address absolute memory locations through symbolic expres-
                    sions.  A symbolic expression evaluates to either an address or a data
                    item.





       ED 1)1(;ITAI. RESEAR(,H"'                                                         5-103

     The SID Command                                                     CP/M 3 User's Guide

                   A symbolic expression can be a name from a SYM file produced from
                   your program by a CP/M Macro Assembler.  When you precede the
                   symbolic expression with a period, SID returns its address in hexadeci-
                   mal.  When you precede the symbolic expression with the at sign, @,
                   SID returns the 16-bit value stored at that location and the next contig-
                   uous location.  When you precede the symbolic expression with an equal
                   sign, SID returns the 8-bit value stored at that location.  For two-byte
                   expressions, this is the low byte because the 8080 microprocessor stores
                   the low value of a two-byte word first.

                   A symbolic expression can be a literal value in hex, decimal, or ASCII,
                   as indicated in the following list:

                   0   SID uses literal hex values as given, but truncates any digits in
                       excess of four on the left.  The leftmost digit is the most significant
                       digit.  The rightmost digit is the least significant digit.
                   0   To indicate decimal values precede them with a pound sign,
                       Decimal values that evaluate to more than four hex digits are eval-
                       uated as the modulo of hex value FFFF.  For example,
                       #65534 = FFFEH, while #65536 = 0001H.
                   0   SID translates literal ASCII character strings between apostrophes
                       to the hex value of the two rightmost ASCII characters.

                   You can combine symbolic expressions with the symbolic operators, +
                   or - @ to produce another symbolic expression.  Symbolic expressions
                   combined in this way can be used to calculate the offset of an indirectly
                   addressed data item, for example a subscripted variable.  A special up-
                   arrow operator, , can reference the top-of-stack item.  A string of n '
                   operators can reference the nth stack item without changing stack con-
                   tent or the stack pointer.

                   Table 5-18 lists the SID commands with their corresponding parame-
                   ters and options.  The actual command letter is printed in boldface.  The
                   parameters are in lower-case and follow the command letter.  Optional
                   items are in braces.  Replace the arguments with the appropriate sym-
                   bolic expressions as listed.  Where two symbolic expressions are needed,
                   SID can calculate the second one from the first using the symbolic
                   operators described previously.


     5-104                                                              10 DIGITAL RESEARCH@'

           CPIM I U,,,,,', Guide                                                           The SID Command

                                           Table 5-18.  SID Commands
              Name-                Syntax                                    Meaning

            Assemble          As                      Enter assembly language statements. s is the start
                                                      address.

            Call              Cs fbf,d})              Call to memory location from SID. s is the called
                                                      address, b is the value of the BC register pair,
                                                      and d is the value of the DE register pair.

            Display           DIWIfsji,fl             Display memory in hex and ASCII. W specifies
                                                      a 16-bit word format, s is the start address,
                                                      and f is the finish address.

            Load              Epgm-filespec           Load program and symbol table for execution.
                              f,sym-filespecl

            Load              E* sym-filespec         Load a symbol table file.

            Fill              Fs,f,d                  Fill memory with constant value. s is the start
                                                      address, f is the finish address, and d is an 8-
                                                      bit data item.

            Go                Glplf,af,bll            Begin execution. p is a start address, a is a tem-
                                                      porary breakpoint, and b is a second tempo-
                                                      rary breakpoint.  GO exits SID by performing a
                                                      warm boot.

            Hex               H                       Displays all symbols with addresses in hex. The
                              Ha                      first syntax displays hex, decimal, and ASCII
                              Ha,b                    values of a. The second syntax performs num-
                                                      ber and character conversion, where a is a sym-
                                                      bolic expression, and the third syntax com-
                                                      putes hex sum and difference of a and b, where
                                                      a and b are symbolic expressions.

            Input             Icommand tail           Input CCP command line.

            List              L fs)f,fl               List 8080 mnemonic instructions. s is the start
                                                      address, and f is the finish address.


          i-O Dl(,]'rAL RESEAR(,H"'
                                                                                                         5-105

     The SID Command                                                       CP/M 3 User's Guide

                                     Table 5-18. (continued)

             e            Syntax 7-                              Meaning

       Move            Mslih)d               Move memory block. s is the start address, h is
                                             the high address of the block, and d is the des-
                                             tination start address.

       Pass            Pf pl,cl@             Pass point set, reset, and display. p is a perma-
                                             nent breakpoint address, and c is initial value
                                             of pass counter.

       Read            Rfilespeci,dl         Read code/symbols. d is an offset to each
                                             address.

       Set             sfwls                 Set memory values. s is an address where value
                                             is sent, W is a 16-bit word.

       Trace           Tfni,cll              Trace program execution. n is the number of
                                             program steps, and c is the utility entry address.

       Trace           TIW)fnf,cll           Trace without call. W instructs SID not to trace
                                             subroutines,, n is the number of program steps,
                                             and c is the utility entry address.

       Untrace         UfW)fnf,cll           Monitor execution without trace. n is the num-
                                             ber of program steps, c is the utility entry
                                             address, W instructs SID not to trace
                                             subroutines.

       Value           v                     Display the value of the next available location
                                             in memory (NEXT), the next location after the
                                             largest file read in (MSZE), the current value of
                                             the program counter (PC), and the address of
                                             the end of available memory (END).

       Write           Wfilespecl,s,fl       Write the contents of a contiguous block of
                                             memory to filespec. s is the start address, f is
                                             the finish address.

       Examine         Xfflfrl               Examine/alter CPU state. f is flag bit C, E, 1,
                                             M, or Z; r is register A, B, D, H, P or S.


     5-106                                                                 K Dl(;I'f AL RESEAR(H"'

       CPIM I User's Guide                                                 The SID Command

       Examples:     A>SID

                     In the preceding example CP/M 3 loads SID from drive A into memory.
                     SID displays the # prompt when it is ready to accept commands.

                     A>B:SID SAMPLE#HEX

                     In the preceding example, CP/M 3 loads SID and the program file
                     SAMPLE.HEX into memory from drive B. SID displays:

                     NEXT MSZE PC END
                     nnnn      mmmm pppp eeee

                     In the preceding example, nnnn is a hexadecimal address of the next
                     free location following the loaded program, and mmmm is the next
                     location after the largest program.  This is initially the same value as
                     NEXT. pppp is the initial hexadecimal value of the the program coun-
                     ter. eeee is the hexadecimal address of the logical end of the TPA.

                     #DFEOO+#12B+5

                     In the preceding example the first pound sign, #, is the SID prompt.
                     This SID command, D, displays the values stored in memory start-
                     ing at address FE80 (FEOO + #128) and ending at address FE85
                     (FE80 + 5).

       SID Utilities

                     The SID utilities HIST.UTL and TRACE.UTL are special programs that
                     operate with SID to provide additional debugging facilities.  The mech-
                     anisms for system initialization, data collection, and data display are
                     described in the CPIM SID" Symbolic Instruction Debugger User's
                     Guide.  The following discussion illustrates how a utility is activated.
                     You load the utility by naming it as a parameter when invoking SID:

                     SID filename.UTL

                     In the preceding example filename is the name of the utility.  Following
                     the initial sign-on, the utility can prompt you for additional debugging
                     parameters.

       [K DIGITAL RESEARCH TM
                                                                                         5-107

     Ile SID Command                                                  CP/M 3 User's Guide

                   The HIST utility creates a histogram (bar graph) showing the relative
                   frequency of execution of code within selected program segments of the
                   test program.  The HIST utility allows you to monitor those sections of
                   code that execute most frequently.

                   Upon start-up HIST prompts

                   TYPE HISTOGRAM BOUNDS

                   Enter the bounds in the following format-,

                   aaaa,bbbb

                   for a histogram between locations aaaa and bbbb inclusive.  Collect
                   data in U or T mode, then display results.

                   The TRACE utility obtains a traceback of the instructions that led to a
                   particular breakpoint address in a program under test.  You can collect
                   the addresses of up to 256 instructions between pass points in U or T
                   modes.








     5-108                                                            1101 DIGITAL RESEARCH'@

       CPIM I U,,,r', Guide                                             ne SUBMIT Command

       The SUBMIT Command

       Syntax:        SUBMIT ffilespecl fargumentl ... largumentl

       Explanation:   The SUBMIT command lets you execute a group or batch of com-
                      mands from a SUB file, which is a file with filetype of SUB.

                      Usually, you enter commands one line at a time.  If you must enter the
                      same sequence of commands several times, you might find it easier to
                      batch the commands together using the SUBMIT command.  To do this,
                      create a file and enter your commands in this file.  The file is identified
                      by the filename, and must have a filetype of SUB.  When you issue the
                      SUBMIT command, SUBMIT reads the file named by the filespec and
                      prepares it for interpretation by CP/M 3. When the preparation is com-
                      plete, SUBMIT sends the file to CP/M 3 line-by-line, as if you were
                      typing each command.

                      The SUBMIT command executes the commands from a SUB file as if
                      you are entering the commands from the keyboard.

                      You create the SUB file with the ED utility.  It can contain CP/M 3
                      commands, nested SUBMIT commands, and input data for a CP/M 3
                      command or a program.

                      You can pass arguments to SUB files when you execute them.  Each
                      argument you enter is assigned to a parameter in the SUB file.  The first
                      argument replaces every occurrence of $1 in the file, the second argu-
                      ment replaces parameter $2, etc., up to parameter $9.  For example, if
                      your file START.SUB contains the following commands:

                      ERA $1.BAK
                      DIR $1
                      PIP $1 =A: $2.COM

                      and you enter the following SUBMIT command:

                      A> SUBMIT START SAM TEX


       OLC DIGITAI- RESEARCH"'                                                             5-109

   Tle SUBMIT Command                                               CP/M 3 User's Guide


                  the argument SAM is substituted for every $1 in the START.SUB file,
                  and TEX for every occurrence of $2 in the START.SUB file.  SUBMIT
                  then creates a file with the parameter substitutions and executes this
                  file.  This file now contains the following commands:

                  ERA SAM.BAK
                  DIR SAM
                  PIP SAM= A:TEX.COM

                  If you enter fewer arguments in the SUBMIT command than parame-
                  ters in the SUB file,, the remaining parameters are not included in the
                  commands.

                  If you enter more arguments in the SUBMIT command than parameters
                  in the SUB file, the remaining arguments are ignored.

                  To include an actual dollar sign, $ in your SUB file, type two dollar
                  signs, $$.  SUBMIT replaces them with a single dollar sign when it
                  substitutes an argument for a parameter in the SUB file.  For example,
                  if file AA.SUB contains line:

                  MAC $1 $$$2

                  and you enter the following SUBMIT command:

                  A>SUBtlIT AA ZZ SZ

                  then the translated file contains the following:

                  MAC ZZ $SZ


    Program Input Lines in a SUB File

                  A SUB file can contain program input lines.  Any program input is
                  preceded by a less than sign, <, as in the following example:

                  P I P
                  < B : =*.  ASM
                  <CON:=DUMP#ASM
                  <
                  DIR

    5-110                                                            OEO DIGITAL RESEARCH...

        CPIM I User's Guide                                            The SUBMIT Command

                        The three lines after PIP are input lines to the PIP command.  The third
                        line consists only of the < sign, indicating a carriage return.  The car-
                        riage return causes PIP to return to the system to execute the final DIR
                        command.

                        If the program terminates before using all of the input, SUBMIT ignores
                        the excess input lines and displays the following warning message:

                        Wa rn in 9 : P ro 9 ram in Put i iyno red

                        If the program requires more input than is in the SUB file, it expects
                        you to enter the remaining input from the keyboard.

                        You can enter control characters in a SUB file by using the usual con-
                        vention of preceding the control character by an up-arrow character,, 1,
                        followed by the letter to be converted to a control character.  To enter
                        an actual I character, use the combination 11.  This combination trans-
                        lates to a single T in the same manner that $$ translates to a single


          The SUB File

                        The SUB file can contain the following types of lines:

                        s Any valid CP/M 3 command
                        0 Any valid CP/M 3 command with SUBMIT parameters
                        m Any data input line
                                      1
                        0 Any program input line with parameters ($0 to $9)

                        CP/M 3 command lines cannot exceed 128 characters.





           1170 DIGITAL RESEARCH"M                                                          5-111
                                                                                                    AN
    The SUBMIT Command                                                                   CP/M 3 User's Guide

    Example:          The following lines illustrate the variety of lines that can be entered in
                      a SUB file:

                      D I R
                      0 I R **BAK
                      MAC   $1 $$$4
                      P I P LST: =$l . PRNET$2 $3 $51
                      0 I R     ASM
                      P I P
                      < B :      A S M
                      <CDN:=DUMP.ASM

                      DIR B:

    Executing the SUBMIT Command

    Syntax:           SUBMIT
                      SUBMIT filespec
                      SUBMIT filespec argument ... argument

                      If you enter only SUBMIT, the system prompts for the rest of the
                      command.  You enter the filespec and arguments.

    Example:          A>SUBMIT

                      The system displays the following prompt.  Enter filespec and arguments
                      here, such as:

                      Enter File to Submit: STARTB TEX

                      Another example could be

                      A > SUBM I T SUBA




    5-112                                                                                 RM DIGITAL RESEARCH      TM

       CP/M 3 User's Guide                                           The SUBMIT Command

                     Still another example using parameters is

                     A> SUBMIT AA ZZ SZ

                     where AA is the SUB file AA.SUB, ZZ is the argument to replace any
                     occurrences of $1 in the AA.SUB file and SZ is the argument to replace
                     all occurrences of $2 in the AA.SUB file.

       The PROFILE.SUB Start-up File

                     Every time you turn on or reset your computer, CP/M 3 automatically
                     looks for a special SUB file named PROFILE.SUB to execute.  If it does
                     not exist', then CP/M 3 resumes normal operation.  If the PROFILE.SUB
                     file exists, the system executes the commands in the file.  This file is
                     convenient to use if you regularly execute a set of commands before
                     you do your regular session on the computer.  For example, if you want
                     to be sure that you always enter the current date and time on your
                     computer before you enter any other commands, you can create the
                     PROFILE.SUB file, with ED, and enter the DATE command as follows:

                     DATE SET

                     Then, whenever you bring up the system, the system executes the DATE
                     command and prompts you to enter the date and time.  By using this
                     facility, you can be sure to execute a regular sequence of commands
                     before starting your usual session.








         DL(,ITAL RLSLAR(:H:"                                                           5-113

    'Me @E Command                                                       CP/M 3 User's Guide

    The TYPE Command


    Syntax:        TYPE Ifilespec f[PAGE]I[NO PAGEIII

    Explanation:   The TYPE command displays the contents of an ASCII character file
                   on your screen.  The PAGE option displays the console listing in paged
                   mode, which means that the console listing stops automatically after
                   listing n lines of text, where n is usually the system default of 24 lines
                   per page. (See the DEVICE command to set n to a different value.)
                   Press any character to continue listing another n lines of text.  Press
                   CTRL-C to exit back to the system.  PAGE is the default mode.

                   The NO PAGE option displays the console listing continuously.

                   If you do not enter a file specification in the TYPE command the system
                   prompts for a filename with the message:

                   En t e r f i 1 e n am e :                                                       I
                   Respond with the filespec of the file you want listed.

                   Tab characters occurring in the file named by the file specification are
                   expanded to every eighth column position of your screen.

                   At any time during the display, you can interrupt the listing by pressing
                   CTRL-S.  Press CTRL-Q to resume the listing.

                   Press CTRL-C to exit back to the system.

                   Make sure the file specification identifies a file containing character
                   data.

                   If the file named by the file specification is not present on the specified
                   drive, TYPE displays the following message on your screen:

                   No File



    5-114                                                                9 DIGITAL RESEARCH'M

        CPIM I U,er's Guide                                                The TYPE Command

                      To list the file at the printer and on the screen, type a CTRL-P before
                      entering the TYPE command line.  To stop echoing console output at
                      the printer, type a second CTRL-P.  The type command displays the
                      contents of the file until the screen is filled.  It then pauses until you
                      press any key to continue the display.

        Examples:     A > TYPE M I'PROG, PL I

                      This command displays the contents of the file MYPROG.PLI on your
                      screen, a page at a time.

                      A> TYPE B: THISFILE [NO PAGEJ

                      This command continuously displays the contents of the file THISFILE
                      from drive B on your screen.








           DIGITAL RESEARCH'N'                                                             5-115

    The USER Command                                                    CP/M 3 User's Guide

    The USER Command

    Syntax:       USER lnumber)

    Explanation:  The USER command sets the current user number. When you start
                  CP/M 3, 0 is the current user number.  You can use a USER command
                  to change the current user number to another in the range 0-15.

                  CP/M 3 identifies every file with a user number.  In general, you can
                  access only files identified with the current user number.  However, if
                  you mark a file in user 0 with the SYS attribute, the file can be accessed
                  from all other user numbers.

    Examples:     A > USER

                  The system command prompts for the user number, as follows:

                  Ente r Use r# : 5
                  5A>

                  The current user number is now 5 on drive A.

                  A>USER 3
                  3A>

                  This command changes the current user number to 3.








    5-116                                                              [Co Dl(;I'I'AL RESEARCH"

       CP/M 3 User's Guide                                             The XREF Command

       The XREF Command

       Syntax:      XREF @d:l filename I$Pl

       Explanation: The XREF command provides a cross-reference summary of variable
                    usage in a program.  XREF requires the PRN and SYM files produced
                    by MAC or RMAC for the program.

                    The SYM and PRN files must have the same filename as the filename
                    in the XREF command tall.  XREF outputs a file of type XRF.

       Examples:    A>XREF B:MYPROG

                    In this example, XREF is on drive A. XREF operates on the file
                    MYPROG.SYM and MYPROG.PRN which are on drive B. XREF pro-
                    duces the file MYPROG.XRF on drive B.

                    A>XREF B:MYPROG $P

                    In the preceding example, the $P option directs output to the printer.

                                         End of Section 5








       El DIGITAI, RESEAR(.H"'
                                                                                       5-117

                                           ection

                 ED, The CP/M 3 Context Editor



        6.1 Introduction to ED

          To do almost anything with a computer you need some way to enter data, a way
        to give the computer the information you want it to process.  The programs most
        commonly used for this task are called editors.  They transfer your keystrokes at the
        keyboard to a disk file.  CP/M 3's editor is named ED.  Using ED, you can easily
        create and alter CP/M 3 text files.

          The correct command format for invoking the CP/M 3 editor is given in
        Section 6.2, "Starting ED." After starting ED, you issue commands that transfer text
        from a disk file to memory for editing.  Section 6.3, "ED Operation," details this
        operation and describes the basic text transfer commands that allow you to easily
        enter and exit the editor.

                       44
          Section 6.4, Basic Editing Commands," details the commands that edit a file.
        Section 1,1, "Combining ED Commands," describes how to combine the basic com-
        mands to edit more efficiently.  Although you can edit any file with the basic ED
        commands, ED provides several more commands that perform more complicated
        editing functions, as described in Section 6.6, "Advanced ED Commands."

          During an editing session, ED can return two types of error messages.  Section 6.7,
        "ED Error Messages," lists these messages and provides examples that indicate how
        to recover from common editing error conditions.

        6.2 Starting ED

        Syntax:

            ED input-filespec Id: I output-filespecl

          To start ED, enter its name after the CP/M 3 prompt.  The command ED must be
        followed by a file specification, one that contains no wildcard characters, such as:

        A > ED M)"F I L E. TEX

        Eu Dl(;ITAI. RESEAR(:H"                                                           6-1

      6.2 Starting ED                                                     CP/M 3 User's Guide

        The file specification, MYFILE.TEX in the preceding example, specifies a file to be
      edited or created.  The file specification can be preceded by a drive specification, but
      a drive specification is unnecessary if the file to be edited is on your default drive.
      Optionally, the file specification can be followed by a drive specification, as shown in
      the following example:

      A'.>ED MYFILE.TEX B:

        In response to this command, ED opens the file to be edited, MYFILE.TEX, on
      drive A, but sends all the edited material to a file on drive B.

        Optionally, you can send the edited material to a file with a different filename, as
      in the following example:

      A>ED M@'FILE.TEX YOURFILE*TEX

        The file with the different filename cannot already exist or ED prints the following
      message and terminates.

      OutpLtt File Existst Erase It

        The ED prompt, *, appears at the screen when ED is ready to accept a command,
      as follows

      A>ED M@'FILE, TEX

        If no previous version of the file exists on the current disk, ED automatically
      creates a new file and displays the following message:

      NEW FILE

      Note: before starting an editing session, use the SHOW command to check the
      amount of free space on your disk.  Make sure that the unused portion of your disk
      is at least as large as the file you are editing, or larger if you plan to add characters
      to the file.  When ED finds a disk or directory full, ED has only limited recovery
      mechanisms.  These are explained in Section 6.7, "ED Error Messages."




                                                                          9 DIGITAL RESEARCH"'
      6-2
