\documentstyle[twoside,makeidx]{pdss}
\setlength{\oddsidemargin}{0mm}
\setlength{\evensidemargin}{0mm}
\setlength{\topmargin}{-20mm}
\setlength{\textheight}{250mm}
\setlength{\textwidth}{170mm}
\makeindex
\begin{document}
\advance\oddsidemargin   -1mm
\advance\evensidemargin -11mm

\thispagestyle{empty}
\pagestyle{empty}
\begin{center}
\rule{0mm}{0mm}
\vspace*{60mm}\\
{\titlefont PDSS Manual}%{\titlefont PDSS Quick Reference Manual}
\vspace*{10mm}\\
{\LARGE (Version 2.52e )}
\vspace*{90mm}\\

{\Large Dec 26 1989}
\vspace*{10mm}\\
{\Large Institute for New Generation Computer Technology}
\vspace*{5mm}\\
{\Large Fourth Laboratory}
\vspace*{10mm}\\
{\large\sf
Copyright (C) 1988,89 by ICOT}
\end{center}

\newpage

\begin{center}
\rule{0mm}{0mm}
\vspace*{70mm}\\
{\LARGE\bf Acknowledgment}
\vspace*{10mm}\\
{\large\baselineskip3ex
\begin{minipage}{110mm}
\parindent3ex
This manual was translated from Japanese version by Dr. Kouichi Wada, a 
lecturer of Tsukuba university, Dr. Masaki Kohata, a lecturer of Okayama 
science university, and Dr. Daniel Dure, a visiting researcher of ICOT 
from France. Translation was done in March, 1989.
\end{minipage}}
\end{center}

\NewpageDouble

\tableofcontents

\NewpageDouble

\pagestyle{plain}
\pagenumbering{arabic}
\section{What is PDSS}
\label{sec-PDSS}
PDSS, which stands for PIMOS Development Support System, is a KL1 system to 
develop the PIMOS.
PDSS is widely compatible with the KL1 system found on Multi-PSI V2,
besides implementation details, execution speed, etc.
The main differences are enumerated below.
\begin{itemize}
\item Some of the functions implemented through software (e.g atom
management) are treated by the compiler. Some atom related operations are
available as built-in predicates.
\item Code management is done by compiler.
\item The only resource known by PDSS is the number of performed reductions.
\item The I/O device stream has a different form.
\item Because PDSS is a single processor system, there is no processor pointing
function for process dispersion.
\end{itemize}

Another function of PDSS is to provide tools for the development of parallel
programs. To this end, PDSS has been written in a style which ensures
portability and it will be installed onto various UNIX
\footnote{UNIX is a trademark of Bell Laboratories.} systems.
We tried to build PDSS as a handy development tool.
We expect it to be improved along the development of PIMOS.

PDSS consists mainly of two parts : one is the language processing system which
executes KL1 and the other is the user interface system, called Micro PIMOS.
Micro PIMOS is a single user, single task operating system which provides I/O
and code management functions to its user. Its description is held in
chapter \ref{sec-Micro-PIMOS}. Figure \ref{fig-PDSS} shows PDSS configuration.
\index{PDSS Configuration}

\begin{figure}[h]
\begin{center}
\setlength{\unitlength}{0.7mm}
\begin{picture}(120,120)(-60,0)
\thicklines
\put(-60,0){\framebox(120,120){}}
\put(-60,100){\line(1,0){120}}
\put(-60,60){\line(1,0){120}}
\put(-60,20){\line(1,0){120}}
\put(0,50){\line(1,0){60}}
\put(0,50){\line(0,-1){30}}
\put(0,110){\makebox(0,0){\large User Program}}
\put(0,80){\makebox(0,0){\shortstack{{\large Micro PIMOS (KL1)}\\ I/O\\
 code management\\ exception handling\\ command interpreter\\ compiler}}}
\put(-30,40){\makebox(0,0){\large\shortstack{KL1 processor\\ (C language)}}}
\put(30,35){\makebox(0,0){\large\shortstack{Multi Windows\\ (Emacs)}}}
\put(0,10){\makebox(0,0){\large UNIX}}
\end{picture}\\
\caption{PDSS configuration}
\label{fig-PDSS}
\end{center}
\end{figure}

In figure \ref{fig-PDSS}, we see that a multi-window environment is provided
through the GNU-Emacs full-screen editor. Its library has been written in
Emacs-LISP.

In PDSS, I/O and code magement functions use a special
built-in stream, called device stream. Specifications of this stream can be
found in \ref{sec-IO-device} and \ref{sec-code-device}.
Anyway, the average user doesn't have to use device stream directly,
as most necessary  facilities are provided in Micro-PIMOS libraries.

\newpage
\section{KL1 Language Specification\index{KL1 Language Specification}}
\label{sec-KL1}

The language specification of the KL1 dialect executable on PDSS lies
in this chapter. Note that there may be differences between
this specification and ones found on other systems, such as Multi-PSI V2.

\subsection{Outline}
\label{sec-KL1-abstract}

KL1 is a language based on GHC (Guarded Horn Clauses) which
moreover embeds some extensions related to OS description, modular
programming, etc. KL1 also has some restrictions, due to implementation
limitations. Its main characteristics are now described :
\vspace{1ex}

\noindent\underline{\bf Sequentiality of guard}\index{Sequentiality}
\index{Guard}\vspace{1ex}\par
Unification of head parameters and execution of guard goals are performed
sequentially, from left to right. In the following example, suspension occurs
until variable X is instantiated. Note that the following predicate
does not fail.
\begin{verbatim}

                Goal:     ?- p(a,X,b).
                Clause:   p(a,c,d) :- true | true.

\end{verbatim}
\vspace{1ex}

\noindent\underline{\bf Guard restrictions}\vspace{1ex}\par
Only built-in predicates can be used within the guard. These predicates are
described in section \ref{sec-builtin}.
\vspace{1ex}

\noindent\underline{\bf Equality\index{Equality} of variables}\vspace{1ex}\par
Equality of unbound variables is not checked in the guard part. Suspension
occurs in the following program, until variables X and Y are instantiated,
independently from the execution order of the goals of the topmost clause.
\begin{verbatim}

                Goal:     ?- X=Y, p(X,Y).
                Clause:   p(A,A) :- true | true.

\end{verbatim}
\vspace{1ex}

\noindent\underline{\bf Module\index{Module} functionality}\vspace{1ex}\par
Clustering clauses in several modules allows modular compilation and
debugging. In the current version, to each file corresponds a unique module.
\vspace{1ex}

\noindent\underline{\bf Sho-en\index{Sho-en}}\vspace{1ex}\par
An original functional unit, called Sho-en, has been introduced.
It is possible to control the execution priority and
resource allocation of each Sho-en. OS itself is constructed as such a Sho-en.
\vspace{1ex}

\noindent\underline{\bf Exception handling}\vspace{1ex}\par
Handling of exceptions occuring during the execution of a program is described
in KL1, using Sho-en and second-order predicates.
\vspace{1ex}

\noindent\underline{\bf Failure\index{Failure} handling}\vspace{1ex}\par
All failures are considered as exceptions within KL1 and execution of a
program can be resumed using exception handling facilities.

\subsection{Sho-en}
\label{sec-shoen}\index{Sho-en}

A Sho-en is the minimum unit of resource management,
priority management and exception handling which exists in the language.
Two streams, called control and report streams, are connected to each Sho-en.
The control stream\index{Control Stream} is used to control the Sho-en,
and can carry various commands. The report stream\index{Report Stream}
carries information and requests coming from the Sho-en.
Users of Sho-en can handle exceptions\index{Exception}
if they write programs interpreting the information from the report stream.

\begin{figure}[ht]
\begin{center}
\setlength{\unitlength}{0.9mm}
\begin{picture}(140,75)(0,0)
\thicklines
\put(0,0){\framebox(130,70){}}
\put(10,10){\framebox(70,40){}}
\put(15,15){\framebox(25,15){}}
\put(140,47){\vector(-1,0){20}}
\put(120,27){\vector(1,0){20}}
\put(90,35){\vector(-1,0){20}}
\put(70,25){\vector(1,0){20}}
\put(45,25){\vector(-1,0){10}}
\put(35,20){\vector(1,0){10}}
\put(0,73){\makebox(0,0)[l]{\large parent Sho-en}}
\put(10,53){\makebox(0,0)[l]{\large current Sho-en}}
\put(15,33){\makebox(0,0)[l]{\large child Sho-en}}
\put(85,38){\makebox(0,0)[l]{control stream}}
\put(85,22){\makebox(0,0)[l]{report stream}}
\multiput(35,40)(10,0){4}{\circle{2}}
\multiput(49,30)(10,0){2}{\circle{2}}
\put(20,22){\circle{2}}
\end{picture}\\
\caption{An instant picture of some Sho-ens}
\label{fig-Shoen}
\end{center}
\end{figure}

\noindent\underline{\bf Resource management functions}
\index{Resource Management Functions}
\vspace{1ex}\par
The resource\index{Resource} managed by PDSS is the number of
performed reductions. It can be seen as a rough measure of
the computing time and memory usage.
For all goals which belong to the same Sho-en, it is possible
to specify the maximum number of reductions.
\index{Resource!Maximum Number of Reductions}By default,
the system assigns the maximum possible number of reductions. When the Sho-en
is generated, i.e when it starts, this amount (or the default amount) is
attributed. When reduction allocation is exhausted during the course of
execution, an exception \verb|resource_low|
\index{Resource!Resourse_low Exception} is inserted in the report stream
of the Sho-en. It is possible to increase the reduction resource via an
\verb|add_resource(R)|\index{add_resourse} command in the control stream,
as explained later.

The resource comsumption control is performed in a discrete manner 
: independently from the maximum number of allowed reductions,
there is a system dependent reduction granularity according to
which control is exerted. Typically, a few thousands reductions.
Resource control can be seen as a recursive allocation process :
when a Sho-en starts, it is allocated, say, 2000 reductions.
When this number is exhausted, a 2000 reductions resource is subtracted
from the parent Sho-en and added to the current Sho-en.
This may trigger a recursive process, during which
reduction allocation is eventually done at the debts of some grand-father
Sho-en. During this process, and only at this time, the maximum allocation
limit is checked. 
\vspace{1ex}

\noindent\underline{\bf Priority management}
\index{Priority Management}\vspace{1ex}\par
Another function of the Sho-en is priority management. Each Sho-en holds a
record of upper and lower priority bounds, for inner goals. Goals
cannot be executed with a priority beyond upper bound and below lower bound.
Priority specification is described in section \ref{sec-priority}.

\subsubsection{Sho-en generation}
\index{Sho-en!Generation}

Sho-en generation is performed using the ``Sho-en'' system module,
\index{Sho-en System Module} which contains the predicates execute/7
\index{execute}(and an old format execute/8 also remains).
Below, \verb|code|\index{Code} is a three elements vector : 
\{\verb|module-name|, \verb|predicate-name|, \verb|number-of-args|\}.
\verb|argument| is a vector with arguments of the goal.
(In Multi-PSI V2, \verb|code| data type is used for the \verb|code|
argument.)
\begin{verbatim}

        execute(code, argument, minimum-priority,
                maximum-priority, tag, control, report)

        execute(module-name, predicate-name, argument, minimum-priority,
                maximum-priority, tag, control, report)

\end{verbatim}
Above, \verb|minimum-priority|\index{Minimum Priority} holds the value used 
to calculate the lower limit of priority bounds 
within which goals are executed.
It is an integer which ranges from 0 to 4096 and specifies 
what degree the lower limit is made lower.
When it is 0, it is the same as the lower limit of the  parent Sho-en,
and when it is 4096 , it is the same priority of the goal:execute.
\verb|Maximum-priority|\index{Maximum Priority} holds the value
used to calculate the upper limit.
It is also an integer which ranges from 0 to 4096, and sepecifies 
what degree the upper limit is made upper.
When it is 0, it is the same priority of the goal:execute,
and when it is 4096, it is the same as the upper limit of the parent Sho-en.
That is shown in Figure\ref{fig-Shoen-priority}.\index{Sho-en Priority}
\verb|Tag|\index{Sho-en Tag}\index{Sho-en!Tag} is a bit mask
used to filter the exceptions received by the Sho-en. 
\verb|Tag| is described in \ref{sec-Shoen-tag} fully. 
Control stream is unified with \verb|control|, 
and report stream is unified with \verb|report|.
The initial state of the generated Sho-en is \verb|suspend|, and the allowed
reduction count is not set.\vspace{1ex}

$\ll$ \verb|ex| $\gg$
\verb| 'Sho-en':execute({primes,do,3},{1,300,PRIMES},0,2,-1,CONTROL,REPORT)|

\begin{figure}[ht]
\begin{center}
\setlength{\unitlength}{1mm}
\begin{picture}(130,96)(-20,-36)
\put(-20,-36){\framebox(130,96){}}
\thicklines
\put(75,58){\makebox(0,0){high}}
\put(75,5){\vector(0,1){50}}
\put(75,5){\vector(0,-1){0}}
\put(74.6,7){\line(0,1){46}}
\put(75.4,7){\line(0,1){46}}
\put(75,2){\makebox(0,0){low}}
\put(60,50){\makebox(0,0)[r]{maximun priority($Smax$)}}
\put(63,50){\vector(1,0){10}}
\put(60,40){\makebox(0,0)[r]{priority of goal which generates Sho-en($Cp$)}}
\put(63,40){\vector(1,0){10}}
\put(60,30){\makebox(0,0)[r]{\bf maximum priority of new Sho-en($NSmax$)}}
\put(63,30){\vector(1,0){10}}
\put(60,20){\makebox(0,0)[r]{\bf minimum priority of new Sho-en($NSmin$)}}
\put(63,20){\vector(1,0){10}}
\put(60,10){\makebox(0,0)[r]{minimum priority($Smin$)}}
\put(63,10){\vector(1,0){10}}
\put(77,40){\line(1,0){16}}
\put(77,30){\line(1,0){6}}
\put(77,20){\line(1,0){6}}
\put(77,10){\line(1,0){16}}
\put(80,30){\vector(0,1){10}}
\put(80,30){\vector(0,-1){0}}
\put(81,35){\makebox(0,0)[l]{$Max$}}
\put(80,10){\vector(0,1){10}}
\put(80,10){\vector(0,-1){0}}
\put(81,15){\makebox(0,0)[l]{$Min$}}
\put(90,10){\vector(0,1){30}}
\put(90,10){\vector(0,-1){0}}
\put(91,25){\makebox(0,0)[l]{4096}}
\put( 0, -4){\makebox(0,0)[l]{
  $ NSmax = Cp - { (Cp - Smin) } \times {{Max} \over {4096}} $}}
\put( 0,-12){\makebox(0,0)[l]{
  $ NSmin = Smin + { (Cp - Smin) } \times {{Min} \over {4096}} $}}
\put(10,-19){\makebox(0,0)[l]{
  $ 0 \leq Max \leq 4096 \qquad Max=\makebox{maximum priority within Sho-en} $}}
\put(10,-25){\makebox(0,0)[l]{
  $ 0 \leq Min \leq 4096 \qquad Min=\makebox{minimum priority within Sho-en} $}}
\put(10,-31){\makebox(0,0)[l]{
  $ 0 \leq Min + Max \leq 4096 $}}
\end{picture}
\caption{Calculation of Sho-en Priority}
\label{fig-Shoen-priority}
\end{center}
\end{figure}

\subsubsection{Control stream}\index{Control Stream}

Below are the commands which can be inserted in the control stream. When the
control stream is closed, the Sho-en is abandoned. Conversely, if the user
does never close the stream, execution of Sho-en itself never stops.
\begin{itemize}

\ControlMessage{start}
Activates goal execution in the Sho-en.

\ControlMessage{stop}
Suspends goal execution. Previous command causes execution to resume.

\ControlMessage{abort}
Aborts goal execution once and for all. In particular, start command cannot
resume execution.

\ControlMessage{add_resource(Reduction)}\index{add_resource}
Adds \verb|Reduction| to the current number of allowed reductions.

\ControlMessage{allow_resource_report}
This command is an answer to the exception \verb|resource_low|. This
exception cannot be reported again until this command is inserted.

\ControlMessage{statistics}
Asks statistics about the Sho-en. Information is inserted in the report
stream.

\end{itemize}
\subsubsection{Report stream}\index{Report Stream}

The following information can be found in the report stream.
\vspace{1ex}

\noindent\underline{\bf Acknowledgment messages to control stream commands :}
\vspace{1ex}\par
Here are the responses to commands put in the control stream.
\begin{itemize}

\ReportedMessage{started}
\verb|Start| message has been received.

\ReportedMessage{stopped}
\verb|Stop| message has been received.

\ReportedMessage{aborted}
\verb|Abort| message has been received.

\ReportedMessage{resource_added}
\verb|Add_ressource| message has been received.

\ReportedMessage{resource_report_allowed}
\verb|Allow_resource_report| message has been received.
Exception \verb|resource_low| can be reported again after this message.

\ReportedMessage{statistics_started}
\verb|Statistics| message received. The statistic information itself is
reported once collected.

\end{itemize}
\vspace{1ex}

\noindent\underline{\bf Status information}
\index{Report Stream!Status Information}
\vspace{1ex}\par
Here is the information reported whenever Sho-en status changes.
\begin{itemize}

\ReportedMessage{terminated}
Execution of Sho-en has finished. If \verb|abort| had been sent previously,
this message indicates that the execution has been aborted. Otherwise,
it indicates success of all goals.

\ReportedMessage{resource_low}
The number of performed reductions is close to the maximum allowed amount, or
this amount is not sufficient. When this exception occurs, Sho-en state becomes
\verb|suspend|. No other \verb|resource_low|
report can occur before that \verb|allow_resource_report|
is inserted in the control stream.

\end{itemize}
\vspace{1ex}

\noindent\underline{\bf Statistic information}
\index{Report Stream!Statistic Information}\vspace{1ex}\par
Here, we get statistic information about the Sho-en,
whenever collection has been done.
\begin{itemize}

\ReportedMessage{statistics(Info)}
Unifies the statistic information with \verb|Info|, which is one-element-vector
, indicating the number of reductions performed. This number includes
reductions performed by children Sho-ens.

\end{itemize}
\vspace{1ex}

\noindent\underline{\bf Exception information}
\index{Report Stream!Exception Information}\index{Exception Information}
\vspace{1ex}\par
Here is the description of exceptions which can be
reported by a Sho-en.
Excluding deadlock, they specify the handling processes for the exceptions.
If an exception condition is detected by PDSS, 
\verb|apply(NewCode, NewArgv)| is generated within the Sho-en 
to handle the exception.\index{apply}
Then, system waits for the unification of this goal with \verb|NewCode| and
\verb|NewArgv|.
The predicate specified with \verb|NewCode| must be declared as public.
When \verb|NewCode| is unified with \verb|[]|, no goal is executed any more.
\begin{itemize}

\ReportedMessage{exception(ExcpCode, Info, NewCode, NewArgv)}
Exception occured in Sho-en. \verb|ExcpCode| is a positive integer 
which indicates the type of exception.
\verb|Info| is an information about the exception, and
it is unique corresponding to the type of exception.
Each exception code is described in \ref{sec-exception}.
The new code and arguments of the goal chosen
by the user, in place of the failing goal which caused exception, should be
unified with \verb|NewCode| and \verb|NewArgv|.
\verb|ExcpCode| and \verb|Info| are described as follows.
Below \verb|Caller| is the code of the predicate 
which calls a built-in predicate.
\verb|OpCode| is the operation code of the built-in predicate, 
\verb|Argv| is the argument vector, and \verb|Code| is a three elements vector:
\{module-name, preicate-name, number-of-arguments\}.

\begin{tabular} {rl@{\ ::\ }ll}
\verb|ExcpCode| & meaning & \verb|Info| & definition \\
0 & Illegal Input Type & \{0, Caller, OpCode, Pos, Argv\}
& Pos is the position of \\
 & & & the invalid argument(1 $\sim$ 7)\\
1 & Range Overflow & \{0, Caller, OpCode, Argv\} & \\
3 & Integer Overflow & \{0, Caller, OpCode, Argv\} & \\
5 & Floating Point Error & \{0, Caller, OpCode, Argv\} & \\
8 & Illegal Merger Input & \{0, Caller, OpCode, MI, FMI\}
& MI is the invalid input data for merger \\
 & & & FMI is the input stream to merger \\
9 & Reduction Failure & \{0, Code, Argv\} & \\
10 & Unification Failure & \{0, X, Y\}
& X and Y are the terms which \\
 & & & causes failure in body part unification \\
12 & Raised & \{0, RType, RInfo\}
& RType,RInfo are the terms \\
 & & &given by the built-in predicate:raise/3 \\
16 & Incorrect Priority & \{0, Caller, OpCode, Argv\} & \\
17 & Module Not Found & \{0, Code, Argv\} & \\
18 & Predicate Not Found & \{0, Code, Argv\} & \\
\end{tabular}

\ReportedMessage{deadlock(ExcpCode, Info)}
Deadlock\index{Deadlock} has been detected in Sho-en. 
\verb|ExcpCode| is an integer indicating 
that the type of exception is deadlock.
\verb|Info| is an information about the exception, 
and now its format is shown below.
\verb|DGoal| is the code of the predicate which causes deadlock, or \verb|[]|
(in the case that deadlock is detected in global garbage collection).
\verb|DType| is an integer indicating
deadlock type(see chapter \ref{sec-deadlock}).
\verb|GoalsList| is the list of codes of goals which are deadlock roots.

\begin{tabular} {rl@{\ ::\ }ll}
\verb|ExcpCode| & meaning & \verb|Info| & definition \\
11 & Deadlock & \{0, DGoal, DType, GoalsList\} & described above \\
\end{tabular}

\end{itemize}

\subsection{Priority\index{Priority}}
\label{sec-priority}

In KL1, it is possible to specify the priority at which each goal is executed.
There are logical and physical priorities, and each goal can have its own
logical priority.
\index{Priority!Logical Priority}\index{Priority!Physical Priority}
There are different levels of physical priority in the system, and
the scheduler converts logical priority into physical priority when it
connects goals to the goal stack. (As physical priority is less accurate than
logical priority, user should not expect scheduling to reflect exactly the
logical priority.) Upper/lower limits of priority in the Sho-en are also
logical.

Priority of a goal is specified relatively to its
parent goal, or relatively to the Sho-en it belongs to.
The former method is called ``relative self specification in the belonging
Sho-en'' and the later is called ``rate specification in the belonging
Sho-en''.
\index{Priority!Relative Self Specification}
\index{Priority!Rate Specification}
\vspace{1ex}

\noindent\underline{\bf Rate specification in the belonging Sho-en}
\index{Priority!Rate Specification}
\vspace{1ex}\par
Goal priority is specified by a value relative to the upper/lower limit of the
belonging Sho-en. It is written as follows :
\begin{center}
{\bf Goal @ priority(\verb|*|, Rate)}
\end{center}\index{\verb|@|}
In this case, the goal priority is computed shown 
in Figure \ref{fig-priority1} :

\begin{figure}[ht]
\begin{center}
\setlength{\unitlength}{1mm}
\begin{picture}(140,60)(-30,0)
\put(-30,0){\framebox(140,60){}}
\thicklines
\put(75,58){\makebox(0,0){high}}
\put(75,5){\vector(0,1){50}}
\put(75,5){\vector(0,-1){0}}
\put(74.6,7){\line(0,1){46}}
\put(75.4,7){\line(0,1){46}}
\put(75,2){\makebox(0,0){low}}
\put(60,50){\makebox(0,0)[r]{upper-limit($Smax$)}}
\put(63,50){\vector(1,0){10}}
\put(60,40){\makebox(0,0)[r]{priority of the calling goal($CP$)}}
\put(63,40){\vector(1,0){10}}
\put(60,30){\makebox(0,0)[r]{\BF new goal priority($NP$)}}
\put(63,30){\vector(1,0){10}}
\put(60,10){\makebox(0,0)[r]{lower-limit($Smin$)}}
\put(63,10){\vector(1,0){10}}
\put(77,50){\line(1,0){16}}
\put(77,30){\line(1,0){6}}
\put(77,10){\line(1,0){16}}
\put(80,10){\vector(0,1){20}}
\put(80,10){\vector(0,-1){0}}
\put(81,20){\makebox(0,0)[l]{\footnotesize\BF Rate}}
\put(90,10){\vector(0,1){40}}
\put(90,10){\vector(0,-1){0}}
\put(91,30){\makebox(0,0)[l]{4096}}
\put(65,23){\makebox(0,0)[r]{
  $ Smin + {(Smax - Smin)} \times {{\hbox{\footnotesize\BF Rate}}
    \over {4096}} \qquad (0 \leq \hbox{\BF Rate} \leq 4096) $}}
\end{picture}
\caption{computation of the goal priority by rate specification in the belonging Sho-en}
\label{fig-priority1}
\end{center}
\end{figure}
\noindent\underline{\bf Relative self specification in the belonging Sho-en}
\index{Priority!Relative Self Specification}
\vspace{1ex}\par
Goal priority is specified by a value relative to the logical priority of the
parent goal. This priority cannot exceed the upper/lower limit of the Sho-en.
\begin{center}
{\bf Goal @ priority(\verb|$|, Rate)}
\end{center}
This time, priority is computed accoding to the sign of Rate
as shown in Figure \ref{fig-priority2} (in case of plus) 
and Figure \ref{fig-priority3} (in case of minus).

\begin{figure}[ht]
\begin{center}
\setlength{\unitlength}{1mm}
\begin{picture}(140,60)(-30,0)
\put(-30,0){\framebox(140,60){}}
\thicklines
\put(75,58){\makebox(0,0){high}}
\put(75,5){\vector(0,1){50}}
\put(75,5){\vector(0,-1){0}}
\put(74.6,7){\line(0,1){46}}
\put(75.4,7){\line(0,1){46}}
\put(75,2){\makebox(0,0){low}}
\put(60,50){\makebox(0,0)[r]{upper-limit($Smax$)}}
\put(63,50){\vector(1,0){10}}
\put(60,30){\makebox(0,0)[r]{\BF new goal priority($NP$)}}
\put(63,30){\vector(1,0){10}}
\put(60,20){\makebox(0,0)[r]{priority of the calling goal($CP$)}}
\put(63,20){\vector(1,0){10}}
\put(60,10){\makebox(0,0)[r]{lower-limit($Smin$)}}
\put(63,10){\vector(1,0){10}}
\put(77,50){\line(1,0){16}}
\put(77,30){\line(1,0){6}}
\put(77,20){\line(1,0){16}}
\put(80,20){\vector(0,1){10}}
\put(80,20){\vector(0,-1){0}}
\put(81,25){\makebox(0,0)[l]{\footnotesize\BF Rate}}
\put(90,20){\vector(0,1){30}}
\put(90,20){\vector(0,-1){0}}
\put(91,35){\makebox(0,0)[l]{4096}}
\put(65,37){\makebox(0,0)[r]{
  $ CP + {(Smax - CP)} \times {{\hbox{\footnotesize\BF Rate}}
    \over {4096}} \qquad (0 \leq \hbox{\BF Rate} \leq 4096) $}}
\end{picture}
\caption{computation of the goal priority by relative self specification in the belonging Sho-en(plus)}
\label{fig-priority2}
\end{center}
\end{figure}

\begin{figure}[ht]
\begin{center}
\setlength{\unitlength}{1mm}
\begin{picture}(140,60)(-30,0)
\put(-30,0){\framebox(140,60){}}
\thicklines
\put(75,58){\makebox(0,0){high}}
\put(75,5){\vector(0,1){50}}
\put(75,5){\vector(0,-1){0}}
\put(74.6,7){\line(0,1){46}}
\put(75.4,7){\line(0,1){46}}
\put(75,2){\makebox(0,0){low}}
\put(60,50){\makebox(0,0)[r]{upper-limit($Smax$)}}
\put(63,50){\vector(1,0){10}}
\put(60,40){\makebox(0,0)[r]{priority of the calling goal($CP$)}}
\put(63,40){\vector(1,0){10}}
\put(60,30){\makebox(0,0)[r]{\BF new goal priority($NP$)}}
\put(63,30){\vector(1,0){10}}
\put(60,10){\makebox(0,0)[r]{lower-limit($Smin$)}}
\put(63,10){\vector(1,0){10}}
\put(77,40){\line(1,0){16}}
\put(77,30){\line(1,0){6}}
\put(77,10){\line(1,0){16}}
\put(80,30){\vector(0,1){10}}
\put(80,30){\vector(0,-1){0}}
\put(81,35){\makebox(0,0)[l]{$|\hbox{\footnotesize\BF Rate}|$}}
\put(90,10){\vector(0,1){30}}
\put(90,10){\vector(0,-1){0}}
\put(91,25){\makebox(0,0)[l]{4096}}
\put(65,23){\makebox(0,0)[r]{
  $ CP - {(CP - Smin)} \times {{|\hbox{\footnotesize\BF Rate}|}
    \over {4096}} \qquad (-4096 \leq \hbox{\BF Rate} < 0) $}}
