
.bp
.pn 76
.cs 5
.mt 5
.mb 6
.pl 66
.ll 65
.po 10
.hm 2
.fm 2
.he CP/M-8000 Programmer's Guide          4.4  Character I/O Functions
.ft All Information Presented Here is Proprietary to Digital Research
.tc                Get I/O Byte Function
.ul
Get I/O Byte Function
.qu
.ix get I/O byte function
.sp 3
.nf
                    FUNCTION 7:  GET I/O BYTE

                Entry Parameters:
                   Register   R5:  07H

                Returned  Values:
                   Register   R7:  I/O Byte Value
.sp 2
.fi
.pp 5
The Get I/O Byte Function returns the current value of I/O Byte
in register   R7. The I/O Byte contains the current assignments
for the logical devices CONSOLE, AUXILIARY INPUT, AUXILIARY
OUTPUT, and LIST. Note that this function is valid only if the
BIOS implements its I/O Byte Function.  Refer to the \c
.ul
CP/M-8000 Operating System System Guide \c
.qu
for details on implementing the
BIOS I/O Byte Function. 
.ix get I/O byte
.bp
.tc                Set I/O Byte Function
.ul
Set I/O Byte Function
.qu
.ix set I/O byte function
.sp 3
.nf
                    FUNCTION 8:  SET I/O BYTE

                Entry Parameters:
                   Register   R5:  08H
                   Register   R7:  I/O Byte Value

                Returned  Values:
                   Register   R7:  00H
.sp 2
.fi
.pp
The Set I/O Byte Function changes the system I/O Byte value to
the value passed in register   R7.  This function allows programs
to modify the current assignments for the logical devices
CONSOLE, AUXILIARY INPUT, AUXILIARY OUTPUT, and LIST in the I/O
Byte. This function is valid only if the BIOS
implements its I/O Byte Function.  Refer to the \c
.ul
CP/M-8000 Operating System System Guide \c
.qu
for details on implementing the I/O Byte Function.   
.ix set I/O byte
.sp 2
.he CP/M-8000 Programmer's Guide         4.5  System Control Functions
.tc    4.5  System/Program Control Functions
.sh 
4.5  System/Program Control Functions 
.qs
.ix system/program control functions
.pp 
The System and program control functions described in this 
section warm boot the system, return the operating system version number, call 
the Basic I/O System (BIOS) functions, and, terminate and load programs. 
These functions are listed in Table 4-17.
.sp 2
.ce
.sh
Table 4-17. System and Program Control Functions
.sp 
.nf
.in 13
      Function             Function Number
.sp 
System Reset                      0
.sp
Return Version Number            12
.sp
Set/Get User Code                32
.sp
Chain to Program                 47
.sp
Flush Buffers                    48
.sp
Direct BIOS Call                 50
.sp
Program Load                     59
.ix program control functions
.ix system control functions
.in 0
.bp
.tc         4.5.1  System Reset Function
.sh
4.5.1  System Reset Function
.qs
.ix system reset function
.sp 3
.nf
                    FUNCTION 0:  SYSTEM RESET

              Entry Parameters:
                 Register   R5:  00H

              Returned  Values:  Function Does Not
                                 Return to Calling
                                 Program
.sp 2
.fi
.pp
The System Reset Function terminates the current program and returns
program control to the CCP command level. 
.ix system reset
.bp
.tc         4.5.2  Return Version Number Function
.sh
4.5.2  Return Version Number Function
.qs
.ix return version number function
.sp 3
.nf
               FUNCTION 12:  RETURN VERSION NUMBER

                Entry Parameters:
                   Register   R5:  0CH

                Returned  Values:
                   Register   R7:  Version Number
.fi
.sp 2
.ix version dependent programming
.ix version numbers
.pp
The Return Version Number Function provides information that
allows version dependent programming. The one-word value 2022H is
the version number returned in register   R7 for Release 1.1 of CP/M-8000.
Table 4-18 lists the version numbers this function returns
for Digital Research operating systems. 
.sp 2
.ce
.sh
Table 4-18.  Version Numbers 
.qs
.sp 
.nf
     Operating System             Version       Version Number
.sp
        CP/M-8000                    1.1             2022H
.sp
        CP/M-80                     1.4             0014H
.sp
        CP/M-80                     2.2             0022H
.sp
        CP/M-80                     3.0             0031H
.sp 
        MP/M-80                     1.1             0122H
.sp
        MP/M-80                     2.0             0130H
.sp
        MP/M-80                     2.1             0130H
.sp 2
        CP/M-86                     1.0             1022H
.sp
        CP/M-86                     1.1             1022H
.sp
        MP/M-86                     2.0             1130H
.sp
        MP/M-86                     2.1             1130H
.sp 2
     Concurrent CP/M-86             1.0             1430H
     (for the IBM 
      Personal Computer)                   
