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



                         BDOS FUNCTION 6: DIRECT CONSOLE 1/0

                      Entry Parameters:
                            Registers C: 06H
                                       E: OFFH (input/status) or
                                                  OFEH (status) or
                                                  OFDH (input) or
                                                  char (output)

                      Returned Value:
                             Register A: char or status (no value)


          CP/M 3 supports direct 1/0 to the logical console, CONIN:, for those specialized
       applications where unadorned console input and output is required.  Use Direct Con-
       sole 1/0 carefully because it bypasses all the normal control character functions.
       Programs that perform direct 1/0 through the BIOS under previous releases of CP/M
       should be changed to use direct 1/0 so that they can be fully supported under future
       releases of MP/M and CP/M.

          A program calls Function 6 by passing one of four different values in register E.
       The values and their meanings are summarized in Table 3-1.








         DIGITAL RESEARCH
                                                                                          3-7

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

                         Table 3-1.  Function 6 Entry Parameters
     Register
     E value                                      Meaning

     OFFH             Console input/status command returns an input character; if no
                      character is ready, a value of zero is returned.

     OFEH             Console status command (On return, register A contains 00 if no
                      character is ready; otherwise it contains FFH.)

     OFDH             Console input command, returns an input character; this func-
                      tion will suspend the calling process until a character is ready.

     ASCII            Function 6 assumes that register E contains a valid ASCII char-
     character        acter and sends it to the console.








   3-8                                                                    DIGITAL RESEARCH'

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



                     BDOS FUNCTION 7: AUXILIARY INPUT STATUS

                     Entry Parameters:
                           Register C: 07H

                     Returned Value:
                           Register A: Auxiliary Input Status


         The Auxiliary Input Status function returns the value OFFH in register A if a
       character is ready for input from the logical auxiliary input device, AUXIN:.  If no
       character is ready for input, the value OOH is returned.








         DIGITAL RESE.ARCH,
                                                                                 3-9
   3 BDOS Calls: Function 8                          CP/M 3 Programmer's Guide



               BDOS FUNCTION 8: AUXILIARY OUTPUT STATUS

                Entry Parameters:
                      Register C: 08H

                Returned Value:
                      Register A: Auxiliary Output Status


     The Auxiliary Output Status function returns the value OFFH in register A if the
   logical auxiliary output device, AUXOUT:, is ready to accept a character for output.
   If the device is not ready for output, the value OOH is returned.








    3-10                                                            DIGITAL RESEARCH'

       CPIM I   Programmer's Guide                            3 BDOS Calls: Function 9

                             BDOS FUNCTION 9: PRINT STRING

                      Entry Parameters:
                            Registers C: 09H
                                     DE: String Address


         The Print String function sends the character string addressed by register pair DE
       to the logical console, CONOLJT:, until it encounters a delimiter in the string.  Usu-
       ally the delimiter is a dollar sign, $, but it can be changed to any other value by
       Function 110, Get/Set Output Delimiter.  If the Console Mode is in the default state
       (see Section 2.2.1), Function 9 expands tab characters, CTRL-1, in columns of 8
       characters.  It also checks for stop scroll, CTRL-S, start scroll, CTRL-Q, and echoes
       to the logical list device, LST:, if printer echo, CTRL-P, has been invoked.








         DICITAL RESEARCH'                                                               3-11

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




                    BDOS FUNCTION 10: READ CONSOLE BUFFER


                    Entry Parameters:
                          Registers C: OAH
                                    DE: Buffer Address

                    Returned Value:
                          Console Characters in Buffer



      The Read Console Buffer function reads a line of edited console input from the
    logical console, CONIN:, to a buffer that register pair DE addresses.  It terminates
    input and returns to the calling program when it encounters a return, CTRL-M, or a
    line feed, CTRL-J, character.  Function 10 also discards all input characters after the
    input buffer is filled.  In addition, it outputs a bell character, CTRL-G, to the console
    when it discards a character to signal the user that the buffer is full.  The input buffer
    addressed by DE has the following format:

         DE: +0 +1 +2 +3 +4 +5 +6 +7 +8                             +n

              mx  I nc I cl I c2 I c3 I c4 I c5 I c6 I c7


    where mx is the maximum number of characters which the buffer holds, and nc is
    the number of characters placed in the buffer.  The characters entered by the operator
    follow the nc value.  The value mx must be set prior to making a Function 10 call
    and may range in value from 1 to 2SS.  Setting mx to zero is equivalent to setting mx
    to one.  The value nc is returned to the calling program and may range from zero to
    mx. If nc < mx, then uninitialized positions follow the last character, denoted by ??
    in the figure.  Note that a terminating return or line feed character is not placed in
    the buffer and not included in the count nc.

       If register pair DE is set to zero, Function 10 assumes that an initialized input
    buffer is located at the current DMA address (see Function 26, Set DMA Address).
    This allows a program to put a string on the screen for the user to edit.  To initialize
    the input buffer, set characters cl through cn to the initial value followed by a binary
    zero terminator.


    3-12                                                                      DIGITAL RESEARCH,

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


           When a program calls Function 10 with an initialized buffer, Function 10 operates
            if
         as 1 the user had typed in the string.  When Function 10 encounters the binary zero
         terminator, it accepts input from the console.  At this point, the user can edit the
         initialized string or accept it as it is by pressing the RETURN key.  However, if the
         initialized string contains a return, CTRL-M, or a linefeed, CTRL-J, character, Func-
         tion 10 returns to the calling program without giving the user the opportunity to edit
         the string.

           The level of console editing supported by Function 10 differs for the banked and
         nonbanked versions of CP/M 3. Refer to the CPIM Plus (CPIM Version 3) Operating
         System User's Guide for a detailed description of console editing.  In the nonbanked
         version, Function 10 recognizes the edit control characters summarized in Table 3-2.


                      Table 3-2.  Edit Control Characters (Nonbanked CP/M 3)

           Character -T                            Edit Control Function

           rub/de]           Removes and echoes the last character; GENCPM can change
                             this function to CTRL-H

           CTRL-C            Reboots when at the beginning of line; the Console Mode can
                             disable this function

           CTRL-E            Causes physical end of line

           CTRL-H            Backspaces one character position; GENCPM can change this
                             function to rub/del

           CTRL-J            (Line-feed) terminates input line

           CTRL-M            (Return) terminates input line

           CTRL-P            Echoes console output to the list device

           CTRL-R            Retypes the current line after new line

           CTRL-U            Removes current line after new line

           CTRL-X            Backspaces to beginning of current line




           DICITAL RESEARCH                                                                  3-13



                                                                                                    AM

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

     The banked version of CP/M 3 expands upon the          editing provided in the non-
    banked version. The functionality of the two versions    is similar when the cursor is
    positioned at the end of the line.  However, in the banked version, the user can move
    the cursor anywhere in the current line, insert characters, delete characters, and
    perform other editing functions.  In addition, the banked version saves the previous
    command line; it can be recalled when the current line is empty.  Table 3-3 summa-
    rizes the edit control characters supported by Function 10 in the banked version of
    CP/M 3.

                  Table 3-3.  Edit Control Characters (Banked CP/M 3)
     Character                               Edit Control Function

     rub/del            Removes and echoes the last character if at the end of the line;
                        otherwise deletes the character to the left of the current cursor
                        position; GENCPM can change this function to CTRL-H.

     CTRL-A             Moves cursor one character to the left.

     CTRL-B             Moves cursor to the beginning of the line when not at the begin-
                        ning; otherwise moves cursor to the end of the line.

     CTRL-C             Reboots when at the beginning of line; the Console Mode can
                        disable this function.

     CTRL-E             Causes physical end-of-line; if the cursor is positioned in the
                        middle of a line, the characters at and to the right of the cursor
                        are displayed on the next line.

     CTRL-F             Moves cursor one character to the right.

     CTRL-G             Deletes the character at the current cursor position when in the
                        middle of the line; has no effect when the cursor is at the end of
                        the line.

     CTRL-H             Backspaces one character position when positioned at the end
                        of the line,; otherwise deletes the character to the left of the
                        cursor; GENCPM can change this function to rub/del.




                                                                            DIGITAL RESEARCH
    3-14
           CP/M 3 Programmer's Guide                               3 BDOS Calls: Function 10

                                           Table 3-3. (continued)
            Character                                Edit Control Function
            CTRL-J             (Line-feed) terminates input; the cursor can be positioned any-
                               where in the line; the entire input line is accepted; sets the pre-
                               vious line buffer to the input line.

            CTRL-K             Deletes all characters to the right of the cursor along with the
                               character at the cursor.

            CTRL-M             (Return) terminates input; the cursor can be positioned any-
                               where in the line; the entire input line is accepted; sets the pre-
                               vious line buffer to the input line.

            CTRL-P             Echoes console output to the list device.

            CTRL-R             Retypes the characters to the left of the cursor on the new line.

            CTRL-U             Updates the previous line buffer to contain the characters to the
                               left of the cursor; deletes current line, and advances to new line.

            CTRL-W             Recalls previous line if current line is empty; otherwise moves
                               cursor to end-of-line.

            CTRL-X             Deletes all characters to the left of the cursor.


           For banked systems, Function 10 uses the console width field defined in the System
           Control Block.  If the console width is exceeded when the cursor is positioned at the
           end of the line, Function 10 automatically advances to the next line.  The beginning
           of the line can be edited by entering a CTRL-R.

             When a character is typed while the cursor is positioned in the middle of the line,
           the typed character is inserted into the line.  Characters at and to the right of the
           cursor are shifted to the right.  If the console width is exceeded, the characters disap-
           pear off the right of the screen.  However, these characters are not lost.  They reappear
           if characters are deleted out of the line, or if a CTRL-E is typed.






             DIGITAL RESEARCH'
                                                                                                 3-15

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



                   BDOS FUNCTION 11: GET CONSOLE STATUS

                  Entry Parameters:
                        Register C: OBH

                  Returned Value:
                        Register A: Console Status


     The Get Console Status function checks to see if a character has been typed at
   the logical console, CONIN:.  If the Console Mode is in the default state (see
   Section 2.2.1), Function 11 returns the value 01H in register A when a character is
   ready.  If a character is not ready, it returns a value of OOH.

     If the Console Mode is in CTRL-C Only Status mode, Function 11 returns the
   value 01H in register A only if a CTRL-C has been typed at the console.








                                                                      Li@o DIGITAL RESEARCH'
   3-16
      CP/M 3 Programmer's Guide                     3 BDOS Calls: Function 12



                 BDOS FUNCTION 12: RETURN VERSION NUMBER

                   Entry Parameters:
                        Register C: OCH

                   Returned Value:
                       Register HL: Version Number


        The Return Version Number function provides information that allows version
      independent programming.  It returns a two-byte value in register pair HL: H con-
      tains OOH for CP/M and L contains 31H, the BDOS file system version number.
      Function 12 is useful for writing applications programs that must run on multiple
      versions of CP/M and MP/M.








       DIGITAL RESEARCH'
                                                                           3-17
    3 BDOS Calls: Function 13                              CP/M 3 Programmer's Guide



                      BDOS FUNCTION 13: RESET DISK SYSTEM

                   Entry Parameters:
                         Register C: ODH


      The Reset Disk System function restores the file system to a reset state where all
    the disk drives are set to read-write (see Functions 28 and 29), the default disk is set
    to drive A, and the default DMA address is reset to 0080H.  This function can be
    used, for example, by an application program that requires disk changes during
    operation.  Function 37, Reset Drive, can also be used for this purpose.








                                                                        io'DIGITAL RESEARCH
    3-18
        CP/M 3 Programmer's Guide                                 3 BDOS Calls: Function 14



                                 BDOS FUNCTION 14: SELECT DISK

                         Entry Parameters:
                               Registers C: OEH

                         Returned Value:   E: Selected Disk

                               Registers A: Error Flag
                                           H: Physical Error


            The Select Disk function designates the disk drive named in register E as the
          default disk for subsequent BDOS file operations.  Register E is set to 0 for drive A,
          1 for drive B, and so on through 15 for drive P in a full 16-drive system.  In addition,
          Function 14 logs in the designated drive if it is currently in the reset state.  Logging-
          in a drive activates the drive's directory until the next disk system reset or drive reset
          operation.

            FCBs that specify drive code zero (dr = OOH) automatically reference the currently
          selected default drive.  FCBs with drive code values between 1 and 16, however,
          gnore the selected default drive and directly reference drives A through P.

            Upon return, register A contains a zero if the select operation was successful.  If a
          physical error was encountered, the select function performs different actions depend-
          ing on the BDOS error mode (see Function 45).  If the BDOS error mode is in the
          'default mode, a message identifying the error is displayed at the console, and the
          calling program is terminated.  Otherwise, the select function returns to the calling
          program with register A set to OFFH and register H set to one of the following
          physical error codes:

               01   Disk 1/0 Error
               04   Invalid drive







            DIGITAL RESEARCH,
                                                                                                ,3-19

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



                            BDOS FUNCTION 15: OPEN FILE

                    Entry Parameters:
                          Registers C: OFH
                                    DE: FCB Address

                    Returned Value:
                          Registers A: Directory Code
                                     H: Physical or Extended Error


      The Open File function activates the FCB for a file that exists in the disk directory
    under the currently active user number or user zero.  The calling program passes the
    address of the FCB in register pair DE, with byte 0 of the FCB specifying the drive,
    bytes 1 through 11 specifying the filename and filetype, and byte 12 specifying the
    extent.  Usually, byte 12 of the FCB is initialized to zero.

      If the file is password protected in Read mode, the correct password must be
    placed in the first eight bytes of the current DMA, or have been previously estab-
    lished as the default password (see Function 106).  If the current record field of the
    FCB, cr, is set to OFFH, Function 15 returns the byte count of the last record of the
    file in the cr field.  You can set the last record byte count for a file with Function 30,
    Set File Attributes.  Note that the current record field of the FCB, cr, must be zeroed
    by the calling program before beginning read or write operations if the file is to be
    accessed sequentially from the first record.

      If the current user is non-zero, and the file to be opened does not exist under the
    current user number, the open function searches user zero for the file.  If the file exists
    under user zero, and has the system attribute, t2', set, the file is opened under user
    zero.  Write operations are not supported for a file that is opened under user zero in
    this manner.








                                                                             [16A DIGITAL RESEARCH
    3-20
        CP/M 3 Programmer's Guide                                  3 BDOS Calls: Function 15

           If the open operation is successful, the user's FCB is activated for read and write
         operations.  The relevant directory information is copied from the matching directory
         FCB into bytes dO through dn of the FCB.  If the file is opened under user zero when
         the current user number is not zero, interface attribute f8' is set to one in the user's
         FCB.  In addition', if the referenced file is password protected in Write mode, and the
         correct password was not passed in the DMA, or did not match the default pass-
         word, interface attribute f7' is set to one.  Write operations are not supported for an
         activated FCB if interface attribute f7' or f8' is true.

           When the open operation is successful, the open function also makes an Access
         date and time stamp for the opened file when the following conditions are satisfied:
         the referenced drive has a directory label that requests Access date and time stamp-
         ing, and the FCB extent number field is zero.

           Upon return, the Open File function returns a directory code in register A with the
         value OOH if the open was successful, or FFH, 255 decimal, if the file was not found.
         Register H is set to zero in both of these cases.  If a physical or extended error was
         encountered, the Open File function performs different actions depending on the
         BDOS error mode (see Function 45).  If the BDOS error mode is in the default mode,
         a message identifying the error is displayed at the console and the program is termi-
         nated.  Otherwise, the Open File function returns to the calling program with register
         A set to OFFH, and register H set to one of the following physical or extended error
         codes:

              01 : Disk 1/0 Error
              04 : Invalid drive error
              07 : File password error
              09 : ? in the FCB filename or filetype field








           DIGITAL RESEARCH'
                                                                                                 3-21

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



                           BDOS FUNCTION 16: CLOSE FILE

                  Entry Parameters:
                        Registers C: 10H
                                  DE: FCB Address

                  Returned Value:
                        Registers A: Directory Code
                                    H: Physical or Extended Error


     The Close File function performs the inverse of the Open File function.  The calling
    program passes the address of an FCB in register pair DE.  The referenced FCB must
    have been previously activated by a successful Open or Make function call (see
    Functions 15 and 22).  Interface attribute f5' specifies how the file is to be closed as
    shown below:

        f5' = 0 - Permanent close (default mode)
        f5' = 1 - Partial close

    A permanent close operation indicates that the program has completed file operations
    on the file.  A partial close operation updates the directory, but indicates that the file
    is to be maintained in the open state.

     If the referenced FCB contains new information because of write operations to the
    FCB, the close function permanently records the new information in the referenced
    disk directory.  Note that the FCB does not contain new information, and the direc-
    tory update step is bypassed if only read or update operations have been made to the
    referenced FCB.








                                                                          h DIGITAL RESEARCH
    3-22

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

          Upon return, the close function returns a directory code in register A with the
        value OOH if the close was successful,, or FFH, 255 Decimal, if the file was not found.
        Register H is set to zero in both of these cases.  If a physical or extended error is
        encountered, the close function performs different actions depending on the BDOS
        error mode (see Function 45).  If the BDOS error mode is in the default mode, a
                  identifying the error is displayed at the console, and the calling program is
        message I
        terminated.  Otherwise, the close function returns to the calling program with register
        A set to OFFH and register H set to one of the following physical error codes:

             01   Disk 1/0 error
             02   Read/only disk
             04   Invalid drive error








          DIGITAL RESEARCH'
                                                                                             3-23


                                                                                                  AN

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



                      BDOS FUNCTION 17: SEARCH FOR FIRST

                  Entry Parameters:
                        Registers C: 11H
                                  DE: FCB Address

                  Returned Value:
                        Registers A: Directory Code
                                    H: Physical Error


     The Search For First function scans the directory for a match with the FCB addressed
   by register pair DE.  Two types of searches can be performed.  For standard searches,
   the calling program initializes bytes 0 through 12 of the referenced FCB, with byte 0
   specifying the drive directory to be searched, bytes 1 through 11 specifying the file or
   files to be searched for,, and byte 12 specifying the extent.  Usually byte 12 is set to
   zero.  An ASCII question mark, 63 decimal, 3F hex, in any of the bytes 1 through 12
   matches all entries on the directory in the corresponding position.  This facility, called
   ambiguous reference, can be used to search for multiple files on the directory.  When
   called in the standard mode, the Search function scans for the first file entry in the
   specified directory that matches the FCB, and belongs to the current user number.

     The Search For First function also initializes the Search For Next function.  After
   the Search function has located the first directory entry matching the referenced FCB,
   the Search For Next function can be called repeatedly to locate all remaining match-
   ing entries.  In terms of execution sequence, however, the Search For Next call must
   either follow a Search For First or Search For Next call with no other intervening
   BDOS disk-related function calls.

     If byte 0 of the referenced FCB is set to a question mark, the Search function
   ignores the remainder of the referenced FCB, and locates the first directory entry
   residing on the current default drive.  All remaining directory entries can be located
   by making multiple Search For Next calls.  This type of search operation is not
   usually made by application programs, but it does provide complete flexibility to
   scan all current directory values.  Note that this type of search operation must be
   performed to access a drive's directory label (see Section 2.3.6).


                                                                           @JDIGITAL RESEARCH'
   3-24

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

          Upon return, the Search function returns a Directory Code in register A with the
        value 0 to 3 if the search is successful, or OFFH, 255 Decimal, if a matching directory
        entry is not found.  Register H is set to zero in both of these cases.  For successful
        searches, the current DMA is also filled with the directory record containing the
        matching entry, and the relative starting position is A * 32 (that is, rotate the A
        register left 5 bits, or ADD A five times).  Although it is not usually required for
        application programs, the directory information can be extracted from the buffer at
        this position.

          If the directory has been initialized for date and time stamping by INITDIR, then
        an SFCB resides in every fourth directory entry, and successful Directory Codes are
        restricted to the values 0 to 2. For successful searches, if the matching directory
        record is an extent zero entry, and if an SFCB resides at offset 96 within the current
        DMA, contents of (DMA Address + 96) = 21H, the SFCB contains the date and
        time stamp information, and password mode for the file.  This information is located
        at the relative starting position of 97 + (A * 10) within the current DMA in the
        following format:

            0 - 3   Create or Access Date and Time Stamp Field
            4 - 7   Update Date and Time Stamp Field
            8 :     Password Mode Field

          (Refer to Section 2.3.8 for more information on SFCBS.)

          If a physical error is encountered, the Search function performs different actions
        depending on the BDOS error mode (see Function 45).  If the BDOS error mode is in
        the default mode, a message identifying the error is displayed at the console, and the
        calling program is terminated.  Otherwise, the Search function returns to the calling
        program with register A set to OFFH, and register H set to one of the following
        physical error codes:

            01   Disk 1/0 error
            04    Invalid drive error








        @l@ DIGITAL RESEARCH@
                                                                                             3-25

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



                  BDOS FUNCTION 18: SEARCH FOR NEXT


               Entry Parameters:
                     Register C: 12H

               Returned Value:
                    Registers A: Directory Code
                             H: Physical Error



    The Search For Next function is identical to the Search For First function, except
   that the directory scan continues from the last entry that was matched.  Function 18
   returns a Directory code in register A, analogous to Function 17.

   Note: in execution sequence, a Function 18 call must follow either a Function 17 or
   another Function 18 call with no other intervening BDOS disk-related function calls.








                                                             fool DIGITAL RESEARCH'
   3-26

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



                               BDOS FUNCTION 19: DELETE FILE

                        Entry Parameters:
                             Registers C: 13H
                                       DE: FCB Address

                        Returned Value:
                             Registers A: Directory Code
                                         H: Extended or Physical Error


           The Delete File function removes files or XFCBs that match the FCB addressed in
         register pair DE.  The filename and filetype can contain ambiguous references, that is,
         question marks 'in bytes fl through t3, but the dr byte cannot be ambiguous, as it
         can in the Search and Search Next functions.  Interface attribute f5' specifies the type
         of delete operation that is performed.

             f5' = 0 - Standard Delete (default mode)
             f5' = 1 - Delete only XFCBs

         If any of the files that the referenced FCB specify are password protected, the correct
         password must be placed in the first eight bytes of the current DMA buffer, or have
         been previously established as the default password (see Function 106).

           For standard delete operations, the Delete function removes all directory entries
         belonging to files that match the referenced FCB.  All disk directory and data space
         owned by the deleted files is returned to free space, and becomes available for allo-
         cation to other files.  Directory XFCBs that were owned by the deleted files are also
         removed from the directory.  If interface attribute f5' of the FCB is set to 1, Function
         19 deletes only the directory XFCBs that match the referenced FCB.

         Note: if any of the files that match the input FCB specification fall the password
         check, or are Read-Only, then the Delete function does not delete any files or XFCBS.
         This applies to both types of delete operations.





           DIGITAL RESEARCH'
                                                                                             3-27

   3 BDOS Calls: Function 19                                 CP/M 3 Programmcr's Guide

     In nonbanked systems, file passwords and XFCBs are not supported.  Thus, if the
   Delete function is called with interface attribute f5' set to true, the Delete function
   performs no action but returns with register A set to zero.

     Upon return, the Delete function returns a Directory Code in register A with the
   value 0 if the delete is successful, or OFFH, 255 Decimal, if no file that matches the
   referenced FCB is found.  Register H is set to zero in both of these cases.  If a physical,
   or extended error is encountered, the Delete function performs different actions
   depending on the BDOS error mode (see Function 45).  If the BDOS error mode is
   the default mode, a message identifying the error is displayed at the console and the
   calling program is terminated.  Otherwise, the Delete function returns to the calling
   program with register A set to OFFH and register H set to one of the following
   physical or extended error codes:

        01 : Disk I/O error
        02 : Read-Only disk
        03 : Read-Only file
        04 : Invalid drive error
        07 : File password error








                                                                          @e DIGITAL RESEARCH'
   3-28
       CP/M 3 Programmer's Guide                                3 BDOS Calls: Function 20



                           BDOS FUNCTION 20: READ SEQUENTIAL

                       Entry Parameters:
                             Registers C: 14H
                                       DE: FCB Address

                       Returned Value:
                             Registers A: Error Code
                                        H: Physical Error


          The Read Sequential function reads the next 1 to 128 128-byte records from a file
       into memory beginning at the current DMA address.  The BDOS Multi-Sector Count
       (see Function 44) determines the number of records to be read.  The default is one
       record.  The FCB addressed by register pair DE must have been previously activated
       by an Open or Make function call.

          Function 20 reads each record from byte cr of the extent, then automatically
       increments the cr field to the next record position.  If the cr field overflows, then the
       function automatically opens the next logical extent and resets the cr field to 0 in
       preparation for the next read operation.  The calling program must set the cr field to
       0 following the Open call if the intent is to read sequentially from the beginning of
       the file.

          Upon return, the Read Sequential function sets register A to zero if the read oper-
       ation is successful.  Otherwise, register A contains an error code identifying the error
       as shown below:

              01  Reading unwritten data (end-of-file)
              09  Invalid FCB
              10  Media change occurred
             255  Physical Error; refer to register H








          DIGITAL RESEARCH
                                                                                            3-29

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

     Error Code 01 is returned if   no data exists at the next record position of the file.
   Usually, the no data situation   is encountered at the end of a file. However, it can
   also occur if an attempt is made to read a data block that has not been previously
   written, or an extent which has not been created.  These situations are usually restricted
   to files created or appended with the BDOS random write functions (see Functions
   34 and 40).

     Error Code 09 is returned if the FCB is invalidated by a previous BDOS close call that
   returns an error.

     Error Code 10 is returned if a media change occurs on the drive after the refer-
   enced FCB is activated by a BDOS Open, or Make Call.

     Error Code 255 is returned if a physical error is encountered and the BDOS error
   mode is Return Error mode, or Return and Display Error mode (see Function 45).  If
   the error mode is the default mode, a message identifying the physical error is dis-
   played at the console, and the calling program is terminated.  When a physical error
   is returned to the calling program, register H contains one of the following error
   codes:

        01   Disk 1/0 error
        04   Invalid drive error

     On all error returns except for physical error returns, A = 255, Function 20 sets
   register H to the number of records successfully read before the error is encountered.
   This value can range from 0 to 127 depending on the current BDOS Multi-Sector
   Count.  It is always set to zero when the Multi-Sector Count is equal to one.








                                                                           L@'DICITAL RESEARCH'
   3-30

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



                           BDOS FUNCTION 21: WRITE SEQUENTIAL

                        Entry Parameters:
                              Registers C: 15H
                                        DE: FCB Address

                        Returned Value:
                              Registers A: Error Code
                                         H: Physical Error


          The Write Sequential function writes 1 to 128 128-byte data records, beginning at
        the current DMA address into the file named by the FCB addressed in register pair
        DE. The BDOS Multi-Sector Count (see Function 44) determines the number of 128
        byte records that are written.  The default is one record.  The referenced FCB must
        have been previously activated by a BDOS Open or Make function call.

          Function 21 places the record into the file at the position indicated by the cr byte
        of the FCB, and then automatically increments the cr byte to the next record posi-
        tion.  If the cr field overflows, the function automatically opens, or creates the next
        logical extent, and resets the cr field to 0 in preparation for the next write operation.
        If Function 21 is used to write to an existing file, then the newly written records
        overlay those already existing in the file.  The calling program must set the cr field to
        0 following an Open or Make call if the intent is to write sequentially from the
        beginning of the file.

          Function 21 makes an Update date and time for the file if the following conditions
        are satisfied: the referenced drive has a directory label that requests date and time
        stamping, and the file has not already been stamped for update by a previous Make
        or Write function call.








         DIGITAL RE@RCH'
                                                                                             3-31
                                                             CP/M 3 Programme            1
   3 BDOS Calls: Function 21                                                      r s Guide

      Upon return, the Write Sequential function sets register A to zero if the write
   operation is successful.  Otherwise, register A contains an error code identifying the
   error as shown below:

          01  No available directory space
          02  No available data block
          09  Invalid FCB
          10  Media change occurred
         2S5  Physical Error : refer to register H

      Error Code 01 is returned when the write function attempts to create a new extent
    that requires a new directory entry, and no available directory entries exist on the
    selected disk drive.

      Error Code 02 is returned when the write command attempts to allocate a new
    data block to the file, and no unallocated data blocks exist on the selected disk drive.

      Error Code 09 is returned if the FCB is invalidated by a previous BDOS close call
    that returns an error.

      Error Code 10 is returned if a media change occurs on the drive after the refer-
    enced FCB is activated by a BDOS Open or Make call.








                                                                           N DIGITAL RESEARCH
    3-32

         CP/M 3 Programmcr's Guide                             3 BDOS Calls: Function 21

           Error Code 255 is returned if a physical error is encountered and the BDOS error
         mode is Return Error mode, or Return and Display Error mode (see Function 45).  If
         the error mode is the default mode, a message identifying the physical error is dis-
         played at the console, and the calling program is terminated.  When a physical error
         is returned to the calling program, register H contains one of the following error
         codes:

             01   Disk 1/0 error
             02   Read-Only disk
             03   Read-Only file or
                  File open from user 0 when
                  the current user number is non-zero or
                  File password protected in Write mode
             04   Invalid drive error

           On all error returns, except for physical error returns, A @ 255, Function 21 sets
         register H to the number of records successfully written before the error was encoun-
         tered.  This value can range from 0 to 127 depending on the current BDOS Multi-
         Sector Count.  It is always set to zero when the Multi-Sector Count is set to one.








          DIGITAL RESEARCH
                                                                                         3-33

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



                           BDOS FUNCTION 22: MAKE FILE

                  Entry Parameters:
                        Registers C: 16H
                                   DE: FCB Address

                  Returned Value:
                         Registers A: Directory Code
                                    H: Physical or Extended Error


     The Make File function creates a new directory entry for a file under the current
   user number.  It also creates an XFCB for the file if the referenced drive has a direc-
   tory label that enables password protection on the drive, and the calling program
   assigns a password to the file.

     The calling program passes the address of the FCB in register pair DE, with byte 0
   of the FCB specifying the drive, bytes 1 through 11 specifying the filename and
   filctype, and byte 12 set to the extent number.  Usually, byte 12 is set to zero.  Byte
   32 of the FCB, the cr field, must be initialized to zero, before or after the Make call,
   if the intent is to write sequentially from the beginning of the file.

     Interface attribute f6' specifies whether a password is to be assigned to the created
   file.

        f6' = 0 - Do not assign password (default)
        f6' = 1 - Assign password to created file

   When attribute f6' is set to 1, the calling program must place the password in the
   first 8 bytes of the current DMA buffer, and set byte 9 of the DMA buffer to the
   password mode (see Function 102).  Note that the Make function only interrogates
   interface attribute f6' if passwords are activated on the referenced drive.  In non-
   banked systems, file passwords are not supported, and attribute f6' is never interrogated.

      The Make function returns with an error if the referenced FCB names a file that
   currently exists in the directory under the current user number.


                                                                            lo DIGITAL RESEARCH
   3-34

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

            If the Make function is successful, it activates the referenced FCB for file opera-
          tions by opening the FCB, and initializes both the directory entry and the referenced
          FCB to an empty file.  It also initializes all file attributes to zero.  In addition, Function
          22 makes a Creation date and time stamp for the file if the following conditions are
          satisfied: the referenced drive has a directory label that requests Creation date and
          time stamping and the FCB extent number field is equal to zero.  Function 22 also
          makes an Update stamp if the directory label requests update stamping and the FCB
          extent field is equal to zero.

            If the referenced drive contains a directory label that enables password protection,
          and if interface attribute f6' has been set to 1, the Make function creates an XFCB
          for the file.  In addition, Function 22 also assigns the password, and password mode
          placed in the first nine bytes of the DMA, to the XFCB.

            Upon return, the Make function returns a directory code in register A with the
          value 0 if the make operation is successful, or OFFH, 25S decimal, if no directory
          space is available.  Register H is set to zero in both of these cases.  If a physical or
          extended error is encountered, the Make function performs different actions depend-
          ing on the BDOS error mode (see Function 45).  If the BDOS error mode is the
          default mode, a message identifying the error is displayed at the console, and the
          calling program is terminated.  Otherwise, the Make function returns to the calling
          program with register A set to OFFH, and register H set to one of the following
          physical or extended error codes:

               01 : Disk 1/0 error
               02 : Read-Only disk
               04 : Invalid drive error
               08 : File already exists
               09 : ? in filename or filetype field








           DIGITAL RESEARCH'
                                                                                                 3-35

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



                        BDOS FUNCTION 23: RENAME FILE

                  Entry Parameters:
                        Registers C: 17H
                                  DE: FCB Address

                  Returned Value-.
                        Registers A: Directory Code
                                   H: Physical or Extended Error


     The Rename function uses the FCB, addressed by register pair DE, to change all
   directory entries of the file specified by the filename in the first 16 bytes of the FCB
   to the filename in the second 16 bytes.  If the file specified by the first filename is
   password protected, the correct password must be placed in the first eight bytes of
   the current DMA buffer, or have been previously established as the default password
   (see Function 106).  The calling program must also ensure that the filenames specified
   in the FCB are valid and unambiguous, and that the new filename does not already
   exist on the drive.  Function 23 uses the dr code at byte 0 of the FCB to select the
   drive.  The drive code at byte 16 of the FCB is ignored.








                                                                          'Du DIGITAL RESEARCH'
   3-36
          CP/M 3 Programmer's Guide                                3 BDOS Calls: Function 23

             Upon return, the Rename function returns a Directory Code in register A with the
          value 0 if the rename is successful, or OFFH, 25S Decimal, if the file named by the
          first filename in the FCB is not found.  Register H is set to zero in both of these cases.
          If a physical or extended error is encountered, the Rename function performs differ-
          ent actions depending on the BDOS error mode (see Function 45).  If the BDOS error
          mode is the default mode, a message identifying the error is displayed at the console
          and the program is terminated.  Otherwise, the Rename function returns to the calling
          program with register A set to OFFH and register H set to one of the following
          physical or extended error codes:

               01   Disk 1/0 error
               02   Read-Only disk
               03   Read-Only file
               04   Invalid drive error
               07   File password error
               08   File already exists
               09   ? in filename or filetype field








          lul DIGITAL RESEARCH
                                                                                                3-37

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



                    BDOS FUNCTION 24: RETURN LOGIN VECTOR

                    Entry Parameters:
                           Register C: 18H

                    Returned Value:
                         Register HL: Login Vector


      Function 24   returns the login vector in register pair HL. The login vector is a 16-
     bit value with the least significant bit of L corresponding to drive A, and the high-
     order bit of H corresponding to the 16th drive, labelled P. A 0 bit indicates that the
     drive is not on-line, while a 1 bit indicates the drive is active.  A drive is made active
     by either an explicit BDOS Select Disk call, number 14, or an implicit selection when
     a BDOS file operation specifies a non-zero dr byte in the FCB.  Function 24 maintains
     compatibilty with earlier releases since registers A and L contain the same values
     upon return.








                                                                            !Eo DIGITAL RESEARCH
     3-38

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



                    BDOS FUNCTION 25: RETURN CURRENT DISK

                    Entry Parameters:
                          Register C: 19H

                    Returned Value:
                          Register A: Current Disk


         Function 25 returns the currently selected default disk number in register A. The
       disk numbers range from 0 through 15 corresponding to drives A through P.








        DIGITAL RESEARCH'                                                     3-39

     3 BDOS (,'ails: Function 26                            CP/M 3 Programnier's Guide



                       BDOS FUNCTION 26: SET DMA ADDRESS

                   Entry Parameters:
                         Registers C: 1AH
                                   DE: DMA Address


      DMA is an acronvm for Direct Memory Address, which is often used in connec-
     tion with disk controllers that directly access the memory of the computer to transfer
     data to and from the disk subsystem.  Under CP/M 3, the current DMA is usually
     defined as the buffer in memory where a record resides before a disk write, and after
     a disk read operation.  If the BDOS Multi-Sector Count is equal to one (see Function
     44), the size of the buffer is 128 bytes.  However, if the BDOS Multi-Sector Count is
     greater than one, the size of the buffer must equal N * 128, where N equals the
     Multi-Sector Count.

       Some BDOS functions also use the current DMA to pass parameters, and to return
     values.  For example, BDOS functions that check and assign file passwords require
     that the password be placed in the current DMA.  As another example, Function 46,
     Get Disk Free Space, returns its results in the first 3 bytes of the current DMA. When
     the current DMA is used in this context, the size of the buffer in memory is deter-
     mined by the specific requirements of the called function.

       When a transient program is initiated by the CCP,       its DMA address is set to
     0080H.  The BDOS Reset Disk System function, Function 13, also sets the DMA
     address to 0080H.  The Set DMA function can change this default value to another
     memory address.  The DMA address is set to the value passed in the register pair DE.
     The DMA address remains at this value until it is changed by another Set DMA
     Address, or Reset Disk System call.








                                                                             DIGITAL RESEARCH'
     3-40

        CP/M 3 Programmcr's Guide                             3 BDOS Calls: Function 27



                          BDOS FUNCTION 27: GET ADDR(ALLOC)

                       Entry Parameters:
                             Register C: 1BH

                       Returned Value:
                            Register HL: ALLOC Address


          CP/M 3 maintains an allocation vector in main memory for each active disk drive.
        Some programs use the information provided by the allocation vector to determine
        the amount of free data space on a drive.  Note, however, that the allocation infor-
        mation might be inaccurate if the drive has been marked Read-Only.

          Function 27 returns in register pair HL, the base address of the allocation vector
        for the currently selected drive.  If a physical error is encountered when the BDOS
        error mode is one of the return modes (see Function 4S), Function 27 returns the
        value OFFFFH in the register pair HL.

          In banked CP/M 3 systems, the allocation vector can be placed in bank zero.  In
        this case, a transient program cannot access the allocation vector.  However, the
        BDOS function, Get Disk Free Space (Function 46), can be used to directly return
        the number of free 128-byte records on a drive.  The CP/M 3 utilities that display a
        drive's free space, DIR and SHOW, use Function 46 for that purpose.








         DIGITAL RESEARCH'                                                             3-41

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




                   BDOS FUNCTION 28: WRITE PROTECT DISK


                 Entry Parameters:
                       Register C: 1CH



      The Write Protect Disk function provides temporary write protection for the cur-
    rently selected disk by marking the drive as Read-Only, No program can write to a
    disk that is in the Read-Only state.  A drive reset operation must be performed for a
    Read-Only drive to restore it to the Read-Write state (see Functions 13 and 37).








     3-42                                                            DIGITAL RESEARCH'

      @p'lo I Programmer's Guide                         3 BDOS Calls: Function 29


                    BDOS FUNCTION 29: GET READ-ONLY VECTOR

                     Entry Parameters:
                           Register C: lDH

                     Returned Value:
                         Register HL: R/O Vector Value


         Function 29 returns a bit vector in register pair HL that indicates which drives
      have the temporary Read-Only bit set.  The Read-Only bit can be set only by a BDOS
      Write Protect Disk call.

         The format of the bit vector is analogous to that of the login vector returned by
      Function 24.  The least significant bit corresponds to drive A, while the most signifi-
      cant bit corresponds to drive P.








        DIGITAL RESEARCH'
                                                                                 3-43

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



                      BDOS FUNCTION 30: SET FILE ATTRIBUTES


                    Entry Parameters:
                          Registers C: 1EH
                                    DE: FCB Address

                    Returned Value:
                          Registers A: Directory Code
                                      H: Physical or Extended error



       By calling the Set File Attributes function, a program can modify a file's attributes
    and set its last record byte count.  Other BDOS functions can be called to interrogate
    these file parameters, but only Function 30 can change them.  The file attributes that
    can be set or reset by Function 30 are fl' through f4', Read-Only, tl', System, t2',
    and Archive, t3'.  The register pair DE addresses an FCB containing a filename with
    the appropriate attributes set or reset.  The calling program must ensure that it does
             'fy an ambiguous filename.  In addition, if the specified file is password to-
    not speci            I                                                                p
    tected, the correct password must be placed in the first eight bytes of the current
    DMA buffer or have been previously established as the default password (see Func-
    tion 106).

       Interface attribute f6' specifies whether the last record byte count of the specified
    file is to be set:

         f6' = 0 - Do not set byte count (default mode)
         f6' = 1 - Set byte count

    If interface attribute f6' is set, the calling program must set the cr field of the refer-
    enced FCB to the byte count value.  A program can access a file's byte count value
    with the BDOS Open, Search, or Search Next functions.

       Function 30 searches the referenced directory for entries belonging to the current
    user number that matches the FCB specified name and type fields.  The function then
    updates the directory to contain the selected indicators, and if interface attribute f6'
    is set, the specified byte count value.  Note that the last record byte count is main-
    tained in byte 13 of a file's directory FCBS.


    3-44                                                                     @to DIGITAL RESEARCH

         CP/M 3 Programmcr's Guide                                   3 BDOS Calls: Function 30

           File attributes tl', t2', and t3' are defined by CP/M 3. (They are described in
         Section 2.3.4.) Attributes fl' through f4' are not presently used, but can be useful for
         application programs, because they are not involved in the matching program used
         by the BDOS during Open File and Close File operations.  Indicators f5' through f8'
         are reserved for use as interface attributes.

           Upon return, Function 30 returns a Directory Code in register A with the value 0
                                                                    if the file specified by the refer-
         if the function is successful, or OFFH, 255 Decimal, 1
         enced FCB is not found.  Register H is set to zero in both of these cases.  If a physical
         or extended error is encountered', the Set File Attributes function performs different
         actions depending on the BDOS error mode (see Function 45).  If the BDOS error
         mode is the default mode, a message identifying the error is displayed at the console,
         and the program is terminated.  Otherwise, Function 30 returns to the calling pro-
         gram with reg'ls-Ler A set to OFFH, and register H set to one of the following physical
         or extended error codes:

             01    Disk 1/0 error
             02    Read-Only disk
             04    Select error
             07    File password error
             09    ? in filename or filetype field








         1-@ DIGITAL RESEARCH
                                                                                                    3-45

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



                   BDOS FUNCTION 31: GET ADDR(DPB PARMS)

                  Entry Parameters:
                        Register C: 1FH

                  Returned Value:
                      Register HL: DPB Address


     Function 31 returns in register pair HL the address of the BIOS-resident Disk
   Parameter Block, DPB, for the currently selected drive. (Refer to the CP/M Plus
   (CP/M Version 3) Operating System System Guide for the format of the DPB).  The
   calling program can use this address to extract the disk parameter values.

     If a physical error is encountered when the BDOS error mode is one of the return
   modes (see Function 45), Function 31 returns the value OFFFFH in the register pair
   HL.








                                                                       DIGITAL RESEARCH'
   3-46
       CP/M 3 Programmer's Guide                            3 BDOS Calls: Function 32



                         BDOS FUNCTION 32: SET/GET USER CODE

                       Entry Parameters:
                            Registers C: 20H

                       Returned Value: E: OFFH (get) or User Code (set)

                              Register A: Current Code or
                                           (no value)


          A program can change, or interrogate the currently active user number by calling
        Function 32.  If register E = OFFH, then the value of the current user number is
        returned in register A, where the value is in the range of 0 to 15.  If register E is not
        OFFH, then the current user number is changed to the value of E, modulo 16.








          DIGITAL RESEARCH'
                                                                                       3-47


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



                       BDOS FUNCTION 33: READ RANDOM

                  Entry Parameters:
                        Registers C: 21H
                                  DE: FCB Address

                  Returned Value:
                        Registers A: Error Code
                                   H: Physical Error


     'ne Read Random function is similar to the Read Sequential function except that
   the read operation takes place at a particular random record number, selected by the
   24-bit value constructed from the three byte, rO, rl, r2, field beginning at position
   33 of the FCB.  Note that the sequence of 24 bits is stored with the least significant
   byte first, rO, the middle byte next, rl, and the high byte last, r2.  The random record
   number can range from 0 to 262,143.  This corresponds to a maximum value of 3 in
   byte r2.

     To read a file with Function 33, the calling program must first open the base
   extent, extent 0. This ensures that the FCB is properly initialized for subsequent
   random access operations.  The base extent may or may not contain any allocated
   data.  Function 33 reads the record specified by the random record field into the
   current DMA address.  The function automatically sets the logical extent and current
   record values, but unlike the Read Sequential function, it does not advance the
   current record number.  Thus, a subsequent Read Random call rereads the same
   record.  After a random read operation, a file can be accessed sequentially, starting
   from the current randomly accessed position.  However, the last randomly accessed
   record is reread or rewritten when switching from random to sequential mode.

     If the BDOS Multi-Sector Count is greater than one (see Function 44), the Read
   Random function reads multiple consecutive records into memory beginning at the
   current DMA.  The rO, rl, and r2 field of the FCB is automatically incremented to
   read each record.  However, the FCBs random record number is restored to the first
   record's value upon return to the calling program.



                                                                          DIGITAL RESEARCH
   3-48
        CP/M 3 Programmer's Guide                               3 BDOS Calls: Function 33

           Upon return, the Read Random function sets register A to zero if the read opera-
        tion was  successful. Otherwise, register A contains one of the following error codes:

               01  Reading unwritten data (end-of-file)
               03  Cannot close current extent
               04  Seek to unwritten extent
               06  Random record number out of range
               10  Media change occurred
              255  Physical Error : refer to register H

           Error Code 01 is returned if no data exists at the next record position of the file.
        Usually, the no data situation is encountered at the end of a file.  However, it can
        also occur if an attempt is made to read a data block that has not been previously
        written.

           Error Code 03 is returned when the Read Random function cannot close the
        current extent prior to moving to a new extent.

           Error Code 04 is returned when a read random operation accesses an extent that
        has not been created.

           Error Code 06 is returned when byte 35, r2, of the referenced FCB is greater than
        3.

           Error Code 10 is returned if a media change occurs on the drive after the refer-
        enced FCB is activated by a BDOS Open or Make Call.

           Error Code 255 is returned if a physical error is encountered, and the BDOS error
        mode is one of the return modes (see Function 45).  If the error mode is the default
        mode, a message identifying the physical error is displayed at the console, and the
        calling program is terminated.  When a physical error is returned to the calling pro-
        gram, register H contains one of the following error codes:

             01   Disk 1/0 error
             04   Invalid drive error

           On all error returns except for physical errors, A = 255, the Read Random
        function sets register H to the number of records successfully read before the error is
        encountered.  This value can range from 0 to 127 depending on the current BDOS
        Multi-Sector Count.  It is always set to zero when the Multi-Sector Count is equal to
        one.

           DIGITAL RESEARCH'
                                                                                            3-49



                                                                                                   IN

    3 BI)OS (:ails:     Function 34                           (:P/M 3 Progranimcr's Guidc



                         BDOS FUNCTION 34: WRITE RANDOM

                    Entry Parameters:
                          Registers C: 22H
                                    DE: FCB Address

                    Returned Value:
                          Registers A: Error Code
                                     H: Physical Error


       The Write Random function is analogous to the Read Random function, except
    that data is written to the disk from the current DMA address.  If the disk extent or
    data block where the data is to be written is not already allocated, the BDOS auto-
    matically performs the allocation before the write operation continues.

       To write to a file using the Write Random function, the calling program must first
    open the base extent, extent 0. This ensures that the FCB is properly initialized for
    subsequent random access operations.  If the file is empty, the calling program must
    create the base extent with the Make File function before calling Function 34.  The
    base extent might or might not contain any allocated data, but it does record the file
    in the directory, so that the file can be displayed by the DIR utility.

       The Write Random function sets the logical extent and current record positions to
    correspond with the random record being written, but does not change the random
    record number.  Thus, sequential read or write operations can follow a random write,
    with the current record being reread or rewritten as the calling program switches
    from random to sequential mode.

       Function 34 makes an Update date and time stamp for the file if the following
    conditions are satisfied: the referenced drive has a directory label that requests Update
    date and time stamping if the file has not already been stamped for update by a
    previous BDOS Make or Write call.






                                                                            lb! DIGITAL RESEARCH
    3-50
          CP/M 3 Programmer's Guide                                 3 BDOS Calls: Function 34

            If the BDOS Multi-Sector Count is greater than one (see Function 44), the Write
          Random function reads multiple consecutive records into memory beginning at the
          current DMA.  The rO, rl, and r2 field of the FCB is automatically incremented to
          write each record.  However, the FCB's random record number is restored to the first
          record's value when it returns to the calling program.  Upon return, the Write Ran-
          dom function sets register A to zero if the write operation is successful.  Otherwise,
          register A contains one of the following error codes:

                02   No available data block
                03   Cannot Close current extent
                05   No available directory space
                06   Random record number out of range
                10   Media change occurred
                255  Physical Error : refer to register H

            Error Code 02 is returned when the write command attempts to allocate a new
          data block to the file and no unallocated data blocks exist on the selected disk drive.

            Error Code 03 is returned when the Write Random function cannot close the
          current extent prior to moving to a new extent.

            Error Code 05 is returned when the write function attempts to create a new extent
          that requires a new directory entry and no available directory entries exist on the
          selected disk drive.

            Error Code 06 is returned when byte 35, r2, of the referenced FCB is greater than
          3.

            Error Code 10 is returned if a media change occurs on the drive after the refer-
          enced FCB is activated by a BDOS Open or Make Call.








            DIGITAL RESEARCH'
                                                                                                  3-51
     3 BDOS Calls: Function 34                               CP/M 3 Programmer's Guide

      Error Code 255 is returned if a physical error is encountered and the BDOS error
     mode is one of the return modes (see Function 45).  If the error mode is the default
     mode, a message identifying the physical error is displayed at the console, and the
     calling program is terminated.  When a physical error is returned to the calling pro-
           ' ' identified by register H as shown below:
     gram, it is 1

         01   Disk 1/0 error
         02   Read-Only disk
         03   Read-Only file or
              File open from user 0 when the current user number is nonzero or
              File password protected in Write mode
         04   Invalid drive error

       On all error returns, except for physical errors, A = 255, the Write Random
     function sets register H to the number of records successfully written before the error
     is encountered.  This value can range from 0 to 127 depending on the current BDOS
     Multi-Sector Count.  It is always set to zero when the Multi-Sector Count is equal to
     one.








                                                                           t-0- DIGITAL RESEARCH
     3-52

        CP/M 3 I)rogrammer's Guide                                   3 BDOS ('ails: F'tiiictioii 35



                             BDOS FUNCTION 35: COMPUTE FILE SIZE

                          Entry Parameters:
                                Registers C: 23H
                                           DE: FCB Address

                          Returned Value:
                                Registers A: Error Flag
                                            H: Physical or Extended error

                                Random Record Field Set


           The Compute File Size function determines the virtual file size, which is, in effect,
         the address of the record immediately following the end of the file.  The virtual size
         of a file corresponds to the physical size if the file is written sequentially.  If the file is
         written in random mode, gaps might exist in the allocation, and the file might con-
         tain fewer records than the indicated size.  For example, if a single record with record
         number 262,143, the CP/M 3 maximum is written to a file using the Write Random
         function, then the virtual size of the file is 262,144 records even though only 1 data
         block 'is actually allocated.

           To compute file size, the calling program passes in register pair DE the address of
         an FCB in random mode format, bytes rO, rl and r2 present.  Note that the FCB
         must contain an unambiguous filename and filetype.  Function 35 sets the random
         record field of the FCB to the random record number + 1 of the last record in the
         file.  If the r2 byte is set to 04, then the file contains the maximum record count
         262,144.

           A program can append data to the end of an existing file by calling Function 35 to
         set the random record position to the end of file, and then performing a sequence of
         random writes starting at the preset record address.

         Note: the BDOS does not require that the file be open to use Function 35.  However,
         if the file has been written to, it must be closed before calling Function 35.  Other-
         wise, an incorrect file size might be returned.



           DIGITAL RESEARCH,
                                                                                                    3-53

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

     Upon return, Function 35 returns a zero in register A if the file specified by the
   referenced FCB is found, or an OFFH in register A if the file is not found.  Register H
   is set to zero in both of these cases.  If a physical error is encountered, Function 35
   performs different actions depending on the BDOS error mode (see Function 45).
   If the BDOS error mode is the default mode, a message identifying the error is
   displayed at the console and the program is terminated.  Otherwise, Function 35
   returns to the calling program with register A set to OFFH, and register H set to one
   of the following physical errors:

       01   Disk 1/0 error
       04   Invalid drive error








                                                                        ED DIGITAL RESEARCH'
   3-54

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



                         BDOS FUNCTION 36: SET RANDOM RECORD

                        Entry Parameters:
                              Registers C: 24H
                                        DE: FCB Address

                        Returned Value: Random Record Field Set


          The Set Random Record function returns the random record number of the next
        record to be accessed from a file that has been read or written sequentially to a
        particular point.  This value is returned in the random record field, bytes rO, rl, and
        r2, of the FCB addressed by the register pair DE.  Function 36 can be useful in two
        ways,

          First, it is often necessary to initially read and scan a sequential file to extract the
        positions of various key fields.  As each key is encountered, Function 36 is called to
        compute the random record position for the data corresponding to this key.  If the
        data unit size is 128 bytes, the resulting record number minus one is placed into a
        table with the key for later retrieval.  After scanning the entire file and tabularizing
        the keys and their record numbers, you can move directly to a particular record by
        performing a random read using the corresponding random record number that you
        saved earlier.  The scheme is easily generalized when variable record lengths are involved,
        because the program need only store the buffer-relative byte position along with the
        key and record number to find the exact starting position of the keyed data at a later
        time.

          A second use of Function 36 occurs when switching from a sequential read or
        write over to random read or write.  A file is sequentially accessed to a particular
        point in the file, then Function 36 is called to set the record number, and subsequent
        random read and write operations continue from the next record in the file.








          DIGITAL RESEARCH'
                                                                                               3-55




                                                                                                      IN

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



                          BDOS FUNCTION 37: RESET DRIVE

                   Entry Parameters:
                         Registers C: 25H
                                   DE: Drive Vector

                   Returned Value:
                          Register A: OOH


     The Reset Drive function programmatically restores specified drives to the reset
   state.  A reset drive is not logged-in and is in Read-Write status.  The passed parame-
   ter in register pair DE is a 16-bit vector of drives to be reset, where the least signifi-
   cant bit corresponds to the first drive A, and the high-order bit corresponds to the
   sixteenth drive, labelled P. Bit values of 1 indicate that the specified drive is to be
   reset.








                                                                        9 DIGITAL RESEARCH   TM
   3-56

