\chapter{Installation guide}
\label{install}

\section{XANADU}
The QDP/PLT software is a stand-alone segment of a larger package
called {\em XANADU} ({\em X-ray ANalysis And Data Utilization}).
Subroutines commonly used in XANADU software are placed in a
library/archive called XANLIB.
QDP/PLT is supplied with source code for the entire XANLIB library.
If you are short of disk space, it is possible to delete many of
the supplied files.
This appendix describes the minimum set of source files you need from
these directories.
Of course, if you don't plan to modify the code you can delete all
source files once the object library has been created.

All XANADU software uses a virtual disk called {\tt XANADU} to hide
system-dependent disk names.
It is possible to run the QDP/PLT software without implementing
the virtual disk, however, some commands such as interactive help
will not be able to locate supporting files.

\section{VMS instructions}
All the QDP/PLT software can be used
by adding a few lines to your {\tt LOGIN.COM} file.
First, you must define the {\tt XANADU} logical name
(to create a virtual disk).
In brief, if QDP is in the directory called {\tt DRB1:[XRAY.BIN]},
then the following line should be in your {\tt LOGIN.COM}:
\begin{verbatim}
$ DEFINE/TRANS=(TERM,CONCEAL)   XANADU   DRB1:[XRAY.]
\end{verbatim}
(The above line is {\em very} system dependent.)
In this example, {\tt DRB1:} is the physical device name.
If you do not translate to the physical device name,
but to a logical name (for example, {\tt USER:[XRAY.]})
then you should omit the {\tt TERM} option for the {\tt /TRANS} switch.
You will need to define the the following logical names:

\begin{verbatim}
$ DEFINE   GRAPHICS   XANADU:[PLOT.PGPLOT]
$ DEFINE   GRPSHR     GRAPHICS:GRPSHR.EXE
$ DEFINE   PLT$FONT   GRAPHICS:GRFONT.DAT
$ DEFINE   UFNYSHR    XANADU:[LIB]UFNYSHR.EXE
\end{verbatim}

{\tt GRAPHICS} should point to the top level PGPLOT directory.
In the above example,
this was assumed to be \verb@XANADU:[PLOT.PGPLOT]@
and should be changed appropriately if PGPLOT lies in another location.
{\tt GRPSHR} and {\tt PLT\$FONT} should not need to be changed.
You will also need to set up symbols pointing to both QDP and COD with
\begin{verbatim}
$ QDP      :==$ XANADU:[BIN]QDP
$ COD      :==$ XANADU:[BIN]COD
\end{verbatim}

\section{SUN UNIX instructions}
In order to create a {\em virtual} disk on a Unix system,
it is necessary to create a link in the root directory.
To do this, you must be root on your machine.
If QDP is in the directory {\tt /user/xray/bin},
then go to \, {\tt /} \, and type
\begin{verbatim}
% ln -s /user/xray xanadu
\end{verbatim}

In your \verb@ .cshrc @ file,
you will need to define the the following PGPLOT environment variable:
\begin{verbatim}
setenv PGPLOT_FONT /xanadu/plot/pgplot/grfont.dat
\end{verbatim}
Finally you will need to include the XANADU \verb@ bin @ directory
in your current path.
If you have not already added other directories to your upath,
you should add the following line to your \verb@ .cshrc @ file:
\begin{verbatim}
set upath = (/xanadu/bin)
\end{verbatim}

\section{NeXT NextStep instructions}
The UNIX interface on the NeXT is highly compatible with the SUN.
Therefore you should follow the instructions given in the previous
section.
Currently, QDP must be run from within a terminal application and
not as a stand-alone program with its own icon.

\section{MS DOS instructions}
PGPLOT and QDP/PLT have been tested under MS DOS.
Currently the only PGPLOT device handler that supports IBM graphics
cards (EGA and so forth) requires the use of Microsoft Fortran 5.0 (or later).
If you do not have this version of Microsoft Fortran,
you will need to write a new device handler as described in the PGPLOT
manual.
DOS versions of the system-dependent routines exist,
and all the of the QDP/PLT software has been compiled and tested
with the Microsoft Fortran compiler.
Command line editing is fully implemented under DOS,
but you will need to install the DOS {\tt ANSI.SYS} device driver.
This is done by adding a line like the following to your
\verb@CONFIG.SYS@ file.

