DOORS
		Dynamic Object Oriented Runtime System
		A short description
		(C) moove 1994-2004

		Last Update: 2/25/2004, LB


DOORS is available for application server - e.g. moove online Community Server
and for clients, e.g. Roomancer Browser Edition.

The client version has restricted functionality for security reasons:
File and registry operations are only possible in application context ("Sandbox").
Some functions are totally disabled (please see "The DOORS Editor").


DOORS organizes entities.
Sources of these entities are stored in a repository (the "Akasha" storage system).
Entities are compilable atomic units:

1) Functions

	Syntax:
	FUNCTION <function name> ( [ <arguments> ] )

	Functions can be executed synchronously or asynchronously (as threads).

	Examples:
	FUNCTION HelloWorld
	MessageBox("Hello World")

	FUNCTION Add(a, b)
	RETURN a + b			// optional return value



2) Classes

	Syntax:
	CLASS [ BYNAME ] <class name> [ PARENT <parent class> ]
	[ EXPORTED ]
	[ <exported member names> ]

	[ PROTECTED ]
	[ <protected member names> ]

	[ EXPORTED <exported member names> ]
	[ PROTECTED <protected member names> ]

	Classes provide a per instance scope for data and executable entities.
	Every instance of a class contains all of these data called MEMBER
	(see below).
	The BYNAME keyword provides instance creation by name
	(e.g. newest version after change of the class).
	The PARENT keyword provides the scope of an existing class.

	Example 1:
	CLASS SoulActor	// Soul of any actor

	m_pActor		// pointer to C++ actor

	EXPORTED
	m_nCreationTime
	m_nSpecificWeight

	PROTECTED x, y, z


	Example 2:
	CLASS SoulBeing PARENT SoulActor

	m_nBodyTemperature


	Example 3:
	CLASS SoulHuman PARENT SoulBeing

	EXPORTED m_bSex



3) Methods

	Syntax:
	ON <class name> <method name> ( [ <arguments> ] )

	Methods are functions in the scope of an instance, e.g. its class.

	Example 1:
	ON SoulActor Init(pActor)

	m_pActor := pActor

	Example 2:
	ON SoulBeing Init(pActor)

	m_pActor := pActor			// MEMBER declared in PARENT class
	RETURN m_nBodyTemperature


4) Templates

	Syntax:
	TEMPLATE <template name>
		[ PARENT <parent template> [ SCALE <x-, y-, z-factor> ] ]
	[
		PART <part name>
		[ DIM <x, y, z> ]
		[ ORIGIN <x, y, z> ]
		[ NONBBOX ]
	]
	[
		JOINT <joint name>
		FROM <part name> <x, y, z>
		[
		AXES <flexAxis, twistAxis, pivotAxis>
			[ RANGE <MinFlexRot, MaxFlexRot  MinTwistRot, MaxTwistRot  MinPivotRot, MaxPivotRot> ]
		]
		TO <part name> <x, y, z>
	]

	Templates describe the morphology of an actor.
	The PARENT keyword provides the morphology of an existing actor.
	The provided morphology can be scaled in x, y and z direction.

	Example 1:
	TEMPLATE Box

	PART HEAD				// first declared PART has to be HEAD
		DIM 100, 100, 100		// dimension
						// default ORIGIN of a part is half dimension
	JOINT Neck
		FROM ORIGIN 0, 0, 0	// ORIGIN is the predefined root and is used for the location of an actor
						// default AXES are X, Y, Z, e.g. flexAxis is X etc.
						// default RANGE is 0,0 0,0 0,0 (degree), e.g. no rotation
		TO HEAD 50, 50, 50


	Example 2:
	TEMPLATE "Little Sam" PARENT "Big Sam" SCALE 0.5, 0.4, 0.5
		// quotes needed to embed e.g. spaces

	PART Hips
		DIM 29.8 33.8 24.4
		ORIGIN 14.90 7.49 10.63

	JOINT LeftHip
		FROM Hips 9.91 19.3 2
		RANGE 330,150 310,50 345,110
		TO LeftThigh 0 0 0	// LeftThigh known from PARENT

	JOINT RightHip
		FROM Hips -9.91 19.3 2
		AXES X -Y -Z		// negative axes reverse rotation direction
		RANGE 330,150 310,50 345,110
		TO RightThigh 0 0 0

	JOINT ORIGINHips
		FROM ORIGIN 0 0 0
		AXES -X -Y  0.1, 0.2, 1	// special axis for pivot
		RANGE 0,360 0,360 0,360
		TO Hips 0 0 0


