MILC logo

IndexVorigeVolgendeLeeg

Sliding into bdos [1/6]
M.J.Karas, 00-00-00


    
[ Converted Mnemonics to Z80, -PG ]

                        SLIDING INTO BDOS

                     THE SMOOTH AND EASY WAY


                                   by: Michael J. Karas
                                       2468 Hansen Court
                                       Simi Valley, CA 93065


     What  is this thing everybody is talking about called  BDOS? 
This  series will attempt to answer this question in some  detail 
but  first we need a little basis to understand WHY in the  first 
place.  Digital  Research CP/M is an operating system for smaller 
type micro processor computer systems that is designed to  remove 
much of the normal computer operation drudgery experienced by the 
computer  operator.  The  operating  system software  embodies  a 
"system  philosophy"  that structures and  generalizes  upon  the 
operating  environment  of a piece of electronics  hardware.  The 
environment  presented  actually  allows  that  piece  of  quiet, 
transistorized machinery to be used at a much higher  level.  The 
full  impact of what this operating system provides to a computer 
is  most probably felt by the typical micro computer hacker  that 
worked  the  hard way to get a computer system  up  and  running. 
While  building,  debugging,  and  integrating  the  pieces,  the 
computer  was just a whole bunch of parts interfaced together  in 
an  organized  manner.  However,  when  the thing  is  finally  a 
"computer" how does it get used.  The low level process of poking 
data into memory from a front panel or even filling,  dumping, or 
block  moving  memory data with an EPROM based "monitor  program" 
hardly  makes this computer "useful".  The process of putting  on 
disks  and  bringing  up  CP/M  lights  the  torch  for  computer 
usability.  In this case the hacker experiences an elated feeling 
now "NOW I CAN DO SOMETHING!"

     Buried inside of the total operating system presentation  is 
the   concept  of  generalization  brought  up  in  the  previous 
paragraph.  One  of  the major requirements in order  to  make  a 
computer  useful  is that there has to be  applications  software 
that  performs  the  jobs intended for the  computer.  Jobs  like 
accounting,  word  processing,  spread sheet  data  analysis,  or 
inventory   control.   Unfortunately  the  process  of  producing 
applications software is very, very expensive. A good package may 
take anywhere from one to ten man years of development effort  to 
make.  If the process of making an applications package had to be 
custom  taylored to a specific hardware environment,  then  there 
would  not be affordable software available for use upon a  given 
XYZ  computer.  Generalization  in the operation  of  a  computer 
environment  solves this problem however.  With the understanding 
that at a certain level "all microprocessor computer systems  are 
alike" it is possible,  with minimum constraints, to define a set 
of logical type operations that make a computer useful. 

     This  logical  set of operations,  for the Digital  Research 
CP/M operating system,  is defined within the BDOS portion of the 
operating system.  Here in about 3 1/2 K bytes of tightly written 
assembly  language is the "generalization converter"  that  takes 
I/O  requests for hardware independant applications programs  and 
turns them into a lower level set of simplistic hardware oriented 
functions  that  are  then  processed  through  the  BIOS.   This 
conversion  process is beneficial in the light that CP/M Ver  2.2 
can be setup to run on a typical brand XYZ computer for about one 
half  of  the effort needed to convert even one of  the  simplest 
application  packages  had  that application been  written  in  a 
hardware  dependant manner.  Conclusion;  software developers can 
make better,  more sophisticated applications available for lower 
cost  and computer users find a competitive software market place 
where  there  are  many times multiple  packages  available  that 
perform similar functions.

     The  thrust of this presentation is to show the  prospective 