\end{picture}
\caption{computation of the goal priority by relative self specification in the belonging Sho-en(minus)}
\label{fig-priority3}
\end{center}
\end{figure}

\subsection{Syntax\index{Syntax}}
\label{sec-syntax}

Differences between GHC and KL1 are described here. Main differences are
concerned with :
\begin{itemize}
\item Module definition
\item Clause ordering
\item Priority specification
\item Macros description
\end{itemize}
The macros are described later in this document.

\subsubsection{Module definition\index{Module definition}}

The following is a module\index{module} definition :
\begin{verbatim}
                :- module module-name.
\end{verbatim}
This declaration must appear at the head of any module.
Furthermore, any predicate defined in this module but used outside
of it should be declared as follows :
\index{public}\index{Public Declaration}\vspace{1ex}

\hspace{19ex}\verb|:- public predicate-name/number-of-arguments, |$\cdots$ .

Note that predicates executed by a built-in predicate \verb|apply|
and those specified at Sho-en generation must be declared public\index{public}.
Multiple definitions of a predicate, spreading over several clauses, cannot
be split by the definition of a different predicate.
Doing otherwise causes display of the message ``Assembler: Doubly
defined label.''.

A goal whose definition pertains to a different module can be used
as indicated below :\index{Goal Definition Pertaining to a Different Module}
\begin{verbatim}
                module-name : goal-name
\end{verbatim}

Conversely, any goal without \verb|"module-name : "| is 
recognized as a goal called inside the module.
That is, a goal name is efficient in each module, and 
the same predicate names can be used as different predicate definition 
as far as they are belong to different modules.

\subsubsection{Clause ordering\index{Clause Ordering}}

Compilation of KL1 program goes through clause indexing, in order to maximize
efficiency. This may in return change the order according to which clauses are
selected for evaluation. If clause evaluation ordering is a necessity, 
the following statements should be used.
\vspace{1ex}

\noindent\underline{\bf Scheduling\index{Scheduling} order}\vspace{1ex}\par
The statement \verb|alternatively|\index{alternatively}
can be used to separate two sets of clauses,
the first of which should be scheduled with a higher priority. However, if all
clauses in the first set are suspended or fail, evaluation of clauses in
the second set starts.\vspace{1ex}

\hspace{19ex}\verb!foo([X|XX],Z) :- true | p(X,XX,Z).!

\hspace{30ex}$\cdots$

\hspace{19ex}\verb!alternatively.!

\hspace{19ex}\verb!foo(X,[Z|ZZ]) :- true | q(X,Z,ZZ).!

\hspace{30ex}$\cdots$
\vspace{1ex}

\noindent\underline{\bf Evaluation\index{Evaluation} order}\vspace{1ex}\par
The \verb|otherwise|\index{otherwise} statement is more straightforward 
: clauses following it are evaluated only if all of the preceeding clauses
failed. Suspension does not trigger anything in this case.\vspace{1ex}

\hspace{19ex}\verb!foo([X|XX]) :- X=a | pa(X,XX).!

\hspace{19ex}\verb!foo([X|XX]) :- X=b | pb(X,XX).!

\hspace{30ex}$\cdots$

\hspace{19ex}\verb|otherwise.|

\hspace{19ex}\verb!foo(X) :- true | q(X).!

\hspace{30ex}$\cdots$

\subsection{Data types\index{Data Types}}
\label{sec-data-type}

Here are the data types supported by PDSS. 
The system recognizes only these data types as "data",
that is, only these data types can make sense for the system.
\begin{itemize}

\item Unbound variables $\cdots$ \verb|A, A12, B, _abc, _|\\
\index{Unbound Variables}
As Prolog, an unbound variable consists of charactors and numerals, 
and begins with a capital charactor or a underscore.
Unbound variables of a same name in one clause are identified as the same.
Note that isolated underscores are recognized as different each other.

\item Atoms $\cdots$ \verb|abc, 'ABC', :=, 'can''t'|\\ \index{Atoms}
As Prolog, an atom consists of 
charactors which begin with a small letter, 
or only of signs, or of charactors quoted with single quotation marks.
To use a sigle quotation mark: \verb|'| as an element of an atom name,
use two single quotation marks and quote the term with single quotation marks.
Note that `\verb|$|' is used by the system as a particular usage,
so users had better not use it as an atom (or an element of it).

\item Integers $\cdots$ \verb|123, 16'ACE, 8'37, +3, -5|\\ \index{Integers}
Usually an integer is expressed by the decimal notation, and 
ranges from $-2147483648$ to $2147483647$.
Then the sign of it is taken as a part of an integer,
unless spaces do not follow it. 
When an integer in format x'y is used, the radix base x may vary between 2 and
36, with classical convention for figures. 
But the sign cannot be included in this expression.
Note that x'y format produces a syntax error on the Prolog-based compiler, 
which makes sense for the reader of PDSS.
The form \verb|radix-base#number| should be used instead. 
Note that the \verb|number| is expressed as a string(e.g. \verb|16#"12AC"|).

\item Floating Point $\cdots$ \verb|1.23, 1.0e10, 3.0E-30, -2.0|\\
\index{Floating Point}
Floating point is expressed by following format:\\
\hspace*{4em} \verb|[sign]| \verb|number| $\SS{+}$
		\verb|  decimal point number|$\SS{+}$
		\verb|[e| or \verb|E| \verb|[sign of index number]| 
		\verb|number|$\SS{+}$ ]\\
Above, \verb|[...]| expresses an option and \verb|number|$\SS{+}$ 
expresses numeral(s).
It is not allowed to include any space in this expression.
As in an integer, the sign is taken as a part of an floating pont.
PDSS supports a single-precision (32 bits ) floating point number.
It expresses a value by about seven places of decimal which 
ranges from $-3.402823 \times 10\SS{38}$ to $3.402823 \times 10\SS{38}$.\\
To unify two floating point numbers, comparison of bit patterns
of internal forms is used. Even if displayed two values seems to be unifiable,
there are some possibilities of failing in unification.
So, for general, 
unification of two floating point numbers should not be intended.

\item Lists $\cdots$ \verb![1,2,3], [X|Y]!\\ \index{Lists}
A list is expressed by \verb|[ ]|. Car and Cdr can be expressed 
by using `\verb!|!'.

\item Vectors $\cdots$ \verb|{1,2,{3,4}}, f(X), {}|\\ \index{Vectors}
A vector is a structure of one dimension arrays, possibly of 0 dimension.
To express a vector, it is allowed to use \verb|{ }| or the functor format.
For example, \verb|f(a)| and \verb|{f,a}| have the same structure.

