HMINI Common Histogramming Library
T. Osborne, J.O. Petersen and D. Samyn, October 1989. Lynx/OS version by C.N.P.Gee.
This is a user's guide and a reference manual for the hmini histogram library.
Routine Calling Sequences
HC1GST HC1LIN HC1LOG HC1PLO HC1PRI HC1RES
HC2DOT HC2LEV HC2PLO
HC2PRI HC2RES HCCCUR
HCCCNT HCCDEL HCCERR
HCCFRA HCCGAR HCCGD3
HCCINI HCCLMS HCCLPL
HCCLPR HCCMAX HCCMIN
HCCMXC HCCPAG HCCRST
HCCSPA HCIDAL HCSIZE
HCTYPE HI1ADD HI1AFI
HI1BOO HI1DIR HI1FIL
HI1GIN HI1PUT HI1SPL
HI1SPR HI2ADD HI2AFI
HI2BOO HI2DIR HI2FIL
HI2PUT HI2SPL HI2SPR
HICAGE HICAPU HR1ADD
HR1AFI HR1BOO HR1DIR
HR1FIL HR1PUT HR1SPL
HR1SPR HR2ADD HR2AFI
HR2BOO HR2DIR HR2FIL
HR2GIN HR2PUT HR2SPL
HR2SPR HRCAGE HRCAPU
HMINI is a general histogram package providing histogramming facilities typically
required in the online computing environment of physics experiments at CERN. The package
is written in portable FORTRAN and is largely computer independent (except for a few
routines concerned with I/O and basic bit manipulations).
The library has been implemented on the minicomputers and micros supported by the OC
group i.e. VAX, NORD and MC68000.
For graphics operations, HMINI relies on the standard CERN graphics package miniGD3
HMINI provides facilities for
The following sections will explain and discuss these features in more detail. Each
section is an overview of one of the following chapters.
Two areas of memory are associated with each histogram : the directory area
describes the histogram parameters (title, bin limits etc.) while the data area is
used to store the bin contents. The histogram directories and data areas are allocated on two
labelled common blocks, HDIR and HDAT : COMMON / HDIR / IDIRBU (length) COMMON / HDAT /
IDATBU (length)
The first histogramming call in the user's program must be an initialisation
call (HCCINI) in order to specify the lengths of HDIR and HDAT. A detailed description of
the histogram buffer organisation is given in chapter
After the HMINI package has been initialised histograms may be booked. It is
possible to define one and two dimensional histograms of type INTEGER and REAL; the two
types refer to histograms in which the values to be histogrammed are of type integer or
real respectively.
A histogram is uniquely defined by an identifier (ID) ; the histogram identifier
is a user defined integer # 0 which is used in all further calls referring to the same
histogram. In some calls, ID=0 means that the call refers to all defined histograms.
The maximum bin contents (the bin capacity) may be specified by the user through the
parameter IMXCNT. The default value of IMXCNT is 0 which means that one computer word is
used for each histogram bin. If the contents of bin overflows, additional space is
allocated dynamically in the data buffer. If IMXCNT=0, the maximum bin contents on a 16
bit computer is (2**321).
In order to reduce memory space, other values of IMXCNT can be chosen. The number of
bits allocated to a bin is the smallest integer, NBB, for which 2**NBB > IMXCNT. In
addition a bin cannot cross a computer word boundary.
Thus, on a 16 bit computer the possible values of NBB are between 1 and 16 but 9 <=
NBB le 15 will not give any reduction in histogram space. The most 'reasonable' values,
except the default NBB=16, are NBB=4 and 8 corresponding to 8 le IMXCNT le 15 and 128 le
IMXCNT le 255 respectively. On a 32bit computer 16 bits per bin can be allocated by
defining 32768 le IMXCNT le 65535 e.g. IMXCNT = 2**161. In general, NBB bits per bin can
be allocated by specifying IMXCNT = 2**NBB1.
If a 'reduced' bin overflows, a full computer word is used for the overflow counts. If
for example a byte per bin is specified by IMXCNT, maximum bin contents are
(2**8)*(2**16)1 on a 16bit computer.
Booked histograms may be deleted (HCCDEL); the
space freed by this call may be recuperated on user request by garbage collection (HCCGAR).
In HMINI, bins are defined by bin value and not by bin number. For a one
dimensional histogram any value XVAL along the Xaxis defines uniquely a bin (and a bin
number). Similarly in a two dimensional histogram a set of values (XVAL, YVAL) define
uniquely a bin. In previous histogramming packages (ZHIST, RSXLIB) bins were referred to
by bin number.
If the bin value lies outside the range of values specified at booking time for the
histogram the bin is defined as an underflow or overflow bin. For 1dimensional histograms
there is one underflow and one overfiow bin. For 2dimensional histograms there exists a
set of 8 underflow/overflow bins for all combinations of underflow and overflow of X and Y
values see section 5.1.2 for definitions of these.
For the time critical filling calls an additional parameter NHIST is introduced in
order to reduce the execution time. The first time a filling routine is called, the
directory pointer for the histogram defined by ID is returned in NHIST. Following calls to
the filling routines then use NHIST for direct fast access to the directory thereby
avoiding the sequential scanning of histogram directories to find the directory
corresponding to histogram ID.
The following rules apply to the use of the NHIST parameter
 NHIST should be set to zero before the first filling call
 NHIST is a histogram dependent variable : the user must define one NHIST variable per
histogram
 NHIST variables should never be changed by the user
Bin contents are in HMINI internally represented as bit strings in unsigned integer
format with a maximum length of two computer words. First this implies that HMINI does not
support weighted bin contents or negative bin contents. Secondly, since bin contents may
exceed the maximum possible integer value (2**321 versus 2**151 on a 16 bit computer), real
parameters are used to represent bin content variables in subroutine calls (e.g.
PUT/GET/ADD).
Booked histograms can be filled in two ways. The simplest is to enter a single value in
a histogram (single fill) but the possibility also exists to enter an array of
values in one subroutine call (array fill).
Other subroutine calls are available to modify the bin contents of a histogram. The PUT
calls are used to replace bin contents individually (single put) or 'globally' (array put)
in other words to store an array in a histogram. In a similar way values may be ADDED to
the bin contents  bin by bin (single add) or 'globally' (array add). This allows
histograms to be added (or subtracted) : the bin contents of one histogram can be
extracted (array get, see below) and added (array put) to another histogram.
Histograms may be displayed in print or plot format with a variety of options; for
plotting, HMINI uses the standard CERN graphics package miniGD3 which supports TEKTRONIX
devices (T4006, T4010, T4012, T4014, T4027). For HMINI running on MC68000 other options
are available, see the VALETplus User's Guide for details.
On the output terminal (VDU, Tektronix, line printer) each histogram is identified by
the title and identifier as defined at booking.
By default, histograms are printed or plotted with maximum output scaling i.e. the
scale for bin contents spans the interval from zero to max. bin contents. This scaling may
be redefined by user specified lower and upper limits (HCCMIN, HCCMAX).
For onedimensional histograms it is possible to choose a logarithmic scale (HC1LOG,
HC1LIN).
Histograms can be output in print format on an alphanumeric terminal (VDU) or a line
printer. One dimensional histograms are by default printed with the bin contents scale
horizontally i.e. across the paper with the scale adjusted to the paper wi The bin value
axis (xaxis) is printed vertically i.e. along the paper with one bin per line (full
resolution). Two dimensional histograms are by default printed so as to fit onto one page
and bin contents are displayed using 10 levels i.e. with a resolution of 1/10 using the
symbols .,+,2,3,4,5,6,7,8,9. These defaults can be changed by the user (HCCPAG, HC2LEV).
Histograms may be displayed in plot format on Tektronix terminals or in graphics
windows on personal computers. The default terminal is T4012 with small character size but
these parameters as well as the logical unit number can be redefined by the user (HCCGD3,
HCCLPL). The number of histograms on the screen, by default one, may be selected by
calling the routine HCCFRA. The plot resolution can be changed by rebinning (HC*RES) and
in 2 dimensional histograms, where dots are used to represent bin contents, the max. # of
dots/bin can be defined (HC2DOT).
After a plot the screen cursor is left in an 'undefined' state. A call to HCCCUR resets
the cursor position to the lower left hand corner of the screen, which allows some text to
be output together with the plot. Any other cursor manipulation or more generally any
graphics operation must be done by direct calls to the miniGD3 routines.
In addition to routines for printing and plotting full histograms, there are
calls which allow user selected parts of a histogram to be displayed (zooming).
The print and plot formats are described in detail in the introduction to chapter
These routines provide user access to either histogram directories or histogram data
(bin contents).
The GET function calls are the inverse of the PUT subroutine calls described above; as
for those, single and array GETs are available. Note that bin contents returned by the GET
routines are floating point values which allows overflow bin contents to be returned
correctly.
On graphics devices with input facilities bin values and contents may be retrieved by
positioning the crosshair cursor at the appropriate bin.
Finally, real function calls are available to get integrated, maximum and minimum bin
contents of any histogram.
Error messages are reported on a logical unit defined by the user (HCCLMS). If the
logical unit is equal to zero, error output is suppressed, but the last error and the
routine in which it occurred is always available to the user via a call to HCCERR.
The histogramming requirements for online minicomputer applications can not be met with
a subset of HBOOK calls. The following technical requirements lead to differences in
external specifications:
 HMINI separates histogram directory and data space in two common blocks in order to
