next up previous contents
Next: 6. Document Change Log Up: Status Server Client C Previous: 4. Detailed API   Contents

Subsections

5. Examples

5.1 Retrieve the value of an object from the Status Server

This is the source code for 'ssGet', a command line utility which retrieves the value of an object from the Status Server. The following would retrieve the current temperature reading from the Status Server.


#!/bin/sh
ssGet /p/logger/weather/temperature

Here is the source for the ssGet.c program:


#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include "cli/cli.h"
#include "ss/ss_define.h"
#include "ssapi/ss_api.h"
#include "ssapi/ss_error.h"


/* Print a message to stderr indicating what the proper usage syntax is */
static void usageSyntax(void) {
   fprintf(stderr, "usage: ssGet [NAME=]name\n");
}


/* Clean up routine to free up any used memory and exit with a failure */
static void exitWithFailure(command_opt_t* opts) {
   cli_opts_free(opts);
   exit(EXIT_FAILURE);
}

int
main(int argc, char* const argv[])
{
   char *name = NULL;      /* Location to store the name of the object */
   char *value = NULL;     /* Location to store the value */

   /* Set up the command parsing array for population */
   command_opt_t get_opts[] = {
      { "n*ame", &name, "The name of the object" },
      OPTIONLIST_END
   };

   /* Parse the argument list */
   if (cli_opts(argv + 1, get_opts) != argc - 1) {
	    
      /* Error occured during option parsing */
      usageSyntax();
      exitWithFailure(get_opts);
   }

   /* Make sure that a valid object name was supplied */
   if (!name || !*name) {
	       
      /* Error occured during option parsing */
      usageSyntax();
      exitWithFailure(get_opts);
   }

   /* Allocate space to hold the value returned from the Status Server */
   value = (char *)malloc(SS_MAX_VALUE_SIZE);
   if (value == NULL) {
      fprintf(stderr, "error: memory allocation failed.\n");
      exitWithFailure(get_opts);
   }

   /* Log on to the Status Server */
   if (ssLogon(argv[0]) == FAIL) {
      fprintf(stderr, "Connection failed: %s\n", ssGetStrError()); 
      free(value);
      exitWithFailure(get_opts);
   }

   /* Retrieve the contents from the Status Server */
   if (ssGetString(name, value, SS_MAX_VALUE_SIZE) == FAIL) {
      fprintf(stderr, "ssGet `%s' failed: %s\n", name, ssGetStrError());
      free(value);
      exitWithFailure(get_opts);
   }
   puts(value);
   free(value);
   cli_opts_free(get_opts);
   exit(EXIT_SUCCESS);
}

5.2 Update the value of a Status Server object

This is the source code for 'ssPut', a command line utility which update the value of a Status Server object. The following would update the value of ``/test/testval1'' to be ``TEST VALUE'' with a lifetime of 5 seconds. In this case, if the object does not already exist, it would be created prior to being updated.


#!/bin/sh
ssPut /test/testval1 "TEST VALUE" comment="test update" lifetime=5

Here is the source for the ssPut.c program:


#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <limits.h>
#include "cli/cli.h"
#include "ss/ss_define.h"
#include "ssapi/ss_api.h"
#include "ssapi/ss_error.h"


/* Print a message to stderr indicating what the proper usage syntax is */
static void usageSyntax(void) {
   fprintf(stderr, "usage: ssPut [NAME=]name [VALUE=]value "
	   "[COMMENT=comment] [LIFETIME=lifetime]\n");
}


/* Clean up routine to free up any used memory and exit with a failure */
static void exitWithFailure(command_opt_t opts[]) {
   cli_opts_free(opts);
   exit(EXIT_FAILURE);
}


int
main(int argc, char* const argv[])
{
   char *name = NULL;      /* Location to store the name of the object */
   char *comment = NULL;   /* Location to store the comment */
   char *lifetime = NULL;  /* Location to store the lifetime value */
   char *value = NULL;     /* Location to store the value */
   PASSFAIL rc;            /* Return code value */ 

   time_t lifetime_val = 0;      /* lifetime (0=unlimited) */

   /* Set up the command parsing array for population */
   command_opt_t put_opts[] = {
      { "n*ame",     &name,     "Name of the object"                 },
      { "v*alue",    &value,    "Value of the object"                },
      OPTIONLIST_NONPOSITIONAL,
      { "c*omment",  &comment,   "Descriptive comment of the object" },
      { "l*ifetime", &lifetime,  "Time(seconds) this object is valid"},
      OPTIONLIST_END
   };

   /* Parse the argument list */
   if (cli_opts(argv + 1, put_opts) != argc - 1) {
	    
      /* Error occured during option parsing */
      usageSyntax();
      exitWithFailure(put_opts);
   }

   /* Make sure that at a minimum, a valid object name, and object 
    * value were supplied */
   if (!name || !*name || !value) {
	       
      /* Error occured during option parsing */
      usageSyntax();
      exitWithFailure(put_opts);
   }

   /* Check to make sure that the value specified by the client 
    * not beyond what the Status Server can store */
   if (strlen(value) > SS_MAX_VALUE_SIZE) {
      fprintf(stderr, "error: value to large to store in the "
	      "Status Server");
      exitWithFailure(put_opts);
   }

   /* Make sure if a lifetime parameter was supplied that it is valid */
   if (lifetime && *lifetime) {
		  
      /* Parse the lifetime option */
      char *stop_at = NULL;     /* Location at which strtol may stop */

      lifetime_val = strtol(lifetime, &stop_at, 10);

      if (lifetime_val < 0 || *stop_at != '\0' ||
	  ((lifetime_val == LONG_MIN || lifetime_val == LONG_MAX) && 
	   (errno == ERANGE)) ||
	  ((lifetime_val == 0) && (errno == EINVAL))) {

	 /* lifetime value is invalid */
	 fprintf(stderr, "error: lifetime parameter supplied is invalid");
	 exitWithFailure(put_opts);
      }
   }

   /* Log on to the Status Server */
   if (ssLogon(argv[0]) == FAIL) {
      fprintf(stderr, "Connection failed: %s\n", ssGetStrError()); 
      exitWithFailure(put_opts);
   }

   /* Perform a touch of the object in the Status Server */
   if (lifetime && *lifetime)
      rc = ssTouchObjectWithLifetime(name, comment, lifetime_val);
   else
      rc = ssTouchObject(name, comment);

   if (rc == FAIL) {
      fprintf(stderr, "Put failed: %s\n", ssGetStrError());
      exitWithFailure(put_opts);
   }

   /* Perform an update of the object in the Status Server */
   if (ssPutString(name, value) == FAIL) {
      fprintf(stderr, "ssPut failed: %s\n", ssGetStrError());
      exitWithFailure(put_opts);
   }
   cli_opts_free(put_opts);
   exit(EXIT_SUCCESS);
}