applications  programmer  how to use most of the generalized  set 
of  "BDOS System Calls" within Digital Researches CP/M  Ver  2.2. 
The presentation scheme will be to describe all of the  functions 
and  use  simple examples.  The reader is assumed to be  modistly 
familiar  with 8080 Assembly Language Programming as all  of  the 
examples  will be given in machine language.  Likewise,  in  this 
environment  it  is  assumed  by  default  that  the  prospective 
programmer  is planning to code in assembly language.  If a  CP/M 
compatible  high level language is used for programming,  such as 
Digital  Research PL/I-80 or Microsoft BASIC-80,  then of  course 
the  program  interface  at  the  "System  Call"  level   becomes 
transparent to the programmer. Run time subroutines make the high 
level  coded application get converted through yet another  step. 
(One major reason applications code in a high level language runs 
slower   than   the  equivalent  function  written  in   assembly 
language).

SUMMARY OF CP/M SYSTEM CALLS 

     The  set of system or "BDOS" I/O entry points  available  to 
the CP/M programmer is complete yet simple. The primary beauty of 
the  CP/M  system  is  this small  world  of  completeness.  Many 
programmers  familair with other operating systems complain  that 
the CP/M system is weak,  unflexible, and incomplete. However, in 
a  microprocessor type computer world,  the generalization  level 
defined for the CP/M system allows 85% of all microprocessor type 
appliciation jobs to be programmed with relative ease.  Also,  in 
my  opinion,  8-bit microprocessor hardware is easily capable  of 
performing  about  90 percent of the typical tasks  targeted  for 
microcomputers.  So  what is this set of functions?  The chart of 
Figure 1 summarizes,  in function number order, all of the system 
operations  specific to CP/M Version 2.2 that will be covered  in 
this  presentation.  In the subsequent sections that  follow  the 
functions  will  be  grouped  into  categories  so  that  related 
operations may become familiar with reference to one another.

       FIGURE 1. DETAILED SUMMARY OF CP/M 2.2 SYSTEM CALLS


Function                           Entry Value to     Return Value from
 Number                            BDOS Passed in       BDOS Passed in 
DEC  HEX     Function             (DE) or (E) regs   (HL) or (A) register
-------------------------------------------------------------------------
 0    00 | System Reset           |      ****        |      ****        |
 1    01 | Console Input          |      ****        | (A)=character    |
 2    02 | Console Output         | (E)=character    |      ****        |
 3    03 | Reader Input           |      ****        | (A)=character    |
 4    04 | Punch Output           | (E)=character    |      ****        |
 5    05 | Printer Output         | (E)=character    |      ****        |
 6    06 | Direct Console I/O     | (E)=0FFH is input| (A)=character    |
         |                        | (E)=chr is output|      ****        |
 7    07 | Get IOBYTE             |      ****        | (A)=IOBYTE       |
 8    08 | Set IOBYTE             | (E)=IOBYTE       |      ****        |
 9    09 | Display Console String | (DE)=string addr |      ****        |
10    0A | Input Console String   | (DE)=string addr | (A)=# chr input  |
11    0B | Get Console Status     |      ****        | (A)=000H idle    |
         |                        |                  | (A)=0FFH ready   |
12    0C | Get CP/M Version Number|      ****        | (HL)=Version #   |
13    0D | Reset Disk Subsystem   |      ****        |      ****        |
14    0E | Select Disk Drive      | (E)=disk number  |      ****        |
15    0F | Open a File            | (DE)=FCB address | (A)=dir code     |
16    10 | Close a File           | (DE)=FCB address | (A)=dir code     |
17    11 | Search for File        | (DE)=FCB address | (A)=dir code     |
18    12 | Search for Next        |      ****        | (A)=dir code     |
19    13 | Delete File            | (DE)=FCB address | (A)=dir code     |
20    14 | Read next Record       | (DE)=FCB address | (A)=error code   |
21    15 | Write next Record      | (DE)=FCB address | (A)=error code   |
22    16 | Create New File        | (DE)=FCB address | (A)=dir code     |
23    17 | Rename File            | (DE)=FCB address | (A)=dir code     |
24    18 | Get Login Vector       |      ****        | (HL)=login vector|
25    19 | Get Logged Disk Number |      ****        | (A)=logged disk  |
26    1A | Set R/W Data Buff Addr | (DE)=buffer addr |      ****        |
27    1B | Get Allocation Vector  |      ****        | (HL)=alloc vector|
         |                        |                  |      address     |