allow mapping of the histogram data space.
 HMINI minimises execution time for integer filling. This means separate calls for
integer and floating point filling, integer bin contents only and no support for weighted
filling.
 HMINI separates calls to one and two dimensional histograms in order to get load time
modularity.
 HMINI supports graphic input
 Garbage collection is user controllable so that it can be done outside time critical
periods.
 Error conditions are optionally available to user programs and need not always be
printed.
With these differences in mind HMINI has been designed to be as close as possible to
HBOOK, without introducing unnecessary confusion.
This has been achieved through the following guidelines:
 All HMINI names are different from HBOOK names
 HMINI naming conventions are consistent and follow a set of rules similar to the ESONE
CAMAC calls.
 In all HMINI calls for which an equivalent HBOOK call exists the parameter passing is
identical.
There are two types of calls. The INTEGER calls which refer to histograms where bin
limits and values to be histogrammed are integer values and REAL calls which refer to
histograms where bin limits and values to be histogrammed are floating point values.
Subroutine name conventions:
 INTEGER calls : 
HI**** 
 REAL calls : 
HR**** 
 common to INTEGER and REAL : 
HC**** 
 1dimension calls : 
H*1*** 
 2dimension calls : 
H*2*** 
 common to 1 and 2dimension : 
H*C*** 
 common to real/integer and 1/2 dimension : 
HCC*** 
CALL HCCINI(NDIRLG, NDATLG)
Action Initialise the HDIR and HDAT buffer (in COMMON).
Parameters
 NDIRLG
 integer  # words for HDIR space
 NDATLG
 integer  # words for HDAT space
Remarks
 For space requirements refer to chapter 9 for a complete description or sections 3.1,
3.2 for a definition of space required for a histogram
CALL HCCSPA(RNW, RND)
Action Unused space in HDIR and HDAT buffers is returned
Parameters
 RNW
 real  # words left in HDIR buffer
 RND
 real  # words left in HDAT buffer
CALL HI1BOO(ID, TIT, INBINS, ILOW, IUP, IMXCNT)
Action Book a 1dimensional histogram
Parameters
 ID
 integer  histogram identifier
 TIT
 array  histogram title
 INBINS
 integer  number of bins
 ILOW
 integer  lower value of first bin
 IUP
 integer  upper value of last bin
 IMXCNT
 integer  maximum single bin contents
Special values
IMXCNT = 0  bits/bin = computer word size
Remarks
CALL HI2BOO(ID, TIT, IXBINS, IXLOW, IXUP, IYBINS, IYLOW, IYUP, IMXCNT)
Action Book a 2dimensional histogram
Parameters
 ID
 integer  histogram identifier
 TIT
 array  histogram title
 IXBINS
 integer  number of X bins
 IXLOW
 integer  lower value of first X bin
 IXUP
 integer  upper value of last X bin
 IYBINS
 integer  number of Y bins
 IYLOW
 integer  lower value of first Y bin
 IYUP
 integer  upper value of last Y bin
 IMXCNT
 integer  maximum single bin contents
Special values
IMXCNT = 0  bits/bin = computer word size
Remarks
 the identifier must be unique for each histogram.
 the title is an hollerith string terminated by a $ character.
 if IMXCNT=0 and bins don't overflow the space required is (in words):
 16 + title length in common block HDIR
 # bins + 8 in common block HDAT
 if the X bin width, defined as (IXUP  IXLOW)/IXBINS, is not an integer, the upper value
of last bin will be redefined internally. IXUP is NOT modified. Similarly the upper Y bin
value will be recomputed if the calculated Y bin width is not an integer.
 see section 1.1.2 for a description of the parameter IMXCNT
CALL HR1BOO(ID, TIT, INBINS, RLOW, RUP, IMXCNT)
Action Book a 1dimensional histogram
Parameters
 ID
 integer  histogram identifier
 TIT
 vector  histogram title
 INBINS
 integer  number of bins
 RLOW
 real  lower value of first bin
 RUP
 real  upper value of last bin
 IMXCNT
 integer  maximum single bin contents
Special values
IMXCNT = 0  bits/bin = computer word size
Remarks
 the identifier must be unique for each histogram.
 the title is an hollerith string terminated by a $ character.
 if IMXCNT=0 and bins don't overflow the space required is (in words): 15 + title length
in common block HDIR # bins + 2 in common block HDAT
 see section 1.1.2 for a description of the parameter IMXCNT
CALL HR2BOO(ID, TIT, IXBINS, RXLOW, RXUP, IYBINS, RYLOW, RYUP, IMXCNT)
Action Book a 2dimensional histogram
Parameters
 ID
 integer  histogram identifier
 TIT
 vector  histogram title
 IXBINS
 integer  number of X bins
 RXLOW
 real  lower value of first X bin
 RXUP
 real  upper value of last X bin
 IYBINS
 integer  number of Y bins
 RYLOW
 real  lower value of first Y bin
 RYUP
 real  upper value of last Y bin
 IMXCNT
 integer  maximum single bin contents
Special values
IMXCNT = 0  bits/bin = computer word size
Remarks
 the identifier must be unique for each histogram.
 the title is an hollerith string terminated by a $ character.
 if IMXCNT=0 and bins don't overflow the space required is (in words):
 22 + title length in common block HDIR
 # bins + 8 in common block HDAT
 see section 1.1.2 for a description of the parameter IMXCNT
CALL HCCDEL(ID)
Action Delete histogram. The space allocated to the histogram is not freed.
Parameters
 ID
 integer  histogram identifier (ID=0 means all)
CALL HCCGAR(IDUM)
Action Recover space allocated to deleted histograms.
Parameters
 IDUM
 integer  dummy parameter
Remarks
 Histogram pointers NHIST must be reset to zero the user after call to HCCGAR
CALL HI1FIL(ID, NHIST, IVAL)
Action Fill a 1dimensional histogram. The contents of the bin defined by IVAL,
is incremented by one.
Parameters
 ID
 integer  histogram identifier
 NHIST
 integer  histogram pointer
 IVAL
 integer  value to be histogrammed
Special values
NHIST must be equal to zero the first time the filling routine is called.
Remarks
 the variable NHIST must not be changed by the program
 NHIST is histogram dependent : the user must define one NHIST variable per histogram
 the bin "defined by IVAL" is bin number NX where
 ILOW+(NX1)*IBW<=IVALIBW is the bin width which is derived from the booking parameters IBW =
(IUPILOW)/INBINS. If IVAL = IUP, the underflow or overflow bins resp. are incremented
CALL HI2FIL(ID, NHIST, IXVAL, IYVAL)
Action Fill a 2dimensional histogram. The contents of the bin, defined by
(IXVAL, IYVAL), is incremented by one.
Parameters
 ID
 integer  histogram identifier
 NHIST
 integer  histogram pointer
 IXVAL
 integer  X value to be histogrammed
 IYVAL
 integer  Y value to be histogrammed
