                                                   COPYRIGHT

    Copyright 01983 Digital Research Inc.  All rights reserved.  No part of this publication may be reproduced,
    transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in
    anv form or by any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise, without
    the prior written permission of Digital Research Inc., 60 Garden Court, Box DRI, Monterey, California
    93942.


                                                  DISCLAIMER

    DIGITAL RESEARCH INC.  MAKES NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO
    THE CONTENTS HEREOF AND SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF MER-
    CHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE.  Further, Digital Research Inc. reserves
    the right to revise this publication and to make changes from time to time in the content hereof without
    obligation of Digital Research Inc. to notify any person of such revision or changes.


                                              NOTICE TO USER

    From time to time changes are made in the filenames and in the files actually included on the distribution disk.
    This manual should not be construed as a representation or warranty that such files or facilities exist on the
    distribution disk or as part of the materials and programs distributed.  Most distribution disks include a
    "README.DOC" file.  This file explains variations from the manual which do constitute modification of the
    manual and the items included therewith.  Be sure to read this file before using the software.


                                                 TRADEMARKS

    CP/M and Digital Research and its logo are registered trademarks of Digital Research Inc.  ASM, CP/M Plus,
    LINK-80, MAC, MP/M, MP/M 11, and RMAC are trademarks of Digital Research Inc.  Intel is a registered
    trademark of Intel Corporation.

    The CPIM Plus (CP/M Version 3) Operating System Programmer's Guide was printed in the United States of
    America.

                                             First Edition: January 1983
                                             Second Edition: April 1983

                                            orewor




          CP/M@ 3 is a microcom uter operating system designed for the Intelg 8080, Intel
                                   p
       8085, or other compatible microprocessor.  To run CP/M 3, your computer must
       have an ASCII console, which includes a keyboard and screen, or another display
       device, from one to sixteen disk drives and a minimum of 32K of memory space.  To
       support additional memory beyond the 64K addressing limit of the processors listed
       above, CP/M 3 can also support bank-switched memory.  The minimum memory
       requirement for a banked system is 96K.

          This manual describes the programming environment of CP/M 3, and is written
       for experienced programmers who are writing application software in the CP/M 3
       environment.  It assumes you are familiar with the system features and utilities described
       in the CP/M Plus (CPIM Version 3) Operating System User's Guide and the
       Programmer's Utilities Guide for the CPIM Family of Operating Systems.  It also
       assumes that your CP/M 3 system has been customized for your computer's hard-
       ware and is executing as described in the CPIM Plus (CPIM Version 3) Operating
       System User's Guide.  If you need to customize your system, please refer to the CPIM
       Plus (CPIM Version 3) Operating System System Guide.

          Section 1 of this manual describes the components of the operating system, where
       they reside in memory, and how they work together to provide a standard operating
       environment for application programs.  Section 2 describes how an application pro-
       gram can call on CP/M 3 to perform serial input and output and manage disk files.
       Section 3 provides a detailed description of each operating system function.  Section
       4 presents example programs.

          The CPIM Plus (CPIM Version 3) Operating System Programmer's Guide contains
       five appendixes.  Appendix A describes the CP/M 3 System Control Block, and defines
       its fields.  Appendix B supplies the format for the Page Relocatable Program.  Appen-
       dix C tells you how to generate System Page Relocatable files.  Appendix D lists the
       ASCII Symbol Table, and Appendix E summarizes BDOS functions.

                                       Table of Contents



          I Introduction to CP/M 3
                 1.1    Banked and Nonbanked Memory Organization    1-2
                 1.2    System Components      1-5
                 1.3    System Component Interaction and Communication    1-7
                        1.3.1 The BDOS and BIOS      1-7
                        1.3.2 Applications and the BDOS     i-8
                        1.3.3 Applications and RSXs     1-9
                 1.4    Me'mory Region Boundaries     1-9
                 1.5    Disk and Drive Organization and Requirements   1-11
                 1.6    System Operation     1-13
                        1.6.1   Cold Start Operation     1-14
                        1.6.2   CCP Operation     1-16
                        1.6.3   Transient Program Operation    1-22
                        1.6.4   Resident System Extension Operation    1-23
                        1.6.5   SUBMIT Operation      1-26
                 1.7    System Control Block     1-27

          2 The BDOS System Interface

                 2.1    BDOS    Calling Conventions      2-1
                 2.2    BDOS Serial Device 1/0      2-2
                        2.2.1   BDOS Console 1/0       2-3
                        2.2.2   Other Serial I/O      2-6
                 2.3    BDOS File System      2-7
                        2.3.1   File Naming Conventions     2-9
                        2.3.2   Disk and File Organization    2-11
                        2.3.3   File Control Block Definition    2-13
                        2.3.4   File Attributes    2-16
                        2.3.5   User Number Conventions     2-18
                        2.3.6   Directory Labels and XFCBs    l@-19
                        2.3.7   File Passwords    2-21
                        2.3.8   File Date and Time Stamps    2-23
                        2.3.9   Record Blocking and Deblocking   2-25
                        2.3.10  Multi-Sector 1/0     2-26
                        2.3.11  Disk Reset and Removable Media   2-27
                        2.3.12  File Byte Counts     2-28


                                                           v

                    Table of Contents (continued)



                2.3.13 BDOS Error Handling    2-28
         2.4 Page Zero Initialization    2-34

   3 BDOS Function Calls

   4 Programming Examples
         4.1    A Sample File-To-File Copy Program    4-1
         4.2    A Sample File Dump Utility    4-5
         4.3    A Sample Random Access Program    4-10
         4.4    Construction of an RSX Program    4-20
                4.4.1 The RSX Prefix    4-21
                4.4.2 Example of RSX Use    4-22

                                        Appendixes

   A System Control Block    A-1

   B   PRL File Generation    B-1
      B. 1 PRL Format    B-1
      B. 2 Generating a PRL    B-2

   C SPR Generation     C-1

   D ASCII and Hexadecimal Conversions    D-1

   E BDOS Function Summary    E-1








                                                 vi

                                          e of Contents (continued)


                                                         Tables

                   2-1.   Valid Filename Delimiters        2-10
                   2-2.   Logical Drive Capacity         2-12
                   2-3.   BDOS Interface Attributes        2-17
                   2-4.   Password Protection Modes       2-22
                   2-5.   BDOS Functions That Test for Password      2-22
                   2-6.   SFCB Subfields Format         2-24
                   2-7.   Register A BDOS Error Codes       2-31
                   2-8.   BDOS Directory Codes         2-32
                   2-9.   BDOS Error Flags         2-33
                   2-10.  BDOS Physical and Extended Errors      2-34
                   2-11.  Page Zero Areas         2-35
                   3-1.   Function 6 Entry Parameters          3-8
                   3-2.   Edit Control Characters (Nonbanked CP/M 3)     3-13
                   3-3.   Edit Control Characters (Banked CP/M 3)      3-14
                   3-4.   System Control Block         3-70
                   3-5.   Program Return Codes         3-90
                   3-6.   FCB Format          3-98
                   A- 1.  SCB Fields and Definitions         A-1
                   B-1.   PRL File Format          B-1
                   D- 1.  ASCII Symbols      D-1
                   D-2.   ASCII Conversion Table          D-2
                   E-1.  BDOS Function Summary         E-1








                                                           vii

                                 Table of Contents (continued)


                                                           Tables

                     2-1.   Valid Filename Delimiters       2-10
                     2-2.   Logical Drive Capacity        2-12
                     2-3.   BDOS Interface Attributes       2-17
                     2-4.   Password Protection Modes       2-22
                     2-S.   BDOS Functions That Test for Password      2-22
                     2-6.   SFCB Subfields Format        2-24
                     2-7.   Register A BDOS Error Codes       2-31
                     2-8.   BDOS Directory Codes        2-32
                     2-9.   BDOS Error Flags         2-33
                     2-10.  BDOS Physical and Extended Errors       2-34
                     2-11.  Page Zero Areas          2-3S
                     3-1.   Function 6 Entry Parameters        3-8
                     3-2.   Edit Control Characters (Nonbanked CP/M 3)      3-13
                     3-3.   Edit Control Characters (Banked CP/M 3)       3-14
                     3-4.   System Control Block         3-70
                     3-5.   Program Return Codes         3-90
                     3-6.   FCB Format           3-98
                     A- 1.  SCB Fields and Definitions         A-1
                     B-1.   PRL File Format           B-1
                     D-1.   ASCII Symbols           D-1
                     D-2.   ASCII Conversion Table          D-2
                     E-1. BDOS Function Summary          E-1








                                                           vii

                              a eo                   ontents (continued)


                                                      Tables

               2-1.     Valid Filename Delimiters        2-10
               2-2.     Logical Drive Capacity         2-12
               2-3.     BDOS Interface Attributes        2-17
               2-4.     Password Protection Modes        2-22
               2-5.     BDOS Functions That Test for Password      2-22
               2-6.     SFCB Subfields Format         2-24
               2-7.     Register A BDOS Error Codes        2-31
               2-8.     BDOS Directory Codes         2-32
               2-9.     BDOS Error Flags         2-33
               2-10,    BDOS Physical and Extended Errors       2-34
               2-11.    Page Zero Areas          2-35
               3-1.     Function 6 Entry Parameters         3-8
               3-2.     Edit Control Characters (Nonbanked CP/M 3)     3-13
               3-3.     Edit Control Characters (Banked CP/M 3)      3-14
               3-4.     System Control Block         3-70
               3-5.     Program Return Codes         3-90
               3-6.     FCB Format          3-98
               A- 1.    SCB Fields and Definitions         A-1
               B-1.     PRL File Format          B-1
               D- 1.    ASCII Symbols           D-1
               D-2.     ASCII Conversion Table         D-2
               E-1.     BDOS Function Summary         E-1








                                                           vii

                       Table of Contents (continued)



                                                Figures

            1-1.   Nonbanked System Memory Organization      1-2
            1-2.   Banked System Memory Organization      1-3
            1-3.   Banked Memory with Bank 1 in Context I     1-4
            1-4.   CP/M 3 Logical Memory Organization      1-5
            1-5.   System Components and Regions in Logical Memory     1-6
            1-6.   System Modules and Regions in Logical Memory    1-10
            1-7.   Disk Organization       1-12
            1-8.   RSX File Format       1-25

            2-1.   XFCB Format       2-19
            2-2.   Directory Label Format      2-20
            2-3.   Directory Record with SFCB      2-23








                                                      viii

                                          Section 1

                           Introduction to CP/M 3



          This section introduces you to the general features of CP/M 3 with an emphasis
        on how CP/M 3 organizes your computer's memory.  The section begins by describing
        the general memory organization of banked and nonbanked systems and defines the
        programming environment they have in common.  It then shows how CP/M 3 defines
        memory space into standard regions for operating system modules and executing
        programs.  Subsequent paragraphs describe the components of the operating system,
        how they communicate with each other and the application program, and in greater
        detail where each component and program is located in memory.  After a brief intro-
        duction to disk organization, the final section gives examples of system operation.

          CP/M 3 is available in two versions: a version that supports bank-switched mem-
        or, Y, and a version that runs on nonbanked systems. CP/M 3 uses the additional
        memory available in banked systems to provide functions that are not present in the
        nonbanked version.  For example, the banked version of CP/M 3 supports file pass-
        words; the nonbanked version does not.  However, because a nonbanked system
        treats passwords the same way as a banked system does when password protection
        is not enabled, an application program can run under either system without modifi-
        cation.








        Etc] DIGI'I-AL RESEAR(,H"

   1.1 Baiiked/Nonbanked Organization                   CP/M 3 Programmer's Guide



   1.1 Banked and Nonbanked Memory Organization


     The memory organization for a nonbanked CP/M 3 system is very simple, as

   shown in Figure 1-1.



                          TOP OF MEMORY@
                                                 BUFFERS



                                                   O.S.








                             LOW MEMORY
                                    (OOOOH)                   AN 064

                 Figure 1-1.  Nonbanked System Memory Organization


     In the nonbanked organization, physical memory consists of a single, contiguous
   region addressable from OOOOH up to a maximum of OFFFFH (64K-1).  The shaded
   region below the operating system represents the memory space available for the
   loading and execution of transient programs.  The clear area above the operating
   system represents space that GENCPM can allocate to the operating system for disk
   record buffers and directory hash tables, as described in the CPIM Plus (CPIM Ver-
   sion 3) Operating System System Guide.  The minimum size of this area is determined
   by the specific hardware requirements of the host microcomputer system.







                                                                  IC DIGITAL RESEARCHT.@
   1-2

     CP/M 3 Programmer's Guide      1.1 Banked/Nonbanked Organization

      To expand memory capacity beyond the 64K address space of an 8-bit micropro-
     cessor, CP/M 3 supports bank-switched memory in a special version called the banked
     system.  In the banked version, the operating system is divided into two modules: the
     resident portion and the banked portion.  The resident portion resides in common
     memory; the banked portion resides just below the top of banked memory in Bank 0.
     Figure 1-2 shows memory organization under the banked system.


      TOP OF MEMORY -
                        BUFFERS

                          O.S.
           (COMMON)


      TOP OF BANKED
             MEMORY     BANKED
                          O.S.


     (BANK SWITCHED)



        LOW MEMORY
              (OOOOH)
                         BANK 0         BANK1         BANK N
                                                            AN 062
                Figure 1-2.  Banked System Memory Organization


      In Figure 1-2, Bank 0 is switched in or in context.  The top region of memory, the
     common region, is always in context; that is, it can always be referenced, no matter
     what bank is switched in.  Figure 1-3 shows memory organization when Bank 1 is in
     context.








     170 DL(.ITAL RESEARC,H"
                                                              1-3

   1.1 Banked/Nonbanked Organization        CP/M 3 Programmer's Guide

                   TOP OF MEMORY b.
                                        BUFFERS

                                          O.S.
                         (COMMON)


   TOP OF BANKED
          MEMORY        BANKED
                         o@s.



   (BANK SWITCHED) -




     LOW MEMORY
           (OOOOH)
                       BANK 0            BANK1    ....   BANK NAN 165
              Figure 1-3.  Banked Memory with Bank 1 in Context


    From a transient program@s perspective, Bank 1 is always in context.  The operating
   system can switch to Bank 0 or other banks when performing operating system
   functions without affecting.the execution of the transient program.  Any bank-switch-
   ing performed by the operating system is completely transparent to the calling pro-
   gram.  Because the major portion of the operating system resides in Bank 0 in banked
   systems, more memory space is available for transient programs in banked CP/M 3
   systems than in nonbanked systems.

    The operating system uses the clear areas in Figures 1-2 and 1-3 for disk record
   buffers and directory hash tables.  The clear area in the common region above the
   operating system represents space that can be allocated for data buffers by GENCPM.
   Again, the minimum size of this area is determined by the specific hardware require-
   ments of the host microcomputer system.






                                                    P DIGITAL RESEARCHT"
   1-4

        CP/M 3 Programmer's Guide                    1.1 Banked/Nonbanked Organization

          The banked version of CP/M 3 requires a minimum of two banks, Bank 0 and
        Bank 1, and can support up to 16 banks of memory.  Bank numbers are generally
        arbitrary with the following exceptions: Bank 0 is the system bank and is in context
        when CP/M 3 is started.  Bank 1 is the transient program bank, and must be contig-
        uous from location zero to the top of banked memory.  This requirement does not
        apply to the other banks.  However, common memory must be contiguous.

          The size of the common region is typically 16K.  The only size requirement on the
        common region is that it must be large enough to contain the resident portion of the
        operating system.  The maximum top of memory address for both banked and non-
        banked systems is 64K-1 (OFFFFH).

          In summary, no matter how physical memory is configured, or whether the oper-
        ating system is banked or nonbanked, CP/M 3 always organizes memory logically so
        that to a transient program in any CP/M 3 system, memory appears as shown in
        Figure 1-4.

                               TOP OF MEMORY           BUFFERS

                                                          O.S.





                                   LOW MEMORY
                                          (OOOOH)                   AN 061

                       Figure 1-4.  CP/M 3 Logical Memory Organization


        1.2 System Components

          Functionally, the CP/M 3 operating system is composed of distinct modules.  Tran-
        sient programs can communicate with these modules to request system services.  Fig-
        ure 1-5 shows the regions where these modules reside in logical memory.  Note that
        from the transient program's perspective, Figure 1-5 is just a more detailed version
        of Figure 1-4.



        'Do DIGITAL RESEARCH'@
                                                                                          1-5

   1.2 System Components                                    CP/M 3 Programmer's Guide

            HIGH MEMORY:
                                   BIOS: BASIC INPUT/OUTPUT SYSTEM
                 BIOS-BASE:
                                   BDOS: BASIC DISK OPERATING SYSTEM
                BDOS-BASE:
                                   LOADER: PROGRAM LOADER MODULE
             LOADER-BASE:
                                   RSX(s): RESIDENT SYSTEM EXTENSIONS
                 RSX-BASE-.
                                            TRANSIENT PROGRAM AREA

                                            NSOLE COMMAND PROCESSOI
                      010OH:
                                   PAGE ZERO                                     AN 063
                      OOOOH:

            Figure 1-5.  System Components and Regions in Logical Memory

      The Basic Input/Output System, BIOS, is a hardware-dependent module that defines
   the low-level interface to a particular computer system.  It contains the device-driving
   routines necessary for peripheral device 1/0.

      The Basic Disk Operating System, BDOS, is the hardware-independent module that
   is the logical nucleus of CP/M 3. It provides a standard operating environment for
   transient programs by making services available through numbered system function
   calls.

      The LOADER module handles program loading for the Console Command Proces-
   sor and transient programs.  Usually, this module is not resident when transient pro-
   grams execute.  However, when it is resident, transient programs can access this
   module by making BDOS Function 59 calls.

      Resident System Extensions, RSXS, are temporary additional operating system
   modules that can selectively extend or modify normal operating system functions.
   The LOADER module is always resident when RSXs are active.





                                                                      F!cl DIGITAL RESEARCH"
   1-6

        CP/M 3 Programmer's Guide                                 1.2 System Components

          The Transient Program Area, TPA, is the region of memory where transient pro-
        grams execute.  The CCP also executes in this region.

          The Console Command Processor, CCP, is not an operating system module, but is
        a system program that presents a human-oriented interface to CP/M 3 for the user.

          The Page Zero region is not an operating system module either, but functions
        primarily as an interface to the BDOS module from the CCP and transient programs.
        It also contains critical system parameters.

        1.3 System Component Interaction and Communication

          This section describes interaction and communication between the modules and
        regions defined in Section 1.2. The most significant channels of communication are
        between the BDOS and the BIOS, transient programs and the BDOS, and transient
        programs and RSXS.

          ne division of responsibility between the different modules and the way they
        communicate with one another provide three important benefits.  First, because the
        operating system is divided into two modules-one that is configured for different
         ardware environments, and one that remains constant on every computer-CP/M 3
        software is hardware independent; you can port your programs unchanged to differ-
        ent hardware configurations.  Second, because all communication between transient
        programs and the BDOS is channeled through Page Zero, CP/M 3 transient programs
        execute, if sufficient memory is available, independent of configured memory size.
        Third, the CP/M 3 RSX facility can customize the services of CP/M 3 on a selective
        basis.

        1.3.1 The BDOS and BIOS
          CP/M 3 achieves hardware independence through the interface between the BDOS
        and the BIOS modules of the operating system.  This interface consists of a series of
        entry points in the BIOS that the BDOS calls to perform hardware-dependent primi-
        tive functions such as peripheral device VO.  For example, the BDOS calls the CONIN
        entry point of the BIOS to read the next console input character.

          A system implementor can customize the BIOS to match a specific hardware envi-
        ronment.  However, even when the BIOS primitives are customized to match the host
        computer's hardware environment, the BIOS entry points and the BDOS remain
        constant.  Therefore, the BDOS and the BIOS modules work together to give the CCP
        and other transient programs hardware-independent access to CP/M 3's facilities.

        Fi-al DIGITAT- RESEARCH"'
                                                                                          1-7

     1.3 Component Interaction                               CP/M 3 Programmer's Guide

     1.3.2 Applications and the BDOS
       Transient programs and the CCP access CP/M 3 facilities by making BDOS func-
     tion calls.  BDOS functions can create, delete, open, and close disk files, read or write
     to opened files, retrieve input from the console, send output to the console or list
     device, and perform a wide range of other services described in Section 3,"BDOS
     Functions."

       To make a BDOS function call, a transient program loads CPU registers with
     specific entry parameters and calls location 0005H in Page Zero.  If RSXs are not
     active in memory, location 0005H contains a jump instruction to location
     BDOS - base + 6. If RSXs are active, location 0005H contains a jump instruction to
     an address below BDOS   -base. Thus, the Page Zero interface allows programs to run
     without regard to where the operating system modules are located in memory.  In
     addition, transient programs can use the address at location 0006H as a memory
       'ling.
     cel

       Some BDOS functions are similar to BIOS entry points, particularly in the case of
     simple device 1/0.  For example, when a transient program makes a console output
     BDOS function call, the BDOS makes a BIOS console output call.  In the case of disk
     1/0, however, this relationship is more complex.  The BDOS might call many BIOS
     entry points to perform a single BDOS file 1/0 function.

       Transient programs can terminate execution by jumping to location OOOOH in the
     Page Zero region.  This location contains a jump instruction to BIOS base+3, which
     contains a jump instruction to the BIOS warm start routine.  The BIOS warm start
     routine loads the CCP into memory at location 100H and then passes control to it.

       The Console Command Processor is a special system program that executes in the
     TPA and makes BDOS calls 'ust like an application program.  However, the CCP has
     a unique role: it gives the user access to operating system facilities while transient
     programs are not executing.  It includes several built-in commands, such as TYPE and
     DIR, that can be executed directly without having to be loaded from disk.  When the
     CCP receives control, it reads the uscr's command lines, distinguishes between built-
     in and transient commands, and when necessary, calls upon the LOADER module to
     load transient programs from disk into the TPA for execution.  Section 1.6.2 describes
     CCP operation in detail.







                                                                        A DIGITAL RESEARCH   TM
     1-8

       CP/M 3 Programmer's Guide                                 1.3 Component Interaction

       1.3.3 Applications and RSXs
         A Resident System Extension is a temporary additional operating system module.
       An RSX can extend or modify one or more operating system functions selectively.
       As with a standard BDOS function, a transient program accesses an RSX function
       through a numbered function call.

         At any one time there might be zero, one, or multiple RSXs active in memory.
       When a transient program makes a BDOS function call, and RSXs are active, each
       RSX examines the function number of the call.  If the function number matches the
       function the RSX is designed to extend or modify, the RSX performs the requested
       function.  Otherwise, the RSX passes the function request to the next RSX.  Noninter-
       ceptcd functions are eventually passed to the BDOS for standard execution.

         RSXs are loaded into memory when programs containing RSXs are loaded.  The
       CP/M 3 utility, GENCOM, can attach RSXs to program files.  When attaching RSXS,
       GENCOM places a special one page header at the beginning of the program file.  The
       CCP reads this header, learns that a program has attached RSXS, and loads the RSXs
       accordingly.  The header itself is not loaded into memory; it merely indicates to the
       CCP that RSX loading is required.

         The LOADER module is a special type of RSX that supports BDOS function 59,
       Load Overlay.  It is always resident when RSXs are active.  To indicate RSX support
       is required, a program that calls function 59 must have an RSX header attached by
       GENCOM, even if the program does not require other RSXS.  When the CCP
       encounters this type of header in a program file when no RSXs are active, it sets the
       address at location 0006H in Page Zero to LOADER-base + 6 instead of
       BDOS-base + 6.

       1.4 Memory Region Boundaries

         This section reviews memory regions under CP/M 3, and then describes some
       details of region boundaries.  It then relates the sizes of various modules to the space
          ']able for the execution of transient programs.  Figure 1-6 reviews the location of
       aval                    I                                          I             I
       regions in logical memory.







        lo: DIGITAL RESEARCH'@
                                                                                            1-9

      1.4 Region Boundaries                                   CP/M 3 Programmer's Guide


               HIGH MEMORY:

                  BIOS BASE:        BIOS: BASIC 1/0 SYSTEM

                                    BDOS: BASIC DISK OPERATING SYSTEM
                   BDOS-BASE:       LOADER: PROGRAM LOADER MODULE
                LOADER-BASE:
                                    RSX(l): RESIDENT SYSTEM EXTENSION



                                    RSX(N): RESIDENT SYSTEM EXTENSION
                 RSX(N)-BASE:
                                    TPA: TRANSIENT PROGRAM AR

                                  @CCP: CONSOLE COMMAND PRO
                          010OH:    PAGE ZERO
                          OOOOH:                                                  I AN D66

                 Figure 1-6.  System Modules and Regions in Logical Memory

        First note that all memory regions in CP/M 3 are page-aligned.  This means that
      regions and operating system modules must begin on a page boundary.  A page is
      defined as 256 bytes, so a page boundary always begins at an address where the low-
      order byte is zero.

        The term High Memory in Figure 1-6 denotes the high address of a CP/M 3
      system.  This address may fall below the actual top of memory address if space above
      the operating system has been allocated for directory hashing or data buffering by
      GENCPM.  The maximum top of memory address for both banked and nonbanked
      systems is 64K-1 (OFFFFH).

        T'he labels BIOS-base, BDOS_base, and LOADER_base represent the base addresses
      of the operating system regions.  These addresses always fall on page boundaries.  The
      size of the BIOS region is not fixed, but is determined by the requirements of the
      host computer system.


      1-10                                                               90 DIGITAL RESEARCH  TM

        CP/M 3 Programmer's Guide                                     1.4 Region Boundaries

          The size of the BDOS region differs for the banked and nonbanked versions of
        CP/M 3. In the banked version, the resident BDOS size is 6 pages, 1.5K. In the
        nonbanked system, the BDOS size ranges from 31 pages, 7.75K, to 33 pages, 8.25K,
        depending on system generation options and BIOS requirements.

          RSXs are page aligned modules that are stacked in memory below LOADER          - base
        in memory.  In the configuration shown in Figure 1-6, location 0005H of Page Zero
        contains a jump to location RSX(N)_base + 6. Thus, the memory ceiling of the TPA
        region is reduced when RSXs are active.

          Under CP/M 3. the CCP is a transient program that the BIOS loads into the TPA
        region of memory at system cold and warm start.  The BIOS also loads the LOADER
        module at this time, because the LOADER module is attached to the CCP.  When the
        CCP gains control, it relocates the LOADER module just below BDOS          -base. The
        LOADER module handles program loading for the CCP.  It is three pages long.

          The maximum size of a transient program that can be loaded into the TPA Is
        limited by LOADER-base because the LOADER cannot load a program over itself.
        Transient programs may extend beyond this point, however, by using memory above
        LOADER   - base for uninitialized data areas such as 1/0 buffers. Programs that use
        memory above BDOS-base cannot make BDOS function calls.

        1.5 Disk and Drive Organization and Requirements

          CP/M 3 can support up to sixteen logical drives, identified by the letters A through
        PI, with up to 512 megabytes of storage each.  A logical drive usually corresponds to
        a physical drive on the system, particularly for physical drives that support remova-
        ble media such as floppy disks.  High-capacity hard disks, however, are commonly
        divided up into multiple logical drives.  Figure 1-7 illustrates the standard organiza-
        tion of a CP/M 3 disk.








        Ec DIGITAL RESEARCH"

   1.5 Disk Organization                                    CP/M 3 Programmer's Guide

                   TRACK M
                                      CP/M 3 DATA REGION
             DATA TRACKS
                                      CP/M 3 DIRECTORY REGION
                   TRACK N
                                      CCP (OPTIONAL)

          SYSTEM TRACKS               CPMLDR

                                      COLD BOOT LOADER
                     TRACKO   -                                                     AN 067

                              Figure 1-7.  Disk Organization

     In Figure 1-7, the first N tracks are the system tracks.  System tracks are required
   only on the disk used by CP/M 3 during system cold start or warm start.  The
   contents of this region are described in Section 1.6.1. All normal CP/M 3 disk access
   is directed to the data tracks which CP/M 3 uses for file storage.

     The data tracks are divided into two regions: a directory area and a data area.  The
   directory area defines the files that exist on the drive and identifies the data space
   that belongs to each file.  The data area contains the file data defined by the directory.
   If the drive has adequate storage, a CP/M 3 file can be as large as 32 megabytes.

     The directory area is subdivided into sixteen logically independent directories.  These
   directories are identified by user numbers 0 through 15.  During system operation,
   CP/M 3 runs with the user number set to a single value.  The user number can be
   changed at the console with the USER command.  A transient program can change
   the user number by calling a BDOS function.

     The user number specifies the currently active directories for all the drives on the
   svstem.  For example, a PIP command to copy a file from one disk to another gives
   t@e destination file the same user number as the source file unless the PIP command
   is modified by the [G] option.






                                                                       P DIGITAL RESEARCH   TM
   1-12

        CPIM I Programmer's Guide                                        1.5 Disk Organization

          The directory identifies each file with an eight-character filename and a three-
        character filetype.  Together, these fields must be unique for each file.  Files with the
        same filename and filetype can reside in different user directories on the same drive
        without conflict.  Under the banked version of CP/M 3, a file can be assigned an
        eight-character password to protect the file from unauthorized access.

          All BDOS functions that involve file operations specify the requested file by file-
        name and filetype.  Multiple files can be specified by a technique called ambiguous
        reference, which uses question marks and asterisks as wildcard characters to give
        CP/M 3 a pattern to match as it searches the directory.  A question mark in an
        ambiguous reference matches any value in the same position in the directory filename
        or filetype field.  An asterisk fills the remainder of the filename or filetype field of the
        ambiguous reference with question marks.  Thus, a filename and filetype field of all
        question marks, ????????.???, equals an ambiguous reference of two asterisks,
        and matches all files in the directory that belong to the current user number.

          The CP/M 3 file system automatically allocates directory space and data area space
        when a file is created or extended, and returns previously allocated space to free
        space when a file is deleted or truncated.  If no directory or data space is available for
        a requested operation, the BDOS returns an error to the calling program.  In general,
        the allocation and deallocation of disk space is transparent to the calling program.
        As a result, you need not be concerned with directory and drive organization when
        using the file system facilities of CP/M 3.

        1.6 System Operation

          This section introduces the general operation of CP/M 3. This overview covers
        opics concerning the CP/M 3 system components, how they function and how they
        interact when CP/M 3 is running.  This section does not describe the total function-
        t
        ality of CP/M 3, but simply introduces basic CP/M 3 operations.

          For the purpose of this overview, CP/M 3 system operation is divided into five
        categories.  First is system cold start, the process that begins execution of the operat-
        ing system.  This procedure ends when the Console Command Processor, CCP, is
        loaded into memory and the system prompt is displayed on the screen.  Second is the
        operation of the CCP, which provides the user interface to CP/M 3. Third is transient
        program initiation, execution and termination.  Fourth is the way Resident System
        Ex,ensions run under CP/M 3. The fifth and final category describes the operation of
        the CP/M 3 SUBMIT utility.



        -io DIGITAL RESEAR(:H"'
                                                                                               1-13

   1.6 System Operation                                     CP/M 3 Programmer's Guide

   1.6.1 Cold Start Operation
      The cold start procedure is typically executed immediately after the computer is
   turned on.  The cold start brings CP/M 3 into memory and gives it control of the
   computer's resources.  Cold start is a four-stage procedure.

      In the first stage, a hardware feature, or ROM-based software associated with
   system reset, loads a small program, called the Cold Boot Loader, into memory from
   the system tracks of drive A (see figure 1-6).  The Cold Boot Loader is usually 128 or
   256 bytes long.

      The Cold Boot Loader performs the second stage of the cold start process.  It loads
   the CP/M 3 loader program, CPMLDR, into memory from the system tracks of the
   system disk and passes control to it.  During this stage, the Cold Boot Loader can
   also perform other tasks, such as initializing hardware dependent 1/0 ports.

      CPMLDR performs the third stage in the cold start process.  First, it reads the
   CPM3.SYS file from the data area of the disk.  The CPM3.SYS file, which is created
   by the CP/M 3 system generation utility GENCPM, contains the BDOS and BIOS
   system components and information indicating where these modules are to reside in
   memory.  Once CPMLDR has loaded the BDOS and BIOS into memory, it sends a
   sign-on message to the console and passes control to the BIOS Cold Boot entry point.
   If specified as a GENCPM option, CPMLDR can also display a memory map of the
   CP/M 3 system.

      CPMLDR is a small, self-contained version of CP/M 3 that supports only console
   output and sequential file input.  Consistent with CP/M 3's organization, it contains
   two modules, an invariant CPMLDR-BDOS, and a variant CPMLDR              -BIOS that is
   adapted to match the host microcomputer hardware environment.  Cold start initiali-
   zation of VO ports and similar functions can also be performed in the CPMLDR-BIOS
   module during the third stage of cold start.

      In the banked version of CP/M 3, these first three stages of the cold boot procedure
   are performed with Bank 0 in context.  The BIOS Cold Start function switches in
   Bank 1 before proceeding to stage four.




   1-14                                                              9 DIGITAL RESEARCHTN'

        CP/M 3 Programmer's Guide                                      1.6 System Operation

           The fourth and final stage in the cold start procedure is performed by the BIOS
        Cold Start function, Function 0. The entry point to this function is located at
        BIOS -base as described in Section 1.4. The BIOS Cold Start function begins by
        performing any remaining hardware initialization, and initializing Page Zero.  To
        initialize Page Zero, the BIOS Cold Start function places a jump to BIOS base + 3,
        the BIOS Warm Start entry point, at location OOOOH, and a jump to BDOS-base + 6,
        the BDOS entry point, at location 0005H in memory.

           The BIOS Cold Start function completes the fourth stage by loading the CCP into
        the TPA region of memory and passing control to it.  The CCP can be loaded from
        one of two locations.  If there is sufficient space in the system tracks for the CCP, it
        is usually loaded from there.  If there is not enough space in the system tracks, the
        BIOS Cold Start function can read the CCP from the file CCP.COM.

           On some banked systems, the CCP is also copied to an alternate bank, so that
        warm start operations can copy the CCP into the TPA from memory.  This speeds up
        the system warm start operation, and makes it possible to warm start the system
        without having to access a system disk.

           When the CCP gains control, it displays a prompt that references the default disk.
        If a PROFILE.SUB submit file is present on the default drive, the CCP executes this
        submit file before prompting the user for a command.

           At this point, the cold start procedure is complete.  Note that the user number is
        set to zero when CP/M 3 is cold started.  However, the PROFILE submit file can set
        the user number to another value if this is desirable.

           The cold start procedure is designed so that the system tracks need to be initialized
        only once.  This is accomplished because the system track routines are independent of
        the configured memory size of the CP/M 3 system.  The Cold Boot Loader loads
        CPMLDR into a constant location in memory.  This location is chosen when the
        system is configured.  However, CPMLDR locates the BDOS and BIOS system com-
        ponents in memory as specified by the CPM3.SYS file.  The CCP always executes at
        location 100H in the TPA.  Thus, CP/M 3 allows the user to generate a new system
        with GENCPM, and then run it without having to update the system tracks of the
        system disk.








         'Do DL(.ITAL RESEARCH"
                                                                                             1-15



                                                                                                 AN

    1.6 System Operation                                      CP/M 3 Programmer's Guide

    1.6.2 CCP Operation
      The Console Command Processor provides the user access to CP/M 3 facilities
    when transient programs are not running.  It also reads the user's command lines,
    differentiates between built-in commands and transient commands, and executes the
    commands accordingly.

      This section describes the responsibilities and capabilities of the CCP in some
    detail.  The section begins with a description of the CCP's activities when it first
    receives control from the Cold Start procedure.  The section continues with a general
    discussion of built-in commands, and concludes with a step-by-step description of
    the procedure the CCP follows to execute the user's commands.

      When the CCP gains control following a cold start procedure, it displays the
    system prompt at the console.  This signifies that the CCP is ready to execute a
    command.  The system prompt displays the letter of the drive designated as the initial
    default drive during GENCPM operation.  For example, if drive A was specified as
    the initial default drive, the CCP displays the following prompt:

    A >

    After displaying the system prompt, the CCP scans the directory of the default drive
    for the file PROFILE.SUB. If the file exists, the CCP creates the command line
    SUBMIT PROFILE; otherwise the CCP reads the user's first command line by mak-
    ing a BDOS Read Console Buffer function call (BDOS Function 10).

      The CCP accepts two different command forms.  The simplest CCP command form
    changes the default drive.  The following example illustrates a user changing the
    default drive from A to B.

    A>B:
    B >

    This command is one of the CCP's built-in commands.  Built-in commands are part
    of the CCP.  They reside in memory while the CCP is active, and therefore can be
    executed without referencing a disk.




    1-16                                                                19 DIGITAL RESEARCHT@

        CP/M 3 Programmer's Guide                                          1.6 System Operation

          The second command form the CCP accepts is the standard CP/M command line.
        A standard CP/M command line consists of a command keyword followed by an
        optional command tail.  The command keyword and the command tall can be typed
        in any combination of upper-case and lower-case letters; the CCP converts all letters
        n the command line to upper-case.  The following syntax defines the standard CP/M
        command line:
        i
             <command> <command tail>

        where
             <command>                      = > <filespec> or
                                                 <built-in>

             <command tail>                 = >  (no command tail) or
                                                 <filespec> or <filespec><delimiter><filespec>

             <filespec>                     = >  Id:lfilenamef.typl{;passwordl

             <built-in>                     = >  one of the CCP built-in commands

             <delimiter>                    = >  one or more blanks or a tab or one of the
                                                 following:"=,[]<> "

             d:                             = >  CP/M 3 drive specification,"A"through"P"

             filename                       = >  1 to 8 character filename

             typ                            = >  1 to 3 character filetype

             password                       = >  I to 8 character password value

        Fields enclosed in curly brackets are    optional. If there is no drive Id:l present in a file
             'fication <filespec>, the default   drive is assumed. If the type field f.typl is omit-
        speci
        ted, a type field of all blanks is implied.  Omitting the password field @;passwordl
        implies a password of all blanks.  When a command line is entered at the console, it
        is terminated by a return or line-feed keystroke.

           Transient programs that run under CP/M 3 are not restricted to the above com-
        mand tail definition.  However, the CCP only parses command tails in this format for
        transient programs.  Transient programs that define their command tails differently
        must perform their own command tall parsing.

           DIGITAL RESEARCH"'                                                                      1-17

    1.6 System Operation                                      CP/M 3 Programmer's Guide

      The command field must identify either a built-in command, a transient program,
    or a submit file.  For example, USER is the keyword that identifies the built-in com-
    mand that changes the current user number.  The CP/M 3 CCP displays the user
    number in the system prompt when the user number is non-zero.  The following
    example illustrates changing the user number from zero to 15.

    B>USER 15
    155>

    The following table summarizes the built-in commands.

                           Table 1-1.  CP/M 3 Built-in Commands

     Command                                          Meaning

     DIR                 displays a list of all filenames from a disk directory except those
                         marked with the SYS attribute.

     DIRSYS              displays a filename list of those files marked with the SYS
                         attribute in the directory.

     ERASE               erases a filename from a disk directory and releases the storage
                         occupied by the file.

     RENAME              renames a file.

     TYPE                displays the contents of an ASCII character file at your console
                         output device.

     USER                changes from one user number to another.


       Some built-in commands have associated command files which expand upon the
                 'ded by the built-in command.  If the CCP reads a command line and
    options provi                I
    discovers the built-in command does not support the options requested in the com-
    mand line,, the CCP loads the built-in function's corresponding command file to
    perform the command.  The DIR command is an example of this type of command.
    Simple DIR commands are supported by the DIR built-in directly.  More complex
    requests are handled by the DIR.COM utility.


                                                                        k DIGITAL RESEARCH  TM

         CP/M 3 Programmer's Guide                                        1.6 System Operation

         All command keywords that do not identify built-in commands identify either a
         transient program file or a submit file.  If the CCP identifies a command keyword as
         a transient program, the transient program file is loaded into the TPA from disk and
         executed.  If it recognizes a submit file, the CCP reconstructs the command line into
         the following form:

             SUBMIT <command> <command tail>

         and attempts to load and execute the SUBMIT utility.  Thus, the original command
         fie'ld becomes the first command tail field of the SUBMIT command.  Section 1.6.5
         describes the execution of CP/M 3's SUBMIT utility.  The procedure the CCP follows
         o parse a standard command line and execute built-in and transient commands is
         described as follows:
         t
             1. The CCP parses the command line to pick up the command field.
             2. If the command field is not preceded by a drive specification, or followed by
                a filetype or password field, the CCP checks to see if the command is a CCP
                built-in function.  If the command is a built-in command, and the CCP can
                support the options specified in the command tail, the CCP executes the
                command.  Otherwise, the CCP goes on to step 3.
             3. At this point the CCP assumes the command field references a command file
                or submit file on disk.  If the optional filetype field is omitted from the com-
                mand, the CCP usually assumes the command field references a file of type
                COM.  For example, if the command field is PIP, the CCP attempts to open
                the file PIP.COM.
                Optionally, the CP/M 3 utility SETDEF can specify that a filetype of SUB
                also be considered when the command filetype field is omitted.  When this
                automatic submit option is in effect, the CCP attempts to open the command
                with a filetype of COM.  If the COM file cannot be found, the CCP repeats
                the open op  eration with a filetype of SUB. As an alternative, the order of
                open operations can be reversed so that the CCP attempts to open with a
                filetype of SUB first.  In either case, the file that is found on disk first deter-
                mines the filetype field that is ultimately associated with the command.
                If the filetype field is present in the command, it must equal COM, SUB or
                PRL.  A PRL file is a Page Relocatable file used in Digital Research's multi-
                user operating system, MP/M".  Under CP/M 3, the CCP handles PRL files
                exactly like COM files.




         IC DIGITAL RESEARCH'@                                                                1-19

    1.6 System Operation                                      CP/M 3 Programmer's Guide

            If the command field is preceded by a drive specification id:), the CCP attempts
            to open the command or submit file on the specified drive.  Otherwise, the
            CCP attempts to open the file on the drives specified in the drive chain.
            The drive chain specifies up to four drives that are to be referenced in sequence
            for CCP open operations of command and submit files.  If an open operation
            is unsuccessful on a drive in the drive chain because the file cannot be found,
            the CCP repeats the open operation on the next drive in the chain.  This
            sequence of open operations is repeated until the file is found, or the drive
            chain is exhausted.  The drive chain contains the current default drive as its
            only drive unless the user modifies the drive chain with the CP/M 3 SETDEF
            utility.
            When the current user number is non-zero, all open requests that fail because
            the file cannot be found, attempt to locate the command file under user zero.
            If the file exists under user zero with the system attribute set, the file is
            opened from user zero.  This search for a file under user zero is made by the
            BDOS Open File function.  Thus, the user zero open attempt is made before
            advancing to the next drive in the search chain.
            When automatic submit is in effect, the CCP attempts to open with the first
            filetype, SUB or COM, on all drives in the search chain before trying the
            second filetype.
            In the banked system, if a password specified in the command field does not
            match the password of a file on a disk protected in Read mode, the CCP file
            open operation is terminated with a password error.
            If the CCP does not find the command or submit file, it echoes the command
            line followed by a question mark to the console.  If it finds a command file
            with a filetype of COM or PRL, the CCP proceeds to step 4. If it finds a
            submit file, it reconstructs the command line as described above, and repeats
            step 3 for the command, SUBMIT.COM.







   1-20                                                                 9 DIGITAL RESEARCHT@

         CP/M    3 Programmer's Guide                                  1.6 System Operation

             4.  When the CCP successfully opens the command file, it initializes the follow-
                 ing Page Zero fields for access by the loaded transient program:
                 OOSOH    Drive that the command file was loaded from
                 0051H    Password address of first file in command tail
                 0053H    Password length of first file in command tail
                 0054H    Password address of second file in command tail
                 0056H    Password length of second file in command tail
                 005CH    Parsed FCB for first file in command tail
                 006CH    Parsed FCB for second file in command tail
                 0080H    Command tail preceded by command tail length
                 Page Zero initialization is covered in more detail in Section 2.4.
             5.  At this point, the CCP calls the LOADER module to load the command file
                 into the TPA.  The LOADER module terminates the load operation if a read
                 error occurs, or if the available TPA space is not large enough to contain the
                 file.  If no RSXs are resident in memory, the available TPA space is deter-
                 mined by the address LOADER    - base because the LOADER cannot load over
                 itself.  Otherwise, the maximum TPA address is determined by the base address
                 of the lowest RSX in memory.
             6.  Once the program is loaded, the LOADER module checks for a RSX header
                 on the program.  Programs with RSX headers are identified by a return
                 instruction at location 100H.
                 If an RSX header is present, the LOADER relocates all RSXs attached to the
                 end of the program, to the top of the TPA region of memory under the
                 LOADER module, or any other RSXs that are already resident.  It also updates
                 the address in location 0006H of Page Zero to address the lowest RSX in
                 memory.  Finally, the LOADER discards the RSX header and relocates the
                 program file down one page in memory so that the first executable instruc-
                 tion resides at 100H.
             7.  After initializing Page Zero, the LOADER module sets up a 32-byte stack
                 with the return address set to location OOOOH of Page Zero and jumps to
                 location 100H.  At this point, the loaded transient program begins execution.








         IFO'!  DIGITAL RESEAR(.H"@
                                                                                           1-21

    1.6 System Operation                                     CP/M 3 Programmer's Guide

      When a transient program terminates execution, the BIOS warm start routine
    reloads the CCP into memory.  When the CCP receives control, it tests to see if RSXs
    are resident in memory.  If not, it relocates the LOADER module below the BDOS
    module at the top of the TPA region of memory.  Otherwise, it skips this step because
    the LOADER module is already resident.  The CCP execution cycle then repeats.

      Unlike earlier versions of CP/M, the CCP does not reset the disk system at warm
    start.  However, the CCP does reset the disk system if a CTRL-C is typed at the
    prompt.

    1.6.3 Transient Program Operation
      A transient program is one that the CCP loads into the TPA region of memory
    and executes.  As the name transient implies, transient programs are not system resi-
    dent.  The CCP must load a transient program into memory every time the program
    is to be executed.  For example, the utilities PIP and RMAC" that are shipped with
    CP/M 3 execute as transient programs; programs such as word processing and
    accounting packages distributed by applications vendors also execute as transient
    programs under CP/M 3.

      Section 1.6.2 describes how the CCP prepared the CP/M 3 environment for the
    execution of a transient program.  To summarize, the CCP initializes Page Zero to
    contain parsed command-line fields and sets up a 32-byte stack before jumping to
    location 0100H to pass control to the transient program.  In addition, the CCP might
    also load RSXs attached to the command file into memory for access by the transient
    program.

      Generally, an executing transient program communicates with the operating sys-
    tem only through BDOS function calls.  Transient programs make BDOS function
    calls by loading the CPU registers with the appropriate entry parameters and calling
    location 0005H in Page Zero.

      Transient programs can use BDOS Function 50, Call BIOS, to access BIOS entry
    points.  This is the preferred method for accessing the BIOS; however, for compatibil-
    ity with earlier releases of CP/M, transient programs can also make direct BIOS calls
    for console and list 1/0 by using the jump instruction at location OOOOH in Page
    Zero.  But, to simplify portability, use direct BIOS calls only where the primitive level
    of functionality provided by the BIOS functions is absolutely required.  For example,
    a disk formatting program must bypass CP/M's disk organization to do its job, and
    therefore is justified in making direct BIOS calls.  Note however, that disk formatting
    programs are rarely portable.

                                                                       B DIGITAL RESEARCH   T'
    1-22

          CP/M 3 Programmcr's Guide                                      1.6 System Operation

           A transient program can terminate execution in one of three ways: by jumping to
          location OOOOH, by making a BDOS System Reset call, or by making a BDOS Chain
          To Program call.  The first two methods are equivalent; they pass control to the BIOS
          warm start entry point, which then loads the CCP into the TPA, and the CCP
          prompts for the next command.

           The Chain to Program call allows a transient program to specify the next com-
          mand to be executed before it terminates its own execution.  A Program Chain call
          executes a standard warm boot sequence, but passes the command specified by the
          terminating program to the CCP in such a way that the CCP executes the specified
          command instead of prompting the console for the next command.

           Transient programs can also set a Program Return Code before terminating by
          making a BDOS Function 108 call, Get/Set Program Return Code.  The CCP initial-
          izes the Program Return Code to zero, successful, when it loads a transient program,
          unless the program is loaded as the result of a program chain.  Therefore, a transient
          program that terminates successfully can use the Program Return Code to pass a
          value to a chained program.  If the program terminates as the result of a BDOS fatal
          error, or a CTRL-C entered at the console, the BDOS sets the return code to an
          unsuccessful value.  All other types of program termination leave the return code at
          its current value.

           The CCP has a conditional command facility that uses the Program Return Code.
          If a command line submitted to the CCP by the SUBMIT utility begins with a colon,
          the CCP skips execution of the command if the previous command set an unsuccess-
          ful Program Return Code.  In the following example, the SUBMIT utility sends a
          command sequence to the CCP:

          A>SUBIIIT SUBFILE
          A>CCMPUTERESULTS,,DAT
          A >: REPORT RESUL TS # DA T

          The CCP does not execute the REPORT command if the COMPUTE command sets
          an unsuccessful Program Return Code.

          1.6.4 Resident System Extension Operation
            This section gives a general overview of RSX use, then describes how RSXs are
          loaded, defines the RSX file structure, and tells how the LOADER module uses the
          RSX prefix and flags to manage RSX activity.




          E DIGITAL RESEARCH'@
                                                                                              1-23

    1.6 System Operation                                   CP/M 3 Programmer's Guide

      A Resident System Extension (RSX) is a special type of program that can be
    attached to the operating system to modify or extend the functionality of the BDOS.
    RSX modules intercept BDOS functions and either perform them, translate them into
    other BDOS functions, or pass them through untouched.  The BDOS executes non-
    intercepted functions in the standard manner.

      A transient program can also use BDOS Function 60, Call Resident System Exten-
    sion, to call an RSX for special functions.  Function 60 is a general purpose function
    that allows customized interfaces between programs and RSXS.

      Two examples of RSX applications are the GET utility and the LOADER module.
    The GET.COM command file has an attached RSX, GET.RSX, which intercepts all
    console input calls and returns characters from the file specified in the GET command
    line.  The LOADER module is another example of an RSX, but it is special because
    it supports Function 59, Load Overlay.  It is always resident in memory when other
    RSXs are active.

      RSXs are loaded into memory at program load time.  As described in Section 1.6.2,
    after the CCP locates a command file, it calls the LOADER module to load the
    program into the TPA.  The LOADER loads the transient program into memory
    along with any attached RSXS.  Subsequently, the loader relocates each attached RSX
    to the top of the TPA and adjusts the TPA size by changing the jump at location
    0005H in Page Zero to point to the RSX.  When RSX modules reside in memory, the
    LOADER module resides directly below the BDOS, and the RSX modules stack
    downward from it.

      The order in which the RSX modules are stacked affects the order in which they
    intercept BDOS calls.  A more recently stacked RSX has precedence over an older
    RSX.  Thus,, if two RSXs in memory intercept the same BDOS function, the more
    recently loaded RSX handles the function.

      The CP/M 3 utility GENCOM attaches RSX modules to program files.  Program
    files with attached RSXs have a special one page header that the LOADER recognizes
    when it loads the command file.  GENCOM can also attach one or more RSXs to a
    null command file so that the CCP can load RSXs without having to execute a
    transient program.  In this case, the command file consists of the RSX header fol-
    lowed by the RSXS.

      RSX modules are Page Relocatable, PRL, files with the file type RSX.  RSX files
    must be page relocatable because their execution address is determined dynamically
    by the LOADER module at load time.  RSX files have the following format:

                                                                    19 DIGITAL RESEARCHT@
    1-24

          CP/M 3 Programmer's Guide                                        1.6 System Operation

                             END OF FILE-.
                                                  PRL BIT MAP

                                                  RSX CODE

                                                  RSX PREFIX
                                     010OH-.
                                                  256 BYTE PRL HEADER
                                     OOOOH:     I                                 AN 060

                                       Figure 1-8.  RSX File Format

            RSX files begin with a one page PRL header that specifies the total size of the RSX
          prefix and code sections.  The PRL bit map is a string of bits identifying those bytes
          in the RSX prefix and code sections that require relocation.  The PRL format is
          described in detail in Appendix B. Note that the PRL header and bit map are removed
          when an RSX is loaded into memory.  They are only used by the LOADER module
          to load the RSX.

            The RSX prefix is a standard data structure that the LOADER module uses to
          manage RSXs (see Section 4.4). Included in this data structure are jump instructions
          to the previous and next RSX in memory, and two flags.  The LOADER module
          initializes and updates these 'ump instructions to maintain the link from location 6
                                         i
          of Page Zero to the BDOS entry point.  The RSX flags are the Remove flag and the
          Nonbanked flag.  The Remove flag controls RSX removal from memory.  The CCP
          tests this flag to determine whether or not it should remove the RSX from memory
          at system warm start.  The nonbanked flag identifies RSXs that are loaded only in
          nonbanked CP/M 3 systems.  For example, the CP/M 3 RSX, DIRLBL.RSX, is a
          nonbanked RSX.  It provides BDOS Function 100, Set Directory Label, support for
          nonbanked systems only.  Banked systems support this function in the BDOS.

            The RSX code section contains the main body of the RSX.  This section always
          begins with code to intercept the BDOS function that is supported by the RSX.
          Nonintercepted functions are passed to the next RSX in memory.  This section can
          also include initialization and termination code that transient programs can call with
          BDOS Function 60.





            DL(,ITAL RESEAR('H
                                                                                                  1-25

    1.6 System Operation                                    CP/M 3 Programmer's Guide

      When the CCP gains control after a system warm       start, it removes any RSXs in
    memory that have the Remove flag set to OFFH.  All other RSXs remain active in
    memory.  Setting an RSX's Remove flag to OFFH indicates that the RSX is not active
    and it can be removed.  Note that if an RSX marked for removal is not the lowest active
    RSX in memory, it still occupies memory after removal.  Although the removed RSX
    cannot be executed, its space is returned to the TPA only when all the lower RSXs are
    removed.

      There 'is one special case where the CCP does not remove an RSX with the Remove
    flag set to OFFH following warm start.  This case occurs on warm starts following the
    load of an empty file with attached RSXS.  This exception allows an RSX with the
    Remove flag set to be loaded into i-nemory before a transient program.  The transient
    program can then access the RSX during execution.  After the transient program
    terminates, however, the CCP removes the RSX from the system environment.

      As an example of RSX operation, here is a description of the operation of the GET
      'lity.  The GET.COM command file has an attached RSX.  The LOADER moves
    uti
    this RSX to the top of the TPA when it loads the GET.COM command file.  The
    GET utility performs necessary initializations which include opening the ASCII file
    specified in the GET command line.  It also makes a BDOS Function 60 call to
    initialize the GET.RSX. At this point, the GET utility terminates.  Subsequently, the
    GET.RSX intercepts all console input calls and returns characters from the file speci-
    fied in the GET command line.  It continues this action until it reads end-of-file.  At
    this point, it sets its Remove flag in the RSX prefix, and stops intercepting console
    input.  On the following warm boot, the CCP removes the RSX from memory.

    1.6.5 SUBMIT Operation
      A SUBMIT command line has the following syntax:

        SUBMIT <filespec> <parameters>

    If the CCP identifies a command as a submit file, it automatically inserts the SUBMIT
    keyword into the command line as described in Section 1.6.2.








                                                                      10 DIGITAL RESEARCH  TM
    1-26

         CP/M 3 Programmer's Guide                                        1.6 System Operation

           When the SUBMIT utility begins execution, it opens and reads the file specified by
         <filespec> and creates a temporary submit file of type $$$ on the system's tempo-
         rary file drive.  GENCPM initializes the temporary file drive to the CCP's current
         default drive.  The SETDEF utility can set the temporary file drive to a specific drive.
         As it creates the temporary file, SUBMIT performs the parameter substitutions requested
         by the <parameters> subfield of the SUBMIT command line.  See the CP/M Plus
         (CPIM Version 3) Operating System User's Guide for a detailed description of this
         process.

           After SUBMIT creates the temporary submit file, its operation is similar to that of
         the GET utility described in Section 1.6.4. The SUBMIT command file also has an
         attached RSX that performs console input redirection from a file.  However, the
         SUBMIT RSX expands upon the simpler facilities provided by the GET RSX.  Com-
         mand lines in a submit file can be marked to indicate whether they are program or
         CCP input.  Furthermore, if a program exhausts all its program input, the next SUB-
         MIT command is a CCP command, the SUBMIT RSX temporarily reverts to console
         input.  Redirected input from the submit file resumes when the program terminates.

           Because CP/M 3's submit facility is implemented with RSXS, submit files can be
         nested.  That is) a submit file can contain additional SUBMIT or GET commands.
         Similarly, a GET command can specify a file that contains GET or SUBMIT com-
         mands.  For example, when a SUBMIT command is encountered in a submit file, a
         new SUBMIT RSX is created below the current RSX.  The new RSX handles console
                   'I it reads end-of-file on its temporary submit file.  At this point, control
         input unti 1
         reverts to the previous SUBMIT RSX.

         1.7 System Control Block

           The System Control Block, SCB, is a 100 byte CP/M 3 data structure that resides
         in the BDOS system component.  The SCB contains internal BDOS flags and data,
         CCP flags and data, and other system information such as console characteristics and
         the current date and time.  The BDOS, BIOS, CCP system components as well as
         CP/M 3 utilities and RSXs reference SCB fields.  BDOS Function 49, Get/Set System
         Control Block, provides access to the SCB fields for transient programs, RSXS, and
         the CCP.








          E, t)](,'ITAL RESEAR(H"
                                                                                                1-27

    1.7 System Control Block                                  CP/M 3 Programmer's Guide

      However, use caution when you access the SCB through Function 49 for two
    reasons.  First, the SCB is a CP/M 3 data structure.  Digital Research's multi-user
    operating system, MP/M, does not support BDOS Function 49.  Programs that access
    the SCB can run only on CP/M 3. Secondly, the SCB contains critical system param-
    eters that reflect the current state of the operating system.  If a program modifies these
                illegally, the operating system might crash.  However, for application writ-
    parameters 1
    ers who are writing system-oriented applications, access to the SCB variables might
    prove valuable.

      For example, the CCP default drive and current user number are maintained in the
    System Control Block.  This information is displayed in the system prompt.  If a
    transient program changes the current disk or user number by making an explicit
    BDOS call, the System Control Block values are not changed.  They continue to reflect
    the state of the system when the transient program was loaded.  For compatibility
    with CP/M Version 2, the current disk and user number are also maintained in
    location 0004H of Page Zero.  The high-order nibble contains the user number, and
    the low-order nibble contains the drive.

      Refer to the description of BDOS Function 49 in Section 2.5 for more information
    on the System Control Block.  The SCB fields are also discussed in Appendix A.

                                       End of Section 1








                                                                        l@ DIGITAL RESEARCH  TM
    1-28

                                           Section

                       The BDOS System Interface



           This section describes the operating system services available to a transient pro-
         gram through the BDOS module of CP/M 3. The section begins by defining how a
         transient program calls BDOS functions, then discusses serial 1/0 for console, list and
         auxiliary devices, the file system, and Page Zero initialization.

         2.1 BDOS Calling Conventions

           CP/M 3 uses a standard convention for BDOS function calls.  On entry to the
         BDOS, register C contains the BDOS function number, and register pair DE contains
         a byte or word value or an information address. BDOS functions return single-byte
         values in register A, and double-byte values in register pair HL. In addition, they
         return with register A equal to L, and register H equal to B. If a transient program
         makes a BDOS call to a nonsupported function number in the range of 0 to 127, the
         BDOS returns with register pair HL set to OFFFFH.  For compatibility with MP/M,
         the BDOS returns with register pair HL set to OOOOH on nonsupported function
         numbers in the range of 128 to 255. Note that CP/M 2 returns      with HL set to zero
         on all invalid function calls.  CP/M 3's register passing conventions for BDOS func-
         tion calls are consistent with the conventions used by the Intel PL/M systems pro-
         gramming language.

           When a transient program makes a BDOS function call, the BDOS does not restore
         registers to their entry values before returning to the calling program.  The responsi-
         bility for saving and restoring any critical re 'ster values rests with the calling program.
                                                    91

           When the CCP loads a transient program, the LOADER module sets the stack
         pointer to a 16 level stack, and then pushes the address OOOOH onto the stack.  Thus,
         an immediate return to the system is equivalent to a jump to OOOOH.  However, most
         transient programs set up their own stack, and terminate execution by making a
         BDOS System Reset call (Function 0) or by jumping to location OOOOH.








         Fool [)[(;I FAL RLSLAR(:H
                                                                                              2-1

    2.1 BDOS Calling Conventions                                  CP/M 3 Prograiiimer's Guide

      The following example illustrates how a transient program calls a BDOS function.
    This program reads characters continuously until it encounters an asterisk.  Then it
        mates execution by returning to the system.
    term'

    bdos        EqU       0005h             ;BDOS entry Point in Page Zero
    conin       eqU       I                 ;BDOS console input function

                a r I     100h              ;Base of Transient Program Area
    nextc:      MI)i      c t can i n
                call      bdos              ;Return character in A
                cpi       1*1               ;End of Processini?
                inz       nextc             ;Loop if not
                r e t                       ;Terminate Program
                e n d

    2.2 BDOS Serial Device I/O

      Under CP/M 3, serial device 1/0 is simply input to and output from simple devices
    such as consoles, line printers, and communications devices.  These physical devices
    can be assigned the logical device names defined below:

        CONIN:              logical console input device
        CONOUT:             logical console output device
        AUXIN:              logical auxiliary input device
        AUXOUT:             logical auxiliary output device
        LST:                logical list output device

      If your system supports the BIOS DEVTBL function, the CP/M 3 DEVICE utility
    can display and change the assignment of logical devices to physical devices.  DEVICE
    can also display the names and attributes of physical devices supported on your
    system.  If your system does not support the DEVTBL entry point, then the logical to
    physical device assignments are fixed by the BIOS.

      In general, BDOS serial 1/0 functions read and write an individual ASCII charac-
    ter, or character string to and from these devices, or test the device's ready status.
    For these BDOS functions, a string of characters is defined as zero to N characters
    terminated by a delimiter.  A block of characters is defined as zero to N characters
    where N is specified by a word count field.  The maximum value of N in both cases
    is limited only by available memory.  The following list summarizes BDOS serial
    device 1/0 functions.

                                                                              9 DIGITAL RESEARCH    TM
    2-2

         CP/M 3 Programmer's Guide                                   2.2 BDOS Serial Device 1/0

              Read a character from CONIN:
              Read a character buffer from CONIN:
              Write a character to CONOUT:
              Write a string of characters to CONOUT:
              Write a block of characters to CONOUT:
              Read a character from AUXIN:
              Write a character to AUXOUT:
              Write a character to LST:
              Write a block of characters to LST:
              Interrogate CONIN:, AUXIN:, AUXOUT: ready

           CP/M 3 cannot run unless CONIN: and CONOLJT: are assigned to a physical
         console.  The remaining logical devices can remain unassigned.  If a logical output
         device is not assigned to a physical device, an output BDOS call to the logical device
         performs no action. If a logical input device is not assigned to a physical device, an
         input BDOS call to the logical device typically returns a CTRL-Z (lAH), which
         indicates end-of-file.  Note that these actions depend on your system's BIOS
         implementation.

         2.2.1 BDOS Console 1/0
           Because a transient program's main interaction with its user is through the console,
         the BDOS supports many console 1/0 functions.  Console PO functions can be divided
         into four categories: basic console 1/0, direct console I/O, buffered console input,
         and special console functions.  Using the basic console 1/0 functions, programs can
         access the console device for simple input and output.  The basic console 1/0 func-
         tions are:

                 1. Console Input - Inputs a single character
                 2. Console Output- Outputs a single character
                 9. Print String     - Outputs a string of characters
                11. Console Status - Signals if a character is ready for input
              111. Print Block       - Outputs a block of characters

           The input function echoes the character to the console so that the user can identify
         the typed character.  The output functions expand tabs in columns of eight characters,








         -far DIGITAL RESEAR(.'Hl"
                                                                                                    2-3

     2.2 BDOS Serial Device 1/0                                CP/M 3 Progranimer's Guide

       The basic 1/0 functions also monitor the console to stop and start console output
     scroll at the user's request.  To provide this support, the console output functions
     make internal status checks for an input character before writing a character to the
     output device.  The console input and console status functions also check the input
     character.  If the user types a CTRL-S, these functions make an additional Blos
     console input call.  This input call suspends execution until a character is typed.  If the
     typed character is not a CTRL-Q, an additional BIOS console input call is made.
     Execution and console scrolling resume when the user types a CTRL-Q.

       When the BDOS is suspended because of a typed CTRL-S, it scans input for three
     special characters: CTRL-Q, CTRL-C, and CTRL-P.  If the user types any other
     character, the BDOS echoes a bell character, CTRL-G, to the console, discards the
     input character, and continues the scan.  If the user types a CTRL-C, the BDOS
     executes a warm start which terminates the calling program.  If the user types a
     CTRL-P, the BDOS toggles the printer echo switch.  The printer echo switch controls
     whether console output is automatically echoed to the list device, LST:.  The BDOS
     signals when it turns on printer echo by sending a bell character to the console.

       All basic console 1/0 functions discard any CTRL-Q or CTRL-P character that is
     not preceded by a CTRL-S character.  Thus, BDOS function 1 cannot read a CTRL-
     S, CTRL-Q, or CTRL-P character.  Furthermore, these characters are invisible to the
     console status function.

       The second category of console 1/0 is direct console 1/0.  BDOS function 6 can
         'de direct console   1/0 in situations where unadorned console 1/0 is required.
     prove     I                  I   I    t
     Function 6 actually consists of several sub-functions that support direct console input,
     output, and status checks.   The BDOS does not filter out special characters during
     direct console 1/0.  The direct output sub-function does not expand tabs, and the
     direct input sub-function does not echo typed characters to the console.

       The third category of console 1/0 accepts edited input from the console.  The only
     function in this category, Function 10, Read Buffer Input, reads an input line from a
     buffer and recognizes certain control characters that edit the input.  As an option, the
     line to be edited can be initialized by the calling program.

       In the nonbanked version of CP/M 3, editing within the buffer is restricted to the
     last character on the line.  That. is, to edit a character embedded in the line, the user
     must delete all characters that follow the erroneous character, correct the error, and
     then retype the remainder of the line.  The banked version of CP/M 3 supports
     complete line editing in which characters can be deleted and inserted anywhere in the
     line.  In addition', the banked version can also recall the previously entered line.

                                                                           DIGITAL RESEARCH'@@
     2-4

         CP/M 3 Programmer's Guide                                   2.2 BDOS Serial Device 1/0

           Function 10 also filters input for certain control characters.  If the user types a
         CTRL-C as the first character in the line, Function 10 terminates the calling program
         by branching to the BIOS warm start entry point.  A CTRL-C in any other position
         is simply echoed at the console.  Function 10 also watches for a CTRL-P keystroke,
         and if it finds one at any position in the command line, it toggles the printer echo
         switch.  Function 10 does not filter CTRL-S and CTRL-Q characters, but accepts
         them as normal input.  In general, all control characters that Function 10 does not
         recognize as editing control characters, it accepts as input characters.  Function 10
         identifies a control character with a leading caret, ', when it echoes the control
         character to the console.  Thus, CTRL-C appears as 'C in a Function 10 command
         line on the screen.

           The final category of console 1/0 functions includes special functions that modify
         the behavior of other console functions.  These functions are:

              109.  Get/Set Console Mode
              110.  Get/Set Output Delimiter

         Function 110 can get or set the current delimiter for Function 9, Print String.  The
         delimiter is $, when a transient program begins execution.  Function 109 gets or sets
         a 16-bit system variable called the Console Mode.  The following list describes the
         bits of the Console Mode variable and their functions:

         bit 0    If this bit is set, Function 11 returns true only if a CTRL-C is typed at the
                  console.  Programs that make repeated console status calls to test if execution
                  should be interrupted, can set this bit to interrupt on CTRL-C only.  The
                  CCP DIR and TYPE built-in commands run in this mode.

         bit 1    Setting this bit disables stop and start scroll support for the basic console
                  110 functions, which comprise the first category of functions described in
                  this section.  When this bit is set, Function 1 reads CTRL-S, CTRL-Q, and
                  CTRL-P, and Function 1 1 returns true if the user types these characters.  Use
                  this mode in situations where raw console input and edited output is needed.
                  While in this mode, you can use Function 6 for input and input status, and
                  Functions 1, 9, and 111 for output without the possibility of the output
                  functions intercepting input CTRL-S, CTRL-Q, or CTRL-P characters.

         bit 2 :  Setting this bit disables tab expansion and printer echo support for Functions
                  21 9. and 1 1 1. Use this mode when non-edited output is required.



         [C@] DIGITAL RLSEARCH""                                                                    2-5

    2.2 BDOS Serial Device 1/0                             CP/M 3 Programmer's Guide

    bit 3 : This bit disables all CTRL-C intercept action in the BDOS.  This mode is
            useful for programs that must control their own termination.

    bits 8 and 9 : The BDOS does not use these bits, but reserves them for the CP/M 3
            GET RSX that performs console input redirection from a file.  With one
            exception, these bits determine how the GET RSX responds to a program
            console status request (Function 6, Function 11, or direct BIOS).

            bit 8 =  01 bit 9 = 0 - conditional status
            bit 8 @ 0, bit 9 = 1 - false status
            bit 8 =  1, bit 9 = 0 - true status
            bit 8 =  1, bit 9 = 1 - do not perform redirection

      In conditional status mode, GET responds false to all status requests except for a
    status call preceded immediately by another status call.  On the second call, GET
    responds with a true result.  Thus, a program that spins on status to wait for a
    character is signaled that a character is ready on the second call.  In addition, a
    program that makes status calls periodically to see if the user wants to stop is not
    signaled.

       When  a transient program begins execution, the Console Mode bits are normally
    set to zero.  However,, the CP/M 3 utility GENCOM can attach an RSX header to a
    COM file so that when it is loaded, the console mode bits are set differently.  This
    feature allows you to modify a program's console 1/0 behavior without having to
    change the program.

    2.2.2 Other Serial I/O
      The BDOS supports single character output functions for the logical devices LST:
    and AUXOUT:, an input function for AUXIN:, and status functions for AUXIN:
    and AUXOUT:.  A block output function is also supported for the LST: device.
    Unlike the console 1/0 functions, the BDOS does not intercept control characters or
    expand tabs for these functions.  Note that AUXIN: and AUXOUT: replace the
    READER and PUNCH devices supported by earlier versions of CP/M.








                                                                      9 DIGITAL RESEARCH  TM
    2-6

          CP/M 3 Programmer's Guide                                        2.3 BDOS File System

          2.3 BDOS File System

            Transient programs depend on the BDOS file system to create, update, and main-
          tain disk files.  This section describes the capabilities of the BDOS file system in detail.
          You must understand the general features of CP/M 3 described in Section 1 before
          you can use the detail presented in this section.

            The remaining introductory paragraphs define the four categories of BDOS file
          functions.  This is followed by a review of file naming conventions and disk and file
          organization.  The section then describes the data structure used by the BDOS file,
          and directory oriented functions: the File Control Block (FCB).  Subsequent discus-
          sions cover file attributes, user numbers, directory labels and extended File Control
          Blocks (XFCBs), passwords, date and time stamping, blocking and deblocking, multi-
          sector 1/0, disk reset and removable media, byte counts, and error handling.  These
          topics are closely related to the BDOS file system.  You must be familiar with the
          contents of Section 2 before attempting to use the BDOS functions described individ-
          ually in Section 3.

            The BDOS file system supports four categories of functions: file access functions,
          directory functions, drive related functions, and miscellaneous functions.  The file
          access category includes functions to create a file, open an existing file, and close a
          file.  Both the make and open functions activate the file for subsequent access by
          BDOS file access functions.  The BDOS read and write functions are file access func-
          tions that operate either sequentially or randomly by record position.  They transfer
          data in units of 128 bytes, which is the basic record size of the file system.  The close
          function makes any necessary updates to the directory to permanently record the
          status of an activated file.








          9 DIGITAL RESEARCH'@
                                                                                                 2-7

    2.3 BDOS File System                                       CP/M 3 Ilrogrammer's Guide

     BDOS directory functions operate on existing file entries in a drive's directory.
    This category includes functions to search for one or more files, delete one or more
    files, truncate a file, rename a file, set file attributes, assign a password to a file, and
    compute the size of a file.  The search and delete functions are the only BDOS func-
    tions that support ambiguous file references.  All other directory and fi e related func-
    tions require a specific file reference.

     The BDOS drive-related category includes functions that select the default drive,
    compute a drive's free space, interrogate drive status, and assign a directory label to
    a drive.  A drive's directory label controls whether or not CP/M 3 enforces file pass-
    word protection, or stamps files with the date and time.  Note that the nonbanked
    version of CP/M 3 does not support file passwords.

     The miscellaneous category includes functions to set the current DMA address,
    access and update the current user number, chain to a new program, and flush
    internal blocking/deblocking buffers.  Also included are functions that set the BDOS
    multi-sector count, and the BDOS error mode.  The BDOS multi-sector count deter-
    mines the number of 128-byte records to be processed by BDOS read and write
    functions.  It can range from 1 to 128.  The BDOS error mode determines how the
    BDOS file system handles certain classes of errors.

      Also included in the miscellaneous category are functions that call the BIOS directly,
    set a program return code, and parse filenames.  If the LOADER RSX is resident in
    memory, programs can also make a BDOS function call to load an overlay.  Another
    miscellaneous function accesses system variables in the System Control Block.








                                                                            DiGi,rAL RESEARCH   TM
    2-8

       CP/M 3 Programmer's Guide                                  2.3 BDOS File System

          The following list summarizes the operations performed by the BDOS file system-

            Disk System Reset
            Drive Selection
            File Creation
            File Open
            File Close
            Directory Search
            File Delete
            File Rename
            Random or Sequential Read
            Random or Sequential Write
            Interrogate Selected Disks
            Set DMA Address
            Set/Reset File Attributes
            Reset Drive
            Set BDOS Multi-Sector Count
            Set BDOS Error Mode
            Get Disk Free Space
            Chain to Program
            Flush Buffers
            Get/Set System Control Block
            Call BIOS
            Load Overlay
            Call RSX
            Truncate File
            Set Directory Label
            Get File's Date Stamps and Password Mode
            Write File XFCB
            Set/Get Date and Time
            Set Default Password
            Return CP/M 3 Serial Number
            Get/Set Program Return Code
            Parse Filename

       2.3.1 File Naming Conventions

         Under CP/M 3, a file specification consists of four parts: the drive specifier, the
       filename field, the filetype field, and the file password field.  The general format for a
       command line file specification is shown below:

            fd:lfilenamef.typlf;passwordl

             I-Al, RFSEAR('H                                                         2-9

    2.3 BDOS File System                                        CP/M 3 Programmer's Guide

    The drive specifier field specifies the drive where the file is located. The filename and
    type fields identify the file.  The password field specifies the password if a file is
    password protected.

      -ne drive, type, and password fields are optional, and the delimiters :.; are required
    only when specifying their associated field.  The drive specifier can be assigned a letter
    from A to P where the actual drive letters supported on a given system are deter-
    mined by the BIOS implementation.  When the drive letter is not specified, the current
    default drive is assumed.

      The filename and password fields can contain one to eight non-delimiter charac-
    ters.  The filetype field can contain one to three non-delimiter characters.  All three
    fields are padded with blanks, if necessary.  Omitting the optional type or password
    fields implies a field specification of all blanks.

      The CCP calls BDOS Function 152, Parse Filename, to parse file specifications
    from a command line.  Function 152 recognizes certain ASCII characters as valid
    delimiters when it parses a file from a command line.  The valid delimiters are shown
    in Table 2-1.


                              Table 2-1.  Valid Filenamc Delimiters

                               ASCII           HEX EQUIVALENT

                                null                      00
                               space                      20
                               return                     OD
                                 tab                      09
                                                          3A
                                                          2E
                                                          3B
                                                          3D
                                                          2C
                                                          5B
                                                          5D
                                  <                       3C
                                  >                       3E
                                                          7C


     2-10                                                                    IL70, DIGITAL RESEARCH'@

            CP/M 3 Programmer's Guide                                        2.3 BDOS File System

            Function 152 also excludes all control characters from the file fields, and translates all
            lower-case letters to upper-case.

              Avoid using parentheses and the backslash character, \, in the filename and filetype
            fields because they are commonly used delimiters.  Use asterisk and question mark
            characters, * and ?, only to make an ambiguous file reference.  When Function 152
            encounters an * in a filename or filetype field, it pads the remainder of the field with
            question marks.  For example, a filename of X*.* is parsed to X???????.???. The
            BDOS search and delete functions treat a ? in the filename and type fields as follows:
            A ? in any position matches the corresponding field of any directory entry belonging
            to the current user number.  Thus, a search operation for X???????.??? finds all the
            current user files on the directory beginning in X. Most other file related BDOS
            functions treat the presence of a ? in the filename or type field as an error.

              It is not mandatory to follow the file naming conventions of CP/M 3 when you
            create or rename a file with BDOS functions.  However, the conventions must be used
            if the file is to be accessed from a command line.  For example, the CCP cannot locate
            a command file in the directory if its filename or type field contains a lower-case
            letter.

              As a general rule, the filetype field names the generic category of a particular file,
            while the filename distinguishes individual files in each category.  Although they are
            generally arbitrary, the following list of filetypes names some of the generic categories
            that have  been established.

                 ASM     Assembler Source              PLI    PL/I Source File
                 PRN     Printer Listing               REL    Relocatable Module
                 HEX     Hex Machine Code              TEX    TEX Formatter Source
                 BAS     Basic Source File             BAK    ED Source Backup
                 INT     Intermediate File             SYM    SID Symbol File
                 COM     Command File                  $$$    Temporary File
                 PRL     Page Relocatable              DAT    Data File
                 SPR     Sys. Page Reloc.              SYS    System File

            2.3.2 Disk and File Organization
              The BDOS file system can support from one to sixteen logical drives.  The maxi-
            mum file size supported on a drive is 32 megabytes.  The maximum capacity of a
            drive is determined by the data block size specified for the drive in the BIOS.  The
            data block size is the basic unit in which the BDOS allocates disk space to files.


            'EC] D I (i I'FA I- R ESLA RCH                                                        2-11

   2.3 BDOS File System                                         CP/M 3 Programmer's Guide




          Table 2-2 displays the relationship between data block size and drive capacity.




                              Table 2-2.  Logical Drive Capacity

                      Data Block Size           Maximum Drive Capacity


                              1K                       256 Kilobytes

                              2K                        64 Megabytes

                              4K                       128 Megabytes

                              8K                      256 Megabytes

                             16K                      512 Megabytes
                     I                                                        I                       I

      Logical drives are divided into two regions: a directory area and a data area.  The

    directory area contains from one to sixteen blocks located at the         beginning of the

    drive.  The actual number is set in the BIOS.  This area contains entries that define

    which files exist on the drive.  The directory entries corresponding to a particular file

    define those data blocks in the drive's data area that belong to the file.  These data

    blocks contain the file's records.  The directory area is logically subdivided into six-

    teen independent directories identified as user 0 through 15.  Each independent direc-

    tory shares the actual directory area on the drive.  However, a file's directory entries

    cannot exist under more than one user number.  In general, only files belonging to

    the current user number are visible in the directory.


      Each disk file consists of a set of up to 262,144 128-byte records.  Each record in

    a file is identified by its position in the file.  This position is called the record's random

    record number.  If a file is created sequentially, the first record has a position of zero,

    while the last record has a position one less than the number of records in the file.

    Such a file can be read sequentially in record position order beginning at record zero,

    or randomly by record position.  Conversely, if a file is created randomly, records are

    added to the file by specified position.  A file created in this way is called sparse if

    positions exist within the file where a record has not been written.


      The BDOS automatically allocates data blocks to a file to contain its records on

    the basis of the record positions consumed.  Thus, a sparse file that contains two

    records, one at position zero, the other at position 262,143, consumes only two data

    blocks in the data area.  Sparse files can only be created and accessed randomly, not

    sequentially.  Note that any data block allocated to a file is permanently allocated to

    the file until the file is deleted or truncated.  These are the only mechanisms supported

    by the BDOS for releasing data blocks belonging to a file.





    2-12                                                                    'ED] DIGITAL RESEARCH TM

        CP/M 3 Programmer's Guide                                         2.3 BDOS File System

          Source files under CP/M 3      are treated as a sequence of ASCII characters, where
        each line of the source file is followed by a carriage return line-feed sequence, ODH
        followed by OAH.  Thus a single 128-byte record could contain several lines of source
        text.  The end of an ASCII file is denoted by a CTRL-Z character, 1AH, or a real end
        of file, returned by the BDOS read operation.  CTRL-Z characters embedded within
        machine code files such as COM files are ignored.  The actual end-of-file condition
        returned by the BDOS is used to terminate read operations.

        2.3.3 File Control Block Definition
          The File Control Block, FCB, is a data structure that is set up and initialized by a
        transient program, and then used by any BDOS file access and directory functions
        called by the transient program.  Thus the FCB is an important channel for informa-
        tion exchange between the BDOS and a transient program.  For example, when a
        program opens a file, and subsequently accesses it with BDOS read and write record
        functions, the BDOS file system maintains the current file state and position within
        the program's FCB.  Some BDOS functions use certain fields in the FCB for invoking
        special options.  Other BDOS functions use the FCB to return data to the calling
        program.  In addition, all BDOS random I/O functions specify the random record
        number with a 3-byte field at the end of the FCB.

          When a transient program makes a file access or directory BDOS function call,
        register pair DE must address an FCB.  The length of the FCB data area depends on
        the BDOS function.  For most functions, the required length is 33 bytes.  For random
        1/0 functions, the Truncate File function, and the Compute File Size function, the
        FCB length must be 36 bytes.  The FCB format is shown on the next page.






          DIGITAL RESEARCH'                                                                    2-13
                                                                                                         IN
    2.3 BDOS File System                                              CP/M 3 Programmer's Guide



      dr I fil f2 II f8              31  ex I  SiI s2 I  rcI  do II dn  Lcr  I rO I r:l E               I
      00 01 02  08   09 10     11   12 13 14        15   16  31    32 33     34 35

      where
           dr                  drive code (O - 16)
                               0 = > use default drive for file
                               1 = > auto disk select drive A,
                               2 = > auto disk select drive B,

                               16 = > auto disk select drive P.

           fl ... f8           contain the filename in ASCII
                               upper-case, with high bit = 0.
                               fl"..., f8' denote the high-
                               order bit of these positions,
                               and are file attribute bits.

           tl,t2,t3            contain the filetype in ASCII
                               upper-case, with high bit = 0.
                               tl') t2'1 and t3' denote the
                               high bit of these positions,
                               and are  file attribute bits.
                               tl' = 1 = > Read/Only file
                               t2' = 1 = > System file
                               t3' = 1  = > File has been archived

           ex                  contains  the current extent number,
                               usually set to 0 by the calling program,
                               but can range 0 - 31 during file 1/0

           sl                  reserved for internal system use

           s2                  reserved for internal system use

           rc                  record count for extent "ex"
                               takes on values from 0 - 255
                               (values greater than 128 imply
                               record count equals 128)



       2-14                                                                              DIGITAL RESEARCH'

          CP/M 3 Programmer's Guide                                      2.3 BDOS File System

              dO ... dn        filled-in by CP/M 3, reserved for
                               system use

              cr               current record to read or write in
                               a sequential file operation, normally
                               set to zero by the calling program
                               when a file is opened or created

              rO,,rl,r2        optional random record number in the
                               range 0-262,143 (O - 3FFFFH).
                               ro,rl,r2 constitute a 18 bit value
                               with low byte rO, middle byte rl, and
                               high byte r2.

            For BDOS directory functions, the calling program must initialize bytes 0 through
          11 of the FCB before issuing the function call.  The Set Directory Label and Write
          File XFCB functions also require the calling program to initialize byte 12.  The Rename
          File function requires the calling program to place the new filename and type in bytes
          17 through 27.

            BDOS open or make function calls require the calling program to intialize bytes 0
          through 12 of the FCB before making the call.  Usually, byte 12 is set to zero.  In
                    if the file is to be processed from the beginning using sequential read or
          addition, 1
          write functions, byte 32, cr, must be zeroed.

           After an FCB is activated by an open or make operation, a program does not have
          to modify the FCB to perform sequential read or write operations.  In fact, bytes 0
          through 31 of an activated FCB should not be modified.  However, random 1/0
          functions require that a program set bytes 33 through 35 to the requested random
          record number prior to making the function call.

           File directory entries maintained in the directory area of each disk have the same
          format as FCBS, excluding bytes 32 through 35, except for byte 0 which contains the
          file's user number.  Both the Open File and Make File functions bring these entries,
          excluding byte 0, into memory in the FCB specified by the calling program.  All read
          and write operations on a file must specify an FCB activated in this manner.


           DIGITAL RESFARCH                                                                  2-15

    2.3 BDOS File System                                         CP/M 3 Programmer's Guide

      The BDOS updates the memory copy of the FCB during file processing to maintain
    the current position within the file.  During file write operations, the BDOS updates
    the memory copy of the FCB to record the allocation of data to the file, and at the
    termination of file processing, the Close File function permanently records this infor-
    mation on disk.  Note that data allocated to a file during file write operations is not
    completely recorded in the directory until the calling program issues a Close File call.
    Therefore,, a program that creates or modifies files must close the files at the end of
    any write processing.  Otherwise, data might be lost.

      The BDOS Search and Delete functions support multiple or ambiguous file refer-
    ences.  In general, a question mark in the filename, filetype, or extent field matches
    any value in the corresponding positions of directory FCBs during a directory search
    operation.  The BDOS search functions also recognize a question mark in the drive
    code field, and if specified, they return all directory entries on the disk regardless of
    user number, including empty entries.  A directory FCB that begins with E5H is an
    empty directory entry.

    2.3.4 File Attributes
      The high-order bits of the FCB filename, fl',...,f8', and filetype, tl',t2',t3', fields
    are called attribute bits.  Attributes bits are 1 bit Boolean fields where 1 indicates on
    or true, and 0 indicates off or false.  Attribute bits indicate two kinds of attributes
    within the file system: file attributes and interface attributes.

      The file attribute bits, fl ...... f4' and tl',t2',t3', can indicate that a file has a defined
    file attribute.  These bits are recorded in a file's directory FCBS.  File attributes can be
    set or reset only by the BDOS Set File Attributes function.  When the BDOS Make
    File function creates a file, it initializes all file attributes to zero.  A program can
    interrogate file attributes in an FCB activated by the BDOS Open File function, or in
    directory FCBs returned by the BDOS Search For First and Search For Next functions.

    Note: the BDOS file system ignores file attribute bits when it attempts to locate a file
    in the directory.

       The file system defines the file attribute bits, tl',t2',t3', as follows:

    tl': Read-Only attribute - The file system prevents write operations to a file with
           the read-only attribute set.



    2-16                                                                           DIGITAL RESEARCH"

