HISTOGRAM

#### Search Results

Search

# HISTOGRAM

`HISTOGRAM` |  | `ALL` |  | [MULTI-FETCH-clause ] [multi-fetch-factor] [`IN`] [`FILE`] view-name
(operand1)
[`PASSWORD=`operand2]
| [`IN`] |  | `ASC` `ENDING` |  | [`SEQUENCE`] |
`DESC` `ENDING`
`VARIABLE` operand3
`DYNAMIC` operand3
[`VALUE`] [`FOR`] [`FIELD`] operand4
[STARTING/ENDING-clause]
[`WHERE` logical-condition]
statement
`END-HISTOGRAM` (structured mode only)
`LOOP` (reporting mode only)

Dieses Dokument behandelt folgende Themen:

- Funktion

- Einschränkungen

- Syntax-Beschreibung

- Bei HISTOGRAM verfügbare Systemvariablen

- Beispiele

Eine Erläuterung der in dem Syntax-Diagramm verwendeten Symbole entnehmen Sie dem Abschnitt Syntax-Symbole.

Verwandte Statements: `ACCEPT/REJECT` | `AT BREAK` | `AT START OF DATA` | `AT END OF DATA` | `BACKOUT TRANSACTION` | `BEFORE BREAK PROCESSING` | `DELETE` | `END TRANSACTION` | `FIND` | `GET` | `GET SAME` | `GET TRANSACTION DATA` | `LIMIT` | `PASSW` | `PERFORM BREAK PROCESSING` | `READ` | `RETRY` | `STORE` | `UPDATE`

Gehört zur Funktionsgruppe: Datenbankzugriffe und Datenbankänderungen

## Funktion

Das Statement `HISTOGRAM` dient dazu, Werte eines Datenbankfeldes, das als Deskriptor, Subdeskriptor oder Superdeskriptor definiert ist, zu lesen. Die Werte werden direkt von der Adabas Invertierten Liste (bzw. dem VSAM-Index) gelesen. Das `HISTOGRAM`-Statement löst zwar eine Verarbeitungsschleife aus, es kann aber auf keine anderen Datenbankfelder als auf das mit dem `HISTOGRAM`-Statement angegebene Feld zugegriffen werden.

Siehe auch folgende Abschnitte im Leitfaden zur Programmierung.

- HISTOGRAM-Statement

- Schleifenverarbeitung

- Datenbankfelder mit der (r)-Notation referenzieren

Anmerkung
Bei SQL-Datenbanken: Mit `HISTOGRAM` erhalten Sie die Anzahl der Reihen, die in einer bestimmten Spalte den gleichen Wert haben.

## Einschränkungen

Dieses Statement kann nicht mit Entire System Server verwendet werden.

Bei einer VSAM-Datenbank gilt das `HISTOGRAM`-Statement nur für KSDS und ESDS.

## Syntax-Beschreibung

Operanden-Definitionstabelle:

Operand | Mögliche Struktur | Mögliche Formate | Referenzierung erlaubt | Dynam. Definition
--- | --- | --- | --- | ---
operand1 | C | S |  |  |  |  |  | N | P | I |  | B * |  |  |  |  |  |  | ja | nein
operand2 | C | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  |  | ja | nein
operand3 |  | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  |  | ja | nein
operand4 |  | S |  |  |  | A |  | N | P | I | F | B | D | T | L |  |  |  | nein | nein

* Format B von operand1 kann nur mit einer Länge von kleiner gleich 4 benutzt werden.

Syntax-Element-Beschreibung:

