3.5.1 Remote Control C Interface Library

The RTD supports remote access via a simple socket interface. This interface works a bit like the Tk send command in that you send a command to execute and get the result back, however in this case, only RTD subcommands are allowed. Remote clients can connect to a running RTD widget and send RTD subcommands to be executed and get the results. Some of the RTD subcommands are designed especially for use with this interface. For example, the shm command gives access to the image header and data as shared memory. Remote clients can execute any of the RTD image subcommands. In addition, applications can extend the list of available remote commands by specifying a Tcl command to be called for unknown subcommands.

The remote control interface is implemented on the client side by the client writing to and reading from the socket or optionally through a simple C library (module rtdrmt ). On the server side, the C++ class RtdRemote(3) is used to start listening for connections. By default, a port number is chosen automatically and the information is saved in the file $HOME/.rtd-remote as 3 values: processID , hostname and port . Since the server is started as an rtdimage subcommand ( remote ), you can also specify a port number to use.

Client commands are sent as strings over a socket, one line for each command sent. The strings are interpreted directly as rtdimage subcommands. The client waits for a reply on the same socket used to send the request. The reply consists of 2 lines. The first line contains 2 numbers: the status of the command (0 for OK) and the length of the command result that follows.:

Command Format	Result Format
command <newline>	status length <newline> result[length]

Example Usage

The following example demonstrates the use of the remote RTD interface, using the example C library:

 

 
static char* send_rtd(char* cmd)  
{ 
    char* result = NULL; 
    int status = rtdRemoteSend(cmd, &result);  
    printf("%s ==> %s: %s\n", cmd, (status ? "FAILED" : "OK"), result); 
    return result; 
}
 
main
() 
{ 
    int data_id, header_id; 
  
    /*  
     * open the  
     */ 
    if (rtdRemoteConnect(0, NULL, 0) != 0)  
        exit(1); 
 
    /* send some commands to RTD to be evaluated
 */ 
    send_rtd("wcscenter"); 
    send_rtd("bitpix"); 
    send_rtd("scale"); 
    send_rtd("width"); 
    send_rtd("height"); 
    send_rtd("config -file ngc1316r.fits"); 
    send_rtd("width"); 
    send_rtd("height"); 
 
    data_id = atoi(send_rtd("shm get data")); 
    header_id = atoi(send_rtd("shm get header")); 
 
    exit(0); 
}

The following example shows how you could use the remote interface without using the C library. This example uses Tcl (with the TclX extension):

 
 
# open a socket to a running Rtd application and return the file 
# descriptor for remote commands 
 
proc connect_to_rtd {} { 
    global env 
    # get the hostname and port info from the file ~/.rtd-remote, 
    # which is created by rtdwhen the remote subcommand is used 
    if {[catch {set fd [open $env(HOME)/.rtd-remote]} msg]} { 
        puts "can't open ~/.rtd-remote: make sure rtd is running: $msg" 
        exit 1 
    } 
 
    lassign [read $fd] pid host port 
    close $fd 
 
    if {[catch {exec kill -0 $pid} msg]} { 
        puts "could it be that rtd is not running? ($msg)" 
        exit 1 
    } 
 
    set fd [server_connect -nobuf $host $port] 
    return $fd 
} 
 
# send the command to rtd and return the results or generate an error 
 
proc send_to_rtd {args} { 
    global rtd_fd 
    puts $rtd_fd $args 
    lassign [gets $rtd_fd] status length 
    set result {} 
    if {$length > 0} { 
        set result [read $rtd_fd $length] 
    } 
    if {$status != 0} { 
        error $result 
    } 
    return $result 
} 
 
puts "testing the RTD remote interface..." 
 
# open the connection 
set rtd_fd [connect_to_rtd] 
 
# this allows us to use the remote rtdimage as if it were local 
set image send_to_rtd 
 
# send some commands to RTD to be evaluated  
puts "WCS image center is: [$image wcscenter]" 
puts "image type: [$image bitpix]" 
puts "current scale factor: [$image scale]" 
puts "image dimensions: [$image width] x [$image height] pixels" 
puts "loading a new file: ngc1316r.fits [$image config -file ngc1316r.fits]" 
puts "setting cut levels: [$image autocut]" 
puts "new image dimensions: [$image width] x [$image height] pixels" 
 
puts "shared memory Id for image data: [$image shm get data]" 
puts "shared memory Id for image header: [$image shm get header]"

Here is the output from the above script (rtd was already running):

 
testing the RTD remote interface... 
WCS image center is: 03:19:48.243 +41:30:40.31 J2000 
image type: 16 
current scale factor: 1 1 
image dimensions: 353 x 353 pixels 
loading a new file: ngc1316r.fits  
setting cut levels:  
new image dimensions: 512 x 512 pixels 
shared memory Id for image data: 7400 
shared memory Id for image header: 601