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



                    BDOS FUNCTION 108: GET/SET PROGRAM RETURN
                                               CODE

                       Entry Parameters:
                            Registers C: 6CH
                                      DE: OFFFFH (Get) or
                                           Program Return Code (Set)

                          Returned Value:
                            Register HL:   Program Return Code or (no value)


          CP/M 3 allows programs to set a return code before terminating.  This provides a
        mechanism for programs to pass an error code or value to a following 'ob step in
        batch environments.  For example, Program Return Codes are used by the CCP in
        CP/M 3's conditional command line batch facility.  Conditional command lines are
        command lines that begin with a colon, :. The execution of a conditional command
        depends on the successful execution of the preceding command.  The CCP tests the
        return code of a terminating program to determine whether it successfully completed
        or terminated in error.  Program return codes can also be used by programs to pass
        an error code or value to a chained program (see Function 47, Chain To Program).

          A program can set or interrogate the Program Return Code by calling Function
        108.  If re 'ster pair DE = OFFFFH, then the current Program Return Code is returned
        in register pair HL.  Otherwise, Function 108 sets the Program Return Code to the
        'value contained in register pair DE.  Program Return Codes are defined in Table 3-5.








        470 DIGI-I'AL RESEARCH'M
                                                                                          3-89

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

                       Table 3-5. Program Return Codes
        Code                                Meaning

    0000 - FEFF        Successful return

    FFOO - FFFE        Unsuccessful return

    0000               The CCP initializes the Program Return Code to zero unless
                       the program is loaded as the result of program chain.

    FF80 - FFFC        Reserved

    FFFD               The program is terminated because of a fatal BDOS error.

    FFFE               The program is terminated by the BDOS because the user
                       typed a CTRL-C.








                                                         @0i'DIGITAL RESEARCH"'
   3-90

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



                        BDOS FUNCTION 109: GET/SET CONSOLE MODE

                        Entry Parameters:
                              Registers C: 6DH
                                        DE: OFFFFH (Get) or Console Mode (Set)

                           Returned Value:
                             Register HL: Console Mode or (no value)


          A program can set or interrogate the Console Mode by calling Function 109.  If
        register pair DE = OFFFFH, then the current Console Mode is returned in register
        HL. Otherwise, Function 109 sets the Console Mode to the value contained in regis-
        ter pair DE.

           The Console Mode is a 16-bit system parameter that determines the action of
        certain BDOS Console 1/0 functions.  The definition of the Console Mode is:

              bit 0 = 1 - CTRL-C only status for Function 1 1.
                    = 0 - Normal status for Function 1 1.

              bit 1 =   1- Disable stop scroll, CTRL-S, start scroll, CTRL-Q, support.
                    =   0-Enable stop scroll, start scroll support.

              bit 2 =   1- Raw console output mode. Disables tab expansion for Functions 2,
                          9 and 111.  Also disables printer echo, CTIRL-P, support.
                    =   0 - Normal console output mode.

              bit 3 =   1 - Disable CTRL-C program termination
                    =   0 - Enable CTRL-C program termination








         i-c DI(ilTAL RESEAR(:Il""
                                                                                                3-91

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

       bits 8,9  -Console status mode for RSXs that perform console input redirec-
                  tion from a file.  These bits determine how the RSX responds to
                  console status requests.

                  bit 8 = 03 bit 9 = 0 - conditional status
                  bit 8 = 01 bit 9 = 1 - false status
                  bit 8 = 1, bit 9 = 0 - true status
                  bit 8 = 11 bit 9 = 1 - bypass redirection

    Note that the Console Mode bits are numbered from right to left.

    The CCP initializes the Console Mode to zero when it loads a program unless the
  program has an RSX that overrides the default value.  Refer to Section 2.2.1 for
  detailed information on Console Mode.








                                                                R DIC;ITAL RESEARCH"'
  3-92

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



                    BDOS FUNCTION 110: GET/SET OUTPUT DELIMITER

                        Entry Parameters:
                             Registers C: 6EH
                                       DE: OFFFFH (Get) or
                                         E: Output Delimiter (Set)

                        Returned Value:
                              Register   A: Output Delimiter or (no value)


          A program can set or interrogate the current Output Delimiter by calling Function
        110.  If register pair DE = OFFFFH, then the current Output Delimiter is returned in
        register A. Otherwise, Function 110 sets the Output Delimiter to the value contained
        in register E.

          Function 110 sets the string delimiter for Function 9, Print String.  The default
        delimiter value is a dollar sign, $. The CCP restores the Output Delimiter to the
        default value when a transient program is loaded.








          1)1(.I'FAL RESEARCH"'
                                                                                             3-93

   3 BDOS Calls: Function 111                               CP/M 3 Programmer's ('.aide



                         BDOSFUNCTION111: PRINTBLOCK

                   Entry Parameters:
                         Registers C: 6FH
                                  DE: CCB Address

                      Returned Value: none


      The Print Block function sends the character string located by the Character Con-
   trol Block, CCB, addressed in register pair DE, to the logical console, CONOUT:.  If
   the Console Mode is in the default state (see Section 2.2.1), Function 111 expands
   tab characters, CTRL-1, in columns of eight 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.

      The CCB format is:

        byte 0 - 1  Address of character string (word value)
        byte 2 - 3  Length of character string (word value)








                                                                      F!-Ol DIGITAL RESEARCH"'
   3-94

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



                            BDOS FUNCTION 112: LIST BLOCK

                     Entry Parameters:
                          Registers C: 70H
                                   DE: CCB Address

                        Returned Value: none


         The List Block function sends the character string located by the Character Control
       Block, CCB, addressed in register pair DE, to the logical list device, LST.-.

         The CCB format is:

           byte 0 - 1 Address of character string (word value)
           byte 2 - 3 Length of character string (word value)








       ECO' DIGITAL RESEARCH'"
                                                                                   3-95



                                                                                          IN

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



                      BDOS FUNCTION 152: PARSE FILENAME

                  Entry Parameters:
                        Registers C: 98H
                                  DE: PFCB Address

                     Returned Value:
                       Register HL: Return code
                       Parsed file control block


      The Parse Filename function parses an ASCII file specification and prepares a File
    Control Block, FCB.  The calling program passes the address of a data structure called
    the Parse Filename Control Block, PFCB, in register pair DE.  The PFCB contains the
    address of the input ASCII filename string followed by the address of the target FCB
    as shown below:

    PFCB: DW INPUT ; Address of input ASCII string
             DW FCB          ; Address of target FCB

    The maximum length of the input ASCII string to be parsed is 128 bytes.  The target
    FCB must be 36 bytes in length.

      Function 152 assumes the input string contains file specifications in the following
    form:

        {d:lfilename{.typll;passwordl

    where items enclosed in curly brackets are optional.  Function 152 also accepts iso-
    lated drive specifications d: in the input string.  When it encounters one, it sets the
    filename, filetype, and password fields in the FCB to blank.








                                                                      IF-0 DIGITAL RESEARCH
    3-96
         CP/M 3 Programmer's Guide                               3 BDOS Calls: Function 152

           The Parse Filename function parses the first file specification it finds in the input
         string.  The function first eliminates leading blanks and tabs.  The function then assumes
         that the file specification ends on the first delimiter it encounters that is out of
         context with the specific field it is parsing.  For instance, if it finds a colon, and it is
         not the second character of the file specification, the colon delimits the entire file
         specification.

           Function 152 recognizes the following characters as detimiters:

              space
              tab
              return
              nut]
               (semicolon) - except before password field
              = (equal)
              < (less than)
              > (greater than)
               (period) - except after filename and before filetype
               (colon) - except before filename and after drive
               (comma)
               (vertical bar)
               (left square bracket)
               (right square bracket)

         If Function 152 encounters a non-graphic character in the range 1 through 31 not
         listed above, it treats the character as an error.  The Parse Filename function initializes
         the specified FCB shown in Table 3-6.








         ff@ Dl('.ITAL RESEARCH[M
                                                                                                 3-97

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

                                  Table 3-6.  FCB Format
     Location                                        Contents

    byte 0               The drive field is set to the specified drive. If the drive is not
                         specified, the default drive code is used. 0 = default, 1 = A,
                         2 = B.

    byte 1-8             The name is set to the specified filename. All letters are con-
                         verted to upper-case.  If the name is not eight characters long,
                         the remaining bytes in the filename field are padded with blanks.
                         If the filename has an asterisk,,  *, all remaining bytes in the
                         filename field are filled in with question marks, ?. An error
                         occurs if the filename is more than eight bytes long.

    byte 9-11            The type is set to the specified filetype. If no filetype is speci-
                         fied, the type field is initialized to blanks.  All letters are con-
                         verted to upper-case.  If the type is not three characters long,
                         the remaining bytes in the filetype field are padded with blanks.
                         If an asterisk, *, occurs, all remaining bytes are filled in with
                         question marks, ?. An error occurs if the type field is more
                         than three bytes long.

    byte 12-15           Filled in with zeros.

    byte 16-23           The password field is set to the specified password. If no pass-
                         word is specified, it is initialized to blanks.  If the password is
                         less than eight characters long, remaining bytes are padded
                         with blanks.  All letters are converted to upper-case.  If the pass-
                         word field is more than eight bytes long, an error occurs.  Note
                         that a blank in the first position of the password field implies
                         no password was specified.

    byte 24-31           Reserved for system use.








                                                                        iDo DIGITAL RESEARCHTM
   3-98

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

           If an error occurs, Function 152 returns an OFFFFH in register pair HL.

           On a successful parse, the Parse Filename function checks the next item in the
         input string.  It skips over trailing blanks and tabs and looks at the next character.  If
         the character is a null or carriage return, it returns a 0 indicating the end of the input
         string.  If the character is a delimiter, it returns the address of the delimiter.  If the
         character is not a delimiter, it returns the address of the first trailing blank or tab.

           If the first non-blank or non-tab character in the input string is a null, 0, or
         carriage return, the Parse Filename function returns a zero indicating the end of
         string.

           If the Parse Filename function is to be used to parse a subsequent file specification
         in the input string, the returned address must be advanced over the delimiter before
         placing it in the PFCB.

                                             End of Section 3








         [K DIGITAL RESEARCH7@
                                                                                               3-99



                                                                                                     IN

                                            ection

                          Programming Examples



          The programs presented in this section illustrate how to use the BDOS functions
        described in the previous section.  The examples show how to copy a file, how to
        dump a file, how to create or access a random access file, and how to write an RSX
        program.

        4.1 A Sample File-To-File Copy Program

          The following program illustrates simple file operations.  You can create the pro-
        gram source file, COPY.ASM, using ED or another editor, and then assemble
        COPY.ASM using MAC".  MAC produces the file COPY.HEX. Use the utility
        HEXCOM to produce a COPY.COM file that can execute under CP/M 3.

          The COPY program first sets the stack pointer to a local area, then moves the
        second name from the default area at 006CH to a 33-byte file control block named
        DFCB.  The DFCB is then prepared for file operations by clearing the current record
        field.  Because the CCP sets up the source FCB at 005CH upon entry to the COPY
        program, the source and destination FCBs are now ready for processing.  To prepare
        the source FCB, the CCP places the first name into the default FCB, with the proper
        fields zeroed, including the current record field at 007CH.

          COPY continues by opening the source file, deleting any existing destination file,
        and then creating the destination file.  If each of these operations is successful, the
        COPY program loops at the label COPY until each record is read from the source
        file and placed into the destination file.  Upon completion of the data transfer, the
        destination file is closed, and the program returns to the CCP command level by
        lumping to BOOT.








                 RLSLARC',H"'
                                                                                           4-1

     4.1 A Sample Copy Program                                                                            CP/M 3 Programmer's Guide

                                             sample file-to-file copy Program

                                             at the ccp levels the command

                                                              copy a:xiy b:utv

                                             copies the file named x.y from drive
                                             a t a a f i le named               u . v on d rive b .

       0000      =            boat           equ              0000h          ;  system rebout
       0005      =            bdos           equ              0005h          ;  bdos entry Point
       005c      =            fcbl           e9u              005ch          ;  first file name
       005C      =            sfcb           equ              fcbl           ;  source fob
       006C      =            fcb2           equ              006ch          ;  second tile name
       0080      =            dbuff          equ              00BOh          ;  default buffer
       0100      =            tpa            eqU              0100h          i  beginning of tpa

       0009      =            Printf         equ              9              1  Print buffer func#
       00of      =            openf          equ              15                open file func*
       0010      =            closef         eqU              16                close file func*
       0013      =            deletef        eqU              is                delete file func*
       0014      =            readf          eqU              20                sequential read
       0015      c            writef         e4qu             21                sequential write
       0016      =            makef          equ              22                make file func#

       0100                                  orl              tpa               beginning of tpa
       0100      3llbO2                      lxi              sppstack;         local stack

                                             move second file name to dfcb
       0103      OelO                        mvi              CTIG           ;  half an fob
       0105      116coo                      1 x i            d tf ob2       ;  source of move
       0108      21da0l                      I x i            h t d f c b    ;  destination fob
       010b      la           mfcb:          ldax             d              ;  source fob
       010c      13                          inx              d              ;  ready next
       010d      77                          mov              mta            ;  dest fob
       010e      23                          inx              h              ;  ready next
       010f      Od                          dcr              c              ;  count 16 ... 0
       0110      c2ObOl                      inz              mfcb           ;  loop IG times

                                             name has been movedt zero or
       0 1 1 3   at                          x r a            a              ; a = 00h
       0114      32fa0i                      sta              dfcbcr ; current rec = 0








                                                                                                                             1170 DIGITAL RESEARCHI@'
       4-2

          CP/M 3 Programmer's Guide                                                            4.1 A Sample Copy Program

                                            source and destination fcbs ready

           0117 115cOO                      Ixi          dtsfcb ;        source file
           Olla    cdGgOl                   call         open          ; error if 255
           Olld    118701                   Ixi          dtnofile;       ready message
           0120    3c                       inr          a             ; 255 becomes 0
           0121    ccGlOl                   CZ           finis         ; done if no file

                                            source file open           t Prep destination
           0124    Ilda0l                   Ixi          dtdfcb        ; destination
           0127    cd7301                   call         delete        ; remove if Present

           012a    llda0l                   Ixi          dtdfcb        ; destination
           012d    cdB2Ol                   call         make          ; create the file
           0130    119GOI                   Ixi          dtnodir       ; ready message
           0133    3c                       inr          a             ; 255 becomes 0
           0134    cc6lOl                   CZ           finis         ; done if no dir space

                                            source     file opent        dest file open
                                            copy until end of            file on source

           0137 115cOO         copy:        ]xi          dtsfcb          source
           0 1 3 a cd7BOl                   c a 11       read            read next reco rd
           013d    b7                       ora          a               end of file?
           013e    c25101                   inz          eafile          skip write if so

                                            n o t end    of f i le     write the record
           0141    ilda0l                   Ixi          dtdfcb          destination
           0144    cd7dOl                   call         write           write record
           0147    1 1 a9Ol                 I x i        dtspace         ready message
           0 1 4 a b7                       0 r a        a               00 if write ok
           014b    c46101                   cnz          finis         i end it so
           014e    c33701                   imp          COPY            loop until eof

                               eofile:      ; end of fileo close destination
           0151    llda0i                   Ixi          dtdfcb          destination
           015a    cdGPOI                   call         close           255 if error
           1117    21blOl                   ]xi          htwrprot; ready message
           015a    3c                       inr          a               255 becomes 00
           015b    ccGlOt                   CZ           finis           should not happen

                                            copy operation complete end
           0 1 5 e I I c c 0 1              1 x i        dtnormal;       ready message

                               finis:          write     message given by det reboot
           0161    OeO9                     mvi          ctprintf
           0163    cdO5OO                   call         bdos            write message
           0166    c3OOOO                   imp          boot            reboot system


           Eo 1)1("ITAI.  RESEAR("HI"
                                                                                                                                       4-3

     4.1 A Sample Copy Program                                                                   CP/M 3 Programmer's Guide

                                           system interface subroutines
                                           (all   return di rectly f rom bdos)

        0169 OeOf           open:          mk)i          ctopenf
        016b    c3O5OO                     imp           bdos

        0 1 6 e 0 e I 0     close:         mvi           c t c 1 o s e f
        C170    c3(D500                    imp           bdos

        0173    Oel3        delete:        mvi           c,deletef
        0175    c3O5OO                     imp           bdos

        0179    Oel4        r e a d        m v i         c Preadf
        017a    c3O5OO                     imp           bdos

        0 1 7 d Oel5        w r i t e      m v i         ctwritef
        017f    c3O5OO                     imp           bdos

        0182    0 e 1 6     make:          m v i         ctmakef
        oie4    c3O5OC                     imp           bdos

                                           console       messages
        0187    6eSf2Ofnofile;             db            /no source file$'
        0196    6e6f2O9nodir:              db             no directory space$'
        Olag    6f7574fspace:              db            iout of data space$'
        Oibb    7772695wrprot:             db            'write Protected?$'
        oicc    636f7OOnormal:             db            /copy complete$'

                                           data areas
        Olda                 dfcb:         ds            33               destination fcb
                              dfcbcr       eqU           dfcb+32          current record

        Olfb                               ds            32                16 leuel stack
                             s t a c K :
        021b                               end

          Note that this program                 makes several simplifications and could be enhanced. First,
        it does not check for invalid filenames that could, for example, contain ambiguous
        references.  This situation could be detected by scanning the 32-byte default area
        starting at location 005CH for ASCII question marks.  To check that the filenames
        have, in fact, been included, COPY could check locations 005DH and 006DH for
        nonblank ASCII characters.  Finally, a check should be made to ensure that the source
        and destination filenames are different.  Speed could be improved by buffering more
        data on each read operation.  For example, you could determine the size of memory
        by fetching FBASE from location 0006H, and use the entire remaining portion of
        memory for a data buffer.  You could also use CP/M 3's Multi-Sector 1/0 facility to
        read and write data in up to 16K units.


        4-4                                                                                                       *-ol [)[(;I'FAL- RESLAR(:H

        CP/M 3 Programmer's Guide                              4.2 A Sample File Dump Litility

        4.2 A Sample File Dump Utility

          The following dump program reads an input file specified in the CCP command
        line, and then displays the content of each record in hexadecimal format at the
        console.         DUMP Program reads input file and displays hex data

         0100                   orl       100h
         0005  =       bdos     e9u       0005h    ;dos entry Point
         0001  =       cons     eqU       I        ;read console
         0002  =       typef    equ       2        ;type function
         0009  =       Printf   equ       9        ;buffer Print entry
         000b  =       brkf     eqU       11       ;break key function (true if char
         00of  =       opent    e9u       15       ;file open
         0014  =       readf    eqU       20       ;read function

         005c  =       fob      eqU       5ch      ;file control block address
         0080  =       buff     eqU       Boh      ;input disk buffer address

                                non   graphic characters
         000d  =       or       eqU       Odh      ;carriage return
         000a  =       if       equ       Oah      ;line feed

                                file control block definitions
         005c  =       fcbdn    equ       fcb+O    ;disk name
         005d  =       fcbfn    eqU       fcb+l    ifile name
         0065  =       tcbft    equ       fcb+9    ;disk file type (3 characters)
         0068  =       fcbrl    equ       fcb+12   ;file's current reel number
         006b  =       tcbrc    equ       fcb+15   ;file's record count (O to 128)
         007c  =       fcbcr    ecqu      fcb+32   ;current (next) record number (O
         007d  =       fcbln    equ       fcb+33   ;fcb length

                                set up  stack
         0100  210000           lxi       hiO
         0103  39               dad       SP
                                entry stack Pointe r in hl f rom the cop
         0104  221502           shld      oldsp
                                set sp to local stack area ( resto red at finis
         0107  315702           Ixi       spistktop
                                read and Print successive buffers
         010a  cdol0l           call      setup    ;Set up input file
         010d  feff             cpi       255      ;255 if file not Present
         010f  c2lbOl           inz       openok   ;skip if open is oK





        ieci Dl(;ITAI, RESEAR('HI"
                                                                                               4-5

        4.2 A Sample File Dump Utility                                                   CP/M 3 Programmer's Guide


                                        file not      theret give error message and return
        0112 lif3ol                     lxi           dtopnmsi
        0115 cd9cOl                     call          err
        0118    c35101                  imp           finis       !to return

                         openok:        ;open operation           oRt set buffer index to end
        Ollb    3eBO                    m v i         a P80h
        Olld    321302                  sta           ibp         ;set buffer Pointer to 80h
                                        hl contains next address to Print
        0120    210000                  Ixi           hoO         ;start with 0000

                          lloc)p:
        0123    e5                      Push          h           gsave line Position
        0124    cda2Ol                  call          gnb
        0127    el                      POP           h           ;recall line Position
        0128    da5lOl                  ic            finis       ;carry set by inb if end file
        012b    47                      (ACV          b ta
                                        Print hex values
                                        check for line fold
        012c    7d                      mov           aft
        012d    EGOI                    ani           Ofh         ;check low 4 bits
        012t    c24401                  inz           nanum
                                        Print line number
        0 1 32  cd7201                  c a I 1       c r 1 f

                                        cheek fo      r break Key
        0135    cd59Ol                  call          break
                                        accum lsb = I if character ready
        0138    Of                      rre                       ;into carry
        0139    da5lOl                  ic            finis       ;do not Print any more
           013c 7c                      mov           ath
        013d    cdBfOl                  call          phex
        0140    7d                      (AOV          ail
        0141    cdSfOl                  call          Phex
                           nonum:
        0144    23                      inx           h           ;to next line number
        0145    3e2O                    mui           at' 1
        0147    cdG5Ol                  call          Pchar
        0 1 4 a 78                      mov           a i b
        014b    cdBfOl                  call          Phex
        014e    c32301                  imp           gloop





        4-6                                                                                                  1)1(,'ITAI- RESEAR(HI"

             CP/M 3 Programmer's Guide                                                                   4.2 A Sample File Dump Utility



                                    f i n i s
                                                    end of dump
             0151 cd7201                            call           crlf
             0154 2al5O2                            lhld           oldsp
             0157 f9                                sphl
                                                    stack Pointer contains ccp's stack location
             0158 c9                                ret                           ;to the ccp


                                                    subroutines

                                    break:          ;check break key (actually any key will do)
             0159 e5d5c5                            Push h! Push d! Push b; environment saved
             015c     OeOb                          m v i          etbrkf
             015e     cdO5OO                        call           bdos
             0161     oldlel                        Pop b! Pop d! Pop h; environment restored
             0164     c9                            ret

                                    Pchar:          ;Print a character
             0165     e5d5c5                        Push h! Push d! Push b; saved
             0168     OeO2                          mvi            cotypef
             015a     5t                            mov            e P a
             016b     cdO5OO                        call           bdos
             OlGe     cldlel                        Pop    b! Pop d! Pop h; restored
             0 1 7 1  c 9                           ret

                                    c r 1 f
             0172     3eOd                          m v i          a tc r
             0174     ed6501                        call           Pchar
             0177     3eOa                          m v i          a p 1 f
             0179     cd6501                        call           Pchar
             017c     c9                            ret


                                    Pnib:           ;Print nibble in rel a
             017d     e6Of                          ani            Ofh             ;low 4 bits
             017f     fe0a                          cpi            to
             0181     d289Ol                        inc            Plo
                                                    less than or equal to 9
             0184     c63O                          adi            lo,
             0186     c3BbOl                        imp            Prn

                                                    9 reat e r     or equal to 10
             0189     c637          Plo:            adi            la' - 10
             018b     cd6501        Prn:            call           Pchar
             OlBe     cg                            ret




             0 Dl(,ITAI- RESEAR(HI"
                                                                                                                                                                 4-7

      4.2     A Sample File Dump Utility                                                 CP/M 3 Programmer's Guide


                          Phex:        ;Print hex char in rel a
      018f    f5                       Push          PSW
      0190    Of                       r r c
      0191    Of                       r r c
      0192    Of                       rrc
      0193    Of                       rrc
      0194    cd7dOl                   call          Pnib        ;Print nibble
      0197    fl                       POP           PSW
      0198    cd7dOl                   call          Pnib
      019b    cg                       ret

                          e r r        ip rint e rro r message
                                       die addresses message ending with"$"
      019c    OeO9                     mvi           ctprintf                ;Print buffer function
      019e    cdO5OO                   call          bdos
      Olal    Cs                       ret


                          !inb:        ;get next byte
      Ota2    3al3O2                   lda           ibp
      Ola5    feBO                     cpi           Boh
      Ola7    c2b3Ol                   inz           10
                                       read another buffer


      Olaa    cdce0l                   call          diskr
      Olad    b7                       Ora           a           ;zero value if read OK
      Olae    cab3Ol                   iz            so          ;for another byte
                                       end   of  datat return with carry set for eof
      Olbi    37                       s t c
      Olb2    c9                       r e t

                          10:          ;read the byte at buff+ref a
      Olb3    5f                       mov           eta         ;ls byte of buffer index
      Olb4    1600                     mui           diO         ;double Precision index to de
      Olb6    3c                       inr           a           ;index=index+l
      Olb7    321302                   sta           ibp         ;back to memory
                                       Pointer       is  incremented
                                       save the current file address
      Olba    218000                   lxi           hibuff
      0 1 b d 19                       dad           d
                                       absolute character address is in hl
      Olbe    7e                       mov           arm
                                       byte is       in the accumulator
      Olbf    b7                       Ora           a           ;reset carry bit
      olco    C9                       ret





                                                                                                        [la] 1)1(,'II'AL RESLAR(,H
      4-8

                CP/M 3 Programmer's Guide                                                                          4.2 A Sample File Dump Utility

                                         setup:           iset up          file
                                                          open the file for input
                0 1 c I    a f                            x ra             a               ;Zero to accum
                0 1 c 2    327cOO                         s t a            t c b c r       ;clea r cu r rent reco rd

                Olc5       115cOO                         Ixi              dtfcb
                OlcB       OeOf                           mvi              ctopenf
                Olca       cdO5OO                         call             bdos
                                                          255     in    accum if open error
                Olcd       c9                             ret

                                         diskr:           ;read disk file record
                Oice       e5d5c5                         Push h! Push d! Push b
                0 1 d 1    115cOO                         I x i            d tf cb
                Old4       Oel4                           mvi              ctreadf
                Old6       cdO5OO                         call             bdos
                Old9       cldlel                         Pop    b!     Pop d! Pop h
                Oldc       c9                             ret

                                                          fixed message area
                Oldd       46494cOsignon:                 db               'file dump version 2.0$'
                Olf3       OdOa4eOopnmsi:                 db               crtlfp'no input file Present on disk$'

                                                          variable area
                0213                     ibp:             ds               2               ;input buffer Pointer
                0215                     o I d s P        ds               2               ;ent ry sp val ue f Yom cop

                                                          stack area
                0217                                      ds               64              ;reserve 32 level stack
                                         stktop:

                0257                                      end








                     [)[(,ITAL.  RESEAR(@ii
                                                                                                                                                                             4-9

   4.3 A Sample Random Access Program                    CP/M 3 Programmer's Guide

   4.3 A Sample Random Access Program

     This example is an extensive but complete example of random access operation.
   The following program reads or writes random records upon command from the
   terminal.  When the program has been created, assembled, and placed into a file
   labeled RANDOM.COM, the CCP level command

   A>RANDOM X.DAT

   can start the test program.  In this case, the RANDOM program looks for a file
                 if 't finds ' prompts the console for input.  If X.DAT is not found,
   X.DAT and, 1 1          it@
   RANDOM creates the      file before displaying the prompt. Each prompt takes the
   form:

        next command?

   and is followed by operator input, terminated by a carriage return.  The input com-
   mands take the form:

        nW nR nF Q

   where n is an integer value in the range 0 to 262143, and W, R, F, and Q are simple
   command characters corresponding to random write, W, random read, R, random
   write with zero fill, F, and quit processing, Q. If you enter a W or F command, the
   RANDOM program issues the prompt:

   type data:

   You then respond by typing up to 127 characters, followed by a carriage return.
   RANDOM then writes the character string into the X.DAT file at record n. If you
   enter an F command, the RANDOM program fills previously unallocated data blocks
   with zeros before writing record n. If you enter the R command, RANDOM reads
   record number n and displays the string value at the console.  If you enter the Q
   command, the X.DAT file is closed, and the program returns to the console com-
   mand processor.  In the interest of brevity, the only error message is:

   e r ro r t t ry a !I a i n






                                                                     1)1(.'l ['A[, RLSLAR('.Ei
   4-10

        CP/M 3 Programmer's Guide                       4.3 A Sample Random Access Program

           The program begins with an initialization section where the input file is opened or
        created, followed by a continuous loop at the label ready where the individual com-
        mands are interpreted.  The program uses the default file control block at 005CH and
        the default buffer at 0080H in all disk operations.  The utility subroutines that follow
        contain the principal input line processor, called readc.  This particular program shows
        the elements of random access processing and can be used as the basis for further
        program development.


                              sample random access Program for cp/m 3


          0100                      orl       looh     !base of tpa

          0000  =          reboot   eqU       0000h    ;system reboot
          0005  =          bdos     equ       0005h    ;bdas entry Point

          0001  =          coninp   equ       1        ;console input function
          0002  =          conout   eqU       2        ;console output function
          0009  =          p S t r i n IeqU   9        ;print string unt i 1
          OOOA  =          rstrin5  eqU       10       ;read console buffer
          OOOC  =          ve rsi on eqU      1 2      ;return version  number
          OOOF  =          openf    eqU       15       ;file open function
          0010  =          closef   eqU       1E       ;close function
          0016  =          makef    eqU       22       ;make file function
          0021  =          readr    eqU       33       ;read random
          0022  =          writer   eqU       34       ;write random
          0028  =          wrtrzf   eqU       40       ;write random zero fill
          0098  =          Parsef   equ       152      ;Parse function

          005C  =          fcb      eqU       005ch    ;default file control black
          007D  =          ranrec   eqU       f c b+33 i random re cord Po s it ion
          007F  =          ranovf   eqU       fcb+35   ihigh order (overflow) byte
          0080  =          buff     eqU       0080h    ;buffer address

          OOOD  =          or       eqU       Odh      ;carriage return
          OOOA  =          if       eqU       Oah      ;line feed








         Ec DIGITAL RESEARCH'@
                                                                                                4-11

   4.3 A Sample Random Access Program                          CP/M 3 Programmer's Guide




                        load SPt set-up file for random access


   0100 313703                lmi       sptstack

                              version   3,1?
   0103  OEOC                 mui       ctuersion
   0105  CDO500               call      bdos
   0108  FE20                 cpi       31h      ;version 3.1 or better?
   010A  D21601               inc       versok
                              bad versions messaye and go back
   0100  119102               lxi       dtbadver
   0110  CD3102               call      Print
   0113  C30000               imp       reboot

                    versak:
                              correct   ve rsion to r random access
   0116  OEOF                 mvi       ciapenf ;open default fcb
   0118  3A5DOO     rdname:   lda       fcb+i
   011B  FE20                 cpi       I I
   0110  C22COI               inz       opfile
   0120  IIE002               Ixi       dtentmsg
   0123  CD3102               call      Print
   0126  CD2002               call      Parse
   0129  C31801               imp       rdname
   oizc  115coo     opt i le  lxi       d tf cb
   012F  CDO500               call      bdos
   0132  3C                   i n r     a       !err 255 becomes zero
   0133  C24BOI               inz       ready

                              cannot open f i le t so create it
   0136  OE16                 mvi       ctmaket
   0138  115coo               Ixi       dtfcb
   013D  CDO500               call      bdos
   013E  3C                   inr       a       ;err 255 becomes zero
   013F  C24BOI               inz       ready

                              cannot c  reate f i le t di rectory f ul I
   0142  IIA002               lmi       dtnospace
   0145  C03102               call      Print
   0148  C30000               imp       reboot ;back to ccp








                                                                         JID DICITAL RESEAR('H
   4-12

              CP/M 3 Programiiier's Guide                              4.3 A Sample Random Access Program
                                        loop back to "ready" after each command
                                   r e a d Y
                                             file is     ready for Processing

              014B   CD3CO2                  call        readcom ;read next command
              014E   227DOO                  shld        ranrec    ;sto re input reco rd*
              0151   217FOO                  Ixi         hpranovf
              0154   71                      mov         ffitc     ;set ranrec high byte
              0155   FE51                    cpi         IQI       ;quit?
              0157   C26901                  inz         notq

                                             quit Processinit       close file
              015A   OEIO                    m v i       ctcloset
              015C   115COO                  Ixi         dtfeb
              015F   CDO500                  call        bdos
              0162   3C                      inr         a         ;err 255 becomes 0
              0163   CAFF01                  iz          error     ;error message# retry
              OIGG   C30000                  imp         reboat    ;back to cop



                                      end of quit command# Process write


                                 n o t 9 .
                                             not the     quit commandi random write?
              0169 FE57                      cpi         twi
              0165   C29COI                  inz         notw

                                             this is     a random writer fill buffer until cr
              016E   1IB302                  Ixi         dpdatmsi
              0171   CD3102                  call        Print     ;data Prompt
              0174   OE7F                    mvi         ctl27     ;up to 127 characters
              017G   218000                  lxi         htbuff ;destination
                                 rloop.      ;read next character to buff
              0179   C5                      Push        b         ;save counter
              017,1  E5                      Push        h         ;next destination
              017B   CDO802                  call        getchr    ;character to a
              017E   El                      POP         h         ; resto re counter
              017F   Cl                      p 0 p       b         ;restore next to fill
              01110  FEOI                    cpi         or        ;end of line?
              0182   CABBOI                  iz          erloop



               DICITAL RESEARCH'''
                                                                                                                  4- 1 3

    4.3    A Sample Random Access Program                            CP/M 3 Programmer's Guide

                                 not  endt store character
    0185   77                    mov        moa
    0186   23                    inx        h         ;next to fill
    0187   OD                    dcr        c         icounter goes down
    0188   C27901                inz        rloop     ;end of buffer?
                       erloop:
                                 end  of  read loopt store 00
    018B   3600                  mvi        mto

                                 write the record to selected record number
    OIBD   OE22                  mvi        cowriter
    OIGF   115COO                Ixi        dtfcb
    0192   CDO500                call       bdas
    0195   57                    ora        a         ;error code zero?
    0196   C2FFOI                inz        error     ;message if not
    0199   C34BOL                imp        r e a d Y ;f or another record


                                                                                             *
                           end of write command t Process write random zero f i I 1 *
                                                                                             *

                       n 0 t w
                                 not the    quit command t random write zero f ill?
    019C FE46                    cpi        'Fo
    019E   C2CF01                inz        notf

                                 this is    a random writer fill buffer until or
    OlAl   115302                1)(i       dtdatmsg
    OIA4   C03102                call       print     !data Prompt
    OIA7   OE7F                  mvi        ctl27     iup to 127 characters
    OIA9   218000                Ixi        htbuff ;destination
                       rloopl:   ;read next character to buff
    OIAC   C5                    Push       b         ;save counter
    OIAD   E5                    Push       h         !next destination
    01AE   C00802                call       getchr    ;character to a
    OlDl   El                    POP        h         ;restore counter
    OlB2   Cl                    pop        b         ;restore next to fill
    OIB3   FEOD                  opi        or        ;end of line?
    OIB5   CA15EOI               iz         e r I o o p 1
                                 n o te n d store character
    01BB   77                    mov        mpa
    0159   23                    inx        h         ;next to fill
    OIBA   00                    dcr        c         ;counter goes    down
    01BB   C2ACOI                inz        rloopl    ;end of buffer?




                                                                                Ll:ol DI(it'I'Al.  RLSEAR(,H
    4-14

             CP/M 3 Programmer's Guide                                                       4.3 A Sample Random Access Program


                                         e rl cl DP I -
                                                         en d o t re a d I o a p t st o re 00
             01BE 3600                                   mvi              m@O

                                                         w r i te the         record to selected record number
             OICO     OE28                               mvi              cpwrtrzf
             OIC2     115COO                             Ixi              dtfcb
             OIC5     CDO500                             call             bdos
             OICB     57                                 o r a            a             ;error code zero?
             OlC9     C2FF01                             inz              error         ;message if not
             OICC     C34BOI                             imp              ready         ;for another record



                                               end of write commands Process read


                                         notf
                                                         not a write commandt read record?
             OICF FE52                                   cpi              'Rt
             0 1 D I  C2FF01                             inz              e r r o r     iskip if not

                                                         read random record
             OID4     OE21                               mvi              ctreadr
             OIDG     115COO                             Ixi              dtfcb
             OID9     CDO500                             call             bdos
             OIDC     B7                                 ora              a             ireturn code 00?
             01DO     C2FFOI                             inz              e r ra r

                                                         read was successful# write to console
             OIEO     CD1502                             call             crlf          ;new line
             OIE3     OEBO                               mvi              cpl28         imax 128 characters
             OIE5     218000                             lxi              htbuff        ;next to get
                                         w   o o p
             OIEB     7E                                 mov              atm           ;next character
             OIES     23                                 inK              h             ;next to get
             OIEA     E67F                               ani              7fh           ;mask Parity
             OIEC     C14501                             iz               r e a d Y     ifor another command if 00
             OIEF     C5                                 Push             b             ;save counter
             OIFO     E5                                 Push             h             ;save next to let
             OlFl     FE20                               epi              I   I         ;graphic?
             OIFI     1IOE02                             cnc              Putchr        ;skip output if not
             OIFG     El                                 pop              h
             0IF7     Cl                                 POP              b
             OIFB     OD                                 dcr              c             ;count=count-1
             IIFI     12EI01                             inz              W10op
             OIFC     C34BOI                             imp              ready




             i@o DIGI I AL RESEAR(H
                                                                                                                                                              4- 1 5

     4.3 A Sample Random Access Program                                                   CP/M 3 Programmer's Guide





                                   end of read command t a l I e r ro rs end -up here



                               er r or
       OLFF IIBF02                           lxi          doerrmsi
       0202 CD3102                           call         Print
       0205 C34501                           imp          ready



                                    utility subroutines for console i/o


                               getchr,       iread next console character to a
       0208 OEOI                             mvi          ctraninp
       020A CDO500                           call         bdos
       020D    CS                            r e t

                               Putchr-.
                                             ;write character from a to console
       020E OE02                             m v i        ctconout
       0210 5F                               mov          eta          ;character to send
       0211    CDO500                        call         bdos         ;send character
       0214    CS                            ret

                               c r 1 f
                                             ;send carriage return line feed
       02 1 5  3EOD                          mvi          a t c r      ;carriage return
       0217    CDOE02                        call         Putchr
       021A    3EOA                          mvi          atlf         ;line feed
       021C    CDOE02                        call         Putchr
       021F    CS                            ret

                               p a r s e
                                             ;read and Parse filespec
       0220    IIFIOZ                        Ixi          dtconbuf
       0223    OEOA                          mvi          ctrstrini
       0225    C00500                        call         bdas
       0228    111303                        Ixi          dtpfncb
       022B    OE98                          mvi          ctparsof
       022D    CDO500                        call         bdos
       0230    CS                            ret



                                                                                                           MDIGITAL RESEARCH'M
       4- 16
         CP/M 3 Programmer's Guide                       4.3 A Sample Random Access Program

                          P r i n t :
                                    ;Print the buffer addressed by de until $
         0231  D5                   Push     d
         0232  CD1502               call     crlf
         0235  Dl                   POP      d        ;new line
         0236  OE09                 m v i    ctpstring
         0238  CDO500               call     bdos     ;Print the string
         023B  C9                   ret

                          readcom:
                                    ;read the next command line to the conbuf
         023C  110102               lxi      dtprompt
         023F  CD3102               call     Print    icammand?
         0242  OEOA                 mvi      ctrstring
         0244  1 1 F I 0 2          1 x i    dtconbuf
         0247  CDO500               call     bdos     ;read command line
                                    command  line is Presentt scan it
         024A  OEOO                 mvi      ct 0     ;start with 00
         024C  210000               lxi      htO                   0000
         024F  1IF302               lxi      dtconlin;command line
         0252  IA         reads:    Idax     d        ;next command character
         0253  13                   inx      d        ;to next command Position
         0254  B7                   ora      a        !cannot be end of command
         0255  CB                   rz
                                    not zerot  numeric?
         0256  D630                 sui      lo/
         0258  FEOA                 Gpi      10       ;carry if numeric
         025A  D27902               ine      endrd








         Ka) [)I(;ITAL RESEAR(,H"'
                                                                                                4-17

    4.3     A Sample Random Access Program                                             CP/M 3 Programmer's Guide


                                         add-in next digit
    025D    F5                           PLLS h        PSW
    025E    79                           m 0 v         a  C         ;value in ahl
    025F    29                           dad           h
    0260    BF                           adc           a            ;*2
    0261    F5                           Push          a            ;save value * 2
    0262    E5                           P U S h       h
    0263    29                           dad           h            ;*4
    0264    SF                           a d c         a
    0265    29                           dad           h            ;*e
    0266    SF                           adc           a
    0267    Cl                           POP           b            ;*2 + *8        *10
    02GB    09                           dad           b
    0269    Cl                           POP           b
    026A    68                           adc           b
    02GE    Cl                           POP           b            ;+diiit
    026C    48                           mou           ctb
    02GD    0600                         mvi           biO
    02GF    09                           d a d         b
    0270    CEOO                         aci           0
    0272    4F                           mov           cta
    0273    D25202                       inc           readc
    0276    C33CO2                       imp           readcom
                            end rd
                                         e n d of readt restore value in a
    0279    C630                         adi           lot          ;command
    027D    FE61                         cpi           la/          !translate case?
    0270    DB                           rc
                                         lower caset        mask lower case bits
    027E    E65F                         ani           101$llllb
    0280    C9                           r e t                      ;return with value in chl



                                 string data area for console messages


                            badver:
    0281 73GF727279         nospace:     db            so r ry t You need cplm ve rs i on 3$

    02AO 6EGF206469                      db            'no directory space$'
                            d a t m s I :
    0253 7479706520         errmsg:      db            'type data: $'

    02BF 857272GF72                      db            terrort try again.$'
                            Prompt:
    02DI 6E65787420         entmsl:      db            next command? $'

    02EO 65GE746572                      db            'enter filename: $'


                                                                                                      Ka] DIGITAL RESEARCH
    4-18

         CP/M 3 Programmer's Guide                     4.3 A Sample Random Access Program



                             fixed and variable data area


         02Fl 21          conbut: db        conlen ;length of console buffer
         02F2             consiz:  ds       I        ;resulting size after read
         02F3             conlin:  ds       32       ;length 32 buffer
         0021             conlen   eqU      $-consiz

                          p t n c b
         0313 F302                 dw       conlin
         0315 5COO                 dw       fcb

         0317                      ds       32       ;16 level stack
                          5tack:
         0337                      end

          You could make the following major improvements to this program to enhance its
         operation.  With some work, this program could evolve into a simple data base
         management system.  You could, for example, assume a standard record size of 128
         bytes, consisting of arbitrary fields within the record.  You could develop a program
         called GETKEY that first reads a sequential file and extracts a specific field defined
         by the operator.  For example, the command

         GETKEY NAMES*DAT LASTNAME 10 20

         would cause GETKEY to read the data base file NAMES.DAT and extract the
         "LASTNAME" field from each record, starting at position 10 and ending at charac-
         ter 20.  GETKEY builds a table in memory consisting of each particular LASTNAME
         field, along with its 16-bit record number location within the file.  The GETKEY
         program then sorts this list and writes a new file, called LASTNAME.KEY. This list,
         sometimes called an inverted index, is an alphabetical list of LASTNAME fields with
         their corresponding record numbers.

          You could rename the program shown above to QUERY, and modify it so that it
         reads a sorted key file into memory.  The command line might appear as

         QUERY NAMES.DAT LASTNAME4KEY







         for DIGITAL RESEAR(:H!'
                                                                                              4-19

   4.3 A Sample Random Access Program                        CP/M 3 Programmer's Guide

   Instead of reading a number, the QUERY program reads an alphanumeric string
   which is a particular key to find in the NAMES.DAT data base.  Because the LAST-
   NAME.KEY list is sorted, you can find a particular entry quickly by performing a
   binary search, similar to looking up a name in the telephone directory.  Start at both
   ends of the list and examine the entry halfway in between and, if not matched, split
   either the upper half or the lower half for the next search.  You will quickly reach the
   item you are looking for, in log2(n) steps, where you will find the corresponding
   record number.  Fetch and display this record at the console as the program illustrates.

      At this point, you are just getting started.  With a little more work, you can allow
   a fixed grouping size, which differs from the 128-byte record shown above.  You can
   accomplish this by keeping track of the record number as well as the byte offset
   within the record.  Knowing the group size, you can randomly access the record
   containing the proper group, offset to the beginning of the group within the record,
   and read sequentially until the group size has been exhausted.

      Finally, you can improve QUERY considerably by allowing Boolean expressions
   that compute the set of records that satisfy several relationships, such as a LAST-
   NAME between HARDY and LAUREL and an AGE less than 45.  Display all the
   records that fit this description.  Finally, if your lists are getting too big to fit into
   memory, randomly access your key files from the disk as well.

   4.4 Construction of an RSX Program

      This section describes the standard prefix of a Resident System Extension (RSX)
   and illustrates the construction of an RSX with an example. (See Section 1.6.4 for a
   discussion of how RSXs operate under CP/M 3.) RSX programs are usually written
   in assembler, but you can use other languages if the interface between the language
   and the calling conventions of the BDOS are set up properly.








                                                                        'Cgl [)](.'I'I'AL RESEAR(:H
   4-20

            CP/M 3 Programmer's Guide                         4.4 Construction of an RSX Program

            4.4.1 The RSX Prefix
             The first 27 bytes of an RSX program contain a standard data structure called the
            RSX prefix.  The RSX prefix has the following format:

                         d b       0 #0 #0 #0 to to
            sta rt .
                         imp       ?test                           ; start of Program
            n e x t :
                         db        Oc3h                            ; jump instruction to
                         dw        0                               ; next module in line
            Prev:        dw        0                               ; Previous module
            remove:
                         db        Offh                            ; remove flag
            nonbank:
                         db        0                               ; nonbank flag
            n a m e :
                         db        '123456713'                     ; any B-character name
            1 oade r :
                         db        0                               ; loader flag
                         db        0#0                             ;  reserved area

              The only   fields of the RSX prefix that you must initialize are the remove: flag, the
            nonbank: flag, and the name: of the RSX.

              For compatibility with previous releases of CP/M, the serial: field of the prefix is
            set to the serial number of the operating system by the LOADER module when the
            RSX is loaded into memory.  Thus, the address in location 6 locates the byte follow-
            .g the serial number of the operating system with or withou; RSXs in memory.
            in                                                                  1.

              The start: field contains a 'ump instruction to the beginning of the RSX code
            where the RSX tests to see if this BDOS function call is to be intercepted or passed
            on to the next module in line.

              The next: field contains a jump instruction to the next module in the chain or the
            LOADER module if the RSX is the oldest one in memory.  The RSX program must
            make its own BDOS function calls by calling the next: entry point.






            V-0 DIGITAI, RESEAR(,H"'
                                                                                                       4-21

    4.4 Construction of an RSX Program                      CP/M 3 Programmer's Guide

      The prev: field contains the address of the preceding RSX in memory or location 5
    if the RSX is the first RSX in the chain.

      The remove: field controls whether the RSX is removed from memory by the next
    call to the LOADER module via BDOS function 59.  If the remove: flag is OFFH, the
    LOADER removes the RSX from memory.  Note that the CCP always calls the
    LOADER module during a warm start operation.  An RSX that remains in memory
    past warm start because its remove: flag is zero, must set the flag at its termination
    to ensure its removal from memory at the following warm start.

      The nonbank: field controls when the RSX is loaded.  If the field is OFFH, the
    LOADER only loads the module into memory on nonbanked CP/M 3 systems.
    Otherwise, the RSX is loaded into memory under both banked and nonbanked ver-
    sions of CP/M 3.

      The loader: flag identifies the LOADER RSX.  When the LOADER module loads
    an RSX into memory, it sets this prefix flag of the loaded RSX to zero.  However, the
    loader: flag in the LOADER's prefix contains OFFH.  Thus, this flag identifies the last
    RSX in the chain, which is always the LOADER.

    4.4.2 Example of RSX Use
      These two sample programs illustrate the use of an RSX program.  The first
    program, CALLVERS, prints a message to the console and then makes a BDOS
    Function 12 call to obtain the CP/M 3 version number.  CALLVERS repeats this
    sequence five times before terminating.  The second program, ECHOVERS, is an RSX
    that intercepts the BDOS Function 12 call made by CALLVERS, prints a second
    message, and returns the version 0031H to CALLVERS.  Although this example is
    simple, it illustrates BDOS function interception, stack swapping, and BDOS function
    calls within an RSX.








                                                                     R 1)1(;ITAL RESEAR(,Yi"'
    4-22

             CP/M      3 Programmer's Guide                                   4.4     Construction of an RSX Program

                                    ; CALLVERS Program
             0005    =              b d a s     e9u          5                       ;  ent ry Point f o r BOOS
             0009    =              Prtstr      eqU          9                       ;  Print string function
             OOOC    =              vers        eq U         12                         get version function
             OOOD    =              or          eqU          Odh                        carriage return
             OOOA    =              if          e9u          Dah                        line feed

             0100                               orl          100h
             0100    1605                       m v i        d t5                       Perform 5 times
             0102    D5             loop;       Push         d                          save counter
             0103    OE09                       mui          c#prtstr
             0105    IlIE01                     Ixi          dicall$msi                 Print call message
             0108    CDO500                     call         bdcs
             OIOB    OEOC                       mvi          ctt)ers
             OIOD    CDO500                     call         bdos                       try to let ve rsion
                                                                                        CALLVERS will intercept
             0110    70                         mov          atl
             0111    323401                     sta          curvers
             0114    DI                         POP          d
             01  15  15                         do r         d                          dec reroent counte r
             0116    C20201                     inz          loop
             0119    OEOO                       mvi          CPO
             OIIB    C30500                     imp          bdos
                                    call$msg:
             OIIE    ODOA2A2A2A                 db           crtlft'**** CALLVERS
             0134    00             curvers db               0
             0135                               end

                                      ECHOYERS RSX

             0009    =              Pstrini eqU              9                          string Print function
             OOOD    =              or          eqU          Odh
             OOOA    =              if          eqU          Oah

                                                             RSX PREFIX STRUCTURE

             0000    0000000000                 db           0 10 to to to to        ;  room f o r se ri al numbe r
             0006    C31500                     imp          ftest                   ;  begin of Program
             0009    C3             next:       db           Oc3H                    ;  jump
             OOOA    0000                       dw           0                       ;  next module in line
             oooc    0000           Prev:       dw           0                       ;  Previous module
             OOOE    FF             remov:      db           Offh                    ;  remove flag set
             OOOF    00             nonbnk:     db           0
             0010    4543484F56                 db           'ECHOVERS'
             0018    000000                     db           0 to to





                [)I(;i rA[.  RE@EAR('.H
                                                                                                                                 4-23

   4.4   Construction of an RSX Program                       CP/M 3 Programmer's Guide

                    ftest:                               i is this function 12?
   001B  79                   mov      aic
   001C  FEOC                 c P i    1 2
   OOIE  CA2400               iz       begin             ; Yes - intercept
   0021  C30900               imp      next              ; some other function
                    b e I i n :
   0024  210000               1 x i    h PO
   0027  39                   dad      SP                ; save stack
   0028  225400               shld     ret$stack
   002B  317600               lxi      sptloc$stack

   002E  DE09                 m v i    ctpstrinf
   0030  113EOO               Ixi      dttest$msi        ; Print message
   0033  CDO900               call     next              ; call BDOS

   0036  2A5400               lhld     ret$stack         ; restore user stack
   0039  F9                   sphl
   003A  213100               Ixi      hoOO31h           ; return version number
   003D  C9                   r e t

                    test$msg:
   003E  ODOA2A2A2A           db       crtlft'**** ECHOVERS ****$,
                    ret$stack:
   0054  0000                 dw       0
   0056                       ds       32                  16 level stack
                    loc$stack:
   0076                       end








                                                                         9 DIGITAL RESEARCH"
   4-24

       CP/M 3 Programmer's Guide              4.4 Construction of an RSX Program

       You can prepare the above programs for execution as follows:

         1. Assemble the CALLVERS program using MAC as follows:
            MAC CALLVERS
         2. Generate a COM file for CALLVERS with HEXCOM:
            HEXCOM CALLVERS
         3. Assemble the RSX program ECHOVERS using RMAC:
            RMAC ECHOYERS
         4. Generate a PRL file using the LINK command:
            LINK ECHOVERS [OPI
         S. Rename the PRL file to an RSX file:
            RENAME ECHOVERS*RSX=ECHOVERS.PRL
         6. Generate a COM file with an attached RSX using the GENCOM command:
            GENCOM CALLVERS ECHOVERS
         7. Run the CALLVERS.COM module:
            CALLVERS
            T'he message
            **** CALLVERS
            followed by the message
            **** ECHOVERS ****
            appears on the screen five times if the RSX program works.

                                 End of Section 4








       19 DIGITAL RESEARCH"
                                                                          4-25

                                      Appen ix A

                             System Control Block



          The System Control Block (SCB) is a CP/M 3 data structure located in the BDOS.
       CP/M 3 uses this region primarily for communication between the BDOS and the
       BIOS.  However, it is also available for communication between application pro-
       grams, RSXS, and the BDOS.  Note that programs that access the System Control
       Block are not version independent.  They can run only on CP/M 3.

          The following list describes the fields of the SCB that are available for access by
       application programs and RSXS.  The location of each field is described as the offset
       from the start address of the SCB (see BDOS Function 49).  The RW/RO column
       indicates if the SCB field is Read-Write or Read-Only.

                              Table A-1.  SCB Fields and Definitions
           OffsetTRWIRO                                   Definition

         00 - 04         RO         Reserved for system use.

         05              RO         BDOS Version Number.

         06 - 09         RW         Reserved for user use. Use these four bytes for your
                                    own flags or data.

         OA - OF         RO         Reserved for system use.

         10 - 11         RW         Program Error Return Code. This 2-byte field can be
                                    used by a program to pass an error code or value to a
                                    chained program.  CP/M 3's conditional command facil-
                                    ity also uses this field to determine if a program exe-
                                    cutes successfully.  The BDOS Function 108 (Get/Set
                                    Program Return Code) is used to get/set this value.

         12 - 19         RO         Reserved for system use.





       R DIGITAL RESEARCH"
                                                                                          A-1

   A Svstem Control Block                                  CP/M 3 Programmer's Guide


                                  Table A-1. (continued)

       Offset T-RW/RO I                                Definition

     1A               RW         Console Width. This byte contains the number of col-
                                 umns, characters per line, on your console relative to
                                 zero.  Most systems default this value to 79.  You can
                                 set this default value by using the GENCPM or the
                                 DEVICE utility.  The console width value is used by the
                                 banked version of CP/M 3 in BDOS function 10,,
                                 CP/M 3's console editing input function.  Note that typ-
                                 ing a character into the last position of the screen, as
                                 specified by the Console Width field, must not cause
                                 the terminal to advance to the next line.

     1B               RO         Console Column Position. This byte contains the cur-
                                 rent console column position.

     ic               RW         Console Page Length. This byte contains the page length,
                                 lines per page, of your console.  Most systems default
                                 this value to 24 lines per page.  This default value may
                                 be changed by using the GENCPM or the DEVICE util-
                                 ity (see the CPIM Plus (CPIM Version 3) Operating
                                 System User's Guide).

     1D - 21          RO         Reserved for system use.

     22 - 2B          RW         Redirection flags for each of the five logical character
                                 devices.  If your system's BIOS supports assignment of
                                 logical devices to physical devices, you can direct each
                                 of the five logical character devices to any combination
                                 of up to 12 physical devices.  The 16-bit word for each
                                 device represents the following:
                                 Each bit represents a physical device where bit 15 cor-
                                 responds to device zero and bit 4 corresponds to device
                                 11. Bits zero through 3 are reserved for system use.
                                 You can redirect the input and output logical devices
                                 with the DEVICE command (see CP/M Plus (CP/M
                                 Version 3) Operating System User's Guide).




                                                                     R DIGITAL RLSEARCH"
    A-2

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

                                           Table A-1. (continued)

              Offset       RW/RO                                   Definition

           22 - 23           RW          CONIN Redirection Flag.

           24 - 25           RW          CONOUT Redirection Flag.

           26 - 27           RW          AUXIN Redirection Flag.

           28 - 29           RW          AUXOUT Redirection Flag.

           2A - 2B           RW          LSTOUT Redirection Flag.

           2C                RW          Page Mode. If this byte is set to zero, some CP/M 3
                                         utilities and CCP built-in commands display one page
                                         of data at a time; you display the next page by pressing
                                         any key.  If this byte is not set to zero, the system dis-
                                         plays data on the screen without stopping.  To stop and
                                         start the display, you can press CTRL-S and CTRL-Q,
                                         respectively.

           2D                RO          Reserved for system use.

           2E                RW          Determines if CTRL-H is interpreted as a rub/del char-
                                         acter.  If this byte is set to 0, then CTRL-H is a back-
                                         space character (moves back and deletes).  If this byte is
                                         set to OFFH, then CTRL-H is a rub/del character, echoes
                                         the deleted character.

           2F                RW          Determines if rub/del is interpreted as CTRL-H charac-
                                         ter.  If this byte is set to 0, then rub/del echoes the deleted
                                         character.  If this byte is set to OFF, then rub/del is inter-
                                         preted as a CTRL-H character (moves back and deletes).

           30 - 32           RO          Reserved for system use.

           33 - 34           RW          Console Mode. This is a 16-bit system parameter that
                                         determines the action of certain BDOS Console 1/0
                                         functions. (See Section 2.2.1 and BDOS Function 109,
                                         Get/Set Console Mode, for a thorough explanation of
                                         Console Mode.)

          Ec DIGITAL RESEARCH  TM
                                                                                                     A-3

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

                                  Table A-1. (continued)
      Offset       RW/RO I                              Definition

    35 - 36           RO        Reserved for system use.

    37                RW        Output delimiter character. The default output delim-
                                iter character is $, but you can change this value by
                                using the BDOS Function 110, Get/Set Output Delimiter.

    38                RW        List Output Flag. If this byte is set to 0, console output
                                is not echoed to the list device.  If this byte is set to 1
                                console output is echoed to the list device.

    39 - 3B           RO        Reserved for system use.

    3C - 3D           RO        Current D@ Address. This address can be set by BDOS
                                Function 26 (Set DMA Address).  The CCP initializes
                                this value to 0080H.  BDOS Function 13, Reset Disk
                                System, also sets the DMA address to 0080H.

    3E                RO        Current Disk. This byte contains the currently selected
                                default disk number.  This value ranges from 0-15 cor-
                                responding to drives A-P, respectively.  BDOS Function
                                25, Return Current Disk, can be used to determine the
                                current disk value.

    3F - 43           RO        Reserved for system use.

    44                RO        Current User Number. This byte contains the current
                                user number.  This value ranges from 0-15.  BDOS Func-
                                tion 32, Set/Get User Code, can change or interrogate
                                the currently active user number.

    45 - 49           RO        Reserved for system use.

    4A                RW        BDOS Multi-Sector Count. This field is set by BDOS
                                Function 44,, Set Multi-Sector Count.





                                                                      'ED DIGITAL RESEARCH'M
  A-4

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

                                        Table A-1. (continued)

            Offset       RWIRO                                Defint.tion

          4B               RW         BDOS Error Mode. This field is set by BDOS Function
                                      45, Set BDOS Error Mode.
                                      If this byte is set to OFFH, the system returns to the
                                      current program without displaying any error messages.
                                      If it is set to OFEH, the system displays error messages
                                      before returning to the current program.  Otherwise, the
                                      system terminates the program and displays error mes-
                                      sages.  See description of BDOS Function 45, Set BDOS
                                      Error Mode, for discussion of the different error modes.

          4C     4F        RW         Drive Search Chain. The first byte contains the drive
                                      number of the first drive in the chain, the second byte
                                      contains the drive number of the second drive in the
                                      chain, and so on, for up to four bytes.  If less than four
                                      drives are to be searched, the next byte is set to OFFH
                                      to signal the end of the search chain.  The drive values
                                      range from 0-16, where 0 corresponds to the default
                                      drive, while 1-16 corresponds to drives A-P, respec-
                                      tively.  The drive search chain can be displayed or set
                                      by using the SETDEF utility (see CPIM Plus (Version 3)
                                      Operating System User's Guide).

          50               RW         Temporary File Drive. This byte contains the drive
                                      number of the temporary file drive.  The drive number
                                      ranges from 0-16, where 0 corresponds to the default
                                      drive, while 1-16 corresponds to drives A-P, respectively.

          51               RO         Error drive. This byte contains the drive number of the
                                      selected drive when the last physical or extended error
                                      occurred.

          52 - 56          RO         Reserved for system use.








        9 DIGITAL RESEARCH'-
                                                                                             A-5

  A S),stem Control Block                                  CP/M 3 Programmer's Guide

                                 Table A-1. (continued)
     Offset       RW/RO                                Definition

    57               RO        BDOS Flags. Bit 7 applies to banked systems only. If
                               bit 7 is set, then the system displays expanded error
                               messages.  The second error line displays the function
                               number and FCB information. (See Section 2.3.13).
                               Bit 6 applies only to nonbanked systems.  If bit 6 is set,
                               it indicates that GENCPM has specified single alloca-
                               tion vectors for the system.  Otherwise, double alloca-
                               tion vectors have been defined for the system.  Function
                               98, Free Blocks, returns temporarily allocated blocks to
                               free space only if bit 6 is reset.

    58 - 59          RW        Date in days in binary since 1 Jan 78.

    5A               RW        Hour in BCD (2-digit Binary Coded Decimal).

    5B               RW        Minutes in BCD.

    5C               RW        Seconds in BCD.

    5D - 5E          RO        Common Memory Base Address. This value is zero for
                               nonbanked systems and nonzero for banked systems.

    5F - 63          RO        Reserved for system use.


                                    End of Appendix A








                                                                      Fiol DIGITAL RESEARC:H"'
   A-6

                                           ppenaix

                               PRL File Generation



       B. 1 PRL Format

         A Page Relocatable Program has an origin offset of 100H bytes that is stored on
       disk as a file of type PRL.  The format is shown in Table B-1.

                                    Table B-1.  PRL File Format

           Address      7-                                Contents

        000 1-0002H            Program size

        0004-0005H             Minimum buffer requirements (additional memory)

        0006-OOFFH             Currently unused, reserved for future allocation

        0100 + Program size = Start of bit map


         The bit map is a string of bits identifying those bytes in the source code that
       require relocation.  There is one byte in the bit map for every 8 bytes of source code.
       The most significant bit, bit 7, of the first byte of the bit map indicates whether or
       not the first byte of the source code requires relocation.  If the bit is on, it indicates
       that relocation is required.  The next bit, bit 6, of the first byte corresponds to the
       second byte of the source code, and so forth.








       4V t)i(;ITAL RESEAR(,H"
                                                                                              B-1

   B PRL Generation                                   CP/M 3 Programmer's Guide

   B.2 Generating a PRL

     The preferred technique for generating a PRL file is to use the CP/M LINK-80",
   which can generate a PRL file from a REL relocatable object file.  This technique is
   described in the Programmer's Utilities Guide for The CPIM Family of Operating
   Systems.  A sample link command is shown below.

   A>Iink dumpropi

                                 End of Appendix B








                                                               B DIGITAL RESEARCH"
   B-2

                                       Appendix C

                                   SPR Generation



          System Page Relocatable, SPR, files are similar in format to PRL files except that
        SPR files have an origin offset of OOOOH (see Appendix B).  SPR Files are provided as
        part of the standard CP/M 3 System: the resident and banked portions of the banked
        BDOS, named RESBDOS3.SPR and BNKBDOS3.SPR, and the nonbanked BDOS,,
        named BDOS3.SPR. The customized BIOS must also be generated in SPR format
        before GENCPM can create a CP/M 3 system.  The BIOS SPR file is named
        BNKBIOS3.SPR for banked systems and BIOS3.SPR for nonbanked systems.  A detailed
        discussion of the generation of BIOS3.SPR or BNK-BIOS3.SPR is provided in the
        CPIM Plus (CP/M Version 3) Operating System System Guide.

          The method of generating an SPR is analogous to that of generating a Page Relo-
        catable Program (described in Appendix B) with the following exceptions:

            s If LINK-80 is used, the output file of type SPR is specified with the [os] or [b]
               option.  The [b] option is used when linking BNKBIOS3.SPR.
            0 'ne code in the SPR is ORGed at OOOH rather than 100H.


                                          End of Appendix C








          DIGITAI- RESEARCH Tl
                                                                                             C-1

                                         Appendix D

              ASCII and Hexadecimal Conversions



          This appendix contains tables of the ASCII symbols, including their binary, deci-
        mal, and hexadecimal Conversions.

                                      Table D-1.  ASCII Symbols
          Symbol7                Meaning              Symbol                      Meaning

          ACK              acknowledge                   FS                file separator
          BEL              bell                          GS                group separator
          BS               backspace                     HT                horizontal tabulation
          CAN              cancel                        LF                line-feed
          CR               carriage return               NAK               negative acknowledge
          DC               device control                NUL               null
          DEL              delete                        RS                record separator
          DLE              data link escape              Si                shift in
          EM               end of medium                 so                shift out
          ENQ              enquiry                       SOH               start of heading
          EOT              end of transmission           SP                space
          ESC              escape                        STX               start of text
          ETB              end of transmission           SUB               substitute
          ETX              end of text                   SYN               synchronous idle
          FF               form-feed                     us                unit separator
                                                         VT                vertical tabulation








          DL(;ITAL RESEAR(-H'-
                                                                                               D-1

  D ASCII and HEX Conversions                          CP/M 3 Programmer's Guide

                        Table D-2.  ASCII Conversion Table
    Binary             Decimal            Hexadecimal                 ASCII

    0000000               000                   00                NUL
    0000001               001                   01                SOH (CTRL-A)
    0000010               002                   02                STX (CTRL-B)
    0000011               003                   03                ETX (CTRL-C)
    0000100               004                   04                EOT (CTRL-D)
    0000101               005                   05                ENQ (CTRL-E)
    0000110               006                   06                ACK  (CTRL-F)
    0000111               007                   07                BEL  (CTRL-G)
    0001000               008                   08                BS   (CTRL-H)
    0001001               009                   09                HT   (CTRL-I)
    0001010               010                   OA                LF   (CTRL-J)
    0001011               Oil                   OB                VT   (CTRL-K)
    0001100               012                   oc                FF   (CTRL-L)
    0001101               013                   OD                CR   (CTRL-M)
    0001110               014                   OE                SO   (CTRL-N)
    0001111               015                   OF                SI   (CTRL-0)
    0010000               016                   10                DLE  (CTRL-P)
    0010001               017                   it                DC1  (CTRL-Q)
    0010010               018                   12                DC2  (CTRL-R)
    0010011               019                   13                DC3  (CTRL-S)
    0010100               020                   14                DC4  (CTRL-T)
    0010101               021                   15                NAK (CTRL-U)
    0010110               022                   16                SYN (CTRL-V)
    0010111               023                   17                ETB (CTRL-W)
    0011000               024                   18                CAN (CTRL-X)
    0011001               025                   19                EM   (CTRL-Y)
    0011010               026                   1A                SUB  (CTRL-Z)
    0011011               027                   IB                ESC  (CTRL-[)
    0011100               028                   ic                FS   (CTRL- \)
    0011101               029                   1D                GS   (CTRL-1)
    0011110               030                   1E                RS   (CTRL--)
    0011111               031                   1F                US   (CTRL-_)
    0100000               032                   20                (SPACE)
    0100001               033                   21                  1
    0100010               034                   22
    0100011               035                   23
    0100100               036                   24                  $


                                                                UG DIGITAL RESEAR(.Hrm
   D-2

      CP/M I Progrimner's Guide                   D ASCII and HEX Conv

                                Table D-2. (continued)                  ersions


        Binary           Decimal          Hexadecimal           ASCII

       0100101             037                25                    %
       0100110             038                26                    &
       0100111             039                27
       0101000             040                28
       0101001             041                29
       0101010             042                2A
       0101011             043                2B
       0101100             044                2C
       0101101             045                2D
       0101110             046                2E
       0101111             047                2F
       0110000             048                30                    0
       0110001             049                31                    1
       0110010             050                32                    2
       0110011             051                33                    3
       0110100             052                34                    4
       0110101             053                35                    5
       0110110             054                36                    6
       0110111             05S                37                    7
       0111000             056                38                    8
       0111001             057                39                    9
       0111010             058                3A
       0111011             059                3B
       0111100             060                3C                    <
       0111101             061                3D
       0111110             062                3E                    >
       0111111             063                3F                    ?
       1000000             064                40                    @
       1000001             065                41                    A
       1000010             066                42                    B
       1000011             067                43                    c
       1000100             068                44                    D
       1000101             069                45                    E
       1000110             070                46                    F
       1000111             071                47                    G
       1001000             072                48                    H
       1001001             073                49                    1


      k DIGITAL RESEARCHT@                                                D-3

  D ASCII and HEX Conversions                    CP/M 3 Programmer's Guide

                            Table D-2. (continued)
     Binary          Decimal          Hexadecimal            ASCII
    1001010            074                 4A                    i
    1001011            075                 4B                    K
    1001100            076                 4C                    L
    1001101            077                 4D                    m
    1001110            078                 4E                    N
    1001111            079                 4F                    0
    1010000            080                 50                    p
    1010001            081                 51                    Q
    1010010            082                 52                    R
    1010011            083                 53                    s
    1010100            084                 54                    T
    1010101            085                 55                    u
    1010110            086                 56                    v
    1010111            087                 57                    w
    1011000            088                 58                    x
    1011001            089                 59                    y
    1011010            090                 SA                    z
    1011011            091                 5B
    1011100            092                 5C
    1011101            093                 5D
    1011110            094                 5E
    1011111            095                 5F                    <
    1100000            096                 60
    1100001            097                 61                    a
    1100010            098                 62                    b
    1100011            099                 63                    c
    1100100            100                 64                    d
    1100101            101                 65                    e
    1100110            102                 66                    f






  D-4                                                    9 DIGITAL RESEAR(:H"'

      CPIM I Programmer's Guide                    D ASCII and HEX Conversions

                                Table D-2. (continued)
                  -T     Decimal     T-    Hexadecimal     F-     ASCII
         Binary
        1100111             103                67                     9
        1101000             104                68                     h
        1101001             105                69
        1101010             106                6A
        1101011             107                6B                     k
        1101100             108                6C                     I
        1101101             109                6D                     m
        1101110             110                6E                     n
        1101111             ill                6F                     0
        1110000             112                70                     p
        1110001             113                71                     q
        1110010             114                72                     r
        1110011             115                73                     s
        iiioioo             116                74                     t
        1110101             117                75                     u
        1110110             118                76                     v
        1110111             119                77                     w
        1111000             120                78                     x
        1111001             121                79                     y
        1111010             122                7A                     z
        1111011             123                7B
        1111100             124                7C
        1111101             125                7D
        1111110             126                7E
        iiiiiii             127                7F                     DEL


                                   End of Appendix D








       9 L)IGITAL RESEARCH'-
                                                                            D-5

                                            ppenaix
                                                    0
                         BDOS Function Summary



                                Table E-1.  BDOS Function Summary

         Function         Function Name           Input Parameters          Returned Values

            0         System Reset                none                 none
            1         Console Input               none                 A  =  Char
            2         Console Output              E =   char           A  =  OOH
            3         Auxiliary Input             none                 A  =  char
            4         Auxiliary Output            E =   char           A  =  OOH
            5         List Output                 E =   char           A  =  OOH
            6         Direct Console 1/0          E =   OFFH/          A  =  char/status/
                                                        OFEH/                none
                                                        OFDH/
                                                        char
            7         Auxiliary Input             none                 A =   OO/OFFH
                      Status
            8         Auxiliary Output            none                 A =   OO/OFFH
                      Status
            9         Print String                DE =     String      A =   OOH
           10         Read Console Buffer         DE =     BufferO     Characters in buffer
           11         Get Console Status          none                 A = 00/01
           12         Return Version Number       none                 HL = Version (0031H)
           13         Reset Disk System           none                 A = OOH
           14         Select Disk                 E     =  Disk        A  =  Err Flag
                                                  Number
           15         Open File                   DE =     FCB         A  =  Dir Code
           16         Close File                  DE =     FCB         A  =  Dir Code
           17         Search for First            DE =     FCB         A  =  Dir Code
           18         Search for Next             none                 A  =  Dir Code
           19         Delete File                 DE =     FCB         A  =  Dir Code
           20         Read Sequential             DE =     FCB         A  =  Err Code
           21         Write Sequential            DE =     FCB         A  =  Err Code
           22         Make File                   DE =     FCB         A  =  Dir Code
           23         Rename File                 DE =     FCB         A  =  Dir Code
           24         Return Login Vector         none                 HL = Login Vector
           25         Return Current Disk         none                 A = Cur Disk#

           1)1(.I'I'Al- RESEAR('H
                                                                                               E-1

  E BDOS Function Summary                                 CP/M 3 Programmer's Guide

                                 Table E-1. (continued)

   Function    Function Name              Input Parameters    Returned Values

     25        Return Current Disk        none                A = Cur Disk#
     26        Set DMA Address            DE =   DMA          A = OOH
     27        Get Addr(Alloc)            none                HL = Alloc
     28        Write Protect Disk         none                A = OOH
     29        Get R/O Vector             none                HL = R/O Vector
     30        Set File Attributes        DE =   FCB          A = Dir Code
     31        Get Addr(DPB)              none                HL = DPB
     32        Set/Get User Code          E = OFFH/           A = Curr User/
                                               user number         OOH
     33        Read Random                DE  = FCB           A =  Err Code
     34        Write Random               DE  = FCB           A =  Err Code
     35        Compute File Size          DE  = FCB           rO, rl, r2
                                                              A = Err Flag
     36        Set Random Record          DE  =  FCB          rO, rl, r2
     37        Reset Drive                DE  =  Drive        A = OOH
                                          Vector
     38        Access Drive               none                A  = OOH
     39        Free Drive                 none                A  = OOH
     40        Write Random with          DE =   FCB          A  = Err Code
               Zero Fill
     41        Test and Write Record      DE =   FCB          A  = OFFH
     42        Lock Record                DE =   FCB          A  = OOH
     43        Unlock Record              DE =   FCB          A  = OOH
     44        Set Multi-sector Count     E = # Sectors       A  = Return Code
     45        Set BDOS Error Mode        E = BDOS Err        A  = OOH
                                          Mode
     46        Get Disk Free Space        E = Drive           Number of Free Sectors
                                          number              A = Err Flag
     47        Chain to Program           E = Chain Flag      A = OOH
     48        Flush Buffers              E = Purge Flag      A = Err Flag
     49        Get/Set System             DE = SCB PB         A = Returned Byte
               Control Block                                  HL = Returned Word
     50        Direct BIOS Calls          DE = BIOS PB        BIOS Return
     59        Load Overlay               DE = FCB            A = Err Code
     60        Call Resident System       DE = RSX PB         A = Err Code
               Extension

    Note: . indicates the address of

                                                                   IN DIGITAL RESEARCH"
   E-2

        CP/M 3 Programmer's Guide                               E   BDOS Function Summary

                                       Table E-1. (continued)
          Function I Function Name              Input Parameters
                                             I                      Returned Values
            98       Free Blocks                none                A = Err Flag
            99       Truncate File              DE = FCB            A = Dir Code
          100        Set Directory Label        DE = FCB            A  =  Dir Code
          101        Return Directory           E = Drive           A  =  Dir label data byte
                     Label Data
          102        Read File Date Stamps      DE = FCB            A  =  Dir Code
                     and Password Mode
          103        Write File XFCB            DE  =  FCB          A  =  Dir Code
          104        Set Date and Time          DE  =  DAT          A  =  OOH
          105        Get Date and Time          DE  =  DAT          Date and Time
                                                                    A =   seconds
          106        Set Default Password       DE  =  Password     A = OOH
          107        Return Serial Number       DE  =  Serial       Serial Number
                                                       field
          108        Get/Set Program            DE  =  OFFFFH/      HL Program Ret Code
                     Return Code                Code                      none
          109        Get/Set Console Mode       DE =   OFFFFH/      HL = ConsoleMode
                                                Mode                       none
          110        Get/Set Output             DE =   OFFFFH/      A = OutputDclimiter
                     Dclimiter                    E =  Delimiter          none
          ill        Print Block                DE =   CCB          A =   OOH
          112        List Block                 DE =   CCB          A =   OOH
          152        Parse Filename             DE =   PFCB         See definition

          Note: . indicates the address of

                                         End of Appendix E






           Dl(,ITAI, RLSEAR(H@"                                                            E-3

                                       Index



       ? in filename error, 2-30            Basic  Disk operating System
       III filetype, 1-27                      See BDOS
                                            Basic  Input/Output System
       A                                       See BI[OS
                                            basic  record size, 2-7
       absolute module, 3-73                BDOS,  1-6, 1-8, 1-11, 1-14
       access                                  calling conventions, 2-1
         date and time stamp, 3-21             Call Resident System
         stamp types, 2-24                       Extension (RSX), 1-24
       ACCESS DRIVE, 3-57                      chain to program call, 1-23
       address, maximumm, 1-5                  directory codes, 2-32
       allocation vector,   2-27 ,             directory functions, 2-7
           3-41 , 3- 75                        drive-related functions, 2-7
       ambiguous file reference,               error codes, 2-31
           1-13, 2-16, 3-24, 3-27              error flags, 2-33
       archive attribute, 2-17                 error mode, 2-29
       ASCII character file, 1-18              extended error codes, 2-34
       ASM'- , 2-11                            file access functions, 2-7
       assembler source, 2-11                  file system, 2-7, 2-11
       associated command files,    1-18       miscellaneous functions, 2-7
       asterisk, 1-13, 2-11                    physical errors, 2-34
       attribute bits, 2-16                    read character, 2-3
       attributes                              write character, 2-3
         set file, 2-22                     BDOS  base, 1-8 to 1-11
       automatic submit, 1-19               bell character, 3-12
       Auxiliary Input, 3-4                 binary zero terminator, 3-12
       Auxiliary Input Status,     3-9      BIOS, 1-6, 1-7, 1-14, 2-29
       Auxiliary Output, 3-5                   cold start, 1-15
       Auxiliary Output Status, 3-10           DEVRBL entry point, 2-2
       AUXIN, 2-2, 2-6, 3-4, 3-9               entry points, 1-7
       AUXO(JT, 2-2, 2-6, 3-5, 3-10            Parameter Block, 3-72
                                               warm start, 1-15
       B                                    BIOS base, 1-8, 1-10, 1-15
                                            BIOS-PB, 3-72
       backspace, 3-2                       bit map, B-1
       BAK, 2-11                            bit vector, 3-43
       Bank 0, 1-3                          blocking, record, 3-63
         in context,  1-3                   block size, 2-11
         switched in,    1-3                Boolean fields, 2-16
       Bank 1, 1-3, 1-4                     buffers, 1-4
       banked, 1-2, 1-11                       disk, 1-2
         memory, 1-3                        built-in command, 1-8, 1-16
         operating system module, 1-3       byte, 2-1
         system, 1-3                        byte count, 2-28
         version requirements, 1-5
       bank-switching, 1-4                  c
       bank-switched memory, 1-1, 1-3
       BAS, 2-11                            Call BIOS, 1-22
       base address, 1-21                   Call Resident System
       base extent, 3-48,   3-50                 Extension (RSX), 3-74
       basic console I/O,   2 -3

                                      Index-1

   calling program, 2-15                      input, 2-3, 3-2
      return to, 2-28                         output, 2-3, 3-3
   carriage return,     2-13, 3-2             page length, 3-70
   CCB, 3-94, 3-95                            status, 2-3, 3-8
   CCP                                        string output, 2-3
      description 1-7, 1-8,                   width, 3-70
        1-11, 1-13                          Console Command Processor,
      location, 1-6, 1-15                     See CCP
      operation, 1-16 to 1-28               Console Input, 3-2
      user number, 2-18                     Console Mode, 2-5, 3-91
   CCP.COM, 1-15                              default state, 3-2
   CCP command form, 1-16                   Console Output, 3-3
   chain flag, 3-67                         control character ('), 2-5
   Chain To Program, 3-67                   COPY, 4-1
   change default drive, 1-16               copy file, 1-12, 4-1
   character   block, 2-2                   CP/M, 1-1, 1-2
   Character   Control Block                CP/M 2, 1-28, 2-1
      See CCB                               CPM3.SYS file, 1-14
   character   echo, 2-3                    CPMLDR, 1-14, 1-15
   character   string,   2-2                CPMLDR BDOS, 1-14
   check-sum   vector,   2 -27              CPU registers, 1-22
   Close File, 2-17,     3 -2 2             or field, 3-29, 3-31, 3-34
   cold boot, 1-14                          create
   Cold Boot Loader,     1-14                 date and time stamp, 3-35
   cold start, 1-14,     1-15,  1-16          directory entry, 3-34
   COM, 2-11                                  directory label, 3-78
      filetype, 1-19                          stamp types, 2-24
   command,                                   XFCB,   3- 34
      drive field, 2-37                     CTRL-A,   3-14
      field, 1-20                           CTRL-B,   3-14
      keyword, 1-17                         CTRL-C,   1-22, 2-4, 2-5,
   Command File, 2-11                            3-13, 3-14
   command line, 1-17                         reboot, 3-13
      characters, 2-38                      CTRL-E, 3-13, 3-14, 3-15
   command tail, 1-16                         end of line, 3-13
      parsing, 1-17                         CTRL-F, 3-14
   common memory, 1-3,      1-5             CTRL-G, 2-4,    3-14
      base address, 3-71                    CTRL-H, 3-2,    3-13, 3-14
      region, 1-3                             backspace,    3-13
   common region, 1-3                       CTRL-I,   3-2,  3- 3
      size, 1-5                             CTRL-J,   3-13,   3-15
   compatibility, 1-22, 1-28                  line   feed,  3-13
   compatibility between CP/M 3             CTRL-K,   3-15
        and MP/M, 3-61, 3-62                CTRL-M,   3-13,   3-15
   Compute File Size, 2-28, 3-53            CTRL-P,   2-4,  2-5, 3-2, 3-3,
   conditional command, 1-23                     3-13, 3-15
   conditional status, 2-6                    list device, 3-13
   configured memory size, 1-7              CTRL-Q,   2-4 , 2-5, 3 -2, 3-3
   CONIN, 1-7, 2-2, 2-3, 3-2,, 3-16         CTRL-R,   3-13, 3-15
   CONOUT, 2-2, 2-3, 3-3                      retype   line, 3-13
   console,                                 CTRL-S,   2-4, 2 -5, 3- 2, 3- 3
      block output, 2-3                     CTRL-U,   3-13, 3-15
      characteristics, 1-27                   remove line, 3-13
      column position, 3-70                 CTRL-W,   3-15
      I/O functions, 2-3

                                     Index-2

        CTRL-X, 3-13, 3-15                      functions, 2-8
           beginning of line, 3-13              hash tables, 1-2, 1-4
        CTRL-Z, 2-3, 2-13                       space, 1-13
        curly brackets, 3-96                 directory label, 2-19, 2-20,
        current record, 2-15                    create, 3-78
        current record field   of the           data byte definition,
            FCB, 3-20                            3-78, 3-80
        current record position, 2-36           password, 2-21
        current user number, 1-28               update, 3-78
                                             DIRLBL.RSX, 1-25, 2-21, 3-78
        D                                    DIRSYS, 1-18
                                             disk, 1-11
        DAT, 2-11, 3-85                         access, 1-12
        data                                    change, 2-27
           area, 1-12, 1-13, 2-12               current, 3-71
           block, 2-11, 2-12, 3-75              default, 1-15, 3-19
        data base management system,            directory area, 2-12
            4-19                                drive organization, 1-12
        Data File, 2-11                         formatting program, 1-22
        data tracks,                            I/O error, 2-28, 2-29
           directory area, 1-12                 record buffers, 1-2, 1-4
           data area, 1-12                      select, 2-29
        date and time stamping,    2-20 ,       space, 1-13
            2-23, 2-25, 3-35,                Disk Parameter Block
            3-81, 3-85                            (DPB), 3-46
        DATE utility, 2-25                   Disk Reset, 2-27
        default                              DMA, 3-40
           disk, 1-15,  3-19                    address, 3-71
           @ buffer,    2-35                    buffer, 2-35
           drive, 1-16, 1-28                    default address, 2-38
           FCB, 2-37                         DPB (Disk Parameter
           mode, 3-64                             Block), 3-46
           output delimiter,  3-93           drive,
           password, 2-23, 3-87                 access, 3-57
        Default Error Mode, 3-64                allocation vector, 2-27
        Delete File, 2-17, 2-22,    3- 27       capacity, 2-12
        delimiter, 1-17, 2-10,                  chain, 1-20
             3-11, 3-93                         code, 2-14
           file specification,   3- 97          default, 1-16, 1-28
        DEVICE utility, 2-2                     functions, 2-8
        differences: banked and                 read-only, 3-43
           nonbanked, 1-2                       reset, 3-56
        DIR, 1-18                               search chain, 3-71
        DIR.COM utility,   1-18                 select code, 2-9,
        Direct BIOS Calls, 1-22, 3-72           specification, 1-17, 1-20
        Direct Console I/O, 3-7                 specifier, 2-9
        Direct Memory Address                   support, 1-11
           (DMA), 3-40                       drive-related functions,
        directory                                     2-7, 2-8
           area, 1-12                        dump program, 4-5
           check-sum vector, 2-27            dynamic allocation, 1-13
           codes, 2-30, 2-32
           entries, 2-15




                                         Index-3

   E                                       size, 1-12, 2-12, 3-53
                                           space allocation, 1-13
   ED Source Backup, 2-11                  spec if icat ion, 2-9
   edit control characters,                types of, 2-11
     banked CP/M 3, 3-14                 file access functions, 2-7
     nonbanked CP/M 3, 3-13              File Control Block
   empty directory entry, 2-16             See FCB
   end-of-file, 1-26, 2-3                default, 2-36
   entry values, 2-1                     File Dump, 4-5
   environment, 1-7                      File Exists error, 2-30
   ERASE, 1-18                           filename, 1-13, 1-17, 2-9,
   errors, 2-30, 2-31                        2-11, 2-15
     ? in filename, 2-30                   ambiguous, 2-11
     extended, 2-29, 2-34                  parse, 3-96
     file exists, 2-30                   filespec, 1-17
     flag, 2-33                          filetype, 1-13, 1-17, 2-9,
     handling, 2-28                          2-11, 2-15
     invalid drive, 2-29                 floppy disk, 1-11
     messages, 2-29, 2-30                Flush Buffers, 2-25,
     mode, 2-29, 3-64, 3-71                  2-33, 3-68
     physical, 2-28, 2-29, 2-34          Free Blocks, 2-33, 3-75
     program code, 3-89                  Free Drive, 3-58
     read-only, 2-30                     free space, 1-13, 3-65
     return code, 3-70                   Function Calls-.
   extend operating system                 0: System Reset, 3-1
     functions, 1-9, 1-23                  1: Console Input, 3-2
   extended error codes, 2-29,             2: Console Output, 3-3
       2-30, 2-34,                         3: Auxiliary Input, 3-4
   extended FCB, 2-19                      4: Auxiliary Output, 3-5
   extent 0, 3-48, 3-50                    5: List Output, 3-6
   extent field format,   3-83             6: Direct console I/O, 3-7
   extent number, 2-14                     7: Auxiliary Input Status,
                                              3-9
   F                                       8: Auxiliary Output Status,
                                              3-10
   false status, 2-6                       9: Print String, 3-11
   FCB, 3-20                               10: Read Console Buffer, 3-12
     default, 2-36, 2-37                   11: Get Console Status, 3-16
     extent number field, 3-35             12: Return Version Number,
     format, 2-18, 3-98                        3-17
     length, 2-13                          13: Reset Disk System, 3-18
     parsed, 1-21                          14: Select Disk, 3-19
     random record field, 3-55             15: Open File, 3-20
   field, 1-19                             16: Close File, 3-22
   file                                    17: Search For First, 3-24
     access functions, 2-7                 18: Search For Next, 3-26
     attributes, 2-16                      19: Delete File, 3-27
     byte count, 2-28, 3-44                20: Read Sequential, 3-29
     directory elements, 2-15              21: Write Sequential, 3-31
     format, 2-13                          2 2: Make File, 3-34
     ident if icat ion, 1 -1 2             2 3: Rename File, 3-36
     naming conventions,   2-11            24: Return Login Vector, 3-38
     organization, 2-11                    25: Return Current Disk, 3-39
     passwords, 2-21                       2 6: Set @ Address, 3-40
     password error, 2-30                  27: Get ADDR(ALLOC), 3-41

                                  Index-4

            28:    Write Protect Disk, 3-42                          112: List Block, 3-95
            29:    Get Read-Only Vector,                             152: Parse Filename, 3-96
                   3-43
            30:    Set File Attributes, 3-44                      G
            31:    Get ADDR(DPB PARMS), 3-46
            3 2 :  Set/Get User Code,              3-47           GENCOM, 1-9, 1-24, 2-6
            3 3:   Read Random, 3-48                              GENCPM, 1-2, 1-16
            34:    Write Random, 3-50                             generic filetypes, 2-11
            3 5:   Compute File Size,              3-53           Ge t
            36:    Set Random Record,              3- 55             ADDR(ALLOC), 2-34, 3-41
            3 7:   Reset Drive, 3-56                                 ADDR(DPB PARMS), 3-46
            38:    Access Drive, 3-57                                  COM, 1-24, 1-26
            39:    Free Drive, 3-58                                  Console Status, 3-16
            40:    Write Random with Zero                            Da te a nd Ti me, 3- 86
                   Fi 1 1, 3- 59                                     Disk Free Space, 2-33,
            41:    Test and Write Record,                               3-41, 3-65
                   3-60                                              Output Delimiter, 3-93
            42:    Lock    Record, 3-61                              Program Return Code, 3-89
            43-    Unlock Record, 3-62                               Read-Only Vector, 3-43
            44:    Set Multi-Sector Count,                           RSX, 2-6
                   3-63                                               RSX, 1-24
            45:    Set BDOS Error Mode, 3-64                         User Code, 3-47
            46:    Get Disk Free Space,                 3-65         utility, 1-24, 1-26
            47:    Chain To Program, 3-67                         Get/Set
            48:    Flush Buffers, 3-6B                               Console Mode, 2-5, 3-91
            49:    Get/set system control                            Output Delimiter, 3-93
                   Block, 3-69                                       Program Return Code,
            50:    Direct BIOS Calls, 3-72                              1-23, 3-89, 3-90
            5 9:   Load Overlay, 3-73                                System Control Block, 3-69
            60:    Call Resident System                              User Code, 3-47
                   Extension, 3-74                                graphic characters, 3-2
            98:    Free Blocks, 3-75
            99:    Truncate File, 3-76                            H
            100:     Set directory Label,
                     3-78                                         hash table, 1-4, 2-27
            101:     Return Directory Label                          directory, 1-2
                     Data, 3-80                                   HEX, 2-11
            102:     Read File Date Stamps                        Hex Machine Code, 2-11
                     and Password Mode, 3-81                      highest memory address, 2-35
            103:     Write File XFCB, 3-83                        host computer's environment,
            104:     Set Date and Time, 3-85                            1-7
            105:     Get Date and Time, 3-86
            106:     Set Default Password,
                     3-87
            107:     Return Serial Number,                        information address, 2-1
                     3-88                                         INITDIR utility, 2-24, 3-79
            108:     Get/set Program Return                       initializing an FCB, 2-15
                     Code, 3-89                                   input buffer, 3-12
            109:     Get/Set Console Mode,                        INT, 2-11
                     3-91                                         Intel'& PL/M systems programming
            110:     Get/Set Output                                     language, 2-1
                     Delimiter, 3-93                              interface attribute, 2-17, 3-21
            111:     Print Block, 3-94                            Intermediate File, 2-11




                                                         Index-5

  internal date and time, 3-85          maximum
  Invalid Drive error, 2-29               file size, 2-11
  invalid function calls, 2-1             memory, 1-2
                                          memory address, 1-10
                                          record count, 3-53
                                          TPA address, 1-21
  jump instructions, 1-25               media change, 2-27
                                        memory, 1-2
  K                                       banked, 1-3
                                          base address,   1-10
  key fields, 3-55                        loading, 1-14
                                          logical, 1-5
  L                                       map, 1-14
                                          maximum, 1-2
  length, 1-21, 2-23                      minimum, 1-2
  line editing, 2-4                       organization, 1-1, 1-2
  line feed, 2-13, 3-2                    regions, 1-9, 1-10
  LINK-80@- , B-2                         size configured, 1-7
  List Block, 3-95                        space, 1-2
  list device, 2-4,   3-2                 top of, 1-10
  List Output, 3-6                      miscellaneous functions, 2-7
  LOADER  base, 1-9,  1-11              modify file attribute, 3-44
  LOADER module, 1-6, 1-9, 1-11,          operating system
      1-21, 1-23, 1-24,                     functions, 1-9, 1-24
      3-73, 4-21                          other functions, 2-5
  Load Overlay, 1-9, 1-24, 3-73         modules, 1-6
  load RSX, 1-9, 1-24                     of operating system, 1-5
  Lock Record, 3-61                     MP/M, 1-19, 1-28,
    MP/M, 3-61                              2-1, 3-17
  logged-in, 2-27                       multi-sector count, 2-26,
  logical,                                  3-29, 3-63, 3-71
    auxiliary input device, 2-2         Multi-Sector I/O, 2-26
    auxiliary output device, 2-2        multi-user operating system,
    AUXIN, 2-2                              1-19, 1-28
    AUXOLJT, 2-2                        multiple file reference, 1-13
    CONIN,  2-2
    CONOUT, 2-2                         N
    console input device, 2-2
    console output device, 2-2          next record, 3-55
    device names, 2-2                   nibble, 1-28
    drive, 1-11, 2-11, 2-12             nonbanked memory organization,
    list device, 3-6                        1-2
    list output device, 2-2             nonbanked systems, 1-1
    LST, 2-2                            nonsupported function number,
    memory organization, 1-5                2-1
    record size, 2-25                   null byte, 3-67
  LST, 2-4, 2-6                         null command file, 1-24
  LST:, 3-2, 3-6, 3-95
                                        0
  m
                                        OFFSET parameter, 3-69
  Make File, 2-15, 2-17,                Open File, 2-16, 3-20
       2-21, 3-34                       operating system modules,
                                          banked, 1-3,
                                          resident, 1-3

                                  Index-6

        output delimiter, 3-70, 3-93            printer echo, 2-4, 2-5, 3-2
        overlay, 3-73                           printer listing, 2-11
                                                Print String, 3-11
        p                                       PRL file, 1-19, 1-24,
                                                     2-11, 3-73
        page,                                   PRL File Format, B-1
          alignment, 1-10                       PRN, 2-11
          boundaries, 1-10                      PROFILE.SUB, 1-15
          mode, 3-70                            PROFILE submit file, 1-15
        Page Relocatable file, 1-19,            program chain, 1-23, 3-67
            1-24, 2-11                          Program Return Code,
        Page Zero, 1-6, 1-7, 1-15,                   1-23, 3-89
            1-21, 1-22, 1-25, 1-28              PUNCH, 2-6
          areas, 2-35                           Purge Flag, 3-68
          fields, 1-21, 2-38
          initialize, 1-15, 2-34 to 2-38
          interface, 1-28
        Parameter Block                         question mark, 1-13, 2-11
          BIOS, 3-72
          RSX, 3-74                             R
          SCB, 3-69                             RANDOM, 4-10
        parameter substitutions, 1-27
        parse,                                  random
          procedure, 1-19                         access program, 4-10
        parsed FCB, 1-21                          access processing, 4-11
        Parse Filename, 3-96                      file, 2-12
        Partial Close, 2-17,    3-22              record, 3-55
        password, 1-17, 1-20,                     record number   , 2-12, 2-15
            2-21, 3-83,                           record position, 2-36
          assign, 2-17                          read
          default, 2-23, 3-87                     character, 3-2
          field, 2-9, 2-10, 2-35                  edited console input, 3-12
          length, 2-23, 2-35, 2-36                file date stamps and password
          mode, 3-81                                 mode, 3-81
          protection, 1-13, 2-22,      3- 33 ,    next record, 3-29
            3-34, 3-87                          Read Buffer Input, 2-4
          support, 1-1                          Read Console Buffer, 3-12
          testing, 2-22                         READER, 2-6
        Password Protection Modes,      2-22    Read File Date Stamps and
        permanent close operation,      3-22         Password Mode,    3-81
        physical                                Read-Only, 3-42
          drive, 1-11                             attribute, 2-16
          error,  2-29, 3-33                      Disk error, 2-30
          error  codes, 2-34, 3-19,               drives, 3-43
               3-21 , 3-25                        File error, 2-30
          file size, 3-53                       Read Random, 2-30, 3-48
          memory, 1-2                           Read Sequential, 2-30,
          record size, 2-25                          3-29, 3-48
          write operations, 2-25                Read-Write, 3-42
        PIP command, 1-12                       record, 2-12, 3-60
        PIP utility, 2-17                         blocking, 2-25, 3-63
        PL/I Source File,    2-11                 count, 2-14
        PL/M, 2-1                                 deblocking, 2-25
        Print Block, 2-3,    3-94                 lock , MP/M, 3-61
        Print String, 2-3,    2-5,  3-11          size, 2-7

                                         Index-7

     test, 3-60                        s
     unlock, MP/M, 3-62
     write, 3-60                       SCB, 1-27, 1-28, 3-69, 3-70
   redirected input, 1-27              SCB parameter block, 3-69
   region boundaries, 1-9              scroll, 3-2
   register,                             output, 2-4
     A, 2-31                             support, 2-5
     entry values, 2-1                 Search, 2-28
     pair, 2-1                         Search and Delete, 2-16
     restoring values,  2-1            search chain, 1-20
     saving values, 2-1                Search For First, 3-24
   REL, 2-11                           Search For Next, 3-24, 3-26
   Relocatable Module,  2-11, 3-73     sectors, 3-65
   relocation, B-1                     Select Disk, 2-29, 2-33, 3-19
   re move                             sequential file, 2-12
     flag, 1-26                        sequential I/O processing, 2-26
     last character, 3-13              serial device I/O, 2-2
     RSX, 1-26                         serial number, 3-88
   RENAME, 1-18                        Set
   Rename File,  3-36                    BDOS Error Mode, 3-64
   Reset Disk System, 1-22, 3-18         Console Mode, 3-91
   Reset Drive, 2-27, 3-18, 3-56         Date and Time, 3-85
   resident operating system             Default Password, 2-23, 3-87
       module, 1-3                       Directory Label, 1-25,
   resident portion, 1-3                    2-21, 2-22, 3-78
   Resident System Extension             DMA Address, 3-40
       See RSX                           Error Mode, 2-29
   Resident System Extension             File Attributes, 2-16, 2-17,
       program, 4-20                        2-22, 2-28, 3-44
   Return                                file byte count, 2-17
     Current Disk, 3-39                  Multi-Sector Count,
     Directory Label, 2-21                  2-26, 3-63
     Directory Label Data,               Output Delimiter, 3-93
       2- 33 , 3-80                      Program Return Code, 3-89
     Error Mode, 3-64                    Random Record, 3-55
     Login Vector, 3-38                  User Code, 3-47
     Serial Number, 3-88               SETDEF utility, 1-19,
     Version Number, 3-17                   1-20, 1-27
   return address, 1-21                Set/Get User Code, 3-47
   Return and Display Error Mode,      SET parameter, 3-69
       3-64                            SFCB, 2-23, 2-24, 3-79
   returned error codes, 2-31          SID  TI Symbol File, 2-11
   RSX, 1-6, 1-11, 1-21, 1-23,         sign-on message, 1-14
       1-25 ,3-74, 4-20                size
     active, 1-9                         BDOS, 1-11
     attach, 1-9                         common region, 1-5
     file format, 1-25                   compute File BDOS, 3-53
     flags, 1-25                         LOADER, 1-11
     header, 1-9, 1-21, 1-24, 3-73       record, 2-7
     nonbanked flag, 1-25                transient program, 1-11
     prefix, 4-21                      source files, 2-13
     programs, 4-20                    space
     remove flag, 1-25                   disk, 3-65
   RSX Parameter Block, 3-74           sparse, 2-12
   rub/del, 3-13                       sparse file,  2-12

                                 Index-8

        SPR, 2-11                            Test and Write Record, 3-60
        standard CP/M command line,          TEX, 2-11
            1-17                             TEX Formatter Source, 2-11
        standard delete, 3-27                TPA, 1-6, 1-15, 1-21, 1-22
        standard search, 3-24                  size, 1-11
        start scroll, 3-2                      space, 1-21
        stop scroll, 3-2                     transient commands, 1-8
        subfields, 2-24                      transient program, 1-4 to 1-9,
        SUB filetype, 1-19                        1-11 to 1-13, 1-18,
        submit                                    1-22, 2-7
          command line, 1-26                   area, 1-6, 1-7
          file, 1-15, 1-18,                    size, 1-11
            1-20, 1-26                       true status, 2-6
        SUBMIT, 1-19                         Truncate File, 2-22, 3-76
          RSX, 1-27                          TYPE, 1-18
          utility, 1-13, 1-26                types of file stamps, 2-24
        successful function,   2- 32
        SYM, 2-11                            u
        SYS, 2-11
        SYS attribute, 1-18                  Unlock Record, 3-62
        Sys. Page Reloc., 2-11               unsuccessful function, 2-32
        system                               update
          attribute, 1-18                      date and time stamp,
          cold start, 1-11,                       3- 35, 3- 50
            1-12, 1-13                         directory label, 3-78
          communication, 1-7                   stamp types, 2-24
          components, 1-5                    user
          date and time, 2-24                  code, 3-47
          generation, 1-14                     command, 1-12
          interaction, 1-7                     directories, 2-18
          modules, 1-5                         number, 1-12, 1-15, 1-18,
          operation, 1-13                         1-20, 1-28, 2-18, 3-47
          prompt, 1-13, 1-15,                     conventions, 2-18
            1-16, 1-28                            current, 3-71
          regions, 1-5                         zero, 1-20, 2-17, 2-18, 3-20
          tracks, 1-12, 1-14,   1-15         USER, 1-18
          warm start, 1-11, 1-12,            User 0, 2-18
            1-15, 1-25
        System Control Block, 1-27,          v
            3-69, 3-70
        System File, 2-11                    VALUE parameter, 3-69
        System Reset, 3-1                    version-independent
                                                  programming, 3-17
        T                                    version number, 3-70
                                             virtual file size, 3-53
        tab characters, 3-2
        tab expansion, 2-3, 2-5              w
        temporarily allocated data
            block, 3-75                      warm start, 1-11, 1-15,
        temporary                                 1-22, 1-25, 3-1
          file, 2-11                         wildcard characters, 1-13
          file drive, 1-27, 3-71             write data record, 3-31
          submit file, 1-27
        terminate program execution,
            1-8, 1-22

                                        Index-9

  Wr ite
    File XFCB, 2-22, 3-83
    Protect Disk, 3-42, 3-43
    Random, 2-30, 3-50
    Random with Zero Fill,
      2 -30, 3- 59
    Sequential, 2-30, 3-31
  write-pending records, 3-68

  x

  XFCB, 2-19
    delete, 3-27
    Write File, 2-22

  z

  Zero Fi 11
    Write Random, 3-59








                               Index-10

