QUICKSTART GUIDE FOR APPMAP:


1.  Unpacking APPMAP:

	a.  cd to the parent directory of your choice (hereafter
	    parent_dir)
	b.  tar xvf appmap.tar

2.  Environment setup:

	In your .login
	  setenv APPMAP_HOME /parent_dir/appmap
	  place $APPMAP_HOME as the first directory searched in your path

3.  For each application you which to service by appmap, do the
following steps:

	a. Determine the command string to start the application from
	each system/group of systems.

	b. cd $APPMAP_HOME

	c. vi appmap.tbl
	   Create entries that define the rules for starting the app
	   from each system/group of systems.  See below for more
	   detail on this.


4.  For each application which has entries in appmap.tbl.

	ln -s appmap name

    Where name is the name by which users will attempt to start the
    application.  "name" must match the first field in the
    corresponding line in appmap.tbl.

5.  Test mode:

	name --t

    --t puts appmap in test mode where it reports what's to be done,
    but doesn't actually start anything.

    Test it from various systems to make sure your appmap.tbl works
    everywhere.

    If multiple revisions are defined in appmap.tbl, use

	name --rt #

    where # is a number that matches an entry in field 2 of the
    corresponding line in appmap.tbl.

6.  Real test:

	name
     or name --r #

    Typing name should start the application.


The APPLICATION ROADMAP TABLE (appmap.tbl):

Entries in appmap.tbl are one line of the form:

  app#rev#host#apphost#local-setup#remote-setup#exe

field delimiter: "#"

The first 3 fields identify the system that the particular line
pertains to.  The following 4 fields identify how to start the
application on that particular system.

The following describes the meaning of each field and how the appmap
script interprets it:

	app:  indicates the name of the application to be started.

	rev:  indicates the revision of the application that the user wishes to
	run.  If the user passed a "--r n" on the command line, then
	"n" is the specific revision the user wishes to run.  

	      NOTE : If no revision is specified, then the first line in 
		     appmap.tbl will be used which contains no entry for 
		     rev and passes the host-specific criteria tests.

	host: 	identifies an appmap.tbl entry that is specific to a particular host.
		Besides having a valid hostname as an acceptable entry, other
		entries which are also valid are :
  
		"-hostname" entries exclude a host and return an error
			ie. -saranac
		   Indicates the app is refused execution on the machine saranac.
		"solaris1" indicates any host which is running Solaris 1.x
		"solaris2" indicates any host which is running Solaris 2.x
		
		An empty "host" field specifies that the local system is to
		be used.  

	apphost: identifies the system the application should be run
	on.  This is used primarly for running an application across the
	network and displaying it locally.  It also gives the system administrator
	the capability to load balance those applications that "must" be run using X.

	local-setup: command(s) which should be run on the local system
	before starting this application.  Ex:

		xhost +myhost
	
	remote-setup:  command(s), which should be run on the apphost
	(only, if this application is to be run remotely and displayed
	locally) before starting this application.  Ex:

		setenv IOFFICE /export/apps/ioffice

	exe: a string of commands to be run on whichever system will
	run the application. 

