PIP(1)                    General Commands Manual                    PIP(1)



NAME
       PIP - package for parsing input parameters from Fortran or C

USER DESCRIPTION
       PIP is a package of functions for entering parameters into programs.
       A program using PIP will accept input in two different ways.
       Options and their values can be entered as command line arguments,
       or on separate lines with one option name per line followed by its
       value.  The multi-line entry can be made via standard input, on
       lines following the command line invoking the program; in addition,
       the program may also allow entries in this format to be read from a
       separate parameter file.  These different methods may even be used
       together, with some options taken from the command line and some
       from line entries.

       Options are generally given both a short and long name, with the
       short name designed for convenience when used at the command line,
       and the long name being more descriptive for use in command files.
       However, either form may be used in either place.  The names are
       case-sensitive.  Options can be abbreviated to their shortest unique
       form, sometimes one or two letters.

       When entered at the command line, options must be preceded by one or
       two dashes (- or --).  The option must be followed by a space then a
       value if appropriate.  If the value contains embedded blanks it must
       be enclosed in quotes.  Options cannot be concatenated the way
       single letter options in Unix programs often can be.

       Multiple-line entry is invoked by entering the argument
       -StandardInput on the command line, or, if the program allows, by
       entering the option to read a parameter file, followed by the name
       of the file.  The program will read lines of input until the tag
       EndInput is read or until the end of the file is reached.  It will
       then resume processing command line arguments, if any.

       The format of the line entry is an option name followed by any
       number of spaces or tabs and an optional equals sign, followed by
       the value of the option.  If the value consists of multiple numbers,
       they can be separated by spaces, tabs or commas.  If a value
       consists of a text string, it may contain embedded blanks.

       Blank lines and lines starting with # are ignored.  A comment
       starting with # can also be placed on a line after an option and its
       value.

       Programs may allow Fortran-style default input, in which a comma
       without a number indicates that the default value for the number
       should be taken, and a / indicates that all remaining numbers have
       their default values.  For example, 23,,15 takes the default for the
       second value and ,42,17 takes the default for the first; 1,1024/
       takes the default for all values after the first two and / takes the
       default for all values.  Defaults can be used only when a fixed
       number of values are expected.

       Boolean options are ones that turn a particular feature on or off.
       When entered as command lines arguments, they must not be followed
       by a value; in other words, the presence of the entry sets the
       option to true or on.  However, when a boolean option is entered in
       a separate line in a command file, it may be followed by 0, F, f,
       FALSE, false, OFF, off, 1, T, t, TRUE, true, ON, or on.

       Options can be entered more than once.  In most cases a later value
       will supercede a previous entry, but in some cases the multiple
       entries will accumulate.  This is useful if multiple input file
       names are needed, or if more numbers need to be entered than will
       fit on a line.  In rare cases, each entry of an option is associated
       with (linked to) the next entry of another option; this is the only
       situation where the order of entering different options matters.

       PIP provides a standard help output which the program should make
       available with an option such as -help or -usage.  Invoking a
       program with no arguments may also cause this to be printed, unless
       the program still supports old-style interactive input as the
       default when there are no arguments.  The help output will list the
       two forms for each option, indicate what kind of value is expected,
       and provide a one-line description of the option.  In addition, it
       will indicate if multiple entries of an option will accumulate.

       The man page and usage output will also show the current shortest
       unique short name for each option in parentheses.  These allowed
       abbreviations can change when new options are added, but should
       never become longer than three letters.  Thus, when writing a script
       that runs a program with short option names, always use at least 3
       letters for each option.

       For example, suppose you wanted a shell script to run newstack and
       reduce a file by the number in its first argument and convert to
       bytes, with input and output files in the second and third
       arguments.  To use the command line format, you could write
          newstack -mod 0 -flo 2 -shr $1 "$2" "$3"

       where the $2 and $3 are quoted because they might contain spaces,
       and every option is specified with 3 letters. Sequential input would
       be written as

       newstack -StandardInput << ENDHERE
         InputFile $2
         OutputFile $3
         ModeToOutput 0
         FloatDensities 2
         ShrinkByFactor $1
       ENDHERE

       where the "ENDHERE" is an arbitrary delimiter.  Note that the input
       can be indented for clarity.


