% $Id: MCB.TEX 1.1 2000/01/24 10:18:51 ska Exp ska $
\section{\label{ssmcb}\subsys{mcb}}

This subsystem contains functions dealing with MCBs
({\bf M}emory {\bf C}ontrol {\bf B}lock), the way
DOS manages the conventional -- the first 1MB of the -- RAM.

\subsection{Design}

DOS maintains a list of memory blocks describing whether or not the
block is in use, by whom and how large the block is. Each block is
preceeded by one control block, the so-called MCB. The DOS memory
management handles the conventional real-mode memory only, by default.
All sizes are given in paragraphes -- 16 bytes that begins on an address
dividable by 16 -- so that an address to such block is just one word (two
bytes), because the offset portion of such real-mode address is always
zero.

The functions of this subsystem are designed to handle a varity of
functions one wants to process the DOS memory with.

\subsection{Implementation}

Usually all functions are passed or return the address of a MCB. Unless
stated otherwise, this is the address to the MCB rather than the
address of the associated data blocks, which are returned by the
native DOS API. That means if one allocates memory via the DOS API, but
wants to perform function of this subsystem, one must use the function
\fct{SEG2MCB()} to transform the address to the data segment into the
address of the MCB.

Furtherly, \quote{segment}, \quote{data segment} or \quote{segment
number} shall refer to the segment portion of the real-mode address of
the data memory blocks; whereas, \quote{MCB} or \quote{MCB address}
refers to the segment portion of the real-mode address of the Memory
Control Block associated to a data segment.

The phrase \quote{a MCB contains} means that the data segment associated
to the MCB contains the required contents.

Nearly all functions, macros, types and names of source code files
begin with \fct{mcb} or \fct{MCB}.

\subsubsection{Types and Macros}

\begin{tabTS}
\fct{SEG\_OFFSET} & The displacement between a MCB and its associated segment.
	The useage of this constant is depreviated; use the functions
	\fct{SEG2MCB} and \fct{MCB2SEG} instead. \\
\tok{struct MCB} & Structure of a MCB. Members:
\begin{description}
\item[\tok{mcb\_type}]	Type of MCB:
\begin{description}
\item[\tok{'Z'}] last MCB in chain
\item[\tok{'M'}] not last MCB in chain
\item[{\it else}] invalid $\Rightarrow$ MCB chain corrupted
\end{description}
\item[\tok{mcb\_ownerPSP}]	 Segment number of owner process
\item[\tok{mcb\_size}]	 Size of this MCB in paragraphes (16 bytes)
\item[\tok{mcb\_name}]	 Name of program. the name maybe
	absent, in which case it is filled with random values; otherwise
	upto eight characters, possibly \tok{'\\0'} terminated or
	blank padded.
\end{description}
\tok{OFF\_MCB\_TYPE} & The offset of the MCB type within the \tok{MCB}
	structure.
	The useage of this constant is depreviated; use the ANSI function
	\tok{offsetof(struct MCB, mcb\_type)} instead. \\
\tok{OFF\_MCB\_OWNER} & The offset of the MCB owner process within the \tok{MCB}
	structure.
	The useage of this constant is depreviated; use the ANSI function
	\tok{offsetof(struct MCB, mcb\_owner)} instead. \\
\tok{OFF\_MCB\_SIZE} & The offset of the MCB size within the \tok{MCB}
	structure.
	The useage of this constant is depreviated; use the ANSI function
	\tok{offsetof(struct MCB, mcb\_size)} instead. \\
\tok{OFF\_MCB\_NAME} & The offset of the MCB owner name within the \tok{MCB}
	structure.
	The useage of this constant is depreviated; use the ANSI function
	\tok{offsetof(struct MCB, mcb\_name)} instead. \\
\fct{MCB\_WALKFUNC} & Type of function used by function \fct{mcb\_walk}
	and \fct{mcb\_allParents}. \\
\end{tabTS}

\subsubsection{Functions}

\begin{tabTS}
\fct{SEG2MCB} &		Transforms a segment number into the assoicated MCB. \\
\fct{MCB2SEG} &		Transforms a MCB into the assoicated segment number. \\
\fct{mcb\_env} &  Transforms a MCB into the segment number of the default
	environment of the process addressed by the MCB; requires that the
	MCB contains a PSP, thus, contains a process created by DOS. \\
\fct{mcb\_allParents} &	Spawns a function for the MCBs of the
	current process and all its parents. \\
\fct{isEnv} &		Checks, if a MCB contains an environment segment. \\
\fct{isMCB} &		Checks, if a MCB is valid. \\
\fct{mcb\_length} &	Returns the length of the {\bf segment} in bytes. \\
\fct{mcb\_primaryShell} &	Returns the MCB of the primary shell. \\
\fct{nxtMCB} &		Returns the next MCB in the chain. \\
\fct{mcb\_owner} &	Returns the MCB of the process owning a
	given MCB. \\
\fct{mcb\_shell} &	Returns the MCB of the shell of the owner process of the
	the given MCB. \\
\fct{isPSP} &		Checks, if a MCB contains a valid process (PSP). \\
\fct{isShell} &		Checks, if a MCB contains a shell process. \\
\fct{mcb\_walk} &	Spawns a function for each MCB in the system. \\ 
\end{tabTS}
