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

       t2':  System attribute - This attribute, if set, identifies the file as a CP/M 3 system
             file.  System files are not usually displayed by the CP/M 3 DIR command.  In
             addition, user-zero system files can be accessed on a read-only basis from other
             user numbers.

       t3':  Archive attribute - This attribute is designed for user written archive programs.
             When an archive program copies a file to backup storage, it sets the archive
                'bute of the copied files.  The file system automatically resets the archive
             attri
             attribute of a directory FCB that has been issued a write command.  The archive
             program can test this attribute in each of the file's directory FCBs via the BDOS
             Search and Search Next functions.  If all directory FCBs have the archive attri-
             bute set, it indicates that the file has not been modified since the previous
             archives Note that the CP/M 3 PIP utility supports file archival.

       Attributes fl' through f4' are available for definition by the user.

         The interface attributes are indicated by bits f5' through f8' and cannot be used as
       file attributes.  Interface attributes f5' and f6' can request options for BDOS Make
       File, Close File, Delete File, and Set File Attributes functions.  Table 2-3 defines options
       indicated by the f5' and f6' interface attribute bits for these functions.

                               Table 2-3.  BDOS Interface Attributes
                       BDOS Function                 Interface Attribute Definition

                    16. Close File                   f5'    1   Partial Close

                    19. Delete File                  f5'     1   Delete file XFCBs
                                                                 only

                    22. Make File                    f6' = 1    Assign password to
                                                                file

                    30. Set File Attributes          f6' = 1    Set file byte count


       Section 3 discusses each interface attribute in detail in the definitions of the above
       functions.  Attributes f5' and f6' are always reset when control is returned to the
       calling program.  Interface attributes f7' and f8' are reserved for internal use by the
       BDOS file system.

         DIGITAL RESEARCH,                                                                     2-17


                                                                                                      AN

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

     2.3.5 User Number Conventions
       The CP)'M 3 User facility divides each drive directory into sixteen logically inde-
     pendent directories, designated as user 0 through user 15.  Physically, all user direc-
     tories share the directory area of a drive.  In most other aspects, however, they are
     independent.  For example, files with the same name can exist on different user num-
     bers of the same drive with no conflict.  However, a single file cannot reside under
     more than one user number.

       Only one user number is active for a program at one time, and the current user
     number applies to all drives on the system.  Furthermore, the FCB format does not
     contain any field that can be used to override the current user number.  As a result,
     all file and directory operations reference directories associated with the current user
     number.  However, it is possible for a program to access files on different user num-
     bers; this can be accomplished by setting the user number to the file's user number
     with the BDOS Set User function before making the desired BDOS function call for
     the file.  Note that this technique must be used carefully.  An error occurs if a program
     attempts to read or write to a file under a user number different from the user
     number that was active when the file was opened.

       When the CCP loads and executes a transient program, it initializes the user num-
     ber to the value displayed in the system prompt.  If the system prompt does not
     display a user number, user zero is implied.  A transient program can change its user
     number by making a BDOS Set User function call.  Changing the user number in this
     way does not affect the CCP's user number displayed in the system prompt.  When
     the transient program terminates, the CCP's user number is restored.  However, an
     option of the BDOS Program Chain command allows a program to pass its current
     user number and default drive to the chained program.

       User 0 has special properties under CP/M 3. When the current user number is not
     equal to zero, and if a requested file is not present under the current user number,
     the file system automatically attempts to open the file under user zero.  If the file
     exists under user zero, and if it has the system attribute, t2', set, the file is opened
     from user zero.  Note, however, that files opened in this way cannot be written to;
     they are available only for read access.  This procedure allows utilities that may
     include overlays and any other commonly accessed files to be placed on user zero,
     but also be available for access from other user numbers.  As a result, commonly
     needed utilities need not be copied to all user numbers on a directory, and you can
     control which user zero files are directly accessible from other user numbers.

     2-18                                                                  sr DIGITAL RESEARCH

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

        2.3.6 Directory Labels and XFCBs
          The BDOS file system includes two special types of FCBS: the XFCB and the
        Directory Label.  The XFCB is an extended FCB that optionally can be associated
        with a file in the directory.  If present, it contains the file's password.  Note that
        password protected files and XFCBs are supported only in the banked version of
        CP/M 3. The format of the XFCB follows.


                 DR FILE       TYPE PM Sl S2 RC PASSWORD                      RESERVED

                 00 01 ...      09.. 12 13 14 15            16 ......          24 ......
                                                                                         AN 069
                                        Figure 2-1.  XFCB Format

             dr           -         drive code (O - 16)
             file         -         filename field
             type         -         filetype field
             PM           -         password mode
                                    bit 7 - Read mode
                                    bit 6 - Write mode
                                    bit 5 - Delete mode
                                          - bit references are right to left,
                                            relative to 0
             sl,s2, rc    -         reserved for system use
             password -             8-byte password field (encrypted)
             reserved     -         8-byte reserved area








           DIGITAL RESEAPCH                                                                       2-19

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

       An XFCB can be created only on a drive that has a directory label, and only if the
     directory label has activated password protection.  For drives in this state, an XFCB
     can be created for a file in two ways: by the BDOS Make function or by the BDOS
     Write File XFCB function.  The BDOS Make function creates an XFCB if the calling
     program requests that a password be assigned to the created file.  The BDOS Write
     File XFCB function can be used to assign a password to an existing file.  Note that in
     the directory, an XFCB is identified by a drive byte value, byte 0 in the FCB, equal
     to 16 + N, where N equals the user number.

       For its drive, the directory label specifies if file password support is to be activated,
     and if date and time stamping for files is to be performed.  The format of the Direc-
     tory Label follows.


                DR NAME TYPE Dl Sl S2 RC PASSWORD TS1 TS2

                00     01        09      12 13 14 15          16  ......       24     28
                                                                                           AN 070

                                Figure 2-2.  Directory Label Format

          dr           -          drive code (O - 16)
          name         -          Directory Label name
          type         -          Directory Label type
          dl           -          Directory Label data byte
                                  bit 7 - require passwords for password
                                          protected files
                                  bit 6  - perform access time stamping
                                  bit 5  - perform update time stamping
                                  bit 4  -perform create time stamping
                                  bit 0  -Directory Label exists
                                         -bit references are right to left,
                                          relative to 0
          sl,s2,rc     -          n/a
          password     -          8-byte password field (encrypted)
          tsl          -          4-byte creation time stamp field
          ts2          -          4-byte update time stamp field


     2-20                                                                           DIGITAL RESEARCH'

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

         Only one Directory Label can exist in a drive's directory.  The Directory Label name
         and type fields are not used to search for a Directory Label; they can be used to
         identify a disk.  A Directory Label can be created, or its fields can be updated by
         BDOS function 100, Set Directory Label.  This function can also assign a Directory
         Label a password.  The Directory Label password, if assigned, cannot be circum-
         vented, whereas file password protection is an option controlled by the Directory
         Label.  Thus, access to the Directory Label password provides a kind of super-user
         status on that drive.

           The nonbanked version of CP/M 3 does not support file passwords.  However, it
         does provide password protection of directory labels.  The CP/M 3 RSX, DIRLBL.RSX,
         which implements BDOS Function 100 in the nonbanked version of CP/M 3, pro-
           'des this support.
         vi

           The BDOS file system has no function to read the Directory Label FCB directly.
         However, the Directory Label data byte can be read directly with the BDOS Function
         101, Return Directory Label.  In addition, the BDOS Search functions, with a ? in the
         FCB drive byte, can be used to find the Directory Label on the default drive.  In the
         directory, the Directory Label is identified by a drive byte value, byte 0 in the FCB,
         equal to 32, 20H.

         2.3.7 File Passwords
           Only the banked version of CP/M 3 supports file passwords.  In the nonbanked
         version, all BDOS functions with password related options operate the same way the
         banked version does when passwords are not enabled.

           Files can be assigned passwords in two ways: by the Make File function or by the
         Write File XFCB function.  A file's password can also be changed by the Write File
         XFCB function if the original password is supplied.

           Password protection is provided in one of three modes.  Table 2-4 shows the differ-
         ence in access level allowed to BDOS functions when the password is not supplied.





           DIGITAL RESEARCH                                                                   2-21

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

                          Table 2-4.  Password Protection Modes
                  Password           Access level allowed wben the Password
                  Mode               is not supplied.

                  1. Read            The file cannot be read.

                  2. Write           The file can be read, but not modified.

                  3. Delete          The file can be modified, but not
                                     deleted.


    If a file is password protected in Read mode, the password must be supplied to open
    the file.  A file protected in Write mode cannot be written to without the password.
    A file protected in Delete mode allows read and write access, but the user must
        'fy the password to delete the file, rename the file, or to modify the file's attri-
    speci
    butes.  Thus, password protection in mode 1 implies mode 2 and 3 protection, and
    mode 2 protection implies mode 3 protection.  All three modes require the user to
    specify the password to delete the file, rename the file, or to modify the file's attributes.

      If the correct password is supplied, or if password protection is disabled by the
    Directory Label, then access to the BDOS functions is the same as for a file that is
    not password protected.  In addition, the Search For First and Search For Next func-
    tions are not affected by file passwords.

    Table 2-5 lists the BDOS functions that test for password.

                    Table 2-5.  BDOS Functions That Test For Password
                     15.                                Open File
                     19.                                Delete File
                     23.                                Rename File
                     30.                                Set File Attributes
                     99.                                Truncate File
                     100.                               Set Directory Label
                     103.                               Write File XFCB



    2-22                                                                   LI DIGITAL RESEARCH'

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

         File passwords are eight bytes in length.  They are maintained in the XFCB Direc-
        tory Label in encrypted form.  To make a BDOS function call for a file that requires
        a password, a program must place the password in the first eight bytes of the current
        DMA, or specify it with the BDOS function, Set Default Password, prior to making
        the function call.
        Note: the BDOS keeps an assigned default password value until it is replaced with a
        new assigned value.

        2.3.8 File Date and Time Stamps
         The CP/M 3 File System uses a special type of directory entry called an SFCB to
        record date and time stamps for files.  When a directory has been initialized for date
        and time stamping, SFCBs reside in every fourth position of the directory.  Each SFCB
        maintains the date and time stamps for the previous three directory entries as shown
        in Figure 2-3.

                                                    FCB 1
                                                    FCB 2
                                                   FCB 3



                          STAMPS FOR        STAMPS FOR        STAMPS FOR
                    21        FCB 1             FCB 2             FCB 3              AN 068


                             Figure 2-3.  Directory Record with SFCB





        This figure shows a directory record that contains an SFCB.  Directory records consist

        of four directory entries, each 32 bytes long.  SFCBs always occupy the last position

        of a directory record.


          The SFCB directory item contains five fields.  The first field is one byte long and

        contains the value 21H.  This value identifies the SFCB in the directory.  The next

        three fields, the SFCB subfields, contain the date and time stamps for their corre-

        sponding FCB entries in the directory record.  These fields are 10 bytes long.  The last

        byte of the SFCB is reserved for system use.  The format of the SFCB subfields is

        shown in Table 2-6.


        1 DIGITAL RESEARCH'
                                                                                            2-23





                                                                                                   IN

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

                              Table 2-6.  SFCB Subfields Format
                  Offset in Bytes  I          SFCB Subfield Contents

                    0 - 3           Create or Access Date and Time Stamp field
                    4 - 7           Update Date and Time Stamp field
                      8             Password mode field
                      9             Reserved


       An SFCB subfield contains   valid information only if its corresponding FCB in the
    directory record is an extent  zero FCB. This FCB is a file's first directory entry. For
    password protected files, the  SFCB subfield also contains the password mode of the
    file.  This field is zero for files that are not password protected.  The BDOS Search and
    Search Next functions can be used to access SFCBs directly.  In addition, BDOS
    Function 102 can return the file date and time stamps and password mode for a
    specified file.  Refer to Section 3, function 102, for a description of the format of a
    date and time stamp field.

       CP/M 3 supports three types of file stamping: create, access, and update.  Create
    stamps record when the file was created, access stamps record when the file was last
    opened, and update stamps record the last time the file was modified.  Create and
    access stamps share the same field.  As a result, file access stamps overwrite any create
    stamps.

      The CP/M 3 utility, INITDIR, initializes a directory for date and time stamping by
    placing SFCBs in every fourth directory entry.  Date and time stamping is not sup-
    ported on disks that have not been initialized in this manner.  For initialized disks the
    disks' Directory Label determines the type of date and time stamping supported for
    files on the drive.  If a disk does not have a Directory Label, or if it is Read-Only, or
    if the disk's Directory Label does not specify date and time stamping, then date and
    time stamping for files is not performed.  Note that the Directory Label is also time
    stamped, but these stamps are not made in an SFCB.  Time stamp fields in the last
    eight bytes of the Directory Label record when it was created and last updated.
    Access stamping for Directory Labels is not supported.





    2-24                                                                   IC DIGITAL RESEARCH'

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

              The BDOS file system uses the CP/M 3 system date and time when it records a
              date and time stamp.  This value is maintained in a field in the System Control Block
              (SCB).  On CP/M 3 systems that support a hardware clock, the BIOS module directly
              updates the SCB system date and time field.  Otherwise, date and time stamps record
              the last initialized value for the system date and time.  The CP/M 3 DATE utility can
              be used to set the system date and time.

              2.3.9 Record Blocking and Deblocking
               Under CP/M 3, the logical record size for disk 1/0 is 128 bytes.  This is the basic
              unit of data transfer between the operating system and transient programs.  However,
              on disk, the record size is not restricted to 128 bytes.  These records, called physical
              records, can range from 128 bytes to 4K bytes in size.  Record blocking and deblock-
              ing is required on systems that support drives with physical record sizes larger than
              128 bytes.

               The process of building up physical records from 128 byte logical records is called
              record blocking.  This process is required in write operations.  The reverse process of
              breaking up physical records into their component 128 byte logical records is called
              record deblocking.  This process is required in read operations.  Under CP/M 3, record
              blocking and deblocking is normally performed by the BDOS.

               Record deblocking implies a read-ahead operation.  For example, if a transient
              program makes a BDOS function call to read a logical record that resides at the
              beginning of a physical record, the entire physical record is read into an internal
              buffer.  Subsequent BDOS read calls for the remaining logical records access the
              buffer instead of the disk.  Conversely, record blocking results in the postponement
              of physical write operations but only for data write operations.  For example, if a
              ransient program makes a BDOS write call, the logical record is placed in a buffer
              equal in size to the physical record size.  The write operation on the physical record
              t
              buffer is postponed until the buffer is needed in another 1/0 operation.  Note that
              under CP/M 3, directory write operations are never postponed.

               Postponing physical record write operations has implications for some applications
              programs.  For those programs that involve file updating, it is often critical to guar-
              antee that the state of the file on disk parallels the state of the file in memory after
              the update operation.  This is only an issue on systems where physical write opera-
              tions are postponed because of record blocking and deblocking.  If the system should
              crash while a physical buffer is pending, data would be lost.  To prevent this loss of
              data, the BDOS Flush Buffers function, function 48, can be called to force the write
              of any pending physical buffers.

               DIGITAL RESEARCH
                                                                                                  2-25

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

    Note: the CCP automatically discards all pending physical data buffers when it
    receives control following a system warm start.  However, the BDOS file system
    automatically makes a Flush Buffers call in the Close File function.  Thus, it is suffi-
    cient to close a file to ensure that all pending physical buffers for that file are written
    to the disk.

    2.3.10 Multi-Sector 1/0
      CP/M 3 can read or write multiple 128-byte records in a single BDOS function
    call.  This process, called multi-sector 1/0, is useful primarily in sequential read and
    write operations, particularly on drives with physical record sizes larger than 128
    bytes.  In a multi-sector 1/0 operation, the BDOS file system bypasses, when possible,
    all intermediate record buffering.  Data is transferred directly between the TPA and
    the drive.  In addition, the BDOS informs the BIOS when it is reading or writing
    multiple physical records in sequence on a drive.  The BIOS can use this information
    to further optimize the 1/0 operation resulting in even better performance.  Thus, the
    primary objective of multi-sector 1/0 is to improve sequential 1/0 performance.  The
    actual improvement obtained, however, depends on the hardware environment of the
    host system, and the implementation of the BIOS.

      The number of records that can be supported with multi-sector 1/0 ranges from 1
    to 128.  This value can be set by BDOS function 44, Set multi-sector Count.  The
    multi-sector count is set to one when a transient program begins execution.  However,
    the CP/M 3 LOADER module executes with the multi-sector Count set to 128 unless
    the available TPA space is less than 16K.  In addition, the CP/M 3 PIP utility also
    sets the multi-sector count to 128 when sufficient buffer space is available.  Note that
    the greatest potential performance increases are obtained when the multi-sector count
    is set to 128.  Of course, this requires a 16K buffer.

      The multi-sector count determines the number of operations to be performed by
    the following BDOS functions:

         o Sequential Read and Write functions
         o Random Read and Write functions including Write Random with Zero Fill

      If the multi-sector count is N, calling one of the above functions is equivalent to
    making N function calls.  If a multi-sector I/O operation is interrupted with an error
    such as reading unwritten data, the file system returns in register H the number of
    128-byte records successfully processed.




                                                                             EIOJ DIGITAL RESEARCH
    2-26
        CP/M 3 Prograiiimer's Guide                                    2.3 BDOS File System

        2.3.11 Disk Reset and Removable Media
          The BDOS functions, Disk Reset (function 13) and Reset Drive (function 37) allow
        a program to control when a disk's directory is to be reinitialized for file operations.
        This process of initializing a disk's directory is called logging-in the drive.  When
        CP/M 3 is cold started, all drives are in the reset state.  Subsequently, as drives are
        referenced, they are automatically logged-in by the file system.  Once logged-in, a
        drive remains in the logged-in state until it is reset by BDOS function 13 or 37.
        Following the reset operation, the drive is again automatically logged-in by the file
        system when it is next used.  Note that BDOS functions 13 and 37 have similar effects
        except that function 13 is directed to all drives on the system.  Any combination of
        drives can be reset with Function 37.

          Logging-in a drive consists of several steps.  The most important step is the initiali-
        zation of the drive's allocation vector.  The allocation vector records the allocation
        and deallocation of data blocks to files, as files are created, extended, deleted, and
        truncated, Another function performed during drive log-in is the initialization of the
        directory check-sum vector.  The file system uses the check-sum vector to detect media
        changes on a drive.  Note that permanent drives, which are drives that do not support
        media changes, might not have check-sum vectors.  If directory hashing has been
        specified for the drive, a BIOS and GENCPM option, the file system creates a hash
        table for the directory during log-in.

          The primary use of the drive reset functions is to prepare for a media change on a
        drive.  Subsequently, when the drive is accessed by a BDOS function call, the drive is
        automatically logged-in.  Resetting a drive has two important side effects.  First of all,
        any pending blocking/deblocking buffers on the reset drive are discarded.  Secondly,
        any data blocks that have been allocated to files that have not been closed are lost.
        An application program should close files, particularly files that have been written to,
        prior to resetting a drive.

           Although CP/M 3 automatically relogs in removable media when media changes
        are detected, the application program should still explicitly reset a drive before
        prompting the user to change disks.








           DIGITAL RESEARCH
                                                                                              2-27

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

    2.3.12 File Byte Counts
      Although the logical record size of CP/M 3 is restricted to 128 bytes, CP/M 3 does
    provide a mechanism to store and retrieve a byte count for a file.  This facility can
    identify the last byte of the last record of a file.  The BDOS Compute File Size
    function returns the random record number, plus 1, of the last record of a file.

      The BDOS Set File Attributes function can set a file's byte count.  Conversely, the
    Open function can return a file's byte count to the cr field of the FCB.  The BDOS
    Search and Search Next functions also return a file's byte count.  These functions
    return the byte count in the sl field of the FCB returned in the current DMA buffer
    (see BDOS Functions Returned 17 and 26).

      Note that the file system does not access or update the byte count value in file read
    or write operations.  However, the BDOS Make File function does set the byte count
    of a file to zero when it creates a file in the directory.

    2.3.13 BDOS Error Handling
      The BDOS file system responds to error situations in one of three ways:

        Method 1.             It returns to the calling program with return codes       in register
                              A3 H, and L identifying the error.

        Method 2.             It displays an error message on the console, and branches to
                              the BIOS warm start entry point, thereby terminating execu-
                              tion of the calling program.

        Method 3.             It displays an error message on the console, and returns to
                              the calling program as in method 1.

    The file system handles   the majority of errors it detects by method 1. Two examples
    of this kind of error are the file not found error for the open function and the reading
    unwritten data error for a read function.  More serious errors, such as disk I/O errors,
    are usually handled by method 2. Errors in this category, called physical and extended
    errors, can also be reported by methods 1 and 3 under program control.








                                                                                Yo DIGITAL RESEARCH
    2-28

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

         The BDOS Error Mode, which can exist in three states, determines how the file
        system handles physical and extended errors.  In the default state, the BDOS displays
        the error message, and terminates the calling program, method 2. In return error
        mode, the BDOS returns control to the calling program with the error identified in
        registers A, H, and L, method 1. In return and display mode, the BDOS returns
        control to the calling program with the error identified in registers A, H, and L, and
        also displays the error message at the console, method 3. While both return modes
        protect a program from termination because of a physical or extended error, the
        return and display mode also allows the calling program to take advantage of the
        built-in error reporting of the BDOS file system.  Physical and extended errors are
        displayed on the console in the following format:

            CP/M Error on d: error message
            BDOS function = nn File = filename.typ

        where d identifies the drive selected when the error condition is detected; error mes-
            identifies the error; nn is the BDOS function number, and filename.typ identifies
        sage I
        the file specified by the BDOS function.  If the BDOS function did not involve an
        FCB, the file information is omitted.  Note that the second line of the above error
        message is displayed only in the banked version of CP/M 3 if expanded error message
        reporting is requested in GENCPM.  It is not displayed in the nonbanked version of
        CP/M 3.

         The BDOS physical errors are identified by the following error messages:

            0 Disk 1/0
            m Invalid Drive
            0 Read-Only File
            m Read-Only Disk

        The Disk 1/0 error results from an error condition returned to the BDOS from the
        BIOS module.  The file system makes BIOS read and write calls to execute file-related
        BDOS calls.  If the BIOS read or write routine detects an error, it returns an error
        code to the BDOS resulting in this error.

          The Invalid Drive error also results from an error condition returned to the BDOS
        from the BIOS module.  The BDOS makes a BIOS Select Disk call prior to accessing
        a drive to perform a requested BDOS function.  If the BIOS does not support the
        selected disk, the BDOS returns an error code resulting in this error message.




          DIGITAL RESEARCH
                                                                                           2-29

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

     The Read-Only File error is returned when a program attempts to write to a file
   that is marked with the Read-Only attribute.  It is also returned to a program that
   attempts to write to a system file opened under user zero from a nonzero user
   number.  In addition, this error is returned when a program attempts to write to a
   file password protected in Write mode if the program does not supply the correct
   password.

     The Read-Only Disk error is returned when a program writes to a disk that is in
   read-only status.  A drive can be placed in read-only status explicitly with the BDOS
   Write Protect Disk function.

     The BDOS extended errors are identified by the following error messages:

        m Password Error
        0 File Exists
        m ? in Filename

     The File Password error is returned when the file password is not supplied, or
   when it is incorrect.  This error is reported only by the banked version of CP/M 3.

     The File Exists error is returned by the BDOS Make File and Rename File func-
   tions when the BDOS detects a conflict such as a duplicate filename and type.

     The ? in Filename error is returned when the BDOS detects a ? in the filename or
   type field of the passed FCB for the BDOS Rename File, Set File Attributes, Open
   File, Make File, and Truncate File functions.

     The following paragraphs describe the error return code conventions of the BDOS
   file system functions.  Most BDOS file system functions fall into three categories in
   regard to return codes: they return an Error Code, a Directory Code, or an Error
   Flag.  The error conventions of CP/M 3 are designed to allow programs written for
   earlier versions of CP/M to run without modification.

     The following BDOS functions return an Error Code in register A.

        20. Read Sequential
        21. Write Sequential
        33. Read Random
        34. Write Random
        40. Write Random w/Zero Fill


                                                                      K DIGITAL RESEARCHT@
   2-30

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

        The Error Code definitions for register A are shown in Table 2-7.

                             Table 2-7. Register A BDOS Error Codes
         Code                                            Meaning

          00                 Function successful
          255                Physical error : refer to register H
          01                 Reading unwritten data or no available directory space (Write
                             Sequential)
          02                 No available data block
          03                 Cannot close current extent
          04                 Seek to unwritten extent
          05                 No available directory space
          06                 Random record number out of range
          09                 Invalid FCB (previous BDOS close call returned an error code
                             and invalidated the FCB)
          10                 Media Changed (A media change was detected on the FCB's
                             drive after the FCB was opened)


        For BDOS read or write functions, the file system also sets register H when the
        returned Error Code is a value other than zero or 255.  In this case, register H
        contains the number of 128-byte records successfully read or written before the error
        was encountered.  Note that register H can contain only a nonzero value if the calling
        program has set the BDOS Multi-Sector Count to a value other than one; otherwise
        register H is set to zero.  On successful functions, Error Code = 0, register H is also
        set to zero.  If the Error Code equals 255, register H contains a physical error code
        (see Table 2-11).








        1-@D DL(,ITAL RESEARCH"'
                                                                                             2-31

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

     The following BDOS functions return a Directory Code in register A:

           15. Open File
           16. Close File
           17. Search For First
           18. Search For Next
           19. Delete File
           22. Make File
           23. Rename File
           30. Set File Attributes
           35. Compute File Size
           99. Truncate File
          100. Set Directory Label
          102.  Read File Date Stamps and Password Mode
          103.  Write File XFCB

          - This function is supported in the DIRLBL.RSX in the nonbanked version of
           CP/M 3.
          - This function is supported only in the banked version of CP/M 3.

   The Directory Code definitions for register A are shown in Table 2-8.

                        Table 2-8.  BDOS Directory Codes
                       Code                 Meaning

                     00 - 03:          successful function
                     255               unsuccessful function


   With the exception of the BDOS search functions, all functions in this category
   return with the directory code set to zero on successful returns.  However, for the
   search functions, a successful Directory Code also identifies the relative starting posi-
   tion of the directory entry in the calling program's current DMA buffer.








                                                               DIGITAL RESEAPCH'
   2-32

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

          If the Set BDOS Error Mode function is used to place the BDOS in return error
         mode, the following functions return an Error Flag on physical errors:

              14. Select Disk
              46. Get Disk Free Space
              48. Flush Buffers
              98. Free Blocks
             101.  Return Directory Label Data

         The Error Flag definition for register A is shown in Table 2-9.

                                    Table 2-9.  BDOS Error Flags
                                Code   I             Meaning

                             00         successful function
                             255        physical error : refer to register H


           The BDOS returns nonzero values in register H to identify a physical or extended
         error if the BDOS Error Mode is in one of the return modes.  Except for functions
         that return a Directory Code, register A equal to 255 indicates that register H iden-
         tifies the physical or extended error.  For functions that return a Directory Code, if
         register A equals 255, and register H is not equal to zero, register H identifies the
         physical or extended error.  Table 2-10 shows the physical and extended error codes
         returned in register H.








           DIGITAL RESEARCH
                                                                                             2-33

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

                   Table 2-10.  BDOS Physical and Extended Errors
                    Code                          Meaning

                    00   -            no error, or not a register H error
                    01 -              Disk 1/0 error
                    02   -            Read-Only Disk
                    03   -            Read-Only File or File Opened
                                      under user zero from another user
                                      number or file password protected
                                      in write mode and correct pass-
                                      word not specified.
                    04   -            Invalid Drive : drive select error
                    07   -            Password Error
                    08   -            File Exists
                    09   -            ? in Filename


    The following two   functions represent a special case because they return an address
  in registers H and L.

       27. Get Addr(Alloc)
       31. Get Addr(Disk Parms)

  When the BDOS is in return error mode, and it detects a physical error for these
  functions, it returns to the calling program with registers A, H, and L all set to 255.
  Otherwise, they return no error code.

  2.4 Page Zero Initialization

    Page Zero is the region of memory located from OOOOH to OOFFH.  This region
  contains several segments of code and data that are used by transient programs while
  running under CP/M 3. The code and data areas are shown in Table 2-11 for reference.








                                                                     K DIGITAL RESEARCH'@
  2-34

          CP/M 3 Programmer's Guide                                  2.4 Page Zero Initializatioil

                                      Table 2-11. Page Zero Areas
                 Location                                    Contents
            From          TO
           OOOOH - 0002H         Contains a jump instruction to the BIOS warm start entry
                                 point at BIOS - base + 3. The address at location OOOIH can
                                 also be used to make direct BIOS calls to the BIOS console
                                 status, console input, console output, and list output primitive
                                 functions.

           0003H - 0004H         (Reserved)

           0005H - 0007H         Contains a jump instruction to the BDOS, the LOADER, or
                                 to the most recently added RSX, and serves two purposes:
                                 JMP 0005H provides the primary entry point        to the BDOS,
                                 and LHLD 0006H places the address field of the jump
                                 instruction in the HL register pair. This value,   minus one, is
                                 the highest address of memory available to         the transient
                                 program.

           0008H - 003AH         Reserved interrupt locations for Restarts 1 - 7

           003BH - 004FH         (Not currently used - reserved)

           0050H                 Identifies the drive from which the transient program was load-
                                 ed. A value of one to sixteen identifies drives A through P.

           0051H - 0052H         Contains the address of the password field of the first command-
                                   'I operand in the default DMA buffer beginning at 0080H.
                                 tal          I
                                 The CCP sets this field to zero if no password for the first
                                 command-tail operand is specified.

           0053H                 Contains the length of the password field for the first command-
                                 tail operand.  The CCP also sets this field to zero if no password
                                 for the first command tail is specified.

           0054H         0055H   Contains the address of the password field of the second corn-
                                 mand-tail operand in the default DMA buffer beginning at
                                 0080H.  The CCP sets this field to zero if no password for the
                                 second command-tail operand is specified.

          Fi-el 1)1(.'[ ['AL RLSLARC@H
                                                                                               2-35

   2.4 Page Zero Initialization                              CP/M 3 Programmer's Guide

                                  Table 2-11. (continued)

          Location -T                                 Contents
     From           TO
     005 6H                Contains the length of the password field for the second corn-
                           mand-tail operand.  The CCP also sets this field to zero if no
                           password for the second command tail is specified.

     0057H - 005BH         (Not currently used - reserved)

     005CH - 007BH         Default File Control Block, FCB, area 1 initialized by the CCP
                           from the first command-tail operand of the command line, if
                           it exists.

     006CH - 007BH         Default File Control Block, FCB, area 2 initialized by the CCP
                           from the second command-tail operand of the command line,
                           if it exists.

                           Note: this area overlays the last 16 bytes of default FCB
                           area 1. To use the information in this area, a transient program
                           must copy it to another location before using FCB area 1.

     007CH                 Current record position of default FCB area 1. This field is used
                           with default FCB area 1 in sequential record processing.

     007DH - 007FH         Optional default random record position. This field is an exten-
                           sion of default FCB area 1 used in random record processing.

     0080H - OOFFH         Default 128-byte disk buffer. This buffer is also filled with the
                           command tail when the CCP loads a transient program.








                                                                             DIGITAL RESEARCH'
   2-36

        CP/M 3 Programmer's Guide                                    2.4 Page Zero Initialization

          The CCP initializes Page Zero prior to initiating a transient program.  The fields at
        0050H and above are initialized from the command line invoking the transient pro-
        gram.  The command line format was described in detail in Section 1.6.2. To sum-
        marize, a command line usually takes the form:

             <command> <command tail>

        where

             <command>             = >    <file Spec>

             <command tail>        = >    (no command tail)
                                   = >    <file Spec>
                                   = >    <file spec><delimiter><file spec>

             <file spec>           = >    fd:lfilenamef.typel f;passwordl

        The CCP initializes the command drive field at 0050H to the drive index, A = 1,
        P = 16, of the drive from which the transient program was loaded.

          The default FCB at 005CH is defined if a command tail is entered.  Otherwise, the
        fields at 005CH, 0068H to 006BH are set to binary zeros, the fields from 005DH to
        0067H are set to blanks.  The fields at 0051H through 0053H are set if a password
        is specified for the first <file Spec> of the command tail.  If not, these fields are set to
        zero.

          The default FCB at 006CH is defined if a second <file spec> exists in the com-
        mand tail.  Otherwise, the fields at 006CH, 0078H to 007BH are set to binary zeros,
        the fields from 005DH to 0067H are set to blanks.  The fields at 0054H through
        0056H are set if a password is specified for the second <file spec> of the command
        tail.  If not, these fields are set to zero.

          Transient programs often use the default FCB at 005CH for file operations.  This
        FCB may even be used for random file access because the three bytes starting at
        007DH are available for this purpose.  However, a transient program must copy the
        contents of the default FCB at 006CH to another area before using the default FCB
        at 005CH, because an open operation for the default FCB at 005CH overwrites the
        FCB data at 006CH.





          DIGITAL RESEARCH'
                                                                                                 2-37

                                                             CP/M 3 Programm              1
    2.4   Page Zero Initialization                                                cr s Guide

      The default DMA address for transient programs is 0080H.  The CCP also initial-
    izes this area to contain the command tall of the command line.  The first position
    contains the number of characters in the command line, followed by the command
    line characters.  The character following the last command tail character is set to
    binary zero.  The command line characters are preceded by a leading blank and are
    translated to ASCII upper-case.  Because the 128-byte region beginning at 0080H is
    the default DMAI, the BDOS file system moves 128-byte records to this area with
    read operations and accesses 128-byte records from this area with write operations.
    The transient program must extract the command tail information from this buffer
    before performing file operations unless it explicitly changes the DMA address with
    the BDOS Set DMA Address function.

      The Page Zero fields of 0051H through OOS6H locate the password fields of the
    first two file specifications in the command tail if they exist.  These fields are provided
    so that transient programs are not required to parse the command tail for password
    fields.  However, the transient program must save the password, or change the DMA
    address before performing file operations.

      The following example illustrates the initialization of the command line fields of
    Page Zero.  Assuming the following command line is typed at the console:

        D '.'- A : PROGRAM B : FILE t TYPE ; PASS C ;FILE.  TYPE ; PASS14ORD

    A hexadecimal dump of 0050H to 0OA5H would show the Page Zero initialization
    performed by the CCP.

    005OH:  01 OD  00 04 9D  00 08 00  00 00 00 00 02 46 49 4C FIL
    006OH:  a5 20  20 20 20  54 59 50  00 00 00 00 03 46 49 4C    E TYP FIL
    007OH:  45 20  20 20 20  54 59 50  00 00 00 00 00 00   00 00  E TYP too#
    OOSOH:  24 20  42 3A 46  49 4C 45  2E 54 59 50 3B 50   41 53  . BIFILE.TYP;PAS
    009OH:  53 20  43 3A 46  49 4C 45  2E 54 59 50 3B 50   41 53  S C:FILE.TYPIPAS
    OOAOH:  53 57  4F 52 44  00                                   SWORD.

                                        End of Section 2








                                                                      - :Cc 1)1(,I-I-AL RESEARCH"'
    2-38

                                          Section 3

                             BDOS Function Calls



          This section describes each CP/M 3 system function, including the parameters a
       program must pass when calling the function, and the values the function returns to
       the program.  The functions are arranged numerically for easy reference.  You should
       be familiar with the BDOS calling conventions and other concepts presented in Section.,
       before referencing this section.


                              BDOS FUNCTION 0: SYSTEM RESET

                       Entry Parameters:
                             Register C: OOH


          The System Reset function terminates the calling program and returns control to
       the CCP via a warm start sequence (see Section 1.3.2). Calling this function has the
       same effect as a 'ump to location OOOOH of Page Zero.
                        i

          Note that the disk subsystem is not reset by System Reset under CP/M 3. The
       calling program can pass a return code to the CCP by calling Function 108, Get/Set
       Program Return Code, prior to making a System Reset call or jumping to location
       OOOOH.








       @l@ 1)1(;I-FAI- RLSLAR(:H"'
                                                                                             3-1


                                                                                                  IN

                                                                                 r's Guide
   3 BDOS Calls: Function I                                 CP/M 3 Programme






                        BDOS FUNCTION 1: CONSOLE INPUT

                  Entry Parameters:
                         Register C: 01H

                  Returned Value:



     The Console Input function reads the next character from the logical console,
    CONIN:, to register A. Graphic characters, along with carriage return, line-feed, and
    backspace, CTRL-H, are echoed to the console.  Tab characters, CTR-L-1, are expanded
    in columns of 8 characters.  CTRL-S, CTRL-Q, and CTRL-P are normally intercepted
    as described below.  All other non-graphic characters are returned in register A but
    are not echoed to the console.

      When the Console Mode is in the default state (see Section 2.2.1), Function 1
    intercepts the stop scroll, CTRL-S, start scroll, CTRL-Q, and start/stop printer echo,
    CTRL-P, characters.  Any characters that are typed following a CTRL-S and preced-
    ing a CTRL-Q are also intercepted.  However, if start/stop scroll has been disabled
    by the Console Mode, the CTRL-S, CTRL-Q, and CTRL-P characters are not inter-
    cepted.  Instead, they are returned in register A, but are not echoed to the console.

      If printer echo has been invoked, all characters that are echoed to the console are
    also sent to the list device, LST:.

      Function 1 does not return control to the calling program until a non-intercepted
    character is typed, thus suspending execution if a character is not ready.








                                                                          ea@ DIGITAL RESEARCH'
    3-2

      CP/M 3 Programmer's Guide                    3 BDOS Calls: Function 2



                      BDOS FUNCTION 2: CONSOLE OUTPUT

                   Entry Parameters:
                       Registers C: 02H
                                E: ASCII Character


        The Console Output function sends the ASCII character from register E to the
      logical console device, CONOUT:.  When the Console Mode is in the default state
      (see Section 2.2.1), Function 2 expands tab characters, CTRL-1, in columns of 8
      characters, checks for stop scroll, CTRL-S, start scroll, CTRL-Q, and echoes charac-
      ters to the logical list device, LST:, if printer echo, CTRL-P, has been invoked.








        DIGITAL RESEARCH'                                                 3-3

   3 BDOS Calls: Function 3                       CP/M 3 Programmer's Guide



                   BDOS FUNCTION 3: AUXILIARY INPUT

               Entry Parameters:
                     Register C: 03H

               Returned Value:
                     Register A: ASCII Character


    The Auxiliary Input function reads the next character from the logical auxiliary
   input device, AUXIN:, into register A. Control does not return to the calling program
     'I the character is read.
   unti








                                                          B DIGITAL RESEARCH'@"
   3-4

      CP/M 3 Programiner's Guide                       3 BDOS Calls: Function 4



                       BDOS FUNCTION 4: AUXILIARY OUTPUT

                    Entry Parameters:
                         Registers C: 04H
                                   E: ASCII Character


        The Auxiliary Output function sends the ASCII character from register E to the
      logical auxiliary output device, AUXOUT:.








      -iol DIGI'FAL RESEAR(H                                                  3-5
                                                                                   AN
   3 BDOS Calls: Function 5                          CP/M 3 Programmer's Guide


                       BDOS FUNCTION 5: LIST OUTPUT

                Entry Parameters:
                      Registers C: 05H
                                E: ASCII Character
          I                                                             i          I

     The List Output function sends the ASCII character in register E to the logical list
   device, LST:.








                                                                  DIGITAL RESEARCH@
    3-6