Syntax-Element | Beschreibung
--- | ---
`operand1 / ALL` | Anzahl der Deskriptorwerte: Sie können die Anzahl der Deskriptorwerte, die mit dem `HISTOGRAM`-Statement gelesen werden sollen, auf eine bestimmte Zahl (operand1) begrenzen, die Sie entweder als numerische Konstante (`0` bis `99999999`) oder über eine Benutzervariable (die einen Ganzzahlwert enthält) angeben. Andernfalls werden alle Deskriptorwerte gelesen, was Sie zusätzlich durch das Schlüsselwort `ALL` hervorheben können. Das mit operand1 angegebene Limit hat bei diesem Statement Vorrang vor einem mit einem `LIMIT`-Statement gesetzten Limit. Ist mit dem Profilparameter `LT` ein kleineres Limit gesetzt, so gilt das `LT`-Limit. Anmerkungen: Wenn Sie eine vierstellige Anzahl von Deskriptorwerten lesen möchten, geben Sie diese mit einer vorangestellten Null an: `(0nnnn)`; denn Natural interpretiert jede vierstellige Zahl in Klammern als Zeilennummer-Referenzierung auf ein Statement. operand1 wird zu Beginn des ersten `HISTOGRAM`-Schleifendurchlaufs ausgewertet. Wird der Wert von operand1 innerhalb der `HISTOGRAM`-Schleife geändert, hat dies keine Auswirkungen auf die Anzahl der gelesenen Werte.
`MULTI-FETCH-clause` | MULTI-FETCH-Klausel: Siehe MULTI-FETCH-Klausel weiter unten.
`view-name` | View-Name: Als view-name geben Sie den Namen eines Views an, der entweder in einem `DEFINE DATA`-Block oder in einer programmexternen Global oder Local Data Area definiert ist. Der View darf außer dem im `HISTOGRAM`-Statement verwendeten Feld (operand4) keine anderen Felder enthalten. Ist das im View definierte Feld ein in einer Periodengruppe enthaltenes Feld oder ein multiples Feld, das mit einem Indexbereich definiert ist, dann wird jeweils nur die erste Ausprägung dieses Bereiches vom `HISTOGRAM`-Statement gefüllt; alle anderen Ausprägungen bleiben von der Ausführung des `HISTOGRAM`-Statements unberührt. Im Reporting Mode ist view-name der Name eines DDM, falls kein `DEFINE DATA LOCAL`-Statement benutzt wird.
`PASSWORD`=operand2 | PASSWORD-Klausel: Die `PASSWORD`-Klausel dient dazu, ein Passwort (operand2) anzugeben, um auf Daten einer passwort-geschützten Adabas-Datei zugreifen zu können. Weitere Informationen hierzu siehe `FIND`-Statement und `PASSW`-Statement.
`SEQUENCE` | SEQUENCE-Klausel Die Klausel gilt nur für Adabas-, VSAM- und SQL-Datenbanken. Mit dieser Klausel können Sie bestimmen, ob die Werte in aufsteigender Reihenfolge oder in absteigender Reihenfolge gelesen werden sollen. Standardmäßig werden die Werte in aufsteigender Reihenfolge gelesen (was Sie mit dem Schlüsselwort `ASCENDING` auch ausdrücklich angeben können, aber nicht müssen). Wenn die Werte in absteigender Reihenfolge gelesen werden sollen, geben Sie das Schlüsselwort `DESCENDING` an. Wenn erst zur Laufzeit bestimmt werden soll, ob die Werte in aufsteigender oder absteigender Reihenfolge gelesen werden sollen, geben Sie das Schlüsselwort `VARIABLE` oder `DYNAMIC` gefolgt von einer Variablen (operand3) an. Der Wert von operand3 zu Beginn der `HISTOGRAM`-Verarbeitungsschleife bestimmt dann die Reihenfolge. operand3 muss Format/Länge A1 haben und kann den Wert `A` (für `ASCENDING` = aufsteigend) oder `D` (für `DESCENDING` = absteigend) enthalten. Wenn das Schlüsselwort `VARIABLE` benutzt wird, wird die Leserichtung (Wert von operand3) beim Start der `HISTOGRAM`-Verarbeitungsschleife ausgewertet, und bleibt dieselbe, bis die Schleife beendet wird, ungeachtet der Tatsache, ob das Feld für operand3 in der `HISTOGRAM`-Schleife geändert wird oder nicht. Wenn das Schlüsselwort `DYNAMIC` benutzt wird, wird die Leserichtung (Wert von operand3) vor jedem Einlesen eines Datensatzes in der `HISTOGRAM`-Verarbeitungsschleife ausgewertet und kann von Datensatz zu Datensatz geändert werden. Dies ermöglicht das Ändern der Blätter-Reihenfolge von aufsteigend in absteigend (und umgekehrt) an einer beliebigen Stelle in der `HISTOGRAM`-Schleife. Beispiele für `SEQUENCE`-Klausel: Beispiel 2 − HISTOGRAM-Statement mit in absteigender Reihenfolge gelesenen Sätzen Beispiel 3 − HISTOGRAM-Statement mit variabler Reihenfolge
`operand4` | Deskriptor: Als operand4 kann ein Deskriptor, ein Subdeskriptor, ein Superdeskriptor oder ein Hyperdeskriptor angegeben werden. Ein Deskriptorfeld, das Teil einer Periodengruppe ist, kann entweder mit oder ohne Index angegeben werden. Wird kein Index angegeben, so wird ein Datensatz ausgewählt, wenn der Suchwert in irgendeiner Ausprägung gefunden wird. Wird ein Index angegeben, so wird ein Datensatz nur ausgewählt, wenn der Suchwert in der im Index angegebenen Ausprägung gefunden wird. Es muss ein konstanter Index angegeben werden; es darf kein Indexbereich angegeben werden. Ist das angegebene Deskriptorfeld ein multiples Feld, darf kein Index angegeben werden. Ein Datensatz wird ausgewählt unabhängig davon, in welcher Ausprägung des Feldes der Suchwert gefunden wird.
`STARTING-ENDING-clause` | STARTING/ENDING-Klausel: Mit den Schlüsselwörtern `STARTING` und `ENDING` (bzw. `THRU`) können Sie einen Startwert und einen Endwert angeben, und zwar in Form einer Konstanten oder einer Benutzervariablen. Damit legen Sie fest, ab welchem Wert und bis zu welchem Wert gelesen werden soll. Weitere Informationen siehe Start-/Endwerte angeben weiter unten.
`WHERE` `logical-condition` | WHERE-Klausel: Mit der `WHERE`-Klausel können Sie ein zusätzliches Selektionskriterium in Form einer logischen Bedingung (logical-condition) angeben. Dies wird ausgewertet, nachdem ein Wert gelesen wurde, aber bevor eine weitere Verarbeitung auf der Grundlage dieses Wertes (einschließlich `AT BREAK`-Verarbeitung) erfolgt. Der in der `WHERE`-Klausel angegebene Deskriptor muss mit dem im `HISTOGRAM`-Statement referenzierten Deskriptor identisch sein. Keine anderen Felder von der ausgewählten Datei stehen zur Verarbeitung bei einem `HISTOGRAM`-Statement zur Verfügung. Die Syntax für eine logical-condition ist im Abschnitt Logische Bedingungen im Leitfaden zur Programmierung beschrieben.
`END-HISTOGRAM` | Ende des HISTOGRAM-Statements: Im Structured Mode muss das für Natural reservierte Schlüsselwort `END-HISTOGRAM` zum Beenden des `HISTOGRAM`-Statements benutzt werden. Im Reporting Mode wird das Natural-Statement `LOOP` zum Beenden des `HISTOGRAM`-Statements benutzt.
`LOOP`

