NAME

       VistaIOParseFilterCmd - parse command line options and filenames

SYNOPSIS

       #include <vistaio.h>

       void VistaIOParseFilterCmd (noptions, options, argc, argv, input, output)
              int noptions, argc;
              VistaIOOptionDescRec options[noptions];
              char *argv;
              FILE *input;
              FILE *output;

ARGUMENTS

       noptions  Specifies the number of entries in the table of option descriptors.

       options   Specifies the location of the table of option descriptors.

       argc      Specifies the number of command line arguments to be parsed.

       argv      Specifies a vector of command line arguments to be parsed.

       input     Returns a pointer to the input file. The input file is set as specified in the command line, or
                 else it defaults to the standard input stream. If input is NULL, then it  is  assumed  that  no
                 input   file   is   required.   Note  that  the  file  is  opened  and  ready  for  input  when
                 VistaIOParseFilterCmd returns.

       output    Similar to input, except that it returns the output file, which defaults to the standard output
                 stream.

DESCRIPTION

       VistaIOParseFilterCmd  is  used  to  parse command line options and filenames for most Vista programs. It
       implements the standard Vista command line options -help, -in,  and  -out,  and  reports  all  errors  in
       parsing  or  in  attempting to open the input and output files. Its major limitation is that it allows at
       most one input file and one output file.

       Options particular to a program are specified in a table given by the noptions and options arguments. See
       the VistaIOoption(3) manual page for the form of this table.

       The  argc  and  argv  arguments  to VistaIOParseFilterCmd are normally identical to the parameters of the
       program's main function.

       VistaIOParseFilterCmd   uses   the   first   command   line   argument,   argv[0],   in   a    call    to
       VistaIOSetProgramName(3) to record the program's name for future error messages.

       The  remaining  command  line  arguments  are  then  processed  sequentially.  An argument is examined to
       determine whether it is an initial substring of any option keyword defined in the options table.  If  so,
       arguments following the keyword may be parsed as values associated with the option. The values are stored
       at locations specified by the options table.

       In addition to the options specified by the options table, VistaIOParseFilterCmd recognizes  the  options
       -help,  -in,  and  -out.  When  it  encounters  -help,  VistaIOParseFilterCmd  prints  the  command usage
       information and exits. The -in and -out arguments are used to identify input  and  output  files,  as  is
       standard for Vista programs.

SEE ALSO

       VistaIOParseCommand(3), VistaIOIdentifyFiles(3), VistaIOoption(3),

NOTES

       VistaIOParseFilterCmd may modify the argv vector of command line arguments.

DIAGNOSTICS

       VistaIOParseFilterCmd  reports  errors in command line options by printing directly to the standard error
       stream. For all major errors, VistaIOParseFilterCmd also exits the program with a status code of 1 rather
       than  return  to  the caller. Error reports include the program name obtained from argv[0]. The following
       messages may be produced:

       ``Duplicate -option option; ignoring all but last.''
              The specified option was found more than once on the command line.

       ``Option -option has incorrect value arg.''
              One of the values associated with -option on the command line is arg, which is of the  wrong  form
              with respect to the type of value required.

       ``Option -option requires m value(s); found only n.''
              The  option keyword -option must be followed by n values on the command line. Only m were present,
              however.

       ``Option -option must be specified.''
              The option -option is required but it was not present on the command line.

       ``Unable to open input/output file filename.''
              An error was detected while attempting to open a file named on the command line.

AUTHOR

       David Lowe <lowe@cs.ubc.ca>

       Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>