RJTOOLS  -  Rolf A. Jansen's miscellaneous tasks & tools package

RJTOOLS is a package of IRAF CL scripts and a few auxilliary compiled tasks, that I developed over the years while at the Kapteyn Laboratory, CfA, ESA's ESTEC and presently at ASU, and were sufficiently useful to me to think that they might be of more general use. About half of them are low-level tasks, meant to be used as part of scripts. Many of these tasks return the result of their action as task parameters (and sometimes, optionally, to the standard output and/or a text log file as well). This effectively allows easy nesting of tasks and building quite complex scripts (rather than having to resort to programming directly in SPP, Fortran or C), and surpasses the capabilities of using pipes to pass the output of one task to the input of another.

The tasks are transparantly grouped into several sub-packages and were tested under IRAF v2.11.3--v2.12.2, but if you find any bugs or if you improved any of these tasks I would like to hear from you.

Finally, this code is provided as is and no suitability for any purpose, existing or future, is claimed nor implied, nor will any liability for the use or mis-use of this product ever be accepted be neither the author nor any of his former, current or future employers. Reselling for profit or hiding or attempting to hide the source code, or patenting or attempting to patent any of the code, or use for military purposes is strictly forbidden. Otherwise, and whereever this blurb is unclear, incomplete, untenable or plain nonsense, the provisions of the GNU General Public License will apply to this product. Share and Enjoy!

Rolf A. Jansen <Rolf.Jansen@asu.edu>
Tempe AZ, Aug 25 2004

RELEASE INFORMATION
=============================================================================
Tue Aug 11 18:00:00 MST 2003   --> version = 11Aug2003
        Initial public version for IRAF v2.12.1 (rjtools_v2.12) (RAJ).
Wed Dec 10 18:00:00 MST 2003   --> version = 10Dec2003
        Release including 'tvtools/ctrcoo.cl' and updated man pages and
        'apropos' database. (RAJ).
Tue Aug 25 18:00:00 MST 2004   --> version = 25Aug2004
	Release including 'markall'/'tvmarkall' and 'imregister', with
        updated 'help' pages and 'apropos' database (RAJ).
Sun Mar 27 18:00:00 MST 2005   --> version = 27Mar2005
        Minor release that adds 'markstds' to 25Aug2004 release (RAJ).
Thu Jun 16 18:00:00 MST 2005   --> version = 16Jun2005
        Fix of bug in version-check in 'imgstat' (RAJ).
Thu Jul 12 18:00:00 MST 2007   --> version = 12Jul2007
        Fixed bug in 'xdisplay', added parameters and/or functionality
        to 'imregister' and 'markall'; new RHE4.3 and MacOS10.4[Intel]
        binaries for task 'arg'; updated 'help' pages. (RAJ).

INSTALLATION INSTRUCTIONS
=============================================================================
Installation of this external package  consists of obtaining  a compressed
tar archive, unpacking it,  and telling IRAF about its existence.  On some
platforms, if no pre-compiled binary is available, you may need to compile
the source code of task  'arg'.  The package may be installed for either a
site or as a personal installation.

[1] The package is distributed as a  gzip-compressed tar archive with both
    all scripts, source code and, for select host architectures,  binaries
    of task 'arg'.  Note that IRAF includes a tar reader.  The most recent
    version (see Release Information above)  of the compressed tar archive
    may be obtained via the web from URL:

        http://www.public.asu.edu/~rjansen/iraf/rjtools_2.12_version.tgz

    Download (binary mode) and save the file to disk to /iraf/extern/  for
    a site installation,  or to (a subdirectory of)  your IRAF home direc-
    tory  for a personal installation.  For a site installation,  you must
    now login as the 'iraf' user and go to /iraf/extern/.