.sp 
     Concurrent CP/M-86             2.0             1431H
.sp 
.pp
.fi
Add the hexadecimal value 0200 to any version number when the
system implements CP/NET.   For example, CP/M-80 Release 2.2
returns the version 0222H when the system implements CP/NET.
.ix version number, return
.he CP/M-8000 Programmer's Guide          4.5 System Control Functions
.bp
.tc         4.5.3  Set/Get User Code
.sh
4.5.3  Set/Get User Code
.qs
.ix Set/Get user code
.sp 3
.nf
                 FUNCTION 32:  SET/GET USER CODE

                 Entry Parameters:
                    Register   R5:  20H
                    Register   R7:  FFH (get)
                                       or
                                    User Code
                                      (set)

                 Returned  Values:
                    Register   R7:  Current User
                                    Number
.sp 2
.fi
.ix user number
.pp
An application program can change or obtain the currently active
user number by calling the Set/Get User Code Function.  If the 
value in register   R7 is FFH, the value of the current user number
is returned in register   R7. The value ranges from  0 to 15
(decimal). If register   R7 contains a value in the range 
0 through  15 (decimal), the current user number is changed to 
the value in register   R7. When the program terminates and 
control returns to the CCP, the user number reverts to the BDOS
default user number.  The BDOS assumes the default is zero unless
you explicitly specify the USER command to set an alternate default.
.ix get or set user code
.bp
.tc         4.5.4  Chain To Program Function
.sh
4.5.4  Chain To Program Function
.qs
.ix chain to program function
.sp 3
                 FUNCTION 47:  CHAIN TO PROGRAM

              Entry Parameters:
                 Register   R5:  2FH

              Returned  Values:
                 Register   R7:  Function Does Not
                                 Return to Calling
                                 Program
.sp 2
.fi
.pp
The Chain to Program Function terminates the current program and
executes the command line stored in the current DMA buffer. The
format of the command line consists of a one-byte character count
(N), the command line characters, and a null byte as shown in
Figure 4-4.  The character count contains the number of
characters in the command line. The count must be no more than 
126 
characters. If an error occurs, you receive one of the CCP errors
described in Appendix E.
.sp 3
.nf 
  
    N             Command Line (N characters)                0   

 1 byte              N bytes <\b_ 126 bytes                 1 byte
.fi
.sp 2
.ce
.sh 
Figure 4-4. Command Line Format in the DMA Buffer
.bp
.tc         4.5.5  Flush Buffers Function
.sh
4.5.5  Flush Buffers Function 
.qs
.ix flush buffers function
.sp 3
.nf
                   FUNCTION 48:  FLUSH BUFFERS

              Entry Parameters: 
                 Register   R5:  30H

              Returned  Values:
                 Register   R7:  Return Code

                                 success:  00H
                                   error:  nonzero
                                           value
.fi
.sp 2
.pp
The Flush Buffers Function calls a BIOS Flush Buffers Function
(21), which forces the system to write the contents of any
unwritten or modified disk buffers to the appropriate disks.
Control and editing applications use this function to ensure
data is periodically physically written to the appropriate disks. 
When the buffers are successfully flushed, this function returns
the value 00H in register   R7.  However, if an error occurs, and
this function does not complete successfully, this function returns
a nonzero value in register   R7.
.bp
.tc         4.5.6  Direct BIOS Call Function
.sh
4.5.6  Direct BIOS Call Function
.qs
.ix direct BIOS call function
.ix BIOS return code
.ix BIOS parameter block (BPB)
.sp 3
.nf
                 FUNCTION 50:  DIRECT BIOS CALL

               Entry Parameters:  
                  Register   R5:  32H
                  Register  RR6:  BPB Address

               Returned  Values:
                  Register   R7:  BIOS Return Code
                                      (if any)
.sp 2
.fi
.pp
Function 50 allows a program to call a BIOS function and
transfers control through the BDOS to the BIOS.  The  RR6
register contains the address of the BIOS Parameter Block (BPB),
a 5-word memory area containing
two BIOS function parameters, P1 and P2, as shown in Figure 4-5.
When a BIOS function returns a value, it is returned in register
  R7. 
.pp
Like other BDOS functions, your program must specify a SC #2
Instruction to invoke this BDOS function after the
registers are loaded with the appropriate parameters.  The 
starting location of the BPB must be an even-numbered address.
.sp 3
.nf
               Field                          Size


            Function Number                   1 word 

            Value P1                          1 longword

            Value  P2                         1 longword