\begin{verbatim}
Device   = C:\ANSI.SYS
\end{verbatim}

To default with command line editing switched on you should add
the following line to your \verb@AUTOEXEC.BAT@ file.

\begin{verbatim}
SET GTBUF_EDIT=ON
\end{verbatim}

\section{Portability}
The QDP/PLT software was originally developed on a DEC-VMS system
and later ported to a SUN-UNIX and NeXT NextStep systems.
QDP/PLT is currently supported on these three systems.
Since standard Fortran is extremely portable,
it should be a simple matter to port QDP/PLT to other systems.
Support for other systems will be minimal (due to lack of time),
but occasionally QDP/PLT will be tested on other systems,
such as MS DOS, to ensure that major problems are not being
introduced.

The author is interested in any attempt to port the QDP/PLT software
to other systems
and should be consulted before any such attempt is made.
System-dependent routines have been isolated into two files
called {\tt SYSIO.xxx} and \verb@SYS.xxx@,
where \verb@xxx@ denotes the operating system.
If the software is ported to new systems,
it may be necessary to add additional routines to the \verb@SYS.xxx@ file.
Although \verb@SYS.xxx@ should only be used on one system,
you should still write the routines in standard Fortran
so that others can use your file as a template.

\section{Relation to PGPLOT}
The QDP/PLT software can be considered to be a layer on top of PGPLOT.
Thus when installing QDP/PLT on your system,
you must first get PGPLOT working.
PGPLOT can either be obtained directly from Tim Pearson
or from the author when you obtain the QDP/PLT software.
If you are already running PGPLOT on your system,
then you will need to check that the installed version
is sufficiently recent to work with QDP/PLT.
If your version of PGPLOT does not contain the routines PGBBUF/PGEBUF,
then you will need to update it.
You may still wish to update PGPLOT if you discover
that your version is older than the version currently being used with QDP/PLT.
Of course, if you decide to update your version of PGPLOT,
you should be careful to save any locally written or modified versions
of PGPLOT device drivers.

If you are not running PGPLOT on your system,
then you will need to install it.
Since PGPLOT uses its own set of logical names to locate supporting files,
it can be located anywhere.
However, for consistency with other XANADU systems,
you may wish to install PGPLOT
in the \, {\tt XANADU:[PLOT.PGPLOT...]} \, directory.

\section{Directory structure}
In this documentation, VMS file names have been used.
It is a simple matter to map VMS file names to UNIX or DOS names.
A file name of \verb@ XANADU:[LIB.PLT]PLT.FOR@
implies that the file \verb@PLT.FOR@ is on the {\tt XANADU} disk,
in the {\tt PLT} sub-directory of a main directory called {\tt LIB}\@.
For example, on a Unix system,
the above file would be called \verb@/xanadu/lib/plt/plt.for@.
For ease of sharing XANADU files with systems that are not case sensitive,
only lower case file names are allowed under Unix.
On an MS-DOS system,
{\tt XANADU} should be the top level directory on your default hard disk;
so our sample file would be called \verb@\XANADU\LIB\PLT\PLT.FOR@.
An attempt should be made to preserve this type of organization on
other systems.

