1 RDPAR
!  HELP file for RDPAR Rev 1.2
!  John Lavagnino	March 29, 1982
		                        Last update: May 10, 1982

RDPAR is a set of input routines for use in place of FORTRAN formatted
input.  (It can be used with any other language supplied by DEC, but
there is little formal support as yet for any language other than FORTRAN.)

With RDPAR, all input is handled through a "parameter file".  This is just
an ordinary text file, containing the data you want to pass to your program.
But the order in which data appears in a parameter file is not important.
Rather than using position to identify data, RDPAR uses a "parameter name":
a string which appears at the start of each line.  A call to RDPAR within a
program specifies a parameter name, and RDPAR searches through the file
for it.

For each parameter name, you can specify that the (interactive) user should
be prompted for the data, or that the data should come from the DCL command
line used to run the program.  These and other features are handled entirely
within the parameter file; no recompilation of the program is necessary.

Any questions, complaints, paeans, or suggestions relating to RDPAR and its
documentation should be communicated to John Lavagnino  (P-315, 495-7389, or
GPVAX::LAV).
2 CAVEAT
There is only one way to get yourself into really serious trouble using
RDPAR: if you use the N-type parameter-reading routines improperly, you
can make loops in your program infinite.  This subset of routines is used
when you want to repeatedly look for the same parameter name, an
indeterminate number of times; for example, in reading a series of file
names.  The list of lines with this repeated parameter name in your
parameter file must end with one that has &NULL in place of a parameter.
Otherwise your program will go back to the start of the list and begin
again, and keep repeating this until your program decides to stop it; if
there is no other check in your program on this loop, it never will stop.

This problem cannot occur in using the R-type parameter-reading routines.
And it is as easy to avoid as it is to cause. See the Guide for more
verbiage on this subject.
2 DOUBLE_PRECISION
Since FORTRAN includes provisions for changing the data type used for
double precision variables without altering the source program (by use of
the /G_FLOATING compilation qualifier), RDPAR does too.  The calls RDDFP
and NRDDFP may be used if you want to explicitly require the use of
D-floating for reading in a parameter; RDGFP and NRDGFP do the same for
G-floating.  But the data type used by RDEXT and NRDEXT depends on the
version of the system you link to.  D4RDPAR.OBJ contains D-floating
versions of those calls; G4RDPAR.OBJ contains G-floating versions.

The data type used by RDEXT and NRDEXT for double precison is also used by
the calls RDPAR and NRDPAR, but only in converting floating-point
numerals.

The 4 in the object names means INTEGER*4; an INTEGER*2 version of
the system may appear sometime in the future.
2 GUIDE
A comprehensive Guide is available for RDPAR, including exhaustive
definitions of RDPAR's capabilities, examples, and notes on compatibility
with former versions.  This valuable document can be yours, if you merely
type
     
	$ PRINT/LOWER SYS$HELP:RDPAR.MEM
   
2 IMPLEMENTATION
First, make the following assignments (in your LOGIN file, ideally):

	$ ASSIGN SYS$UTIL:D4RDPAR.OBJ D4RDPAR
	$ ASSIGN SYS$UTIL:G4RDPAR.OBJ G4RDPAR

Then, whenever you link a program which uses RDPAR, include either
D4RDPAR or G4RDPAR in your LINK command; the second should be used
only if you used the /G_FLOATING qualifier in compiling your program.
A typical LINK command for a program using RDPAR:

	$ LINK THRENODY, SUB1, D4RDPAR, SYS$UTIL:PEPLIB/LIB

2 NOTES
There is one minor problem with interactive mode.  It occurs when you
use a formation like this:
    
Parameter name		^
   $     !Helpful text

If to the prompt "Parameter name: " which this produces you respond with
a ?, to output the comment, the comment will not be properly output as
"Helpful text" but as "nameful text": the parameter name "Parameter name"
is overlaid on the continuation line.  If the comment starts farther along
in the continuation line, "after" the parameter name, its text will not be
corrupted.
