The tsmAPI Library: Tutorials

PARSING COMMAND LINE ARGUMENTS

When developing any shell applications you will normally want to parse the command line to see if the user has supplied any arguments or options to your program. Because this is such a common process, tsmApi provides you with facilities to parse your command line, as well as routines that can perform certain tsmApi functions automatically based upon certain command line options.

In the first instance, tsmApi provides you with the following functions to allow you to parse your command line easily and effortlessly:

tsmGetArg : checks for the existence of a simple argument, such as "-arg".
tsmGetArgInt checks for the existence of an argument and then returns the value following that argument as an integer. This is useful for parsing arguments like "-size 5".
tsmGetArgFloat checks for the existence of an argument and then returns the value following that argument as a floating point value. This is useful for parsing arguments like "-scale 0.5".
tsmGetArgString checks for the existence of an argument and then returns the string following that argument. This is useful for parsing arguments like "-name Yosemite".

For example:

   int    arg_supplied, size;
   double scale;

   arg_supplied = tsmGetArg( argc, argv, "-arg" );
   tsmGetArgInt( argc, argv, "-size", &size );
   tsmGetArgFloat( argc, argv, "-scale", &scale );

In addition to giving you tools for you to parse the command line, tsmApi provides functions that will parse the command line looking for some standard tsmApi arguments and then perform some specific function for you. To take the simplest case first, the tsmParseArgs function will check your command line for the -debug option and will set the tsmApi debug trace level to the value following the option, e.g. at the start of your program you would simply put:

   int main( int argc, char **argv ) {
      tsmParseArgs( argv, argc ); 
      ...

Another power facility is the ability to get tsmApi to create a TsmConnectionParams structure for you based upon your command line. This structure is passed to tsmConnect to control various characteristics of the connection and the data that is selected. This lets you easily support all of the power of the TsmConnectionParams facility without ever needing to allocate the structure, parse the command line yourself, set entries in the structure, etc. You just use one of tsmParseReadArgs or tsmParseWriteArgs, depending upon whether you are opening a read or a write connection. For example:

   TsmConnectionParams params;

   params = tsmParseReadArgs( argv, argc );
   tsmConnect( name, "r", params );
   tsmFreeParams( params );   /* don't forget this bit */

The advantages of these construct are:

Your program automatically supports the various command line options with full error checking and reporting.
If more facilities are provided by tsmApi in the future, then your program just needs a recompile and it will automatically take advantage of these new command line options.
All programs developed using tsmApi will have a standard set of command line options.
And finally, it just makes your life easier!

You may also want to print out a helpful list of command line options if the user does not provide any command line options. If you don't know what options tsmParseArgs or tsmParseReadArgs is scanning for, then how do you know what options to say that your program supports. The answer: you don't. There is a function called tsmDescribeArgs that will print out a description of the currently support set of tsmApi options that it will search for. So you can do something like:

   if ( argc == 1 ) {
      printf( "usage: foo [...]\n" );
      tsmDescribeArgs( TSM_ARG_INIT | TSM_ARG_READ );
      /* means that we have used tsmParseArgs and tsmParseReadArgs */
   }

Next Tutorial: The Emulation Layer
Previous Tutorial: Copying Data
Manual Page References: tsmGetArg, tsmGetArgInt, tsmGetArgFloat, tsmGetArgString, tsmParseArgs, tsmParseReadArgs, tsmParseWriteArgs, tsmParseConnectArgs, TsmDescribeArgs

The tsmApi Home Page / The tsmApi Tutorials Page

Martin Reddy, <reddy@ai.sri.com> / Yvan Leclerc, <leclerc@ai.sri.com>
Last modified: Wed Aug 23 00:45:38 PDT 2000