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>

VistaIO Version 1.2.14                           28 January 1994                        VistaIOParseFilterCmd(3)