.MB +5
.MT -3
.LL 65
.PN 17
.HE MP/M User's Guide
.FT   (All Information Herein is Proprietary to Digital Research.)
.sp 2
2.  MP/M INTERFACE GUIDE
.sp
.pp
This section describes MP/M system organization including
the structure of memory and system call functions.  The intention
is to provide the necessary information required to write
page relocatable programs and resident system processes
which operate under MP/M, and which use the real-time, multi-tasking,
peripheral, and disk I/O facilities of the system.
.sp
.pp
2.1  Introduction
.pp
MP/M is logically divided into several modules.  The three primary
modules are named the Basic and Extended I/O
System (XIOS), the Basic Disk Operating System
(BDOS), and the Extended Disk Operating System (XDOS).
The XIOS is a hardware-dependent module which defines the
exact low level interface to a particular computer system which
is necessary for peripheral device I/O.  Although a standard
XIOS is supplied by Digital Research, explicit instructions
are provided for field reconfiguration of the XIOS to match
nearly any hardware environment.
.pp
MP/M memory structure is shown below:
.sp
.cp 40
.li
                    --------------------------- --+
              high  |                         |   |
                    |       SYSTEM.DAT        |   |
                    |                         |   |
                    ---------------------------   |
                    |                         |   |
                    |      CONSOLE.DAT        |   |
                    |                         |   |
                    ---------------------------   |
                    |                         |   |
                    |      USERSYS.STK        |   |
                    |                         |   |
                    ---------------------------   |
                    |                         |   |   These segments
                    |          XIOS           |   +-- must reside in
                    |                         |   |   common memory:
                    ---------------------------   |
                    |                         |   |   memory always
                    |      BDOS or ODOS       |   |   accessible no
                    |                         |   |   matter which
                    ---------------------------   |   bank is
                    |                         |   |   switched in.
                    |          XDOS           |   |
                    |                         |   |
                    ---------------------------   |
                    |                         |   |
                    |          RSPs           |   |
                    |                         |   |
                    --------------------------- --+
                    |                         |
                    |    BNKBDOS (Optional)   |
                    |                         |
                    ---------------------------
                    |                         |
                    |        MEMSEG.USR       |
                    |                         |
                                ...
                    |                         |
                    |        MEMSEG.USR       |
                    |                         |
                    ---------------------------
                    |                         |
                    |      ABSOLUTE TPA       |
              low   |                         |
                    ---------------------------
