		     SCADALisp, Shareware Release
		    Cogent Real-Time Systems Inc.
			  September 20, 1995

		    Functions and Global Variables

Table of Contents
=================

1.  Global Variables
2.  Shareware Version
    2.1  CAR, CDR and Related functions
    2.2  List Functions
    2.3  Quote and Macro Functions
    2.4  Assignment Functions
    2.5  Function definition functions
    2.6  Output Functions
    2.7  Property Functions
    2.8  Time and Date Functions
    2.9  Evaluation Functions
    2.10 Miscellaneous Functions
    2.11 Data type functions
    2.12 Data type conversion functions
    2.13 Logic and flow control functions
    2.14 Array functions
    2.15 Buffer functions
    2.16 Error functions
    2.17 File system functions
    2.18 Comparison Functions
    2.19 Simple Math Functions
    2.20 Binary Math Functions
    2.21 Signal handling and timers
    2.22 Object-Oriented Programming Functions
    2.23 Event Handling Functions
    2.24 QNX Windows Functions
    2.25 Photon Functions
    2.26 Photon Structures Mapped as Classes
    2.27 Photon Widgets
3.  Registered Version
    3.1  List Functions
    3.2  Output Functions
    3.3  Miscellaneous Functions
    3.4  String functions
    3.5  File system functions
    3.6  Advanced Math Functions
    3.7  Trigonometric Functions
4.  Commercial Version
    4.1  Encapsulated QNX IPC
5.  Control Version
    5.1  Real-time database Functions
6.  Specialty Versions
    6.1  ProcessVision functions
7.  Usage Tips
    7.1  The Main Event Loop
    7.2  Processing all Waiting Events
    7.3  Loading Photon Application Builder .wgtw Files
    7.4  Getting On-Line Help for Functions
    7.5  Examining the Instance Variables in a Class or Instance
    7.6  Undefined symbols
    7.7  Dynamic Scope
    7.8  Properties and Scoping
    7.9  Forward and Back Quote Syntax
    7.10 Using the debug> Prompt
    7.11 Getting Rid of the debug> Prompt
    7.12 Literal Array Syntax
    7.13 Literal Instance Syntax
    7.14 Passing Arguments to SCADALisp Programs
    7.15 Making Stand-Alone Programs with SCADALisp
8.  Situations which might cause SCADALisp to crash


1.  Global Variables
====================

*undefined*	- Special variable which causes the error "Undefined Symbol"

*jump-stack*	- The function call stack at the time of an error

*last-error*	- The text description of the last error 

*fixed-point*	- If T, map all floating point numbers to 16.16 fixed point

*debug*		- Unused

this		- The current symbol within a function called through the
		  following facilities:
			add-read-function
			add-set-function
			add-exception-function
			add-echo-function
			add-event-function

previous	- The previous value of the variable named in 'this'.

value		- The current value of 'this'.

self		- The current instance within a method.

&optional	- Keyword used in function argument declarations to
		  make all following arguments optional.  An optional
		  argument will have the value *undefined* if it is not
		  provided.  This can only be tested with the function
		  (undefined-p ...)

&noeval		- Keyword to make one following argument in a function
		  argument list non-evaluated.

&rest		- Keyword to make the last argument in a function
		  argument list accept any number of values.  The
		  argument will be passed to the function as a list of
		  all of the remaining arguments.

*case-sensitive*  If T, make all symbols case-sensitive, including function
		  names.  Otherwise symbols are converted to lower case
		  prior to being processed.  Default to T.

*eval-stack*	- List of all functions called to this point in the
		  code, in reverse order.  Use the (stack) function to
		  read this list.

*eval-silently*	- If T, ignore "Undefined symbol" errors

*eof*		- Returned when a read function encounters the end of file

*eol*		- Returned when a read function encounters an unexpected
		  end of line

*current-input*	- The file which is providing the input to the reader.
		  This is an internal variable and should not be used.

*require-path*	- A list of paths to search when the (require "")
		  function is called.  Default: ("." "/usr/lib/scadalisp/lib")

*load-extensions* - A list of file name extensions to search for when
		  a load or require function is called.
		  Default: ("" ".lsp")

stdin		- The standard input

stdout		- The standard output

stderr		- The standard error output

*sighup*	- First argument to the (signal ...) function must be
*sigint*	  one of these
*sigquit*
*sigill*
*sigtrap*
*sigiot*
*sigabrt*
*sigemt*
*sigfpe*
*sigkill*
*sigbus*
*sigsegv*
*sigsys*
*sigpipe*
*sigterm*
*sigusr1*
*sigusr2*
*sigchld*
*sigpwr*
*sigwinch*
*sigurg*
*sigpoll*
*sigio*
*sigstop*
*sigtstp*
*sigcont*
*sigttin*
*sigttou*
*sigdev*

*event*		- The name of the most recent QNX Windows event.  Can
		  be one of:
			"qw_click"
			"qw_edited"
			"qw_typed"
			"qw_quit"

qw-char		- The character code (decimal) of the character typed
		  to a "qw_typed" message.

qw-typed-fn	- A function to call when a "qw_typed" message occurs.
			e.g.,  (defun qw-typed-fn ()
				 (princ "You typed " qw-char)
				 (terpri))

		  If there is no qw-typed-fn, the event is sent to the
		  element in which it occurred.

qw-adjust-fn	- A function to call when a "qw_click" message occurs
		  with the "adjust" button pressed

qw-menu-fn	- A function to call when a "qw_click" message occurs
		  with the "menu" button pressed

*** NOTE: qw-typed-fn, qw-adjust-fn and qw-menu-fn may change or be
	  removed in future.


2.  Shareware Version
=====================

2.1  CAR, CDR and Related functions
===================================

(car list)			- the first element in a list
(cdr list)			- all elements in a list except the first
(caar list)			- (car (car list))
(cadr list)			- (car (cdr list))
(cdar list)			- (cdr (car list))
(cddr list)			- (cdr (cdr list))
(caaar list)			- (car (car (car list)))
(caadr list)			- (car (car (cdr list)))
(cadar list)			- (car (cdr (car list)))
(caddr list)			- (car (cdr (cdr list)))
(cdaar list)			- (cdr (car (car list)))
(cdadr list)			- (cdr (car (cdr list)))
(cddar list)			- (cdr (cdr (car list)))
(cdddr list)			- (cdr (cdr (cdr list)))
(nth-car list number)		- apply car to a list number times
(nth-cdr list number)		- apply cdr to a list number times