.fi
.sp 2
.ce
.sh
Figure 4-5.  BIOS Parameter Block (BPB) 
.qs
.sp 3
In the above figure, the function number is a BIOS function
number.  See Appendix A.  The two values, P1 and P2, are 
32-bit BIOS parameters, which are passed in
registers  RR6 and D2.L before your program invokes the BIOS function. 
Appendix A contains a list of BIOS functions.  For more details
on BIOS functions, refer to the \c
.ul
CP/M-8000 Operating System System Guide. 
Note that if the parameters are addresses, they are 
.ul
not
mapped, so that the caller can specify addresses in any part
of memory.
.qu
.ix direct BIOS call
.bp
.tc         4.5.7  Program Load Function
.sh
4.5.7  Program Load Function
.qs
.ix program load function
.sp 3
                   FUNCTION 59:  PROGRAM LOAD

            Entry Parameters:  
               Register   R5:  3bH
               Register  RR6:  LPB Address

            Returned  Values:
               Register   R7:  Return Code

                                success:  00H
                                  error:  01H - 03H
.fi
.sp 2
.ix function code
.ix load parameter block (LPB)
.pp
The Program Load function loads an executable command file into
memory.  In addition to the function code, passed in register
  R5, the address of the Load Parameter Block (LPB) is passed in
register  RR6.  After a program is loaded, the BDOS returns one
of the return codes listed below in register   R7. 
.sp 2
.ce
.sh
Table 4-19.  Program Load Function Return Codes
.qs
.sp
.in 5
.nf
Code                         Meaning
.fi
.ll 60
.in 14
.ti -8
.sp
00      the function is successful
.sp
.ti -8
01      insufficient memory exists to load the file or the header is bad
.sp
.ti -8
02      a read error occurs while the file is loaded in memory
.sp
.ti -8
03      bad relocation bits exist in the program file 
.sp
.in 0
.ll 65
.fi
.pp
The LPB describes the program and denotes the address at which it is loaded.  
The format of the LPB is outlined in Figure 4-6.  The starting location of 
the LPB must be an even-numbered address.
.bp
.nf
Byte                    Content                            Size
Offset         


 0H  address of FCB of successfully opened program file   1 longword 

 4H  lowest address of area in which to load program      1 longword

 8H  highest address of area in which to load program +1  1 longword

 CH  address of base page        (returned by BDOS)       1 longword

10H  default user stack pointer  (returned by BDOS)       1 longword

14H  loader control flags                                 1 word

.fi
.sp 2
.ce
.sh
Figure 4-6. Format of the Load Parameter Block (LPB) 
.sp 2
.ix load parameter block (LPB)
.pp
Before a program specifies the Program Load function, the file
must be opened with an Open File Function (15).
The memory addresses specified for the program in the LPB must
lie within the TPA. When the CCP calls the Program
Load function to load a transient program, the LPB 
addresses are the boundaries of the TPA. 
.pp
The loader control flags in the LPB select loader options as shown
in Table 4-20.
 ========= ACTUALLY, THE LOAD ADDRESSES GET IGNORED ===========
 ========= IN THE PRESENT VERSION.  ALSO, THE LOW   ===========
 ========= AND HIGH ADDRESSES WILL BE CHANGED TO    ===========
 ========= REFLECT THE SEGMENT ACTUALLY USED.       ===========
.sp 2
.ce
.sh 
Table 4-20.   Load Parameter Block Options
.sp
.ix load parameter block options
.nf
.in 5
.ll 60
   Bit Number    Value               Meaning
.sp 
.in
.ti -
0 (least           0       load  program in  the lowest
   significant             possible    part   of    the 
   byte)                   supplied address space
.sp
                   1       load program  in the highest
                           possible    part   of    the 
                           supplied address space
.sp
1 - 15 (decimal)   0       Reserved, should  be  set to 
                           zero.
.sp
.in 0
.ll 65
.ix CCP
.fi
.pp
The CCP uses the Program Load Function to load a command file.
The CCP places the base page address on the
program's stack. The base page address is located at the
the address pointed to by register R15 (non-segmented) or 
RR14 (segmented), the stack pointer.  The program must return
to the CCP by executing the BDOS function 0 (Reset).
.ix base page
.pp
The BDOS allocates memory for the base page within the limits set
by the low and high addresses in the LPB and returns the address
of the allocated base page in the LPB.  Locations 0000H - 0024H
of the base page are initialized by the BDOS. Locations 0025H
through 0037H are not initialized but are allocated and reserved
by the BDOS.  The CCP initializes the remaining base page values
when it loads a program. 
.ix initial stack pointer
.pp
The BDOS allocates a user stack located in the highest address of the TPA.
The maximum size of the stack equals the address of the stack pointer minus
the last address of the program plus 1. The value of the initial
stack pointer is passed to the LPB by the BDOS. 
.pp
For programs loaded by a transient program rather than 
the CCP, refer to Section 2.2.3.
============= THE FOLLOWING EXAMPLES HAVE TO BE COOKED UP ========
Appendix B contains two examples, an assembly language  program 
and a C language program, that illustrate how a transient program 
loads another program with the Program Load Function but without the CCP.
.ix program load
.nx fourg
