\section{Low Level Routines}

\subsection{Plotting Routines}

\subsubsection{CLEARPLOT}

CLEARPLOT will reset the IDL plotting variables. \index{CLEARPLOT}

\subsubsection{CLEAR\_UTPLOT}

CLEAR\_UTPLOT will reset the UTPLOT plotting variables.\index{CLEAR\_UTPLOT}

\subsection{File and Directory Routines}

\subsubsection{CONCAT\_DIR}

CONCAT\_DIR is fundamental in allowing software to be portable
between Unix and VMS systems.  Given a directory logical name (or
environment variable) it will figure out whether to put a `/' between
the directory and the file name (for Unix systems), or to use
a `:' (for VMS systems).  A restriction is that the directory must
be a logical or environment variable.  Some sample calls are:
%
\idlinputa{outfil = concat\_dir(dir, filnam)}	\index{CONCAT\_DIR}
\idlinputc{outfil = concat\_dir('\$DIR\_GEN\_OBS', 'obs92\_23a.01')} 
%

\subsubsection{BREAK\_PATH}

Not sure why this was missing!!!!!

\subsubsection{FILE\_LIST}

FILE\_LIST enables you to get a string array {\it infil} with all the files
that fulfill a set of specifications by typing:
%
\idlinputa{infil = file\_list(dir, filenam)}\index{FILE\_LIST}
\idlinputa{infil = file\_list(dir, filenam, /cd)}
%
where {\it dir} is a string array of directory name(s) and {\it filenam} is a string
with the file designation (wild cards are ok --- e.g., sfd* or bda920101.*).

\subsubsection{FILE\_MENU}

FILE\_MENU works very much like FILE\_LIST but is menu driven.  It only
gets you a single file (infil) by typing:
%
\idlinputd{infil = file\_menu(dir,filenam)} \index{FILE\_MENU} 
%
\subsubsection{DATA\_PATHS}

DATA\_PATHS is fundamental to several routines including YODAT.  The
routine should return a string array with all the directories where
there are Yohkoh reformatted data.  The routine is site specific since
each institute organizes the data slightly differently.  A common practice
is to use DATA\_PATHS2 to get the standard data directories, and 
then append the specialized data directories.  See the sample DATA\_PATHS
program in the `site' branch of the Yohkoh software.
\index{DATA\_PATHS}

\subsubsection{DATA\_PATHS2}

DATA\_PATHS2 searches all `/yd' directories for directories with 
YY\_WW names (for example, `/yd1/92\_36a' or `/yd10/91\_35a').  Since the
generation of the data directory list is done automatically, it is not
necessary for a programmer to edit DATA\_PATHS every time a new week
of data are placed on-line.
\index{DATA\_PATHS2}

\subsubsection{NEW\_DPATH}\index{data directories}
\index{customizing your data path}

NEW\_DPATH will add elements to the Yohkoh data paths array. These are the disk areas
automatically searched for reformatted files.  A file option allows reading from a file
of pathnames.  This can be conveniently called from an a personal IDL startup file to
automatically define paths when entering IDL.  Switches are available to add current directory,
initialize contents, remove elements, or save current contents for later input via file option.
%
\idlinputa{new\_dpath, patharray}\index{NEW\_DPATH}
\idlinputb{new\_dpath, /current}
\idlinputb{new\_dpath, /init}
\idlinputb{new\_dpath, /file}
\idlinputb{new\_dpath, file=file}
\idlinputb{new\_dpath, /save}
%
Current contents of data paths area may be reviewed with the command:
\idlinputd{prstr, data\_paths()}

\subsubsection{GBO\_PATHS}

GBO\_PATHS is similar to DATA\_PATHS, but it looks for the
environment variables beginning with `DIR\_GBO' and creates a list.
This routine is used by YODAT to find where the ground-based FITS
files are located.
\index{GBO\_PATHS}

\subsubsection{GET\_SUBDIRS}

GET\_SUBDIRS will return all the subdirectories under a given
directory.  An example:
%
\idlinputd{dirs = get\_subdirs('/ys')}\index{GET\_SUBDIRS} 
%

\subsubsection{PR\_PATH}
\index{PR\_PATH}

PR\_PATH will display all the directories that are in the
IDL variable !path.

\subsubsection{PATH\_LIB}

PATH\_LIB will search directories in the IDL !path variable in the
order of the list to find a given IDL program.  The default is to
only give the first instance that the file is found, but it is possible to
get all locations by using the {\it /multi} switch.  A wild card (`*')
effectively sets the {\it /multi} switch).  Same examples are:
%
\idlinputa{path = path\_lib()}	\index{PATH\_LIB}
\idlinputb{path = path\_lib('add*')}	
\idlinputc{path = path\_lib('yodat', /multi)} 
%
\subsubsection{PR\_PATH\_LIB}

