PIP(1)                                                                  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.


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

       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 if the user did not enter this
       option.  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 if the
       user did not enter this option.


       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 if the user did
       not enter this option.


       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 if
       the user did not enter this option.


       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 if the user did not enter the given
       option.

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

       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)



BL3DEMC                              4.7.3                              PIP(1)