2.2  List Functions
===================

(append list...)		- append all arguments to form a new list
(assoc s-exp list)		- find an expression in an association list
(assoc-equal s-exp list)	- assoc using equal instead of eq to compare
(cons s-exp list)		- create a list whose car is s-exp, cdr is list
(copy s-exp)			- copy the top level of a list
(copy-tree s-exp)		- recursively copy a list
(find s-exp list)		- return the tail of list starting at s-exp
(find-equal s-exp list)		- find using equal instead of eq
(length list)			- length of a list, array or buffer
(list s-exp...)			- create a list of all arguments
(listq s-exp...)		- create a list of all args without evaluating
(nappend list...)		- destructive append
(nremove s-exp list)		- destructively remove all s-exp from list
(nreplace new-s-exp		- destructively replace all new with old
          old-s-exp list)
(nreplace-equal new-s-exp	- nreplace using equal instead of eq to compare
	  old-s-exp list)
(reverse list)	    		- reverse of the top level of a list
(rplaca cons s-exp)		- destructively replace the car of a cons cell
(rplacd cons s-exp)		- destructively replace the cdr of a cons cell

2.3  Quote and Macro Functions
==============================

(backquote s-exp)		- macro expandable quotation
(quote s-exp)			- protect the argument from the evaluator

2.4  Assignment Functions
=========================

(add-set-function symbol s-exp)	- add an expression to eval when symbol is set
(remove-set-function symbol	- remove an add-set-function expression
		     s-exp)
(set symbol s-exp)   		- set the value of a symbol 
(setq symbol s-exp)		- set a symbol, don't evaluate the symbol
(setqq symbol s-exp)		- set a symbol, don't evaluate either arg
(when-set-fns symbol)		- query the functions from add-set-function

2.5  Function definition functions
==================================

(defun name args expression...)	- define a function
(defune name args		- define a function, evaluating name and args
	expression...)
(lambda args expression...)	- define a lambda expression (nameless func)
(local variable...)		- declare a local variable (for SLANG)

2.6  Output Functions
=====================

(pretty-princ s-exp...)		- beautified human-readable output
(pretty-print s-exp...)		- beautified machine-readable output
(princ s-exp...)		- human-readable output
(print s-exp...)		- machine-readable output
(terpri &optional file)		- write a carriage return to stdout or file

2.7  Property Functions
=======================

(getprop symbol property)	- get the value of prop property from symbol
(properties symbol)		- get all properties from symbol
(setprop symbol property value)	- set a property for symbol
(setprops symbol properties)	- set all properties for symbol

2.8  Time and Date Functions
============================

(clock)				- seconds since midnight Jan. 1, 1970, GMT
(date)				- the time and date as a string
(date-of)			- the time and date of a clock value
(sleep seconds)			- pause for some seconds
(time iterations		- run time of specified iterations of command
      &noeval command)

2.9  Evaluation Functions
=========================

(eval s-exp)			- evaluate an expression
(eval-count)			- cumulative number of calls to eval
(eval-list list)		- evaluate a list of expressions, return list
(eval-string string)		- evaluate a string as a LISP expression
(funcall function args)		- call a function with a list of arguments

2.10 Miscellaneous Functions
============================

(allocated-cells)		- report on memory allocation
(errno)				- error number from last failed system call
(exit-program return-value)	- exit the program, returning to the shell
(free-cells)			- report on free cells
(gc)				- force a garbage collection now
(gc-trace t|nil)		- print info during garbage collection
(qnx_osinfo node)		- get QNX OS information for node
(qnx_osstat node)		- get QNX OS statistics for node
(random)			- generate a random float 0 <= x < 1
(raw-memory)			- raw memory allocated to LISP objects
(set-random integer-seed)	- seed the random number generator
(stack)				- show the current calling stack

2.11 Data type functions
========================

(alist-p s-exp)			- is the argument an association list?
(array-p s-exp)			- is the argument an array?
(class-p s-exp)			- is the argument a class?
(cons-p s-exp)			- is the argument a list?
(destroyed-p s-exp)		- is the argument a destroyed instance?
(file-p s-exp)			- is the argument a file?
(fixed-point--p s-exp)		- is the argument a fixed point float?
(function-p s-exp)		- is the argument a function or lambda?
(instance-p s-exp)		- is the argument an instance of a class?
(int-p s-exp)			- is the argument an integer?
(list-p s-exp)			- is the argument a list?
(long-p s-exp)			- is the argument an integer?
(method-p s-exp)		- is the argument a class method?
(nil-p s-exp)			- is the argument nil?
(number-p s-exp)		- is the argument a number?
(real-p s-exp)			- is the argument a floating point number?
(string-p s-exp)		- is the argument a character string?
(sym-alist-p s-exp)		- is the argument a symbol association list?
(symbol-p s-exp)		- is the argument a symbol?
(true-p s-exp)			- is the argument true (T)?
(undefined-p s-exp)		- is the argument undefined?

2.12 Data type conversion functions
===================================

(bin number)			- change representation of number to binary
(char number)			- create 1-character string from ASCII number
(char-val char-as-string)	- create ASCII number from 1-character string
(dec number)			- change representation of number to decimal
(hex number)			- change representation of number to hex
(int s-exp)			- create an integer from a string
(number s-exp)			- create a number from a string
(oct number)			- change representation of number to octal
(string s-exp...)		- create a string from args, machine-readable
(stringc s-exp...)		- create a string from args, human-readable
(symbol s-exp)			- create a symbol from a string

2.13 Logic and flow control functions
=====================================

(and condition...)		- logical AND
(cond cond/actions)		- choose one of many condition/action pairs
(do locals condition body)	- generalized iteration statement
(eq s-exp s-exp)		- test for identical equality
(equal s-exp s-exp)		- test for practical equality
(for var in|on list		- list traversal iteration statement
      do|collect ...)
