Gamma™

Version 4.0

Jan 07, 2003

Gamma is a dynamically-typed interpreted programming language that has been specifically designed to allow rapid development of control and user interface applications. Gamma has a syntax similar to C and C++, but has a range of built-in features that make it a far better language for developing sophisticated real-time systems.

With version 4.0, Cogent software now includes source-code compatibility among the QNX 4, QNX 6 and Linux operating systems, a reorganized and expanded API, and other improvements. Version 4.0 of Cogent's tools will not interoperate with version 3 or older. This documentation has been edited and reorganized to reflect those changes. For documentation of Cogent software version 3.x, please contact Cogent Real-Time Systems, Inc.

Go to the Cogent Web Site.

Table of Contents

I. Programmers Manual

1. Introduction

1.1. What is Gamma?
1.2. Assumptions about the Reader
1.3. System Requirements
1.4. Download and Installation
1.5. Where can I get help?

2. Getting Started

2.1. Interactive Mode
2.2. Executable Programs
2.3. Symbols and Values

3. Basic Data Types and Mechanisms

3.1. Numeric Types
3.2. Logical Types
3.3. Strings
3.4. Lists and Arrays
3.5. Constants
3.6. Operators and Expressions
3.7. Comments
3.8. Reserved Words
3.9. Memory Management

4. Tutorial I

4.1. Lists
4.2. "Hello world" program

5. Control Flow

5.1. Statements
5.2. Function Calls
5.3. Event Handling
5.4. Error Handling

6. Tutorial II

6.1. Error Handling - try/catch, protect/unwind
6.2. Dynamic Scoping
6.3. Error Handling - interactive session

7. Functions and Program Structure

7.1. Function Definition
7.2. Function Arguments
7.3. Function Renaming
7.4. Loading files
7.5. The main Function
7.6. Executable Programs
7.7. Running a Gamma Program
7.8. Command Line Arguments

8. Object Oriented Programming

8.1. Classes and Instances
8.2. Methods
8.3. Inheritance
8.4. Instance Variables
8.5. Class Variables
8.6. Constructors and Destructors
8.7. Polymorphism
8.8. Binary Classes and User Classes

9. Tutorial III

9.1. Classes and OOP

10. Interactive Development and Debugging

10.1. Interactive Mode Implementation
10.2. Getting On-Line Help for Functions
10.3. Examining Variables in a Class or Instance
10.4. Using the Debug Prompt
10.5. Debugging a program

11. Advanced Types and Mechanisms

11.1. Symbols
11.2. Evaluation
11.3. Literal Syntax and Evaluation

12. Input and Output

12.1. Referencing Files
12.2. Lisp and Gamma I/O mechanisms
12.3. Writing
12.4. Reading

13. Special Topics

13.1. Modifying QNX Process Environment Variables
13.2. QNX 4 Interprocess Communication (IPC)
13.3. Cogent IPC

A. Function List

II. Reference

I. Symbols and Literals

Data Types and Predicates -- testing for data types.
undefined_p, undefined_symbol_p -- test for undefined types and symbols.
Literals -- defined for integers, reals, strings, and symbols.
Predefined Symbols -- a table.
Reserved Words -- a table.
nil -- the logically false value.
gamma, phgamma -- start Gamma and Gamma/Photon from the shell prompt.
t -- a logically true value.

II. Operators

