home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / pascal / library / dos / pstoolbx / kalunit.doc < prev    next >
Encoding:
Text File  |  1993-07-28  |  17.2 KB  |  401 lines
  1. ╔════════════════════════════════════════════════════════════════════╗
  2. ║                                                                    ║
  3. ║                   ██▀▀▀▀▀▀▀▌  ██      ██  ██          ██           ║
  4. ║                   ██          ██      ██  ██          ██           ║
  5. ║                   ██          ██      ██  ██          ██▄▄▄▄▄▄▄    ║
  6. ║                   ██     ▀▀█  ██      ██  ██          ██       █   ║
  7. ║                   ██       █  ██      ██  ██       ▐  ██       █   ║
  8. ║                   ██████████  ██████████  ██████████  ██████████   ║
  9. ║                                                                    ║
  10. ║                                                                    ║
  11. ║   S O F T W A R E                                                  ║
  12. ║********************************************************************║
  13. ║*                                                                  *║
  14. ║*                   K A L E N D E R - T O O L B O X                *║
  15. ║*                                                                  *║
  16. ║*  VERSION 2.00                          (c) 1989,91 G. Blumert    *║
  17. ║********************************************************************║
  18. ╚════════════════════════════════════════════════════════════════════╝
  19.  
  20. Gunnar Blumert                                  Burg, im April    1991
  21. Hochdonner Chaussee 16
  22.  
  23. 2224 Burg/Dithm.
  24.  
  25.  
  26. Bankverbindung: Postgiroamt Hamburg (BLZ 200 100 20)
  27.                 Konto - Nr. 3979 41-206
  28.  
  29.  
  30.  
  31. 1. Was kann man mit der Kalender-Toolbox machen?
  32.  
  33. Diese Toolbox deckt alles ab, was die Kalenderrechnung vom Programmierer
  34. verlangt, von der einfachen Wochentags-Berechnung bis hin zu komplexen
  35. Fenstern, die vielerlei Informationen darstellen.
  36. Dabei unterstützt die Toolbox nicht nur den heute üblichen gregorianischen
  37. Kalender, sondern auch den hebräischen, julianischen, moslemischen und den
  38. der französischen Revolution.
  39.  
  40. Die Units sind nur verwendungsfähig unter Turbo-Pascal 6.0 und Turbo-
  41. Vision. Allerdings verwenden die eigentlichen Kalender-Units lediglich
  42. Kollektionen (anstelle von selbst konstruierten verketteten Listen) und
  43. die Funktion MemAlloc der Unit MEMORY. Besitzer der Version 5.5 können
  44. die entsprechenden Passagen des Quelltextes leicht ändern (MemAlloc durch
  45. GetMem ersetzen und Kollektionen selber basteln).
  46. Mit noch früheren Compilerversionen wird es allerdings schwierig, denn
  47. die Unit stützt sich voll auf die virtuellen Mechanismen, die es seit der
  48. Einführung objektorientierter Erweiterungen gibt.
  49.  
  50.  
  51. 2. Was ist auf der Diskette?
  52.  
  53. KALDEF.TPU      implementiert ein abstraktes Kalendarium
  54. F_KAL.TPU       implementiert das Kalendarium d. franz. Rev.
  55. G_KAL.TPU       implementiert den gregorianischen Kalender
  56. H_KAL.TPU       implementiert den hebräischen Kalender
  57. J_KAL.TPU       implementiert den julianischen Kalender
  58. M_KAL.TPU       implementiert den moslemischen Kalender
  59.  
  60. TABELLEN.TPU    enthält Tabellen für Osterfest- und Mondphasenberechnung
  61.                 wird von KALDEF und G_KAL benötigt
  62.  
  63. F_KAL.GK3       Definitionsdatei für den fr. Kal.
  64. G_BRDKAL.GK3            "        für den greg. Kal.
  65. H_KAL.GK3               "        für den heb. Kal.
  66. J_KAL.GK3               "        für den jul. Kal.
  67. M_KAL.GK3               "        für den mosl. Kal. (astronomisch)
  68. M_KAL2.GK3              "        für den mosl. Kal. (nicht astronomisch)
  69.  
  70. MAKEFKAL.PAS    erstellt F_KAL.GK3
  71. MBRDKAL.PAS     erstellt G_BRDKAL.GK3
  72. MAKEHKAL.PAS    erstellt H_KAL.GK3
  73. MAKEJKAL.PAS    erstellt J_KAL.GK3
  74. MAKEMKAL.PAS    erstellt M_KAL.GK3
  75. MMKAL2.PAS      erstellt M_KAL2.GK3
  76.  
  77. KALDEMO.EXE     Turbo-Vision - Demonstrationsprogramm für die Kalendarien
  78. KALDEMO.PAS
  79.  
  80. KALWIN.TPU      Enthält die View-Objekte des Demonstrationsprogramms
  81.  
  82. KALLIST.TPU     Enthält eine Liste zur Aufnahme von Kalendarien - wird von
  83.                 KALDEMO benötigt
  84.  
  85. KALDOS.TPU      Enthält Routinen, die man in jedem Programm brauchen kann;
  86. KALDOS.PAS      wird von KALDEMO benötigt.
  87.  
  88. KALCOMS.TPU     Enthält einige Konstantendeklarationen, z. B. die Kommandos
  89. KALCOMS.PAS     für die HandleEvent-Messages
  90.  
  91. Die nicht aufgeführten Quelltexte erhalten nur Anwender, die sich bei mir
  92. haben registrieren lassen. Der Preis beträgt DM 188,-- .
  93. Die Shareware-Versionen enthalten stattdessen Dateien mit der Extension .INT
  94. (für IINTERFACE), in denen der Interface-Teil der Units dokumentiert ist.
  95.  
  96.  
  97. 3. Wie funktioniert das?
  98.  
  99. Sie können diese Tollbox in drei Stufen nutzen: nur die Algorithmen, zusätz-
  100. lich die Berechnung der Feiertage, schließlich komplette View-Objekte, die
  101. Sie direkt in ein Turbo-Vision-Programm einbinden können.
  102.  
  103. Zunächst drucken Sie sich bitte den INTERFACE-Teil der Unit KALDEF.PAS aus
  104. (bzw. die Datei KALDEF.INT), um einen Überblick über die Funktionen zu er-
  105. halten.
  106.  
  107. KALDEF implementiert ein Objekt KALENDARIUM, das allerdings noch viele
  108. abstrakte Methoden enthält.
  109. Allerdings können Sie alle Funktionen auf ein beliebiges Kalendarium anwen-
  110. den, wenn Sie ein Kalendarieum aus den *_KAL.TPU - Dateien initialisiert
  111. haben.
  112. Dies erledigen Sie am einfachsten über einen Aufruf des INIT-Konstruktors.
  113. Dabei werden allerdings die Listen, die Wochentags-, Monats- und Feiertags-
  114. namen sowie deren Zuordnung enthält, nicht initialisiert.
  115. Sie können zwar alle Algorithmen benutzen; die Funktionen, die Feiertage be-
  116. stimmen, werden jedoch jeden Tag für einen Werktag halten.
  117.  
  118. Die Informationen über Feiertage etc. sind in .GK3 Dateien enthalten.
  119. Deren Aufbau ist aus den MAKE*KAL - Programmen ersichtlich.
  120.  
  121. Um eine solche Datei zu laden und mit einem Kalendarium zu verknüpfen,
  122. müssen Sie den Konstruktor LOAD aufrufen, der als Parameter den Datei-
  123. namen erwartet.
  124. Danach stehen Ihnen alle Funktionen uneingeschränkt zur Verfügung mit einer
  125. Ausnahme: Die Funktion Goldene_Zahl steht nur im gregorianischen und im
  126. julianischen Kalender zur Verfügung! In den anderen ist sie wenig sinnvoll,
  127. denke ich, wer will, kann sie ja selbst "nachrüsten".
  128.  
  129. Schließlich gibt es noch drei View-Objekte, die sich in der Unit KALWIN
  130. befinden.
  131. Deren Verwendung entnehmen Sie dem Programm KALDEMO.PAS, das im Quelltext
  132. beiliegt.
  133.  
  134.  
  135. 4. Die Feiertage
  136.  
  137.   Die Feiertage werden in folgendermaßen in den .GK3-Dateien gespeichert:
  138.   Zunächst werden die Namen aufgeführt, darauf folgen, in der gleichen
  139.   Reihenfolge, die Tabellen, die die Lage des Feiertages im Jahr beschrei-
  140.   ben.
  141.   Dises Tabellen sind folgendermaßen definiert:
  142.  
  143.   Feiertagstabelle = RECORD
  144.                    beachten    : BOOLEAN;
  145.                    JMin, JMax  : INTEGER;
  146.                    CASE Art: CHAR OF
  147.                      'A','O': (Differenz: INTEGER);
  148.                      'W': (T_min, Dummy: WORD; Wochentagnummer: BYTE);
  149.                      'D': (Tagnummer: WORD);
  150.                      'S': (Nummer: INTEGER)
  151.  
  152.   Die Variable BEACHTEN kann in Ihren eigenen Programmen von Nutzen sein,
  153.   wenn Sie z. B. den Rosenmontag zwar als Feiertag anzeigen wollen, der Tag
  154.   aber trotzdem als normaler Werktag gelten soll.
  155.   In diesem Fall setzen Sie BEACHTEN auf FALSE.
  156.  
  157.   JMin und JMax geben den Zeitraum an, in dem der Feiertag angezeigt werden
  158.   soll.
  159.   Soll die Anzeige nach oben oder unten unbegenzt erfolgen, geben Sie für
  160.   den entsprechenden Wert eine 0 an.
  161.  
  162.   Wie Sie wissen, gibt es unterschiedliche Arten von Feiertagen, nämlich
  163.   feste und bewegliche.
  164.   Diese Festlegung treffen Sie im varianten Teil des RECORDS.
  165.  
  166.   'A' steht für Abhängigkeit vom 1. Advent, O für Ostersonntag.
  167.   Mit Differenz geben Sie den Abstand vom 1. Advent/Ostersonntag an. Dieser
  168.   kann auch negativ sein (z. B. -2 für Karfreitag).
  169.   Wenn Sie den Abstand so groß wählen, daß das Datum in ein anderes Jahr
  170.   fallen würde, haben Sie allerdings Pech gehabt: der Feiertag wird dann
  171.   nicht mehr angezeigt.
  172.  
  173.   'W' steht für einen Feiertag, der auf das erste Auftreten eines Wochentages
  174.   ab dem durch T_min bezeichneten Tag des Jahres. Dabei ist als T_min die
  175.   laufende Nummer des Tages in nicht-Schaltjahren anzugeben.
  176.   Die Wochentagnummer entspricht den von der Funktion Ermittle_Wochentagnummer
  177.   zurückgegebenen Werten: 0 = Montag, ...
  178.   Ein Beispiel: für den Muttertag (zweiter Sonntag im Mai) wäre anzugeben
  179.   T_min = 128 und Wochentagnummer = 6.
  180.   Aus "historischen" Gründen gibt es noch das Dummy-Feld, in dem früher
  181.   einmal T_max abgelegt werden mußte.
  182.   Der Wert des Dummy-Feldes ist nunmehr gleichgültig und steht zu Ihrer
  183.   Verfügung.
  184.  
  185.   'D' bezeichnet Feiertage, die stets auf das gleiche Datum fallen. Die Tag-
  186.   nummer ist so zu ermittlen wie T_min für die Ar 'W'.
  187.   In den Kalendarien mit der Kennung F, H oder M wird für diese Art der je-
  188.   weilige Kennbuchstabe verwendet.
  189.   Die Art 'D' hat dort eine besondere Bedeutung, und zwar wird damit ein
  190.   Datum nach christlicher Chronologie bezeichnet. Dazu wird der gregoriani-
  191.   sche Kalender verwendet, falls er gültig ist, anderenfalls der julianische.
  192.   Sie können so z. B. im hebräischen Kalender auch das christliche Weih-
  193.   nachtsfest beobachten.
  194.  
  195.   'S' bezeichnet den Schalttag in Schaltjahren.
  196.   Da der hebräische Kalender einen ganzen Schaltmonat einschiebt, können
  197.   Sie in dem Fall die Nummer des Tages im Schaltmonat in das Feld NUMMER
  198.   eintragen.
  199.   In allen anderen Kalendarien wird das Feld NUMMER ignoriert.
  200.  
  201.  
  202. 5. Die einzelnen Routinen
  203.  
  204.     CONSTRUCTOR Load(Name: pathstr);  
  205.     Lädt die angegebene Kalenderdefinitionsdatei und initialisiert das
  206.     Objekt.
  207.  
  208.     CONSTRUCTOR INIT;
  209.     Initialisiert das Objekt, ohne Feiertagstabellen zu initialisieren.
  210.  
  211.     DESTRUCTOR DONE; VIRTUAL;
  212.     Räumt den Heap wieder auf und sollte immer aufgerufen werden, wenn
  213.     ein Objekt nicht mehr benötigt wird. Auch dann, wenn Sie selber keine
  214.     dynamischen Datenstrukturen erzeugen - die Kalendarien tun dies!
  215.     Zuvor wird das Feld "Changed" überprüft, und, wenn TRUE, die Prozedur
  216.     Store aufgerufen.
  217.     Sofern Sie dem Anwender das Ändern der Kalendarien erlauben, sollten Sie
  218.     die Prozedur Store besser vorher aufrufen, denn ein Destruktoraufruf
  219.     kann nicht rückgängig gemacht werden, wenn etwa ein Schreibfehler aufge-
  220.     treten ist.
  221.  
  222.     PROCEDURE Store;
  223.     Schreibt das Kalendarium wieder zurück auf die Platte. Diese Funktion
  224.     wird nur benötigt, wenn Sie dem Anwender erlauben, die Kalendarien zu
  225.     ändern.
  226.  
  227.     PROCEDURE InitDate; VIRTUAL;
  228.     Setzt das interne Datum des Kalendariums auf das aktuelle Rechnerdatum,
  229.     sofern dieses für das Kalendarium gültig ist. Anderenfalls wird der An-
  230.     fang des Gültigkeitsbereiches eingestellt.
  231.  
  232.     FUNCTION Valid: BOOLEAN; VIRTUAL;
  233.     Gibt TRUE zurück, wenn bei der Initialisierung kein Fehler auftrat und
  234.     sollte vor der Benutzung des Objekts stets abgefragt werden.
  235.  
  236.     PROCEDURE KGetDate(VAR t,m,j: INTEGER);
  237.     Ermittelt das interne Datum des Kalendariums.
  238.  
  239.     PROCEDURE KSetDate(t,m,j: INTEGER);
  240.     Setzt das interne Datum des Kalenders neu.
  241.  
  242.     FUNCTION Date_JD(t,m,j: INTEGER): LongInt;           VIRTUAL;
  243.     Rechnet Tag, Monat, Jahr in julianische Tagnummer (JD) um.
  244.  
  245.     PROCEDURE JD_Date(jd: LongInt; VAR t,m,j: INTEGER);  VIRTUAL;
  246.     Rechnet julianische Tagnummer in Tag, Monat, Jahr um.
  247.  
  248.     FUNCTION MakeJD(nr, j: INTEGER): LongInt;
  249.     Ermittlet aus laufender Nummer des Tages im Jahr und Jahreszahl die
  250.     julianische Tagnummer.
  251.  
  252.     FUNCTION FirstJ: INTEGER;  VIRTUAL;
  253.  
  254.     FUNCTION LastJ : INTEGER;  VIRTUAL;
  255.     Gibt letztes Jahr der Gültigkeit des Kalendariums zurück.
  256.  
  257.     FUNCTION FirstJD:LongInt;  VIRTUAL;
  258.     Gibt ersten julianischen Tag (JD) der Gültigkeit zurück.
  259.  
  260.     FUNCTION LastJD: LongInt;  VIRTUAL;
  261.     Gibt letzten julianischen Tag (JD) der Gültigkeit zurück.
  262.  
  263.     FUNCTION Check_Date(t,m,j: INTEGER):BOOLEAN;
  264.     Gibt TRUE zurück, wenn Datum innerhalb der Gültigkeit.
  265.  
  266.     FUNCTION Check_Day(t,m,j: INTEGER): BOOLEAN;
  267.     TRUE, wenn Tag gültig. Geht davon aus, das Monat und Jahr gültig sind!
  268.  
  269.     FUNCTION Check_Month(m,j: INTEGER): BOOLEAN;
  270.     TRUE, wenn Monat gültig. Geht davon aus, das Jahr gültig ist.
  271.  
  272.     FUNCTION Check_Year(j: INTEGER):    BOOLEAN; VIRTUAL;
  273.     TRUE, wenn Jahr innerhalb der Gültigkeit.
  274.  
  275.     FUNCTION Check_JD(jd: LongInt):     BOOLEAN;
  276.     TRUE, wenn jul. Tagnummer (JD) gültig.
  277.  
  278.     Die folgenden Funktionen dienen zum weiterzählen von Kalenderdaten. Sie
  279.     geben TRUE zurück, wenn das neue Datum im Gültigkeitsbereich ist.
  280.  
  281.     FUNCTION Inc_Tag(VAR t,m,j: INTEGER): BOOLEAN;
  282.     FUNCTION Dec_Tag(VAR t,m,j: INTEGER): BOOLEAN;
  283.     Zählt einen Tag vor/zurück.
  284.  
  285.     FUNCTION Inc_Monat(VAR m,j: INTEGER): BOOLEAN;
  286.     FUNCTION Dec_Monat(VAR m,j: INTEGER): BOOLEAN;
  287.     Zählt einen Monat vor/zurück
  288.  
  289.     FUNCTION Inc_Jahr(count: INTEGER; VAR j: INTEGER): BOOLEAN; VIRTUAL;
  290.     Zählt Count Jahre vor bzw. zurück, wenn Count < 0.
  291.  
  292.     FUNCTION Anz_Tage(m,j: INTEGER):    BYTE;               VIRTUAL;
  293.     Gibt die Azahl der Tage des angegebenen Monats zurück.
  294.  
  295.     FUNCTION Anz_Monate(j: INTEGER): BYTE;                  VIRTUAL;
  296.     Gibt die Anzahl der Monate im Jahr J zurück.
  297.  
  298.     FUNCTION Monatname(m,j: INTEGER): STRING;               VIRTUAL;
  299.     Gibt den Namen des Monats als STRING zurück, allerdings nur, wenn
  300.     das Kalendarium über LOAD initialisiert wurde. Anderenfalls erhalten
  301.     Sie einen Leerstring.
  302.  
  303.     FUNCTION Julian_Year(jd: LongInt): INTEGER;
  304.     Ermittelt aus der jul. Tagnummer (JD) die Nummer des jul. Jahres.
  305.  
  306.     FUNCTION Schaltjahr(j: INTEGER): BOOLEAN;                VIRTUAL;
  307.     Gibt in Schaltjahren TRUE zurück.
  308.  
  309.     FUNCTION Ermittle_Wochentagnummer(t,m,j: INTEGER): BYTE; VIRTUAL;
  310.     0 = Montag
  311.  
  312.     FUNCTION RoemerZinsZahl(jj: INTEGER): BYTE;
  313.     Ermittelt die Indiktionszahl. JJ ist eine julianische Jahreszahl!
  314.  
  315.     FUNCTION GOLDENE_ZAHL(j: INTEGER): BYTE;                VIRTUAL;
  316.     Gibt die goldene Zahl für das Jahr J zurück. Ist nur für gregorianische
  317.     und julianische Kalendarien implementiert.
  318.  
  319.     FUNCTION TAG_IM_JAHR(t,m,j: INTEGER): INTEGER;          VIRTUAL;
  320.     Ermittelt die laufende Nummer des Tages im Jahr.
  321.  
  322.     PROCEDURE ERMITTLE_DATUM(nr: INTEGER; VAR t,m: INTEGER; j: INTEGER); VIRTUAL;
  323.     Eingabe: laufende Nummer des Tages und Jahr - Ausgabe: Tag und Monat.
  324.  
  325.     FUNCTION KAL_WO(t,m,j: INTEGER): BYTE;                   VIRTUAL;
  326.     Ermittelt aus dem Datum die Nummer der dazugehörigen Kalenderwoche.
  327.     Diese Funktion geht in der Regel davon aus, daß die Woche, in die
  328.     der erste Tag mit der Nummer 0 (Montag) fällt, die erste Kalenderwoche
  329.     ist.
  330.     Eine Funktion nach DIN 1355 ist in G_Kal.PAS implementiert.
  331.  
  332.     FUNCTION OSTERN(j: INTEGER): INTEGER;                   VIRTUAL;
  333.     Ermittelt die laufende Tagnummer von Ostersonntag.
  334.  
  335.     FUNCTION ADVENT(j: INTEGER): INTEGER;                   VIRTUAL;
  336.     Ermittelt die laufende Tagnummer des 1. Advent.
  337.  
  338.     FUNCTION IsFeiertag(tnr,t,m,j: INTEGER): BOOLEAN; VIRTUAL;
  339.     TRUE, wenn Datum ein Feiertag ist.
  340.  
  341.     PROCEDURE FTAG_NUMMER(nr, j: INTEGER; VAR FTs: FTagArr);
  342.     Gibt ein Array mit bis zu vier Feiertagen zurück, wenn mehrere auf den
  343.     gleichen Tag fallen. $ffff = ungültig!
  344.     nr enthält die laufende Nummer des Tages im Jahr.
  345.  
  346.     PROCEDURE GET_MoonMonth(mm,mj: INTEGER; VAR mond: mondmonat); VIRTUAL;
  347.     Gibt in Mond die Daten der drei am nächsten liegenden Vollmond/
  348.     Neumond - Daten zurück.
  349.     1..3 = Neumond, 4..6 = Vollmond; 0 ==> ungültig.
  350.  
  351.     FUNCTION MakeMoonString(m: INTEGER; index: BYTE; Mond: MondMonat): STRING;
  352.     Gibt Vollmond bzw. Neumond - Daten als String zurück.
  353.  
  354.     FUNCTION Werktag_im_Monat(tt,mm,jj: INTEGER): INTEGER;
  355.     FUNCTION Werktag_im_Jahr(tt,mm,jj: INTEGER): INTEGER;
  356.     Laufende Nummer des Werktages im Monat/Jahr.
  357.  
  358.     FUNCTION MakeMonat(VAR s: STRING40): INTEGER;
  359.     Gibt die Nummer des als String übergebenen Monats zurück, wenn nicht
  360.     gefunden, dann 0.
  361.     Der String kann den Monat als Ziffer oder als Klartext enthalten.
  362.  
  363.     FUNCTION MakeDatum(altdatum: STRING40): BOOLEAN;
  364.     Ermittelt aus dem übergebenen String das Datum und stellt Kalender
  365.     entsprechend ein. Im String darf auch ein Monatsname im Klartext
  366.     (oder ein Teil davon) enthalten sein.
  367.     Gültig wäre z. B. 1. Ap. 91
  368.     Im greg. Kal wird Jahreszahl < 100 als 1980 < j <= 2080 interpretiert.
  369.     Im Erfolgsfall (wenn das Datum gültig ist) wird TRUE zurückgegeben.
  370.  
  371.     FUNCTION Fuelle_FeiertagsListe(FListe: PUnsortedStringCollection): BOOLEAN;
  372.     Füllt die Kollektion mit Namen und Daten der Feiertage des eingestellten
  373.     Monats.
  374.  
  375.     PROCEDURE InitJahr(j: INTEGER);
  376.     Füllt Feiertage^.
  377.  
  378.     FUNCTION GetFtDayNumber(Tab: Feiertagstabelle;j: INTEGER): INTEGER; VIRTUAL;
  379.     Ermittelt aus der übergebenen Tabelle die Nummer des Tages im Jahr j,
  380.     auf den der beschriebene Feiertag fällt.
  381.  
  382.     PROCEDURE Trage_ein(tnr: INTEGER; FTagNum: WORD);
  383.     Trägt die Nummer FTagNum für den Tag tnr in Feiertage^ ein.
  384.  
  385.     FUNCTION CheckFTJahr(Jmin, JMax, J: INTEGER): BOOLEAN;
  386.     Prüft, ob Feiertag im Jahr j angezeigt werden soll.
  387.  
  388.     PROCEDURE InitSpecials; VIRTUAL;
  389.     Setzt einige Parameter in Abhängigkeit des Kalendariums.
  390.  
  391.  
  392.  
  393. 5. Copyright
  394. Das Programm KALDEMO darf nicht kommerziell verwertet werden.
  395. Die Weitergabe ist nur zusammen mit der kompletten Shareware-Fassung der
  396. Toolbox gestattet.
  397. Das Einbinden der Units in eigene Programme ist nur registrierten Nutzern
  398. gestattet. Diese dürfen die selbsterstellten Programme ohne Einschränkung
  399. vermarkten.
  400.  
  401.