(if condition then else)	- if
(let locals body)		- compound statement with local variables
(not condition)			- logical NOT
(or condition...)		- logical OR
(progn body)			- compound statement
(switch s-exp value/action...)	- choose one of many value/action pairs
(while condition body)		- while iteration statement

2.14 Array functions
====================

(aref array index)		- return an element of an array
(array s-exp...)		- create an array of the arguments
(aset array index value)	- set an element of an array
(delete array position)		- delete an array element, collapse array
(insert array			- insert an element in array, expand array
	position-or-function
	value)
(make-array n-elements)		- create an empty array of n elements
(shorten-array array n-elements)- alter the size of an array

2.15 Buffer Functions
=====================

(bref buffer index)		- return an element of a buffer
(buffer contents...)		- create a buffer with given contents
(bset buffer index value)	- set an element of a buffer
(bdelete buffer position)	- delete a buffer element, collapse buffer
(binsert buffer position value)	- insert an element into buffer, expand buffer
(make-buffer n-elements)	- create an empty buffer of n elements
(shorten-buffer buffer		- alter the size of a buffer
		n-elements)

2.16 Error and Debugging Functions
==================================

(error string)			- cause an error with string as message
(notrace &optional s-exp)	- don't trace this expression or turn off trace
(trace &optional s-exp)		- trace this expression or turn on global trace
(trap-error sexp1 sexp2)	- trap errors, clear error status,
				  eval sexp2 only on error
(unwind-protect sexp sexp)	- trap errors, don't clear error
				  status, eval sexp2 regardless


				  
2.17 File system functions
==========================

(absolute-path filename)	- return the absolute pathname of a file
(close file)			- close a file
(directory path filetypes	- directory, filetype=0,1,2, fullpaths=t,nil
	   fullpaths)
(is-dir path)			- t if path is a directory
(is-file path)			- t if path is a regular file
(load filename)			- read and execute a file in current grammar
(load-lisp filename)		- read and execute a LISP file
(open file mode)		- open a file, mode="r","w","a"
(open-string string)		- open a string as if it were a file
(read file)			- read one expression from a file
(read-char file)		- read one char from a file
(read-line file)		- read one line from a file
(read-long file)		- read one long in binary format from a file
(read-n-chars file nchars)	- read n characters from a file, as buffer
(read-short file)		- read one short in binary format from a file
(require filename)		- load a file iff not previously loaded
(require-lisp filename)		- load a LISP file iff not previously loaded
(root-path path)		- remove last name from path


2.18 Comparison Functions
=========================

(!= number number)		- numerically not equal
(< number number)		- numerically less than
(<= number number)		- numerically less than or equal
(= number number)		- numerically equal
(> number number)		- numerically greater than
(>= number number)		- numerically greater than or equal

2.19 Simple Math Functions
==========================

(% number number)		- modulus
(* number number)		- multiplication
(+ number number)		- addition
(++ symbol)			- increment a symbol, return value
(+++ symbol)			- return value of symbol, then increment
(- number number)		- subtraction
(-- symbol)			- decrement a symbol, return value
(--- symbol)			- return value of symbol, then decrement
(/ number number)		- division
(ceil number)			- smallest integer >= number
(div number number)		- integer division
(floor number)			- largest integer <= number
(neg number)			- negation (unary minus)

2.20 Binary Math Functions
==========================

(band number number)		- binary AND
(bnot number)			- binary NOT
(bor number number)		- binary OR
(bxor number number)		- binary XOR

2.21 Signal handling and timers
===============================

(after seconds action...)	- perform an action after seconds have elapsed
(at day month year hour minute	- perform a possibly repeating action
     second action...)
(block-signal signal-number)	- prevent signal from occurring
(block-timers)			- prevent timer signals from occurring
(cancel timer-number)		- cancel a timer by number
(every seconds action...)	- perform an action every number of seconds
(signal signal action...)	- define action to take when signal occurs
(timer-is-proxy t|nil)		- use proxies instead of signals for timers
(unblock-signal signal-number)	- allow a signal to occur
(unblock-timers)		- allow timer signals to occur

2.22 Object-Oriented Programming Functions
==========================================

(-> instance variable value)	- write to an instance variable
(:-> instance variable value)	- write to an instance variable, eval variable
(:@ instance variable)		- read an instance variable, eval variable
(@ instance variable)		- read an instance variable
(call instance method		- call a method with arguments
      argument...)
(class-add-ivar class variable	- add an instance variable to a class
	&optional initial-value
	type)
(class-name class)		- get the name of a class
(class-of instance)		- get the class definition for an instance
(defclass class-name superclass	- define a class
	  class-vars
	  instance-vars)
(definst class variable-array)	- (Obsolete)
(defmethod class method-name	- define a method for a class
	   arguments body...)
(has-ivar instance|class	- determine if class or instance has variable
	  variable)
(instance-vars instance|class)	- get all instance vars for class or instance
(ivar-type instance variable)	- get type of instance var
(new class)			- create a new instance of a class
(parent-class instance|class)	- get the parent class of instance or class

2.23 Event Handling Functions
=============================

(next-event)			- perform the next event, block if none
(next-event-nb)			- perform the next event, don't block

2.24 QNX Windows Functions
==========================

(add-event-function symbol	- attach code to a QNX Windows event
		    s-exp)
(remove-event-function symbol	- remove a QNX Windows event function
		       s-exp)
(when-event-fns symbol)		- query QNX Windows event functions for symbol