Special values
NHIST must be equal to zero the first time the filling routine is called.
Remarks
 the bin "defined by (IXVAL, IYVAL)" is bin number (NX, NY) where
 IXLOW+(NX1)*IXBW le IXVAL IYLOW+(NY1)*IYBW le IYVAL IXBW, IYBW are bin widths in (x,
y) which are derived from the booking parameters: IXBW=(IXUPIXLOW)/IXBINS,
IYBW=(IYUPIYLOW)/IYBINS. If IXVAL ge IXUP or IYVAL geIYUP the appropriate underflow,
overflow bins are incremented
CALL HI1AFI(ID, NHIST, IARRV, INSIZ)
Action fill a 1dimensional histogram.The contents of the bins, defined by the
values in IARRV, are incremented by one.
Parameters
 ID
 integer  histogram identifier
 NHIST
 integer  histogram pointer
 IARRV
 integer  1dimensional array of bin values to be histogrammed
 INSIZ
 integer  no. of bin values
Special values: NHIST must be equal to zero the first time the filling routine is
called.
Remarks
 the variable NHIST must not be changed by the program
 NHIST is histogram dependent : the user must define one NHIST variable per histogram
 for the rules governing the filling, see HI1FIL
CALL HI2AFI(ID, NHIST, IARRV, INSIZ)
Action Fill a 2dimensional histogram.The contents of the bins, defined by the
values in IARRV, are incremented by one.
Parameters
 ID
 integer  histogram identifier
 NHIST
 integer  histogram pointer
 IARRV
 integer  2dimensional array of bin values, dimension (2, INSIZ)
 INSIZ
 integer  no. of bin values
Special values
NHIST must be equal to zero the first time the filling routine is called.
Remarks
 the X bin value must be stored in IARRV(1, i) and the Y bin value in IARRV(2, i).
 the variable NHIST must not be changed by the program
 NHIST is histogram dependent : the user must define one NHIST variable per histogram
 for the rules governing the filling, see HI2FIL
CALL HI1PUT(ID, IVAL, RCON)
Action Replace in a 1dimensional histogram. The contents of the bin, defined by
IVAL, is replaced by a new contents RCON
Parameters
 ID
 integer  histogram identifier
 IVAL
 integer  bin value
 RCON
 real  new bin contents
Remarks
 Any fractional part of RCON is ignored
 if RCON is negative, an error message is given and results will be unpredictable
 if IVAL is outside bin limits for histogram ID, the underflow or overflow bins will be
replaced
CALL HI2PUT(ID, IXVAL, IYVAL, RCON)
Action Replace in a 2dimensional histogram. The contents of the bin, defined by
a (IXVAL, YVAL), is replaced by a new contents RCON
Parameters
 ID
 integer  histogram identifier
 IXVAL
 integer  X bin value
 IYVAL
 integer  Y bin value
 RCON
 real  new bin contents
Remarks
 Any fractional part of RCON is ignored
 if RCON is negative, an error message is given and results will be unpredictable
 if (IXVAL, IYVAL) are outside bin limits for histogram ID, the underflow or overflow
bins will be replaced
CALL HICAPU(ID, RARRC)
Action Replace in a 1dimensional or 2dimensional histogram: all the bins get
their contents replaced sequentially by new contents contained in array RARR
Parameters
 ID
 integer  histogram identifier
 RARRC
 real array  new bin contents
 one dimensional histograms: RARRC(INBINS)
 two dimensional histograms: RARRC(IXBINS, IYBINS)
Remarks
 Any fractional parts of array elements are ignored
 the elements of RARRC should not be negative. For each element <0 an error message is produced and results will be unpredictable.
 underflow and overflow
bins are not replaced.
CALL HI1ADD(ID, IVAL, RCON)
Action Add in a 1dimensional histogram. The contents of the bin, defined by
(IXVAL, IYVAL), is incremented by a value RCON
Parameters
 ID
 integer  histogram identifier
 IVAL
 integer  bin value
 RCON
 real  value to be added to bin contents
Remarks
 RCON can be positive or negative but resulting content must not be negative. If they
are, an error message will be issued and results will be unpredictable.
 Any fractional part of RCON will be ignored
 IVAL is outside bin limits of histogram ID, the underflow or overflow bins will be
updated.
CALL HI2ADD(ID, IXVAL, IYVAL, RCON)
Action Add in a 2dimensional histogram. The contents of the bin, defined by
(IXVAL, IYVAL), is incremented by a value RCON
Parameters
 ID
 integer  histogram identifier
 IXVAL
 integer  X bin value
 IYVAL
 integer  Y bin value
 RCON
 real  value to be added to bin contents
Remarks
 RCON can be positive or negative but resulting contents must not be negative. If they
are, an error message will be issued and results will be unpredictable.
 Any fractional part of RCON will be ignored
 if (IXVAL, IYVAL) are outside bin limits of histogram ID, the underflow or overflow bins
will be updated.
CALL HR1FIL(ID, NHIST, RVAL)
Action Fill a 1dimensional histogram. The contents of the bin, defined by RVAL,
is incremented by one.
Parameters
 ID
 integer  histogram identifier
 NHIST
 integer  histogram pointer
 RVAL
 real  value to be histogrammed
Special Values
NHIST must be equal to zero the first time the filling routine is called.
Remarks
 the variable NHIST must not be changed by the program
 NHIST is histogram dependent : the user must define one NHIST variable per histogram
 the bin "defined by RVAL" is bin number NX where
 RLOW+(NX1)*BWleRVALBW is the bin width which is derived from the booking parameters :
BW = (RUPRLOW)/INBINS. If RVALge RUP, the underflow or overflow bins resp. are
incremented
CALL HR2FIL(ID, NHIST, RXVAL, RYVAL)
Action Fill a 2dimensional histogram. The contents of the bin, defined by
(RXVAL, RYVAL), is incremented by one.
Parameters
 ID
 integer  histogram identifier
 NHIST
 integer  histogram pointer
 RXVA
 real  X value to be histogrammed
 RYVAL
 real  Y value to be histogrammed
Special values
NHIST must be equal to zero the first time the filling routine is called. Remarks
 the bin "defined by (RXVAL, RYVAL)" is bin number (NX, NY) where
RXLOW+(NX1)*RXBW le RXVAL le RYVAL ge RXUP or RYVAL ge RYUP the appropriate underflow,
overflow bins are incremented
CALL HR1AFI(ID, NHIST, RARRV, INSIZ)
Action Fill a 1dimensional histogram.The contents of the bins, defined by the
values in RARRV, are incremented by one.
Parameters
 ID
 integer  histogram identifier
 NHIST
 integer  histogram pointer
 RARRV
 real  1dimensional array of bin values to be histogrammed
 INSIZ
 integer  no. of bin values
Special values
NHIST must be equal to zero the first time the filling routine is called.
Remarks
 the variable NHIST must not be changed by the program
 NHIST is histogram dependent : the user must define one NHIST variable per histogram
 for the rules governing the filling, see HI1FIL
CALL HR2AFI(ID, NHIST, RARRV, INSIZ)
Action Fill a 2dimensional histogram.The contents of the bins, defined by the
values in RARRV, are incremented by one.
Parameters
 ID
 integer  histogram identifier
 NHIST
 integer  histogram pointer
 RARRV
 real  2dimensional array of bin values, dimension (2, INSIZ)
 INSIZ
 integer  no. of bin values
Special values
NHIST must be equal to zero the first time the
Remarks
 the variable NHIST must not be changed by the program
 NHIST is histogram dependent : the user must define one NHIST variable per histogram
 for the rules governing the filling, see HI2FIL
CALL HR1PUT(ID, RVAL, RCON)
Action Replace in a 1dimensional histogram. The contents of the bin, defined by
RVAL, is replaced by a new contents RCON
Parameters
 ID
 integer  histogram identifier
 RVAL
 real  bin value
 RCON
 real  new bin contents