.sp
.pp
The exact memory addresses for each of the memory segments shown
above will vary with MP/M version and depend on the
operator specifications made during the system generation process.
.bp
The memory segments are described as follows:
.sp
.in 16
.ti -8
SYSTEM.DAT    The SYSTEM.DAT segment contains 256 bytes used by the
loader to dynamically configure the system.  After loading, the
segment is used for storage of system data such as submit flags.
See section 3.4 under SYSTEM DATA for a detailed description of
the byte allocation.
.sp
.ti -8
CONSOLE.DAT   The CONSOLE.DAT segment varies in length with the
number of consoles.  Each console requires 256 bytes which contains
the TMP's process descriptor, stack and buffers.
.sp
.ti -8
USERSYS.STK   The USERSYS.STK segment is optional depending upon
whether or not the user intends to run CP/M *.COM files.  This
segment contains 64 bytes of stack space per user memory segment
and is used as a temporary stack when user programs make
BDOS calls.  Specification of the option to include this segment
is made during system generation.
The size of the USERSYS.STK segment varies as follows:
.ti +3
000H - No user system stacks
.ti +3
100H - 1 to 4 memory segments
.ti +3
200H - 5 to 8 memory segments
.sp
.ti -8
XIOS          The XIOS segment contains the user customized
basic and extended I/O system in page relocatable format.
.sp
.ti -8
BDOS/ODOS     The BDOS segment contains the disk file and multiple
console management functions.  The segment is about 1400H bytes
in length.
.sp
The ODOS segment contains the resident portion of the banked BDOS
file and console management functions.  The segment is about 800H bytes
in length.
.sp
.ti -8
XDOS          The XDOS segment contains the MP/M nucleus and
the extended disk operating system. The segment is about 2000H bytes
in length.
.sp
.ti -8
RSPs          The operator makes a selection of Resident System
Processes during system generation.  The RSPs require varying amounts
of memory.
.sp
.ti -8
BNKBDOS (Optional)  The BNKBDOS segment is present only in systems with
a bank switched BDOS.  It contains the non-resident portion of the
banked BDOS disk file management.  This segment is about E00H bytes in
length.
.sp
.ti -8
MEMSEG.USR    The user can specifiy 1 to 8 user memory segments during
the system generation process.  These memory segments may be in the
same address space with different bank numbers.
.sp
.ti -8
TPA           The ABSOLUTE TPA is a user memory segment which is based
at 0000H.  In systems with bank switched memory there may be more
than one ABSOLUTE TPA.
.in 0
.pp
Each user memory segment, including the TPA, is further divided
into two regions.  The first is called the system parameter area.
The system parameter area occupies the first 100H bytes of the
memory segment and is defined similarily to that of CP/M.
See APPENDIX E for
a detailed description of the system parameter area.  This area is
also called the memory segment base page.
.pp
The second region of the user memory segment is the user code area.
This area begins at 0100H relative to the base of the memory segment.
When a program is loaded, code is placed into the user memory segment
beginning at the start of the user code area.
.pp
Transient programs are loaded into memory by the Command Line
Interpreter (CLI).  CLI receives commands from the Terminal Message
Process (TMP) which accepts the operator console input.
The TMP is a reentrant program which is executed by as many processes
as there are system consoles.
The operator communicates with the TMP by typing command lines
following each prompt.  Each command line generally takes one of the
forms:
.sp
.cp 4
.li
                          command
                          command file1
                          command file1 file2
.sp
where "command" is either a queue such as SPOOL or ATTACH,
or the name of a transient command or program.
.pp
A brief discussion of CLI operation will describe the loading of
transient programs.
.pp
When CLI receives a command line it parses the first entry on the
command line and then tries to open a queue using the parsed name.
If the open queue succeeds the command tail is written to the queue
and the CLI operation is finished.  If the open queue fails, a file
type of PRL is entered for the parsed file name and a file open is
attempted.  If the file open succeeds then the header of the PRL
file is read to determine the memory requirements.
A relocatable memory request is made to obtain a memory segment in
which to load and run the program.  If this request is satisfied
the PRL file is read into the memory segment, relocated, and it is
executed, completing the CLI operation.
.PP
If the PRL file type open fails then the file type of COM is entered
for the parsed file name and a file open is attempted.  If the open
succeeds then a memory request is made for an absolute TPA, memory
segment based at 0000H.  If this request is satisfied the COM file is
read into the absolute TPA and it is executed, completing the CLI
operation.
.pp
If the command is followed by one or two file specifications, the CLI
prepares one or two file control block (FCB) names in the system
parameter area.  These optional FCB's are in the form necessary
to access files through MP/M BDOS calls, and are described in
the next section.
.pp
The CLI creates a process descriptor for each program which is
loaded, setting up a 20 level stack which forces a branch to the base
of the user code area of the memory segment.  The default stack is
set up so that a return from the loaded program causes a branch
to the MP/M facility which terminates the process.
This stack has 19 levels available which can generally be used by the transient
program since it is sufficiently large to handle system calls.
.pp
The transient program then begins execution,
perhaps using the I/O facilities of MP/M to communicate
with the operator's console and peripheral devices, including
the disk subsystem.  The I/O system is accessed by passing a
"function number" and an "information address" to MP/M through
the entry point at the memory segment base +0005H.  In the case of a
disk
read, for example, the transient program sends the number corresponding
to a disk read, along with the address of an FCB to MP/M.
MP/M, in turn, performs the operation and returns with either
a disk read completion indication or an error number indicating
that the disk read was unsuccessful.  The function numbers and
error indicators are given in sections 2.2 and 2.4.
.sp 2
.ce
OPERATING SYSTEM CALL CONVENTIONS
.sp
.pp
The purpose of this section is to provide detailed information
for performing direct operating system calls from user programs.
Many of the functions listed below, however, are more simply
accessed through the I/O macro library provided with the MAC
macro assembler, and listed in the Digital Research manual
entitled "MAC Macro Assembler: Language Manual and Applications
Guide."
.pp
MP/M facilities which are available for access by transient
programs fall into two general categories:  simple device
I/O, disk file I/O, and the XDOS functions.
.bp
.ti +6
The simple device operations include:
.sp
.cp 8
.li
               Read/Write a Console Character
               Write a List Device Character
               Print Console Buffer
               Read Console Buffer
               Interrogate Console Ready
