\begindata{text,539403492}
\textdsversion{12}
\template{help}
\define{global
}


\chapter{runapp: run an Andrew application


}\section{What runapp is

}\leftindent{
runapp is the Andrew application bootstrap program.  When a new Andrew 
application is developed, the application's creator will place a link to 
runapp in the Andrew system's program directory.  This entry will cause runapp 
to be invoked when the application's name is typed to a command shell such as 
typescript.  When runapp in invoked under these circumstances, it will 
determine the command name that was give by the user and run that Andrew 
application on the user's behalf.


}\section{Warning

}\leftindent{
runapp is not meant to be invoked by casual Andrew users.  One should simply 
start an application by typing the application's name such as "typescript" or 
"ez" rather than "runapp tscriptapp" or "runapp ezapp".  runapp is used by 
application developers in order to operate an application under controlled 
conditions thus easing the debugging process.


}\section{Quick reference

}\leftindent{
The runapp can be invoked in two different ways.  The first, and most common 
method of invocation happens when an application's name is linked (see help on 
\italic{\helptopic{ln}}) to the runapp executable file.  This causes runapp to 
load the dynamic object that implements that Andrew application, initialize 
the application, pass the command line arguments to the application and 
finally, start execution of the application.  The second method of invocation 
is used to operate applications in a controlled environment to aid in the 
process of application development.


\bold{Method 1:}


appname [ appargs.... ]


appname -- name used to invoke the desired Andrew application.  runapp appends 
"app" to appname and uses the result to load an object that implements that 
application.  As an example, when one invokes runapp with the name "ez", 
runapp appends "app" to the name and loads the "ezapp" class.  If the 
application is not found, runapp attempts to load the class of name appname. 
 If this class is of type dataobjects ez is started in a mode that causes it 
to edit an object of type appname.


appargs... -- command line arguments to be passed to the application.



\bold{Method 2:}


runapp [ -dDx ] appclassname [ appargs... ]


-d -- turns on the display of debugging messages from the dynamic loader. 
 (see help on \italic{class})


-D -- disables the static loading feature of runapp.  This causes all class 
objects to be dynamically loaded rather than using the statically loaded 
entries.  (see help on \italic{class})


-x -- print a brief help message.


appclassname -- the name of the Andrew class that implements the desired 
application.


appargs... -- command line arguments to be passed to the application.


}\section{Environment

}\leftindent{
runapp looks in a few places to try to determine its environment.  This 
information is used when runapp initializes the class system (see help on 
 \italic{\helptopic{class} }) and sets the path to use to load dynamically 
loaded objects.  To determine the appropriate path, runapp first looks for an 
environment variable called CLASSPATH (see help on  \italic{\helptopic{environ} 
} to learn how environment variables work).  If CLASSPATH is found in the 
environment, that path is used.  Next, runapp looks for ANDREWDIR in the 
environment.  If ANDREWDIR is found, "/dlib/atk" is appended to its value and 
the result is used as the search path.  If neither CLASSPATH nor ANDREWDIR is 
defined in the environment, runapp looks in the AndrewSetup file (see help on 
 \italic{\helptopic{AndrewSetup} }) is not found, runapp appends "/dlib/atk" 
to the "ANDREWDIR" found in that file and uses the result as the search path 
for the class system.  If none of these configuration specifiers is defined or 
available, runapp initializes the search string to "/usr/andrew/dlib/atk".


}\section{Advice

}\leftindent{
If you are not an Andrew application developer, don't worry about runapp.  All 
the grubby details are being taken care of by the Andrew system developers.


If you are a system developer and are having trouble debugging your 
application, study the runapp command carefully as you will probably be using 
the runapp command to debug your Andrew application in a controlled 
environment with conventional debuggers.


Remember, runapp can only start applications that are implemented as 
subclasses of the Andrew application object.  For more information about the 
application class of objects, please refer to the Andrew Programmers' 
Reference Guide (/usr/andrew/doc/atk/overview.doc).


If you don't understand what the command switches mean you should probably 
refer to the Andrew Programmer's Reference Guide before you attempt to use 
runapp by name.

}
\section{Diagnostic and Informational Messages}


Most of the debugging will be done using facilities available from class. 
 runapp issues few error messages on its own.


\subheading{Informational Messages:}


\typewriter{Starting APPLICATION (Version MAJOR.MINOR, ATK VERSION), please 
wait...


}\leftindent{a short message that gives you an indication of the MAJOR and 
MINOR version number for APPLICATION and the ATK VERSION.  These number should 
accompany bug reports or requests for clarification about the behaviour of a 
particular application.


}
\subheading{Diagnostic Messages:}


\typewriter{usage: runapp [-dDx] appclassname [appargs...] ....

}
\leftindent{a short description of runapp's command line switches if runapp is 
invoked as "runapp" and the -x switch is given or an error is found in the 
command line switches.


}
\typewriter{usage: PROGRAMNAME [appargs...]}

\typewriter{
Please see the specific help file for PROGRAMNAME to

obtain more information about the command line switches.


}\leftindent{a short message that directs the user to help on PROGRAMNAME if a 
command line error is detected.

}
\typewriter{runapp:  SOME UNIX ERROR MESSAGE.

}
\leftindent{a short error message that is printed when some UNIX facility was 
unable to perform the action requested by runapp.  See help on 
\italic{\helptopic{errno}} and \italic{\helptopic{intro(2)}} to determine the 
cause of the problem.

}

  fprintf(stderr,"%s: Error loading the application %s.\\n",RUNAPP,appclass);


	    fprintf(stderr,"%s: There is no known application called 
%s.\\n",RUNAPP,appclass);

	fprintf(stderr,"%s: Error creating the %s object.\\n", RUNAPP, appclass);


		    fprintf(stderr,"%s: Error loading the %s object.\\n",RUNAPP,appclass);

		    fprintf(stderr,"%s: There is no known application or datatype called



\section{Bugs}


\leftindent{There are too many places to "squirrel away" configuration 
information.  (enviroment, AndrewSetup in many places, wired in to the 
program)


The use of runapp switches to set the class system's behaviour is 
questionable.


runapp and the application class assume all applications have windows thus 
making it confusing if one wants to create ATK programs that execute with 
command-line interfaces.


perror should not be used if we really expect the system to be usable by 
novices.}


\section{Related tools}  


Select (highlight) one of the italicized names and choose "Show Help on 
Selected Word" from the pop-up menu to see the help file for:


\leftindent{\italic{\helptopic{class}}

\italic{\helptopic{programming}

\helptopic{environ}

\helptopic{AndrewSetup}

}}


\begindata{bp,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,1383,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,539403492}
