Index: /trunk/doc/pslib/ChangeLogSDRS.tex =================================================================== --- /trunk/doc/pslib/ChangeLogSDRS.tex (revision 4710) +++ /trunk/doc/pslib/ChangeLogSDRS.tex (revision 4711) @@ -1,3 +1,3 @@ -%%% $Id: ChangeLogSDRS.tex,v 1.161 2005-07-22 22:39:21 price Exp $ +%%% $Id: ChangeLogSDRS.tex,v 1.162 2005-08-05 03:51:16 price Exp $ \subsection{Changes from version 00 to version 01} @@ -760,4 +760,11 @@ \item \code{psPixelCoord} now contains floats. \item \code{psImageSlice} uses \code{psPixels} to output coordinates. -\end{itemize} - +\item Added \code{psTimer} functions (prototypes by EAM). +\item \code{psLibInit} and \code{psLibCleanup} changed to + \code{psTimeInitialize} and \code{psTimeFinalize}. Calls to + functions that require the time tables before calling + \code{psTimeInitialize} shall produce an error. +\item Added \code{psArgument} functions to provide simple argument + handling. +\end{itemize} + Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 4710) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 4711) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.321 2005-07-22 22:36:33 price Exp $ +%%% $Id: psLibSDRS.tex,v 1.322 2005-08-05 03:51:16 price Exp $ \documentclass[panstarrs,spec]{panstarrs} @@ -271,30 +271,6 @@ \subsection{Initialization} -PSLib may be initialized by calling \code{psLibInit} by the user -before use. This enables the library to perform the following tasks -that are required before general use: -\begin{itemize} -\item Set the error codes for PSLib. -\item Read the \code{psTime} configuration file (\code{timeConfig}) - and set up the appropriate \code{psTimeTable}s and predictions. -\end{itemize} - -The prototype is: -\begin{prototype} -void psLibInit(const char *timeConfig); -\end{prototype} - -\code{timeConfig} specifies the filename of the configuration file -for \code{psTime} metadata. - -\subsection{Finalization} - -\begin{prototype} -void psLibCleanup(void); -\end{prototype} - -\code{psLibCleanup} shall free memory that was allocated by -\code{psLibInit}, allowing a subsequent search for leaked memory (even -memory marked as \code{persistent}). +Before certain \code{psTime} functions can be employed, the user must +call \code{psTimeInitialize}. \subsection{Memory Management} @@ -1628,5 +1604,5 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Abort} @@ -1639,5 +1615,49 @@ \end{prototype} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subsection{Command-line arguments} + +The following functions are provided to aid parsing of command-line +arguments: + +\begin{prototype} +int psArgumentGet(int argc, char **argv, const char *arg); +bool psArgumentRemove(int argnum, int *argc, char **argv); +\end{prototype} + +\code{psArgumentGet} shall return the index of the element in the +argument list, \code{argv} with number of entries \code{argc}, that +matches the specified argument, \code{arg}, or zero if there is no +match. + +\code{psArgumentRemove} shall remove from the argument list +(\code{argv} with number of entries \code{argc}) the argument whose +index is \code{argnum}. The number of entries in the argument list +shall be decremented. The function shall return \code{true} if the +\code{argnum} is in the argument list, and \code{false} otherwise. + +\begin{prototype} +int psArgumentVerbosity(int *argc, char **argv); +\end{prototype} + +\code{psArgumentVebosity} shall implement the various verbosity +controls under the following guidelines: +\begin{itemize} +\item \code{-v} switch shall set the log level to 3. +\item \code{-vv} switch shall set the log level to 4. +\item \code{-vvv} switch shall set the log level to 5. +\item \code{-logfmt someFormat} switch shall set the log format to + \code{someFormat}. +\item \code{-trace facility level} switch shall set the trace level + for the specified \code{facility} to the specified \code{level}. +\item \code{-trace-levels} switch shall print the trace levels as + currently set. +\end{itemize} + +The above arguments shall be removed from the argument list as they +are processed. The function shall return the resultant logging level. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \pagebreak @@ -5730,4 +5750,29 @@ track the time system being represented. +\subsubsection{Initialization and Finalization} + +The conversions between various time standards, and the polar motion +requires importing external data (``time tables''), the locations of +which are specified in a configuration file. + +\begin{prototype} +void psTimeInitialize(const char *timeConfig); +\end{prototype} + +\code{psTimeInitialize} shall read the \code{psTime} configuration +file (\code{timeConfig}) and set up the appropriate +\code{psTimeTable}s and predictions. + +{\bf Calls to \code{psTime} functions that require the time tables +before calling \code{psTimeInitialize} shall result in an error.} + +\begin{prototype} +void psTimeFinalize(void); +\end{prototype} + +\code{psTimeFinalize} shall free memory that was allocated by +\code{psTime} functions, allowing a subsequent search for leaked +memory (even memory marked as \code{persistent}). + \subsubsection{Data Types} @@ -5952,4 +5997,7 @@ and ``to'' dates of applicability will be specified through metadata (\S\ref{sec:timeMetadata}). + +{\bf Calls to \code{psTime} functions that require the time tables +before calling \code{psTimeInitialize} shall result in an error.} When a value is required, the tables shall shall be checked in @@ -6017,4 +6065,23 @@ A series of test inputs is contained in \S\ref{sec:timetest}. +\subsection{Timers} + +It is useful to be able to time an operation. For this purpose, we specify +the following: + +\begin{prototype} +bool psTimerStart(char *name); +psF64 psTimerMark(char *name); +psF64 psTimerStop(void); +\end{prototype} + +\code{psTimerStart} shall store the current time in a \code{psHash} of +timers, under the supplied \code{name}. \code{psTimerMark} shall +return the elapsed time, in seconds, for the timer specified by +\code{name}. \code{psTimerStop} shall free all memory associated with +the timers, so that no memory is leaked, and return the maximum time +expended. + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%