#### MULTI-FETCH-Klausel

Anmerkung
Diese Klausel kann nur bei Adabas- oder Db2-Datenbanken benutzt werden.

| `MULTI-FETCH` |  | `ON` |  |
`OFF`
[`OF`] multi-fetch-factor

Weitere Informationen siehe Multi-Fetch-Klausel (Adabas) im Leitfaden zur Programmierung oder Multiple Row Processing (SQL) im Natural for Db2-Teil der Database Managment System Interfaces-Dokumentation.

### Start-/Endwerte angeben

Mit den Schlüsselwörtern `STARTING` und `ENDING` (bzw. `THRU`) können Sie einen Startwert und einen Endwert angeben, und zwar in Form einer Konstanten oder einer Benutzervariablen. Damit legen Sie fest, ab welchem Wert und bis zu welchem Wert gelesen werden soll.

Wenn der angegebene Startwert nicht vorhanden ist, wird der nächsthöhere vorhandene Wert als Startwert genommen. Ist kein höherer Wert vorhanden, wird die `HISTOGRAM`-Schleife nicht ausgeführt.

Wenn Sie einen Endwert angeben, wird bis einschließlich des Endwertes gelesen.

Für Deskriptoren des Formats A oder B können hexadezimale Konstanten als Start- und Endwert angegeben werden.