5.3 Monitor a Status Server object

This is the source code for 'ssMonitor', a command line utility which will place monitor on a Status Server object and exit with a new value once it is different than the value specified on the command line.


#!/bin/sh
ssMonitor /test/testval1 "OLD VALUE"

Here is the source for the ssMonitor.c program:


#ifdef VXWORKS
#include <selectLib.h>
#else
#include <sys/time.h>
#include <sys/types.h>
#endif
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <unistd.h>
#include "cli/cli.h"
#include "ss/ss_define.h"
#include "ssapi/ss_api.h"
#include "ssapi/ss_error.h"


/* Print a message to stderr indicating what the proper usage syntax is */
static void usageSyntax(void) {
   fprintf(stderr, "usage: ssMonitor [NAME=]name [VALUE=]value\n");
}


/* Clean up routine to free up any used memory and exit with a failure */
static void exitWithFailure(command_opt_t* opts) {
   cli_opts_free(opts);
   exit(EXIT_FAILURE);
}


int
main(int argc, char* const argv[])
{

   char *name = NULL;            /* location to store the name */
   char *value = NULL;           /* object value for comparison */
   char *ss_value = NULL;        /* value received from the Status Server */
   ss_stat_t status = SS_VALID;  /* object status */

   /* Set up the command parsing array for population */
   command_opt_t mon_opts[] = {
      { "n*ame", &name,   "Name of the object"        },
      { "v*alue", &value, "Value used for comparison" },
      OPTIONLIST_END
   };

   /* Parse the argument list */
   if (cli_opts(argv + 1, mon_opts) != argc - 1) {
	    
      /* Error occured during option parsing */
      usageSyntax();
      exitWithFailure(mon_opts);
   }

   /* Make sure that a valid object name and comparison value were supplied */
   if (!name || !*name || !value) {
	       
      /* Error occured during option parsing */
      usageSyntax();
      exitWithFailure(mon_opts);
   }

   /* Allocate space to hold the value returned from the Status Server */
   ss_value = (char *)malloc(SS_MAX_VALUE_SIZE);
   if (ss_value == NULL) {
      fprintf(stderr, "error: memory allocation failed.\n");
      exitWithFailure(mon_opts);
   }

   /* Log on to the Status Server */
   if (ssLogon(argv[0]) == FAIL) {
      fprintf(stderr, "Connection failed: %s\n", ssGetStrError()); 
      free(ss_value);
      exitWithFailure(mon_opts);
   }

   /* Place a monitor on the Status Server variable */
   if (ssMonitorString(name, SS_MAX_VALUE_SIZE,
		       ss_value, &status) == FAIL) {
      fprintf(stderr, "ssMonitor failed: %s\n", ssGetStrError());
      free(ss_value);
      exitWithFailure(mon_opts);
   }

   /* Go in to a loop surrounding ssWait() and break out of the routine 
    * when the retrieved value following a monitor update is different
    * than the specified value */
   for (;;) {

      /* Initiate a poll request to retrieve monitor information.  The
       * ssWait() routine with a parameter of -1 will cause the wait
       * to block indefinitely until data is received on the socket */
      if (ssWait(-1) == FAIL) {
	 fprintf(stderr, "Poll failed: %s\n", ssGetStrError());
	 free(ss_value);
	 exitWithFailure(mon_opts);
      }
	 
      /* Check whether the return value is valid.  If so, echo the
       * new monitored value to stdout.  Otherwise, continue back in
       * the select loop. */
      if (status == SS_VALID) {
	 if (strcmp(ss_value, value) != 0) {
	    puts(ss_value);
	    free(ss_value);
	    cli_opts_free(mon_opts);
	    exit(EXIT_SUCCESS);
	 }
      }
      else {
	 if (status == SS_NONEXISTENT) {
	    fprintf(stderr, "Monitored object does not exist\n");
	 } else if (status == SS_NOTDEFINED) {
	    fprintf(stderr, "Monitored object is not defined\n");
	 } else if (status == SS_EXPIRED) {
	    fprintf(stderr, "Monitored object is expired\n");
	 }
	 else {
	    fprintf(stderr, "Invalid monitor object status\n");
	 }
	 free(ss_value);
	 exitWithFailure(mon_opts);
      }
   }
}


next up previous contents
Next: 6. Document Change Log Up: Status Server Client C Previous: 4. Detailed API   Contents
Tom Vermeulen
2008-02-07