../doc/db.tex
created from help file
../help/db.hlp
January 12, 2001
Synopsis
? produces a list of commands recognized
(at the current level of CMLI).
help All help topics, via ASK or CMLI
?? All help topics, via ASK or CMLI
?? [helplibraryname] All help topics in another library,
via ASK or CMLI.
\H ASK help topics, via ASK or CMLI.
\H [helplibraryname] ASK help topics, via ASK or CMLI.
Description:
Get access to help facilities. Defaults to USERS.HLP, top-most level.
If programming using CMLI rather than ASK, CMLI will catch a single '?'
and list all currently available commands instead
See also <QuestionMarkX2> (??), \H, and <QuestionMark> (?).
Synopsis
??
?? [helplibraryname]
Description:
Get access to help facilities.
[helplibraryname] defaults to USERS, top-most level,
unless program has defined the help file using INIT_HELP() or CMLI_HELP().
See also HELP and \H and <QuestionMark>.
Synopsis
\H
\H [helplibraryname]
Description:
Get access to help facilities for ASK.
[helplibraryname] defaults to USERS, ASK level if it exists, unless
the program has defined the help file using INIT_HELP() or CMLI_HELP().
See also HELP, <QuestionMarkX2>, and <QuestionMark>.
? produces a list of commands recognized by CMLI (at this
level of CMLI).
Help files *.HLP are ASCII, with each topic indicated by a line
with a number (topic level) in the first column and the topic name.
The following text is the body of the help for that topic.
1 indicates the topmost level. All subtopics which follow are
associated with that topic, until a new topic of the same level appears.
Exclamation marks (!) comment out a line. Under VMS, *.HLP files
are converted to binary *.HLB for use with executables.
In order for both standard help facilities (like for ASK) to be
available along side program specific ones, create only one top
level per help file. For example,
"1 ASK" in ASK.HLP (Need)
"1 HELP" in HELP.HLP (Need)
"1 CMLI" in CMLI.HLP (Optional)
"1 DOPLOT" in DOPLOT.HLP (Optional)
"1 MINUIT" in MINUIT.HLP (Optional)
"1 MSRLIB" in MSRLIB.HLP (Optional)
"1 YOURPROGRAM" in YOURPROGRAMONLY.HLP (Preferably)
Then concatinate the files together into YOURPROGRAM.HLP
(see [.HELP]DESCRIP.MMS or [.HELP]Makefile.)
Finally, only on VMS systems, create a binary help library *.HLB.
Note, the help files you include should reflect the program library
modules you are linking.
Programming note:
ASK.FOR and CMLI.FOR have common block variables HLP_PATH and HLP_FIL,
which needs to be initialized in main part of program,
by calling
call init_help('path', 'yourhelpfile', 'level').
Do not include a path or an extention in 'yourhelpfile'.
'level' is optional.
Alternatively, don't define the path directly using init_help.
Either
call init_help(' ', 'yourhelpfile', ' ')
or
call CLMI_HELP('yourhelpfile', ' ')
and instead the default path can be set using
assign <path> MSRHELP: (On VMS)
or
setenv MSRHELP <helpdir> (On Unix)
before running the program.
Both help-unx.c and help-vms.for have the environment variable MSRHELP
available to use if the path for the help file is not defined
within the program.
The assignments are best set on a system-wide basis by your system
manager for shared stable programs. The "init_help()" is convenient for
those who are unfamiliar with assignments and/or who are actively developing
software.
ASK libary for user IO, for linking to FORTRAN code.
Summary
* Macro playing and recording (see commands containing @, \ )
* Assignment of "variables" (see \= and \CALC)
* Command line history and in-line editing (on some operating systems)
* Can go into CALCulator mode (see \C*ALC).
* Can to into EVALuation mode (see \=).
* Can issue a system call on some operating systems.
* Help.
Synopsis
\C, \C*ALC
Description:
Enter calculator mode. Exit with a single blank line.
Expressions and assignments to variable names are allowed.
All implimented functions use the generic fortran name.
All numbers and variables are stored as double, including
logicals .TRUE. and .FALSE.
See Expressions
program prompt >>\= pisq = pi**2
9.8696044
program prompt >>\= run = 1234
1234.0000
program prompt >>\calc
CALC> run = run + 1
1235.0000
CALC> silly = (cos(pisq) .eq. run)
0.0000000
CALC> silly
0.0000000
CALC>
program prompt >>
Enter run number >> run
Synopsis
\= [expression]
Enter EVALuation mode. Identical to \CALC, except that exits
after one line. See \CALC for which functions, operators, etc.
are allowed in expressions and assignments.
All constants created can be saved to a macro (indirect)
file using the command @#[filename].
Alternatively, the routines EVALLOAD(filename) and
EVALSAVE(FILENAME, USE_INDIRECT) in EVALTAB.FOR reads in/saves
to the user's evalrc resource file for defining variables for EVAL/CALC/ASK.
It briefly uses the first free unit number between 0 and 19
to open and read the file. These routines are not currently called by ASK,
other than @# using EVALSAVE.
Run a macro (indirect) file using @. Record a macro file
by starting with @+[filename] and ending with @-.
See @, @-, @+
Synopsis
@ [filename]
Get responses from macro (indirect) file instead of from terminal.
Synopsis
@+ [filename]
Record responses from terminal to a macro (indirect) file.
Use @- to stop recording. See \NOISY.
Synopsis
@-
Stop recording responses from terminal. (See @+)
Synopsis
@# [filename]
Save all ASK constants to a macro (indirect) file.
** OBSCURE COMMAND ** Not Fully tested.
Synopsis
\@ Resume reading from a macro (indirect) file
\-@ Suspend reading from a macro (indirect) file
** OBSCURE COMMAND ** Not Fully tested.
Synopsis
\-I
Indirect mode off.
Synopsis
\N, \NOISY Enable noisy recording mode
\-N, \-NOISY Disable noisy recording mode
When recording users responses to a files with the @+ command,
a comment line containing the prompt is written to the recording
file, on the line before the user's response.
Synopsis
\D [character] Add a delimitor character
\-D [character] Remove a delimitor character
Delimitor characters are the characters such as comma (,) or space ( )
which separate numbers and strings when ASK is called with
more than one variable. The default delimitor is comma.
Synopsis
\G [character] Add an ignored character
\-G [character] Remove an ignored character
Specifies characters to ignore when reading in numerical
fields but not character fields. These are by default [ and ],
which are used by TELL to indicate arrays of numbers,
but which are not recognized by ASK.
Synopsis
\E, \E*CHO enable echoing
\-E, \-E*CHO disable echoing
Enable or disable echoing of ASK, TELL prompts and the responses to ASK,
when running a macro (indirect) file.
Synopsis
\L [n]
Loop back to the beginning of the current macro (indirect) file
(if any) [n] times. The total number of times the macro will
be run is n + 1 times. Note: \l must be the last command of the macro file.
Probably doesn't make sense outside of macro files.
Note: the number of repeats may be a variable that has been
previously assigned using "\=" or just a number.
program> \= ifore = 23154 file loopy.jes:
program> \= iback = 23167 \= ifore = ifore + 1
program> \= nrepeat = 4 \= iback = iback + 1
program> @loopy.jes \l (nrepeat-1)
** OBSCURE COMMAND ** Not Fully tested.
Synopsis
\T [filename]
Type a file.
DISABLED!! ** OBSCURE COMMAND ** DISABLED!!
Synopsis
\W [n]
Wait [n] seconds.
Disabled because very system dependent and of no obvious use.
See HELP under top level HELP, or HELP help file,
for a description of help under ASK.
Synopsis
! Comments out rest of line
Synopsis
! Comments out rest of line
How to make system calls from within the program.
See SystemCall.
How to make system calls from within the program.
Synopsis
$ [dcl command]
Creates a spawned process so that you can issue a single DCL command.
Synopsis
$ [shell command]
^Z Suspend program
fg resume program
Control Z suspends the program, so you may make system calls.
fg resumes the program. $ creates a spawned process so that you can
issue a single shell command.
Command line history (up arrow, etc.) and in-line editing capabilities
are available on some operating systems.
Command line history and in-line editing capabilities
are via routines in prompt-vms.for, tt_get_input.for, tt_input.for
and system calls LIB$SYS_TRNLOG('SYS$COMMAND',,SYSCOM),
LIB$SYS_TRNLOG('SYS$INPUT',,SYSINP).
Command line history and in-line editing capabilities
are via routines in prompt-unx.c and the gnu library readline.
...ASK Evolved descendant of ASKFOR (FREAD-with-Prompt):
New version includes Expression Evaluation via LOC_EVAL
and Indirect File processing (nesting up to 10 deep);
also list processing, "Comments and \Command lines (e.g., \CALC)
Deliver a one-line question stored in PROMPT (must not be empty!)
and get back (on the same line) a list of *** up to 20 ***
Fields of Answer(s), each Field specified as either a single variable
or an array; any Field may be in any sequence:
'D' (Real*8) 'R' (Real*4)
'I' (Integer*4) 'M' (Integer*2)
'S' (character Array) 'L' (Logical*4)
'C' (Complex*8) 'K' (Logical*2)
'A' (character String)
Thus (e.g.)
'3R' calls for an array of 3 Real*4 variables
'D' calls for a single Real*8 variable.
'80S' calls for a character array of 80 characters
[character*1 str(80)]
'80A' calls for a character string of 80 characters
[character str*(80)]
'S' and 'A' should have the opposite names, but for compataibility
with older versions of ask, which only had 'S', this is the way it is
done.
Note: The complex type is NOT implimented in PARSE.FOR!!!
Prompts are printed out with trailing blanks removed,
followed by a single space. If using ASK<N>D() rather than ASK<N>()
or ASK<N>S(), the prompt is followed by the default values of the
fields, in curly braces {}, followed by a space.
Arrays of numbers are placed in square brackets, e.g., [1,2,3].
Note: In response to ASK*(), do NOT include square brackets []
when entering values of arrays.
L<N> is the formating string (see Formating). For example, 'S20'
A<N> is the variable field (whose type is defined by L<N>),
which is going to get filled in.
CALL ASK0 (PROMPT)
CALL ASK1 (PROMPT, L1,A1)
...
CALL ASK20 (PROMPT, L1,A1, L2,A2, L3,A3, L4,A4,
> L5,A5, L6,A6, L7,A7, L8,A8, L9,A9, L10,A10,
> L11,A11, L12,A12, L13,A13, L14,A14, L15,A15,
> L16,A16, L17,A17, L18,A18, L19,A19, L20,A20)
These routines require the user to enter all the fields correctly,
comma separated, unless different deliminators have been defined by
\D(elim). Any unentered values default to zero for numbers and
empty strings for string variables.
CALL ASK0S (PROMPT, NCH_Q)
CALL ASK1S (PROMPT, L1,A1, NCH_Q)
...
CALL ASK20S (PROMPT, L1,A1, L2,A2, L3,A3, L4,A4,
> L5,A5, L6,A6, L7,A7, L8,A8, L9,A9, L10,A10,
> L11,A11, L12,A12, L13,A13, L14,A14, L15,A15,
> L16,A16, L17,A17, L18,A18, L19,A19, L20,A20, NCH_Q)
These routines require the user to enter all the fields correctly,
comma separated, unless different deliminators have been defined by
\D(elim). Any unentered values default to zero for numbers and
empty strings for string variables. NCH_Q returns the number of
characters entered by the user. It is only really useful for ASK1S
called with a string variable, where the length of the entered string
is shorter than the allowed space.
CALL ASK1D (PROMPT, L1,A1)
...
CALL ASK10D (PROMPT, L1,A1, L2,A2, L3,A3, L4,A4,
> L5,A5, L6,A6, L7,A7, L8,A8, L9,A9, L10,A10)
These routines require the user to enter all the fields correctly,
comma separated, unless different deliminators have been defined by
\D(elim). Any unentered values default to the original values of the
variables A1 through A<N>. In addition, the default values are
placed in a string "{A1, ..., A<N>}" which is appended on the end
of the prompt. Therefore, the user knows what the default values are
when they enter values.
These routines are limited to 10 fields, because of the
limitiations of TELL (which it uses) and by the practical consideration
that it is unreasonable to prompt the user for more than a handful
of values at a time. The prompt line quickly gets too long!
IF (ASK_IF (QUESTION)) THEN
Returns .TRUE. if user enters 'Y' or 'y'.
Returns .FALSE. if user enters 'N' or 'n'.
Returns .FALSE. if user gives a null length answer.
IF (ASK_IFD (QUESTION, LOGICAL_DEF)) THEN
Returns .TRUE. if user enters 'Y' or 'y' and
LOGICAL_DEF is updated to .TRUE..
Returns .FALSE. if user enters 'N' or 'n' and
LOGICAL_DEF is updated to .FALSE..
Returns with default value of LOGICAL_DEF if
user gives a null length answer.
WARNING!!! Make sure that LOGICAL_DEF is declared as a variable
and NOT as a parameter or a constant string!
...CALL SET_ASK_DELIMS (', !...') to define Delimiter
characters recognized by ASK (',' recommended!)
...CALL SET_ASK_ECHO (ECH) to turn Indirect-mode Echoing
on (ECH = .TRUE.) or off (ECH = .FALSE.)
...CALL SET_ASK_FILE (Filename) to redirect Input to Filename.
(same as "@Filename" in input stream;
can be nested up to 10 deep.)
...CALL SET_ASK_INDIR (IND, LUN) to turn Indirect processing via LUN
on (IND = .TRUE.) or off (IND = .FALSE.)
(in Local Indirect mode, IND = .FALSE.
closes current file and decrements pointer.)
...Tell is Format-Free Output to SYS$OUTPUT:
Deliver a one-line message stored in STORY, followed by up to
10 fields of variables.
ENTRY TELL0 (STORY)
ENTRY TELL1 (STORY, L1,A1)
....
ENTRY TELL10 (STORY, L1,A1, L2,A2, L3,A3, L4,A4,
> L5,A5, L6,A6, L7,A7, L8,A8, L9,A9, L10,A10)
Output places arrays in square brackets, e.g., [1,2,3].
CALL INIT_HELP('path', 'hlp_fil', 'level') to select the help file
which otherwise defaults to USERS or ASK.
Leave off the path and extention on the file name 'hlp_fil'.
If the path is a null string, the program defaults to
the system logical MSRHELP in VMS of Unix.
See HELP help topic.
ASK's subroutine TT_GET_INPUT.FOR (only for VMS)
uses the routine FIND_UNIT() to find a unit number
between 30 and 99 which is not currently used.
ASK uses this to assign unit numbers to 'indirect' (a.k.a. macro) files.
I don't think that we use the this portion of TT_GET_INPUT
(reading and writting a buffer list from/to a file.)
ASK also searched for itself, backwards and forwards
from MY_LUN_0=83. (?? is the maximum number of units allowed under
Linux systems, rather than 99 on VMS.)
The routines EVALLOAD(filename) and EVALSAVE(FILENAME)
in EVALTAB.FOR reads in or saves to the user's evalrc resource
file (FILENAME) containing defining variables for EVAL/CALC/ASK.
It briefly uses the first free unit number between 0 and 19 to
open and read or write to the file. These routines are not currently
called by ASK.
The default system unit numbers for the terminal are
6 and 7.
Therefore, if you are going to use fixed unit numbers in
your program, use numbers between 0 and 29, except for 6 and 7.
That way the unit number will be always free when you go to use it.
Numbers between 30 and perhaps 70 are pretty safe, assuming
that it is unlikely that you will have nesting of indirect files
of more than a handful.
If your typing string L<N> is mismatched with the FORTRAN
tyoe of the corresponding variable A<N>, i.e.
call ask1('Enter integer ', 'R', i)
the number will be nonsense, rather than being
conveniently converted.
If the user enters a real value when asked for an integer,
ASK rounds it to the nearest integer.
Note: an absent operator defaults to multiply, e.g.
b cos(x) = b*cos(x).
This can cause some odd looking expressions to be evaluated
in unexpected ways. For example 55.5.5 does not
give an error but instead returns 55.5*0.5 = 27.75
Expressions are combinations of ASK contants,
your program's variables, FORTRAN 77-like functions,
operators and parentheses (,).
Note: an absent operator defaults to multiply, e.g.
b cos(x) = b*cos(x).
This can cause some odd looking expressions to be evaluated
in unexpected ways. For example 55.5.5 does not
give an error but instead returns 55.5*0.5 = 27.75
Example:
\= ninety = (180/pi)*asin(1.0)
\= z = sqrt((abs(x))^2 + (abs(y))^2)
\= z (echoes back current value of z)
\= (180/pi)*asin(1.0) (echoes back value)
See also Assignment Functions Operators Constants \=
Assignment =
Example: \= twopi = 2.0*pi
The following FORTRAN 77-like functions are defined:
Trig functions:
sin cos tan
asin acos atan
sinh cosh tanh
Exponential functions:
exp log log10
Square Root:
sqrt
Round down and nearest integer:
aint anint
Absolute value: (useful for before you take a power!)
abs
Programmers note: These are defined in EVALFUN.FOR
The following FORTRAN 77-like operators are allowed:
Exponent **
Multiply *
Divide /
Add +
Subtract -
Logical ops == != > >= <= < & | !
FORTRAN 77 equivalent: .EQ. .NE. .GT. .GE. .LT. .LE. .AND. .OR. .NOT.
Either the FORTRAN 77 version or the math version maybe used.
Logical values .TRUE. .FALSE.
Pre-defined constants: e pi
User defined constants \= myconstan = [expression]
Allowed characters in constants name are a-z, 0-9, "_", "$".
Upper and lower case characters are treated equivalently.
(Not yet completed. Direct from CMLI.FOR comments.)
...ComMand Line Interpreter for general use:
...Using the ASK utility, request (using PROMPT), receive and interpret
a User Command Line beginning with an NCH-character Command
which must match one of the NCMD Commands CMDS(i) defined by the caller,
followed by up to 19 "fields" of arguments A1, etc., of types L1, etc.,
and return the command number JCMD and arguments to the calling program.
In case of erroneous input (e.g., an unrecognizable Command) the user
will be prompted for new input. For examples see the HELP library below.
...User input is normally converted to upper case, meaning of course
that any command appearing in the CMDS(i) list which contains lower case
characters can never be matched. This is a good way to indicated
as-yet unsupported commands. To turn off upper case conversion
and allow more flexibility/confusion, CALL CMLI_UPPER (.FALSE.)
..Abbreviations are normally accepted for all commands, meaning of course
that ambiguities are resolved in favour of the command appearing earliest
in the CMDS(i) list. To reject abbreviations, CALL CMLI_ABBREV (.FALSE.)
-- Jess Brewer (Jan. 1984)
-- Updated August 1987 to allow up to 19 "fields".
See HELP under top level HELP, or HELP help file,
for a description of help under CMLI.
Not written yet.
Not written yet.
CERN Minuit package.
See CERN minuit reference manual, (minuit.tex),
CERN Program Library Long Writeup D506.
See below for list of MINUIT Interactive commands, used by this
program.
List of MINUIT Interactive commands:
CLEar Reset all parameter names and values undefined
CONtour Make contour map of the user function
EXIT Exit from Interactive Minuit and MSRFIT.
END Exit from MINUIT and start another fit.
FIX Cause parameter(s) to remain constant
HESse Calculate the Hessian or error matrix.
IMPROVE Search for a new minimum around current minimum
MIGrad Minimize by the method of Migrad
MINImize MIGRAD + SIMPLEX method if Migrad fails
MINOs Exact (non-linear) parameter error analysis
MNContour Calculate one MINOS function contour
PARameter Define or redefine new parameters and values
QUIT Panic stop.
RELease Make previously FIXed parameters variable again
REStore Release last parameter fixed
SAVe Save current parameter values on a file
SCAn Scan the user function by varying parameters
SEEk Minimize by the method of Monte Carlo
SET Set various MINUIT constants or conditions
SHOw Show values of current constants or conditions
SIMplex Minimize by the method of Simplex
STOP Panic stop.
Simple DOPLOT library for plotting, using PGPLOT library.
TRIUMF GPLOT version written by Jess Brewer for use by msrfit,
DB, etc. Translated to the PGPLOT Library by Paul Kienzle.
Must be used with ASK library.
Synopsis
DOPLOT> LOG
Logarithmic X Scale? [no]
Logarithmic Y Scale? [no]
DOPLOT> LOG
Logarithmic X Scale? [no]
There are zero or negative X values. Truncate? yes
Truncating non-positive X values
Logarithmic Y Scale? [no]
There are zero or negative Y values. Truncate? [no]
Plotting negative y as log10(abs(y)) using left arrow
Plot using log-based-10 scale instead of linear.
If there are negative values, the program will ask you if you wish to
truncate these values. If yes, it will take the absolute value before
taking the log, and indicate this with a left arrow (for negative y's) or
a down arrow (for negative x's). If no, it will only plot positive values.
Synopsis
DOPLOT> INVSCALE
Inverse X Scale? y
There are zero or negative X values. Truncate?
Plotting negative x as -log10(abs(x)), using down arrow
Inverse Y Scale? n
This should plot -log10(abs(value)), the same as for LOGSCALE.
Broken.
Synopsis
DOPLOT> X_LIMITS [xmin], [xmax]
Set x axis limits. If either [xmin] or [xmax] (or both)
are missing or have the value zero, then it is set to auto scaling.
Synopsis
DOPLOT> Y_LIMITS [ymin], [ymax]
Set y axis limits. If either [ymin] or [ymax] (or both)
are missing or have the value zero, then it is set to auto scaling.
Synopsis
DOPLOT> BOX
Label Axes etc.? [no]
Either plots axes and data with [yes] or without [no] (the default)
title, and labels.
Synopsis
DOPLOT> tics [xspacing], [yspacing]
Determines the spacing of the major tics and numbers on the
two axes. A value of zero means that the program automatically
selects the spacings.
Synopsis
DOPLOT> AXES
Plot X-axis? [yes]
Plot Y-axis? [yes]
Plot x and or y origin axes, using a dashed line.
Synopsis
DOPLOT> WIDTH [r]
Plot width in inches. Ignored by x-windows.
Might not work at all.
Synopsis
DOPLOT> HEIGHT [r]
Plot height in inches. Ignored by x-windows.
Might not work at all.
Synopsis
DOPLOT> MARGINS [xleft], [ybottom]
Lower left corner of plot now at (X,Y) = 0, 0.
Margins size for graph. Ignored by x-windows.
Might not work at all.
Synopsis
DOPLOT> point [size]
Point size (") now 0.125
Sets the symbol size in inches for plots (assuming
letter sized paper).
Synopsis
DOPLOT>
DOPLOT> CHARSIZE [size]
Character size (") now 0.25
Sets the font size in inches for plots (assuming
letter sized paper).
Synopsis
DOPLOT> DEVICE
Selectes the PGPLOT output device (defaults to x windows),
for terminal output (Interactive devices). Will not work properly for
file devices. Use HARDCOPY instead for output to a file, including postscript.
See PGPLOT documentation for more detail.
Synopsis
DOPLOT> HARDCOPY
...
Format? (filename/devicetype) > junk.ps/vps
Outputs the current plot to a PGPLOT device.
Please only select a non-interactive file format such as postscript.
See PGPLOT documentation for more detail.
Synopsis
DOPLOT> TITLE
Present Title:
junk
Replacement? a new title
Change the title.
Note: The text will be truncated at the first defined deliminator
found. The defined deliminators is almost always a comma.
Synopsis
DOPLOT> LABELS
Present X Label:
x
Replacement? xx
Present Y Label:
y
Replacement? yy
Change the x and y axes labels. Carriage return preserves the
current title.
Note: The text will be truncated at the first defined deliminator
found. The defined deliminators is almost always a comma.
Synopsis
DOPLOT> CAPTION
Enter a line of Caption > [This is a caption]
Character size (") > [newcharsize]
Angle > [angle]
Position 1st character w/cursor & hit any key but CR: [cr]
Places caption anywhere you want on screen using cursor
(for VTXXX terminals?) or the mouse (for x windows).
Note: The text will be truncated at the first defined deliminator
found. The defined deliminators is almost always a comma.
See also TEXT
Synopsis
DOPLOT> TEXT
This seems to be like CAPTION, except it doesn't work.
Note: The text will be truncated at the first defined deliminator
found. The defined deliminators is almost always a comma.
See also CAPTION
Synopsis
DOPLOT> FONT [n]
Selects which font to use, for the whole page.
Standard san serif font is 1.
Roman font is 2.
Italic font is 3.
Script font is 4.
Synopsis
DOPLOT> DB_DUMP
DB file to contain the point > [junkdump.db]
Outputs the contents of the plot to a file,
using DB format, only labeled by x, y and symbol type.
Synopsis
DOPLOT> KEEP
Keeps the current plot in "memory". You can then leave
DOPLOT, re-enter with new data to plot and the new plot
will be added to the old one.
Synopsis
DOPLOT> ADD
Entering a Line? y
Add (X,Y) point (0,0 when done) > 0.2, 112
Add (X,Y) point (0,0 when done) > 12, 143
Add (X,Y) point (0,0 when done) > 0,0
DOPLOT> add
Entering a Line? n
Entering a Character? y
Add (X,Y,CH) point (0,0 when done) > 0.1, 100, a
Add (X,Y,CH) point (0,0 when done) > 0, 0
Enter points for a line or disconnected single
letters or characters. Characters are useful for labling
portions of a complex plot.
Synopsis
DOPLOT> TERSE
Plot all symbols as dots, etc.? y
For temporarily removing all symbols and error bars.
Synopsis
DOPLOT> REMEMBER
Store setup details in DOPLOT.INIT.
Crashes program.
See also RECALL
Synopsis
DOPLOT> RECALL
Restore setup details in DOPLOT.INIT
See also REMEMBER
Synopsis
DOPLOT> EDGR
Not implimented.
Not implimented. Intended for using publishers convention for
numbers, etc.
Synopsis
DOPLOT>
Like regular DOPLOT except without interactive loop
and do not clear display between this plot and the next
(meant to be used with call DOPLOT_MARGINS to
plot several frames in one window.
Does not work.
See also MARGINS
Synopsis
DOPLOT> QUIT
EXIT the program. (Use EXIT to leave DOPLOT level and return to
the level which called DOPLOT.)
See also EXIT
Synopsis
DOPLOT> EXIT
Leave DOPLOT level and return to the level which called DOPLOT.
See also QUIT
Note: The text will be truncated at the first defined deliminator
found. The defined deliminators is almost always a comma.
This affects TITLE, LABELS, CAPTION, TEXT.
On output devices which handle color,
curves are drawn cycling between 7 colors
(white/black, red, green, blue, cyan, purple, yellow and orange).
The first 7 point types have the same corresponding colors.
All other symbols are drawn in white/blank, so that the
symbol is the opposite color of the background.
Special characters may be embedded in the title, labels
and caption. See PGPLOT manual section 4.5.1 "Escape sequences."
Because ASK already uses backslash to start special commands,
DOPLOT uses the hat symbol "^" in place of the backslash.
The routine PGPTXT (and all the PGPLOT routines which call it,
e.g., PGTEXT, PGLAB) allows one to include escape sequences in the
text string to be plotted. These are character-sequences that
are not plotted, but are interpreted as instructions to change
font, draw superscripts or subscripts, draw non-ASCII characters
(e.g., Greek letters), etc. All escape sequences start with a backslash
or hat character (\ or ^) in PGPLOT and in DOPLOT, respectively.
The following escape sequences are defined (see next level of help)
(the letter following the \ or ^ may be either upper or lower case):
^u
start a superscript, or end a subscript
^d
start a subscript, or end a superscript
(note that ^u and ^d must always be used in pairs)
^fn
switch to Normal font (1)
^fr
switch to Roman font (2)
^fi
switch to Italic font (3)
^fs
switch to Script font (4)
^b
backspace (i.e., do not advance text pointer
after plotting the previous character)
^x
multiplication sign (x)
^.
centered dot (·)
^A
ångström symbol (Å)
^gx
greek letter corresponding to roman letter x, as indicated in Fig4.3
^mn
^mnn
graph marker number n or nn (1-31), as indicated in Figure 4.1
^(nnnn)
character number nnnn (1 to 4 decimal digits) from the
Hershey character set; the closing parenthesis may be omitted if
the next character is neither a digit nor ``)''. This makes a
number of special characters (e.g., mathematical, musical,
astronomical, and cartographical symbols) available.
See Appendix B for a list of available characters.
^u ^d
start/end a superscript or subscript
^fn ^fr ^fi ^fs
switch to Normal, Roman, Italic or Script font.
^b
backspace (i.e., do not advance)
^x
multiplication sign (x)
^.
centered dot (·)
^A
ångström symbol (Å)
^gx
greek letter corresponding to roman letter x, as indicated in Fig4.3
^mn ^mnn
graph marker number n or nn (1-31), as indicated in Figure 4.1
^(nnnn)
character number nnnn (1 to 4 decimal digits) from the
Hershey character set; the closing parenthesis may be omitted if
the next character is neither a digit nor ``)''.
DOPLOT> cap
Enter a line of Caption > ^(0637)=1800^A ^m12 ^fi x^u2^d ^x y^u2^d ^fn ^gl HI!
Character size (") >
Angle >
Position 1st character w/cursor & hit any key but CR:
Note: this example creates the greek character lambda
two different ways, with ^(0637) and ^gl.
When plotting (from DB, msrfit, etc.), a point type of
value between 0 and 7 produces colored "standard" symbols.
Point types between 8 and 31 produce
symbols with the same number as the PGPLOT
standard graph markers. PGPLOT standard graph markers with
negative numbers are not available (solid polygons),
and appear as dots instead.
Point types between 32 and 127 appear as ASCII characters.
Above that, Hershey symbols are used. Unprintable characters
only appear as dots. The appearance of symbols above 31
may depend on the font selected and/or the output device.
User beware.
Note: to plot point types above the number 9,
make sure that they are evaluated as an expression,
either by entering a variable name or using parentheses,
e.g. (11) not 11. Othersize the program will just use the first
digit.
Point type Shape Color PGPLOT graph marker number
-------------+-------------+------------+----------------------------
0 Square White/Blank 0
1 Circle Red 4
2 Triangle Green 7
3 Pointy square Blue 10
4 Diamond Cyan 11
5 Star Purple 12
6 X Yellow 5
7 * Orange 3
See appendix B or fig 4.1 of the PGPLOT documentation for
a table of the standard PGPLOT symbols.
Point type numbers entered between 32 and 127 that are interpreted as
ASCII representations of characters, to be used as the symbol.
Point type numbers entered with values between 127 and 2932
are interpreted as Hershey symbol numbers, to be used as the symbol.
For example, 637 draws a lambda. See appendix B of the
PGPLOT documentation for tables of the Hershey characters.
LOGSCALE X_LIMITS Y_LIMITS HARDCOPY EXIT QUIT
AXES TITLE LABELS CAPTION ADD KEEP
BOX POINTSIZ CHARSIZE DEVICE
TICS FONT DB_DUMP TERSE
Broken or unimplimented commands are:
WIDTH HEIGHT INVSCALE MARGINS
TEXT REMEMBER RECALL EDGR PUBLISH NEXT
Working commands are:
X_LIMITS Y_LIMITS BOX AXES LOGSCALE
POINTSIZ CHARSIZE EXIT DEVICE
TITLE LABELS TICS HARDCOPY CAPTION FONT
DB_DUMP KEEP ADD TERSE QUIT
This documentation is out of date. November 2000
A command-driven DataBase handling program with extensive PLOTting
capabilities. Can be used by itself for plotting simple functions
without need for recompiling or task building (thanks to LOC_EVAL)
or with ".DB" EDTable data files of a standard but VERY free format.
The prompt of DB is (obviously) DB>
Note that data can be input "by hand" using the commands of DB or
loaded from a ".DB" file via DB>@filename.DB Whichever way
the data comes in, it has the SAME FORMAT, including commands defining
data structures, etc. Thus there is NO distinction between "manual input"
and "stored-file input". This makes it especially easy to remember the
format of the files, once you have become familiar with DB.
DB intercepts Error Traps and CTRL-C Traps.
This command has no arguments; it activates a search of
subsequent input for at most 100 80-character lines of
"Abstract", the significance of which is up to the user.
At the moment, DB uses the Abstract only for detailed
identification of the contents of ".DB" files.
The input is terminated by a (COMPLETELY) blank line.
This command has no arguments; it activates a search of
subsequent input for at most 10 80-character "Comment"
lines, the significance of which is up to the user.
At the moment, DB uses the Comment only for detailed
identification of the contents of ".DB" files.
The input is terminated by a (COMPLETELY) blank line.
NOTE: NOT IMPLIMENTED for use with PGPLOT graphics library!
This command initiates entry of a succession of ordered
triplets (one triplet to a line, separated by commas)
terminated by a completely blank line, describing a 3D
space curve to be drawn by DOPL3D. Thus
DB>CURVE
>1,1,1
>2,4,1
>3,9,1
>4,16,1
>
will cause DOPL3D to draw a roughly parabolic line of
connected points (X=1,Y=1), (X=2,Y=4), (X=3,Y=9), (X=4,Y=16)
at constant Z=1.
This command MUST have arguments, namely the Names of the
Variables to be loaded as (X,dX+,dX-), (Y,dY+,dY-), ... etc.
on subsequent lines, terminated by a (COMPLETELY) blank line.
The best way to explain this format is by example:
DB>DATA T A B
> 5,1,1.5, 10,1,2, 55.1,18,, [Remark 1]
> 7.5,2,, 18.1,5.4,2.3, 127.5,22,, [Remark 2]
> 14,2,, 21.2,7,, 337.4,45,, [Remark 3]
would load the Variable array "T" with the numbers in the first column,
storing the Value, its Positive Error and its Negative Error, and
similarly for the Variable "A" in column 2 and "B" in column 3.
Any zero Negative Errors (e.g., where you see 14,2,, above) are
automatically set equal to the Positive Error for that entry.
Each Point (row) may be identified by a Remark after all the numbers.
This command deletes a column of data.
DB>DELELTE T
Exits the program.
NOTE: Needs updating!
This command has arguments which will be prompted for
if omitted. The most general form is
DB>FIT X Y
Here we are fitting the Independent Variable named "X"
and the Dependent Variable named "A" to a form which
may be given by an Expression (MINUIT fits).
You will be queried to find out which you want. After FITting you
may draw the data points and a line through them, if desired.
It is wise to store the parameters and theoretical
formula in a macro file.
Note: eventially the fitting program will use the
covariance mentrix when MAXHES or HESMAX is present.
Not implimented yet.
DB> fit b max
MINUIT Fit? y
Point type?
DB>
MINUIT RELEASE 93.11 INITIALIZED. DIMENSIONS 100/ 50 EPSMAC= 0.44E-15
TITLE (or @Filename) > Fit to gaussian
Parameter # LABEL VALUE ERR LLIM ULIM REMARK > 1 amp 775 1.5 0.001 1000.
Parameter # LABEL VALUE ERR LLIM ULIM REMARK > 2 b0 0.0095 2.8E-7 0.007 0.011
Parameter # LABEL VALUE ERR LLIM ULIM REMARK > 3 bwid 1.3E-4 3.3E-7 1.E-9 0.005
Parameter # LABEL VALUE ERR LLIM ULIM REMARK >
For curve # 1
Enter theoretical formula for MAX
in terms of Parameters (by name) and B
>max = amp*exp(-0.5*(b-b0)*(b-b0)/(bwid*bwid))
...
Want to PLOT? n
Enter i to Modify P(i) >
New P [, dP, Pmin, Pmax] > 780
Enter i to Modify P(i) >
New Theory?
Replot? y
Plot Diff between Theory & Data?
Default range [Min,Max,Npts] =0.0070023, 0.011975, 99
Enter range [Min,Max,Npts] of B
for plot:
DOPLOT>
Enter i to Modify P(i) >
...
MINUIT> migr
MINUIT> exit
Want to PLOT?
Finished Plotting? y
Write results to a MINUIT input file? y
Enter file name > gaus3.ixy
DB>
DB> FRACERR INVAR OUTVAR
Calculates the fractional error of the
data column invar and places the result in
in a new data column outvar.
One may Generate a new Data Variable (Column) from the
values of all the existing Variables (Columns) with this
command. Any LOC_EVALuatable expression referring to the
other Variables by their Names is allowed. DB does
the best it can (without calculating partial derivatives
analytically) to generate Errors for the new Variable
that include the Errors of the old Variables; but the
result is necessarily symmetrical (Positive Error =
Negative Error) and crude. User beware!
The muSR Maxium Entropy program MaxErr saves its output P(b)
in a DB file *.mdb, which has an extra DB command MaxHes (or HesMax),
which contains information about the hessian matrix, from which the
covariance matrix can be re-constructed. The covariance matrix
may be used in place of the independent errors, when fitting
(NOT IMPLIMENTED YET).
The formats for MaxHes and HesMax differ slightly.
It contains the entropy S(b) and grad grad chi^2 with respect to
the field b.
Use IMPORT to copy over the entropy and/or grad grad chi^2
to the DATA array, so you can plot.
The command allows the vectors which are read by by HESMAX and MAXHES
(referred to as ENTROPY and GGCHI2) to be copied over to a new column of
data. Then you can plot it, or manipulate it as you wish.
DB> IMPORT ENTROPY
DB> IMPORT GGCHI2
The muSR Maxium Entropy program MaxErr saves its output P(b)
in a DB file *.mdb, which has an extra DB command MaxHes (or HesMax),
which contains information about the hessian matrix, from which the
covariance matrix can be re-constructed. The covariance matrix
may be used in place of the independent errors, when fitting
(NOT IMPLIMENTED YET).
The formats for MaxHes and HesMax differ slightly.
It contains the entropy S(b) and grad grad chi^2 with respect to
the field b.
Use IMPORT to copy over the entropy and/or grad grad chi^2
to the DATA array, so you can plot.
This command can be used with or without arguments.
With no arguments, it activates a search of subsequent
input for at most nineteen Labels of 80 characters or less
describing the meanings of the corresponding variables
in the DATA array (which see). DB automatically
uses these Labels in any PLOTs of the data (which see).
The input is terminated by a (COMPLETELY) blank line.
With one of the existing DATA Variable Names as an argument,
this command can be used to modify an existing label
(namely, the one for that Variable). E.g.,
DB>LABEL T
>Temperature [K] gives the new Label "Temperature [K]" to
the existing Variable "T".
This command initiates entry of a succession of ordered pairs
(one pair to a line, separated by commas) terminated by a
completely blank line, describing a 2D curve to be drawn
by DOPLOT. Thus
DB>LINE
>1,1
>2,4
>3,9
>4,16
>
will cause DOPLOT to draw a roughly parabolic line of
connected points (1,1), (2,4), (3,9), (4,16).
One may Modify any Column of the Data array. For example,
DB>MODIFY FREQ
...(remarks by DB)...
>FREQ = FREQ/(2*PI)
will convert frequencies in radians/sec into Hz.
One may also take square roots, logs, invert, etc....
Restore DB database contents from a binary file (for whose name
you will be asked) previously generated by the SAVE command
(which see).
One form of Modification which is special enough to have
its own separate command is Normalization, the meaning
of which should be obvious.
Not implimented.
This command has arguments which will be prompted for if omitted.
The most general form is
DB>PLOT T A [B] [IF Expression(s)]
Point type? [expression2]
Here we are plotting Data Points with the Variable named "T"
on the X axis, "A" on the Y axis, and [if specified] "B" on the
Z axis. Note that the choice of 2-D or 3-D plot is determined
by context alone. All error bars are drawn automatically.
Note that no distinction is made between "dependent" and
"independent" variables in the Data Points.
NOTE: 3D plots are NOT IMPLIMENTED for use with
PGPLOT graphics library!
The "IF Expression(s)" option allows one to display only
that subset of the Points for which up to 4 "Expressions"
are separately and individually satisfied; an Expression
may contain an "==" sign, in which case the left and right
sides must be equal to satisfy the condition, or not, in
which case the expression must be GREATER THAN ZERO following
evaluation by LOC_EVAL. Each "Expression" can refer to
the current value (for this Point) of any of the Variables
by Variable Name, but can be no more than 32 characters long
and MUST NOT CONTAIN ANY EMBEDDED BLANKS! (Blanks are used
as delimiters between Expressions.)
See the ASK help, for more information about Expressions,
Functions, and Operators.
Plotting all the points, but with different symbols,
is also possible using the choise of point type.
See also PointType
If a number is entered, then a symbol corresponding to the number
is plotted. If a variable or an expression is entered, the point type
(a.k.a. symbol) is then calculated for each point.
See DOPLOT help for documentation on the symbols (and color) available.
Point type? (carriage return)
Defaults to type 0, squares.
Point type? 2
Circles
Point type? 637
Hershey symbol lambda.
Point type? (1*(t.lt.30) + 2*(t.ge.30))
Circles if t < 30 and triangles if t >= 30
(Note: This can be done another way using PLOT [x] [y] IF [expression].)
DB>PLOT T A will plot A(T) for all available Points.
DB>PLOT A B IF T==15 will plot B(A) for all Points having T=15.
DB>PLOT A B IF 10-T will plot B(A) for all Points having T<10.
DB>PLOT T A B IF 20-T T-10 will plot (T,A,B) Points in 3-D
for all Points having 10<T<20.
DB>PLOT T A IF 20-T T-10 B==1 will plot (T,A) Points in
2-D for all Points having
10<T<20 and B=1.
The current contents stored by the program (Title, Labels,
Comment, Abstract and Data) can be written out to a new
file in a reasonably aesthetic format for line-printer style printer.
Exits the program.
Variables, once entered, may be RENAMEd for aesthetic or
mnemonic reasons. E.g.,
DB>RENAME T TEMP
renames the variable "T" to "TEMP".
This command causes the current contents of the DB database
to be saved in a binary file (for whose name you will be asked).
The results can be restored later by the LOAD command (which see).
The only advantage over WRITE (which see) is that it is slightly
more compact for databases containing more numbers than text.
The disadvantage is that you can't alter the result with any
normal text editor. (I suppose this might appeal to paranoids.)
One often forgets just what Data etc. have been loaded.
This command allows one to recall without reloading or
plotting unnecessarily. One can SHOW the following:
TITLE ABSTRACT COMMENTS LABELS DATA
Of these, only DATA needs further explanation.
For practical and aesthetic reasons one may only
SHOW one Column of Data at a time; if the command
line does not say which, e.g.,
DB>SHOW DATA T
then you will be prompted to tell which Variable (Column)
you want to see.
Not implimented.
The current contents stored by the program (Title, Labels,
Comment, Abstract and Data) can be written out to a new
spreadsheet-ready file (suggest ".SPR") in a reasonably aesthetic format.
The title is included, and the variable's names.
Columns labled "ep" and "em" indicate the high and low errors, for
each variable. Unfortunately, only three columns fit across,
so the contents of the data are written in batches of three.
This command has arguments, the first of which will be
prompted for if omitted. The most general form is
DB>STAT X [N] [Xmin] [Xmax]
which gives the UNWEIGHTED Min, Max, Sum, Avg and StdDev
of variable "X" and asks if you want a Histogram of the
frequency spectrum from Xmin to Xmax broken into N bins.
If you don't want a plot, the optional arguments are
unnecessary and will be ignored; if you omit them but
ask for a plot anyway, DB will use my judgement in
choosing aesthetic binning.
BUG report: STATS crashes DB if you try to bin the results.
This command allows one to load theoretical curves to be plotted,
either superimposed on the data or independently. I.e., if
any Data has already been loaded for plotting (see PLOT)
but has not yet been plotted (see blank_line), the Theory curve
will go onto the same plot; if the plot buffer is empty, the
Theory curve will be plotted by itself (if no Data is loaded
after the Theory and before plotting).
For Theory curves, the variable names are the conventional names
of the coordinate axes, namely "X", "Y" and "Z". One must first
specify which is the independent and which the dependent variable.
The choices are
Y(X) Z(X) X(Y) Z(Y) X(Z) Y(Z)
Note that if either variable is "Z" then you imply a 3-D plot. Then
you must specify TWO algorithms, one for each dependent variable as a
function of the independent variable. This will define a SPACE CURVE
in three dimensions. This is loads of fun but hard to visualize
satisfactorily.
NOTE: 3D plots are NOT IMPLIMENTED for use with
PGPLOT graphics library!
You will be prompted to enter an algorithm for (e.g.) Y(X);
this character string must be interpreted by LOC_EVAL
(as in $CALC) which will have the current value of the
independent variable (in this example, "X") defined when it
tries to evaluate the answer for (in this case) "Y". You may
use any global constants (e.g., "PI") that you have assigned,
but you are restricted to the function names that LOC_EVAL will
accept. We hope this repertoire will grow with time. For example,
> Y = EXP(-SQRT(X))*COS(2*PI*X) should be OK.
If there is Data to be plotted on the same graph, the Data Labels
and Title will override the Theory; if not, then the expression
entered will also be used as a Title for the plot.
This command has no arguments; it merely signals that the
following input line contains a Title of at most 80 characters
identifying the contents of the ".DB" file. This Title
will automatically be displayed on any plots generated from
the associated data.
Not implimented.
The current contents stored by the program (Title, Labels,
Comment, Abstract and Data) can be written out to a new
".DB" file in a reasonably aesthetic format for long-term
storage. This may or may not be the best way to create
such ".DB" files in the first place.
This command deletes any Data arrays presently loaded.
Both the commands and the variable names can be abbreviated
to as little as a single letter. This may sometimes lead to
ambiguities, about which DB will NOT complain; instead, it
will just take the FIRST on its list (of commands or variables)
-- which may not be the one you wanted! So it is advisable
to use long enough abbreviations (2-3 characters are often
enough) to resolve such ambiguities.
A blank line (COMPLETELY blank) is used to terminate
an ABSTRACT, a COMMENT, a LABELS list or a DATA list.
When you plot Data via the PLOT command or a Theory curve
via the THEORY command, the results are not plotted
immediately; you may wish to add more Points, curves,
etc. The actual plotting (with DOPLOT and DOPLOT_3D)
is done when you enter a blank line to the DB> prompt.
Anywhere that DB wants a NUMBER as input, you may substitute
an EXPRESSION, including named variables and/or any of the
functions defined in LOC_EVAL. This is because all DB I/O
goes through the ASK subroutine, about which you can get
more information by the command
DB>\h
anytime DB is waiting for your instructions.
TITLE ABSTRACT COMMENTS LABELS ZERO
DATA PLOT QUIT EXIT QUIT
MAXHES HESMAX MODIFY GENERATE DELETE
SHOW LINE CURVE RENAME STATS
SPREAD
FIT THEORY LINE CURVE
IMPORT
SAVE LOAD WRITE PRINT
SAVE LOAD
STATs crashes DB if you try to bin the results.
CURVE SORT PACK WEED
Variable Names can be no more than 8 characters long
and must be acceptable as variable names in LOC_EVAL
(as in $CALC).
There can be (at the moment) no more than 19 Variables (columns).
The product of the number of Variables (columns) with the number
of Points (rows) cannot exceed 9000 without recompiling DB.
../doc/db.tex
created from help file
../help/db.hlp
This document was generated using the
LaTeX2HTML translator Version 99.2beta6 (1.42)
Copyright © 1993, 1994, 1995, 1996,
Nikos Drakos,
Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999,
Ross Moore,
Mathematics Department, Macquarie University, Sydney.
The command line arguments were:
latex2html -split 0 -show_section_numbers db.tex
The translation was initiated by Dr TM Riseman on 2001-01-12
Dr TM Riseman
2001-01-12
CALC
ExclamationMark