5) Postures

	Syntax:
	POSTURE <posture name>
		<flexRot, twistRot, pivotRot> <joint name>
		<muscle name> <contraction> [<part name>]
	
	Postures describe axes rotations (in degree) for a list of joints.
	The joints are identified by their names.
	So the posture can be applied to any actor having these joints declared in its template.
	Postures are normally generated by the Posture Wizard.

	Example:
	POSTURE 	"BackFlip 3"	// quotes needed to embed e.g. spaces
	  0 348   0 Neck
 	163   0   0 HipsChest
	146   0   0 ORIGINHips
	339   0  11 LeftHip
	339   0  11 RightHip		// rotation for RightHip has same values as 
						for LeftHip, because of negative axes
						(see above)



The DOORS Editor
================

The Entity sources are editable by DOORS entity editors.
An unlimited number of editors can be opened at a time.

The Test mode has to be set.
Then you can activate the menu entry "Dev\New Source Editor".
Or type !Ed() at the command line.

The "Chk" button lets you compile the entity to check for errors.
Additionally you get some information from the compiler:
1) For the executable entities (Function, Method) you get
	a) Security flags as combination of
		N	// Non threadable
		Q	// Query	(only, if persistent)
		S	// Set	(only, if persistent)
		R	// Read
		W	// Write
		E	// Execute 	(late bound)
		U	// Unknown because of EarlyFunc to low
		D	// Disabled if IsCB()
	   You can find these flags in the DOORS API Reference, too.
	b) Source size
	c) Code size
	d) Number of string constants
	e) Total string constant size
	f) Number of LOCALs
	g) Number of errors


2) Classes:
	a) Source size
	b) Number of MEMBERs

3) Templates:
	a) Source size
	b) Number of PARTs (= number of JOINTs)

4) Postures:
	a) Source size
	b) Data size
	c) Number of joint entries
	d) Number of "empty" joint entries (all three rotations are 0)
	   "empty" entries are candidates for removal...

The "Run" button lets you:
1) Start a Function asynchronously (as thread).
2) Apply a Posture to your actor and get following information:
	a) Height with initial posture
	b) Size vector
	c) ORIGIN height
	d) Y rotation difference between body and view
	e) X rotation of view
	f) Distance vector left - right foot (if available)
3) Change the Template of your actor

The "Call" button lets you:
1) Start a Function synchronously (in MainThread) and get its result.
2) Start a Method of for your Actor Soul synchronously (in MainThread) and get its result.
   Example: Method ActorMooveAround() of Class SoulActor

You could use any other plain ASCII editor to write your entities.
Text files containing DOORS entities have normally the extension ".Uni" (Universal Syntax).
Lines starting with "----" are ignored on importing,
so you could use this feature e.g. to visually separate your entities
or to have "internal" comments.
Lines starting with "----#" may contain importer commands:
	examples:		meaning:
	----#VC		V:Version C:Community Browser ("Roomancer") only
	----#VAR		V:Version A:Appserver R:Roomancer
	----#E.?'Hello'	E:Execution on import
	----#EImportSource('Test.UNI')


There is an interface to external file editors (multi entity) like Multi-Edit and our editor UniEdit (in CD path Goodies):
You can import, compile and execute from the external editor.
Please see ACTION ProvideEntityComment to get info about system functions for an external editor.
In the CD path SDK\EdSupport\Macro\ you can find editor macros and related documentations.
Related ProfileStrings of the "Roomancer" section are (WIN.INI):
	"CurrentHWND"		// for external SendMessage()
	"EvalIn"			// input for evaluation
	"EvalOut"			// output
	"CurrentWord"		// input for systemfunction documentation
	"CurrentComment"		// output

