Send data to one or more XPA servers
Integer_Type xpaset(targets, xpa_cmd [, param, param, ... [,data]])
This function is used to send information or commands to one or more XPA server(s). The return value indicates the number of application servers contacted.
These commands load a new file into DS9 and select the
() = xpaset("ds9","file new stars.fits") () = xpaset("ds9","cmap","heat")
heatcolormap, discarding the return values. They also demonstrate the flexibility with which XPA parameters may be passed to the server, either by concatenation with the XPA command name or as distinct comma-separated arguments.
Internally the function automatically appends all scalar parameters (char, short, integer, long, float, or string) to the XPA command name before transmission. When a non-scalar parameter argument is present (e.g. an array of floats) it will be treated as data (see the XPA documentation) for the command, and all subsequent arguments will be ignored.
The next example creates two test patterns directly from an in-memory S-Lang array:
and should yield a result which looks like
() = evalfile("./setup.sl"); variable arr = Short_Type; arr[[0:499]] = 100; arr[[500:999]] = 200; arr[[1000:1499]] = 400; arr[[1500:1999]] = 800; arr[[2000:2499]] = 1600; () = xpaset("ds9","frame new"); () = xpaset("ds9","cmap rainbow"); () = xpaset("ds9","array [dim=50,bitpix=16]",arr); () = xpaset("ds9","frame new"); () = xpaset("ds9","cmap green"); () = xpaset("ds9","array [dim=50,bitpix=-64]",log10(arr));
The first block of
xpasetinvocations sends 2500 short integers, as binary data, to the DS9 array command, along with instructions that it be visualized in the rainbow colormap and treated as a 50x50 image with 16 bits per pixel.
The subsequent statements generate a new image by performing a base 10
logarithmic transform of the original image, indicating how simple and
natural it can be to perform sophisticated image manipulations.
Moreover, instead of the
log10 function one could in principle
substitute any numerical function callable from S-Lang scope, such
as that which might be provided by the GSL module (which binds
the GNU Scientific Library to S-Lang), or even your own homegrown
C or FORTRAN codes. The entire script may be executed from the
examples directory, under UNIX for instance, via
your_unix_machine % slsh testpattern.sl
In the CIAO 3.0 bindings this function did not return a value. This was intended to reflect the most common usage, namely that the the number of servers contacted is usually ignored at the command line, avoiding superfluous
notation in scripts (which would be required in S-Lang 1.x to explicitly pop the return value off the stack), in favor of the "more natural"
() = xpaset(...);
The caller could determine the number of servers contacted during these calls by inspecting the
slxpa_errnovariable upon return. See section Backwards_Compatibility to restore this behavior.
Retrieve information from XPA servers, by name
Array_Type xpaget(targets [, xpa_cmd = ""])
This function is used to retrieve information from the specified XPA server(s). Results are returned as an array of strings, one from each application server contacted.
When no XPA command is given the application(s) contacted typically return a list of the XPA commands that the application supports.
This command dumps to the screen the entire list of XPA commands supported by DS9. As another example, if DS9 were invoked as
vmessage( xpaget("ds9")  );
then the following
your_unix_machine % ds9 examples/stars.fits &
vmessage( xpaget("ds9","file")  );
XPAGet, XPAGetToFile, xpaset
In the CIAO 3.0 bindings this function would return a single string, rather than an array containing only 1 string, when only a single application server responded. See section Backwards_Compatibility to restore this behavior.
Determine how many XPA servers offer the specified command(s)
Integer_Type xpaaccess(targets [, acc_mode = "gs"])
Returns 0, 1, or more to indicate how many XPA servers are running which offer commands (access points) matching the given target template.
Bring down any running instances of DS9, then launch it 3 times via
and observe how
your_unix_machine % ds9 &
your_unix_machine % slsh <<EOT import("xpa"); message(string(xpaaccess("ds9"))); EOT
returns the value 3. Similarly, if we then did
then issuing the above
your_unix_machine % ds9 -title BOB &
xpaaccesscommand again would still indicate that only 3 instances of DS9 were running, while
would return 1.
xpaaccess command line utility.