[2a] To extract all package files from the tar archive using 'rtar':

        cl> !(g)unzip rjtools_2.12_version.tgz     (GNU: gunzip, otherwise: unzip)
        cl> softools
        so> rtar -xrf rjtools_2.12_version.tar
        so> bye
    
    On some systems, an error message will appear ("Copy  'bin.generic' to
    './bin  fails") which can be ignored.

[2b] Alternatively, (GNU) tar may be used to extract the source files:
    
        %  gtar -xvpzf rjtools_2.12_version.tgz    (Linux)
    or:
        %  (g)unzip rjtools_2.12_version.tgz        (Unix)
        %  (g)tar xvpf rjtools_2.12_version.tar


    Sites  should leave  the  symbolic link  'bin'  in  the  package  root 
    directory  pointing  to  'bin.generic',  but  can  delete  any  of the
    bin.arch  directories that won't be used.  If there is
    no binary directory for the system you are installing,  create it  now.
    The tar file can be deleted after successfully unpacking  'rjtools' .


[3] Next, tell IRAF about the existence of  'rjtools' .

  [site installation]
    If this is a site installation, edit  hlib$extern.pkg :

        %  cd $hlib
        %  vi extern.pkg    (or use 'emacs' instead of 'vi')

    Define  the environment  variable  rjtools  to be  the pathname to the
    'rjtools' package root directory.  Unix pathnames  MUST  be terminated
    with a '/'.  Edit  extern.pkg  to include the following lines:

        reset rjtools        = /path/rjtools_2.12/
        task rjtools.pkg     = rjtools$rjtools.cl

    where  "path"  is the full directory path to where you
    unpacked the tar archive  (e.g., /iraf/extern/).  Near the end  of the
    extern.pkg  file, update the definition of  helpdb  so it includes the
    'rjtools' help database, copying the syntax already used in the string.
    Add this line  before the line containing  a closing quote:
    
        ,rjtools$lib/helpdb.mip\

    In order for 'rjtools' tasks to be found by task 'apropos',  you might
    consider appending the look-up table rjtools$lib/apropos.db  to either
    of the following two files (depending on whether and where the  STSDAS
    package is installed on your system):

        /iraf/extern/stsdas_version/lib/apropos.db
        /iraf/iraf/local/apropos.db.local

    For example:
        cl>  type rjtools$lib/apropos.db dev=txt >> stsdas$/lib/apropos.db
    or: %   cd /iraf/extern
        %   cat rjtools_2.12/lib/apropos.db >> stsdas_4.3/lib/apropos.db


  [personal installation]
    If you are installing the 'rjtools' for personal use,  tell IRAF about
    the  package  via  your  login.cl  or  loginuser.cl  file.   Somewhere
    before the final "keep" statement, insert:

        reset rjtools        = /local_path/rjtools_2.12/
        task rjtools.pkg     = rjtools$rjtools.cl
        printf ("reset helpdb=%s,rjtools$lib/helpdb.mip\nkeep\n",
            envget("helpdb")) | cl
        flpr


[4] Should you need to (re)compile the 'arg' source code, then you need to
    enter the  src  subdirectory of  rjtools_2.12  and run  C-shell script
    arg_iraf.install  after defining the IRAFARCH environment variable:

        cl>  show arch
        .redhat                         <&mdash for example

    Then the  IRAFARCH  environment variable should be set to  redhat  (no
    leading period!):

        %  setenv IRAFARCH redhat       (csh or tcsh)
        %  export IRAFARCH=redhat       (bash)

        %  cd rjtools_2.12/src       or:  cl>  cd rjtools$src/
        %  ./arg_iraf.install             cl>  !arg_iraf.install

    This will try  to determine  the current directory path  (used to link
    the Unix 'man' page for 'arg' ), compile the source code,  and install
    executable 'arg'  in the appropriate 'bin.arch' directory.  You may be
    prompted for a Fortran77 compiler, if neither 'f77' nor 'g77' is found
    automatically  on your system.  When recompiling,  allow the script to
    overwrite the pre-packaged executable if prompted.

    Check for errors. If the executable is not moved to the correct binary
    subdirectory, then the step to define the path and/or architecture for
    the package was not done correctly.


This should complete the installation.  Task 'sysinfo' requires a "username"
to be defined.  To do so, add a line to the default "login.cl" file, e.g.,
directly following the line defining the 'userid' (in fact, it may be a copy
of that line):

        set     userid          = "jdoh"
        set     username        = "John/Jane D'Oh"

You can now start up IRAF, load the package and begin testing and using it.

================================ R.A. Jansen ================================