Remarks
 Any fractional part of RCON is ignored
 if RCON is negative, an error message is given and results will be unpredictable
 if RVAL is outside bin limits for histogram ID, the underflow or overflow bins will be
replaced
CALL HR2PUT(ID, RXVAL, RYVAL, RCON)
Action Replace in a 2dimensional histogram. The contents of the bin, defined by
(RXVAL, RYVAL), is replaced by a new contents RCON
Parameters
 ID
 integer  histogram identifier
 RXVAL
 real  X bin value
 RYVAL
 real  Y bin value
 RCON
 real  new bin contents
Remarks
 Any fractional part of RCON is ignored
 If RCON is negative, an error message is given and results will be umpredictable
 if RVAL is outside bin limits for histogram ID, the underflow or overflow bins will be
replaced
CALL HRCAPU(ID, RARRC)
Action Replace in a 1dimensional or 2dimensional histogram: all the bins get
their contents replaced sequentially by new contents contained in array RARRC.
Parameters
 ID
 integer  histogram identifier
 RARRC
 real array  new bin contents
  one dimensional histograms : RARRC(INBINS)
  two dimensional histograms : RARRC(IXBINS, IYBINS)
Remarks
 Any fractional part of array elements is ignored
 the elements of RARRC should not be negative. For each element <0 an error message is produced and results will be unpredictable.
 underflow and overflow
bins are not replaced.
CALL HR1ADD(ID, RVAL, RCON)
Action Add in a 1dimensional histogram. The contents of the bin, defined by
RVAL, is incremented by a value RCON
Parameters
 ID
 integer  histogram identifier
 RVAL
 real  bin value
 RCON
 real  value to be added to bin contents
Remarks
 RCON can be positive or negative but resulting contents must not be negative. If they
are, an error message will be issued and results will be unpredictable.
 Any fractional part of RCON will be ignored
 if RVAL is outside bin limits of histogram ID, the underflow or overflow bins will be
updated.
CALL HR2ADD(ID, RXVAL, RYVAL, RCON)
Action Add in a 2dimensional histogram. The contents of the bin, defined by
(RXVAL, RYVAL), is incremented by a value RCON
Parameters
 ID
 integer  histogram identifier
 RXVAL
 real  X bin value
 RYVAL
 real  Y bin value
 RCON
 real  value to be added to bin contents
Remarks
 RCON can be positive or negative but resulting contents must not be negative. If they
are, an error message will be issued and results will be unpredictable.
 Any fractional part of RCON will be ignored
 if RVAL is outside bin limits of histogram ID, the underflow or overflow bins will be
updated.
CALL HCCRST(ID)
Action Reset a histogram. The bin contents are reset to zero.
Parameters
 ID
 integer  histogram identifier (ID=0 means all)
In sections 5.1 and 5.2 is given a description of the histogram print and plot output
formats.
For a general overview of the histogram display facilities available in HMINI see
section 1.1.4
For definition of subroutines used for histogram display see sections 5.3 to 5.5
Histograms can be output in print format on an alphanumeric terminal (VDU) or a line
printer. The default output unit for printed histograms is the standard print logical unit
for the computer. This can be changed by a call to HCCLPR. Each histogram is identified by
the title and identifier as defined at booking.
Each histogram is started on a new page. The output size of histograms can be defined
by a call to HCCPAG. If the number of bins in the histogram is greater than the user
defined number of lines, automatic rebinning will take place. A factor R is calculated
internally and every successive R bins are combined where R=1,2,5 or 10 etc.
One dimensional histograms are printed with the bin contents horizontally i.e. across
the paper and the bin value axis vertically i.e. along the paper. For each bin the bin
number, lower bin limit and bin contents are printed as well as a number of asterisks
representing the bin contents. The underflow and overflow bin contents and the upper limit
of the last bin are also given. Bin limits and contents are printed in real format.
The bin contents scale is adjusted to the page width. The lower limit of the scale is
by default equal to 0 and the upper limit equal to the maximum bin contents. The scale
limits can be redefined by calls to HCCMIN and HCCMAX.
The contents of each bin is represented by a number of asterisks followed by an X. The
number of asterisks N is the nearest integer to S where
S = (bin contents  lower limit of scale) / (upper limit of scale  lower limit of
scale) * page width (in characters)
Output statistics
The following statistics for the histogram are printed:
 Integrated contents defined as the sum of the bin contents NOT including the underflow
and overflow bins
 Maximum bin contents (not including underflow or overflow bins)
 Min Scale defined as lower limit of scale (0.0 is output if scaling is automatic)
 Max scale defined as upper limit of scale (0.0 is output if scaling is automatic)
 Log Output defined as 1 if histogram format is logarithmic, 0 otherwise
 Resolution defined as R above.
 Bin format defined as number of bits per bin (0 is printed if default), see section
1.1.3
 Mean value defined as
M = (N1*X1+N2*X2+  +NI*XI+  +NN*XN) / NTOT
where NI is the contents of bin number I, XI is the centre value of bin number I and
NTOT = N1+N2  NI++NN is the total number of entries (excluding underflow/overflow). If
only a part of a histogram is output, the mean value is computed from the entries in the
selected part only i.e. N = # bins in the selected part.
 Sigma defined as
S = SQRT [(N1*X1**2+ + NI*XI**2+ + NN*XN**2)/NTOT  M**2]
with NI, XI, NTOT and M defined as above.
 Entries/asterisk = # entries represented by one asterisk
The Yaxis is printed vertically and the Xaxis horizontally (i.e. across the paper on
a line printer). The lower limit of each Ybin is given as well as the upper limit of the
last Ybin. The Xaxis is printed with + characters indicating bins no. 6,11,16,21 etc.
The lower limits of every fifth bin are printed starting from the first bin i.e. the
numbers printed are lower limits of bins indicated by the + characters.
Bin contents are represented by alphanumeric characters with each character
representing a certain number of entries. The number of characters or levels can be
changed up to a max. of 36 by calling the routine HC2LEV. The range of bin contents
corresponding to one character (i.e. the number of entries per level) is given by
NPL = (upper limit of scale  lower limit of scale) / # levels
The relation between levels, characters and bin contents is given in the table below:
Level Symbol Bin contents range 1 . 0.0
Any cell with zero contents is left blank. Any contents greater than the upper limit
for scaling is represented by an asterisk.
Output statistics
Statistics printed are:
 No. of levels
 Bin format defined as number of bits per bin (0 is printed if default) see section 1.1.4
 Min Scale defined as lower limit of scale (0.0 is output if scaling is automatic)
 Max scale defined as upper limit of scale (0.0 is output if scaling is automatic)
 Total  total number of histogram entries (including underflow/overflow)
 Entries/level = NPL as defined above
 Underflow/Overflow entries are represented in a table
N1 N2 N3 N4 N5 N6 N7 N8 N9 where N1 = no.of entries with underflow in X and overflow
in Y N2 = no.of entries with X in range and overflow in Y N3 = no.of entries with overflow
in X and overflow in Y N4 = no.of entries with underflow in X and Y in range N5 = no.of
entries with X in range and Y in range = integrated contents N6 = no.of entries with
overflow in X and Y in range N7 = no.of entries with underflow in X and underflow in Y N8
= no.of entries with X in range and underflow in Y N9 = no.of entries with overflow in X
and underflow in Y The sum of N1, N2....N9 equals total no. of entries
Histograms may be displayed in plot format on Tektronix terminals or, in case of HMINI
running on MC68000, also on PCs. The default terminal is T4012 with small character size
but these parameters as well as the logical unit number can be redefined by the user
(HCCGD3, HCCLPL). The number of histograms on the screen, by default one, may be selected
by calling the routine HCCFRA. The plot resolution can be changed by rebinning (HC*RES).
Each histogram is identified by the title and identifier as defined at booking. Every
histogram is surrounded by a rectangular box.
The bin contents axis is vertical and is labelled with tick marks and numbers defining
the bin contents scale. If the max. bin contents exceeds 1000, a scale factor of format
10**N is indicated at the upper end of the axis. The bin value axis is horizontal and is
in a similar way labelled with a (variable) number of tick marks and numeric values.
For integer histograms these values are in the range 999 to 999, and for real
histograms in the ranges 9.99 to .1 or .1 to 9.99. If the user defined histogram limits
fall outside these intervals, a scale factor of format 10**N is indicated at the right end
of the xaxis.
The histogram contour is drawn as a full line.
Output Statistics
Below the histogram the following statistics are output:
 M Mean value defined as