.pp
The BDOS operations which perform disk Input/Output are
.sp
.cp 16
.li
               Disk System Reset
               Drive Selection
               File Creation
               File Open
               File Close
               Directory Search
               File Delete
               File Rename
               Random or Sequential Read
               Random or Sequential Write
               Interrogate Available Disks
               Interrogate Selected Disk
               Set DMA Address
               Set/Reset File Indicators
               Reset Drive
               Access/Free Drive
               Random Write With Zero Fill
.pp
The XDOS functions are
.sp
.cp 21
.li
	       Absolute and Relocatable Memory Request
	       Memory Free
	       Device Poll
	       Flag Waiting and Setting
	       Make Queue
	       Open Queue
	       Delete Queue
	       Read and Conditional Read Queue
	       Write and Conditional Write Queue
	       Delay
	       Dispatch
	       Terminate and Create Process
	       Set Priority
	       Attach and Detach Console
	       Set and Assign Console
	       Send CLI Command
	       Call Resident System Procedure
	       Parse Filename
	       Get Console Number
	       System Data Address
	       Get Date and Time
	       Return Process Descriptor Address
	       Abort Specified Process
.pp
As mentioned above, access to the MP/M functions is accomplished
by passing a function number and information address through the
primary entry point at location memory segment base +0005H.
In general, the function number is passed in register C with
the information address in the double byte pair DE.
Single byte values are returned in register A, with
double byte values returned in HL
(a zero value is returned when the function number is
out of range).
For reasons of compatibility,
register A = L and register B = H upon return in all cases.
Note that the register passing conventions of MP/M agree with
those of Intel's PL/M systems programming language.
.pp
The list of MP/M BDOS function numbers is given below.
.sp
.cp 20
.li
      0  System Reset           21  Write Sequential
      1  Console Input          22  Make File
      2  Console Output         23  Rename File
      3  Raw Console Input      24  Return Login Vector
      4  Raw Console Output     25  Return Current Disk
      5  List Output            26  Set DMA Address
      6  Direct Console I/O     27  Get Addr(Alloc)
      7  Get I/O Byte           28  Write Protect Disk
      8  Set I/O Byte           29  Get R/O Vector
      9  Print String           30  Set File Attributes
     10  Read Console Buffer    31  Get Addr(Disk Parms)
     11  Get Console Status     32  Set/Get User Code
     12  Return Version Number  33  Read Random
     13  Reset Disk System      34  Write Random
     14  Select Disk            35  Compute File Size
     15  Open File              36  Set Random Record
     16  Close File             35  Compute File Size
     17  Search for First       36  Set Random Record
     18  Search for Next        37  Reset Drive
     19  Delete File            38  Access Drive
     20  Read Sequential        39  Free Drive
                                40  Write Random With Zero Fill