PROGRAMMING DESCRIPTION
       The simplest way to use PIP is first to set up its state with
       optional calls to PipExitOnError and PipAllowCommaDefaults, then
       pass it the list of options and have it parse input with
       PipParseInput, then get option values with a series of PipGet...
       calls, then finish with PipDone.  PIP can also read the list of
       options from a separate file, referred to as an autodoc file.  In
       this case, instead of calling PipParseInput, one calls
       PipReadOptionFile to read the options from the file, then
       PipParseEntries to parse the input.  There is also a convenience
       function, PipReadOrParseOptions, that will first try to read options
       from an autodoc file, then fall back to a list of options supplied
       by the calling program.

       For use from C, the header file parse_params.h is in the
       IMOD/include directory.  The PIP package and Fortran-callable
       wrappers are in the libcfshr library.  The Fortran versions of
       PipParseInput and PipReadOptionFile are in the libhvem library,
       which requires libcfshr.

       Fortran-callable wrappers to the C functions have been given the
       same name as the C functions, although internally they are all lower
       case with an underscore appended, or all uppercase in Windows.  The
       function calls from Fortran are case-insensitive but they are shown
       with mixed case here for clarity.

       PIP can also be used from Python by importing the pip module in the
       IMOD/pylib directory.  Up to IMOD 3.11 this was a compiled extension
       module using the C code, but this is now written in Python to avoid
       compatibility problems.  The calling conventions are described in a
       separate section below.


   Option Specifications Supplied by the Calling Program
       Each legal option should be specified with a string having up to 4
       components:
         shortName:longName:type:helpString

       The short name is intended to be used predominantly on the command
       line, while the long name would be more suitable in parameter files.
       However, PIP makes only one distinction between the short and long
       names - if a short name consists of a single letter, there can be
       other short names starting with that letter.  Either name can be
       abbreviated, either name can be preceded by either one or two
       dashes, and either name can be omitted.  Any of these 4 components
       can be omitted as long as there is either a short or a long name.
       The string must have 3 colons.


   Option Types
       B    Boolean - the only type that does not require a value
       I    Integer
       IP   Pair of integers
       IT   Three integers
       IA   Integer array
       F    Floating point
       FP   Pair of floating point numbers
       FT   Three floating point numbers
       FA   Floating point array
       CH   Character string
       FN   File name
       LI   List (comma-separated list of ranges)
       PF   Parameter file

       If an option specification ends in M or L, this indicates that
       multiple entries of the option will accumulate rather than supercede
       each other.  This allows multiple filenames of a particular type to
       be entered, or multiple lines of input for long lists of numbers.
       The L ending indicates that each entry of the option is associated
       with, or linked to, the next occurrence of some other option.  It
       must be specified in order to use the PipLinkedIndex function.

       PIP uses these types primarily to provide information in the help
       output and does not enforce the implications of these types, except
       as follows: an option that does not take an argument must be coded
       as B; a parameter file option must be coded as PF.


   Option Specifications in an Autodoc File
       The autodoc file is designed to provide a single source of
       information about program options for the program itself, the man
       page, and graphical user interfaces that run the program.  The file
       consists of global metadata at the start, then a series of sections
       starting with a token inside brackets.  Each section can then
       contain keyword-value pairs.  The general form of a token entry is:
          [token delimiter value]
       and the general form of a keyword-value pair is:
          keyword delimiter value
       Tokens, keywords, and token values must not contain embedded spaces,
       although keyword values may.  There must be no space between the
       opening [ and a token or between its value and the ending ].  There
       can be spaces or tabs before and after the delimiter; these will not
       be considered part of the token or value strings.  PIP will ignore
       white space before keywords or tokens, but other parsers of autodoc
       files may not accept this.  The default delimiter is an equals sign
       (=).  It can be changed once, in the metadata, before any tokens
       have been encountered, with a statement such as:
          KeyValueDelimiter = ==

       PIP will examine keyword-value pairs only after a Field token, which
       signifies the start of an option, or after a SectionHeader token,
       which can be used to introduce some header text into the usage or
       manpage outputs.  The following keywords are understood by PIP in a
       Field section, while others are ignored:
       short    Short option name
       long     Long option name
       type     Type of option; see table above
       format   String shown after the option in usage or manpage output
       default  Default value returned when no option is entered
       usage    Help string for usage output
       tooltip  Help string for tooltip
       manpage  Help string for manual page

       If one of these keywords has no value after it, PIP will ignore the
       entry.  Short and long option names should not contain spaces.  If a
       Field has a value, it becomes the default long option name, in which
       case long can be omitted.  Alternatively, a long entry can be used
       to override the value of the field, and a blank long entry can be
       used to eliminate the default long option name provided by a Field
       value.

       If a format entry is destined for a .man-type manpage, it will be
       italicized by default by wrapping it in \fI and \fR.  It can contain
       these kind of font specifiers, and the default wrapping will be
       omitted if it starts with one of the specifiers.  Thus, enclose the
       entry in \fB and \fR or start it with \fR to have it be in bold or
       regular font.

       The help strings are allowed to contain spaces, and to continue on
       multiple lines.  A continuation line should not have # or [ as its
       first non-white space character, nor should it contain the key-value
       delimiter.  Lines are added to a help string until a line with the
       delimiter is encountered.  If you want to use = in help strings,
       change the delimiter to == as shown above, or enclose the entire
       (possibly multiline) string in quotes.  The quote can be a single
       quote, double quote, or backtick character.  PIP will look for a
       matching quote only at the end of a line, but other autodoc parsers
       may be confused by a matching quote embedded in the line, so it is
       best to use a quote that is not used literally in the string.

       Use ^ at the beginning of a continuation line to start a new line
       before outputting the text on the line.  Spaces after the ^ will be
       retained, so that lines can be indented in a man page.

       Lines containing only white space, and lines with # as the first
       non-white space, are ignored.

       If a default value is supplied with the default entry, help strings
       can contain %{default}, which will be substituted with the default
       value.  Do not change delimiters from = when using default values,
       because then these entries will not be recognized by the script that
       creates a fallback list of default settings, which is used when an
       autodoc cannot be found.  Defaults cannot be set for boolean
       options.

       In a SectionHeader section, keywords besides usage and manpage are
       ignored.  Help strings will be output without indentation; for a man
       page that is input to nroff, start the string with .SS or .SH to
       avoid the regular indentation of option text.

       Other meaningful metadata entries are NoHelpAbbrevations to avoid
       showing unique abbreviations in help output, NoAbbreviations to turn
       on the flag for no abbreviations internally and allow otherwise
       ambiguous options, and DoubleDashOptions to show options with two
       dashes in help output.


   Errors and Return Values
       All functions return a negative number if an error occurs.
       Functions in which an option is specified typically return -1 if the
       option is not a legal one, or -2 if the option is abbreviated
       ambiguously.  An error string is available after an error by calling
       PipGetError.  Alternatively, the program can call PipExitOnError at
       any point, and PIP will print the error string itself and exit with
       an error status.


   Functions for Initialization
       int PipExitOnError(int useStdErr, const char *prefix);

       integer*4 function PipExitOnError(useStdErr, prefix)
       integer*4 useStdErr
       character*N prefix

       Use this function to enable PIP to exit with a message upon any
       error in program function or user input.  The string prefix will be
       placed in front of the error message that PIP ordinarily generates
       upon error, and the message will be printed to standard output or
       standard error depending on whether useStdErr is 0 or 1.  PIP will
       exit with an error status.  If prefix is an empty string, then this
       feature is disabled.


       void PipAllowCommaDefaults(int val);

       subroutine PipAllowCommaDefaults(val)
       integer*4 val

       If Ival is non-zero, then Fortran-style default input will be
       allowed whenever a fixed number of values are being returned.
       Specifically, if commas are used to separate entries and there is no
       entry between a pair of commas, then the returned value will be
       unmodified from the default value supplied in the call.  A /
       character will terminate input and leave all remaining expected
       elements at their default values.


       void PipSetSpecialFlags(int noCase, int doneEnds,  int takeStdin,
                               int nonOptLines,  int noAbbrevs)

       subroutine PipSetSpecialFlags(noCase, doneEnds,  takeStdin,
                                     nonOptLines,  noAbbrevs)
       integer*4 noCase, doneEnds,  takeStdin, nonOptLines, noAbbrevs

       This call can be used to set flags that modify the behavior as
       follows:
       noCase non-zero allows case-insensitive options
       doneEnds non-zero allows DONE to be used in place of EndInput
       takeStdin non-zero runs a program with no arguments as if
       -StandardInput were entered
       nonOptLines greater than zero allows the first few lines of input to
       be taken as non-option arguments, up to a number of lines given by
       the value.
       noAbbrevs non-zero means that options must be entered in full
       The first four behaviors were required to convert Tilt to PIP
       input without retaining the old input code, but none of this should
       be needed elsewhere.

       int PipSetLinkedOption(const char *option);

       integer*4 function PipSetLinkedOption(option)
       character*N option
       This function will set a specific option as the linked option, so
       that the current count (index of next occurrence) of that option
       will be recorded for each entry of other options.

       int PipParseInput(int argc, char *argv[], const char *options[],
                         int numOptions, int *numOptArgs,
                         int *numNonOptArgs);

       integer*4 function PipParseInput(options, numOptions, separator,
                                        numOptArg, numNonOptArg)
       character*N options(N)
       integer*4 numOptions
       character separator
       integer*4 numOptArg, numNonOptArg    [Returned arguments]

       This is a high-level function that will initialize PIP
       (PipInitialize) for the number of options given in numOptions, take
       the list of all available options specified in options and add them
       one at a time with PipAddOption, parse command line arguments and
       other input with PipNextArg, and return the number of option
       arguments in numOptArg and the number of non-option arguments in
       numNonOptArg.  At the end, it calls PipPrintEntries, which will
       print program entries if enabled (see below).  The C version
       receives the command line arguments directly while the Fortran
       version fetches them with getarg.

       There are two alternatives for Fortran usage.  Each option
       specification can be placed in a separate element of the options
       array.  In this case, options should be dimensioned to the number of
       options, separator should be a space character, and the length of
       the character elements of the array should at least as big as the
       longest option description.  Alternatively, all of the options can
       be placed in one character string, separated by the character given
       in separator.  In this case, set the dimension of options to 1 and
       make its length be big enough for the entire string.


       int PipReadOptionFile(const char *progName, int helpLevel, int localDir)

       integer*4 function PipReadOptionFile(progName, helpLevel, localDir)
       character*N progName
       integer*4 helpLevel, localDir

       This function will read options from an autodoc file, progName.adoc.
       If localDir is 0, this file will be sought first in the directory
       pointed to by the environment variable AUTODOC_DIR, if it is
       defined; then in the directory $IMOD_DIR/autodoc; then in the
       current directory.  If localDir is 1 or 2, etc., the file will be
       sought in ../autodoc or ../../autodoc, etc., then in the current
       directory.  This allows PIP to generate a man page entry from the
       autodoc file in the current source tree rather than in the installed
       version of IMOD.

       The helpLevel argument determines which help string is used when
       multiple strings are available.
       If helpLevel is 1, then the usage string will be stored if
       available, or the tooltip string if there is no usage string, or the
       manpage string if neither tooltip nor usage is available.
       If helpLevel is 2, then the tooltip string will be stored if
       available, or the usage string if there is no tooltip string, or the
       manpage string if neither tooltip nor usage is available.
       If helpLevel is 3, then the manpage string will be stored if
       available, or the tooltip string if there is no manpage string, or
       the usage string if neither tooltip nor manpage is available.


       int PipParseEntries(int argc, char *argv[], int *numOptArgs,
                           int *numNonOptArgs);

       integer*4 function PipParseEntries(numOptArg, numNonOptArg)
       integer*4 numOptArg, numNonOptArg    [Returned arguments]

       This high-level function is used after options have been read from
       an autodoc file with PipReadOptionFile.  It parses command line
       arguments and other input with PipNextArg, and return the number of
       option arguments in numOptArg and the number of non-option arguments
       in numNonOptArg.  The C version receives the command line arguments
       directly while the Fortran version fetches them with getarg.


       subroutine PipReadOrParseOptions(options, numOptions, progName,
                                        exitString, interactive, minArgs,
                                        numInFiles, numOutFiles,
                                        numOptArg, numNonOptArg)
       character*N options
       character*N progName
       character*N exitString
       logical interactive
       integer*4 minArgs, numInFiles, numOutFiles
       integer*4 numOptArg, numNonOptArg    [Returned arguments]

       This Fortran subroutine performs a sequence of initialization tasks.
       It first attempts to read options for the program progName from an
       autodoc file using PipReadOptionFile then PipParseEntries.  If this
       fails, it falls back to calling PipParseInput to define numOptions
       options from the single string options, with the separator @ between
       options.  It allows comma defaults with PipAllowCommaDefaults, and
       calls both PipExitOnError and setExitPrefix with the prefix string
       in exitString.  If interactive is .true., the routine returns if
       there are no input arguments.  Otherwise, it checks for whether to
       print a usage output.  If the number of arguments is less than
       minArgs or -help is entered as an argument, then it calls
       PipPrintHelp with numInFiles and numOutFiles as arguments for the
       number of input and output files, then exits.  The option help must
       therefore be defined.

       void PipReadOrParseOptions(int argc, char *argv[],
                                  const char *options[], int numOptions,
                                  const char *progName, int minArgs,
                                  int numInFiles, int numOutFiles,
                                  int *numOptArgs, int *numNonOptArgs,
                                  void (headerFunc)(const char *));

       This C function performs a similar sequence of initialization tasks.
       It first attempts to read options for the program progName from an
       autodoc file using PipReadOptionFile then PipParseEntries.  If this
       fails, and if numOptions options are provided in an array of
       strings, options, it falls back to calling PipParseInput.  It calls
       PipExitOnError with "ERROR: progName - " as the error string,
       defining standard out as the destination for error output.  If the
       number of arguments is less than minArgs, it first calls the
       function supplied in headerFunc if it is non-NULL, then calls
       PipPrintHelp with numInFiles and numOutFiles as arguments for the
       number of input and output files, then exits.

       int PipInitialize(int numOpts);

       integer*4 function PipInitialize(int numOpts)
       integer*4 numOpts

       This function will initialize PIP and allocate memory for the number
       of options given in numOpts.


       int PipAddOption(const char *optionString);

       integer*4 function PipAddOption(optionString)
       character*N optionString

       This function is used to add one option at a time to PIP's table of
       options.


       int PipNextArg(const char *argString);

       integer*4 function PipNextArg(argString)
       character*N argString

       This function is used to send each argument in turn to PIP.  An
       option will be checked against the list of legal options; a value
       for an option will be associated with the option in PIP's table; and
       a non-option argument will be stored in PIP's list of those.  The
       function returns 1 if an argument is an option that requires a
       value.


       void PipNumberOfArgs(int *numOptArgs, int *numNonOptArgs);

       subroutine PipNumberOfArgs(numOptArgs, numNonOptArgs);
       integer*4 numOptArg, numNonOptArg      [Returned arguments]

       After arguments have been parsed, this function returns the number
       of option arguments in numOptArg and the number of non-option
       arguments in numNonOptArgs.


   Functions for Getting Values
       int PipNumberOfEntries(const char *option, int *numEntries);

       integer*4 function PipNumberOfEntries(option, numEntries);
       character*N option
       integer*4 numEntries     [Returned argument]

       This function returns the number of accumulated entries for the
       given option in the argument numEntries.  After calling this
       function, simply call a function to get the value of the option that
       number of times to retrieve all of the entered values.

       int PipLinkedIndex(const char *option, int *Iindex);

       integer*4 function PipLinkedIndex(option, index);
       character*N option
       integer*4 index     [Returned argument]

       This function returns into the argument index the index of the next
       entry of a linked option, for the next entry of the given option to
       be retrieved.  It returns the index of a specific linked option if
       one was identified with PipSetLinkedOption and if entries were made
       with that option; otherwise it returns the index of the next
       nonoption argument.

       int PipGetNonOptionArg(int argNo, char **arg);

       integer*4 function PipGetNonOptionArg(argNo, arg)
       integer*4 argNo
       character*N arg           [Returned argument]

       This function returns the non-option argument specified by argNo
       (numbered from 0 in C and Python, from 1 in Fortran) in as a string
       in the argument arg.  Note that non-option arguments can also be
       retrieved by calling PipGetString repeatedly with the option as
       NonOptionArgument or any abbreviation thereof.  When called from C
       and a string is returned, the string is allocated with malloc() and
       should be freed with free().

       int PipGetString(const char *option, char **string);

       integer*4 function PipGetString(option, string)
       character*N option
       character*N string        [Returned argument]

       This function returns the value of the given option as a string in
       the argument string.  The return value is 1 or 2 if the user did not
       enter this option (2 if a default value from autodoc was returned).
       When called from C and a string is returned, the string is allocated
       with malloc() and should be freed with free().


       int PipGetInteger(const char *option, int *val);

       integer*4 function PipGetInteger(option, val)
       character*N option
       integer*4 val             [Returned argument]

       int PipGetFloat(const char *option, float *val);

       integer*4 function PipGetFloat(option, val)
       character*N option
       real*4 val                [Returned argument]

       These functions returns a single integer or floating point value for
       the given option in the argument val.  The return value is 1 or 2 if
       the user did not enter this option (2 if a default value from
       autodoc was returned).


       int PipGetTwoIntegers(const char *option, int *val1, int *val2);

       integer*4 function PipGetInteger(option, val1, val2)
       character*N option
       integer*4 val1, val2             [Returned arguments]

       int PipGetTwoFloats(const char *option, float *val1, float *val2);

       integer*4 function PipGetTwoFloats(option, val1, val2)
       character*N option
       real*4 val1, val2             [Returned arguments]


       These functions returns two integers or two floats for the given
       option in the arguments val1 and val2.  The return value is 1 or 2
       if the user did not enter this option (2 if a default value from
       autodoc was returned).


       int PipGetThreeIntegers(const char *option, int *val1, int*val2,
                               int*val3,);

       integer*4 function PipGetInteger(option, val1, val2, val3)
       character*N option
       integer*4 val1, val2, val3             [Returned arguments]

       int PipGetThreeFloats(const char *option, float *val1, float*val2,
                             float*val3);

       integer*4 function PipGetThreeFloats(option, val1, val2, val3)
       character*N option
       real*4 val1, val2, val3             [Returned arguments]


       These functions returns three integers or three floats for the given
       option in the arguments val1, val2, and val2.  The return value is 1
       or 2 if the user did not enter this option (2 if a default value
       from autodoc was returned).


       int PipGetBoolean(const char *option, int *val);

       integer*4 function PipGetBoolean(option, val)
       character*N option
       integer*4 val             [Returned argument]

       This function returns a value of 0 or 1 for the given boolean option
       in the argument val.  The return value is 1 if the user did not
       enter this option.


       integer*4 function PipGetLogical(option, val)
       character*N option
       logical val             [Returned argument]

       This function returns a value of .true. or .false. for the given
       boolean option in the argument val.  The return value is 1 if the
       user did not enter this option.


       int PipGetIntegerArray(const char *option, int *array, int *numToGet,
                              int arraySize);

       integer*4 function PipGetIntegerArray(option, array, numToGet,
                                             arraySize)
       character*N option
       integer*4 array(N)        [Returned argument]
       integer*4 numToGet        [Returned argument if initially 0]
       integer*4 arraySize

       int PipGetFloatArray(const char *option, float *array, int *numToGet,
                            int arraySize);

       integer*4 function PipGetFloatArray(option, array, numToGet,
                                           arraySize)
       character*N option
       real*4 array(N)           [Returned argument]
       integer*4 numToGet        [Returned argument if initially 0]
       integer*4 arraySize

       These functions return an array of integers or floating point values
       for the given option.  The argument numToGet should be set to the
       number of values to be retrieved, or to 0 if a variable number of
       entries is allowed.  In the latter case, the functions will return
       the number of values in numToGet.  The size of array should be
       specified in arraySize.  The return value is 1 or 2 if the user did
       not enter the given option (2 if a default value from autodoc was
       returned).

       int PipGetInOutFile(const char *option, int nonOptArgNo,
                           char **filename)

       integer*4 function PipGetInOutFile(option, nonOptArgNo, prompt,
                                          filename)
       character*N option, prompt
       integer*4 nonOptArgNo
       character*N filename           [Returned argument]

       This function gets a filename specified by option; if that option
       was not entered, it gets the non-option argument in the nonOptArgNo
       position (numbered from 0 in C and Python, from 1 in Fortran).  If
       that argument does not exist either, it returns with an error.
       Alternatively for Fortran, if interactive input is being used, it
       prompts for the filename interactively with the string in prompt.
       If there is no interactive input, supply an empty string for prompt.

       To prevent the function from looking for a non-option argument, call
       it with nonOptArgNo bigger than the value of numNonOptArg.



   Functions for Help, Entry Printing, Cleanup, and Errors
       int PipSetManpageOutput(int type);

       subroutine PipSetManpageOutput(type)
       integer*4 type

       This function stores type in the static variable outputManpage to
       control the type of help output.  If the value is left at 0, a
       standard usage output is produced.  A value of 1 produces output for
       a man page to be interpreted by nroff (a .man file), while -1
       produces output for a preformatted man page (a .1 file).  A value of
       -2 produces the complete Fortran code for a fallback option string,
       while 2 or 3 produce output for C or Python code defining an array
       of option strings, all suitable for passing to
       PipReadOrParseOptions.

       int PipSetUsageString(const char *usage);

       integer*4 function PipSetUsageString(usage)
       character*N usage

       This function allows you set a custom usage string to replace the
       default output entirely.  PIP will print a newline after this string
       so it need not be included.  A multiline string can be supplied with
       embedded newlines.

       int PipPrintHelp(const char *progName, int useStdErr, int inputFiles,
                        int outputFiles);

       integer*4 function PipPrintHelp(progName, useStdErr, inputFiles,
                                       outputFiles)
       character*N progName
       integer*4 useStdErr, inputFiles, outputFiles

       This function produces a complete, formatted listing of options and
       their help strings, depending on the value of outputManpage as
       described just above.  The program name should be supplied in
       progName.  The listing is sent to standard output or standard error
       depending on whether useStdErr is 0 or 1.  The usage summary
       includes input_file or input_files... if inputFiles is 1 or 2,
       respectively; and output_file or output_files... if outputFiles is 1
       or 2 respectively.

       void PipEnableEntryOutput(int enable);

       subroutine PipEnableEntryOutput(enable)
       integer*4 enable

       This call controls whether PipPrintEntries will print the entries to
       the program.  If enable is 1, printing is enabled; if it is 0
       printing is disabled, and if it is -1 then printing is controlled by
       the value of the environment variable PIP_PRINT_ENTRIES.

       void PipPrintEntries(void);
       subroutine PipPrintEntries()

       This call causes the module to print a summary of all options
       entered to the program, if enabled either by a call to
       PipEnableEntryOutput or by the environment variable
       PIP_PRINT_ENTRIES.  The header line will include the program name if
       PipReadOptionFile was used for startup.

       void PipDone(void);
       subroutine PipDone()

       This call frees all allocated memory and reinitializes all variables
       so that another complete round of processing could occur.


       int PipGetError(char **errString);

       integer*4 function PipGetError(errString)
       character*N errString     [Returned argument]

       Use this function to get the error string generated by PIP from the
       last error.  When called from C and a string is returned, the string
       is allocated with malloc() and can be freed with free().


       int PipMemoryError(void *ptr, const char *routine);

       Tests ptr and returns 0 if it is non-NULL; otherwise it makes up an
       error string including the name given in routine and calls
       PipSetError, then returns -1.

       int PipSetError(const char *errString);

       Sets the error string and, if PIP has been set to exit on error,
       prints an error message and exits.

       void exitError(const char *format, ...);

       subroutine exitError(errString)
       character*N errString

       void setExitPrefix(const char *prefix);

       subroutine setExitPrefix(prefix)
       character*N prefix

       subroutine memoryError(ierr, errString)
       integer*4 ierr
       character*N errString

       exitError exits after printing an error string after a prefix, which
       is set by calling setExitPrefix.  The Fortran version takes the
       error string while the C version takes variable arguments like
       printf.  A space will be printed between the prefix and error
       string, and a newline printed after the error, so it is not
       necessary to include a newline in the string.  The prefix is also
       set automatically by calling PipReadOrParseOptions or
       PipExitOnError; in the latter case the destination for error output
       can be specified, whereas using setExitPrefix will cause output to
       go to standard out.  These two functions can be used by programs
       that do not call anything else in PIP; however, exitError will work
       only if the exit prefix has been set to a non-empty string with
       either setExitPrefix or PipExitOnError.  The Fortran routine
       memoryError tests whether ierr  is nonzero and, if so, calls
       exitError with errString appended to "FAILURE TO ALLOCATE ".


   Calling from Python
       The Python versions of the functions handle returned values
       differently: the values that would be returned in the function
       arguments in C or Fortran are returned in a single object as the
       return value of the function.  For functions with multiple values,
       this will be a tuple.  When an error occurs, this will be None.  The
       value corresponding to the return value from a C function is
       obtained by calling the function PipGetErrNo.  Functions that in C
       do not return any values except for the error code also set the
       error code for retrieval by PipGetErrNo and return 0 for success or
       None for an error.

       If you do not set PIP to exit on error, then you need to process
       return values in two steps, as in:
          retval = PipGetThreeIntegers('option', ix, iy, iz)
          if retval == None:
               process the error
          (ix, iy, iz) = retval

       This is not needed if PIP exits on error.  In that case, if you need
       to determine whether an option was entered, use:
          (ix, iy, iz) = PipGetThreeIntegers('option', ix, iy, iz)
          optionEntered = 1 - PipGetErrNo()

       Here are the conventions for all of available function calls:

       Functions for Initialization:

       status = PipExitOnError(useStdErr, prefix)

       PipSetLinkedOption(option)

       (numOptArgs, numNonOptArgs) = PipParseInput(sys.argv, options)

       PipReadOptionFile(progName)
       In the call to the C function, the helpLevel argument is set at 1
       and the localDir argument is set at 0.

       (numOptArgs, numNonOptArgs) = PipParseEntries(sys.argv)

       (numOptArgs, numNonOptArgs) = PipReadOrParseOptions(sys.argv, options,
                          progName, minArgs, numInFiles, numOutFiles)
       These are similar to the C functions described above.  options
       should be a list of strings as in the call to the C function.  If
       -help is defined as an option and the user adds this option, then
       PipReadOrParseOptions will print the usage and exit as in Fortran.

       status = PipInitialize(numOpts)

       (numOptArgs, numNonOptArgs) = PipNumberOfArgs()

       Functions for Getting Values:
       When an option is not entered, the function returns the supplied
       argument value(s), or a default value if one is defined in an
       autodoc.

       numEntries = PipNumberOfEntries(option)

       index = PipLinkedIndex(option)

       string = PipGetNonOptionArg(nonOptArgNo)

       string = PipGetString(option, string)

       iVal = PipGetInteger(option, iVal)

       fVal = PipGetFloat(option, fVal)

       (iVal1, iVal2) = PipGetTwoIntegers(option, iVal1, iVal2)

       (fVal1, fVal2) = PipGetTwoFloats(option, fVal1, fVal2)

       (iVal1, iVal2, iVal3) = PipGetThreeIntegers(option, iVal1, iVal2, iVal3)

       (fVal1, fVal2, fVal3) = PipGetThreeFloats(option, fVal1, fVal2, fVal3)

       iVal = PipGetBoolean(option,iVal)

       iArray = PipGetIntegerArray(option, numToGet)

       fArray = PipGetFloatArray(option, numToGet)
       These two functions return the arrays as lists of values.  As for
       the C functions, numToGet specifies the number to return, or 0 to
       return all available values.

       filename = PipGetInOutFile(option, nonOptArgNo)

       Functions for Help, Cleanup, and Errors:

       status = PipPrintHelp(progName, useStdErr, inputFiles, outputFiles)

       PipEnableEntryOutput(enable)

       PipPrintEntries()

       PipDone()

       errStr = PipGetError()

       errNo = PipGetErrNo()

       status = PipSetError(errString)

       exitError(string)

       setExitPrefix(prefix)


AUTHOR
       David Mastronarde (mast at colorado dot edu)



IMOD                              4.10.10                            PIP(1)