HISTOGRAM command

Used to produce a graphical representation of the distribution of values in a numeric or character field or expression.

Syntax

HISTOGRAM {<ON>
numeric_field {<MINIMUM min MAXIMUM max> <INTERVALS num>|
FREE interval_value <...n> last_interval}| <ON> character_field}
<TO SCREEN|filename|GRAPH|PRINT> <IF test> <WHILE test> <FIRST|NEXT range>
<HEADER header_text> <FOOTER footer_text> <KEY break_field> <SUPPRESS>
<COLUMNS n> <APPEND> <LOCAL> <OPEN>

Parameters

ON numeric_field

Specify the numeric field or expression to generate the histogram for. The ON parameter can be omitted.

MINIMUM min

Optional. Applies to numeric fields only. Specifies the minimum value of the first interval. If you issued a PROFILE or STATISTICS command, the default is the lowest value in the numeric field. Otherwise, no default exists. If you specify a MINIMUM value, you must also specify a MAXIMUM value.

MAXIMUM max

Optional. Applies to numeric fields only. Specifies the maximum value of the last interval. If you issued a PROFILE or STATISTICS command, the default is the highest value in the numeric field. Otherwise, no default exists. If you specify a MAXIMUM value, you must also specify a MINIMUM value

INTERVALS num

Optional. Applies to numeric fields only. Specifies the number of even intervals ACL produces over the range of minimum to maximum.

FREE interval_value <...n> last_interval

Specifies start and end points. For numeric histograms only, it allows you to specify the starting point of each interval and the ending point of the last range. The last number entered is interpreted as the end of the final range.

ON character_field

Specifies the character field or expression to generate the histogram for. The ON parameter can be omitted.

TO SCREEN | filename | GRAPH | PRINT
  • Specify TO SCREEN to display the results on screen in ACL. This is the default output if the TO parameter is not specified.

  • Specify TO filename to write the results to a file. You must specify the filename value as a quoted string with the appropriate file extension. For example, specify the .TXT file extension to create a text file.

    For example: TO "Output.TXT"

    You can also specify an absolute or relative file path to an existing folder to write the file to.

    For example: TO "C:\Output.TXT" or TO "Results\Output.TXT"

  • Specify TO PRINT to send the results to the default printer.

  • Specify TO GRAPH to create a graph of the command results and display it on screen in ACL.

IF test

Optional. Specifies a condition that must be met. The command is only executed on records that pass the test.

WHILE test

Optional. Specifies that the command should only be executed while a condition is true. The command processing terminates as soon as the specified test evaluates as false, or the end of the table is reached.

FIRST | NEXT range

Optional. Specify FIRST to start processing at the first record or NEXT to start processing at the currently selected record. Use the range value to specify the number of records to process.

HEADER header_text

Optional. Specifies the text to insert at the top of each page of a report. The header_text value must be specified as a quoted string. The value overrides any value set for the ACL HEADER system variable.

FOOTER footer_text

Optional. Specifies the text to insert at the bottom of each page of a report. The footer_text value must be specified as a quoted string. The value overrides any value set for the ACL FOOTER system variable.

KEY break_field

Optional. Specifies that a subtotal should be calculated each time the value of the specified field or expression changes. You can only specify a single field, but you can specify an expression that contains more than one field. The break_field value must be a character field or expression.

SUPPRESS

Optional. Specifies that values above the MAXIMUM value and below the MINIMUM value should be excluded from the command output.

COLUMNS n

Specifies the number of columns that you want for the text representation of the command results. ACL scales interval counts to the space available. The default is 78.

APPEND

Optional. Specifies that command output should be appended to the end of an existing file instead of overwriting the existing file. You must ensure that the structure of the two files is identical when using this parameter, if maintaining a consistent file structure is important (e.g., when you are appending data to an existing ACL table), because ACL appends output to an existing file regardless of its structure.

LOCAL

Optional. Specifies that the output file should be saved in the same location as the ACL project. This parameter only applies when the command is run on an ACL Server table and the output file is an ACL table.

OPEN

Optional. Specifies that the table created by the command should be opened after the command executes. This parameter is only valid if the command creates an output table.

Example

a. Basic histogram for hourly salary

The following example uses the HISTOGRAM command to create a graph showing the distribution of wages between 0 and 100 dollars per hour.

HISTOGRAM ON Rate MINIMUM 0 MAXIMUM 100 TO GRAPH

b.Histogram with defined intervals for hourly salary

The following example refines the HISTOGRAM command to specify the ranges in the graph in a more meaningful way. Most of the wages fall between 5 and 50 dollars per hour, so the graph includes three intervals in this range, and only one for 50-100 and one for > 100.

HISTOGRAM ON Rate MINIMUM 0.0000 MAXIMUM 100 FREE 5,10,20,50,100 TO GRAPH



(C) 2013 ACL Services Ltd. All Rights Reserved. | Send feedback