(N1*X1+N2*X2+  +NI*XI+  +NN*XN) / NTOT
where NI is the contents of bin number I, XI is the centre value of bin number I and
NTOT = N1+N2  NI++NN is the total number of entries (excluding underflow/overflow). If
only a part of a histogram is output, the mean value is computed from the entries in the
selected part only i.e. N = # bins in the selected part.
 S Sigma defined as
SQRT [(N1*X1**2+ + NI*XI**2+ + NN*XN**2)/NTOT  M**2]
with NI, XI, NTOT and M defined above.
 U underflow  No. of entries in underflow bin
 O overflow  No. of entries in overflow bin
 C Integrated contents  Total number of entries not including underflow/overflow
 MX  maximum bin contents
The Y and X axes are now both representing bin values and are labelled in a way similar
to the bin value axis in one dimensional histograms.
Bin contents are represented by dots (= little crosses), the number of dots being
proportional to the number of entries per bin : a densely populated area of the xy plane
has a high dot density. The maximum number of dots per bin can be changed by calling
HC2DOT.
Below the plot the following statistics are output
 C Integrated contents  number of entries not including underflow/overflow
 U/O no. of entries in all underflow/overflow bins
 MX maximum bin contents
CALL HCCMAX(ID, RMX)
Action Overruling the automatic maximum used for output scaling. If HCCMAX is
not  called, the upper limit of scale is automatically the maximum bin contents.
Parameters
 ID
 integer  histogram identifier (ID=0 means all)
 RMX
 real  upper limit of scale for all subsequent output
Special values RMX=0.0 resets subsequent outputs for automatic calculation of upper
limit for scaling.
CALL HCCMIN(ID, RMN)
Action Overruling the automatic zero lower limit for output scaling. If HCCMIN
is not called, the lower limit of scale is automatically zero.
Parameters
 ID
 integer  histogram identifier (ID=0 means all)
 RMN
 real  lower limit of scale for all subsequent output
Special values RMN=0.0 resets subsequent outputs for automatic zero lower limit
for scaling.
CALL HC1LOG(ID)
Action Logarithmic presentation of subsequent outputs. If HC1LOG is not called,
output is in linear presentation.
Parameters
 ID
 integer  histogram identifier (ID=0 means all)
CALL HC1LIN(ID)
Action Linear presentation of subsequent outputs.
Parameters
 ID
 integer  histogram identifier (ID=0 means all)
Note that parameters set in the routines HCCLPR, HCCPAG, HC2LEV apply to all histograms
output after the call and are in effect until another call to the same routine resets
them.
CALL HCCLPR(LU)
Action Set logical unit for print output.
Parameters
 LU
 integer  logical unit
Remarks
 Defaults: NORD = 1, VAX = 6, MC68000 = 6
CALL HCCPAG(ICOLUM, ILINES)
Action Defines maximum histogram size on print output
Parameters
 ICOLUM
 integer  # characters per line
 ILINES
 integer  # lines per histogram
Remarks
 Defaults:
 ICOLUM = 72 (narrow paper width)
 ILINES = (no. of bins + constant) for 1D histogram
 ILINES = 50 for 2D histogram (normal output page length)
If the number of bins is too large to fit into the histogram size the contents of every
R bins are combined where R=2,5 or 10 and histograms are output with a reduced number of
output bins. The most suitable value for R is calculated internally.
CALL HC2LEV(NBL)
Action Sets the number of levels to be used in printing a 2 dimensional
histogram.
Parameters
 NBL
 integer  # of levels
Remarks
 Default value = 10 using symbols .,+,1,2....9
 Maximum value = 36 using symbols .,+,1,2...9, A,B...Z
 Any value of NBL greater than 36 will be converted to 36
CALL HC1PRI(ID)
Action Print a 1dimensional histogram.
Parameters
 ID
 integer  histogram identifier (ID=0 means all)
CALL HC2PRI(ID)
Action Print a 2dimensional histogram.
Parameters
 ID
 integer  histogram identifier (ID=0 means all)
CALL HI1SPR(ID, IFIRST, ILAST)
Action Print part of a 1dimensional histogram.
Parameters
 ID
 integer  histogram identifier (ID=0 means all)
 IFIRST
 integer  bin value defining first bin to be displayed
 ILAST
 integer  bin value defining last bin to be displayed
Remarks
 for bin definitions, see HI1FIL
CALL HR1SPR(ID, RFIRST, RLAST)
Action Print part of a 1dimensional histogram.
Parameters
 ID
 integer  histogram identifier (ID=0 means all)
 RFIRST
 real  bin value defining first bin to be displayed
 RLAST
 real  bin value defining last bin to be displayed
Remarks
 for bin definitions, see HR1FIL
CALL HI2SPR(ID, IXFRST, IXLAST, IYFRST, IYLAST)
Action Print part of a 2dimensional histogram.
Parameters
 ID
 integer  histogram identifier (ID=0 means all)
 IXFRST
 integer  bin value defining first X bin to be displayed
 IXLAST
 integer  bin value defining last X bin to be displayed
 IYFRST
 integer  bin value defining first Y bin to be displayed
 IYLAST
 integer  bin value defining last Y bin to be displayed
Remarks
 for bin definitions, see HI2FIL
CALL HR2SPR(ID, RXFRST, RXLAST, RYFRST, RYLAST)
Action Print part of a 2dimensional histogram.
Parameters
 ID
 integer  histogram identifier (ID=0 means all)
 RXFRST
 real  bin value defining first X bin to be displayed
 RXLAST
 real  bin value defining last X bin to be displayed
 RYFRST
 real  bin value defining first Y bin to be displayed
 RYLAST
 real  bin value defining last Y bin to be displayed
Remarks
 for bin definitions, see HR2FIL
Note that parameters set in the routines HCCLPL, HCCGD3, HCCFRA, HC1RES, HC2RES, HC2DOT
apply to all histograms output after the call and are in effect until another call to the
same routine resets them.
CALL HCCLPL(LU)
Action Set logical unit for plot output.
Parameters
 LU
 integer  logical unit
Remarks
 Defaults: NORD = 1, VAX = 6, MC68000 = 6
CALL HCCGD3(IDEV, ICHAR, IDUM)
Action Sets the device type and character size of plot terminal.
Parameters
 IDEV
 integer  device type, with one of the following values:
 4006 (Tektronix)
 4010 (Tektronix)
 4012 (Tektronix) DEFAULT
 4014
 4027
 68 output on personal computer (MAC, IBM PC, VAX station)
 69 output on colour monitor (Eltec)
 70 output on both
 ICHAR
 integer  character size
 1 = small DEFAULT
 2 = medium
 3 = large
 IDUM
 integer  dummy argument
Remarks
 If call to HCCGD3 is made it must take place AFTER call to HCCINI but BEFORE call to
HCCLPL
 This must not contradict any calls directly to MINIGD3 that specify that specify the
same parameters. If a call to miniGD3 specifying these parameters has been made this call
to HCCGD3 must also be made otherwise HMINI defaults will be in effect.
 The possible values of ICHAR obviously depend on available character sizes on plotting
terminal being used.
 The device types 68, 69, 70 are available on VALETplus.
CALL HCCFRA(NBX, NBY, NACTP)
Action Divides the screen into NBX*NBY frames and selects one frame for the next
display.
Parameters
 NBX
 integer  # of pictures along X  default 1
 NBY
 integer  # of pictures along Y  default 1
 NACTP
 integer  frame number (default = 1)
Remarks
 The frame number is defined as increasing by 1 horizontally i.e. if NBX=3 and NBY=2 then
values of NACTP on screen are as follows: 1 2 3 4 5 6
 this format only works correctly when small character size has been selected.
CALL HC1RES(NRES)
Action Sets number of bins grouped together in one output bin for 1dimensional
histogram plot.
Parameters
 NRES
 integer  # bins/output bin  default 1
