Service I/O Library
and Return Structure Handling

Table of Contents

General Description

This library allows the user to fire up external processes as services, to send commands and receive structured responses, and to parse those responses to extract keyword = value pairs or the value of a particular keyword.


Service Control

The calls in the svcio library are as follows:

	 void              svc_debug(FILE *stream);
	 int   svc       = svc_init(char *cmdline);
	 int   svc       = svc_run(cmdline);
	 int   status    = svc_send(svc, cmd);
	 char *retstr    = svc_receive(svc);
	 int   status    = svc_command(int svc, char *cmd);
	 int   status    = svc_close(int svc);
	 int   status    = svc_closeall();
	 void              svc_sigset();
	 void              svc_sighandler(int sig);
	 SVC  *svcstruct = svc_struct(char *retstr);
	 char *val       = svc_val(char *structstr, char *key, char *val);
	 char *val       = svc_value(char *ref);
where SVC is defined by

         typedef struct
         {
            int  nalloc;
            int  count;
            char **key;
            char **val;
         }  SVC;

Function descriptions:


Structure Format and Dereferencing

Structure strings have the form (see the Structure Format description for details on the genesis of this format):

        [struct ... ]

or

        [array  ... ]

where the body of the structure is composed of key = val, key = val, ... or val, val, ... sets (for structs and array respectively). For the key = val construct, values can be numbers, quoted strings or arrays/structures in their own right.

For illustration, this is a typical structure (newlines added for readability):

        [struct stat = "OK", 
         count = 3, values = [array "first", 2, "and third"],
         child = [struct pid = 55455, date = "Thu Jul 27 09:51:11 PDT 1995"]]

Returns from services are newline-delimited strings and are limited to 4096 characters.

When using svc_val(), element names look like C structure references:

        scale.winref.xval[4]
In this example, "scale", "winref", and "xval" are keys in the returned structure. "4", is the counter for an array.

If the structure for the above was

        [struct name = "test", winref = [struct xval = [array 1, 2, 3, 4, 5],
                yval = [array 6, 7, 8, 9, 10]]]

svc_val(retstr, "scale.winref.xval[4]", val) would return val = "5".


Usage Examples

The following are example code snippets from test programs using the svcio library routines.

test1.c

        index  = svc_init    ("agra -s");
                 svc_send    (index, cmdstr);
        retstr = svc_receive (index);
        val    = svc_struct  (retstr);

             i = val->count;  =>  ( val->key[i], val->val[i] )

                 svc_free    (val);
                 svc_close   (index);

test1 is run with a script file as input (i.e., test1 < script).

test2.c

        index  = svc_init    ("agra -s");
                 svc_send    (index, cmdstr);
        retstr = svc_receive (index);
                 svc_val     (retstr, "return.value[3]", val);
                 svc_close   (index);

test2 requires no arguments.

Both these test programs would require a valid copy of AGRA in the users path.

test3.c

The third example program (programs are available here) reads a service structure from stdin, concatenating multiple lines (for readability) into a single structure. It then recursively decomposes the structure, writing the results to stdout.

Any additional lines in the file are taken to be structure component references and the program looks these up in the structure and prints out the values.

For example, if the input to the program is:

[struct 
   cmd = "pi",
   stat="OK",
   center = [struct 
      pixel_value = 297 ,
      units = " DN",
      coord = [struct 
	 coord_sys = "screen",
	 x = "100",
	 y = [array 
	    100,
	    "      x      ",
	    "",
	    234.333,
	    "abc def"
	 ]
      ],
      coefficients = [array
	 [struct A=0.305, B=0.764, C=0.163, D=0.002],
	 [struct A=0.852, B=0.293, C=0.841, D=0.004],
	 [struct A=0.274, B=0.516, C=0.565, D=0.001],
	 [struct A=0.747, B=0.457, C=0.454, D=0.003],
	 [struct A=0.815, B=0.372, C=0.648, D=0.001]
      ]
   ],
   pixel_count = 1,
   max_pixel_value = 2975,
   frame = 1,
   filename = "/home/jcg/ki0260032.fits"
]

stat
pixel_count
filename
center.coefficients[2].B
center.coord.x
center.coord.y[1]

the following would be output:

---------------------------------------------


   sv->count = 7

   0: <cmd> = <pi>
   1: <stat> = <OK>
   2: <center> = 

      sv->count = 4

      0: <pixel_value> = <297>
      1: <units> = < DN>
      2: <coord> = 

         sv->count = 3

         0: <coord_sys> = <screen>
         1: <x> = <100>
         2: <y> = 

            sv->count = 5

            0: <0> = <100>
            1: <1> = <      x      >
            2: <2> = <>
            3: <3> = <234.333>
            4: <4> = <abc def>


      3: <coefficients> = 

         sv->count = 5

         0: <0> = 

            sv->count = 4

            0: <A> = <0.305>
            1: <B> = <0.764>
            2: <C> = <0.163>
            3: <D> = <0.002>

         1: <1> = 

            sv->count = 4

            0: <A> = <0.852>
            1: <B> = <0.293>
            2: <C> = <0.841>
            3: <D> = <0.004>

         2: <2> = 

            sv->count = 4

            0: <A> = <0.274>
            1: <B> = <0.516>
            2: <C> = <0.565>
            3: <D> = <0.001>

         3: <3> = 

            sv->count = 4

            0: <A> = <0.747>
            1: <B> = <0.457>
            2: <C> = <0.454>
            3: <D> = <0.003>

         4: <4> = 

            sv->count = 4

            0: <A> = <0.815>
            1: <B> = <0.372>
            2: <C> = <0.648>
            3: <D> = <0.001>



   3: <pixel_count> = <1>
   4: <max_pixel_value> = <2975>
   5: <frame> = <1>
   6: <filename> = </home/jcg/ki0260032.fits>

---------------------------------------------

<stat> = <OK>
<pixel_count> = <1>
<filename> = </home/jcg/ki0260032.fits>
<center.coefficients[2].B> = <0.516>
<center.coord.x> = <100>
<center.coord.y[1]> = <      x      >

---------------------------------------------

Author: John Good
Address: jcg@ipac.caltech.edu
Last update: 03-Jan-97