(Ask long string string)
(AttachLabel string string)
(AttachRepeat long long long long)
(Blink string long long long long)
(ChangeBox string long long)
(ChangeColor string long)
(ChangeEdge string long)
(ChangeFill string long long)
(ChangeGroup string string string string string)
(ChangeLabel string string long string)
(ChangeLink string string string)
(ChangeNumber string long)
(ChangeNumberColors string long long long long long long long long long long)
(ChangeNumberRange string long long long long long)
(ChangeOptions string string)
(ChangeOutline string long)
(ChangeReal string real)
(ChangeRealRange string real real real real real)
(ChangeRepeat string long long long long)
(ChangeSize string long)
(ChangeState string long)
(ChangeTag string string)
(ChangeText string string long long long)
(ChangeView string long string)
(Choose string string)
(ColorHSV long long long)
(ColorMenu string long long string)
(ColorRGB long long long)
(CursorArea long long long long string)
(CursorAt)
(CursorHide)
(CursorMove string long long)
(CursorPos)
(Deselect string)
(DialogAt long long string string)
(DialogCancel string string)
(DialogCurrent string)
(Drag tag)
(DragArea long long long long string)
(Draw)
(DrawAfter long)
(DrawArc long long long long string string)
(DrawAt long long)
(DrawAtRel long long)
(DrawButton string string string string)
(DrawContext)
(DrawDirectArea long long long long)
(DrawEnd string)
(DrawGroup long long long string string string)
(DrawLine long long string string)
(DrawLink string string string string)
(DrawNumber long long string string string)
(DrawOffset long long)
(DrawPara string long long string string)
(DrawPoly point-list options tag)
(DrawReal long real string string string)
(DrawRect long long string string)
(DrawSpacing long long)
(DrawText string long long long string string)
(Drawf string string string)
(DrawingAt)
(ElementBox)
(ElementCount string)
(ElementFind tag)
(ElementFirst tag)
(ElementFont)
(ElementFormat string)
(ElementInfo string)
(ElementLabel)
(ElementMax string)
(ElementNext)
(ElementNumber)
(ElementOption option)
(ElementReal)
(ElementState)
(ElementTag)
(ElementText)
(ElementTypeParam)
(Erase)
(FileMenu label title directory pattern options)
(GraphicsClose long)
(GraphicsCurrent long)
(GraphicsInit long)
(GraphicsOpen string)
(GraphicsState string)
(Hit row col depth options)
(Menu string string long string string)
(MenuItem long)
(Notice string string string string string)
(Pane long string)
(PaneChange long long long string)
(PaneClose long)
(PaneCurrent long)
(PaneOpen long long long long string)
(PaneView long long long long long long long)
(PickElements string string long long long long long)
(Picture string string)
(PictureChange title background pattern options)
(PictureClose long)
(PictureContinue)
(PictureCopy tag picture after offset-list options)
(PictureCurrent long)
(PictureFind string string)
(PictureHold)
(PictureOpen name file title background pattern options)
(PictureSave string)
(PixelArea long long long long string)
(PixelRect long long long long long long long)
(PrinterMenu string string string)
(Prompt string string long string string string string)
(RubberBand tag anchor options)
(RubberBandArea long long long long string)
(RubberSelect options)
(ScreenColor long long long long string string)
(ScreenFont string string long long string)
(ScreenOptions string)
(ScreenSleep long)
(ScrollBarClose string)
(ScrollBarOpen long long long long string)
(Select string long long)
(SelectEdit string long long)
(SetBaseline long)
(SetButton long long string)
(SetColor string long)
(SetEdge string long)
(SetFill string long long)
(SetFont string string string long long)
(SetFontId string long)
(SetFormat string string)
(SetLabel string long long string)
(SetLineThickness string long)
(SetName string string)
(SetNumberColors long long long long long long long long long long)
(SetNumberFormat long long string long long long)
(SetNumberRange long long long long long)
(SetOptions string string)
(SetPointArea long long)
(SetRealRange real real real real real)
(SetRoundness string long)
(ShiftArea long long long long long long)
(ShiftBy string long long)
(ShiftTo string long long)
(Tell string string)
(Window string string string string)
(WindowAt long long string string)
(WindowChange color options actions)
(WindowClose)
(WindowContinue)
(WindowCurrent long)
(WindowFind string string)
(WindowHold)
(WindowKeys string)
(WindowMsg string string string string)
(WindowOpen string long long string string string long)
(WindowSave string string)
(WindowState string)
(WmWindowPropRead name)

2.25 Photon Functions
=====================

(PhGetRects event)
(PgBlueValue color)
(PgCMY cyan magenta yellow)
(PgGray gray)
(PgGrayValue color)
(PgGreenValue color)
(PgHSV hue saturation value)
(PgRGB red green blue)
(PgRedValue color)
(PtAttachCallback widget callback-num callback-function &optional event-num)
(PtCollideWidget widget target-list flags)
(PtContainerHold widget)
(PtContainerRelease widget)
(PtContainingParent widget)
(PtDestroyWidget widget)
(PtEventHandler event)
(PtFlush)
(PtGetAbsPosition widget)
(PtHold)
(PtInit name)
(PtInitDrag widget container flags)
(PtMainLoop)
(PtModalEnd start-number)
(PtModalStart)
(PtQueryCallbacks widget callback-number)
(PtRealizeWidget widget)
(PtRelease)
(PtRemoveCallback widget callback-number function)
(PtReParentWidget widget parent-widget)
(PtResourceName widget|class resource-number)
(PtSetParentWidget widget)
(PtUnrealizeWidget widget)
(PtWidgetChildren widget)
(PtWidgetToBack widget)
(PtWidgetToFront widget)
(PxHelpQuit)
(PxHelpTopic topic)
(PxHelpTopicRoot topic-root)
(PxHelpTopicTree topic-tree)
(PxHelpUrl url)
(PxHelpUrlRoot url-root)
(PxLoadImage filename)
(PxReduceImage image xscale yscale)
(PxSubImage image x y width height)
(TranslateRect original-rect translation-rect)


2.26 Photon Structures Mapped as Classes
========================================

PhPoint
	int x, y

PhDim
	int w, y

PhLpoint
	int x, y

PhRgb
	int r, g, b

PhPrect
	PhPoint ul, lr

PhRect
	PhPoint ul, lr

PhArea
	PhPoint pos
	PhDim size

PhExtent
	PhRect rect
	int valid

PhEventRegion
	RID rid
	int handle

PhEvent
	int type
	int subtype
	PhEventRegion emitter
	PhEventRegion collector
	Flag flags
	int timestamp
	int num_rects
	int data_len

PhDrawEvent
	int cmd_buffer_size
	int context_size
	int id

PhPointerEvent
	PhPoint pos
	int buttons
	int button_state
	int click_count
	int flags
	int z
	int key_mods

PhDragEvent
	PhRect rect
	RID rid
	int flags
	PhRect boundary

PhBlitEvent
	RID rid
	PhRect rect
	PhPoint offset

PhBoundaryEvent
	PhEventRegion entered
	PhEventRegion left

