SYNOPSIS

CALL HSTOPC (STRING,STRNG2,NUMBER,ILCH)

C-BINDING SYNOPSIS

#include <ncarg/ncargC.h>

void c_hstopc (char *string, char *strng2, int number,
int ilch)

DESCRIPTION

STRING

Character, input -- Selects an internal parameter. The possibilities are:

  'FOR=ON' or 'FOR=OFF'

  'TIT=ON' or 'TIT=OFF'

  'LAB=ON' or 'LAB=OFF'

  'PTI=ON' or 'PTI=OFF'

  'FQN=ON' or 'FQN=OFF'

  'CHR=ON, or 'CHR=OFF'

If an option is turned 'ON' then the STRNG2, NUMBER, and ILCH arguments can be used to override the default settings of that option.

If the value of a STRING option is 'OFF' then the next three arguments of the HSTOPC call can be any dummy value. Option settings will be returned to their default values.

The following options are defined by this subroutine:

FOR

Format for class labels. The 'FOR=OFF' default is
 '(G10.3)'. Although class values are real numbers, integer formats are allowed, in which case HISTGR will convert from real to integer before plotting labels.

TIT

A main title of up to 96 characters. Only 45 characters are written per line so up to 3 lines may be written. The 'TIT=OFF' default is no title.

LAB

A label for the class interval (histogram bar) axis. The 'LAB=OFF' default value is 'CLASS INTERVALS' when the HSTOPL option 'MID=OFF' is selected, and 'CLASS MIDVALUES' when 'MID=ON'.

In order to delete this axis label, select 'LAB=ON' for STRING and 'NOLABEL' for STRNG2.

PTI

The percent axis label. Default value when 'PTI=OFF' is 'PERCENT OCCURRENCE' when IFLAG = 0, or 1, and 'PERCENT of MAXIMUM' when IFLAG = 2, or 3.

FQN

The frequency axis label. The 'FQN=OFF' default value is 'FREQUENCY'.

In order to delete this axis label, select 'FQN=ON' for STRING and 'NOLABEL' for STRNG2.

CHR

A concatenated string of alphanumeric class interval labels. The default value is a set of internally computed numeric class labels.

STRNG2

Character, input -- A string of up to 45 characters.

 'FOR=ON', STRNG2 is a format for the class labels.

 'TIT=ON', STRNG2 is a histogram main title.

 'LAB=ON', STRNG2 is a label for the class interval axis.

 'PTI=ON', STRNG2 is a label for the percentage axis.

 'FQN=ON', STRNG2 is a label for the frequency axis.

 'CHR=ON', STRNG2 is a concatenated string of class labels.

The length of this character string will be NUMBER*ILCH, where NUMBER is the number of class intervals and ILCH is the number of characters in the interval label.

NUMBER

Integer, input -- It only applies to the following options:

 'FOR=ON', NUMBER specifies the maximum number of class intervals (histogram bars) that will be labeled. The default values ('FOR=OFF') are 9 labels for vertical bars and 15 labels for horizontal bars.

 'CHR=ON', NUMBER must be set to NCLASS, an argument of the next call to be made to routine HISTGR.

NUMBER is not used under any other option setting.

Calls to HSTOPC with either 'FOR=ON' or 'CHR=ON' may be performed in any order; the parameters set by NUMBER are mutually exclusive.

ILCH

Integer, input -- It only applies in the following instance.

If 'CHR=ON', ILCH specifys the number of characters in each label of a class interval (histogram bar). ILCH cannot be greater than 15.

C-BINDING DESCRIPTION

The C-binding argument descriptions are the same as the FORTRAN argument descriptions.

USAGE

HSTOPC is called to set parameters of type CHARACTER before entry HISTGR is called to generate the histogram. Options are main and axes titles, class interval (bar) labels, and class interval formats.

For a complete list of parameters available in this utility, see the histogram_params man page.

EXAMPLES

Use the command "ncargex thstgr" to generate a three frame example of histogram options. The following code causes the second frame to have a class interval axis of 12 intervals, each with a 3 character label that specifies a month of the year.

PARAMETER (NCLASS=12, ILCH=3)
CHARACTER*55 MON
MON='JANFEBMARAPRMAYJUNJULAUGSEPOCTNOVDEC'
CALL HSTOPC('CHR=ON',MON,12,3)

Example "ncargex thstmv" shows three examples of histograms with missing values in the input data.

ACCESS

To use HSTOPC or c_hstopc, load the NCAR Graphics libraries ncarg, ncarg_gks, and ncarg_c, preferably in that order.

MESSAGES

See the histogram man page for a description of all Histogram error messages and/or informational messages.

COPYRIGHT

Copyright (C) 1987-2009
University Corporation for Atmospheric Research
The use of this Software is governed by a License Agreement.