HISTOGRAM

HISTOGRAM

ALL

[MULTI-FETCH-clause ] [multi-fetch-factor] [IN] [FILE] view-name
(operand1)
[PASSWORD=operand2]

[IN]

ASCENDING

[SEQUENCE]

DESCENDING
VARIABLE operand3
DYNAMIC operand3
[VALUE] [FOR] [FIELD] operand4
[STARTING/ENDING-clause]
[WHERE logical-condition]
statement
END-HISTOGRAM [(r)] (structured mode only)
LOOP [(r)] (reporting mode only)

Dieser Abschnitt behandelt folgende Themen:

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 HISTOGRAM

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.

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

Einschränkungen HISTOGRAM

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 HISTOGRAM

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:

  1. 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.
  2. 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:

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 (r)
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 Structured Mode können Sie bei END-HISTOGRAM Labels oder Zeilennummern angeben.

Im Reporting Mode wird das Natural-Statement LOOP zum Beenden des HISTOGRAM-Statements benutzt.

Im Reporting Mode können Sie bei LOOP Labels oder Zeilennummern angeben.

LOOP (r)

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 Management 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 HISTOGRAM

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