PhKeyEvent
	int key_mods
	int key_flags
	int key_cap
	int key_sym

PhRegion
	RID rid
	int handle
	MPID owner
	int flags
	int events_sense
	int events_opaque
	int state
	PhPoint origin
	RID parent
	RID child
	RID bro_in_front
	RID bro_behind
	int input_group
	PgColor cursor_color
	int cursor_type
	int data_len

PtBasicCallback
	int value

PtListCallback
	int mode
	String item
	int item_len
	int item_pos

PtScrollbarCallback
	int action
	int position

PtMultiTextCallback
	int cur_insert
	int new_insert
	int start_pos
	int end_pos
	int length
	String text
	int doit

PtTextCallback
	int cur_insert
	int new_insert
	int start_pos
	int end_pos
	int length
	String text
	int doit

PhWindowEvent
	int event_f
	int state_f
	RID rid
	int event_state
	PhPoint pos
	PhPoint size

PtCallbackInfo
	int reason
	PhEvent event
	PhBasicCallback basic
	PhRect container
	PhListCallback list
	PhScrollbarCallback scrollbar
	PhTextCallback text
	PhMultiTextCallback multitext

PtEventData
	PhWindowEvent window_event
	PhDrawEvent draw_event
	PhPointerEvent pointer_event
	PhDragEvent drag_event
	PhBlitEvent blit_event
	PhBoundaryEvent boundary_event
	PhKeyEvent key_event
	PhRect rect

PhImage
	int type
	int image_tag
	int bpl
	PhDim size
	int palette_tag
	int colors
	int xscale
	int yscale
	int format
	int flags
	int[] palette
	Buffer image

2.27 Photon Widgets
===================

PtWidget
{
	PhArea area
	int cursor_type
	PgColor cursor_color
	PhDim dim
	Flag flags
	PhPoint pos
	Flag resize_flags
}
	PtBasic
	{
		int border_width
		PgColor bot_border_color
		PgColor color
		PgColor fill_color
		Pattern fill_pattern
		int margin_height
		int margin_width
		PgColor top_border_color
	}
		PtBarGraph
		{
			int bargraph_base
			PgColor bargraph_color
			BarData bargraph_data
			int bargraph_depth
			int bargraph_flags
			int bargraph_max
			int bargraph_min
		}
		PtBitmap
		{
			PgColor[] bitmap_colors
			int[] bitmap_data
			PgColor[] set_bitmap_colors
			int[] set_bitmap_data
			PgColor set_bg_color
			int set_bg_fill
		}
		PtComboBox
		{
			Flag cbox_flags
			int cbox_sel_item
			String[] cbox_items
			int cbox_spacing
			int cbox_sel_mode
			int cbox_visible_count
			PgColor cbox_selection_fill_color
			PgColor cbox_selection_text_color
			int cbox_button_width
			int cbox_max_length
			int cbox_cursor_position
			String cbox_text_font
			String cbox_text_string
		}
		PtContainer
		{
			PhRect anchor_offsets
			Flag anchor_flags
		}
			PtGroup
			{
				Flag group_flags
				int group_orientation
				int group_spacing
				int group_vert_align
				int group_horz_align
				int group_rows_cols
			}
			PtPane
			{
				int dummy
			}
				PtBkgd
				{
					int bkgd_brt_from
					int bkgd_brt_to
					int bkgd_hue_from
					int bkgd_hue_to
					int bkgd_sat_from
					int bkgd_sat_to
					int bkgd_mix
					int bkgd_orientation
					int bkgd_steps
					int bkgd_pixcolors
					int bkgd_pix_width
					int bkgd_pix_height
					int[] bkgd_pixmap
					int bkgd_tile
					int bkgd_type
				}
			PtScrollArea
			{
				int scroll_area_max_x
				int scroll_area_max_y
				int scroll_area_pos_x
				int scroll_area_pos_y
				int scroll_area_increment_x
				int scroll_area_increment_y
				int scrollbar_x_display
				int scrollbar_y_display
				int scrollbar_x_height
				int scrollbar_y_width
			}
			PtWindow
			{
				PtWidget default_action
				PtWidget icon_window
				int max_height
				int max_width
				int min_height
				int min_width
				Flag managed_flags
				Flag notify_flags
				Flag render_flags
				int state
				int force_front
				int cursor_override
				String title
			}
				PtIcon
				{
					int dummy
				}
				PtMenu
				{
					Flag menu_flags
					int menu_spacing
					String menu_text_font
					String menu_title
					String menu_title_font
				}
		PtGauge
		{
			Flag gauge_flags
			String gauge_font
			int gauge_minimum
			int gauge_maximum
			int gauge_value
			int gauge_orientation
		}
			PtSlider
			{
				Flag slider_flags
				int slider_increment
				String slider_label_tl
				String slider_label_br
				PgColor slider_label_tl_col
				PgColor slider_label_br_col
				int slider_multiple
				int slider_handle_width
				int slider_handle_height
				PhImage slider_image
				PgColor slider_tick_major_col
				PgColor slider_tick_minor_col
				int slider_tick_minor_div
				int slider_tick_major_div
				int slider_tick_major_len
				int slider_tick_minor_len
				int slider_trough_size
				PgColor slider_trough_col
			}
		PtGraphic
		{
			int line_width
			int line_cap
			int line_join
			PhPoint origin
			PhPoint points
			Flag graphic_flags
		}
			PtArc
			{
				int arc_start
				int arc_end
				int arc_type
			}
			PtEllipse
			{
				int dummy
			}
			PtLine
			{
				int dummy
			}
			PtPolygon
			{
				Flag polygon_flags
			}
			PtRect
			{
				int rect_roundness
			}
		PtLabel
		{
			int label_type
			Flag label_flags
			int horizontal_alignment
			int vertical_alignment
			String text_string
			String text_font
			int margin_left
			int margin_right
			int margin_top
			int margin_bottom
			String accel_key
			int balloon_position
			PgColor underline1
			PgColor underline2
			int underline_type
			PhImage label_data
		}
			PtButton
			{
				PgColor arm_color
				int arm_fill
				String arm_data
				PhImage arm_image
			}
			PtMenuButton
			{
				String accel_text
				String accel_font
				int button_type
				int offset
			}
			PtText
			{
				int columns
				int cursor_position
				Flag text_flags
				int max_length
			}
			PtMultiText
			{
				Flag multitext_wrap_flags
				Flag multitext_flags
				int multitext_line_spacing
			}
			PtToggleButton
			{
				PgColor set_color
				int set_fill
				int indicator_color
				int indicator_type
				int spacing
				int indicator_depth
				int indicator_width
				int indicator_height
			}
				PtOnOffButton
				{
					int onoff_state
				}
		PtList
		{
			String[] items
			String list_font
			Flag list_flags
			int list_spacing
			int scrollbar_width
			int sel_indexes
			int sel_mode
			PgColor selection_fill_color
			PgColor selection_text_color
			int top_item_pos
			int visible_count
		}
		PtMeter
		{
			int meter_minimum
			int meter_maximum
			int meter_position
			int meter_top_width
			int meter_bot_width
			int meter_height
			PgColor meter_center_color
			int meter_start_angle
			int meter_end_angle
			int meter_use_bfill
		}
		PtPixel
		{
			int dummy
		}
		PtRaw
		{
			int dummy
		}
		PtScrollbar
		{
			int increment
			int maximum
			int minimum
			int page_increment
			int scroll_position
			Flag scrollbar_flags
			int show_arrows
			int slider_size
		}
		PtSeparator
		{
			Flag sep_flags
			int sep_orientation
			int sep_type
		}
		PtTrend
		{
			int[] trend_data
			Flag trend_flags
			PgColor trend_grid_color
			int trend_grid_horiz
			int trend_grid_vert
			int trend_inc
			int trend_max
			int trend_min
		}
		RtTrend
		{
			int[][] rttrend_data
			int trend_grid_x
			int trend_grid_y
			int trend_count
			Flag rttrend_flags
			PgColor trend_grid_color
			int trend_max
			int trend_min
			int trend_inc
			PgColor trend_color_list
			int[] trend_attributes
		}