Syntax-Option 1:

| [`STARTING`] |  | `WITH` |  | [`VALUES`] operand5 |  |  |  |  | `THRU` |  | operand6 |
`FROM` | `ENDING AT`

Syntax-Option 2:

[`STARTING`] |  | `WITH FROM` |  | [`VALUES`] operand5 | `TO` | operand6

Syntax-Option 3:

| < |  | operand5
`LT`
`LESS THAN`
>
`GT`
`GREATER THAN`
`<=`
`LE`
`LESS EQUAL`
`>=`
`GE`
`GREATER EQUAL`

Anmerkung
Wenn die Vergleichsoperatoren von Diagramm 3 benutzt werden, dürfen die Optionen `ENDING AT`, `THRU` und `TO` nicht benutzt werden. Diese Vergleichsoperatoren sind auch für das `READ`-Statement gültig.

Operanden-Definitionstabelle:

Operand | Mögliche Struktur | Mögliche Formate | Referenzierung erlaubt | Dynam. Definition
--- | --- | --- | --- | ---
operand5 | C | S |  |  |  | A | U | N | P | I | F | B | D | T | L |  |  |  | ja | nein
operand6 | C | S |  |  |  | A | U | N | P | I | F | B | D | T | L |  |  |  | ja | nein

Syntax-Element-Beschreibung:

Syntax-Element | Beschreibung
--- | ---
`STARTING FROM ... ENDING AT/TO` | STARTING FROM / ENDING AT-Klauseln: Diese Klauseln werden benutzt, um das Lesen auf einen vom Benutzer angegebenen Bereich von Werten einzuschränken. Die `STARTING FROM`-Klausel (= oder `EQ` oder `EQUAL TO` oder `[STARTING] FROM`) legt den Startwert für die Lese-Operation fest. Wenn ein Startwert angegeben wird, beginnt der Lesevorgang bei dem angegebenen Wert. Wenn der Startwert nicht vorhanden ist, wird der nächsthöhere Wert (oder nächstniedrigere Wert für einen absteigenden Lesevorgang) zurückgegeben. Ist kein höherer Wert (oder niedrigerer Wert für `DESCENDING`) vorhanden, wird die `HISTOGRAM`-Schleife nicht ausgeführt. Um die Werte auf einen Endwert zu beschränken, können Sie eine `ENDING AT`-Klausel bei den Schlüsselwörtern `THRU`, `ENDING AT` oder `TO` angeben, die einen einschließenden Bereich implizieren. Immer wenn das Deskriptorfeld den angegebenen Endwert überschreitet, erfolgt eine automatische Beendigung der Schleife. Obwohl die Basis-Funktionalität der Schlüsselwörter `TO`, `THRU` und `ENDING AT` ähnlich ist, so unterscheiden sie sich doch intern durch ihre Funktionsweise.
`THRU/ENDING AT` | THRU / ENDING AT-Option: Wird `THRU` oder `ENDING AT` benutzt, wird nur der Startwert der Datenbank bekannt gegeben; es wird aber vom Natural-Laufzeitsystem eine Prüfung auf den Endwert vorgenommen, nachdem der Wert von der Datenbank zurückgegeben worden ist. Die Klauseln `THRU` und `ENDING AT` können für alle Datenbanken benutzt werden, die die `HISTOGRAM`-Statements unterstützen.
`TO` | Bereich: Wird das Schlüsselwort `TO` benutzt, werden sowohl der Startwert als auch der Endwert der Datenbank übergeben, und Natural prüft nicht auf Wertebereiche ab. Wenn der Endwert überschritten wird, reagiert die Datenbank genauso, als sei das Dateiende (End-of-File) erreicht worden, und die Datenbank-Schleife wird verlassen. Da die ganzen Bereichsprüfungen von der Datenbank durchgeführt werden, wird der niedrigere Wert (des Bereichs) immer beim Startwert und der höhere Wert beim Endwert angegeben, ganz gleich ob Sie einen Lesevorgang in aufsteigender (`ASCENDING`) oder absteigender (`DESCENDING`) Reihenfolge durchführen.