.bp
The list of MP/M XDOS function numbers is given below.
.sp
.cp 14
.li
    128  Absolute Memory Rqst  143  Terminate Process
    129  Relocatable Mem. Rqst 144  Create Process
    130  Memory Free           145  Set Priority
    131  Poll                  146  Attach Console
    132  Flag Wait             147  Detach Console
    133  Flag Set              148  Set Console
    134  Make Queue            149  Assign Console
    135  Open Queue            150  Send CLI Command
    136  Delete Queue          151  Call Resident Sys. Proc.
    137  Read Queue            152  Parse Filename
    138  Cond. Read Queue      153  Get Console Number
    139  Write Queue           154  System Data Address
    140  Cond. Write Queue     155  Get Date and Time
    141  Delay                 156  Return Proc. Descr. Adr.
    142  Dispatch              157  Abort Specified Process
.sp
.ce
DISK FILE STRUCTURE
.pp
MP/M implements a named file structure on each disk, providing
a logical organization which allows any particular file to
contain any number of records from completely empty, to the
full capacity of the drive.  Each drive is logically distinct
with a disk directory and file data area.  The disk file names
are in three parts:  the drive select code, the file name
consisting of one to eight non-blank characters, and the file
type consisting of zero to three non-blank characters.
The file type names the generic category of a particular
file, while the file name distinguishes individual files
in each category.  The file types listed below name a few
generic categories which have been established, although
they are generally arbitrary:
.sp
.cp 10
.li
    ASM  Assembler Source     PLI  PL/I Source File
    PRN  Printer Listing      REL  Relocatable Module
    HEX  Hex Machine Code     TEX  TEX Formatter Source
    BAS  Basic Source File    BAK  ED Source Backup
    INT  Intermediate Code    SYM  SID Symbol File
    COM  CCP Command File     $$$  Temporary File
    PRL  Page Relocatable     RSP  Resident Sys. Process
    SPR  Sys. Page Reloc.     SYS  System File
.sp
Source files are treated as a sequence of ASCII characters,
where each "line" of the source file is followed by
a carriage-return line-feed sequence (0DH followed by 0AH).
Thus one 128 byte MP/M record could contain several lines
of source text.
The end of an ASCII file is denoted by a control-Z character
(1AH) or a real end of file (i.e. no more sectors), returned by the
MP/M read operation.
Control-Z characters embedded within machine code files
(e.g., COM files) are ignored, however, and the end of
file condition returned by MP/M is used to terminate
read operations.
.pp
Files in MP/M can be thought of as a sequence of up to 65536
records of 128 bytes each, numbered from 0 through 65535,
thus allowing a maximum of 8 megabytes per file.
Note, however, that although the records may be considered
logically contiguous, they are not necessarily physically contiguous
in the disk data area.
Internally, all files are broken into 16K byte segments called
logical extents, so that counters are easily maintained as
8-bit values.
Although the decomposition into extents is discussed in
the paragraphs which follow, they are
of no particular consequence to the programmer
since each extent is automatically accessed in both sequential
and random access modes.
.pp
In the file operations
starting with function number 15, DE usually addresses a
file control block (FCB).
Transient programs often use the default file control block area
reserved by MP/M at location memory segment base +005CH for
simple file operations.
The basic unit of file information
is a 128 byte record used for all file operations, thus a
default location for disk I/O is provided by MP/M at location
memory segment base +0080H which is the initial default
DMA address (see function 26).
All directory
operations take place in a reserved area which does
not affect write buffers as was the case in CP/M release
1, with the exception of Search First and Search Next,
where compatibility is required.
.pp
The File Control Block (FCB) data area consists of a sequence
of 33 bytes for sequential access and a series of 36 bytes
in the case that the file is accessed randomly.  The default
file control block normally located at memory segment base +005CH can
be used for random access files, since the three bytes starting
at memory segment base +007DH
are available for this purpose.
.bp
.li
The FCB format is shown with the following fields:

  ------------------------------------------------------------
  |dr|f1|f2|/ /|f8|t1|t2|t3|ex|s1|s2|rc|d0|/ /|dn|cr|r0|r1|r2|
  ------------------------------------------------------------
   00 01 02 ... 08 09 10 11 12 13 14 15 16 ... 31 32 33 34 35

