National Aeronautics and Space Administration

Remote Proposal Submission (RPS) Software Installation Guide

Table of Contents:

• Machine Requirements
• Downloading the RPS Software
• Setup Instructions
  • Getting Started
  • Source Code and Makefile Modifications
  • Compiling the Software
  • Editing the Scripts
    • Description of RPS Environment Variables
  • Modifying the Project Support Files
    • Description of Project Support Files
• Testing and Troubleshooting

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:

Setup Instructions:

1. Getting Started:

1. Create an account on the computer on which you intend to use RPS. The instructions below assume the account name is "rps".
2. Retrieve the archive "rps-package.tar.gz" (see Downloading the RPS Software) and place it in the "rps" home directory.
3. 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/

4. After obtaining the slalib C library (see Downloading the RPS Software), put the source code files into the ~rps/src/slalib/ directory.
5. 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:

6. 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).
7. Also, if line 102 of Sview.c causes your f77 to give a compilation error, remove the string "' ' //" from this line.
8. 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,^/,,"

9. 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.)
10. 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.
11. 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.
12. 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.
13. 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:

14. 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.)
15. 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:

16. 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.)

    
    

17. 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:

18. 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.

    
    

19. 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:

	% ps auxgw | grep rpsd

	% ps -elf | grep rpsd

	% rps -h mission

	% rpsp -h mission

	% rps mission > test.form

	% rps mission test.form

	% rps -l mission test.form > test.latex