CALL HC2RES(XRES, YRES)
Action Sets number of bins per grouped together in one output bin for
2dimensional histogram
Parameters
 XRES
 integer  # bins/output bin along X  default 1
 YRES
 integer  # bins/output bin along Y  default 1
CALL HC2DOT(NBD)
Action Sets the maximum number of dots per bin for the plot drawn (2dimensional
histogram).
Parameters
 NBD
 integer  # of dots per bin  default 10
CALL HCCCUR
Action Sets the cursor at the bottom left hand corner of the screen. This is
useful for writing a line of text after a plot.
CALL HC1PLO(ID)
Action Plot a 1dimensional histogram.
Parameters
 ID
 integer  histogram identifier (ID=0 means all)
CALL HC2PLO(id)
Action Plot a 2dimensional histogram.
Parameters
 ID
 integer  histogram identifier (ID=0 means all)
CALL HI1SPL(ID, IFIRST, ILAST)
Action Plot part of a 1dimensional histogram.
Parameters
 ID
 integer  histogram identifier (ID=0 means all)
 IFIRST
 integer  bin value defining first bin to be displayed
 ILAST
 integer  bin value defining last bin to be displayed
Remarks
 for bin definitions, see HI1FIL
CALL HR1SPL(ID, RFIRST, RLAST)
Action Plot part of a 1dimensional histogram.
Parameters
 ID
 integer  histogram identifier (ID=0 means all)
 RFIRST
 real  bin value defining first bin to be displayed
 RLAST
 real  bin value defining last bin to be displayed
Remarks
 for bin definitions, see HR1FIL
CALL HI2SPL(ID, IXFRST, IXLAST, IYFRST, IYLAST)
Action Plot part of a 2dimensional histogram.
Parameters
 ID
 integer  histogram identifier (ID=0 means all)
 IXFRST
 integer  bin value defining first X bin to be displayed
 IXLAST
 integer  bin value defining last X bin to be displayed
 IYFRST
 integer  bin value defining first Y bin to be displayed
 IYLAST
 integer  bin value defining last Y bin to be displayed
Remarks
 for bin definitions, see HI2FIL
CALL HR2SPL(ID, RXFRST, RXLAST, RYFRST, RYLAST)
Action Plot part of a 2dimensional histogram.
Parameters
 ID
 integer  histogram identifier (ID=0 means all)
 RXFRST
 real  bin value defining first X bin to be displayed
 RXLAST
 real  bin value defining last X bin to be displayed
 RYFRST
 real  bin value defining first Y bin to be displayed
 RYLAST
 real  bin value defining last Y bin to be displayed
Remarks
 for bin definitions, see HR2FIL
CALL HI1DIR(ID, TIT, INBINS, ILOW, IUP, INBWT, NHIST)
Action Get directory of 1dimensional histogram
Parameters
 ID
 integer  histogram identifier
Values returned TITarray  histogram title INBINSinteger 
number of bins ILOWinteger  lower value of first bin IUPinteger  upper
value of last bin INBWTinteger  number of machine words of title NHISTinteger
 histogram directory pointer CALL HI2DIR(ID, TIT, IXBINS, IXLOW,
IXUP, IYBINS, IYLOW, IYUP, INBWT, NHIST)
Action Get directory of 2dimensional histogram
Parameters
 ID
 integer  histogram identifier
Values returned
 TIT
 array  histogram title
 IXBINS
 integer  number of X bins
 IYBINS
 integer  number of Y bins
 IXLOW
 integer  lower value of first X bin
 IXUP
 integer  upper value of last X bin
 IYLOW
 integer  lower value of first Y bin
 IYUP
 integer  upper value of last Y bin
 INBWT
 integer  number of machine words of title
 NHIST
 integer  histogram directory pointer
RCON=HI1GET(ID, IVAL)
Action Get from a 1dimensional histogram. The contents of the bin, defined by
IVAL, is returned in RCON.
Parameters
 ID
 integer  histogram identifier
 IVAL
 integer  bin value
 RCON
 real  bin contents returned by the function
Remarks:
 If IVAL is outside histogram limits underflow or overflow values will be returned
RCON=HI2GET(ID, IXVAL, IYVAL)
Action Get from a 2dimensional histogram. The contents of the bin, defined by
(IXVAL, IYVAL), is returned in RCON.
Parameters
 ID
 integer  histogram identifier
 IXVAL
 integer  X bin value
 IYVAL
 integer  Y bin value
 RCON
 real  bin contents returned by the function
Remarks
 If IXVAL or IYVAL are outside histogram limits underflow or overflow values will be
returned
CALL HICAGE(ID, RARRC)
Action Get from a 1 or 2dimensional histogram. The contents of all the bins are
returned in array RARRC.
Parameters
 ID
 integer  histogram identifier
 RARRC
 real array  bin contents returned in RARRC(INBINS) or RARRC(IXBINS, IYBINS)
These routines only work with T4010, T4012, T4014 or T4027 graphics terminals or with
personal computers (MAC, IBM PC, VAX station) controlling a VALET.
The bin contents and value are returned under the assumption that the cursor points to
the last histogram displayed when the histogram has been plotted by a call to HC*PLO(ID)
routine where ID is not equal to zero. Calling the graphic get routines activates the
cursor. Hitting a character (not carriage return) enters the cursor coordinates. These
routines only work when there is ONE histogram per frame. There should be NO input/output
on the plot terminal between the call to HC*PLO and the call to H**GIN. This includes
calls to HCCCUR. The bin contents and values returned by these functions are independent
of any change in output resolution made by call to HC*RES routines.
RCON=HI1GIN(IVAL, CHAR, IRES)
Action Graphic get of bin value and bin contents from a 1dimensional histogram:
the contents and bin value indicated by the crosshair cursor, character entered and bin
resolution is returned.
Parameters
 RCON
 real  bin contents returned by the function
 IVAL
 integer  bin value
 CHAR
 integer  character entered  right justified (LSB) (hollerith)
 IRES
 integer  bin resolution (normally 1 unless HC1RES has been called)
RCON=HI2GIN(IXVAL, IYVAL, CHAR, IXRES, IYRES)
Action Graphic get of X and Y bin values and bin contents from a 2dimensional
histogram: the contents and x.y bin values of the bin indicated by the crosshair cursor,
character entered and bin resolutions are returned.
Parameters
 RCON
 real  bin contents returned by the function
 IXVAL
 integer  X bin value
 IYVAL
 integer  Y bin value
 CHAR
 integer  character entered, right justified (LSB) (hollerith)
 IXRES
 integer  bin resolution in X (normally 1 unless HC2RES has been called)
 IYRES
 integer  bin resolution in Y (normally 1 unless HC2RES has been called)
CALL HR1DIR(ID, TIT, INBINS, RLOW, RUP, INBWT, NHIST)
Action Get directory of 1dimensional histogram
Parameters
 ID
 integer  histogram identifier
Values returned
 TIT
 array  histogram title
 INBINS
 integer  number of bins
 RLOW
 real  lower value of first bin
 RUP
 real  upper value of last bin
 INBWT
 integer  number of machine words of title
 NHIST
 integer  histogram directory pointer
CALL HR2DIR(ID, TIT, IXBINS, RXLOW, RXUP, IYBINS, RYLOW, RYUP, INBWT, NHIST)
Action Get directory of 2dimensional histogram
Parameters
 ID
 integer  histogram identifier
Values returned
 TIT
 array  histogram title
 IXBINS
 integer  number of X bins
 IYBINS
 integer  number of Y bins
 RXLOW
 real  lower value of first X bin
 RXUP
 real  upper value of last X bin
 RYLOW
 real  lower value of first Y bin
 RYUP
 real  upper value of last Y bin
 INBWT
 integer  number of machine words of title
 NHIST
 integer  histogram directory pointer
RCON=HR1GET(ID, RVAL)
Action Get from a 1dimensional histogram. The contents of the bin, defined by
RVAL, is returned in RCON.
Parameters
 ID
 integer  histogram identifier
 RVAL
 real  bin value
 RCON
 real  bin contents returned by the function
