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.
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.