28    1C | Write Protect Disk     | (E)=disk number  |      ****        |
29    1D | Get Read Only Vector   |      ****        | (HL)=R/O vector  |
30    1E | Set File Attributes    | (DE)=FCB address | (A)=dir code     |
31    1F | Get Addr of Disk Parms |      ****        | (HL)=parm addr   |
32    20 | Get/Set User Select    | (E)=0FFH get     | (A)=current user |
33    21 | Read Random Record     | (DE)=long FCB adr| (A)=error code   |
34    22 | Write Random Record    | (DE)=long FCB adr| (A)=error code   |
35    23 | Get Size of File       | (DE)=long FCB adr| (r0-2=rec cnt)   |
36    24 | Set Random Record Num  | (DE)=long FCB adr| (r0-2=rec numb)  |
37    25 | Reset Drive            | (DE)=drive vector|      ****        |
38    26 | Not used               |                  |                  |
39    27 | Not used               |                  |                  |
40    28 | Write Random with      | (DE)=long FCB adr| (A)=error code   |
-------------------------------------------------------------------------
     The  technical means required to "use" or interface  to  the
CP/M system for each function contains a certain common structure 
that  will  be discussed here.  The base memory page  of  a  CP/M 
system memory map includes,  at a specific memory address, a JUMP 
instruction  to the CP/M BDOS entry point.  For most CP/M systems 
this is address 00005H.  To accomplish BDOS I/O the number of the 
function  is  placed  into the (C)  register.  If  the  parameter 
requires  input  parameters,  then they are passed  in  the  (DE) 
register  pair  or  the individual (E)  register  depending  upon 
whether the parameter is a word or byte value. Result information 
returned  by some functions is sent back to the users program  in 
either  the (A) register or the (HL) register pair depending upon 
if  the  value is a byte or word.  The following  simple  program 
segment demonstrates the scheme used to output the 26  characters 
A-Z to the console screen through the use of function number 2.


BDOS    EQU     0005H           ; SYSTEM ENTRY
CONOUT  EQU     2               ; OUTPUT FUNCTION

        ORG     0100H           ; TPA BASE
        LD      B,26            ; PRINT 26 COUNTER
        LD      C,'A'           ; START WITH 'A'
;
LOOP:
        PUSH    BC              ; SAVE COUNTER & LETTER
        LD      E,C             ; LETTER TO (E) FOR OUTPUT
        LD      C,CONOUT        ; BDOS FUNC TO (C)
        CALL    BDOS            ; GO GO OUTPUT
        POP     BC
        INC     C               ; SEQUENCE TO NEXT CHAR
        DEC     B               ; DECREASE CHR COUNTER
        JP      NZ,LOOP         ; MORE TO DO IF NOT TO ZERO
        RET                     ; IMMEDIATE CCP RETURN


SYSTEM CALLS FOR OPERATOR CONSOLE INPUT AND OUTPUT

     Intrinsic   to   the  operation  of  any  computer   system, 
especially  of  the CP/M gender,  is the  operator  console.  The 
device  provides  the human interface to the machine and as  such 
the  BDOS  includes a generalized set of  operator  communication 
functions  to  perform I/O with the console device.  The  various 
options available will each be presented with a brief example.


INPUT FROM CONSOLE KEYBOARD: Function 1.

     This  function waits for and reads in a character  from  the 
console  device keyboard.  The operator typed character is echoed 
automatically back to the console display if the character is  an 
ASCII  printable  character  (020H to 07EH) or it is  a  carriage 
return,  line  feed,  back  space,  or tab.  Note that  the  BDOS 
automatically expands tabs to columns of eight  characters.  Upon 
outputting  the  character  for the echo,  a check  is  made  for 
console  start/stop,  CTL-S,  and if so the console input routine 
does not return to the users program until another arbitrary  key 
is depressed.

      
;CONSOLE INPUT EXAMPLE
;
CONIN   EQU     001H            ; FUNC # 1
BDOS    EQU     0005H           ; SYSTEM ENTRY

        ORG     0100H           ; START
        LD      C,CONIN         ; FUNCTION
        CALL    BDOS            ; GO GET CHARACTER
        LD      (INCHAR),A      ; SAVE FOR WHATEVER REASON
        RET                     ; IMMEDIATE CCP RETURN
