\begindata{text,538442764}
\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


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}


\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 Typescript:


\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 Typescript:


\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,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,564,0,0}
Copyright 1992 Carnegie Mellon University and IBM.  All rights reserved.

\smaller{\smaller{$Disclaimer: This software is part of version 6.1 of the 

Andrew User Interface System and is 

the property of IBM, Carnegie Mellon University, 

and the other copyright holders.  The source 

code of this version is for the sole use of 

the individual named in ./config/allsys.h.  

This source code is not to be redistributed.  

Binary object code compiled or derived from 

these sources is not to be distributed to non-

members.  Members may have additional 

distribution rights granted by prior written 

permission of Carnegie Mellon University.



IBM, CARNEGIE MELLON UNIVERSITY, 

AND THE OTHER COPYRIGHT HOLDERS

 DISCLAIM ALL WARRANTIES WITH 

REGARD TO THIS SOFTWARE, INCLUDING 

ALL IMPLIED WARRANTIES OF MERCHANT-

ABILITY AND FITNESS. IN 

NO EVENT SHALL  IBM, CARNEGIE 

MELLON UNIVERSITY, OR ANY OTHER 

COPYRIGHT HOLDER BE LIABLE FOR 

ANY SPECIAL, INDIRECT OR CONSE-

QUENTIAL 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,538442764}