Anmerkung
Das Ergebnis von `READ`/`HISTOGRAM` `THRU`/`ENDING AT` kann vom Ergebnis bei `READ`/`HISTOGRAM` `TO` abweichen, wenn Natural und die Datenbank, auf die zugegriffen wird, sich auf verschiedenen Plattformen mit unterschiedlichen Sortierfolgen befinden.

## Bei HISTOGRAM verfügbare Systemvariablen

Die Natural-Systemvariablen `*ISN`, `*NUMBER` und `*COUNTER` können bei einem `HISTOGRAM`-Statement verwendet werden.

`*NUMBER` und `*ISN` stehen erst nach Auswertung der `WHERE`-Klausel zur Verfügung. Sie dürfen nicht innerhalb der logischen Bedingung einer `WHERE`-Klausel eingesetzt werden.

Systemvariable | Erläuterung
--- | ---
`*NUMBER` | Die Systemvariable `*NUMBER` enthält die Anzahl der Datensätze, die den zuletzt gelesenen Wert enthalten. Bezüglich SQL-Datenbanken siehe *NUMBER bei SQL Datenbanken in der Systemvariablen-Dokumentation.
`*ISN` | Die Systemvariable `*ISN` enthält die Nummer der Ausprägung einer Periodengruppe des aktuellen Datensatzes, die den zuletzt gelesenen Wert enthält. Ist der Deskriptor nicht in einer Periodengruppe enthalten, enthält `*ISN` den Wert `0`. Bei SQL- und VSAM-Datenbanken kann `*ISN` nicht verwendet werden.
`*COUNTER` | Die Systemvariable `*COUNTER` enthält die Gesamtzahl der bisher gelesenen Werte (nach Auswertung der `WHERE`-Klausel).

## Beispiele

- Beispiel 1 - HISTOGRAM-Statement

- Beispiel 2 - HISTOGRAM-Statement mit in absteigender Reihenfolge gelesenen Sätzen

- Beispiel 3 - HISTOGRAM-Statement mit variabler Reihenfolge

### Beispiel 1 - HISTOGRAM-Statement

    ** Example 'HSTEX1S': HISTOGRAM (structured mode)
    ************************************************************************
    DEFINE DATA LOCAL
    1 EMPLOY-VIEW VIEW OF EMPLOYEES
      2 CITY
    END-DEFINE
    *
    LIMIT 8
    HISTOGRAM EMPLOY-VIEW CITY STARTING FROM 'M'
      DISPLAY NOTITLE
              CITY 'NUMBER OF/PERSONS' *NUMBER *COUNTER
    END-HISTOGRAM
    *
    END

Ausgabe des Programms `HSTEX1S`:

            CITY          NUMBER OF     CNT
                           PERSONS
    -------------------- ----------- -----------

    MADISON                        3           1
    MADRID                        41           2
    MAILLY LE CAMP                 1           3
    MAMERS                         1           4
    MANSFIELD                      4           5
    MARSEILLE                      2           6
    MATLOCK                        1           7
    MELBOURNE                      2           8