;
INCHAR:
        DEFS    1               ; PLACE TO STORE INPUT CHAR
;
        END


OUTPUT TO CONSOLE DISPLAY: Function 2.

     The  ASCII  character  in the (E) register is  sent  to  the 
console display device. The output may be any byte value but many 
times  the hardware driver BIOS routines automatically strip  off 
the  upper  bit of the byte.  Upon output the printer  echo  flag 
within  BDOS is checked (CTL-P) and if set the character is  also 
sent  to  the  printer  peripheral device.  Note  that  the  BDOS 
automatically expands output tabs to columns of eight characters. 
Upon  outputting  the  character a check is  made  for  input  of 
console start/stop,  CTL-S,  and if so the console output routine 
does  not return to the users program until another arbitrary key 
is depressed.

      
;CONSOLE OUTPUT EXAMPLE
;
CONOUT  EQU     002H            ; FUNC # 2
BDOS    EQU     0005H           ; SYSTEM ENTRY

        ORG     0100H           ; START
        LD      A,(OUTCHAR)     ; GET CHARACTER TO OUTPUT
        LD      E,A
        LD      C,CONOUT        ; FUNCTION
        CALL    BDOS            ; GO SEND CHARACTER
        RET                     ; IMMEDIATE CCP RETURN
;
OUTCHAR:
        DEFB    'X'             ; PLACE TO GET OUTPUT CHAR
;
        END


DIRECT USER INTERFACE TO CONSOLE: Function 6.

     Some  programming  applications require that  the  BDOS  not 
monitor  the  input/output  character  stream  as  is  done  with 
functions  1  & 2.  To allow for these functions the  direct  I/O 
function is supported. The following example shows how it is used 
to  input values and echo them until an input control-Z character 
is typed.

;DIRECT CONSOLE I/O EXAMPLE
;
DIRCIO  EQU     006H            ; FUNCTION NUMBER
BDOS    EQU     0005H           ; SYSTEM ENTRY POINT
CTLZ    EQU     'Z'-040H        ; ASCII CTL-Z CHARACTER
INPUT   EQU     0FFH            ; DIRECT INPUT FLAG

        ORG     0100H           ; CONSOLE INPUT
;
LOOP:
        LD      E,INPUT         ; SET FOR INPUT
        LD      C,DIRCIO        ; FUNCTION
        CALL    BDOS            ; GET INPUT OR STATUS
        OR      A               ; IF (A)=0 NO CHAR WAS READY
        JP      Z,LOOP          ; CONTINUE TO WAIT FOR INPUT
        CP      CTLZ            ; IF INPUT WAS CTL Z THEN END
        RET     Z               ; CCP RETURN ON END
        LD      E,A             ; CHARACTER TO (E) FOR OUTPUT
        LD      C,DIRCIO        ; SAME FUNCTION NUMBER AGAIN
        CALL    BDOS            ; GO OUTPUT IT
        JP      LOOP            ; NEXT CHARACTER INPUT LOOP
;
        END



PRINTING STRINGS OF CHARACTERS TO THE CONSOLE: Function 9.

     Message  string  sequences of characters to be sent  to  the 
console  are quite common in  applications  programming.  Typical 
uses  may be for user prompt messages,  program sign-on  messages 
etc.  The  BDOS  provides  a convenient mechanism  to  allow  the 
programmer  to  output a whole string of characters  rather  than 
having  to  loop with single character  outputs.  The  string  is 
intended  to  be stored in consecutive memory locations  and  end 
with  the  ASCII '$' character.  The (DE) registers are  used  to 
point to the start of the string.  The '$' signals the end of the 
string  to  display and is not sent to the  console.  The  output 
bytes  may be any 8-bit value but many times the hardware  driver 
BIOS  routines automatically strip off the upper bit of the byte. 
Upon  output of each character the printer echo flag within  BDOS 
is  checked (CTL-P) and if set the character is also sent to  the 
printer  peripheral  device.  Note that  the  BDOS  automatically 
expands  output  tabs  to  columns  of  eight  characters.   Upon 
outputting  each  character a check is made for input of  console 
start/stop,  CTL-S,  and if so the console string output  routine 
does  not return to the users program until another arbitrary key 
is depressed.
      

