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 "=" and may be used to define arbitrary parameters of the message. To send a message to a specific application, the argument "to=" 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 [] : samp trace [] : samp access [] : samp handler [ ] : samp meta [ ] : samp send [ ....] : samp exec : samp pointAt : samp setenv : samp getenv : samp setparam : samp getparam : samp loadImage : samp loadVOTable : samp loadFITS : samp showRow [] [] : samp selectRows [] [] ,,.... : 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 . .