Äquivalentes Reporting Mode-Beispiel: `HSTEX1R`.

### Beispiel 2 - HISTOGRAM-Statement mit in absteigender Reihenfolge gelesenen Sätzen

    ** Example 'HSTDSCND': HISTOGRAM (with DESCENDING)
    ***********************************************************************
    DEFINE DATA LOCAL
    1 EMPL VIEW OF EMPLOYEES
      2 NAME
    END-DEFINE
    *
    HISTOGRAM (10) EMPL IN DESCENDING SEQUENCE FOR NAME FROM 'ZZZ'
      DISPLAY NAME *NUMBER
    END-HISTOGRAM
    END

Ausgabe des Programms `HSTDSCND`:

    Page      1                                                  05-01-13  13:41:03

            NAME            NMBR
    -------------------- -----------

    ZINN                           1
    YOT                            1
    YNCLAN                         1
    YATES                          1
    YALCIN                         1
    YACKX-COLTEAU                  1
    XOLIN                          1
    WYLLIS                         2
    WULFRING                       1
    WRIGHT                         1

### Beispiel 3 - HISTOGRAM-Statement mit variabler Reihenfolge

    ** Example 'HSTVSEQ': HISTOGRAM (with VARIABLE SEQUENCE)
    ***********************************************************************
    DEFINE DATA LOCAL
    1 EMPL VIEW OF EMPLOYEES
      2 NAME
    *
    1 #DIR      (A1)
    1 #STARTVAL (A20)
    END-DEFINE
    *
    SET KEY PF3 PF7 PF8
    *
    MOVE 'ADKINSON' TO #STARTVAL
    *
    HISTOGRAM (9) EMPL FOR NAME FROM #STARTVAL
      WRITE NAME *NUMBER
      IF *COUNTER = 5
        MOVE NAME TO #STARTVAL
      END-IF
    END-HISTOGRAM
    *
    #DIR := 'A'
    *
    REPEAT
      HISTOGRAM EMPL IN VARIABLE #DIR SEQUENCE
                FOR NAME FROM #STARTVAL
        MOVE NAME TO #STARTVAL
        INPUT NO ERASE  (IP=OFF AD=O)
              15/01 NAME *NUMBER
              //   'Direction:' #DIR
              //   'Press PF3 to stop'
              /    '      PF7 to go step back'
              /    '      PF8 to go step forward'
              /    '      ENTER to continue in that direction'
        /*
        IF *PF-KEY = 'PF7' AND #DIR = 'A'
          MOVE 'D' TO #DIR
          ESCAPE BOTTOM
        END-IF
        IF *PF-KEY = 'PF8' AND #DIR = 'D'
          MOVE 'A' TO #DIR
          ESCAPE BOTTOM
        END-IF
        IF *PF-KEY = 'PF3'
          STOP
        END-IF
      END-HISTOGRAM
      /*
      IF *COUNTER(0250) = 0
        STOP
      END-IF
    END-REPEAT
    END

Ausgabe des Programms `HSTVSEQ`:

    Page      1                                                  05-01-13  13:50:31

    ADKINSON                       8
    AECKERLE                       1
    AFANASSIEV                     2
    AHL                            1
    AKROYD                         1
    ALEMAN                         1
    ALESTIA                        1
    ALEXANDER                      5
    ALLEGRE                        1

    MORE

Nach Drücken von EINGABE:

    Page      1                                                  05-01-13  13:50:31

    ADKINSON                       8
    AECKERLE                       1
    AFANASSIEV                     2
    AHL                            1
    AKROYD                         1
    ALEMAN                         1
    ALESTIA                        1
    ALEXANDER                      5
    ALLEGRE                        1

    AKROYD                         1

    Direction: A

    Press PF3 to stop
          PF7 to go step back
          PF8 to go step forward
          ENTER to continue in that direction

### On this page

- Funktion
- Einschränkungen
- Syntax-Beschreibung
- Bei HISTOGRAM verfügbare Systemvariablen
- Beispiele