RPS Logo

Remote Proposal Submission (RPS) Software Installation Guide


Table of Contents:


Machine Requirements:

System Type:
Linux (Red Hat Enterprise Linux and variants are known to work)
other Unix system types are certainly possible but may require a lengthier installation process

Installed Software:
libxanlib.a (from the HEAsoft software package)
gzip (GNU zip compression software)
gcc (GNU C compiler) or other ANSI-compliant C compiler
GNU make or a BSD-compatible make
f77 or possibly some other FORTRAN-77 compiler (such as GNU Fortran)

Downloading the RPS Software:

The complete package of RPS software, including project support files for ASCA, XTE, and ROSAT, is available by HTTP from heasarc.gsfc.nasa.gov. The slalib C library should be obtained separately from the author. See How to Obtain SLALIB/C for more information.

Setup Instructions:

  1. Getting Started:

  2. Create an account on the computer on which you intend to use RPS. The instructions below assume the account name is "rps".
  3. Retrieve the archive "rps-package.tar.gz" (see Downloading the RPS Software) and place it in the "rps" home directory.
  4. Type the following commands to unzip and dearchive the various files and directories and move a few files around:
    	% gzip -d < rps-package.tar.gz | tar xvf -
            % mv rps-package.tar.gz distrib/
  5. After obtaining the slalib C library (see Downloading the RPS Software), put the source code files into the ~rps/src/slalib/ directory.
  6. Go into the "project" directory and delete all project files related to the missions that are not to be supported on your machine. For example, if you are supporting ASCA, remove all files that start with "rosat" and "xte". If project files do not already exist in this directory for the mission you will be supporting, you will most likely have to create your own project files. See the item Modifying the Project Support Files below for more information.

    Source Code and Makefile Modifications:

  7. Change directory to ~rps/src/Sview and edit the Makefile. Change the path specified by "XANLIB = ..." to the correct location on your machine. If your implementation of f77 doesn't like the ".for" extension for FORTRAN code files (e.g., some MIPS variations of f77), then you will also need to modify the ".for.a" rule. Insert the line "mv $< $*.f" (indented with a tab) after the line ".for.a:". Then, after the line "$(RM) -f $*.o", insert the line "mv $*.f $<" (again indented with a tab).
  8. Also, if line 102 of Sview.c causes your f77 to give a compilation error, remove the string "' ' //" from this line.
  9. In the same directory, edit the file view_wrap.for and search for "heasarc". Replace "heasarc" with the result of the following command:
    	% cd ~rps/..; pwd | sed "s,^/,,"
  10. Change directory to ~rps/src/rps and edit rps.c. Change the string 'alegacy.gsfc.nasa.gov' to the name of the computer you are installing RPS on. (Type `hostname` from the shell prompt if you are unsure what the exact name is. It's probably a good idea to use the fully qualified domain name.)
  11. If your C compiler (cc) is not ANSI-compliant, you will have to use gcc. All the makefiles (or Makefiles as the case may be) will have to have their "CC" variables changed accordingly. Also, any reference to a "-Olimit" option for cc in any Makefile will have to be removed as gcc does not support such an option.
  12. If you do not have gcc and your cc is ANSI-compliant, then you will need to edit the makefile in ~rps/src/slalib and change the variable settings for "CCOMPC" and "CFLAGC" to replace gcc usage with cc.
  13. Also, if you are not installing the RPS software on either of the two suggested platforms, then you will need to either modify many of the makefiles in the ~rps/src directory tree or use GNU make. Several of the makefiles use a specific feature of BSD-compatible versions of make (e.g., the make on DEC platforms) in relation to libraries. Any reference to something like "library_name(objectcode_file.o)" will probably fail on most strict System V-compliant Unix versions unless you install and use GNU make instead of the make that comes on your system. If installing GNU make is not feasible, consult with your local Unix guru or software development team on how to alter the makefiles to work on your system.
  14. RPS uses a client/server suite of programs. Thus, it must use one of the ports for communicating. The default set up uses port 56327, but that can be changed. No other widely used Unix program uses port 56327, so you probably won't have any problems with this, but check with your system administrator first. If you want to use a different port number, the number must be changed in the following files: ~rps/src/rps/rps.c and ~rps/src/rpss/rpss.c. Search for the string "#define PORT" in each file and change the number that follows this string to the port number you want to use. Make sure the port numbers are the same in both files! If they are not the same, then the client and the server will not be able to communicate with each other.

    Assuming your compiler and C libraries are ANSI C-compatible, then no other modifications to the source code should be necessary.

    Compiling the Software:

  15. You should now be ready to compile the software. Change directory to ~rps/src and execute the build.csh script. If something doesn't compile correctly, check the above information for step 5 again and make sure you haven't made any mistakes. If you have not made any mistakes in regards to modifications to either the source code or the Makefiles, then try to investigate why the code will not compile and fix it, if possible. (We cannot anticipate problems or test the software on every possible platform.)
  16. Once all source code has been successfully compiled, you can just execute the install.csh script to install the software. First, however, check that the $DESTDIR variable in this script is set correctly for your system and make sure that your current directory is ~rps/src.

    Editing the Scripts:

  17. In the ~rps/bin directory, edit each of the files that end in ".csh". In startRPS.csh, change '-----' to whatever the command `hostname` returns on the machine you are installing RPS on. Also, make sure the path defined on the line "setenv MAIL ..." correctly points to the mail spool file for the "rps" account if such a line is present. The other environment variables specified in this script are all required by the RPS software. The paths are customizable to your system. If you change any of the environment variables, make sure you move/rename the directories and/or support files accordingly.

    Description of RPS Environment Variables:
    $RPSHOMEDIR:
    This should be set to the path to the top-level RPS directory. Only, the "*.csh" scripts use this variable (as a convenience), so setting it outside of these scripts is not necessary. The default sets it to $HOME.
    $RPSPRJDIR:
    This environment variable should point to the directory that contains the various project support files (~rps/project in the distribution).
    $RPSTMPDIR:
    This directory is where temporary files are created by the RPS processor.
    $RPSMAILS_MAIL (deprecated):
    This should point to the location of the file (that should not already exist! the RPS e-mail server will create it as necessary) where the mail spool file is copied temporarily for processing by the RPS e-mail server.
    $RPSMAILS_TEMP (deprecated):
    For temporary files created by the e-mail server. Setting it to the same location as $RPSTMPDIR is fine.
    $RPSMAILS_TCOM (deprecated):
    This should point to the help file (~rps/template in the distribution) that users get when they send an e-mail that doesn't contain recognizable commands to the server.
    $RPSMAILS_HIST (deprecated):
    Path and file name of the e-mail server's history log file. (The software will create this file.)

  18. Arrange things with your system administrator so that the script ~rps/bin/startRPS.csh is executed by userid "rps" whenever the machine is rebooted. This script automatically starts both RPS servers.

    Modifying the Project Support Files:

  19. Now, it is time to modify the project support files in ~rps/project for your local use. Replace "project" in the following file names with actual name(s) of the mission(s) you intend to support. The following information pretty much assumes you are not creating project files from scratch for a new mission. The process is obviously much more lengthy if you have create these files for a completely new mission. If that is what you are doing, try to minimize the set up time by basing your forms and project files on those of a mission that already exists, if possible.

    Description of Project Support Files:
    project.paf:
    This should contain only one line with the address to which successfully submitted proposals should be sent. This e-mail address should not be the same address used by the RPS e-mail server or else all proposal submissions would be lost. It is probably a good idea to create another account on one of your local machines where nothing but processing of RPS submissions will take place.
    project_cover.pdf:
    This file contains the form field names and their default values for non-target-related fields. If you are setting up the software outside of the United States, you should at least change the default values for the POSTAL.COUNTRY and COI.COUNTRY(#) fields from "USA" to the abbreviation for your country. (Check the file project.pcf for the list of accepted country abbreviations.)
    project_target.pdf:
    This file contains the form field names and their default values for target-related fields. You probably will not need to change anything here.
    project.pcf:
    This file contains the constraints on a given field. Make sure each constraint is consistent with your intended usage. Specifically, you might need to modify the PROPOSAL.TYPE and DISTRIB.MEDIUM constraints, especially if you are installing RPS outside of the United States.
    project.phf:
    This is the help file, and it contains all the mission-specificdescriptions of the various fields on the form. If you made any changes to the above files, you should similarly reflect those changes here in the help file. Make sure you modify the first paragraph to reflect your intended usage regarding such issues as whether forms should be submitted in hard copy (and, if so, how many), etc.
    project.plf:
    This is the LaTeX template. Do not modify this unless you are familiar with LaTeX.

  20. Now, you need to edit ~rps/template and change it to reflect information specific to your local site. Things that should be changed here are: the e-mail address that users send to in order to interact with the e-mail server and the e-mail address for comments, questions, and feedback. You may also need to change the part that says whether or not electronic submission is required or not, and you should definitely change the third paragraph to reflect which missions are you supporting. Feel free to make any other additions you like here.

Testing and Troubleshooting:

Now, you are ready to start using RPS! Execute the script ~rps/bin/startRPS.csh. Check to make sure the rpsd server has been started using the command:
	% ps auxgw | grep rpsd
This assumes you are using a BSD-compatible version of Unix. Otherwise, type the following on strictly System V-compatible Unix flavors instead:
	% ps -elf | grep rpsd
If the result of this command lists the rpsd process, you should proceed by testing the RPS client with the following command (replace "mission" with the name of the mission you are supporting):
	% rps -h mission
You should get back the contents of ~rps/project/mission.phf. If you do not, check the rpsd.log file located in the ~rps/log directory to see if any error messages were logged. Also, review the above instructions to make sure you have made the necessary modifications to the various support files and mission project files, and make sure the environment variables are correctly set in the startRPS.csh script. If you still can't find the problem, try invoking the processor directly: (again replace "mission" with the name of the mission you are supporting)
	% rpsp -h mission
If the processor doesn't work, then there is either a problem with your project files or your environment variables or there may have been a problem compiling the RPS software on your computer. If the processor works and the client/server does not, make sure the port number being used by RPS is not being used by some other program. Are you sure the host name is set correctly? The other possibility is that your are installing RPS on a strictly System V-compatible version of Unix. RPS relies on certain BSD Unix-isms that may be incompatible with some System V implementations. Many System V Unix flavors also include an optional BSD compatibility library which may need to be installed separately. Please refer to your local system administrators on this issue. If the processor and client/server both return the help file correctly, then the software would appear to be working. Now, check your mission's form:
	% rps mission > test.form
If you have created your own project files for a previously unsupported mission, then be sure to read over 'test.form' carefully and compare it with your ".pdf" and ".pcf" files in ~rps/project. If you are satisfied the form looks as intended, fill it out with some test information, verify it, and check the LaTeX output:
	% rps mission test.form
(If verification successful...)
	% rps -l mission test.form > test.latex


If you have any questions concerning RPS or the installation procedure, please contact the RPS Team Leader directly via e-mail.
Last modified: Wednesday, 24-Jan-2024 17:47:46 EST
Page author: Edward J. Sabol (ADNET), RPS Team Leader
RPS Development Team: RPS Help Desk
HEASARC Home | Observatories | Archive | Calibration | Software | Tools | Students/Teachers/Public