Contents | < Browse | Browse >
9F. system support functions
----------------------------

	bool:=KickVersion(vers)

Will give TRUE if the kickstart in the machine your program is running
on is equal or higher than vers, else FALSE

	mem:=New(n)

This dynamically creates an array (or memory area, if you wish) of
n bytes. Difference with AllocMem() is that it is called automatically
with flags $10000 (i.e cleared mem, any type) and that no calls to
Dispose() are necessary, as it is linked to a memory list that is
automatically de-allocated upon exit of your program.
(see  4K , also)

	mem:=NewR(n)

same as New(), only now automatically raises the "MEM" exception
instead of return if no memory could be allocated.

	mem:=NewM(n,flags)

same as NewR(), but also allows you to specify flags (MEMF_CHIP etc.)

	Dispose(mem)

Frees any mem allocated by New(). You only have to use this function
if you explicitly wish to free memory _during_ your program, as all
is freed at the end anyway.

	CleanUp(returnvalue=0)

[obsolete: use exception handling]
Exits the program from any point. It is the replacement for the DOS
call Exit(): never use it! instead use CleanUp(), which allows
for the deallocation of memory, closing libraries correctly etc.
The return value will be given to dos as returncode.
Cleanup() is ONLY necessary if you have to exit at a point different
from ENDPROC in main.

	amount:=FreeStack()

returns the amount of free stack space left. This should always be 1000 or
more. (see  16C  on how E organizes its stack. If you don't do heavy recursion,
you need not worry about your free stack space.

	bool:=CtrlC()

Returns TRUE if Ctrl-C was pressed since you last checked, else FALSE.
This only works for programs running on a console, i.e. cli-programs.

Example of how these last three functions may be used:

/* calculate faculty from command-line argument */

OPT STACK=100000

PROC main()
  DEF num,r
  num:=Val(arg,{r})
  IF r=0 THEN WriteF('bad args.\n') ELSE WriteF('result: \d\n',fac(num))
ENDPROC

PROC fac(n)
  DEF r
  IF FreeStack()<1000 OR CtrlC() THEN CleanUp(5)    /* xtra check */
  IF n=1 THEN r:=1 ELSE r:=fac(n-1)*n
ENDPROC r

Of course, this recursion will hardly run out of stack space, and when it
does, it's halted by FreeStack() so fast you won't have time to press
CtrlC, but it's the idea that counts here.
A definition of fac(n) like:

PROC fac(n) IS IF n=1 THEN 1 ELSE fac(n-1)*n

would be less safe.


	mem:=FastNew(size)	FastDispose(mem,size)	FastDisposeList(list)

FastNew() and FastDispose() are replacements for NewR(size) and
Dispose(ptr) (they are used by NEW and END). this is what they have
in common:
- "NEW" exceptions may be Raised
- memory is always cleared
- auto-dealloc at end of program
- NIL accepted in deallocation
but the following differences should be noted (positive):
- they are varying from 10 to 50 times faster (!)
- they use way less memory for small objects
- they do not fragment memory
[all this is for objects <=256 bytes, for bigger ones NewR() and
 Dispose() are used].
negative:
- they do not free mem, but recycle it.
- FastDispose() needs exact size of allocation. END also.

List allocated with NEW need the function FastDisposeList(). Because
Lists have a length, the size parameter isn't needed.