Remarks
 If RVAL is outside histogram limits underflow/overflow values will be returned
RCON=HR2GET(ID, RXVAL, RYVAL)
Action Get from a 2dimensional histogram. The contents of the bin, defined by
RXVAL, RYVAL, is returned in RCON.
Parameters
 ID
 integer  histogram identifier
 RXVAL
 real  X bin value
 RYVAL
 real  Y bin value
 RCON
 real  bin contents returned by the function
Remarks
 If RXVAL or RYVAL are outside histogram limits underflow/overflow values will be
returned
CALL HRCAGE(ID, RARRC)
Action Get from a 1 or 2dimensional histogram. The contents of all the bins are
returned in array RARRC.
Parameters
 ID
 integer  histogram identifier
 RARRC
 real array  bin contents returned in RARRC(INBINS) or RARRC(IXBINS, IYBINS)
These routines only work with T4010, T4012, T4014 or T4027 graphics terminals or with
personal computers (MAC, IBM PC, VAX station) controlling a VALET.
The bin contents and value are returned under the assumption that the cursor points to
the last histogram displayed when the histogram has been plotted by a call to HC*PLO(ID)
routine where ID is not equal to zero. Calling the graphic get routines activates the
cursor. Hitting a character (not carriage return) enters the cursor coordinates. These
routines only work when there is ONE histogram per frame. There should be NO input/output
on the plot terminal between the call to HC*PLO and the call to H**GIN. This includes
calls to HCCCUR. The bin contents and values returned by these functions are independent
of any change in output resolution made by call to HC*RES routines.
RCON=HR1GIN(RVAL, CHAR, IRES)
Action Graphic get of bin value and bin contents from a 1dimensional histogram:
the contents and the value of the bin indicated by the crosshair cursor, character entered
and bin resolution are returned.
Parameters
 RCON
 real  bin contents returned by the function
 RVAL
 real  bin value
 CHAR
 integer  character entered  right justified (LSB) (hollerith)
 IRES
 integer  bin resolution (normally 1 unless HC1RES been called)
RCON=HR2GIN(RXVAL, RYVAL, CHAR, IXRES, IYRES)
Action Graphic get of X and Y bin values and bin contents from a 2dimensional
histogram: the contents and bin values of the bin indicated by the crosshair cursor,
character entered and bin resolutions are returned.
Parameters
 RCON
 real  bin contents returned by the function
 RXVAL
 real  X bin value
 RYVAL
 real  Y bin value
 CHAR
 integer  character entered  right justified (LSB) (hollerith)
 IXRES
 integer  bin resolution in X (normally 1 unless HC2RES has been called)
 IYRES
 integer  bin resolution in Y (normally 1 unless HC2RES has been called)
CALL HCTYPE(ID, IT)
Action The histogram type is returned
Parameters
 ID
 integer  histogram identifier
 IT
 integer  histogram type
CALL HCSIZE(ID, ISIZE)
Action # bins of histogram is returned
Parameters
 ID
 integer  histogram identifier
 ISIZE
 integer  # X bins * # Y bins, where # Y bins = 1 if one dimensional
IEX = HCEXIS(ID)
Action Checks if histogram exists
Parameters
 ID
 integer  histogram identifier
 IEX
 integer  = 1 if histogram exists , = 0 otherwise
CALL HCIDAL(IDVECT, TPVECT, N)
Action Return identifiers, types and number of existing histograms
Parameters
 IDVECT
 integer array  array of IDs, dimension > # of existing histograms
 TPVECT
 integer array  array of TYPES
 N
 integer  # booked histograms
Remarks
 arrays must be dimensioned to accomodate the maximum possible number of histograms
CALL HC1GST(ID, RMEAN, RSIG, RMAX)
Action Extract statistics for a onedimensional histogram
Parameters
 ID
 integer  histogram identifier
 RMEAN
 real  mean value
 RSIG
 real  root mean square (sigma)
 RMAX
 realmax. bin contents
RCON=HCCCNT(ID)
Action The integrated contents of a histogram is returned.
Parameters
 ID
 integer  histogram identifier
 RCON
 real  integrated contents returned by the function (not including
under/overflow)
RCONMX=HCCMXC(ID)
Action The maximum bin contents of a histogram is returned.
Parameters
 ID
 integer  histogram identifier
 RCONMX
 real  maximum contents returned by the function (not including
underflow/overflow bins)
RCONMN=HCCMNC(ID)
Action The minimum bin contents of a histogram is returned.
Parameters
 ID
 integer  histogram identifier
 RCONMN
 real  minimum contents returned by the function (not including
underflow/overflow bins)
CALL HCCLMS(LU)
Action Set logical unit for error messages output.
Parameters
 LU
 integer  logical unit
Special values
LU = 0  suppress error messages output
Defaults NORD = 1 PDP = 5 VAX = 6
IERR=HCCERR(ERR)
Action The value of the last error and the routine name are returned.
Parameters
 IERR
 integer  last error number
 ERR
 array  3word integer array in which the routine name is returned
Remarks
 HCCERR is an integer function although the name does not follow the normal convention
 111
 reference to a non existing histogram
 112
 histogram already booked
 114
 illegal parameter (outside allowed bounds)
 in HCCINI NDIRLG
 in H**BOO IMXCNT
 in H**FIL ID and NHIST incompatible
 Histogram pointer NHIST pointing to histogram area of different ID
 116
 Negative bin contents
 216
 title error ($ character is missing)
 811
 not enough space in HDIR or HDAT area
 813
 initialisation not done  see HCCINI
The HDIR labelled common is used to store the histogram directories. The OPTIONS AREA
is used to store dynamic histogram options (maximum and minimum scale, ...). The histogram
bins and bin overflows are stored in the HDAT labelled common.
In the common HDIR a working space is reserved by the package for internal parameters
storage:
HDIR working space : 70 words
DIR LIST is the header of the created histograms list.
DEL LIST is the header of the deleted histograms list.
Space requirements:
INTEGER directory: 12 words + TITLE length (in words)
REAL directory : 15 words + TITLE length (in words)
NOTES:
 TYPE is the histogram directory type : 0 : 1dim integer directory 1 : 2dim integer
directory 2 : 1dim real directory 3 : 2dim real directory
 In case of REAL directory, the inverse of the bin width is stored.
2 Space requirements:
INTEGER directory: 16 words + TITLE length (in words)
REAL directory : 22 words + TITLE length (in words)
NOTES:
 TYPE is the histogram directory type : 0 : 1dim integer directory 1 : 2dim integer
directory 2 : 1dim real directory 3 : 2dim real directory
 in case of REAL directory, the inverse of the bin width is stored.
