Repatch (from linux) of OSX IRAF

1 files changed, 241 insertions, 0 deletions

diff --git a/pkg/vocl/Notes.samp b/pkg/vocl/Notes.samp
new file mode 100644
index 00000000..5575062b
--- /dev/null
+++ b/pkg/vocl/Notes.samp
@@ -0,0 +1,241 @@
+
+							Sep 17, 2011
+
+			    IRAF SAMP Integration
+
+Introduction
+------------
+
+    The SAMP interface in IRAF is implemented in two modes:  A "Command
+Mode" provides a natural command-line interface to either control the SAMP
+messaging (e.g. to enable/disable messaging), or to send messages manually.
+As an example,
+
+    cl> samp start			# start SAMP messaging
+    on					  <-- shows status
+
+This also takes advantage CL-specific features such as logical directories
+or support for sexagesimal value.  For instance:
+
+    cl> samp loadImage data$foo.fits	# broadcast an image load message
+    ok
+    cl> samp pointAt (15 * 10:23:01) 34:12:45 to=aladin
+    ok
+
+In the first case the 'data$' logical dir is converted internally so the
+SAMP application is given the expected URI, in the second case the
+arguments are expected to be in decimal degrees and converting RA is done
+trivially.
+
+The second form, known as "Program Mode", provides the same functionality
+in the form of CL builtin functions more suited for CL scripting.  For
+example,
+
+    if (sampStatus("on") != "on") {
+	error (0, "Cannot enable SAMP messaging")
+    } else {
+	if (sampLoadImage (img, "aladin") != "ok") {
+	    error (0, "Cannot load image " // img)
+	}
+    }
+
+A complete list of both the Command and Program mode functions is given in
+the Appendix below.
+
+    Explicitly enabling the SAMP message (e.g. with "samp start") is not
+necessary to send messages to other applications, any 'samp' command that
+requires a SAMP Hub will attempt to start a connection automatically.
+However, for the CL to receive messages from other applications the SAMP
+interface must be enabled.  This can be done explicitly as above, by
+setting the "samp_onstart" CL environment variable in the hlib$zzsetenv.def
+file, or by uncommenting the "samp on" command in the login.cl file.
+
+
+Receiving Messages in the CL
+----------------------------
+
+    By default, the CL will subscribe only to the following SAMP mtypes:
+
+	client.cmd.exec			# execute a command string
+	client.env.set			# set and environment variable
+	client.env.get			# get and environment variable (*)
+	client.param.set		# set a task parameter value
+	client.param.get		# get a task parameter value
+
+Except for the client.env.get mtype, these are all newly defined mtypes that
+may not be available to other SAMP applications.  Testing these messages
+can be done with the samp library tasks or from another CL session.
+
+Additional message types can be received by defining handlers for each 
+mtype, for example
+
+    cl> samp handler image.load.fits "imstat $url"
+or
+    cl> =sampHandler ("image.load.fits", "imstat $url")
+
+This will subscribe the current session to the 'image.load.fits' mtype, and
+when received will execute the IMSTAT command on the named URL.  The '$url'
+in the command string is replaced by the value of that parameter sent in
+the message.  The mtype parameter names are defined in the Appendix below.
+
+Proprietary messages can be defined using the same mechanism.  For instance
+
+    cl> samp handler pipeline.event "imcopy $url image.fits"
+
+will create a handler for the 'pipeline.event' mtype and execute the
+associated command.  Another client could send a message of this type
+regardless of whether this is an mtype approved by the IVOA.  Calling
+the sampHandler (or 'samp handler') function with no arguments will print
+the list of user-defined handlers, supplying only the 'mtype' argument
+will print the handler defined for just that mtype (or a null string).
+
+By default a SAMP-enabled CL session will be known as 'IRAF' to other
+applications, this can lead to a name conflict when sending directed
+messages.  To solve this, a session can define it's own name to other
+applications using any of the following:
+
+    cl> samp name iraf2
+    cl> samp meta samp.name iraf2
+    cl> =sampName ("iraf2")
+    cl> =sampMetadata ("samp.name", "iraf2")
+
+The sampMetadata() function (or 'samp meta' command) can declare arbitrary
+metadata about the session that can be discovered by other apps, the 
+name in this case is provided as a convenience function and will cause
+the name to be updated immediately.
+
+
+
+Sending Messages from the CL
+----------------------------
+
+    Sending messages from the CL can be done using either the command
+or program form of a command, high-level functions are implemented for
+the most common messages (e.g. to 'load an image') as well as one low-level
+method for sending arbitrary messages.  For example,
+
+    cl> samp loadImage http://foo.edu/test.fits	    # load an image
+    cl> samp loadVOTable images.xml		    # load a VOTable
+    cl> samp loadFITS imtab.fits		    # load a FITS bintable
+
+Or the low-level 'send' command as in
+
+    cl> samp send pipeline.event url=http://foo.edu/test.fits
+or
+    cl> =sampSend ("pipeline.event", "url=http://foo.edu/test.fits")
+
+In this case the first argument is always the mtype, remaining arguments
+are of the form "<param>=<value>" and may be used to define arbitrary
+parameters of the message.  To send a message to a specific application,
+the argument "to=<appName>" may be appended to these commands, e.g.
+
+    cl> samp loadFITS test.fits to=topcat	    # load table in Topcat
+  
+
+When using the program mode the recipent application name is one of the
+optional parameters, e.g.
+
+    cl> =sampLoadImage ("image.fits")		    # broadcast to all apps
+    cl> =sampLoadImage ("image.fits", "aladin")	    # send to aladin
+
+
+
+
+
+Appendix
+========
+
+
+Command Mode Summary
+--------------------
+
+#  The following command is a builtin but doesn't push anything on the
+#  result stack, instead result values are printed to the stdout/stderr.
+#  The intent is to provide a simple command interface without requiring
+#  the function syntax.
+
+samp status						cl_Samp
+samp on|start						   :
+samp off|stop						   :
+samp restart						   :
+samp name 	  [<appName>]				   :
+samp trace 	  [<value>]				   :
+samp access 	  [<appName>]				   :
+samp handler	  [<mtype> <cmd>]			   :
+samp meta	  [<param> <value>]			   :
+
+samp send	  <mtype> [<args> ....]			   :
+samp exec	  <cmd>					   :
+samp pointAt	  <ra> <dec>				   :
+samp setenv	  <name> <value>			   :
+samp getenv	  <name>				   :
+samp setparam	  <name> <value>			   :
+samp getparam	  <name>				   :
+samp loadImage	  <url>					   :
+samp loadVOTable  <url>					   :
+samp loadFITS	  <url>					   :
+samp showRow	  [<tblId>] [<url>] <row>		   :
+samp selectRows	  [<tblId>] [<url>] <row>,<row>,....  	   :
+
+
+Program Mode Summary
+--------------------
+
+#  The following functions do push a result on the stack.  This allows 
+#  scripts to be written to check the return value before continuing.
+
+on|off  = sampStatus ( [on|off|restart] )		func_sampStatus
+
+yes|no  = sampAccess (appName)				func_sampAccess
+ok|name = sampName ([name])				func_sampName
+ok|val  = sampMetadata ([name, [val]])			func_sampMetadata
+yes|no  = sampHandler (mtype, cmd)			func_sampAddHandler
+
+ok|err  = sampLoadImage (url[, to, id, name])		func_sampLoadImage
+ok|err  = sampLoadVOTable (url[, to, id, name])		func_sampLoadVOTable
+ok|err  = sampLoadFITS (url[, to, id, name])		func_sampLoadFITS
+ok|err  = sampLoadSpec (url[, to, id, name])		func_sampLoadImage
+ok|err  = sampLoadBibcode (bibcode[, to])		func_sampLoadBibcode
+ok|err  = sampLoadResource (url[, to, meta, id, name])	func_sampLoadResource
+
+ok|err  = sampShowRow (url, id, row[, to])		func_sampShowRow
+ok|err  = sampSelectRowList (url, id, *row[, to]) 	func_sampSelectRowList
+ok|err  = sampPointAt (ra, dec[, to])			func_sampPointAt
+
+ok|err  = sampCmdExec (cmd[, to])			func_sampCmdExec
+ok|err  = sampEnvSet (par, val[, to])			func_sampEnvSet
+val|err = sampEnvGet (par[, to])			func_sampEnvGet
+ok|err  = sampParamSet (par, val[, to])			func_sampParamSet
+val|err = sampParamGet (par[, to])			func_sampParamGet
+
+--------------------------------------------------------------------------------
+
+			Command		Function
+on|start		   Y		   .
+off|stop		   Y		   .
+restart			   Y		   .
+status			   Y		   .
+access			   Y		   .
+handler			   Y		   .
+metadata		   Y		   .
+
+send			   Y		   .
+loadImage		   Y		   .
+loadVOTable		   Y		   .
+loadFITS		   Y		   .
+
+cmdExec			   Y		   .
+envGet			   Y		   .
+envSet			   Y		   .
+paramGet		   Y		   .
+paramSet		   Y		   .
+
+pointAt			   Y		   .
+showRow			   Y		   .
+selectRows		   Y		   .
+
+resourceLoad		   .		   .
+specLoad		   .		   .
+bibcodeLoad		   .		   .
+
+