where

   dr        drive code (0 - 16)
             0 => use default drive for file
             1 => auto disk select drive A,
             2 => auto disk select drive B,
             ...
             16=> auto disk select drive P.

   f1...f8   contain the file name in ASCII
             upper case, with high bit = 0

   t1,t2,t3  contain the file type in ASCII
             upper case, with high bit = 0
             t1', t2', and t3' denote the
             bit of these positions,
             t1' = 1 => Read/Only file,
             t2' = 1 => SYS file, no DIR list
             t3' = 0 => File has been updated

    ex       contains the current extent number,
             normally set to 00 by the user, but
             in range 0 - 31 during file I/O

    s1       reserved for internal system use

    s2       reserved for internal system use, set
             to zero on call to OPEN, MAKE, SEARCH

    rc       record count for extent "ex,"
             takes on values from 0 - 128

    d0...dn  filled-in by MP/M, reserved for
             system use

    cr       current record to read or write in
             a sequential file operation, normally
             set to zero by user

    r0,r1,r2 optional random record number in the
             range 0-65535, with overflow to r2,
             r0,r1 constitute a 16-bit value with
             low byte r0, and high byte r1
.pp
Each file being accessed through MP/M must have a corresponding
FCB which provides the name and allocation information for all
subsequent file operations.  When accessing files, it is the
programmer's responsibility to fill the lower sixteen bytes
of the FCB and initialize the "cr" field.  Normally,
bytes 1 through 11 are set to the ASCII character
values for the file name and file type, while all other
fields are zero.
.pp
FCB's are stored in a directory area of the disk, and are
brought into central memory before proceeding with file
operations (see the OPEN and MAKE functions).  The memory
copy of the FCB is updated as file operations take place
and later recorded permanently on disk at the termination
of the file operation (see the CLOSE command).
.pp
The CLI constructs the first sixteen bytes of two optional
FCB's for a transient by scanning the remainder of the line
following the transient name, denoted by "file1" and "file2"
in the prototype command line described above,
with unspecified fields set to ASCII blanks.  The first
FCB is constructed at location memory segment base +005CH, and can
be used as-is for subsequent file operations.  The second
FCB occupies the d0 ... dn portion of the first FCB,
and must be moved to another area of memory before use.
If, for example, the operator types
.sp
.ce
PROGNAME B:X.ZOT Y.ZAP
.sp
the file PROGNAME.PRL is loaded into a user memory segment or if
it is not on the disk,
the file PROGNAME.COM is loaded into the TPA, and the default
FCB at memory segment base +005CH is initialized to drive code 2, file
name "X" and file type "ZOT".  The second drive code takes
the default value 0, which is placed at memory segment base +006CH,
with the file name "Y" placed into location memory segment base +006DH
and file type "ZAP" located 8 bytes later at memory segment base +0075H.
All remaining fields through "cr" are set to zero.  Note again
that it is the programmer's responsibility to move this second
file name and type to another area, usually a separate file
control block, before opening the file which begins at
memory segment base +005CH, due to the fact that the open operation
will overwrite the second name and type.
.pp
If no file names are specified in the original command,
then the fields beginning at memory segment base +005DH and +006DH
contain blanks.  In all cases, the CLI translates lower
case alphabetics to upper case to be consistent with
the MP/M file naming conventions.
.pp
As an added convenience, the default buffer area at location
memory segment base +0080H is initialized to the command line tail
typed by the operator following the program name.  The first
position contains the number of characters, with the characters
themselves following the character count.
.bp
Given the above
command line, the area beginning at memory segment base +0080H is
initialized as follows:
.sp
.cp 4
.li
   Memory Segment Base +0080H:
   +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +10 +11 +12 +13 +14
    14 " " "B" ":" "X" "." "Z" "O" "T" " " "Y" "." "Z" "A" "P"
.sp
where the characters are translated to upper case ASCII with
uninitialized memory following the last valid character.
Again, it is the responsibility of the programmer to extract
the information from this buffer before any file operations
are performed, unless the default DMA address is explicitly
changed.
.pp
The individual functions are described in detail in the sections
which follow.
.br
