\begindata{text,538478900}
\textdsversion{12}
\template{help}
\define{global
}
\define{sans
menu:[Font,Sans]
attr:[FontFamily AndySans Int 0]}
\chapter{Ness: An Extension Language for the Andrew Toolkit

}

\section{What is Ness?


}\leftindent{Ness is a programming language and associated system based 
upon the Andrew Toolkit (\italic{\helptopic{ATK}}).  It can be used to 
create stand-alone Ness programs or to create Ness scripts, which are 
programs that are embedded in an ATK document or application.  Ness is 
particularly suited to extending existing ATK objects and string-processing 
applications.  \



Examples of Ness programs and scripts created so far include databases, 
document formatting converters, new key definitions and menu functions for 
EZ, an expandable calculator, and combined music/text/animation programs 
that can be sent and executed in Messages.  Many of these programs and 
scripts have been created using objects available from the Andrew 
Development Environment Worksheet (\italic{\helptopic{ADEW}}).


This help file contains some warnings about using Ness, some pointers on 
using Ness for both non-programmers and programmers, a Quick Reference of 
Ness compilation methods and access levels for programmers, and more 
detailed instructions on running and compiling Ness programs and scripts 
for non-programmers.

}
\section{Warnings

}
\leftindent{A Ness script is a program.  Like any program it can modify the 
files of a user who executes it.  Therefore you should be careful to use 
scripts that come from people you know and trust.  Before a script within a 
document will do anything, you must select the "Empower" option, either 
from the script or from the dialog box.  See the section on 
\section{Running a Ness Script from EZ or Messages}.}


\section{Using Ness:  Non-programmers


}\leftindent{If you are not a programmer, you may still want to know a few 
things about Ness.  In particular, you will want to know how to:


1.  Read a message or EZ file that contains a Ness script.


2.  Run a Ness program someone has created from the Typescript window or 
other command window.


Both these operations are described in this help document.}


\section{Using Ness:  Programmers}

