sun268.tex

\documentstyle[11pt]{article}
\pagestyle{myheadings}

% -----------------------------------------------------------------------------
% ? Document identification
%------------------------------------------------------------------------------
\newcommand{\stardoccategory}  {Starlink User Note}
\newcommand{\stardocinitials}  {SUN}
\newcommand{\stardocsource}    {sun268.0}
\newcommand{\stardocnumber}    {268.0}
\newcommand{\stardocauthors}   {D.S. Berry \& M.J. Currie}
\newcommand{\stardocdate}      {14th November 2013}
\newcommand{\stardoctitle}     {CVG \\ [\latex{1ex}]
                                A Library of Format Conversion Utilities}
\newcommand{\stardocversion}   {Version 1.0}
\newcommand{\stardocmanual}    {Programmer's Manual}
% ? End of document identification
% -----------------------------------------------------------------------------

\newcommand{\stardocname}{\stardocinitials /\stardocnumber}
\markright{\stardocname}
\setlength{\textwidth}{160mm}
\setlength{\textheight}{230mm}
\setlength{\topmargin}{-2mm}
\setlength{\oddsidemargin}{0mm}
\setlength{\evensidemargin}{0mm}
\setlength{\parindent}{0mm}
\setlength{\parskip}{\medskipamount}
\setlength{\unitlength}{1mm}

% -----------------------------------------------------------------------------
%  Hypertext definitions.
%  ======================
%  These are used by the LaTeX2HTML translator in conjunction with star2html.

%  Comment.sty: version 2.0, 19 June 1992
%  Selectively in/exclude pieces of text.
%
%  Author
%    Victor Eijkhout                                      <eijkhout@cs.utk.edu>
%    Department of Computer Science
%    University Tennessee at Knoxville
%    104 Ayres Hall
%    Knoxville, TN 37996
%    USA

%  Do not remove the %begin{latexonly} and %end{latexonly} lines (used by
%  star2html to signify raw TeX that latex2html cannot process).
%begin{latexonly}
\makeatletter
\def\makeinnocent#1{\catcode`#1=12 }
\def\csarg#1#2{\expandafter#1\csname#2\endcsname}

\def\ThrowAwayComment#1{\begingroup
    \def\CurrentComment{#1}%
    \let\do\makeinnocent \dospecials
    \makeinnocent\^^L% and whatever other special cases
    \endlinechar`\^^M \catcode`\^^M=12 \xComment}
{\catcode`\^^M=12 \endlinechar=-1 %
 \gdef\xComment#1^^M{\def\test{#1}
      \csarg\ifx{PlainEnd\CurrentComment Test}\test
          \let\html@next\endgroup
      \else \csarg\ifx{LaLaEnd\CurrentComment Test}\test
            \edef\html@next{\endgroup\noexpand\end{\CurrentComment}}
      \else \let\html@next\xComment
      \fi \fi \html@next}
}
\makeatother

\def\includecomment
 #1{\expandafter\def\csname#1\endcsname{}%
    \expandafter\def\csname end#1\endcsname{}}
\def\excludecomment
 #1{\expandafter\def\csname#1\endcsname{\ThrowAwayComment{#1}}%
    {\escapechar=-1\relax
     \csarg\xdef{PlainEnd#1Test}{\string\\end#1}%
     \csarg\xdef{LaLaEnd#1Test}{\string\\end\string\{#1\string\}}%
    }}

%  Define environments that ignore their contents.
\excludecomment{comment}
\excludecomment{rawhtml}
\excludecomment{htmlonly}

%  Hypertext commands etc. This is a condensed version of the html.sty
%  file supplied with LaTeX2HTML by: Nikos Drakos <nikos@cbl.leeds.ac.uk> &
%  Jelle van Zeijl <jvzeijl@isou17.estec.esa.nl>. The LaTeX2HTML documentation
%  should be consulted about all commands (and the environments defined above)
%  except \xref and \xlabel which are Starlink specific.

\newcommand{\htmladdnormallinkfoot}[2]{#1\footnote{#2}}
\newcommand{\htmladdnormallink}[2]{#1}
\newcommand{\htmladdimg}[1]{}
\newenvironment{latexonly}{}{}
\newcommand{\hyperref}[4]{#2\ref{#4}#3}
\newcommand{\htmlref}[2]{#1}
\newcommand{\htmlimage}[1]{}
\newcommand{\htmladdtonavigation}[1]{}
\newcommand{\latexhtml}[2]{#1}
\newcommand{\html}[1]{}

%  Starlink cross-references and labels.
\newcommand{\xref}[3]{#1}
\newcommand{\xlabel}[1]{}

%  LaTeX2HTML symbol.
\newcommand{\latextohtml}{{\bf LaTeX}{2}{\tt{HTML}}}

%  Define command to re-centre underscore for Latex and leave as normal
%  for HTML (severe problems with \_ in tabbing environments and \_\_
%  generally otherwise).
\newcommand{\latex}[1]{#1}
\newcommand{\setunderscore}{\renewcommand{\_}{{\tt\symbol{95}}}}
\latex{\setunderscore}

%  Redefine the \tableofcontents command. This procrastination is necessary
%  to stop the automatic creation of a second table of contents page
%  by latex2html.
\newcommand{\latexonlytoc}[0]{\tableofcontents}

% -----------------------------------------------------------------------------
%  Debugging.
%  =========
%  Remove % on the following to debug links in the HTML version using Latex.

% \newcommand{\hotlink}[2]{\fbox{\begin{tabular}[t]{@{}c@{}}#1\\\hline{\footnotesize #2}\end{tabular}}}
% \renewcommand{\htmladdnormallinkfoot}[2]{\hotlink{#1}{#2}}
% \renewcommand{\htmladdnormallink}[2]{\hotlink{#1}{#2}}
% \renewcommand{\hyperref}[4]{\hotlink{#1}{\S\ref{#4}}}
% \renewcommand{\htmlref}[2]{\hotlink{#1}{\S\ref{#2}}}
% \renewcommand{\xref}[3]{\hotlink{#1}{#2 -- #3}}
%end{latexonly}
% -----------------------------------------------------------------------------
% ? Document specific \newcommand or \newenvironment commands.

%+
%  Name:
%     SST.TEX

%  Purpose:
%     Define LaTeX commands for laying out Starlink routine descriptions.

%  Language:
%     LaTeX

%  Type of Module:
%     LaTeX data file.

%  Description:
%     This file defines LaTeX commands which allow routine documentation
%     produced by the SST application PROLAT to be processed by LaTeX and
%     by LaTeX2html. The contents of this file should be included in the
%     source prior to any statements that make of the sst commnds.

%  Notes:
%     The style file html.sty provided with LaTeX2html needs to be used.
%     This must be before this file.

%  Authors:
%     RFWS: R.F. Warren-Smith (STARLINK)
%     PDRAPER: P.W. Draper (Starlink - Durham University)

%  History:
%     10-SEP-1990 (RFWS):
%        Original version.
%     10-SEP-1990 (RFWS):
%        Added the implementation status section.
%     12-SEP-1990 (RFWS):
%        Added support for the usage section and adjusted various spacings.
%     8-DEC-1994 (PDRAPER):
%        Added support for simplified formatting using LaTeX2html.
%     {enter_further_changes_here}

%  Bugs:
%     {note_any_bugs_here}

%-

%  Define length variables.
\newlength{\sstbannerlength}
\newlength{\sstcaptionlength}
\newlength{\sstexampleslength}
\newlength{\sstexampleswidth}

%  Define a \tt font of the required size.
\latex{\newfont{\ssttt}{cmtt10 scaled 1095}}
\html{\newcommand{\ssttt}{\tt}}

%  Define a command to produce a routine header, including its name,
%  a purpose description and the rest of the routine's documentation.
\newcommand{\sstroutine}[3]{
   \goodbreak
   \rule{\textwidth}{0.5mm}
   \vspace{-7ex}
   \newline
   \settowidth{\sstbannerlength}{{\Large {\bf #1}}}
   \setlength{\sstcaptionlength}{\textwidth}
   \setlength{\sstexampleslength}{\textwidth}
   \addtolength{\sstbannerlength}{0.5em}
   \addtolength{\sstcaptionlength}{-2.0\sstbannerlength}
   \addtolength{\sstcaptionlength}{-5.0pt}
   \settowidth{\sstexampleswidth}{{\bf Examples:}}
   \addtolength{\sstexampleslength}{-\sstexampleswidth}
   \parbox[t]{\sstbannerlength}{\flushleft{\Large {\bf #1}}}
   \parbox[t]{\sstcaptionlength}{\center{\Large #2}}
   \parbox[t]{\sstbannerlength}{\flushright{\Large {\bf #1}}}
   \begin{description}
      #3
   \end{description}
}

%  Format the description section.
\newcommand{\sstdescription}[1]{\item[Description:] #1}

%  Format the usage section.
\newcommand{\sstusage}[1]{\item[Usage:] \mbox{}
\\[1.3ex]{\raggedright \ssttt #1}}

%  Format the invocation section.
\newcommand{\sstinvocation}[1]{\item[Invocation:]\hspace{0.4em}{\tt #1}}

%  Format the arguments section.
\newcommand{\sstarguments}[1]{
   \item[Arguments:] \mbox{} \\
   \vspace{-3.5ex}
   \begin{description}
      #1
   \end{description}
}

%  Format the returned value section (for a function).
\newcommand{\sstreturnedvalue}[1]{
   \item[Returned Value:] \mbox{} \\
   \vspace{-3.5ex}
   \begin{description}
      #1
   \end{description}
}

%  Format the parameters section (for an application).
\newcommand{\sstparameters}[1]{
   \item[Parameters:] \mbox{} \\
   \vspace{-3.5ex}
   \begin{description}
      #1
   \end{description}
}

%  Format the examples section.
\newcommand{\sstexamples}[1]{
   \item[Examples:] \mbox{} \\
   \vspace{-3.5ex}
   \begin{description}
      #1
   \end{description}
}

%  Define the format of a subsection in a normal section.
\newcommand{\sstsubsection}[1]{ \item[{#1}] \mbox{} \\}

%  Define the format of a subsection in the examples section.
\newcommand{\sstexamplesubsection}[2]{\sloppy
\item[\parbox{\sstexampleslength}{\ssttt #1}] \mbox{} \vspace{1.0ex}
\\ #2 }

%  Format the notes section.
\newcommand{\sstnotes}[1]{\item[Notes:] \mbox{} \\[1.3ex] #1}

%  Provide a general-purpose format for additional (DIY) sections.
\newcommand{\sstdiytopic}[2]{\item[{\hspace{-0.35em}#1\hspace{-0.35em}:}]
\mbox{} \\[1.3ex] #2}

%  Format the implementation status section.
\newcommand{\sstimplementationstatus}[1]{
   \item[{Implementation Status:}] \mbox{} \\[1.3ex] #1}

%  Format the bugs section.
\newcommand{\sstbugs}[1]{\item[Bugs:] #1}

%  Format a list of items while in paragraph mode.
\newcommand{\sstitemlist}[1]{
  \mbox{} \\
  \vspace{-3.5ex}
  \begin{itemize}
     #1
  \end{itemize}
}

%  Define the format of an item.
\newcommand{\sstitem}{\item}

%% Now define html equivalents of those already set. These are used by
%  latex2html and are defined in the html.sty files.
\begin{htmlonly}

%  sstroutine.
   \newcommand{\sstroutine}[3]{
      \subsection{#1\xlabel{#1}-\label{#1}#2}
      \begin{description}
         #3
      \end{description}
   }

%  sstdescription
   \newcommand{\sstdescription}[1]{\item[Description:]
      \begin{description}
         #1
      \end{description}
      \\
   }

%  sstusage
   \newcommand{\sstusage}[1]{\item[Usage:]
      \begin{description}
         {\ssttt #1}
      \end{description}
      \\
   }

%  sstinvocation
   \newcommand{\sstinvocation}[1]{\item[Invocation:]
      \begin{description}
         {\ssttt #1}
      \end{description}
      \\
   }

%  sstarguments
   \newcommand{\sstarguments}[1]{
      \item[Arguments:] \\
      \begin{description}
         #1
      \end{description}
      \\
   }

%  sstreturnedvalue
   \newcommand{\sstreturnedvalue}[1]{
      \item[Returned Value:] \\
      \begin{description}
         #1
      \end{description}
      \\
   }

%  sstparameters
   \newcommand{\sstparameters}[1]{
      \item[Parameters:] \\
      \begin{description}
         #1
      \end{description}
      \\
   }

%  sstexamples
   \newcommand{\sstexamples}[1]{
      \item[Examples:] \\
      \begin{description}
         #1
      \end{description}
      \\
   }

%  sstsubsection
   \newcommand{\sstsubsection}[1]{\item[{#1}]}

%  sstexamplesubsection
   \newcommand{\sstexamplesubsection}[2]{\item[{\ssttt #1}] #2}

%  sstnotes
   \newcommand{\sstnotes}[1]{\item[Notes:] #1 }

%  sstdiytopic
   \newcommand{\sstdiytopic}[2]{\item[{#1}] #2 }

%  sstimplementationstatus
   \newcommand{\sstimplementationstatus}[1]{
      \item[Implementation Status:] #1
   }

%  sstitemlist
   \newcommand{\sstitemlist}[1]{
      \begin{itemize}
         #1
      \end{itemize}
      \\
   }
%  sstitem
   \newcommand{\sstitem}{\item}

\end{htmlonly}

%  End of "sst.tex" layout definitions.
%.



% ? End of document specific commands
% -----------------------------------------------------------------------------
%  Title Page.
%  ===========
\renewcommand{\thepage}{\roman{page}}
\begin{document}
\thispagestyle{empty}

%  Latex document header.
%  ======================
\begin{latexonly}
   STFC / {\sc Joint Astronomy Centre, Hawaii} \hfill {\bf \stardocname}\\
   {\large Science \& Technology Facilities Council}\\
   {\large Starlink Project\\}
   {\large \stardoccategory\ \stardocnumber}
   \begin{flushright}
   \stardocauthors\\
   \stardocdate
   \end{flushright}
   \vspace{-4mm}
   \rule{\textwidth}{0.5mm}
   \vspace{5mm}
   \begin{center}
   {\Huge\bf  \stardoctitle \\ [2.5ex]}
   {\LARGE\bf \stardocversion \\ [4ex]}
   {\Huge\bf  \stardocmanual}
   \end{center}
   \vspace{5mm}

% ? Heading for abstract if used.
   \vspace{10mm}
   \begin{center}
      {\Large\bf Abstract}
   \end{center}
% ? End of heading for abstract.
\end{latexonly}

%  HTML documentation header.
%  ==========================
\begin{htmlonly}
   \xlabel{}
   \begin{rawhtml} <H1> \end{rawhtml}
      \stardoctitle\\
      \stardocversion\\
      \stardocmanual
   \begin{rawhtml} </H1> \end{rawhtml}

% ? Add picture here if required.
% ? End of picture

   \begin{rawhtml} <P> <I> \end{rawhtml}
   \stardoccategory\ \stardocnumber \\
   \stardocauthors \\
   \stardocdate
   \begin{rawhtml} </I> </P> <H3> \end{rawhtml}
      \htmladdnormallink{CCLRC}{http://www.cclrc.ac.uk} /
      \htmladdnormallink{Rutherford Appleton Laboratory}
                        {http://www.cclrc.ac.uk/ral} \\
      \htmladdnormallink{Particle Physics \& Astronomy Research Council}
                        {http://www.pparc.ac.uk} \\
   \begin{rawhtml} </H3> <H2> \end{rawhtml}
      \htmladdnormallink{Starlink Project}{http://www.starlink.ac.uk/}
   \begin{rawhtml} </H2> \end{rawhtml}
   \htmladdnormallink{\htmladdimg{source.gif} Retrieve hardcopy}
      {http://www.starlink.ac.uk/cgi-bin/hcserver?\stardocsource}\\

%  HTML document table of contents.
%  ================================
%  Add table of contents header and a navigation button to return to this
%  point in the document (this should always go before the abstract \section).
  \label{stardoccontents}
  \begin{rawhtml}
    <HR>
    <H2>Contents</H2>
  \end{rawhtml}
  \renewcommand{\latexonlytoc}[0]{}
  \htmladdtonavigation{\htmlref{\htmladdimg{contents_motif.gif}}
        {stardoccontents}}

% ? New section for abstract if used.
  \section{\xlabel{abstract}Abstract}


% ? End of new section for abstract
\end{htmlonly}

% -----------------------------------------------------------------------------
% ? Document Abstract. (if used)
%   ==================

CVG provides utility functions for handling data format conversion tasks.

% ? End of document
% -----------------------------------------------------------------------------
% ? Latex document Table of Contents (if used).
%  ===========================================
 \newpage
 \begin{latexonly}
   \setlength{\parskip}{0mm}
   \latexonlytoc
   \setlength{\parskip}{\medskipamount}
   \markright{\stardocname}
 \end{latexonly}
% ? End of Latex document table of contents
% -----------------------------------------------------------------------------
\newpage
\renewcommand{\thepage}{\arabic{page}}
\setcounter{page}{1}

\section {Introduction}

This library contains routines that originally formed part of the CONVERT
application package, but which are are of more general use and so have
been moved into a separate library.

\appendix
\section{\label{APP:SPEC}Routine Descriptions}

% Routine descriptions:
% =====================
\small
\sstroutine{
   CVG\_ASSOC
}{
   Opens an existing FITS file specified by an environment parameter
}{
   \sstdescription{
      This function opens an existing FITS file with a path obtained from
      the environment, and returns a logical unit number that can be used
      to access it using CVG and FITSIO functions.
   }
   \sstinvocation{
      CALL CVG\_ASSOC( PARAM, MODE, FUNIT, BLOCKF, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         PARAM = CHARACTER $*$ ( $*$ ) (Given)
      }{
         The name of the environemt parameter to use.
      }
      \sstsubsection{
         MODE = CHARACTER $*$ ( $*$ ) (Given)
      }{
         The access mode: {\tt '}READ{\tt '} or {\tt '}UPDATE. Case insensitive.
         Abbreviations can be used.
      }
      \sstsubsection{
         FUNIT = INTEGER (Returned)
      }{
         The logical unit number of the FITS file. Returned equal to
         CVG\_NOLUN if an error occurs.
      }
      \sstsubsection{
         BLOCKF = INTEGER (Returned)
      }{
         The logical record blocking factor.
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
   }
}
\sstroutine{
   CVG\_BT2FT
}{
   Creates an AST FitsTable from a FITS binary table
}{
   \sstdescription{
      This function creates a new AST FitsTable object holding the data
      read from a FITS binary table held in a named extension of the
      supplied FITS file.
   }
   \sstinvocation{
      CALL CVG\_BT2FT( FUNIT, EXTNAM, EXTVER, EXTLEVEL, TABLE, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         FUNIT = INTEGER (Given)
      }{
         The FITSIO unit number for the FITS file.
      }
      \sstsubsection{
         EXTNAM = CHARACTER $*$ ( $*$ ) (Given)
      }{
         The name of the FITS extension containing the required binary
         table.
      }
      \sstsubsection{
         EXTVER = INTEGER (Given)
      }{
         The value of the EXTVER keyword in the required binary-table
         HDU.
      }
      \sstsubsection{
         EXTLEVEL = INTEGER (Given)
      }{
         The value of the EXTLEVEL keyword in the required binary-table
         HDU.
      }
      \sstsubsection{
         TABLE = INTEGER (Returned)
      }{
         A pointer to the new FitsTable. A value of AST\_\_NULL is
         returned (without error) if the named extension cannot be
         found.
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
   }
}
\sstroutine{
   CVG\_CLEAN
}{
   Removes standard header cards from a FitsCHan
}{
   \sstdescription{
      This removes the following cards, if present, from the supplied
      FitsChan: SIMPLE, BITPIX, EXTEND, NAXIS, NAXISj, all WCS related
      cards.
   }
   \sstinvocation{
      CALL CVG\_CLEAN( IPROV, FC, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         FC = INTEGER (Given)
      }{
         The FitsChan to clean.
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
   }
}
\sstroutine{
   CVG\_CLOSE
}{
   Closes a FITS file
}{
   \sstdescription{
      This function closes the FITS files specified by the supplied
      logical unit number. It returns without error if the supplied
      logical unit number is currently not attached to a file.
   }
   \sstinvocation{
      CALL CVG\_CLOSE( FUNIT, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         FUNIT = INTEGER (Given and Returned)
      }{
         The logical unit number of the FITS file. Always returned equal
         to CVG\_\_NOLUN.
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function attempts to run even if an error has already
         occurred.
      }
   }
}
\sstroutine{
   CVG\_CREAT
}{
   Create a new FITS file specified by an environment parameter
}{
   \sstdescription{
      This function creates a new FITS file with a path obtained from the
      environment, and returns a logical unit number that can be used to
      access it using CVG and FITSIO functions.
   }
   \sstinvocation{
      CALL CVG\_CREAT( PARAM, BLOCKF, OVRWRT, FUNIT, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         PARAM = CHARACTER $*$ ( $*$ ) (Given)
      }{
         The name of the environemt parameter to use.
      }
      \sstsubsection{
         BLOCKF = INTEGER (Given)
      }{
         The blocking factor for the new file. It must be a positive
         integer between 1 and 10.
      }
      \sstsubsection{
         OVRWRT = LOGICAL (Returned)
      }{
         If .TRUE., any existing file with the given name is silently
         over-written. Otherwise, an error is reported if the file
         already exists.
      }
      \sstsubsection{
         FUNIT = INTEGER (Returned)
      }{
         The logical unit number of the FITS file. Returned equal to
         CVG\_NOLUN if an error occurs.
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
   }
}
\sstroutine{
   CVG\_FC2HD
}{
   Copies all headers from a FitsChan to the current HDU
}{
   \sstdescription{
      This routine extracts all headers from the supplied FitsChan and
      stores them in the current HDU of the supplied FITS file. The HDU
      header may be emptied first (see argument CLEAR).
   }
   \sstinvocation{
      CALL CVG\_FC2HD( FC, CLEAR, FUNIT, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         FC = INTEGER (Given)
      }{
         Pointer to the FitsChan.
      }
      \sstsubsection{
         CLEAR = LOGICAL (Given)
      }{
         Should he header be cleared before copying in the new cards?
         Otherwise, the new cards are appended to the end of the HDU.
      }
      \sstsubsection{
         FUNIT = INTEGER (Given)
      }{
         The FITSIO unit number for the FITS file.
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
   }
   \sstdiytopic{
      Prior Requirements
   }{
      The FITS file must already be opened with the FITSIO library.
   }
}
\sstroutine{
   CVG\_FIOER
}{
   Reports error messages associated with a call to a FITSIO routine
}{
   \sstdescription{
      This routine writes a standard error report for an error arising
      within a FITSIO-library routine.  The report comprises two parts.
      First there is a contextual error report.  The error number is
      translated to an error string and appended to the supplied
      message.  Thus the contextual message is of the form:
         $<$ROUTIN$>$: $<$MESSGE$>$  Error was:
      or
         $<$MESSGE$>$  Error was:
      when ROUTIN is a blank string.  After this header message, the
      FITSIO error stack is flushed.  If for some strange reason, there
      are no error messages in the stack, this routine appends the
      short translation of the error number, and if there is no
      translation, it reports the FITSIO error number and instruct the
      reader to consult the FITSIO User{\tt '}s Guide.

      The global status is set to SAI\_\_ERROR.  This routine attempts
      to work even if the global status is bad on entry.
   }
   \sstinvocation{
      CALL CVG\_FIOER( FSTAT, PARAM, ROUTIN, MESSGE, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         FSTAT = INTEGER (Given)
      }{
         The FITSIO status.
      }
      \sstsubsection{
         PARAM = CHARACTER $*$ ( $*$ ) (Given)
      }{
         The parameter name of the error report.  It usually comprises
         the name of the routine where the FITSIO routine is called
         followed by some suitable suffix like {\tt '}\_ERR{\tt '}.
      }
      \sstsubsection{
         ROUTIN = CHARACTER $*$ ( $*$ ) (Given)
      }{
         The name of the FITSIO routine where the error occurred.
         It may be blank to prevent it appearing in the error report.
      }
      \sstsubsection{
         MESSGE = CHARACTER $*$ ( $*$ ) (Given)
      }{
         A contextual error message to form part of the error report.
         It should indicate what was happening when the call to the
         FITSIO routine was made.  No punctuation is added between
         this and the {\tt "}Error was{\tt "} text, so a full stop should appear
         in this message.
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
   }
   \sstnotes{
      The error name for the FITSIO error messages is FITSIO\_ERR.

      [optional\_subroutine\_items]...
   }
}
\sstroutine{
   CVG\_FT2BT
}{
   Creates a FITS binary table from a AST FitsTable
}{
   \sstdescription{
      This function creates a new FITS binary table holding data copied
      from an AST FitsTable. If a binary table extension with the given
      extension name already exists in the FITS file, it is replaced by
      the new one. Otherwise, the table is written into the current HDU.
      The current HDU on exit can be selected using MKCHDU.
   }
   \sstinvocation{
      CALL CVG\_FT2BT( TABLE, FUNIT, EXTNAM, ASTVER, MKCHDU, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         TABLE = INTEGER (Given)
      }{
         A pointer to the FitsTable.
      }
      \sstsubsection{
         FUNIT = INTEGER (Given)
      }{
         The FITSIO unit number for the FITS file.
      }
      \sstsubsection{
         EXTNAM = CHARACTER $*$ ( $*$ ) (Given)
      }{
         The name of the new FITS extension containing the binary table.
      }
      \sstsubsection{
         ASTVER = INTEGER (Given)
      }{
         This parameter determines what to do if the FITS file already
         contains an extension with the name given by EXTNAM. Normally,
         an error is reported, but if the extension was created by AST
         (i.e. if EXTNAM is equal to the symbolic constant AST\_\_TABEXTNAME),
         and the table version for the existing table is equal to the
         value of ASTVER, then no error is reported and this function
         returns without action.
      }
      \sstsubsection{
         MKCHDU = LOGICAL (Given)
      }{
         If .TRUE., the new binary table extension is made the current
         HDU on exit. Otherwise, the original current HDU is unchanged on
         exit.
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
   }
}
\sstroutine{
   CVG\_HD2FC
}{
   Copies all headers from the current HDU into a FitsChan
}{
   \sstdescription{
      This routine extracts all headers from the current HDU and stores
      them in the supplied FitsChan. The FitsChan is first emptied.
   }
   \sstinvocation{
      CALL CVG\_HD2FC( FUNIT, FC, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         FUNIT = INTEGER (Given)
      }{
         The FITSIO unit number for the FITS file.
      }
      \sstsubsection{
         FC = INTEGER (Given)
      }{
         Pointer to the FitsChan.
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
   }
   \sstdiytopic{
      Prior Requirements
   }{
      The FITS file must already be opened with the FITSIO library.
   }
}
\sstroutine{
   CVG\_HDATE
}{
   Converts the NDF history date into a more-pleasing format
}{
   \sstdescription{
      This makes a few minor modifications to the date string obtained
      from NDF history records to make it more like UNIX and
      astronomical style.  Specifically two hyphens around the month are
      replaced by spaces, and the second and third letters of the month
      are made lowercase.
   }
   \sstinvocation{
      CALL CVG\_HDATE( DATE, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         DATE = CHARACTER $*$ ( $*$ ) (Given and Returned)
      }{
         On input the NDF format for a date and time, namely
         YYYY-MMM-DD HH:MM:SS.SSS.  On exit, the ISO-order format for a
         date and time, namely YYYY Mmm DD HH:MM:SS.SSS
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
   }
}
\sstroutine{
   CVG\_HECHO
}{
   Writes history text to the FITS headers
}{
   \sstdescription{
      This routine appends the history text associated with an
      NDF to the current FITS header.  It is not called directly (by
      CVG\_WHISR), but is passed as an external argument to routine
      NDF\_HOUT.  (It is an equivalent to NDF\_HECHO.  See SUN/33 for
      more details.)
   }
   \sstinvocation{
      CALL CVG\_HECHO( NLINES, TEXT, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         NLINES = INTEGER (Given)
      }{
         Number of lines of history text.
      }
      \sstsubsection{
         TEXT( NLINES ) = CHARACTER $*$ ( $*$ ) (Given)
      }{
         The history text.
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The argument list should not be changed.

         \sstitem
         There is no error checking of the FITSIO status.
      }
   }
   \sstdiytopic{
      Prior Requirements
   }{
      The NDF and the FITS file must already be open.  The current
      HDU in the FITS file should be the primary and the other headers
      should have been written.
   }
}
\sstroutine{
   CVG\_NEW
}{
   Creates a new FITS file and return a unit number for it
}{
   \sstdescription{
      This function creates a new FITS file with a given path, and
      returns a logical unit number that can be used to access it
      using CVG and FITSIO functions.
   }
   \sstinvocation{
      CALL CVG\_NEW( PATH, BLOCKF, OVRWRT, FUNIT, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         PATH = CHARACTER $*$ ( $*$ ) (Given)
      }{
         The path to the file to be created. A file type of {\tt "}.fit{\tt "} will be
         added if there is no file type in the supplied string.
      }
      \sstsubsection{
         BLOCKF = INTEGER (Given)
      }{
         The blocking factor for the new file. It must be a positive
         integer between 1 and 10.
      }
      \sstsubsection{
         OVRWRT = LOGICAL (Returned)
      }{
         If .TRUE., any existing file with the given name is silently
         over-written. Otherwise, an error is reported if the file
         already exists.
      }
      \sstsubsection{
         FUNIT = INTEGER (Returned)
      }{
         The logical unit number of the FITS file. Returned equal to
         CVG\_NOLUN if an error occurs.
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
   }
}
\sstroutine{
   CVG\_OPEN
}{
   Opens an existing FITS file for read or update access
}{
   \sstdescription{
      This function opens an existing FITS file with a given path,
      and returns a logical unit number that can be used to access it
      using CVG and FITSIO functions.
   }
   \sstinvocation{
      CALL CVG\_OPEN( PATH, MODE, FUNIT, BLOCKF, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         PATH = CHARACTER $*$ ( $*$ ) (Given)
      }{
         The path to the file to be created. A file type of {\tt "}.fit{\tt "} will be
         added if there is no file type in the supplied string.
      }
      \sstsubsection{
         MODE = CHARACTER $*$ ( $*$ ) (Given)
      }{
         The access mode: {\tt '}READ{\tt '} or {\tt '}UPDATE. Case insensitive.
         Abbreviations can be used.
      }
      \sstsubsection{
         FUNIT = INTEGER (Returned)
      }{
         The logical unit number of the FITS file. Returned equal to
         CVG\_NOLUN if an error occurs.
      }
      \sstsubsection{
         BLOCKF = INTEGER (Returned)
      }{
         The logical record blocking factor.
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
   }
}
\sstroutine{
   CVG\_PCADC
}{
   Writes CADC-style provenance records to the current FITS header
}{
   \sstdescription{
      This creates headers in the current FITS header that record the
      number and names of all the immediate parents in the supplied
      NDG provenance structure. It also records the number of root
      parents---those without ancestors---and their observation
      identifiers from component OBIDSS within the MORE component of
      the supplied provenance structure. These are the observations.

      The names follow CADC convention as follows.  For the immediate
      parents:

      PRVCNT  =             \_INTEGER / Number of parents
      PRV1    = \_CHAR                / Name of the first parent
      PRV2    = \_CHAR                / Name of the second parent
          :        :        :        :        :        :
      PRVn    = \_CHAR                / Name of the PRVCNTth parent

      for the root provenance:
      OBSCNT  =             \_INTEGER / Number of root-ancestor headers
      OBS1    = \_CHAR                / First observation identifier
          :        :        :        :        :        :
      OBSn    = \_CHAR                / OBSCNTth observation identifier

      and the output file name:
      FILEID  = \_CHAR                / Filename without extension

      The above headers are prefaced by a blank header and a title
      {\tt "}Provenance:{\tt "} comment.

      The PRODUCT keyword{\tt '}s value is modified for FITS extensions.  It
      has {\tt '}\_$<$extname$>${\tt '} appended where $<$extname$>$ is the lowercase name of
      the standard EXTNAME keyword.
   }
   \sstinvocation{
      CALL CVG\_PCADC( IPROV, FUNIT, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         IPROV = INTEGER (Given)
      }{
         The identifier of the PROVENANCE that is to be written to
         the FITS headers. If NDG\_\_NULL is supplied, no provenance is
         stored in the header, but the PRODUCT keyword is still updated.
      }
      \sstsubsection{
         FUNIT = INTEGER (Given)
      }{
         The logical unit number of the output FITS file.
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Ancestors that have been flagged as {\tt "}hidden{\tt "} are ignored.

         \sstitem
         A warning is issued if the OBSIDSS component cannot be found
         for a root ancestor.  The value of OBSCNT gives the number of
         ancestors with an OBSIDSS value.
      }
   }
   \sstdiytopic{
      Prior Requirements
   }{
      The FITS file must already be open.  The current HDU in the FITS
      file should be the primary and the standard headers should be
      present.
   }
}
\sstroutine{
   CVG\_RETRx
}{
   Retrieves a value from an array
}{
   \sstdescription{
      The value stored at a given index within the supplied array is
      returned.
   }
   \sstinvocation{
      CALL CVG\_RETRx( EL, INDEX, DATA, VALUE, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         EL = INTEGER (Given)
      }{
         The number of elements in the array.
      }
      \sstsubsection{
         INDEX = INTEGER (Given)
      }{
         The index within the array of the required value.
      }
      \sstsubsection{
         DATA( EL ) = ? (Given)
      }{
         The input array.
      }
      \sstsubsection{
         VALUE = ? (Returned)
      }{
         The returned value.
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         There is a routine for all numeric data types: replace {\tt "}x{\tt "} in
         the routine name by B, D, I, R, UB, UW, or W as appropriate.  The
         VALUE and DATA arguments must have the data type specified.
      }
   }
}
\sstroutine{
   CVG\_SCADC
}{
   Writes CADC-style provenance to a FITS file specified by an
   environment parameter
}{
   \sstdescription{
      This opens the FITS file associated with the specified parameter,
      and adds headers to the primary FITS header that record the
      number and names of all the immediate parents in the supplied
      NDG provenance structure. It then closes the FITS file. It also
      records the number of root parents---those without ancestors---and
      their observation identifiers from component OBIDSS within the
      MORE component of the supplied provenance structure. These are
      the observations.

      The names follow CADC convention as follows.  For the immediate
      parents:

      PRVCNT  =             \_INTEGER / Number of parents
      PRV1    = \_CHAR                / Name of the first parent
      PRV2    = \_CHAR                / Name of the second parent
          :        :        :        :        :        :
      PRVn    = \_CHAR                / Name of the PRVCNTth parent

      for the root provenance:
      OBSCNT  =             \_INTEGER / Number of root-ancestor headers
      OBS1    = \_CHAR                / First observation identifier
          :        :        :        :        :        :
      OBSn    = \_CHAR                / OBSCNTth observation identifier

      and the output file name:
      FILEID  = \_CHAR                / Filename without extension

      The above headers are prefaced by a blank header and a title
      {\tt "}Provenance:{\tt "} comment.

      The PRODUCT keyword{\tt '}s value is modified for FITS extensions.  It
      has {\tt '}\_$<$extname$>${\tt '} appended where $<$extname$>$ is the lowercase name of
      the standard EXTNAME keyword.
   }
   \sstinvocation{
      CALL CVG\_SCADC( IPROV, PARAM, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         IPROV = INTEGER (Given)
      }{
         The identifier of the PROVENANCE that is to be written to
         the FITS headers. If NDG\_\_NULL is supplied, no provenance is
         stored in the header, but the PRODUCT keyword is still updated.
      }
      \sstsubsection{
         PARAM = CHARACTER $*$ ( $*$ ) (Given)
      }{
         The name of the environment parameter associated with the FITS
         file.
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Ancestors that have been flagged as {\tt "}hidden{\tt "} are ignored.

         \sstitem
         A warning is issued if the OBSIDSS component cannot be found
         for a root ancestor.  The value of OBSCNT gives the number of
         ancestors with an OBSIDSS value.
      }
   }
}
\sstroutine{
   CVG\_SHOWHEADER
}{
   Displays all headers from one or all HDUs on standard output
}{
   \sstdescription{
      This routine displays headers from the current HDU, or all HDSUs,
      on standard output.
   }
   \sstinvocation{
      CALL CVG\_SHOWHEADER( FUNIT, ALL, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         FUNIT = INTEGER (Given)
      }{
         The FITSIO unit number for the FITS file.
      }
      \sstsubsection{
         ALL = LOGICAL (Given)
      }{
         If .TRUE., list headers from all HDUs. Otherwise, list only the
         current HDU.
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
      \sstsubsection{
         Copyright (C) 2013 Science \& Technology Facilities Council.
      }{
      }
      \sstsubsection{
         All Rights Reserved.
      }{
      }
   }
}
\sstroutine{
   CVG\_WHISR
}{
   Appends NDF history records to the current FITS header
}{
   \sstdescription{
      This appends all the NDF HISTORY records in an easy-to-read format
      to the current FITS header.
   }
   \sstinvocation{
      CALL CVG\_WHISR( NDF, FUNIT, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         NDF = INTEGER (Given)
      }{
         The identifier of the NDF whose HISTORY records are to be
         written to the FITSD headers.
      }
      \sstsubsection{
         FUNIT = INTEGER (Given)
      }{
         The logical unit number of the output FITS file.
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
   }
   \sstdiytopic{
      Prior Requirements
   }{
      The NDF and the FITS file must already be open.  The current
      HDU in the FITS file should be the primary and the other headers
      should have been written.
   }
}
\sstroutine{
   CVG\_WPROV
}{
   Writes general provenance records to the current FITS header
}{
   \sstdescription{
      This creates headers in the current FITS header that record the
      supplied provenance information.

      The tabulated indexed headers below, all with string values, are
      written for each ancestor NDF.  The keyword index n is the
      provenance identifier for each NDF, starting at 0 corresponding
      to the current NDF.  All have value {\tt '}$<$unknown$>${\tt '} if the information
      could not be found, except for MORE information; the PRVMn header
      is omitted if there is no MORE information to record.

      Keyword   Comment
      \sstitemlist{

         \sstitem
         ------   -------
         PRVPn     Path of the $<$nth$>$ parent
         PRVIn     Identifiers of direct parents for $<$nth$>$ ancestor
         PRVDn     Creation date of $<$nth$>$ parent
         PRVCn     Creator software of $<$nth$>$ parent
         PRVMn     Contents of MORE of $<$nth$>$ parent

      }
      where $<$nth$>$ is the appropriate ordinal string, e.g. 1st, 2nd,
      3rd, 4th.

      The above headers are prefaced by a blank header and a title
      {\tt "}Provenance:{\tt "} comment.  There is a blank header between each set
      for improved legibility.
   }
   \sstinvocation{
      CALL CVG\_WPROV( IPROV, FUNIT, STATUS )
   }
   \sstarguments{
      \sstsubsection{
         IPROV = INTEGER (Given)
      }{
         The identifier of the PROVENANCE that is to be written to
         the FITS headers. If NDG\_\_NULL is supplied, this function
         returns without action.
      }
      \sstsubsection{
         FUNIT = INTEGER (Given)
      }{
         The logical unit number of the output FITS file.
      }
      \sstsubsection{
         STATUS = INTEGER (Given and Returned)
      }{
         The global status.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Supports up to 9999 ancestors.

         \sstitem
         The PRVPn, PRVIn, and PRVMn keywords may often need more than
         the maximum 68 characters allowed in a keyword character value.
         Therefore this routine uses the non-standard Long-string Keyword
         Convention that permits long strings to continue over multiple
         headers.  If any of the aforementioned keywords{\tt '} values exceeds 68
         characters, this routine adds a warning in some COMMENT headers
         and writes a LONGSTRN header, whose value is the version of the
         convention being used.
      }
   }
   \sstdiytopic{
      Prior Requirements
   }{
      The FITS file must already be open.  The current HDU in the FITS
      file should be the primary and the standard headers should have
      been written.
   }
}
\normalsize

\end{document}