3.  Registered Version
======================

3.1  List Functions
===================

(difference list1 list2)	- find all elements of list2 not in list1
(intersection list1 list2)	- find all elements in both list1 and list2
(union list1 list2)		- all elements in either list1 or list2
(sort list-or-array		- sort a list or array according to a function
      compare-function)

3.2  Output Functions
=====================

(pretty-write file s-exp...)	- beautified machine-readable output to file
(terpri-context context)	- write a carriage return to an output context
(write file s-exp...)		- machine-readable output to file
(writec file s-exp...)		- human-readable output to file
(write-context context s-exp...)- human-readable output to an output context

3.3  Miscellaneous Functions
============================

(conf s-exp)			- confidence of an expression
(gensym prefix-string)		- generate a symbol guaranteed not to exist
(set-conf s-exp number|s-exp)	- set the confidence for an expression
(system command-line)		- perform a command in the operating system


3.4  String functions
=====================

(format format-string		- printf-style formatting, returns string
	&optional argument...)
(strchr string char-as-string)	- find index of a character in a string
(strcmp string string)		- compare two strings, return number
(stricmp string string)		- case-insensitive comparison of 2 strings
(string-split string delimiters	- split a string at separators
	      max-words)
(string= string string)		- compare two strings, return T or nil
(strlen string)			- length of a string
(strncmp string string length)	- compare 2 strings for a limited length
(strnicmp string string length)	- case-insensitive strncmp
(strrchr string char-as-string)	- find index from end of a char. in a string
(strrev string)			- reverse of a string
(strstr string1 string2)	- find index of string2 in string1 
(substr string start-index	- substring of a string
	length)
				  
3.5  File system functions
==========================

(cd path)			- change current working directory
(file-date filename)		- modification date of a file
(file-size filename)		- size of a file in bytes
(flush file)			- flush output on a file
(is-busy filename)		- t if file is busy
(is-readable path)		- t if path is readable
(is-writable path)		- t if path is writable
(path-node path)		- extract the node from a path
(read-double file)		- read one double in binary format from a file
(read-float file)		- read one float in binary format from a file
(read-until file delimiters)	- read until any delimiter is reached
(rename filename new-name)	- rename a file
(string-file-buffer file)	- the buffer of a string file, as string 
(tmpfile file-prefix)		- create a temporary file
(unlink filename)		- delete a file
(unread-char file char)		- put a character back onto a file


3.6  Advanced Math Functions
============================

(exp number)			- e to the number power
(log number)			- natural logarithm
(log10 number)			- logarithm base 10
(logn base number)		- logarithm base n
(pow base exponent)		- base to the exponent
(round number)			- round to the nearest integer
(sqr number)			- square of a number
(sqrt number)			- square root of a number

3.7  Trigonometric Functions
============================

(acos number)			- arc cosine in radians
(asin number)			- arc sine in radians
(atan number)			- arc tangent in radians
(atan2 y x)			- arc tangent of y/x with bounds checking
(cos number)			- cosine of radians
(sin number)			- sine of radians
(tan number)			- tangent of radians

3.8  QNX IPC Functions
======================

(qnx_name_attach node name)	- attach a name, return name id
(qnx_name_detach name_id)	- detach a name
(qnx_name_locate node name	- locate a name, return task id
		 size)
(qnx_vc_attach node taskid	- attach a virtual circuit, return task id
	max-msg-length flags)
(qnx_vc_detach taskid)		- detach a virtual circuit
(qnx_vc_name_attach node	- attach a vc by name, return task id
	max-msg-length name)
(qnx_send taskid message)	- send a string message to a task
(qnx_receive taskid)		- receive string message from task id
(qnx_reply taskid message)	- reply to taskid with string


4.  Commercial Version
======================

4.1  Encapsulated QNX IPC
=========================

(close-task task)		- stop talking to a task
(flush-events)			- flush all incoming events
(init-async-ipc other-task)	- initialize asynchronous IPC with a task
(init-ipc my-name		- initialize IPC
	  my-queue-name)
(isend task s-exp)		- send a message, ignore the result
(locate-task task-name		- locate a task by name
	     async-reqd)
(locate-task-id task id node	- locate a task by ID
		async-reqd)