\item Strings $\cdots$ \verb|"abc", "", """"|\\ \index{Strings}
A string is expressed by charactors qouted with double qoutation marks: 
\verb|"|. To use a double quotation mark: \verb|"| as an element of a string,
use two double quotation marks and quote the term with double quotation marks.
The size of the string allowed by the system ranges from 1 bit to 32 bits.
On PDSS, a string expressed by \verb|"..."| is recognized as an 8 bits string.
On Prolog-based compiler, \verb|"..."| is not precisely distinguished
from lists, because a string is expressed by a list of codes 
of charactors on Prolog. 
So, a macro expression of the form \verb|string#"..."| should be used 
to generate a string.
Here, strings, excluding 8 bits strings, are used only for internal forms,
and cannot be used in source files as constants.\\
Indeed, unification of two strings will success
if the strings have identical length and contents.

\end{itemize}
\subsection{Built-in predicates\index{Built-in Predicates}}
\label{sec-builtin}

We now give the list of the built-in KL1 primitives supported by PDSS.
The following is an example of the format we use :
\vspace{2ex}

\hspace*{10em}
\shortstack{\underline{\bf vector(X, ^Size)} 
{\bf ::}\\ $\uparrow$ \\ Call format}
\shortstack[l]{\underline{\bf G}\\ $\uparrow$ \\ Valid location for occurence}
\vspace{2ex}

In this case, {\bf G} means that the predicate can appear in the guard of the
clause. Some predicates can occur in the body, in which case the letter
{\bf B} is used. {\bf GB} denotes predicates which can occur in both places.
Besides, arguments with a {\bf ^} are outputs, whereas other arguments are
inputs. One should take this into account, because binding an output argument
with an already instantiated variable may cause suspension. Also, unification
occuring in the guard is passive, whereas unification in the body can be
active. 

For some of the predicates described therein, input parameters should verify
some domain constraints. Typically, to divide a number by 0 is not a very
sound operation. If a domain constraint is not respected,
depending on the predicate position, two different things may happen : 
if the predicate is used within the guard part of a clause, 
this clause fails. If the predicate is in the body, an exception occurs.

The system presents arithmetic macros for arithmetic operation, so
it is not necessary to describe relevant built-in predicates.
Macros are described in capter \ref{sec-macro}.
\vspace{1ex}

\subsubsection{Type checking}\index{Built-in Predicates!Type Checking}
\begin{itemize}

\Builtin{wait}{(X)}{G}
If \verb|X| is unbound, suspension occurs. Otherwise, this predicate succeeds.

\Builtin{atom}{(X)}{G}
If \verb|X| is unbound, suspension occurs.
If \verb|X| is an atom, this predicate succeeds, otherwise it fails.

\Builtin{integer}{(X)}{G}
If \verb|X| is unbound, suspension occurs.
If \verb|X| is an integer, this predicate succeeds, otherwise it fails.

\Builtin{floating_point}{(X)}{G}
If \verb|X| is unbound, suspension occurs.
If \verb|X| is a floating point, this predicate succeeds, otherwise it fails.

\Builtin{list}{(X)}{G}
If \verb|X| is unbound, suspension occurs.
If \verb|X| is a list, this predicate succeeds, otherwise it fails.

\Builtin{vector}{(X)}{G}
If \verb|X| is unbound, suspension occurs.
If \verb|X| is a vector, this predicate succeeds, otherwise it fails.

\Builtin{string}{(X)}{G}
If \verb|X| is unbound, suspension occurs.
If \verb|X| is a string, this predicate succeeds, otherwise it fails.

\Builtin{unbound}{(X, ^Result)}{B}
This primitive always succeeds.
If \verb|X| is unbound, \verb|Result| is unified with a three-elements-vector
\verb|{PE, Addr, X}|. Here,
\verb|PE| is the number of PE which holds the variable \verb|X| 
(on PDSS always unified with 0),
and \verb|Addr| is an address of the variable \verb|X|.
Conversely, if \verb|X| is bound when this primitive is executed,
\verb|Result| is unified with \verb|{X}|.
This primitive never causes suspension.\\
\Caution The values of \verb|PE| and \verb|Addr| will be changed after
garbage collection.

\end{itemize}
\subsubsection{Diff}
\begin{itemize}

\Builtin{diff}{(X, Y)}{G}
If \verb|X| and \verb|Y| are identified as not to be unifiable 
by comparison of the two terms, this predicate succeeds.
Conversely if \verb|X| and \verb|Y| can be identified as
completely to have the same structure, the predicate fails.
Otherwise suspension occurs. Following macro can be used.
\begin{verbatim}
        X \= Y  <=>  diff(X,Y).
\end{verbatim}
\Caution Comparison of the terms is made in depth first from left to right.
If any unbound variables are found in comparison,
comparison procedure is stopped and suspension occurs.
If \verb|X| and \verb|Y| are structured terms, unifiability checking is
limited in depth. If terms are unifiable in the depth limit,
the predicate will fail, although a difference may exist deeper 
in the structures.

\index{\verb|\=|}
\end{itemize}
\subsubsection{Arithmetic comparison (Integer)}
\index{Built-in Predicates!Arithmetic Comparison(Integer)}
\begin{itemize}

\Builtin{equal}{(Integer1, Integer2)}{G}
If \verb|Integer1| or \verb|Integer2| is unbound, suspension occurs.
If both \verb|Integer1| and \verb|Integer2| are integers and are equal,
this predicate succeeds. Otherwise it fails. Following macro can be used.
\begin{verbatim}
        X =:= Y  <=>  equal(X,Y).
\end{verbatim}

\index{\verb|=:=|}
\Builtin{not_equal}{(Integer1, Integer2)}{G}
If \verb|Integer1| or \verb|Integer2| is unbound, suspension occurs.
If both \verb|Integer1| and \verb|Integer2| are integers and are not equal,
this predicate succeeds. Otherwise it fails. Following macro can be used.
\begin{verbatim}
        X =\= Y  <=>  not_equal(X,Y).
\end{verbatim}

\index{\verb|=\=|}
\Builtin{less_than}{(Integer1, Integer2)}{G}
If \verb|Integer1| or \verb|Integer2| is unbound, suspension occurs.
If both \verb|Integer1| and \verb|Integer2| are integers 
and the value of the former is less than that of the latter,
this predicate succeeds. Otherwise it fails. Following macro can be used.
\begin{verbatim}
        X < Y  <=>  less_than(X,Y).
        X > Y  <=>  less_than(Y,X).
\end{verbatim}

\index{\verb|<|} \index{\verb|>|}
\Builtin{not_less_than}{(Integer1, Integer2)}{G}
If \verb|Integer1| or \verb|Integer2| is unbound, suspension occurs.
If both \verb|Integer1| and \verb|Integer2| are integers 
and the value of the former is larger than, or equal that of the latter,
this predicate succeeds. Otherwise it fails. Following macro can be used.
\begin{verbatim}
        X >= Y  <=>  not_less_than(X,Y).
        X =< Y  <=>  not_less_than(Y,X).
\end{verbatim}

\index{\verb|>=|} \index{\verb|=<|}
\end{itemize}
\subsubsection{Arithmetic operations (Integer)}
\index{Built-in Predicates!Arithmetic Operations(Integer)}
\begin{itemize}

\Builtin{add}{(Integer1, Integer2, ^NewInteger)}{GB}
If \verb|Integer1| or \verb|Integer2| is unbound, suspension occurs.
If terms are not integers, failure or exception occurs.
The result of the addition is unified with \verb|NewInteger|, then
if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Z := X + Y  <=>  add(X,Y,Z).
\end{verbatim}

\index{\verb|+|}
\Builtin{subtract}{(Integer1, Integer2, ^NewInteger)}{GB}
If \verb|Integer1| or \verb|Integer2| is unbound, suspension occurs.
If terms are not integers, failure or exception occurs.
The result of the subtraction is unified with \verb|NewInteger|, then
if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Z := X - Y  <=>  subtract(X,Y,Z).
\end{verbatim}

\index{\verb|-|}
\Builtin{multiply}{(Integer1, Integer2, ^NewInteger)}{GB}
If \verb|Integer1| or \verb|Integer2| is unbound, suspension occurs.
If terms are not integers, failure or exception occurs.
The result of the multiplication is unified with \verb|NewInteger|, then
if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Z := X * Y  <=>  multiply(X,Y,Z).
\end{verbatim}

\index{\verb|*|}
\Builtin{divide}{(Integer1, Integer2, ^NewInteger)}{GB}
If \verb|Integer1| or \verb|Integer2| is unbound, suspension occurs.
If terms are not integers, failure or exception occurs.
The result of the division is unified with \verb|NewInteger|.
Then if overflow is detected, or if \verb|Interger2| is bound to 0, 
failure or exception occurs. Following macro can be used.
\begin{verbatim}
        Z := X / Y  <=>  divide(X,Y,Z).
\end{verbatim}

\index{\verb|/|}
\Builtin{modulo}{(Integer1, Integer2, ^NewInteger)}{GB}
If \verb|Integer1| or \verb|Integer2| is unbound, suspension occurs.
If terms are not integers, failure or exception occurs.
The result of the rest of the euclidian division is unified with 
\verb|NewInteger|. 
Then if overflow is detected, or if \verb|Interger2| is bound to 0, 
failure or exception occurs. Following macro can be used.
\begin{verbatim}
        Z := X mod Y  <=>  modulo(X,Y,Z).
\end{verbatim}

\index{mod}
\Builtin{minus}{(Integer, ^NewInteger)}{GB}
If \verb|Integer| is unbound, suspension occurs.
If it is not an integer, failure or exception occurs.
\verb|NewInteger| is unified with \verb|Integer| with sign exchanged, then
if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Y := -X  <=>  minus(X,Y).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{\verb|-|}
\Builtin{increment}{(Integer, ^NewInteger)}{GB}
If \verb|Integer| is unbound, suspension occurs.
If it is not an integer, failure or exception occurs.
The result to add 1 to \verb|Integer| is unified with \verb|NewInteger|, then
if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Y := X + 1  <=>  increment(X,Y).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{\verb|+|}
\Builtin{decrement}{(Integer, ^NewInteger)}{GB}
If \verb|Integer| is unbound, suspension occurs.
If it is not an integer, failure or exception occurs.
The result to subtract 1 from \verb|Integer| is unified with \verb|NewInteger|,
then if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Y := X - 1  <=>  decrement(X,Y).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{\verb|-|}
\Builtin{abs}{(Integer, ^NewInteger)}{GB}
If \verb|Integer| is unbound, suspension occurs.
If it is not an integer, failure or exception occurs.
The absolute value of \verb|Integer| is unified with \verb|NewInteger|,
then if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Y := abs(X)  <=>  abs(X,Y).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{abs}
\Builtin{min}{(Integer1, Integer2, ^NewInteger)}{GB}
If \verb|Integer1| or \verb|Integer2| is unbound, suspension occurs.
If terms are not integers, failure or exception occurs.
The lesser value of two input parameters is unified with \verb|NewInteger|.
Following macro can be used.
\begin{verbatim}
        Z := min(X,Y)  <=>  min(X,Y,Z).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{min}
\Builtin{max}{(Integer1, Integer2, ^NewInteger)}{GB}
If \verb|Integer1| or \verb|Integer2| is unbound, suspension occurs.
If terms are not integers, failure or exception occurs.
The larger value of two input parameters is unified with \verb|NewInteger|.
Following macro can be used.
\begin{verbatim}
        Z := max(X,Y)  <=>  max(X,Y,Z).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{max}
\Builtin{and}{(Integer1, Integer2, ^NewInteger)}{GB}
If \verb|Integer1| or \verb|Integer2| is unbound, suspension occurs.
If terms are not integers, failure or exception occurs.
The result of a bitwise logic and operation is unified with \verb|NewInteger|.
Following macro can be used.
\begin{verbatim}
        Z := X /\ Y  <=>  and(X,Y,Z).
\end{verbatim}

\index{\verb|/\|}
\Builtin{or}{(Integer1, Integer2, ^NewInteger)}{GB}
If \verb|Integer1| or \verb|Integer2| is unbound, suspension occurs.
If terms are not integers, failure or exception occurs.
The result of a bitwise logic or operation is unified with \verb|NewInteger|.
Following macro can be used.
\begin{verbatim}
        Z := X \/ Y  <=>  or(X,Y,Z).
\end{verbatim}

\index{\verb|\/|}
\Builtin{exclusive_or}{(Integer1, Integer2, ^NewInteger)}{GB}
If \verb|Integer1| or \verb|Integer2| is unbound, suspension occurs.
If terms are not integers, failure or exception occurs.
The result of a bitwise logic exclusive or operation is unified with 
\verb|NewInteger|. Following macro can be used.
\begin{verbatim}
        Z := X xor Y  <=>  exclusive_or(X,Y,Z).
\end{verbatim}

\index{xor}
\Builtin{complement}{(Integer, ^NewInteger)}{GB}
If \verb|Integer| is unbound, suspension occurs.
If it is not an integer, failure or exception occurs.
This unifies \verb|NewInteger| with the 1's complement of \verb|Integer|.
This is equivalent to exclusive_or(-1, \verb|Integer|, \verb|NewInteger|).
Following macro can be used.
\begin{verbatim}
        Y := \(X)  <=>  complement(X,Y).
\end{verbatim}

\index{\verb|\|}
\Builtin{shift_left}{(Integer, ShiftWidth, ^NewInteger)}{GB}
If \verb|Integer| is unbound, suspension occurs.
If it is not an integer, failure or exception occurs.
If \verb|ShiftWidth| is unbound, suspension occurs.
If it should be an integer in the range [0,31], failure or exception occurs.
\verb|NewInteger| is unified with the result of logic bitwise shift.
Following macro can be used.
\begin{verbatim}
        Z := X << Y  <=>  shift_left(X,Y,Z).
\end{verbatim}

\index{\verb|<<|}
\Builtin{shift_right}{(Integer, ShiftWidth, ^NewInteger)}{GB}
If \verb|Integer| is unbound, suspension occurs.
If it is not an integer, failure or exception occurs.
If \verb|ShiftWidth| is unbound, suspension occurs.
If it should be an integer in the range [0,31], failure or exception occurs.
\verb|NewInteger| is unified with the result of right logic bitwise shift.
Following macro can be used.
\begin{verbatim}
        Z := X >> Y  <=>  shift_right(X,Y,Z).
\end{verbatim}

\index{\verb|>>|}
\end{itemize}
\subsubsection{Arithmetic comparison (Floating point)}
\index{Built-in Predicates!Arithmetic Comparison(Floating Point)}
\begin{itemize}

\Builtin{floating_point_equal}{(Float1,Float2)}{G}
If \verb|Float1| or \verb|Float2| is unbound, suspension occurs.
If both \verb|Float1| and \verb|Float2| are floating points and equal,
this predicate succeeds. Otherwise it fails. Following macro can be used.
\begin{verbatim}
        X $=:= Y  <=>  floating_point_equal(X,Y).
\end{verbatim}

\index{\verb|$=:=|}
\Builtin{floating_point_not_equal}{(Float1, Float2)}{G}
If \verb|Float1| or \verb|Float2| is unbound, suspension occurs.
If both \verb|Float1| and \verb|Float2| are floating points and are not equal,
this predicate succeeds. Otherwise it fails. Following macro can be used.
\begin{verbatim}
        X $=\= Y  <=>  floating_point_not_equal(X,Y).
\end{verbatim}

\index{\verb|$=\=|}
\Builtin{floating_point_less_than}{(Float1,Float2)}{G}
If \verb|Float1| or \verb|Float2| is unbound, suspension occurs.
If both \verb|Float1| and \verb|Float2| are floating points 
and the value of the former is less than that of the latter,
this predicate succeeds. Otherwise it fails. Following macro can be used.
\begin{verbatim}
        X $< Y  <=>  floating_point_less_than(X,Y).
        X $> Y  <=>  floating_point_less_than(Y,X).
\end{verbatim}

\index{\verb|$<|} \index{\verb|$>|}
\Builtin{floating_point_not_less_than}{(Float1,Float2)}{G}
If \verb|Float1| or \verb|Float2| is unbound, suspension occurs.
If both \verb|Float1| and \verb|Float2| are floating points 
and the value of the former is larger than, or equal that of the latter,
this predicate succeeds. Otherwise it fails. Following macro can be used.
\begin{verbatim}
        X $>= Y  <=>  floating_point_not_less_than(X,Y).
        X $=< Y  <=>  floating_point_not_less_than(Y,X).
\end{verbatim}

\index{\verb|$>=|} \index{\verb|$=<|}
\end{itemize}
\subsubsection{Arithmetic operations (Floating point)}
\index{Built-in Predicates!Arithmetic Operations(Floating Point)}
\begin{itemize}

\Builtin{floating_point_add}{(Float1, Float2, ^NewFloat)}{GB}
If \verb|Float1| or \verb|Float2| is unbound, suspension occurs.
If terms are not floating points, failure or exception occurs.
The result of the addition is unified with \verb|NewFloat|, then
if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Z $:= X + Y  <=>  floating_point_add(X,Y,Z).
\end{verbatim}
\Caution On Multi-PSI V2, if overflow is detected, failure or exception 
will not occur, and \verb|infinity| outputs into \verb|NewFloat|.

\index{\verb|+|}
\Builtin{floating_point_subtract}{(Float1, Float2, ^NewFloat)}{GB}
If \verb|Float1| or \verb|Float2| is unbound, suspension occurs.
If terms are not floating points, failure or exception occurs.
The result of the subtraction is unified with \verb|NewFloat|, then
if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Z $:= X - Y  <=>  floating_point_subtract(X,Y,Z).
\end{verbatim}
\Caution On Multi-PSI V2, if overflow is detected, failure or exception 
will not occur, and \verb|infinity| outputs into \verb|NewFloat|.

\index{\verb|-|}
\Builtin{floating_point_multiply}{(Float1, Float2, ^NewFloat)}{GB}
If \verb|Float1| or \verb|Float2| is unbound, suspension occurs.
If terms are not floating points, failure or exception occurs.
The result of the multiplication is unified with \verb|NewFloat|, then
if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Z $:= X * Y  <=> floating_point_multiply(X,Y,Z).
\end{verbatim}
\Caution On Multi-PSI V2, if overflow is detected, failure or exception 
will not occur, and \verb|infinity| outputs into \verb|NewFloat|.

\index{\verb|*|}
\Builtin{floating_point_divide}{(Float1, Float2, ^NewFloat)}{GB}
If \verb|Float1| or \verb|Float2| is unbound, suspension occurs.
If terms are not floating points, failure or exception occurs.
The result of the division is unified with \verb|NewFloat|.
Then if overflow is detected, or if \verb|Float2| is bound to 0, 
failure or exception occurs. Following macro can be used.
\begin{verbatim}
        Z $:= X / Y  <=>  floating_point_divide(X,Y,Z).
\end{verbatim}
\Caution On Multi-PSI V2, if overflow is detected, failure or exception 
will not occur, and \verb|infinity| outputs into \verb|NewFloat|.

\index{\verb|/|}
\Builtin{floating_point_minus}{(Float, ^NewFloat)}{GB}
If \verb|Float| is unbound, suspension occurs.
If it is not a floating point, failure or exception occurs.
\verb|NewFloat| is unified with \verb|Float| with sign exchanged, then
if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Y $:= -X  <=>  floating_point_minus(X,Y).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{\verb|-|}
\Builtin{floating_point_abs}{(Float, ^NewFloat)}{GB}
If \verb|Float| is unbound, suspension occurs.
If it is not a floating point, failure or exception occurs.
The absolute value of \verb|Float| is unified with \verb|NewFloat|,
Following macro can be used.
\begin{verbatim}
        Y $:= abs(X)  <=>  floating_point_abs(X,Y).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{abs}
\Builtin{floating_point_min}{(Float1, Float2, ^NewFloat)}{GB}
If \verb|Float1| or \verb|Float2| is unbound, suspension occurs.
If terms are not floating points, failure or exception occurs.
The lesser value of two input parameters is unified with \verb|NewFloat|.
Following macro can be used.
\begin{verbatim}
        Z $:= min(X,Y)  <=>  floating_point_min(X,Y,Z).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{min}
\Builtin{floating_point_max}{(Float1, Float2, ^NewFloat)}{GB}
If \verb|Float1| or \verb|Float2| is unbound, suspension occurs.
If terms are not floating points, failure or exception occurs.
The larger value of two input parameters is unified with \verb|NewFloat|.
Following macro can be used.
\begin{verbatim}
        Z $:= max(X,Y)  <=>  floating_point_max(X,Y,Z).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{max}
\Builtin{floating_point_floor}{(Float, ^NewFloat)}{GB}
If \verb|Float| is unbound, suspension occurs.
If it is not a floating point, failure or exception occurs.
The largest integer not greater than \verb|Float| is unified with 
\verb|NewFloat|.
Following macro can be used.
\begin{verbatim}
        Y $:= floor(X)  <=>  floating_point_floor(X,Y).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{floor}
\Builtin{floating_point_sqrt}{(Float, ^NewFloat)}{GB}
If \verb|Float| is unbound, suspension occurs.
If it is not a floating point, failure or exception occurs.
If \verb|Float| is negative number, failure or exception occurs.
The square root of \verb|Float| is unified with \verb|NewFloat|.
Following macro can be used.
\begin{verbatim}
        Y $:= sqrt(X)  <=>  floating_point_sqrt(X,Y).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{sqrt}
\Builtin{floating_point_ln}{(Float, ^NewFloat)}{GB}
If \verb|Float| is unbound, suspension occurs.
If it is not a floating point, failure or exception occurs.
If \verb|Float| is less than 0.0, failure or exception occurs.
The natural logarithm of \verb|Float| is unified with \verb|NewFloat|.
Following macro can be used.
\begin{verbatim}
        Y $:= ln(X)  <=>  floating_point_ln(X,Y).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{ln}
\Builtin{floating_point_log}{(Float, ^NewFloat)}{GB}
If \verb|Float| is unbound, suspension occurs.
If it is not a floating point, failure or exception occurs.
If \verb|Float| is less than 0.0, failure or exception occurs.
The base 10 logarithm of \verb|Float| is unified with \verb|NewFloat|.
Following macro can be used.
\begin{verbatim}
        Y $:= log(X)  <=>  floating_point_log(X,Y).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{log}
\Builtin{floating_point_exp}{(Float, ^NewFloat)}{GB}
If \verb|Float| is unbound, suspension occurs.
If it is not a floating point, failure or exception occurs.
$e$ is raised to \verb|Float| power and
the result is unified with \verb|NewFloat|,
then if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Y $:= exp(X)  <=>  floating_point_exp(X,Y).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{exp}
\Builtin{floating_point_pow}{(Float1,Float2, ^NewFloat)}{GB}
If \verb|Float1| or \verb|Float2| is unbound, suspension occurs.
If terms are not floating points, failure or exception occurs.
If \verb|Float1| is not a negative number, and \verb|Float2| is not an integer,
failure or exception occurs.
\verb|Float1| is raised to \verb|Float2| power
and the result is unified with \verb|NewFloat|,
then if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Y $:= X**Y  <=>  floating_point_pow(X,Y,Z).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{\verb|**|}
\Builtin{floating_point_sin}{(Float, ^NewFloat)}{GB}
If \verb|Float| is unbound, suspension occurs.
If it is not a floating point, failure or exception occurs.
sin( \verb|Float|) is unified with \verb|NewFloat|,
then if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Y $:= sin(X)  <=>  floating_point_sin(X,Y).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{sin}
\Builtin{floating_point_cos}{(Float, ^NewFloat)}{GB}
If \verb|Float| is unbound, suspension occurs.
If it is not a floating point, failure or exception occurs.
cos( \verb|Float|) is unified with \verb|NewFloat|.
Following macro can be used.
\begin{verbatim}
        Y $:= cos(X)  <=>  floating_point_cos(X,Y).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{cos}
\Builtin{floating_point_tan}{(Float, ^NewFloat)}{GB}
If \verb|Float| is unbound, suspension occurs.
If it is not a floating point, failure or exception occurs.
tan( \verb|Float|) is unified with \verb|NewFloat|,
then if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Y $:= tan(X)  <=>  floating_point_tan(X,Y).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{tan}
\Builtin{floating_point_asin}{(Float, ^NewFloat)}{GB}
If \verb|Float| is unbound, suspension occurs.
If it is not a floating point, failure or exception occurs.
If \verb|Float| should be in the range [-1.0,1.0], 
failure or exception occurs.
arcsin( \verb|Float|) is unified with \verb|NewFloat|,
Following macro can be used.
\begin{verbatim}
        Y $:= asin(X)  <=>  floating_point_asin(X,Y).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{asin}
\Builtin{floating_point_acos}{(Float, ^NewFloat)}{GB}
If \verb|Float| is unbound, suspension occurs.
If it is not a floating point, failure or exception occurs.
If \verb|Float| should be in the range [-1.0,1.0], 
failure or exception occurs.
arccos( \verb|Float|) is unified with \verb|NewFloat|.
Following macro can be used.
\begin{verbatim}
        Y $:= acos(X)  <=>  floating_point_acos(X,Y).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{acos}
\Builtin{floating_point_atan}{(Float, ^NewFloat)}{GB}
If \verb|Float| is unbound, suspension occurs.
If it is not a floating point, failure or exception occurs.
arctan( \verb|Float|) is unified with \verb|NewFloat|,
then if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Y $:= atan(X)  <=>  floating_point_atan(X,Y).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{atan}
\Builtin{floating_point_atan}{(Float1,Float2, ^NewFloat)}{GB}
If \verb|Float1| or \verb|Float2| is unbound, suspension occurs.
If terms are not floating points, failure or exception occurs.
If \verb|Float2| is 0.0, failure or exception occurs.
arctan( \verb|Float|/ \verb|Float2|) is unified with \verb|NewFloat|,
then if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Z $:= atan(X/Y)  <=>  floating_point_atan(X,Y,Z).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{atan}
\Builtin{floating_point_sinh}{(Float, ^NewFloat)}{GB}
If \verb|Float| is unbound, suspension occurs.
If it is not a floating point, failure or exception occurs.
sinh( \verb|Float|) is unified with \verb|NewFloat|,
then if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Y $:= sinh(X)  <=>  floating_point_sinh(X,Y,Z).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{sinh}
\Builtin{floating_point_cosh}{(Float, ^NewFloat)}{GB}
If \verb|Float| is unbound, suspension occurs.
If it is not a floating point, failure or exception occurs.
sinh( \verb|Float|) is unified with \verb|NewFloat|,
then if overflow is detected, failure or exception occurs.
Following macro can be used.
\begin{verbatim}
        Y $:= cosh(X)  <=>  floating_point_cosh(X,Y).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{cosh}
\Builtin{floating_point_tanh}{(Float, ^NewFloat)}{GB}
If \verb|Float| is unbound, suspension occurs.
If it is not a floating point, failure or exception occurs.
tanh( \verb|Float|) is unified with \verb|NewFloat|,
Following macro can be used.
\begin{verbatim}
        Y $:= tanh(X)  <=>  floating_point_tanh(X,Y,Z).
\end{verbatim}
\Caution This is not supported on Multi-PSI V2.

\index{tanh}
\end{itemize}
\subsubsection{Conversion (Integer - Floating Point)}
\index{Built-in Predicates!Conversion}
\begin{itemize}
\Builtin{floating_point_to_integer}{(Float, ^Integer)}{GB}
If \verb|Float| is unbound, suspension occurs.
If it is not a floating point, failure or exception occurs.
Otherwise this predicate converts \verb|Float| into integer
(The integer is returned the value of
the least integer greater than  or equal to ) ,
and unifies it with \verb|Integer|.
Following macro can be used.
\begin{verbatim}
        Y := int(X)  <=>  floating_point_to_integer(X,Y,Z).
\end{verbatim}

\index{int}
\Builtin{integer_to_floating_point}{(Integer, ^Float)}{GB}
If \verb|Integer| is unbound, suspension occurs.
If it is not an integer, failure or exception occurs.
Otherwise this predicate converts \verb|Integer| into floating point,
and unifies it with \verb|Float|.
Following macro can be used.
\begin{verbatim}
        Y $:= float(X)  <=>  integer_to_floating_point(X,Y,Z).
\end{verbatim}

\index{float}
\end{itemize}
\subsubsection{Vector predicates}\index{Built-in Predicates!Vector Predicates}
\begin{itemize}

\Builtin{vector}{(X, ^Size)}{G}
If \verb|X| is unbound, suspension occurs. If \verb|X| is a vector,
this predicate succeeds and \verb|Size| is unified with the vector size.
Otherwise the predicate fails.

\Builtin{vector}{(X, ^Size, ^NewVector)}{B}
If \verb|X| is unbound, suspension occurs. If \verb|X| is a vector,
\verb|Size| is unified with the vector size, and
\verb|NewVector| is unified with a copy of \verb|X|.
Otherwise exception occurs.
This is useful to duplicate a vector and avoid
inter-process references, which are the pain for the garbage collector.

\Builtin{new_vector}{(^Vector, Size)}{B}
If \verb|Size| is unbound, suspension occurs.
If it is not positive or null, exception occurs.
If the size of a vector freshly allocated with size \verb|Size|
is beyond the heap size, exception occurs.
Otherwise this predicate unifies \verb|Vector| with a freshly allocated vector,
filled with zeros, which size is given by \verb|Size|.

\Builtin{vector_element}{(Vector, Position, ^Element)}{G}
This predicate is used to extract one element from a vector. 
If \verb|Vector| or \verb|Position| is unbound, suspension occurs.
If \verb|Vector| is not a vector, the predicate fails.
\verb|Position| indicates the rank of the element, starting from 0.
If \verb|Position| is not a positive integer, 
or if it is beyond the size of the vector, the predicate fails.
Otherwise \verb|Element| is unified with the result of extraction.

\Builtin{vector_element}{(Vector, Position, ^Element, ^NewVector)}{B}
This predicate is used to extract one element from a vector. 
If \verb|Vector| or \verb|Position| is unbound, suspension occurs.
If \verb|Vector| is not a vector, exception occurs.
\verb|Position| indicates the rank of the element, starting from 0.
If \verb|Position| is not a positive integer, 
or if it is beyond the size of the vector, exception occurs.
Otherwise \verb|Element| is unified with the result of extraction,
and \verb|NewVector| is unified with a copy of \verb|Vector|.
This is useful to avoid multiple references which could impair garbage
collector operations.

\Builtin{set_vector_element}{(Vector, Position, ^OldElem, NewElem, ^NewVect)}{B}
This predicate is used to extract one element from a vector and
replaces it with a new element, and makes a copy of the original vector.
If any of \verb|Vector| or \verb|Position| or \verb|NewElem| are unbound,
suspension occurs.
If \verb|Vector| is not a vector, exception occurs.
\verb|Position| indicates the rank of the element, starting from 0.
If \verb|Position| is not a positive integer, 
or if it is beyond the size of the vector, exception occurs.
Otherwise \verb|OldElem| is unified with the result of extraction.
Then the predicate makes a copy of \verb|Vector| and replaces the element 
specified by \verb|Position|, and unifies the modified vector 
with \verb|NewVect|.

\end{itemize}
\subsubsection{String predicates}\index{Built-in Predicates!String Predicates}
\begin{itemize}

\Builtin{string}{(X, ^Size, ^ElementSize)}{G}
If \verb|X| is unbound, suspension occurs. If \verb|X| is a string,
\verb|Size| is unified with the number of characters in the string
and \verb|ElementSize| is unified with the length of each character,
expressed in bits. Otherwise the predicate fails.

\Builtin{string}{(X, ^Size, ^ElementSize, ^NewString)}{B}
If \verb|X| is unbound, suspension occurs. If \verb|X| is a string,
\verb|Size| is unified with the number of characters in the string
and \verb|ElementSize| is unified with the length of each character,
expressed in bits. Then \verb|NewString| is unified with a copy of the string.
Otherwise exception occurs.

\Builtin{new_string}{(^String, Size, ElementSize)}{B}
If \verb|Size| or \verb|ElementSize| is unbound, suspension occurs.
\verb|Size| specifies the length of the string.
If \verb|Size| is not a positive integer, exception occurs.
\verb|ElementSize| specifies how many bits contains each character.
If \verb|ElementSize| is an integer in the range [1,32], exception occurs.
If the size of a string freshly created with size specified by
\verb|Size| and \verb|ElementSize| is beyond the heap size, exception occurs.
Otherwise the prediate unifies \verb|String| with a freshly created string
specified by \verb|Size| and \verb|ElementSize|.
The string is filled with zeros.

\Builtin{string_element}{(String, Position, ^Element)}{G}
This predicate is used to extract one character from a string.
If \verb|String| or \verb|Position| is unbound, suspension occurs.
If \verb|String| is not a string, this prediacte fails.
If \verb|Position| is not a positive integer or if it is beyond the length of
the string, the predicate fails.
Otherwise \verb|Element| is unified with the charactor(integer) specified by
\verb|Position|. \verb|Position| of the first character is 0.

\Builtin{string_element}{(String, Position, ^Element, ^NewString)}{B}
This predicate is used to extract one character from a string, and
makes a copy of an original string.
If \verb|String| or \verb|Position| is unbound, suspension occurs.
If \verb|String| is not a string, exception occcurs.
If \verb|Position| is not a positive integer or if it is beyond the length of
the string, exception occurs.
Otherwise \verb|Element| is unified with the charactor(integer) specified by
\verb|Position|, and \verb|NewString| is unified with a copy of \verb|String|.
\verb|Position| of the first character is 0.

\Builtin{set_string_element}{(String, Position, NewElement, ^NewString)}{B}
If \verb|String| or \verb|Position| or \verb|NewElement| is unbound,
suspension occurs.
If \verb|String| is not a string, exception occcurs.
If \verb|Position| is not a positive integer or if it is beyond the length of
the string, exception occurs.
If \verb|NewElement| is not an integer or if it is beyond the width of one
element, exception occurs.
Otherwise this predicate makes a copy of \verb|String| and replaces
the element of \verb|Position| with \verb|NewElement|, and
unifies the modified string with \verb|NewString|.

\Builtin{substring}{(String, Position, Length, ^SubString, ^NewString)}{B}
If \verb|String| or \verb|Position| or \verb|Length| is unbound,
suspension occurs.
If \verb|String| is not a string, exception occcurs.
If \verb|Position| is not a positive integer or if it is beyond the length of
the string, exception occurs.
If \verb|Length| is not a positive integer or if the length of \verb|Position|
+ \verb|Length| exceeds the length of \verb|String|, exception occurs.
Otherwise this predicate extracts a substring from the original string,
starting from \verb|Position| with length \verb|Length|.
Then \verb|SubString| is unified with the result, and \verb|NewString| is
unified with the original one.

\Builtin{set_substring}{(String, Position, SubString, ^NewString)}{B}
If \verb|String| or \verb|Position| or \verb|SubString| is unbound,
suspension occurs.
If \verb|String| is not a string, exception occcurs.
If \verb|Position| is not a positive integer or if it is beyond the length of
the string, exception occurs.
If the width of one element of \verb|SubString| is not the same as that of
\verb|String|, exception occurs.
If the length of \verb|SubString| + \verb|Position| exceeds the length of
\verb|String|, exception occurs.
Otherwise this predicate substitutes element(s) of the \verb|String| specified
by \verb|Position| for \verb|SubString|, and \verb|NewString| is unified with
the result of this substitution.

\Builtin{append_string}{(String1, String2, ^NewString)}{B}
If \verb|String1| or \verb|String2| is unbound, suspension occurs.
If two input strings are not the same bitwise type, exception occurs.
Otherwise this predicate unifies \verb|NewString| with the result of
concatenating \verb|String2| after \verb|String1|.

\end{itemize}
\subsubsection{Atom predicates}\index{Built-in Predicates!Atom Predicates}
\begin{itemize}

\Builtin{intern_atom}{(^Atom, String)}{B}
If \verb|String| is unbound, suspension occurs.
If \verb|String| is not a string of 8-bits characters, exception occurs.
Otherwise this predicate transforms a string of 8-bits characters \verb|String|
into an atom, whose name matches the string contents.
This atom is unified with \verb|Atom|.\\
\Caution On Multi-PSI V2, this is not a built-in predicate but a function
of operating system.

\Builtin{new_atom}{(^Atom)}{B}
This predicate creates a new atom and unifies it with \verb|Atom|.
The atom has no printing name.

\Builtin{atom_name}{(Atom, ^String)}{B}
If \verb|Atom| is unbound, suspension occurs, and
if it is not an atom, exception occurs.
Otherwise \verb|String| is unified with a 8-bits string which contains the name
of the atom.\\
\Caution On Multi-PSI V2, this is not a built-in predicate but a function
of operating system.

\Builtin{atom_number}{(Atom, ^Number)}{B}
If \verb|Atom| is unbound, suspension occurs, and
if it is not an atom, exception occurs.
Otherwise \verb|Number| is unified with the atom number
corresponding to \verb|Atom|.
The atom number is identically given by the system to each atom according to
the order of creation of it.

\end{itemize}
\subsubsection{Code predicates}\index{Built-in Predicates!Code Predicates}
\begin{itemize}

\Builtin{predicate_to_code}{(Mod, Pred, Arity, ^Code)}{B}
If any of \verb|Mod| or \verb|Pred| or \verb|Arity| are unbound,
suspension occurs.
If \verb|Mod| or \verb|Pred| is not an atom, or 
if \verb|Arity| is not a positive integer, exception occurs.
Otherwise \verb|Code| is unified with the code specified by \verb|Mod|,
\verb|Pred|, and \verb|Arity|.
If the module, specified by \verb|Mod|, does not exist,
or if the predicate is not found(i.e. it is not defined or is not be delared
as public), \verb|Code| is unified with an atom \verb|[]|.

\Builtin{code_to_predicate}{(Code, ^Mod, ^Pred, ^Arity, ^Info)}{B}
If \verb|Code| is unbound, suspension occurs.
If \verb|Code| is not a three-elements-vector, exception occurs.
Any elements of \verb|Code| are unbound, suspension occurs.
The fist element of it is a module name, and if it is not an atom or if it does
not exist, exception occurs.
The second element is a predicate name, and if it is not an atom or if it is
not found, exception occurs.
The third element is a number of arguments of the predicate,
and if it is not a positive integer, exception occurs.
Otherwise this predicate unifies the module name with \verb|Mod|, and
the predicate name with \verb|Pred|, and the number of arguments with
\verb|Arity|. \verb|Info| is unified with an integer indicating whether
the predicate is spied(1), or not(0).

\end{itemize}
\subsubsection{Stream support}\index{Built-in Predicates!Stream Support}
\begin{itemize}

\Builtin{merge}{(In, ^Out)}{B}
This primitive can be used to merge one or more input streams (\verb|In|) and
unify the result with \verb|Out|. A vector
of streams, if given as one of the input, is divided into its stream
components.
The following is a partial definition of this predicate :
\begin{verbatim}
        merge([], O) :- true | O=[].
        merge([A|I], O) :- true | O=[A|NO], merge(I, NO).
        merge({}, O) :- true | O=[].
        merge({I}, O) :- true | merge(I, O).
        merge({I1,I2}, O) :- true | merge(I1, I2, O).
        merge({I1,I2,I3}, O) :- true | merge(I1, I2, I3, O).
                        ...
        merge([], I2, O) :- true | merge(I2, O).
        merge(I1, [], O) :- true | merge(I1, O).
        merge([A|I1], I2, O) :- true | O=[A|NO], merge(I1, I2, NO).
        merge(I1, [A|I2], O) :- true | O=[A|NO], merge(I1, I2, NO).
        merge({}, I2, O) :- true | merge(I2, O).
        merge(I1, {}, O) :- true | merge(I1, O).
        merge({I3,I4}, I2, O) :- true | merge(I3, I4, I2, O).
        merge({I3,I4,I5}, I2, O) :- true | merge(I3, I4, I5, I2, O).
                        ...
\end{verbatim}

\end{itemize}
\subsubsection{Second order function}
\index{Built-in Predicates!Second Order Function}
\begin{itemize}

\Builtin{apply}{(Code, Args)}{B}
If \verb|Code| or \verb|Args| is unbound, suspension occurs.
If \verb|Code| is not a three-elements-vector, exception occurs.
Any elements of \verb|Code| are unbound, suspension occurs.
The fist element of it is a module name, and if it is not an atom
or if it does not exist, exception occurs.
The second element is a predicate name, and if it is not an atom
or if it is not found, exception occurs.
The third element is a number of arguments of the predicate,
and if it is not a positive integer, exception occurs.
If \verb|Args| is not a vector or if the number of arguments of it is not
identical with the third element of \verb|Code|, exception occcurs.
Otherwise this primitive calls the predicate specified by \verb|Code|,
with arguments specified by \verb|Args|.

\end{itemize}
\subsubsection{Special I/O functions}
\index{Built-in Predicates!Special I/O Functions}
\begin{itemize}

\Builtin{read_console}{(^Integer)}{G}
This predicate unifies \verb|Integer| with a number
read from the console window.\\
\Caution The language processor is halted during this operation. This
predicate is used mainly for debugging purposes.

\Builtin{display_console}{(X)}{G}
This predicate displays the current value of \verb|X| on the console window,
even if this variable is unbound.

\Builtin{put_console}{(X)}{G}
If \verb|X| is an integer, this primitive puts the equivalent ASCII character
on the console window.
If \verb|X| is an 8-bits character string,
the string is put on the console window.
If \verb|X| is undefined, or has any other type, the predicate does nothing.
Anyway no line feed or carriage return is added.

\end{itemize}
\subsubsection{Other predicates}
\begin{itemize}

\Builtin{raise}{(Tag, Type, Info)}{B}
If \verb|Tag| is unbound, suspension occurs.
If it is not a positive integer, exception occurs.
A ground-term does not include any unbound variables.
If \verb|Type| is not a ground-term, suspension occurs. Otherwise
this predicate causes \verb|Tag| to be logically and-ed with the tag of all
ancestor Sho-ens, starting from the current Sho-en until the top, recursively.
This process stops as soon as the result of the and operation is not zero.
Then, a message is inserted in the report stream of the referred Sho-en.
This message is as follows
(also see exception information in chapter \ref{sec-shoen}) : 
\begin{verbatim}
        exception(12, {0, Type, Info}, NewCode, NewArgv)
\end{verbatim}

\Builtin{consume_resource}{(Red)}{B}
If \verb|Red| is unbound, suspension occurs.
If it is not a positive integer, exception occurs.
Otherwise this predicate emulates the consumption of computing resources,
as if due to actual reductions.
\verb|Red| is the number which is added to the count of performed reductions.
If this count exceeds the allowed maximum,
the \verb|resource_low| condition occurs.

\Builtin{hash}{(X, ^Value, ^NewX)}{B}
If \verb|X| is unbound, suspension occurs.
Otherwise this predicate unifies \verb|Value| with a hash code computed
according to \verb|X|, and also unifies \verb|NewX| with \verb|X|.

\Builtin{current_processor}{(^ProcessorNumber, ^X, ^Y)}{B}
This predicate unifies \verb|ProcessorNumber| with the processor number of the
processor executing this predicate.
\verb|X| and \verb|Y| are unified with the coordinates of this processor,
depending on the topology of the connection network.
On PDSS, which emulates execution by a single processor,
\verb|ProcessorNumber| is unified arbitrarily with 0, and
\verb|X| and \verb|Y| are unified with 1.

\Builtin{current_priority}{(^CurrentPriority, ^ShoenMin, ^ShoenMax)}{B}
This predicate unifies \verb|CurrentPriority| with the priority of the goal
executing this predicate.
And it also unifies \verb|ShoenMin| with the lower limit of priority
in the Sho-en, \verb|ShoenMax| with the upper limit of priority.

\end{itemize}

\subsection{Macros\index{Macros}}
\label{sec-macro}

For ease of writing, several categories of macros have been introduced in KL1.
\begin{itemize}
\item Macros for the description of constants.
\item Macros for arithmetic comparison.
\item Macros for conditional branch.
\item Macros for the declaration of implicit arguments.
\end{itemize}
In the current version, users cannot define their own macros.

\subsubsection{Constant description macros}\index{Constant Description Macros}

The following macros generate constant numbers.\index{Strings} \index{\verb|#|}
\begin{itemize}

\Macro{\verb|Base#"character-string"|}\\
This macro generates an integer number, in the integer \verb|Base|
specified before the sharp sign.
The base must be from 2 to 36. Figures can be taken in
[0,9] and [a/A,z/Z], as most commonly.

\Macro{\verb|string#"character-string"|}\\
This macro can be used to generate a string of default type.
Within PDSS, default type is ASCII stored as 8 bits characters.
On Multi-PSI V2, characters are taken within the JIS Kanji set,
stored as 2 bytes characters.

\Macro{\verb|ascii#"character-string"|}\\
This is useful to assert that the generated string is coded in ASCII, within
one byte characters.

\Macro{\verb|#"character"|}\\
This macro generates a character, using the default representation of
the system. In this aspect, it is similar to the \verb|string| macro
introduced above. On Multi-PSI V2, characters are taken within
the JIS Kanji set.

\Macro{\verb|c#"character"|}\\
This macro asserts generation of an ASCII character, stored as a single byte.

\Macro{\verb|ascii#character-atom|}\\
This has the same effect, but the character is entered as an atom,
not between double quotes. (ex: \verb|ascii#'['|).

\Macro{\verb|key#lf|}\\
This macro generates a line feed in ASCII.

\Macro{\verb|key#cr|}\\
This macro generates a carriage return in ASCII.

\end{itemize}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{table}[t]
\begin{center}
\begin{tabular}{|c|c|l|}
\multicolumn{3}{l}{\BF For Integer}\\ \hline
Priority   & Operator & \multicolumn{1}{c|}{Expanded pattern} \\ \hline\hline
         & \verb|X =:= Y| & equal(X,Y)         \\
 700     & \verb|X =\= Y| & not_equal(X,Y)     \\
(xfx)    & \verb|X < Y|   & less_than(X,Y)     \\
         & \verb|X > Y|   & less_than(Y,X)     \\
         & \verb|X =< Y|  & not_less_than(Y,X) \\
         & \verb|X >= Y|  & not_less_than(X,Y) \\ \hline
\end{tabular}
\index{equal}  \index{not_equal}  \index{less_than}  \index{not_less_than}
\index{\verb|=:=|} \index{\verb|=\=|} \index{\verb|<|} \index{\verb|>|}
\index{\verb|=<|} \index{\verb|>=|}
\hspace{1em}
\begin{tabular}{|c|c|l|}
\multicolumn{3}{l}{\BF For Floating Point}\\ \hline
Priority   & Operator & \multicolumn{1}{c|}{Expanded pattern} \\ \hline\hline
         & \verb|X $=:= Y| & floating_point_equal(X,Y)         \\
 700     & \verb|X $=\= Y| & floating_point_not_equal(X,Y)     \\
(xfx)    & \verb|X $< Y|   & floating_point_less_than(X,Y)     \\
         & \verb|X $> Y|   & floating_point_less_than(Y,X)     \\
         & \verb|X $=< Y|  & floating_point_not_less_than(Y,X) \\
         & \verb|X $>= Y|  & floating_point_not_less_than(X,Y) \\ \hline
\end{tabular}
\index{floating_point_equal}      \index{floating_point_not_equal}
\index{floating_point_less_than}  \index{floating_point_not_less_than}
\index{\verb|$=:=|} \index{\verb|$=\=|} \index{\verb|$<|} \index{\verb|$>|}
\index{\verb|$=<|} \index{\verb|$>=|}
\caption{Arithmetic Comparison Macros}
\label{tab-macro-compare}
\end{center}
\end{table}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Unification macros\index{Unification Macros}}
\begin{itemize}

\Macro{\verb|left-hand = right-hand|}\\ \index{\verb|=|}
This macro performs unification of left and right hands. It can be used in
body and guard.

\Macro{\verb|left-hand \= right-hand|}\\ \index{\verb|\=|}
This is equivalent to diff(\verb|left-hand|, \verb|right-hand|).
This macro can be used only in guard part of a clause.

\Macro{\verb|left-hand := right-hand|}\\ \index{\verb|:=|}
This macro unifies the left hand with the right hand, but if integer operation
macros feature in the right hand, evaluation takes place. This macro, which can
be used in guard or body, is similar to the ``is'' operator of Prolog.

\Macro{\verb|left-hand $:= right-hand|}\\ \index{\verb|$:=|}
This macro unifies the left hand with the right hand, but if floating point
operation macros feature in the right hand, evaluation takes place.
This macro, which can be used in guard or body, is similar to
the ``is'' operator of Prolog.
\end{itemize}

\subsubsection{Arithmetic comparison macros}
\index{Arithmetic Comparison Macros}

Arithmetic comparison operators can be used in guard, in place of built-in
predicates. But integer or floating point operation macros in both hands of
the comparison are not evaluated when built-in predicates are used.
The comparison operators are described in Table \ref{tab-macro-compare}.

\def\M#1{\multicolumn{2}{|c|}{#1}}
\begin{table}[t]
\begin{center}\
\begin{tabular}{|c|c|c|c|l|l|}\hline
Priority & Type & Operator & Expansion
& \multicolumn{2}{c|}{Generated built-in predicate}\\ \cline{5-6}
       &    &          &pattern
&\multicolumn{1}{c|}{in integer expression}
&\multicolumn{1}{c|}{in floating point expression} \\ \hline\hline
    & yfx & X \verb|+| 1      & Z & increment(X,Z)                  &\\
500 & yfx & X \verb|+| Y      & Z & add(X,Y,Z)
                                    & floating_point_add(X,Y,Z)      \\
    & yfx & X \verb|-| 1      & Z & decrement(X,Z)                  &\\
    & yfx & X \verb|-| Y      & Z & subtract(X,Y,Z)
                                    & floating_point_subtract(X,Y,Z) \\
    &  fx & \verb|-| X        & Z & minus(X,Z)
                                    & floating_point_minus(X,Z)      \\
    & yfx & X \verb|\/| Y     & Z & or(X,Y,Z)                       &\\
    & yfx & X \verb|/\| Y     & Z & and(X,Y,Z)                      &\\
    & yfx & X xor Y           & Z & exclusive_or(X,Y,Z)             &\\ \hline
    & yfx & X \verb|*| Y      & Z & multiply(X,Y,Z)
                                    & floating_point_multiply(X,Y,Z) \\
400 & yfx & X \verb|/| Y      & Z & divide(X,Y,Z)
                                    & floating_point_divide(X,Y,Z)   \\
    & yfx & X \verb|<<| Y     & Z & shift_left(X,Y,Z)               &\\
    & yfx & X \verb|>>| Y     & Z & shift_right(X,Y,Z)              &\\ \hline
300 & xfx & X mod Y           & Z & modulo(X,Y,Z)                   &\\
    & xfy & X \verb|**| Y     & Z & & floating_point_pow(X,Y,Z)      \\ \hline
\M{}      & abs(X)            & Z & abs(X,Z)
                                    & floating_point_abs(X,Z)        \\
\M{as a term} & min(X,Y)       & Z & min(X,Y,Z)
                                    & floating_point_min(X,Y,Z)      \\
\M{}      & max(X,Y)          & Z & max(X,Y,Z)
                                    & floating_point_max(X,Y,Z)      \\
\M{}      & \verb|\|(X)       & Z & complement(X,Z)                 &\\
\M{}      & floor(X)          & Z & & floating_point_floor(X,Z)      \\
\M{}      & sqrt(X)           & Z & & floating_point_sqrt(X,Z)       \\
\M{}      & ln(X)             & Z & & floating_point_ln(X,Z)         \\
\M{}      & log(X)            & Z & & floating_point_log(X,Z)        \\
\M{}      & exp(X)            & Z & & floating_point_exp(X,Z)        \\
\M{}      & sin(X)            & Z & & floating_point_sin(X,Z)        \\
\M{}      & cos(X)            & Z & & floating_point_cos(X,Z)        \\
\M{}      & tan(X)            & Z & & floating_point_tan(X,Z)        \\
\M{}      & asin(X)           & Z & & floating_point_asin(X,Z)       \\
\M{}      & acos(X)           & Z & & floating_point_acos(X,Z)       \\
\M{}      & atan(X)           & Z & & floating_point_atan(X,Z)       \\
\M{}      & atan(X\verb|/|Y)  & Z & & floating_point_atan(X,Y,Z)     \\
\M{}      & sinh(X)           & Z & & floating_point_sinh(X,Z)       \\
\M{}      & cosh(X)           & Z & & floating_point_cosh(X,Z)       \\
\M{}      & tanh(X)           & Z & & floating_point_tanh(X,Z)       \\
\M{}      & int(F)            & I & floating_point_to_integer(F,I)  &\\
\M{}      & float(I)          & F & & integer_to_floating_point(I,F) \\ \hline
\end{tabular}
%%%% index %%%%%
\index{increment}
\index{add}				\index{floating_point_add}
\index{decrement}
\index{subtract}			\index{floating_point_subtract}
\index{minus}				\index{floating_point_minus}
\index{or}
\index{and}
\index{exclusive_or}
\index{multiply}			\index{floating_point_multiply}
\index{divide}				\index{floating_point_divide}
\index{shift_left}
\index{shift_right}
\index{modulo}
					\index{floating_point_pow}
\index{abs}				\index{floating_point_abs}
\index{min}				\index{floating_point_min}
\index{max}				\index{floating_point_max}
\index{complement}
					\index{floating_point_floor}
					\index{floating_point_sqrt}
					\index{floating_point_ln}
					\index{floating_point_log}
					\index{floating_point_exp}
					\index{floating_point_sin}
					\index{floating_point_cos}
					\index{floating_point_tan}
					\index{floating_point_asin}
					\index{floating_point_acos}
					\index{floating_point_atan}
					\index{floating_point_sinh}
					\index{floating_point_cosh}
					\index{floating_point_tanh}
\index{floating_point_to_integer}	\index{integer_to_floating_point}
\index{\verb|+|} \index{\verb|-|} \index{\verb|\/|} \index{\verb|/\|}
\index{xor} \index{\verb|*|} \index{\verb|/|} \index{\verb|<<|}
\index{\verb|>>|} \index{mod} \index{\verb|**|} \index{\verb|\|}
\index{floor} \index{sqrt} \index{ln} \index{log} \index{exp} \index{sin}
\index{cos} \index{tan} \index{asin} \index{acos} \index{atan} \index{sinh}
\index{cosh} \index{tanh} \index{int} \index{float}
\caption{Arithmetic operation macros}
\label{tab-macro-calculate}
\end{center}
\end{table}

\subsubsection{Arithmetic operation macros\index{Arithmetic Operation Macros}}

Arithmetic macros are using \verb|+,-,*,/|.
The conversion of data types needs to describe it explicitly,
because it is not performed automatically by the system.
Expansion is done according to the following rules :
\begin{itemize}

\item The right hand of the \verb|:=|, \verb|$:=| macro\\
\index{\verb|:=|} \index{\verb|$:=|}
The result of the evaluation of the right hand of the operator is
unified with the left hand (as for the ``is'' operator of Prolog).
\verb|:=| is used for integer operation,
and \verb|$:=| for floating point operation.

\item Both hands of comparison macros\\
The both results of the evaluation are compared to each other.
The operator without \verb|$| is used for integer operation, and
one with \verb|$| is for floating point operation.

\item The right hand of implicit argument macro \verb|<=|, \verb|$<=|\\
\index{\verb|<=|} \index{\verb|$<=|}
The result of evaluation of the right hand side is unified
with the argument specified by left hand side.
\verb|<=| is used for integer operation, and
\verb|$<=| is for floating point operation.

\item In the case that \verb|~(expression)| or \verb|$~(expression)|
is used to explicitly require expansion of the expression.\\
\index{\verb|~|} \index{\verb|$~|}
ex: \verb|p(~(X+Y+1))| becomes \verb|add(X,Y,A),add(A,1,B),p(B)|.
\end{itemize}
Macros embedding constants are evaluated during compilation.

The arithmetic operators are described in Table \ref{tab-macro-calculate}. 
The higher is the priority, the lower is the precedence.
It is always possible to make a term by using \verb|( )|.\\
\Caution On Multi-PSI V2, supported floating point operators are only on
the arithmetic operation.

When users need to constrain expansion of macros, it is used back quotes.
\index{Constraint of Macro Expansion}
\begin{itemize}
\item ``(term)\\ \index{\verb|``|}
All the expansion of macro in "term" are completely constrained.
\item `(term)\\ \index{\verb|`|}
If "term" is a structure, the expansion of the top level of it is exclusively
constrained, and at the deeper level macros are expanded.
\end{itemize}
\vspace{1ex}

\subsubsection{Macros for implicit argument passing}
\index{Implicit Argument Macros}

It is very unconvenient to rewrite arguments which appear recurrently in the
head of several clauses. To lighten this tedium, implicit argument
 support(through macros) has been provided.

Two kinds of parameter declarations are possible, depending on the scope which
is desired. The first one is global, i.e applies to a module wholly,
whereas the second is local to a part of a module :
\index{Implicit Argument Macros!Global Declaration}
\index{Implicit Argument Macros!Local Declaration}
\begin{verbatim}

        :- implicit arg-name : type { , arg-name : type , ... }.

        :- local_implicit arg-name : type { , arg-name : type , ... }.

\end{verbatim}
\index{implicit} \index{local_implicit}
Here, \verb|arg-name| (atom) is the name of the implicit argument.
Type can be : \verb|shared|, \verb|stream|, \verb|oldnew|
or \verb|string|.

The global implicit declaration can appear only once in a module, right after
the public declaration.
Local declarations can appear several times in a module.
Each time it appears, it invalidates the previous declaration. To suppress
the usage of all implicit arguments, use the following :
\begin{verbatim}
        :- local_implicit.
\end{verbatim}
The name space of local and global arguments are the same, so that different
names have to be used.

\index{Implicit Argument Macros!Expansion}
Using \verb|-->|\index{\verb|-->|} in place of \verb|:-|,
means that a predicate uses implicit arguments.
They are inserted in the predicate arguments list, before
arguments explicitly given by the user. Exact order is as follows :
\begin{enumerate}
\item Global arguments
\item Local arguments
\item explicit arguments (order is not changed)
\end{enumerate}
$\ll$ \verb|ex| $\gg$\\
\begin{verbatim}
          :- module test.
          :- public XXX.
          :- implicit a:oldnew, b:shared.

          p(X) --> true | q(X), r.
             %% Here, a and b are added to the argument list.
              ...

          :- local_implicit d:oldnew.
             %% At this point a,b and d are added.
              ...

          :- local_implicit d:shared, e:stream.
             %% From this point, a,b,d and e are added.
             %% The type of d has changed, from oldnew to shared.
              ...

          :- local_implicit.
             %% From this point, only the global args. a and b will be added.
              ...

\end{verbatim}

\index{Implicit Argument Macros!Access to Arguments}
To access a global argument in a clause, \verb|&|\index{\verb|&|}
must be put before the argument. To update a value (or unify with some value),
\index{Implicit Argument Macros!Update Arguments}
the operator \verb|<=| or \verb|$<=| or \verb|<<=| is used.
\index{\verb|<=|} \index{\verb|$<=|} \index{\verb|<<=|}
If the argument is a string or a vector, use :
\begin{verbatim}
                &arg-name(position)
\end{verbatim}
to update or access one of its elements. The first element has position 1.
The following is a presentation of each type, with some examples.
\vspace{1ex}

\noindent\underline{\bf shared argument type}
\index{Shared Argument} \vspace{1ex}\par
If no update of a shared argument occurs within a given clause, all goals
of the clause share the same instance of the argument. This is illustrated in
example a) below. If the value has to be updated in the clause, use the
following syntax :
\begin{verbatim}
                &arg-name  <= new-value
                &arg-name $<= new-value
\end{verbatim} \index{\verb|<=|} \index{\verb|$<=|}
The new value is effective after update. That means that the respective
position of update statement and goals in a clause determines whether the
old argument value or the new argument value is used. This is illustrated
in examples b) to d).\vspace{1ex}

$\ll$ \verb|ex| $\gg$ \verb| definition:  :- implicit counter:shared.|
\begin{verbatim}

  a) before expansion:  p --> true | q, r.
     after expansion:   p(Cnt) :- true | q(Cnt), r(Cnt).

  b) before:  p --> true | &counter <= &counter + 1, q.
     after:   p(Cnt) :- true | add(Cnt,1,Cnt1), q(Cnt1).

  c) before:  p --> true | &counter <= &counter+1, &counter <= &counter*2, q.
     after:   p(Cnt) :- true | add(Cnt,1,Cnt1), multiply(Cnt1,2,Cnt2), q(Cnt2).

  d) before:  p --> true | &counter <= &counter(2), q.
     after:   p(Cnt) :- true | set_vector_element(Cnt,2,Elem,Elem,_), q(Elem).
\end{verbatim}
\vspace{1ex}

\noindent\underline{\bf stream argument type}
\index{Stream argument} \vspace{1ex}\par
This type is provided to ease output stream management. If no update occurs
within the clause, the streams coming from goals are merged into the argument
stream. This is illustrated below, in example a). To update the stream, i.e.
insert elements, the following syntax should be used :\index{\verb|<<=|}
\begin{verbatim}
                &arg-name <<= [element 1, element 2, ... ]
\end{verbatim}
This is illustrated below, in example b). Note that the relative position
of the update within the clause conditions the insertion order, although this
may be of little importance for streams.\vspace{1ex}

$\ll$ \verb|ex| $\gg$ \verb| definition:  :- implicit window:stream.|
\begin {verbatim}

  a) before expansion:  p --> true | q, r.
     after expansion:   p(Win) :- true | Win={In1,In2}, q(In1), r(In2).

  b) before:  p --> true | &window <<= [putb("gazonk")], r.
     after:   p(Win) :- true | Win=[putb("gazonk")|Win1], r(Win1).
\end{verbatim}
\vspace{1ex}

\noindent\underline{\bf oldnew argument type}
\index{Oldnew Argument} \vspace{1ex}\par
This type calls after a pair of arguments, in a similar fashion to Prolog's
DCG, except that arguments are not restricted to difference lists. As an
example, when using a vector as an updatable table, to improve efficiency, one
often restricts the number of references to 1. To this end, the oldnew argument
type is useful. Also, if you use this type of argument for a difference list,
there is a notation to concatenate elements to the list, like for the stream
type :\index{\verb|<<=|}
\begin{verbatim}
                &arg-name <<= [element 1, element 2, ... ]
\end{verbatim}
If the argument is an integer or a floating point,
use the following for update :
\begin{verbatim}
                &arg-name  <= new-value
                &arg-name $<= new-value
\end{verbatim}
If argument is a vector, use the following syntax.
Then on the right side of \verb|<=| integer operation macros are expanded, and
on the left side of \verb|$<=| floating point operation macros are expanded.
\index{\verb|<=|} \index{\verb|$<=|}
\begin{verbatim}
        { element update(1) }
                &arg-name(position)  <= new-value
                &arg-name(position) $<= new-value

        { element reference }
                &arg-name(position)    %% cannot also appear on the left side of <=

        { element update(2) }
                &arg-name(position) <<= [element 1, element 2, ... ]
\end{verbatim}
update(1) and update(2) can be used in body part only,
 as they use the built-in predicate
set_vector_element/5. Reference can appear in guard, where it appeals to
vector_element/3, or in body, where it uses vector_element/5. The relationship
between homonymous elements is similar to that of DCG (from left to right,
top to bottom). See example a),b) and f) below.

In (1), replacement is done at the specified position, as illustrated in
examples c) and d). In (2), the right side list is inserted in the difference
list. New tail is set to the location specified by position. See example e).

There is also a way to refer the current old value of some argument :
\begin{verbatim}
                &arg-name(old)
\end{verbatim}
This is useful in particular to access the value of a counter. This is
illustrated in example g) below.\vspace{1ex}

$\ll$ \verb|ex| $\gg$ \verb| definition:  :- implicit mutter:oldnew.|
\begin{verbatim}

  a) before expansion:  p --> true | q, r.
     after expansion:   p(Old,New) :- true | q(Old,Mid), r(Mid,New).

  b) before:  p --> true | &mutter <<= [naha], r.
     after:   p(Old,New) :- true | Old=[naha|Mid], r(Mid,New).

  c) before:  p --> true | &mutter(3) <= naha, r.
     after:   p(Old,New) :- true | set_vector_element(Old,3,_,naha,Mid), r(Mid,New).

  d) before:  p --> true | &mutter(1) <= &mutter(3), r.
     after:   p(Old,New) :- true |
                  set_vector_element(Old,3,Elem,Elem,Mid1),
                  set_vector_element(Mid1,1,_,Elem,Mid2), r(Mid2,New).

  e) before:  p --> true | &mutter(2) <<= [naha,uhi,ehe], r.
     after:   p(Old,New) :- true |
                  set_vector_element(Old,2,[naha,uhi,ehe|Cdr],Cdr,Mid),
                  r(Mid,New).

  f) before:  p --> true | &mutter <= &mutter+1, r.
     after:   p(Old,New) :- true | add(Old,1,Mid), r(Mid,New).

  g) before:  p(X) --> true | X = [&mutter(old)|XX], &mutter <= &mutter+1, p(XX).
     after:   p(Old,New,X) :- true | X=[Old|XX], add(Old,1,Mid), p(Mid,New,XX).
\end{verbatim}
\vspace{1ex}

\noindent\underline{\bf string argument type}
\index{String Argument} \vspace{1ex}\par
This works basically as the previous type, except that
predicates string_element/3 and set_string_element/4 are used instead of
vector-based predicates.
\vspace{2ex}

\noindent\underline{\bf Automatic generation of terminating processes}
\index{Implicit Argument Macros!Terminating Process}
\vspace{1ex}\par
When no user-defined goal is called in the body, the following unifications
are automatically performed, depending on the type of declared arguments :

\vspace{1ex}
\hspace*{15mm}\begin{tabular}{l@{ :: }l}
shared type & Nothing done.\\
stream type & Unification with the atom \verb|[]|.\\
oldnew type & Old and New are unified.\\
string type & Old and New are unified.\\
\end{tabular}
\vspace{1ex}

\noindent\underline{\bf Implicit arguments expansion control}
\index{Implicit Argument Macros!Expansion Control} \vspace{1ex}\par
If you call a predicate with no implicit arguments from a predicate with
implicit arguments, use double braces : \verb|{{| predicate(...) \verb|}}|,
in order to suppress argument addition. See example below :
\begin{verbatim}

        :- module test.
        :- public go/0.
        :- implicit    input   : stream,
                       output  : oldnew,
                       counter : shared.

        go :- true |
            merge(FILEout, FILEin),
            file:create(FILEin, "del.del", r),
            file:create(Answer, "/tmp/miyadel", w),
            loop(FILEout, Answer,[], 100 ,_).

        loop(_) --> &counter =< 0 | true.
        otherwise.
        loop(A) --> true |
            &counter <= &counter - 1,
            &input <<= [getc(X)],
          {{ check(X, &output, &counter) }},
            loop(A).

        check(ascii#a, Oh,Ot, Counter) :- true | Oh=[putt(Counter),nl|Ot].
        otherwise.
        check(_, Oh,Ot, _) :- true | Oh=Ot.

\end{verbatim}
In the previous example, three global implicit arguments are declared,
with types \verb|stream|, \verb|oldnew| and \verb|shared|.
Predicates using \verb|-->| instead of \verb|:-| are
regarded as having three implicit arguments and are converted at
preprocessing time. As an example, loop predicate is expanded as follows :
\begin{verbatim}

        loop(In, Oh,Ot, Cnt, A) :- Cnt =< 0 | In=[], Oh=Ot.
        otherwise.
        loop(In, Oh,Ot, Cnt, A) :- true |
            Cnt1 := Cnt-1, In=[getc(X)|In1],
            check(X, Oh,Om, Cnt1),
            loop(In1, Om,Ot, Cnt1, A).

\end{verbatim}
Note that the check/4 predicate, used between braces, has no implicit argument,
and is expanded as a predicate of arity 4. In order to use some of implicit
arguments when calling this predicate, \verb|&| has to be put before the names
of the implicit arguments which are explicitely specified in the call.
\vspace{2ex}

\noindent\Caution
Can implicit arguments take any value, declared types notwithstanding.
As a matter of fact, the macro processor only expands. If the programmer is
not careful enough, errors may be difficult to detect.

\subsubsection{Conditional branch macros} \index{Conditional Branch Macros}

The following is a notation which allows conditional execution within a single
clause, as in DEC10 Prolog :
\begin{verbatim}
                foo(X,Y) :- true |
                    ( X=:=0 -> p(Y,Z);
                      X > 0 -> q(Y,Z);
                      otherwise;
                      true  -> r(Y,Z) ),
                    s(X,Z).
\end{verbatim}\index{\verb|->|}
If the goal on the left hand side of \verb|->| is a condition and if this
condition is satisfied, then the goal on the right hand side is executed.
The preprocessor generates the following KL1 clauses, from the above
example :
\begin{verbatim}
                foo(X,Y) :- true |
                    '$foo/2/0'(X,Y,Z),
                    s(X,Z).

                '$foo/2/0'(X,Y,Z) :- X=:=0 | p(Y,Z).
                '$foo/2/0'(X,Y,Z) :- X > 0 | q(Y,Z).
                otherwise.
                '$foo/2/0'(X,Y,Z) :- true  | r(Y,Z).
\end{verbatim}
The predicate \verb|'$foo/2/0'| has been generated by the preprocessor. More
generally, predicates starting with a dollar sign are generated by the
preprocessor. The user should not use the same convention!

\Caution Only built-in predicates may be included in a conditional branch.

\Caution The Prolog-based compiler does not support nested conditions, whereas
the KL1 compiler does.

\subsubsection{Macro library} \index{Macro Library}

Macros in system's library to be used should be declared at the top
of the module. Declaration goes as follows :\index{with_macro}
\begin{verbatim}
        :- with_macro macro-definition-name.
\end{verbatim}
where \verb|macro-definition-name| is an atom. 

The macro definition files are located in a system dependant directory.
In this file, macros are defined as follows :
\begin{verbatim}
        fileio#normal      => 0.
        fileio#end_of_file => 1.
        fileio#read_error  => 2.
        fileio#write_error => 3.
\end{verbatim}\index{\verb|#|}\index{\verb|=>|}
In the current version, the left part from the sharp sign must be an atom.

\newpage
\section{Micro PIMOS} \index{Micro PIMOS}
\label{sec-Micro-PIMOS}

Micro PIMOS is a very simple operating system which provides various
services for KL1 users on PDSS. 
It is basically designed for single user, single task operations.
Services supported by Micro PIMOS follow :
\begin{itemize}
\item Command Interpreter.
\item I/O Functions (windows, files, etc.).
\item Code Management.
\item Display of exception information.
\end{itemize}

On Micro PIMOS, all commands given to the command interpreter are executed
within a unit called 'task'. The task is implemented using Sho-en functions
described in section \ref{sec-shoen}.

\Caution Bits 15:31 in exception tag are reserved for 
Micro PIMOS. When using functions of Micro PIMOS,
user must not modify bits 15:31 in tag of his Sho-en.
Beside commands, a way to use
Micro PIMOS functions
is to issue requests to Micro PIMOS through the user's goal
which supervises the Sho-en.\index{Exception Tag}

\begin{figure}[ht]
\begin{center}
\setlength{\unitlength}{0.9mm}
\begin{picture}(135,15)(0,0)
\thicklines
\put(0,0){\framebox(135,10){}}
\put(45,0){\line(0,1){10}}
\put(75,0){\line(0,1){10}}
\put(0,13){\makebox(0,0)[l]{31}}
\put(45,13){\makebox(0,0)[l]{19}}
\put(75,13){\makebox(0,0)[l]{15}}
\put(135,13){\makebox(0,0)[r]{0}}
\put(22.5,12.5){\makebox(0,0){(12 bits)}}
\put(60,12.5){\makebox(0,0){(4 bits)}}
\put(105,12.5){\makebox(0,0){(16 bits)}}
\put(22.5,5){\makebox(0,0){language(KL1)}}
\put(60,5){\makebox(0,0){Micro PIMOS}}
\put(105,5){\makebox(0,0){avaible to the user}}
\end{picture}
\caption{Sho-en exception tag}
\label{fig-MPIMOS-tag}
\end{center}
\end{figure}

\subsection{Command interpreter\index{Command Interpreter}}
\label{sec-MPIMOS-shell}

When  Micro PIMOS starts, a command interpreter is created to provide 
user with an interface to PDSS.

When the command interpreter is invoked, it issues a prompt and waits
for the next command. Default prompt is \verb!| ?-!, or \verb|[debug]?-| 
when debugging mode is on.

The command interpreter starts by executing the file \verb|"~/.pdssrc"| (if it 
exists) as a command file. User can set up a convenient working 
environment via this file. About command file, refer to command take/1.

\subsubsection{Command input format}
\index{Command Interpreter!Command Input Format}

It is possible to write one or more commands in a command line or command file.
Depending on the delimiter, commands are executed as follows :
\begin{itemize}
\item comma (``\verb|,|'')\\ \index{\verb|,|}
Commands both before and after the delimiter are executed in parallel.
\item semicolon (``\verb|;|'')\\ \index{\verb|;|}
Waits for the termination of commands before the delimiter, and then execute 
remaining commands. (sequential execution.)
\item vertical line (``\verb!|!'')\\ \index{\verb!|!}
After executing the commands before the delimiter, displays the value of 
variables after this sign. The delimiter between variables is a comma,
and \verb|all| stands for all variables.
\end{itemize}
Lists of commands may be embedded in \verb|( )| to form nested commands.
\\
$\ll$ \verb|ex| $\gg$ 
\verb!  | ?- comp("bench");(stat(bench:primes(1,300,P))|P),save(bench).!
\begin{verbatim}
             %  After compiling "bench.kl1", executes the goal 'bench:primes' 
             %  and saves the code in parallel. During the execution of the
             %  goal, reports statistical information and indicates
             %  the value of variable 'P' after termination.
\end{verbatim}

Constant description macros in a command line(terms) are expanded.
Macros are described in \ref{sec-macro}.\vspace{1ex}

$\ll$ \verb|ex| $\gg$ \verb!  | ?- X=16#"FF",Y=16"Z",Z="FF"|all.!
\begin{verbatim}
          X=255
          Y=16#"FF"
          Z="FF"
\end{verbatim}

\subsubsection{Commands}\index{Commafnd Interpreter!Commands}

Here are the commands supported by the command interpreter, in its current
version.
Some of the commands expect files to have an extension.
If no extension is found, operation is done with the default extension,
following the specified filename.
Strings or atoms can be used to specify filenames.
\vspace{1ex}

\noindent\underline{\bf Built-in predicates}\index{Built-in Predicates}
\vspace{1ex}\par
The command interpreter can execute the built-in predicates
which can be described
in the body part as a commands.
Description using \verb|:=| and arithmetic macros are also possible.
\vspace{1ex}

\noindent\underline{\bf Basic commands}
\index{Command Interpreter!Commands!Basic Commands}\vspace{1ex}\par
\begin{itemize}

%\MpShellCommand{ModuleName:Goal}
\item[] \hskip -2em {\BF{ModuleName:Goal}} \\
Executes \verb|Goal| in the module \verb|ModuleName|.
Maximum number of
reductions is set according to the value of environment variable
\verb|reduction|.
If the number of performed reductions 
crosses the limit, the user will be asked whether to continue or to abort.

\MpShellCommand{help}{}
Displays the list of available help commands.

\MpShellCommand{help}{(Type)}
Displays the list of available commands specified by \verb|Type| as follows :\\
1: builtin, 2: basic, 3: code, 4: dir, 5: debug, 6: env, all.

\MpShellCommand{gc}{}
Invokes GC over the heap area.

\MpShellCommand{gc}{(all)}
Invokes GC for both heap and code areas.

\MpShellCommand{take}{(FileName)}
Executes the command file specified by \verb|FileName|.
There is no restriction as to the type of command which can be used in such a
file.

\verb|%| or \verb|/* */| are available to mark comments, as in KL1 program.

\MpShellCommand{cputime}{}
Display the CPU time since PDSS started.
Unit is millisecond.

\MpShellCommand{cputime}{(^Time)}
Unifies the CPU time since PDSS started with the variable \verb|Time|. 
The result is an integer and unit is millisecond.

\MpShellCommand{apply}{(CommandName, ArgsList)}
Executes \verb|CommandName| upon each element specified in
\verb|ArgList|. ModuleName:PredicateName is also possible for
\verb|CommandName|.

\MpShellCommand{stat}{}
Displays the current memory status.

\MpShellCommand{stat}{(Commands)}
Displays the execution time (CPU time) and reduction count of \verb|Commands|.

\MpShellCommand{window}{(IOStream)}
Opens a new window. About commands which deal with I/O streams,
refer to the section \ref{sec-MPIMOS-IO}.
Window name is set automatically. 

\MpShellCommand{add_op}{(Precedence, Type, Operator)}
Add an operator to the window of command interpreter.

\MpShellCommand{remove_op}{(Precedence, Type, Operator)}
Deletes an operator from the window of command interpreter.

\MpShellCommand{operator}{(Operator)}
Displays the definition of the operator \verb|Operator| in the window of 
command interpreter.

\MpShellCommand{operator}{(OperatorName, ^Definition)}
Unifies the definition of operator \verb|Operator|, (format is 
\{Precedence, Type\}) in the window of command interpreter with 
\verb|Definition|.

\MpShellCommand{replace_op_pool}{(^OldOpPool,NewOpPool)}
Unifies the old operator pool with \verb|OldOpPool|, and replaces the operator
pool with \verb|NewOpPool|. The format of an operator pool is
[\{OpName, [\{Precedence, Type\}, ...]\}, ...].

\MpShellCommand{change_op_pool}{(NewOpPool)}
Changes the operator pool to \verb|NewOpPool|.

\MpShellCommand{halt}{}
Terminates PDSS. All windows are closed automatically.

\end{itemize}
\vspace{1ex}

\noindent\underline{\bf Code commands}
\index{Command Interpreter!Commands!Code Commands}\vspace{1ex}\par
\begin{itemize}

\index{Compile}
\MpShellCommand{comp}{(FileName)}
Compiles the KL1 source file (with extension \verb|.kl1|)
\verb|FileName| and loads the result into code area. 
Trace mode is off for the newly loaded module.

\MpShellCommand{comp}{(FileName, OutFileName)}
Compiles the KL1 source file (with extension \verb|.kl1|)
\verb|FileName| and outputs the result into the file
(with extension \verb|.asm|) \verb|OutFileName|.

\MpShellCommand{compile}{(FileName)}
Compiles the KL1 source file (with extension \verb|.kl1|)
\verb|FileName| and outputs the result into file (with extension \verb|.asm|)
\verb|FileName|. Then, loads it into code area and saves into file (with 
extension \verb|.sav|).
\verb|FileName| can also hold a list of files.

\MpShellCommand{load}{(FileName)}
Loads the previously saved file \verb|FileName|
(with extension
\verb|.sav|) into code area.
If such a file does not exist, assembler file (extension is \verb|.asm|)
is loaded into code area. Trace mode of the newly loaded module is off.

\MpShellCommand{dload}{(FileName)}
As above, but trace mode of the newly loaded module is on.
Then debug mode of it is set to on.

\MpShellCommand{save}{(ModuleName)}
Saves the executable code module \verb|ModuleName| to the directory 
specified by environment variable \verb|savedir|. By default, the directory is 
\verb|~/.PDSSsave|. It can be changed with the 'ch_savedir' command.
\verb|ModuleName| is also used to determine file name.
Extension is \verb|.sav|.

\MpShellCommand{save}{(ModuleName, FileName)}
Saves the executable code \verb|ModuleName| to the file
\verb|FileName| (with extension \verb|.sav|).

\MpShellCommand{save_all}{}
Saves all loaded modules (except the ones which have already been saved by the 
\verb|save(ModuleName)| command) into the directory specified by environment
variable \verb|savedir|.

\MpShellCommand{ch_savedir}{(Directory)}
Changes the default directory for auto_load and auto_save, to the directory 
specified by \verb|Directory|. The existence of directory is checked.

\MpShellCommand{listing}{}
Displays information about loaded modules.

\MpShellCommand{listing}{(^Modules)}
Generates a list of all loaded module names and unifies it with \verb|Modules|.

\MpShellCommand{public}{(ModuleName)}
Displays a catalog of public predicates within
the module specified by \verb|ModuleName|.

\MpShellCommand{public}{(ModuleName, ^Public)}
Creates a list of information about 
predicates declared as public, and unifies it with
\verb|Public|. Each element of the list is a two-elements-vector of form
\{predicate-name-atom, arity\}.

\end{itemize}
\vspace{1ex}

\noindent\underline{\bf Directory commands}
\index{Command Interpreter!Commands!Directory Commands}\vspace{1ex}\par
\begin{itemize}

\MpShellCommand{cd}{(Directory)}
Changes current directory to the directory specified by \verb|Directory|.

\MpShellCommand{pwd}{}
Displays the pathname of current directory.

\MpShellCommand{pwd}{(^World)}
Unifies the pathname of current directory with \verb|World|.

\MpShellCommand{ls}{(WildCard)}
Displays the pathname of file \verb|WildCard|.

\MpShellCommand{ls}{(WildCard, ^Files)}
Creates a list with the pathnames corresponding to \verb|WildCard|
and unifies it with \verb|Files|.

\MpShellCommand{rm}{(WildCard)}
Deletes the file corresponding to \verb|WildCard| from the directory.

\end{itemize}
\vspace{1ex}

\noindent\underline{\bf Debug commands}
\index{Command Interpreter!Commands!Debug Commands}\vspace{1ex}\par
\begin{itemize}

\MpShellCommand{trace}{(ModuleName)}
Sets the trace mode on for the code of module \verb|ModuleName|.
The debug mode is set to on.

\MpShellCommand{notrace}{(ModuleName)}
Sets the trace mode off for the code of module \verb|ModuleName|.

\MpShellCommand{spy}{(ModuleName, PredicateName, Arity)}
Enables spying of the predicate \verb|PredicateName|/\verb|Arity|
in the module \verb|ModuleName|. Then trace mode and debug mode is set to on.

\MpShellCommand{nospy}{(ModuleName, PredicateName, Arity)}
Disables spying of the predicate \verb|PredicateName|/\verb|Arity|
 in the module \verb|ModuleName|.

\MpShellCommand{spying}{(ModuleName)}
Displays the list of the predicates
currently spied in the module \verb|ModuleName|.

\MpShellCommand{spying}{(ModuleName,^Spying)}
Creates a list of the predicates currently spied in 
the module \verb|ModuleName|, and then unifies it 
with \verb|Spying|. Each element of the list is a two-elements-vector formed
as \{predicate-name-atom, arity\}.

\MpShellCommand{debug}{}
Sets debug mode on.

\MpShellCommand{nodebug}{}
Sets debug mode off.

\MpShellCommand{backtrace}{}
Sets display mode on for backtrace information (deadlock information).

\MpShellCommand{nobacktrace}{}
Sets display mode off for backtrace information (deadlock information).

\MpShellCommand{varchk}{(FileName, Mode, Form)}
Checks variables in the KL1 source file (with extension \verb|.kl1|) specified 
by \verb|FileName| in the mode \verb|Mode|.
The result is displayed on the window 
in the format \verb|Form|. \verb|FileName| can also be a list of files.
The definition of \verb|Mode| and \verb|Form| follows :

\vspace{1ex}
\hspace*{15mm}\begin{tabular}{ll@{ $\cdots$ }l} 
Mode:: & \verb|o| or \verb|one|   
		& Displays variables which appear once in a clause.\\
       & \verb|m| or \verb|mrb|   & Displays variables whose MRB is set.\\
       & \verb|a| or \verb|all|   
		& Displays variables of both one and mrb modes.\\
Form:: & \verb|s| or \verb|short|     & Outputs clauses as a single line.\\
       & \verb|l| or \verb|long|      
		& Outputs clauses using line feeds and indentation.\\
\end{tabular}
\index{Variables Check}\vspace{1ex}

\MpShellCommand{varchk}{(FileName, Mode)}
Checks variables in mode \verb|Mode| and displays in \verb|long| format.

\MpShellCommand{varchk}{(FileName)}
Checks variables in mode \verb|one| and displays in \verb|long| format.

\MpShellCommand{xref}{(FileName, Mode)}
Performs a cross reference check upon the KL1 source file \verb|FileName|
 (with extension \verb|".kl1"|) and displays result on the window.
\verb|FileName| can also be a list of filenames. In this case, references 
across modules are also checked. \verb|Mode| can be taken amongst the following
values :

\vspace{1ex}
\hspace*{15mm}\begin{tabular}{lcl}
\verb|c| or \verb|check|       & $\cdots$ & Checks only predicate calls.\\
\verb|l| or \verb|list|        & $\cdots$ 
  & Outputs the reference list (table of definition/reference of predicates).\\
\verb|s| or \verb|system|      & $\cdots$ 
  & Outputs the predicates referring to PDSS modules.\\
\verb|b| or \verb|builtin|     & $\cdots$ 
  & Outputs predicates referring to body-built-in predicates.\\
\verb|g| or \verb|guard|       & $\cdots$
& Outputs predicates referring to guard-built-in predicates.\\
\verb|a| or \verb|all|         & $\cdots$ & Outputs all of above predicates.\\
\verb|List|      & $\cdots$    
  & Outputs a reference list for specified elements.\\
                 &      & Where \verb|List| can include :\\
                 &      & * Module name.\\
                 &      & * Body-built-in predicates.\\
                 &      & * User-defined predicates.\\
\verb|short|    & $\cdots$ & Checks with no display of predicate information.\\
\verb|short(Mode)|      & $\cdots$ 
  & Checks according to \verb|Mode| with no display of predicate information.\\
\verb|update|    & $\cdots$ 
  & When duplicate module names are found in specified files, \\
		&	& recognizes the latter definition as efficient,\\
		&	& and checks without a caution.\\
\verb|update(Mode)| & $\cdots$
  & When duplicate module names are found in specified files, \\
		&	& recognizes the latter definition as efficient,\\
		&	&and checks according to \verb|Mode| without a caution.
\end{tabular}
\index{Cross Reference Check}\vspace{1ex}

\MpShellCommand{xref}{(FileName)}
Checks the cross-references in \verb|check| mode.

\MpShellCommand{xref}{(FileName, Mode, OutFile)}
Checks the cross-references and outputs the list to \verb|OutFile|.
Any mode is available except \verb|check|.

\MpShellCommand{profile}{(ModuleName, Mode)}
Displays how many times the predicates which are defined in 
the module \verb|ModuleName| were  called and suspended.
\verb|ModuleName| can also be a list of modules.
\verb|Mode| can be chosen as follows :

\vspace{1ex}
\hspace*{15mm}\begin{tabular}{l@{ $\cdots$ }l}
\verb|c| or \verb|call|   & Sorts according to call count and displays.\\
\verb|s| or \verb|susp|   & Sorts according to suspension count and displays.\\
\verb|n| or \verb|no|
& Displays following the order of appearance within the code area.\\
\end{tabular}
\vspace{1ex}

\MpShellCommand{profile}{(ModuleName)}
Executes \verb|profile| command in \verb|call| mode.

\MpShellCommand{reset_profile}{(ModuleName)}
Resets counts of calls and suspensions for predicates defined 
in \verb|ModuleName|. \verb|ModuleName| can also be a list of modules.
\end{itemize}
\vspace{1ex}

\noindent\underline{\bf Environment commands}
\index{Command Interpreter!Commands!Environment Commands}\vspace{1ex}\par
These commands can be used to change values of environment variables
for the command interpreter. The following environment variables are used :
\index{Environment Variables}\vspace{1ex}
\begin{center}
\begin{tabular}{|l|l|}\hline
\multicolumn{1}{|c|}{name (atom)} & \multicolumn{1}{c|}{meaning}\\ \hline\hline
\verb|world| & {\small Pathname string of current directory.}\\
\hline
\verb|trace| & {\small Mode of tracer (\verb|on| or \verb|off|). 
					Initial value is \verb|off|.}\\
\hline
\verb|backtrace| & {\small Display mode of backtrace (\verb|on| or \verb|off|).
					 Initial value in \verb|on|.}\\
\hline
\verb|modules| & {\small List of module names in which commands are 
								searched.}\\
\hline
\verb|reduction| & {\small Upper limit of the number of reductions assigned
			 when the task was created. The basic allocation}\\
		& {\small unit is 10000 reductions.
			 (0 $<$ number $<$ 100000, Initial value is 10000)}\\
\hline
\verb|ucounter| & {\small Counter used to create the names of 
						work files or work windows.}\\
\hline
\verb|savedir| & {\small String with the pathname of directory in which
			save/1 and save_all will produce their effects.}\\
		& {\small Initial value is \verb|~/.PDSSsave|.}\\
\hline
\verb|loaddir| & {\small list of pathnames of directories to examine 
						when auto-loading code.}\\
& {\small Initial value is \verb|[~/.PDSSsave, pathname of library directory,
								 ...]|}\\
& {\small Note: There are more than two library directories, 
			which may differ from one machine to another.}\\
\hline
\verb|auto_load| & {\small Flag for auto_loading (\verb|yes| or \verb|no|).
					 Initial value is \verb|yes|.}\\
\hline
\verb|plength| & {\small Maximum length of structure which can displayed
				 in the window of the command interpreter.}\\
		& {\small Initial value is 10.}\\
\hline
\verb|pdepth| & {\small Maximum depth of structure which can be displayed
		 		on the window of the command interpreter.}\\
		& {\small Initial value is 5.}\\
\hline
\verb|pvar| & {\small Displays modes of variables in the window of 
		command interpreter. The value is \verb|nu| or \verb|na|.}\\
	    & {\small (\verb|nu| works as _0,_1,_2, ... , and \verb|na| 
			works as A,B,C, ...) Initial value is \verb|nu|.}\\
\hline
\end{tabular}
\end{center}
\vspace{1ex}
\begin{itemize}

\MpShellCommand{setenv}{(Name, Value)}
Sets the environment variable \verb|Name| after \verb|Value|.
Environment variable is set after that \verb|Name| becomes an atom and 
\verb|Value| becomes a ground term.

\MpShellCommand{getenv}{(Name, ^Value)}
Unifies the value of environment variable \verb|Name| with \verb|Value|.

\MpShellCommand{printenv}{(Name)}
Displays the value of environment variable \verb|Name|.

\MpShellCommand{printenv}{}
Displays the values of all environment variables of the command interpreter.

\MpShellCommand{resetenv}{}
Initializes all environment variables of the command interpreter.

\end{itemize}

\subsection{I/O functions\index{I/O Functions}}
\label{sec-MPIMOS-IO} \index{Window} \index{File}

Micro PIMOS offers two types of I/O services : window and file I/O services.
To use them, Micro PIMOS predicates are provided, which give access to
command streams.\index{I/O Functions!Command Stream}
How commands can be inserted in these streams is now described.
\verb|[]| closes a command stream and, by the way, the associated
I/O device. Commands are inserted in command stream by a merger.

\subsubsection{Command stream attachment}
\index{I/O Functions!Command Stream Attachment}
\noindent\underline{\bf Windows}\vspace{1ex}\par
\index{I/O Functions!Window}\index{Window}
\begin{itemize}

\MpIOCreate{window:create(Stream, WindowName, ^Status)}
Creates a window with name \verb|WindowName| (8 bits string). Command stream
is unified with
\verb|Stream|. \verb|Status| is unified with the following terms :
\vspace{1ex}

\hspace*{15mm}\begin{tabular}{l@{ $\cdots$ }l}
\verb|success| & Window successfully created.\\
\verb|error(cannot_create_window)| & Failure : window cannot be opened.\\
\verb|error(bad_window_name_type)| 
		& Failure : \verb|WindowName| is not an 8 bits string.\\
\end{tabular}

\Caution When the window is created, it is not in visible state. Use command
\verb|show| to make it appear.

\MpIOCreate{window:create(Stream, WindowName)}
Creates a window with name \verb|WindowName| (8 bits string). Command stream
is unified with \verb|Stream|. If the window cannot be created, the whole task
is aborted.\index{window}

\Caution When the window is created, it is not in visible state. Use command
\verb|show| to make it appear.
\end{itemize}
\vspace{1ex}

\noindent\underline{\bf Files}\vspace{1ex}\par
\index{I/O Functions!File}\index{File}
\begin{itemize}

\MpIOCreate{file:create(Stream, FileName, Mode, ^Status)}
Opens file with name \verb|FileName| (8 bits string) with mode \verb|Mode|.
\verb|Mode| is an atom chosen among : \verb|r| for read, \verb|w| for write and
\verb|a| for append. The command stream of this file is unified
with \verb|Stream|.\index{file}
\verb|Status| is unified with one of the following terms :
\vspace{1ex}

\hspace*{15mm}\begin{tabular}{l@{ $\cdots$ }l}
\verb|success| & Open successful.\\
\verb|error(cannot_open_file)| & Cannot open the file.\\
\verb|error(bad_file_name_type)| & \verb|FileName| is not an 8 bits string.\\
\verb|error(bad_open_mode_type)| & \verb|Mode| is not atom.\\
\verb|error(bad_open_mode)| & \verb|Mode| is an atom other than \verb|r|,
							\verb|w| or \verb|a|.
\end{tabular}
\vspace{1ex}

\MpIOCreate{file:create(Stream, FileName, Mode)}
Opens a file as the previous command. \verb|Stream|, \verb|FileName| and
\verb|Mode| have same meanings, but if open does not succeed,
the whole task is aborted.

\end{itemize}
\subsubsection{Command list}\index{I/O Functions!Commands}

Commands allowed in stream are now listed. These commands are common to
window and file, unless otherwise specified.
\vspace{1ex}

\noindent\underline{\bf Input commands}\vspace{1ex}\par
\index{I/O Functions!Input Commands}
\begin{itemize}

\MpIOCommand{getc}{(^Char)}
Reads an ascii character from I/O device. Value is between 0 and 255.
\verb|Char| is unified with the result of input.
Upon end of file, \verb|Char| is unified with the atom \verb|end_of_file|.

\MpIOCommand{getl}{(^String)}
Reads one line from I/O device. This line is converted into an 8 bits string,
unified with \verb|String|. 
Upon end of file, \verb|String| is unified with the atom \verb|end_of_file|.

\MpIOCommand{getb}{(^Buffer, Size)}
The number of character specified by \verb|Size| is read from I/O
and converted into an 8 bits string, which is unified with \verb|Buffer|.
If a carriage return or an end of file is encountered,
only characters read before are considered as input.
Upon end of file, \verb|Buffer| is unified  with the atom \verb|end_of_file|.

\MpIOCommand{gett}{(^Term) }
A string containing one term is read. (A term ends with \verb|.| + CR or 
\verb|.| + space) These characters are analyzed and transformed into a term,
which is unified with \verb|Term|. If an error occurs during analysis,
if input device is a window, error is output on this window
and term input is resumed. If input device is a file,
error is displayed on the command interpreter window,
then next term is read from the file. At end of file, term is unified with
\verb|end_of_file|.

\MpIOCommand{gett}{(^Term, ^Status)}
Almost same as \verb|gett/1|,
except that \verb|Status| is unified with one of the following terms.
\vspace{1ex}

\hspace*{15mm}\begin{tabular}{l@{ $\cdots$ }l}
\verb|success|                & Input a term successful.\\
\verb|syntax_error(Position)| & Syntax error in \verb|Position|.\\
\verb|ambiguous(Position)|    & Ambiguous expression in \verb|Position|.\\
\verb|end_of_file|            & End of file.\\
\verb|eof_in_quote|           & End of file between quotation marks.\\
\end{tabular}

When \verb|Status| is \verb|syntax_error|, \verb|ambiguous|,
\verb|eof_in_quote|, \verb|Term| is unified with a token list
(See \ref{sec-IO-device} gettkn/4).

\MpIOCommand{getft}{(^Term, ^NumberOfVariables)}
This command is very similar to \verb|gett/1|, but variables in the term
are analyzed then output as \verb|$VAR(N,VN)|.
N is the variable number (0 $\leq$ N $<$ \verb|NumberOfVariables|)
and VN is the variable name (8 bits string).
\verb|NumberOfVariables| is unified
with the number of variables appearing in the term. Upon end of file,
\verb|Term| is unified with \verb|end_of_file| and \verb|NumberOfVariables|
is unified with 0.

\MpIOCommand{getft}{(^Term, ^NumberOfVariables, ^Status)}
Almost same as \verb|getft/2|, and see \verb|gett/2| about \verb|Status|.

\MpIOCommand{skip}{(Char)}
Skips until the charactor code \verb|Char| or end of file is found.\\

\end{itemize}
\Caution If end of file has been encountered during the execution of previous
commands, successive input commands will return end of file.
\vspace{1ex}

\noindent\underline{\bf Output commands}\vspace{1ex}\par
\index{I/O Functions!Output Commands}
\begin{itemize}

\MpIOCommand{putc}{(Char)}
Outputs on the I/O device the character with ASCII code \verb|Char|, between
0 and 255.

\MpIOCommand{putl}{(String)}
Outputs the 8 bits string \verb|String| on the I/O device and adds a new line
character.

\MpIOCommand{putb}{(Buffer)}
Outputs 8 bits string \verb|Buffer|. No carriage return is added.

\MpIOCommand{putb}{(Buffer, Count)}
Outputs on the I/O device the charactors by certain length specified by
\verb|Count| extracted from 8 bits string. If the length of \verb|Bffer|
is less than the specified length, this is the same as putb/1.

\MpIOCommand{putt}{(Term, Length, Depth)}
Outputs term \verb|Term|. If structure depth exceeds \verb|Depth| ($>$ 0) or
length exceeds \verb|Length| ($>$ 0), remainder is output as '\verb|...|'.
This is similar to Prolog's write.

\Caution Atoms are not quoted, so that the result of this command may be
unsuited to further read using gett or getft.

\MpIOCommand{putt}{(Term)}
Similar to the previous command, but default value is used for depth and
length.

\MpIOCommand{puttq}{(Term, Length, Depth)}
This is similar to putt/3 command, but atoms are quoted when necessary.

\MpIOCommand{puttq}{(Term)}
This is similar to putt/1 command, but atoms are quoted when necessary.

\MpIOCommand{nl}{}
Outputs a new line character.

\MpIOCommand{tab}{(N)}
Outputs \verb|N| (0 $\leq$ N $<$ 1000) space characters.

\end{itemize}
\Caution On Micro PIMOS, I/O is blocked, for efficiency reasons.
Buffers are flushed only in the following cases :
\begin{itemize}
\item Buffer is full.
\item \verb|flush| command has been received.
\item I/O device is closed.
\item (in the case of windows) some input or show/hide command is
received.
\end{itemize}
\vspace{1ex}

\noindent\underline{\bf Control of output format}\vspace{1ex}\par
\index{I/O Functions!Control of Output Format}
Output limitations for structure in putt/1 and puttq/1 commands
can be changed as follows :
\begin{itemize}

\MpIOCommand{print_length}{(Length)}
This command changes the default length limit to \verb|Length| (\verb|Length|
$>$ 0). Initial value is 10 for windows, 100 for files.

\MpIOCommand{print_depth}{(Depth)}
This command changes the default depth limit to \verb|Depth| (\verb|Depth|
$>$ 0). Initial value is 10 for windows, 100 for files.

\MpIOCommand{print_var_mode}{(VariableMode)}
This command is used to change the output format of terms describing variables.
\verb|VariableMode| is the new mode which must be \verb|nu| or \verb|na|.
Initial value is \verb|na|.

\vspace{1ex}

\hspace*{15mm}\begin{tabular}{lcl@{ $\rightarrow$ }l}
\verb|na| -- Name Mode   & :: & \$VAR(N,VN) 
				& VN (Variable name string).\\
                  &    & \$VAR(N)    & A,B,C $\cdots$ .\\
\verb|nu| -- Number Mode & :: & \$VAR(N,VN) & _N (Variable number).\\
                  &    & \$VAR(N)    & _N (Variable number).\\
\end{tabular}
\vspace{1ex}
\end{itemize}
\vspace{1ex}

\noindent\underline{\bf Output buffer commands}\vspace{1ex}\par
\index{I/O Functions!Output Buffer Commands}
The following command control output buffer parameters.
\begin{itemize}

\MpIOCommand{flush}{(^Status)}
This command flushes characters left in buffer. After completion, \verb|Status|
is unified with atom \verb|done|.

\MpIOCommand{buffer_length}{(BufferLength)}
This command changes output buffer length to \verb|BufferLength| ($>$ 0).
Initial value is 512 bytes for a window and 2048 bytes for files.

\end{itemize}
\vspace{1ex}

\noindent\underline{\bf Operators}\vspace{1ex}\par
\index{I/O Functions!Operators}
The following commands are related to operators for parsing.
\begin{itemize}

\MpIOCommand{add_op}{(Precedence, Type, OperatorName)}
This command adds an operator with precedence \verb|Precedence| (1 $\leq$
\verb|Precedence| $\leq$ 1200), type \verb|Type| (an atom chosen among
\verb|fx|,\verb|fy|, \verb|xf|, \verb|yf|, \verb|xfy|, \verb|xfx|, \verb|yfx|)
and name \verb|OperatorName| (atom).\\
\Caution When the specified type is competitive with already defined type
(fx $\leftrightarrow$ fy, xf $\leftrightarrow$ yf, xfy $\leftrightarrow$ xfx 
$\leftrightarrow$ yfx), the latter is deleted.

\MpIOCommand{remove_op}{(Precedence, Type, OperatorName)}
This command removes an operator. Parameters have the same meaning as in
the previous command.

\MpIOCommand{operator}{(OperatorName, ^Definition)}
This command return a list \verb|Definition| of operators matching name
\verb|OperatorName| (atom). Each element of the list is in the form
\{precedence, type\}.

\MpIOCommand{replace_op_pool}{(^OldOpPool, NewOpPool)}
Unifies the old operator pool with \verb|OldOpPool|, and replaces the operator
pool with \verb|NewOpPool|. The format of an operator pool is
[\{OpName, [\{Precedence, Type\}, ...]\}, ...].

\MpIOCommand{change_op_pool}{(NewOpPool)}
Changes the operator pool to \verb|NewOpPool|.

\end{itemize}
\vspace{1ex}

\noindent\underline{\bf Grouped processing of commands}\vspace{1ex}\par
\index{I/O Functions!Grouped Processing}
\begin{itemize}

\MpIOCommand{do}{(CommandList)}
This command groups the list of command \verb|CommandList| within
a single command. Even though merger is used to insert commands in the stream,
sequence of commands in \verb|CommandList| is preserved.

\end{itemize}
\vspace{1ex}

\noindent\underline{\bf Control command}\vspace{1ex}\par
\index{I/O Functions!Control Commands}
\begin{itemize}

\MpIOCommand{close}{(^Status)}
Closes I/O operation. It is not possible to send other commands after that
one. (Only \verb|[]| can be sent to close the stream.)
\verb|Status| is unified with atom \verb|success|.

\end{itemize}
\vspace{1ex}

\noindent\underline{\bf Window commands}\vspace{1ex}\par
\index{I/O Functions!Window Commands}
The following commands are effective only for windows.
\begin{itemize}

\MpIOCommand{show}{}
An hidden window will show up when this command is executed.

\MpIOCommand{hide}{}
A visible window will be hidden when this command is executed.

\MpIOCommand{clear}{}
Clears the window space.

\MpIOCommand{beep}{}
Rings the terminal bell.

\MpIOCommand{prompt}{(^Old, New)}
Changes prompt string displayed in executing \verb|gett| or \verb|getft|
command.  \verb|Old| is unified with current prompt string(8 bits string)
and the new prompt becomes \verb|New| (also an 8 bits string).
The initial prompt is \verb|"?-"|.

\end{itemize}

\subsection{Directory management\index{Directory Management}}
\label{sec-MPIMOS-directory}

The directory services of Micro PIMOS are available through the directory
command stream.\index{Directory Management!Directory Command Stream}
This stream is available via a Micro PIMOS predicate,
in a similar fashion to I/O services.

Operations on the directory are done by inserting commands into this stream.
The stream can be closed with \verb|[]|.

\subsubsection{Acquisition of command stream}
\index{Directory Management!Acquisition of Command Stream}
\begin{itemize}

\MpDirCreate{directory:create(Stream, DirectoryName, ^Status)}
Accesses the directory named \verb|DirectoryName| (8 bits string) and
unifies the command stream connected to the directory with \verb|Stream|.
\verb|Status| can be unified with the following terms :\index{directory}

\vspace{1ex}

\hspace*{15mm}\begin{tabular}{l@{ $\cdots$ }l}
\verb|success| & Access succeeded.\\
\verb|error(cannot_access)| & The directory cannot be accessed.\\
\verb|error(bad_directory_name_type)| 
			& \verb|DirectoryName| is not an 8 bits string.\\
\end{tabular}
\end{itemize}

\subsubsection{Commands}\index{Directory Management!Commands}

The following commands can be inserted into the command stream.

\begin{itemize}

\MpDirCommand{pathname}{(^PathName)}
Unifies the full pathname of the directory (8 bits string)
with \verb|PathName|.

\MpDirCommand{listing}{(WildCard, ^FileNames, ^Status)}
Creates the list of pathnames of files corresponding to \verb|WildCard|
and unifies it with \verb|FileNames|. \verb|Status| can be unified with the
following terms :

\vspace{1ex}
\hspace*{15mm}\begin{tabular}{l@{ $\cdots$ }l}
\verb|success| & List successfully created.\\
\verb|error(cannot_listing)| & List cannot be created.\\
\end{tabular}
\vspace{1ex}

\MpDirCommand{delete}{(WildCard, ^Status)}
Deletes files corresponding to \verb|WildCard| (8 bits string) from
the directory. \verb|Status| can be unified with the following terms :

\vspace{1ex}
\hspace*{15mm}\begin{tabular}{l@{ $\cdots$ }l}
\verb|success| & Deletion successful.\\
\verb|error(cannot_delete)| & Cannot delete the file.\\
\end{tabular}
\vspace{1ex}

\MpDirCommand{open}{(Stream, FileName, Mode, ^Status)}
Opens the file \verb|FileName| (8 bits string) with mode \verb|Mode|
(atom \verb|r| for read, \verb|w| for write or
\verb|a| for append) and unifies the command stream connected to the file
with \verb|Stream|.
\verb|Status| can be unified with the following terms :

\vspace{1ex}
\hspace*{15mm}\begin{tabular}{l@{ $\cdots$ }l}
\verb|success| & Open successful.\\
\verb|error(cannot_open_file)| & Cannot open the file.\\
\verb|error(bad_file_name_type)| & \verb|FileName| is not an 8 bits string.\\
\verb|error(bad_open_mode_type)| & \verb|Mode| is not atom.\\
\verb|error(bad_open_mode)| 
	& \verb|Mode| is an atom other than \verb|r|,\verb|w| or \verb|a|.
\end{tabular}
\end{itemize}

\subsection{Device Stream for I/O}\index{Device Stream}
\label{sec-MPIMOS-device}\index{Input/Output Device}

To use Input/Output device functions directly from Micro PIMOS, 
one can use the libraries now described.  The purpose of the functions therein
is to describe other OS than Micro PIMOS (e.g. PIMOS) in KL1.
Average user does not need device streams shown below.

These device streams are supervised by Micro PIMOS. So if a wrong command 
is inserted, it only results in the failure of user task; the language
processor is unaffected.

\subsubsection{Securing device stream}
\index{Device Stream!Securing Device Stream}

User can extract a device stream from Micro PIMOS by using the following 
predicates. \verb|mpimos_io_device| can also be used as a module name.

\begin{itemize}

\MpDevCreate{mpimos_window_device:windows(Stream)}
\index{mpimos_window_device}
Unifies the stream which has a function of window device with \verb|Stream|.

\MpDevCreate{mpimos_file_device:files(Stream)}
Unifies the stream which has a function of file device with \verb|Stream|.
\index{mpimos_file_device}

\MpDevCreate{mpimos_timer_device:timer(Stream)}
Unifies the stream which has a function of timer device with \verb|Stream|.
\index{mpimos_timer_device}
\end{itemize}

\subsubsection{Command}\index{Device Stream!Command}

The commands which can be sent to each device stream, stream of opened window, 
file and directory are just the same as mentionned in \ref{sec-IO-device}.
As to the I/O commands for file/window streams, only the commands shown 
below are allowed.

\begin{itemize}
\item Window
\begin{itemize}

\item[Input]  Only getl(^Line, ^Status, Cdr) is available.\\
getc/3, getb/4, gettkn/4 are not available.

\item[Output] Only putb(Buffer, ^Status, Cdr) is available.\\
putc/3, putl/3, putt/5 are not available.
\end{itemize}
\item File
\begin{itemize}

\item[Input]  Only getb(Size, ^Bufferm ^Status, Cdr) is available.\\
getc/3, getl/3, gettkn/4 are not available.

\item[Output] Only putb(Buffer, ^Status, Cdr) is available.\\
putc/3, putl/3, putt/5 are not available.
\end{itemize}
\end{itemize}

\subsection{Code management\index{Code Management}}
\label{sec-MPIMOS-code}

The principal functions for code management on Micro PIMOS now follow.

\begin{itemize}
\item Functions to manage the name and information (like the catalog of
public predicates and spied predicates) of loaded modules and display this
information upon request.
\item Auto_load function of modules which are saved by \verb|save(ModuleName)|
or \verb|save_all| commands from the command interpreter.
\end{itemize}

The directory from which \verb|auto_load| is performed
is decided after the environment variable \verb|loaddir|
of command interpreter. User had better make a directory 
\verb|~/.PDSSsave| to use the auto_load function,\index{auto_load function}
because the default value of first element of both
\verb|loaddir| and \verb|savedir| is \verb|~/.PDSSsave|. The value of
environment variables can be changed. User can disable the auto load
function by setting the environment variable \verb|auto_load| to \verb|no|.

\subsection{Displaying exception information}\index{Exception Information}
\label{sec-MPIMOS-exception}

The KL1 exceptions handled by PDSS are shown in section \ref{sec-exception}.
On Micro PIMOS, information about an exception which has occurred within
the user task is displayed
on the window of command interpreter. The task in which exception has
occurred is immediately stopped and its resources (windows and files)
are released.\index{Exception}

Other exceptions, reported by Micro PIMOS, are handled by Micro PIMOS.
Those are consequent to an illegal command to the window, trying to 
open a file that does not exist, etc. In those cases,
as in the case of language definition exceptions,
information is displayed on the window of 
command interpreter and the task is immediately stopped.
All resources of the task are released.

\newpage
\section{PDSS Optional Parameters}\index{PDSS Invocation}

PDSS is usually invoked under GNU-Emacs. This may be seen as the best way
to use PDSS, from an
execution environment point of view, as all PDSS functions are available.
It is possible to execute PDSS on a stand alone basis, but in this case,
some functions disappear.

\subsection{Usage under GNU-Emacs}\index{PDSS Invocation!Under GNU-Emacs}

To call PDSS under GNU-Emacs, send the following command. Libraries are
automatically loaded and PDSS starts.
\vspace{2ex}\\
\hspace*{10em}\underline{{\bf meta-X pdss} {\it return}}
\vspace{2ex}

To specify options, type ctrl-U before meta-X. Option contents are described
later.
\vspace{2ex}\\
\hspace*{10em}\underline{{\bf ctrl-U meta-X pdss} {\it return}}\\
\hspace*{10em} PDSS Option?: \underline{{\bf [ parameter ]} {\it return}}
\vspace{2ex}

When PDSS starts, a window named ``console window'' is created.
This window is used to trace execution and for input/display at console.
Then, several modules are loaded, including runtime support and Micro PIMOS.
Then, Micro PIMOS starts.
After that, command interpreter window is created and waits for user commands.

When operation is done within GNU-Emacs, PDSS input is asynchronous.
Therefore the whole system does not hold when input occurs.
There is an exception to this for console inputs while tracing.
In this case, system halts until input completion.
It is possible to control PDSS by striking control keys in the window.
These keys are defined in a GNU-Emacs library. Besides following commands,
a complete list of supported keys can be found in \ref{sec-emacs}.
\vspace{1ex}

\hspace*{15mm}\begin{tabular}{lcl}
ctrl-C ctrl-C & :: & Turns on trace flag.\\
ctrl-C ctrl-Z & :: & Sends interrupt code 1.\\
              &    & In Micro PIMOS, this aborts task.\\
ctrl-C ctrl-T & :: & Sends interrupt code 2.\\
              &    & In Micro PIMOS, this prints number of reductions
							performed so far.\\
ctrl-C !      & :: & Starts GC.\\
ctrl-C @      & :: & Aborts PDSS.\\
ctrl-C ctrl-B & :: & Generates a window buffer menu for PDSS.\\
ctrl-C ESC    & :: & Reexecutes PDSS system.\\
ctrl-C k      & :: & Removes contents of current window.\\
ctrl-C ctrl-K & :: & Deletes contents of the window created by PDSS.\\
ctrl-C ctrl-Y & :: & Reprints the last input string.\\
ctrl-C ctrl-F & :: & Prints manual of built-in predicates.\\
ctrl-C f   & :: & Prints manual of command interpreter.\\
\end{tabular}
\vspace{1ex}

\Caution When a PDSS window is removed by ctrl-X k, subsequent execution
results are not guaranteed to be meaningful.

\subsection{PDSS on stand-alone}\index{PDSS Invocation!Stand-alone}

To use PDSS without GNU-Emacs, type the following command :
\vspace{2ex}\\
\hspace*{10em}\underline{{\bf pdss [ parameter ]} {\it return}}
\vspace{2ex}

Outside of GNU-Emacs, all messages to windows are merged. If any window waits
for some input, the whole system stops. Window control keys are not available
but, on the other hand, keyboard interrupt is supported. If ctrl-c is typed,
one can enter control commands after the prompt.

\subsection{Optional parameters}
\index{PDSS Invocation!Optional Parameters}

Optional parameters can be specified at start, to modify the execution
environment. Possible parameters follow :
\vspace{1ex}

\hspace*{15mm}\begin{tabular}{l@{ :: }p{120mm}}
\verb|-hNNN| &
Size of heap area is \verb|NNN| words.
				Default is 200 kwords(1 word = 8 bytes).\\
\verb|-cNNN| &
Size of code area is \verb|NNN| bytes. Default is 300 kbytes.\\
{\bf file name} &
Uses this file instead of the standard startup file.\\
\verb|+t/-t| &
Uses start up file or not. Default is to use it.\\
\verb|-v| &	This option changes the way variables appear during trace.
		By default,variables are printed using their name.
		If \verb|-v| option is used, they are identified
		by their relative position to heap bottom.
		This may change after each GC, so be careful.\\
\verb|-dNNN| & Scheduling politics for goals are changed to depth-first.
		\verb|NNN| gives depth limit for TRO.\\
\verb|-bNNN| & Scheduling politics for goals are changed to breadth-first.
		\verb|NNN| gives depth limit for TRO.\\
\verb|-rRR,SS,NNN| & Scheduling politics for goals are basically depth-first,
		and some of goals are pushed to the tail of the scheduleing
		queue according to the calculated random number.
		This makes possible to simulate the undecided
		reduction ordering. \verb|RR| specifies the ratio of goals
		pushed to the tail of the queue by percentage. \verb|SS| is the
		seed of the calculation of random number.
		\verb|NNN| gives depth limit for TRO.\\
\verb|-a| &
Inhibits timer interrupt. This is used when debugging PDSS itself, under dbx.\\
\end{tabular}
\vspace{1ex}

There are two ways to specify these options  :
\begin{itemize}
\item Options can be given when starting PDSS. They are treated as arguments
of the PDSS command.
\begin{verbatim}
      example-1)
             PDSS Option ?: -h300000 -c50000 -v    (Execution under GNU-Emacs)
      example-2)
             [UNIX]% pdss -h300000 -c50000 -v      (Execution on stand alone)
\end{verbatim}
\item Options can also be specified through an environment variable.
\begin{verbatim}
      example)
             [UNIX]% setenv PDSSOPT "-h300000 -c50000 -v"
             [UNIX]% pdss
\end{verbatim}
\end{itemize}

\newpage
\section{Tracer}\index{Tracer}
\label{sec-tracer}

The tracer functions supported by PDSS are now described.

\subsection{Principle of operation}

Basically, in PDSS, trace operations can occur whenever a goal is in one of the
following states. These events are called trace points.\index{Trace Points}
\begin{itemize}
\item Goal call.
\item Suspension due to an uninstanciated argument.
\item End of suspension.
\item Goal failure.
\item Swap out (Caused by interruption or scheduling of a higher priority
goal).
\end{itemize}

There are two ways to operate trace in KL1 : upon predicate execution or
upon goal call.

To trace upon predicate execution is to trace when the code, which ones
want to trace, is executed. In this case, it is possible to specify trace mode
for each module. In the following description, this mode is called
``code trace''.\index{Code Trace}
It is also to trace each predicate separately.
This is called ``code spying''.\index{Spying!Code Spying}\index{Spying}

To trace upon goals is to trace, or not to trace, descendant goals of each
generated goals. In the following description, we call this ``goal trace''.
It also possible to limit trace to the descendant goals of specific goals.
This is called ``goal spying''.
\index{Goal Trace}\index{Spying!Goal Spying}\index{Spying}

Let's see some example. In the following program, we assume that \verb|foo|
is in trace state and \verb|bar| is not. Then, \verb|q| and \verb|r|
which are called from \verb|foo| are also traced. Conversely, \verb|q|
and \verb|r| which are called by \verb|bar| are not traced.
\begin{verbatim}
                foo :- p.   bar :- p.   p :- q, r.
\end{verbatim}

In PDSS, it is possible to specify before or during execution whether or not
code trace is done. On the other hand, goal trace status must be on at first;
then, some of the goals can be untraced by relevant commands during tracing.
Only goals which have both code trace status on and goal trace status on
are actually traced.

In case of spying it is possible to specify before or during execution whether
or not code spying is done. Goal spying can be done only on goals which is
speculated by tracer. The four possible cases of spying are the following :
\index{Spying}\index{Spying!Code Spying}\index{Spying!Goal Spying}
\begin{itemize}
\item Code is spied.
\item Goal is spied.
\item Code or goal are spied.
\item Code and goal are spied.
\end{itemize}\index{Trace Points}

\subsection{How to read the display}

Trace display contains 4 different information zones :
\vspace{2ex}\\
\hspace*{15mm}
\shortstack[l]{\underline{\tt [0012]}\\ 1}
\shortstack[l]{\underline{\tt CALL}\\ 2}
\shortstack[l]{\underline{\tt *\$}\\ 3}
\shortstack[l]{\underline{\tt module:goal(a1,a2)}\\ 4}
\vspace{2ex}
\begin{enumerate}

\item Identity of the Sho-en to which this goal belongs.

\item Type of trace event :
\vspace{1ex}\\
\hspace*{15mm}\begin{tabular}{l@{ :: }p{120mm}}
\verb|CALL| & Dequeue from goal queue.\\
\verb|Call| & Goal called during TRO.\\
\verb|SUSP| & Suspension due to an uninstanciated argument.\\
\verb|Susp| & Suspension due to an uninstanciated argument
		which specifies the ratio calculating the priority.\\
\verb|RESU| & End of suspension.\\
\verb|FAIL| & Goal failure.\\
\verb|SWAP| & Swap out.\\
\end{tabular}
\vspace{1ex}

\item Spy flags :\index{Spy Flags}
\vspace{1ex}\\
\hspace*{15mm}\begin{tabular}{l@{ :: }p{120mm}}
\verb|*| & Code of executing goal is spied.\\
\verb|$| & Goal is spied.\\
\end{tabular}
\vspace{1ex}

\item Goal\\
Terms in argument list which are potentially referred several times
(MRB is on) are appended with an \verb|x| mark.\\
Variables are shown as follows, according to their type :
\begin{itemize}
\item Ordinary unbound variable :\\
First letter is upper case, or underscore, and is followed by a number...
\verb|X1|, \verb|_23611|.
\item Some goal waits for instantiation of this variable :\\
Format is the same as an ordinary unbound variable, followed by a tilde...
\verb|X1~|, \verb|_23611~|.
\item Merger input variable :\\
As above, replacing tilde with carret...
\verb|X1^|, \verb|_23611^|.
\end{itemize}
\end{enumerate}

In addition to this description, priority is displayed whenever it changes.

\subsection{Commands}\index{Tracer!Commands}

The description of tracer commands has the following meta syntax :
\vspace{2ex}\\
\hspace*{5em}Command name :: input format  \{argument\}  \{ [options] \}
\vspace{2ex}
\begin{itemize}

\TrCommand{Help}{?}
Command help.

\TrCommand{No Trace}{X}
No trace from now on.

\TrCommand{No Goal Trace}{x}
Turns off trace for the descendants of current goal,
i.e. goals called from this goal.

\TrCommand{Set Goal Spy}{g}
Spies current goal from now on.

\TrCommand{Reset Goal Spy}{G}
Stops spying current goal, from now on.

\TrCommand{Set Module Debug Mode}{d MODULE \{ MODULE ... \}}
Sets debug flag on for specified modules. By this mean, code trace is done
when predicates from this module are executed.

\TrCommand{Reset Module Debug Mode}{D MODULE \{ MODULE ... \}}
Effects are opposite to the previous command.

\TrCommand{Set Procedure Spy}{p MODULE:PROCEDURE \{ MODULE:PROCEDURE ... \}}
Sets trace on for a given predicate in a given module.

\TrCommand{Reset Procedure Spy}{P MODULE:PROCEDURE \{ MODULE:PROCEDURE ... \}}
Opposite of previous command.

\TrCommand{Step}{s [COUNT]}
Stops again at next trace point. If \verb|COUNT| is given, stop occurs only
after that \verb|COUNT| trace points have passed. Here and in the following,
\verb|COUNT| can be considered as a repetition factor.

\TrCommand{Step to Next Spied Procedure}{sp [COUNT]}
Continues until the next spied predicate is called, then stops.

\TrCommand{Step to Next Spied Goal}{sg [COUNT]}
As above, but we look for a spied goal.

\TrCommand{Step to Next Spied Procedure or Spied Goal}{ss [COUNT]}
In this case, any spy case causes stop.

\TrCommand{Step to Next Spied Procedure and Spied Goal}{SS [COUNT]}
In this case, procedure must be traced and called from a traced goal, to
cause stop.

\TrCommand{Skip to Next Spied Procedure}{np [COUNT]}
This works similarly to \verb|sp| command, but no trace is done until stop.

\TrCommand{Skip to Next Spied Goal}{ng [COUNT]}
This works similarly to \verb|sg| command, but no trace is done until stop.

\TrCommand{Skip to Next Spied Procedure or Spied Goal}{ns [COUNT]}
This works similarly to \verb|ss| command, but no trace is done until stop.

\TrCommand{Skip to Next Spied Procedure and Spied Goal}{NS [COUNT]}
This works similarly to \verb|SS| command, but no trace is done until stop.

\TrCommand{Enqueue This Goal to Head of Ready Goal Queue}{\verb|<|}
Enqueues the goal displayed at the time to head of ready goal queue.
This can be specified at \verb|RESU| and \verb|SWAP|.

\TrCommand{Enqueue This Goal to Tail of Ready Goal Queue}{\verb|>|}
Enqueues the goal displayed at the time to tail of ready goal queue.
This can be specified at \verb|RESU| and \verb|SWAP|.

\TrCommand{Depth First Schedule}{\verb|<<| [DEPTH]}
Scheduling politics for goals are changed to depth-first.
\verb|DEPTH| gives depth limit for TRO. Initial value is $2\SS{31}$.

\TrCommand{Breadth First Schedule}{\verb|>>| [DEPTH]}
Scheduling politics for goals are changed to breadth-first.
\verb|DEPTH| gives depth limit for TRO. Initial value is 100.

\TrCommand{Random Schedule}{\verb|><| [RATE[SEED[DEPTH]]]}
Scheduling politics for goals are basically depth-first,
and some of goals are pushed to the tail of the scheduleing queue
according to the calculated random number.
This makes possible to simulate the undecided reduction ordering.
\verb|RATE| specifies the ratio of goals pushed to the tail of the queue
by percentage. \verb|SEED| is the seed of the calculation of random number.
\verb|DEPTH| gives depth limit for TRO.

\TrCommand{Re-Write Goal}{w LENGTH [DEPTH]}
This redisplays current goal and arguments, with modified format limits
\verb|LENGTH| and \verb|DEPTH|. This is useful when arguments are large.

\TrCommand{Where call from}{where}
Shows the names of predicate and module which called current traced goal. This
is valid only for run-time support routines or built-in predicates (D code).

\TrCommand{Monitor Variable}{m VARIABLE_NAME [NAME] [LIMIT]}
\index{Monitor Variables}
Monitors the value of variable, whenever it is bound. If the value is a
list or a stream, display occurs whenever the top element is bound. Using
\verb|NAME|, it is possible to assign a new identifier to the monitored
variable, so that the value is shown under that name. \verb|LIMIT| is the
number of times value can be shown without stopping the system. Without this
parameter, whenever a variable is bound, the value is shown and the tracer
waits for a user command.\\
During display of value, whether the value is a list or
not is distinguished :\vspace{1ex}

\hspace{10ex}
\verb|mon#var-name => value %%|\hspace{4ex} $\cdots$
					\verb|In the case of a list.|

\hspace{10ex}
\verb|mon#var-name == value %%|\hspace{4ex} $\cdots$ \verb|Otherwise.|

In this situation, the following commands are available :
\vspace{1ex}\\
\hspace*{15mm}\begin{tabular}{l@{ :: }l}
{\bf ?}                     & Help.\\
{\bf x}                     & Stops monitoring this variable or list.\\
{\bf s  [COUNT]}            & Goes ahead monitoring value without stop, 
					for \verb|COUNT| times.\\
{\bf w  LENGTH [DEPTH]}     & Redisplays value.\\
{\bf m  VAR [NAME] [LIMIT]} & Sets a different monitoring.\\
\end{tabular}
\vspace{1ex}

\TrCommand{Inspect Ready Queue}{ir [PRIORITY]}
Shows goals in ready queue. If \verb|PRIORITY| is given, only goals with that
 physical priority are shown.

\TrCommand{Inspect Variable}{iv VARIABLE_NAME}
Shows state of specified variable. When state is HOOK or MHOOK (goals are
waiting for the instantiation of this variable), shows the waiting goals. When
state is MGHOK (input merger variable), shows merger output variable.

\TrCommand{Inspect Sho-en tree}{is}
Shows Sho-en tree structure at current time. Horizontal drawing axis is used
to represent the parent/children dependency, whereas the vertical axis is
used to represent brotherhood. Each Sho-en is described using 5 characters :
the first one corresponds to the state of Sho-en and the remaining 4 to its
ID. Possible Sho-en status follow :
\vspace{1ex}\\
\hspace*{15mm}\begin{tabular}{c@{ :: }l}
R & Ready.\\
S & Suspended.\\
A & Aborted.\\
\end{tabular}
\vspace{1ex}

\TrCommand{Trace Shoen tree}{ts}
Turn on/off the trace flag of Sho-en tree structure. When on, tree structure is
shown before and after each modification(e.g. generation, abortion,
termination). The format of the description is the same as for above command.

\TrCommand{Set Tracer Variable}{set NAME [VALUE]}
Tracer variable \verb|NAME| is set to \verb|VALUE|, if present. Otherwise,
current value is displayed.
Current tracer variables and their default values are now listed.
\vspace{1ex}\\
\hspace*{15mm}\begin{tabular}{c@{ :: }p{120mm}}
{\bf pv} & Print variable mode. If value is \verb|n|, variables are displayed
alphabetically. If \verb|a| is used, relative address are used.\\
{\bf pl} & Print length value.\\
{\bf pd} & Print depth value.\\
{\bf g} & Gate switch which determines whether trace is done or not upon each
trace point. Value is made of five characters, each one with value \verb|n|,
\verb|t| or \verb|s|. These values correspond to ``no trace'',
``trace (no stop)'' and ``trace (stop)'' respectively.
Characters correspond to points CALL/call,
SUSP/Susp, RESU, SWAP and FAIL, respectively.\\
{\bf c}  & Gate Switch for CALL points. Value is n, t or s.\\
{\bf s}  & Gate Switch for SUSP points. Value is n, t or s.\\
{\bf r}  & Gate Switch for RESU points. Value is n, t or s.\\
{\bf w}  & Gate Switch for SWAP points. Value is n, t or s.\\
{\bf f}  & Gate Switch for FAIL points. Value is n, t or s.\\
\end{tabular}
\vspace{1ex}
\end{itemize}

\newpage
\section{Dead-lock Detection}\index{Deadlock}
\label{sec-deadlock}

In PDSS, there are two dead-lock detection mechanisms. One acts through global
GC, whereas the other tries to detect deadlock during execution. During GC,
deadlock\index{deadlock} is always detected, whereas deadlock check done
during execution sometimes fails.

In the following, types of deadlock detected in PDSS and tracer messages are
shown.
\vspace{2ex}

\noindent\underline{\bf Dead lock detection occurred during GC : Type=0}
\vspace{1ex}\par
Example : when executing the following goal :
\begin{verbatim}
            Goal :: ?- add(X,_,Y), divide(Y,_,Z), modulo(Z,_,_).
\end{verbatim}\par
Following information is shown on the console window.
\begin{verbatim}
            GC-1     KL1-Data   Srec   Grec  Prec  HeapTotal     Code
            Used :       2594     20     75    10      30112        0
            Deadlock::[0001]$$$SYSTEM:modulo(A~,B,C)
            Deadlock::[0001]$$$SYSTEM:divide(D~,E,A~)
            Deadlock::[0001]$$$SYSTEM:add(F~,G,D~)
            *** Previous goal is deadlock root!
            Shoen is terminated by deadlock!
            After:       1083     14     57     3      15344        0
            GCed :       1511      6     18     7      14768        0
                         word    rec    rec   rec       byte     byte
            GC Time: 40 msec
\end{verbatim}\par
The goal appearing before message
``Previous goal is deadlock root!'' on console window
is the root of the data dependance tree. There are some cases where several
such trees exist and root is not unique in general. If there are loops
structures, there is no root.
\vspace{1ex}

\noindent\underline{\bf
Variable referred only by itself (void variable) waiting for instantiation : 
Type=10}
\vspace{1ex}\par
Example : In the following program, after execution of \verb|p(X)| is executed.
\begin{verbatim}
            Goal :: ?- module:go.
            Clause-1 :: go   :- p(X).
            Clause-2 :: p(a) :- true | true.
\end{verbatim}\par
Following information is shown on the console window.
\begin{verbatim}
            *** Deadlock occurred. [suspend(UNDEFoo)]
            *** Waiting for instantiation of a void variable.
            [0001]module:p(A).
\end{verbatim}
\vspace{1ex}

\noindent\underline{\bf
Waiting for instantiation of a variable which will never be instantiated by
other goals : Type = 11}
\vspace{1ex}\par
Example : In the following program, after execution of \verb|p(X)|, \verb|q(X)| is executed.
\begin{verbatim}
            Goal :: ?- module:go.
            Clause-1 :: go   :- true | p(X), q(X).
            Clause-2 :: p(a) :- true | true.
            Clause-3 :: q(a) :- true | true.
\end{verbatim}\par
Following information is shown on the console window.
\begin{verbatim}
            *** Deadlock occurred. [suspend(HOOKoo)]
            *** Waiting for instantiation of a variable which never be instantiated.
            [0001]module:q(A~).
            [0001]module:p(A~).
\end{verbatim}
\vspace{1ex}

\noindent\underline{\bf
Input variable of the merger, referred only by itself, waiting for instantiation : Type=12}
\vspace{1ex}\par
Example : In the following program, after execution of \verb|merge(In,Out)|,
\verb|p(X)| is executed.\vspace{1ex}

\hspace{11ex} \verb|Goal :: ?- module:go.|

\hspace{11ex}
\verb!Clause-1  :: go   :- true | merge(In, Out), p(In), ! $\cdots$ .

\hspace{11ex}
\verb!Clause-2  :: p(a) :- true | true.!
\par
Following information is shown on the console window.
\begin{verbatim}
            *** Deadlock occurred. [suspend(MGHOKo)]
            *** Waiting for instantiation of a merger input variable.
            [0001]module:p(A^).
            [0001]merge(A^,B) in module:go/0
\end{verbatim}
\vspace{1ex}

\noindent\underline{\bf
Variable, which has a goal waiting for instantiation, is unified with
a void variable : Type=20}
\vspace{1ex}\par
Example : In the following program, after execution of \verb|p(X)|,
\verb|q(X,Y)| is executed. This case also occurs if \verb|Y| was not void,
but would turn void as a result of the execution.
\begin{verbatim}
            Goal :: ?- module:go.
            Clause-1 :: go :- p(X), q(X,Y).
            Clause-2 :: p(a) :- true | true.
            Clause-3 :: q(A,B) :- true | A=B.
\end{verbatim}\par
Following information is shown on the console window.
\begin{verbatim}
            *** Deadlock occurred. [unify(HOOKoo,VOID)]
            *** A variable which has a goal waiting for instantiation is unified with
            *** a void variable.
            *** Unification occurred in module:q/2
            [0001]module:p(A~).
\end{verbatim}
\vspace{1ex}

\noindent\underline{\bf
Merger input is unified with void variable : Type=21}
\vspace{1ex}\par
Example : In the following program, \verb|p(In,_)| is executed after \verb|merge(In,Out)|.
\begin{verbatim}
            Goal :: ?- moduel:go.
            Clause-1  :: go :- true | merge(In, Out), p(In,_), q(Out).
            Clause-2  :: p(A,B) :- true | A=B.
            Clause-3  :: q([_|Cdr]) :- true | q(Cdr).
\end{verbatim}\par
Following information is shown on the console window.
\begin{verbatim}
            *** Deadlock will occur. [unify(MGHOKo,VOID)]
            *** A merger input variable is unified with a void variable.
            *** Unification occurred in module:p/2
            [0001]merge(A^,B) in module:go/0
\end{verbatim}
\vspace{1ex}

\noindent\underline{\bf
Unifying two variables which have goals waiting for instantiation : Type = 22}
\vspace{1ex}\par
Example : In the following program, \verb|r(X,Y)| is executed after \verb|p(X)| and \verb|q(X)|.
\begin{verbatim}
            Goal :: ?- module:go.
            Clause-1 :: go :- true | p(X), q(Y), r(X,Y).
            Clause-2 :: p(a) :- true | true.
            Clause-3 :: q(a) :- true | true.
            Clause-4 :: r(A,B) :- true | A=B.
\end{verbatim}\par
Following information is shown on the console window.
\begin{verbatim}
            *** Deadlock occurred. [unify(HOOKoo,HOOKoo)]
            *** Unifying two variables which have goals waiting for instantiation.
            *** Unification occurred in module:r/2
            [0001]module:p(A~).
            [0001]module:q(B~).
\end{verbatim}
\vspace{1ex}

\noindent\underline{\bf
Unifying input of merger and variable which has a goal waiting for instantiation : Type=23}\vspace{1ex}\par
Example : In the following program, \verb|q(X,In)| is executed after
\verb|merge(In,Out)| and \verb|p(X)|.
\begin{verbatim}
            Goal :: ?- module:go.
            Clause-1 :: go   :- true | merge(In, Out), p(X), q(X, In), r(Out).
            Clause-2 :: p(a) :- true | true.
            Clause-3 :: q(A,B) :- true | A=B.
            Clause-4 :: r([_|Cdr]) :- true | r(Cdr).
\end{verbatim}\par
Following information is shown on the console window.
\begin{verbatim}
            *** Deadlock occurred. [unify(HOOKoo,MGHOKo)]
            *** Unifying variable which has a goal waiting for instantiation is unified
            *** and a merger input variable.
            *** Unification occurred in module:q/2
            [0001]module:p(A~).
            [0001]merge(B^,C) in module:go/0
\end{verbatim}
\vspace{1ex}

\noindent\underline{\bf
Unification of two merger inputs : Type = 24}
\vspace{1ex}\par
Example : In the following program, \verb|In1=In2| is executed after
\verb|merge(In1,Out1)| and \verb|merge(In1,Out2)|.
\begin{verbatim}
            Goal :: ?- module:go.
            Clause-1 :: go :- true | merge(In1, Out1), merge(In2, Out2),
                                     p(In1,In2), q(Out1), r(Out2).
            Clause-2 :: p(A,B) :- true | A=B.
            Clause-3 :: q([_|Cdr]) :- true | q(Cdr).
            Clause-4 :: r([_|Cdr]) :- true | r(Cdr).
\end{verbatim}\par
Following information is shown on the console window.
\begin{verbatim}
            *** Deadlock will occur. [unify(MGHOKo,MGHOKo)]
            *** Unifying two merger input variables.
            *** Unification occurred in module:p/2
            [0001]merge(A^,B) in module:go/0
            [0001]merge(C^,D) in module:go/0
\end{verbatim}
\vspace{1ex}

\noindent\underline{\bf
A variable which has a goal waiting for instantiation is
not referred : Type=30}\vspace{1ex}\par
Example : In the following program, \verb|q(X)| is executed after \verb|p(X)|.
\begin{verbatim}
            Goal :: ?- module:go.
            Clause-1 :: go   :- true | p(X), q(X).
            Clause-2 :: p(a) :- true | true.
            Clause-3 :: q(_) :- true | true.
\end{verbatim}\par
Following information is shown on the console window.
\begin{verbatim}
            *** Deadlock occurred. [collect(HOOKoo)]
            *** A variable which has a goal waiting for instantiation was abandoned.
            *** Collect_value occurred in module:q/1
            [0001]module:p(A~).
\end{verbatim}
\vspace{1ex}

\noindent\underline{\bf
A merger input variable is not referred : Type=31}
\vspace{1ex}\par
Example : In the following program, \verb|p(In)| is executed after \verb|merge(In,Out)|.
\begin{verbatim}
            Goal :: ?- module:go.
            Clause-1 :: go   :- true | merge(In, Out), p(In), q(Out).
            Clause-2 :: p(_) :- true | true.
            Clause-3 :: q([_|Cdr]) :- true | q(Cdr).
\end{verbatim}\par
Following information is shown on the console window.
\begin{verbatim}
            *** Deadlock will occur. [collect(MGHOKo)]
            *** A merger input variable was abandoned.
            *** Collect_value occurred in module:p/1
            [0001]merge(A^,B) in module:go/0
\end{verbatim}

\newpage
\BeginAppendix

\Appendix{I/O devices}\index{I/O Devices}
\AppendixLabel{sec-IO-device}

PDSS provides window, file and timer I/O devices.\index{Window}\index{File}
Commands to these devices are inserted in streams.
These devices are defined in modules named \verb|pdss_window_device|,
\verb|pdss_file_device| and \verb|pdss_timer_device|.  This specification is
based upon ``FEP-Host I/O Interface (V0.9)''.  Full features have
not be implemented. Some of the messages or commands are therefore 
dummy or illegal.
And macro expression \verb|fep#xxxx| is in the library, so to use these macros,
the following definition must be declared in the module.
\begin{verbatim}
          :- with_macro pdss.
\end{verbatim}\index{with_macro}
\vspace{1ex}

\noindent\underline{\bf Acquisition of device stream}\vspace{1ex}\par
\index{Input/Output Device!Device Stream}
\index{Input/Output Device!Securing Device Stream}
Device stream can be obtained by the predicates listed below.
These predicates can be called only once after the emulator has been
invoked.  Twice or more calls will fail.
\begin{itemize}

\DevCreate{pdss_window_device:windows(Stream)}
Unifies \verb|Stream| with the command stream of window device.

\DevCreate{pdss_file_device:files(Stream)}
Unifies \verb|Stream| with the command stream of file device.

\DevCreate{pdss_timer_device:files(Stream)}
Unifies \verb|Stream| with the command stream of timer device.

\end{itemize}
\vspace{1ex}

\noindent\underline{\bf Device commands}\vspace{1ex}\par
\index{Input/Output Device!Device Commands}
\begin{enumerate}
\item Window device\\ \index{Input/Output Device!Window Device}
Window device provides multiple window facility within GNU-Emacs. The following
commands can be sent to this device :
\begin{itemize}

\DevCommand{create(BufferName, WindowStream, ^Status, Cdr)}
Opens a window with buffer name \verb|BufferName| (8 bits string),
then unifies its command stream with \verb|WindowStream|.  When
window is opened successfully, \verb|Status| is unified with
\verb|fep#normal|.  PDSS can't open more than 16 windows at a
time. Therefore, it fails when user tries to open too many windows. In this
case,
\verb|Status| is unified with \verb|fep#abnormal|. I/O commands and
control commands described below can be inserted in the command stream of
a window which has been successfully opened. Note that reset/4 command must
be applies before those commands to set up abort and attention lines. 
The window is automatically closed when its stream is closed.

\DevCommand{create(WindowStream, ^Status, Cdr)}
Create/3 without buffer name is not available.

\DevCommand{get_max_size(X, Y, PathName, ^Characters, ^Lines, ^Status, Cdr)}
Always returns \verb|Characters| = 80, \verb|Lines| = 40,
\verb|Status| = \verb|fep#normal|.

\end{itemize}
\item File device\\ \index{Input/Output Device!File Device}
This device provides standard facilities of UNIX files. The following commands
can be applied to this device :
\begin{itemize}

\DevCommand{open(PathName, Mode, FileStream, ^Status, Cdr)}
Opens file with path name \verb|PathName| (8 bits string), mode
\verb|Mode| (atom:\verb|fep#read| = read mode, \verb|fep#write| =
write mode, \verb|fep#append| = append mode), then unifies
\verb|FileStream| with the command stream.  When the file is opened
successfully, \verb|Status| is unified with \verb|fep#normal|.
Otherwise, \verb|Status| is unified with \verb|fep#abnormal|.  I/O
commands and control commands can be applied to a file
which has been successfully opened (reset/4 is also requisite for files).
The file is automatically closed when its stream is closed.

\DevCommand{directory(PathName, DirectoryStream, ^Status, Cdr)}
Opens directory with path name \verb|PathName| (8 bits string) and
unifies \verb|DirectoryStream| with its command stream.  When
open is successful, \verb|Status| is unified with \verb|fep#normal|.
When it fails, \verb|Status| is unified with
\verb|fep#abnormal|.  Commands can be inserted in a
directory stream which has been successfully created
(reset/4 is also requisite
for directory.). A directory is automatically closed when its
stream is closed.

\end{itemize}
\item Timer device \index{Input/Output Device!Timer Device}

Unit of time of the timer device is millisecond, but updates are actually
performed each second. The following commands can be sent to the timer
device :
\begin{itemize}

\DevCommand{get_count(^Count, ^Status, Cdr)}
\verb|Count| is unified with the total elapsed milliseconds since 00:00:00
AM. \verb|Status| is unified with \verb|fep#normal|.

\DevCommand{on_at(Count, ^Now, ^Status, Cdr)}
When the time specified by \verb|Count| is reached, \verb|Now| is unified with
\verb|fep#wake_up|.  \verb|Status| is unified with \verb|fep#normal|
when the command is over.

\DevCommand{on_after(Count, ^Now, ^Status, Cdr)}
When duration specified by \verb|Count| has elapsed, \verb|Now| is unified with
\verb|fep#wake_up|. Status is unified with \verb|fep#normal|
when the command is over.

\end{itemize}
\end{enumerate}
\vspace{1ex}

\noindent\underline{\bf Window, file and directory commands}
\index{Window|(} \index{File|(}
\vspace{1ex}\par
\begin{enumerate}
\item Control commands common to windows and files\\

These commands are available for window and file devices.
\begin{itemize}

\DevCommand{reset(AbortLine, ^AttentionLine, ^Status, Cdr)}
Sets up abort and attention lines. This command should be issued
right after the I/O stream has been generated. To abort an I/O request,
\verb|AbortLine| must be unified with \verb|fep#abort| by the host.  Once
unified, abort line and attention line must be set up again
with reset/4 command. Otherwise, the stream can still be closed with
\verb|[]|. \verb|AttentionLine| is unified with interrupt code generated by
device (integer). Upon interrupt,
I/O should be aborted or attention line should be set again
with next_attension/3 command.

\DevCommand{next_attention(^Attention, ^Status, Cdr)}
Only attention line is set by this command. This command is used
when user does not want to abort I/O after interrupt.

\end{itemize}

\item Common input commands\\

There commands are available for window or file devices working in
read mode.
\begin{itemize}

\DevCommand{getc(^Char, ^Status, Cdr)}
Reads one character and unifies it with \verb|Char|. When input is
completed successfully, \verb|Status| is unified with
\verb|fep#normal|. If end of file is encountered,
\verb|Status| is unified with \verb|fep#end_of_file|.

\Caution Not available on Multi-PSI V2 FEP.

\DevCommand{getl(^Line, ^Status, Cdr)}
Reads one line, converts it into an 8 bits string, then unifies it with
\verb|Line|.  At this time, newline code is removed. When the input is
completed successfully, \verb|Status| is unified with
\verb|fep#normal|. If end of file is encountered,
\verb|Status| is unified with \verb|fep#end_of_file|.

\Caution Not available for files on Multi-PSI V2 FEP.

\DevCommand{getb(Size, ^Buffer, ^Status, Cdr)}
Reads the number of bytes specified by \verb|Size| (integer),
and converts them into an 8 bits
string, unified with \verb|Buffer|. If a newline is encountered while
reading from a window, input stops at newline character.
When the input is completed successfully, \verb|Status| is unified with
\verb|fep#normal|. If end-of-file is encountered,
it is unified with \verb|fep#end_of_file|.

\Caution Not available for windows on Multi-PSI V2 FEP.

\DevCommand{gettkn(^TokenList, ^Status, ^NumberOfVariables, Cdr)}
Reads a string constructed as one term then analyzes this string
to extract tokens. The list of generated tokens is unified with
\verb|TokenList|.\index{Token Format}

\vspace{1ex}
\hspace*{15mm}\begin{tabular}{l@{ :: }l}
variable          & \verb|$VAR(N,String)|\\
atom              & \verb|atom(Atom)|\\
integer           & \verb|integer(Integer)|\\
floating point    & \verb|float(Float)|\\
string            & \verb|string(String)|\\
functor           & \verb|open(Atom)|\\
signs             & \verb|sign(Atom)|\\
special character & atom that has special character as print name.\\
illegal data      & \verb|illegal(String)|\\
end               & \verb|end|\\
\end{tabular}

\vspace{1ex}
When the input is completed successfully, \verb|Status| is unified with
\verb|fep#normal|. If end-of-file is found, it is unified with
\verb|fep#end_of_file|. If an error occured during token
analysis, \verb|Status| is unified with \verb|fep#abnormal|.

\Caution Not available on Multi-PSI V2 FEP.

\end{itemize}
\item Common output commands\\

These commands are available for window and file devices opened in write or
append more.
\begin{itemize}

\DevCommand{putc(Char, ^Status, Cdr)}
Writes the character corresponding to \verb|Char| (integer)
according to the ASCII code.
\verb|Status| is unified with \verb|fep#normal|.

\Caution Not available on Multi-PSI V2 FEP.

\DevCommand{putl(Line, ^Status, Cdr)}
Writes string \verb|Line| (8 bits string) and adds a newline character.
\verb|Status| is unified with \verb|fep#normal|.

\Caution Not available on Multi-PSI V2 FEP.

\DevCommand{putb(Buffer, ^Status, Cdr)}
Writes string in Buffer (8 bits string).  \verb|Status| is
unified with \verb|fep#normal|.

\DevCommand{putt(Term, Length, Depth, ^Status, Cdr)}
Writes the term specified by \verb|Term|, whith maximum length \verb|Length|
and maximum depth \verb|Depth|. The part of term which exceeds Length or Depth
is printed as `\verb|...|'. \verb|Status| is unified with \verb|fep#normal|.
Since this command uses output function for debugging, variables in \verb|Term|
are written like A, B, C with a symbol MRB or HOOK.

\Caution Not available on Multi-PSI V2 FEP.

\end{itemize}
\item Window control commands\\

These commands are available only for windows.
\begin{itemize}

\DevCommand{close(^Status)}
Closes the window. \verb|Status| is unified with \verb|fep#normal|.

\DevCommand{flush(^Status, Cdr)}
No op. \verb|Status| is unified with \verb|fep#normal|. Data
which have been written are automatically flushed, even if flush/2
is not issued.

\DevCommand{beep(^Status, Cdr)}
Rings the terminal bell. \verb|Status| is unified with \verb|fep#normal|.

\DevCommand{clear(^Status, Cdr)}
Erases contents of window. \verb|Status| is unified with
\verb|fep#normal|.

\DevCommand{show(^Status, Cdr)}
Makes window visible. \verb|Status| is unified with \verb|fep#normal|.
Since the window stays invisible after creation, one has to
make it explicitely visible with this command.

\DevCommand{hide(^Status, Cdr)}
Makes window invisible. \verb|Status| is unified with \verb|fep#normal|.

\DevCommand{activate(^Status, Cdr)}
Same as show/2.

\DevCommand{deactivate(^Status, Cdr)}
Same as hide/2.

\DevCommand{set_inside_size(Characters, Lines, ^Status, Cdr)}
No op. \verb|Status| is unified with \verb|fep#normal|.

\DevCommand{set_size(fep\#manipulator, ^Status, Cdr)}
No op. \verb|Status| is unified with \verb|fep#normal|.

\DevCommand{set_position(X, Y, ^Status, Cdr)}
No op. \verb|Status| is unified with \verb|fep#normal|.

\DevCommand{set_position(fep\#manipulator, ^Status, Cdr)}
No op. \verb|Status| is unified with \verb|fep#normal|.

\DevCommand{set_title(String, ^Status, Cdr)}
No op. \verb|Status| is unified with \verb|fep#normal|.

\DevCommand{reshape(X, Y, Characters, Lines, ^Status, Cdr)}
No op. \verb|Status| is unified with \verb|fep#normal|.

\DevCommand{reshape(fep\#manipulator, ^Status, Cdr)}
No op. \verb|Status| is unified with \verb|fep#normal|.

\DevCommand{set_font(PathName, ^Status, Cdr)}
No op. \verb|Status| is unified with \verb|fep#normal|.

\DevCommand{select_buffer(BufferName, ^Status, Cdr)}
Not available.

\DevCommand{get_inside_size(^Characters, ^Lines, ^Status, Cdr)}
Always returns \verb|Characters| = 80, \verb|Lines| = 20,
\verb|Status| = \verb|fep#normal|.

\DevCommand{get_position(^X, ^Y, ^Status, Cdr)}
Always returns \verb|X| = 0, \verb|Y| = 0, \verb|Status| = \verb|fep#normal|.

\DevCommand{get_title(^Title, ^Status, Cdr)}
Returns name with which the window was created.

\DevCommand{get_font(PathName, ^Status, Cdr)}
Not available.

\end{itemize}
\item File control commands\\

These commands are available for only files.
\begin{itemize}

\DevCommand{close(^Status)}
Closes file. \verb|Status| is unified with \verb|fep#normal|.

\DevCommand{end_of_file(^Status, Cdr)}
\verb|Status| is unified with \verb|fep#yes| when the end of file
has been encountered. Otherwise, it is unified with \verb|fep#no|.

\DevCommand{pathname(^PathName, ^Status, Cdr)}
Unifies file pathname with \verb|PathName|. \verb|Status| is unified with
\verb|fep#normal|.

\end{itemize}\index{Window|)}\index{File|)}
\item Directory control command\\

These commands are available for only directory streams.
\begin{itemize}

\DevCommand{pathname(^PathName, ^Status, Cdr)}
Unifies pathname of directory with \verb|PathName|. \verb|Status|
is unified with  \verb|fep#normal|.

\DevCommand{listing(WildCard, FileNameStream, ^Status, Cdr)}
Unifies the list of pathnames corresponding to \verb|WildCard| (8 bits string)
with \verb|FileNameStream|. \verb|Status| is unified with \verb|fep#normal|. 
\verb|FileNameStream| can include a command
next_file_name (^FileName, ^Status, Cdr).
Then one file name (8 bits string) is returned through
\verb|FileNameStream| and \verb|Status| is unified with \verb|fep#normal|.
When no more files are available, \verb|Status| is unified with
\verb|fep#end_of_file|.

\DevCommand{delete(WildCard, ^Status, Cdr)}
Deletes all files corresponding to \verb|WildCard| (8 bits string). PDSS
can not recover deleted files. \verb|Status| is unified with
\verb|fep#normal|.

\DevCommand{undelete(WildCard, ^Status, Cdr)}
No op. \verb|Status| is unified with \verb|fep#normal|.

\DevCommand{purge(WildCard, ^Status, Cdr)}
No op. \verb|Status| is unified with \verb|fep#normal|.

\DevCommand{deleted(WildCard, ^FileNameStream, ^Status, Cdr)}
Returns a stream from which deleted files corresponding to \verb|WildCard|
(8 bits string) can be extracted.
This list is always empty. Status is unified with \verb|fep#normal|.

\DevCommand{expunge(^Status, Cdr)}
No op. \verb|Status| is unified with \verb|fep#normal|.

\end{itemize}
\end{enumerate}

\newpage
\Appendix{Code device}\index{Code Device}
\AppendixLabel{sec-code-device}

This device manages code. Code can be manipulated by inserting
commands into device stream. (Currently, only Micro PIMOS
is allowed to use code device stream, which is not available for the average
user.)\index{Code Device!Code Device Stream}
\begin{itemize}

\DevCommand{assemble_module(^ModuleName, FileName, ^Status)}
Assembles the file \verb|FileName| (8 bits string) and
loads it into the code area. \verb|ModuleName| is unified with the atom named
after the assembled module name. \verb|Status| is unified with \verb|success|,
\verb|cannot_open_file|, \verb|memory_limit|, \verb|module_protected|
or \verb|load_error|, depending on how the operation has been proceeded.

\DevCommand{load_module(^ModuleName, FileName, ^Status)}
Loads file specified by \verb|FileName| into code area. File format should
be either save or assembler format. \verb|ModuleName| is unified
with the atom named after the loaded module name. \verb|Status| is unified with
\verb|success|, \verb|cannot_open_file|, \verb|memory_limit|,
\verb|module_protected| or \verb|error|, depending on the course of operations.

\DevCommand{save_module(ModuleName, FileName, ^Status)}
Saves the module \verb|ModuleName| (atom) to file
\verb|FileName| (8 bits string).
\verb|Status| is unified with \verb|success|,
\verb|cannot_open_file| or \verb|module_not_found|.

\DevCommand{remove_module(ModuleName, ^Status)}
Deletes module \verb|ModuleName| (atom). \verb|Status| is unified
with \verb|success|, \verb|module_not_found| or \verb|module_protected|.

\DevCommand{debug(Flag, ^Status)}
Switches debugging mode on or off. \verb|Flag| is \verb|on|
or \verb|off|(atom).  \verb|Status| is unified with \verb|success|
or \verb|undefined_module|.

\DevCommand{backtrace(Flag, ^Status)}
Switches backtrace (display of deadlocked goals detected
during global GC) on or off.  \verb|Flag| is atom \verb|on| or \verb|off|.
\verb|Status| is unified with \verb|success| or \verb|undefined_module|.

\DevCommand{trace_module(ModuleName, Mode, ^Status)}
Changes trace mode of the module \verb|ModuleName| (atom) to
\verb|Mode|.  Mode is \verb|on| or \verb|off|(atom). \verb|Status| is
unified with \verb|success|, \verb|module_not_found|, \verb|undefined_mode|
or \verb|native_code_module|.

\DevCommand{get_module_status(ModuleName, ^Mode, ^Status)}
Checks trace mode of the module \verb|ModuleName| (atom). 
\verb|Mode| is unified with \verb|on| or \verb|off|, according to the state of
trace mode. \verb|Status| is unified with \verb|success|,
\verb|module_not_found| or \verb|native_code_module|.

\DevCommand{spy_predicate(ModuleName, PredicateName, Arity, Mode, ^Status)}
Changes trace mode of the predicate
\verb|PredicateName|/\verb|Arity| in module \verb|ModuleName| (atom), to
\verb|Mode|. \verb|Mode| is atom \verb|on| or \verb|off|. \verb|Status| is
unified with \verb|success|, \verb|module_not_found|,
\verb|predicate_not_found|, \verb|undefined_mode| or \verb|native_code_module|.

\DevCommand{get_spied_predicates(ModuleName, ^Predicates, ^Status)}
Unifies \verb|Predicates| with
a list of information about the predicates spied in the
module \verb|ModuleName| (atom). Each element
is a two-elements-vector of the form \{predicate name atom, arity\}. 
\verb|Status| is unified with either \verb|success| or \verb|module_not_found|.

\DevCommand{get_public_predicates(ModuleName, ^Public, ^Status)}
Unifies \verb|Public| with a list of information about public predicates
in the module \verb|ModuleName|(atom). Each
element is a two-elements-vector of the form \{predicate name atom, arity\}. 
\verb|Status| is unified with either \verb|success| or \verb|module_not_found|.

\end{itemize}

\newpage
\Appendix{PIMOS common utilities}\index{PIMOS Common Utilities}
\AppendixLabel{sec-PIMOS-utl}

These utility programs were developped for PIMOS, but can be used on PDSS as
well. When provided modules are called, these utilities are loaded
automatically by Micro PIMOS auto-load function.

PIMOS provides the following conversion and store functions are common
utilities which can be used in both PIMOS and application programs.
When one wishes to use these facilities, he can get the conversion result
or object connection stream by calling predicates of the modules provided in
PIMOS. User manipulates objects by inserting messages in this stream,
through a merger.
\begin{itemize}
\item Comparison : a function which generates a total order upon KL1 data.
\item Hashing : a classical hash function.
\item Pool without key : bag, stack, queue, sorted bag.
\item Pool with key : keyed bag, keyed set, keyed sorted bag, keyed sorted set.
\end{itemize}
\vspace{3ex}

\noindent\underline{\bf 1. Comparison}\vspace{1ex}\par
\index{PIMOS Common Utilities!Comparison}
Generally, any KL1 data can compare via this mechanism.
\begin{itemize}

\PimosUtlCommand{comparator:sort(X, Y, ^S, ^L, ^Swapped)}
Compares \verb|X| and \verb|Y|, then
unifies the left hand element of the relation with \verb|S| and the right
one with \verb|L|. If \verb|X| = \verb|Y|, \verb|S| is unified with \verb|X|
and \verb|L| with \verb|Y| (like this relation is said to be stable).
Besides, if \verb|X| is larger than \verb|Y|,
\verb|Swapped| is unified with \verb|yes|, or with \verb|no| otherwise.
\vspace{1ex}

{\bf Definition of the comparison relation :}\\
If types of both data are different, order is the type order, i.e. integer,
atom, string, list, vector, from left to right. Otherwise, the relation is
defined as follows :
\vspace{1ex}

\hspace*{10mm}\begin{tabular}{l@{$\cdots$}p{120mm}}
$\bullet$ integer & Comparison between integers.\\
$\bullet$ atom  & Comparison between atom numbers.\\
$\bullet$ string & Lexicographic order, if strings are of the same type.
			Otherwise, type order.\\
$\bullet$ list & Comparison of Car. If they are the same, comparison of Cdr,
						and so on.\\
$\bullet$ vector & Comparison of the number of elements.
		If it is the same for both vectors, proceeds as for lists.\\
\end{tabular}
\end{itemize}
\vspace{1ex}

\noindent\underline{\bf 2. Hashing}\vspace{1ex}\par
\index{PIMOS Common Utilities!Hashing}
Standard hash function via this mechanism.
\begin{itemize}

\PimosUtlCommand{hasher:hash(X, ^H, ^Y)}
\verb|H| is unified with a non negative integer holding hash result. \verb|Y|
is unified with \verb|X|.
\vspace{1ex}

{\bf Hash function definition}\\
\hspace*{10mm}\begin{tabular}{l@{$\cdots$}p{120mm}}
$\bullet$ integer   & Absolute value.\\
$\bullet$ atom & Atom number.\\
$\bullet$ string & Cb $\times$ first-element + Cm $\times$ middle-element 
		+ Ce $\times$ last-element + string-length. 
		Cb, Cm and Ce are the same as KL0 built-in predicates.\\
$\bullet$ list & Car hash value + 5 $\times$ Cdr hash value.\\
$\bullet$ vector & number of elements + sum (for the first, middle 
	and last elements) of ((2 to the power of element rank+ 1) 
	$\times$ element hash value)\\
\end{tabular}
\end{itemize}
\vspace{1ex}

\noindent\underline{\bf 3. Pool without key}
\index{PIMOS Common Utilities!Pool without Key}\vspace{1ex}\par
Any KL1 data stored via this mechanism.
\vspace{1ex}

\noindent\underline{\bf Bag\index{Bag}}\vspace{1ex}\par
A basic pool. There are only basic functions put and get. To refer an element
 in
the pool we have to extract it, and there is no way to leave it inside pool.
\begin{itemize}

\PimosUtlCommand{pool:bag(Stream)}
Generates a bag object. \verb|Stream| is the command stream associated to it.

\end{itemize}
{\bf Message protocol :}
\begin{itemize}

\PimosUtlCommand{empty(^YorN)}
Returns \verb|yes|(atom) if the bag is empty, \verb|no| otherwise.

\PimosUtlCommand{put(X)}
Puts \verb|X| into the bag.

\PimosUtlCommand{get(^X)}
Gets \verb|X| from the bag. It is not possible to select a specific element.
After this operation, the element is removed from the bag. If no element is
in the bag, failure occurs.

\PimosUtlCommand{get_all(^O)}
\verb|O| is unified with the list of all elements in the bag. If none,
it is unified with \verb|[]|.

\PimosUtlCommand{get_and_put(^X, Y)}
Pulls out one element and unifies it with \verb|X|, then puts \verb|Y|
in its place. If the bag is empty, failure occurs.

\end{itemize}
\vspace{1ex}

\noindent\underline{\bf Stack}
\index{PIMOS Common Utilities!Stack}\vspace{1ex}\par
Basically the same as bag, but element order is LIFO.
\begin{itemize}

\PimosUtlCommand{pool:stack(Stream)}
Generates a stack object. \verb|Stream| is unified with the control stream.

\end{itemize}
{\bf Message protocol :} Same as bag protocol.
\vspace{1ex}

\noindent\underline{\bf Queue\index{Queue}}\vspace{1ex}\par
Basically the same as bag, but element order is FIFO.
\begin{itemize}

\PimosUtlCommand{pool:queue(Stream)}
Generates a queue. \verb|Stream| is unified with the control stream.

\end{itemize}
{\bf Message protocol :} Same as bag.
\vspace{1ex}

\noindent\underline{\bf Sorted Bag\index{Sorted Bag}}\vspace{1ex}\par
Works like a bag, but extraction order is 'least element first', according
to comparison function.
\begin{itemize}

\PimosUtlCommand{pool:sorted_bag(Stream)}
Generates a sorted bag object, with a standard comparator:sort/5 comparison
routine. \verb|Stream| is unified with the command stream.

\PimosUtlCommand{pool:sorted_bag(Comparator, Stream)}
Works the same, but comparison routine is specified by \verb|Comparator|, whose
format is \{module name atom, predicate name atom, arity\}. 
Sorted bag object, which has a \verb|Comparator| routine, is generated. 
\verb|Stream| is unified with the command stream. This predicate
must have been declared as public, with the same arity and function as
comparator:sort/5.

\end{itemize}
{\bf Message protocol :}\par
Same as bag. \verb|get| returns the least one and \verb|get_all| returns a
list sorted in ascending order.
\vspace{1ex}

\noindent\underline{\bf Keyed pool\index{Keyed Pool}}\vspace{1ex}\par
KL1 data are stored with a key by this mechanism.
\vspace{1ex}

\noindent\underline{\bf Keyed Bag\index{Keyed Bag}}\vspace{1ex}\par
Basic pool with a key. This is based on a hash table.
\begin{itemize}

\PimosUtlCommand{pool:keyed_bag(Stream)}
Generates a keyed bag object, using the standard hash function
(hasher:hash/3). \verb|Stream|
is unified with the command stream. Initial hash table size is 1.

\PimosUtlCommand{pool:keyed_bag(Stream, Size)}
This works the same as the previous predicate,
except that hash size is given by \verb|Size|.

\PimosUtlCommand{pool:keyed_bag(Hasher, Stream, Size)}
With this predicate, it is not only possible to specify hash table size,
but also the hash function. \verb|Hasher| is of the form \{module name atom,
predicate name atom, arity\}. The corresponding predicate must have been
declared as public, and have same arity and function as hasher:hash/3.

\end{itemize}
{\bf Message protocol :}
\begin{itemize}

\PimosUtlCommand{empty(^YorN)}
Returns \verb|yes|(atom) if bag is empty and \verb|no| otherwise.

\PimosUtlCommand{empty(Key, ^YorN)}
As above, but subset of elements with key \verb|Key| is examined.

\PimosUtlCommand{put(Key, X)}
Puts \verb|X| into the bag, using key \verb|Key|.

\PimosUtlCommand{get(Key, ^X)}
Unifies \verb|X| with one element with key \verb|Key|. If there are several
possible choices, one is picked up at random. After this operation, the
chosen element is removed from the bag. If no element with key \verb|Key| is
in the bag, failure occurs.

\PimosUtlCommand{get_all(^O)}
\verb|O| is unified with the list of all elements in the bag.
Each item in the list
is of the form \{key, element\}. If the bag is empty, \verb|O| is unified
with \verb|[]|.

\PimosUtlCommand{get_all(Key, ^O)}
\verb|O| is unified with the list of all elements with key \verb|Key|.

\PimosUtlCommand{get_and_put(Key, ^X, Y)}
Unifies \verb|X| with an element with key \verb|Key|, then replaces it with
\verb|Y|. If there is no such element, failure occurs.
\end{itemize}
\vspace{1ex}

\noindent\underline{\bf Keyed Set\index{Keyed Set}}\vspace{1ex}\par
This works like a keyed pool, except that duplicated keys are not allowed.
\begin{itemize}

\PimosUtlCommand{pool:keyed_set(Stream)}
This creates a keyed set. \verb|Stream| is unified with the command stream.
Standard hash function(hasher:hash/3) is used. Initial hash table size is one.

\PimosUtlCommand{pool:keyed_set(Stream, Size)}
This works the same, but hash table size is \verb|Size|.

\PimosUtlCommand{pool:keyed_set(Hasher, Stream, Size)}
This works the same, but it is also possible to specify the hash function which
should be used. See keyed_bag/3 predicate above.

\end{itemize}
{\bf Message protocol :}
\begin{itemize}

\PimosUtlCommand{empty(^YorN)}
Returns \verb|yes|(atom) if the bag is empty, \verb|no| otherwise.

\PimosUtlCommand{empty(Key, ^YorN)}
This works the same, but only the subset of elements with key \verb|Key| is
analyzed.

\PimosUtlCommand{put(Key, X, ^OldX)}
Adds an element with key \verb|Key| and value \verb|X|. If there is already
an element with the same key, its value is updated, and \verb|OldX| is
unified with \verb|{|old value\verb|}|.
Otherwise, \verb|OldX| is unified with \verb|{}|.

\PimosUtlCommand{get(Key, ^X)}
Unifies \verb|X| with the element with key \verb|Key|. If there is no such
element, failure occurs. The element is removed from the set
after this operation.

\PimosUtlCommand{get_all(^O)}
All elements are removed from the set, and \verb|O| is unified with a list
whose elements are of the form \{key, data\}. If the set was already empty,
\verb|O| is unified with \verb|[]|.

\PimosUtlCommand{get_all(Key, ^O)}
\verb|O| is unified with a list containing element with key \verb|Key|, which
is removed from the set. If there is no such element, \verb|O| is unified with
\verb|[]|.

\PimosUtlCommand{get_and_put(Key, ^X, Y)}
Replaces element with key \verb|Key| with \verb|Y|. Old value is return in
\verb|X|. If there is no element with such a key, failure occurs.

\end{itemize}
\vspace{1ex}

\noindent\underline{\bf Keyed Sorted Bag\index{Keyed Sorted Bag}}
\vspace{1ex}\par
This is similar to sorted bag, but sort is performed only upon key.
\begin{itemize}

\PimosUtlCommand{pool:keyed_sorted_bag(Stream)}
Generates a keyed sorted bag, using standards compare routine
(comparator:sort/5). \verb|Stream| is unified with the command stream.

\PimosUtlCommand{pool:keyed_sorted_bag(Comparator, Stream)}
Works the same, but \verb|Comparator| can be used to specify the sort routine.
Refer to sorted_bag/2 above, and comparator:sort/5.

\end{itemize}
{\bf Message protocol :}\par
It is similar to the one of keyed bag, but data comes out in increasing order
of key.
\vspace{1ex}

\noindent\underline{\bf Keyed Sorted Set\index{Keyed Sorted Set}}
\vspace{1ex}\par
This is similar to keyed sorted bag, but identical keys are not allowed.
\begin{itemize}

\PimosUtlCommand{pool:keyed_sorted_set(Stream)}
Generates keyed sorted set object, with standard compare routine
(comparator:compare/5). \verb|Stream| is unified with command stream.

\PimosUtlCommand{pool:keyed_sorted_set(Comparator, Stream)}
Works the same but \verb|Comparator| can be used to specify the comparison
predicate. See sorted_bag/2 above, and comparator:sort/5, for more information.

\end{itemize}
{\bf Message protocol :}\par
This is the same as the one of keyed set, but data comes out in increasing
order of key.

\newpage
\Appendix{Reserved module names}
\AppendixLabel{sec-system-module}

The following module names are reserved by PDSS, and should not be used.
Names marked with \verb|*| are available.
\begin{center}
\begin{minipage}[t]{70mm}
\begin{verbatim}

  'Sho-en'
* directory
* file
* window
* mpimos_io_device
  monogyny_list_index
  mpimos_booter
  mpimos_builtin_predicate
  mpimos_cmd_basic
  mpimos_cmd_code
  mpimos_cmd_debug
  mpimos_cmd_directory
  mpimos_cmd_environment
  mpimos_cmd_utl
  mpimos_code_manager
  mpimos_command_interpreter
  mpimos_libdir
  mpimos_directory
  mpimos_directory_device_driver
  mpimos_file
  mpimos_file_device_driver
  mpimos_file_manager
  mpimos_window_device
  mpimos_file_device
  mpimos_timer_device
  mpimos_macro_expander
  mpimos_module_pool
  mpimos_opcode_table
  mpimos_operator_manipulator
  mpimos_parser
  mpimos_task_monitor
  mpimos_unparser
  mpimos_utility
* mpimos_varchk
  mpimos_window
  mpimos_window_device_driver
  mpimos_window_manager
* mpimos_xref
* mpimos_xref_table
* mpimos_pretty_printer
  pdss_code_device

\end{verbatim}
\end{minipage}
\begin{minipage}[t]{70mm}
\begin{verbatim}

  pdss_window_device
  pdss_file_device
  pdss_timer_device
  pdss_runtime_active_unify
  pdss_runtime_debug
  pdss_runtime_exception_handling
  pdss_runtime_body_builtin
  kl1cmp_blttbl
  kl1cmp_command
  kl1cmp_compile
  kl1cmp_mrb
  kl1cmp_normalize
  kl1cmp_output
  kl1cmp_reader
  kl1cmp_register
  kl1cmp_macro
  kl1cmp_macro_arg
  kl1cmp_mtbl
  kl1cmp_struct

\end{verbatim}
\end{minipage}
\end{center}

\newpage
\Appendix{Reserved operator names}
\AppendixLabel{sec-operator}

The following operators are defined for PDSS windows and file input.
\begin{center}
\begin{minipage}[t]{70mm}
\begin{verbatim}

 1200   xfx   :-
 1200    fx   :-
 1200   xfx   -->
 1150    fx   module
 1150    fx   public
 1150    fx   implicit
 1150    fx   local_implicit
 1150    fx   with_macro
 1100   xfy   ;
 1100   xfy   |
 1090   xfx   =>
 1050   xfy   ->
 1000   xfy   ,
  800   xfx   :
  700   xfx   =
  700   xfx   \=
  700   xfx   =\=
  700   xfx   =:=
  700   xfx   ==
  700   xfx   $=:=
  700   xfx   $=\=
  700   xfx   $<
  700   xfx   $>
  700   xfx   $=<
  700   xfx   $>=
  700   xfx   $:=
  700   xfx   $<=
  700   xfx   <
  700   xfx   >
  700   xfx   =<
  700   xfx   >=
  700   xfx   :=
  700   xfx   <=
  700   xfx   <<=
  700   xfy   @
  500   yfx   +
  500    fx   +
  500   yfx   -
  500    fx   -
  500   yfx   /\
  500   yfx   \/
  500   yfx   xor
  400   yfx   *
  400   yfx   /
  400   yfx   <<
  400   yfx   >>
  300   xfx   mod
  300   xfy   **
  200    fx   &

\end{verbatim}
\end{minipage}
\begin{minipage}[t]{70mm}
\begin{verbatim}

  150   xf    ++
  150   xf    --
  100   xfx   #
  100    fx   #

\end{verbatim}
\end{minipage}
\end{center}

\newpage
\Appendix{List of built-in predicates}
\AppendixLabel{sec-builtin-table}
\begin{enumerate}

\item Type checking.
\begin{verbatim}
wait(X) :: G
atom(X) :: G
integer(X) :: G
floating_point(X) :: G
list(X) :: G
vector(X) :: G
string(X) :: G
unbound(X, ^PE, ^Addr, ^NewX) :: B

\end{verbatim}
\item diff
\begin{verbatim}
diff(X, Y) :: G

The following operator is available :  \=

\end{verbatim}
\item Comparison
\begin{verbatim}
equal(Integer1, Integer2) :: G
not_equal(Integer1, Integer2) :: G
less_than(Integer1, Integer2) :: G
not_less_than(Integer1, Integer2) :: G

The following operators are available :
    =:=, =\=, <, =<, >, >=

\end{verbatim}    
\item Arithmetic Operations
\begin{verbatim}
add(Integer1, Integer2, ^NewInteger) :: GB
subtract(Integer1, Integer2, ^NewInteger) :: GB
multiply(Integer1, Integer2, ^NewInteger) :: GB
divide(Integer1, Integer2, ^NewInteger) :: GB
modulo(Integer1, Integer2, ^NewInteger) :: GB
minus(Integer, ^NewInteger) :: GB
increment(Integer, ^NewInteger) :: GB
decrement(Integer, ^NewInteger) :: GB
abs(Integer, ^NewInteger) :: GB
min(Integer1, Integer2, ^NewInteger) :: GB
max(Integer1, Integer2, ^NewInteger) :: GB
and(Integer1, Integer2, ^NewInteger) :: GB
or(Integer1, Integer2, ^NewInteger) :: GB
exclusive_or(Integer1, Integer2, ^NewInteger) :: GB
complement(Integer, ^NewInteger) :: GB
shift_left(Integer, ShiftWidth, ^NewInteger) :: GB
shift_right(Integer, ShiftWidth, ^NewInteger) :: GB

:=, <= can be used with the following operators :
    +, -, *, /, mod, /\, \/, xor, <<, >>

\end{verbatim}
\item Floating Point Comparison
\begin{verbatim}
floating_point_equal(Float1, Float2) :: G
floating_point_not_equal(Float1, Float2) :: G
floating_point_less_than(Float1, Float2) :: G
floating_point_not_less_than(Float1, Float2) :: G

The following operators are available :
   $=:=, $=\=, $<, $=<, $>, $>=

\end{verbatim}
\item Floating Point Operations
\begin{verbatim}
floating_point_add(Float1, Float2, ^NewFloat) :: GB
floating_point_subtract(Float1, Float2, ^NewFloat) :: GB
floating_point_multiply(Float1, Float2, ^NewFloat) :: GB
floating_point_divide(Float1, Float2, ^NewFloat) :: GB
floating_point_minus(Float, ^NewFloat) :: GB
floating_point_abs(Float, ^NewFloat) :: GB
floating_point_min(Float1, Float2, ^NewFloat) :: GB
floating_point_max(Float1, Float2, ^NewFloat) :: GB
floating_point_floor(Float, ^NewFloat) :: GB
floating_point_sqrt(Float, ^NewFloat) :: GB
floating_point_ln(Float, ^NewFloat) :: GB
floating_point_log(Float, ^NewFloat) :: GB
floating_point_exp(Float, ^NewFloat) :: GB
floating_point_pow(Float1, Float2, ^NewFloat) :: GB
floating_point_sin(Float, ^NewFloat) :: GB
floating_point_cos(Float, ^NewFloat) :: GB
floating_point_tan(Float, ^NewFloat) :: GB
floating_point_asin(Float, ^NewFloat) :: GB
floating_point_acos(Float, ^NewFloat) :: GB
floating_point_atan(Float, ^NewFloat) :: GB
floating_point_atan(Float1, Float2, ^NewFloat) :: GB
floating_point_sinh(Float, ^NewFloat) :: GB
floating_point_cosh(Float, ^NewFloat) :: GB
floating_point_tanh(Float, ^NewFloat) :: GB

$:=, $<= can be used with the following operators :
    +, -, *, /, **

\end{verbatim}
\item Floating Point Conversion
\begin{verbatim}
floating_point_to_integer(Float, ^Integer) :: GB
integer_to_floating_point(Integer, ^Float) :: GB

\end{verbatim}
\item Vectors
\begin{verbatim}
vector(X, ^Size) :: G
vector(X, ^Size, ^NewVector) :: B
new_vector(^Vector, Size) :: B
vector_element(Vector, Position, ^Element) :: G
vector_element(Vector, Position, ^Element, ^NewVector) :: B
set_vector_element(Vector, Position, ^OldElem, NewElem, ^NewVect) :: B

\end{verbatim}
\item Strings
\begin{verbatim}
string(X, ^Size, ^ElementSize) :: G
string(X, ^Size, ^ElementSize, ^NewString) :: B
new_string(^String, Size, ElementSize) :: B
string_element(String, Position, ^Element) :: G
string_element(String, Position, ^Element, ^NewString) :: B
set_string_element(String, Position, NewElement, ^NewString) :: B
substring(String, Position, Length, ^SubString, ^NewString) :: B
set_substring(String, Position, SubString, ^NewString) :: B
append_string(String1, String2, ^NewString) :: B

\end{verbatim}
\item Atoms
\begin{verbatim}
intern_atom(^Atom, String) :: B
new_atom(^Atom) :: B
atom_name(Atom, ^String) :: B
atom_number(Atom, ^Number) :: B

\end{verbatim}
\item Code
\begin{verbatim}
predicate_to_code(Mod, Pred, Arity, ^Code) :: B
code_to_predicate(Code, ^Mod, ^Pred, ^Arity, ^Info) :: B

\end{verbatim}
\item Stream support
\begin{verbatim}
merge(In, ^Out) :: B

\end{verbatim}
\item Second order function
\begin{verbatim}
apply(Code, Args) :: B

\end{verbatim}
\item Special I/O
\begin{verbatim}
read_console(^Integer) :: G
display_console(X) :: G
put_console(X) :: G

\end{verbatim}
\item Others
\begin{verbatim}
raise(Tag, Type, Info) :: B
consume_resource(Reduction) :: B
hash(X, ^Value, ^NewX) :: B
current_processor(^ProcessorNumber, ^X, ^Y) :: B
current_priority(^CurrentPriority, ^ShoenMin, ^ShoenMax) :: B

\end{verbatim}
\end{enumerate}

\newpage
\Appendix{Exception codes}\index{Exception Code}
\AppendixLabel{sec-exception}
\vspace{3ex}
\begin{itemize}

\item Illegal Input Type :: 0\\
An illegal data type appeared as an input argument of some built-in predicate.

\item Range Overflow :: 1\\
The range of some input argument of a built-in predicate(excluding arithmetic
operation) is incorrect.

\item Integer Overflow :: 3\\
As a result of integer operation, overflow occurs.
Zero division is included here.

\item Floating Point Error :: 5\\
The range of some input argument of a floating point operation is incorrect.
Or as a result of floating point operation, overflow occurs.

\item Illegal Merger Input :: 8\\
Data different from \verb|[]| or list or vector has been input through merger.

\item Reduction Failure :: 9\\
No candidate clause are selected for goal execution.

\item Unification Failure :: 10\\
Body unification has failed.

\item Raised :: 12\\
A built-in predicate \verb|raise/3| is executed.

\item Incorrect Priority :: 16\\
Assigned priority is outside of the Sho-en bounds.

\item Module Not Found :: 17\\
An unloaded module has been referred to.

\item Predicate Not Found :: 18\\
A given predicate does not appear in the required module.

\item Deadlock :: 11\\
Deadlock is detected in the Sho-en.
\end{itemize}
\vspace{5ex}

\newpage
\Appendix{Reserved Sho-en tags}
\AppendixLabel{sec-Shoen-tag}
\index{Exception Tag}\index{Sho-en!Tag}\index{Sho-en Tag}

In current version, the following bits of Sho-en tag are reserved for the
KL1 language and for Micro PIMOS usage.
\begin{figure}[ht]
\begin{center}
\setlength{\unitlength}{0.9mm}
\begin{picture}(135,15)(0,0)
\thicklines
\put(0,0){\framebox(135,10){}}
\put(45,0){\line(0,1){10}}
\put(75,0){\line(0,1){10}}
\put(0,13){\makebox(0,0)[l]{31}}
\put(45,13){\makebox(0,0)[l]{19}}
\put(75,13){\makebox(0,0)[l]{15}}
\put(135,13){\makebox(0,0)[r]{0}}
\put(22.5,12.5){\makebox(0,0){(12 bits)}}
\put(60,12.5){\makebox(0,0){(4 bits)}}
\put(105,12.5){\makebox(0,0){(16 bits)}}
\put(22.5,5){\makebox(0,0){language(KL1)}}
\put(60,5){\makebox(0,0){Micro PIMOS}}
\put(105,5){\makebox(0,0){avaible to the user}}
\end{picture}
\caption{Sho-en exception tag}
\end{center}
\end{figure}
\vspace{3ex}
\begin{itemize}
\item bit 16 --- I/O stream required from parent Sho-en.
\item bit 17 --- Error message sent to parent Sho-en.
\item bit 18 --- Message output on Micro PIMOS shell window.
\item bit 19 --- Not used.
\item bit 20 --- Deadlock detected.
\item bit 21 --- Illegal input type.
\item bit 22 --- Range overflow.
\item bit 23 --- Integer overflow.
\item bit 24 --- Floating point error.
\item bit 25 --- Not used.
\item bit 26 --- Illegal merger input.
\item bit 28 --- Unification failure.
\item bit 29 --- Incorrect priority.
\item bit 30 --- Module not found.
\item bit 31 --- Exception while calling a built-in predicate.
\end{itemize}

\newpage
\Appendix{GNU-Emacs library}
\AppendixLabel{sec-emacs}

There are two library modes in PDSS. The first one is the kl1-mode, used to
edit programs, and the second is PDSS-mode, used to run PDSS. Commands
defined in each mode are shown below :\index{kl1-mode}\index{PDSS-mode}
\index{Compile}
\begin{enumerate}
\item kl1-mode
\begin{enumerate}
\begin{itemize}

\EmacsCommand{ctrl-C ctrl-C}\\
Compiles all the text in the buffer in which command has been executed, as if
this text was KL1 source code.

\EmacsCommand{ctrl-C ctrl-R}\\
Copies specified range of text in the buffer \verb|PDSS=COMPILER|.

\EmacsCommand{ctrl-C ctrl-D}\\
Compiles the contents of the buffer \verb|PDSS=COMPILER| as a KL1 program.
Then, looks for the assembler file(*.asm) which has the same name as the buffer
and updates parts of this file which have changed.
Eventually, generates save file.\\
This command is used with {\bf ctrl-C ctrl-R} to recompile updated parts
only. Assembly files should therefore not be deleted.

\EmacsCommand{meta-X pdss-kl1cmp-switch-macro-mode}
\EmacsCommand{meta-X pdss-kl1cmp-switch-indexing-mode}
\EmacsCommand{meta-X pdss-kl1cmp-switch-debug-mode}
\EmacsCommand{meta-X pdss-kl1cmp-switch-system-mode}\\
Changes options of the Prolog version compiler. Commands with no argument
work as toggle switches, while arguments 1/0 corresponds to on/off. Detailed
meaning and initial values of these options are described in \ref{sec-pdsscmp}.
Above commands correspond to \verb|e|, \verb|i|, \verb|d|
and \verb|s| options, resp.\\
When using KL1 version compiler, these commands are not available.

\Caution Information and prompt are output in buffer \verb|PDSS=COMPILE|,
but basically, user does not need to type anything in this buffer.

\EmacsCommand{ctrl-C ctrl-F}\\
Displays the manual of built-in predicates.

\end{itemize}
\end{enumerate}
\item PDSS-mode
\begin{enumerate}
\item Window/buffer operations
\begin{itemize}

\EmacsCommand{meta-.}\\
Displays a candidate string, beginning with \verb|?- | and matches the previous
string which has been entered.
This is used to repeat the last interpreted command.

\EmacsCommand{ctrl-C ctrl-Y}\\
Redisplays previous input.

\EmacsCommand{ctrl-C k}\\
Deletes all text in the buffer.

\EmacsCommand{ctrl-C ctrl-K}\\
Deletes all text in all PDSS-mode buffers.

\EmacsCommand{ctrl-C ctrl-B}\\
Displays buffer menu of PDSS-mode buffer.

\EmacsCommand{ctrl-C m}\\
Looks for the pattern module-name:predicate-name from the beginning of current
line, and start insert at its current position. This is convenient to set
variable name when setting variable monitor in the tracer.

\EmacsCommand{ctrl-C ctrl-F}\\
Displays built-in predicate manual.

\EmacsCommand{ctrl-C f}\\
Displays command manual for command interpreter.

\EmacsCommand{ctrl-X k}\\
Kills buffer, but gives a warning if PDSS is running.

\end{itemize}
\item KL1 program control
\begin{itemize}

\EmacsCommand{ctrl-C ctrl-Z}\\
Inserts 1 into the attention stream of the KL1 window process that corresponds
to current buffer. This is treated as a task stop request by Micro PIMOS.

\EmacsCommand{ctrl-C ctrl-T}\\
Puts 2 in the same buffer as above. This causes display of
statistic information from Micro PIMOS.

\end{itemize}
\item Emulator control
\begin{itemize}

\EmacsCommand{ctrl-C !}\\
Garbage collection request.

\EmacsCommand{ctrl-C @}\\
Stops PDSS system, but the buffers used as Micro PIMOS windows are left
untouched.

\EmacsCommand{ctrl-C ESC}\\
Restarts PDSS.

\end{itemize}
\end{enumerate}
\item Mode independent command
\begin{enumerate}
\begin{itemize}

\EmacsCommand{ctrl-C ctrl-P}\\
Displays next PDSS-mode buffer in current window. The PDSS buffer group is
managed as a circular list. So, if user repeats this command, all buffers are
displayed one by one.

\EmacsCommand{ctrl-C p}\\
This is almost the same as the previous command, but display occurs in the
other window.

\end{itemize}
\end{enumerate}
\end{enumerate}

\newpage
\Appendix{Using command procedures for compiling}
\AppendixLabel{sec-pdsscmp}
\index{Compile}\index{pdsscmp}\index{Compile!Command Procedures}

This is the description of the command procedure to compile a KL1 program,
used as a
UNIX command. It may be useful to compile it within a makefile. There are
two versions of this command : one for the KL1/KL1 compiler and the other
 for the
KL1/Prolog compiler. Basic usage rules are the same, but some available 
options are different.
\vspace{3ex}

\noindent\underline{\bf Command :}\vspace{2ex}\par
\hspace*{8em}{\bf pdsscmp\index{pdsscmp}  [ options ]  file names ...}
\vspace{3ex}

\noindent\underline{\bf Options :}\vspace{2ex}\par
\begin{center}
\begin{tabular}{l@{ :: }p{120mm}}
\verb|+i / -i| &
Indexing code is generated or not. Default is not to generate it. KL1/Prolog only.\\
\verb|+m / -m| &
Code for MRB-GC is generated or not. Default is to generate it.\\
\verb|+a / -a| &
Assemble is performed or not. Default is to perform it. When performed, an assembler file (xxx.asm) and
a save file (xxx.sav) are generated. Otherwise, only assembler file is
generated.\\
\verb|+s / -s| &
Compiles for Micro PIMOS or for user. Default is to compile for user.
System-mode private built-in predicates can be used in the first case. Built-in
predicates in this manual can be compiled with the user version. KL1/Prolog only. (All built-in predicates can be compiled in KL1/KL1.)\\
\verb|-o=PATH| &
Changes output directory to \verb|PATH|. Current working  directory
 is the default.
\end{tabular}
\end{center}
\vspace{3ex}

\noindent\underline{\bf File name :}\vspace{2ex}\par
\begin{center}
\begin{tabular}{l@{ :: }p{120mm}}
xxx.asm &
Assembles an assembler-file (xxx.asm) and creates a save file (xxx.sav).\\
xxx.kl1 &
Compiles a source file (xxx.kl1), makes assembler file and then assembles it
to make save file.\\
xxx &
same as xxx.kl1.\\
\end{tabular}
\end{center}
\vspace{3ex}
\noindent\underline{\bf Examples :}\vspace{2ex}\par
\begin{itemize}
\item To compile and assemble the two source files append.kl1 and queen.kl1,
and then to make append.asm, append.sav, queen.asm and queen.sav
in the current directory :
\begin{verbatim}
        pdsscmp  append.kl1 queen.kl1    or
        pdsscmp  append queen
\end{verbatim}

\item To compile and assemble append.kl1 and assemble queen.asm :
\begin{verbatim}
        pdsscmp  append.kl1 queen.asm
\end{verbatim}

\item To compile and assemble all .kl1 files in the directory \verb|source|
 and then to put assemble and save files in directory \verb|object|:
\begin{verbatim}
        pdsscmp  -o=object source/*.kl1
\end{verbatim}
\end{itemize}

\newpage
\Appendix{Sample program}
\AppendixLabel{sec-sample}
\begin{verbatim}

:- module sample.
:- public primes/2, primes/1.

primes(N, PL) :- true | gen(2, N, NL), sift(NL, PL).

primes(N) :- true | 
    gen(2, N, NL), sift(NL, PL), 
    window:create([show|Window], "sample"),
    outconv(PL, Window).

gen(Max, S):- true | gen(1, Max, S).
gen(N, Max, S) :- N =<  Max, M := N+1 | S=[N|S1], gen(M, Max, S1).
gen(N, Max, S) :- N > Max | S=[].

sift([P|L], S) :- true | S=[P|S1], filter(P, L, K), sift(K, S1).
sift([],    S) :- true | S=[].

filter(P, [Q|L], K) :- Q mod P=:=0 |           filter(P, L, K).
filter(P, [Q|L], K) :- Q mod P=\=0 | K=[Q|K1], filter(P, L, K1).
filter(P, [],    K) :- true        | K=[].

outconv([P|PL], W) :- true | W=[putt(P),nl|W1], outconv(PL, W1).
outconv([], W) :- true | W=[putb("END"),getc(_)].


| ?- sample:primes(10,PL).

yes.
| ?- sample:primes(10,PL)|PL.
PL = [2,3,5,7]

yes.
| ?- sample:primes(10).
2
3
5
7
END

yes.
| ?- halt.

\end{verbatim}

\newpage
\Appendix{What to do if a bug is found out...}
\begin{enumerate}
\item When you find system bugs, please inform the PDSS development group.
E-mail address is :
\vspace{1ex}\\
\hspace*{8em}{\bf pdss@icot21.icot.junet}
\vspace{1ex}\\
In your mail, include the following information :
\begin{enumerate}
\item PDSS (emulator, Micro PIMOS) version number.
\item Compiler version number.
\item The program in which you found the bug.
\item How to start it, and what happens.
\item Execution log and queer points.
\end{enumerate}

\item If it is a bug of a program of your own, go at the least 
through the following list :
\begin{enumerate}

\item Have you done varchk?

\item In case of deadlock, if there are the following goals in the incriminated
part, you may have forgotten to close command stream to file or window, or
you may have requested the output of undefined variables. Check your code.
\begin{verbatim}
        mpimos_file:xxxxxx( ... )     or
        mpimos_window:xxxxxxx( ... )
        merge( ... ) in mpimos_file:xxxxx/x
        merge( ... ) in mpimos_window:xxxxx/x
\end{verbatim}
\end{enumerate}
\end{enumerate}

\NewpageDouble

\printindex

\end{document}
