libsvc.a
Service I/O Library and Return Structure Handling
|
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.
|
| |
|
Platforms:
Blurb about being tested on XXX platforms, but since written in ANSI-C should be platform-independent
|
| |
|
Comments:
Structure strings have the form:
[struct ... ]
or
[array ... ]
where the body of the structure is composed of key = val, key = val, ... or val, val, ... sets (for structures and arrays 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".
|
Library Routines:
svc_debug() |
| |
|
Description:
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)
Syntax:
svc_debug(*FILE)
|
| |
| Input |
Data Type |
Description |
|
| FILE |
file pointer |
location to write debugging stream |
|
| |
|
svc_init() |
| |
|
Description:
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.
Syntax:
index = svc_init(*cmdline)
|
| |
| Input |
Data Type |
Description |
|
| cmdline |
string |
command line to start service |
|
| |
| Output |
Data Type |
Description |
|
| index |
integer |
index number of process |
|
| |
|
svc_send() |
| |
|
Description:
Sends a command string to a service.
Syntax:
status = svc_send(index, *cmd)
|
| |
| Input |
Data Type |
Description |
|
| index |
integer |
index of service to be given command |
|
| cmd |
string |
command to send to service |
|
| |
| Output |
Data Type |
Description |
|
| status |
integer |
0 if successful; -1 if error |
|
| |
|
svc_receive() |
| |
|
Description:
Receives a response from a service
Syntax:
*msg = svc_receive(index)
|
| |
| Input |
Data Type |
Description |
|
| index |
integer |
index of service to be given command |
|
| |
| Output |
Data Type |
Description |
|
| msg |
string |
response from service |
|
| |
|
svc_command() |
| |
|
Description:
Relatively generic interaction routine, where we assume there will be a response to each command,
and if the response is an invalid structure we exit (calls svc_send() and svc_receive() in tandem).
Syntax:
status = svc_command(index, *cmd)
|
| |
| Input |
Data Type |
Description |
|
| index |
integer |
index of service |
|
| cmd |
string |
command to be given to service |
|
| |
| Output |
Data Type |
Description |
|
| status |
integer |
0 if service gives a valid response; -1 if an invalid response is received. |
|
| |
|
svc_close() |
| |
|
Description:
Closes down a service.
Syntax:
status = svc_close(index)
|
| |
| Input |
Data Type |
Description |
|
| index |
integer |
index of service |
|
| |
| Output |
Data Type |
Description |
|
| status |
integer |
0 if successful; -1 for error. |
|
| |
|
svc_closeall() |
| |
|
Description:
Closes down all services.
Syntax:
status = svc_closeall()
|
| |
| Output |
Data Type |
Description |
|
| status |
integer |
0 if successful; -1 for error. |
|
| |
|
svc_value() |
| |
|
Description:
Relatively generic routine to extract the structure value requested and return a string pointer to it.
Syntax:
*strval = svc_value(*ref)
|
| |
| Input |
Data Type |
Description |
|
| ref |
string |
name of structure. For instance, if a service returned the message:
[struct stat="OK", lon="37.2" ...
then ref would be "lon". |
|
| |
| Output |
Data Type |
Description |
|
| strval |
string |
value of the requested structure |
|
| |
|
Usage Examples
agra = svc_init( "agra -s -x" );
svc_command(agra, "pscolor on");
svc_command(agra, "gifsize 640");
if(gotlocation)
svc_command(agra, "scale x y");
strcpy(scale_proj, svc_value("return.proj"));
svc_command(agra, "apply");
}
svc_command(agra, "dcs eq J 2000");
svc_command(agra, "gcs eq J 2000");
svc_command(agra, "color black");
svc_command(agra, "border");
svc_command(agra, "pscolor on");
svc_command(agra, "color blue");
svc_command(agra, "grid");
svc_command(agra, "border");
svc_command(agra, "color green");
sprintf(cmd, "%s/images.agra", directory);
svc_command(agra, cmd);
.
.
.
svc_command(agra, cmd);
svc_command(agra, "quit" );
svc_close(agra);
|