PR\_PATH\_LIB is like PATH\_LIB, except PR\_PATH\_LIB is a procedure which
will print the results to your screen.  For example,
%
\idlinputa{pr\_path\_lib,'gt\_*'}
%
will return a list of all ``gt\_'' routines

\subsubsection{FILES\_SEARCH}

FILES\_SEARCH will search all files in sub-directories from a given directory
for a given string.  In the following example, all .PRO files under the
/ys tree are searched to find the string `CONV\_'.
%
\idlinputd{files\_search, '/ys', 'CONV\_'} \index{FILES\_SEARCH} 
%
\subsection{String Manipulation}

\subsubsection{PRSTR}

PRSTR prints any string array to the terminal or a file, one element per line.
For terminal output, the default is to print by screen (Unix ``more'' behavior).
The {\it /compress} switch removes null lines and excess white space prior to output.
This is useful (for example) for printing FITS headers to terminal.  {\it /hc}
will create a hard copy to the printer selected by PPRINT.  {\it file=file} will write the results to a file.
%
\idlinputa{prstr, strarray}\index{PRSTR}
\idlinputb{prstr, strarray, /print}
\idlinputb{prstr, strarray, /compress}
\idlinputc{prstr, strarray, lun}
%
\subsubsection{STR2ARR}

Given a string, STR2ARR will separate the items into an array
using a `,' as the delimiter by default.  Some examples are:
%
\idlinputa{arr = str2arr('a,b,c,d,e,f,ggg,hh')}	\index{STR2ARR}
\idlinputc{arr = str2arr(!path, delim=':')} 
%
\subsubsection{ARR2STR}

Given an array, ARR2STR converts it to a string.  The items will be separated by
a comma by default.
%
\idlinputd{str = arr2str(indgen(10))}\index{ARR2STR} 
%
\subsubsection{STR\_REPLACE}

Given a string (or an array of strings) it is possible to replace all
occurrences of a given string using STR\_REPLACE.  In the example below, all occurrences of
``sfr'' are replaced with ``spr''.
%
\idlinputd{out = str\_replace(in, 'sfr', 'spr')}\index{STR\_REPLACE}
%

\subsubsection{WC\_WHERE}
The WC\_WHERE function will search a string array for the occurrence of a substring and
return the indices of the elements where a match is found.  The substring
may contain one or more wild cards.  An optional third parameter contains
a count of the elements returned.  The {\it case\_ignore} switch may be
used to force the search to be insensitive to the case of the characters.
%
\idlinputa{ss=wc\_where(strarray, pattern)}\index{WC\_WHERE}
\idlinputb{ss=wc\_where(filearray, 'sfr9310*', filecount)}
\idlinputc{ss=wc\_where(strarray, '*time*',/case\_ignore)}

\subsection{Miscellaneous}

\subsubsection{REBIN [IDL]}

REBIN is an IDL routine that enables you to make a 2
dimension array larger or smaller (it also works on
multidimensional arrays). To use it to create a new
512$\times$512 image (ndat) from a 64$\times$64 image (data) type:
%
\idlinputa{ndat=rebin(data,512,512,/sample)} \index{REBIN}
%
Note that the new x and y dimensions must be integral
multiples (or divisors) of the original array dimensions.

\subsubsection{PLOT\_TRAV}

