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 1 or 2 runs a program with no arguments as if
-StandardInput were entered; 1 works from Fortran and 2 is needed
from C.
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 or -1 if a variable number
of entries is allowed. A value of 0 will result in an error if
there are more values on the line than fit in the array; a value
less than 0 will just get as many values as fit in the array and
ignore extra ones. In either 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.11.0 PIP(1)