\leftindent{
}\leftindent{If you are a programmer, in addition to the information above 
on running Ness programs and scripts, you may want to know how to create 
programs and scripts.  You need not have facility in any specific 
programming language to use Ness, but some knowledge of ATK programming and 
ADEW may be useful. The Reference manual for Ness is located in \



		\italic{/usr/andrew/doc/atk/ness/*.doc}


where a guide to the other Ness documents is in nessuser.doc.  For 
information about programming in ATK, see the files in other subdirectories 
of /usr/andrew/doc/atk; especially the examples subdirectory.}


\section{Running a Ness Script from EZ or Messages}

\leftindent{
A Ness script within a message, document, or application will look like a 
piece of text with a scroll bar.  Usually the text will begin, "\bold{NESS} 
- This inset is a Ness script.  If ...", and will continue with a 
description of the hazards and options for "Empowering" the script.  If you 
do not empower the script, it will be inert and will not affect the 
document or your files.  \



The options are at the end of the scroll, where you can get to them by 
clicking the bottom endzone in the scroll bar.  These are your options:


\sans{\bold{\leftindent{Scan for dangerous statements}}}


The script is checked for potentially dangerous statements.  For each, the 
script is scrolled to the statement, it is highlighted, and a message is 
displayed at the bottom.  To see the next potentially dangerous statement, 
select \bold{NextError} from the \bold{Ness} menu card.  (The system is 
quite paranoid and often identifies as potentially harmful statements that 
are actually entirely innocuous.)


\bold{\sans{\leftindent{Author mode - Let me edit the script}}}


The warning statement is removed from around the script and the script is 
made to be read-write.  You may then modify the script.


\sans{\bold{\leftindent{Empower - I trust the source of this script}}}


This option causes Ness to compile the script and activate any "extend" 
definitions.  Thereafter any extended inset may behave differently from its 
normal behvior in response to your actions.  For instance a mouse click on 
a button might be made to play music.

}
\section{Running a Stand-alone Ness Program from Typescript or Another 
Command Window}


\leftindent{The program /usr/andrew/bin/nessrun is used to compile and 
execute a Ness program.  All Ness program file names should end in a .n 
extension.


If you want to run a Ness program, type the following from your command 
window:


\example{nessrun <program-file-name> <arguments>}


where \example{<program-file-name> }is the name of the Ness program 
and\example{ <arguments>} are any arguments you need to pass along to the 
program (such as another filename).


You are not given any options for deciding whether to trust the Ness 
program;  it is assumed that if you asked it to execute you trust it.

}
\section{Quick Reference

}
\leftindent{To execute a Ness program from your command window:


\example{nessrun <programname> <arguments>}



To insert a Ness script in a document (such as EZ or a SendMessage):


\example{<ESC> <TAB> ness <RETURN>}



To execute a Ness script in a document (EZ or SendMessage):


Select "\bold{Empower}" from the menu or from the end of the text in the 
script.  Then select \bold{DoMain()} from the \bold{Ness} menu card.



To execute a single Ness statement  from applications, first put this line 
in your ~/.atkinit file:


\example{addkey ness-dostmt  \\e\\e  view  }\



then use \example{<ESC> <ESC>} in your application to get the prompt for 
the Ness statement.


Example script:


\leftindent{-- With this script, a button inset named "when" is extended 
with a new behavior for a mouse click.  Whenever the left mouse button goes 
up in this inset, the date is printed in the message line.

--

extend "when" on mouse "any"

	if mouseaction = mouseleftup then

		telluser(system("date"))

	end if

end mouse end extend}


Example program:

\leftindent{
-- This program is executed via

--		nessrun pgm.n filename

-- it reads the file and calls the Ness library function wc_CountWords to 
count the words.  Finally, it prints the count

--

}\leftindent{function \bold{main}(f)

	marker text

	integer cnt

	text := readfile(f)

	cnt := wc_CountWords(text)

	printline("There are " \


		~ textimage(cnt) \


		~ " words in " ~ f)

end function}

}

\section{Pop-Up Menu meanings}


Certain menu options are available only under certain conditions, as noted.


\italic{Ness Menu Card}

\leftindent{
\bold{Next Error:} Highlights the next portion of the Ness script that had 
an error and scrolls the text so it is visible.  If there are no more 
errors, it displays a message; selecting the option again will start over 
with the first error.  This option is available only after an 
\bold{Empower-compile} which had an error or after an error occurs during 
execution.  In the latter case, there will be only one error.



\bold{Show Origin:} Displays in the message line the probable author and 
date of the last modification to the script.  (This value can be forged, 
but no instance of this has yet occurred.  Forgery is a violation of 
University Regulations.)



\bold{Scan for danger:} Analyzes the script to find any statement or 
function call which might conceivably modify any of your files, whether in 
memory or on the disk.



\bold{Empower-compile:} Compiles the Ness script and also enables 
interception of events for objects mentioned in \bold{extend} statements in 
the script.  This option is available if the script has never been compiled 
or if the script has been changed.



\bold{Do main():} Calls the function called \bold{main} if the script has 
one.  The option appears after the script has been \bold{Empower-compiled}.


\bold{Author mode:} Makes a script read-write.  You can use this option if 
you want to modify a script.  Also, if the warning notice text is wrapped 
around the script, this option removes it.  The option is only available if 
the text is read-only.



\bold{Add warning:} This option wraps the warning notice text around the 
script and makes the whole thing read-only.  An author can then see how the 
script will appear to a user.  This option is only available if the warning 
notice is absent.}

\leftindent{
}\section{Preferences}


\leftindent{\bold{NessUseDialogBoxInsteadOfWarning:\italic{ on}}

If this option is off, every script is wrapped with a warning notice 
describing the possible consequences of allowing a Ness to execute and 
providing options to enable it.  When you have experience with Ness and 
understand the (remote, but) potential danger, you can set this preference. 
 Thereafter when Ness scripts appear a dialog box is displayed each time a 
script is first encountered in a document or application.  (Default value 
is \italic{off}.)


\bold{NessPath:\italic{~/nesslib:usr/andrew/lib/ness}}

Ordinarily, Ness searches for Ness library function definitions in 
/usr/andrew/lib/ness.  To search in alternative directories, the NessPath 
preference can be specified with a value of a colon-separated list of 
directories.  In the example value shown, searches for files will begin in 
the directory 'nesslib' of the user's home directory and will proceed next 
to the standard system directory.  \



Warning: Putting a directory in your NessPath means that Ness programs in 
.n files in that directory can be compiled and executed whenever 
referenced.  No visible warning is given to you that the files are being 
called.}


\section{Proctable Entries}

\description{
ness-dostmt 		Read a Ness statement seqeunce from the message line and 
execute it

ness-load 			Read and compile a Ness program file \


nessview-next-error  	See the source code for the next error

nessview-show-origin 	Show the author and date of last change

nessview-scan-for-danger 	Check for any statements that might be harmful

nessview-compile 		Compile the text in this view

nessview-execute 		Compile Ness and execute function main()

nessview-author-mode 	Change to be an author; remove warning text;  make 
read-write

nessview-user-mode 		Reinsert the warning text and be readonly

}

\section{Program Author

}
\leftindent{Wilfred J.  Hansen}


\section{Related tools}  \



\leftindent{Select (put a box around) one of the italicized names and 
choose "Get Help on Selected Word" from the pop-up menu to see the help 
file for:

\leftindent{\italic{
\helptopic{atk}

\helptopic{adew}

\helptopic{insets}}}}\leftindent{


You may also read further about Ness in the files in 
/usr/andrew/doc/atk/ness:


\leftindent{\description{nessuser.doc  -  aid in using applications written 
with Ness

nessauth.doc - aid for authors of Ness scripts

nesstut.doc - a tutorial on the Ness language

nessman.doc - a description of the language

nessfunc.doc - a decription of each of the functions available to Ness

nesshack.doc - some nitty-gritty stuff}}}


\begindata{bp,538505984}
\enddata{bp,538505984}
\view{bpv,538505984,1,0,0}
Copyright 1992 Carnegie Mellon University and IBM.  All rights reserved.

\smaller{\smaller{$Disclaimer: 

Permission to use, copy, modify, and distribute this software and its 

documentation for any purpose is hereby granted without fee, 

provided that the above copyright notice appear in all copies and that 

both that copyright notice, this permission notice, and the following 

disclaimer appear in supporting documentation, and that the names of 

IBM, Carnegie Mellon University, and other copyright holders, not be 

used in advertising or publicity pertaining to distribution of the software 

without specific, written prior permission.



IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS 

DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 

ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO EVENT 

SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER 

BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY 

DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 

WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS 

ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 

OF THIS SOFTWARE.

 $

}}\enddata{text,538478900}
