5. Low Level XPA Interface

Note that in the SLxpa api the mode parameter has been moved to the end of the argument list for those functions which utilize such. This simplifies scriptwriting, since clients rarely utilize a mode, by allowing the parameter to be omitted from most calls.

5.1 XPA_Type

SLxpa introduces the XPA_Type S-Lang type to wrap the XPA structure defined within the XPA C library. Instantiated variables of this type are opaque, meaning their contents cannot be inspected in S-Lang scope.

5.2 XPAOpen

Synopsis

Allocate a persistent client handle

Usage

XPA_Type     XPAOpen([mode])

Description

Explicitly instantiate a persistent XPA_Type client handle for use in subsequent XPA calls. This is most useful for high-volume traffic, to avoid the cost of setting up and tearing down the communications channel to the server(s) during each message exchange. The mode parameter is currently ignored by XPA, and so may be omitted from SLxpa calls with no consequence.

See Also

XPAClose

5.3 XPAClose

Synopsis

Close a persistent client handle

Usage

Void_Type     XPAClose(XPA_Type xpa)

Description

Explicitly close an XPA handle and free its resources. Strictly speaking it is not necessary to call this function, since SLxpa automatically closes XPA connections when they go out of scope. This routine is provided mainly for completeness.

See Also

XPAOpen

5.4 XPAGet

Synopsis

Retrieve information from XPA servers, using client handle, as strings

Usage

  (results, names, messages)  =  XPAGet(handle, targets, xpa_cmd
                                [,max_recipients = XPA_MAXHOSTS [, mode = ""]])

Description

Similar to xpaget, but offers finer control and returns additional information. The results,names, and messages return values are all arrays of String_Type, whose length indicates the number of servers contacted.

In practice most XPA commands do not return binary data, but rather a small number of discrete datapoints (e.g coordinate values, filename(s), upper/lower limits). This routine is well suited for retrieving results from such access points. Use either XPAGetB or XPAGetToFile to retrieve binary data.

See Also

xpaget, XPAGetB, xpaset, XPASet

Compatibility Note

In the CIAO 3.0 bindings this function , like xpaget, would return a single string, rather than an array containing only 1 string, when only a single application server responded. Moreover, the return value did not reflect the lens, names, or messages arrays populated by underlying C function. See section Backwards_Compatibility to restore this behavior.

5.5 XPAGetB

Synopsis

Retrieve information from XPA servers, using client handle, as binary data

Usage

  (results, names, messages)  =  XPAGetB(handle, targets, xpa_cmd
                                [,max_recipients = XPA_MAXHOSTS [, mode = ""]])

Description

Similar to XPAGet, the only difference being that the results array is of type BString_Type.

Example

Consider the visual

generated by the following script:

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

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

    % Retrieve the file as raw binary data
    variable result;
    (result, , ) = XPAGetB( XPAOpen(), "ds9", "array");

    % Zero pixels with less than 200 counts in brightness
    variable image = bstring_to_array(result[0]);
    image [ where (image < 200) ] = 0;

    % Display the zeroed image.  Note that newer versions of DS9
    % provide a way of retrieving the dimensions of displayed images,
    % but for convenience we simply hardcode 255x225 here
    () = xpaset("ds9","frame new");
    () = xpaset("ds9","array [xdim=255,ydim=225,bitpix=8]",image);

    % Re-retrieve it, to test the interface
    (result, , ) = XPAGetB( XPAOpen(), "ds9", "array");
    variable test = bstring_to_array(result[0]);
    if (length (where (test != image)))
       () = fprintf (stderr, "XPAGetB has failed\n");

Here we've combined XPAGetB with the S-Lang binary string manipulators, yielding a powerful mechanism for transmitting DS9 images between applications while using no intermediate files.

See Also

xpaget, XPAGet, xpaset, XPASet

5.6 XPAGetToFile

Synopsis

Retrieve information from XPA servers, using client handle, write results to file

Usage

  (names, messages)  =  XPAGetToFile(handle, targets, xpa_cmd
                                                [, fileid = stdout
                                                [, max_recipients = XPA_MAXHOSTS
                                                [, mode = ""]]])

Description

This is the SLxpa wrapper for XPAGetFd, renamed slightly to connote increased generality. It is similar to XPAGet and XPAGetB, except that results are written (as binary data) to the given file identifier, instead of being returned on the stack.

The file identifier may one of

• the name of a file that will be written to (and created or overwritten as necessary)
• a file pointer, such as returned by fopen() or popen()
• a file descriptor, such as returned by open() or dup_fd()

Unlike the C api, at present only 1 unique file may be specified in the S-Lang layer.

Example

Rather than using binary string data the previous example could be rewritten to make use of the UNIX mmap function as wrapped by the varray module bundled with the S-Lang distribution:

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

    import("varray");                           % module bundled with S-Lang

    % Newer versions of DS9 provide a way of retrieving the dimensions of
    % displayed images, but for convenience we simply hardcode them here
    variable names, messages, size = 255*225;
    variable handle = XPAOpen();

    (names,messages) = XPASet(handle, "ds9", "file new stars.fits");
    check_errors(names,messages);

    variable tmpfile = "tempfile.dat";
    () = remove(tmpfile);

    (names,messages) = XPAGetToFile( handle ,"ds9", "array", tmpfile);
    check_errors(names,messages);

    variable finfo = stat_file(tmpfile);
    if (orelse {finfo == NULL}  {finfo.st_size != size})
       error(tmpfile +" for mmap() is missing or of incorrect size");

    variable arr = mmap_array(tmpfile,0,UChar_Type,size);

    % duplicate the mmap'd array, so we can modify its content
    arr = @arr;
    arr [ where (arr < 200) ] = 0;

    () = xpaset("ds9","frame new");
    () = xpaset("ds9","array [xdim=255,ydim=225,bitpix=8]",arr);

    () = remove(tmpfile);

See Also

XPAGet, xpaget, xpaset

5.7 XPASet

Synopsis

Send data to one or more XPA servers, using client handle

Usage

 
  (names, messages)  =  XPASet(handle, targets, xpa_cmd
                        [, max_recipients = XPA_MAXHOSTS
                        [, data = NULL
                        [, mode = ""]]])

Description

Similar to xpaset(), but with more user control. The names and messages return values are, again, arrays of String_Type, whose lengths indicate the number of servers contacted.

Note that the len parameter present in the C function signature (which indicates the number of data bytes to be transmitted) is not required in S-Lang, since that can be determined automatically.

See Also

xpaset, xpaget, XPAGet

Compatibility Note

In the CIAO 3.0 bindings this function did not return the names or messages arrays populated by underlying C function, but rather returned only an integer indicating the number of servers contacted. See section Backwards_Compatibility to restore this behavior.