\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}