RPS Installation Guide

RPS Logo

Remote Proposal Submission (RPS) Software Installation Guide

Machine Requirements:

System Type:: DEC Alpha OSF/1 3.x or DEC MIPS Ultrix; Linux (Red Hat 7.x is known to work, but will require modification of most Makefiles as instructed below); 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

The complete package of RPS software, including project support files for ASCA, XTE, and ROSAT, is available by anonymous FTP or 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:

Getting Started:

Create an account on the machine in which you intend to use RPS. Make sure it satisfies the above criteria! The account name should be "rps" to be consistent with other sites using the RPS software.
Retrieve the archive "rps-package.tar.gz" (see Downloading the RPS Software) and place it in the "rps" home directory.
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/
```
After obtaining the slalib C library (see Downloading the RPS Software), put the source code files into the ~rps/src/slalib/ directory.
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:
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).
Also, if line 102 of Sview.c causes your f77 to give a compilation error, remove the string "' ' //" from this line.
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,^/,,"
```
Change directory to ~rps/src/rps and edit rps.c. Change the string 'legacy.gsfc.nasa.gov' to the name of the machine 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.)
If you are not installing the RPS software on either of the two suggested platforms, then you will need to check to see if the `Mail` command works the same on your machine as it does on ours. Does the following command work from the shell prompt?
```
	% Mail -s "any subject" your-address@local.machine < ~rps/template
```
If that command gives you an error, then you must alter the source code file ~rps/src/util/mail.c so that it will send e-mail correctly on your system. After doing that, be sure to test it thoroughly. Also, the `Mail` command should be located in one of the following directories: /usr/ucb, /usr/bin, or /bin. If it exists elsewhere, then you will need to make the appropriate modifications to the "set path" commands in the csh scripts in ~rps/bin.
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.
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.
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.
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:
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.)
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:
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. The other environment variables specified in this script are all required by the RPS software. A certain amount of customizability is allowed here, but be sure you know what you are doing. If you change any of the environment variables, make sure you move/rename the directories and/or support files accordingly. Follow through and make the same changes in startRPSmail.csh and startRPSserver.csh as you did for startRPS.csh.

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:
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:
For temporary files created by the e-mail server. Setting it to the same location as $RPSTMPDIR is fine.
$RPSMAILS_TCOM:
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:
Path and file name of the e-mail server's history log file. (The software will create this file.)
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:
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.
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 both servers (rpsd and rpsmaild) were started using the command:

	% ps auxgw | grep rps

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 rps

If the result of this command lists both the rpsd and rpsmaild processes, you should proceed by testing the RPS client first 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 the RPS client and server appear to be working correctly, try sending a blank e-mail message to the rps account on your machine. The e-mail server should almost instantaneously respond with the contents of the ~rps/template file. If it does not respond, check the ~rps/log/rpsmaild.log file and the ~rps/xhistorydb.dat file to see if your e-mail was received and processed by the e-mail server software. If it was not, make sure the MAIL environment variable is correctly set and look in the mail spool directory to see if the message is there. If it's still there, either you have the MAIL environment variable incorrectly set in the startRPS.csh script or the e-mail server may have terminated. If it has terminated (check first!), try restarting it by executing the ~rps/bin/startRPSmail.csh script. If the message was processed and logged in both the log file and the history file and the e-mail server is still running, then it is possible your mail transport agent or mail delivery agent is not working correctly on your machine or is working but not in the manner RPS expects. Otherwise, if you have made modifications to ~rps/src/util/mail.c in step 7(d), then the problem is most likely there. Check that module again to see if you have modified it correctly.

If you have any questions concerning RPS or the installation procedure, please contact the RPS Team Leader directly via e-mail.

Last modified: Friday, 07-Dec-2007 21:45:25 EST
Page author: Edward J. Sabol (ADNET), RPS Team Leader

RPS Development Team: RPS Help Desk

Last modified: Friday, 07-Dec-2007 21:45:25 EST

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: