4. High Level XPA Interface

4.1 xpaset

Synopsis

Send data to one or more XPA servers

Usage

Integer_Type     xpaset(targets, xpa_cmd [, param, param, ... [,data]])

Description

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.

Example

        () = xpaset("ds9","file new stars.fits")
        () = xpaset("ds9","cmap","heat")

These commands load a new file into DS9 and select the heat colormap, 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:

    () = evalfile("./setup.sl");

    variable arr = Short_Type[2500];
    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));

and should yield a result which looks like

The first block of xpaset invocations 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

See Also

XPASet, xpaget

Compatibility Note

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

                () = xpaset(...);

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_errno variable upon return. See section Backwards_Compatibility to restore this behavior.

4.2 xpaget

Synopsis

Retrieve information from XPA servers, by name

Usage

Array_Type     xpaget(targets [, xpa_cmd = ""])

Description

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.

Example

        vmessage( xpaget("ds9") [0] );

This command dumps to the screen the entire list of XPA commands supported by DS9. As another example, if DS9 were invoked as

        your_unix_machine % ds9 examples/stars.fits &

then the following

        vmessage( xpaget("ds9","file") [0] );

would print

        examples/stars.fits

See Also

XPAGet, XPAGetToFile, xpaset

Compatibility Note

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.

4.3 xpaaccess

Synopsis

Determine how many XPA servers offer the specified command(s)

Usage

Integer_Type     xpaaccess(targets [, acc_mode = "gs"])

Description

Returns 0, 1, or more to indicate how many XPA servers are running which offer commands (access points) matching the given target template.

Example

Bring down any running instances of DS9, then launch it 3 times via

        your_unix_machine % ds9 &

and observe how

        your_unix_machine % slsh <<EOT
        import("xpa");
        message(string(xpaaccess("ds9")));
        EOT

returns the value 3. Similarly, if we then did

        your_unix_machine % ds9 -title BOB &

then issuing the above xpaaccess command again would still indicate that only 3 instances of DS9 were running, while

        xpaaccess("BOB");

would return 1.

See Also

The xpaaccess command line utility.