1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
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 . .
|
