diff options
Diffstat (limited to 'pkg/vocl/Notes.samp')
| -rw-r--r-- | pkg/vocl/Notes.samp | 241 |
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 . . + + |