% $Id: intro.tex,v 1.6 1993/01/19 14:29:04 cim Exp $
\documentstyle{article}
\begin{document}
\title{\Huge\bf \shortstack{~\\~\\
User's and \\~\\~\\ Installation Guide \\ ~\\ ~\\ Portable Simula System \\~\\~\\ based on C }}
\author{\linethickness{.5mm}{\fbox{\linethickness{.5mm}\shortstack{~ \\ \Large\sf ~~~\\ \Large\sf by\\ 
\Large\sf Sverre Johansen \\ \Large\sf Stein Krogdahl \\ \Large\sf and Terje Mj\o{}s \\ \Large\sf Department of informatics \\ \Large\sf University of Oslo \\ ~}}}}
\date{January 1991}
\maketitle
\section{Introduction}

Cim is a compiler for the programming language Simula,
as approved (not yet) by the SIMULA Standards Group (except
unspecified parameters to formal or virtual procedures).
It offers a class concept, separate compilation with 
full type checking, interface to external C-routines,
an application package for process simulation
and a coroutine concept. Reference is the book:
Kirkerud, Object-oriented programming with SIMULA,
Addison Wesley 1989.

Cim is a Simula compiler whose portability is based on
the C programming language. The compiler and the
run-time system is written in C, and the compiler
produces C-code, that is passed to a C-compiler for
further processing towards machine code.

\section{Installation}

The system is distributed as a compressed tar file.
Take the following actions to install the software:

\begin{enumerate}
\item	Uncompress the tar file with the tar command:
	\begin{verbatim}
	%uncompress cim.tar.Z
	\end{verbatim}
\item	Extract the file with the tar command:
	\begin{verbatim}
	%tar xf cim.tar
	\end{verbatim}
\item  	List the files with the ls command to verify that you 
	have gotten the correct files:
	\begin{verbatim}
	%ls
	Makefile        cim.1           cim.h           cim.tar
	cimtest.sim	cim		libcim.a
	\end{verbatim}
\item	Read the make file, and create the needed directories 
	to run make install.
\item	Install the system by entering super user and make install:
	\begin{verbatim}
	%su
	Password:
	%make install
	%exit
	\end{verbatim}
\item	A simple test of the installation can be made by make test:
	\begin{verbatim}
	%make test
	cim -r test
	Compiling: test.sim
	cc -w -c test.c
	cc -o testinst test.o -lcim -lm
	Executing testinst:
	Installation: No errors found
	\end{verbatim}
\end{enumerate}

\section{A simple example}

We show in this section a simple example of a SIMULA program 
and how to compile and run it.

Create a SIMULA program with a text editor, and give it a name with
extension ``sim''. In this example we name it doesit.sim:

\begin{verbatim}
begin
    Outtext("Simula does it in C");
    Outimage;
end
\end{verbatim}

You can now compile the program with the cim command:

\begin{verbatim}
%cim doesit
Compiling: doesit.sim
cc -w -c doesit.c 
cc -o doesit doesit.o -lcim -lm
%
\end{verbatim}

The compiler will produce C code that is further processed towards 
machine code with a standard C compiler. 
All produced files have the same name as the input file,
but with different extensions.
The compiled and linked program can be invoked by entering:

\begin{verbatim}
%doesit
Simula does it in C
%
\end{verbatim}
 
\section{Compiling}

Cim is a Simula compiler that first compiles the source code into C.
The C code
will then be compiled with cc, and linked with other modules.

The Cim command
will accept one Simula program and other none Simula modules.
The specified Simula program will be compiled and linked with the 
modules. If a main Simula program is compiled, it will automatic
be linked with the necessary Simula modules. If a separate Class or
Procedure is compiled, then the linking will be suppressed.

The diagnostics produced by the Simula compiler are intended to
be self-explanatory.

The following options are accepted by the cim command:

\begin{itemize}
\item 	-c\\
	Suppress linking of the complete program.
\item	-C\\
	Only link the specified files.
\item	-cc\\
	The following argument is the name of the C-compiler.
\item	-D{\it name}\\
	Define a symbol {\it name}.
\item	-E\\
	Run only the preprocessor and output 
	the result to standard output.
\item	-g\\
	Make the C compiler produce debugging information.
	This option is useful for debugging the generated code.
\item	-gcc\\
	Invoke the Gnu Project C compiler instead of the standard C compiler.
	This option can be used if the standard C compiler 
	don't generate correct code.
\item	-I {\it dir}\\
	Use the Simula include file located in directory {\it dir} 
	instead of the standard directory.
	This information may also be given by setting the 
	environment variable CIMINCLUDEDIR.
\item	-l\\
	Omit line number information in the  compiled  program.
	This  will  make the program smaller and faster.
\item	-l{\it library}\\
	Link with object library {\it library}.
	This option is parsed to the link-command.
\item	-L{\it dir}\\
	Use the Simula library located in directory {\it dir} instead of the
	standard directory. This information may also
	be given by setting the environment variable CIMLIBDIR.
\item	-m\\
	The memory pool size may be set at runtime 
	by an option -m{\it n}.
\item	-m{\it n}\\
	Set the initial memory pool size to {\it n} mega bytes.
\item	-M{\it n}\\
	Set the maximal memory pool size to {\it n} mega bytes.
\item	-o\\
	The following argument is the name of the output 
	executable file.
\item	-oc\\
	The following argument will be parsed to the CC-command.
\item	-ol\\
	The following argument will be parsed to the link-command.
\item	-q\\
	Run the compiler in quiet mode.
\item	-r\\
	Run the program after compilation.
\item	-R\\
	Recompile the module using the same timestamp.
\item	-s\\
	Only C-compile and link the specified files.
\item	-S\\
	Run the source file through Simula-compiler, only.
\item   -t\\
	Do not remove temporary files. 
	If a main program is compiled with option -r,
	then the executable file will be removed 
	unless this option or option -T is specified.
\item   -T\\
	Do not remove the executable file.
\item	-U{\it name}\\
	Remove any initial definition of the symbol {\it name}
	(Inverse of the -D option).
\item	-v\\
	Run the compiler in verbose mode.
\item	-w\\
	Do not print warnings.
\end{itemize}

\subsection{Arguments}

The following arguments are accepted by the Cim command:

\begin{itemize}
\item	{\it file}.a\\
	Library of object files and attribute files.
	Include this simula library when compiling and linking.
	The simula library is created with ar(1V) and ranlib(1).
\item	{\it file}.o\\
	Object file of other none Simula modules.
\item	{\it file}.sim\\
	Simula source file. A file name without an extension are assumed
	to be shorthand notation for the corresponding Simula file.
\end{itemize}


\section{Implementation Aspects}

\subsection{Language restrictions}

A formal or virtual procedure must be specified with respect to its type,
and type, kind and transmission mode of its parameters.

\subsection{Allowed implementation restrictions}

\begin{itemize}
\item	The type short integer and long real 
	is implemented as integer and real.
\item	The standard access mode SHARED for files is not implemented.
\item	The only and default byte size of access mode BYTESIZE is 8.
\end{itemize}

\subsection{Implementation dependent characteristics}

\begin{itemize}
\item	Trailing blanks of image are not transferred to the external file on
	outfile.outimage excepts it's a direct file.
\item	A parameter to printfile.spacing with value zero gives the
	standard effect of overprint.
\item	The procedures lock and unlock are not implemented.
\item	All open external files are closed when a program is terminated.
\item	The following directive lines is supported:
	\begin{itemize}
	\item	{\tt \%} {\it whitespace} ...\\
		A directive line with a whitespace 
		is treated as a comment line.
	\item	{\tt \%nocomment} ...\\
		The rest of the line is treated as ordinary source text.
		Some other simula implementations will ignore this line,
		and give a warning message. But this can be useful as the 
		following example shows. In this implementation formal
		procedures must be specified, 
		but that should not be done in standard simula.
		This will work both on LSH 
		(Simula implementation from Lund Software House AB, Sweden)
		and Cim:

\begin{verbatim}
PROCEDURE P(i1,P2);INTEGER i1;
%nocomment PROCEDURE P2 IS 
              INTEGER PROCEDURE P2
%nocomment      (i,j);INTEGER i,j;
           ;
\end{verbatim}

	\item	{\tt \%comment}\\
		Will cause the compiler to strip all lines until the
		corresponding \%endcomment is reached. This directive
		may be nested.
	\item	{\tt \%eof}\\
		Will cause the compiler to react as if the end of the 
		source file was reached. Include files that is placed in
		a archive must be preceded with this directive line.
	\item	{\tt \%casesensitive} ON/OFF\\
		The case sensitivity of identifiers and keywords is turned
		ON or OFF. Default value is OFF.
	\item	{\tt \%define} {\it name}\\
		Define a name. 
		Names such as 
		aix,
		amigados,
%		aux,
		convex, cray
%		hp9000s300, hp9000s500, hp9000s700, 
		hp9000s800,
		hppa, hpux, i286, i386, i486, 
		linux,
		mach, 
		minix,
%		mpw,
		msdos, 
		mc68000, mc68010, 
		mc68020, mc68030, mc68040, 
		m88000, mips, next,
		ns32000,
%		pyr, 
		sony, sparc, sunos, 
		ultrix, unicos, unix, vax and vms
		are defined dependent of the system.
		The name cim is defined for implementations that 
		is generating C code.
	\item	{\tt \%error} ...\\
		Will cause the compiler to believe that it has found an error
		in the source text. The message that is preceded on the line
		is printed as an error message.
	\item	{\tt \%ifdef} {\it name}\\
		If {\it name} is not defined then the compiler will strip 
		all lines until the corresponding {\tt \%else} or 
		{\tt \%endif} is reached.
		If {\it name} is not defined then the compiler will strip
		all lines between the optional {\tt \%else} and {\tt \%endif}.
	\item	{\tt \%include} {\it filename}\\
		Will cause the compiler to include the indicated file in 
		place of the INCLUDE directive line. This directive may be
		nested, but only to a level of 10.
	\item	{\tt \%nameasvar} ON/OFF\\
		If it is turned ON, then transmission mode for name is 
		implemented as reference. 
		This will produce more efficient code. Default value is OFF.
	\item	{\tt \%staticblock} ON/OFF\\
		If it is turned on, then data objects will be allocated
		static instead of dynamic,
		and the compiler may generate more efficient code.
		This option should be used with care and
		should not be used for blocks which may have
		more than one active data object at a given time.
		The option may not be used for classes that are given
		as prefix or virtual procedures or procedures that
		are parameter to other procedures.
		It may not be used for external
		classes or procedures.
	\item	{\tt \%stripsideeffects} ON/OFF\\
		If it is turned ON, then the compiler can generate more
		efficient code, 
		but not necessary correct code due to evaluation
		order for expressions. Default value is OFF.
	\item	{\tt \%undefine} {\it name}\\
		Undefine a name. If the name is not defined the directive line
		has no effect.
%	\item	{\tt \%warning} ...\\
%		The message that is preceded on the line
%		is printed as a warning message.
	\end{itemize}
\item	C is the only language supported for none-Simula external procedures.
	``Kind'' is interpreted as ``C'', 
	and the {\it external-item} is case sensitive.
	External C procedures must be specified in the following way:	
	
	{\tt External C procedure} {\it external-item} 
	{\tt is} {\it type} {\tt procedure} {\it procedure-identifier} 
	{\it parameter/mode/specification-part} {\tt ; ;}

	The rules for external C procedures are:
	
	\begin{itemize}
	\item	Avoid global symbols prefixed with ``\_\_'', it may lead to
		conflicts with system names in Cim.
	\item	The procedure may have any type, except {\it ref}.
		If the type is {\it text}, then the null terminated string
		returned from C is converted to a Simula text object.
	\item	Parameters may not be a 
		Simula-procedure, switch or label.
	\item	Parameters transmitted by value are always copied.
		Text or arrays are allocated by malloc, 
		and are not deallocated by Cim.
		It's the C-programs responsibility to dealloc the space.
	\item	Parameters transmitted by reference or name are transmitted
		to C as pointer to. Array or text are transmitted to C
		by the location of the first element.
	\item	External C procedures with variable number of parameters
		can be specified by use of ``...'' 
		in the end of the parameter list. Printf and scanf can
		be specified as follows:
\begin{verbatim}
EXTERNAL C PROCEDURE printf IS 
   INTEGER PROCEDURE printf(t,...);TEXT t;;
EXTERNAL C PROCEDURE scanf IS
   INTEGER PROCEDURE scanf(t,...);NAME ...;TEXT t;;
\end{verbatim}
	\end{itemize}
\end{itemize}

\subsection{Implementation defined characteristics}

\begin{itemize}
\item	The internal character are the same as the standard character set.
\item	Inlength and outlength are equal to 80.
\item	SYSIN, SYSOUT and SYSERR is connected to standard input, 
	standard output and standard error.
	If they are closed and reopened they are connected to 
	{\tt /dev/tty} under UNIX, AIX and MINIX and 
	{\tt sys\$input} and {\tt sys\$output} under VMS.
\item	The relative value ranges of real are as double in C and
	ranges of integer are as long.
\item	Conversion from an integer type to a real type are exact except
	for implementations where integer have better precision than real
	(which is the case for the cray implementation.)
\item	The effect is not defined if the range of a numeric item in a de-editing
	procedure exceeds the value range of the procedure result.
\item	The exponent from ``putreal'' has 5 characters except
	for the cray implementation where it may be 6 characters.
\item	A text frame has a maximum length of about 64K characters.
\item	The return values of ``char'' and ``rank'' are as given by the standard
	character set.
\item	The exact definitions of the standard mathematical functions are
	system specific.
\item	The association between a file object and an external file 
	are standard procedures based on C's FILE.
	The object is connected to the external file when open is called.
\item	Several file objects may represent the same external file,
	but the effect is not defined if some of them is opened for writing.
\item	A minimum of checks are performed at ``locate''.
\item	The default value to LINES\_PER\_PAGE is MAXINT.
\item	The ``basic random drawing'' is implemented as suggested in the standard.
\item 	Two decimals are used for the field for seconds of the function
	``datetime''.
\item	Evaluation of arithmetic expressions are based on C,
	but the Simula expression are by default divided up in several expressions,
	to guarantee correct evaluation order.
\end{itemize}

\subsection{Capacity limitations}

The compiler have the following logical limitations:

\begin{itemize}
\item	The maximal number of Simula-libraries that the compiler can search
	is 100 libraries.
\item	Length of a token in the input stream is restricted to 
	about 1000 characters.
\item	The nesting of compiler directives is limited to 100.
\item	The level of nesting of include files must not exceed 10.
\item	The parser is written i YACC and the parser stack have a size
	equal 1500 elements.
\item	Block nesting level is limited to 100.
\item	The compiler builds an expression tree for each Simula-expression,
	and one tree is limited to 1000 nodes.
\item	The code generator have a stack of labels with 1000 elements.
\item	Temporary expressions may not consist of more than 100 value-type,
	100 text, or 100 ref-type elements.
\item	The nesting of temporary expressions may not be deeper than
	100 levels.
\item	The maximum number of dimensions for arrays is 100.
\item	Text objects may not contain more than about 64K characters.
\item	Some other limitations that is based on the underlying hardware or
	the operating system, and that is not checked by the compiler.
\end{itemize}

\subsection{Extension to the environment}
The following procedures is added to the Simula environment
and may be called directly from Simula:
\begin{itemize}
\item	{\tt PROCEDURE Gbc;...;}\\
	The garbage collector is called when the dynamic 
	storage exceeds an implementation dependent limit. 
	The garbage collector traverse and moves all the accessible objects,
	and leaves the free space as one area initialized to zero.
	The garbage collector may be called explicitly
	through the procedure Gbc.
\item	{\tt INTEGER PROCEDURE Argc;...;}\\
	Returns the number of command-line arguments
	that the program was invoked with.
\item	{\tt INTEGER PROCEDURE Argv;...;}\\
	Returns a pointer to an array of character strings 
	(in C fashion) that contains the arguments.
\item	{\tt PROCEDURE Dump(t);TEXT t;...;}\\
	Dump the state of the Simula-program to file.
	Before a call on Dump all files except SYSIN,
	SYSOUT and SYSERR should be closed.
\item	{\tt PROCEDURE UnDump(t);TEXT t;...;}\\
	Read a previously stored state from file 
	and start the program in that state.
	To get these procedures to work,
	they should be compiled into the same program.
	The program may not be re-compiled 
	between a call on Dump and UnDump. 
\item	{|tt REF(PrintFile) PROCEDURE SysErr;...;}\\
	Returns the file object associated with standard error.
\end{itemize} 

\section{Error report}

Errors should be reported to cim-bug@ifi.uio.no.

\section{Authors}

\begin{itemize}
\item	Terje M\o{}s, Hydro Data, Oslo.

\item	Sverre Johansen, Department of Informatics, University of Oslo.

\item	Stein Krogdahl, Department of Informatics, University of Oslo.
\end{itemize}
\end{document}