Operator Precedence and Associativity -- a table.
Arithmetic Operators -- (+, -, *, /, %)
Assignment Operators -- (=, :=, ::=)
Binary Operator Shorthands -- (+=, -=, *=, /=, %=, &=, ^=, <<=, >>=)
Bitwise Operators -- (<<, >>, ~ , &, |, ^)
Class Operators -- (., ..)
Comparison Operators -- (!=, <, <=, ==, >, >=, )
Evaluation Order Operators -- , ( )
Increment and Decrement Operators -- (++, --)
Logical Operators -- (!, &&, ||)
Quote Operators -- (#, `, @)
Ternary Operator -- ( ? : )

III. Statements

class -- defines a class.
condition -- tests conditions.
for -- checks a condition and performs a statement.
function -- creates a new function.
if -- conditionally evaluates statements.
local -- allows for implementing local variables within functions.
method -- defines a method for a given class.
progn, prog1 -- group several statements into one expression.
protect unwind -- evaluates protected code, despite errors.
switch -- tests arguments with conditions.
try catch -- catches errors in the body code.
while -- iterates, evaluating a statement.
with -- traverses an array or list performing a statement.

IV. Core Functions

call -- calls a class method for a given instance.
class_add_cvar -- adds new class variables.
class_add_ivar -- adds an instance variable to a class.
class_name -- gives the name of the class.
class_of -- gives the class definition of a given instance.
defclass -- is the function equivalent of the class statement.
defmacro, defmacroe -- are the Lisp equivalents of the macro function.
defun, defune, -- are the function equivalents of the function statement.
defmethod -- is the function equivalent of the method statement.
defvar -- defines a global variable with an initial value.
destroy -- destroys a class instance.
eq, equal -- compare for identity and equivalence.
error -- redirects the interpreter.
eval -- evaluates an argument.
eval_list -- evaluates each element of a list.
eval_string -- evaluates a string.
funcall -- provides compatibility with other Lisp dialects.
function_args -- lists the arguments of a function.
function_body -- gives the body of a user-defined function.
function_name -- gives the name of a function.
getprop -- returns a property value for a symbol.
has_cvar -- queries for the existence of a class variable.
has_ivar -- queries for the existence of an instance variable.
instance_vars -- finds all the instance variables of a class or instance.
is_class_member -- checks if an instance or class is a member of a class.
ivar_type -- returns the type of a given instance variable.
macro -- helps generate custom functions.
new -- creates a new instance of a class.
parent_class -- returns the closest parent (base) of a class or instance.
print_stack -- prints a Gamma stack.
properties -- should never be used.
quote, backquote -- correspond to Quote Operators.
require, load -- load files.
set, setq, setqq -- assign a value to a symbol.
setprop -- sets a property value for a symbol.
setprops -- lists the most recent property value settings.
trap_error -- traps errors in the body code.
unwind_protect -- ensures code will be evaluated, despite errors in the body code.
whence -- gives input information.

V. Lists and Arrays

append -- concatenates several lists into a single new list.
aref -- returns an array expression at a given index.
array -- constructs an array.
array_to_list -- converts an array to a list.
aset -- sets an array element to a value at a given index.
assoc, assoc_equal -- search an association list for a sublist.
bsearch -- searches an array or list for a element.
car, cdr, and others -- return specific elements of a list.
cons -- constructs a cons cell.
copy -- makes a copy of the top list level of a list.
copy_tree -- copies the entire tree structure and elements of a list.
delete -- removes an element from an array.
difference -- constructs a list of the differences between two lists.
find, find_equal -- search a list using the eq and equal functions.
insert -- inserts an array value at a given position.
intersection -- constructs a list of all the elements found in both of two lists.
length -- counts the number of elements in a list or array.
list, listq -- create lists.
list_to_array -- converts a list to an array.
make_array -- creates an empty array.
nappend -- appends one or more lists, destructively modifying them.
nremove -- removes list items, destructively altering the list.
nreplace, nreplace_equal -- replace elements in a list.
nth_car, nth_cdr -- iteratively apply the car and cdr functions to a list.
remove -- removes list items without altering the list.
reverse -- reverses the order of list elements.
rplaca, rplacd -- replace the car and cdr of a list.
shorten_array -- reduces or expands the size of an array.
sort -- sorts a list or array, destructively modifying the order.
union -- constructs a list containing all the elements of two lists.

VI. Strings and Buffers

bdelete -- deletes a single character from a buffer.
binsert -- inserts a value into a buffer.
buffer -- constructs a buffer.
buffer_to_string -- converts a buffer to a string.
format -- generates a formatted string.
make_buffer -- creates a new, empty buffer.
open_string -- allows a string to be used as a file.
parse_string -- parses an input string.
raw_memory -- tells the amount of memory in use.
shell_match -- compares string text to a pattern.
shorten_buffer -- reduces the size of a buffer.
strchr, strrchr -- search a string for an individual character.
strcmp, stricmp -- compare strings.
string -- constructs a string.
stringc -- constructs a string in Lisp-readable form,
string_file_buffer -- queries a string file for its internal buffer.
string_split -- breaks a string into individual words.
string_to_buffer -- creates a buffer object from a string.
strlen -- counts the number of characters in a string.
strncmp, strnicmp -- compare two strings and return a numeric result.
strrev -- reverses the order of characters in a string.
strstr -- finds the location of a given substring.
substr -- returns a substring for a given location.
tolower -- converts upper case letters to lower case.
toupper -- converts lower case letters to upper case.

VII. Data Type Conversion

bin -- converts numbers into binary form.
char -- generates an ASCII character from a number.
char_val -- generates a character's numeric value.
dec -- converts numbers into base-10 form.
hex -- converts numbers into hexadecimal form.
int -- converts to integer form.
number -- attempts to convert an expression to a number.
oct -- converts numbers into octal form.
symbol -- constructs a symbol from a string.

VIII. Math

acos, asin, atan, atan2 -- perform trigonometric arc functions.
and, not, or -- are the same as the corresponding Logical Operators.
band, bnot, bor, bxor -- perform bitwise operations.
ceil -- rounds a real number up to the next integer.
cfand, cfor -- perform and and or functions with confidence factors.
conf, set_conf -- query and set confidence factors.
cos, sin, tan -- perform trigonometric functions.
div -- divides, giving an integer result.
exp -- calculates an exponent of the logarithmic base (e).
floor -- rounds a real number down to its integer value.
log, log10, logn -- calculate logarithms.
neg -- negates.
pow -- raises a base to the power of an exponent.
random -- generates random numbers from 0 to 1.
round -- rounds a real number up or down to the nearest integer.
set_random -- starts random at a different initial number.
sqr -- finds the square of a number.
sqrt -- finds the square root of a number.

IX. Input/Output

close -- closes an open file.
fd_close -- closes a file identified by a file descriptor.
fd_data_function -- attaches a write-activated callback to a file.
fd_eof_function -- attaches an eof-activated callback to a file.
fd_open -- opens a file or device and assigns it a file descriptor.
fd_read -- reads a buffer or string from a file identified by a file descriptor.
fd_to_file -- creates a file pointer from a descriptor.
fd_write -- writes a buffer or string to a file identified by a file descriptor.
fileno -- creates a file descriptor from a pointer.
ioctl -- performs control functions on a file descriptor.
open -- attempts to open a file.
pipe -- creates a pipe.
princ, print, pretty_princ, pretty_print -- write to the standard output file.
pty, ptytio -- run programs in a pseudo-tty.
read -- reads a Lisp expression from a file.
read_char, read_double, read_float, read_long, read_short -- read the next character, double, float, long or short value in binary representation from the input file.
read_eval_file -- reads a file, evaluating and counting expressions.
read_line -- reads a single line of text.
read_n_chars -- reads and stores characters.
read_until -- reads characters, constructing a string as it goes.
seek -- sets the file position for reading or writing.
ser_setup -- sets parameters for a serial port device.
tell -- indicates file position.
terpri -- prints a newline to an open file.
unread_char -- attempts to replace a character to a file for subsequent reading.
write, writec, pretty_write, pretty_writec -- write an expression to a file.
write_n_chars -- writes characters from a buffer to a file.

X. File System

absolute_path -- returns the absolute path of the given file.
access -- checks a file for various permissions.
basename -- gives the base of a filename.
cd -- changes the working directory.
chars_waiting -- checks for characters waiting to be read on a file.
directory -- returns the contents of a directory.
dirname -- returns the directory path of a file.
drain -- modifies end-of-file detection.
file_date -- gives the file modification date.
file_size -- gives the file size.
flush -- flushes any pending output on a file or string.
getcwd -- gets the current working directory.
is_busy -- determines if a file is busy.
is_dir -- determines if a file is a directory.
is_file -- determines if a file exists.
is_readable -- determines if a file is readable.
is_writable -- determines if a file is writable.
mkdir -- creates a new sub-directory.
path_node -- gives the node number of a path in a QNX 2 path definition.
rename -- renames a file.
root_path -- strips the final file or directory name from a path.
tmpfile -- generates temporary output file names.
unbuffer_file -- causes a file to be treated as unbuffered on both input and output.
unlink -- deletes a file.

XI. OS APIs

atexit -- evaluates code before exiting a program.
block_signal, unblock_signal -- delimit signal blocking.
errno -- detects and numbers errors.
exec -- executes a program.
exit_program -- terminates the interpreter.
fork -- duplicates a process.
getenv -- retrieves the value of an environment variable.
gethostname -- gets the computer's host name.
getnid -- returns the local node number.
getpid -- returns the program ID.
getsockopt, setsockopt -- get and set a socket option.
kill -- sends a signal to a process.
nanosleep -- pauses the interpreter for seconds and nanoseconds.
setenv -- sets an environment variable for the current process.
shm_open -- opens shared memory objects.
shm_unlink -- removes shared memory objects.
signal -- defines an expression to be evaluated at an OS generated signal.
sleep, usleep -- suspend execution.
strerror -- retrieves an error message.
system -- treats its argument as a system command.
wait -- waits for process exit status.

XII. Dynamic Loading

AutoLoad -- allows for run-time symbol lookup.
autoload_undefined_symbol -- checks undefined symbols for AutoLoad.
AutoMapFunction -- maps a C function to a Gamma function.
ClearAutoLoad -- removes all AutoLoad rules.
dlclose -- closes an open dynamic library.
dlerror -- reports errors in dl functions.
dlfunc -- reserved for future use.
DllLoad -- loads dynamic libraries.
dlmethod -- reserved for future use.
NoAutoLoad -- removes selected AutoLoad rules.
dlopen -- loads a dynamic library from a file.

XIII. Profiling and Debugging

allocated_cells -- gives the number of allocated and free cells.
eval_count -- counts evaluations made since a program started.
free_cells -- returns the number of available memory cells.
function_calls -- tells how often a function was called during profiling.
function_runtime -- gives the time a function has run during profiling.
gc -- runs the garbage collector.
gc_blocksize -- for internal use only.
gc_enable -- for internal use only.
gc_newblock -- for internal use only.
gc_trace -- controls the tracing of garbage collection.
profile -- collects statistics on function usage and run time.
set_autotrace -- is reserved for future use.
set_breakpoint -- is reserved for future use.
time -- gives command execution times.
trace, notrace -- turn tracing on or off.

XIV. Miscellaneous

apropos -- finds all defined symbols in the current interpreter environment.
create_state, enter_state, exit_state -- are part of the SCADALisp exception-driven state machine mechanism.
gensym -- generates a unique symbol.
modules -- is obsolete, and returns nothing of value.
stack -- lists all functions called so far.

XV. IPC

add_hook -- hooks a function to an event.
close_task -- closes a task opened by locate_task.
_destroy_task -- should never be used.
init_async_ipc -- requests queue information from a task.
init_ipc -- sets up necessary data structures for IPC.
isend -- sends a synchronous message and doesn't wait for the result.
locate_task -- finds and connects to tasks by name.
locate_task_id -- finds and connects to tasks by task ID and network node.
name_attach -- attaches a name to a task.
nserve_query -- puts information from nserve into an array.
remove_hook -- removes a hooked function.
run_hooks -- runs a hooked function.
send -- transmits expressions for evaluation.
send_async -- transmits expressions asynchronously.
send_string -- transmits strings for evaluation.
send_string_async -- transmits a string asynchronously.
taskdied, taskstarted -- internal functions that call another function when a task starts or stops.
task_info -- gets information from a task descriptor.

XVI. Events and Callbacks

add_set_function -- sets an expression to be evaluated when a given symbol changes value.
flush_events -- handles all pending events, then exits.
next_event, next_event_nb -- wait for an event and call the event handling function.
remove_set_function -- removes a set function from a symbol.
when_set_fns -- returns all functions set for a symbol.

XVII. Time, Date, and Timers

after -- performs an action after a period of time.
at -- performs an action at a given time, or regularly.
block_timers, unblock_timers -- block and unblock timer firing.
cancel -- removes a timer from the set of pending timers.
clock, nanoclock -- get the OS time.
date -- gets the OS date and time; translates seconds into dates.
date_of -- is obsolete, see date
every -- performs an action every number of seconds.
timer_is_proxy -- controls timer handling in Gamma.

XVIII. Cascade DataHub

add_exception_function, add_echo_function -- assign functions for exceptions or echoes on a point.
lock_point -- locks or unlocks points.
point_locked -- indicates if a point is locked.
point_nanoseconds -- gives the nanoseconds from point_seconds that a point value changed.
point_seconds -- gives the time the point value changed.
point_security -- gives the security level of a point.
read_existing_point, read_point -- retrieve points.
register_all_points -- registers an application to receive exceptions for all points.
register_exception -- not yet documented.
register_point, register_existing_point -- register an application to receive exceptions for a single point.
remove_echo_function -- removes an echo function from a symbol.
remove_exception_function -- removes an exception function from a symbol.
secure_point -- alters the security level on a point.
set_domain -- sets the default domain for future calls.
set_security -- changes the security level for the current process.
unregister_point -- stops echo and exception message sending.
when_echo_fns, when_exception_fns -- indicate the functions for echos or exceptions on a point.
write_existing_point, write_point -- write point values.

XIX. QNX 4

dev_read -- is a modification of QNX 4 dev_read.
dev_setup -- is obsolete, see ser_setup.
inp, inpw -- query hardware ports.
mmap -- implements the C mmap function call.
outp, outpw -- write values to hardware ports.
qnx_name_attach -- registers a local or global name.
qnx_name_detach -- detaches a name.
qnx_name_locate -- is an implementation of the C function qnx_name_locate.
qnx_osinfo -- returns a class very similar to QNX 4 struct_osinfo.
qnx_osstat -- lists processor loads and number of READY processes at each priority level.
qnx_proxy_attach -- creates a proxy message for a process.
qnx_proxy_detach -- removes a proxy.
qnx_proxy_rem_attach -- creates a remote proxy message for a task.
qnx_proxy_rem_detach -- removes a remote proxy.
qnx_receive -- performs a QNX 4 Receive.
qnx_reply -- replies to qnx_receive messages.
qnx_send -- implements QNX 4 Send.
qnx_spawn_process -- is an implementation of the C function qnx_spawn.
qnx_trigger -- tells a proxy to send its message.
qnx_vc_attach -- establishes a virtual circuit between two processes on two computers.
qnx_vc_detach -- detaches a virtual circuit.
qnx_vc_name_attach -- attaches a virtual circuit with a name instead of a process ID number.

Index

Colophon

List of Tables
10-1. Global Variables in Gamma
11-1. Type Evaluation
1. Data Types and Related Predicates
1. Integers
2. Real numbers
3. Strings
4. Symbols
5. Other Data Types
1. Symbols that are predefined in Gamma
1. Words reserved in Gamma
1. Operator Precedence and Associativity
1. User/owner permission modes
2. Group permission modes
3. Other permission modes
1. Signals
1. dev_read min, time, and timeout values

Prev	Home	Next
Cogent Documentation		Programmers Manual