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



                          BDOS FUNCTION 38: ACCESS DRIVE

                    Entry Parameters:
                          Register C: 26H


         This is an MP/M function that is not supported under CP/M 3. If called, the file
       system returns a zero In register A indicating that the access request is successful.








       IL-01 DIGITAL RESEARCH"
                                                                                 3-57

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


                        BDOS FUNCTION 39: FREE DRIVE

                 Entry Parameters:
                       Register C: 27H


     This is an MP/M function that is not supported under CP/M 3. If called, the file
   system returns a zero In register A indicating that the free request is successful.








                                                                    DIGITAL RESEARCH'
   3-58
        CP/M 3 Programmer's Guide                               3 BDOS Calls: Function 40



                         BDOS FUNCTION 40: WRITE RANDOM WITH
                                                    ZERO FILL

                        Entry Parameters:
                              Registers C: 28H
                                        DE: FCB address

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



           The Write Random With Zero Fill function is identical to the Write Random
         function (Function 34) with the exception that a previously unallocated data block is
         filled with zeros before the record is written.  If this function has been used to create
         a file, records accessed by a read random operation that contain all zeros identify
         unwritten random record numbers.  Unwritten random records in allocated data blocks
         of files created using the Write Random function (Function 34) contain uninitialized
         data.








          DIGITAL RESEARCH'
                                                                                            3-59
 3 BDOS Calls: Function 41                      CP/M 3 Programmer's Guide



             BDOS FUNCTION 41: TEST AND WRITE RECORD

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

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


   The Test and Write Record function is an MP/M 11" function that is not sup-
  ported under CP/M 3. If called, Function 41 returns with register A set to OFFH and
  register H set to zero.








                                                         IC DIGITAI.  RESEAR(.H!"
  3-60
        CP/M 3 Programmer's Guide                          3 BDOS Calls: Function 42



                           BDOS FUNCTION 42: LOCK RECORD

                     Entry Parameters:
                           Registers C: 2AH
                                    DE: FCB Address

                     Returned Value:
                           Register A: OOH


         The Lock Record function is an MP/M 11 function that is supported under CP/M 3
        only to provide compatibility between CP/M 3 and MP/M.  It is intended for use in
        situations where more than one running program has Read-Write access to a com-
        mon file.  Because CP/M 3 is a single-user operating system in which only one pro-
        gram can run at a time, this situation cannot occur.  Thus, under CP/M 3, Function
        42 performs no action except to return the value OOH in register A indicating that
        the record lock operation is successful.








        'ED] I)IGITAL RESEAR(:H"'
                                                                                       3-61


                                                                                            AN

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



                     BDOS FUNCTION 43: UNLOCK RECORD

                 Entry Parameters:
                      Registers C: 2BH
                                DE: FCB Address

                 Returned Value:
                       Register A: OOH


     The Unlock Record function is an MP/M 11 function that is supported under
   CP/M 3 only to provide compatibility between CP/M 3 and MP/M.  It is intended for
   use in situations where more than one running program has Read-Write access to a
   common file.  Because CP/M 3 is a single-user operating system in which only one
   program can run at a time, this situation cannot occur.  Thus, under CP/M 3, Func-
   tion 43 performs no action except to return the value OOH in register A indicating
   that the record unlock operation is successful.








                                                                      DIGITAL RESEARCH,
   3-62
        CP/M 3 Programmer's Guide                              3 BDOS Calls: Function 44



                      BDOS FUNCTION 44: SET MULTI-SECTOR COUNT

                       Entry Parameters:
                             Registers C: 2CH
                                         E: Number of Sectors

                       Returned Value:
                              Register   A: Return Code


          The Set Multi-Sector Count function provides logical record blocking under
        CP/M 3. It enables a program to read and write from 1 to 128 records of 128 bytes
        at a time during subsequent BDOS Read and Write functions.

          Function 44 sets the Multi-Sector Count value for the calling program to the value
        passed in register E. Once set, the specified Multi-Sector Count remains in effect until
        the calling program makes another Set Multi-Sector Count function call and changes
        the value.  Note that the CCP sets the Multi-Sector Count to one when it initiates a
        transient program.

          The Multi-Sector Count affects BDOS error reporting for the BDOS Read and
        Write functions.  If an error interrupts these functions when the Multi-Sector is greater
        than one, they return the number of records successfully read or written in register
        H for all errors except for physical errors (A = 25S).

          Upon return, register A is set to zero if the specified value is in the range of 1 to
        128.  Otherwise, register A is set to OFFH.








         DIGITAL RESEARCH'
                                                                                            3-63


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



                   BDOS FUNCTION 45: SET BDOS ERROR MODE

                   Entry Parameters:
                         Registers C: 2DH
                                    E: BDOS Error Mode

                      Returned Value: None


      Function 45 sets the BDOS error mode for the calling program to the mode speci-
    fied in register E. If register E is set to OFFH, 255 decimal, the error mode is set to
    Return Error mode.  If register E is set to OFEH, 254 decimal, the error mode is set
    to Return and Display mode.  If register E is set to any other value, the error mode is
    set to the default mode.

      The SET BDOS Error Mode function determines how physical and extended errors
    (see Section 2.2.13) are handled for a program.  The Error Mode can exist in three
    modes: the default mode, Return Error mode, and Return and Display Error mode.
    In the default mode, the BDOS displays a system message at the console that identi-
    fies the error and terminates the calling program.  In the return modes, the BDOS sets
    register A to OFFH, 255 decimal, places an error code that identifies the physical or
    extended error in register H and returns to the calling program.  In Return and
    Display mode, the BDOS displays the system message before returning to the calling
    program.  No system messages are displayed, however, when the BDOS is in Return
    Error mode.








                                                                       10 DIGITAL RESEARCH'@
    3-64

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



                          BDOS FUNCTION 46: GET DISK FREE SPACE

                        Entry Parameters:
                              Registers C: 2EH
                                           E: Drive

                           Returned Value:    First 3 bytes
                                              of current DMA
                                              buffer
                              Registers A:    Error Flag
                                          H:  Physical Error


          The Get Disk Free Space function determines the number of free sectors, 128 byte
        records, on the specified drive.  The calling program passes the drive number in
        register E, with 0 for drive A, 1 for B, and so on, through 15 for drive P in a full 16-
        drive system.  Function 46 returns a binary number in the first 3 bytes of the current
        DMA buffer.  This number is returned in the following format:

                                            fso    fsl   fs2

                                     Disk Free Space Field Format

                                           fso = low      byte
                                           fsl = middle byte
                                           fs2 = high     byte

          Note that the returned free space value might be inaccurate if the drive has been
        marked Read-Only.







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

    Upon return, register A is set to zero if the function is successful.  However, if the
  BDOS Error Mode is one of the return modes (see Function 45), and a physical error
  is encountered, register A is set to OFFH, 255 decimal, and register H is set to one of
  the following values:

      01 - Disk 1/0 error
      04 - Invalid drive error








                                                             Li DIGITAL RESEARCH'
   3-66

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



                         BDOS FUNCTION 47: CHAIN TO PROGRAM

                        Entry Parameters:
                             Registers C: 2FH
                                         E: Chain Flag


           The Chain To Program function provides a means of chaining from one program
         to the next without operator intervention.  The calling program must place a com-
         mand line terminated by a null byte, OOH, in the default DMA buffer.  If register E is
         set to OFFH, the CCP initializes the default drive and user number to the current
         program values when it passes control to the specified transient program.  Otherwise,
         these parameters are set to the default CCP values.  Note that Function 108, Get/Set
         Program Return Code, can be used to pass a two byte value to the chained program.

           Function 47 does not return any values to the calling program and any encoun-
         tered errors are handled by the CCP.








          DIGITAL RESEARCH'
                                                                                           3-67

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



                       BDOS FUNCTION 48: FLUSH BUFFERS

                 Entry Parameters:
                       Registers C: 30H

                 Returned Value:   E: Purge Flag

                       Registers A: Error Flag
                                   H: Physical Error


    The Flush Buffers function forces the write of any write-pending records contained
   in internal blocking/deblocking buffers.  If register E is set to OFFH, this function also
   purges all active data buffers.  Programs that provide write with read verify support
   need to purge internal buffers  to ensure that verifying reads actually access the disk
   instead of returning data that is resident in internal data buffers.  The CP/M 3 PIP
   utility is an example of such a program.

     Upon return, register A is    set to zero if the flush operation is successful. If a
   physical error is encountered,  the Flush Buffers 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 Flush Buffers function returns to the
   calling program with register A set to OFFH and register H set to the following
   physical error code:

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








                                                                       0 DIGITAL RESEARCHT-@
   3-68
       CP/M 3 Programmer's Guide                              3 BDOS Calls: Function 49



                           BDOS FUNCTION 49: GET / SET SYSTEM
                                                     CONTROLBLOCK

                       Entry Parameters:
                            Registers C: 31H
                                      DE: SCB PB Address

                       Returned Value:
                            Registers A: Returned Byte
                                      HL: Returned Word


          Function 49 allows access to parameters located in the CP/M 3 System Control
       Block (SCB).  The SCB is a 100-byte data structure residing within the BDOS that
       contains flags and data used by the BDOS, CCP and other system components.  Note
       that Function 49 is a CP/M 3 specific function.  Programs intended for both MP/M 11
       and CP/M 3 should either avoid the use of this function or isolate calls to this
       function in CP/M 3 version-dependent sections.

          To use Function 49, the calling program passes the address of a data structure
       called the SCB parameter block in register pair DE.  This data structure identifies the
       byte or word of the SCB to be updated or returned.  The SCB parameter block is
       defined as:

       SCBPB:             DB OFFSET             ;  Offset within SCB
                          DB SET                ;  OFFH if settin!i a byte
                                                ;  OFEH if setting a word
                                                ;  001H - OFDH are reserved
                                                ;  OOOH if a get operation
                          DW VALUE              ;  Byte or word value to be set

       The OFFSET parameter identifies the offset of the field within the SCB to be updated
       or accessed.  The SET parameter determines whether Function 49 is to set a byte or
       word value in the SCB or if it is to return a byte from the SCB.  The VALUE
       parameter is used only in set calls.  In addition, only the first byte of VALUE is
       referenced in set byte calls.


       'Do DIGITAL RESEARCH"'
                                                                                          3-69

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

      Use caution when you set SCB fields.  Some of these parameters reflect the current
   state of the operating system.  If they are set to invalid values, software errors can
   result.  In general, do not use Function 49 to set a system parameter if another BDOS
   function can achieve the same result.  For example, Function 49 can be called to
   update the Current DMA Address field within the SCB.  This is not equivalent to
   making a Function 26, Set DMA Address call, and updating the SCB Current DMA
   field in this way would result in system errors.  However, you can use Function 49 to
   return the Current DMA address.  The System Control Block is summarized in the
   following table.  Each of these fields is documented in detail in Appendix A.

                              Table 3-4.  System Control Block
                     Offset   -7            Description

                    00 - 04            Reserved For System Use
                    05                 BDOS version number
                    06 - 09            User Flags
                    OA - OF            Reserved For System Use
                    10 - 11            Program Error return code
                    12 - 19            Reserved For System Use
                    1A                 Console Width (columns)
                    1B                 Console Column Position
                    ic                 Console Page Length
                    1D -    21         Reserved For System Use
                    22 -    23         CONIN       Redirection flag
                    24 - 25            CONOUT      Redirection flag
                    26 - 27            AUXIN       Redirection flag
                    28 - 29            AUXOUT      Redirection flag
                    2A - 2B            LSTOUT      Redirection flag
                    2C                 Page Mode
                    2D                 Reserved For System Use
                    2E                 CTRL-H Active
                    2F                 Rubout Active
                    30  - 32           Reserved For System Use
                    33  - 34           Console Mode
                    35  - 36           Reserved For System Use
                    37                 Output Delimiter
                    38                 List Output Flag
                    39  - 3B           Reserved For System Use




                                                                          9 DIGITAL RESEARCH
    3-70

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

                                     Table 3-4. (continued)

                         Offset               Description
                       3C-3D            Current DMA Address
                       3E               Current Disk
                       3F - 43          Reserved For System Use
                       44               Current User Number
                       45 - 49          Reserved For System Use
                       4A               BDOS Multi-Sector Count
                       4B               BDOS Error Mode
                       4C - 4F          Drive Search Chain (DISKS A:,E:,F:)
                       50               Temporary File Drive
                       51               Error Disk
                       52 - 56          Reserved For System Use
                       57               BDOS flags
                       58 - 5C          Date Stamp
                       5D - 5E          Common Memory Base Address
                       5F - 63          Reserved For System Use


        If Function 49 is called with the OFFSET parameter of the SCB parameter block
        greater than 63H, the function performs no action but returns with registers A and
        HL set to zero.








         DI(-,ITAL RLSLARCH:"
                                                                                    3-71

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



                      BDOS FUNCTION 50: DIRECT BIOS CALLS

                  Entry Parameters:
                        Registers C: 32H
                                  DE: BIOS PB Address

                     Returned Value: BIOS RETURN


      Function 50 provides a direct BIOS call through the BDOS to the BIOS.  The
    calling program passes the address of a data structure called the BIOS Parameter
    Block (BIOSPB) in register pair DE.  The BIOSPB contains the BIOS function number
    and register contents as shown below:

    BIOSPB:                db FUNC             ; BIOS function no.
                           db   AREG           ; A register contents
                           dw   BCREG          ; 15C register contents
                           dw   DEREG          ; DE resfister contents
                           dw   HLR@EG         ; HL register contents

      System Reset (Function    0) is equivalent to Function 50 with a BIOS       function
    number of 1.

      Note that the register pair BIOSPB fields (BCREG, DEREG, HLREG) arc defined
    in low byte, high byte order.  For example, in the BCREG field, the first byte contains
    the C register value, the second byte contains the B register value.

      Under CP/M 3, direct BIOS calls via the BIOS jump vector are only supported for
    the BIOS Console 1/0 and List functions.  You must use Function 50 to call any other
    BIOS functions.  In addition, Function 50 intercepts BIOS Function 27 (Select Mem-
    ory) calls and returns with register A set to zero.  Refer to the CPIM Plus (CP/M
    Version 3) Operating System System Guide for the definition of the BIOS functions
    and their register passing and return conventions.






                                                                      17-01 DL(;ITAL RFSEARCH"'
    3-72

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



                               BDOS FUNCTION 59: LOAD OVERLAY

                          Entry Parameters:
                                Registers C: 3BH
                                          DE: FCB Address

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


             Only transient programs with an RSX header can use the Load Overlay function
          because BDOS Function 59 is supported by the LOADER module.  The calling pro-
          gram must have a header to force the LOADER to remain resident after the program
          is loaded (see Section 1.3).

             Function 59 loads either an absolute or relocatable module.  Relocatable modules
              'dent'fied by a filetype of PRL.  Function 59 does not call the loaded module.
          are 1    1

             The referenced FCB must be successfully opened before Function 59 is called.  The
          load address is specified in the first two random record bytes of the FCB, rO and rl.
          The LOADER returns an error if the load address is less than 100H, or if performing
          the requested load operation would overlay the LOADER, or any other Resident
          System Extensions that have been previously loaded.

             When loading relocatable files, the LOADER requires enough room at the load ad-
          dress for the complete PRL file including the header and bit map (see Appendix B).
          Otherwise an error is returned.  Function 59 also returns an error on PRL file load
          requests if the specified load address is not on a page boundary.

             Upon return, Function 59 sets register A to zero if the load operation is successful.
          If the LOADER RSX is not resident in memory because the calling program did not
          have a RSX header, the BDOS returns with register A set to OFFH and register H set
          to zero.  If the LOADER detects an invalid load address, or if insufficient memory is
             'Table to load the overlay, Function 59 returns with register A set to OFEH.  All
          aval
          other error returns are consistent with the error codes returned by BDOS Function
          20, Read Sequential.

          V, Dl(.ITAI- RFSEAR(@H"                                                             3-73

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



                  BDOS FUNCTION 60: CALL RESIDENT SYSTEM
                                            EXTENSION

                  Entry Parameters:
                       Registers C: 3CH
                                 DE: RSX PB Address

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


     Function 60 is a special BDOS function that you use when you call Resident
    System Extensions.  The RSX subfunction is specified in a structure called the RSX
    Parameter Block, defined as follows:

    RSXPB:                 db FUNC            ; RSX Function number
                           db NUMPARMS        ; Number of word Parameters
                           dw PARMETER1       ; Parameter I
                           dw PARMETER2       ; Parameter 2
                           f t   0
                           dw PARMETERN       ; Parameter n

      RSX modules filter all BDOS calls and   capture RSX function calls that they can
    handle.  If there is no RSX module present in memory that can handle a specific RSX
    function call, the call is not trapped, and the BDOS returns OFFH in registers A and
    L. RSX function numbers from 0 to 127 are available for CP/M 3 compatible soft-
    ware use.  RSX function numbers 128 to 255 are reserved for system use.








                                                                     IC DIGITAI- RESEARCH"
    3-74

       CPIM I P,ogrimmcr's Guide                               3 BDOS Calls: Function 98



                              BDOS FUNCTION 98: FREE BLOCKS

                       Entry Parameters:
                              Register C: 62H

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


          The Free Blocks function scans all the currently logged-in drives, and for each
        drive returns to free space all temporarily-allocated data blocks.  A temporarily-allo-
        cated data block is a block that has been allocated to a file by a BDOS write
        operation but has not been permanently recorded in the directory by a BDOS close
        operation.  The CCP calls Function 98 when it receives control following a system
        warm start.  Be sure to close your file, particularly any file you have written to, prior
        to calling Function 98.

          In the nonbanked version of CP/M 3, Function 98 frees only temporarily allocated
        blocks for systems that request double allocation vectors in GENCPM.

          Upon return, register A is set to zero if Function 98 is successful.  If a physical
        error is encountered, the Free Blocks 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 Free Blocks function returns to the calling
        program with register A set to OFFH and register H set to the following physical
        error code:

             04 : Invalid drive error






          Dl(,I'l AL. RESEAR('H"'                                                            3-75

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



                        BDOS FUNCTION 99: TRUNCATE FILE

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

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


      The Truncate File function sets the last record of a file to the random record
    number contained in the referenced FCB.  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 bytes 33 through 35, rO, rl, and
    r2, specifying the last record number of the file.  The last record number is a 24 bit
    value, stored with the least significant byte first, rO, the middle byte next, rl, and the
    high byte last, r2.  This value can range from 0 to 262,143, which corresponds to a
    maximum value of 3 in byte r2.

      If the file specified by the referenced FCB is password protected, the correct pass-
    word 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).

      Function 99 requires that the file specified by the FCB not be open, particularly if
    the file has been written to.  In addition, any activated FCBs naming the file are not
    valid after Function 99 is called.  Close your file before calling Function 99, and then
    reopen it after the call to continue processing on the file.





    3-76                                                                 P Dl(;II'AL RESEARCH"'

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

          Function 99 also requires that the random record number field of the referenced
        FCB specify a value less than the current file size.  In addition, if the file is sparse, the
        random record field must specify a record in a region of the file where data exists.

          Upon return, the Truncate function returns a Directory Code in register A with the
        value 0 if the Truncate function is successful, or OFFH, 255 decimal, if the file is not
        found or the record number is invalid.  Register H is set to zero in both of these
        cases.  If a physical or extended error is encountered, the Truncate 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 terminated.  Otherwise, the Truncate 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
             09    ? in filename or filetype field








         1101 DL(;ITAL RESEARCH"                                                                 3-77

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




                     BDOS FUNCTION 100: SET DIRECTORY LABEL


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

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



      The Set Directory Label function creates a directory label, or updates the existing
    directory label for the specified drive.  The calling program passes in register pair DE
    the address of an FCB containing the name, type, and extent fields to be assigned to
    the directory label.  The name and type fields of the referenced FCB are not used to
    locate the directory label in the directory; they are simply copied into the updated or
    created directory label.  The extent field of the FCB, byte 12, contains the user's
        'ficat-on of the directory label data byte.  The definition of the directory label
    speci       1
    data byte   is:

         bit 7  -Require passwords for password-protected files
                 (Not supported in nonbanked CP/M 3 systems)
             6  -Perform access date and time stamping
             5  -Perform update date and time stamping
             4  -Perform create date and time stamping
             0  -Assign a new password to the directory label

    If the current directory label is password protected, the correct password must be
    placed in the first eight bytes of the current DMA, or have been previously estab-
    I'tshed as the default password (see Function 106).  If bit 0, the low-order bit, of byte
    12 of the FCB is set to 1, it indicates that a new password for the directory label has
    been placed in the second eight bytes of the current DMA.

      Note that Function 100 is implemented as an RSX, DIRLBL.RSX, in nonbanked
    CP/M 3 systems.  If Function 100 is called in nonbanked systems when the DIRLBL.RSX
                'dent',
    is not resi       an error code of OFFH is returned.



    3-78                                                                       'Do DIGITAL RESEARCH'@'

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

           Function 100 also requires that the referenced directory contain SFCBs to activate
         date and time stamping on the drive.  If an attempt is made to activate date and time
         stamping when no SFCBs exist, Function 100 returns an error code of OFFH in
         register A and performs no action.  The CP/M 3 INITDIR utility initializes a directory
         for date and time stamping by placing an SFCB record in every fourth entry of the
         directory-

           Function 100 returns a Directory Code in register A with the value 0 if the direc-
         tory label create or update is successful, or OFFH, 255 decimal, if no space exists in
         the referenced directory to create a directory label, or if date and time stamping was
         requested and the referenced directory did not contain SFCBS.  Register H is set to
         zero in both of these cases.  If a physical error or extended error is encountered,
         Function 100 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,
         Function 100 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
             07    File password error








         9 DIGITAL RESEARCH"'
                                                                                                 3-79

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



                    BDOS FUNCTION 101: RETURN DIRECTORY
                                                 LABEL DATA

                   Entry Parameters:
                         Registers C: 65H
                                      E: Drive

                      Returned Value:
                         Registers A:   Directory Label
                                        Data Byte
                                     H: Physical Error


     The Return Directory Label Data function returns the data byte of the directory
   label for the specified drive.  The calling program passes the drive number in register
   E with 0 for drive A, 1 for drive B, and so on through 15 for drive P in a full sixteen
   drive system.  The format of the directory label data byte is shown below:

        bit 7 - Require passwords for password protected files
           6 - Perform access date and time stamping
           5 - Perform update date and time stamping
           4 - Perform create date and time stamping
           0 - Directory label exists on drive

   Function  101 returns the directory label data byte to the calling program in register
   A. Register A equal to zero indicates that no directory label exists on the specified
   drive.  If a physical error is encountered by Function 101 when the BDOS Error mode
   is in one of the return modes (see Function 45), this function returns with register A
   set to OFFH, 25S decimal, and register H set to one of the following:

        01   Disk I/O error
        04   Invalid drive error



   3-80                                                               9 DIGITAL RESEARCH"'

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



                      BDOS FUNCTION 102: READ FILE DATE STAMPS
                                                  AND PASSWORD MODE

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

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


          Function 102 returns the date and time stamp information and password mode for
       the specified file in byte 12 and bytes 24 through 32 of the specified FCB.  The calling
       program passes in register pair DE, the address of an FCB in which the drive, file-
       name, and filetype fields have been defined.

          If Function 102 is successful, it sets the following fields in the referenced FCB:

            byte 12 : Password mode field
                      bit 7 - Read mode
                      bit 6 - Write mode
                      bit 4 - Delete mode

       Byte 12 equal to zero indicates the file has not been assigned a password.  In non-
       banked systems, byte 12 is always set to zero.

            byte 24 - 27   Create or Access time stamp field
            byte 28 - 31   Update time stamp field

       The  date stamp fields are set to binary zeros if a stamp has not been made. The
       format of the time stamp fields is the same as the format of the date and time
       structure described in Function 104.






        I Dl(;I'FAI- RESEAR('H
                                                                                           3-81

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

       Upon return, Function 102 returns a Directory Code in register A with the value
          if the function is successful, or OFFH, 255 decimal, if the specified file is not
    zero 1            1   1
    found. Register H is  set to zero in both of these cases. If a physical or extended error
    is encountered, Function 102 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, Function 102 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
         09   ? in filename or filetype field








                                                                        Li@o 1)1(;II'Al- RFSFAR('H"'
    3-82

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



                            BDOS FUNCTION 103: WRITE FILE XFCB

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

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


           Ile Write File XFCB function creates a new XFCB or updates the existing XFCB
         for the specified file.  The calling program passes in register pair DE the address of an
         FCB in which the drive, name, type, and extent fields have been defined.  The extent
         field specifies the password mode and whether a new password is to be assigned to
         the file.  The format of the extent byte is shown below:

             FCB byte 12 (ex) : XFCB password mode
             bit 7 - Read mode
             bit 6 - Write mode
             bit 5 - Delete mode
             bit 0 - Assign new password to the file

         If the specified file is currently password protected, the correct password must reside
         in the first eight bytes of the current DMA, or have been previously established as
         'the default password (see Function 106).  If bit 0 is set to 1, the new password must
            'de in the second eight bytes of the current DMA.
         resi  I               I








           I)I(;l I-Al, RESEAR('H
                                                                                              3-83

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

      Upon return, Function 103 returns a Directory Code in register A with the value
         if the XFCB create or update is successful, or OFFH, 255 decimal, if no directory
    zero 1                                                                 1
    label exists on the specified drive, or the file named in the FCB is not found, or no
    space exists in the directory to create an XFCB.  Function 103 also returns with OFFH
    in register A if passwords are not enabled by the referenced directory's label.  On
    nonbanked systems, this function always returns with register A = OFFH because
    passwords  are not supported. Register H is set to zero in all of these cases. If a
    physical or extended error is encountered, Function 103 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, Function 103 returns to the calling pro-
    gram 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
         07   File password error
         09   ? in filename or filetype field








                                                                      9 DIGITAL RESEARCH'"
    3-84

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



                            BDOS FUNCTION 104: SET DATE AND TIME

                          Entry Parameters:
                                Registers C: 68H
                                          DE: DAT Address

                             Returned Value: none


            The Set Date and Time function sets the system internal date and time.  The calling
           program passes the address of a 4-byte structure containing the date and time speci-
           fication in the register pair DE.  The format of the date and time (DAT) data structure
           is:

               byte 0 - 1   Date field
               byte 2       Hour field
               byte 3       Minute field

           The date is represented as a 16-bit integer with day 1 corresponding to January 1,
           1978.  The time is represented as two bytes: hours and minutes are stored as two
           BCD digits.

             This function also sets the seconds field of the system date and time to zero.








           N DIGITAI.  RESEARCH"'
                                                                                                  3-85

  3 BDOS Call@: Function 105                               CP/M 3 Programmer's Guide



                   BDOS FUNCTION 105: GET DATE AND TIME

                  Entry Parameters:
                       Registers C: 69H
                                 DE: DAT Address

                     Returned Value:
                        Register A:    seconds
                        DAT set



     The Get Date and Time function obtains the system internal date and time.  The
  calling program passes in register pair DE, the address of a 4-byte data structure
  which receives the date and time values.  The format of the date and time, DAT, data
  structure is the same as the format described in Function 104.  Function 105 also
  returns the seconds field of the system date and time in register A as a two digit BCD
  value.








                                                                     R DIGITAL RESEARCHrm
   3-86

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



                       BDOS FUNCTION 106: SET DEFAULT PASSWORD

                       Entry Parameters:
                             Registers C: 6AH
                                       DE: Password Address

                          Returned Value: none


          The Set Default Password function allows a program to specify a password value
        before a file protected by the password is accessed.  When the file system accesses a
        password-protected file, it checks the current DMA, and the default password for the
        correct value.  If either value matches the file's password, full access to the file is
        allowed.  Note that this function performs no action in nonbanked CP/M 3 systems
        because file passwords are not supported.

          To make a Function 106 call, the calling program sets register pair DE to the
        address of an 8-byte field containing the password.








          DI(;ITAL RESEARCH
                                                                                           3-87

  3 BDOS (,ails: Function 107                      CP/M 3 Programmer's Guide



              BDOS FUNCTION 107: RETURN SERIAL NUMBER

               Entry Parameters:
                    Registers C: 6BH
                             DE: Serial Number Field

                  Returned Value: Serial number field set


    Function 107 returns the CP/M 3 serial number to the 6-byte field addressed by
  register pair DE.








   3-88                                                     10 DIGITAL RESEARCH