OPTION FORMAT
Each time a bin contents overflows, two words are added to the overflow list of that
histogram:
word 1 : bin number
word 2 : overflow value
The overflow value is incremented by one for each overflow of the concerned bin. The
bin contents is then reset to zero.
Space requirements: N words if INB = 0 (N+(J1))/J words if INB > 0 where N
= # bins + 2 and J = word size/INB and INB = # bits per bin
Space requirements: N words if INB = 0 (N+(J1))/J words if INB > 0 where N
= # bins + 8 and J = word size/INB and INB = # bits per bin
HMINI Routine HBOOK Routine Function
HI1BOO HBOOK1 book
HR1BOO HBOOK1 book
HI2BOO HBOOK2 book
HR2BOO HBOOK2 book
HI1FIL single fill
HR1FIL single fill
HI2FIL single fill
HR2FIL single fill
HI1AFI array fill
HR1AFI array fill
HI2AFI array fill
HR2AFI array fill
HI1PUT single put
HR1PUT single put
HI2PUT single put
HR2PUT single put
HICAPU HPAK array put
HRCAPU HPAK array put
HI1ADD HFF1 single add
HR1ADD HFF1 single add
HI2ADD HFF2 single add
HR2ADD HFF2 single add
HI1GET HX single get
HR1GET HX single get
HI2GET HXY single get
HR2GET HXY single get
HICAGE HUNPAK array get
HRCAGE HUNPAK array get
HI1GIN graphic get
HR1GIN graphic get
HI2GIN graphic get
HR2GIN graphic get
HC1PRI HPHIST print
HC2PRI HPSCAT print
HI1SPR selective print
HR1SPR selective print
HI2SPR selective print
HR2SPR selective print
HC1PLO HPLOT plot
HC2PLO HPLOT plot
HI1SPL selective plot
HR1SPL selective plot
HI2SPL selective plot
HR2SPL selective plot
HI1DIR HGIVE directory
HR1DIR HGIVE directory
HI2DIR HGIVE directory
HR2DIR HGIVE directory
HCCINI initialisation
HCCERR error return
HCCRST HRESET reset
HCCDEL HDELET delete
HCCGAR garbage collection
HCCCNT HSUM integrated contents
HCCCUR cursor position set
HCCMXC HMAX maximum bin contents
HCCMNC HMIN minimum bin contents
HCCMAX HMAXIM scaling
HCCMIN HMINIM scaling
HC1LOG logarithmic
HC1LIN linear
HCCPAG HPAGSZ paper size
HCCLPR HOUTPU print logical unit
HCCLPL HPLINT plot logical unit
HCCLMS error messages logical unit
HC2LEV levels
HCCGD3 plotting output device
HC2DOT number of dots
HCCFRA frame
HC1RES HBIGBI output resolution
HC2RES output resolution
This chapter describes some example and test programs for HMINI with print and plot
output.
Example with print output
A 1D integer and a 2D real histogram are booked.
The 1D histogram is filled with a spectrum representing a step function while the 2D
histogram is filled, using a put routine, with a distribution corresponding to the
function f(x, y) = x+y1. The histograms are displayed in print format on the default
print logical unit (6 on VAX, 1 on NORD). Space statistics and error messages appear on
LUN 6. PROGRAM TEST1 INTEGER HCCERR, ERR(3) COMMON/HDIR/IDIRBU(200)
COMMON/HDAT/IDATBU(1200) C ALLOCATE SPACE FOR HISTOGRAMS CALL HCCINI(200,1200)
IF(HCCERR(ERR).GT.0)GO TO 100 C NOTE THAT DEFAULT LOGICAL UNITS ARE USED C BOOK 1
DIMENSIONAL INTEGER HISTOGRAM WITH 100 BINS OF WIDTH 1 CALL HI1BOO(1,12HEXAMPLE
ONE$,100,1,101,0) IF(HCCERR(ERR).GT.0)GO TO 100 C BOOK 2DIMENSIONAL REAL HISTOGRAM WITH
20 XBINS AND 50 YBINS CALL HR2BOO(2,12HEXAMPLE TWO$,20,1.0,21.0,50,0.0,50.0,0)
IF(HCCERR(ERR).GT.0)GO TO 100 C SEE HOW MUCH SPACE LEFT CALL HCCSPA(RW, RD) WRITE(6,60)RW,
RD 60 FORMAT(' NO. OF DIRECTORY, DATA WORDS LEFT',2F10.2) NHIST1=0 NHIST2=0 DO 10 I=1,100
IVAL=I DO 10 J=1, I C FILLING OF HISTOGRAM 1 CALL HI1FIL(1, NHIST1, IVAL) 10 CONTINUE DO
11 I=1,20 RI=FLOAT(I) DO 11 J=1,50 RJ=FLOAT(J1) RCON=FLOAT(J+I) C FILLING OF HISTOGRAM 2
USING PUT ROUTINE CALL HR2PUT(2, RI, RJ, RCON) 11 CONTINUE C PRINTOUT OF HISTOGRAMS 1 AND
2 CALL HC1PRI(1) CALL HC2PRI(2) C CHANGE NO. OF LEVELS FOR GREATER RESOLUTION IN 2D
HISTOGRAM CALL HC2LEV(36) CALL HC2PRI(2) STOP 100 IERR=HCCERR(ERR) WRITE(6,50)IERR, ERR 50
FORMAT(' ERROR NUMBER ', I5,' IN ROUTINE ',3A2) END
Example with plot output
A 1D real histogram is booked and filled, using array fill, with a spectrum
corresponding to a step function. A 2D integer histogram is booked and filled, using a
real put routine, with a distribution representing the function f(x, y) = 4*X**2 
Y**2+400. The histograms are output in plot format, using small characters, on plot
logical unit no. 6, which is assumed to be a Tektronix 4012.
User input for page control is on LUN 5 and possible error messages are written to LUN
no. 6. PROGRAM TEST2 INTEGER HCCERR, ERR(3) COMMON/HDIR/IDIR(200) COMMON/HDAT/IDAT(500)
DIMENSION DVAL(1300) C INITIALISE HMINI CALL HCCINI(200,500) IF(HCCERR(ERR).GT.0)GO TO 100
C SET TERMINAL TYPE (T4012, SMALL CHAR'S ACTUALLY=DEFAULT !) CALL HCCGD3(4012,1, IDUM)
IF(HCCERR(ERR).GT.0)GO TO 100 C SET PLOT UNIT CALL HCCLPL(6) C ONEDIM REAL HISTOGRAM,
50 BINS , WIDTH 1 CALL HR1BOO(1,12HEXAMPLE ONE$,50,1.0,51.0,0) IF(HCCERR(ERR).GT.0)GO TO
100 C TWODIM INTEGER HISTOGRAM, 10 X BINS AND 20 YBINS CALL HI2BOO(2,12HEXAMPLE
TWO$,10,10,10,20,20,20,0) IF(HCCERR(ERR).GT.0)GO TO 100 NHIST1=0 NHIST2=0 JJ=0 DO 10
I=1,50 RVAL=FLOAT(I) DO 10 J=1, I C DVAL CONTAINS N'TH BIN VALUE N TIMES JJ=JJ+1
DVAL(JJ)=RVAL+0.5 10 CONTINUE C FILL HISTOGRAM ONE USING ARRAY FILL CALL HR1AFI(1, NHIST1,
DVAL, JJ) C FILL HISTOGRAM TWO USING PUT C DEFINE PARABOLOID WITH MAX 400 IN (X, Y)=(0,0)
DO 11 I=9,9,2 DO 11 J=19,19,2 RCON = 4*I*I  J*J +400 C MAKE SURE RCON >0 !!
IF(RCON.LT.0.5)RCON=0.5 CALL HI2PUT(2, I,J, RCON) 11 CONTINUE C NOW PLOT CALL HC1PLO(1) C
SET CURSOR AT BOTTOM LEFT CORNER CALL HCCCUR WRITE(6,50) 50 FORMAT(' STEP FUNCTION, 1
CLEAR PAGE, THEN TYPE ANY NUMBER, RETURN TO CONTINUE'/) READ(5,*)IDUM CALL HC2PLO(2) CALL
HCCCUR WRITE(6,60) 60 FORMAT(' PARABOLOID WITH MAX 400 IN (0,0), 1 CLEAR PAGE, THEN TYPE
ANY NUMBER, RETURN TO CONTINUE'/) READ(5,*)IDUM C CHANGE MAX NO OF DOTS CALL HC2DOT(20)
CALL HC2PLO(2) CALL HCCCUR WRITE(6,70) 70 FORMAT(' SAME WITH DOUBLE DOT DENSITY') STOP 100
IERR=HCCERR(ERR) WRITE(6,110)IERR, ERR 110 FORMAT(' ERROR NO ', I5,' IN ROUTINE ',3A2) END
Test programs
HMINI Test programs
In addition to the examples there exist two test programs. The TESTPRINT program calls
almost all of the HMINI routines related to booking, filling and printing of histograms.
The histograms are output in print format on the default print unit and each histogram has
a short explanatory text that allows to check the correctness of the print output.
The TESTPLOT program produces a subset of the histograms in TESTPRINT and
outputs these in Plot format. In addition graphics input is tested. Each histogram has one
line of text which gives a reference to one of the histograms in TESTPRINT. In other
words, the plots produced by TESTPLOT should be checked quantitatively by comparing to the
printed histograms. INDEX HISTOGRAMMING CALLS INDEX
R. Nierhaus
miniGD3, Introductory Guide for Users