(name-attach task-name)		- attach a name in the name server
(send task s-exp)      		- send a message and return the reply
(send-async task s-exp)		- send a message asynchronously
(send-string task string)	- send a string
(send-string-async task string)	- send a string asynchronously


5.  Control Version
===================

5.1  Real-time database Functions
=================================

(add-echo-function symbol	- attach code to a database echo event
		   s-exp)
(add-exception-function symbol	- attach code to a database value change event
			s-exp)
(read-existing-point symbol)	- read a database point if it exists
(read-point symbol)		- read a database point, creating if necessary
(register-existing-point	- register a database point if it exists
		symbol)
(register-point symbol)		- register a point, creating if necessary
(remove-echo-function symbol	- remove a database echo function
		      s-exp)
(remove-exception-function	- remove a database exception function
		symbol s-exp)
(set-domain domain-name)	- set this task's default database domain
(when-echo-fns symbol)		- query database echo functions for symbol
(when-exception-fns symbol)	- query database exception functions for symbol
(write-existing-point symbol	- write a database point if it exists
		      value)
(write-point symbol value)	- write a point, creating if necessary


6.  Specialty Versions
======================

6.1  ProcessVision functions
============================

(pv-declare-hist triplet period	- declare a historical triplet
		 interval)
(pv-get-hist triplet		- find the value of a historical triplet
	     seconds-ago)
(pv-message message		- send a message to mg_admin
	    message-class)
(pv-put-hist triplet value	- write a historical triplet value
	     certainty)
(pv-read-point symbol)		- read a point in the database
(pv-set-cluster cluster-name)	- set the default cluster for this task
(pv-write-point symbol value)	- write a point in the database


7.  Usage Tips
==============

7.1  The Main Event Loop
========================

In Photon, the main event loop can be entered through the function
(PtMainLoop).  In either Photon or QNX Windows, the following
construct can be used, and gives greater flexibility.  The loop can be
conditionally terminated, an action can be performed after every
event, or the loop may be wrapped in an (unwind-protect ...) construct:

	(while t (next-event))

7.2  Processing all Waiting Events
==================================

If you wish to process all waiting events and then continue, you can
use the construct:

	(while (not (undefined-p (next-event-nb))) t)

7.3  Loading Photon Application Builder .wgtw Files
===================================================

There should be a library file included with this release named
"readwgt.lsp" which will read a PhAB .wgtw file and display a window
based on that file.  To use this, include the line:

	(require "readwgt")

near the top of your file.  Subsequently, a call to the function:

	(wload "filename")

will load a .wgtw file and display it as a window on the screen.  If
the file "readwgt.lsp" is in the directory /usr/lib/scadalisp/lib or
in a directory named in the *require-path* global variable, then
SCADALisp will automatically find it.


7.4  Getting On-Line Help for Functions
=======================================

SCADALisp can display function definitions and parameters.  To do
this, start SCADALisp interactively and type the name of the function
followed by return.  For example,
 
	andrewt@1:~> scadalisp
	SCADALisp - Real-time LISP for Process Control
	Copyright (C) Sakura Software Inc., 1994.  All rights reserved.
	Serial #SS000000DEMO
	       Unlicensed Version
	       For demonstration purposes only.
	lisp> init-ipc
	(defun init-ipc (my-name my-queue-name) ...)
	lisp> new
	(defun new (class) ...)
	lisp> cond
	(defun cond (&rest &noeval cond/actions) ...)
	lisp> insert
	(defun insert (array position-or-function value) ...)

7.5  Examining the Instance Variables in a Class or Instance
============================================================