Entries in the exe field CAN be shell scripts which do more
sophisticated processing before starting the application.  If you
already have some form of wrapper for a particular application, you can
place the fullpath and wrapper name in the exe field.  You MUST use the 
full path if the wrapper has the same name as that of the link in APPMAP_HOME.  
(otherwise, you'll get into a loop with appmap calling itself perpetually!)

NOTE : 	Do "not" use appmap itself to start that application.  If there 
	is no link in the APPMAP_HOME directory for the given application,
	the rest of your path will be searched as before.

It's a matter of administrative policy if other variables, such as
$OPENWINHOME, are to be setup in the .cshrc/.login files, or if the
appmap.tbl entries will take care of them.  Using APPMAP to control
variables like OPENWINHOME and LD_LIBRARY_PATH has some advantage, but
at the cost of making appmap.tbl rather hard to read.

Here's some examples of various appmap entries, and an english
interpretation of what they mean:

Remember, entries in appmap.tbl are one line of the form:

  app#rev#host#apphost#local-setup#remote-setup#exe

Example #1 : A simple appmap entry for local application startup:

	IslandWrite######\$IOFFICE/bin/IslandWrite

	field 1:  Indicates that IslandWrite is the application 

	field 2:  Indicates the desired revision. In this example, its left
		  left empty which indicates it is the default entry for
		  when users do not specifiy a particular revision.

		  If you have a line that has a revision entered, that
		  makes it specific to a particular revision level.  For
		  example, if a user then requests a specific revision by tying
		  IslandWrite --r 5 the line is this example will NOT be used,
		  as appmap would look for an entry that matches IslandWrite for
		  revision level 5.  Again, the above example indicates a
		  default entry for when users do not specify a particular
		  revision.

	field 3:  Indicates that this line can be used from ANY host.

	field 4:  Is empty, so this app will be started locally.

	field 5:  Is empty, which indicates no local setup required 
		  (apparently IOFFICE was set in .cshrc)

	field 6:  n/a... not running app remotely

	field 7:  how to actually start the default revision of IslandWrite.

Example #2 : A simple appmap entry for remote application startup:

Wingz#3.0#glaive#sunrock#xhost +sunrock#setenv DISPLAY `hostname`\:0#/usr/local/bin/Wingz

	field 1: Wingz is the application

	field 2: If you specify 3.0 on the command line, this line is
	used.  If you don't Specify a revision, this line won't be
	used. Presumably, there's a line somewhere after this one which
	has no entry in this field, and serves as the default
	revision.  That default entry MAY STILL be version 3.0.

	field 3: The ONLY host that "starts" Wingz this way is glaive

	field 4: This application is to be run on sunrock, and
	displayed on glaive. If field 3 were empty, and this line
	applied to any host, then the local display would be whichever
	host the user is sitting at.

	field 5: run xhost +sunrock on this system before starting the application.

	field 6: on sunrock set display to glaive

	field 7: start Wingz (NOTE:  I couldn't just place the command
	Wings in this field, or else the link to appmap would have been
	called instead of the actual Wingz execuitable.

Example #3 : A complicated appmap entry for remote application startup:

IslandWrite##solaris2#sunrock#xhost +sunrock#setenv IOFFICE /usr/dist/pkgs/ioffice,v3.0.p;setenv DISPLAY `hostname`\:0#\$IOFFICE/bin/bin.sun4/bin.ow3/IslandWrite

	field 1:  IslandWrite is the application

	field 2:  If you specify a specific revision by tying
	IslandWrite --r 5 this line will not be used.  This is the
	default entry for when users do not specify a particular
	revision.

	field 3:  Only solaris2.x systems will choose this line.
	Solaris 1.x systems will not.

	field 4: This application is to be run on sunrock, and
	displayed on local system (again, if its a solaris 2.x system).

	field 5:  xhost +sunrock on local system

	field 6:  on sunrock, set IOFFICE environment variable, and set
		  the display variable.

	field 7:  how to start IslandWrite on sunrock.

	NOTICE how hard to read this entry is.  BLANK lines between
	this and other lines will make appmap.tbl more readable.
	Actually, # can be used to mark a blank or comment line as
	well.

---------------------------------------------------------------------------------------------

GUIDELINES FOR BUILDING APPMAP.TBL:

Group entries for a specific application together for ease of
reading.  (ie: sort by first field)

	ex:  frame#1#solaris1###maker
	     frame#####maker
	
	     IslandWrite#####/path/IslandWrite


Revision field:
	
	If a user doesn't specify a revision on the comman line (--r
	#), he'll ONLY get a match on those lines that match his application 
	and have a blank revision field. Therefore, you MUST have an entry/line 
	with a blank revision field. Place this line at the end of the group 
	of lines for the application.  This line acts as the default.
	
Host field:
	
	Lines with host field entry apply only to that specific host
	and are ignored when called by other hosts.  Place lines with a
	host field entry first, so they're tested before other
	lines.  

	Remember: The first line which is acceptiblie is used.
	This is extremely important when you want to deny an
	application to be run on a given host (ie. -saranac).

	Place lines that specify solaris1 and solaris2 after lines that
	specify a particular host but before lines with no host entry.

	You must Place lines with no host entry last, as they're
	acceptible to host.  You MUST have an entry/line with a
	blank host field.

Defaults: 

	You should have a line with both the rev and host fields empty
	at the end of the grouping of lines for an application.  This
	is the default.

Testing:

	The easiest way to determine what information to place in the
	final 4 fields is to start the application at a system and
	record what steps were taken to do so.  Example:  To start
	IslandWrite on system sparcy, I type:

	setenv IOFFICE /apps/island
	$IOFFICE/bin/IslandWrite

	An appmap.tbl entry specific to sparcy would thus be:

	sparcy##sparcy##setenv IOFFICE /apps/island##$IOFFICE/bin/IslandWrite

	The final step is to create the link in $APPMAP_HOME:

	ln -s appmap IslandWrite

	Before starting the application, you should run it in "test" mode, to
	see what appmap will do:

	IslandWrite --t

	appmap will report the value of the settings for fields 1 - 7, allowing
	you to verify that appmap has chosen the correct line in appmap.tbl.

Special characters: 

In the final 3 fields, local_setup, remote_setup, and exe, there are
considerations for specific characters and when you should/should not
protect them with a backslash (\).

a. The backquote and the dollar sign:

	The backquote (`) and dollar sign ($) should NOT be protected if you want them 
	interpreted on the local system, and SHOULD be protected if you want them interpreted 
	on the remote system.  Exapmle:  if you use `hostname` in the local_setup field, 
	you DO NOT want to protect it.  If you use $OPENWINHOME in the local_setup field, you 
	DO NOT want to protect it, if you use $OPENWINHOME in the remote_setup field, 
	you DO want to protect it.

b.  Colon:
	the ":" character MUST be protected by a backslash (\) in all cases.  

d.  The semicolon:
	the ";" should NOT be preceded by a backslash "\" in any case.

Examples: 

In the remote_setup field, it's often useful to set the DISPLAY
variable to the local system name.  To do so,  

		setenv DISPLAY `hostname`\:0

If a users startup files does not set OPENWINHOME, you can set it in
appmap.tbl.  Here's an example of setting it in remote_setup,

		setenv OPENWINHOME /pkgs/openwin;setenv LD_LIBRARY_PATH \$OPENWINHOME/lib
	
	Notice that we did protect OPENWINHOME in the setting of LD_LIBRARY_PATH, so that
	the OPENWINHOME variable was interpreted on the remote system and not locally.