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);

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

Function descriptions:

• svc_debug() The library will print a running commentary on what memory it is allocating, what commands it is sending to what services, etc. to whatever stream this function selects (usually stdout though the default is (FILE *)NULL).

• svc_init() Child services are started by giving this routine a command-line-like string (e.g. "skyview -n -server"). The return string is an integer handle to be used in future references to the service.

• svc_run() This routine is a wrapper for svc_init(), svc_command(), and svc_close(), where all the user wants to do is run a command-line driven program which runs to completion and returns a single structure.

• svc_send() Send a command to a service.

• = svc_receive() Recieve a response from a service. Usually, this response will be in the form of a structure string and usually there will be only on response for each svc_send() call. However, this routine can be called multiple times in those cases where there are multiple lines of response.

• svc_command() This routine is a wrapper for svc_send() and svc_receive() in the usual case where there is one of each called one after the other.

• svc_close() Closes a service.

• svc_closeall() Closes all active services.

• svc_sigset() If this routine is called, all signals (except of course for SIGKILL which cannot be trapped) will be sent to the function svc_sighandler().

• svc_sighandler() The default svc_sighandler() function prints (to the svc_debug() stream) a message for any fatal signals, then exits. All other signals it ignores and continues execution. This routine can be overridden by the user or individual signal handlers can be implemented for specific signals (e.g.SIGALRM).

• svc_struct() This routine takes apart a string which has the form of a return stucture (see below) and populates a SVC structure. It is not recursive; elements of the structure which are themselves need to be taken apart individually as needed.

• svc_val() This routine (using svc_struct() recursively) looks up a specific structure value (see below).

• svc_value() This a a wrapper for svc_val() for the specific case where we are taking apart the string returned internally by svc_command. Also, rather than putting the result into a val argument, svc_value() also takes the responsibility for managing string space and returns a pointer to the extracted value.

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]

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      >

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