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>