Classes and instances can be examined in two ways.  For a class, you
can simply type the name at the prompt.  If the class is bound to a C
structure, you will get no information.  You will then have to use the
(instance-vars) function.  To examine an instance of a class, simply
type an expression which evaluates to that instance (usually the
variable named in which it's stored).

	 lisp> PhImage
	 #<Binary Class: PhImage>

	 lisp> (instance-vars PhImage)
	 [(bpl) (colors) (flags) (format) (image) (image_tag) (palette) \
	  (palette_tag) (size) (type) (xscale) (yscale)]

	 lisp> (setq x (new PhImage))
	 {PhImage (bpl . 0) (colors . 0) (flags . 0) (format . 0) (image . \
	 (buffer )) (image_tag . 0) (palette . []) (palette_tag . 0) (size . \
	 {PhDim (h . 0) (w . 0)}) (type . 0) (xscale . 0) (yscale . 0)}

 	 lisp> x
	 {PhImage (bpl . 0) (colors . 0) (flags . 0) (format . 0) (image . \
	 (buffer )) (image_tag . 0) (palette . []) (palette_tag . 0) (size . \
	 {PhDim (h . 0) (w . 0)}) (type . 0) (xscale . 0) (yscale . 0)}

 	 lisp> (instance-vars x)
	 [(bpl . 0) (colors . 0) (flags . 0) (format . 0) (image . (buffer )) \
	 (image_tag . 0) (palette . []) (palette_tag . 0) (size . {PhDim (h . \
	 0) (w . 0)}) (type . 0) (xscale . 0) (yscale . 0)]

 	 lisp> (pretty-princ x "\n")
	 {PhImage (bpl . 0) (colors . 0) (flags . 0) (format . 0)
	  (image . (buffer )) (image_tag . 0) (palette . [])
	  (palette_tag . 0) (size . {PhDim (h . 0) (w . 0)}) (type . 0)
	  (xscale . 0) (yscale . 0)}
	 t


7.6  Undefined symbols
======================

In SCADALisp a variable must be assigned a value.  A variable which is
used but never assigned a value will cause an Undefined Symbol error.
Simple assignment using set, setq or setqq is sufficient to define the
variable within its scope.

7.7  Dynamic Scope
==================

Unlike many procedural languages such as C and Pascal, SCADALisp uses
dynamic scoping.  That means that if a function defines a local
variable, then that variable becomes global to any functions that it
calls.  If the function was previously defined in a higher call, or at
the global level, then the value used will be the value of the local
variable most recently declared in the calling sequence.  The scope of
the variable is thus determined at run-time by the order in which
functions were called.  This is very different from the convention in
C known as lexical scoping, where the scope of a variable is
determined according to the syntactic position in a program where it
is declared.

7.8  Properties and Scoping
===========================

Properties are associated with a symbol, not the scope of that symbol.
This means that if a variable property is set in the global scope, it
will be available to any local variables of the same name in lower
scopes.

7.9  Forward and Back Quote Syntax
==================================

The syntax of the forward and back quotes is slightly confusing, and
very important, particularly when assigning event functions such as
Photon callbacks and database value change events.

A forward quote causes the next LISP item to be protected from the
evaluator, turning it into a literal.  For example:

	lisp> (setq x "hello")
	"hello"
	lisp> x
	"hello"
	lisp> 'x
	x
	lisp>

In this case, the forward quote was used to produce the literal symbol
x instead of the value for x.  Another example:

	lisp> (+ 5 6)
	11
	lisp> '(+ 5 6)
	(+ 5 6)
	lisp>

Here the forward quote protected the entire list (+ 5 6) from the
evaluator.  A quote always protects an entire expression.

The back quote is used to construct a literal in which some portions
of the literal must be evaluated.  This is done using back quote,
comma and comma-at combinations:

	lisp> `(+ 5 6)			; acts like forward quote
	(+ 5 6)
	lisp> `(+ ,(/ 10 2) 6)		; evaluates (/ 10 2) within quote
	(+ 5 6)
	lisp>

Here the comma is used within the back quoted expression to cause a
sub-expression to be evaluated.  Any sub-expression can be evaluated
in this manner, to any degree of complexity.  More than one comma can
appear in a back quoted expression.

Sometimes comma evaluation results in a list.  This would behave as follows:

	lisp> (setq x '(a b c))
	(a b c)
	lisp> `(1 ,x 2)
	(1 (a b c) 2)
	lisp>

It may be useful at some point to have the result of the comma
evaluation be spliced into the result rather than be a sub-element.
This is done using the comma-at directive:

	lisp> (setq x '(a b c))
	(a b c)
	lisp> `(1 ,@x 2)
	(1 a b c 2)
	lisp>

The burning question is: why would you ever use back quote notation?
Generally back quoting is used when you wish to create a literal piece
of LISP code to pass as an argument to a function.  For example,
suppose we are trying to tie a callback to a Photon PtButton:

	lisp> (setq button (new PtButton))
	<button-definition>
	lisp> (PtAttachCallback button
				Pt_CB_ACTIVATE `(do-button-function ,button))
	t
	lisp>

This example will cause a PtButton to be created and will cause the
piece of code (do-button-function <button-definition>) to be called.
If we had used the piece of code:

	lisp> (PtAttachCallback button
				Pt_CB_ACTIVATE '(do-button-function button))

then the code to be executed would be (do-button-function button).
The variable "button" would not be evaluated until the callback was
called.  The variable "button" may have changed value or be out of
scope when the callback is called, producing an incorrect result.  We
could have coded this without the back quote.  It would look like this:

	lisp> (PtAttachCallback button Pt_CB_ACTIVATE
				(list 'do-button-function button))

This seems a little harder to interpret.  If the callback function has
more than one level of lists, this method quickly becomes unmanageable.


7.10 Using the debug> Prompt
============================

The debug> prompt appears when an error occurs in interactive mode.
It halts execution of the program and produces a prompt.  You can
query the calling stack using the (stack) function.  You can query the
value of any variable simply by typing its name.  You can perform any
action at the debug> prompt that you can perform at the top level,
including modifying program source and setting variable values.  Once
the debug> prompt appears, the program cannot be continued.  You must
re-start the program.

7.11 Getting Rid of the debug> Prompt
=====================================

You can move up a debug level by pressing CTRL-D at the debug prompt.

7.12 Literal Array Syntax
=========================

Arrays are implemented in SCADALisp using square brackets [] for
literal arrays and the functions array, make-array, aref and aset for
dynamic creation and manipulation.  Note the difference between the []
syntax and the array function:

	lisp> [(+ 5 6) (- 4 2) 72]
	[(+ 5 6) (- 4 2) 72]
	lisp> (array (+ 5 6) (- 4 2) 72)
	[11 2 72]
	lisp>

Generally, you should avoid literal arrays except for static
variables.  A literal array is embedded into your code.  If you change
it, you are effectively changing your code!

7.13 Literal Instance Syntax
============================

Literal instances of classes are implemented using curly braces {}.
For example, a PhPoint instance may be {PhPoint (x . 5) (y . 10)}.
Note that nothing is evaluated within {}, and back quote syntax will
not cause anything to be evaluated.  A literal instance within your
code will cause the instance constructor to be called at read-time.
Be sure the class is fully defined before you read code with a literal
instance in it.  The resulting instance will be embedded into your
code.  Subsequent changes to the instance will be effectively changing
your code!

Literal instances are generally used for file storage.  They can also
act as static local variables, though this can sometimes cause
confusion.

7.14 Passing Arguments to SCADALisp Programs
============================================

Please see the file INSTALL for a discussion of the command line
arguments.  This file includes an example of how to pass command line
arguments to a SCADALisp program.

7.15 Making Stand-Alone Programs with SCADALisp
===============================================

There is currently no facility for embedding LISP source into a
SCADALisp executable.  However, it is possible to create a SCADALisp
program which appears to be a stand-alone executable to the user.
This is done by using the shell's #! directive at the top of the LISP
file.  Simply include the line:

	#!/usr/lib/scadalisp/bin

at the top of a LISP file, and change the permissions on the LISP file
to be executable.  You can now run the LISP file directly as if it
were a stand-alone executable.  Any command line arguments will be
passed to the LISP program in the list variable argv.


8.  Situations which might cause SCADALisp to crash
===================================================

1) A call to (init-ipc) inside a timer or signal handling routine.
   You should call (init-ipc) once at the beginning of your program if
   at all.

2) Abuse of Photon widget resources.  While care has been taken to
   minimize the risk of a crash by abusing the Photon widgets, the
   bottom line is that widgets are raw C structures with fairly
   complex manipulation functions.  If you write a bad value into a C
   structure, your program will crash.  If you fail to call PtInit,
   your program will crash.  If you create a non-window widget with no
   parent, your program will crash.  These are just facts of life.

Having said these things, we are always interested in hearing about
new ways that we can make SCADALisp more robust.  Please don't
hesitate to let us know if you find a weak spot.