The following directories of the {\tt XANADU} virtual disk contain
files needed by the QDP/PLT software:
\begin{description}
 \item[{\verb@XANADU:[BIN]@}]
  contains the executable versions of both COD and QDP.
 \item[{\verb@XANADU:[LIB]@}]
  contains the XANLIB object library.
  \item[{\verb@XANADU:[LIB.COD]@}]
   contains a set of sample COD files.
  \item[{\verb@XANADU:[LIB.PLT]@}]
   contains the source code for the PLT subroutine
   and for other supporting routines.
  \item[{\verb@XANADU:[LIB.TERMIO]@}]
   contains the source code for the low level terminal IO routines.
  \item[{\verb@XANADU:[LIB.UFNY]@}]
   contains the source code for the demo user function.  On VMS systems
   \verb@UFNY.FOR@ should NOT be installed into the XANLIB library, but
   rather the sharable library used instead.
  \item[{\verb@XANADU:[LIB.XANLIB]@}]
   contains the system dependent routines.
   Currently, there is a \verb@SYS.VMS@ should be used on VAX VMS systems,
   \verb@SYS.SUN@ on SUN UNIX systems,
   and \verb@SYS.NEX@ on NeXT NextStep systems.
  \item[{\verb@XANADU:[LIB.XCOMS]@}]
   This directory contains the system-wide indirect command files.
   For example, the file \verb@HARD.PCO@ should create a hardcopy file and
   then queue the file to the printer.
  \item[{\verb@XANADU:[LIB.XHELP]@}]
   contains the source code for the interactive help.
  \item[{\verb@XANADU:[LIB.XPARSE]@}]
   contains the XSPEC parser routines.  Currently the following files
   are required from this directory: \verb@IXPLWR.FOR@,
   \verb@XCHKBL.FOR@, \verb@XCHKDL.FOR@, \verb@XCHOSE.FOR@,
   \verb@XCREAD.FOR@, \verb@XGTARG.FOR@, \verb@XMATCH.FOR@,
   \verb@XQMTCH.FOR@, \verb@XQUEST.FOR@, \verb@XSQUEZ.FOR@,
   \verb@XUNIDS.FOR@, and the include file
   \verb@XPARINC.INC@.
 \item[{\verb@XANADU:[PLOT.QDP]@}]
  contains the source code for the COD and QDP programs,
  the interactive help files, and the demonstration QDP files.
 \item[{\verb@XANADU:[PLOT.QDP.MANUAL]@}]
  contains the source listings of this manual in LaTeX format.
  To print the manual,
  you will need to issue the command \verb@ LATEX QDP @ twice,
  to ensure that the table of contents is correct.
 \item[{\verb@XANADU:[SRC.DOC]@}]
  contains the source code for the system level help programs.
  These are not needed to run the QDP/PLT software,
  but are useful when creating the help libraries.
\end{description}

\section{Porting to other systems}

When porting QDP/PLT to a new system, you should first get the
PGPLOT software working.
There are extensive instructions in the PGPLOT manual to help you
in this area.
Once PGPLOT is working you should next direct your attention to the
TERMIO software.

\subsection{Porting TERMIO software}

The TERMIO routines provide the basic terminal I/O for XANADU.
Currently the TERMIO software reads
and writes to the terminal using one of two completely different
methods.
One method involves standard Fortran I/O and the second method involves
single-character I/O.
The single-character method supports command line editing, which should
be regarded as a convenience and not as a necessity.
Therefore when porting TERMIO to a new operating system, it is a good
idea to first get the code working without command line editing.
Once the code is working and you have some free time, then you can
go back and add the single character I/O routines.

The system dependent routines are in {\tt SYSIO.xxx}.
Initially {\tt SYSIO.xxx} should be fairly simple and
only allow standard Fortran I/O.
To disable single character I/O, you will need to create a new version
of \verb@SYSIO.xxx@ (where xxx is your system descriptor).
This file should contain six routines, and five of these routines
can return without doing anything.
The routine \verb@FORTYP@ should return with the variable \verb@IFTYPE@
set equal to zero.
When this is done, it becomes impossible to accidently turn on command
line editing, which would cause the program to go into an infinite
loop if the \verb@RDCHR@ and \verb@PUTSTR@ routines have not been
implemented.

The {\tt [LIB.TERMIO]} directory contains several {\tt makefile}'s,
plus an example program {\tt TSTREC.FOR}.
You should try out the TSTREC program on your system to ensure that
the basic terminal I/O routines are working.