;CONSOLE STRING PRINT EXAMPLE
;
CONSTR  EQU     009H            ; FUNC # 9
BDOS    EQU     0005H           ; SYSTEM ENTRY
CR      EQU     0DH             ; ASCII CARRIAGE RETURN
LF      EQU     0AH             ; ASCII LINE FEED

        ORG     0100H           ; START
        LD      DE,MESSAGE      ; POINT AT STRING TO SEND
        LD      C,CONSTR        ; FUNCTION
        CALL    BDOS            ; GO SEND STRING
        RET                     ; IMMEDIATE CCP RETURN
;
MESSAGE:
        DEFB    CR,LF,'Hello Operator',CR,LF,'$'
;
        END


READING A STRING OF CHARACTERS IN FROM KEYBOARD: Function 10.

     The CP/M console command processor (CCP) assumed to be  vary 
familiar  to  most CP/M system operators allows buffered  command 
input with editing features.  It turns out that this operation is 
a  much needed function for getting in strings of text  from  the 
operator console.  Use of this function allows standardization of 
the command input functions so that the operator can easily learn 
the  editing key functions.  It also removes the pain of  writing 
the  same  function  over  and over  again  by  the  applications 
programmer.  The  read string command inputs the edited text to a 
buffer  pointerd  to  by  the  (DE)  register  pair.  The  caller 
specifies  the  maximum length desired and the BDOS  returns  the 
actual  length  of string entered if carriage return  is  entered 
prior to exceeding the maximum input length.  The input length is 
returned  in  both the (A) register and as part  of  the  buffer. 
Bytes  in the string buffer past the end of the entered text  are 
uninitialized. The example shown below gives an assembly language 
view  point  of the buffer structure and how to program an  input 
function.

     The  editing functions supported are the  following  control 
and/or special characters:

          rub/del        removes and echos the last entered char
           ctl-C         initiates system reboot if first char
           ctl-E         echos a CR & LF to console without
                           putting them into buffer
           ctl-H         (or back space key) back spaces one char
                           removing last entered character
           ctl-J         (or line feed key) terminates line input
           ctl-M         (or carriage return) terminates input
           ctl-R         retypes currently entered characters 
                           under current line
           ctl-U         deletes all of currently entered data
                           and restarts buffer input on new line
           ctl-X         deletes all of currently entered data
                           and restarts buffer input on same line


;CONSOLE INPUT BUFFER EXAMPLE
;
CONBUF  EQU     00AH            ; STRING INPUT FUNCTION
BDOS    EQU     0005H           ; SYSTEM ENTRY POINT
LENGTH  EQU     32              ; DESIRED MAXIMUM CHARACTERS

        ORG     0100H           ; START POINT
        LD      DE,STRING       ; POINT AT BUFFER AREA
        LD      C,CONBUF        ; FUNCTION NUMBER
        CALL    BDOS            ; GO GET STRING
        RET                     ; RETURN TO CCP WITHOUT
                                ; ...DOING ANYTHING WITH DATA
;
;
;CONSOLE INPUT BUFFER LAYOUT
;
STRING:
        DEFB    LENGTH          ; MAXIMUM DESIRED INPUT LENGTH
AMOUNT:
        DEFS    1               ; BYTE WHERE BDOS RETURNS
                                ; ..ACTUAL BYTE COUNT
STRBF:
        DEFS    LENGTH          ; RESERVED STORAGE FOR UP TO
                                ; "LENGTH" NUMBER OF CHARACTERS
;
        END
                                   

    

Index

Vorige

Volgende