It is possible to plot a time line showing when the SXT and BCS team members 
will be on travel to Japan by using PLOT\_TRAV.  The plot separates the
people by institution.  Some examples are:
%
\idlinputa{plot\_trav}	\index{PLOT\_TRAV}
\idlinputb{plot\_trav, /lparl}	
\idlinputb{plot\_trav, /ops}	
\idlinputb{plot\_trav, /bcs}
%
The default is to plot SXT personnel.  To show BCS personnel use the {\it /bcs}
switch.  The {\it /lparl} switch will only plot
the key Lockheed SXT personnel.

\subsubsection{RD\_TFILE (How to Read Text Files with IDL)}

RD\_TFILE is a generic ASCII (text) file reading routine.  It can be used to 
return the contents of any text file as an IDL array.  A fast algorithm is 
used which makes it more than an order of magnitude faster than reading 
line by line until the end of the file.  It can optionally read and convert string or 
numeric tables.  It is ideally suited for use in reading calibration files --
in many cases, existing ASCII calibration files can be read without change.
The automatic comment elimination feature makes it simple to internally
document calibration files or add to existing documentation without any 
changes to the IDL access routines.

It is hoped that the use of specialized ASCII read routines can be minimized 
by use of this routine.  Even if a calibration file has a complex internal structure,
RD\_TFILE can perform the initial read and the user can handle special
formatting problems with the IDL intrinsic READS function (read from the 
string array returned by RD\_TFILE).  No explicit file open or close commands
would be required by those routines which use RD\_TFILE.  Other typical 
uses are reading IDL source code (extract documentation), reading in 
Unix script and VMS command files for parsing, etc.

\index{ASCII files, reading}
\index{reading ASCII files}
\index{file, ASCII, reading}
The following features are available:
\IItem
\item read ASCII files into IDL variables
\item read table data using default or user specified delimiter
\item convert ASCII numeric vector or table data 
\item remove partial and full comment lines using default or user specified
  comment delimiter
\item optionally remove excess white space and null strings 
\end{itemize}

Calling Examples
%
\idlinputA{3.8}{text=rd\_tfile(filename)                   }{; orig. file-$>$ string array}\index{RD\_TFILE}
\idlinputB{3.8}{text=rd\_tfile(filename,/nocomment)        }{; same less comment lines}
\idlinputB{3.8}{text=rd\_tfile(filename,/compress)         }{; same less excess blanks}
\idlinputB{3.8}{data=rd\_tfile(filename,/hskip,head=head)  }{; return file header in head}
\idlinputB{3.8}{data=rd\_tfile('text.dat',3)               }{; strarr(3,N) (table data)}
\idlinputB{3.8}{data=rd\_tfile('fdata.dat',/auto,/convert) }{; auto determine \#col/data-type}
%
As a specific example, you can read in a Unix password file as a table
with a single command:
%
\idlinputa{passwd=rd\_tfile('/etc/passwd',delim=':',/auto,/nocomment)}
\idlinputb{help,passwd}

\begin{verbatim}
PASSWD          STRING    = Array(7, 39)
\end{verbatim}

Now, search for given user using WC\_WHERE and print out relevant fields 
%
\idlinputA{3.5}{ss=wc\_where(passwd(0,*),'free*')	  }{; search on name field}
\idlinputB{3.5}{prstr,passwd(*,ss)			  }{; print users record}

\begin{verbatim}
freeland
YI/g8JD8wqOuo
5498
15
Samuel L. Freeland
/sxt1data0/people/freeland
/bin/tcsh
\end{verbatim}

\subsubsection{DEF\_TAPD}

DEF\_TAPD returns default tape drive names as a scaler string.  It includes default entries for the
most common operating systems.  It offers automatic substitution of the an
input drive number (default is drive 0).  If the system variable !ys\_deftape is defined,
the routine will return that value (with drive number substitution, if requested).\index{tape drive names}
%
\idlinputa{drive = def\_tapd()}\index{DEF\_TAPD}\index{default tape drive}\index{tape drive names}
\idlinputc{drive = def\_tapd(2)}

\subsubsection{WMENU\_SEL}

WMENU\_SEL is an expansion on the IDL WMENU routine.  It allows for many menu
pages if the number of items will not fit on one page.  It also allows a user
to select several items.  Some sample calls are:
%
\idlinputa{ss = wmenu\_sel(array)}	\index{WMENU\_SEL}
\idlinputc{ss = wmenu\_sel(files, /one)}
%