Related messages for external editors are:
	UM_EVAL		(WM_USER + 141)
		execute "EvalIn". If WPARAM, run it as thread, else call it in sync and store result into "EvalOut"
	UM_PROCESS_UNI	(WM_USER + 139)
		imports file. WPARAM is global atom of file name. If LPARAM, compile all.
	UM_GET_COMMENT	(WM_USER + 140)
		ACTION ProvideEntityComment is called


Another way to start Functions is to start your chat lines with "!":
(The registry key "Settings\ShowMenu" has to be set to "1".)
Examples:
!CreateFunctionDocus()		// creates the file "FunctionDocus.TXT", which contains an actual documentation for all SystemFunctions
!CreateFixedSymbolList()	// creates the file "FixedSymbols.TXT", which contains a list of all actual FixedSymbols.
!CreateDOORSHTM()			// creates the file "DOORS.HTM"


If a function shall be automatically executed at member login, use
RegisterSetUserAction(#<FunctionName>) to register and
UnRegisterSetUserAction(#<FunctionName>) to unregister


The DOORS Compiler
==================
Several instances of the DOORS Compiler can run at a time (e.g. in different threads).
This behaviour is necessary for the compile on demand mechanism. This gives you both optimal compile and runtime speed. And for a real "virtual reality" application it is very important to allow code import and creation at runtime.
This allows you very efficient development cycles, too.
Entities can even be recompiled while Roomancer is running.
There is additionally a mechanism to add or replace system functions at runtime (see below).
Typically millions of source lines (if available <g>) are compiled in a minute.

In case of a compilation error a DOORS editor pops up with the source of the entity.
The related code is selected. Information about the error and a short documentation
for a related system function is given.
The same mechanism works at runtime.
Errors are written to the file "RMError.Log". Some error messages may be sent to the Log window.

Compiler switches can influence the Compiler behaviour.
The default settings are stored in registry. The related entry can be modified
by the menu entry "Dev\Debug Monitor Control".

Inside an entity the behaviour can be changed temporary by the PRAGMA keyword:
example:
PRAGMA EARLYFUNC 2

List of possible PRAGMAs:

EARLYFUNC 0 / 1 / 2	// 0: called entities may not exist at compile time
				//   They may be searched and compiled on demand at runtime
				// 1: calls to entities check for existence
				//    The entities may be compiled on demand at runtime
				// 2: called entities are searched and compiled at compile time
FOLDFUNC FALSE / TRUE	// TRUE lets system functions be folded at compile time
				// example: Space(5) will be folded to "     "
FOLDCONST FALSE / TRUE	// TRUE lets constant expressions be folded at compile time
				// example: 1 | 3 | 4  will be folded to 7 at compile time
STRICT FALSE / TRUE	// FALSE assumes a LOCAL on an assignment to an undeclared variable
				// TRUE doesn't allow undeclared variables
QUIET FALSE / TRUE	// FALSE doesn't inform the user on compiler errors
				// and so doesn't wait for MessageBoxes
WARNING 0 - 5		// sets warning level. Higher means stricter.
SCODE FALSE / TRUE	// TRUE means optimizer ON for Code generation
STRINGSET FALSE / TRUE	// FALSE means following strings are not related to StringSet
QOUT FALSE / TRUE		// TRUE means, "?" is not only translated to Out
				// but provide also the code line (quote output)
				// example:
				// ? 1 + 2	gets	>3 //1 + 2;
TRACEASSIGN FALSE / TRUE	// TRUE triggers a call to
					// FUNCTION TraceResult(xValue, symRoutine)
					// for every result of Function / Method runtime call
TRACERESULT FALSE / TRUE	// TRUE triggers a call to
					// FUNCTION TraceAssign(xValue, symVar, symClass)
					// for every assignment at runtime
TRACE FALSE / TRUE		// set all TRACE pragmas (ASSIGN + RESULT)
ASSERTFUNC [Func]   		// default assertion function "Assert()" can be overridden
REFRESH FALSE / TRUE		// TRUE means: a later recompile of a new version
					// will replace the actual code automatically
					// FALSE means: references to this code are not refreshed
					// even after a recompile of this entity
DEBUG FALSE / TRUE		// TRUE means: a "!" at start of line triggers a call to
					// FUNCTION Assert(sAssertionInfo)
					// in case of the following expression evaluating to FALSE
					// FALSE means: these lines are ignored
					// examples:
					// !IsMainThread()
					// !i = 9
					// Additionally some runtime type and bounding checks
					// are omitted for speed with DEBUG FALSE

MESSAGEBOX <anything>		// starts a MessageBox(<anything>) at compile time
SETLINE <n>				// set current line number to <n>


DOORS Data
==========

DOORS Data are polymorphic.
They may be of one of the following
Types:
---------

NIL			not initialised
			example:
			RETURN NIL

BOOL			boolean TRUE or FALSE
			example:
			RETURN TRUE

INT			integer (actual implementation: 32 bit)
			examples:
			? -1			// decimal
			? 0xF, 0X0a5	// hexadecimal
			? 0b11, 0B0101	// binary
			? 0o77, 0O0721	// octal

REAL			real (floating point) (actual implementation: 64 bit)
			examples:
			? 0.5
			? -1.2
			? 123456789012345	// out of integer range
			? 0xFFFFFFFFFF	// out of integer range
			? 2.0e4
			? -0.7E3
			? 3.7e+3
			? -6.4E-9

SYMBOL		symbol (limit of different symbols only by memory)
			The representing string size is only limited by memory,
			but routines, which use symbols may limit this size.
			E.g. JOINT names are restricted to 255 chars
			by actual implementation.
			examples:
			? #World = #WORLD	// TRUE, not case sensitive
			? #World		// string representation depends
						// from first occurrence in Roomancer
			? StringAsSymbol("Hello World")	// to embed e.g. spaces

STRING		string (size limit only by memory)
			example:
			? "Hello World"

			localized strings may be preceded with '#' (see 'StringSet' declaration)
			they always override the PRAGMA STRINGSET switch
			example:
			? #"Hello World"

			embedded backslashes are treated special:
			\nnn	ASCII value in decimal
			\xnn	ASCII value in hexadecimal
			\n		\10	\x0a	newline
			\t		\9	\x09	tab (horizontal)
			\\		\92	\x5c	backslash
			\"		\34	\x22	double quote
			\r		\13	\x0d	carriage return
			\v		\11	\x0b	vertical tab
			\f		\12	\x0c	formfeed
			\a		\7	\x07	alert
			\b		\b	\x08	backspace

			example:
			? "Hello\nWorld"

			single quoted strings are treated raw:
			examples:
			? 'You are "The best"'
			? #'Hello /.\'
			LOCAL sFile := PathName() +'Art\Rom'

			square bracket quoted strings are treated raw, too.
			The right delimiter is optional, e.g. is replaceable by end of line
			examples:
			? sAuthor , #[said: "It's super"]
			?[<A href="http://community.moove.com/">
			?[CommSQLExec( "DELETE customer WHERE memb_id='12345'" )

			multiline strings are treated raw, too.
			examples:
			? sAuthor , /'It's super'/
			s := /'
			Here is my story:
			'First' line
			"Second" line
			[Third] line
			'/

POINTER		pointer to the outside world, subtype by name or number
			? Ptr(0)			// >Ptr(0x0, #0)
			? PTR(-1)			// >Ptr(0xFFFFFFFF, #0)
			? PTR(0xffffffff, #test)// >Ptr(0xFFFFFFFF, test)
			? StringCompile("1+2")	// >CodeBuffer for FUNCTION '__StringCompile'
							// the result can be used e.g. for
							// CodeExec(), CodeExecThread(), AEval() etc.
			? WAV := WAVAlloc("St.WAV")
				// >WAVBuffer for file 'd:\DEV\ROOMANCER\SOUNDS\St.WAV'
				// (for every pointer name you can declare e.g. a function
				// to get a string info about pointers of this name)

			example C++ source for system function WAVAlloc():
			//////////////////////////////////////////////////////////////////////////
			static ptr _stdcall SysWAVAlloc
			(
				CPoly valsFileName,
				CPoly valfLooped
			)
			{
				ptr Ptr = {0, ATOM_SOUND};

				if(valsFileName.Tag() == vtStr)
				{
					Ptr.pPtr = (void*)SoundProvide(valsFileName.GetLPCSTR(), valfLooped);
				} else
				{
					ErrType(SysWAVAlloc, &valsFileName);
				}
				return Ptr;
			}
				//////////////////////////////////////////////////////////////////////////


ARRAY			array (size limit only by memory)
			Contains list of data, which are accessed by number.
			Size is dynamic. e.g. may be changed at runtime.
			May be multidimensional.
			example:
			? { 1.5, 2.7, 3.1 }
			? { { 1, 2, 3 }, { 1, 2, 3 }, { 1, 2, 3 } }
			? ArrayCreate(70000)	// array with 70000 elements
			a := {1, 2, 3}; b := a; a[0] := 4	// because of reference semantic, array b is changed, too.

INSTANCE		instance of a class, subtype by class
			Contains list of data, which are accessed by their name.
			Reference semantic like ARRAY.
			? SoulActor{}

COM			COM object
			example:
			LOCAL comWB := Com("Word.Basic")
			comWB.AppShow()
			comWB.FileNewDefault()
			comWB.Insert("Hello World")
			comWB.FileSaveAs(GetTempPath() +"Temp.doc")

A call to ComRelease() is optional to enforce a release at once. Otherwise are all references
to COM objects handled automatically. Releases are done by the garbage collector.

VECTOR		3D vector (x, y, z information)
			examples:
			? VECTOR{}	// VECTOR{0.000, 0.000, 0.000}
			? VECTOR{0, -1.0, 0.5}
			vecRes :=  VAdd(VECTOR{10, 10, 10}, VECTOR{20, 20, 20})	
				// dynamic allocation
			VAdd(VECTOR{10, 10, 10}, VECTOR{20, 20, 20}, vecRes)		
				// No dynamic allocation, change by reference


COLOR			color
			examples:
			? Color{51, 2, 255}
			? Color{}
			? Color{##LightMagenta}
			? Color{0xff0077}


Most DOORS data are "self contained", but some contain
only automatic references to the "real" data.
These data are of type STRING, ARRAY, INSTANCE, COM or VECTOR.
The "real" data may be part of the entity, example:
? "Hello world"	// static memory
If the data are created at runtime, it is part of dynamic memory:
? TimeString()	// >10/24/96 01:48 PM
Dynamic memory is automatic, e.g. it is created on the fly and
there is no need to free it explicitly. So programming is very easy.
You never can cause "memory leakage".
DOORS dynamic memory is extremely efficient, e.g. very fast and space efficient.
Every thread has its own dynamic memory, so normally there is no need
to protect and synchronize the data between the threads (like in ....).
On thread termination all its dynamic memory is freed at once.
In other words: speed and safety.


Scope, lifetime and usage:
----------------------------------

LOCAL		Scope is restricted to declaring executable entity
		from declaration line to end of entity.
		Lifetime is from entity execution entry up to
		entity execution exit. Exit may be indirect by THROW
		in a subroutine and CATCH in a calling routine (see below).
		LOCALs always residue on processor stack.

		example:
		FUNCTION TestLocal
		LOCAL a := { { 1, 2, 3 }, { 1, 2, 3 }, { 1, 2, 3 } }, b, c := 1, d := TimeString()
		? c
		? a[0][2]	// all offsets in Roomancer are 0-based
				// because they are consistently meant as distance from beginning
		a[0][2] := c
		LOCAL x	// declaration any time


Parameters	They are declared implicit by their name in the routine declaration line.
		Scope and lifetime are identical to LOCALs.
		Parameters which are not given by the caller are init to NIL.
		The number of parameters given by the caller can be provided by PCount().
		You can access parameters not only by name, but also by number with ParamGet(n).
		So you can even access parameters which are not declared but given additionally
		by the caller.

		example:
		ON SoulHuman TestParameter(a, b, c)
		? PCount()
		? ParamGet(0), ParamGet(1), ParamGet(2), ParamGet(3), ParamGet(4)
		? a
		a:= 4


GLOBAL	Scope is restricted to declaring executable entity
		from declaration line to end of entity.
		GLOBALs (of equal name) declared in different entities map to the same data.
		Lifetime is restricted to the lifetime of the executing thread.
		The same entity running in different threads is accessing different GLOBALs, so no thread synchronization is necessary.

		example:
		FUNCTION TestGLOBAL
		TestGLOBALSubroutine()
		GLOBAL g
		? g		// >7

		FUNCTION TestGLOBALSubroutine
		GLOBAL g
		g := 7


EXTERN	Scope is restricted to declaring executable entity
		from declaration line to end of entity.
		EXTERNs (of equal name) declared in different entities map to the same data.
		Lifetime is restricted to the lifetime of the Roomancer application.
		Different threads are accessing the same EXTERNs,
		so thread synchronization is necessary, which is done by DOORS automatically.
		For synchronization in a bigger context and for thread control
		powerful functions are available.

		example:
		FUNCTION TestEXTERN
		EXTERN e_nThreadStarted := 0
		LOCAL nThreadStarted := 0
		REPEAT
			? ++nThreadStarted
			DO TestEXTERNThread	// start another thread
		UNTIL e_nThreadStarted >= 5
		? e_nThreadStarted
		Sleep(5000)				// wait 5000 milliseconds
		? e_nThreadStarted


		FUNCTION TestEXTERNThread
		EXTERN e_nThreadStarted
		e_nThreadStarted++


MEMBER	MEMBERs are declared in a CLASS (see also above).
		Scope is restricted to methods of this CLASS.
		Lifetime is related to lifetime of the instance which is its container.
		Classes inherit MEMBERs and their scope by the PARENT keyword (see also above).

		Example:
		CLASS SoulBeing PARENT SoulActor

		m_nBodyTemperature


		CLASS SoulHuman PARENT SoulBeing

		EXPORTED m_bSex


		ON SoulBeing Test()
		? m_nBodyTemperature

		ON SoulHuman Test()
		? m_nBodyTemperature


		EXPORTED MEMBERs are additionally accessible through instances
		by the "." operator
		Example:
		FUNCTION TestEXPORTED
		LOCAL oSoul := SoulHuman{}
		oSoul.m_bSex := FALSE
			// ? oSoul.m_nBodyTemperature // would generate a compiler error...




The DOORS Syntax
================

		+	addition
		-	subtraction
		*	multiplication
		/	division
		%	remainder (modulo)
		<<	left shift
		>>	right shift
		&	bitwise AND
		|	bitwise OR
		^	bitwise XOR

		:=	assignment
		++	postfix increment
		--	postfix decrement

		+=	assignment after addition
		-=	assignment after subtraction
		*=	assignment after multiplication
		/=	assignment after division
		%=	assignment after remainder (modulo)
		<<=	assignment after left shift
		>>=	assignment after right shift
		&=	assignment after bitwise AND
		|=	assignment after bitwise OR
		^=	assignment after bitwise XOR

		AND	boolean AND
		OR	boolean OR


		+	unary plus
		-	unary arithmetic negation
		++	prefix increment
		--	prefix decrement

		~	bitwise complement

		!	boolean NOT


		=	equal
		==	equal
		!=	unequal
		<>	unequal
		<	less
		<=	less or equal
		>	greater
		>=	greater or equal


		{}				array creation
		symArray[]			array subscript
		symFunc()			function call
		symInst.			member selection (instance)
		symInst.symMethod()	method call (scope of class of instance)
		SELF.symMethod()		method call (scope of class of calling method)
		PARENT.symMethod()	method call (scope of parent class of calling method)

		SELF				instance of calling method


		IF bCond			condition
		[ ELSEIF bCond]
		[ ... ]
		[ ELSE ]
		ENDIF



		TRY				// start exception handling
		...
		[ THROW [expression] ]	// throw exception (may be in subroutine)
		...
		[ CATCH [symVar] ]	// catch exception [and assign to symVar]
						// exception may be generated by THROW
						// or by low level exceptions, e.g. by hardware or system
		...
		[ THROW [expression] ]	// throw exception for outer level exception handler (may be in subroutine)
		...
		ENDTRY			// end exception handling, now outer level exception handler again active



		FOR symVar := nStartVal TO nEndVal [ STEP nStepSize ]
			// start iteration with assignment to symVar
			// check for symVar being in range of nStartVal TO nEndVal
			// else exit iteration
		...
		NEXT	// add 1 / [ nStepSize ] to symVar, loop to check of start


		WHILE bCond		// start iteration, if bCond, else exit
		...
		[ LOOP ]		// loop to start to check for bCond
		[ EXIT ]		// exit iteration
		...
		ENDWHILE		// end of iteration, loop to start


		REPEAT		// start iteration (in any case)
		...
		[ LOOP ]		// loop to check for bCond
		[ EXIT ]		// exit iteration
		...
		UNTIL bCond		// exit, if bCond, else loop to start


		LABEL symLabel	// declare LABEL symLabel in entity scope
		GOTO symLabel	// GOTO LABEL symLabel in entity scope


RETURN [expression]	// exit entity scope, provide result [expression] / NIL

STRINGSET	// must be first command, every line in between replaces a string literal in the following code
...		// empty lines prevent replacement.
		// use ! before debug mode only strings
		// Use PRAGMA STRINGSET TRUE/FALSE for setting the default string behavior
		// localized strings (#"...") always overide the PRAGMA STRINGSET switch
END
					Example:
					STRINGSET German
						"Hallo"		// "Hello"
						'"\" wird im Pfad vermißt'
									// "Sorry"
						!; !"Lesefehler"	//	!? "WAV:", sFile, "read error"
					END


DO symFunction	// start symFunction as thread
			// if you want to control symFunction, use the Thread() function instead
			// (see System function documentation)


\			// line concatenation (several physical lines per statement)

;			// statement separator (several statements per physical line) (logical lines)

//			// comment up to end of physical line

/* ... */		// comment from /* upto */, maybe inline or spanning several (physical) lines


?			Out(), see PRAGMA QOUT
				Example:
				? 'Nr.', 1

??			OutAdd(), see PRAGMA QOUT
				Example:
				?? 'ID', 1

!			// logical lines starting with "!" are only compiled while in debug mode, see PRAGMA DEBUG, IsDebugMode()
!<expr>		expression <expr> is validated
			expression, which are FALSE, trigger the function Assert(), see PRAGMA DEBUG
			Examples:
			! n > 5
			! n > 5	// Please call operator "Boomer"
			more parameters are optional:
			Example:
			! n > 5, n	// we are interested in the value of <n>

!.<stat>		statement <stat> is executed
			Example:	!.LOCAL n := 3

!?			Out(), if IsDebugMode()
			Example:	!? "Finished", CodeName(0)


DOORS FixedSymbols
==================

If you want to use integers values by name, DOORS provides FixedSymbols for you.
		Like all symbols, they are not case sensitive.

		examples:
		? ##INT_MAX

		IF AnyType(ParamGet(3)) = ##String
			? "4. parameter is a string"
		ENDIF


		FUNCTION ASSERT(sAssertion)
		LOCAL sText := "Assertion failed in Line "+ Str(CodeLine(1))
		LOCAL nResp :=MessageBox(sText	\
					+ " of "		\
					+ CodeType(1)	\
					+ " " 		\
					+ CodeName(1)	\
					+ ":\n"		\
					+ sAssertion, NIL, ##MB_ABORTRETRYIGNORE)

		RaiseEditor(sText + ": " + sAssertion,	\
					CodeType(1), 	\
					CodeName(1), 	\
					CodeLine(1),	\
					CodeClass(1)	)

		IF nResp = ##IDABORT
			THROW
		ENDIF



		You can check for existence of FixedSymbols, example:
		? IsFixedSymbol("MyFixedSymbol")

		You can create FixedSymbols, example:
		? CreateFixedSymbol("MyFixedSymbol", 4711)
		? ##MyFixedSymbol	// >4711

		CreateFixedSymbol() is an example for functions, which are ALWAYS
		resolved at compile time. (See also above PRAGMA FOLDFUNC).



DOORS SystemFunctions
=====================

Systemfunctions are predeclared functions, which can be found by the compiler
before searching through akasha storages. If you import sources into the storage,
e.g. by writing a new entity, you get a warning, if a function is already declared
as system function.
Even while Roomancer applications are running, new or replacement systemfunctions
e.g. written in C++, ASM etc. can be added and declared.
This declaration can provide parameter types, return value type, calling convention,
minimum and maximum number of parameters, transparent overloading with systemfunctions
of the same name. You can provide a documentation for the function.
All these infos are used by DOORS at compile time and at runtime.
You can even declare a related function, which is called by the compiler with
the given parameters. This function can fold the function call before code is generated.

List of actual provided SystemFunctions:
(Meaning of security flags see above)
Please see DOORS.HTM (DOORS API Reference) or DOORSAPP.HTM (DOORS API Reference for AppServer)

DOORS Compilation speed
=======================

DOORS can compile several MB's of source code per second!
The compilation speed can exactly be measured 
using the functions CompileTime() and CodeTime().


DOORS Execution speed
=====================

following C++ program sequence was ported to DOORS:
//////////////////////////////////////////////////
	DWORD start, end;
	int i;

	start = timeGetTime();

	i = 0;
	CString s;
	do
	{
		s = (char)i;
		s += "Hello world";

	} while (!(++i > 255*255*255));

	end = timeGetTime();

	int nRes = end - start;
//////////////////////////////////////////////////

DOORS version:
//////////////////////////////////////////////////
	LOCAL start, end
	LOCAL i

	start := Milliseconds()

	i := 0
	LOCAL s
	REPEAT
		s := chr(i)
		s += "Hello world"

	UNTIL ++i > 255*255*255

	end := Milliseconds()

	LOCAL nRes := end - start
//////////////////////////////////////////////////

JAVA version:
//////////////////////////////////////////////////
	long start, end;
	int i;

	start = System.currentTimeMillis();

	i = 0;
	StringBuffer s;
	do
	{
		s = new StringBuffer( new Character( (char)i ).toString() );
		s.append("Hello world");

	} while( !(++i > 255*255*255) );

	end = System.currentTimeMillis();

	long nRes = end - start;
//////////////////////////////////////////////////

The results:

Computer:	Pentium Pro 200 MHz

The C++ program was compiled with MSVC version 4.2.
ALL compiler optimizations ON for speed (therefore version 4.2), release runtime libraries.

The JAVA program was compiled with J++ 1.0
and executed with Microsoft Explorer 3.02, JIT compilation on.

C++	    46184 milliseconds
DOORS     13900 milliseconds
JAVA    1801990 milliseconds


Further readings
================
Use !CreateDOORSHTM() to create the DOORS.HTM (DOORS API Reference) specific to your application.

For AutoChat functionality please see AutoChat.ac

You can find some test routines in Test.Uni.


************* eof DOORS.TXT *************