Once you have the standard Fortran version working,
and are fishing around for something to do,
you should then implement the single character I/O routines.
This means implementing the other routines found in \verb@SYSIO.FOR@.
Since many UNIX systems do not allow system functions to be called
directly from Fortran, many systems use some C code to provide this
interface.
Under SUN UNIX some routines are implemented using the file \verb@ciosun.c@.
The {\tt SYSIO.FOR} routine \verb@TTINIT@ should put the terminal
into single character I/O mode (called cbreak in UNIX).
\verb@TTRSET@ should return the
terminal to normal mode (called cooked in UNIX).
\verb@RDCHR@ should read a single character, and \verb@PUTSTR@ should
write a string to the terminal.
Both \verb@RDCHR@ and \verb@PUTSTR@ should work in passthru mode where
control characters (such as escape) are not interpreted by the terminal
driver but rather passed to the terminal.
\verb@PUTSTR@ can buffer the output, until \verb@FLUSH@ is called,
whereon all data should actually be written to the terminal.
Finally, you will need to modify \verb@FORTYP@ to return either +1
or -1 depending on whether Fortran on your system outputs a return
before or after each Fortran \verb@WRITE@ operation.
This will also allow command line editing to be switched on.

To test command-line editing, try the \verb@TSTREC.FOR@ program and
use the interactive \verb@%ED%ON@ command to switch it on.
Once you are convinced that command-line editing is working you can
then use the GTBUF\_EDIT logical name/environment variable to
automatically switch on editing for all XANADU software.

\subsection{Creating a new SYS.xxx routine}

Before you can run QDP you will need to create one other system
dependent file called \verb@XANADU:[LIB.XANLIB]SYS.xxx@.
As described below, not all routines in {\tt SYS.xxx} need to be fully
implemented in order to use QDP/PLT.
In addition, some of the routines are used by other parts of the
XANADU software and are not needed by QDP/PLT
This section only deals with the routines that are needed by QDP/PLT.

The following routines are implemented in standard Fortran in
\verb@SYS.SUN@ and therefore you should be able use that version
without modification:
\begin{verbatim}
FRELUN   Free up a logical unit number
GETLUN   Get a free logical unit number
LOCASE   Convert to lower case
UPC      Convert to upper case
\end{verbatim}

The following routines can be considered optional in that QDP/PLT
will still work if these routines do nothing.  Of course, implementing
these routines will increase the usefulness of QDP/PLT.
\begin{verbatim}
CONC     Converts filename to system preferred case
PLTTER   Toggle graphics/alpha mode on terminal
RDFORN   Read a foreign command, {\it i.e.}, the command line
SPAWN    Spawn to the operating system
\end{verbatim}

The last set of routines need to be implemented, although in many
cases some loss of functionality is allowed.
For example, subroutine \verb@PROMT@ must display the prompt.
It would be nice if the cursor was left at
the end of the prompt line, but if you don't know how to do that on
your system, use a standard Fortran write operation.
\begin{verbatim}
DIRPOS   Return the number of characters in directory spec
OPENWR   Wrapup for the Fortran OPEN statement
PROMPT   Write a prompt on the user's terminal
PTEND    Add prefix (disk and directory name) to file names
TRLOG    Translate logical name/environment variable
\end{verbatim}

\subsection{Compile and link the QDP program}

The final step should be fairly simple.
You should compile all the programs in the {\tt [LIB.PLT]} and
{\tt [LIB.XHELP]} directories.
You should also compile the needed files from {\tt [LIB.XPARSE]} and
{\tt [LIB.UFNY]}.
The non-system dependent routines should all compile without
errors.
If you do get an error (for example, due to some non-standard Fortran
sneaking in) then please let the author know so that the original can be
made made more portable.
All files in the {\tt [LIB...]} directory tree should be placed
in a library/archive.
Finally you should move to the {\tt [PLOT.QDP]} directory and
try to link the QDP program.
There are several {\tt makefile}'s that can be used as examples.
